@sabaiway/agent-workflow-kit 5.3.0 → 5.4.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/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/run-gates.mjs

@@ -68,7 +68,13 @@ import {
   isReviewDependentGate, unknownPregateExcludeIds, derivePregateSubsetGates,
 } from './gates-declaration.mjs';
 
+// The coverage vocabulary lives in a LEAF below this runner AND core-evidence (which validates the
+// token this runner records) — run-gates already imports core-evidence, so a shared home is the
+// only direction that has no cycle. Re-exported here: this module is the vocabulary's public face.
+import { COVERAGE } from './coverage-state.mjs';
+
 export { GATES_REL, loadDeclaration, validateDeclaration, canonicalCheckerGates, isFinalCapableDeclaration, isReviewDependentGate };
+export { COVERAGE };
 
 // The full exit-code table — one distinct code per honest outcome (never a silent green).
 // 7 is RETIRED (the deleted --record arm's outcome) — never reused for a new meaning.
@@ -117,12 +123,18 @@ const USAGE = [
   'deletes the stale git-dir lcov first, exports AW_GIT_DIR to every gate cmd, records EVERY',
   'attempt (start + completed green/red) in the core-evidence store, and binds the receipt to',
   '{ fingerprint before/after, the full declaration, per-gate results, the canonical red-proof +',
-  'degrade evidence hashes, the lcov sha, and — when a flow store exists — evidenceHashes.flow,',
-  'the owner-scoped flow projection hash (D10; projection movement under the run is a red',
-  'integrityFailure) }. --final refuses --only (a subset never attests).',
+  'degrade evidence hashes, the lcov sha, the run\'s own coverage token, and — when a flow store',
+  'exists — evidenceHashes.flow, the owner-scoped flow projection hash (D10; projection movement',
+  'under the run is a red integrityFailure) }. --final refuses --only (a subset never attests).',
   '',
   `Runs the gates declared in <cwd>/${GATES_REL} (one bash command line each, project root as cwd).`,
   'Prints a per-gate PASS/FAIL table + one machine-readable summary line; exit 0 iff all green.',
+  `The summary line carries coverage=<${COVERAGE.certified}|${COVERAGE.notRun}|${COVERAGE.none}|${COVERAGE.unknown}> — whether a coverage`,
+  'VERDICT rode this run: certified (one was issued, pass OR fail), not-run (the checker issued',
+  'none — no lcov, or this run does not own it), none (no canonical checker ran here), unknown (the',
+  'run ended before the gates produced a signal, or the signal is unreadable). The checker\'s own',
+  'table row names a withheld verdict in the same words. DETAIL only: the exit code and the status=',
+  'token are untouched by it.',
   '',
   'Producer env: AW_GIT_DIR (inside a git tree) and AW_LCOV_FILE (--final only) are computed and',
   'exported to every gate child, and STRIPPED from the inherited environment first — a host-set',
@@ -238,23 +250,82 @@ export const runGates = (gates, { cwd, spawn = spawnGateViaBash, now = Date.now,
 };
 
 // The per-gate PASS/FAIL table (printed after every gate ran — failures never stop the matrix).
-export const formatTable = (results) => {
+// `notes` annotates rows by gate id: the coverage signal names a WITHHELD verdict on the checker's
+// own row, so a PASS there can never read as a claim the checker did not make. A Map, not an
+// object — a gate id is any kebab word, `constructor` included, and a plain object would answer
+// that lookup from its prototype.
+export const formatTable = (results, notes = new Map()) => {
   const idWidth = Math.max(...results.map((result) => result.id.length), 'gate'.length);
   const pad = (text) => text + ' '.repeat(idWidth - text.length);
   const lines = ['', `${pad('gate')}  result`];
   for (const result of results) {
-    lines.push(`${pad(result.id)}  ${result.ok ? 'PASS' : `FAIL (exit ${result.code})`}`);
+    const note = notes.get(result.id);
+    lines.push(`${pad(result.id)}  ${result.ok ? 'PASS' : `FAIL (exit ${result.code})`}${note ? `  ${note}` : ''}`);
   }
   return lines;
 };
 
+// ── the coverage signal this run carries (Decision 8) ─────────────────────────────────
+// The checker's two fully anchored machine lines. Exactly ONE of each rides a run: the --final
+// receipt binds them (an injected or duplicated line must never shadow the real one), and the
+// summary field below is derived from the SAME bytes, so the two can never disagree.
+const LCOV_SHA_LINE_RE = /^coverage-check: lcov-sha256=([0-9a-f]{64}|none)$/;
+const ATTESTED_LINE_RE = /^coverage-check: attested=(yes|no)$/;
+const anchoredMachineLines = (stdout, re) => String(stdout ?? '').split(/\r?\n/).filter((line) => re.test(line));
+const exactlyOneMachineValue = (stdout, re) => {
+  const lines = anchoredMachineLines(stdout, re);
+  return lines.length === 1 ? re.exec(lines[0])[1] : null;
+};
+
+// Which SELECTED gate is the canonical checker — resolved BEFORE anything spawns, because the
+// answer is a property of the DECLARATION, not of the post-run filesystem. The predicate reads the
+// tool path through realpath, so a gate that deletes or redirects it mid-run would otherwise turn
+// the checker this run selected into "no checker at all" (`none`) — and a --final receipt refuses
+// that state, which would lose the whole attempt's evidence rather than record it honestly.
+export const resolveCheckerIndex = (selected, projectDir) =>
+  selected.findIndex((gate) => matchesCanonicalCheck(FINAL_CORE_CHECKS[1], gate.cmd, projectDir));
+
+// coverageSignal(checkerAt, results) → { state, note, checkerRow } — what THIS run can honestly say
+// about coverage, decided by the checker's own OUTPUT rather than by its exit status (it exits 0
+// both when it certifies and when it withholds). BOTH anchored lines are read and CROSS-CHECKED:
+// neither alone is trustworthy — a missing or duplicated line is unreadable, and an attestation
+// over bytes that were never consumed is a contradiction. `note` is the checker row's table
+// annotation, null when there is nothing to name.
+export const coverageSignal = (checkerAt, results) => {
+  if (checkerAt === -1) return { state: COVERAGE.none, note: null, checkerRow: null };
+  const checkerRow = results[checkerAt] ?? null;
+  if (checkerRow === null || checkerRow.code === SPAWN_FAILED_CODE) {
+    return { state: COVERAGE.unknown, note: null, checkerRow };
+  }
+  const unreadable = (why) => ({ state: COVERAGE.unknown, note: `coverage=${COVERAGE.unknown} (${why})`, checkerRow });
+  const attested = exactlyOneMachineValue(checkerRow.stdout, ATTESTED_LINE_RE);
+  const consumed = exactlyOneMachineValue(checkerRow.stdout, LCOV_SHA_LINE_RE);
+  if (attested === null || consumed === null) {
+    return unreadable('the checker printed no single anchored attested= / lcov-sha256 pair — whether coverage was certified is unknowable');
+  }
+  if (attested === 'yes') {
+    return consumed === 'none'
+      ? unreadable('the checker attested over an lcov it never read — a contradictory pair, fail closed')
+      : { state: COVERAGE.certified, note: null, checkerRow };
+  }
+  return {
+    state: COVERAGE.notRun,
+    note: consumed === 'none'
+      ? `coverage=${COVERAGE.notRun} (no lcov bytes were read; no coverage verdict was issued)`
+      : `coverage=${COVERAGE.notRun} (an lcov was read but no verdict was issued)`,
+    checkerRow,
+  };
+};
+
 // The ONE machine-readable summary line — always the LAST line printed for every non-usage
-// outcome. Schema (pinned by tests): status ∈ ok|fail|missing|empty|malformed|no-bash.
-export const composeSummaryLine = ({ status, results = [] }) => {
+// outcome. Schema (pinned by tests): status ∈ ok|fail|missing|empty|malformed|no-bash, plus
+// coverage ∈ the COVERAGE vocabulary. The coverage DEFAULT is `unknown`: a lane that ended before
+// the gates could produce a signal says exactly that, never a claim it cannot support.
+export const composeSummaryLine = ({ status, results = [], coverage = COVERAGE.unknown }) => {
   const passed = results.filter((result) => result.ok).length;
   const failed = results.filter((result) => !result.ok);
   const failedIds = failed.length > 0 ? failed.map((result) => result.id).join(',') : NO_FAILED_IDS;
-  return `[run-gates] status=${status} gates=${results.length} passed=${passed} failed=${failed.length} failed_ids=${failedIds}`;
+  return `[run-gates] status=${status} gates=${results.length} passed=${passed} failed=${failed.length} failed_ids=${failedIds} coverage=${coverage}`;
 };
 
 // ── CLI ───────────────────────────────────────────────────────────────────────────────
@@ -655,8 +726,15 @@ export const runCli = (argv, deps = {}) => {
         return EXIT.finalFailed;
       }
     }
+    // The checker's position is pinned BEFORE the matrix spawns; the tree it leaves behind never
+    // gets to re-decide which gate this run selected.
+    const checkerAt = resolveCheckerIndex(selected, projectDir);
     const results = runGates(selected, { cwd: projectDir, spawn: gateSpawn, log, now });
-    for (const line of formatTable(results)) log(line);
+    // Decided once, from the checker's own machine lines, and carried to BOTH surfaces of this run:
+    // the checker's table row and the machine summary field (Decision 7/8).
+    const coverage = coverageSignal(checkerAt, results);
+    const coverageNotes = coverage.note && coverage.checkerRow ? new Map([[coverage.checkerRow.id, coverage.note]]) : new Map();
+    for (const line of formatTable(results, coverageNotes)) log(line);
     const allGreen = results.every((result) => result.ok);
     if (opts.preReview) {
       // The named diagnosis (#66): review-dependence is derived, so an abstracted checker can only
@@ -675,7 +753,7 @@ export const runCli = (argv, deps = {}) => {
           && endRead.records.some((r) => r.kind === CHAIN_KIND && r.purpose === 'adoption');
         if (armedNow) {
           logError('[run-gates] --pre-review: the flow was ARMED while this run executed — the run started unarmed, so its result is NOT recorded (round-11 fold); re-run under the armed flow');
-          log(composeSummaryLine({ status: 'fail', results }));
+          log(composeSummaryLine({ status: 'fail', results, coverage: coverage.state }));
           return EXIT.fail;
         }
       }
@@ -686,7 +764,7 @@ export const runCli = (argv, deps = {}) => {
         if (results.some((result) => result.code === SPAWN_FAILED_CODE)) {
           logError('[run-gates] --pre-review: a gate could not SPAWN — an infrastructure failure is not a gate red, so NO subset-attempt was recorded; fix the spawn failure and re-run');
           releaseSubsetRunLock();
-          log(composeSummaryLine({ status: 'fail', results }));
+          log(composeSummaryLine({ status: 'fail', results, coverage: coverage.state }));
           return EXIT.fail;
         }
         const attemptStatus = allGreen ? 'green' : 'red';
@@ -711,23 +789,18 @@ export const runCli = (argv, deps = {}) => {
           logError(`[run-gates] --pre-review: the subset attempt could not be recorded — ${err.message}`);
           logError("[run-gates] an armed flow's subset run IS a recorded attempt; an unrecordable run refuses (fail closed)");
           releaseSubsetRunLock();
-          log(composeSummaryLine({ status: 'fail', results }));
+          log(composeSummaryLine({ status: 'fail', results, coverage: coverage.state }));
           return EXIT.fail;
         }
       }
     }
-    // A green gate's stdout is deliberately not echoed — the table IS the report. But the checker
-    // exits 0 both when it certifies and when it WITHHOLDS a verdict, so on a plain run the table
-    // would read PASS over a coverage claim that was never made: the same false reassurance one
-    // layer up from the defect this whole mechanism exists to close. Surface it, and only it.
-    if (!opts.final) {
-      const checkerAt = selected.findIndex((gate) => matchesCanonicalCheck(FINAL_CORE_CHECKS[1], gate.cmd, projectDir));
-      const checkerRow = checkerAt === -1 ? null : results[checkerAt];
-      if (checkerRow?.ok && /^coverage-check: attested=no$/m.test(String(checkerRow.stdout ?? ''))) {
-        log(`── ${checkerRow.id} — NO COVERAGE VERDICT (the gate passed; it did not certify)`);
-        for (const line of String(checkerRow.stdout).split(/\r?\n/).filter((l) => /^coverage-check: (NO VERDICT|skipped-no-lcov)/.test(l))) log(line);
-        log('   A coverage verdict is issued only by run-gates.mjs --final, which owns the lcov for the whole run.');
-      }
+    // A green gate's stdout is deliberately not echoed — the table IS the report. The row above
+    // now names the withheld verdict; this block adds the checker's OWN words and the remedy, so a
+    // plain run never leaves a PASS standing for a coverage claim that was never made. Only that.
+    if (!opts.final && coverage.state === COVERAGE.notRun && coverage.checkerRow?.ok) {
+      log(`── ${coverage.checkerRow.id} — NO COVERAGE VERDICT (the gate passed; it did not certify)`);
+      for (const line of String(coverage.checkerRow.stdout).split(/\r?\n/).filter((l) => /^coverage-check: (NO VERDICT|skipped-no-lcov)/.test(l))) log(line);
+      log('   A coverage verdict is issued only by run-gates.mjs --final, which owns the lcov for the whole run.');
     }
     if (opts.final) {
       // The checker's verbatim diagnostics surface even on green — skipped-no-lcov and the
@@ -770,17 +843,15 @@ export const runCli = (argv, deps = {}) => {
         }
         // Exactly ONE full machine line binds the receipt — an unanchored first-match would let
         // an injected/duplicated line shadow the real one and skip the end re-hash.
-        const shaLineRe = /^coverage-check: lcov-sha256=([0-9a-f]{64}|none)$/;
-        const shaLines = String(checkerRow?.stdout ?? '').split(/\r?\n/).filter((l) => shaLineRe.test(l));
-        const shaValue = shaLines.length === 1 ? shaLineRe.exec(shaLines[0])[1] : null;
+        const shaLines = anchoredMachineLines(checkerRow?.stdout, LCOV_SHA_LINE_RE);
+        const shaValue = shaLines.length === 1 ? LCOV_SHA_LINE_RE.exec(shaLines[0])[1] : null;
         const lcovSha256 = shaValue !== null && shaValue !== 'none' ? shaValue : null;
         // The attestation line, on the SAME exactly-one-anchored-line contract as the sha: a green
         // exit status alone never proves the checker certified anything — it exits 0 both when it
         // attests and when it withholds a verdict. Without this arm a gate that removed the start
         // record mid-run would yield a green receipt carrying no coverage claim at all.
-        const attestLineRe = /^coverage-check: attested=(yes|no)$/;
-        const attestLines = String(checkerRow?.stdout ?? '').split(/\r?\n/).filter((l) => attestLineRe.test(l));
-        const attested = attestLines.length === 1 ? attestLineRe.exec(attestLines[0])[1] : null;
+        const attestLines = anchoredMachineLines(checkerRow?.stdout, ATTESTED_LINE_RE);
+        const attested = attestLines.length === 1 ? ATTESTED_LINE_RE.exec(attestLines[0])[1] : null;
         if (allGreen && integrityFailure === null && lcovSha256 !== null) {
           if (attestLines.length !== 1) {
             integrityFailure = attestLines.length === 0
@@ -826,6 +897,11 @@ export const runCli = (argv, deps = {}) => {
               ...(finalFlow?.present ? { flow: finalFlow.hash } : {}),
             },
             lcovSha256,
+            // The run's OWN coverage token, recorded rather than re-derived: `lcovSha256` says what
+            // the receipt binds, never whether a verdict was issued (a red run can bind a digest
+            // over an uncertified read, and a null digest is also what an unreadable sha line
+            // leaves). The stateless render reads this field instead of guessing from the digest.
+            coverage: coverage.state,
             integrityFailure,
             timestamp: new Date().toISOString(),
           },
@@ -848,14 +924,17 @@ export const runCli = (argv, deps = {}) => {
     // would be a silent green in the one place a reader parses instead of reads. The run lock
     // releases BEFORE the line composes so a custody violation can never hide behind status=ok.
     const runLockIssue = releaseSubsetRunLock();
-    log(composeSummaryLine({ status: allGreen && finalError === null && runLockIssue == null ? 'ok' : 'fail', results }));
+    log(composeSummaryLine({ status: allGreen && finalError === null && runLockIssue == null ? 'ok' : 'fail', results, coverage: coverage.state }));
     if (finalError) return EXIT.finalFailed;
     if (runLockIssue != null) return EXIT.fail;
     return allGreen ? EXIT.ok : EXIT.fail;
   } catch (err) {
     releaseSubsetRunLock();
     logError(`[run-gates] ${err.message}`);
-    if (err.exitCode === EXIT.malformed) log(composeSummaryLine({ status: 'malformed' }));
+    // The machine line is the LAST line for every NON-USAGE outcome — a thrown refusal is one, and
+    // the gates never produced a signal there, so it carries coverage=unknown. Usage is the single
+    // documented exception: it prints the usage text and no summary at all.
+    if (err.exitCode !== EXIT.usage) log(composeSummaryLine({ status: err.exitCode === EXIT.malformed ? 'malformed' : 'fail' }));
     return err.exitCode ?? EXIT.fail;
   }
 };