pi-dev-team 0.2.0

package/skills/mutation-testing/references/languages/go-go-mutesting.md

@@ -0,0 +1,95 @@
+# Mutation Testing — Go (go-mutesting, advisory only)
+
+Tool: [go-mutesting](https://github.com/zimmski/go-mutesting). Detection: `go.mod` present; `command -v go-mutesting` resolves (installed to `$GOPATH/bin`).
+
+**Advisory only.** go-mutesting is alpha quality — the surviving-mutant count is **not** a reliable gate. Always pair with Go's built-in fuzzing (production-quality) for boundary and edge-case discovery.
+
+## Install / detect
+
+`go install …@latest` writes the binary to `$GOPATH/bin` (typically `~/go/bin`), and `$GOPATH/bin` must be on `PATH` for `go-mutesting` to resolve. There is no project-scoped alternative — this is the one language path where the skill's "prefer local install" recommendation cannot be honored, so the `PATH` requirement is called out explicitly here rather than hidden.
+
+```bash
+go install github.com/zimmski/go-mutesting/cmd/go-mutesting@latest
+```
+
+Confirm the tool resolves before configuring a run:
+
+```bash
+command -v go-mutesting || echo "go-mutesting not on PATH — check \$GOPATH/bin"
+```
+
+## Run (scoped)
+
+> When capturing run output to a log file, do **not** use a bare `go-mutesting ... 2>&1 | tee run.log` — the pipeline exit code is `tee`'s (always 0), so a tool failure is silently masked. Use `>run.log 2>&1` for one-shot runs or `set -o pipefail` for live tail. See [`SKILL.md` → Capturing run output safely](../../SKILL.md#capturing-run-output-safely).
+
+```bash
+# Whole module
+go-mutesting ./...
+
+# Single package
+go-mutesting ./pkg/order
+```
+
+## Per-mutant timeout flag
+
+go-mutesting has no reliable per-mutant flag. Wrap the process externally:
+
+```bash
+timeout <seconds> go-mutesting ./...   # macOS: gtimeout (from coreutils)
+```
+
+Default shipped: 60 s. Set the outer wrapper timeout to `timeout_seconds` (formula in [`SKILL.md`](../../SKILL.md) Step 1b).
+
+## Native report → schema mapping
+
+go-mutesting has no stable machine-readable report. Parse its stdout (each mutant prints `PASS`/`FAIL` with the mutated `file:line`) and map into the standard envelope, adding `"advisory": true` so callers warn instead of halt. The `equivalent` count is `0` unless triage reclassifies a survivor.
+
+```json
+{
+  "schema_version": 1,
+  "tool": "go-mutesting",
+  "advisory": true,
+  "scope": ["pkg/order/order.go"],
+  "captured_at": "2026-06-26T14:31:00Z",
+  "total": 40,
+  "killed": 31,
+  "survived": 9,
+  "equivalent": 0,
+  "survivors": [
+    { "file": "pkg/order/order.go", "line": 22, "operator": "branch/condition", "status": "survived" }
+  ]
+}
+```
+
+Because go-mutesting is advisory, downstream workflow callers MUST treat `advisory: true` as warn-not-block — a non-zero survivor count never fails the gate.
+
+## Language-specific notes
+
+### Advisory mode rationale
+
+The orchestrated workflows (`/coverage-delta`, `/quality-targets-converge`) treat Go mutation results as **warn, do not block** — surface survivors as suggestions, never block on the count. Advisory mode is enforced by the `"advisory": true` flag on the schema envelope.
+
+Never tell a Go project "no tool installed" without giving both:
+
+1. The go-mutesting install path (above), and
+2. The fuzz alternative (below).
+
+### `go test -fuzz` complement (production-quality)
+
+Native Go fuzzing (Go 1.18+) catches boundary/edge cases mutation testing can miss. The `-fuzz` flag takes a regexp matching a single `FuzzXxx` target and fuzzes **one package at a time** — it is **not** a package glob:
+
+```bash
+# Run every fuzz target's seed corpus as ordinary tests (all packages)
+go test ./...
+
+# Actively fuzz one target (bounded for a pre-merge gate)
+go test -fuzz=FuzzXxx -fuzztime=30s ./path/to/pkg
+```
+
+Manage the fuzz corpus deliberately:
+
+- Seed it from known edge cases.
+- Commit interesting inputs under `testdata/fuzz/` so failures reproduce in CI.
+- Run a bounded `-fuzztime` in the pre-merge gate while letting longer campaigns run out of band.
+
+Pair the advisory go-mutesting result with `go test -fuzz` findings when reporting to the operator.

package/skills/mutation-testing/references/languages/java-pitest.md

@@ -0,0 +1,77 @@
+# Mutation Testing — Java / Kotlin (pitest)
+
+Tool: [pitest](https://pitest.org/). Detection: `pom.xml` or `build.gradle` has `pitest` plugin.
+
+## Install / detect
+
+Both install paths are **project-scoped by design** — the Maven `<plugin>` declaration and the Gradle `info.solidsoft.pitest` plugin resolve through the build tool's own dependency resolution, not through any user-configured `PATH`. There is no meaningful "global" alternative to pitest, so this language avoids the silent-failure trap the skill's "prefer local install" note is guarding against.
+
+Maven:
+
+```xml
+<plugin>
+  <groupId>org.pitest</groupId>
+  <artifactId>pitest-maven</artifactId>
+  <version>1.17.4</version>
+</plugin>
+```
+
+Gradle: add the `info.solidsoft.pitest` plugin.
+
+Confirm the plugin resolves before configuring a run:
+
+```bash
+# Maven: prints the help header for the mutationCoverage goal
+./mvnw org.pitest:pitest-maven:help -Ddetail=true -Dgoal=mutationCoverage | head -1
+
+# Gradle: lists the pitest tasks the plugin registers
+./gradlew tasks --group=pitest
+```
+
+## Run (scoped)
+
+> When capturing run output to a log file, do **not** use a bare `mvn pitest:mutationCoverage ... 2>&1 | tee run.log` — the pipeline exit code is `tee`'s (always 0), so a tool failure is silently masked. Use `>run.log 2>&1` for one-shot runs or `set -o pipefail` for live tail. See [`SKILL.md` → Capturing run output safely](../../SKILL.md#capturing-run-output-safely).
+
+```bash
+# Specific class
+mvn pitest:mutationCoverage -DtargetClasses="com.example.Calculator"
+
+# With history (faster incremental runs)
+mvn pitest:mutationCoverage -DwithHistory
+```
+
+## Per-mutant timeout flag
+
+CLI:
+
+```bash
+mvn pitest:mutationCoverage -DtimeoutConst=60 -DtimeoutFactor=2.5
+```
+
+Default shipped: 60 s constant. Set `-DtimeoutConst` to `timeout_seconds` (formula in [`SKILL.md`](../../SKILL.md) Step 1b).
+
+## Native report → schema mapping
+
+Source: `target/pit-reports/<date>/mutations.xml`. Map `<mutation status="SURVIVED">` to `survived`; `<mutation status="NO_COVERAGE">` to `survived` (uncovered, but technically a survivor for downstream callers).
+
+```json
+{
+  "schema_version": 1,
+  "tool": "pitest",
+  "scope": ["src/main/java/com/example/Calculator.java"],
+  "captured_at": "2026-06-19T14:25:11Z",
+  "total": 36,
+  "killed": 30,
+  "survived": 4,
+  "equivalent": 2,
+  "survivors": [
+    { "file": "src/main/java/com/example/Calculator.java", "line": 19, "operator": "CONDITIONALS_BOUNDARY", "status": "survived" }
+  ]
+}
+```
+
+## Language-specific notes
+
+- **`withHistory`** — pitest skips mutants killed in prior runs when history is enabled. First run is slow; incremental runs are fast. Use it in CI for changed-file gates.
+- The pitest HTML report under `target/pit-reports/` is the canonical triage view — note the path when reporting back.
+- For multi-module Maven projects, run `pitest:mutationCoverage` from the aggregator POM and review each module's report individually.

package/skills/mutation-testing/references/languages/javascript-stryker.md

@@ -0,0 +1,188 @@
+# Mutation Testing — JavaScript / TypeScript (Stryker)
+
+Tool: [Stryker Mutator](https://stryker-mutator.io/). Detection: `package.json` has `@stryker-mutator/core` or `stryker.conf.json` exists.
+
+## Install / detect
+
+`--save-dev` is the **local** install path — the binary resolves via `node_modules/.bin` (which `npm run` / `npx` add to `PATH` scope-locally), so no global `PATH` edit is needed. Prefer this over `npm install -g @stryker-mutator/core`, which is the silent-failure trap called out in the skill's "prefer local install" note.
+
+```bash
+npm install --save-dev @stryker-mutator/core @stryker-mutator/vitest-runner  # or jest-runner, karma-runner
+npx stryker init
+```
+
+Confirm the tool resolves before configuring a run:
+
+```bash
+npx stryker --version
+```
+
+## Run (scoped)
+
+> When capturing run output to a log file, do **not** use a bare `npx stryker run ... 2>&1 | tee run.log` — the pipeline exit code is `tee`'s (always 0), so a tool failure is silently masked. Use `>run.log 2>&1` for one-shot runs or `set -o pipefail` for live tail. See [`SKILL.md` → Capturing run output safely](../../SKILL.md#capturing-run-output-safely).
+
+```bash
+# Specific files
+npx stryker run --mutate "src/calculator.ts"
+
+# Changed files only (CI mode)
+npx stryker run --mutate "$(git diff --name-only HEAD~1 -- '*.ts' | grep -v test | tr '\n' ',')"
+```
+
+### Static-mutant skip (`--skip-static-mutants`)
+
+[`mutation-kill`](../../../../agents/mutation-kill.md#invocation)'s opt-in,
+default-OFF `--skip-static-mutants` flag excludes mutants Stryker's
+**native** `reports/mutation/mutation.json` report marks `"static": true`
+from the survivor list handed to **the generation step only**, for that
+round. The filter itself is computed by calling `survivors_by_mutator(...,
+skip_static=True)` in `mutation_report.py` — invoke it through its CLI
+wrapper,
+`python3 "${CLAUDE_PLUGIN_ROOT}/skills/mutation-testing/scripts/mutation_report_cli.py"
+--survivors-by-mutator --skip-static --report <path> --file <path>`, rather
+than re-deriving it here or importing the library directly: the CLI is
+where the inapplicable-skip notice below lives — a bare library call
+computes the same filtered result but emits no diagnostic. A static mutant
+sits in code that runs once at module-initialization time rather than
+per-test, so `coverageAnalysis: "perTest"` cannot isolate it to the tests
+covering it — Stryker must re-run the entire suite to verify one, which is
+what "forcing a full-suite re-run" means in practice. (This field name and
+execution behavior are Stryker's own; verify against the Stryker docs for
+your installed version before relying on it in an automated pipeline.)
+
+**What the trade-off actually buys.** The filter runs *after* Stryker has
+already produced the report — it cannot make Stryker's own run faster, and
+does not claim to. What it saves is the generation-and-verify **rounds**
+`mutation-kill` would otherwise spend chasing mutants that are expensive to
+confirm killed (each needs a full-suite re-run to verify), at the cost of
+deferring each skipped static mutant rather than eliminating it: a skipped
+static mutant that a full-suite run would have killed stays counted as an
+unaddressed survivor for this pass, folded into the accepted-survivors
+accounting below rather than dropped silently.
+
+**Scoring and convergence stay unfiltered.** The `survivors == 0`
+convergence exit, the no-improvement stop predicate, and the honest/reported
+scores all read the report's full, unfiltered survivor count — a file whose
+only remaining survivors are static must never be written as `status:
+"converged"`.
+
+**Line-clustering counts every survivor; only the mutator-grouped generation
+list narrows (#1948, resolved as Option A).** `survivors_by_line()` DOES
+accept a `skip_static` parameter now, but it is a deliberate **no-op** on
+the returned clusters: a static-flagged survivor still counts toward its
+line's cluster weight/ranking exactly as it would without the flag, because
+it's still real evidence of that line's mutation density — only the
+mutator-grouped generation input (`survivors_by_mutator(...,
+skip_static=True)`) actually narrows which mutants get a test written. This
+is a permanent design decision, not an open gap: clustering (the first step
+of generation per [`mutation-kill.md`'s priority-order
+guidance](../../../../agents/mutation-kill.md#target-mutation-types-in-priority-order))
+and the mutator-grouped narrowing that follows it are intentionally
+decoupled.
+
+**Reconciling a clustered-but-unfiltered ranking with a filtered generation
+list in practice.** When you pick a cluster to attack (highest
+survivors-per-line first, per the priority-order guidance) and
+`--skip-static-mutants` is active, don't assume every survivor in that
+cluster is a generation candidate — check each survivor's own `static`
+field (present on the raw mutant dict `survivors_by_line()` returns) before
+writing a test for it:
+
+- If the cluster has a **mix** of static and non-static survivors, write
+  the test(s) targeting the non-static ones as usual; the static ones stay
+  present in the cluster (contributing to its weight) but are not
+  individually targeted this round.
+- If **every** survivor in the top cluster is static, that line has no
+  generation candidate this round even though it ranked first — move to the
+  next cluster with a non-static survivor rather than generating nothing
+  for the "top" line and stopping. The all-static cluster's survivors still
+  count toward the file's raw survivor total and (once folded via
+  `--accepted-static-survivors --skip-static`, below) the accepted-survivors
+  accounting — they are deferred, not lost.
+
+**`adjusted_score` does account for static-skipped mutants.** After the
+existing `--skip-static --survivors-by-mutator` generation call, also call
+`mutation_report_cli.py --accepted-static-survivors --skip-static --report
+<path> --file <path>` and fold each returned entry into the file's own
+"Accepted Survivors (deferred)" table and `adjusted_score` computation,
+exactly like any other `status: "accepted"` entry (see [mutation-kill.md's
+Accepted survivors: raw vs adjusted
+score](../../../../agents/mutation-kill.md#accepted-survivors-raw-vs-adjusted-score)).
+`--skip-static` is required on this call: `accepted_static_survivors()`
+returns `[]` unless its `skip_static_active` evidence is `True`, so calling
+`--accepted-static-survivors` without `--skip-static` yields no accepted
+entries at all, even when static survivors exist in the report. This is now
+documented via the same accepted/reason mechanism used elsewhere in
+`mutation-kill` — not the undocumented, adjusted-score-invisible over-count
+the prior wording described. Clustering (`survivors_by_line()`) still counts
+every survivor including static ones (see above) — it does not filter, so
+there is nothing here for `--skip-static` to have "touched" in the first
+place. **The prior "known overlap" caveat (#1948) is resolved**, not merely
+narrowed: follow the reconciliation guidance above (check each survivor's
+own `static` field before writing a test for it) and a static survivor
+folded into this accepted table is never also independently targeted by
+this same round's generation step — the two paths agree by construction, not
+by coincidence.
+
+**Fallback when the field is absent.** `mutation_report_cli.py --skip-static`
+detects this itself and prints a one-line notice to stderr, distinguishing
+two causes: no mutant in the matched file carries a `static` key at all (an
+older Stryker version, or a report already normalized before the filter
+runs), or the target file isn't present in the report at all. Either way,
+skip is inapplicable; the agent's job is only to surface/relay that notice,
+not re-detect the inapplicable case itself.
+
+**Scope: interactive agent path only.** The `--skip-static-mutants`
+*invocation* flag on `/mutation-kill` itself is agent-parsed prose, not an
+argparse flag — there is no scripted JS/TS mutation-kill loop to add it to
+(unlike the C#/Python loops' real `--headless`/`--model`/`--report` flags).
+The underlying filter *computation* it drives is scripted, though: a real
+argparse flag on `mutation_report_cli.py` (see above). Passed against a
+non-JS/TS target in the interactive path, the invocation flag has no effect
+and the agent prints a one-line ignored notice. It is **not** a flag on
+`mutation_kill_loop.py`/`mutation_kill_loop_python.py`'s `--headless` CLI —
+passing it there is an `unrecognized arguments` error, by design, the same
+as any flag those scripts don't declare. Under `--all --parallel <n>`,
+each spawned sub-agent's prompt must carry the flag explicitly; it does not
+propagate automatically to Phase-4 fan-out sub-agents.
+
+## Per-mutant timeout flag
+
+Configure in `stryker.config.js`:
+
+```js
+{
+  timeoutMS: 60000,       // hard wall-clock cap per mutant
+  timeoutFactor: 2.5,     // multiplier over baseline test time
+}
+```
+
+Default shipped: 60 000 ms. Set `timeoutMS` to `timeout_seconds × 1000` (formula in [`SKILL.md`](../../SKILL.md) Step 1b).
+
+## Native report → schema mapping
+
+Source: `reports/mutation/mutation.json`. Map `metrics` to top-level totals and `files[*].mutants[]` to `survivors[]`.
+
+```json
+{
+  "schema_version": 1,
+  "tool": "stryker",
+  "scope": ["src/calculator.ts"],
+  "captured_at": "2026-06-19T14:22:08Z",
+  "total": 50,
+  "killed": 41,
+  "survived": 6,
+  "equivalent": 3,
+  "survivors": [
+    { "file": "src/calculator.ts", "line": 42, "operator": "ConditionalBoundary", "status": "survived" },
+    { "file": "src/calculator.ts", "line": 67, "operator": "ReturnValue",        "status": "equivalent" }
+  ]
+}
+```
+
+`status: "equivalent"` is set when Stryker's `status` field is `NoCoverage` paired with an operator type the triage step (`SKILL.md` Step 4) classifies as equivalent; otherwise `survived`.
+
+## Language-specific notes
+
+- **`coverageAnalysis: "perTest"`** — set in `stryker.config.js` to run only tests covering the mutated line. This is the single biggest knob on per-mutant time; without it, per-mutant time ≈ full suite time.
+- Stryker's HTML report (`reports/mutation/index.html`) is the most useful triage view — note the path when reporting back.

package/skills/mutation-testing/references/languages/python-mutmut.md

@@ -0,0 +1,97 @@
+# Mutation Testing — Python (mutmut)
+
+Tool: [mutmut](https://mutmut.readthedocs.io/). Detection: `mutmut` in requirements or pyproject.
+
+**Pin `mutmut<3`.** mutmut 3.x ships an incompatible config/CLI contract
+(`source_paths` in a `[mutmut]` setup.cfg section, no `--paths-to-mutate`
+flag, no `run`/`results`/`junitxml` subcommands in the same shape) that the
+adapter and this reference below do not speak. `pip install mutmut`
+unpinned resolves to 3.x today.
+
+## Install / detect
+
+Both install paths are **local** — scoped to the active virtual environment (`.venv/bin/mutmut`), not the system-wide `pip`. Pick one:
+
+```bash
+# (a) install directly into the active venv
+pip install "mutmut<3"
+
+# (b) declare it in pyproject.toml and let pip resolve it as a dev dep
+# [project.optional-dependencies]
+# dev = ["mutmut<3"]
+pip install -e .[dev]
+```
+
+Never `pip install --user mutmut` or run `pip install` outside a venv for this — that puts mutmut in a location whose `PATH` presence depends on the user's shell config, which is the silent-failure trap the skill's "prefer local install" note is trying to avoid.
+
+**The mutmut venv's own Python must be <= 3.12 — distinct from the `--runner`'s interpreter.** `mutmut<3` (2.5.1) crashes under Python 3.13+ with `TypeError: cannot pickle 'itertools.count' object` (a parso/pony-ORM deepcopy incompatibility inside mutmut's own line-caching layer) and produces a junitxml report with **zero testcases at all** — indistinguishable from a fully-converged file by survivor count alone (#1359). This is a version constraint on the interpreter mutmut *itself* runs under, not on the project: build the mutmut venv with `python3.12 -m venv <path>` (or any <=3.12 interpreter) even when the project's real Python is newer, and point `--runner` at the project's normal interpreter (e.g. `--runner "python3 -m pytest ..."`, which can be 3.13+) — only the mutmut process itself needs the older Python. `mutation_kill_loop_python.py`'s `run_for_file` treats a report with zero total mutants (`killed + survived + timeout + no_coverage == 0`) as a crash signal, not convergence, and stops without declaring `survivors == 0` — but avoiding the crash in the first place is cheaper than recovering from it every round.
+
+Confirm the tool resolves in the active venv before configuring a run
+(`version` is a subcommand — there is no `--version` flag):
+
+```bash
+mutmut version
+```
+
+## Run (scoped)
+
+> When capturing run output to a log file, do **not** use a bare `mutmut run ... 2>&1 | tee run.log` — the pipeline exit code is `tee`'s (always 0), so a tool failure is silently masked. Use `>run.log 2>&1` for one-shot runs or `set -o pipefail` for live tail. See [`SKILL.md` → Capturing run output safely](../../SKILL.md#capturing-run-output-safely).
+
+```bash
+mutmut run --paths-to-mutate=src/calculator.py
+```
+
+## Per-mutant timeout
+
+mutmut has no `--timeout <seconds>` flag. Its own per-mutant timeout is
+`baseline_time * test_time_multiplier + test_time_base` (`-m`/`-b`,
+defaults `2.0`/`0.0`) — a mutant whose test run exceeds that computed
+budget is reported `TIMEOUT`. The shipped adapter
+(`hooks/mutation_adapters/mutmut.py`) does not rely on this; it wraps the
+whole `mutmut run` invocation in an external, OS-level timeout
+(`ADAPTER_TIMEOUT`, from `MUTATION_GATE_TIMEOUT`, default 120s) so a
+runaway run is killed regardless of mutmut's own per-mutant accounting.
+
+## Native report → schema mapping
+
+mutmut has no `--json` results output. Source: `mutmut junitxml` — a
+`<testcase>` with a `<failure>` child is a survived mutant under the
+default suspicious/untested policies (both `ignore`); one without is
+killed. `name`, `file`, and `line` come from the `<testcase>` attributes:
+
+```xml
+<testcase name="Mutant #8" file="src/calculator.py" line="12">
+  <failure type="failure" message="bad_survived">--- diff ---</failure>
+</testcase>
+```
+
+Map each `<failure>`-bearing `<testcase>` to a `survived` entry in the
+normalized envelope below (`operator` has no mutmut equivalent — omit it
+or leave `null`, unlike Stryker/pitest which name a mutator/operator per
+survivor):
+
+```json
+{
+  "schema_version": 1,
+  "tool": "mutmut",
+  "scope": ["src/calculator.py"],
+  "captured_at": "2026-06-19T14:28:42Z",
+  "total": 28,
+  "killed": 22,
+  "survived": 5,
+  "equivalent": 1,
+  "survivors": [
+    { "file": "src/calculator.py", "line": 12, "operator": null, "status": "survived" }
+  ]
+}
+```
+
+This normalized envelope is produced by the triaging agent reading the
+native report (per this doc's mapping) — `mutation_report.py` and
+`mutation_kill_loop.py` have no mutmut-specific parsing yet (see
+[SKILL.md → Machine-readable output](../../SKILL.md#machine-readable-output)).
+
+## Language-specific notes
+
+- mutmut stores per-mutant state in `.mutmut-cache` — keep it out of version control but cache it between CI runs for incremental speed.
+- For pytest-based suites, ensure the runner inherits the project's `PYTHONPATH` / virtualenv; mutmut shells out to the same `python` it was invoked with.

package/skills/mutation-testing/references/time-estimation.md

@@ -0,0 +1,34 @@
+# Mutation Testing: Time Estimation
+
+Before running, estimate and present the expected duration to the user.
+
+**Formula:** `mutation time ≈ (number of mutants) × (per-mutant test time)`
+
+Tools optimize per-mutant time significantly:
+
+- **Stryker** with `coverageAnalysis: "perTest"` runs only tests covering the mutated line, not the full suite. See [`languages/javascript-stryker.md`](languages/javascript-stryker.md).
+- **pitest** with `withHistory` skips mutants killed in prior runs — first run is slow, incremental runs are fast. See [`languages/java-pitest.md`](languages/java-pitest.md).
+
+**Rough heuristics (with per-test coverage analysis enabled):**
+
+| Scope | LOC | Expected Duration |
+| --- | --- | --- |
+| Single small file | 50-200 | Seconds to ~1 min |
+| Single medium file | 200-500 | 1-5 min |
+| Multiple files / module | 500-1000 | 5-15 min |
+| Full codebase | 1000+ | 10 min to hours |
+
+The biggest variable is **test execution speed**, not mutant count. A project with slow integration tests will hurt far more than one with many mutants but fast unit tests.
+
+**How to estimate for a specific project:**
+
+1. Check how long the test suite takes: `time npm test` or `time mvn test`
+2. Count approximate mutants: ~5-15 mutants per 100 LOC depending on code density
+3. With per-test coverage: per-mutant time is typically 5-20% of full suite time
+4. Without per-test coverage: per-mutant time ≈ full suite time (configure coverage analysis!)
+
+**Present to user before running:**
+
+> Mutation testing on `src/calculator.ts` (~150 LOC, ~20 mutants). Test suite runs in ~3s. Estimated time: under 1 minute. Proceed?
+
+If the estimate exceeds 5 minutes, suggest scoping down or confirm the user is willing to wait.

package/skills/mutation-testing/references/tool-detection.md

@@ -0,0 +1,15 @@
+# Mutation Testing: Tool Detection
+
+Detect the project's language and resolve to a mutation tool. Each row links to the language-specific knowledge file with install, run, timeout, and report-mapping detail.
+
+| Ecosystem | Tool | Detection | Knowledge file |
+| --- | --- | --- | --- |
+| JS/TS | [Stryker](https://stryker-mutator.io/) | `package.json` has `@stryker-mutator/core` or `stryker.conf.json` exists | [`languages/javascript-stryker.md`](languages/javascript-stryker.md) |
+| Java/Kotlin | [pitest](https://pitest.org/) | `pom.xml` or `build.gradle` has `pitest` plugin | [`languages/java-pitest.md`](languages/java-pitest.md) |
+| Python | [mutmut](https://mutmut.readthedocs.io/) | `mutmut` in requirements or pyproject | [`languages/python-mutmut.md`](languages/python-mutmut.md) |
+| C#/.NET | [Stryker.NET](https://stryker-mutator.io/docs/stryker-net/introduction/) | `dotnet-stryker` in tool manifest | [`languages/csharp-stryker-net.md`](languages/csharp-stryker-net.md) |
+| Go | [go-mutesting](https://github.com/zimmski/go-mutesting) | `go.mod` present; `command -v go-mutesting` resolves (installed to `$GOPATH/bin`). **Advisory only.** | [`languages/go-go-mutesting.md`](languages/go-go-mutesting.md) |
+
+**Do not proceed to mutation testing without a working tool.** If detection finds nothing, follow the install steps in the matching language file. If the user declines to install one, explain that the skill requires real test execution and cannot substitute estimation.
+
+**Go is the one exception** where "no tool" still yields an actionable path: install go-mutesting in advisory mode, or fall back to `go test -fuzz`. Never report "no tool installed" to a Go project without giving both — see [`languages/go-go-mutesting.md`](languages/go-go-mutesting.md).

package/skills/mutation-testing/references/workflow-callers.md

@@ -0,0 +1,23 @@
+# `--workflow-managed-approval` — approved caller registry
+
+The `--workflow-managed-approval` flag on `/mutation-testing` bypasses the Step 0 confirmation prompt because the calling workflow captured operator approval at a higher boundary. The flag is **not** general-purpose; it is a narrow carve-out for orchestrated workflows whose Phase 0 (or equivalent) already obtained explicit operator consent for the run as a whole.
+
+This file is the source of truth for the allowlist. `/mutation-testing` `## Constraints` references this file by path so a new caller only has to update one place.
+
+## Allowed callers
+
+| Caller skill | Workflow it belongs to | Where its approval is captured | Why the carve-out applies |
+| --- | --- | --- | --- |
+| [`/coverage-delta`](../../coverage-delta/SKILL.md) | `/test-improve` Phase 4 (per-Story coverage delta + optional mutation gate) | `/test-improve` Phase 0 ("Approach contract" — the mutation-mode knob (`off` / `kill-loop` / `baseline+kill-loop`) is the workflow-level approval point) | Phase 4 measures mutation per Story automatically when the mutation mode is not `off`; per-invocation prompts would block the workflow on every Story close. |
+| [`/test-improve`](../../test-improve/SKILL.md) | `/test-improve` Phase 2 (baseline mutation, in `baseline+kill-loop` mode) | `/test-improve` Phase 0 (same mutation-mode knob) | Phase 2 measures the mutation baseline across the in-scope files once before any test change so later phases have a floor; a per-invocation prompt at that boundary would break the workflow-level-approval contract. |
+| [`/quality-targets-converge`](../../quality-targets-converge/SKILL.md) | `/test-improve` Phase 6 (Validate convergence loop) | `/test-improve` Phase 0 (same mutation-mode knob) | Phase 6 runs the convergence loop under the `/test-improve` orchestrator; approval was captured once at Phase 0. `/test-improve` Phase 4 drives mutation via the `mutation-kill` agent (which wraps the tool directly and never sets this flag), so the flag enters only through this Phase-6 caller. |
+
+## Adding a new caller
+
+Any new caller must:
+
+1. Document where its workflow-level operator approval is captured (a named Phase, gate, or skill that prompts once for the entire run).
+2. Add a row to the table above naming the caller, the workflow, the approval-capture point, and why the carve-out is justified.
+3. Land all three changes (the new caller, this row, and any cross-skill cross-reference) in the same PR so the auditor can see the full intent.
+
+`/mutation-testing` `## Constraints` is the enforcement surface: it asserts the carve-out invariant but **does not enumerate callers inline**. Reviewers verify allowlist membership by reading this file. Bats tests in `tests/skills/mutation_testing_scoping_tests.bats` assert (a) the carve-out paragraph exists in `## Constraints`, (b) the named callers (`/coverage-delta`, `/quality-targets-converge`) appear in `## Constraints` for human-readable discoverability — once a third caller lands, that test can either be widened or replaced with an assertion that the constraint references this registry.