pi-dev-team 0.2.0

package/skills/test-improve/references/phase-2-baseline.md

@@ -0,0 +1,121 @@
+Capture the objective starting point **before any file under the stack's test
+directory is modified**. Baselines are the ground truth every downstream delta
+compares against; running any test edit before baseline capture invalidates
+the whole run.
+
+**Coverage baseline.** Invoke `/coverage-baseline --workflow test-improve`
+against the resolved repo path. `/coverage-baseline` owns its own
+existing-baseline guard and persist step — see `../../coverage-baseline/SKILL.md`'s
+"Existing-baseline guard" and "Persist the baseline" steps for the full
+mechanics. The result lands directly and atomically at
+`.dev-team-reports/test-improve/<slug>/data/baseline-coverage.json`; there is
+no `.claude/memory/` write and no later copy step for this file — that skill
+has no opt-in awareness of its own, and this write is **unconditional**.
+
+This is independent of the mutation mode: a coverage baseline is persisted in
+every mode, and the mutation baseline is written **only** in
+`baseline+kill-loop` mode (see below).
+
+**Coverage-gap ranking — the targeting input for Phases 1, 4, and 5 (issue
+#1786).** As soon as `baseline-coverage.json` lands, compute the per-module
+uncovered-line breakdown from the same report the baseline was parsed from
+(its `raw_report` field). This runs in **every mutation mode** — it is the
+coverage targeting input, independent of whether mutation work happens at
+all — and it is computed by script, never estimated in prose:
+
+```
+sh "${CLAUDE_PLUGIN_ROOT}/hooks/py.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/coverage_gap_ranking.py" \
+  --report <baseline raw_report> --repo-root <repo-path> \
+  --target-line-pct <line target> --target-branch-pct <branch target> \
+  --top 0 --json \
+  --out .dev-team-reports/test-improve/<slug>/data/coverage-gap-ranking.json
+```
+
+Always pass `--repo-root <repo-path>`: several coverage writers (istanbul/nyc
+`coverage-final.json` among them) emit **absolute** source paths, and without a
+root to strip they would all bucket together — one module makes the seam
+classification a single global comparison, so the check silently stops
+discriminating. The script derives the shared path prefix itself as a fallback,
+and flags `grouping_degenerate: true` whenever many files still land in one
+bucket; treat that flag as "the ranking could not resolve modules", never as a
+verdict.
+
+The script buckets every source file into a package/assembly/module and ranks
+the buckets by **uncovered lines descending**, marking each bucket's `seam`
+as `established` (coverage at or above the seam threshold — a test-only change
+is proven to reach it) or `absent` (near-zero coverage — nothing there is
+proven reachable without a production-code seam). `--out` writes the payload
+atomically (temp-file-then-rename), so `coverage-gap-ranking.json` lands in
+the same git-tracked `data/` sibling as the baselines and is read directly
+from there by Phase 1, Phase 4, and Phase 5.
+
+**Mutation survivors are not an input to this ranking, and must not become
+one.** A surviving mutant can only exist on a line a test already executes, so
+a survivor-ordered priority list structurally *excludes* the 0%-covered layers
+that hold most of the missing coverage. That is the failure this ranking
+exists to prevent: a Pass-1 run spent its entire Phase 5 adding mutation-kill
+assertions to layers already at 88-95% line coverage while the layer holding
+~93% of the lines needed to reach the coverage target sat at 0-11% and was
+never targeted.
+
+**A deferred Phase-0 conflict check resolves here (issue #1787).** When
+`phase-0.md` recorded `coverage_target_conflict: deferred` (no coverage report
+was discoverable at Phase 0), *this* invocation is that check — now with real
+numbers. A `verdict` of `unreachable_without_seams` (exit 3) surfaces the same
+explicit choice Phase 0 defines, **before Phase 1 runs**, with one letter
+changed: **`[w] waive the target / [s] stop and re-run in refactor-allowed mode
+/ [c] continue as-is`**. Phase-0 answers are **immutable** for the rest of the
+run, so `[s]` here **stops the run** and tells the operator to re-invoke
+`/test-improve <repo-path>` choosing `refactor-allowed` — it must **never
+rewrite `refactor-mode`** in `phase-0.md` mid-run. Record the outcome in
+`phase-2.md`. A **non-interactive** run at this point follows Phase 0's rule
+unchanged: record `coverage_target_conflict: unresolved` in `phase-2.md`, print
+the same three options, and continue to Phase 1 — it never auto-stops and never
+auto-waives, and Phase 8 restates the unresolved conflict.
+
+**A missing or unparseable report is not a clean ranking.** **Exit 2** means
+the script found nothing to rank (report absent, unrecognized, or parsed to
+zero coverage records) — never an all-clear. Name the report path it tried and
+resolve it (re-run `/coverage-baseline`, or point `--report` at the artifact
+the coverage tool actually emitted) before Phase 1 runs. **Do not proceed with
+mutation survivors as a stand-in ordering.**
+
+**Mutation baseline (`baseline+kill-loop` only).** When `phase-0.md` recorded
+mutation mode **`baseline+kill-loop`**, check for an existing tracked baseline
+before invoking `/mutation-testing --baseline` — this is Phase 2's own
+existing-baseline guard for `baseline-mutation.json`, needed here (unlike the
+coverage case) because `/mutation-testing` owns no persistence of its own: it
+has no `--baseline`-specific write path of its own to guard. This
+existing-baseline guard is this phase'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; applied here:
+
+- **No existing file, or overwrite chosen** — invoke `/mutation-testing --baseline --workflow test-improve` and persist the result (below).
+- **Existing file, interactive session** — prompt keep/overwrite (default keep). An answer that is neither "keep" nor "overwrite" (case-insensitive) re-prompts with the identical choice — never falls back silently to either option, no retry limit, no timeout.
+- **Existing file, non-interactive** (no usable TTY, or `DEV_TEAM_AUTO_APPROVE=1`) — keep the existing baseline automatically; both log the auto-decision and echo it to Phase 2's own progress output, naming the reused baseline's `captured_at` — reporting parity with the coverage-baseline case, not a silent reuse.
+- **Existing file 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 baseline to keep. Emit a warning naming why a fresh capture is happening, then invoke `/mutation-testing --baseline --workflow test-improve`.
+- **On keep** — do not invoke `/mutation-testing --baseline`; reuse the existing file's fields and report its `captured_at` instead of a freshly captured timestamp.
+
+Persist a freshly captured result directly and atomically (temp-file-then-rename:
+write to `<path>.tmp` then `mv -f <path>.tmp <path>`) to
+`.dev-team-reports/test-improve/<slug>/data/baseline-mutation.json` — never a
+direct, non-atomic write. The file records the **honest score**: hard kills /
+effective total, with the **timeout count reported separately** (timeouts are
+not counted as kills).
+
+**No-baseline modes skip (`off` and `kill-loop`).** When `phase-0.md` recorded
+mutation mode **`off`** or **`kill-loop`**, `/mutation-testing --baseline` is
+**not invoked** and no `baseline-mutation.json` is written — `kill-loop` runs the
+mutant-kill loop in Phase 5 but takes no baseline first. For `off`, the Phase-8
+mutation target is later marked "not enabled", not waived; for `kill-loop`,
+Phase 8 reports the final-survivor count rather than a baseline delta (see
+Phase 8).
+
+**Go advisory marker.** When the resolved stack is Go and mutation mode is
+`baseline+kill-loop`, the
+mutation baseline is **advisory only** — go-mutesting is alpha-quality (see the
+Go advisory in Phase 0). `baseline-mutation.json` is written with the
+`advisory-only: true` marker; survivor counts are not a gate.
+
+**Ordering invariant.** Baselines land **before any test file is modified** — no file under the stack's test directory may change between Phase 0 and the creation of `baseline-coverage.json` (and `baseline-mutation.json` when applicable). Phase 3, Phase 5, and any subsequent test edits depend on this ordering.

package/skills/test-improve/references/phase-3-derive-gherkin.md

@@ -0,0 +1,53 @@
+Gherkin derivation is **conditional on the Phase-0 BDD rubric answer**. It
+runs only when the operator opted in to a binding mode other than `none`.
+
+**Binding mode `none` — skipped entirely.** When `phase-0.md` recorded binding
+mode `none`, Phase 3 is **skipped**: `/gherkin-derive` is **not invoked**, no
+`.feature` files are written, no runner is added. **Phase 1 follows Phase 2
+directly** in this case — the executed sequence becomes `0 → 2 → 1 → 4 → 5 →
+6 → 7/8 → 9` (one fewer named phase; the banner's `<position>` counter still
+advances 1-9 monotonically).
+
+**Binding mode `xunit-with-annotations` — .feature files without a runner.**
+Invoke `/gherkin-derive --workflow test-improve --mode xunit-with-annotations`.
+The skill merges scenarios into `.feature` files under gherkin-derive's
+resolved destination (recorded in `.claude/memory/test-improve/<slug>/gherkin.md` —
+typically `features/test-improve/`, but dynamically resolved per the repo's
+own BDD convention, not a fixed path — see `/gherkin-derive`'s Step 2)
+— an existing file's prior content (hand-authored, or enriched by
+`/feature-coverage-analyzer`) is preserved; only genuinely new scenarios are
+appended (issue #1420) — and **no runner dependency** is added to the project.
+The corresponding xUnit tests (authored in Phase 5) will carry the scenario
+name plus Given/When/Then leading comments that cite the `.feature` file, but
+they run through the existing xUnit runner.
+
+**Binding mode `bdd-runner` — native parser wired.** Invoke
+`/gherkin-derive --workflow test-improve --mode bdd-runner`. The stack profile
+selects the native parser (`cucumber-js` for JS/TS, `SpecFlow` / `Reqnroll` for
+.NET, `cucumber-jvm` for Java, `godog` for Go). `/gherkin-derive`:
+
+- adds the parser as a project dependency,
+- generates pending step-definition stubs,
+- merges scenarios into `.feature` files under its resolved destination
+  (same dynamic resolution as `xunit-with-annotations` mode, recorded in
+  `.claude/memory/test-improve/<slug>/gherkin.md`), preserving any existing
+  enrichment the same way that mode does (issue #1420).
+
+**Persistence.** Record the surface inventory and (in `bdd-runner` mode) the
+parser wiring to `.claude/memory/test-improve/<slug>/gherkin.md`.
+
+**Human gate.** After Phase 3 produces `.feature` files (or parser wiring in
+`bdd-runner` mode), present them to the operator for review — including
+`gherkin_failure_path_gate.py`'s findings (issue #1420) as part of what's
+being approved, the same reviewed-before-proceeding weight the
+characterization-scenario call-out already carries, not an inert report
+line. **Phase 1 does not run** until the operator approves.
+
+**In `bdd-runner` mode with pending step definitions**, Phase 3's own
+not-done statement (`../../gherkin-derive/SKILL.md` Step 6) and Phase 5's later
+hard block on this same state (below) describe one fact at two checkpoints,
+not two separate requirements — both name `/build` (Phase 5's own per-Story
+build loop) as the remediation. Because Phase 5 already owns "what happens
+next" for this state, `gherkin-derive`'s own proactive "continue into
+`/build` now?" ask is suppressed here — it fires only for a genuinely
+standalone invocation with no enclosing orchestrator.

package/skills/test-improve/references/phase-4-plan-fixes.md

@@ -0,0 +1,34 @@
+Convert Phase 1's ordered improvement plan into actionable work items.
+Delegate the write to
+`/issues-from-assessment --workflow test-improve --refactor-mode <value>`
+(`phase-0.md`'s `no-refactor` or `refactor-allowed`); the skill routes the
+memory + plan paths under `test-improve/` (per Slice 11). Threading
+`--refactor-mode` lets the written plan mark refactor-requiring items
+explicitly: in `no-refactor` mode the Phase-7 `[Refactor-for-testability]`
+work surfaces labeled **out-of-scope / skipped-in-no-refactor**, never as
+actionable Phase-5 Stories.
+
+Every finding lands in exactly one of three actionable **gap classes**, plus
+one non-actionable class:
+
+- **`NO_REFACTOR`** — fixable by test edits alone. Written as **Phase-5
+  Stories** to `.claude/plans/test-improve/` (or the configured parent tracker
+  when `--parent` was supplied at Phase 0).
+- **`REFACTOR_REQUIRED`** — needs a production-code seam before a test can reach the behavior. REFACTOR_REQUIRED items are **deferred to Phase 7** and are **not written as Phase-5 Stories**; they surface with rationale for the operator, who decides at Phase 6 whether to enter Phase 7. Under `refactor-mode: no-refactor` they are labeled **out-of-scope (skipped-in-no-refactor)** in the plan — informational context, never an actionable Story this run will execute.
+- **`LOW_VALUE`** — tests that are cheap to have but not worth fixing (e.g. duplicate coverage, trivial getters, dead-code assertions). LOW_VALUE findings are **advisory-only**: enumerated in the report, no PR is opened to delete a test flagged this way.
+- **`NOT_IMPLEMENTED`** (`/test-health`'s gherkin-gap classification only) — the scenario's behavior doesn't exist in production code at all. Not a test-improve target in **any** mode: it is **not** written as a Phase-5 Story and **not** deferred to Phase 7 — Phase 7 accepts seam introductions only, and there is no seam to introduce for behavior that hasn't been written yet. It surfaces only as a feature-gap call-out in the report, same as `LOW_VALUE`'s advisory-only treatment.
+
+**Story order follows the coverage-gap ranking (issue #1786).** When a
+coverage percentage is a stated goal, the NO_REFACTOR Story set is written in
+`coverage-gap-ranking.json` **rank order** — highest uncovered-line bucket
+first — so Phase 5 spends its budget on the layer that actually holds the
+missing coverage. Pass that order to `/issues-from-assessment` as the order to
+preserve; it **does not re-derive an order of its own**, and neither a mutation
+survivor count nor a finding's position in `/test-health`'s prose reorders the
+set.
+
+**Persistence.** Persist the classified finding set to
+`.claude/memory/test-improve/<slug>/phase-4.md`.
+
+**Human gate.** Present the Phase-5 Story set (NO_REFACTOR only) to the
+operator. **Phase 5 does not run** until the operator approves the set.

package/skills/test-improve/references/phase-5-improve.md

@@ -0,0 +1,215 @@
+Iterate the approved Phase-5 Story set. For **each Story**:
+
+**Never dispatch multiple Stories' build loops in parallel against one shared
+working tree (issue #1571).** Each Story's step 1 runs `/build`, which
+`git add`/`git commit`s as it goes — two or more concurrent dispatches
+against the same checkout race on the index and working files, and that race
+is real: it has produced observed data loss (reverted test files, deleted
+`.feature` files) even when the assigned files looked disjoint, because git
+index/commit operations aren't file-scoped the way file edits are. Process
+Stories one at a time in this session, or — if you fan out multiple Stories
+concurrently via the `Agent` tool — dispatch every one of them with
+`isolation: "worktree"` so each gets its own git working tree; disjoint file
+assignment alone is not a substitute for worktree isolation here.
+
+1. **Build** — invoke `/build <story-id>`. `/build` inherits the **no-refactor**
+   mode from Phase 0: production-code changes are **rejected**. A Story that
+   would require a production-code change is surfaced as a REFACTOR_REQUIRED
+   deferral candidate and re-classified for Phase 6.
+2. **Apply the Phase-0 binding mode.** If Phase 0 selected
+   `xunit-with-annotations`, the resulting test names mirror the source
+   scenario name and Given/When/Then lines appear as **leading comments**
+   citing the source `.feature` file. In `bdd-runner` mode, the step
+   definitions are filled in against the parser wired at Phase 3. In `none`
+   mode, the test is authored idiomatically for the stack without
+   feature-file citations.
+3. **Coverage delta** — after `/build` closes the Story, invoke
+   `/coverage-delta --workflow test-improve --story <id>`. The delta is
+   appended to `.dev-team-reports/test-improve/<slug>/data/coverage-history.json`.
+4. **Coverage-delta steering check (issue #1790).** After the delta is
+   appended — **every Story, not only at the end of the phase** — run the
+   trailing-streak check. Do not eyeball the history:
+
+   ```
+   sh "${CLAUDE_PLUGIN_ROOT}/hooks/py.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/coverage_delta_steering.py" \
+     --history .dev-team-reports/test-improve/<slug>/data/coverage-history.json \
+     --json
+   ```
+
+   - **Exit 0** — continue to the mutation-kill step, but read *which* exit-0
+     status came back: `ok` means the last Story actually moved line coverage;
+     `insufficient_history` means too few Stories have closed (or the latest
+     Story's movement could not be measured) to judge a streak;
+     `flat_streak_forming` means the latest Story did **not** move coverage but
+     the streak is still short of the threshold — echo that one to the operator
+     as a watch signal rather than silently treating it as `ok`.
+   - **Exit 3** (`flat_streak`) — three or more consecutive Stories (the
+     default; `--consecutive` and `--min-line-delta` tune it) moved line
+     coverage by less than the minimum expected per-Story delta.
+     **Surface it now, mid-phase** — a run once spent its entire Phase-5
+     budget on an already-covered layer because this signal was only read at
+     the end; **never defer it to the Phase-9 report.** Print the script's
+     flat-Story list and running average, name the top `seam: absent` modules
+     from `coverage-gap-ranking.json`, and prompt **`[t] re-check Phase-1
+     targeting / [c] continue`** (shape `[t/c]` — `t` is unused elsewhere in
+     this flow, and `c` keeps the "accept and move on" meaning it already has
+     in mutation-kill's `[c/r/w/q]`):
+     - **`[t]`** — re-read `coverage-gap-ranking.json` and re-order the
+       remaining Story set into its rank order (Phase 4's rule, applied to
+       what is left) before the next Story's `/build`. A remaining Story whose
+       target module reads `seam: absent` under `refactor-mode: no-refactor` is
+       re-classified **REFACTOR_REQUIRED for Phase 6 rather than retried** —
+       retrying it under no-refactor is what produced the flat streak.
+     - **`[c]`** — continue, recording `coverage_flat_streak: <n> stories` in
+       `.claude/memory/test-improve/<slug>/phase-5.md` so Phase 8 and the
+       report read it from a durable record instead of re-deriving it.
+     - **Non-interactive runs** record the streak and continue — the same
+       **record-and-continue posture, never a silent pass**.
+   - **Exit 2** — the history file is missing or unreadable. Resolve it (the
+     Story's `/coverage-delta` did not append) rather than treating the
+     unknown as `ok`.
+5. **Mutation-kill, once per module batch (`kill-loop` and
+   `baseline+kill-loop`; skipped when `off`).** The `mutation-kill` agent is
+   opus-tier at `effort: high`, and every dispatch re-pays its fixed priming
+   plus the mutation tool's build/instrumentation warm-up. Phase 4 writes the
+   Story set in `coverage-gap-ranking.json` rank order (#1786), so Stories
+   targeting the same module are **adjacent** — dispatching per Story paid
+   that fixed cost again for a scope that was warm one Story ago (#1963).
+
+   **Group contiguous Stories by target module, then dispatch per batch.**
+   Take the grouping from the ranking's own `modules` buckets — the artifact
+   Phase 2 already computed — never by re-deriving a module map here. A batch
+   is a maximal run of consecutive Stories in the approved order whose target
+   files fall in one bucket; a module with a single Story is a batch of one,
+   which behaves **exactly** as the per-Story dispatch did.
+
+   Steps 1-4 above still run **per Story**, unchanged — the build, the binding
+   mode, the coverage delta, and the steering check are per-Story signals and
+   batching them would blunt exactly the mid-phase steering #1790 added. Only
+   this step batches.
+
+   After the batch's **last** Story closes, invoke the **`mutation-kill`
+   agent** once with `--file <every story file in the batch> --max-rounds 3
+   --target-honest-score <the Phase-0 mutation target>`.
+   Residual survivors trigger the **`[c]ontinue / [r]etry / [w]aive /
+   [q]uit`** prompt — the shape is `[c/r/w/q]` — applied to the batch.
+   `[c]` accepts the residual and moves on; `[r]` re-runs one more
+   mutation-kill round; `[w]` waives the residual to `waivers.json`; `[q]`
+   quits Phase 5.
+
+   **Pass the Phase-0 mutation target (#2030).** Phase 8
+   (`/quality-targets-converge`) gates on that number; without
+   `--target-honest-score` the loop runs toward survivor exhaustion instead
+   and buys full-price rounds whose work cannot change the gate's verdict.
+   Threading it is risk-neutral by construction — the honest score stays the
+   only gate, Phase 8 still measures it independently against
+   `baseline-mutation.json`, and stopping *at* the threshold cannot turn a
+   pass into a fail. Omit the flag when Phase 0 recorded no mutation target;
+   the loop then behaves exactly as it did before #2030.
+
+   **A `YIELD FLOOR` line is an operator decision, not a convergence stop.**
+   When the run is invoked with `--min-kills-per-round` and a round kills
+   fewer survivors than the floor while the file is *still below target*,
+   `mutation-kill` stops that file and logs a line prefixed
+   `YIELD FLOOR —`. That is **not** a terminal stop: route it to the same
+   `[c/r/w/q]` prompt above, carrying the line's kill count and floor into
+   the prompt so the operator can price one more round. Treating it as
+   convergence would stop a below-target file on the loop's own initiative,
+   which is precisely what #2030 declined to do.
+
+   **The gate is unchanged in coverage, only in timing.** Every Story's files
+   are still mutation-processed before Phase 5 can close, at the same rounds
+   cap, behind the same prompt: **Phase 5 may not be reported closed with an
+   unprocessed batch**, exactly as it could not close with an unprocessed
+   Story. What moves is *when within the phase* a weak assertion surfaces —
+   at the batch boundary rather than immediately — which is bounded by batch
+   size and by the fact that `mutation-kill` only ever *adds* tests, so a
+   later Story in a batch cannot be invalidated by an earlier one's residual.
+
+   **Name the batches when the phase starts**, so the operator sees the
+   grouping rather than inferring it from dispatch counts: print one line per
+   batch — `Mutation-kill batch <n>: module <module>, Stories <ids>.`
+
+   **Mutation-yield steering check at the batch boundary (issue #2033).**
+   After each batch's `mutation-kill` dispatch returns, append one record to
+   `.dev-team-reports/test-improve/<slug>/data/mutation-history.json` — the
+   git-tracked `data/` sibling of `coverage-history.json`, written atomically
+   the way the baselines are — carrying `batch`, `module`, `captured_at`,
+   `starting_survivors`, `ending_survivors`, `honest_score_before`,
+   `honest_score_after`, and `rounds_spent`. Then run the trailing-streak
+   check. Do not eyeball the history:
+
+   ```
+   sh "${CLAUDE_PLUGIN_ROOT}/hooks/py.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/mutation_yield_steering.py" \
+     --history .dev-team-reports/test-improve/<slug>/data/mutation-history.json \
+     --json
+   ```
+
+   This is the #1790 mechanism ported to the more expensive lane, and it
+   shares that script's status vocabulary and exit-code contract exactly, so
+   read the exit codes the same way:
+
+   - **Exit 0** — continue to the next batch, but read *which* exit-0 status
+     came back: `ok` means the last batch actually killed survivors;
+     `insufficient_history` means too few batches have closed (or the latest
+     batch's yield could not be measured) to judge a streak;
+     `flat_streak_forming` means the latest batch did **not** clear the
+     minimum but the streak is still short of the threshold — echo that one
+     to the operator as a watch signal rather than silently treating it as
+     `ok`.
+   - **Exit 2** — the history is missing, unreadable, or corrupt. **Never
+     read this as `ok`** — it is the same trap #1790 calls out. Fix the
+     history before continuing.
+   - **Exit 3** (`flat_streak`) — two or more consecutive batches (the
+     default; `--consecutive` and `--min-kills` tune it) killed fewer than
+     the minimum net survivors. **Surface it now, at the batch boundary** —
+     per-Story would be meaningless because `mutation-kill` runs per batch.
+     Print the script's flat-batch list and running average, then prompt
+     **`[t] re-check Phase-1 targeting / [c] continue`** — the same `[t/c]`
+     shape the coverage check uses:
+     - **`[t]`** — re-read `coverage-gap-ranking.json` and re-order the
+       remaining batches into its rank order before the next dispatch.
+     - **`[c]`** — continue, recording
+       `mutation_flat_streak: <n> batches` in the phase's progress file so
+       the Phase-9 report carries the accepted signal rather than losing it.
+6. **Go mutation-kill is advisory.** On Go stacks, `mutation-kill` logs
+   survivors but makes **no commit** — the operator is instructed to apply
+   changes manually. Advisory-only handling matches the Phase-0 Go advisory,
+   and applies per batch exactly as it applied per Story.
+
+#### Pending-stub gate (`bdd-runner` mode only, issue #1391)
+
+After **all Phase-5 Stories have closed**, and only when Phase 0 selected
+`bdd-runner` binding mode, run the completion gate before Phase 5 may be
+reported closed — a hard gate, not prose:
+
+```
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/gherkin_stub_gate.py" --dir <step-definitions-dir>
+```
+
+(`<step-definitions-dir>` is wherever test-improve's own Phase 3 —
+`/gherkin-derive`'s Step 4 (stub generation) / Step 5 (output paths) — wrote
+step-definition files, recorded in `.claude/memory/test-improve/<slug>/gherkin.md`.)
+
+- **Exit 0 (no pending stubs)** — Phase 5 proceeds to the end-of-phase review
+  loop below.
+- **Non-zero (pending stubs remain)** — Phase 5 is **not done**. Surface the
+  gate's listed `file:line` pending step definitions to the operator; do not
+  report the phase closed. Route each remaining stub back into the per-Story
+  build loop (step 2 above — fill in the step definition against the parser
+  wired at Phase 3) rather than silently leaving it pending.
+- Skip entirely when binding mode is `none` or `xunit-with-annotations` (no
+  step definitions exist to gate on).
+
+#### End-of-phase review loop
+
+After **all Phase-5 Stories have closed**, run the review loop over the
+Phase-5 diff, writing evidence to
+`.claude/memory/test-improve/<slug>/phase-5-review.json`:
+
+<!-- include: references/review-loop.md -->
+See `review-loop.md` for the single-panel dispatch, the test-lens
+guarantee, the narrowed fix-confirmation, the escalation cap, and the
+fixed evidence-schema fields.
+
+**`/handoff` suggestion** (context-heavy review). Once the loop above closes, print: `Phase 5 complete. Consider running /handoff to compress context before continuing. To resume: /test-improve <repo-path> --from-phase 6 (or --from-phase with no number to auto-detect the resume point)`

package/skills/test-improve/references/phase-6-refactor-decision.md

@@ -0,0 +1,45 @@
+With Phase 5 closed, present the **REFACTOR_REQUIRED** list deferred at
+Phase 4. Each item is shown with three columns:
+
+- **seam-needed** — the production-code seam the test would need (e.g.
+  interface extraction, dependency injection, virtual method).
+- **behavior-gained** — the untested behavior a Phase-7 refactor would
+  unlock coverage for.
+- **estimated-risk** — a qualitative risk marker (low / medium / high) for
+  the specific refactor.
+
+**Phase 6 branches on the Phase-0 `refactor-mode`.** Read `refactor-mode`
+from `.claude/memory/test-improve/<slug>/phase-0.md` **before** rendering any prompt.
+Entering Phase 7 *is* refactoring, so the choice made at Phase 0 governs
+whether Phase 6 is a branch point at all.
+
+**`refactor-mode: no-refactor` (the default) — informational, not a branch
+point.** The operator declined refactoring at Phase 0, so the **`[y] enter
+Phase 7` option does not exist** in this mode. Present the REFACTOR_REQUIRED
+list as *"the following require refactoring and are out of scope in
+no-refactor mode"* — the seam-needed / behavior-gained / estimated-risk
+columns still render, so the operator sees the coverage and behavior left on
+the table. Then **auto-backlog** every item to
+`.dev-team-reports/test-improve/<slug>/refactor-backlog.md` (or update the parent
+tracker when `--parent` was passed) and **continue to Phase 8** with the
+current Phase-5 test suite as the target. The prompt collapses to a single
+**acknowledge/continue** step (equivalent to today's `[b]`); when no operator
+is attached, run it **non-interactively** — no keystroke is required and none
+enters Phase 7. The sanctioned way to actually perform these refactors is the
+Phase-8 coverage-below-90% re-run prompt, which offers a fresh
+`refactor-allowed` invocation the operator explicitly opts into.
+
+**`refactor-mode: refactor-allowed` — full decision prompt.** Prompt the
+operator with **`[y] enter Phase 7 / [b] backlog and skip to Phase 8 /
+[q] quit`** (shape `[y/b/q]`). The letter `y` was chosen deliberately
+over `r` — `[r]` is already claimed by mutation-kill's `[c/r/w/q]` (retry) and
+the review-loop's `[r/w/q]` (revise); a third `[r]` at the
+highest-consequence prompt would confuse operators.
+
+- **`[y]`** — advances to **Phase 7** (refactor-for-testability).
+- **`[b]`** — writes the REFACTOR_REQUIRED items to
+  `.dev-team-reports/test-improve/<slug>/refactor-backlog.md` (or updates the parent
+  tracker when `--parent` was passed); **skips Phase 7** and runs **Phase 8**
+  directly with the current Phase-5 test suite as the target.
+- **`[q]`** — **quits** before Phase 8. No further phase runs; the final
+  report reflects Phase-5 state only.

package/skills/test-improve/references/phase-7-refactor.md

@@ -0,0 +1,44 @@
+Phase 7 runs **only when the operator picked `[y]` at Phase 6**. If Phase 6
+returned `[b]` (backlog) or `[q]` (quit), Phase 7 is **skipped**.
+
+**Hard mode gate — Phase 7 refuses to run under `no-refactor`.** Before any
+Phase-7 work begins, `/test-improve` re-reads `refactor-mode` from
+`.claude/memory/test-improve/<slug>/phase-0.md`. When it records
+`refactor-mode: no-refactor`, Phase 7 **refuses to run** and is skipped —
+**even if `[y]` is somehow reached**. Phase 6 offers no `[y]` in this mode,
+so this gate is a defense-in-depth backstop: Phase 7 executes production-code
+refactors the `no-refactor` operator declined at Phase 0, and the mode — not
+the keystroke — is the final authority. Only `refactor-mode: refactor-allowed`
+permits Phase 7 to execute.
+
+**Seam-only production code changes.** `/build` in Phase 7 accepts **seam
+introductions only** — interface extractions, dependency injection points,
+virtual method promotions, factory wrapping. Any change beyond a seam is
+rejected. Behavior modifications, refactors that alter semantics, and
+opportunistic clean-ups are all out of scope.
+
+**Existing tests are immutable.** Phase 7 **may not modify or remove existing tests** — `/build` rejects deletions and edits to any file under the stack's test directory that existed before Phase 7 started. The pre-Phase-7 suite must stay green throughout; a red pre-Phase-7 test halts the phase.
+
+**Phase-5 precondition-check.** Each Phase-7 Story is paired with the
+corresponding Phase-5 baseline Story that could not close under no-refactor.
+Before `/build` runs a Phase-7 Story, `/test-improve` **verifies the paired
+Phase-5 Story is closed and green**. A missing or failing Phase-5 baseline
+halts that Story until the operator resolves it.
+
+**Phase 5's parallel-dispatch warning (issue #1571) applies equally here** —
+Phase 7 runs the same per-Story `/build` loop against the same shared
+working tree, so **never dispatch multiple Phase-7 Stories' build loops
+concurrently without `isolation: "worktree"` on every dispatch**; see
+`phase-5-improve.md` for why the race is unsafe.
+
+**End-of-phase review loop.** After all Phase-7 Stories close, run the
+**same review loop as Phase 5**, writing evidence to
+`.claude/memory/test-improve/<slug>/phase-7-review.json` using the same
+fixed schema:
+
+<!-- include: references/review-loop.md -->
+See `review-loop.md` for the single-panel dispatch, the test-lens
+guarantee, the narrowed fix-confirmation, the escalation cap, and the
+fixed evidence-schema fields.
+
+**`/handoff` suggestion** (same rationale as Phase 5). Once the loop above closes, print: `Phase 7 complete. Consider running /handoff to compress context before continuing. To resume: /test-improve <repo-path> --from-phase 8 (or --from-phase with no number to auto-detect the resume point)`

package/skills/test-improve/references/phase-8-validate.md

@@ -0,0 +1,66 @@
+Verify the improved suite meets the Phase-0 quality targets. Delegate to
+`/quality-targets-converge --workflow test-improve --refactor-mode <value>`
+(`phase-0.md`'s `no-refactor` or `refactor-allowed`) — the skill routes
+memory and plan paths under `test-improve/` (per Slice 11), and threading
+the flag keeps the operator's no-refactor choice enforced past Phase 6 via
+its own dispatch-table gating.
+
+**Mutation target per mode.** The mutation target reads differently for each
+Phase-0 mutation mode:
+
+- **`off` — skipped (not waived).** The mutation target is **skipped** and marked
+  "not enabled for this run" — it is **not waived**. Skipping and waiving are
+  distinct outcomes: a waiver signals a target failed and the operator accepted
+  the gap; a skip signals the target was never in scope for this run.
+- **`kill-loop` — final-survivor-only.** No Phase-2 baseline was taken, so there is
+  no before/after delta; the target reports the **final surviving-mutant count**
+  from the Phase-5 kill loop.
+- **`baseline+kill-loop` — baseline-delta.** The target reports the
+  **baseline-to-achieved mutation delta** against `baseline-mutation.json`.
+
+**Go mutation advisory.** When the resolved stack is Go and mutation is not `off`,
+the mutation target is **advisory-only** (survivor count is not a gate). The
+target reads with the "advisory only — go-mutesting is alpha" footnote and
+the run may pass regardless of mutation numbers.
+
+**Branch-scoped mutation validation (issue #1208).** `/quality-targets-converge`
+scopes its Phase-8 mutation measurement to the **branch-vs-base cumulative
+changed set** — the production source exercised by the tests this branch
+changed across all its sessions — never the whole repo. It still reports a
+whole-repo score by splicing the freshly-measured changed files over the
+**persisted** Phase-2 baseline (`baseline-mutation.json`), and reports any
+module it could not measure (OOM/timeout) as **held at baseline** rather than
+omitting it. No extra flag is threaded through the delegation above — the
+worker resolves the branch base itself using the same idiom as `/build`'s
+Farley-Score step. The whole-repo splice relies on the
+`.dev-team-reports/test-improve/<slug>/data/baseline-mutation.json` that
+Phase 2 persisted directly and unconditionally (see
+`phase-2-baseline.md`) — always
+available for this same run; there is no separate copy to fall back on or
+diverge from.
+
+**Coverage < 90% in no-refactor mode.** When Phase 8 closes with coverage
+below 90% and Phase 0 recorded `refactor-mode: no-refactor`,
+`/test-improve` surfaces a **re-run prompt** shaped **`[y/n]`**: *"Coverage is
+below 90% in no-refactor mode. Re-run in refactor-allowed mode to close the
+gap? `[y/n]`"*. The prompt names the **backlogged REFACTOR_REQUIRED items**
+that would close the gap (drawn from `.dev-team-reports/test-improve/<slug>/refactor-backlog.md`
+when `[b]` was picked at Phase 6, or from the Phase-4 deferred list when
+Phase 6 was not reached). Whenever shown, `phase-8.md` records `coverage_reprompt_fired: true` plus the answer — the durable source Phase 9's close-out prompt reads to avoid re-asking (see `phase-9-close-out-prompt.md`).
+
+**Evidence.** Persist target outcomes to
+`.claude/memory/test-improve/<slug>/phase-8.md`.
+
+**Test-count-by-type recount.** Alongside the target-outcome persistence
+above, perform the **identical** classification pass Phase 1's
+"Test-count-by-type snapshot" defined — same six-type criteria, same
+tie-break rule, same repo-path scope Phase 1 used (not a re-scoped or
+differently-scoped recount) — and persist
+`.dev-team-reports/test-improve/<slug>/data/test-counts-after.json` — written
+directly to the same git-tracked `data/` sibling as `test-counts-before.json`
+(same no-other-consumer rationale) — in the identical shape as
+`test-counts-before.json` (same six keys, same order, zero-count keys
+present). See Phase 1's own instruction for the full classification
+mechanism; this pass does not restate it.
+
+**`/handoff` suggestion** (context-heavy re-measurement). Once the recount above is persisted, print: `Phase 8 complete. Consider running /handoff to compress context before continuing. To resume: /test-improve <repo-path> --from-phase 9 (or --from-phase with no number to auto-detect the resume point)`

package/skills/test-improve/references/phase-9-close-out-prompt.md

@@ -0,0 +1,11 @@
+**No prompt** when: `.dev-team-reports/test-improve/<slug>/refactor-backlog.md` does not exist (no `REFACTOR_REQUIRED` items were ever backlogged), the file exists but has zero entries (treated the same as absent), `phase-8.md` records `coverage_reprompt_fired: true` (Phase 8's own coverage-driven `[y/n]` already fired this run — no repeating the same question twice), or `phase-0.md` recorded `refactor-mode: refactor-allowed` (a Phase-6 `[b]` backlog entry under `refactor-allowed` mode is the operator's deliberate deferral, not a no-refactor constraint to lift — re-asking "re-run with refactor-allowed mode now?" would be nonsensical when that's the mode already in use).
+
+**Otherwise** (backlog file has ≥1 entry, Phase 8 never fired its prompt,
+and `phase-0.md` recorded `refactor-mode: no-refactor`), prompt **`[y/n]`**
+— distinct from Phase 8's coverage-driven, mid-run prompt, this one is
+backlog-driven and fires at close-out: *"N REFACTOR_REQUIRED items remain
+backlogged. Re-run with refactor-allowed mode now? `[y/n]`"* (N = entry
+count). `[n]` leaves the backlog as-is. `[y]` — Phase-0 answers are
+immutable per-run, so tell the operator to re-run `/test-improve
+<repo-path>` fresh, choosing `refactor-allowed`; this is a new invocation,
+not `--from-phase`.