The refusal surface: one line, reachable, and four false refusals fixed

[wenzowski]

Every mediated Bash call in this repository passes batten hook, and every refusal it emits is paid for in the agent's context window on the turn it fires and on every turn afterwards. Measured live on 2026-09-01, a no-tool-substitution refusal was 88 words / ~115 tokens, and ~300 of them fire in a long session — ~34,500 tokens against a ~175k window.

Thirteen rows all named one file domain: the mediated-call boundary (crates/batten/src/hook.rs), the refusal it constructs (refusal.rs, verdict.rs, redirect.rs, rules.rs, receipt.rs), and the registry that declares what it may say (batten.toml's [[verdict]], [[rule]], protected* tables). Each one's registry or gate is what the next extends, which is why this is one PR rather than thirteen: N PRs would be N CI matrices for one unit of build work.

The outcome: a mediated refusal is now one line — a declared three-word class and its pointers — reachable from every composer, with the reasoning dereferenced through batten policy explain, and with four false-refusal defects in the same boundary fixed so the cheaper line is not also a wrong one.

What landed

Closes CLOUD-1284 — a three-word verdict grammar, gated. VERDICT_PREFIX and ROUTE_PREFIX are gone; arity is fixed at 3 (never ≤N, which is what lets <class> <pointer…> parse on one line with no delimiter), membership is per position, and single-tokenness is asserted against o200k_base through a dev-dependency that ships nothing in the binary.

Closes CLOUD-1189 — a remedy resolves to a declared command or rule. redirect strings were free-form prose and nothing resolved the command they name against anything, so any verb that moves turned every remedy naming it into a lie, silently. redirect::validate_remedies resolves the longest prefix against SURFACE and every remaining word against the declared [[rule]] ids, wired into config::parse_ungated beside its four sibling validators rather than left with no call site — the defect verbs::validate had for its whole life (CLOUD-242). An invocation is a code span: the first predicate read run `batten capture show <handle>` instead as a four-word invocation ending in instead and reported instead as an undeclared rule id, which is a finding invented out of English. See the caveats below.

Closes CLOUD-1088 — R-DECLARE-IT-STAYS-BASH clears the verdict it is offered for: a # stays-bash: line in an ADDED file admits it, and a route naming another rule's mechanism is refused at load when that rule's glob cannot select the paths the verdict is raised over.

Closes CLOUD-1285 — every mediated deny carries a declared class. Eight composers moved off Refusal::new; the prose was hardcoded format! in hook.rs rather than config, so this is ~10 new Native variants under the wildcard-free exhaustiveness match, not 32 config-row edits. policy_refusal was the half-converted one and now records the token it already rendered.

Closes CLOUD-1286 — the hot path emits token and pointer and stops. render_line's unconditional gloss, Refusal::render's wrapper and the duplicated bypass sentence are all gone. Taking the Fix: clause off the line broke three reachability paths, so batten policy explain grew a rule-id resolver, a fact-command printer and a protected-mutation → [[redirect]] resolver before the elision was honest rather than lossy. The CLOUD-122 tension is settled in writing in README.md: the class name IS the pointer, one hop.

Closes CLOUD-1287 — verb/operand attribution no longer stops at a newline. Narrow on purpose: segment identity is untouched, so no landed pipeline verdict moves. .claude/rules/policy-modules.md's "it under-denies, which is the sanctioned direction" sentence is corrected against the measurement. A backslash continuation splitting into two lines was a real bypass this change introduced and CodeRabbit caught; joined_lines counts trailing backslashes, with three cases over it.

Closes CLOUD-1109 — paths resolve against the caller's cwd, and the refusal stops claiming tracked-ness. Envelope::cwd was already decoded and simply unconsumed, so one file named relatively and absolutely from one directory now yields one verdict, with no stat and no spawn. The gate decides containment; the text now says containment.

Closes CLOUD-609 — a bare directory destination is inside the protected set. cp /tmp/x .serena/memories/ was allowed because dir/ is not a member of dir/**. PathSet gained a NAMED containment method; contains is untouched and keeps meaning membership, because scope and unlanded are answers about files and widening it would change two callers that never asked this question.

Closes CLOUD-1258 — a generic read of a memory names read_memory. Pointer-only: the path and the redirect, never a byte. Absent Serena it allows, because a redirect naming a tool the session does not carry is CLOUD-998's defect one layer over.

Closes CLOUD-1282 — the mediated column refusal is derived from the fact model rather than from six hand-written blocks. Fact::tree_key is the predicate, not Surface::Check equality, and the column→Fact map is a census with a verdict per Rule field whose test reads the field list off the struct's own source. Census result, which the suite alone could not establish: no committed row in batten.toml or batten.example.toml is refused; exactly one test fixture was, correctly.

Closes CLOUD-1091 — a branch behind its own receipt is not a restart. branch_validity's comparison was symmetric and the situation is not: it fired just as readily when the receipt's base was NEWER than HEAD, where no number of fresh searches can clear it. Void only where HEAD carries commits the recorded base does not. CLOUD-516's restart is still void, which is what keeps a change that always returned Valid from passing.

Closes CLOUD-896 — one budget for the advisory channel, not per producer. Three producers shared additionalContext with no rate budget; [advisory] max_tokens supersedes the per-producer key. Admitted in AdvisoryTier order, remainder dropped AND COUNTED, because a truncated report that reads as complete is the false green in advisory form.

Closes CLOUD-417 — the row this whole PR is the concrete half of. [hook_output] bounds what a session's hooks cost it, and max_repeats makes "silence on success is the default" and "a repeat is a pointer to the first, not a copy" decidable rather than prose. Event::HookOutput carries a count and a digest; the emitted bytes are hashed and dropped at the parse. batten policy hooks prints one line and nothing around it, and the 20% figure ships as mise run hook-cost rather than as a number in a body.

Closes CLOUD-1308 — a verdict rename is not a hatch newly added. VerdictOverrideAdded was keyed on the class id, so a class renamed with its override untouched left the old id absent and the new one present, and the new one was reported as a hatch newly added; the removal side is deliberately unreported, so nothing cancelled it out. This branch is what made it reachable — it renames every class in the registry, and two of 105 carry an override. The key is now the override's precondition rather than the id: a hatch is identified by the condition it states, so a class whose precondition already existed is that hatch relocated. The comparison still refuses to judge whether one precondition is looser than another; it compares them for identity, not strength. config lint against origin/main now reports 0 smells where it reported 2 admitted.

Caveats a reviewer should not have to find

CLOUD-1189's gate reports nothing on this tree, and that is its own premise. Measured on the committed table: 22 remedy strings, 0 naming a batten invocation; 44 command routes, 0 batten-invoking. The row's acceptance is that the gate survives a surface rename by construction, so the constructed cases are what show it can fail and the_committed_table_loads is the anti-vacuity mirror. Its §5 asks for a [[verdict]] row and it does not ship one: a load-time refusal is a UsageError rather than a raised class, and a declared row nothing raises fails the load, so shipping one would break every consumer's config. Recorded on the row.

Its code-span bound under-denies, deliberately. A command named in bare prose is not judged. That is asserted outright in an_invocation_is_a_code_span_and_bare_prose_is_not_one rather than left to a reader of the predicate.

Two Weakens: trailers on cc49e0ea are withdrawn and left in place. They admitted the two verdict-override-added lines CLOUD-1308 has now made not fire. A trailer naming a smell nothing raises admits nothing, and rebasing 68 commits to remove two inert lines is not worth the churn; the durable correction is on CLOUD-1284's Ready block, where the matching groomed clauses were withdrawn and the claim receipt re-minted without them.

One [[pattern]] id was renamed by accident. The CLOUD-1284 sweep is keyed on the id string, so it rewrote policy-rule-const — whose new spelling collided with a real route id — and config-lint read the row as removed. Restored, with policy/rules-drift.rego's two reads and its fixture registry repointed. No pattern row on this branch differs from main's now.

Shape notes

The branch is keyless on purpose. Branch-name precedence beats the PR body, so a branch named for one ticket would move that ticket and strand the others; all fourteen keys close from this body instead.

WIP will read high on graph-check. That is a reporting artifact rather than a refusal (CLOUD-502, Canceled).

mise run semver reported four API-break lints across the branch — constructible_struct_adds_field, enum_no_repr_variant_discriminant_changed, function_parameter_count_changed, pub_module_level_const_missing — each declared with a BREAKING CHANGE: footer naming its cause.

Four protected paths were written under issued admissions, each with its Admits: block in the commit that made the write: batten.toml (four new tables no non-protected path can carry, and later the one-token pattern-id repair), policy/module-layering.rego (two module placements the absence-is-an-error clause demands), and .serena/memories/core.md (the matching module-map rows).

Two corrections to this body's own earlier versions

CLOUD-1189 was recorded as skipped, on a false premise. The claim was that its Ready block fails ready-lint so claim-check will not pull it. Measured, batten claim check --issue CLOUD-1189 exits 0 and mints a receipt reading ready-lint pass. The skip protocol — write on the issue, move it to Backlog — had not been followed either. The row is claimed, In Progress, and built above.

CLOUD-1308 was filed rather than fixed, and filed-over-own-diff refused that. Correctly: its §1 named crates/batten/src/trust.rs, which this diff has open, and the gate's whole design is that a defect found in your own diff is one you are already holding the file for. Its first declared route is "close the row you filed and fix it in this diff", and the fix turned out to be ~40 lines rather than the ~105 tombstone rows the filed row had priced it at.

[linear-code]

CLOUD-1284 Verdict tokens are free text in SCREAMING-KEBAB, so a class name costs ~9 tokens and explains nothing — declare a three-word vocabulary and gate it

Why

115 verdict classes are spelled V-SCREAMING-KEBAB, mean 22.9 characters, 4.1 hyphen-segments, longest 33 (V-PRIVILEGED-LANE-UNTESTED-ORIGIN). That is close to the worst case for BPE: merges are trained on natural text, where uppercase runs and hyphen-joined compounds are rare. **Measured with **tiktoken o200k_base over all 115 classes:

spelling	total tokens	mean	max
V-SCREAMING-KEBAB, as-is	1,134	9.9	15
lowercase kebab, V- dropped	596	5.2	9
curated three-word (this row's target)	345	3.0	3

So the current spelling costs 6.9 tokens per refusal over the target — about 2,058 tokens per session at ~300 refusals. Worked examples: V-PROTECTED-MUTATION is 7, V-SHELL-EDIT-BEFORE-RETIREMENT is 12, V-PRIVILEGED-LANE-UNTESTED-ORIGIN is 15.

The second cost is the one that matters more. The words are free text with no declared meaning, which is why every class needs its own gloss to explain its own name: 6,640 words of class prose across 90 [[verdict]] rows, mean 74, with zero reuse. A new class buys a new essay.

Measured at 79b8bfd:

classes total	115 — 90 consumer [[verdict]], 7 Native, 18 VENDORED
mean token length	22.9 chars, 4.1 segments
class prose	6,640 words, mean 74 per row

Opaque numeric codes were considered and lose. E0001 is about 3 tokens — no cheaper than three words — while making the gloss mandatory, since nothing can be read without it. pylint-errors is a several-hundred-page community manual that exists precisely because E0001 says nothing. A token that needs no lookup in the common case is the cheap one.

Refinement — Ready (a three-word positional vocabulary, gated at load)

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

• Source of truth (§1). The 90 [[verdict]] rows in batten.toml; crates/batten/src/verdict.rs's Native (7 variants) and VENDORED (18 entries). The vocabulary and the grammar become new declared tables in batten.toml.
• Precedent (§1). Issue CLOUD-1184 is this exact move one namespace over, and it landed: *"declare an imperative *VERB OBJECT registry that makes the effect follow the verb." SURFACE is a const table of CommandDecl { path: "checks green", … } — space-separated lowercase words in a declared grammar — held by surface.rs's is_noun and crates/batten/tests/primitives.rs's verbs_are_partitioned_by_the_one_effect_vocabulary. Copy that shape rather than inventing one; this is consistency with a landed decision.
• Computable predicate (§2). A verdict token is exactly three space-separated words on a positional grammar, each drawn from its own declared list:

<subject> <verb> <condition>

task spelling weakened        Cargo.toml:12
shell edit refused            mise-tasks/land.sh:845

Both halves of that spelling are load-bearing, and the measurement separates them. Space beats hyphen consistently but modestly — task spelling weakened is 3 tokens against task-spelling-weakened's 6, force push trunk 3 against force-push-trunk's 5. Word choice dominates. With a leading space, edited, missing, shell, commit, task, stale, absent and weakened are one token each, while unretired is 3 and unobtainable is 3. A three-word name is therefore 3 tokens only if the vocabulary is curated for it: task spelling weakened is 3, but shell edit unretired is 5 — and that second example, which an earlier draft of this row used as its illustration, would fail arm 4 of this row's own gate. That is exactly what arm 4 is for.

Three 64-word lists give 262,144 ordered triples for 115 classes — log2(115) = 6.8 bits needed against 18 available. The headroom is the point: not entropy, but room enough that the vocabulary never forces an awkward name.

Deliberately not in scope: the flat namespace across 90 consumer / 7 native / 18 preset classes, which is CLOUD-1181's. Changing the spelling does not change the namespace, and a later qualifier composes with either. No predicate changes meaning in this row.

• Mechanism (§3). The gloss stops being a per-class essay and becomes a dictionary: roughly 192 words at ~8 words each ≈ 1,536, reused across 345 word-slots, so the marginal class costs zero new gloss. Position carries the rest — knowing slot 2 is always the verb is what lets task spelling weakened be read with no lookup. That is what makes dropping the gloss from the hot path safe rather than merely cheap.
• The gate (§3, non-negotiable 2). Six arms, every one deciding membership or arity and never quality, so non-negotiable 3 holds — the gate decides conformance and a human still decides whether a name is a good name:
  1. Arity — exactly 3. Fixed, not ≤: fixed arity is what makes <class> <pointer…> parseable on one line with no delimiter. This is the constraint an implementer will want to relax and must not.
  2. Membership — each word is in the declared list for its position.
  3. Uniqueness of the triple. verdict::validate already refuses duplicate ids; extend it.
  4. Single-tokenness — each vocabulary word is one token under a pinned tokenizer. This is the arm that makes the convention enforceable rather than aspirational, and the one new dependency.
  5. No orphan vocabulary — a word no class uses fails the load, mirroring the landed rule that a [[verdict]] row nothing raises fails the load.
  6. Every vocabulary word carries a gloss.
• Output & exit contract (§5). Unchanged. A load-time refusal is the existing shape; this adds arms to it and no new exit code.
• **Commit / bump (§6): **fix(verdict) — patch until 0.1.0 regardless of type. Typed fix rather than refactor because the row adds a gate that did not exist and removes a measured cost, so it is not behaviour-neutral; refactor would also imply no bump, which disagrees with the patch this declares.
• Test obligation (§7). Each gate arm fails a constructed non-conforming registry and passes the real one, over the compiled binary in crates/batten/tests/, never with input as. Anti-vacuity is the load-bearing case: the converted registry must PASS — an arm that refuses everything gets switched off. Firing rate is known exactly rather than estimated: 115 of 115 classes fail before the converting commit and 0 of 115 after, because one commit converts them. There is no steady-state rate; after landing, the only way to fail is to add a non-conforming class, which is the intended deny. Severity is deny on that basis.
• Blockers (§8): none.

Honest costs, stated up front

• Most of the token saving is the lowercasing, not the vocabulary. Measured: as-is 9.9 → lowercase kebab 5.2 → curated three-word 3.0. So dropping V- and the uppercase buys 1,410 tokens per session and the curated vocabulary buys a further 660. Both are real, but the vocabulary's larger payoff is that it makes dropping the gloss safe and gives the naming convention a gate it has never had. If the vocabulary work stalls, the lowercase rename is still worth landing alone.
• The tokenizer pin is model-specific. These figures are tiktoken o200k_base. Declare the pin the way bench/tokens/method.toml declares its byte divisor — printed and sourced — and record that the ratio argument survives a different tokenizer even where absolute counts move. Common English words are single-merge in every modern BPE vocabulary; that part is robust, the exact integer is not.
• **Some classes will fight three words. **V-PRIVILEGED-LANE-UNTESTED-ORIGIN carries five concepts and costs 15 tokens today. Either allow arity 4 for a declared minority, or split the class — decide it here, and do not let it drift to ≤5, which dissolves the grammar back into free text.
• Vocabulary design is the real work. The renames are mechanical and cannot ship half-done: verdict::validate refuses a malformed token, a row nothing raises fails the load, and a token no row declares fails the load, so a missed occurrence fails at load naming itself. Budget this row for the vocabulary, not the edit.

Acceptance

• 115 classes conform to the grammar; VERDICT_PREFIX and ROUTE_PREFIX are gone.
• The gate refuses a four-word class, an undeclared word, a duplicate triple, an orphan vocabulary word, and a multi-token word — each with its own case.
• No predicate changed meaning; the diff is spelling plus the gate.

CLOUD-1088 `V-SHELL-RULE-ADDED` names a route that clears a different rule, so the campaign's own door-tier suites have no landable spelling

Why

V-SHELL-RULE-ADDED declares two routes:

R-WRITE-A-POLICY-MODULE  document  .claude/rules/policy-modules.md
R-DECLARE-IT-STAYS-BASH  document  batten.toml

and its class text says: "bash-surface-not-growing admits it with a # stays-bash: declaration."

Measured 2026-08-28, on the real tree: prepending # stays-bash: CLOUD-312 door-tier suite over the compiled binary to tests/wiring-reclaim.bats and re-running batten check --rule shell-retirement leaves the finding byte-identically where it was. The second route does not clear the verdict it is attached to.

The reason is structural, not a typo. admits_with = "# stays-bash:" belongs to bash-surface-not-growing, whose glob is mise-tasks/** — it never reaches tests/**. And shell-retirement's own arm carries no admission clause at all:

violation contains {"rule": "shell-rule-retired", "verdict": "V-SHELL-RULE-ADDED", ...} if {
	some path in delta.added
	governed_at_head(path)
}

So for a tests/*.bats path the named remedy is unreachable twice over, and for a mise-tasks/** path it clears a different rule while leaving this one standing.

RE-DERIVED 2026-08-31 against origin/main 0683ce53 — the defect holds, two pointers moved, and a second admits_with row now exists

Re-read rather than inherited, because this row was written 2026-08-28 and every claim in it is a pointer into two files that have both grown since.

• **The verdict and its two routes are unchanged. **batten.toml:5335–5355 declares V-SHELL-RULE-ADDED with R-WRITE-A-POLICY-MODULE → .claude/rules/policy-modules.md and R-DECLARE-IT-STAYS-BASH → batten.toml, both kind = "document".
• **The arm still carries no admission clause. **policy/shell-retirement.rego:147–154 is the delta.added × governed_at_head conjunction and nothing else; governed_at_head at :134–136 admits an authored shell path OR any .bats.
• **The line pointer this body carried was stale. **admits_with = "# stays-bash:" is at batten.toml:3112, not :2557 — the number in the paragraph above has been dropped rather than re-pinned, since a line number in an issue body is CLOUD-1166's defect in miniature. The rule NAME is the durable pointer and is what the sentence now carries.
• There are now TWO admits_with = "# stays-bash:" **ratchets, and the second strengthens this row rather than answering it. **CLOUD-1137 landed a sibling at batten.toml:3225–3232 globbing .claude/**. So the token a route tells an author to write is now honoured by two rules, neither of which globs tests/** — the surface the refused suites live on. A reader who finds the second row must not read it as the route working now.

The reproduction in the paragraph above (a # stays-bash: line on tests/wiring-reclaim.bats leaving the finding byte-identical) has not been re-run this session; it is the 2026-08-28 measurement. What has been re-derived is the structural reason it must still fail, from the two files' current bytes.

This is CLOUD-1050's own class. That row replaced msg: String precisely because "a refusal could name no remedy, name a task that does not exist, offer an override with no precondition" and all of it passed a String. The registry gates well-formedness, token equality in both directions, and route TARGET resolution — policy/verdict-routes-resolve.rego asks whether mise run x names a task. What no gate asks is whether a route, followed exactly, clears the verdict that offered it. A document route resolves to a file that exists, and stops there.

The consequence, which is why this is not cosmetic

R-WRITE-A-POLICY-MODULE points at .claude/rules/policy-modules.md, and that document says, under "Two test tiers, and the second is not optional":

tests/<gate>.bats over the compiled binary is the tier that proves the ENGINE builds the input the predicate reads. A with input as case cannot do this … Both live instances of that class were found by adding the second tier, not by reading.

CLOUD-312's per-row differential obligation says the same for a handler destination: *"the fixture goes through *batten hook, and the reply is byte-compared."

So a door migration is required to add a tests/<gate>.bats, and V-SHELL-RULE-ADDED refuses adding one, with a route that does not clear it. Two landed policies mandate exactly what a third refuses. Measured on #714, which adds three such suites — tests/connector-allow-door.bats, tests/run-shape-guard-door.bats, tests/wiring-reclaim.bats — and is refused for all three.

The sibling arm has no route at all. V-SHELL-RULE-EDITED declares R-PORT-AND-RETIRE and no bypass_env, which #718's own body records as already having cost it a repair: "mise-tasks/claim-check.sh is an authored shell rule, so editing it is refused as V-SHELL-RULE-EDITED *with no override route and no *bypass_env", leaving CLOUD-1082's unrecordable groom unfixable. That is a second instance of the same shape and belongs to this row's evidence — but it is a scoping question rather than a route defect, so the fix below stays narrow.

Not in scope

Weakening the ratchet. shell-retirement is CLOUD-843's central mechanism and the campaign's corpus must shrink rather than stay level while the census reports movement; a route that admits editing a shell gate in place is the thing it exists to refuse. This row is about a route that does not do what it says, not about whether the refusal is right.

---

Refinement — Ready

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

• Source of truth (§1). The [[verdict]] registry in batten.toml stays the one place a class and its routes are declared. policy/shell-retirement.rego stays the one place the predicate lives. No second table of "which route clears which verdict".
• Computable predicate (§2). Two, and the second closes the class rather than the instance. (a) V-SHELL-RULE-ADDED's routes are reachable: either the arm honours the declaration its class text names, or the class text stops naming it. (b) A route is refused at load when following it cannot clear the verdict that offered it — the analogue of the registry's existing both-directions equality check, one level in. Where that is not statically decidable, the honest form is narrower: a route whose mechanism is another rule's admits_with must name that rule, and the load refuses a row naming a rule whose glob cannot select the paths this verdict is raised over.
• **Effect (§3). **read. Both are load-time checks over committed configuration; no fact class moves and no verb is added.
• **Generated artifacts (§4). **schema/batten.schema.json if a [[verdict]] route row gains a key; derived-check and schema-check gate it either way.
• Output & exit (§5). Pointer-only. A load refusal names the verdict token and the route id, never the class prose, and the 0/1/2/3 table is unchanged — a refused load is the existing "the module fails to load and says why" path.
• **Commit / bump (§6). **fix(policy) — **patch until **0.1.0.
• Test obligation (§7). Shown able to fail per CLOUD-418, and the reproduction above is the first case: a fixture adding a tests/*.bats with a # stays-bash: line still raises V-SHELL-RULE-ADDED today and must not after (a); a [[verdict]] row whose route names a rule that cannot select the verdict's own paths fails the load, and the same row with a reaching rule does not, for (b). Second tier over the compiled binary per .claude/rules/policy-modules.md — noting that adding it is itself blocked until (a) lands, which is this row's own subject biting.
• Blockers (§8). None. relatedTo CLOUD-1050 (whose registry this extends), CLOUD-1080 (which landed the arms), CLOUD-843 (the campaign the ratchet serves), CLOUD-312 (whose door migrations the defect blocks), CLOUD-1058 (the sibling ratchet whose admits_with this route borrows).

Acceptance

• Following R-DECLARE-IT-STAYS-BASH exactly clears V-SHELL-RULE-ADDED, or that route is not offered.
• A [[verdict]] route that cannot clear its own verdict is refused at load rather than shipped.
• A door migration can add its second-tier tests/<gate>.bats without a waiver and without an override.

Found while rebasing #714 onto main after #718 merged: the branch was refused on twelve shell-rule-retired findings, and the three added ones are the first place a declared route was followed and observed not to work.

---

A reading this row invites, and does not own — recorded 2026-08-28 so it is not re-derived.

Because this row is about V-SHELL-RULE-ADDED refusing an added tests/<gate>.bats, it is easy to read it as owning a broader claim: that shell-retirement and .claude/rules/policy-modules.md are in direct conflict over whether a bats suite may exist at all. They are not. policy-modules.md:229 binds a gate that is in $MUTANT_GATES — a gate that remains registered — and a retirement removes the gate from that list along with its suite. So a whole-file retirement never owes the suite the ratchet would refuse, and the two authorities never meet.

That misreading was taken during a planning session on this date and cost a verification pass to undo. The unscoped sentence is what invites it; CLOUD-1132 carries the one-clause scoping fix to :229, and CLOUD-1132's own body records the measurement.

What this row still owns is unchanged and narrower: R-DECLARE-IT-STAYS-BASH resolves to bash-surface-not-growing's admits_with, whose glob is mise-tasks/** and therefore never reaches tests/** — a declared route that cannot clear the verdict offering it.

CLOUD-1285 8 of 10 refusal composers build untokened refusals, so CLOUD-1053's `render_line` and `policy explain` are unreachable from every path that actually fires

Why

CLOUD-1053 shipped the whole hot-path mechanism — verdict::render_line, GLOSS_MAX, and batten policy explain — and is Done. Almost nothing reaches it. This is CLOUD-1253's class (a landed mechanism nothing calls) on the mechanism built to fix exactly this complaint.

Where the prose actually lives, which is not where it looks. The cause half of a mediated refusal is a hardcoded format! string in crates/batten/src/hook.rs, not consumer config. substitution_refusal composes an 88-word cause inline and calls Refusal::new. A [[rule]] row's reason key is the Fix half, and is already declared config. Any plan that reads "the inline prose lives in the rows" has this backwards, and will size the work wrongly.

Measured at 79b8bfd: 21 Refusal::new sites against 10 Refusal::declared across crates/batten/src. Of the ten composers in hook.rs, eight use Refusal::new:

composer	line	constructor
receipt_refusal	4467	Refusal::new
substitution_refusal	4848	Refusal::new
pipeline_refusal (×3: Piped/Trailing/Orphaned)	4866	Refusal::new
ceiling_refusal	5126	Refusal::new
policy_refusal	5374	Refusal::new
unknown_program_refusal	6379	Refusal::declared
protected_refusal	6537	Refusal::declared
shape_refusal	6597	Refusal::new
content_refusal	6614	Refusal::new
unkeyed_refusal	6638	Refusal::new

Refusal::new leaves verdict: None — a state refusal.rs names outright: "the declared class, or None for a refusal composed from consumer prose." Also 0 of 32 mediated_call rules (0 of 97 rules) declare a verdict key.

policy_refusal is the subtle one: it is half-converted. It passes render_line's output as the reason, so the module path renders the one-line format correctly — but it still calls Refusal::new, so verdict stays None. refusal.verdict() therefore returns None even for module refusals, and policy explain is unreachable from the converted path too. Anything keying off the recorded token sees nothing.

Refinement — Ready (declare the classes the composers already state, and record them)

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

• Source of truth (§1). The ten composers in crates/batten/src/hook.rs tabulated above; refusal.rs's Refusal::new / Refusal::declared pair; verdict.rs's Native enum.
• Computable predicate (§2). Every mediated deny carries a declared class: refusal.verdict() is Some on every path, module refusals included. Decidable by construction and countable — Refusal::new sites in src fall from 21 to roughly 11.
• Mechanism (§3). Each unconverted composer's hardcoded cause becomes a declared class, and the composer switches to Refusal::declared — reuse it; do not write a third constructor. These are engine words about generic concepts (a substitution, a discarded verdict, a ceiling, a shape, unkeyed work), so per verdict.rs's own boundary — "These are Batten's OWN words… A refusal composed from a consumer's [[rule]] row is a different thing… and it is not represented here" — they belong in Native, not in consumer [[verdict]] rows. Native is an enum whose exhaustiveness is compile-checked, so the coupling lands in the type system rather than in a convention. **That is roughly ten new variants, not 32 config-row edits. **policy_refusal additionally records the token it already renders.
• Deliberately not in scope (§2). Rewriting the 6,640 words of class prose, and shortening the emitted line. Placement is this row's defect, not content — a summarisation pass loses the reasoning those rows were written to carry. Dropping the gloss from the hot path is a separate row and depends on this one landing first.
• Output & exit contract (§5). Unchanged. Exit 2 at the hook boundary either way; what changes is that the refusal now carries a token a reader can dereference.
• **Commit / bump (§6): **fix(hook) — patch until 0.1.0 regardless of type.
• Test obligation (§7). No new gate and no new severity, so no firing rate to establish — this converts existing refusals rather than adding one. Over the compiled binary: refusal.verdict() is Some for every mediated deny including the module path; the Refusal::new count in src is asserted rather than counted by hand; and policy explain resolves for every token any composer can raise. A token whose explanation is missing is a dereference pointing at nothing — CLOUD-1189's class, assertion borrowed, row not.
• Blockers (§8): none.

**Note for the implementer. **verdict::validate refuses a class with no route, and one whose only route is an override. A [[verdict]] row nothing raises fails the load, and a token no row declares fails the load — so a composer's token and its declaration must land in the same commit, never as two passes over the tree.

Acceptance

• Refusal::new sites in crates/batten/src fall from 21 to ~11, asserted.
• Tripping any mediated rule yields a refusal whose verdict() is Some, module path included.
• batten policy explain resolves every token any composer can raise.
• No refusal lost its pointer; no emitted text got longer.

CLOUD-1286 The hot path emits the gloss and two wrappers unconditionally, so the one-line format CLOUD-1053 landed is never what an agent actually sees

Why

verdict::render_line ships the target format in its own doc comment — V-TASK-UNDEFINED (a command row names a task this tree does not define) batten.toml:1604 — and GLOSS_MAX = 120 bounds the middle field on the stated reason that "a bound here is what keeps 'one line' a property of the data rather than of the author's restraint." Then three things put the paragraph back:

1. render_line emits (gloss) unconditionally.
2. Refusal::render wraps whatever it got in Refused by <rule>: … Fix: ….
3. The hook appends the bypass sentence — identical on every deny, which CLOUD-437 already recorded as a defect.

So even a declared refusal that render_line already reduced to one line is padded back out. The best refusal in the tree today, V-PROTECTED-MUTATION, is still ~25 words, and most of what it spends is dereferenceable: the Refused by <rule>: prefix restates the token, and the parenthetical is the token's own definition inlined.

The arithmetic. Roughly 300 refusals fire in a long session — every Bash call is mediated. Estimates below are token counts over the rendered text; the class-name column is measured with tiktoken o200k_base on CLOUD-1284:

	est. tokens	× ~300
what fires today (88 words, sampled live)	~115	~34,500
render_line's current output	~43	~12,900
token + pointer, gloss dropped	~6	~1,800

The gloss alone is ~28 of the ~43. ~34,500 against a ~175k window is 20% — which is CLOUD-417's headline figure, arrived at independently from the other direction, and evidence for that row as much as this one.

Cache is not a defence, and it is usually offered as one. Caching rewards repetition, and the boilerplate is byte-identical every firing, so it is already discounted on the invoice. But a cached token occupies exactly the same context window as an uncached one, and window pressure is what forces compaction. The objective is occupancy; the raw count is the honest number.

Rule 4 is not the defect. It forbids leaking matched content and it holds. README.md promises concision — "a wrapped tool's two thousand lines become one" — which is a different property, and nothing gates it. The prose grew inside the pointer.

Refinement — Ready (emit token and pointer; dereference the rest)

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

• **Source of truth (§1). **crates/batten/src/verdict.rs's render_line and GLOSS_MAX; refusal.rs's Refusal::render; the live samples taken 2026-09-01.
• Computable predicate (§2). A mediated refusal's emitted line carries a declared class and its pointers, and nothing else. Decidable over the emitted bytes against a declared ceiling.
• Mechanism (§3). The hot path emits token + pointer and stops: shell edit refused mise-tasks/land.sh:845. The gloss, the Refused by <rule>: prefix, the Fix: clause and the bypass sentence move behind batten policy explain <token>.
  The subject stays inline. render_line**'s own doc still governs: "making a reader run a second command to learn WHICH file would make the common case slower, which is the opposite of the point." This shortens the prose, never the pointer.****
  **Keep GLOSS_MAX. It still bounds explain's first line, and it is what stops the gloss growing back into a paragraph once nothing on the hot path reads it.
  Sequencing against CLOUD-1285, which is not a dependency. That row converts the eight untokened composers. Landing this one first is permitted and simply leaves those composers unchanged, and so unreachable by the ceiling until it lands. Neither row blocks the other.
• The gate (§3, non-negotiable 2). A declared ceiling on the emitted line, in batten.toml and never a literal in the crate — copy policy-budget's shape. GLOSS_MAX bounds one field; this bounds the line.
• **The decision this row must settle in writing (§2). **README.md also promises a refusal "points at the fix — a deny names the rule, the reason, and the command to run instead" — CLOUD-122's landed contract. This drops all three clauses from the emitted line. Either the token is the pointer to the fix (one hop via policy explain), or one remedy command stays inline and only the reasoning is dereferenced. Both are defensible; the second costs roughly 10 tokens × ~300 firings, so price it rather than assuming it free. Pick one, write down why, and amend the README clause to match — leaving the README claiming the other is exactly how this row's defect recurs.
• Deliberately not in scope (§2). Rewriting the 6,640 words of class prose. Placement is the defect, not content; moving it behind the dereference keeps every word available to whoever asks.
• Output & exit contract (§5). Exit codes unchanged. The emitted text is what changes, and it must stay byte-stable.
• **Commit / bump (§6): **fix(hook) — patch until 0.1.0 regardless of type.
• Test obligation (§7). The discriminating pair is the whole commit: a refusal over the ceiling fails, one under it passes. Anti-vacuity is mandatory — the converted no-tool-substitution refusal must still pass; a ceiling that refuses everything gets switched off. Plus: no refusal lost its path:line. Firing rate for the new deny is 0 after the converting commit by construction, and every refusal in the tree before it. Over the compiled binary, never with input as.
• Blockers (§8). Blocked by CLOUD-1284, and by nothing else. Dropping the gloss is safe only where the class name is self-describing on a declared grammar; without that this trades concision for opacity, which is the pylint-errors failure.

Acceptance

• Tripping no-tool-substitution deliberately emits one line: a token and a pointer. No gloss, no Refused by, no Fix:, no bypass sentence.
• batten policy explain resolves that token to the gloss and to the prose that used to be inline.
• No refusal lost its path:line.
• README.md's pointer-and-fix clauses say what the code now does.

CLOUD-1287 A newline is whitespace, so a multi-line call is judged by its first word — `protected_readers` is unreachable from any script, and the documented "under-denies" direction is measured backwards

Why

.claude/rules/policy-modules.md documents the newline bound and states a direction for it:

A newline is whitespace, not a separator — bash disagrees, and the bound is deliberate rather than an oversight… It under-denies, which is the sanctioned direction.

Measured, it over-denies. Discriminating pair, taken 2026-09-01 at 79b8bfd, same file and same read:

call	result
stat -c %s batten.toml	allowed — prints 343806
cd /tmp ⏎ stat -c %s /home/user/batten/batten.toml	refused: V-PROTECTED-MUTATION … /home/user/batten/batten.toml cd

stat is a declared protected_readers entry. Because a newline is whitespace rather than a separator, both lines are one segment, words[0] is cd, and stat is never consulted — the refusal names cd, a verb whose operand is a directory and which writes nothing at all.

**This is not a cosmetic misattribution; it disarms the design's own escape hatch. **batten.toml's protected_readers comment makes the fail-closed argument explicitly, and it rests on the hatch being cheap:

an operand that is a protected path now refuses unless the program is KNOWN — present in [[verb]] at all, or listed here. Forgetting an entry below is a false refusal somebody fixes in a minute; forgetting a writer is no longer a silent hole.

That trade is sound, and CLOUD-1141 landed it on those terms. But it cannot be a one-minute fix for a program that is already listed — stat is in the set and is still refused. Every multi-line script is judged by its first word, so the hatch is unreachable from the shape an agent writes most.

Three further readings from the same session, all consistent with one cause:

• echo hi && true batten.toml → refused, naming true.
• echo … with git grep … -- batten.toml on a later line → refused, naming echo.
• A printf format string on one line was reported as "a path in this repository" for a grep on another. (That last one is also CLOUD-1109's defect two from a new direction, and is recorded there.)

Why it belongs with the refusal-output rows. Every false refusal costs a ~90-token refusal plus a retry, so it inflates the exact bill CLOUD-1285 and CLOUD-1286 are cutting — and it fires on the most common command shape there is.

Refinement — Ready (stop attribution crossing a newline; do not touch the separator semantics)

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

• **Source of truth (§1). **hook::segments' newline handling in crates/batten/src/hook.rs; batten.toml's protected_readers set and the comment above it; the pair above, reproducible from any checkout.
• Computable predicate (§2). A declared reader's read of a protected path yields the same verdict whether or not an unrelated line precedes it in the same call. Decidable from the payload — no filesystem access, no spawn.
• Deliberately not in scope (§2), and this bound is the whole risk of the row. Do not promote a newline to a separator wholesale. .claude/rules/policy-modules.md records why: "promoting it would change every landed pipeline verdict." That is a far larger and riskier change than this defect needs. The narrow fix is that verb/operand attribution stops crossing a newline; segment identity for pipeline rows is untouched.
• **Effect (§3). **read. No verb is added and hook keeps its classification; the derived read-only allowlist does not move.
• **The gate (§3, non-negotiable 2). **crates/batten/tests/mediated_verbs.rs is the landed corpus for exactly this class — add the pair there. The obligation is met by an existing suite rather than a new gate, so nothing new is registered.
• Output & exit contract (§5). Unchanged. A deny is exit 2 at the hook boundary; this row changes which calls reach it, never the shape.
• **Commit / bump (§6): **fix(hook) — patch until 0.1.0. Not breaking for the consumer surface: the change only ever narrows what is refused, so no call allowed today starts failing.
• Test obligation (§7). No new deny and no severity to choose, so there is no firing rate to establish — this row removes refusals. Over the compiled binary: the pair above must produce one verdict, and it is red against the current binary, so it discriminates (CLOUD-418). The discriminator that keeps the fix from becoming a blanket allow: a genuine mutation of a protected path on a later line of a multi-line call must still be refused. Plus an assertion that a declared protected_readers entry is consulted rather than shadowed by an earlier line's verb.
• Blockers (§8): none. relatedTo CLOUD-857 (the landed precedent for anchoring on segments rather than the whole command line, and the same failure measured on the vendored preset), CLOUD-1257 (hook::segments blind to $(…) — a sibling defect in the same parser, not this one), CLOUD-1141 (the fail-closed design whose hatch this disarms) and CLOUD-1109 (the same rule family's path resolution).

Acceptance

• The pair above yields one verdict.
• A genuine mutation on a later line of a multi-line call is still refused.
• A protected_readers entry is consulted regardless of what precedes it in the call.
• .claude/rules/policy-modules.md's "it under-denies, which is the sanctioned direction" sentence is corrected, since it is now measured false — the prose and the parser must not disagree about which way the bound errs.

CLOUD-1109 `no-tool-substitution` resolves a bare relative path against the repo root, then asserts tracked-ness it never checked

Two independent defects in one row, reproduced twice on 2026-08-28 — once by a subagent, once directly.

Reproduction. With cwd /tmp/claude-0/.../scratchpad/probe, a directory outside the repository:

• cat err.txt — refused, verdict prose: "err.txt, a path in this repository", remedy: "a text utility over a path this repository tracks".
• cat /tmp/claude-0/.../scratchpad/probe/err.txt — the identical file, absolute — allowed.

err.txt is a transient scratch file. It is not in the repository and git ls-files has never heard of it.

Defect one: the path is resolved against the wrong root. A bare relative argument is being joined to the repository root instead of to the invocation's working directory. That is why the two spellings of one file get opposite verdicts, and it is the same class as CLOUD-824 — a second root resolver answering a different question from git::repo_root — except here the disagreement is between the repo root and the call's cwd rather than between two repo roots.

The consequence is not just a false positive on scratch work. Every path the guard judges is judged against a root the caller may not be in, so the corpus it thinks it is protecting and the corpus it is actually reading are different sets. A file inside the repo, reached by a relative path from a subdirectory, resolves to a different absolute path than the one the caller meant.

Defect two: the verdict asserts a fact nothing established. Both the verdict prose and the remedy state that the path is in this repository and that this repository tracks it. Neither was checked. .claude/rules/policy-modules.md makes a verdict token a thing a reader can look up; a token whose prose makes an unchecked claim about its subject is worse than an unnameable class, because the reader believes it. It also sends the reader to .claude/rules/scanning.md to choose between question classes that do not apply to a file the repository does not contain.

The two are independent and either can be fixed without the other, which is why both are named. Fixing only the resolution leaves a verdict that would still assert tracked-ness on the strength of containment; fixing only the prose leaves the guard refusing scratch work.

Authority. batten.toml's no-tool-substitution row (kind = "pipeline", scope = "mediated_call", severity = "deny") declares the rule; the path handling is the engine's, in whatever resolves a pipeline row's path arguments at the mediated-call boundary. The verdict prose belongs to the row's [[verdict]] entry.

---

Refinement — Ready (resolve against the caller's cwd, and stop claiming what was never checked)

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

• Authority boundary (§1). Two authorities, one each for the two defects, and neither is a runner. The path resolution belongs to the engine's pipeline argument handling in crates/batten/src/hook.rs, which must ask the invocation's working directory rather than the repository root. The prose belongs to the no-tool-substitution row's [[verdict]] entry in batten.toml. The rule row itself — kind, scope, severity, the utility corpus — does not change.
• Computable predicate (§2). A bare relative path argument resolves against the mediated call's own working directory. Decidable from the payload: the harness supplies the cwd, so the same file named relatively and absolutely from one directory yields one verdict rather than two. The tracked-ness question is decided here rather than deferred: do not check it, and stop asserting it. The guard decides containment, which is what it can see at the boundary; a git ls-files lookup per mediated call would be a spawn on the hook path, which RuleKind::scopes forbids for every mediated_call kind and which perf-assert's p95 budget prices out besides. So the verdict prose says containment, and says nothing about the index.
• **Effect (§3). **read. No verb is added; hook keeps its classification and the derived allowlist does not move.
• Output & exit contract (§5). Unchanged shape — a deny is exit 2 at the hook boundary. What changes is the verdict text: it must state only what the predicate decided. The remedy keeps pointing at .claude/rules/scanning.md, which is correct for a path the repository does contain.
• Commit / bump (§6). Lands as fix(hook) — patch until 0.1.0. Not breaking for the consumer surface: the change only ever narrows what is refused, so no call that is allowed today starts failing.
• Test obligation (§7). Over the compiled binary in crates/batten/tests/mediated_verbs.rs, the pair that is the whole defect: one file outside the repository, named relatively from its own directory and absolutely, must produce the same verdict — today they differ, so the assertion is red against the current binary per CLOUD-418. Plus the discriminator that keeps the fix from being a blanket allow: a relative path naming a file that is inside the repository, from a subdirectory, must still be refused. And a verdict-text assertion that the string carries no tracked-ness claim, so the second defect cannot silently return.
• Blockers (§8). None. relatedTo CLOUD-824, the same class one layer over — a second root resolver answering a different question from the engine's own primitive.

Found while grooming CLOUD-1089; the guard refused a scratch file twice during that work, which is how it surfaced.

CLOUD-609 A bare directory destination escapes the protected gate: `dir/` does not match the `dir/**` glob every consumer writes

Why

protected is a list of globs matched by rules::PathSet over globset with literal_separator(true). A directory-shaped operand — the trailing-slash form — is not a member of dir/**, which requires at least one component after the separator. So every mutating verb aimed at a directory inside the guarded set is allowed:

cp /tmp/draft.md .serena/memories/      # allowed
mv /tmp/draft.md .serena/memories/      # allowed
tee .serena/memories/                   # allowed (nonsense, but the same hole)

while the same commands naming a file inside it deny. .serena/memories/** is the shape consumer #1 declares and the shape the schema's own examples encourage, so this is the ordinary spelling rather than an exotic one.

It is a pre-existing gap, not CLOUD-442's. Measured on CLOUD-442's branch while porting cp/install: the retiring memory-guard-check matched the guarded path as a substring (*.serena/memories/*), so it caught the directory form; the engine's glob matcher does not. That makes it a fidelity loss in the CLOUD-312 port that CLOUD-442 did not introduce and deliberately did not widen its scope to fix — the every-operand verbs (mv, tee, rm) and the redirect pseudo-verbs have carried it since CLOUD-96.

The direction is under-denial, which is sanctioned (house style §5) — but a copy into the memories tree is the exact shape memory-guard existed for, so this one is worth closing rather than accepting.

Where the decision sits

Three candidate mechanisms, and the choice is a policy question rather than a bug fix, which is why this is filed rather than folded in:

1. Normalise the operand. Strip a trailing separator in hook::normalise before matching, so dir/ is asked as dir. Then dir/** still misses it — dir is not inside dir — so this only works together with (2) or (3).
2. Ask the containment question, not the membership one. A destination that is a directory means "write inside it", so the honest predicate is "does this path contain, or sit inside, a protected path" rather than "is it a member". That is a new question for PathSet and would need to be a named method, not a quiet widening of contains — every other caller wants membership.
3. Push it to the consumer. Document that a guarded directory needs both dir/** and dir declared. Cheapest, and it makes every consumer's config carry a subtlety the engine knows and they do not — the shape non-negotiable 1 usually argues for, but here the fact is about the matcher rather than about the repository.

Acceptance

• cp /tmp/x <guarded-dir>/ denies, under whichever mechanism is chosen, with the row's declared redirect intact.
• The read direction is untouched: cp <guarded-dir>/file /tmp/x still allows, and ls <guarded-dir>/ is not this gate's business.
• Whatever changes, PathSet::contains keeps meaning membership for its other callers — scope and unlanded are answers about files, and a rule selecting a directory would select nothing to inspect.

Both questions, answered in the Ready block below

1. Which of the three mechanisms, and specifically whether a containment predicate belongs on PathSet at all — it is a second question over the same lists, and the module's own doc comment says nothing here consults another field.
2. Does the redirect operand form (> dir/) need the same treatment? It cannot name a directory in a working shell (a redirect to a directory is an error), so the answer may be no — which would keep the fix inside protected_mutation's operand path.

Probe plan

• Unresolved decision. Choose normalization plus another mechanism, a distinct PathSet containment predicate, or consumer-declared dir; separately decide whether > dir/ belongs in scope.
• Probe. Run the recorded cp /tmp/x <guarded-dir>/ case and its read-direction controls against a .serena/memories/** declaration; compare the trailing-slash operand with a file inside the same directory. Exercise > <guarded-dir>/ only to establish its documented shell error behavior.
• Record. Allow/deny result for each operand form, redirect result, and whether any candidate changes PathSet::contains membership behavior for scope or unlanded.
• Ready / next step. Ready when one mechanism denies the directory destination while the read controls remain allowed and contains remains membership-only; include redirects only if the probe establishes a protected-mutation path rather than the stated shell error.

---

Refinement — Ready (normalise the operand and ask containment by a named method, never by widening contains)

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

Question 1 is answered (1)+(2), and (3) is declined. Normalisation alone provably does not close it — the body already shows dir is not inside dir/** — so it must pair with the containment predicate. Pushing it to the consumer is the one option that makes every consumer's config carry a subtlety about the matcher: the fact is Batten's, not the repository's, so non-negotiable rule 1 argues the opposite way here from usual. Requiring both dir/** and dir also means every consumer who writes only the shape the schema's own examples encourage stays exposed and never learns why.

Question 2 is answered no, and by evidence rather than by preference: a redirect to a directory is a shell error, so > dir/ cannot reach a working command. The fix stays inside protected_mutation's operand path, and the probe below exercises the redirect only to confirm that error behaviour rather than to gate it.

• **Authority boundary (§1). **crates/batten/src/hook.rs — normalise for the trailing separator, and protected_mutation for the operand. rules::PathSet gains a named containment method; contains is untouched and keeps meaning membership, because scope and unlanded are answers about files and a rule selecting a directory would select nothing to inspect. That is why a quiet widening of contains is refused rather than merely disfavoured: it would change what two unrelated callers ask.
• Computable predicate (§2). A mutating verb whose operand is a directory that contains or sits inside a protected path is denied. Two decidable steps: strip a trailing separator so dir/ is asked as dir, then ask containment rather than membership. The direction is deliberately one-way — the read direction is not this gate's business, so cp <guarded-dir>/file /tmp/x still allows and ls <guarded-dir>/ is never consulted.
• **Effect (§3). **read. hook keeps its classification: it inspects an operand and answers.
• Output & exit (§5). Unchanged: a deny is exit 2 at the hook boundary with the row's declared redirect intact, which is the part a careless fix drops — a refusal that stops naming the sanctioned mutation is a worse refusal even when it denies correctly. Pointer-only: the operand and the matched protected glob, never a file's contents.
• **Commit / bump (§6). **fix(hook) — patch until 0.1.0, since below that release-plz bumps the patch whatever the type says. Not ! for the consumer surface: this only ever adds refusals, which house style §8's raise-only invariant permits, and no exit code or output shape moves — no call allowed today by a correct reading starts failing. mise run semver decides the library half, since a new PathSet method is a pub API change and that must be asked, not assumed.
• Test obligation (§7). Over the compiled binary, shown able to fail per CLOUD-418. Red today, and it is the measured case: cp /tmp/x .serena/memories/ must deny, where the retiring memory-guard-check caught it by substring and the engine's glob matcher does not — a fidelity loss from the CLOUD-312 port, so the assertion is a regression test as much as a new one. The same for the other every-operand verbs the gap has always covered: mv and tee. The direction a careless containment predicate breaks: cp <guarded-dir>/file /tmp/x still allows. And the case that would otherwise ship silently: PathSet::contains still answers membership for scope and unlanded, asserted directly, because widening it would change two callers that never asked this question and would look like nothing in the diff.
• Blockers (§8). None. relatedTo CLOUD-442 (on whose branch this was measured, and which deliberately did not widen scope to fix it), CLOUD-312 (the port during which the substring matcher's coverage was lost), CLOUD-96 (which introduced the guarded set, and where the every-operand verbs have carried this since) and CLOUD-418.

CLOUD-1258 Nothing gates a `Read` of `.serena/memories/**`: `no-tool-substitution` decides over shell argv, so the memory tools are prescribed everywhere and required nowhere

Why

Measured 2026-08-31. A session read .serena/memories/github-access.md with the
generic file-read tool while the Serena MCP server was healthy and
read_memory was loadable. Nothing refused it, and nothing named the tool that
should have been used.

Two gates look like they cover this and neither can:

• no-tool-substitution is kind = "pipeline", scope = "mediated_call", with
  substitutes = ["cat", "head", "tail", "sed:-n", "grep", "rg", "find", "ls", "wc"]. It decides over shell argv. A structured-tool call is not a shell
  command, so the row is structurally incapable of seeing it. It gates
  shell utility → structured surface and there is no row for
  generic structured tool → specific semantic tool.
• .serena/memories/** is in protected, but crossed with the [[verb]]
  table, which enumerates mutations. CLOUD-442's port states "Reads stay
  allowed" — right for the question that row was answering, and the reason
  nobody has asked whether a read through the wrong instrument matters.

CLOUD-185 closed the write half of exactly this shape ("memory-guard sees only
Write/Edit — Bash writes and git mv into the memories tree bypass it").
CLOUD-864 produced no-tool-substitution for the shell half. This is the third
face of the same object and it is the one still open.

Why it is a defect rather than a style preference

A path read couples the caller to the tree layout. CLOUD-868 is an open proposal
to move .serena/memories/ into a private repository. Every flat-path read
of a memory is an unmigrated call site against that move: read_memory keeps
working across it, a hardcoded path does not. The gate makes those call sites
unwritable now rather than discoverable after the move breaks them.

The redirect also already exists — the protected-path rows carry the Serena tool
to use as each row's redirect, which is what makes this a matcher change
rather than new vocabulary.

The honest limit, stated so this row is not oversold

This gate would not have saved the session that found it. The failure there was
not reading the memory through the wrong tool — it was not reading it at all
until prompted, having asserted an environment block the memory exists to
refute. A redirect fires only once a read is already happening. That trigger
problem is a different mechanism and needs its own row; naming it here keeps
this one from claiming a reach it does not have.

Refinement — Ready

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

• **Source of truth (§1). **batten.toml's protected / [[verb]] crossing —
  the path set is already declared; what is missing is a read-side row over the
  structured-tool surface.
• Computable predicate (§2). A tool-call read whose target resolves under
  .serena/memories/** is refused with a redirect naming read_memory, when
  the session offers it. Absent Serena it must allow — a redirect naming a tool
  the session does not carry is CLOUD-998's defect one layer over.
• Effect (§3). No command-surface change.
• Output & exit (§5). Pointer-only: the path and the redirect, never a byte
  of the memory. Exit 2 is the mediated deny, per the one contract.
• **Commit / bump (§6). **feat → patch until 0.1.0.
• Test obligation (§7). A compiled-binary case over the mediated read; and
  the firing rate replayed before deny is chosen, since this fires on a read
  rather than a write and a noisy deny stops the fleet.
• Blockers (§8). None.

{
  "source_of_truth": "batten.toml",
  "gate": { "task": "batten-check", "exits": [0, 2] },
  "commit_type": "feat",
  "blockers": [],
  "tests": [
    {
      "file": "crates/batten/tests/mediated_verbs.rs",
      "mutation": "drop the read-side path match, so a generic read of a memory path is allowed"
    }
  ]
}

Acceptance

• A generic-tool read of a path under .serena/memories/** is refused and names
  read_memory, and the same read allows when Serena is not offered.

CLOUD-1282 A `mediated_call` row may declare tree-only fact columns and nothing refuses it — and the five that ARE refused are a hand-maintained list, which is the drift, not the fix

Why

The declaration-side half of CLOUD-1279's class, split out of it because the fix is a different shape with a different blast radius.

crates/batten/src/rules.rs:3452-3499 refuses five columns on a mediated_call row — documents, sources, lines, uses, invocations — each as its own hand-written if self.scope == RuleScope::MediatedCall && !self.<field>.is_empty() block. The comment on the second one records how the list grew:

"sources and lines are tree columns for the same reason documents is, and they were added to permits without this — so a mediated-call row could declare either and have it silently never read."

So the list is already known to lag the struct, and it still does. A mediated_call row may declare refs, git, ranges, captured, tools, forge, landing, staged, external, symbols or delta_sources today. Each parses, loads, is never acquired for that scope, and the module reading the corresponding input.tree.* key decides nothing — CLOUD-845's dead-gate class, arriving one layer above the module.

Why enumerating the missing ones is the wrong fix

CLOUD-1279's original acceptance asked for five more names to be added "alongside the five columns already refused". That was measured against the struct while building CLOUD-1279's module half and is wrong twice over: the set is larger than five, and a second hand-maintained list is precisely the mechanism that produced this gap. The first five were written by hand, the struct grew, and nobody updated them — writing five more reproduces that in a year.

The module half CLOUD-1279 landed does not have this problem, and it is the shape to copy: it reads the fact model (Fact::tree_key, Class::surface) rather than a list kept beside it, which is what tree_keys()'s own comment argues for — "the check is against the ENGINE's key set rather than against a list kept here… One table, read — never restated, which is the defect this whole row is an instance of."

The blast radius is real and is why this is its own row

A derived refusal can refuse rows that load today — in this repository and in every consumer's. That needs its own census before it lands: which committed rows declare a tree-only column on a mediated scope, and whether any is deliberate. CLOUD-1279's module half could be verified by running the suite; this one cannot.

---

Refinement — Ready (derive the column refusal from the fact model, not from a list)

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

• **Authority boundary (§1). **crates/batten/src/rules.rs and crates/batten/tests/. No mise-tasks/*.sh and no tests/**/*.bats.
• Computable predicate (§2). A mediated_call row declaring any column whose fact is not resolvable on the hook surface is refused at load, naming the column; the same row at scope = "tree" loads. Derived from the fact model, so a column added later is covered without an edit here — which is the property the current five do not have.
• Deliberately not in scope (§2). The module-side guard, which is CLOUD-1279's and landed. Changing which facts either surface carries.
• **Effect (§3). **read. Load-time only.
• Generated artifacts (§4). The config schema may regenerate if the refusal becomes expressible in it. mise run fix; never hand-edit.
• Output and exit (§5). Exit 1, naming the column and the scope. Pointer-only.
• **Commit / bump (§6). **fix(rules) — patch, unless the census finds a committed row it refuses, in which case the bump is that row's to argue.
• Test obligation (§7). Over the compiled binary. Shown able to fail per CLOUD-418: a mediated row declaring a tree-only column is refused naming it, and the anti-vacuity mirror — the same column at tree scope loads, and a mediated row declaring only hook-resolvable columns loads. Plus an arm that fails when a NEW tree-only column is added to the struct without being covered, so the derivation is asserted rather than assumed.
• Blockers (§8). None. relatedTo CLOUD-1279 (the module half, landed, and the row this was split from), CLOUD-845 (the class), CLOUD-876 (the general fix whose scope neither half completed alone), CLOUD-418.

Acceptance

• A mediated_call row declaring a tree-only column is refused at load, naming the column.
• The same column on a tree row still loads, and a mediated row declaring only hook-resolvable columns still loads.
• The refusal is DERIVED from the fact model — adding a tree-only column to Rule needs no edit here, and a test asserts that rather than a comment claiming it.
• The five hand-written blocks are replaced by the derivation rather than left beside it, so there is one authority and not two.
• A census of committed rows records whether any is refused by the change, in this repository and in batten.example.toml.

CLOUD-1091 `branch_validity` reads a branch that is merely BEHIND `origin/main` as CLOUD-516's restart, so a receipt taken against current main is void and re-taking it cannot help

Why

receipt.rs's branch_validity voids a branch-keyed receipt when

if own == 0 && recorded != head {
    return Validity::StaleMain;
}

recorded is the origin/main the check ran against; head is the branch's own HEAD. CLOUD-516's table justifies this for one situation — git checkout -B <name> origin/main after a merge, where the receipt's base is older than HEAD and the branch has nothing of its own.

The comparison is symmetric and the situation is not. It also fires when the receipt's base is newer than HEAD — a branch cut from an earlier main that has not been rebased yet. That is not a restart. The receipt is more current than the branch, not less.

Measured 2026-08-28, on claude/stage-2-3-grooming-uqk71k:

HEAD              8b1d209a      (branch, cut from the previous main)
origin/main       08ed7047      (advanced by one commit mid-session)
own commits       0
receipt base      08ed7047      (recorded by a search taken seconds earlier)
verdict           StaleMain

The issue-search receipt recorded the **current **origin/main, and the gate voided it anyway.

**The remedy the refusal prescribes cannot clear it. **filing-needs-a-search's reason says "Search the board before filing… The receipt mints itself from that result." The receipt is append-only and recorded_base correctly reads the last base line — so a fresh search appends a fresh, correct entry, the comparison still runs against HEAD, and the verdict is unchanged. Three searches were run; all three refused identically. The loop only broke on git merge --ff-only origin/main, which is not what the message asks for.

The message is backwards, which is what makes this expensive. It reads "the receipt was taken against an older origin/main, which has since moved." Both halves are false in this direction: the receipt was taken against the current main, and what is behind is HEAD. An author reading it re-runs the search — the one action guaranteed not to work.

Scope. The predicate is shared by every branch-keyed receipt (claim, issue-search, bot), so the same false void reaches claim-check's receipt and claim-needs-receipt's write gate. Any session on a branch that is behind main with no commits of its own is affected — which is the ordinary state of a freshly-cut branch in a repository landing ~40 commits/day.

What is not claimed. The CLOUD-516 direction is correct and must keep working: a receipt older than a restarted branch stays void. This is about the other direction only.

Acceptance

• A branch with no commits of its own, behind a receipt's recorded base, keeps a valid receipt.
• CLOUD-516's case still voids: a receipt whose base predates a restarted branch's HEAD is refused, with its existing case still red under mutation.
• Where a receipt is genuinely void, the message names the direction that is actually true, so the prescribed remedy is one that can clear it.

---

Refinement — Ready (the direction is the missing conjunct)

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

• **Authority boundary (§1). **crates/batten/src/receipt.rs — branch_validity and the Validity variant it returns. The reason strings on the receipt rows in batten.toml are a binding surface and are corrected in the same change wherever they state the direction; no predicate moves into config.
• Computable predicate (§2). A receipt is void only when its recorded base is an ANCESTOR of HEAD — the restart, where the branch moved forward off a base the receipt predates. A recorded base that HEAD has not reached yet is a branch awaiting a rebase and keeps the receipt. Decided in the engine, from facts repo_facts already resolves; no new rule kind and no new verb.
• **Effect (§3). **read. branch_validity inspects; nothing about the effect table or the derived allowlist changes.
• Output & exit (§5). Unchanged, and pointer-only: the verdict is a Validity variant, and the reason string names the direction and a remedy without carrying a receipt's contents.
• **Commit / bump (§6). **fix(receipt) — patch until 0.1.0. Not ! for the consumer surface: this only ever widens what passes, in the direction that was refusing correct work, and no row's declared shape changes. mise run semver decides the library half, since branch_validity is private.
• Test obligation (§7). Over the compiled binary, three cases, and the third is the discriminator: a behind-HEAD receipt is honoured; CLOUD-516's restart is still void; and a receipt whose base equals HEAD is honoured. Without the restart case a change that always returned Valid would pass, which is the direction this widening makes easy to get wrong. Shown able to fail per CLOUD-418 — the behind-HEAD case must be red against the current predicate, which is the measurement in the body above.
• Blockers (§8). None. relatedTo CLOUD-516 (the row whose fix introduced this comparison, and whose case must stay red), CLOUD-353 (a branch cut from a stale main, the state this misreads), CLOUD-820 and CLOUD-733 (the other two receipt-lifecycle defects on the same store).

Not in scope. The append-only receipt format — recorded_base already reads the last entry and is correct. Changing which checks are branch-keyed.

CLOUD-896 Two advisory producers share one channel and no rate budget, and a third is queued behind them

Why

CLOUD-461 puts the advisory drain onto hookSpecificOutput.additionalContext at PostToolBatch, alongside the drift notice — and its PR is explicit that they "coalesce into one document", asserted by a case that fires both producers on one batch. That solves framing: one JSON object per call. It does not solve volume: the two share no rate budget, and the Stop advisory (CLOUD-892) makes a third.

Coalescing bounds how many documents are emitted. Nothing bounds how much any of them says, or how often the set as a whole speaks. CLOUD-82 already holds a token budget for the drain alone; extending it to the channel rather than the producer is the difference between one well-behaved reporter and three reporters that are each individually reasonable.

The failure mode is CLOUD-417's, measured: hook output at 20% of a long session's context. And it is the same trajectory stop-guard took — one rule, then five, each defensible in isolation, with the aggregate never costed. Setting the ceiling before the third producer arrives is cheaper than rationalizing it after.

Refinement — Ready

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

• Source of truth (§1). One declared budget in batten.toml for the advisory channel, superseding the per-producer key CLOUD-82 shipped. One authority per fact.
• Computable predicate (§2). Producers are admitted to a single emission in AdvisoryTier order (severity as required response latency, CLOUD-80) until the channel budget is spent; the remainder is dropped, and the drop is counted rather than silent — a truncated report that reads as complete is the false green in advisory form.
• Effect (§3). Unchanged.
• Output & exit (§5). Exit 0; pointer-only. The count of suppressed findings is itself a pointer and is the one addition.
• **Commit / bump (§6). **feat → patch until 0.1.0. ! if CLOUD-82's per-producer key is removed rather than deprecated.
• Test obligation (§7). Three producers firing on one boundary emit one document within budget, ordered by tier, with a suppressed-count line. Mutation coverage per CLOUD-418: removing the budget comparison turns the truncation case red.
• Blockers (§8). None; the one blocker has landed. CLOUD-461 was its one blocker, because the channel had to exist before it could have a budget. CLOUD-461 is Done — encode_claude_advice and the one-document drain are on main, and CLOUD-1051 has since moved the Stop surface onto the same channel — so the precondition is discharged and the relation is removed rather than left reading as live. relatedTo CLOUD-82 (the per-producer budget this supersedes), CLOUD-80 (AdvisoryTier, the admission order), CLOUD-892 (the third producer this exists to bound before it arrives), CLOUD-417 (the measured 20% this is the forward-looking half of) and CLOUD-418.

Done

The advisory channel has one declared ceiling that every producer is admitted under, and what does not fit is counted rather than dropped silently.

CLOUD-417 Hook output is 20% of a long session's context, because "pointer, never payload" was never applied to the hooks themselves

Why

Non-negotiable 4 holds every check to "a count, path:line, or boolean — never the content itself." Each hook obeys it individually. Nobody has measured them in aggregate, over a session, where the same compliant line is emitted hundreds of times and every copy stays in context forever.

Measured on transcript 125cdf71 (2026-08-11/12, 758 turns, 5.83 MB):

attachment kind	bytes
hook_success	1181 KB
edited_text_file	95 KB
nested_memory	88 KB
hook_additional_context	42 KB

Hook output alone is 20% of the transcript. The single largest contributor is mcp-attach-check reporting "every enabled MCP server attached this session" on essentially every user turn — a true statement, correctly pointer-shaped, and identical every time. contract-drift is the second: it correctly reports a changed file set once per change-set, but a session editing the same two files repeatedly re-triggers it, and each report is re-read by every subsequent turn.

Why this is Batten's problem specifically. Context is the metered resource an agent pays on every turn (CLOUD-415), and these bytes are spent by the policy engine, on the agent's behalf, without the agent asking. A gate whose own reporting is a material fraction of the budget it protects is measuring the wrong thing. This repository is consumer #1 of its own engine, and this is what that self-application found.

Root cause. The output rule is stated per-check and enforced per-check. There is no rule about a check's output over a session, so a hook that is silent-by-default (correct) and one that confirms success every turn (also individually defensible) are indistinguishable to every gate that exists.

Refinement — Ready

• Source of truth (§1). The session transcript's attachment records, grouped by hook. Exact, on disk, no estimate. Same reading CLOUD-415 takes.
• Mechanism (§3). Two parts, and the first is most of the win:
  • Silence on success is the default. A hook that has nothing to report emits nothing. contract-drift already documents this posture — "Silence is the default; a change-set is reported once" — and it is the right one; the gap is that not every hook adopted it. mcp-attach-check's confirmation is the clearest case: it says the same thing every turn and nothing acts on it.
  • A repeat is a pointer to the first, not a copy. Where a hook must speak again, it emits a one-line reference rather than the full text — the same reason contract-drift reports a change-set once rather than every turn.
• The gate (§3, non-negotiable 2). A budget over hook output per session, in the grammar policy-budget already defines for the instruction surface: a measured ceiling, derived rather than typed, that a hook exceeding it fails. Prose asking hooks to be quiet is exactly the feedforward this repo refuses.
• Deliberately not in scope (§2). Removing any hook, or weakening what it detects. Every finding stays; only its restatement is bounded.

Test obligation

A suite over fixture transcripts: a hook that says the same thing N times is a violation, a hook silent on success is clean, and a hook reporting one change-set once is clean. Plus the property that makes this self-applying — the budget check's own output is one line.

Commit / bump (§6): fix(hooks) — patch until 0.1.0 regardless of type.

Blockers (§8): none. Sharper once CLOUD-415 makes session cost readable, since the same reading serves both.

Acceptance

• Hook output is a measured fraction of session context, reported rather than assumed.
• A hook that repeats an unchanged success message fails a gate.
• The measurement is re-runnable against any transcript, so the 20% figure can be checked rather than believed.

CLOUD-1189 Nothing checks that a remedy names a command that exists, so 31 redirect strings can point at a verb that was renamed away — the refusal contract's own defect class, one table over

Why

redirect.rs owns the per-path-class remedy table: "what to run instead, keyed by what is protected". Its strings are free-form prose, and nothing resolves the command they name against anything. batten.toml carries 31 of them.

CLOUD-122's refusal contract is that every deny names the fix. A deny naming a command that does not exist is worse than a deny naming none: it sends the reader to a shell error instead of a remedy, and it looks authoritative doing it.

This is exactly the defect class CLOUD-1050 recorded — one table over. There, msg was a String, so "a refusal naming no remedy, naming a task that does not exist, or offering an override with no precondition were all expressible and none checkable", and two were live in this repository when the row was written. [[verdict]] fixed it for verdict tokens by making the class a registry a gate can read. The redirect table has the same hole and no such registry.

Why now

A surface rename makes this acute rather than theoretical: any verb that moves turns every remedy naming it into a lie, silently, with no gate reporting it. But the hole is real today — a remedy could already name a command that never existed, and nothing would say so.

The gate is small, the object is a committed file, and it is independent of every other row in this closure.

A LIVE instance measured 2026-08-31, and §2 as written would not catch it

Recorded here rather than filed separately because this row owns the class. It is not a restatement — it is an instance whose object this row's predicate currently excludes, so the row's author has a decision to make rather than a duplicate to close.

mise-tasks/land.sh:1540 refuses a prose-only branch and tells the reader:

*"… or set *BATTEN_PROSE_ONLY_OVERRIDE=1 if the prose is the deliverable and cannot wait — that records which branch used it."

That variable does nothing. batten.toml:3807-3811, on the ported prose-only ***rule, states the opposite in as many words: "THE OVERRIDE IS DECLARED ON THE CLASS, not here. [[verdict]]'s ***V-PROSE-ONLY-DIFF ***carries an ***override ***route with its precondition … No ***bypass_env: the whole point of that row is that the bare variable stops working." CLOUD-1051 removed it deliberately; the message that advertises it was left standing.

So a reader who follows the refusal's own remedy sets a variable with no reader and gets refused again, with no indication why — the shape CLOUD-729 recorded once already ("a refusal advertises a remedy its reader cannot reach").

Why §2 misses it, stated precisely so the scope decision is informed:

this row's §2	the instance
the object is a redirect string in batten.toml	the object is a die message in a mise-tasks/*.sh program
the named thing is a batten <…> invocation	the named thing is an environment variable
resolves against SURFACE or the [[rule]] table	would resolve against the bypass_env fields — a third authority this row does not read

All three differ, so widening is a real design change and not a one-line selector edit. The cheapest correct answer may be neither: land.sh is governed by shell-retirement, so that message cannot be edited at all — only retired — and the stale line therefore dies with land.sh's own retirement whether or not this row widens. Worth knowing before anyone scopes work here.

A second, sharper half, since it is what made the instance costly. The refusal did not arrive through land.sh at all. prose-only is also a tree-scoped [[rule]] run inside batten-check, so verify stopped with its generic line — "a gate refused this tree — read the step's own path:line pointers above" — and V-PROSE-ONLY-DIFF's declared route R-BATCH-IT ("let the next change to these files carry the prose") was never shown. It was found by reading batten.toml by hand. A verdict registry that a gate can read is only half of CLOUD-1050's fix; the other half is the route reaching the reader at the moment of refusal, and on this path it does not.

Refinement — Ready (a remedy resolves to a declared command or rule)

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

• **Authority boundary (§1). **policy/ (a new module) or crates/batten/src/redirect.rs plus its [[rule]] and [[verdict]] rows in batten.toml, and crates/batten/tests/. **No **mise-tasks/ **program and no **.bats suite — V-SHELL-RULE-ADDED refuses.
• Computable predicate (§2). Every batten <…> invocation appearing in a redirect string resolves to either a declared SURFACE path or a declared [[rule]] id. A string naming neither is a finding.
• **It must recognise both object shapes (§2). **batten check <rule-id> resolves against the rule table; batten show config against SURFACE. A gate that only knew one would report the other as broken, which is the false positive that gets a gate switched off.
• Deliberately not in scope (§2). Remedies that name a non-batten command (mise run …, git …) — those are the operator's PATH, and resolving them would need a second authority over what is installed. Rewriting any existing remedy's wording. Whether a remedy is good advice, which is judgement and not gateable.
• **Effect (§3). **read.
• Output and exit (§5). Pointer-only: the redirect row and the unresolvable command, never the remedy prose. Exit follows the 0/1/2/3 table.
• **A **[[verdict]] row ships with it (§5), with routes: correct the remedy, or declare the command. A gate about unresolvable remedies that itself raised an unregistered token would be the joke writing itself.
• **Commit / bump (§6). **feat(policy) — patch.
• Test obligation (§7). Module test_ rules plus a compiled-binary tier in crates/batten/tests/*.rs. Shown able to fail per CLOUD-418, four observed: (a) a remedy naming a removed verb is reported; (b) a remedy naming a declared rule id is not reported — the anti-vacuity mirror; (c) a remedy naming a non-batten command is not reported; (d) all 31 current strings pass, or each failure is recorded as a real finding rather than a reason to weaken the predicate.
• Blockers (§8). None. relatedTo CLOUD-1050 (the same defect class in the verdict table), CLOUD-1184.

Acceptance

• A redirect naming a batten command that is neither a declared path nor a declared rule id is a finding, naming the row and the command.
• All 31 existing strings are resolved; anything that fails today is filed rather than papered over.
• The gate survives the surface rename by construction — it resolves against SURFACE, so a renamed verb makes stale remedies fail immediately rather than silently.

Found while pressure-testing a surface rename: the largest silent hazard was not the code, it was 31 unvalidated strings telling people what to run instead.

CLOUD-1308 config-lint compares verdict classes by id, so any rename of an override-bearing class reads as a hatch newly added — a false positive CLOUD-1284 makes reachable 105 times

Why

trust.rs's verdict_override_entries collects the id of every [[verdict]] class declaring an override route, and weakenings reports the set difference as VerdictOverrideAdded. Its own doc comment says why the id is the object: "a class either offers a hatch or it does not, and which precondition it states is the judgement this module refuses to make."

That is correct for an edit and wrong for a rename. Base and working sets are keyed by id, so a class renamed from A to B leaves A absent and B present, and B is reported as a hatch newly added. The removal side is deliberately not reported (deleting a class is fail-closed — a module raising an undeclared token fails to load), so nothing in the comparison cancels it out.

Measured, on the branch that makes it reachable

CLOUD-1284 renames every class in the registry, so this fires once per override-bearing class in one commit. On claude/refusal-surface-bundle-5l3ovp against origin/main:

batten.toml:verdict[diff ship early].override      verdict-override-added
batten.toml:verdict[issue file same].override      verdict-override-added

Both are pure renames — V-PROSE-ONLY-DIFF and V-FILED-OVER-OWN-DIFF. Route, precondition and gloss are byte-identical to main's; only the id changed. Two of 105 consumer rows carry an override today, so the blast radius is small now and is a property of that ratio rather than of the mechanism.

Why it matters more than two lines of noise

The admission mechanism worked exactly as designed — a Weakens: trailer plus a groomed clause on CLOUD-1284, admitted groomed. But what got admitted is a weakening that did not happen. Every future reader of that receipt and that trailer sees this branch declaring it added two hatches. The record is now wrong in the durable direction, and the correct remedy was spent to make it so.

It also means the gate cannot distinguish the case it exists for. A branch that renamed a class and added a real override to it would produce one indistinguishable line, and the honest admission for the rename would cover the hatch.

Refinement — Ready (a rename is not a hatch)

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

• **Source of truth (§1). **crates/batten/src/trust.rs — verdict_override_entries (the projection) and weakenings' VerdictOverrideAdded block. crates/batten/tests/it/config_trust.rs for the tier.
• Computable predicate (§2). A class present in the working set and absent from the base set is VerdictOverrideAdded only where no base class resolves to it as a rename. What makes a rename resolvable is the open question below, and it is the whole of the work.
• **The candidate mechanism, and its cost stated up front (§2). **DeclaredVerdict already carries successor and withdrawn — a tombstone chain verdict::validate requires to terminate. A rename that leaves the old id as a tombstone naming its successor makes the comparison resolvable with no new field. CLOUD-1284 deleted the old ids outright instead, so it would have owed ~105 tombstone rows; whether that is the right price for a one-time rename is this row's decision and not a foregone conclusion.
• Do NOT report the removal side to cancel it (§2). That was considered and loses: deletion is fail-closed today (a module raising an undeclared token fails the load), so reporting it would add a second finding per rename rather than removing one, and it would report on every legitimate class retirement.
• **Effect (§3). **read.
• Output and exit (§5). Unchanged — the same pointer line and the same admission path.
• **Commit / bump (§6). **fix(trust) — patch.
• Test obligation (§7). The discriminator is the pair, and the second half is what keeps the fix from becoming a blanket allow: a class renamed with its override unchanged is not reported (red today), and a class renamed that also gained an override is still reported. Plus the anti-vacuity mirror config_trust.rs already carries — a class that gained a hatch without a rename is reported, and an unchanged table says nothing.
• Blockers (§8). None. It is decidable from the two configs alone.

Acceptance

• A pure rename of an override-bearing class produces no verdict-override-added.
• A rename that also opens a hatch still does.
• The two lines this branch admitted would not have needed admitting.

Provenance. Found by spending the admission on it: the trailer and the groomed clause on CLOUD-1284 are the durable record of a weakening that did not occur, and writing that clause honestly is what made the defect legible.

Review in Linear

[coderabbitai]

Warning

Review limit reached

Next included review available in 4 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: 0502dd6e-7fa6-47ca-b7f3-d5af0cad62c5

📥 Commits

Reviewing files that changed from the base of the PR and between 7aa647e and 707ab41.

⛔ Files ignored due to path filters (2)

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

📒 Files selected for processing (90)

• .claude/rules/policy-modules.md
• .claude/rules/toolchain.md
• .serena/memories/core.md
• batten.toml
• bench/suites/RESULTS.md
• completions/batten.bash
• completions/batten.fish
• completions/batten.zsh
• crates/batten/src/advisory.rs
• crates/batten/src/budget.rs
• crates/batten/src/bypass.rs
• crates/batten/src/cli.rs
• crates/batten/src/completion.rs
• crates/batten/src/config.rs
• crates/batten/src/hook.rs
• crates/batten/src/hookcost.rs
• crates/batten/src/lib.rs
• crates/batten/src/lint.rs
• crates/batten/src/mutate.rs
• crates/batten/src/policy.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/already-landed-work-is-not-relanded.rego
• crates/batten/src/policy/presets/landing-loop/graded-head-is-not-regraded.rego
• crates/batten/src/policy/presets/landing-loop/lease-authorises-the-branch.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/redirect.rs
• crates/batten/src/resolve.rs
• crates/batten/src/rules.rs
• crates/batten/src/selfwrite.rs
• crates/batten/src/spec.rs
• crates/batten/src/surface.rs
• crates/batten/src/transcript.rs
• crates/batten/src/trust.rs
• crates/batten/src/verdict.rs
• crates/batten/tests/it/cli.rs
• crates/batten/tests/it/config_lint.rs
• crates/batten/tests/it/fact_record_keying.rs
• crates/batten/tests/it/hook_cost.rs
• crates/batten/tests/it/lock_complete.rs
• crates/batten/tests/it/main.rs
• crates/batten/tests/it/memories.rs
• crates/batten/tests/it/pointer_only.rs
• crates/batten/tests/it/redirect_resolves.rs
• crates/batten/tests/it/rules_drift.rs
• crates/batten/tests/it/shell_retirement.rs
• crates/batten/tests/it/staged_facts.rs
• crates/batten/tests/it/stop_posture.rs
• crates/batten/tests/it/target_prune.rs
• man/batten-policy-hooks.1
• man/batten-policy.1
• 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-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/rules-drift.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
• schema/batten.local.schema.json
• schema/batten.schema.json
• tests/fact-record-keying.bats

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Free

Run ID: d17792ec-3e34-4ac0-adac-0b7f2cd094fa

📥 Commits

Reviewing files that changed from the base of the PR and between 4d5bd0c and 7aa647e.

⛔ Files ignored due to path filters (3)

• Cargo.lock is excluded by !**/*.lock
• crates/batten/tests/it/snapshots/it__snapshots__golden_json_schema.snap is excluded by !**/*.snap
• hk.pkl is excluded by !**/*.pkl

📒 Files selected for processing (140)

• .claude/rules/policy-modules.md
• .claude/rules/toolchain.md
• .github/workflows/auto-release-land.yml
• .regal/rules/custom/regal/rules/abi/refusal-is-typed/refusal_is_typed_test.rego
• Cargo.toml
• README.md
• batten.toml
• completions/batten.fish
• completions/batten.zsh
• crates/batten/Cargo.toml
• crates/batten/src/admission.rs
• crates/batten/src/cli.rs
• crates/batten/src/commit.rs
• crates/batten/src/config.rs
• crates/batten/src/hook.rs
• crates/batten/src/lib.rs
• crates/batten/src/perf.rs
• crates/batten/src/policy.rs
• crates/batten/src/policy/presets/ci-hygiene/spend-is-authorised.rego
• crates/batten/src/policy/presets/ci-hygiene/wiring-can-be-reached.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/shell-hygiene/sibling-resolves.rego
• crates/batten/src/policy/presets/trunk-based/no-force-push.rego
• crates/batten/src/ready.rs
• crates/batten/src/receipt.rs
• crates/batten/src/redirect.rs
• crates/batten/src/refusal.rs
• crates/batten/src/rules.rs
• crates/batten/src/semver.rs
• crates/batten/src/surface.rs
• crates/batten/src/trust.rs
• crates/batten/src/verdict.rs
• crates/batten/tests/fixtures/repos/policy-mediated-call/batten.toml.in
• crates/batten/tests/fixtures/repos/policy-mediated-call/gate.rego.in
• crates/batten/tests/it/acquisition_sweep.rs
• crates/batten/tests/it/admission.rs
• crates/batten/tests/it/authority_replay.rs
• crates/batten/tests/it/board_receipts.rs
• crates/batten/tests/it/bypass_scrub.rs
• crates/batten/tests/it/call_background_flag.rs
• crates/batten/tests/it/captured_facts.rs
• crates/batten/tests/it/ci_parity.rs
• crates/batten/tests/it/claim_receipt.rs
• crates/batten/tests/it/cli.rs
• crates/batten/tests/it/commit_admission.rs
• crates/batten/tests/it/commit_meta_facts.rs
• crates/batten/tests/it/common/mod.rs
• crates/batten/tests/it/connector_not_granted.rs
• crates/batten/tests/it/connector_verbs.rs
• crates/batten/tests/it/document_read_count.rs
• crates/batten/tests/it/external_facts.rs
• crates/batten/tests/it/extracted_facts.rs
• crates/batten/tests/it/forge_facts.rs
• crates/batten/tests/it/git_facts.rs
• crates/batten/tests/it/harness_grant.rs
• crates/batten/tests/it/history_facts.rs
• crates/batten/tests/it/hook_profile.rs
• crates/batten/tests/it/issue_key.rs
• crates/batten/tests/it/main.rs
• crates/batten/tests/it/mediated_admission.rs
• crates/batten/tests/it/mediated_verbs.rs
• crates/batten/tests/it/memories.rs
• crates/batten/tests/it/mise_pin_agreement.rs
• crates/batten/tests/it/perf_pair.rs
• crates/batten/tests/it/pinned_programs.rs
• crates/batten/tests/it/pipeline_shapes.rs
• crates/batten/tests/it/pointer_only.rs
• crates/batten/tests/it/policy_severity.rs
• crates/batten/tests/it/policy_test_suite.rs
• crates/batten/tests/it/policy_tree.rs
• crates/batten/tests/it/privileged_lane.rs
• crates/batten/tests/it/prose_only.rs
• crates/batten/tests/it/ready.rs
• crates/batten/tests/it/refusal_ceiling.rs
• crates/batten/tests/it/retirement_doctrine.rs
• crates/batten/tests/it/review_answered.rs
• crates/batten/tests/it/rules_builtin_claims.rs
• crates/batten/tests/it/rules_drift.rs
• crates/batten/tests/it/run_shape.rs
• crates/batten/tests/it/runner_verdict.rs
• crates/batten/tests/it/semver_gate.rs
• crates/batten/tests/it/shell_retirement.rs
• crates/batten/tests/it/shell_write_advisory.rs
• crates/batten/tests/it/sinks.rs
• crates/batten/tests/it/staged_facts.rs
• crates/batten/tests/it/stop_posture.rs
• crates/batten/tests/it/target_prune.rs
• crates/batten/tests/it/task_prose.rs
• crates/batten/tests/it/task_receipt.rs
• crates/batten/tests/it/tool_verdict_facts.rs
• crates/batten/tests/it/verdict_registry.rs
• crates/batten/tests/it/verdict_vocabulary.rs
• crates/batten/tests/policy_modules.rs
• man/batten-override-request.1
• man/batten-override-spend.1
• man/batten-policy-explain.1
• 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/connector-not-granted.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/hook-profile.rego
• policy/lock-entry-complete.rego
• policy/memories.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/rules-drift.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/test-targets.rego
• policy/validator-verdict-clean.rego
• policy/verdict-routes-resolve.rego
• policy/weakens-declared.rego
• policy/workspace-dep-referenced.rego
• renovate.json5
• schema/batten.local.schema.json
• schema/batten.schema.json

🚧 Files skipped from review as they are similar to previous changes (138)

• crates/batten/src/surface.rs
• .claude/rules/toolchain.md
• completions/batten.fish
• crates/batten/tests/it/main.rs
• policy/claim-before-code.rego
• Cargo.toml
• completions/batten.zsh
• man/batten-policy-explain.1
• man/batten-override-spend.1
• .regal/rules/custom/regal/rules/abi/refusal-is-typed/refusal_is_typed_test.rego
• .github/workflows/auto-release-land.yml
• crates/batten/tests/fixtures/repos/policy-mediated-call/gate.rego.in
• policy/workspace-dep-referenced.rego
• renovate.json5
• policy/remedy-authorship.rego
• crates/batten/tests/fixtures/repos/policy-mediated-call/batten.toml.in
• policy/ancestry-decides-nothing.rego
• crates/batten/src/cli.rs
• crates/batten/src/commit.rs
• crates/batten/tests/it/connector_not_granted.rs
• policy/denials-outlive-the-turn.rego
• crates/batten/tests/it/claim_receipt.rs
• crates/batten/tests/it/prose_only.rs
• policy/release-tag-shape.rego
• crates/batten/tests/it/perf_pair.rs
• policy/spawn-adapters.rego
• crates/batten/src/policy/presets/pinned-toolchain/pinned-program-via-the-pin.rego
• crates/batten/tests/it/semver_gate.rs
• crates/batten/tests/it/runner_verdict.rs
• crates/batten/tests/it/harness_grant.rs
• crates/batten/src/policy/presets/shell-hygiene/shebang-names-its-language.rego
• crates/batten/tests/it/rules_builtin_claims.rs
• crates/batten/tests/it/stop_posture.rs
• crates/batten/src/perf.rs
• crates/batten/tests/it/task_receipt.rs
• crates/batten/src/policy/presets/trunk-based/no-force-push.rego
• crates/batten/tests/it/forge_facts.rs
• crates/batten/tests/it/common/mod.rs
• crates/batten/tests/it/external_facts.rs
• crates/batten/tests/it/target_prune.rs
• crates/batten/tests/it/memories.rs
• crates/batten/tests/it/bypass_scrub.rs
• crates/batten/tests/it/pointer_only.rs
• crates/batten/tests/it/hook_profile.rs
• crates/batten/Cargo.toml
• crates/batten/tests/it/authority_replay.rs
• crates/batten/tests/it/commit_meta_facts.rs
• crates/batten/tests/it/run_shape.rs
• policy/validator-verdict-clean.rego
• policy/shell-write-advisory.rego
• crates/batten/tests/it/call_background_flag.rs
• crates/batten/tests/it/staged_facts.rs
• crates/batten/tests/it/commit_admission.rs
• crates/batten/tests/it/history_facts.rs
• man/batten-override-request.1
• crates/batten/tests/it/shell_retirement.rs
• crates/batten/tests/it/acquisition_sweep.rs
• crates/batten/tests/it/task_prose.rs
• crates/batten/src/semver.rs
• policy/harness-wiring.rego
• crates/batten/src/policy.rs
• crates/batten/src/policy/presets/shell-hygiene/sibling-resolves.rego
• crates/batten/tests/it/mise_pin_agreement.rs
• policy/filed-here.rego
• crates/batten/src/policy/presets/landing-loop/graded-head-is-not-regraded.rego
• crates/batten/tests/it/refusal_ceiling.rs
• policy/ci-suite-lane.rego
• crates/batten/tests/it/privileged_lane.rs
• policy/prose-only.rego
• policy/privileged-lane.rego
• policy/task-substitution.rego
• policy/review-answered.rego
• policy/verdict-routes-resolve.rego
• crates/batten/tests/it/pipeline_shapes.rs
• crates/batten/tests/it/connector_verbs.rs
• crates/batten/tests/it/ready.rs
• policy/run-shape.rego
• crates/batten/tests/it/pinned_programs.rs
• policy/stop-posture.rego
• crates/batten/tests/it/captured_facts.rs
• policy/weakens-declared.rego
• schema/batten.local.schema.json
• crates/batten/tests/it/extracted_facts.rs
• policy/module-layering.rego
• crates/batten/src/policy/presets/ci-hygiene/spend-is-authorised.rego
• crates/batten/src/ready.rs
• README.md
• policy/test-targets.rego
• crates/batten/src/lib.rs
• crates/batten/tests/it/sinks.rs
• crates/batten/tests/it/retirement_doctrine.rs
• crates/batten/tests/it/mediated_admission.rs
• policy/connector-not-granted.rego
• policy/lock-entry-complete.rego
• crates/batten/tests/it/tool_verdict_facts.rs
• policy/hk-fix-selection.rego
• crates/batten/tests/it/ci_parity.rs
• crates/batten/tests/it/policy_test_suite.rs
• crates/batten/src/admission.rs
• crates/batten/tests/it/git_facts.rs
• crates/batten/src/receipt.rs
• policy/hook-profile.rego
• crates/batten/src/config.rs
• crates/batten/tests/it/policy_severity.rs
• policy/command-task-defined.rego
• crates/batten/src/policy/presets/commit-hygiene/no-empty-commit.rego
• policy/rules-drift.rego
• crates/batten/tests/it/verdict_vocabulary.rs
• crates/batten/tests/it/issue_key.rs
• policy/harness-grant.rego
• crates/batten/tests/it/shell_write_advisory.rs
• policy/ci-parity.rego
• crates/batten/tests/it/document_read_count.rs
• crates/batten/tests/it/board_receipts.rs
• schema/batten.schema.json
• policy/opa-compliance.rego
• crates/batten/tests/it/mediated_verbs.rs
• crates/batten/tests/it/verdict_registry.rs
• policy/mise-pin-agreement.rego
• crates/batten/src/trust.rs
• policy/memories.rego
• crates/batten/tests/policy_modules.rs
• mise.toml
• policy/forge-verdict-required.rego
• crates/batten/tests/it/review_answered.rs
• crates/batten/tests/it/policy_tree.rs
• crates/batten/src/rules.rs
• policy/suite-subject-retirable.rego
• crates/batten/src/redirect.rs
• crates/batten/src/policy/presets/ci-hygiene/wiring-can-be-reached.rego
• crates/batten/tests/it/admission.rs
• policy/shell-retirement.rego
• .claude/rules/policy-modules.md
• policy/bats-invocation.rego
• crates/batten/tests/it/cli.rs
• crates/batten/tests/it/rules_drift.rs
• crates/batten/src/hook.rs
• batten.toml

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

---

📝 Walkthrough

Walkthrough

The change replaces legacy V-* and R-* identifiers with three-word lowercase verdict and route names. It adds configurable vocabulary validation, tokenizer checks, refusal token ceilings, compact refusal rendering, and policy explanation support. Shell mutation analysis now evaluates newline-separated commands independently, resolves paths relative to the caller’s working directory, and protects contained directories. Shell-retirement rules add # stays-bash: support for additions and expand successor handling. Receipt validation and mediated-rule validation now use directional branch checks and a complete column census. Policies, fixtures, documentation, completions, and integration tests are updated for the new contracts.

Merge Risk: ⚪ Minimal · up to 7aa64

The current change is merge-ready after normal checks and review; no actionable merge-blocking risk remains.

---

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.}

[wenzowski]

SonarCloud: analysis failed on three consecutive heads, and it is not this PR's

sonarqubecloud[bot] has posted "❌ The last analysis has failed" on 31bb1d1,
bc83689 and 32bdec1. Standing down on it, with the reason, rather than
leaving it silent.

It is an analyser-side failure, not a verdict about this diff. "The last
analysis has failed" is the run erroring, not a quality gate returning a rating.
There is nothing on these heads to root-cause in the diff.

It is outside this repository's control by construction. There is no
SONAR_TOKEN and no Sonar step in any workflow — analysis arrives through the
SonarCloud GitHub App's automatic analysis. mem:workflow/sonar-scope records
exactly that, and it is why none of it is observable from here.

It is not in the landing path. 5c510fa removed sonar-gate from final
and from verify:gated. The task still exists and runs by hand; nothing in
CI_REQUIRED_CHECKS reads it. So this cannot block the merge, and restoring it
unfixed is CLOUD-897's, not this PR's.

No re-run spent. A re-run is for confirming a failure that is not this PR's,
and three consecutive failures across three unrelated heads have already
established that. There is also no re-run available: the App triggers itself.

If somebody wants this chased, the probe that actually distinguishes the two
analyses is in mem:workflow/sonar-scope — always read details_url, because
SonarCloud posts the PR-scoped and the branch=main analyses under the identical
check-run name, and a conclusion without it is not a verdict about anything in
particular.

Local verification for these heads is in the PR body: test:cargo 3619/3619,
policy-test 464/464, batten-check clean.

---

Generated by Claude Code

[sonarqubecloud]

❌ The last analysis has failed.

See analysis details on SonarQube Cloud

[wenzowski]

/fast-forward