@sabaiway/agent-workflow-kit 5.2.0 → 5.4.0

package/tools/doc-parity.mjs

@@ -33,6 +33,8 @@ import {
   ACKS_FILE,
 } from './recommendations.mjs';
 import { SKIPPED_READONLY } from './setup-backends.mjs';
+// The host-conditional qualifier every settings-derived runtime claim carries (Decision 11).
+import { HOST_HONORS_QUALIFIER } from './velocity-profile.mjs';
 import { LATENT_ARM_NOTICE } from './review-state.mjs';
 import { QUEUE_SHARED_RULE, LANDING_FROM_MAIN, NO_DEPENDENCIES_POSTURE, CLEANUP_OWNERSHIP_RULE, INCLUDE_IDENTITY_RULE, RESUME_VERIFY_RULE } from './worktrees.mjs';
 // The flow contract constants: the accepted schema version + the honest lagging-kit sentence
@@ -42,6 +44,8 @@ import { FLOW_SCHEMA_VERSION, FLOW_LAGGING_KIT_CONTRACT } from './orchestration-
 import { FLOW_BOOKKEEPING_FLOOR_RESIDUAL } from './set-flow.mjs';
 import { FLOW_ARMED_HALVES_HEADER } from './procedures.mjs';
 import { RECEIPT_DEADLINE_CONTRACT } from './receipt-deadline.mjs';
+// The coverage vocabulary leaf: a CLOSED value set the gates contract doc must enumerate.
+import { COVERAGE } from './coverage-state.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -55,6 +59,7 @@ const WORKTREES_DOC = 'references/modes/worktrees.md';
 const PROCEDURES_DOC = 'references/modes/procedures.md';
 const SET_FLOW_DOC = 'references/modes/set-flow.md';
 const RECEIPT_DEADLINE_DOC = 'references/modes/receipt-deadline.md';
+const GATES_DOC = 'references/modes/gates.md';
 
 // A typed usage failure (exit 2) for the CLI parser — the codebase's typed-error idiom (no classes).
 const usageFail = (message) => Object.assign(new Error(message), { exitCode: 2 });
@@ -99,6 +104,11 @@ export const BINDINGS = Object.freeze([
   // (the incident's "mode-doc apply text stays in lockstep" acceptance as a mechanism, not prose).
   // Bound in BOTH docs that name the path (recommendations.md + velocity.md).
   valueBinding('acks-file', ACKS_FILE, ACKS_FILE, [RECOMMENDATIONS_DOC, VELOCITY_DOC]),
+  // The host-conditional qualifier (Decision 11): the tier notice, the USAGE text and the autonomy
+  // render all state a settings key's RUNTIME effect through this one phrase, so the mode doc that
+  // documents those surfaces must carry it too — a reworded doc that quietly re-promises the effect
+  // fails here instead of shipping.
+  valueBinding('host-honors-qualifier', HOST_HONORS_QUALIFIER, HOST_HONORS_QUALIFIER, [VELOCITY_DOC]),
   // The refresh read-only degrade outcome (REFRESH-EROFS-HONESTY / AD-056): the new skipped-readonly
   // token must render in BOTH mode contracts that enumerate the placed-bridge refresh outcomes
   // (setup.md owns --refresh-placed; upgrade.md pastes its lines) — a reworded doc dropping the
@@ -142,6 +152,10 @@ export const BINDINGS = Object.freeze([
   // satisfaction — is the tool's identity; a mode doc silently drifting off it would re-open the
   // #50 misclassification this runner exists to close.
   valueBinding('receipt-deadline-contract', RECEIPT_DEADLINE_CONTRACT, RECEIPT_DEADLINE_CONTRACT, [RECEIPT_DEADLINE_DOC]),
+  // The runner's `coverage=` summary vocabulary (Decision 8): the gates contract doc enumerates the
+  // CLOSED value set, so a renamed or added value fails here instead of leaving the doc describing
+  // a vocabulary the runner no longer speaks. One binding per value — the set is small and closed.
+  ...Object.values(COVERAGE).map((value) => valueBinding(`coverage-state:${value}`, value, `\`coverage=${value}\``, [GATES_DOC])),
 ].map((b) => Object.freeze(b)));
 
 // ── the pure checker (readText is injectable for hermetic tests) ────────────────────────
@@ -187,12 +201,13 @@ Usage:
 
 A CLOSED, exported registry binds each live code constant — the autonomy-doctor contract (the EXIT
 table, the status tokens, the trusted-dir allowlist), the recommendations/upgrade presentation
-contract (section header, empty line, verdict templates), the acks-store path, the setup refresh
-degrade token, the review-state clean-tree latent-arm notice, the worktrees provision-record
+contract (section header, empty line, verdict templates), the acks-store path, the host-conditional
+qualifier every settings-derived runtime claim carries, the setup refresh degrade token, the review-state clean-tree latent-arm notice, the worktrees provision-record
 orientation contract (shared-queue rule, landing-from-main, no-dependencies install posture), the
 worktrees cleanup-ownership rule, the worktrees include-identity rule, the worktrees
-resume-verify rule, and the flow tolerate contract (the accepted flow schema version + the
-lagging-kit sentence, procedures.md) — to
+resume-verify rule, the flow tolerate contract (the accepted flow schema version + the
+lagging-kit sentence, procedures.md), and the runner's closed coverage= summary vocabulary
+(gates.md) — to
 the exact token its references/modes/*.md contract must carry, and
 asserts the CURRENT value renders into every bound file. A drifted doc, an unreadable bound file,
 or an absent token FAILS CLOSED.

package/tools/flow-check.mjs

@@ -281,7 +281,33 @@ export const evaluateVetoOverride = ({ records, vetoReceipt, tree }) => {
 // and their records remain forgeable (each store's own header says so) — a backdated or
 // backwards-clock instant can move a red across this boundary; the cross-store arming-fence
 // hardening is queued (FLOW-ARMING-FENCE-CROSS-STORE), never pretended here.
-export const collectUnansweredRedRefusals = ({ flowRecords, coreRecords, currentBase, owner }) => {
+//
+// The lane split (FLOW-FINAL-RED-DEADLOCK) — the same reasoning the D10 arm already applies one arm
+// away (see the `consumer` paragraph in computeFlowDecision's own header; a line reference there
+// would rot on the next insertion). The strict rule demands a receipt the gate's OWN run has not
+// written yet: run-gates appends the final receipt only AFTER every gate has run, so an in-matrix
+// flow-check can never see the completed retry that would answer the newest red, and each --final
+// mints red N+1 — no number of rerun-causes converges. On the 'gate' lane a current-base red is
+// therefore ALSO answered by a provable IN-PROGRESS retry: an authoritative rerun-cause naming its
+// attempt AND binding the CURRENT fingerprint, plus a final-start at that fingerprint ordered
+// STRICTLY AFTER that red whose attempt carries no completed final — the shape run-gates creates
+// before any gate runs (run-gates.mjs:636-658), so inside a real final run the conjunction holds by
+// construction while a standalone check on a quiet tree still refuses. The relaxation carries the
+// SAME base correlation the strict rule demands of the retry tree: a fingerprint is not unique to a
+// base (a clean tree hashes identically under every HEAD), so without it a cause minted at another
+// base would answer the gate and leave a green final the commit boundary is guaranteed to reject —
+// the relaxation must only ever admit a state a completed retry could actually clear. It is opt-in
+// by EXACT match: any other consumer — unknown, misspelled, absent — evaluates the strict rule, and
+// a tree whose fingerprint is unresolvable or ambiguously correlated never relaxes. The
+// 'commit-guard' lane is unchanged; the commit boundary still demands a real completed retry.
+// Stated residual: an INTERRUPTED final run leaves exactly that record shape with no live run
+// behind it, so a standalone check reads PASS in that window. It authorizes nothing — commit-guard
+// refuses the dangling start independently (commit-guard.mjs:213-223) and consults the STRICT lane
+// (commit-guard.mjs:253) — and the window closes on the next completed final run. The real fix is a
+// runner-attested capability (a one-time unpublished nonce over stdin or an inherited FD, verified
+// against a one-way commitment recorded in the final-start); it needs its own IPC contract and is
+// QUEUED, never pretended here.
+export const collectUnansweredRedRefusals = ({ flowRecords, coreRecords, currentBase, owner, consumer = 'commit-guard', currentFingerprint = null }) => {
   if (!hasOwnAdoption(flowRecords, owner)) return [];
   const adoptionInstants = flowRecords
     .filter((r) => r.kind === CHAIN_KIND && r.purpose === 'adoption' && r.owner === owner)
@@ -302,6 +328,13 @@ export const collectUnansweredRedRefusals = ({ flowRecords, coreRecords, current
       && basesAt(g.fingerprintBefore).length === 1 && basesAt(g.fingerprintBefore)[0] === currentBase
       && firstFinalByAttempt.get(g.attempt) === gi
       && c.fingerprint === g.fingerprintBefore));
+  const completedAttempts = new Set(finals.map(({ r }) => r.attempt));
+  const relaxes = consumer === 'gate' && typeof currentFingerprint === 'string' && currentFingerprint !== ''
+    && basesAt(currentFingerprint).length === 1 && basesAt(currentFingerprint)[0] === currentBase;
+  const inProgressRetryFor = (red, redAt) => rerunCauses.some((c) => c.attempt === red.attempt
+    && c.fingerprint === currentFingerprint
+    && coreRecords.some((s, si) => si > redAt && s.kind === 'final-start'
+      && s.fingerprint === currentFingerprint && !completedAttempts.has(s.attempt)));
   for (const { r, i } of finals) {
     if (r.status !== 'red') continue;
     if (armingInstant !== null && isCanonicalInstant(r.timestamp) && Date.parse(r.timestamp) < armingInstant) continue;
@@ -315,7 +348,7 @@ export const collectUnansweredRedRefusals = ({ flowRecords, coreRecords, current
       continue;
     }
     if (bases[0] !== currentBase) continue;
-    if (!answeredBy(r, i)) {
+    if (!answeredBy(r, i) && !(relaxes && inProgressRetryFor(r, i))) {
       refusals.push(`a red final (attempt "${r.attempt}") on the CURRENT base (${bases[0] == null ? 'null' : short(bases[0])}) has no later completed retry cleared by a rerun-cause — an unanswered red never passes an armed flow (#65). recovery (edit the quoted cause, then paste; mint on the RETRY tree): ${writerCommand(`rerun-cause --attempt=${shellQuote(r.attempt)} --cause='<the stated cause>'`)}`);
     }
   }
@@ -568,13 +601,14 @@ export const computeAllPathWorktreeSurface = (cwd) => {
   return { ok: true, paths: [...new Set([...tracked, ...untracked])] };
 };
 
-// decideFlowCheck({ flowRead, coreRead, owner, motion?, evidence? }) → { refusals, advisories }.
-// Pure — consumes the FULL read-results of both stores; store health fails closed BEFORE any
-// content judgment. `motion` ({ currentBase, resolveBaseDelta, resolveChangedSurface }) arms the
-// Step-1.4 base-motion refusals; `evidence` ({ receipts, tree, backends }) arms the three Phase-1
-// rungs (#65/#25/#42 — each self-gates on an OWN adoption). Absent inputs keep the decision
-// byte-identical to the Plan-2 checker.
-export const decideFlowCheck = ({ flowRead, coreRead, owner, flowPath = 'the flow store', corePath = 'the core evidence store', motion = null, evidence = null }) => {
+// decideFlowCheck({ flowRead, coreRead, owner, motion?, evidence?, consumer? }) → { refusals,
+// advisories }. Pure — consumes the FULL read-results of both stores; store health fails closed
+// BEFORE any content judgment. `motion` ({ currentBase, resolveBaseDelta, resolveChangedSurface })
+// arms the Step-1.4 base-motion refusals; `evidence` ({ receipts, tree, backends }) arms the three
+// Phase-1 rungs (#65/#25/#42 — each self-gates on an OWN adoption). Absent inputs keep the decision
+// byte-identical to the Plan-2 checker. `consumer` rides through to the #65 lane split and defaults
+// to the STRICT lane, so a caller that forgets to thread it inherits strictness.
+export const decideFlowCheck = ({ flowRead, coreRead, owner, flowPath = 'the flow store', corePath = 'the core evidence store', motion = null, evidence = null, consumer = 'commit-guard' }) => {
   const refusals = [];
   const advisories = [];
   if (flowRead.readError) refusals.push(`the flow store is unreadable (${flowRead.readError}) — the checker consumes the FULL read-result; inspect ${flowPath} (fail closed)`);
@@ -594,7 +628,7 @@ export const decideFlowCheck = ({ flowRead, coreRead, owner, flowPath = 'the flo
   refusals.push(...deltaRefusals(records, owner));
   refusals.push(...degradeOrderingRefusals(coreRead.records));
   if (evidence != null) {
-    refusals.push(...collectUnansweredRedRefusals({ flowRecords: records, coreRecords: coreRead.records, currentBase: evidence.tree.base, owner }));
+    refusals.push(...collectUnansweredRedRefusals({ flowRecords: records, coreRecords: coreRead.records, currentBase: evidence.tree.base, owner, consumer, currentFingerprint: evidence.tree.fingerprint }));
     refusals.push(...collectDegradeCoverageRefusals({ flowRecords: records, coreRecords: coreRead.records, tree: evidence.tree, owner, backends: evidence.degradeBackends }));
     refusals.push(...collectReceiptCoverageRefusals({ flowRecords: records, receipts: evidence.receipts, tree: evidence.tree, owner, backends: evidence.receiptBackends, declaredPaths: evidence.declaredPaths, refreshCap: evidence.refreshCap }));
   }
@@ -611,7 +645,9 @@ export const decideFlowCheck = ({ flowRead, coreRead, owner, flowPath = 'the flo
 // #42 never falls open). `consumer` (Plan 4 Decision 2): the D10 flow→final comparison runs ONLY
 // on the 'commit-guard' lane — the default 'gate' lane (the in-matrix flow-check --check gate)
 // stays inert on it, because during a final run the "latest final" is by construction the
-// PREVIOUS one and an in-matrix comparison would make a new green final unreachable.
+// PREVIOUS one and an in-matrix comparison would make a new green final unreachable. The SAME
+// distinction reaches the #65 unanswered-red rung (its own header states the split): the 'gate'
+// lane also answers a red under a provable in-progress retry, for the same reason.
 export const computeFlowDecision = ({ cwd = process.cwd(), consumer = 'gate', probes = {} } = {}) => {
   const fingerprintProbe = probes.fingerprint ?? computeTreeFingerprint;
   const owner = deriveFlowOwner(cwd);
@@ -745,7 +781,7 @@ export const computeFlowDecision = ({ cwd = process.cwd(), consumer = 'gate', pr
       }
     }
   }
-  const { refusals, advisories } = decideFlowCheck({ flowRead, coreRead, owner, flowPath, corePath, motion, evidence });
+  const { refusals, advisories } = decideFlowCheck({ flowRead, coreRead, owner, flowPath, corePath, motion, evidence, consumer });
   // Semantic refusals bind only an ARMED store; the D10 binding refusals ride the commit-guard
   // lane UNCONDITIONALLY — a deleted or truncated store must never un-arm the binding.
   const effectiveRefusals = healthBroken ? refusals : [...(armed ? [...refusals, ...evidenceRefusals] : []), ...bindingRefusals];

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/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,