@sabaiway/agent-workflow-kit 1.39.0 → 1.41.0

package/tools/review-state.mjs

@@ -15,11 +15,18 @@
 //           EXECUTE- / FEEDBACK-, or a name containing PROMPT / prompt / handoff); when the tree is
 //           clean (nothing to review); when the cwd is not a git work tree (nothing to fingerprint);
 //           and when EVERY recipe-named backend has a current-fingerprint receipt with acceptable
-//           grounding (fresh:true, artifact "code", grounded:true).
-//   exit 1  when a recipe-named backend has no current-fingerprint receipt — including the
-//           stale-after-edit case (any tracked/untracked change after the review moves the
-//           fingerprint) — or when its only current receipts carry grounded:false (an ungrounded
-//           agy review under reviewed/council never satisfies the gate).
+//           grounding (fresh:true, artifact "code", grounded:true) OR is degraded-exempt: the current
+//           plan-execution SEGMENT's latest review-ledger round records that backend degraded:true at
+//           the current tree fingerprint, with >= 1 non-degraded recipe-named backend present with a
+//           current grounded receipt and the ledger reading clean (AD-050; MIRRORS review-ledger
+//           decideStop's degraded handling — presence, not unanimity, never a 0/0-counts gate).
+//   exit 1  when a recipe-named backend has no current-fingerprint receipt AND is not degraded-exempt —
+//           including the stale-after-edit case (any tracked/untracked change after the review moves the
+//           fingerprint) — or when its only current receipts carry grounded:false AND it is not
+//           degraded-exempt (an ungrounded agy review under reviewed/council never satisfies the gate on
+//           its own — but a recorded current-tree degrade still exempts it). An unreadable/malformed
+//           review-ledger DENIES the degraded exemption (fail-closed) but NEVER fails a tree whose
+//           receipts independently satisfy the gate (that stays exit 0, the ledger issue surfaced).
 // Informational receipts NEVER satisfy (nor fail) the tree check: plan/diff-mode receipts
 // (artifact ≠ "code") and continuations (fresh:false — agy --continue/--conversation cannot attest
 // a folded tree; only a fresh grounded re-run mints a gate-satisfying receipt).
@@ -46,12 +53,20 @@ import { createHash } from 'node:crypto';
 import { detectBackends } from './detect-backends.mjs';
 import { resolveActivityRecipe, planRecipe, DISPLAY_ALIASES } from './recipes.mjs';
 import { CONFIG_REL, fail, loadConfig } from './orchestration-config.mjs';
+// The NEUTRAL ledger read-core (AD-050): review-state reads the review-ledger ONLY for the degraded
+// exemption, through the neutral core — never review-ledger.mjs (which imports THIS module, the cycle).
+import { resolveLedgerPath, resolveBase, readLedger, filterSegmentRecords, roundSequenceIntact } from './review-ledger-core.mjs';
 
 export const RECEIPTS_BASENAME = 'agent-workflow-review-receipts.jsonl';
 export const PLANS_REL = 'docs/plans';
 const ACTIVITY = 'plan-execution';
 const SLOT = 'review';
 const GIT_MAX_BUFFER = 256 * 1024 * 1024; // a full-tree diff can be large; never truncate silently
+// --await (BUGFREE-3 / AD-049, item (d)) bounds + poll cadence. The default timeout is generous —
+// a real grounded bridge review can take minutes — and every value is overridable (--timeout / the
+// injectable clock) so hermetic tests never spend wall-clock.
+export const DEFAULT_AWAIT_TIMEOUT_S = 900;
+export const AWAIT_POLL_MS = 5000;
 
 // ── git plumbing (read-only queries; injectable for tests) ─────────────────────────
 
@@ -231,6 +246,45 @@ export const backendReceiptStatus = (receipts, backend, fingerprint) => {
   return { state: own.length > 0 ? 'stale' : 'missing', verdict: null, grounded: null, timestamp: null };
 };
 
+// ── the degraded exemption (AD-050): read the review-ledger for a recorded current-tree degrade ────
+
+// degradedExemptSet(args) → the Set of recipe-named backends EXEMPT from --check because the current
+// segment's LATEST round records them degraded at the current tree fingerprint. It MIRRORS review-ledger
+// decideStop's degraded handling: a backend WITHOUT a current grounded code receipt is exempt IFF
+// (i) exactly one plan is in flight (else the loop is ambiguous — the exempt set is empty, NO fail-closed
+// exit-1 arm) AND the ledger reads clean (a readError / malformed line DENIES the exemption, fail-closed);
+// (ii) the segment (activity=plan-execution, loop, base=resolveBase) has >=1 round with an intact
+// sequence; (iii) its LATEST round records THAT backend degraded; (iv) that round's fingerprint equals
+// the CURRENT tree (the degrade attests THIS tree); (v) >=1 NON-degraded recipe-named backend is present
+// with a current grounded receipt (never everyone degraded). It is VERDICT-BLIND — it mirrors only the
+// PRESENCE half of decideStop (nonDegradedReq >= 1), never its 0/0 counts (Decision 7).
+export const degradedExemptSet = ({ records, readError, malformed, base, plans, currentFingerprint, requiredBackends, backends }) => {
+  const empty = new Set();
+  if (plans.length !== 1) return empty; // (i) ambiguous loop → exemption suppressed (no fail-closed exit-1 arm)
+  if (readError || malformed > 0) return empty; // fail-closed: a corrupt ledger denies the exemption
+  if (currentFingerprint == null) return empty;
+  const loop = plans[0].replace(/\.md$/, '');
+  const rounds = filterSegmentRecords(records, { activity: ACTIVITY, loop, base }).filter((r) => r.kind === 'round');
+  if (rounds.length === 0) return empty; // (ii) empty segment → nothing recorded yet
+  if (!roundSequenceIntact(rounds)) return empty; // (ii) corrupt sequence → fail closed
+  const latest = rounds[rounds.length - 1];
+  if (latest.fingerprint !== currentFingerprint) return empty; // (iv) the degrade must attest THIS tree
+  // Mirror decideStop's PRESENCE discipline (review-ledger.mjs): EVERY recipe-named backend must be IN
+  // the latest round (allPresent) — a backend absent from the round reviewed nothing there, so a stray
+  // current receipt for a NON-recorded backend can never justify the exemption (codex R1: else a
+  // degrade-only round `[{agy degraded}]` + any current codex receipt would exempt agy, disagreeing
+  // with review-ledger, whose decideStop fails allPresent on the absent codex).
+  const entryFor = (rb) => latest.backends.find((b) => b.backend === rb);
+  if (!requiredBackends.every((rb) => entryFor(rb) !== undefined)) return empty;
+  const receiptCurrent = new Set(backends.filter((b) => b.state === 'current').map((b) => b.backend));
+  // (v) >=1 non-degraded recipe-named backend PRESENT in the latest round with a current grounded
+  // receipt — never all degraded (mirrors decideStop's nonDegradedReq >= 1, plus review-state's own
+  // "it really reviewed" = a current receipt).
+  if (!requiredBackends.some((rb) => { const e = entryFor(rb); return e && !e.degraded && receiptCurrent.has(rb); })) return empty;
+  // (iii) exempt each recipe-named backend the latest round records degraded.
+  return new Set(requiredBackends.filter((rb) => { const e = entryFor(rb); return e && e.degraded === true; }));
+};
+
 // ── the check + report core ─────────────────────────────────────────────────────────
 
 // buildState({ cwd, env, detect }) → everything both renders need. Pure I/O at the edges.
@@ -257,6 +311,13 @@ export const buildState = ({ cwd, env = process.env, detect = detectBackends } =
   const receiptsPath = resolveReceiptsPath(cwd, env);
   const { receipts, malformed } = receiptsPath ? readReceipts(receiptsPath) : { receipts: [], malformed: 0 };
   const backends = requiredBackends.map((b) => ({ backend: b, ...backendReceiptStatus(receipts, b, fingerprint) }));
+  // The degraded exemption (AD-050): read the review-ledger ONLY here, ONLY for the exemption — the
+  // whole gate never depends on the ledger (a corrupt ledger fails the exemption CLOSED, never a tree
+  // whose receipts independently satisfy the gate; Decision 3). base/ledger locate the current segment.
+  const base = resolveBase(cwd);
+  const ledgerPath = resolveLedgerPath(cwd, env);
+  const { records, malformed: ledgerMalformed, readError: ledgerReadError } = ledgerPath ? readLedger(ledgerPath) : { records: [], malformed: 0 };
+  const degradedExempt = [...degradedExemptSet({ records, readError: ledgerReadError, malformed: ledgerMalformed, base, plans, currentFingerprint: fingerprint, requiredBackends, backends })];
   return {
     resolved,
     configSource,
@@ -268,6 +329,11 @@ export const buildState = ({ cwd, env = process.env, detect = detectBackends } =
     receiptsPath,
     receiptCount: receipts.length,
     malformed,
+    base,
+    ledgerPath,
+    ledgerMalformed: ledgerMalformed ?? 0,
+    ledgerReadError: ledgerReadError ?? null,
+    degradedExempt,
     detectionWarning,
   };
 };
@@ -297,16 +363,31 @@ export const decideCheck = (state) => {
   // cannot fail the gate by itself (a forged/corrupt line must not brick commits), but the check
   // line always names it so a PASS over a partially-corrupt file is visible.
   const malformedNote = state.malformed > 0 ? ` — ${state.malformed} malformed receipt line(s) ignored; inspect ${state.receiptsPath}` : '';
-  const failing = state.backends.filter((b) => b.state !== 'current');
+  // The review-ledger is consulted ONLY for the degraded exemption; a corrupt ledger DENIES it
+  // (fail-closed) but never fails a tree the receipts independently satisfy — surfaced either way
+  // (No-silent-failures; Decision 3).
+  const ledgerNote = state.ledgerReadError
+    ? ` — review ledger unreadable (${state.ledgerReadError}); degraded exemption unavailable (fail-closed) — inspect ${state.ledgerPath}`
+    : state.ledgerMalformed > 0
+      ? ` — review ledger has ${state.ledgerMalformed} malformed line(s); degraded exemption unavailable (fail-closed) — inspect ${state.ledgerPath}`
+      : '';
+  // The degraded exemption (AD-050): a backend recorded degraded for the current tree is excluded from
+  // `failing` (it reviewed nothing to receipt — MIRRORS decideStop excluding a degraded backend). It
+  // stays verdict-blind: the exemption proves the degrade was RECORDED, never that the tree converged.
+  const exempt = new Set(state.degradedExempt);
+  const failing = state.backends.filter((b) => b.state !== 'current' && !exempt.has(b.backend));
   if (failing.length === 0) {
-    return { code: 0, reason: `every recipe-named backend has a fresh grounded receipt for the current tree (${state.requiredBackends.join(' + ')})${malformedNote}` };
+    if (exempt.size === 0) {
+      return { code: 0, reason: `every recipe-named backend has a fresh grounded receipt for the current tree (${state.requiredBackends.join(' + ')})${malformedNote}${ledgerNote}` };
+    }
+    return { code: 0, reason: `every recipe-named backend reviewed the current tree (${state.requiredBackends.join(' + ')}) — degraded-exempt (recorded degraded for the current tree in the review ledger): ${[...exempt].join(', ')}${malformedNote}${ledgerNote}` };
   }
   const parts = failing.map((b) => {
     if (b.state === 'ungrounded') return `${b.backend}: only ungrounded receipts for the current tree — re-run grounded (--facts)`;
     if (b.state === 'stale') return `${b.backend}: receipts exist but none matches the current tree (edited after review) — run a fresh review`;
     return `${b.backend}: no receipt — run its review wrapper`;
   });
-  return { code: 1, reason: `${parts.join('; ')}${malformedNote}` };
+  return { code: 1, reason: `${parts.join('; ')}${malformedNote}${ledgerNote}` };
 };
 
 // ── rendering ───────────────────────────────────────────────────────────────────────
@@ -324,7 +405,11 @@ const formatHuman = (state, check) => {
   else if (state.clean === true) lines.push('  tree: clean (nothing to review)');
   else lines.push(`  tree fingerprint: ${state.fingerprint}`);
   lines.push(`  receipts: ${state.receiptsPath ?? '(unresolvable — no git dir)'} (${state.receiptCount} line(s)${state.malformed ? `, ${state.malformed} malformed — inspect the file` : ''})`);
+  if (state.ledgerReadError) lines.push(`  ⚠ review ledger unreadable (${state.ledgerReadError}) — degraded exemption unavailable`);
+  else if (state.ledgerMalformed) lines.push(`  ⚠ review ledger: ${state.ledgerMalformed} malformed line(s) — degraded exemption unavailable`);
+  const exempt = new Set(state.degradedExempt);
   for (const b of state.backends) {
+    const exemptTag = exempt.has(b.backend) ? ' — degraded-exempt (recorded degraded in the review ledger for the current tree)' : '';
     const detail =
       b.state === 'current'
         ? `current (verdict: ${b.verdict}, grounded, ${b.timestamp ?? '?'})`
@@ -333,7 +418,7 @@ const formatHuman = (state, check) => {
           : b.state === 'stale'
             ? 'stale — no receipt matches the current tree (edited after review)'
             : 'missing — no receipt from this backend';
-    lines.push(`    ${STATE_GLYPH[b.state]} ${b.backend}: ${detail}`);
+    lines.push(`    ${exempt.has(b.backend) ? '⊘' : STATE_GLYPH[b.state]} ${b.backend}: ${detail}${exemptTag}`);
   }
   lines.push(`  check: ${check.code === 0 ? 'PASS' : 'FAIL'} — ${check.reason}`);
   return lines.join('\n');
@@ -352,9 +437,10 @@ presence + verdict + grounding for the CURRENT tree. Plan/diff-mode receipts and
 (fresh:false) are informational-only — they never satisfy the tree check.
 
 --check exits 0/1 per the normative contract in the tool header: 0 for solo / no plan in flight /
-a clean tree / not-a-git-tree / all recipe-named backends receipted-current-and-grounded; 1 when a
-recipe-named backend is missing, stale (edited after review), or grounded:false under
-reviewed/council. Declare it as a project gate by hand (docs/ai/gates.json) or via the
+a clean tree / not-a-git-tree / all recipe-named backends receipted-current-and-grounded OR
+degraded-exempt (a recorded current-tree degrade in the review-ledger for that backend; AD-050); 1 when
+a recipe-named backend is missing, stale (edited after review), or grounded:false under reviewed/council
+AND is not degraded-exempt. Declare it as a project gate by hand (docs/ai/gates.json) or via the
 explicit-consent seeder (tools/seed-gates.mjs) — never without consent.
 
 Read-only: never writes, never commits, never runs a subscription CLI; spawns read-only git queries.
@@ -387,11 +473,74 @@ export const main = (argv, ctx = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) {
-  const r = main(process.argv.slice(2));
+// ── --await: block until every recipe-named backend has receipted the current tree ─────
+// (BUGFREE-3 / AD-049, item (d)). It waits for every recipe-named backend to be SATISFIED — a fresh
+// grounded current-tree receipt, OR (AD-050) the degraded exemption: once a current-tree degrade is
+// RECORDED in the review-ledger, --await stops waiting for that backend and returns READY (before,
+// it waited forever for a receipt that never comes). It inherits the exemption for FREE — it polls
+// the SAME decideCheck(buildState()) `--check` computes. The completion signal is the RECEIPT (i.e.
+// `--check` would PASS), NEVER a process event — a harness "completed" notification fires early and a
+// bridge's output late-flushes, so polling a pid/receipt-file is the durable mechanization of
+// receipts-not-pgrep. Stays read-only (it only re-reads state — now the ledger too, a few KB per
+// tick); the clock is injectable (ctx.now / ctx.sleep / ctx.pollMs) so hermetic tests never spend
+// wall-clock.
+
+const AWAIT_ALLOWED_ARGS = new Set(['--await', '--timeout']);
+
+const parseAwaitTimeoutS = (argv) => {
+  const i = argv.indexOf('--timeout');
+  if (i === -1) return DEFAULT_AWAIT_TIMEOUT_S;
+  const raw = argv[i + 1];
+  if (!raw || !/^\d+$/.test(raw) || Number(raw) < 1) throw fail(2, '--timeout requires a positive integer number of seconds');
+  return Number(raw);
+};
+
+export const mainAwait = async (argv, ctx = {}) => {
+  const cwd = ctx.cwd ?? process.cwd();
+  const env = ctx.env ?? process.env;
+  const detect = ctx.detect ?? detectBackends;
+  const now = ctx.now ?? (() => Date.now());
+  const sleep = ctx.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const pollMs = ctx.pollMs ?? AWAIT_POLL_MS;
+  try {
+    for (let i = 0; i < argv.length; i += 1) {
+      const a = argv[i];
+      if (a === '--timeout') { i += 1; continue; } // its value is consumed by parseAwaitTimeoutS
+      if (!AWAIT_ALLOWED_ARGS.has(a)) throw fail(2, `--await accepts only --timeout <s> (got ${a})`);
+    }
+    const timeoutS = parseAwaitTimeoutS(argv);
+    const timeoutMs = timeoutS * 1000;
+    const start = now();
+    // Poll the SAME normative decision --check computes: ready == `--check` would pass (solo / no
+    // plan / a clean tree / not-a-git-tree all resolve instantly — nothing to await). Re-read state
+    // every poll so a landed receipt (or a tree edit that re-staled one) is seen fresh. The DEADLINE
+    // is checked BEFORE readiness (codex council R2): once elapsed reaches the timeout the await is
+    // over, so a receipt that only lands AT/after the deadline never flips it to READY; and each
+    // sleep is BOUNDED to the remaining time so a full poll interval can never overshoot the timeout.
+    let lastReason = 'no poll completed before the deadline';
+    for (;;) {
+      const elapsed = now() - start;
+      if (elapsed >= timeoutMs) return { code: 1, stdout: '', stderr: `review-state --await: TIMEOUT after ${timeoutS}s — ${lastReason}` };
+      const check = decideCheck(buildState({ cwd, env, detect }));
+      lastReason = check.reason;
+      if (check.code === 0) return { code: 0, stdout: `review-state --await: READY — ${check.reason}`, stderr: '' };
+      await sleep(Math.min(pollMs, timeoutMs - elapsed));
+    }
+  } catch (err) {
+    return { code: err.exitCode ?? 1, stdout: '', stderr: `review-state: ${err.message}` };
+  }
+};
+
+const emitResult = (r) => {
   // Exact writes + a natural exit: process.exit() can truncate unflushed piped stdio (codex R2).
   if (r.stdout) process.stdout.write(r.stdout.endsWith('\n') ? r.stdout : `${r.stdout}\n`);
   if (r.stderr) process.stderr.write(r.stderr.endsWith('\n') ? r.stderr : `${r.stderr}\n`);
   process.exitCode = r.code;
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--await')) mainAwait(argv).then(emitResult);
+  else emitResult(main(argv));
 }

package/tools/run-gates.mjs

@@ -37,6 +37,13 @@ import { spawnSync } from 'node:child_process';
 import { pathToFileURL } from 'node:url';
 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 per-project declaration (strict JSON, hand-editable). cwd-relative — errors show a path the
 // user can open (the orchestration-config CONFIG_REL idiom).
@@ -74,6 +81,9 @@ const USAGE = [
   '--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.',
   `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.',
 ].join('\n');
@@ -174,8 +184,16 @@ 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.
-export const spawnGateViaBash = (cmd, cwd) =>
-  spawnSync('bash', ['-c', cmd], { cwd, encoding: 'utf8', maxBuffer: MAX_GATE_OUTPUT_BYTES });
+// 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 };
+  delete env.NODE_TEST_CONTEXT;
+  return spawnSync('bash', ['-c', cmd], { cwd, env, encoding: 'utf8', maxBuffer: MAX_GATE_OUTPUT_BYTES });
+};
 
 // The command the bash preflight runs before ANY gate: proves bash itself spawns on this host,
 // so "no bash" is one loud exit-6 error up front — never a per-gate spawn-failure cascade.
@@ -188,10 +206,19 @@ 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 }) => {
+export const runGates = (gates, { cwd, spawn = spawnGateViaBash, now = Date.now, log = console.log, credit = null }) => {
   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;
@@ -271,6 +298,7 @@ export const runCli = (argv, deps = {}) => {
     now,
     record = recordGateRun,
     fingerprint = computeTreeFingerprint,
+    foldCredit = foldSuiteCredit,
   } = deps;
   try {
     const opts = parseArgs(argv);
@@ -305,7 +333,18 @@ export const runCli = (argv, deps = {}) => {
       return EXIT.noBash;
     }
     const fingerprintBefore = opts.record ? fingerprint(projectDir) : null;
-    const results = runGates(selected, { cwd: projectDir, spawn, log, now });
+    // (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);
+    }
+    const results = runGates(selected, { cwd: projectDir, spawn, log, now, credit });
     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

package/tools/sarif.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// sarif.mjs — a dependency-free SARIF (2.1.0) reader for the OPTIONAL advisory findings surface
+// (BUGFREE-3, AD-049, step 1.4 — the reviewdog pattern). Findings are ADVISORY ONLY: they are NEVER
+// recorded on a fold run record (SARIF stays entirely out of the fold result schema — no v4 quartet
+// coupling, no sequencing dependency) and NEVER gate-blocking (fold-completeness --check never reads
+// SARIF). A malformed SARIF fails the advisory READ loudly (a nonzero exit on the advisory verb), but
+// the fold gate — fold-completeness --check — is unaffected. No side effects on import; Node >= 18.
+
+export const SARIF_STOP = 'SARIF_STOP';
+const stop = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'SarifStop', code: SARIF_STOP });
+
+// parseSarif(text) → { findings: [{ ruleId, level, message, file, line }] }. THROWS on a malformed
+// SARIF (not JSON, or no runs[] array) — the advisory read is LOUD, never a silent empty result. A
+// well-formed run with zero results yields an empty findings list (a clean advisory).
+export const parseSarif = (text) => {
+  let doc;
+  try {
+    doc = JSON.parse(text);
+  } catch (err) {
+    throw stop(`SARIF is not valid JSON (${err.message})`);
+  }
+  if (!doc || typeof doc !== 'object' || !Array.isArray(doc.runs)) {
+    throw stop('SARIF has no runs[] array — not a SARIF 2.1.0 document');
+  }
+  const findings = [];
+  for (const run of doc.runs) {
+    const results = Array.isArray(run?.results) ? run.results : [];
+    for (const r of results) {
+      const loc = r?.locations?.[0]?.physicalLocation ?? {};
+      findings.push({
+        ruleId: typeof r?.ruleId === 'string' ? r.ruleId : '(no rule)',
+        level: typeof r?.level === 'string' ? r.level : 'warning',
+        message: typeof r?.message?.text === 'string' ? r.message.text : '',
+        file: typeof loc?.artifactLocation?.uri === 'string' ? loc.artifactLocation.uri : null,
+        line: Number.isInteger(loc?.region?.startLine) ? loc.region.startLine : null,
+      });
+    }
+  }
+  return { findings };
+};
+
+// renderSarifFindings(findings) → a human advisory block (one line per finding). Empty → a stated
+// "no findings" note. Always advisory — the caller never blocks a gate on this.
+export const renderSarifFindings = (findings) => {
+  if (findings.length === 0) return 'SARIF advisory: no findings (advisory only — never gate-blocking).';
+  const lines = [`SARIF advisory: ${findings.length} finding(s) (advisory only — never gate-blocking):`];
+  for (const f of findings) {
+    const at = f.file ? `${f.file}${f.line != null ? `:${f.line}` : ''}` : '(no location)';
+    lines.push(`  [${f.level}] ${f.ruleId} — ${at}${f.message ? ` — ${f.message}` : ''}`);
+  }
+  return lines.join('\n');
+};

package/tools/verification-profile.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+// verification-profile.mjs — read-only schema/read core for the per-project VERIFICATION PROFILE
+// (docs/ai/verification-profile.json), the language-independence contract (BUGFREE-3, AD-049).
+// Companion read-core to the fold-completeness runner. NO writer — the runner is the sole
+// tree-toucher. An ABSENT profile reproduces today's exact behaviour (V8 coverage + node:test
+// TAP-on-stdout); the profile only generalizes the coverage SOURCE, the single-test RESULT FORMAT,
+// and an optional SARIF path — coverage/probe INPUTS, never the suite command.
+//
+// The suite COMMAND is deliberately NOT a profile field: it stays the docs/ai/gates.json unit-tests
+// cmd so the fold run and the unit-tests gate share command-identity (the (a) suite-evidence credit
+// requires the SAME command).
+//
+// Path safety (Decision 4; grounding.mjs assertScratchDestination model): every profile-declared
+// artifact path MUST be gitignored or outside the work tree, checked on the REALPATH (a symlink leaf
+// is refused). An in-tree, not-ignored file the suite writes would move the review fingerprint the
+// run binds to; a symlinked path could route the write onto a tracked file. validateProfile fails
+// CLOSED on any such path.
+//
+// Dependency-free, Node >= 18. No side effects on import.
+
+import { readFileSync, lstatSync, realpathSync } from 'node:fs';
+import { join, resolve, relative, isAbsolute, dirname, basename } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fail } from './orchestration-config.mjs';
+
+// cwd-relative so error prefixes show a path the user can open, never an absolute temp/host path.
+export const PROFILE_REL = 'docs/ai/verification-profile.json';
+export const PROFILE_SCHEMA_VERSION = 1;
+
+export const COVERAGE_KINDS = new Set(['v8', 'lcov']);
+export const RESULT_FORMATS = new Set(['tap-stdout', 'tap-file', 'junit-xml']);
+// File-based formats must be TOLD where to write, so their argv carries {resultPath} (the runner
+// substitutes a fresh out-of-tree path per probe and reads THAT back). tap-stdout reads stdout.
+export const FILE_BASED_FORMATS = new Set(['tap-file', 'junit-xml']);
+export const RESULT_PATH_TOKEN = '{resultPath}';
+export const FILE_TOKEN = '{file}';
+export const PATTERN_TOKEN = '{pattern}';
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
+const isNonEmptyStringArray = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => typeof x === 'string');
+
+// Unknown-key-fails-closed. Returns a reason string or null.
+const unknownKeyReason = (obj, allowed, where) => {
+  for (const k of Object.keys(obj)) {
+    if (!allowed.has(k)) return `${where}: unknown key "${k}" (allowed: ${[...allowed].join(', ')})`;
+  }
+  return null;
+};
+
+const COVERAGE_KEYS = new Set(['kind', 'lcovPath']);
+const SINGLE_TEST_KEYS = new Set(['argv', 'resultFormat']);
+const FINDINGS_KEYS = new Set(['sarifPath']);
+const TOP_KEYS = new Set(['_README', 'schema', 'coverage', 'singleTest', 'findings']);
+
+const defaultGitLine = (args, cwd) => {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8', windowsHide: true });
+  return r.error || r.status == null ? null : { status: r.status, stdout: r.stdout ?? '' };
+};
+
+// Reason string when the declared path is unsafe, else null. Unsafe = a symlink leaf, or an
+// in-work-tree path that is NOT gitignored (writing there moves the review fingerprint; a tracked
+// path reads as not-ignored too). Checked on the REAL destination (parent realpath-resolved) so a
+// symlinked parent cannot route an "outside/ignored" path back onto a tracked file. Outside any git
+// tree → safe. deps.{gitLine,lstat,realpath} are injectable for hermetic tests.
+export const declaredPathUnsafeReason = (label, p, cwd, deps = {}) => {
+  const gitLine = deps.gitLine ?? defaultGitLine;
+  const lstat = deps.lstat ?? lstatSync;
+  const realpath = deps.realpath ?? realpathSync;
+  if (!isNonEmptyString(p)) return `${label} must be a non-empty string`;
+  const lexical = isAbsolute(p) ? p : resolve(cwd, p);
+  let leaf = null;
+  try {
+    leaf = lstat(lexical);
+  } catch {
+    leaf = null; // absent → a fresh file; the parent is realpath-checked below
+  }
+  if (leaf && leaf.isSymbolicLink()) {
+    return `${label} "${p}" is a symlink — refused (the write would follow it onto another file; name the real path)`;
+  }
+  let realParent;
+  try {
+    realParent = realpath(dirname(lexical));
+  } catch {
+    return `${label} "${p}" parent directory does not exist — create the (gitignored) output dir first, or fix the path`;
+  }
+  const full = join(realParent, basename(lexical));
+  const top = gitLine(['rev-parse', '--show-toplevel'], cwd);
+  if (top == null || top.status !== 0) return null; // not a git work tree → not fingerprint-relevant
+  // Realpath the repo root too so both sides of relative() are physical — a checkout opened via a
+  // symlink must not misclassify an in-tree path as OUTSIDE. Fail CLOSED if it can't resolve.
+  let root;
+  try {
+    root = realpath(top.stdout.replace(/\r?\n$/, ''));
+  } catch {
+    return `${label} "${p}" — cannot resolve the repo root's real path (fail closed)`;
+  }
+  const rel = relative(root, full);
+  if (rel.startsWith('..') || isAbsolute(rel)) return null; // outside the work tree → safe
+  const ignored = gitLine(['check-ignore', '-q', '--', rel], root);
+  if (ignored == null || ignored.status !== 0) {
+    return `${label} "${p}" is an in-tree path that is not gitignored — the suite writing there would move the review fingerprint the run binds to; gitignore it (or place it outside the repo)`;
+  }
+  return null;
+};
+
+// validateProfile(obj, { cwd, gitLine, lstat, realpath }?) → { ok, reason }. Strict schema first;
+// then, ONLY when `cwd` is supplied, the declared-path safety check (Decision 4). A pure-schema unit
+// test omits `cwd`; loadProfile passes it so malformed OR unsafe both fail closed.
+export const validateProfile = (obj, ctx = {}) => {
+  if (!isPlainObject(obj)) return { ok: false, reason: `${PROFILE_REL}: must be a JSON object` };
+  const topUnknown = unknownKeyReason(obj, TOP_KEYS, PROFILE_REL);
+  if (topUnknown) return { ok: false, reason: topUnknown };
+  if (obj.schema !== PROFILE_SCHEMA_VERSION) return { ok: false, reason: `${PROFILE_REL}: schema must be ${PROFILE_SCHEMA_VERSION}` };
+  if (obj._README !== undefined && typeof obj._README !== 'string') return { ok: false, reason: `${PROFILE_REL}: "_README" must be a string` };
+
+  // coverage (optional; absent → V8). lcovPath REQUIRED iff lcov, forbidden otherwise.
+  if (obj.coverage !== undefined) {
+    if (!isPlainObject(obj.coverage)) return { ok: false, reason: `${PROFILE_REL}: coverage must be an object` };
+    const ck = unknownKeyReason(obj.coverage, COVERAGE_KEYS, `${PROFILE_REL}: coverage`);
+    if (ck) return { ok: false, reason: ck };
+    if (!COVERAGE_KINDS.has(obj.coverage.kind)) return { ok: false, reason: `${PROFILE_REL}: coverage.kind must be one of ${[...COVERAGE_KINDS].join(', ')}` };
+    if (obj.coverage.kind === 'lcov') {
+      if (!isNonEmptyString(obj.coverage.lcovPath)) return { ok: false, reason: `${PROFILE_REL}: coverage.lcovPath (a non-empty path) is required when coverage.kind is "lcov"` };
+    } else if (obj.coverage.lcovPath !== undefined) {
+      return { ok: false, reason: `${PROFILE_REL}: coverage.lcovPath is only valid when coverage.kind is "lcov"` };
+    }
+  }
+
+  // singleTest (optional; absent → default node:test argv + tap-stdout). argv must carry {file} +
+  // {pattern}; a file-based resultFormat additionally requires {resultPath}.
+  if (obj.singleTest !== undefined) {
+    if (!isPlainObject(obj.singleTest)) return { ok: false, reason: `${PROFILE_REL}: singleTest must be an object` };
+    const sk = unknownKeyReason(obj.singleTest, SINGLE_TEST_KEYS, `${PROFILE_REL}: singleTest`);
+    if (sk) return { ok: false, reason: sk };
+    if (!isNonEmptyStringArray(obj.singleTest.argv)) return { ok: false, reason: `${PROFILE_REL}: singleTest.argv must be a non-empty array of strings` };
+    const argvJoined = obj.singleTest.argv.join(' ');
+    if (!argvJoined.includes(FILE_TOKEN)) return { ok: false, reason: `${PROFILE_REL}: singleTest.argv must carry a ${FILE_TOKEN} placeholder (the runner substitutes the test file)` };
+    if (!argvJoined.includes(PATTERN_TOKEN)) return { ok: false, reason: `${PROFILE_REL}: singleTest.argv must carry a ${PATTERN_TOKEN} placeholder (the runner substitutes the test-name pattern)` };
+    const rf = obj.singleTest.resultFormat;
+    if (rf !== undefined && !RESULT_FORMATS.has(rf)) return { ok: false, reason: `${PROFILE_REL}: singleTest.resultFormat must be one of ${[...RESULT_FORMATS].join(', ')}` };
+    if (FILE_BASED_FORMATS.has(rf) && !argvJoined.includes(RESULT_PATH_TOKEN)) {
+      return { ok: false, reason: `${PROFILE_REL}: singleTest.resultFormat "${rf}" is file-based — singleTest.argv must carry a ${RESULT_PATH_TOKEN} placeholder (the runner substitutes a fresh out-of-tree result path per probe)` };
+    }
+  }
+
+  // findings (optional; an empty object is valid — no SARIF path declared).
+  if (obj.findings !== undefined) {
+    if (!isPlainObject(obj.findings)) return { ok: false, reason: `${PROFILE_REL}: findings must be an object` };
+    const fk = unknownKeyReason(obj.findings, FINDINGS_KEYS, `${PROFILE_REL}: findings`);
+    if (fk) return { ok: false, reason: fk };
+    if (obj.findings.sarifPath !== undefined && !isNonEmptyString(obj.findings.sarifPath)) {
+      return { ok: false, reason: `${PROFILE_REL}: findings.sarifPath must be a non-empty string when present` };
+    }
+  }
+
+  // Declared-path safety — only when a cwd is supplied (Decision 4).
+  if (ctx.cwd != null) {
+    const deps = { gitLine: ctx.gitLine, lstat: ctx.lstat, realpath: ctx.realpath };
+    if (obj.coverage?.kind === 'lcov') {
+      const r = declaredPathUnsafeReason('coverage.lcovPath', obj.coverage.lcovPath, ctx.cwd, deps);
+      if (r) return { ok: false, reason: `${PROFILE_REL}: ${r}` };
+    }
+    if (obj.findings?.sarifPath !== undefined) {
+      const r = declaredPathUnsafeReason('findings.sarifPath', obj.findings.sarifPath, ctx.cwd, deps);
+      if (r) return { ok: false, reason: `${PROFILE_REL}: ${r}` };
+    }
+  }
+  return { ok: true };
+};
+
+// resolvers — env WINS over the profile (ad-hoc override precedence, Decision 3)
+
+export const resolveCoverage = (profile) => {
+  const kind = profile?.coverage?.kind ?? 'v8';
+  return { kind, lcovPath: kind === 'lcov' ? profile.coverage.lcovPath : null };
+};
+
+// argv precedence: AW_FOLD_BOUND_CMD (applied in the runner's resolveBoundArgv, keeping the
+// malformed-override refusal one home) > profile.singleTest.argv > built-in default. This resolver
+// returns the PROFILE view only: argv = the profile template or null → runner default.
+export const resolveSingleTest = (profile) => ({
+  argv: profile?.singleTest?.argv ?? null,
+  resultFormat: profile?.singleTest?.resultFormat ?? 'tap-stdout',
+});
+
+export const resolveSarifPath = (profile) => profile?.findings?.sarifPath ?? null;
+
+// IO — config errors → loud fail(1); an absent FILE → defaults path, NOT an error
+
+// loadProfile(cwd, deps?) → { profile, source }. Absent FILE → { profile: null, source: 'none' }.
+// A directory / dangling symlink / permission error is PRESENT-but-unreadable → loud fail(1), never
+// silently treated as absent. Malformed JSON, schema-invalid, or an unsafe declared path → fail(1).
+export const loadProfile = (cwd, deps = {}) => {
+  const readFile = deps.readFile ?? readFileSync;
+  const lstat = deps.lstat ?? lstatSync;
+  const full = join(cwd, PROFILE_REL);
+  try {
+    lstat(full);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { profile: null, source: 'none' };
+    throw fail(1, `${PROFILE_REL}: unreadable (${(err && err.code) || (err && err.message) || err})`);
+  }
+  let raw;
+  try {
+    raw = readFile(full, 'utf8');
+  } catch (err) {
+    throw fail(1, `${PROFILE_REL}: unreadable (${(err && err.code) || (err && err.message) || err})`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw fail(1, `${PROFILE_REL}: malformed JSON (${err.message})`);
+  }
+  const v = validateProfile(parsed, { cwd, gitLine: deps.gitLine, lstat: deps.lstat, realpath: deps.realpath });
+  if (!v.ok) throw fail(1, v.reason);
+  return { profile: parsed, source: PROFILE_REL };
+};