git:20260709.200c770 to git:20260722.becfb57

+ description: "Coordinates consent-gated, evidence-isolated, behavior-preserving simplification refactors. Use when simplifying, splitting, renaming, moving, deduplicating, or clarifying existing code while preserving the canonical protected surfaces."

+ Portable orchestrator for behavior-preserving simplification refactors. The

+ operating posture: **the best refactor deletes or reuses before it writes** —

+ every plan is checked against the reuse ladder and deletion test in

+ [`references/simplification-heuristics.md`](./references/simplification-heuristics.md)

+ before new code is proposed. One approved target at a time; raw code and diffs

+ stay in subagents; nothing mutates before plan approval; stop rather than

+ crossing [`references/protected-surfaces.md`](./references/protected-surfaces.md).

+ with `Dispatch method: inline` when no subagent primitive exists; inline runs

+ must still write each report to its handoff file and route only on the compact

+ reply, discarding raw inspection detail between phases.

+ `AUTO_APPROVE=true` is defined at both gates: the plan card is auto-accepted

+ only when it contains no size waiver, no non-`safe` validation command, and no

+ protected-surface carve-out — otherwise the run ends `NEEDS_CLARIFICATION`

+ with the card in the handoff. A fix-scope re-approval under `AUTO_APPROVE`

+ always ends `BLOCKED`; the skill never guesses on its own authority.

+ Multiple targets only when enumerated; each runs the full phase sequence

+ independently. Plan approval may be batched across targets; reports stay

+ per-target. Aggregate = worst of (worst first): `ERROR`, `BLOCKED`,

+ `NEEDS_CLARIFICATION`, `NO_CHANGE`, `PASS_WITH_WARNINGS`, `PASS`.

+

+ ## Status Vocabulary

+ One shared enum across all subagents; each role returns the subset that

+ applies, with its role prefix (`BEHAVIOR_MAP:`, `CHUNK_ANALYSIS:`,

+ `IMPLEMENTATION:`, `REFACTOR_REVIEW:`):

+ | Status | Meaning | Orchestrator route |

+ | ------ | ------- | ------------------ |

+ | `PASS` | Phase completed with sufficient evidence | Next phase |

+ | `PASS_WITH_WARNINGS` | Completed, but a warning (e.g. validation not run) must survive to the final | Next phase; cap final at `PASS_WITH_WARNINGS` |

+ | `NO_CHANGE_CANDIDATE` | Mapper only: no useful refactor is evident | `NO_CHANGE` terminal with recommendation; user may override with a recorded objective |

+ | `FAIL` | Reviewer only: required fixes remain | Fix loop (≤2 cycles) |

+ | `NEEDS_CLARIFICATION` | A user decision or missing input blocks progress | Relay the one smallest question, or terminal |

+ | `BLOCKED` | Continuing would cross scope, boundary, or approval | Failure handoff with worktree state |

+ | `ERROR` | Tool or state failure | Retry once only if plausibly transient (timeout, cancelled tool, unavailable VCS metadata — and the report itself marks it transient); else failure handoff |

+ | `behavior-mapper` | `./subagents/behavior-mapper.md` | Read-only behavior, baseline, validation candidates, sizes, risks, chunk list |

+ | `chunk-analyst` | `./subagents/chunk-analyst.md` | Read-only findings for one analysis dimension; one instance per chunk, run concurrently |

+ | `refactor-implementer` | `./subagents/refactor-implementer.md` | Apply approved plan or ledgered fixes; record dispositions and validation evidence |

+ | `refactor-reviewer` | `./subagents/refactor-reviewer.md` | Baseline-scoped dual verdict: behavior preservation and simplification outcome |

+ Read a subagent only when dispatching it. Every dispatch names the role, its

+ inputs, the expected report path under `.handoffs/refactoring-code/`, and the

+ required compact-reply keys. Handoff files are working artifacts: never stage

+ or commit them; delete them at terminal cleanup.

+ Never edit before plan approval.

+ The mapper records commit hash (or `no-vcs`), porcelain summary, and

+ pre-existing dirty files, and proposes 2–5 **target-derived chunks** — the

+ analysis dimensions this specific target needs (e.g. duplication/reuse,

+ complexity and idiom, dead code, naming, test posture), not a fixed list. One

+ `chunk-analyst` per chunk runs concurrently when the runtime supports parallel

+ dispatch, serially with identical contracts otherwise. Analysis is read-only

+ either way; **implementation is always serial and single-writer** so baseline

+ drift detection and disposition tags stay sound.

+ The orchestrator synthesizes analyst findings into one plan card: it merges

+ overlaps, discards low-confidence or conflicting items, keeps only steps that

+ trace to a diagnosis, and batches every decision the user must make — size

+ waivers, non-`safe` command approval, scope conflicts — into that single card.

+

+ The implementer tags each changed file `created`, `edited-from-clean`, or

+ `edited-over-pre-existing`. The reviewer checks only those files against the

+ baseline and fails on extras.

+

+ Validation is a contract: commands only from `TEST_COMMAND`, mapper

+ candidates, or an explicit warning path. Classify with

+ unknown commands are `state-mutating` and need approval. Zero tests executed

+ is `not run` even with exit code 0. Every completion claim needs fresh

+ evidence from this run — exact command, exit code, coverage proof — never a

+ recollection of an earlier result.

+ 1. **Intake** — If `TARGET_PATH` is missing or vague, ask once, then

+ `NEEDS_CLARIFICATION`. Resolve `MAX_LINES`, `AUTO_APPROVE`, enumeration.

+ 2. **Map** — Dispatch `behavior-mapper`. Route by the status table.

+ `NO_CHANGE_CANDIDATE` → recommend `NO_CHANGE`; if the user explicitly

+ continues, record the objective and proceed.

+ 3. **Analyze (parallel)** — Dispatch one `chunk-analyst` per mapper-proposed

+ chunk, each with its own `REPORT_PATH`. Wait for all. Any

+ `NEEDS_CLARIFICATION` → relay before synthesis; a failed analyst after one

+ transient retry degrades to a plan-card disclosure ("dimension X

+ unanalyzed"), not a silent gap.

+ 4. **Synthesize the plan card** — From the analyst report files build:

+ diagnosis list; ordered steps, each traced to a diagnosis and carrying its

+ reuse-ladder rung; per-file map with `create`/`change` dispositions;

+ non-goals; expected net-line and duplication summary; validation contract

+ with safety class; and the batched decisions section (waivers, non-`safe`

+ commands, conflicts, unanalyzed dimensions). Load

+ [`references/file-size-policy.md`](./references/file-size-policy.md) when

+ sizes are at issue. Adding a file not on the approved map later requires

+ re-approval.

+ 5. **Gate: plan approval** — Present the card (skeleton in

+ [`references/workflow-examples.md`](./references/workflow-examples.md)).

+ Approve → implement. Adjust → re-synthesize once from the same analyst

+ reports, then repeat this gate. Decline → `NEEDS_CLARIFICATION` with the

+ plan preserved. `AUTO_APPROVE` per the Inputs rule.

+ 6. **Implement (serial)** — Dispatch `refactor-implementer` with the approved

+ card (on repair: `Fix cycle: n of 2` and `REVIEW_FIXES`). `BLOCKED` or

+ non-retryable `ERROR` → failure handoff with worktree state; never

+ auto-revert.

+ 7. **Review** — Dispatch `refactor-reviewer`. Both verdicts `pass` → final

+ (`PASS`, or `PASS_WITH_WARNINGS` when any warning exists). `FAIL` →

+ step 8.

+ 8. **Fix loop** — At most 2 cycles; the ledger increments exactly once per

+ re-implementation dispatch. Critical/Important findings enter the loop;

+ Minor findings go to the final handoff untouched. A required fix outside

+ the approved card or protected boundary triggers the **fix-scope

+ re-approval gate**: present the expanded scope; decline or `AUTO_APPROVE`

+ → `BLOCKED`. At the cap with `FAIL` outstanding → `BLOCKED`.

+ 9. **Terminal** — One status line first. Success handoffs: behavior summary,

+ diagnosis, changes with dispositions, reuse/deletion summary (net lines,

+ duplication removed vs introduced, ladder rungs used), validation

+ evidence or leading warning, review verdicts and fix cycles, size

+ compliance, worktree end-state (uncommitted; no commits made),

+ disclosures (dispatch method, `AUTO_APPROVE`, retries, unanalyzed

+ dimensions). Stops: smallest reason, next decision, validation state,

+ risks, worktree state if edited. Never auto-revert. Delete

+ `.handoffs/refactoring-code/` artifacts.

+ | Reuse ladder, deletion test, clarity rules, outcome metrics | `./references/simplification-heuristics.md` |

+ `TEST_COMMAND=npm test -- invoice`.

+ The mapper records baseline and proposes chunks `duplication-reuse`,

+ `complexity-idiom`, and `dead-code`. Three analysts run concurrently; the

+ duplication analyst finds that a local rounding helper duplicates

+ `src/shared/money.ts` (`reuse-repo` rung). The plan card proposes deleting the

+ helper, reusing the shared one, and flattening one nested conditional — net

+ −18 lines, no waivers, `safe` command — so a single approval covers

+ everything. After serial implementation, the reviewer confirms behavior

+ preservation and a negative net-line simplification verdict, and the run

+ returns `PASS` with coverage evidence.