mutation-red-team

name	mutation-red-team
description	Launch a mutation-testing agent (Opus) that injects a targeted regression into production code, runs the checks, and reports whether it SURVIVED — a survivor is direct evidence of a test-coverage gap. Use when the user says "mutation test", "break the code", "grade the tests", or after adding production code whose coverage is unproven.

Mutation red-team

Launch an Opus general-purpose agent that does what a mischievous reviewer would if told "try to break this without the checks catching it" — pick a load-bearing invariant, silently mutate it, run the checks, and report the verdict. The invoking agent supplies this project's invariants, commands, and isolation constraints from AGENTS.md.

Surviving mutations are the finding. A SURVIVED mutation means the checks cannot distinguish broken code from working code — a concrete gap pointing at an invariant nothing enforces. Complementary to test-red-team (reads tests statically) and red-team-review (reads prod statically); this is the dynamic, empirical check.

When to invoke

• User says: "mutation test", "break the code", "grade the tests", "can my tests catch regressions"
• After a red-team-review finds a prod bug — confirm the regression test you added actually catches recurrence
• After a milestone that added production code
• Proactively on anything named in AGENTS.md as a load-bearing invariant — above all the GPS publish gate.

How to invoke

Use the Agent tool with:

• subagent_type: "general-purpose"
• model: "opus"
• isolation: "worktree" — mandatory as the outer guard; the agent edits production code. For extra safety (and to survive resume after a transient error re-pointing an agent at a shared tree), the template has the agent snapshot the repo into its OWN fresh temp dir and work there.
• description: 3–5 words (e.g. "Mutation red-team validator")
• prompt: template below. ONE mutation per agent; for N mutations, issue N Agent calls. Watch for shared exclusive resources (a fixed dev/preview port, the real media files) — serialize agents that would collide, and treat any collision as verdict contamination.

Choosing mutations

Do NOT let the agent pick random lines — signal-to-noise on random mutants is terrible. Hand-pick from AGENTS.md invariants: for each named invariant, define ONE mutation that violates it and the specific check that MUST catch it. Concrete starting points for this repo:

• GPS publish gate — in verify_no_gps (build_derivatives.py), make the survivor list always empty (e.g. bad = [] then never appended), or narrow written so a shipped derivative is never passed to the gate. A check worth its name FAILS the build; a SURVIVED mutation here is CRITICAL.
• Metadata stripping — neuter strip_metadata (make it a no-op). The gate should then catch surviving GPS on the shipped derivative.
• Slug identity — remove the slug-collision assert, or make two rows map to one slug.
• Determinism — break fresh() so rebuilds are non-incremental / order dependent.
• Web correctness — weaken a bound/comparison in the clustering or projection math (data.ts / Globe.svelte); npm run check plus any pinned unit test should catch behavioral drift.

Generic mutation shapes: flip/remove a guard, weaken a bound (<→<=, drop a cap), skip a validation step, remove a cleanup on the failure path, drop a stamp/marker a contract depends on, make a "refuse on mismatch" always pass.

Each mutation is stated as an EXACT before→after on ONE named file, tied to the invariant it probes and the check expected to catch it.

Prompt template

You introduce a specific regression into production code, run the checks,
and report whether they caught you. You are operating in an isolated git
worktree — but do NOT work there directly.

## Rules

- FIRST: snapshot the repo into your own fresh temp directory
  (`rsync -a --exclude node_modules --exclude .git --exclude data/derived
  <repo>/ <tmpdir>/`) and do ALL work in that copy; install deps there
  (`cd web && npm ci`).
- Apply EXACTLY the mutation specified below. Do not invent others.
- Do not touch any test file, spec, or fixture. Mutate only the named
  production file.
- Run the project's checks ([EXACT COMMANDS — e.g. `cd web && npm run check`
  and, for a pipeline mutation, the pinned pipeline test / a scoped
  build_derivatives.py run over a fixture]). Capture stdout+stderr and note
  which step failed first (if any).
- Revert the mutation before exiting so the worktree auto-cleans.

## Mutation

File: [ABSOLUTE PATH IN THE COPY]
Change: [EXACT BEFORE → AFTER]
Reasoning-for-humans: [one sentence — which AGENTS.md invariant this probes]

## Verdict

Report exactly:
- CAUGHT if any step failed after the mutation
- SURVIVED if all passed

Include the reported check COUNTS for each step — a verdict without counts
is not trustworthy (a skipped suite reads as a false SURVIVED). For CAUGHT:
name the failing check(s); one to three sentences — is the failure specific
to the invariant, or incidental (e.g. a build error)? For SURVIVED: state
what the code now does incorrectly and what kind of check would have caught
it. No fix — diagnosis only.

## Output format

~150–300 words. Lead with the one-word verdict. Before exiting, `git status`
in the worktree must be clean. Verify and report.

Verdict hygiene

A SURVIVED verdict is only as good as proof the relevant checks actually executed. Require per-step counts, and re-verify any SURVIVED locally (apply the mutation in the main tree, run the narrowest relevant check, revert) before treating it as a gap. Vacuous pins are the dual hazard: a check that early-returns on an environment limitation passes green while asserting nothing — mutation testing is exactly what exposes those; when found, replace the guard with a stub that forces the code path to execute.

Reading the results

• Mutation score = CAUGHT / total. Under 80% is a weak suite; under 50% is dangerous. The GPS gate must score 100% — a leak here is unshippable.
• Surviving mutations by invariant = the prioritized list of missing checks. Every SURVIVED maps to one regression check to add (or one recorded accepted-tradeoff if legitimately unobservable).
• Compare to prior runs — a mutation CAUGHT last cycle that now SURVIVES means a recent change weakened coverage.
• A build-error CAUGHT (type error, not a behavioral failure) is weak evidence — note it; the invariant may still lack a real check.

Cleanup discipline

Stricter than the other red-team skills because this agent writes code.

• Clean revert → worktree auto-deletes. If changes are left, inspect once, then git worktree remove <path>.
• Mutation output belongs inline in the conversation, not a repo file.
• Before returning control: git status clean on the main tree, git worktree list shows no strays, and no exclusive shared resource is left held.