refactor(ci)!: retire the mutation runner onto batten mutate so coverage can reach the Rego layer (CLOUD-1267)

[wenzowski]

Closes CLOUD-1267.

The problem

mise-tasks/mutant.sh:156-158 resolved a gate's SOURCE with a Rego fallback and its SUITE with none:

src="mise-tasks/$gate.sh"
[[ -f "$src" ]] || src="policy/$gate.rego"   # the source has a fallback
suite="tests/$gate.bats"                      # the suite has none

So a mutation could be applied to a .rego module and no suite could ever turn red. At head: 32 policy modules, 32 #MUTANT-EXEMPT rows, 0 tests/.bats, 141 compiled-binary tiers the runner could not see. Seven modules already carried 30 #MUTANT rows that no run had ever applied — a declaration reading as coverage, which is the defect CLOUD-418 exists to refuse, one level up.

This could not be fixed by editing mutant.sh: V-SHELL-RULE-EDITED declares one route, no override, no bypass_env. CLOUD-1111 established that and took the per-migration exemption instead, so the enforced set shrank by one per CLOUD-843 migration while the campaign reported progress. The bundle is the retirement.

What changed

1. feat(mutate) — batten mutate {sweep,census}, a spawning-side verb (Write on the two spawning leaves, Read on census). It cannot be check: §5 declares check read and structurally incapable of spawning; CLOUD-1171's perf pair is the settled precedent.
2. refactor(ci)! — the four predecessor paths deleted, with four file-granularity conserves arms and 37 case arms. hk.pkl and mutant.yml call by task name and are ungoverned — the names survive as one-line [tasks.*] wrappers, so neither caller changes.
3. test(policy) — 26 #MUTANT-EXEMPT rows withdrawn and those modules put into the enforced set against their Rust tiers.

The one behavioural change

A gate's suite comes from a declared mapping — #MUTANT-SUITE crates/batten/tests/.rs — falling back to tests/.bats. The Rust arm runs cargo inside the staged tree, because common::at_root is env!("CARGO_MANIFEST_DIR") and a prebuilt binary would read the unmutated module and let every mutation spuriously survive.

Every predecessor signal is conserved as a distinguishable outcome — no-suite, names-no-case, no-mutant-declared, malformed-row, case-already-red, filter-names-every-case, unappliable-mutation, inert-mutation, self-mutating-row, SURVIVED — because each is a could-not-look and collapsing one into a pass is the defect.

Measured result

	origin/main at branch point	this branch
gates in $MUTANT_GATES	95	120
declared mutations	202	255
module exemptions	32	6

The 6 surviving exemptions each name a different reason — no compiled-binary tier names that module at all — checked one at a time rather than swept. The gate count moved during the branch's life as main retired shell tasks onto the engine (hook-profile-check, renovate-config-validator, gh-guard, memories-check, rules-drift); it is larger than main's at every point, which is the reversal CLOUD-1111's shrinkage asked for.

mutant-census: closed, every gate enforced or exempt by a filed row.

mutant: red, and that is the acceptance. 13 survivors, each carrying an owner:

• validator-verdict-clean/unclean-verdict-unread — #MUTANT-OWNER CLOUD-1265. Nothing writes a tool-verdict record, so the predicate resolves null and refuses nothing. Not patched — building the producer is CLOUD-1265's, and patching this to get green is the laundering the sweep exists to catch.
• 8 × CLOUD-845 — the tier the module names drives the FACT and never installs the module, so no case in it can redden under a mutation of the predicate.
• 4 × CLOUD-989 — masked mutations. CLOUD-989's acceptance said no instance existed in the tree; it now carries a comment naming these four.

#MUTANT-OWNER changes no exit code — it cannot become an exemption in disguise.

Corrections to the row's premise, measured rather than assumed

1. ci-hygiene is CAUGHT, not survived. The row expected CLOUD-1161's two dead preset predicates to show as survivors; both were repaired before this branch and ci_hygiene.rs records it. Reporting this rather than manufacturing the expected survivor.
2. The graph-check repair is WITHDRAWN. Its receipt-carries-no-ids row is stale in both fields — the case was renamed, and the script targets a receipt_ids variable that has not existed since CLOUD-312 replaced the aggregate receipt with one file per subject. shell-rule-retired refuses the edit, correctly: two shapes only, and retiring graph-check is CLOUD-1061/CLOUD-1194's. The file is restored and the defect filed rather than carried.

What the new tiers caught in this branch's own work

• The sweep's summary line added could-not-look findings to uncaught ones, printing 124 of 0 declared mutation(s) … were not caught — a coverage verdict over a denominator of zero, and the exact conflation the Verdict variants are separate to prevent. Found by pointer_only.rs, the tier that drives the engine.
• main landed CLOUD-1269's landing-loop preset mid-flight; the widened census refused it immediately as uncovered. Declared, and the mutation confirmed caught rather than merely declared.
• The windows CI job found that the whole bats arm had never been run on Windows — cross-check type-checks that target but executes nothing. bats is an extensionless bash program Windows can neither symlink nor execute, so 18 cases are #[cfg(unix)]. The Rust-tier arm and the census are deliberately not gated: they are what CLOUD-1267 adds and they carry the Windows coverage on their own.

Disclosure: protected-path edits

policy_protected_paths (CLOUD-833) puts every registered module path into the protected set. The hatch was spent deliberately, with approval, for 37 files — 32 policy/*.rego and 5 vendored presets. Every edit is the same mechanical shape: withdraw #MUTANT-EXEMPT, add #MUTANT-SUITE naming the compiled tier the exemption already cited, add #MUTANT rows. No predicate logic was changed in any of them.

Two commits also carry Admits: articulation blocks, issued through override request/spend after main landed feat(commit): carry the articulation in the commit message. One is worth reading rather than skimming: for .serena/memories/core.md the block does not claim the owning surface failed. The edit was made through Serena's edit_memory. What that surface cannot express is the commit — edit_memory writes a memory and produces no commit — and the commit's diff is what the clause judges. The rejected route is recorded as R-RESTORE-IT, not R-USE-THE-OWNING-SURFACE.

That names a gap in the new clause: a memory edit made correctly through the sanctioned tool still trips admits, and V-PROTECTED-MUTATION's declared precondition is worded for direct writes. Worth a row against the admission campaign.

One unintended bypass, disclosed rather than filed silently. An early edit to policy/shell-retirement.rego went through a python3 heredoc before I knew the path was protected, so the gate never saw it. It names a real hole: protected_readers deliberately omits an interpreter, but a path inside a heredoc is not an operand. That hole is now CLOUD-1304, refined, and pinned as an asserted-allowed case in crates/batten/tests/it/mediated_verbs.rs by PR #814.

Landing status — CORRECTED AFTER THE FACT

This section described a block that no longer held when this PR merged, and it is corrected rather than left standing. It read that verify was green but landing was blocked by a cross-branch collision with the crates/batten/tests/it/ restructure, that the restructure "has not landed", and that main "still carries 151 flat test files" — a snapshot of one lap, written as a state.

What actually happened: the restructure landed while this branch was in the loop, this branch was adapted onto it in-session rather than waiting, and every #MUTANT-SUITE path here was re-pointed before merging — 26 modules and 6 presets, from crates/batten/tests/*.rs to crates/batten/tests/it/*.rs. That re-point is the work the paragraph below predicted as future, and it shipped in this PR. Without it all 32 declarations would have resolved to paths that no longer exist and reported no-suite, which is the same read-as-coverage failure this PR exists to remove, in its own diff.

mutate census is what catches that class rather than passing over it, and that is why the declared mapping is a mapping rather than a convention. It is also what caught the re-point being needed.

Merged at 5a9924b6.

What is not in this PR

• Building the tool-verdict producer — CLOUD-1265.
• Fixing ci-hygiene's preset/[[pattern]] gap — CLOUD-934.
• Retiring graph-check — CLOUD-1061 / CLOUD-1194.
• The [[mint]] fix dispatched as item 4. CLOUD-1266 is now a duplicate of CLOUD-1147, so it closes a different key and belongs in its own PR. It landed as PR fix(hook): recover an intercepted read, and repair three mechanisms that enforced nothing (CLOUD-1147) #814.

[linear-code]

CLOUD-1267 The Rego layer has ZERO mutation coverage and 32 of 32 modules are exempted from saying so — `mutant.sh:158` hardcodes `tests/$gate.bats`, and the only landable fix is retiring the runner it lives in

Why

mutant is CLOUD-418's mechanism: every declared gate must have a mutation its own suite is
proven to catch. It is the only thing in the tree that distinguishes a gate that decides from
a gate that merely parses.

It cannot reach a single policy module, and it never could. mise-tasks/mutant.sh:156-158:

src="mise-tasks/$gate.sh"
[[ -f "$src" ]] || src="policy/$gate.rego"   # the SOURCE has a Rego fallback
suite="tests/$gate.bats"                      # the SUITE has none

The source resolves a Rego module. The suite line is unconditional. So a mutation can be
applied to a .rego module and there is no suite that could turn red — the runner
reports no-suite and moves on.

Measured at origin/main:

policy modules	32
carrying #MUTANT-EXEMPT	32
whose exemption cites this exact hole	29
with a tests/<gate>.bats	0
compiled-binary tiers that exist and are unreachable	141

The exemption is not a hatch being used sparingly. It is 100% spent. Every module the
retirement campaign lands takes one, and each says the same sentence: "mutant resolves a*
gate's suite as tests/$gate.bats, and V-SHELL-RULE-ADDED refuses adding one, so there is
*no named case a mutation could turn red."

The campaign's destination is its blind spot, and it gets worse per migration

CLOUD-843 is moving ~130 governed programs from bash onto Rego. Every one of them leaves
mutation coverage and arrives somewhere it cannot be mutated. CLOUD-1111 measured the
shrinkage as it happened — 228 declared mutations, then 225 after one migration, "the count*
**fell because the retirement removed the shell gate's own row"*. The enforced set shrinks by
one per migration, by construction, and nothing reports the trend.

So the campaign's own success is what is dismantling the anti-vacuity gate, and CLOUD-418's
premise — "a test that cannot discriminate ships as coverage" — now holds for the entire
destination layer.

Why nobody has fixed it: the fix is an edit to a governed program

CLOUD-1111 enumerated the three resolutions and rejected two for the same reason:

"teach mutant to resolve a Rust-tier suite, give $MUTANT_GATES a spelling for that tier,
or accept the exemption per migration… §2 above picks the third, and the reason is the same
*rule one level along: the first two both mean editing mise-tasks/mutant.sh, which is a
*governed program, so they are not available to anyone."

That is correct and it is the trap. V-SHELL-RULE-EDITED declares one route, R-PORT-AND-RETIRE,
no override, no bypass_env. The coverage mechanism cannot be repaired, only retired.
CLOUD-1111 took the third option and is Done — so the deferral is closed while the
condition persists and compounds. That is CLOUD-1253's class on the mechanism that is supposed
to catch this class.

The unit, and it is small and clean

path	lines	#MUTANT	suite s
mise-tasks/mutant.sh	331	2	tests/mutant.bats 14.8
mise-tasks/mutant-census.sh	141	1	tests/mutant-census.bats 1.3
			16.1

Both invokers are ungoverned, so nothing needs repointing: hk.pkl:269-271 runs
mutant-census, and .github/workflows/mutant.yml:105,107 runs both. No mise-tasks/ sibling
calls either — every hit is a #MUTANT row comment in another program, not an invocation.

The seconds are not the point and should not be quoted as the win. The point is that**
retiring these two is the only landable route to a coverage mechanism that can see the layer
**the campaign is migrating onto.

The successor

A spawning-side verb. mutant stages a tracked tree per mutation and re-runs a suite, so
it cannot be check (§5: read, structurally incapable of spawning). CLOUD-1171 settled that
this is legitimate and landed: "batten perf ships and runs hyperfine", effect write.

The one behavioural change: a gate's suite is resolved from a DECLARED mapping, not from a**
**hardcoded path, so a Rego module can name crates/batten/tests/<x>.rs as the tier a mutation
must turn red. Everything else is conserved.

What this bundle proves by going RED

This is the anti-vacuity half, and it is what makes the row worth doing rather than tidy.
Two dead gates are already in the tree and mutation coverage is what finds them:

• policy/validator-verdict-clean.rego — nothing writes a tool-verdict record, so it
  resolves null and refuses nothing on any real checkout (CLOUD-1265). Its own
  test_could_not_look_does_not_fault passes over the dead version.
• CLOUD-1161's ci-hygiene preset — two predicates dead, because a preset cannot read a
  [[pattern]] row a consumer never wrote. .claude/rules/policy-modules.md records it:
  "CLOUD-934 *predicted the failure in those words before it happened; *CLOUD-1161's
  ci-hygiene preset is it happening, two predicates dead."

A mutation over a dead predicate survives, which is the only way either is detectable
mechanically. If the sweep comes back green over both, the successor is as blind as the**
**predecessor and the bundle has not landed.

---

Refinement — Ready (retire the coverage runner so coverage can reach the layer it must judge)

Refinement gate: Definition of Ready & Done. This body carries only specializations.

• **Authority boundary (§1). **mise-tasks/mutant.sh, mise-tasks/mutant-census.sh,
  tests/mutant.bats, tests/mutant-census.bats — deleted, four paths, four conserves
  arms, each naming a policy surface AND a crates/batten/tests/*.rs, with kind:verb on the
  engine-source arm. hk.pkl and .github/workflows/mutant.yml are ungoverned and repoint by
  task name. mise.toml's $MUTANT_GATES and the 32 policy/*.rego modules are outside
  shell-retirement's perimeter.
• Computable predicate (§2). For every gate in the enforced set, each declared mutation is
  applied to its source and the gate's declared suite is shown to turn red. A declared
  mutation whose named case does not exist is reported, never silently counted — conserved
  from the predecessor.
• The discriminating pair (§2), and it is the whole row. A mutation over a live
  predicate is caught; a mutation over a dead one survives and is reported. Without the
  second, the successor is a runner that reports green over a layer it cannot see — which is
  the predecessor.
• Could-not-look is not a pass (§2). A gate whose declared suite cannot be resolved or run
  is exit 3 and is distinguishable from "every mutation caught". The predecessor's no-suite
  is that signal and it must survive the port; collapsing it into a pass is the defect.
• Deliberately not in scope (§2). Retiring graph-check (928 lines, 13 #MUTANT, 21.6s) —
  CLOUD-1061 needs it edited and it is a board gate under CLOUD-1194's family; folding it in
  manufactures glue this partition exists to avoid. Building the tool-verdict producer —
  CLOUD-1265. Fixing ci-hygiene's dead predicates — CLOUD-1161/CLOUD-934.
  This row DETECTS those two; it does not repair either, and both must be left red with a
  filed owner rather than quietly patched to get the sweep green.
• Effect (§3). Spawning side — it stages a tree and runs suites, as perf does. Not
  check.
• Output and exit (§5). Pointer-only: the gate name, the mutation id, and caught/survived.
  Never a line of a mutated source. Exit follows the 0/1/2/3 table.
• **Commit / bump (§6). **feat for the verb, refactor(ci)! for the retirement — patch until
  0.1.0, and the ! is not breaking for the consumer: hk.pkl and mutant.yml invoke by task
  name and neither changes. (Corrected 2026-08-31: this read "no bump", which ready-lint
  refuses as bump-disagrees-with-type — feat implies patch below 0.1.0 — so the row could
  not be claimed.)
• Test obligation (§7). Over the compiled binary in crates/batten/tests/; **no **.bats
  file is added or edited. Shown able to fail per CLOUD-418, plus the anti-vacuity mirror: a
  fully-covered fixture set passes.
• Blockers (§8). None. It blocks the honest completion of CLOUD-843's campaign, since
  every further migration widens the blind spot. relatedTo CLOUD-931 (which found the hole at
  two modules and is Done at 32), CLOUD-1111 (which named the two unavailable fixes and took
  the third), CLOUD-845 and CLOUD-418 (the classes this restores detection for), CLOUD-480,
  CLOUD-1061, CLOUD-1265 and CLOUD-1161 (the two live dead gates this must find).

Acceptance

• mutant.sh, mutant-census.sh and both suites are gone, with one ledger arm each.
• A policy module's mutation resolves against its compiled-binary tier and is shown to turn it
  red.
• **The 29 **#MUTANT-EXEMPT **rows whose sole stated reason is the tests/$gate.bats hole are
  **withdrawn, and those modules enter the enforced set with declared mutations. An exemption
  that survives names a different reason.
• **The sweep is RED on **validator-verdict-clean and on ci-hygiene's two dead predicates,
  each pointing at its owning row. A green sweep over those means the port is blind and has not
  landed.
• hk.pkl and mutant.yml call the successor by task name, unedited in substance.
• The enforced-set count is reported and is larger than before, reversing the per-migration
  shrinkage CLOUD-1111 measured.

Found by asking what else fails the way CLOUD-1266 does — a mechanism whose verdict cannot
correspond to the property it claims to decide, because it cannot reach its subject.

Review in Linear

[coderabbitai]

Warning

Review limit reached

Next included review available in 44 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Free

Run ID: 509012e8-f472-4eae-ac7a-9a3bc3524922

📥 Commits

Reviewing files that changed from the base of the PR and between aa29b10 and 5a9924b.

⛔ Files ignored due to path filters (1)

• crates/batten/tests/it/snapshots/it__snapshots__golden_json_schema.snap is excluded by !**/*.snap

📒 Files selected for processing (40)

• .claude/rules/policy-modules.md
• bench/suites/RESULTS.md
• crates/batten/src/lib.rs
• crates/batten/src/mutate.rs
• crates/batten/src/policy/presets/ci-hygiene/spend-is-authorised.rego
• crates/batten/src/policy/presets/commit-hygiene/no-empty-commit.rego
• crates/batten/src/policy/presets/landing-loop/graded-head-is-not-regraded.rego
• crates/batten/src/policy/presets/pinned-toolchain/pinned-program-via-the-pin.rego
• crates/batten/src/policy/presets/shell-hygiene/shebang-names-its-language.rego
• crates/batten/src/policy/presets/trunk-based/no-force-push.rego
• crates/batten/tests/it/main.rs
• crates/batten/tests/it/mutate.rs
• crates/batten/tests/it/pointer_only.rs
• mise.toml
• policy/bats-invocation.rego
• policy/ci-parity.rego
• policy/ci-suite-lane.rego
• policy/claim-before-code.rego
• policy/denials-outlive-the-turn.rego
• policy/filed-here.rego
• policy/forge-verdict-required.rego
• policy/harness-grant.rego
• policy/harness-wiring.rego
• policy/hk-fix-selection.rego
• policy/lock-entry-complete.rego
• policy/mise-pin-agreement.rego
• policy/privileged-lane.rego
• policy/prose-only.rego
• policy/release-tag-shape.rego
• policy/remedy-authorship.rego
• policy/review-answered.rego
• policy/run-shape.rego
• policy/shell-retirement.rego
• policy/shell-write-advisory.rego
• policy/stop-posture.rego
• policy/suite-subject-retirable.rego
• policy/task-substitution.rego
• policy/validator-verdict-clean.rego
• policy/verdict-routes-resolve.rego
• policy/weakens-declared.rego

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Free

Run ID: faefdf0f-ab9e-41d1-8166-2aea7ef0a328

📥 Commits

Reviewing files that changed from the base of the PR and between 26ae231 and aa29b10.

⛔ Files ignored due to path filters (1)

• crates/batten/tests/snapshots/snapshots__golden_json_schema.snap is excluded by !**/*.snap

📒 Files selected for processing (61)

• .claude/rules/policy-modules.md
• .github/workflows/mutant.yml
• .serena/memories/core.md
• bench/suites/RESULTS.md
• completions/batten.bash
• completions/batten.fish
• completions/batten.zsh
• crates/batten/src/cli.rs
• crates/batten/src/lib.rs
• crates/batten/src/mutate.rs
• crates/batten/src/policy/presets/ci-hygiene/spend-is-authorised.rego
• crates/batten/src/policy/presets/commit-hygiene/no-empty-commit.rego
• crates/batten/src/policy/presets/landing-loop/graded-head-is-not-regraded.rego
• crates/batten/src/policy/presets/pinned-toolchain/pinned-program-via-the-pin.rego
• crates/batten/src/policy/presets/shell-hygiene/shebang-names-its-language.rego
• crates/batten/src/policy/presets/trunk-based/no-force-push.rego
• crates/batten/src/spec.rs
• crates/batten/src/surface.rs
• crates/batten/tests/mutate.rs
• crates/batten/tests/pointer_only.rs
• man/batten-mutate-census.1
• man/batten-mutate-sweep.1
• man/batten-mutate.1
• man/batten.1
• mise-tasks/mutant-census.sh
• mise-tasks/mutant.sh
• mise.toml
• policy/ancestry-decides-nothing.rego
• policy/bats-invocation.rego
• policy/ci-parity.rego
• policy/ci-suite-lane.rego
• policy/claim-before-code.rego
• policy/command-task-defined.rego
• policy/denials-outlive-the-turn.rego
• policy/filed-here.rego
• policy/forge-verdict-required.rego
• policy/harness-grant.rego
• policy/harness-wiring.rego
• policy/hk-fix-selection.rego
• policy/lock-entry-complete.rego
• policy/mise-pin-agreement.rego
• policy/module-layering.rego
• policy/opa-compliance.rego
• policy/privileged-lane.rego
• policy/prose-only.rego
• policy/release-tag-shape.rego
• policy/remedy-authorship.rego
• policy/review-answered.rego
• policy/run-shape.rego
• policy/shell-retirement.rego
• policy/shell-write-advisory.rego
• policy/spawn-adapters.rego
• policy/stop-posture.rego
• policy/suite-subject-retirable.rego
• policy/task-substitution.rego
• policy/validator-verdict-clean.rego
• policy/verdict-routes-resolve.rego
• policy/weakens-declared.rego
• policy/workspace-dep-referenced.rego
• tests/mutant-census.bats
• tests/mutant.bats

💤 Files with no reviewable changes (5)

• mise-tasks/mutant.sh
• mise-tasks/mutant-census.sh
• tests/mutant.bats
• bench/suites/RESULTS.md
• tests/mutant-census.bats

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

Added the compiled batten mutate command with sweep and census subcommands. The implementation resolves declared Bats and Cargo suites, stages repository files, runs mutations, classifies findings, and audits gate coverage. Replaced mutation shell tasks with compiled Mise tasks. Added command specifications, completions, manual pages, integration tests, and pointer-only checks. Updated policy and preset metadata with mutation cases, suite paths, owners, exemptions, and module-placement rules.

Merge Risk: ⚪ Minimal · up to aa29b

The PR moves mutation coverage into batten mutate and updates its policy and CI integration without any identified merge-blocking risk; it is merge-ready after normal checks and review.

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Essentials by visiting https://app.coderabbit.ai/settings/billing.

_{Comment @coderabbitai help to get the list of available commands.}

[sonarqubecloud]

❌ The last analysis has failed.

See analysis details on SonarQube Cloud

[wenzowski]

/fast-forward