# 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.
