On-demand whole-codebase discovery pass for dead paths, convergent duplication, and unconsumed data flow — the findings a per-diff review and an exact-clone linter both structurally miss. Runs four lenses (whole-program reachability, the clone-detector's known-duplication catalogue, a convergence-scoring pass over the code-health rubric, and a producer→consumer data-flow trace for dropped values and orphan stages), triages each finding against tracked ownership, and emits a scorecard plus gap candidates. Use when auditing an inherited or fast-changing codebase, before a large refactor, or when a module feels heavy. Discovery only — it proposes, it does not auto-fix.
The aiwf per-repo code-health ritual — the whole-codebase companion to wf-review-code's per-diff gate. A stack-agnostic field guide of code-health principles: module boundaries, contracts, data discipline, tests that pin behavior, errors/logs/audit, reasoning aids, operational properties. Use when designing a new module, planning a refactor, reviewing a non-trivial diff, writing a spec that introduces new boundaries, or scoring an inherited codebase Strong/Weak/Missing with file:line evidence. These are advisory forces, not rules — consult them, don't enforce them; the project's own conventions win.
Use when the user wants to add a new aiwf entity (epic, milestone, ADR, gap, decision, or contract) or an acceptance criterion under an existing milestone, or to declare a milestone's `depends_on` edges. Runs `aiwf add` (or `aiwf milestone depends-on` for post-allocation edits) so the id allocation, frontmatter, and commit happen mechanically.
Red/green/refactor for a single acceptance criterion or feature unit, ending with a hard-rule branch-coverage audit and a required vacuity check (does a covered assertion actually catch the bug). Write a failing test, write the minimum code to pass, refactor, then walk every reachable conditional branch and confirm an explicit test exercises it. Use during milestone implementation and inside `wf-patch` when the change touches logic.
Sets up and begins an aiwf milestone — preflight checks, branch setup, status promotion to in_progress, then iterative TDD via wf-tdd-cycle. Use when the user says "start milestone M-NNNN" or "implement M-NNNN" and a draft milestone spec exists. Commits and pushes require explicit human approval.
Decomposes an approved aiwf epic into a sequenced set of independently-shippable milestones. Allocates each M-NNNN via `aiwf add milestone --epic E-NNNN`, scaffolds each milestone spec from its template, sequences them by dependency. Use after `aiwfx-plan-epic` when the user says "break this into milestones" or "plan the work for E-NNNN".
Use when the user wants to validate the planning tree or asks why `aiwf check` reported a finding. Explains each finding code and the typical fix.
Closes an aiwf epic — verifies all milestones done, scaffolds a wrap artefact, harvests ADR candidates, runs scoped doc-lint, merges the epic branch into mainline with a trailered merge commit, promotes the epic to done. Use when the user says "wrap E-NN" or "close the auth epic" and every milestone in the epic is wrapped. Commit and push require explicit human approval.