@sabaiway/agent-workflow-kit 2.1.0 → 3.0.0

package/tools/run-gates.mjs

@@ -18,38 +18,31 @@
 // Honest outcomes — each distinct, never a silent green (the exit-code table + the summary-line
 // schema are pinned by run-gates.test.mjs):
 //   0 ok · 1 gate failure · 2 usage · 3 missing declaration · 4 empty gates list ·
-//   5 malformed/invalid declaration · 6 bash unavailable · 7 --record asked but the gate-run
-//   record could not be written. Gate `cmd` lines are BASH command lines (brace/glob expansion);
-//   a host without bash gets the loud exit-6 preflight error, never a silent reinterpretation
-//   under another shell.
+//   5 malformed/invalid declaration · 6 bash unavailable · 8 --final receipt not written.
+//   Gate `cmd` lines are BASH command lines (brace/glob expansion); a host without bash gets the
+//   loud exit-6 preflight error, never a silent reinterpretation under another shell.
 //
-// The runner itself WRITES NOTHING by default. `--record` (BUGFREE-2 / AD-048, D5) mints ONE
-// v4 `gate-run` record — the green-baseline receipt the review-ledger writer's D5 tooth consumes —
-// by DELEGATING to the ledger's sole writer (recordGateRun in review-ledger-write.mjs): this
-// runner never opens the ledger file itself (an import/structure pin holds the boundary). The
-// record carries the FULL declaration + exactly what ran (a --only subset records honestly as a
-// subset — it never satisfies quality-green) + the tree fingerprint BEFORE and AFTER the run (a
-// mutating gate attests no particular tree). Dependency-free, Node >= 18. No side effects on import.
+// The runner itself WRITES NOTHING on a plain run. `--final` (D3(a)) is the ONE writing mode:
+// every attempt lands in the core-evidence store via its sole writer. Dependency-free.
+// No side effects on import.
 
-import { readFileSync, lstatSync } from 'node:fs';
-import { join } from 'node:path';
+import { readFileSync, lstatSync, unlinkSync, realpathSync } from 'node:fs';
+import { join, isAbsolute } from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { pathToFileURL } from 'node:url';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { createHash, randomUUID } from 'node:crypto';
 import { computeTreeFingerprint } from './review-state.mjs';
-import { recordGateRun } from './review-ledger-write.mjs';
-// (a) BUGFREE-3 / AD-049: the one-suite-run credit. The fold runner already spawned the `unit-tests`
-// suite under coverage; --record can CREDIT that gate from the recorded evidence instead of
-// re-spawning it minutes later — read-only (the read core, never the tree-toucher).
-import { foldSuiteCredit } from './fold-completeness.mjs';
-
-// The gate id the (a) credit applies to — the SAME command the fold runner resolves as its suite.
-export const UNIT_TESTS_GATE_ID = 'unit-tests';
+// The D3(a) final receipt rides the core-evidence SOLE WRITER (the sole-writer boundary — this
+// runner never opens the store itself) + the canonical per-kind serialization its hashes bind.
+import { appendEvidenceRecord, resolveEvidencePath, readEvidence, canonicalKindSerialization, EVIDENCE_SCHEMA_VERSION } from './core-evidence.mjs';
+import { LCOV_BASENAME } from './coverage-check.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).
 export const GATES_REL = 'docs/ai/gates.json';
 
 // 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.
 export const EXIT = Object.freeze({
   ok: 0,
   fail: 1,
@@ -58,10 +51,9 @@ export const EXIT = Object.freeze({
   empty: 4,
   malformed: 5,
   noBash: 6,
-  // --record was asked for but the gate-run record could not be written (no in-flight loop, a
-  // malformed ledger, an fs refusal): the invocation's contract included a ledger receipt — not
-  // delivering it is its own loud outcome, never folded into ok/fail.
-  recordFailed: 7,
+  // --final could not write its receipt (a corrupt store, an fs refusal): green gates WITHOUT a
+  // written receipt never read as success (D3(a)).
+  finalFailed: 8,
 });
 
 // A tagged failure carrying its process exit code (the shared orchestration-config idiom).
@@ -74,21 +66,23 @@ const SPAWN_FAILED_CODE = -1;
 const MAX_GATE_OUTPUT_BYTES = 64 * 1024 * 1024;
 
 const USAGE = [
-  'usage: run-gates.mjs [--cwd <dir>] [--only <id>]... [--record] [--help]',
+  'usage: run-gates.mjs [--cwd <dir>] [--only <id>]... [--final] [--help]',
+  '',
+  '--final runs the FULL declared matrix as the D3(a) final verification run: it refuses a',
+  'declaration lacking the canonical core checks (the review-state + coverage-check gates),',
+  '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 }. --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.',
-  '--record additionally mints ONE v4 gate-run record into the review ledger via its sole writer',
-  '(the D5 green-baseline receipt; needs a single in-flight plan): the full declaration + what ran',
-  '+ the pre/post tree fingerprints. A red run records honestly; a --only subset records as a subset.',
-  'In --record mode the unit-tests gate is CREDITED (not re-spawned) when it is the FIRST declared gate',
-  'AND the fold-completeness runner already ran that EXACT command green at the current tree',
-  '(fingerprint-bound + exit-0 + cmd-identity); positioned after another gate, it always re-spawns.',
   'Sandbox-safe: the runner itself needs no network and writes only repo-local state — the D4 sandbox',
   'lane; each DECLARED gate command is the project\'s own, so ITS sandbox-safety is command-shape',
   'dependent (first try the sandbox-safe shape — cache under $TMPDIR, offline/notifier off).',
   `Exit codes: 0 ok · 1 gate failure · 2 usage · 3 missing declaration · 4 empty gates list ·`,
-  '5 malformed/invalid declaration · 6 bash unavailable · 7 --record asked but the record failed.',
+  '5 malformed/invalid declaration · 6 bash unavailable ·',
+  '8 --final asked but its receipt could not be written (green gates never read as success without it).',
 ].join('\n');
 
 // ── declaration validation (malformed → exit 5, loud `path: reason`) ─────────────────
@@ -187,13 +181,11 @@ export const selectGates = (gates, onlyIds) => {
 // Spawn one gate cmd via bash from the project root. `cmd` is a BASH command line by contract
 // (the declaration's _README states it): this repo's own gate matrix needs brace+glob expansion,
 // which /bin/sh does not perform — hence bash explicitly, never the platform default shell.
-// NODE_TEST_CONTEXT is stripped (mirroring the fold suite's childTestEnv): a `node --test` gate spawned
-// while run-gates is itself running under a parent test context would otherwise inherit it, hit Node's
-// recursive-run guard, silently skip every file, and exit 0 — a vacuous false green. Stripping it also
-// makes the plain gate env-equivalent to the fold suite, so the (a) suite-run credit's exit-0 truthfully
-// predicts a plain-spawn exit-0 (the one remaining, documented residual is NODE_V8_COVERAGE).
-export const spawnGateViaBash = (cmd, cwd) => {
-  const env = { ...process.env };
+// NODE_TEST_CONTEXT is stripped: a `node --test` gate spawned while run-gates is itself running
+// under a parent test context would otherwise inherit it, hit Node's recursive-run guard, silently
+// skip every file, and exit 0 — a vacuous false green.
+export const spawnGateViaBash = (cmd, cwd, extraEnv = {}) => {
+  const env = { ...process.env, ...extraEnv };
   delete env.NODE_TEST_CONTEXT;
   return spawnSync('bash', ['-c', cmd], { cwd, env, encoding: 'utf8', maxBuffer: MAX_GATE_OUTPUT_BYTES });
 };
@@ -209,26 +201,17 @@ const trimTrailingNewline = (text) => text.replace(/\n$/, '');
 
 // Run the selected gates sequentially (declaration order). A green gate logs one PASS line; a
 // failing gate logs FAIL + its captured stdout/stderr VERBATIM (triage without re-running).
-export const runGates = (gates, { cwd, spawn = spawnGateViaBash, now = Date.now, log = console.log, credit = null }) => {
+export const runGates = (gates, { cwd, spawn = spawnGateViaBash, now = Date.now, log = console.log }) => {
   const results = [];
   for (const gate of gates) {
     log(`── ${gate.id} — ${gate.title}`);
-    // (a) the one-suite-run credit: for the unit-tests gate, if the fold runner already ran this exact
-    // command green at the current tree, CREDIT it instead of re-spawning (no quality loss — same
-    // execution, same tree, recorded once). Any mismatch → credit is null → the normal spawn below.
-    const credited = credit ? credit(gate) : null;
-    if (credited) {
-      log('   PASS (credited from the fold-completeness suite run — no re-spawn)');
-      results.push({ id: gate.id, title: gate.title, ok: true, code: 0, elapsedMs: 0, credited: true });
-      continue;
-    }
     const startedAt = now();
     const res = spawn(gate.cmd, cwd);
     const elapsedMs = now() - startedAt;
     const spawnError = res.error ? `spawn error: ${res.error.code || res.error.message}` : null;
     const ok = spawnError === null && res.status === 0;
     const code = spawnError === null ? res.status : SPAWN_FAILED_CODE;
-    results.push({ id: gate.id, title: gate.title, ok, code, elapsedMs });
+    results.push({ id: gate.id, title: gate.title, ok, code, elapsedMs, stdout: res.stdout ? String(res.stdout) : '' });
     if (ok) {
       log(`   PASS (${formatSeconds(elapsedMs)})`);
     } else {
@@ -264,7 +247,7 @@ export const composeSummaryLine = ({ status, results = [] }) => {
 // ── CLI ───────────────────────────────────────────────────────────────────────────────
 
 const parseArgs = (argv) => {
-  const opts = { cwd: null, only: [], record: false, help: false };
+  const opts = { cwd: null, only: [], final: false, help: false };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--help' || arg === '-h') {
@@ -277,15 +260,53 @@ const parseArgs = (argv) => {
       i += 1;
       if (argv[i] === undefined) throw fail(EXIT.usage, '--only requires a gate id argument');
       opts.only.push(argv[i]);
-    } else if (arg === '--record') {
-      opts.record = true;
+    } else if (arg === '--final') {
+      opts.final = true;
     } else {
       throw fail(EXIT.usage, `unknown argument "${arg}"\n${USAGE}`);
     }
   }
+  if (opts.final && opts.only.length > 0) {
+    throw fail(EXIT.usage, '--final refuses --only — a subset never attests (the D3(a) receipt binds the FULL declaration)');
+  }
   return opts;
 };
 
+// The canonical core checks a --final declaration must carry (D3(a)), matched as STRICT FULL
+// commands: `node` + ONE (quoted or bare) path token + the exact tool basename + ` --check` +
+// END — and the path token must REALPATH-RESOLVE to the kit's OWN tool (the canonical sibling of
+// this runner). Masked forms (`--check --help`, `--check || true`, prefix commands) never match
+// the shape; a lookalike file that merely carries the basename — whatever it prints — never
+// resolves to the canonical tool. Any form that DOES resolve (bare, relative, absolute, quoted)
+// is accepted, so the anchor adds no false refusals.
+const coreCheckRe = (basename) => new RegExp(`^node\\s+(?:"((?:[^"]*[/\\\\])?${basename})"|((?:[^\\s"]*[/\\\\])?${basename}))\\s+--check$`);
+const FINAL_CORE_CHECKS = [
+  { name: 'review-state', re: coreCheckRe('review-state\\.mjs'), canonical: fileURLToPath(new URL('./review-state.mjs', import.meta.url)) },
+  { name: 'coverage-check', re: coreCheckRe('coverage-check\\.mjs'), canonical: fileURLToPath(new URL('./coverage-check.mjs', import.meta.url)) },
+];
+const matchesCanonicalCheck = (check, cmd, projectDir) => {
+  const m = check.re.exec(cmd.trim());
+  if (!m) return false;
+  const token = m[1] ?? m[2];
+  const abs = isAbsolute(token) ? token : join(projectDir, token);
+  try {
+    return realpathSync(abs) === realpathSync(check.canonical);
+  } catch {
+    return false; // unresolvable → never canonical (fail closed)
+  }
+};
+
+// isFinalCapableDeclaration(gates, projectDir) → whether --final would accept this declaration
+// (every canonical core check present + the checker LAST) — the ONE home consumers (the
+// recommendations guard-install probe) read instead of re-deriving the rule.
+export const isFinalCapableDeclaration = (gates, projectDir) => {
+  if (!Array.isArray(gates) || gates.length === 0) return false;
+  const missing = FINAL_CORE_CHECKS.filter((c) => !gates.some((g) => matchesCanonicalCheck(c, g.cmd, projectDir)));
+  if (missing.length > 0) return false;
+  return matchesCanonicalCheck(FINAL_CORE_CHECKS[1], gates[gates.length - 1].cmd, projectDir);
+};
+const sha256Hex = (data) => createHash('sha256').update(data).digest('hex');
+
 // The full CLI, dependency-injected for hermetic tests. Returns the process exit code; the two
 // output sinks split human-facing report (log) from error channel (logError). The summary line is
 // emitted via `log` as the final line of every non-usage outcome.
@@ -299,9 +320,7 @@ export const runCli = (argv, deps = {}) => {
     readFile,
     lstat,
     now,
-    record = recordGateRun,
     fingerprint = computeTreeFingerprint,
-    foldCredit = foldSuiteCredit,
   } = deps;
   try {
     const opts = parseArgs(argv);
@@ -326,6 +345,39 @@ export const runCli = (argv, deps = {}) => {
       return EXIT.empty;
     }
     const selected = selectGates(declaration.gates, opts.only);
+    // AW_GIT_DIR rides EVERY gate child inside a git tree (plain and --only alike): declared
+    // cmds reference fixed git-dir artifacts (the unit-tests lcov destination) — a plain red-run
+    // must exercise the SAME cmd line --final will, never a broken-only-outside---final variant.
+    const dirRes = spawnSync('git', ['rev-parse', '--absolute-git-dir'], { cwd: projectDir, windowsHide: true });
+    const gitDir = dirRes.error || dirRes.status !== 0 ? null : dirRes.stdout.toString('utf8').replace(/\r?\n$/, '');
+    let gateSpawn = gitDir === null ? spawn : (cmd, cwd2) => spawn(cmd, cwd2, { AW_GIT_DIR: gitDir });
+    // ── --final preflight (D3(a)): the declaration must carry the canonical core checks; the TRUE
+    // git dir resolves AW_GIT_DIR; the stale lcov dies BEFORE the suite so it is never consumed.
+    if (opts.final) {
+      const missing = FINAL_CORE_CHECKS.filter((c) => !declaration.gates.some((g) => matchesCanonicalCheck(c, g.cmd, projectDir)));
+      if (missing.length > 0) {
+        throw fail(EXIT.malformed, `--final refuses a weakened declaration — missing the canonical core check(s): ${missing.map((c) => c.name).join(', ')} (each must be ONE plain --check invocation of the kit's OWN tool in ${GATES_REL} — a masked form, a compound, or a lookalike path never counts)`);
+      }
+      const lastGate = declaration.gates[declaration.gates.length - 1];
+      if (!matchesCanonicalCheck(FINAL_CORE_CHECKS[1], lastGate.cmd, projectDir)) {
+        throw fail(EXIT.malformed, `--final refuses the declaration — the CANONICAL coverage-check gate must be the LAST declared gate (nothing may run after the checker consumed the lcov; "${lastGate.id}" is declared last)`);
+      }
+      if (gitDir === null) throw fail(EXIT.fail, '--final needs a git work tree (cannot resolve the git dir)');
+      try {
+        unlinkSync(join(gitDir, LCOV_BASENAME)); // a stale lcov is never consumed
+      } catch (err) {
+        if (err.code !== 'ENOENT') {
+          // Anything but "absent" leaves a readable stale artifact behind — fail closed BEFORE
+          // the attempt starts (a swallowed delete error could fake coverage).
+          logError(`[run-gates] --final could not delete the stale lcov at ${join(gitDir, LCOV_BASENAME)}: ${err.message} (fail closed)`);
+          log(composeSummaryLine({ status: 'fail' }));
+          return EXIT.finalFailed;
+        }
+      }
+      // ONE lcov path for delete/check/hash/guard: the fixed git-dir file is FORCED into every
+      // gate child env — a stray host AW_LCOV_FILE can never desync the checker from the receipt.
+      gateSpawn = (cmd, cwd2) => spawn(cmd, cwd2, { AW_GIT_DIR: gitDir, AW_LCOV_FILE: join(gitDir, LCOV_BASENAME) });
+    }
     const probe = spawn(BASH_PROBE_CMD, projectDir);
     if (probe.error && probe.error.code === 'ENOENT') {
       logError(
@@ -335,51 +387,123 @@ export const runCli = (argv, deps = {}) => {
       log(composeSummaryLine({ status: 'no-bash' }));
       return EXIT.noBash;
     }
-    const fingerprintBefore = opts.record ? fingerprint(projectDir) : null;
-    // (a) the one-suite-run credit — ONLY in --record mode (the fold-loop flow), ONLY the unit-tests
-    // gate, ONLY when it is the FIRST selected gate (a gate that ran BEFORE it could have side-effected
-    // an ignored/out-of-tree artifact unit-tests depends on WITHOUT moving the fingerprint, so a
-    // later-positioned unit-tests must re-spawn — never credit a state the real matrix might fail), and
-    // ONLY when the fold evidence is fingerprint-bound + exit-0 (foldCredit) AND its recorded cmd EQUALS
-    // this gate's cmd (the --only-subset defense). Any mismatch → credit is null → the normal spawn.
-    let credit = null;
-    if (opts.record && selected[0]?.id === UNIT_TESTS_GATE_ID) {
-      const fold = foldCredit({ cwd: projectDir, env, fingerprint: fingerprintBefore });
-      credit = (gate) => (gate.id === UNIT_TESTS_GATE_ID && fold.credited && fold.evidence.cmd === gate.cmd ? fold : null);
+    // --final needs the pre-run fingerprint (the receipt binds before == after == current).
+    const finalFingerprintBefore = opts.final ? fingerprint(projectDir) : null;
+    const finalAttempt = opts.final ? randomUUID() : null;
+    let finalError = null;
+    let startEvidenceHashes = null;
+    if (opts.final) {
+      try {
+        appendEvidenceRecord({
+          path: resolveEvidencePath(projectDir, env),
+          record: { schema: EVIDENCE_SCHEMA_VERSION, kind: 'final-start', fingerprint: finalFingerprintBefore, attempt: finalAttempt, timestamp: new Date().toISOString() },
+        });
+        // The drift tooth's anchor: the canonical red-proof/degrade serializations BEFORE any
+        // gate runs — no legitimate writer appends those kinds DURING a final run, so any change
+        // by receipt time is an integrity failure, never a green.
+        const { records } = readEvidence(resolveEvidencePath(projectDir, env));
+        startEvidenceHashes = {
+          redProof: sha256Hex(canonicalKindSerialization(records, 'red-proof')),
+          degrade: sha256Hex(canonicalKindSerialization(records, 'degrade')),
+        };
+      } catch (err) {
+        // EVERY attempt is recorded — an unwritable store refuses the whole attempt up front
+        // (green gates without a written receipt never read as success).
+        logError(`[run-gates] --final could not record the attempt start: ${err.message}`);
+        log(composeSummaryLine({ status: 'fail' }));
+        return EXIT.finalFailed;
+      }
     }
-    const results = runGates(selected, { cwd: projectDir, spawn, log, now, credit });
+    const results = runGates(selected, { cwd: projectDir, spawn: gateSpawn, log, now });
     for (const line of formatTable(results)) log(line);
     const allGreen = results.every((result) => result.ok);
-    // The gate-run record (D5): minted for green AND red runs alike (an honest red is telemetry
-    // fuel), via the ledger's sole writer. Emitted BEFORE the summary line — the machine summary
-    // stays the LAST line of every non-usage outcome (pinned).
-    let recordError = null;
-    if (opts.record) {
-      const failing = results.filter((result) => !result.ok);
+    if (opts.final) {
+      // The checker's verbatim diagnostics surface even on green — skipped-no-lcov and the
+      // out-of-domain/unsupported lists must never vanish into a suppressed green stdout.
+      const checkerRow = results[results.length - 1];
+      if (checkerRow?.ok && checkerRow.stdout) {
+        log('── coverage-check diagnostics (verbatim)');
+        log(trimTrailingNewline(checkerRow.stdout));
+      }
+      // The completed attempt (D3(a)): status green/red DERIVED from results + integrity, the
+      // FULL declaration, the per-gate results, the evidence hashes over the CANONICAL
+      // authoritative serializations, and the lcov sha the CHECKER printed for the bytes it
+      // actually read — with an end re-hash agreement check (the checker's own children are the
+      // one write window that survives "coverage-check runs last").
       try {
-        const { writtenPath } = record({
-          cwd: projectDir,
-          env,
-          declared: declaration.gates.map(({ id, cmd }) => ({ id, cmd })),
-          results: results.map(({ id, ok, code }) => ({ id, ok, code })),
-          summary: {
-            status: allGreen ? 'ok' : 'fail',
-            gates: results.length,
-            passed: results.length - failing.length,
-            failed: failing.length,
-            failedIds: failing.map((result) => result.id),
+        const storePath = resolveEvidencePath(projectDir, env);
+        const endRead = readEvidence(storePath);
+        const endBroken = Boolean(endRead.readError) || (endRead.malformed ?? 0) > 0;
+        let integrityFailure = null;
+        if (endBroken) {
+          integrityFailure = 'the evidence store became unreadable under the final run';
+        } else {
+          const endHashes = {
+            redProof: sha256Hex(canonicalKindSerialization(endRead.records, 'red-proof')),
+            degrade: sha256Hex(canonicalKindSerialization(endRead.records, 'degrade')),
+          };
+          if (endHashes.redProof !== startEvidenceHashes.redProof || endHashes.degrade !== startEvidenceHashes.degrade) {
+            integrityFailure = 'the evidence store moved under the final run (the canonical red-proof/degrade serialization changed)';
+          }
+        }
+        // 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 lcovSha256 = shaValue !== null && shaValue !== 'none' ? shaValue : null;
+        if (allGreen && integrityFailure === null) {
+          if (shaLines.length !== 1) {
+            integrityFailure = shaLines.length === 0
+              ? 'the coverage-check gate printed no lcov-sha256 line — the consumed lcov is unknowable (fail closed)'
+              : `the coverage-check gate printed ${shaLines.length} lcov-sha256 lines — exactly ONE full machine line binds the receipt`;
+          } else if (lcovSha256 !== null) {
+            let endSha = null;
+            try {
+              const st = lstatSync(join(gitDir, LCOV_BASENAME));
+              if (st.isFile()) endSha = sha256Hex(readFileSync(join(gitDir, LCOV_BASENAME)));
+            } catch { /* vanished → disagreement below */ }
+            if (endSha !== lcovSha256) integrityFailure = 'the lcov moved under the checker (the end re-hash differs from the checker-read bytes)';
+          }
+        }
+        const status = allGreen && integrityFailure === null ? 'green' : 'red';
+        appendEvidenceRecord({
+          path: storePath,
+          record: {
+            schema: EVIDENCE_SCHEMA_VERSION,
+            kind: 'final',
+            status,
+            attempt: finalAttempt,
+            fingerprintBefore: finalFingerprintBefore,
+            fingerprintAfter: fingerprint(projectDir),
+            declared: declaration.gates.map(({ id, cmd }) => ({ id, cmd })),
+            results: results.map(({ id, ok, code }) => ({ id, ok, code })),
+            evidenceHashes: endBroken
+              ? startEvidenceHashes
+              : {
+                redProof: sha256Hex(canonicalKindSerialization(endRead.records, 'red-proof')),
+                degrade: sha256Hex(canonicalKindSerialization(endRead.records, 'degrade')),
+              },
+            lcovSha256,
+            integrityFailure,
+            timestamp: new Date().toISOString(),
           },
-          fingerprintBefore,
-          fingerprintAfter: fingerprint(projectDir),
         });
-        log(`[run-gates] gate-run recorded → ${writtenPath}`);
+        if (integrityFailure) {
+          finalError = new Error(integrityFailure);
+          logError(`[run-gates] --final integrity failure: ${integrityFailure} — the receipt is RED`);
+        }
+        log(`[run-gates] final receipt recorded (${status}) → ${storePath}`);
+        if (status === 'green' && lcovSha256 === null) {
+          logError(`[run-gates] --final consumed NO lcov — the coverage arm ran skipped-no-lcov; the receipt records lcovSha256:null (the declared unit-tests gate must produce <git-dir>/${LCOV_BASENAME})`);
+        }
       } catch (err) {
-        recordError = err;
-        logError(`[run-gates] --record failed: ${err.message}`);
+        finalError = err;
+        logError(`[run-gates] --final could not write its receipt: ${err.message}`);
       }
     }
     log(composeSummaryLine({ status: allGreen ? 'ok' : 'fail', results }));
-    if (recordError) return EXIT.recordFailed;
+    if (finalError) return EXIT.finalFailed;
     return allGreen ? EXIT.ok : EXIT.fail;
   } catch (err) {
     logError(`[run-gates] ${err.message}`);

package/tools/sandbox-masks.mjs

@@ -31,7 +31,7 @@
 // from the hidden-mode reconcile's block (hide-footprint.mjs — that lane noops on visible
 // deployments; this one serves them too). A malformed fence (start without end / duplicated
 // markers) fails CLOSED: loud report, file untouched. Patterns are root-anchored (`/rel`),
-// glob-metacharacters escaped, NUL-safe walk. Dependency-free, Node >= 18; no side effects on
+// glob-metacharacters escaped, NUL-safe walk. Dependency-free, Node >= 22; no side effects on
 // import (the isDirectRun idiom).
 
 import { lstatSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';

package/tools/semver-lite.mjs

@@ -7,7 +7,7 @@
 // freshness probe that cannot parse a version must degrade to "unknown" — never to a false ordering
 // claim in either direction (INV-B). No `let`: a small functional comparison (AGENTS.md §2.3).
 //
-// Pure, no imports, no side effects, Node >= 18.
+// Pure, no imports, no side effects, Node >= 22.
 
 export const parseSemver = (str) => {
   const m = typeof str === 'string' ? str.trim().match(/^(\d+)\.(\d+)\.(\d+)/) : null;

package/tools/set-autonomy.mjs

@@ -19,7 +19,7 @@
 // (malformed/unreadable policy) or a write STOP (no deployment / symlinked leaf). main(argv, ctx) →
 // { code, stdout, stderr }; cwd / fs are injectable for host-independent tests.
 //
-// Dependency-free, Node >= 18. No side effects on import (the isDirectRun idiom).
+// Dependency-free, Node >= 22. No side effects on import (the isDirectRun idiom).
 
 import { readFileSync, lstatSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';

package/tools/set-recipe.mjs

@@ -19,7 +19,7 @@
 // or a write STOP (no deployment / symlinked leaf). main(argv, ctx) → { code, stdout, stderr }; cwd /
 // env / home / detect / fs are injectable for host-independent tests.
 //
-// Dependency-free, Node >= 18. No side effects on import (the isDirectRun idiom).
+// Dependency-free, Node >= 22. No side effects on import (the isDirectRun idiom).
 
 import { readFileSync, lstatSync } from 'node:fs';
 import { homedir } from 'node:os';

package/tools/setup-backends.mjs

@@ -21,7 +21,7 @@
 // wrappers are POSIX .sh — report unsupported / use WSL and mutate nothing. Every fs primitive is
 // injectable (deps.*) so the whole module is unit-testable without touching the real filesystem.
 //
-// Dependency-free, Node >= 18.
+// Dependency-free, Node >= 22.
 
 import {
   existsSync, lstatSync, statSync, readdirSync, readlinkSync, symlinkSync, mkdirSync, copyFileSync,

package/tools/surface.mjs

@@ -6,7 +6,7 @@
 // `/agent-workflow-kit status` surface always consumes `--json` and localizes itself.
 //
 // Pure + fully injectable (argv / env / isTTY / columns / platform are inputs), no side effects on
-// import, Node >= 18. Tested in isolation against the §4.5 table.
+// import, Node >= 22. Tested in isolation against the §4.5 table.
 
 export const FORMATS = Object.freeze(['auto', 'plain', 'ansi', 'json']);
 export const FORMAT_ENV = 'AGENT_WORKFLOW_FORMAT';

package/tools/uninstall.mjs

@@ -19,7 +19,7 @@
 //                    untouched and reported, never removed.
 //
 // Pure planner (buildPlan) + guarded executor (executePlan), both dependency-injectable so the whole
-// module is unit-testable without the real filesystem. Dependency-free, Node >= 18. No side effects on
+// module is unit-testable without the real filesystem. Dependency-free, Node >= 22. No side effects on
 // import (the isDirectRun idiom).
 
 import { existsSync, statSync, lstatSync, readlinkSync, readFileSync, readdirSync, realpathSync } from 'node:fs';

package/tools/velocity-profile.mjs

@@ -18,7 +18,7 @@ import { findOnPath } from './detect-backends.mjs';
 
 // Deployment-lineage head this velocity build targets; bump together with agent-workflow-memory
 // LINEAGE_HEAD when the deployed docs/ai structure changes.
-export const EXPECTED_WORKFLOW_VERSION = '2.0.0';
+export const EXPECTED_WORKFLOW_VERSION = '3.0.0';
 export const SETTINGS_FILE = '.claude/settings.json';
 export const SETTINGS_LOCAL_FILE = '.claude/settings.local.json';
 export const CLAUDE_DIR = '.claude';
@@ -490,7 +490,7 @@ const isScriptMap = (scripts) => Boolean(scripts) && typeof scripts === 'object'
 const isMutatingScriptName = (name) =>
   MUTATING_SCRIPT_NAME_PATTERN.test(name) || MUTATING_SCRIPT_HOOK_PATTERN.test(name);
 
-// `scriptName` is ADDITIVE (AD-042): the seed-gates offer layer maps a candidate to a
+// `scriptName` is ADDITIVE (AD-042): the gates-init offer layer maps a candidate to a
 // package-manager-aware `{ id, title, cmd }` and needs the raw script name for that derivation;
 // `command` stays the advisory's own npm-run spelling (this fn is otherwise unchanged).
 const makeGateCandidate = (name) => ({

package/tools/view-model.mjs

@@ -6,7 +6,7 @@
 // filenames never reach them). This module resolves public tokens → English phrases (presentation.mjs)
 // and computes the headline counts; the renderers do layout + glyphs only.
 //
-// Pure, no side effects, Node >= 18.
+// Pure, no side effects, Node >= 22.
 
 import { STATE_PHRASING, VISIBILITY_PHRASING } from './presentation.mjs';
 

package/references/modes/fold-completeness.md

@@ -1,30 +0,0 @@
-### Mode: fold-completeness
-
-The FOLD-COMPLETENESS gate (M3a / AD-046, honest red→green BUGFREE-1 / AD-047) — the sibling of the review-round ledger: the ledger computes WHEN the plan-execution review loop stops; this tool pair verifies that the tests the loop's folds bind to ACTUALLY pin the changed code, and that each bound test was SEEN FAILING before its fix (no fix theater). One recorded run proves (a) every changed executable line is executed by the suite and (b) every `fixable-bug` bound testId is N/N green with an observed-red receipt behind it; a read-only checker turns the recorded evidence into a gate exit code. **Since schema v3 (BUGFREE-2 / AD-048, D7) every record carries `base` and the whole proof is SEGMENT-scoped** — bound testIds, receipts, custody chains, and tamper obligations all filter to (loop, `base` = the current HEAD): a committed phase's custody obligations **close with its commit** (editing a custody file in a LATER segment no longer re-demands the closed segment's proof — the cross-phase churn class is dead), while a fold whose red was observed in a PREVIOUS segment still needs the `red-proof` lane (a receipt never crosses a commit boundary — the stated residual). Pre-v3 records never enter a segment; a dirty loop holding only pre-v3 records fails with a reason naming the schema upgrade. **Since schema v4 (BUGFREE-3 / AD-049)** a run record additionally carries the **suite-execution evidence** ((a): `cmd` + exit + pre/post fingerprints — so `run-gates --record` can CREDIT the `unit-tests` gate instead of re-spawning it), and a new record kind **`reattest`** joins `run`/`red-probe` ((c): an operator-minted, recorded custody re-attestation — see the runner's `--reattest`). A placed pre-v4 checker rejects a v4 record outright (the version-skew guard); v1/v2/v3 rules are untouched.
-
-**The fold-time order (the operational contract — red is observed BEFORE the fix):** classify the fixable-bug with its testId → write the failing test → `--red "<testId>"` observes it FAIL on the real pre-fold tree and mints the receipt → fold the fix → the normal run observes green → `--check`. Folding first is not recoverable without reverting the fix to re-observe red — observe red when it actually happens.
-
-**Two tools — the read/run split:**
-
-1. **Runner** — `node ${CLAUDE_SKILL_DIR}/tools/fold-completeness-run.mjs [--suite "<cmd>"] [--cwd <dir>]`, plus the red verb `--red "<test-file>#<test-name-pattern>"` — the SOLE tree-toucher and the SOLE result writer. The default run, over the in-flight plan-execution loop's dirty tree: resolve the loop (the single in-flight plan stem — 0 or >1 plans is a typed refusal), classify the changed surface by a CLOSED extension rule (assessable JS / unsupported TS-JSX / out-of-domain), run the suite ONCE under `NODE_V8_COVERAGE` (the coverage dir lives OUTSIDE the work tree — no repo artifacts), map every changed executable line to covered/uncovered from the V8 report itself, probe each bound testId N times (`AW_FOLD_RERUNS`, default 3; a shell-free spawn of the resolver's canonical path; each run under its own per-run `AW_FOLD_PROBE_TIMEOUT_S`, default 120 — probes only, never the suite) recording rerun counts + the test file's content hash (custody), and append ONE machine-only v3 run record — segment-framed (`base`) and bound to BOTH the tree fingerprint AND the segment's sorted `fixable-bug` testId set — to `<git dir>/agent-workflow-fold-completeness.jsonl` (never committable by construction; `AW_FOLD_RESULTS` overrides). **`--red` observes a testId on the CURRENT (pre-fold) tree**: failing on N/N runs → it appends the observed-red receipt (testId, counts, content hash, fingerprint); observed-green / unresolvable / mixed / timed-out are DISTINGUISHED typed refusals and nothing is written. The verdict algebra is strict N/N: RED = N/N fail, GREEN = N/N pass, anything mixed or timed out is **QUARANTINE** — it never converts and has NO override lane (a flaky pin proves nothing — replace the test). A test that cannot even LOAD pre-fold (it imports an export the fix introduces) is authored with a dynamic `import()` so it loads and fails pre-fold.
-2. **Read-only checker** — `node ${CLAUDE_SKILL_DIR}/tools/fold-completeness.mjs [--check | --status | --json]` — never runs tests, never touches the tree, never imports the runner (an import-split test pins the structural split). Per bound testId (of the CURRENT segment) the gate requires: an N/N-green probe, an observed-red receipt in this segment, that receipt PRECEDING the loop's latest run in ledger order (a post-hoc red proves nothing — a late receipt forces one fresh run), and content **custody** — the run's recorded test-file hash equals the latest custody-eligible receipt hash on that file (eligible = the receipt's own testId is bound AND it precedes the run), so the test that is green now is byte-identical to a test that provably failed; any edit after the receipt requires re-observing red, and appending the NEXT fold's red test to the same file re-attests it without ceremony. `--status` (default) is the human report; **`--check` is the gate exit code — the normative exit contract lives in the CHECKER's tool header (the single home — do not re-enumerate it elsewhere)**; `--json` is the structured state + decision.
-
-**The verification PROFILE — language independence (BUGFREE-3 / AD-049).** An OPTIONAL per-project `docs/ai/verification-profile.json` (seeded by the memory bootstrap; a memory-canon template with a kit mirror) generalizes the fold signal beyond JS/V8 so a consumer on another language/runner drives the SAME gate. It declares three inputs — **`coverage.kind`** `"v8"` (default) or `"lcov"` (+ `lcovPath`: your suite leaves an LCOV file there, parsed by a dependency-free reader — the diff-cover pattern); **`singleTest`** an argv template (`{file}`/`{pattern}`, plus `{resultPath}` for a file-based format) + `resultFormat` `"tap-stdout"` (default) / `"tap-file"` / `"junit-xml"` (the "0 tests matched" → unresolvable guard holds for EVERY format — a zero-match is never read green); and an optional **`findings.sarifPath`** for ADVISORY findings (`--findings` prints them — never recorded, never gate-blocking; a malformed SARIF fails the advisory read loudly but leaves `--check` unaffected). An ABSENT profile reproduces today's exact behaviour (V8 + node:test TAP on stdout); env knobs (`AW_FOLD_SUITE_CMD`/`AW_FOLD_BOUND_CMD`) still override. Every DECLARED path (`lcovPath`, `sarifPath`) MUST be gitignored or outside the repo (a symlink is refused) — else the suite writing there would move the review fingerprint. The suite COMMAND is NOT a profile field: it stays the `gates.json` `unit-tests` cmd (command-identity — the (a) credit).
-
-**The operator verbs (recorded, self-discipline — never auto-detection):** besides `--red`, the runner offers **`--reattest "<testId>"`** ((c)): re-anchor a bound test FILE's custody at its CURRENT bytes after a GREEN-ONLY append — the honest replacement for a `red-proof` waiver (there is no red to observe); it never converts a red baseline or waives the observed-red proof, and the guard still fails closed on any un-reattested change. **`--preflight`** ((f)): the CHEAP half — from the git diff + ledgers (seconds, no suite run, no probe, no coverage) it prints the overrides/re-attests to RECORD BEFORE the expensive pass, routed by kind (`oracle-change` for a tampered file, `--reattest` for a green-only custody delta, `--red`/`red-proof` for a bound testId with no observed-red receipt). **`--findings`**: the SARIF advisory above.
-
-**The oracle-tamper guard + the recorded override lanes (review-ledger schema v3).** The runner also records a **tamper surface** over the tracked working-vs-HEAD diff — the union of test-classified paths and the bound-testId file halves, restricted to files existing at HEAD — classified by hunk line polarity: any removed/modified line (or a deleted file) is TAMPER; pure additions and brand-new test files never trip it. Note two edges: a **rename** reads as delete+add under the pinned `--no-renames` diff, so renaming a test file trips the guard (record the override or split the rename from the fix); and a run record written by a **pre-tamper runner** (no recorded surface) fails the gate with a re-run reason — after an upgrade, one fresh run refreshes the evidence. The gate fails closed on any tampered file not named by a recorded **`oracle-change`** override (`review-ledger-write override --json '{"loop":…,"round":…,"scope":"oracle-change","files":[…],"reason":…}'` — a durable, auditable ledger entry, never a silent waiver; one override covers the named files for the rest of the loop). The second lane, scope **`red-proof`**, names ONE testId whose red is genuinely unestablishable pre-fold (or whose custody file was legitimately edited post-fix) and waives the receipt + custody proof for exactly that testId — never the N/N-green requirement, never QUARANTINE. Overrides are loop + payload scoped, minted only inside the single in-flight loop.
-
-**Wire the gate BY HAND, once, BEFORE the round's runner run.** The candidate line for your own `docs/ai/gates.json`: `{ "id": "fold-completeness", "title": "Fold-completeness — every changed executable line executed by tests (M3a)", "cmd": "node \"<path-to-this-skill>/tools/fold-completeness.mjs\" --check" }` — the path your project reaches the kit by, kept inside the escaped quotes so a path with spaces survives. Wiring comes FIRST because where `docs/ai` is tracked, the gate-file edit itself moves the tree fingerprint — wiring after a run stales the record you just wrote. The consent-gated seeder does NOT offer this entry yet — a deliberate hold: the language-aware verification profile now EXISTS (BUGFREE-3 / AD-049 — coverage via LCOV, single-test via TAP-file/JUnit-XML), so the JS/V8-only blocker is lifted, but consumer-seeding of this gate is a SEPARATE follow-up the profile merely unblocks.
-
-**Run-then-check usage (each plan-execution round):** run the runner AFTER the round's LAST edit — any later tree edit (a source fix, a doc touch, a gate-file tweak) moves the fingerprint and requires a re-run — then the wired `--check` attests it. Staleness is by BOTH bindings: a tree edit moves the fingerprint, and a new `fixable-bug` triage moves the bound-testId set — either makes the previous record STALE, so a green check always attests the CURRENT tree against the CURRENT fold set.
-
-**Suite + bound-test commands:** the suite command defaults to the `unit-tests` gate `cmd` in the project's `docs/ai/gates.json`; absent that, `--suite "<cmd>"` (or `AW_FOLD_SUITE_CMD`) is REQUIRED — refused loudly otherwise. Bound-test probes default to the `node --test --test-name-pattern` shape over the testId halves (`<test-file>#<test-name-pattern>`); a consumer on another runner sets the profile's `singleTest.argv` (or the `AW_FOLD_BOUND_CMD` env override, which wins) — a JSON ARRAY of argv strings with `{file}` / `{pattern}` substitution (plus `{resultPath}` for a file-based `resultFormat`), spawned WITHOUT a shell (testId content never reaches a shell). Coverage comes from V8 by default, or from an LCOV file the suite writes (`coverage.kind:"lcov"` + `lcovPath`) — either source feeds the same uncovered-changed decision. Note: the suite's own child processes must inherit `NODE_V8_COVERAGE` for their lines to count (node child spawns inherit it by default; a test runner that scrubs its child env needs consumer configuration).
-
-**v1 scope (stated):** assessable = `.mjs` / `.cjs` / `.js`, excluding test files (`*.test.*` / `*.spec.*`); changed `.ts` / `.tsx` / `.jsx` / `.mts` / `.cts` files are recorded as unsupported and FAIL the gate CLOSED — the signal never vouches for JS-family source it cannot assess; everything else (docs/config the suite does not execute) is recorded out-of-domain and LOUDLY listed, never gate-blocking. Executability is coverage-derived (V8 by default, or LCOV via the profile): a changed assessable file entirely absent from the coverage report is RED at file level ("never imported" must not read as "nothing executable"). The LANGUAGE-INDEPENDENCE contract (BUGFREE-3) generalizes the coverage source + single-test result format without changing this closed JS assessable rule — a consumer whose suite emits LCOV + JUnit-XML drives the same gate.
-
-**Mutation is NOT shipped (v1).** The result record carries a reserved, always-empty `mutation` shape; the shipped runner performs NO mutation and never modifies a source file, and the checker FAILS CLOSED on a record carrying ANY mutation data (such a record was not produced by this runner version). The researched mutation half was shelved: a bounded operator set tests local expression boundaries, not the cross-module interactions that produce real fold bugs, and it is not language-independent. The `AW_FOLD_MUTANTS_MAX` / `AW_FOLD_HUNK_MUTANTS_MAX` / `AW_FOLD_TIME_BUDGET_S` budgets are parsed and recorded but inert in v1 (reserved).
-
-**Honest residuals (stated, accepted — exactly like review-state's / review-ledger's):** coverage proves EXECUTION, not assertion — an executed-but-unasserted line still reads covered; the per-fold proof remains the M2 discipline (a `fixable-bug` testId written red→green, probed green here), the coverage run is the whole-surface prefilter; the result records, testIds, and ledgers are forgeable (`git commit --no-verify`, file editing) — a self-discipline mechanism against silent process drift, NOT a security boundary.
-
-**Invariants:** the checker is read-only · never commits · never runs a subscription CLI · spawns read-only `git` queries only · the SOLE tree-toucher + result writer is `fold-completeness-run.mjs`, which the checker NEVER imports (read/run split, import-split test) · the runner's only writes land OUTSIDE the work tree (the coverage temp dir + the git-dir result ledger) — the tree fingerprint is byte-identical before and after a run.