manual_slop/conductor/tracks/unused_scripts_cleanup_20260607/spec.md

Track: Unused Scripts Cleanup

Status: Spec approved 2026-06-07 Initialized: 2026-06-07 Owner: Tier 2 Tech Lead Priority: Low (chore; cleanup, not feature)

---

Overview

Remove 30 confirmed-unused scripts from scripts/ so the directory contains only active MMA/MCP/CI/test infrastructure, kept-by-utility tools, or infrastructure referenced by a planned future track. Net effect: scripts/ shrinks from 56 → 26 files (54% reduction).

All deletions are hard deletes via 5 atomic per-category commits. The git log is the restore path; per-category commits give surgical rollback granularity (each commit is one logical category that stands or falls together). No new CI gate is added in this track; a follow-up unused_scripts_audit_20260607 is recorded in §Follow-up.

Current State Audit (as of a88c748d)

scripts/ currently has 56 files in five functional buckets. The audit below is data-grounded: a project-wide grep confirms the "keep" reasons (live references in active code, docs, CI, or planned tracks) and the absence of references for the 30 "remove" files.

Already Implemented (KEEP — DO NOT touch, 26 files)

1. CI audit gates (3 files, 17.7 KB total).

   • audit_main_thread_imports.py — CI gate from startup_speedup_20260606 (T1.4, commit 6f9a3af2); referenced by conductor/workflow.md:584, tests/test_main_thread_purity.py:12, and 4 active planned tracks.
   • audit_weak_types.py — CI gate from data_structure_strengthening_20260606 (commit 84fd9ac9); will gain --strict mode in that track.
   • check_test_toml_paths.py — CI gate from test_consolidation_20260606 (commit 1660114b).

2. MMA infrastructure (5 files, 34.7 KB total).

   • mma_exec.py — referenced 100+ times in workflow.md, tracks.md, all 5 active planned tracks, AGENTS.md. The MMA bridge.
   • mma.ps1 — PowerShell wrapper for mma_exec.py.
   • claude_mma_exec.py (10 KB) — alternative MMA bridge; documented in docs/Readme.md:18 and docs/guide_meta_boundary.md as a Meta-Tooling inter-domain bridge.
   • claude_tool_bridge.py (3.8 KB), cli_tool_bridge.py (6.5 KB) — inter-domain bridges per docs/guide_meta_boundary.md. Active in tests/test_cli_tool_bridge.py and tests/test_cli_tool_bridge_mapping.py.

3. MCP infrastructure (3 files, 13.4 KB total).

   • mcp_server.py (3.2 KB) — referenced in opencode.json:27 as an MCP server entry.
   • mock_mcp_server.py (1.6 KB) — referenced by tests/test_cli_tool_bridge_mapping.py and other bridge tests.
   • py_struct_tools.py (8.6 KB) — shared AST/regex logic for src/mcp_client.py dispatch; created in conductor/archive/python_structural_mcp_tools_20260513/plan.md:4 (commit d044ccb2).

4. Test runner (1 file). run_tests_batched.py (1.3 KB) — the test runner being upgraded by test_batching_refactor_20260606.

5. ImGui linter (1 file). check_imgui_scopes.py (3.5 KB) — mandatory per conductor/product-guidelines.md:26; referenced by 4 archived plans and the workflow.

6. Audit / scaffolding (4 files).

   • audit_gui2_imports.py (3.7 KB) — startup_speedup T1.2 (commit 6f9a3af2).
   • benchmark_imports.py (7.3 KB) — startup_speedup T1.1 (commit 2adf3274).
   • run_subagent.ps1 (3.2 KB) — active MMA sub-agent invocation.
   • __init__.py (0 bytes) — empty package marker.

7. Tool-call bridge (4 files, ≈ 2.8 MB total — dominated by the compiled binary).

   • tool_call.cpp (1.5 KB, source), tool_call.exe (2.8 MB, compiled binary), tool_call.py (1.6 KB, Python bridge), tool_call.ps1 (123 B, PowerShell wrapper) — used by the inter-domain tool-call system referenced in docs/guide_meta_boundary.md. The tool_call.bat and tool_call.cmd aliases are being removed in this track (see §"Gaps to Fill", commit 5).

8. Docker (3 files). docker_build.sh (164 B), docker_push.ps1 (1.5 KB), docker_run.sh (141 B) — referenced by docs/superpowers/plans/2026-06-02-docker-web-frontend.md (planned track).

9. Borderline utility (2 files, KEEP per review).

   • slice_tools.py (2.4 KB) — general-purpose CLI primitive: get_slice / set_slice / get_def. Standalone alternative to mcp_client's file_slice tools; could be used in future AST-driven refactor scripts.
   • validate_types.ps1 (671 B) — plausible ad-hoc ruff + mypy runner on 5 core files. No current consumer, but small and plausibly useful.

Gaps to Fill (this track's scope — 30 file deletions)

These 30 files are confirmed one-off tools from past tracks; their purpose has been served and no current code, doc, or CI references them. Grouped by deletion commit:

Commit	File	Size	Origin / why it's a one-off
1	audit_indentation.py	4.6 KB	1-space indentation is now enforced project-wide (track fix_indentation_1space_20260516). Only referenced in that archived plan.
1	check_hints_v2.py	1.0 KB	Crude regex-based hint checker on 4 hardcoded files. Superseded by scan_all_hints.py (now also being removed).
1	correct_indentation.py	6.4 KB	One-shot indentation corrector; project is already 1-space.
1	extract_symbols.py	547 B	Crude symbol printer; functionality lives in mcp_client.py_get_symbol_info and friends.
1	fix_gaps.py	704 B	Hardcoded whitespace gap fixer for src/gui_2.py; the gaps are already fixed.
1	fix_indent.py	9.6 KB	One of three iterations of an indent fixer; project is already 1-space.
1	fix_indent_ast.py	3.4 KB	AST-based variant of the above.
1	fix_indent_v3.py	2.2 KB	Third variant (render-method-specific).
1	standardize_indent.py	1.0 KB	Indent standardizer; project is already 1-space.
1	type_hint_scanner.py	718 B	Crude CLI hint scanner; superseded by scan_all_hints.py.
2	apply_startup_timeline.py	8.3 KB	One-shot edit during startup_speedup_20260606 (commit 229559ca); edit already applied.
2	apply_type_hints.py	10.5 KB	One-shot type-hint applicator from gui_2_cleanup_20260513; hints already applied.
2	gut_oop_final.py	1.7 KB	OOP culling tool from hot_reload_python_20260516; OOP is already gutted.
2	restore_regions_final.py	4.8 KB	One-shot region restoration for src/gui_2.py; regions are restored.
2	transform_render_methods.py	3.0 KB	Render-method transformer; the delegation refactor (hot-reload track) is done.
2	transform_render_methods_safe.py	2.4 KB	Safer variant of the above.
3	audit_entropy.py	3.1 KB	Early entropy auditor; superseded by the 2 active CI gates.
3	comprehensive_entropy_audit.py	10.5 KB	One-off entropy audit; superseded.
3	focused_entropy_audit.py	6.8 KB	Muratori-style entropy audit; superseded.
3	code_stats.py	7.8 KB	Stats gatherer; no consumer. Created in commit bd7f8e17 "add code status script".
4	migrate_cruft.ps1	2.6 KB	Filesystem migration from consolidate_cruft_and_log_taxonomy_20260228; migration is done.
4	profile_baseline.py	2.4 KB	Profiling baseline tool; baselines live in docs/reports/.
4	repro_history.py	2.3 KB	Repro for a fixed history bug from hot_reload_python_20260516; bug is fixed.
4	sdm_injector.py	6.8 KB	SDM tag injector from sdm_docstrings_20260509; tags in place.
4	sdm_mapper.py	7.3 KB	SDM tag mapper (pilot); tags in place.
4	update_paths.py	789 B	sys.path patcher; the src/ layout is now standard.
5	scan_all_hints.py	2.0 KB	Only referenced in .claude/commands/mma-tier2-tech-lead.md (local AI tool config, not the project). The MMA workflow uses audit_weak_types.py instead.
5	tool_call.bat	49 B	@echo off wrapper for tool_call.py; redundant with tool_call.ps1.
5	tool_call.cmd	50 B	CMD wrapper for tool_call.py; redundant.
5	tool_discovery.py	1.4 KB	Tool spec discovery using the legacy mcp_client.MCP_TOOL_SPECS API path; not the canonical one (will be refactored by mcp_architecture_refactor_20260606).

Total deletions: 30 files, ~115 KB. Net scripts/ count after track: 26 files.

Goals

• Remove the 30 confirmed-unused scripts from scripts/ so the directory is a curated home for active infrastructure.
• Maintain project invariants: all 5 per-category commits are atomic; the test suite passes after each commit; the kept slice_tools.py and validate_types.ps1 remain importable and functional.
• Document the per-file rationale in the spec so a future re-evaluation is fast.

Functional Requirements

• F1. Each of the 30 deletions is committed in the correct category group (1 of 5 atomic commits per §Commit Structure).
• F2. Each commit message includes a brief summary of why these scripts are being removed (per conductor/workflow.md step 9 commit message format).
• F3. A git notes add -m "..." is attached to each commit per conductor/workflow.md steps 10.1-10.3, summarizing the deletion rationale and listing the removed files.
• F4. The state.toml for this track (created by the Tier 2 implementer) reflects all 5 commit SHAs and advances current_phase to "complete" after the final commit.
• F5. tracks.md is updated to add the track entry in the appropriate section (chronological, under whatever phase corresponds to 2026-06-07).

Non-Functional Requirements

• NFR1 (Per-category atomicity). 5 atomic commits, not 30 individual file commits. Each commit's diff is reviewable in isolation; rollback is per-category.
• NFR2 (No CI gate in this track). The follow-up unused_scripts_audit_20260607 will add scripts/audit_unused_scripts.py --strict if desired. Not in scope here.
• NFR3 (No documentation changes). The audit confirms no doc references any of the 30 files by name; no doc churn is required.
• NFR4 (No code style application). N/A — this is deletion only; no new code.
• NFR5 (No new tests required). The existing test suite is the regression net; if no test breaks after the 30 deletions, the track is verifiably safe.

Commit Structure

5 atomic commits, in order:

1. chore(scripts): remove one-shot indentation fixers
   (10 files)
2. chore(scripts): remove one-shot transform scripts
   (6 files)
3. chore(scripts): remove superseded entropy and code-stat audits
   (4 files)
4. chore(scripts): remove one-shot migrators and repros
   (6 files)
5. chore(scripts): remove tool_call aliases and legacy tool discovery
   (4 files; scan_all_hints.py + tool_call.bat + tool_call.cmd + tool_discovery.py)

Each commit message also gets a git notes add -m "..." summary per conductor/workflow.md (per-task commit + git note + state.toml pattern).

Architecture Reference

• docs/guide_meta_boundary.md — explains the inter-domain bridge pattern (why claude_mma_exec.py, cli_tool_bridge.py, claude_tool_bridge.py, mcp_server.py are kept).
• docs/guide_architecture.md — explains the MMA/MCP infrastructure layer that the kept scripts support.
• conductor/workflow.md "Task Workflow" — per-task commit + git note + state.toml pattern (applied to this track).
• conductor/workflow.md "Audit Script Policy" — the audit-script + styleguide pair; the future unused_scripts_audit_20260607 follow-up will follow this pattern.
• conductor/archive/cull_unused_symbols_20260507/ — prior similar cleanup (src/ symbols, 27 removed) for format reference.

Out of Scope

• Active infrastructure (26 KEEPS listed in §"Already Implemented"). Do not touch.
• Docker scripts (3 files). Kept; referenced by the planned Docker track.
• __init__.py. Kept (package marker).
• slice_tools.py and validate_types.ps1. Kept (borderline utility, per the per-file review).
• conductor/archive/, tests/artifacts/, .claude/commands/, .gemini/, opencode.json, docs/. Different domains; not in scope.
• Follow-up unused_scripts_audit_20260607. Recorded in §Follow-up, NOT done in this track.
• Re-evaluating the kept-among-borderline files. slice_tools.py and validate_types.ps1 are kept as-is.

Follow-up

• unused_scripts_audit_20260607 (planned, NOT in this track): adds scripts/audit_unused_scripts.py with --strict mode and a baseline file. Mirrors the scripts/audit_weak_types.py / data_structure_strengthening_20260606 pattern. Catches "new unused script was added" before it lands.

  Rationale for deferral: (1) the project has 3 audit scripts already; adding a 4th is a maintenance commitment; (2) the cleanup is small enough that one-time adjudication is more appropriate than permanent enforcement right now; (3) the audit script itself would be in scripts/ — adding a self-policing layer to a directory that just shrank is overkill for one track.

  Trigger to start this follow-up: when scripts/ grows back to 35+ files (the post-cleanup count is 26; +9 = 35 is a soft signal that one-off tools are accumulating again).

Coordination with Pending Tracks

This track has no blockers and no conflicts. It can ship independently of, and in parallel with, the 5 active planned tracks:

Pending track	Effect on scripts/	Conflict?
test_batching_refactor_20260606	+3 (test_categorizer, test_batcher, pytest_collection_order)	None (additive)
qwen_llama_grok_integration_20260606	0 (all in src/)	None
data_oriented_error_handling_20260606	0 (all in src/)	None
data_structure_strengthening_20260606	+1 (generate_type_registry.py)	None
mcp_architecture_refactor_20260606	0 (all in src/)	None

After all 5 planned tracks + this track ship, scripts/ will have 30 files (26 from this cleanup + 3 from test batching + 1 from data structure strengthening). All under active maintenance.

Risks

Risk	Likelihood	Impact	Mitigation
A removed script was being invoked by hand by the user (not in any code path the grep caught).	Low	Low (one-time re-invocation fails)	git log -- scripts/<file> is one click; per-category commits make rollback surgical.
The user re-evaluates and decides one of the 30 has utility.	Low	Low (work to restore)	The per-file rationale in §"Gaps to Fill" documents the why; per-category commits can be reverted in one step.
An LLM sub-agent reaches for one of the removed scripts during an MMA task.	Very low	Low (the LLM's tool list comes from mcp_client, not scripts/)	None needed; the MMA Tier 3 prompt seeds the sub-agent with the project layout, which no longer lists the removed scripts after the commits land.
A test file imports one of the 30 (e.g., from scripts.scan_all_hints import ...) that the audit missed.	Very low (audit was comprehensive)	Medium (test failure)	Full test suite in 4-at-a-time batches per workflow.md Phase Completion protocol; rollback the affected commit if it fails.

See Also

• conductor/archive/cull_unused_symbols_20260507/ — prior similar cleanup (src/ symbols, 27 removed).
• conductor/archive/consolidate_cruft_and_log_taxonomy_20260228/ — prior filesystem cruft cleanup (logs/artifacts/temp_*.toml).
• conductor/archive/fix_indentation_1space_20260516/ — the track that created the indent-fixer family this cleanup now retires.
• docs/reports/PLANNING_DIGEST_20260606.md §"Recommended Future Tracks" — recommends documentation sync as the next track after the 5 planned ones (this track is independent).
• conductor/tracks.md "Test Regression Verification" archive — another cleanup-style track.