delete-dead-code

Files (17)

• SKILL.md
• guide.md
• dead-code-findings-format.md · references/
• duplicate-findings-format.md · references/
• dead_code_artifacts.py · scripts/
• dead_code_clones.py · scripts/
• dead_code_scope.py · scripts/
• dead_code_units.py · scripts/
• dead_code_scope_bus_stack_test.py · scripts/tests/
• dead_code_scope_clones_test.py · scripts/tests/
• dead_code_scope_directory_overlap_test.py · scripts/tests/
• dead_code_scope_explicit_test.py · scripts/tests/
• dead_code_scope_review_delta_test.py · scripts/tests/
• dead_code_scope_test.py · scripts/tests/
• dead_code_scope_tracks_test.py · scripts/tests/
• dead_code_scope_unit_boundaries_test.py · scripts/tests/
• dead_code_scope_worktree_test.py · scripts/tests/

SKILL.md (first lines)

Judgment principles are in [guide.md](./guide.md). Artifact structure: the dead-code track uses [references/dead-code-findings-format.md](./references/dead-code-findings-format.md),
the duplicate track uses [references/duplicate-findings-format.md](./references/duplicate-findings-format.md). This file defines only the executable flow; the
reason for every step is in the same-named section of guide.md.

**Read guide.md completely before starting**: why the two tracks are separate, the zombie rule, dead branches and fake optionals, version numbers and
compatibility branches, the bar for `CONFIRMED`, recognizing intentional duplication, the four verdicts for a duplicate group, and the consolidation
direction all live there; without it you will delete or consolidate the wrong thing.

```text
INPUT = [--base <immutable commit>] [--directories <dir>…] [--max-parallel <N, default 5>] [--track dead|duplicate|all, default all]

-- Pick one scope source: by default the modules this PR touches (`base...HEAD`); when the user names directories, pass `--directories` (guide.md
--   "When the user names directories"). Wherever `--base "<base>"` appears below, explicit-directory mode substitutes `--directories <dir>…`;
--   boundary checks, module expansion, and batching apply.
-- `--track all`: finish the whole dead-code track (including LAND) before starting the duplicate track; each track lands separately, and the order
--   cannot be swapped.

repo   = git rev-parse --show-toplevel
branch = git branch --show-current
base   = caller-provided immutable commit, otherwise origin/master
branch_slug   = branch with every character outside [A-Za-z0-9_-] replaced by `-`
artifact_root = temp/delete-dead-code/<branch_slug>

========== PREFLIGHT (must hold before each track starts) ==========

Run: python3 skills/delete-dead-code/scripts/dead_code_scope.py preflight --repo "<repo>" --base "<base>"
exit 0 = holds; exit 1 = not on a feature branch, or a unit this invocation owns has uncommitted changes (each listed); exit 2 = the scope cannot be derived.
exit != 0 → STOP.
-- Only this invocation's units are checked; other units' in-flight changes are no reason to STOP (guide.md "Why share one worktree").
-- After the dead-code track's LAND the units are clean again; a failing duplicate-track PREFLIGHT means LAND did not finish: STOP.

========== 1. SCOPE (shared by both tracks) ==========

Run: python3 skills/delete-dead-code/scripts/dead_code_scope.py scope --repo "<repo>" --base "<base>"
Exit 2 = the scope cannot be derived → STOP; never guess a scope and continue.

-- The output is the units in scope (by file count, descending). In PR mode a unit = a top-level subtree such as `src`;
--   loose top-level files form a separate unit. In explicit-directory mode a unit = the requested directory itself, including subdirectories. This is
--   the entire modifiable scope: dead code or duplicates outside it are recorded, never touched (guide.md "Why the scope must be mechanical").
-- Every unit carries `directories` (the scan list) and `excludes` (empty for these disjoint units); both go into briefs verbatim.

IF --track == duplicate: skip to TRACK B.

################################################################################
TRACK A — dead-code track: discover per module, handle per module, delete only
################################################################################

========== A2. PLAN BATCHES ==========

Run: python3 skills/delete-dead-code/scripts/dead_code_scope.py batches --repo "<repo>" --base "<base>" --max-parallel "<N>"
Capture `roundCount` and `rounds`. Rounds are serial, modules within a round parallel. Never regroup them yourself.

========== A3. FAN-OUT LOOP ==========

FOR round IN rounds:
  FOR EACH module IN round:
    Dispatch ONE subagent. The brief must contain verbatim:
      - the sole allowlist: the one directory `<module>` (including same-module tests edited with the deletion)
      - that module's `directories` (scan all of them, one by one) and `excludes` from the scope output, quoted verbatim, never re-derived
      - the base commit, artifact path `<artifact_root>/dead-<module-slug>.md`, artifact header `- Track: \`dead\``, format references/dead-code-findings-format.md
      - the full text of guide.md's "Dead-code track" and "Shared" parts, naming these mandatory checks:
          * package entry points / re-export facades ("Package-level re-export facades")
          * check both directions: consumer counts find dead definitions, producer counts find dead branches and **fake optionals** ("Dead branches are checked in reverse", "Fake optionals")
          * version numbers and compatibility branches: peers delivered atomically in one binary keep no backward compatibility between them; own
            version prefixes with no v2 and constant version handshakes are deleted as dead code; guards for peers that are not delivered atomically
            (the stable endpoint contract, the socket API, installed integration assets), persisted data (including on-disk caches), and endpoints
            that may not be ours are recorded `LIKELY` + `KEPT` with the reason "needs developer ruling: version/compat"
          * this track only deletes, never consolidates: live duplicates where both copies have production callers are neither recorded nor touched;
            when only one copy has a production caller, the other is dead code: delete it and repoint tests to the live one; liveness is judged by
            production wiring only
          * when a baseline / allowlist blocks a deletion, record `HANDOFF` with the exact change to the list; never roll back a verified deletion ("Baselines and allowlists…")
      - hard constraints: no Git write of any kind; never start Bus (`./run dev`, live sessions, `just e2e`); leave no background build/test process;
        never change shared config (`Cargo.toml`, `Cargo.lock`, `justfile`, `clippy.toml`, `rust-toolchain.toml`, `.github/workflows/*`); report it instead
      - verification (only if something changed; otherwise say nothing changed): this module's tests, narrowly (Rust `just test-one <module path filter>`,
        Python `python3 -m unittest scripts.<name>_test` or `python3 -m pytest skills/<skill> -q`, Bun `bun test <test file>`); `rustfmt --check --edition 2021
        <own changed .rs files…>` (never whole-tree `cargo fmt --check`); no coverage, E2E, or whole-tree clippy/build (guide.md "How far each unit verifies itself")

  Wait for every subagent in this round. No short-interval polling.

  FOR EACH module artifact produced this round:
    Run: python3 skills/delete-dead-code/scripts/dead_code_scope.py verify --repo "<repo>" --base "<base>" --artifact "<artifact>" --unit "<module>"
    exit 0 = pass; exit 1 = out of scope or structurally self-contradictory; exit 2 = cannot verify.
    IF exit != 0
      STOP with the offending lines; the main agent reverts out-of-scope edits before deciding, never carries them into the next round.

  IF any subagent reported a blocker or a needed shared-config change
    STOP and report. Never mask it with a retry in the next round.

========== A3b. HANDOFF ROUND ==========

pending = every `path:line` whose Disposition is `HANDOFF` across artifacts (the reason names the blocking module)
IF pending is empty: skip this stage.

Split by whether the blocking module is inside the stage-1 scope:
  - outside the scope → goes unchanged into OUTPUT's "follow-up PR candidates" with the blocking module named; never widen the scope, never downgrade
    to `KEPT` (guide.md "Cross-module deletions").
  - inside the scope → pair by (module holding the symbol, blocking module):
    FOR EACH pair (at most max_parallel concurrently; further rounds beyond that):
      Dispatch ONE subagent, allowlist = the union of the two modules, only the symbols on the list. Brief as in A3, plus: no deletion beyond this HANDOFF list; run both modules' tests.
    Verify each handoff artifact as in A3, `--unit` given both modules of the pair. Whatever still cannot move after pairing stays `KEPT` and is reported.

========== A4. REVIEW (the main agent does it, never delegated) ==========

Run: python3 skills/delete-dead-code/scripts/dead_code_scope.py review --repo "<repo>" --base "<base>" --artifact <every artifact of this track…>
exit 1 = items pending review; exit 0 = no assertion rewrites, skip this stage.

FOR EACH rewritten assertion it lists:
  the artifact must carry a matching "updated to production facts" explanation. A flip without one = expectations changed to turn green. STOP.

========== A5. GATES ==========

delta = this invocation's own changes, taken per unit:
  `git status --porcelain --untracked-files=all --ignore-submodules=all -- <unit path>`
Changes outside the units belong to other owners: never inspected, never committed.

IF any agent reports a changed file outside its allowlist
  STOP "out-of-scope change" and list the files.
IF every module is CLEAN and the units of this invocation have no change
  Record "dead-code track: no confirmable dead code in this scope"; skip A6.

From asura1234/bus, Apache-2.0.

More from asura1234/bus