mutation

mutation

A thin launcher over the existing mutation-runner agent and the fanout stage. The shared engine lives in docs/STAGES.md; this skill does not restate it.

Mutation is analysis-only (like audit): it surfaces surviving mutants and emits work-unit proposals as data for tdd/triage to lift — it never writes or spawns test authors. A surviving mutant means no test fails when the code is broken there — a coverage gap.

Cardinal rules

1. You are the single writer of any run-state you persist; the stage returns data, you merge.
2. A proposal describes the under-tested BEHAVIOR CLASS, never the mutant. "X must reject a zero-length header" — not "kill the < → <= mutant at line 42". Anchoring a test to a mutant produces a brittle, vacuous test.
3. nothing_scanned/zero-mutant is loud. A tool that scanned nothing (absent / empty scope / build failure) is reported distinctly from a real 100% mutation score.
4. Surfaced-bug reflex (STAGES.md rule 7): if this run hits a real defect it is not told to fix — in the target or in straitjacket's own tooling — capture it via straitjacket:report-bug, then resume or stop. Never pivot to fixing or consulting on a fix; turning a surviving-mutant gap or a captured bug into a fix is a tdd/triage job.

Args

• <target> — a file, crate::module, directory, or project to mutate. Absent → the crate/project at repo_root.
• --scope file|module|project — mutation granularity (default: file for Rust, project for C# — Stryker's warm-up makes per-file thrash).
• --file-proposals — also write the proposals to <run_id>/work-units.json as pending units (default: emit them in the summary only, for review first).

Preflight

1. Confirm a git repo; resolve repo_root; tree should be green (mutation is in the green-baseline preflight matcher — mutants are only meaningful against a passing suite). Generate run_id.
2. straitjacket detect-stack --repo-root <repo_root> → stack.
3. Probe the mutation tool (cargo mutants --version / dotnet stryker --version) → <run_id>/tooling.json. If genuinely absent → STOP with a clear message (mutation has no static fallback). If the tool is reported absent but you can see it is installed, treat it as a straitjacket false-negative probe bug and apply the surfaced-bug reflex (STAGES.md rule 7) — capture via straitjacket:report-bug — then STOP and tell the user the run is blocked on a captured plugin bug (do not fix the probe inline; that is a tdd/triage job).

Run the mutation pass

1. Partition the target into runner tasks by --scope (one task per file/module/project).
2. Run the mutation team — capped at 2-3. Workflow path: the fanout stage (tasks = one mutation-runner per target, cap: 3); read the runners' shape off the stage's raw (each returns {surviving_mutants:[...]}, not results). Agent path: spawn the runners in one message. Each returns its mutation score + surviving mutants (file, line, function, original, mutated, mutator).
3. Turn survivors into proposals. For each surviving mutant, infer the under-tested behavior class it exposes and emit a work-unit proposal: { intended_behavior, target_file, target_symbol, kind }. Dedupe proposals that target the same behavior. If --file-proposals, write them to work-units.json as pending, source_of_unit: "mutation_runner", for a tdd run to author.

Final summary (present verbatim)

• Run metadata: run_id, stack, scope, targets mutated.
• Mutation score per target (killed / (killed + survived)).
• 🧟 Surviving mutants (file:line · mutator) — grouped by behavior class.
• 🧪 Coverage-gap proposals (the data to lift with tdd): each proposed intended_behavior + target_file/target_symbol.
• Degraded / skipped (loud): tool absent, targets that failed to build, nothing_scanned.
• Known-limitation note: "A surviving mutant is a hint of a coverage gap, not proof of a bug; some mutants are equivalent (no behavioral change) and should be dismissed, not tested."

Notes

• A capped Haiku mutation-runner team; the proposal-framing is the skill's judgment. Artifacts under <repo>/.straitjacket/<run_id>/; the CLI is on PATH via the plugin's bin/.
• This is the same machinery the tdd post-green stage runs inline; here it is exposed stand-alone so a dev can mutation-test without a full cycle.