@sabaiway/agent-workflow-kit 5.3.0 → 5.5.0

package/tools/gates-declaration.mjs

@@ -10,6 +10,7 @@ import { readFileSync, lstatSync, realpathSync } from 'node:fs';
 import { join, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { fail, loadConfig, CONFIG_REL } from './orchestration-config.mjs';
+import { matchesCoverageProducer } from './coverage-producer.mjs';
 
 // The per-project declaration (strict JSON, hand-editable). cwd-relative — errors show a path the
 // user can open (the orchestration-config CONFIG_REL idiom).
@@ -140,6 +141,54 @@ export const isFinalCapableDeclaration = (gates, projectDir) => {
   return matchesCanonicalCheck(FINAL_CORE_CHECKS[1], gates[gates.length - 1].cmd, projectDir);
 };
 
+// coverageProducerPrecedes(gates, checkerIndex) → whether a producer runs BEFORE the checker at that
+// index. ORDER is the whole question: a producer declared AFTER the checker writes the lcov too late,
+// so the checker reads nothing — or, worse, stale bytes an earlier run left behind — and still
+// passes. ONE home for the rule: the written-declaration defects below and the advisor's
+// inert-declaration item both decide through it, so they cannot drift apart.
+export const coverageProducerPrecedes = (gates, checkerIndex) =>
+  gates.slice(0, checkerIndex).some((gate) => matchesCoverageProducer(gate.cmd));
+
+// coverageDeclarationDefects(gates, projectDir) → the WRITTEN-declaration coverage rule, as a list
+// of named defects (empty = satisfied): at most ONE canonical coverage checker; if one is present
+// it is LAST, and a producer precedes it. Consumers turn a defect into their own refusal — an
+// offer-level check alone is not enough, because the declaration that gets WRITTEN is a merge of an
+// existing file with a consented subset, and every one of these three shapes is reachable that way.
+// Order is deliberate: a duplicate must be resolved before order or production can even be read.
+export const coverageDeclarationDefects = (gates, projectDir) => {
+  const checkers = canonicalCheckerGates(gates, projectDir);
+  if (checkers.length > 1) {
+    return [{
+      kind: 'duplicate-checker',
+      message:
+        `${GATES_REL}: ${checkers.length} gates are the canonical coverage checker (${checkers.map((g) => g.id).join(', ')}) — ` +
+        '--final accepts exactly one; keep a single checker and remove the rest',
+    }];
+  }
+  if (checkers.length === 0) return []; // no checker declared — coverage is optional, nothing to enforce
+  const index = gates.indexOf(checkers[0]);
+  const after = gates.slice(index + 1);
+  if (after.length > 0) {
+    return [{
+      kind: 'checker-not-last',
+      message:
+        `${GATES_REL}: the canonical coverage checker (${checkers[0].id}) must be the LAST declared gate — ` +
+        `${after.map((g) => g.id).join(', ')} would run after it consumed the lcov. REORDER the declaration by hand ` +
+        '(the gate itself is fine — this is an ORDERING refusal, and the fill is append-only, so it cannot reorder for you)',
+    }];
+  }
+  if (!coverageProducerPrecedes(gates, index)) {
+    return [{
+      kind: 'no-producer',
+      message:
+        `${GATES_REL}: the canonical coverage checker (${checkers[0].id}) is declared but NO gate would produce the lcov it reads — ` +
+        'the checker would pass while verifying nothing. Declare a suite gate carrying the coverage reporters ' +
+        '(references/modes/gates.md names the exact form), or drop the checker',
+    }];
+  }
+  return [];
+};
+
 // The review-dependent predicate (#66/P14): a gate is review-dependent iff its cmd IS the plain
 // canonical `--check` invocation of one of the kit's OWN checkers, resolved by realpath — never a
 // project-authored id. A project abstracting the invocation behind its own script declares it in

package/tools/gates-init.mjs

@@ -30,6 +30,12 @@
 //   • the safety claim is scoped to the OFFER DERIVATION, not a runtime sandbox: a gate still
 //     executes project-controlled tooling (a node_modules/.bin PATH shim intercepts under every
 //     form) — the documented residual, disclosed in the preview, bounded by the two consents;
+//   • a `node --test` suite body — the ONE allowlist member that produces lcov unaided — is
+//     emitted WITH the canonical coverage reporters, so the offered checker has a producer; every
+//     other body is emitted verbatim. The coverage-check candidate is WITHHELD (loud note) when
+//     neither the offer nor the existing declaration carries a producer, and --apply refuses to
+//     WRITE a declaration whose checker has no producer, is not last, or has a canonical twin:
+//     the checker READS an lcov, and with nothing writing it the gate passes certifying nothing;
 //   • ids derive kebab-case from script names (build:prod → build-prod) and every offered entry
 //     passes the runner's validateDeclaration (this module imports the validator — NEVER the
 //     reverse: run-gates.mjs stays a runner that writes nothing);
@@ -54,6 +60,8 @@ import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { discoverGateCandidates, EXPECTED_WORKFLOW_VERSION } from './velocity-profile.mjs';
 import { GATES_REL, validateDeclaration } from './run-gates.mjs';
+import { coverageDeclarationDefects, isReviewDependentGate } from './gates-declaration.mjs';
+import { COVERAGE_PRODUCER_BODY, matchesCoverageProducer } from './coverage-producer.mjs';
 import { loadConfig } from './orchestration-config.mjs';
 import { assertDocsAiDeployment, writeDocsAiFileAtomic, lstatNoFollow } from './atomic-write.mjs';
 
@@ -95,7 +103,10 @@ never watch/serve, never a write-mode variant) whose BODY is a member of the lit
 allowlist is offered, as the hook-free \`COREPACK_ENABLE_NETWORK=0 <pm> exec -- <body>\` form for
 the detected package manager. A gate-class script whose body is NOT in the allowlist is screened
 out with a note naming it (a command you trust can still be declared by hand); non-gate-class
-names are excluded silently, as always.
+names are excluded silently, as always. A \`node --test\` body carries the canonical coverage
+reporters; the coverage-check candidate is withheld when nothing would produce the lcov it reads,
+and --apply refuses to write a checker with no producer, a checker that is not last, or a second
+canonical checker.
 ${TRUST_CHAIN_DISCLOSURE}`;
 
 // ── candidate classification: the NAME screens (the LOCKED derivation invariants) ──────
@@ -195,6 +206,13 @@ export const execCmdFor = (pm, body) => {
   };
 };
 
+// The coverage PRODUCER wiring (Decision 1 — closed-world here too). `node --test` is the only
+// allowlist body that produces lcov with no extra dependency, so it is the only body the offer
+// extends with the reporter flags; every other body is emitted verbatim and produces none (an
+// optional-dependency coverage flag set would be speculation about the project's own tooling).
+const COVERAGE_PRODUCING_BODY = 'node --test';
+const emittedBodyOf = (body) => (body === COVERAGE_PRODUCING_BODY ? COVERAGE_PRODUCER_BODY : body);
+
 export const kebabIdOf = (name) =>
   String(name)
     .toLowerCase()
@@ -253,12 +271,14 @@ const deriveScripts = (cwd, deps = {}) => {
       screenedIds.push(id);
       continue;
     }
-    const { cmd, note } = execCmdFor(pm, body);
+    const emitted = emittedBodyOf(body);
+    const { cmd, note } = execCmdFor(pm, emitted);
     if (cmd === null) {
       withheld.push({ id, note });
       continue;
     }
-    entries.push({ id, title: `Project script ${c.scriptName}: ${body}`, cmd });
+    const coverage = emitted === body ? '' : ' (+ the lcov reporters the coverage checker reads)';
+    entries.push({ id, title: `Project script ${c.scriptName}: ${body}${coverage}`, cmd });
   }
   const notes = [];
   if (screenedIds.length) {
@@ -397,7 +417,10 @@ const assertOnlyIdsOffered = (offer, onlyIds = []) => {
   const offered = new Set(offer.entries.map((e) => e.id));
   const unknown = onlyIds.filter((id) => !offered.has(id));
   if (unknown.length) {
-    throw usageFail(`--only names ids not in the offer: ${unknown.join(', ')} (offered: ${[...offered].join(', ') || 'none'})`);
+    // The offer's notes carry WHY a candidate is absent (a withheld checker, a screened body); an
+    // id-not-offered error without them reads as a typo the user did not make.
+    const why = offer.notes.length ? ` — why: ${offer.notes.join(' | ')}` : '';
+    throw usageFail(`--only names ids not in the offer: ${unknown.join(', ')} (offered: ${[...offered].join(', ') || 'none'})${why}`);
   }
 };
 
@@ -411,10 +434,47 @@ export const buildOffer = (cwd, deps = {}) => {
   const rs = reviewStateCandidate(cwd, deps);
   const fc = flowCheckCandidate(cwd, deps);
   const cc = coverageCheckCandidate(cwd, deps);
-  const candidates = [rs.candidate, fc.candidate, cc.candidate].filter(Boolean);
+  // Decision 3 — the checker is never offered DEAD. The producer may come from this offer or from
+  // a declaration the user already wrote by hand, so the rule reads the merged picture; a
+  // declaration this preview cannot read degrades to a stated note, never to a silent withhold.
+  const existing = declaredGatesBestEffort(cwd, deps);
+  const producerPresent =
+    scripts.entries.some((entry) => matchesCoverageProducer(entry.cmd)) ||
+    existing.gates.some((gate) => matchesCoverageProducer(gate.cmd));
+  const withholdCoverage = cc.candidate !== null && !producerPresent;
+  const coverageNote = withholdCoverage
+    ? `the coverage-check candidate was withheld: nothing would PRODUCE the lcov it reads — no offered or ` +
+      `declared gate carries the canonical coverage reporters, and a checker with no producer passes while ` +
+      `verifying nothing (declare a suite gate per references/modes/gates.md, then re-run)`
+    : cc.note;
+  // ALWAYS stated, not only when it changed the withhold: the preview would otherwise promise an
+  // applicable offer over a declaration --apply is certain to refuse.
+  const unreadableNote =
+    existing.unreadable === null
+      ? null
+      : `the existing ${GATES_REL} could not be read (${existing.unreadable}) — this preview treated it as EMPTY, and --apply will refuse until it is fixed`;
+  // An offer that lists nothing but the kit's own checkers reads like a clean offer; say the
+  // consequence out loud (no command bodies are echoed — an unvetted body must never become one
+  // keystroke from a declared, hook-auto-approvable gate). The offer-level fact is ALWAYS true; the
+  // matrix claim and the advice are only true in ONE of three declaration states, and asserting
+  // them in the other two would be the same false report this seam exists to remove:
+  //   unreadable          → the empty gates array means UNPARSED, not undeclared: say nothing more;
+  //   readable, no gate   → the claim and the advice both hold;
+  //   readable, has gate  → a green matrix proves plenty and the user already declared their own.
+  const declarationState =
+    existing.unreadable !== null ? 'unreadable' : existing.gates.some((gate) => !isReviewDependentGate(gate, cwd)) ? 'has-gate' : 'no-gate';
+  const noVerificationNote =
+    scripts.entries.length > 0
+      ? null
+      : `this offer adds no project-verification gate — nothing here runs your suite, linter or build${
+          declarationState === 'no-gate'
+            ? `, and none is declared either, so a green matrix would prove only that the kit's own checkers ran; declare your own in ${GATES_REL}`
+            : ''
+        }`;
+  const candidates = [rs.candidate, fc.candidate, withholdCoverage ? null : cc.candidate].filter(Boolean);
   return {
     entries: [...scripts.entries, ...candidates],
-    notes: [...scripts.notes, rs.note, fc.note, cc.note].filter(Boolean),
+    notes: [...scripts.notes, noVerificationNote, unreadableNote, rs.note, fc.note, coverageNote].filter(Boolean),
   };
 };
 
@@ -479,6 +539,18 @@ const loadExistingDeclaration = (cwd, deps = {}) => {
   return { outcome: 'loaded', readme: typeof parsed._README === 'string' ? parsed._README : undefined, gates };
 };
 
+// The declaration as the OFFER sees it: read-only and non-fatal. The preview must survive a
+// declaration --apply would refuse (missing, malformed, symlinked) — it just reports what it could
+// not read, so the withhold is never blamed on the wrong cause.
+const declaredGatesBestEffort = (cwd, deps = {}) => {
+  try {
+    const existing = loadExistingDeclaration(cwd, deps);
+    return { gates: existing.outcome === 'loaded' ? existing.gates : [], unreadable: null };
+  } catch (err) {
+    return { gates: [], unreadable: err?.message ?? String(err) };
+  }
+};
+
 const templateReadme = (deps = {}) => {
   const read = deps.readTemplate ?? readFileSync;
   try {
@@ -531,6 +603,11 @@ export const applyFill = ({ cwd, onlyIds = [] }, deps = {}) => {
     gates: [...existingGates, ...selected],
   };
   validateDeclaration(merged); // every written declaration passes the runner's validator, always
+  // Decision 4 — the coverage invariant is enforced on the declaration that GETS WRITTEN, not on
+  // the offer: --only filters, the merge appends, and each of those still reaches a dead pair, a
+  // producer landing after an already-last checker, or a second checker under another id.
+  const defects = coverageDeclarationDefects(merged.gates, cwd);
+  if (defects.length) throw stop(`${defects[0].message} — nothing was written`);
   const body = `${JSON.stringify(merged, null, 2)}\n`;
   const { writtenPath } = writeDocsAiFileAtomic(cwd, GATES_REL, body, deps, { stop, noun: 'a gate declaration' });
   return { outcome: 'written', writtenPath, appended: selected.map((e) => e.id), notes: offer.notes };

package/tools/receipt-deadline.mjs

@@ -5,7 +5,9 @@
 // ARRIVAL: a newline-terminated parseable receipt line from the dispatched backend starting
 // at/after the watermark offset, or — PREFERRED whenever a dispatch nonce is supplied and its
 // finding manifest exists — the nonce-matched manifest (the manifest is minted atomically BEFORE
-// the receipt append, so its presence is the stronger dispatch-identity signal).
+// the receipt append, so its presence is the stronger dispatch-identity signal). "Receipt line" is
+// decided POSITIVELY, by the minimal core below: a delegation-ledger line carries a `backend` too,
+// and a review waiter waits for a REVIEW answer (D10).
 //
 // Watermark semantics (P6/P18, split by surface): the PERSISTED dispatch-ledger watermark stays
 // the plain byte-length integer; THIS RUNNER additionally binds the receipts-file PREFIX
@@ -32,10 +34,30 @@ export const DEADLINE_POLL_MS = 5000;
 
 // The one contract sentence, doc-parity-bound into references/modes/receipt-deadline.md — the
 // arrival-not-satisfaction split is the tool's identity and must not drift in the mode doc.
-export const RECEIPT_DEADLINE_CONTRACT = 'satisfaction is receipt ARRIVAL past the watermark — a strictly-newer parseable receipt line from the dispatched backend (or its nonce-matched finding manifest, preferred when present) — never obligation satisfaction';
+export const RECEIPT_DEADLINE_CONTRACT = 'satisfaction is receipt ARRIVAL past the watermark — a strictly-newer parseable REVIEW receipt line from the dispatched backend (or its nonce-matched finding manifest, preferred when present), never a delegation-ledger line that merely names the same backend — never obligation satisfaction';
 
 const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
 
+// The receipts store and the delegation ledger are different files with different schemas, but both
+// are JSONL beside the git dir and both carry a `backend` — so a ledger line reaching this store
+// would satisfy a waiter that matched on the backend alone (D10). The rule is therefore POSITIVE,
+// not a blacklist of foreign kinds: a blacklist goes stale the moment the other family grows a kind,
+// and the two errors are not symmetric — an unrecognised line costs a TIMEOUT that names its
+// watermark (loud), while a false ARRIVED answers a review dispatch with something that is not a
+// review. This is the MINIMAL core every review receipt carries and no delegation record can: the
+// kinds that carry `backend` (dispatch, return) have no `verdict`, and the kind that carries
+// `verdict` (fold) has no `backend`. `fingerprint` must be PRESENT but may be null — an empty
+// fingerprint is legal in some receipt modes, so requiring a value would refuse a real receipt.
+const REVIEW_RECEIPT_SCHEMA = 1;
+
+const isReviewReceiptLine = (parsed, backend) =>
+  parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+  && parsed.schema === REVIEW_RECEIPT_SCHEMA
+  && parsed.backend === backend
+  && typeof parsed.artifact === 'string' && parsed.artifact.length > 0
+  && typeof parsed.verdict === 'string' && parsed.verdict.length > 0
+  && Object.hasOwn(parsed, 'fingerprint');
+
 // Every read rides the kit's ONE race-free reader (flow-store-read's no-follow/non-block
 // discipline): store identity is never resolved through a link, a FIFO can never block the
 // bounded wait, and an invalid-UTF-8 store refuses (a byte-unstable store cannot carry a prefix
@@ -97,7 +119,7 @@ export const pollArrival = ({ path, watermark, prefixHash, backend, nonce = null
     } catch {
       continue; // a malformed line never satisfies — and never masks a later valid one
     }
-    if (parsed && typeof parsed === 'object' && parsed.backend === backend) {
+    if (isReviewReceiptLine(parsed, backend)) {
       return { state: 'satisfied', reason: `a receipt line from backend "${backend}" arrived past watermark offset ${watermark} (${path})` };
     }
   }

package/tools/recommendations.mjs

@@ -33,7 +33,7 @@
 import { readFileSync, readdirSync, lstatSync, existsSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
-import { dirname, join, resolve, sep } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import {
   preflightVelocityProfile,
@@ -55,6 +55,10 @@ import { surveyFamily, surveyGateHook, surveyAdrLayoutStrict } from './family-re
 import { probeSandboxMasks, needsMasksApply } from './sandbox-masks.mjs';
 import { shellQuoteArg } from './review-state.mjs';
 import { isFinalCapableDeclaration } from './run-gates.mjs';
+import { loadDeclaration, canonicalCheckerGates, coverageProducerPrecedes, isReviewDependentGate, GATES_REL } from './gates-declaration.mjs';
+// The declared-path resolution + segment containment this item's convergence lane shares with the
+// autonomy render's allowWrite degrade — ONE leaf, so the two answers cannot drift.
+import { resolveDeclaredDir, dirCovers, isResolvableDeclaredEntry } from './declared-paths.mjs';
 import { resolveGitHooksPath } from './commit-guard.mjs';
 import { loadConfig } from './orchestration-config.mjs';
 import { DEFAULT_BUNDLE_ROOT } from './bridge-settings-read.mjs';
@@ -100,6 +104,8 @@ export const SEVERITIES = Object.freeze({
   'sandbox-provision': SEVERITY_OPTIONAL,
   'review-recipe': SEVERITY_ATTENTION,
   'gates-declaration': SEVERITY_OPTIONAL,
+  'gates-inert': SEVERITY_ATTENTION,
+  'gates-inert.no-verification': SEVERITY_ATTENTION,
   'gate-hook': SEVERITY_OPTIONAL,
   'commit-guard': SEVERITY_OPTIONAL,
   'read-lane': SEVERITY_OPTIONAL,
@@ -158,6 +164,8 @@ export const WHATS = Object.freeze({
   'sandbox-provision.installable': 'the OS sandbox is unavailable: {reason} — installable via the doctor (consent tuple {tuple})',
   'review-recipe': '{degraded}',
   'gates-declaration': 'no declared gate matrix (docs/ai/gates.json absent or empty) — gates prompt one by one; the apply PREVIEWS its --apply line, writes nothing',
+  'gates-inert': 'the declared coverage checker ({id}) has no producer before it — it certifies nothing this run, or reads a stale lcov',
+  'gates-inert.no-verification': "all {n} declared gate(s) are the kit's own checkers — the matrix runs no project-verification command",
   'gate-hook': '{n} declared gate(s) prompt per run — the gate-approval hook is not wired',
   'commit-guard': 'the gate matrix is final-run-capable but no commit-guard arms the pre-commit hook — a commit needs no green receipt yet',
   'read-lane': 'the gate hook is wired but the read-only compound lane is off — pipes/chains of seeded reads still prompt one by one',
@@ -214,6 +222,7 @@ export const BENEFITS = Object.freeze({
   'sandbox-provision': `velocity — confined ad-hoc commands stop prompting; ${DUAL_SECURITY_BENEFIT}`,
   'review-recipe': 'recipe coverage — the review AND execution recipes you configured actually run instead of silently degrading',
   'gates-declaration': 'velocity — your project’s gates run as ONE declared batch with a PASS/FAIL table',
+  'gates-inert': 'honest gates — the declared matrix verifies your project instead of reporting green over a check that ran nothing',
   'gate-hook': 'velocity — your own declared gate commands auto-approve byte-exactly (opt-in PreToolUse hook)',
   'commit-guard': 'integrity — commits require the ONE green --final receipt at the exact staged fingerprint (consented pre-commit arm)',
   'read-lane': 'velocity — pipes/chains of your seeded read-only commands auto-approve instead of prompting (opt-in, conservatively classified)',
@@ -250,6 +259,10 @@ export const OPT_IN_CAPABILITIES = Object.freeze([
   { id: 'autonomy-policy', mode: 'set-autonomy', advisorKey: 'autonomy-policy' },
   { id: 'sandbox-provision', mode: 'autonomy-doctor', advisorKey: 'sandbox-provision' },
   { id: 'gates-declaration', mode: 'gates', advisorKey: 'gates-declaration' },
+  // A DECLARED matrix that verifies nothing is its own capability: the gates-declaration offer
+  // converges the moment any gate exists, so it can never observe this state. The advisor key names
+  // the state it reports (an inert declaration), the capability names what the user gains.
+  { id: 'gates-verification', mode: 'gates', advisorKey: 'gates-inert' },
   { id: 'gate-hook', mode: 'hook', advisorKey: 'gate-hook' },
   { id: 'read-lane', mode: 'hook', advisorKey: 'read-lane' },
   { id: 'commit-guard', mode: 'commit-guard', advisorKey: 'commit-guard' },
@@ -412,6 +425,52 @@ const probeGates = ({ root, deps, add, skip }) => {
   }
 };
 
+// The INERT-DECLARATION item: a gate matrix that is declared, runs green, and verifies nothing.
+// Both causes are read off the DECLARATION through the same predicates the runner and the fill
+// decide with — the checker side through canonicalCheckerGates, the producer side through the
+// closed matchesCoverageProducer — so the advisor can never disagree with what --final accepts.
+//
+// Cause A (a canonical coverage checker with no producer anywhere in the declaration) is checked
+// FIRST and reported alone: its remedy — declaring the producer — also resolves cause B, because a
+// producer gate is not a kit checker. Its apply is HAND-APPLY: the producer must precede the
+// checker, and the fill is append-only (it refuses by name rather than reordering), so the edit is
+// the maintainer's.
+//
+// An ABSENT or EMPTY declaration belongs to the gates-declaration item; a malformed one throws out
+// of the validated reader and becomes this probe's stated skip, never a guess.
+export const probeGatesInert = ({ root, deps, add, skip }) => {
+  try {
+    const declaration = loadDeclaration(root, deps);
+    if (declaration.outcome === 'missing') return;
+    const gates = declaration.gates;
+    if (gates.length === 0) return;
+    const checkers = canonicalCheckerGates(gates, root);
+    if (checkers.length > 0) {
+      // ORDER decides, through the declaration's own shared predicate: a producer declared AFTER the
+      // checker leaves it just as inert as no producer at all (it reads nothing, or stale bytes), and
+      // only --final refuses that shape — a plain run reports every gate PASS.
+      if (coverageProducerPrecedes(gates, gates.indexOf(checkers[0]))) return; // the pair is live
+      const id = truncatedTo(oneLineOf(checkers[0].id), templateBudget(WHATS['gates-inert']));
+      add(
+        'gates-inert',
+        fillTemplate(WHATS['gates-inert'], { id }),
+        `HAND-APPLY: declare or MOVE a suite gate carrying the coverage reporters BEFORE ${id} in ${GATES_REL} (references/modes/gates.md names the exact form), or drop ${id} — the fill is append-only and cannot reorder for you`,
+      );
+      return;
+    }
+    if (gates.every((gate) => isReviewDependentGate(gate, root))) {
+      add(
+        'gates-inert',
+        fillTemplate(WHATS['gates-inert.no-verification'], { n: gates.length }),
+        `node ${q(toolPath('gates-init.mjs'))} --cwd ${q(root)}`,
+        'gates-inert.no-verification',
+      );
+    }
+  } catch (err) {
+    skip('gates-inert', err);
+  }
+};
+
 // The D10 consumer surface: once the declaration is FINAL-capable (the canonical core checks
 // present, the checker LAST — the run-gates helper is the one home of that rule), offer the
 // consented commit-guard install — for a MANAGED guardless pre-commit hook AND for an absent one
@@ -792,7 +851,7 @@ const readReadLaneToggle = (root, deps) => {
 // D3: the risk-marked keys — every key here has a per-item posture note in the mode doc, surfaced
 // at the consent moment; the static contract test asserts EXACT bidirectional coverage
 // (risk-marked keys == mode-doc note keys — a dropped note goes red, not silent).
-export const RISK_NOTED_KEYS = Object.freeze(['sandbox-lane', 'read-lane', 'worktrees-dir', 'adr-store-migration']);
+export const RISK_NOTED_KEYS = Object.freeze(['sandbox-lane', 'read-lane', 'worktrees-dir', 'adr-store-migration', 'gates-inert']);
 
 const probeSandboxLane = ({ root, deps, add, skip }) => {
   try {
@@ -849,22 +908,6 @@ const probeSandboxLane = ({ root, deps, add, skip }) => {
   }
 };
 
-// A declared `sandbox.filesystem.allowWrite` entry, resolved the way a host that honors the key
-// resolves it: `~` and `~/…` against the resolved home, every other form against the project root.
-const resolveDeclaredDir = (entry, { home, root }) => {
-  if (entry === '~') return resolve(home);
-  if (entry.startsWith('~/')) return resolve(home, entry.slice(2));
-  return resolve(root, entry);
-};
-
-// Ancestor-or-equal containment on PATH SEGMENTS, never a raw string prefix — a grant on
-// `<p>/farm` must never read as a grant on the sibling `<p>/farmhouse`. A grant on a DESCENDANT
-// never covers its parent: the parent dir is the one provision writes into.
-const dirCovers = (declaredDir, probeDir) => {
-  const base = declaredDir.endsWith(sep) ? declaredDir.slice(0, -sep.length) : declaredDir;
-  return probeDir === base || probeDir.startsWith(`${base}${sep}`);
-};
-
 // D7 lane 1 — the DECLARATION confirmation. A settings entry is not proof of writable CAPABILITY
 // (runtime truth stays with the provision preflight's real create+delete probe); it is proof the
 // maintainer applied this item's own advice, which is what the item may converge on. Both scopes
@@ -899,7 +942,7 @@ const declaredWritableDirs = (scope, rel) => {
   if (filesystem === null || typeof filesystem !== 'object' || Array.isArray(filesystem)) return [];
   const { allowWrite } = filesystem;
   if (allowWrite === undefined) return [];
-  if (!Array.isArray(allowWrite) || !allowWrite.every((entry) => typeof entry === 'string' && entry.trim() !== '')) {
+  if (!Array.isArray(allowWrite) || !allowWrite.every(isResolvableDeclaredEntry)) {
     throw new Error(`${rel}: sandbox.filesystem.allowWrite must be an array of non-empty strings`);
   }
   return allowWrite;
@@ -1010,6 +1053,7 @@ const PROBES = Object.freeze([
   probeSandboxProvision,
   probeReviewRecipe,
   probeGates,
+  probeGatesInert,
   probeCommitGuard,
   probeReadLane,
   probeStateBlockHook,

package/tools/release-scan.mjs

@@ -35,11 +35,44 @@ const ATTRIBUTION = [
   { re: /reviewed by (claude|codex|chatgpt|gpt|gemini|copilot|cursor|the (ai|model|agent))/i, label: 'AI review attribution' },
   { re: /authored[- ]by[: ][^\n]{0,40}\b(claude|chatgpt|gemini|copilot)\b/i, label: 'AI authorship attribution' },
 ];
+// A line whose FIRST non-space token opens a comment (or a markdown heading) — the surface where a
+// backend name beside a disposition is a credit rather than a data value.
+//
+// STATED RESIDUAL of the two anchored rules below, named rather than implied: they see only lines
+// that OPEN with a comment marker, so a credit inside a string literal, in ordinary markdown prose
+// outside a heading, or in a trailing inline comment is invisible to them. Closing that class needs
+// a code/comment/string lexer this scanner deliberately does not have (the version-pin rung below
+// records what hand-rolling one cost). The UNANCHORED pair narrows the gap for the one construction
+// that has actually shipped past this gate; nothing here proves no attribution exists — it is a
+// high-signal guard, not a proof.
+const COMMENT_LINE = String.raw`^\s*(?://|/\*|\*|#)`;
+const DISPOSITIONS = 'CONFIRM|REFUTE|REVISE|SHIP';
+// Spelled per letter rather than flagged: the four rules below must be case-insensitive on the NAME
+// and case-SENSITIVE on the disposition, and a regex flag cannot apply to half a pattern. All four
+// share this constant, so an ALL-CAPS credit cannot slip past one of them.
+const BACKEND_ANY_CASE = '[Aa][Gg][Yy]|[Cc][Oo][Dd][Ee][Xx]';
+
 const REVIEWER_IDENTITY = [
   // backend-then-round: a bridge name, a separator, then r<N> (with optional +/round suffixes).
   { re: /\b(?:agy|codex)(?:\s+|-)r\d+(?:(?:\+|\/)r?\d+)*(?:-[a-z0-9]+)*\b/i, label: 'reviewer-round identity' },
   // round-then-backend (reverse order): r<N>, a separator, then a bridge name — the release-review gap.
   { re: /\br\d+(?:\s+|-)(?:agy|codex)\b/i, label: 'reviewer-round identity' },
+  // backend beside a DISPOSITION, in a COMMENT: the form a fold note takes when it credits who
+  // decided instead of stating what was decided. Two narrowings make it usable. The line must be a
+  // comment, because a receipt FIXTURE legitimately pairs a backend field with a verdict value and
+  // that is data, not attribution. And the disposition half is case-SENSITIVE, because prose says
+  // "ship" and "revise" constantly while a recorded disposition is written in caps.
+  { re: new RegExp(`${COMMENT_LINE}[^\\n]*\\b(?:${BACKEND_ANY_CASE})\\b[^\\n]{0,24}\\b(?:${DISPOSITIONS})\\b`), label: 'reviewer-round identity' },
+  { re: new RegExp(`${COMMENT_LINE}[^\\n]*\\b(?:${DISPOSITIONS})\\b[^\\n]{0,24}\\b(?:${BACKEND_ANY_CASE})\\b`), label: 'reviewer-round identity' },
+  // The exact PARENTHESISED credit — an open paren, a bridge name, a comma, a disposition, and the
+  // reverse order — matched ANYWHERE on the line, so it also lands inside a string literal, a
+  // markdown sentence and a trailing inline comment, none of which the comment anchor above can
+  // see. It stays clear of data because a fixture QUOTES its values, and a quote sits exactly where
+  // this rule requires the bare disposition word. Both orders END on a word boundary, so a longer
+  // word sharing a disposition's prefix is not a credit — the boundary is what a commit gate needs,
+  // and requiring the CLOSING paren instead would drop the hyphenated form this rule exists for.
+  { re: new RegExp(`\\((?:${BACKEND_ANY_CASE}),\\s*(?:${DISPOSITIONS})\\b`), label: 'reviewer-round identity' },
+  { re: new RegExp(`\\((?:${DISPOSITIONS}),\\s*(?:${BACKEND_ANY_CASE})\\b`), label: 'reviewer-round identity' },
 ];
 
 const allowlistCovers = (matched, allowlist) =>