pi-dev-team 0.2.0

package/skills/test-improve/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: test-improve
+description: >-
+  Consolidated analyze-then-improve test orchestrator. Defaults to lightweight
+  ceremony; opts into heavier capabilities (Gherkin extraction, mutation
+  testing, refactor-for-testability) only when the operator asks. Always
+  baselines coverage (and mutation, when enabled) before any test change, runs
+  the end-of-phase review loop after Phases 5 and 7, and produces a stable
+  10-section executive-summary report. Use when the user says "improve our
+  tests", "modernize the test suite", "upgrade our tests", or runs
+  /test-improve.
+argument-hint: "<repo-path> [--parent <url>] [--analyze-only] [--from-phase [<n>]] [--stack <id>]"
+role: orchestrator
+user-invocable: true
+allowed-tools: Read, Grep, Glob, Bash(git diff *), Bash(python3 *), Bash(sh *), Skill, Agent
+---
+
+# Test Improve
+
+Role: orchestrator. This command sequences existing skills and agents through a
+ten-phase (0-9) analyze-then-improve workflow; it does **not** implement, audit, or
+write tests itself. Each phase is **delegated** to the worker skill or agent
+that owns it, and per-phase progress is persisted to
+`.claude/memory/test-improve/<slug>/phase-<n>.md` so `/continue` (and `--from-phase`)
+can resume.
+
+You have been invoked with the `/test-improve` command.
+
+## Orchestrator constraints
+
+1. **Delegate every phase.** Call the owning skill or agent (`/test-health`,
+   `/gherkin-derive`, `/issues-from-assessment`, `/build`, `/coverage-baseline`,
+   `/coverage-delta`, `/mutation-testing`, `mutation-kill` agent,
+   `/quality-targets-converge`, `/test-design`, `/code-review`, `/apply-fixes`).
+   Never re-implement their logic here.
+2. **Honor the human gates.** Do not advance past a gate without explicit
+   approval.
+3. **Confirm the approach first.** Phase 0 owns the approach contract; do not
+   start work until it has completed and its answers are persisted.
+4. **Baseline before changing anything.** Coverage (and mutation, when
+   enabled) must land directly in `.dev-team-reports/test-improve/<slug>/data/`
+   before any file under the stack's test directory is modified.
+5. **Be concise.** Report each phase's outcome and the next gate, nothing
+   more.
+
+## Parse Arguments
+
+- Positional: `<repo-path>` (default: cwd).
+- `--parent <url>` — optional tracker parent issue URL; the host selects the
+  CLI (ADO / GitHub / GitLab / Jira). Omit for **local-files mode** (the
+  default), which writes to `.dev-team-reports/test-improve/` and `.claude/plans/test-improve/`.
+- `--analyze-only` — run Phase 0 then Phase 1 directly and **exit after Phase 1** with a
+  summary of the improvement plan (bypassing the default Baseline/Derive-Gherkin
+  ordering — see Phase 0's `--analyze-only` semantics). No baseline is
+  captured; no code changes.
+- `--from-phase [<n>]` — skips completed phases and resumes at phase `n` when
+  `.claude/memory/test-improve/<slug>/phase-<n-1>.md` exists. **The number is
+  optional.** Passed with **no argument**, `/test-improve` **auto-detects** the
+  resume point from `.claude/memory/test-improve/<slug>/` (see
+  `references/phase-0-approach-contract.md`): it resumes at the phase after the highest completed
+  progress file and prints which phase it resolved to and why. An explicit
+  `<n>` **overrides** auto-detection. Either form does **not** re-prompt
+  Phase-0 inputs; to change them, delete
+  `.claude/memory/test-improve/<slug>/phase-0.md` and re-run from Phase 0.
+- `--stack <id>` — force a stack profile (e.g. `js`, `dotnet`, `java`, `go`)
+  when manifest detection is ambiguous.
+
+## Phase-start banner
+
+At the start of every phase, print a two-line banner:
+
+```
+Step <position>/<total> — Phase <N>: <phase name>
+mutation: <off|kill-loop|baseline+kill-loop> · binding: <none|xunit-with-annotations|bdd-runner> · refactor: <no-refactor|refactor-allowed> · sink: <tracker|local>
+```
+
+`<N>` is the phase's stable identity number — unchanged by execution order
+(Phase 1 is always Analyze, Phase 2 is always Baseline, etc.). `<position>`
+is a **running count of phases printed so far this run, including this
+one** — increment it by exactly 1 at each phase-start banner, never
+computed from a fixed per-identity table. A bare `Phase N/9` counter would
+print non-monotonically under this reordered execution sequence (`2/9` then
+`3/9` then `1/9`), reading as a hung or looping run to an operator watching
+stdout; a plain running count fixes this without renumbering any phase,
+file, or `--from-phase` flag value, and — unlike a fixed per-identity
+table — it stays correct regardless of which phases actually execute.
+
+**`<total>` is not always 9 or 10 — compute it, never hardcode it.** Two
+independent things vary the count: whether Phase 3 runs (known from Phase
+0's BDD binding mode: skipped when `none`, so **-1**) and whether Phase 7
+runs (Phase 6's decision — Phase 7 and Phase 8 are **not alternatives**;
+when Phase 6 returns `[y]`, both Phase 7 *and* Phase 8 execute in sequence,
+so entering Phase 7 is **+1**, not a shared slot). Concretely:
+
+- Base count is **9** (Phases 0, 2, 3, 1, 4, 5, 6, 8, 9 — Phase 7 excluded
+  by default).
+- **-1** when the Phase-0 BDD binding mode is `none` (Phase 3 never runs) —
+  known from Phase 0 onward, so this adjustment is baked into every
+  banner's `<total>` from the very first one.
+- **+1** the moment Phase 6 resolves to `[y]` (entering Phase 7) — this is
+  **not** knowable before Phase 6 fires (an operator in `refactor-allowed`
+  mode can still pick `[b]`/`[q]` and skip Phase 7 despite the mode
+  permitting it), so `<total>` for Phases 0 through 6's banners uses the
+  **without-Phase-7** count; if Phase 6 then returns `[y]`, print one line
+  before Phase 7's banner — `Phase 7 entered — total phase count for this
+  run is now <new total> (was <old total>).` — and use the new total for
+  Phase 7, 8, and 9's banners. When `refactor-mode: no-refactor` (Phase 6
+  offers no `[y]` at all) or Phase 6 returns `[b]`/`[q]`, no adjustment ever
+  fires and `<total>` stays fixed for the whole run.
+
+This keeps `<position>` strictly monotonic in every run shape, and
+`<total>` honest at each point it's printed — correcting exactly once, with
+a visible reason, only in the one case (entering Phase 7) that's genuinely
+unknowable in advance.
+
+The recap line reflects the still-active Phase-0 settings so an operator
+resuming via `--from-phase` (or returning to a long-running session) sees the
+current phase and active settings without scrollback archaeology.
+
+## Steps
+
+**Execution order.** Phases below are numbered by stable identity, not by
+execution order — Phase 2 (Baseline) and Phase 3 (Derive Gherkin) execute
+before Phase 1 (Analyze) so `/test-health` can use documented-but-untested
+Gherkin scenarios as a coverage signal. **Document order below matches
+execution order**: `0 → 2 → 3 → 1 → 4 → 5 → 6 → 7 → 8 → 9`, where Phase 7
+runs only when Phase 6 returns `[y]` (see "Phase-start banner" above for how
+this affects the banner's `<total>`) — Phase 7 and Phase 8 always run in
+that sequence together, never as alternatives to each other. When the
+Phase-0 BDD binding mode is `none`, Phase 3 is skipped and the executed
+sequence becomes `0 → 2 → 1 → 4 → 5 → 6 → (7) → 8 → 9`.
+
+## Phase Reference Files
+
+Each phase's procedural detail lives in its own reference file, listed below.
+
+| Phase | Name | Reference file |
+| --- | --- | --- |
+| 0 | Approach contract | `references/phase-0-approach-contract.md` |
+| 1 | Analyze via /test-health | `references/phase-1-analyze.md` |
+| 2 | Baseline | `references/phase-2-baseline.md` |
+| 3 | Derive Gherkin | `references/phase-3-derive-gherkin.md` |
+| 4 | Plan fixes | `references/phase-4-plan-fixes.md` |
+| 5 | Improve without refactoring | `references/phase-5-improve.md` |
+| 6 | Refactor decision | `references/phase-6-refactor-decision.md` |
+| 7 | Refactor-for-testability | `references/phase-7-refactor.md` |
+| 8 | Validate | `references/phase-8-validate.md` |
+| 9 | Executive-summary report | `references/phase-9-report.md` |
+
+The After-Phase-9 close-out prompt is not one of the ten numbered phases and deliberately has no row above; it is the separate `### After Phase 9` section further down, backed by `references/phase-9-close-out-prompt.md`.
+
+Before executing a phase, read only that phase's reference file — never a
+phase-specific reference file for a phase already completed in this run or a
+prior resumed session. Shared implementation-detail reference files (e.g.
+`references/review-loop.md`) are not phase-specific and may be read whenever
+the phase you are executing points at them, regardless of whether another
+phase also uses them.
+
+This instruction is prose, not a hook-enforced gate — no mechanism in this
+repo verifies at runtime that only the active phase's reference file was
+read; compliance depends on the executing agent following the rule as
+written.
+
+### Phase 0 — Approach contract
+
+<!-- include: references/phase-0-approach-contract.md -->
+See `references/phase-0-approach-contract.md` for the full prompt battery and conflict-check mechanics.
+
+### Phase 2 — Baseline (coverage + mutation)
+
+<!-- include: references/phase-2-baseline.md -->
+See `references/phase-2-baseline.md` for the full coverage-and-mutation baseline procedure, the coverage-gap ranking, and the ordering invariant.
+
+### Phase 3 — Derive Gherkin (conditional)
+
+<!-- include: references/phase-3-derive-gherkin.md -->
+See `references/phase-3-derive-gherkin.md` for the full binding-mode
+branches, persistence, human gate, and the bdd-runner pending-stub
+interaction with Phase 5 — conditional on the Phase-0 BDD rubric answer.
+
+### Phase 1 — Analyze via /test-health
+
+<!-- include: references/phase-1-analyze.md -->
+See `references/phase-1-analyze.md` for the full `/test-health` delegation,
+the coverage-gap-ranking ordering rule and its `--analyze-only` no-ranking
+case, the test-count-by-type snapshot and existing-snapshot guard, the human
+gate, and the `/handoff` suggestion.
+
+### Phase 4 — Plan fixes (partition findings by gap class)
+
+<!-- include: references/phase-4-plan-fixes.md -->
+See `references/phase-4-plan-fixes.md` for the full gap-class partitioning,
+the coverage-gap-ranking Story order, the persistence path, and the human
+gate blocking Phase 5.
+
+### Phase 5 — Improve without refactoring (build + mutation-kill + review loop)
+
+<!-- include: references/phase-5-improve.md -->
+See `references/phase-5-improve.md` for the full per-Story build,
+coverage-delta, and mutation-kill loop, the pending-stub gate, and the
+end-of-phase review loop (which shares `references/review-loop.md` with
+Phase 7).
+
+### Phase 6 — Refactor decision (mode-gated)
+
+<!-- include: references/phase-6-refactor-decision.md -->
+See `references/phase-6-refactor-decision.md` for the full REFACTOR_REQUIRED
+presentation, the `refactor-mode` branch, and the `[y/b/q]` decision prompt.
+
+### Phase 7 — Refactor-for-testability (conditional)
+
+<!-- include: references/phase-7-refactor.md -->
+See `references/phase-7-refactor.md` for the full hard mode gate, the seam-only and
+existing-tests-immutable constraints, the Phase-5 precondition check, and
+the end-of-phase review loop (which shares `references/review-loop.md` with
+Phase 5).
+
+### Phase 8 — Validate (converge quality targets)
+
+<!-- include: references/phase-8-validate.md -->
+See `references/phase-8-validate.md` for the full mutation-target-per-mode
+rules, the branch-scoped mutation validation, the coverage-<90%-in-no-refactor
+re-run prompt, the evidence and test-count recount, and the `/handoff`
+suggestion.
+
+### Phase 9 — Executive-summary report
+
+<!-- include: references/phase-9-report.md -->
+See `references/phase-9-report.md` for the full executive-summary report
+generation, the template source, output path, interpolation and
+empty-section rules, the mutation row shape, the parent-issue/FEATURE.md
+link update, and the regeneratable-from-tracked-data contract.
+
+### After Phase 9 — Re-run-with-refactor close-out prompt
+
+<!-- include: references/phase-9-close-out-prompt.md -->
+See `references/phase-9-close-out-prompt.md` for the full re-run-with-refactor
+close-out prompt: when it is suppressed, its `[y/n]` decision, and how it
+differs from Phase 8's coverage-driven, mid-run prompt.

package/skills/test-improve/references/phase-0-approach-contract.md

@@ -0,0 +1,228 @@
+Resolve every ambiguous input in **one batch** before any work starts, then
+persist the resolved inputs to `.claude/memory/test-improve/<slug>/phase-0.md`. The
+file must exist **before Phase 1** runs.
+
+**Detect language(s) and stack profile.** Inspect manifests for JS/TS
+(`package.json`), Java (`pom.xml` / `build.gradle`), C# (`*.csproj`), and Go
+(`go.mod`). If `--stack` was passed, honor it. Record the resolved stack in
+`phase-0.md`.
+
+**Go advisory (shown before the mutation prompt when Go is detected).**
+
+> Mutation testing on Go uses **go-mutesting**, which is **alpha**-quality.
+> Survivor count is **not a gate** on Go — treat it as advisory. For real
+> confidence in Go tests, prefer `go test -fuzz` on the parts of the code
+> that reward it. In `baseline+kill-loop` mode the orchestrator records
+> baseline and delta numbers; in `kill-loop` it records only the final
+> surviving-mutant count. Either way the Phase-8 mutation target is
+> advisory-only for Go.
+
+**Prompt battery (one batch, six knobs).** Each prompt displays its default in
+`[brackets]`; pressing **Enter accepts every default in one keystroke** — with
+**one deliberate exception**: knob 6 (code-lookup install) is **not** part of the
+Enter-accepts-all gesture, because accepting it mutates the filesystem (and, for
+Graphify, the repo's `CLAUDE.md`). Knob 6 is the **sole** exception; it requires an
+explicit `y`/`n` and a blank response **re-prompts** rather than defaulting either
+way. This is called out in the knob-6 prompt itself so the divergence is never a
+silent surprise.
+
+1. **Mutation mode** — `[kill-loop]`. A three-way choice; the value recorded in
+   `phase-0.md` and shown in the banner is the canonical token (`off` /
+   `kill-loop` / `baseline+kill-loop`), used verbatim in both places:
+   - `off` — no mutation testing (lightweight ceremony).
+   - `kill-loop` (**default**) — run the mutant-kill loop and produce a final
+     report of surviving mutants, **without** a separate baseline run first.
+   - `baseline+kill-loop` — run the mutation baseline first, then the mutant-kill
+     loop (a before/after mutation delta).
+
+   **Default change — mutation now runs by default.** The old knob defaulted to
+   `off` (no mutation work on Enter-through); under `kill-loop` an Enter-through
+   run **now performs the mutant-kill loop**. The prompt flags this so it is
+   never a silent surprise.
+
+   **Show the relative cost with the choice (#1965).** This knob is the
+   largest single cost multiplier in the workflow, and an operator pressing
+   Enter through the battery was accepting it without the price ever being
+   named. State it in the prompt — qualitatively, never as a fabricated dollar
+   figure (`/cost-report` is the instrument for actuals):
+
+   > Relative cost: `off` adds none. `kill-loop` adds roughly one
+   > opus-tier `mutation-kill` dispatch per module batch in Phase 5 (up to 3
+   > rounds each), plus the mutation tool's own runtime.
+   > `baseline+kill-loop` adds a full mutation baseline run on top of that.
+
+   This is disclosure, not a recommendation and not a default change: the
+   risk-mitigation trade each mode buys is the operator's call, and mutation
+   work is how assertion quality gets measured at all. Naming the price just
+   makes it an informed one.
+2. **BDD rubric** — five yes/no questions from
+   `knowledge/references/bdd-value-guide.md`. **Default `none`** if the
+   operator declines to answer. Scoring: ≥3 yes → `bdd-runner` recommended;
+   1–2 yes → `xunit-with-annotations` recommended; 0 yes → `none`.
+
+   **Relative cost (#1965)**, stated with the choice for the same reason as
+   knob 1:
+
+   > `none` skips Phase 3 entirely. `xunit-with-annotations` adds scenario
+   > derivation and `.feature` authoring. `bdd-runner` adds those plus parser
+   > wiring, step-definition stub generation, and the Phase-5 pending-stub
+   > gate every stub must clear before the phase can close.
+3. **Refactor mode** — `[no-refactor]`. Default is **`no-refactor`**. Choose
+   `refactor-allowed` to permit production-code changes in Phase 7 (seams
+   only; existing tests may not be modified or removed).
+4. **Quality targets** — defaults: coverage ≥ 90% line + branch; surviving
+   mutants = 0 (only when mutation mode is not `off`); determinism = 100%; wall-clock =
+   fastest achievable. Any target can be overridden here; overrides land in
+   `phase-0.md` and flow into Phase 8.
+5. **Sink** — `--parent <url>` selects a tracker (ADO / GitHub / GitLab /
+   Jira via the host CLI); missing CLI or omitted flag falls back to
+   **local-files** mode (writes under `.dev-team-reports/test-improve/` and
+   `.claude/plans/test-improve/`).
+6. **Code-lookup tools (all-or-none install)** — offer to install the three
+   code-lookup tools (**CodeGraph**, **Repowise**, **Graphify**) so the review
+   and analysis agents read verified skeletons and resolved call graphs instead
+   of re-reading whole files. **Recommended: yes** when any of the three is
+   missing. This knob is an **explicit `y`/`n`** (see the Enter-accepts-all
+   exception above); a blank answer re-prompts. The prompt names the three tools
+   and discloses that Graphify writes a `## graphify` section into this repo's
+   `CLAUDE.md` and installs git hooks.
+   - **Idempotent / missing-subset.** Detect which of the three are already
+     present; offer only the **missing** subset. When all three are present,
+     do not prompt — record `code_lookup_tools: already present`.
+   - **Delegate the install — never reimplement it.** On `y`, delegate to
+     `/project-init`'s Step 4c graph-tools group (the canonical installer); do
+     not duplicate install commands or probes here.
+   - **Decline is visibly confirmed.** On `n`, install nothing and print
+     `Code-lookup tools: skipped — agents fall back to Read/Grep/Glob.`
+   - **Partial failure is recorded, not masked.** If the delegated install
+     partially fails, record per-tool success/failure in `phase-0.md` and do
+     not claim full install success.
+
+**Coverage-target vs refactor-mode conflict check (issue #1787).** A stated
+coverage percentage (**knob 4**) and `refactor-mode: no-refactor` (**knob 3**)
+can be structurally incompatible, and Pass 1 held both at once without ever
+saying so: mutation-kill work cannot raise line or branch coverage on code that
+has no tests at all, and a layer at near-zero coverage generally needs a
+production-code seam before any test can reach it. Resolve this **before** any
+work starts — **never by waiving a gate later**, which is what happened when
+branch-90 was quietly waived at a later gate while coverage-90 stayed a stated
+goal to the end.
+
+Run the check; do not judge it in prose:
+
+```
+sh "${CLAUDE_PLUGIN_ROOT}/hooks/py.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/coverage_gap_ranking.py" \
+  --report <existing coverage report> --repo-root <repo-path> \
+  --target-line-pct <line target> --target-branch-pct <branch target> --json
+```
+
+- **A coverage report is discoverable** — a prior run's
+  `.dev-team-reports/test-improve/<slug>/data/baseline-coverage.json`'s
+  `raw_report`, or a report artifact already on disk (`lcov.info`,
+  `coverage.json`, `cobertura.xml`, `jacoco.csv`, `coverage-summary.json`).
+  The script's `verdict` decides:
+  - **`unreachable_without_seams` (exit 3)** — the target cannot be reached even
+    if every module that already has a test seam went to 100%. Present the
+    explicit three-way choice **`[w] waive the target / [s] switch to
+    refactor-allowed / [c] continue as-is`** (shape `[w/s/c]`), naming the
+    script's own numbers — `lines_needed`, `reachable_uncovered_lines`, and the
+    top seam-blocked modules — so the operator sees the arithmetic, not an
+    opinion. `[w]` records the target as **waived at Phase 0** with this reason
+    (Phase 8 then reports it waived up front instead of discovering it); `[s]`
+    records `refactor-mode: refactor-allowed` (Phase 0 is still resolving its
+    own answers here, so this is not an immutability exception); `[c]` proceeds
+    with `coverage_target_conflict: acknowledged` recorded. A **non-interactive**
+    run **does not silently pick a stance** — it records
+    `coverage_target_conflict: unresolved`, prints the same three options, and
+    the conflict is restated at Phase 8 rather than resolved by default.
+  - **`reachable` / `already_met` (exit 0)** — record
+    `coverage_target_conflict: none` and continue.
+- **No coverage report is discoverable** — do **not** fabricate a verdict from
+  no data. Record `coverage_target_conflict: deferred` and run this identical
+  check at Phase 2 against the freshly captured baseline, **before** Phase 1
+  consumes the ranking (see the coverage-gap ranking step in
+  `phase-2-baseline.md`). Deferred means
+  *checked one phase later against real numbers* — never dropped, and never
+  first surfaced in the Phase-9 report.
+
+This check is skipped entirely when knob 4 left no coverage percentage target
+active, or when knob 3 selected `refactor-allowed` (there is no mode conflict
+to surface).
+
+**Persistence.** Write the resolved inputs to `.claude/memory/test-improve/<slug>/phase-0.md` before Phase 1 runs — Phase 1 must not start until `phase-0.md` exists. This includes the knob-6 outcome (the operator's install choice, and for each tool whether it was already present, installed, declined, or failed).
+
+**Immutability.** Phase-0 answers are **immutable** for the remainder of the
+run. `--from-phase` does not re-prompt Phase-0 inputs. To change them, delete
+`.claude/memory/test-improve/<slug>/phase-0.md` and re-run from Phase 0.
+
+**`--analyze-only` semantics.** With `--analyze-only`, Phase 0 completes as
+normal, Phase 1 (`/test-health`) runs, and the orchestrator **exits after Phase 1**
+with a summary of the improvement plan. This is a deliberate carve-out:
+Phase 1 runs **directly**, bypassing the default Baseline (Phase 2) / Derive
+Gherkin (Phase 3) ordering (`0 → 2 → 3 → 1 → 4 → ...`) — not a contradiction
+of it. No baseline is captured; no code changes.
+
+**`--from-phase` semantics.** `--from-phase <n>` resumes **at** phase `n` and
+skips every phase that precedes `n` in the **execution** sequence
+`0, 2, 3, 1, 4, 5, 6, 7, 8, 9` (not identity order — e.g. `--from-phase 1`
+skips Phases 0, 2, and 3, not just 0). Phase-0 inputs are read from
+`phase-0.md` (never re-prompted). **An explicit `<n>` is not validated
+against this sequence** beyond requiring `phase-0.md` to exist — e.g.
+`--from-phase 1` does not check that Phase 2 (Baseline) has actually run
+first, so an operator passing an out-of-sequence `<n>` by hand can skip a
+phase whose output later phases depend on (Baseline before any test-file
+change, in particular). Prefer `--from-phase` with no number
+(auto-detect, below) unless there's a specific reason to name a phase
+explicitly.
+
+**`--from-phase` with no number — auto-detect the resume point.** When
+`--from-phase` is passed **without** a number, resolve the resume phase by
+calling the helper — do **not** infer it in prose:
+
+```
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/test_improve_resume.py" <repo-path>
+```
+
+The helper resolves the slug from `<repo-path>` (its last path segment), scans
+**only** that slug's `.claude/memory/test-improve/<slug>/` directory for the
+completed-phase progress files (`phase-0.md` … `phase-9.md`, excluding
+`phase-3.md` — Phase 3 is conditional and tracked via `gherkin.md` instead,
+never a numbered progress file), finds the highest completed phase in
+**execution** order (`0, 2, 1, 4, 5, 6, 7, 8, 9` — Phase 3 excluded, matching
+the progress-file scan above), and prints a JSON object whose
+`resolved_phase` is the phase to resume at and whose `message` reads e.g.
+`Resuming at Phase 8 (latest completed: phase-6.md).`. Print that `message`
+so the operator can confirm before work starts, then resume at
+`resolved_phase`. Resolution rules the helper encodes:
+
+- A completed `phase-5.md` with **no** `phase-6.md` resumes at **Phase 6**;
+  a completed `phase-6.md` resumes at **Phase 8** (matching the `[b]`/`[q]`
+  skip-to-8 flow); a completed `phase-7.md` resumes at **Phase 8**.
+- Only `phase-0.md` present resumes at **Phase 2** (Baseline — the phase that
+  now executes immediately after Phase 0).
+- A completed `phase-2.md` with **no** `phase-1.md` resumes at **Phase 1**
+  (Phase 3 has no tracked progress file, so the auto-detect skips over it —
+  see `test_improve_resume.py`'s module docstring). A completed `phase-1.md`
+  resumes at **Phase 4**.
+- **No memory dir / no phase files / `phase-0.md` missing** — the helper exits
+  non-zero; surface its error message (which points to running
+  `/test-improve <repo-path>` from Phase 0) and do **not** silently start at
+  Phase 0.
+- A completed `phase-9.md` means the run is already complete (`complete:
+  true`) — report it; there is nothing to resume.
+
+To resolve an **explicit** `<n>` (including validating that `phase-0.md`
+exists) the skill may pass `--explicit <n>`; an explicit `<n>` **overrides**
+auto-detection. Auto-detect and explicit alike read Phase-0 inputs from
+`phase-0.md` and never re-prompt them.
+
+**Phase-6 prompt letter.** The full Phase-6 refactor-decision prompt —
+shown only in `refactor-allowed` mode — uses `[y/b/q]` (not `[r]`; see
+`phase-6-refactor-decision.md` for why `r` was avoided). `[y]` advances to
+Phase 7; `[b]` backlogs the REFACTOR_REQUIRED items and
+skips to Phase 8; `[q]` quits before Phase 8. In `no-refactor` mode (the
+default) Phase 6 is **informational only** — no `[y]` is offered, the
+REFACTOR_REQUIRED items are auto-backlogged, and the run continues to Phase 8
+(see `phase-6-refactor-decision.md` for the full branch mechanics
+and `phase-7-refactor.md` for the hard-mode-gate backstop that
+enforces this same `no-refactor` restriction if Phase 7 is somehow reached).

package/skills/test-improve/references/phase-1-analyze.md

@@ -0,0 +1,131 @@
+Delegate the entire analysis pass to **`/test-health`** — it is the **sole
+worker** for Phase 1. Invoke it exactly once with the resolved repo path from
+Phase 0. `/test-health` internally orchestrates whatever sub-skills it needs
+(CD-alignment audit, test-design assessment, mutation-testing roll-up); the
+orchestrator must **not** invoke `/cd-test-architecture`, `/test-design`, or
+`/mutation-testing` separately here. Any prior workflow that reached those
+skills directly is superseded by the single `/test-health` call.
+
+**Mutation mode gates the mutation sub-run itself, not just the report
+(#1961).** Read the mutation mode from `phase-0.md` and thread it into the
+invocation:
+
+- **Mutation mode `off` — the mutation section is omitted / "not enabled",
+  and the sub-run is skipped too.** Invoke `/test-health --no-mutation`, which
+  skips its Step-5 `mutation-testing` invocation outright rather than running
+  it and discarding the result. This used to be a report-time filter only: the
+  mutation tool ran, the roll-up was produced, and the output was then
+  suppressed — a measurement with no consumer, since `off` also means no
+  Phase-5 kill loop will consume survivor ordering. A skip is not a waiver and
+  not a coverage gap; the target was never in scope for this run.
+- **Mutation mode `kill-loop` or `baseline+kill-loop`** — invoke
+  `/test-health` with no mutation flag. The mutation section is **present**,
+  and its ROI framing feeds the ordered plan as before.
+
+**Order the plan by the coverage-gap ranking whenever a coverage percentage
+is a stated goal (issue #1786).** Read
+`.dev-team-reports/test-improve/<slug>/data/coverage-gap-ranking.json` —
+written by Phase 2 (see `phase-2-baseline.md`) — and order the
+coverage-driven items of `/test-health`'s ordered
+improvement plan by that ranking's `modules` array (`rank` 1 first), not by
+mutation survivor count and not by an ordering re-derived here. `/test-health`'s
+own ordering stands only for items the ranking does not speak to (flakiness,
+determinism, suite shape), and for a run where **no coverage percentage is a
+stated goal** (Phase-0 knob 4 overrode the coverage targets away) the ranking
+is **informational** rather than the ordering authority.
+
+**Under `--analyze-only` there is no ranking to read.** That mode runs Phase 0
+then Phase 1 directly and captures no baseline, so Phase 2 never wrote
+`coverage-gap-ranking.json`. Do not fabricate one and do not silently fall back
+to survivor ordering: present `/test-health`'s own ordering and state plainly
+that the coverage-gap ranking was not computed for this run (a full run would
+order the coverage-driven items by it). The same holds for a `--from-phase 1`
+resume whose `data/` directory has no ranking file — say so rather than
+proceeding as if the ordering were coverage-derived.
+
+**Mutation survivors order work *within* an already-seamed module, never
+across modules.** A module whose ranking entry reads `seam: established`
+already has baseline coverage, so survivor counts are the right next signal
+*there* — that is the ordering the `mutation-kill` agent applies inside Phase
+5. A module whose entry reads `seam: absent` needs coverage before it needs
+assertion quality, and is ordered by uncovered lines alone. Under
+`refactor-mode: no-refactor` a top-ranked `seam: absent` module whose tests
+need a production seam is still shown in the presented plan — labeled
+**skipped-in-no-refactor** per the human gate below — so the operator sees the
+coverage left on the table instead of a plan that quietly reorders around it.
+
+**Output.** Persist the rolled-up analysis plus the ordered improvement plan to
+`.claude/memory/test-improve/<slug>/phase-1.md`.
+
+**Test-count-by-type snapshot.** Independent of the `/test-health` call
+above (and of whether `/test-health`'s own trivial-suite short-circuit
+fired for this run), perform a direct classification pass over the test
+files under the `<repo-path>` Phase 0 resolved: apply
+`knowledge/cd-test-architecture.md`'s
+six-type criteria (Static analysis / Unit / Component / Contract /
+Integration / End-to-end) directly to each test suite/file found. **One
+test file counts as exactly one suite**, regardless of how many describe
+blocks or test classes it contains. Tie-break rule for a file that doesn't
+cleanly fit one type: classify by its dominant/highest-dependency type
+(e.g. a suite exercising a real DB connection classifies as integration
+even if most of its assertions read like unit-level checks); if dominance
+is still tied, classify by the higher-fidelity type using this fixed
+precedence: `end_to_end` > `integration` > `contract` > `component` >
+`unit` (this precedence applies to test files only — `static_analysis` is
+never a legitimate outcome of classifying a test file; see its own
+counting rule below). Persist
+`.dev-team-reports/test-improve/<slug>/data/test-counts-before.json` — written
+**directly** to the git-tracked `data/` sibling (this file has no other
+consumer, so no separate `.claude/memory/` copy is needed) — with the six
+canonical snake_case keys, in this fixed order: `static_analysis`, `unit`,
+`component`, `contract`, `integration`, `end_to_end` — each key present
+even at zero, counting **test suites/files, not individual test cases or
+assertions**. `static_analysis` counts configured linter/scanner tool
+invocations (one per tool — e.g. ESLint, Semgrep, mypy) rather than
+test-directory files, since static analysis runs over non-running code and
+is rarely organized as a describe-block suite; when the repo has no
+configured static-analysis tooling at all, the key is `0`, not omitted.
+
+**Existing-snapshot guard.** Before persisting, check whether
+`test-counts-before.json` already exists under
+`.dev-team-reports/test-improve/<slug>/data/` for the resolved slug. This
+guard is Phase 1's application of the shared existing-tracked-artifact
+re-capture guard — the canonical definition and rationale live once in
+`knowledge/decision-defaults.md`'s "Re-capture: keep vs. overwrite an existing
+tracked artifact" axis; this step cites that axis for the *why* and spells out
+the operational branches below so an executing agent doesn't need to open a
+second file mid-task. **No existing file** → write the fresh snapshot
+directly; no prompt is needed. **An existing file that is malformed or
+corrupt** (fails to parse as JSON — e.g. left over from a prior interrupted
+write) → treat it as absent, never as a snapshot to keep; emit a warning
+naming why a fresh capture is happening, then write the fresh snapshot
+directly (no prompt — there is nothing valid to keep). **An existing, readable
+file**, interactive session → prompt: *"An existing
+test-counts-before.json was found for `<slug>` — overwrite it (starts a fresh
+before/after comparison) or keep it (reuse for this run)? `[keep/overwrite,
+default: keep]`"* Answering `overwrite` replaces the existing file with a
+fresh snapshot. Answering `keep` (or declining) leaves the existing file
+untouched and Phase 1 reuses it for this run. An **unrecognized answer**
+(anything other than `keep` or `overwrite`) re-prompts with the identical
+text — it never silently falls back to the default. When the run is
+**non-interactive** (no usable TTY / `DEV_TEAM_AUTO_APPROVE=1`), the prompt is
+never shown; Phase 1 defaults to **keep existing** and logs the
+auto-decision, mirroring `decision-defaults.md`'s non-interactive rule — never
+a non-default stance (overwrite) with nobody present to confirm it. The
+malformed-file branch above is the one exception to that keep-by-default
+posture — an unreadable file is treated as absent in every mode, since there
+is nothing valid to keep.
+
+This pass does **not** invoke `/test-health` or `/cd-test-architecture`'s
+full skill.
+
+**Human gate.** After `/test-health` returns, present **the ordered improvement
+plan** to the operator and wait for explicit approval. **Phase 4 does not run**
+until the operator approves. This is the human gate for Phase 1; do not advance
+past it without approval. When `phase-0.md` recorded
+`refactor-mode: no-refactor`, any plan item that would require a production-code
+refactor is labeled **skipped-in-no-refactor** (out of scope for this run) so
+the operator sees the coverage/behavior left on the table — such items are never
+presented as ordinary next steps that this run will execute.
+
+**`/handoff` suggestion** (context-heavy analysis). Once the gate above resolves, print: `Phase 1 complete. Consider running /handoff to compress context before continuing. To resume: /test-improve <repo-path> --from-phase 4 (or --from-phase with no number to auto-detect the resume point)`