@sabaiway/agent-workflow-kit 1.37.0 → 1.38.0

package/tools/fold-completeness.mjs

@@ -14,20 +14,35 @@
 // here). The gate is plan-EXECUTION-scoped, filtered to the in-flight plan's filename stem:
 //   exit 0  when the resolved plan-execution.review recipe is solo (configured, or degraded there);
 //           when no plan is in flight; when the tree is clean; when the cwd is not a git work tree;
-//           and when the in-flight plan-execution loop has a CURRENT run record whose BOTH bindings
-//           match — the tree fingerprint AND the sorted fixable-bug testId set recorded in the run —
-//           with every bound testId resolvable + baseline-green, 0 uncovered changed lines, 0 changed
-//           unsupported-source files, and the reserved EMPTY mutation shape (v1 ships no mutation).
+//           and when the in-flight plan-execution loop has a CURRENT run record (kind-aware: the
+//           latest RUN, never a later red-probe) whose BOTH bindings match — the tree fingerprint AND
+//           the sorted fixable-bug testId set recorded in the run — with, per bound testId: an
+//           N/N-green probe (D4), an observed-red receipt in this loop (Approach-1.i), that receipt
+//           PRECEDING the latest run in ledger order (anti-post-hoc), and content CUSTODY — the run's
+//           recorded test-file hash equals the latest custody-eligible red-probe hash on that file
+//           (eligible = the receipt's own testId is bound AND it precedes the run, D5); plus 0
+//           uncovered changed lines, 0 changed unsupported-source files, a recorded tamper surface
+//           with every tampered test-surface file covered by a recorded oracle-change override
+//           (review ledger v3), and the reserved EMPTY mutation shape (no mutation ships). A
+//           recorded red-proof override waives the receipt + custody proof for exactly the testId
+//           it names (D7) — never the N/N-green requirement, never QUARANTINE.
 //   exit 1  for any DIRTY in-flight plan-execution loop lacking such a current run record — including
-//           the stale-fingerprint case (a tree edit moves the fingerprint) and the same-fingerprint/
-//           new-testId case (a triage recorded after the run moves the bound-testId set, Decision 9) —
-//           or a run naming an unresolvable/red-baseline bound test, an uncovered changed line, a
-//           changed unsupported-source file, or ANY mutation data (v1 ships no mutation — such a record
-//           was not produced by this runner version; fail closed); when MORE THAN ONE plan is in
-//           flight (ambiguous loop id). Fail-CLOSED (unknown state, never a fail-open pass) on a
-//           detector failure, an unreadable/malformed result or review ledger, or a corrupt run set —
-//           the only detector-independent green is an EXPLICIT configured solo. Changed OUT-OF-DOMAIN
-//           files (docs/config the suite does not execute) are LOUDLY listed but never gate-blocking
+//           the stale-fingerprint case (a tree edit moves the fingerprint), the same-fingerprint/
+//           new-testId case (a triage recorded after the run moves the bound-testId set, Decision 9),
+//           and a schema-1 (or tamper-less) record as the loop's latest run (an older runner; D2) —
+//           or a tampered test-surface file (a removed/modified line in a pre-existing test file,
+//           or a deleted one — the union of test-classified paths and bound-testId file halves)
+//           not covered by a recorded oracle-change override, a run naming an unresolvable bound
+//           test, a QUARANTINED bound
+//           test (mixed or timed-out probe runs — never an N/N verdict, never converted, no override
+//           lane; D4), a red-baseline bound test, a green bound test with NO observed-red receipt /
+//           a post-hoc receipt / broken custody (D5), an uncovered changed line, a changed
+//           unsupported-source file, or ANY mutation data (no mutation ships — such a record was not
+//           produced by this runner; fail closed); when MORE THAN ONE plan is in flight (ambiguous
+//           loop id). Fail-CLOSED (unknown state, never a fail-open pass) on a detector failure, an
+//           unreadable/malformed result or review ledger, or a corrupt run set — the only
+//           detector-independent green is an EXPLICIT configured solo. Changed OUT-OF-DOMAIN files
+//           (docs/config the suite does not execute) are LOUDLY listed but never gate-blocking
 //           (Decision 5): guarding what the tool cannot assess with a red gate is a pretend-mechanism.
 //
 // HONEST residuals (accepted, documented — exactly like review-state's / review-ledger's): coverage
@@ -50,10 +65,17 @@ import { detectBackends } from './detect-backends.mjs';
 import { resolveActivityRecipe, planRecipe, DISPLAY_ALIASES } from './recipes.mjs';
 import { CONFIG_REL, fail, loadConfig } from './orchestration-config.mjs';
 import { computeTreeFingerprint, isTreeClean, plansInFlight } from './review-state.mjs';
-import { resolveLedgerPath, readLedger, filterLoopRecords } from './review-ledger.mjs';
+import { resolveLedgerPath, readLedger, filterLoopRecords, collectOverrides, isWellFormedTestId, splitTestId } from './review-ledger.mjs';
 
 export const RESULTS_BASENAME = 'agent-workflow-fold-completeness.jsonl';
-export const RESULT_SCHEMA_VERSION = 1;
+// SCHEMA v2 (BUGFREE-1 / AD-047): records gain a kind discriminator — `run` (the fold-completeness
+// run, now with per-testId rerun counts + the test file's content hash) | `red-probe` (the
+// observed-red receipt --red mints). RESULT_SCHEMA_VERSION is what the WRITER emits; the reader
+// tolerates every SUPPORTED version under its own per-version rules (the review-ledger v1→v2
+// precedent), so v1 ledgers never retroactively become malformed — but a v1 record as the loop's
+// LATEST run fails the gate with a named re-run reason (D2).
+export const RESULT_SCHEMA_VERSION = 2;
+export const SUPPORTED_RESULT_SCHEMAS = new Set([1, 2]);
 const ACTIVITY = 'plan-execution';
 const SLOT = 'review';
 
@@ -96,37 +118,109 @@ const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
 const isNonNegInt = (v) => Number.isInteger(v) && v >= 0;
 const isStringArray = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string');
 
-// validateRunRecord(obj) → { ok, reason }. The `reason` names the exact failed check so the
-// malformed-line surface and the per-check named tests can assert it. Mutation is reserved and must
-// stay the empty shape in v1 (the mutation half is shelved); the schema carries the fields so a
-// record validates uniformly and decideCheck enforces the exact reserved shape.
-export const validateRunRecord = (obj) => {
-  if (!isPlainObject(obj)) return { ok: false, reason: 'not an object' };
-  if (obj.schema !== RESULT_SCHEMA_VERSION) return { ok: false, reason: `schema must be ${RESULT_SCHEMA_VERSION}` };
-  if (!isNonEmptyString(obj.loop)) return { ok: false, reason: 'missing loop' };
-  if (!(obj.fingerprint === null || isNonEmptyString(obj.fingerprint))) return { ok: false, reason: 'fingerprint must be null or a non-empty string' };
-  if (!isStringArray(obj.boundTestIds)) return { ok: false, reason: 'boundTestIds must be an array of strings' };
-  if (!Array.isArray(obj.testIds)) return { ok: false, reason: 'testIds must be an array' };
+const HASH_RE = /^[0-9a-f]{64}$/; // sha-256 hex — the content-custody hash shape
+
+// The shared record frame (both versions, both kinds).
+const validateFrame = (obj) => {
+  if (!isNonEmptyString(obj.loop)) return 'missing loop';
+  if (!(obj.fingerprint === null || isNonEmptyString(obj.fingerprint))) return 'fingerprint must be null or a non-empty string';
+  if (!isNonEmptyString(obj.timestamp)) return 'missing timestamp';
+  return null;
+};
+
+// A v1 per-testId probe entry (single-run booleans — the AD-046 shape, tolerated read-only).
+const validateV1Entry = (t) => {
+  if (!isPlainObject(t) || !isNonEmptyString(t.id)) return 'each testId entry needs an id';
+  if (typeof t.resolvable !== 'boolean' || typeof t.baselineGreen !== 'boolean') return `testId ${t.id} needs boolean resolvable + baselineGreen`;
+  if (!isNonNegInt(t.executed)) return `testId ${t.id} executed must be a non-negative integer`;
+  return null;
+};
+
+// A v2 per-testId probe entry: rerun counts (the D4 evidence) + the test file's content hash (the
+// D5 custody anchor) + the derived booleans, VALIDATED consistent with the counts so a forged
+// verdict cannot ride beside honest-looking evidence.
+const validateV2Entry = (t) => {
+  if (!isPlainObject(t) || !isNonEmptyString(t.id)) return 'each testId entry needs an id';
+  if (!isNonNegInt(t.executed)) return `testId ${t.id} executed must be a non-negative integer`;
+  if (!(Number.isInteger(t.runs) && t.runs >= 1)) return `testId ${t.id} runs must be a positive integer`;
+  if (!isNonNegInt(t.greens) || !isNonNegInt(t.reds) || !isNonNegInt(t.timeouts)) return `testId ${t.id} rerun counts (greens/reds/timeouts) must be non-negative integers`;
+  if (t.greens + t.reds + t.timeouts > t.runs) return `testId ${t.id} rerun counts exceed runs`;
+  // A resolved run means at least one matched (executed) test result — greens/reds with executed=0
+  // is a forged N/N verdict carrying zero-match evidence (codex R1, BUGFREE-1 live loop).
+  if (t.greens + t.reds > 0 && t.executed < 1) return `testId ${t.id} executed must be positive when a run resolved (greens+reds > 0)`;
+  if (!(t.fileHash === null || (typeof t.fileHash === 'string' && HASH_RE.test(t.fileHash)))) return `testId ${t.id} fileHash must be null or a 64-hex content hash`;
+  if (t.resolvable !== (t.greens + t.reds === t.runs)) return `testId ${t.id} resolvable must equal (greens + reds === runs)`;
+  if (t.baselineGreen !== (t.greens === t.runs)) return `testId ${t.id} baselineGreen must equal (greens === runs)`;
+  return null;
+};
+
+// The run-record body shared by v1 and v2 (surface classes, coverage, reserved mutation, budgets);
+// the per-testId entry rule is the per-version part.
+const validateRunBody = (obj, validateEntry) => {
+  if (!isStringArray(obj.boundTestIds)) return 'boundTestIds must be an array of strings';
+  if (!Array.isArray(obj.testIds)) return 'testIds must be an array';
   for (const t of obj.testIds) {
-    if (!isPlainObject(t) || !isNonEmptyString(t.id)) return { ok: false, reason: 'each testId entry needs an id' };
-    if (typeof t.resolvable !== 'boolean' || typeof t.baselineGreen !== 'boolean') return { ok: false, reason: `testId ${t.id} needs boolean resolvable + baselineGreen` };
-    if (!isNonNegInt(t.executed)) return { ok: false, reason: `testId ${t.id} executed must be a non-negative integer` };
+    const r = validateEntry(t);
+    if (r) return r;
   }
-  if (!isStringArray(obj.unsupported)) return { ok: false, reason: 'unsupported must be an array of strings' };
-  if (!isStringArray(obj.outOfDomain)) return { ok: false, reason: 'outOfDomain must be an array of strings' };
-  if (!isPlainObject(obj.coverage) || !Array.isArray(obj.coverage.uncoveredChanged)) return { ok: false, reason: 'coverage.uncoveredChanged must be an array' };
+  if (!isStringArray(obj.unsupported)) return 'unsupported must be an array of strings';
+  if (!isStringArray(obj.outOfDomain)) return 'outOfDomain must be an array of strings';
+  if (!isPlainObject(obj.coverage) || !Array.isArray(obj.coverage.uncoveredChanged)) return 'coverage.uncoveredChanged must be an array';
   for (const u of obj.coverage.uncoveredChanged) {
-    if (!isPlainObject(u) || !isNonEmptyString(u.file)) return { ok: false, reason: 'each uncoveredChanged entry needs a file' };
-    if (!(u.line === null || (Number.isInteger(u.line) && u.line >= 1))) return { ok: false, reason: `uncoveredChanged ${u.file} line must be null or an integer >= 1` };
+    if (!isPlainObject(u) || !isNonEmptyString(u.file)) return 'each uncoveredChanged entry needs a file';
+    if (!(u.line === null || (Number.isInteger(u.line) && u.line >= 1))) return `uncoveredChanged ${u.file} line must be null or an integer >= 1`;
   }
   const m = obj.mutation;
   if (!isPlainObject(m) || !isNonNegInt(m.total) || !isNonNegInt(m.killed) || !Array.isArray(m.survived) || !isNonNegInt(m.skipped)) {
-    return { ok: false, reason: 'mutation must be { total, killed, survived[], skipped, killSetBasis }' };
+    return 'mutation must be { total, killed, survived[], skipped, killSetBasis }';
   }
-  if (!(m.killSetBasis === null || isNonEmptyString(m.killSetBasis))) return { ok: false, reason: 'mutation.killSetBasis must be null or a non-empty string' };
-  if (!isPlainObject(obj.budgets)) return { ok: false, reason: 'budgets must be an object' };
-  if (!isNonEmptyString(obj.timestamp)) return { ok: false, reason: 'missing timestamp' };
-  return { ok: true };
+  if (!(m.killSetBasis === null || isNonEmptyString(m.killSetBasis))) return 'mutation.killSetBasis must be null or a non-empty string';
+  if (!isPlainObject(obj.budgets)) return 'budgets must be an object';
+  return null;
+};
+
+// The red-probe receipt (v2 only): the machine attestation that testId FAILED on N/N runs at the
+// recorded content hash. Minted only by the runner's --red verb; reds must equal runs — a receipt
+// never records anything but an honest N/N red (refusals write nothing).
+const validateRedProbe = (obj) => {
+  if (!isWellFormedTestId(obj.testId)) return 'red-probe testId must be "<test-file>#<test-name-pattern>" (a "#" separator, both halves non-empty)';
+  if (!(typeof obj.fileHash === 'string' && HASH_RE.test(obj.fileHash))) return 'red-probe fileHash must be a 64-hex content hash';
+  if (!(Number.isInteger(obj.runs) && obj.runs >= 1)) return 'red-probe runs must be a positive integer';
+  if (obj.reds !== obj.runs) return 'red-probe reds must equal runs (a receipt attests N/N observed red)';
+  return null;
+};
+
+// validateRunRecord(obj) → { ok, reason }. Per-version, per-kind (D2): v1 records (no kind) keep the
+// AD-046 single-run rules; v2 records carry the kind discriminator. The `reason` names the exact
+// failed check so the malformed-line surface and the per-check named tests can assert it. Mutation
+// stays the reserved empty shape (the mutation half is shelved); the schema carries the fields so a
+// record validates uniformly and decideCheck enforces the exact reserved shape.
+export const validateRunRecord = (obj) => {
+  if (!isPlainObject(obj)) return { ok: false, reason: 'not an object' };
+  if (!SUPPORTED_RESULT_SCHEMAS.has(obj.schema)) return { ok: false, reason: `schema must be one of ${[...SUPPORTED_RESULT_SCHEMAS].join(', ')}` };
+  const frame = validateFrame(obj);
+  if (frame) return { ok: false, reason: frame };
+  if (obj.schema === 1) {
+    if (obj.kind !== undefined) return { ok: false, reason: 'a v1 record must not carry kind (kind is a v2 discriminator)' };
+    const r = validateRunBody(obj, validateV1Entry);
+    return r ? { ok: false, reason: r } : { ok: true };
+  }
+  if (obj.kind === 'run') {
+    const r = validateRunBody(obj, validateV2Entry);
+    if (r) return { ok: false, reason: r };
+    // The tamper surface (Phase 2.2) is OPTIONAL on read — a record written by the pre-tamper v2
+    // runner stays readable (never retroactively malformed); the GATE handles the staleness. When
+    // present, the shape is exact.
+    if (obj.tamper !== undefined && (!isPlainObject(obj.tamper) || !isStringArray(obj.tamper.tampered))) {
+      return { ok: false, reason: 'tamper.tampered must be an array of strings (when the tamper surface is recorded)' };
+    }
+    return { ok: true };
+  }
+  if (obj.kind === 'red-probe') {
+    const r = validateRedProbe(obj);
+    return r ? { ok: false, reason: r } : { ok: true };
+  }
+  return { ok: false, reason: `kind must be "run" or "red-probe" (got ${JSON.stringify(obj.kind)})` };
 };
 
 // readResults(path) → { records, malformed, malformedReasons, readError }. Absent file → empty (no run
@@ -157,9 +251,38 @@ export const readResults = (path, readFile = readFileSync) => {
   return { records, malformed: malformedReasons.length, malformedReasons };
 };
 
-// filterLoopResults(records, loop) → the run records of ONE loop, order preserved (latest is last).
+// filterLoopResults(records, loop) → the result records of ONE loop (both kinds), order preserved
+// (latest is last).
 export const filterLoopResults = (records, loop) => records.filter((r) => r.loop === loop);
 
+// ── kind-aware selectors (shared: the runner and the checker read the ledger through THESE) ──────
+
+// A v1 record IS a run (the kindless AD-046 shape); a v2 record is a run only under kind:"run".
+export const isRunRecord = (r) => r.schema === 1 || r.kind === 'run';
+export const isRedProbeRecord = (r) => r.schema >= 2 && r.kind === 'red-probe';
+
+// latestRunRecord(loopRecords) → { record, index } | null over ONE loop's ordered records. Kind-aware
+// (codex R2): a red-probe appended after a run must never be read as the loop's "latest run" — the
+// index anchors the D5/order checks (a custody-eligible receipt PRECEDES the latest run).
+export const latestRunRecord = (loopRecords) => {
+  for (let i = loopRecords.length - 1; i >= 0; i -= 1) {
+    if (isRunRecord(loopRecords[i])) return { record: loopRecords[i], index: i };
+  }
+  return null;
+};
+
+// probeVerdict(entry) → 'green' | 'red' | 'quarantine' | 'unresolvable' — the D4 verdict algebra,
+// the SINGLE home shared by the runner (--red mints only on 'red') and the checker (the gate passes
+// only on 'green'). RED/GREEN are strict N/N verdicts; any timeout, mixed outcome, or partial
+// resolution is QUARANTINE — it never converts and has no override lane (a flaky pin proves
+// nothing — replace the test). Zero resolved runs (or a defensive runs=0) reads unresolvable.
+export const probeVerdict = (t) => {
+  const unresolved = t.runs - t.greens - t.reds - t.timeouts;
+  if (unresolved >= t.runs) return 'unresolvable';
+  if (t.timeouts > 0 || unresolved > 0 || (t.greens > 0 && t.reds > 0)) return 'quarantine';
+  return t.greens === t.runs ? 'green' : 'red';
+};
+
 // ── the check + report core ─────────────────────────────────────────────────────────────────────
 
 // buildFoldState({ cwd, env, detect }) → everything both renders need. Pure I/O at the edges; every
@@ -230,9 +353,15 @@ export const decideCheck = (state) => {
   if (state.reviewMalformed > 0) return { code: 1, reason: `the review ledger has ${state.reviewMalformed} malformed line(s) — failing closed; inspect ${state.reviewPath}` };
 
   const loop = state.plans[0].replace(/\.md$/, '');
-  const runs = filterLoopResults(state.resultRecords, loop);
-  if (runs.length === 0) return { code: 1, reason: `dirty plan-execution loop "${loop}" but no fold-completeness run recorded — run fold-completeness-run.mjs` };
-  const latest = runs[runs.length - 1];
+  const loopResults = filterLoopResults(state.resultRecords, loop);
+  const sel = latestRunRecord(loopResults);
+  if (sel == null) return { code: 1, reason: `dirty plan-execution loop "${loop}" but no fold-completeness run recorded — run fold-completeness-run.mjs` };
+  const latest = sel.record;
+  // D2 — a v1 record as the loop's latest run: the gate now needs the v2 evidence (rerun counts +
+  // custody hashes), which an older runner never recorded. Fail with a named re-run reason. The same
+  // rule covers a v2 record with NO recorded tamper surface (the pre-2.2 runner).
+  if (latest.schema === 1) return { code: 1, reason: `the loop's latest run is a schema-1 record (an older runner — no rerun counts, no custody hashes) — re-run fold-completeness-run.mjs` };
+  if (latest.tamper === undefined) return { code: 1, reason: `the loop's latest run has no recorded tamper surface (an older runner) — re-run fold-completeness-run.mjs` };
 
   // Decision 9 — the double binding. A tree edit moves the fingerprint; a new fixable-bug triage moves
   // the bound-testId set. Either mismatch is STALE (the run no longer describes the committable tree).
@@ -249,10 +378,54 @@ export const decideCheck = (state) => {
   // A changed unsupported-source file → fail closed: the signal never vouches for JS-family source it
   // cannot assess (TS/JSX out of scope v1, Decision 5).
   if (latest.unsupported.length > 0) return { code: 1, reason: `changed unsupported-source file(s) the signal cannot assess (TS/JSX out of scope v1): ${latest.unsupported.join(', ')}` };
-  const unresolvable = latest.testIds.filter((t) => !t.resolvable).map((t) => t.id);
-  if (unresolvable.length > 0) return { code: 1, reason: `unresolvable bound testId(s) — the pattern selects no test: ${unresolvable.join(', ')}` };
-  const redBaseline = latest.testIds.filter((t) => t.resolvable && !t.baselineGreen).map((t) => t.id);
-  if (redBaseline.length > 0) return { code: 1, reason: `bound test(s) with a red baseline (the fold is not complete): ${redBaseline.join(', ')}` };
+
+  // The recorded overrides of this loop (review ledger, schema v3): oracle-change lifts named
+  // tampered files; red-proof waives the receipt + custody proof for exactly the testId it names.
+  const overrides = collectOverrides(state.reviewRecords, { activity: ACTIVITY, loop });
+
+  // Approach-3 — the oracle-tamper guard: any tampered test-surface file (a removed/modified line in
+  // a pre-existing test file, or a deleted one) must be covered by a recorded oracle-change
+  // override. Never silent: the override is a durable, auditable ledger entry.
+  const tamperedUncovered = latest.tamper.tampered.filter((f) => !overrides.oracleChangeFiles.has(f));
+  if (tamperedUncovered.length > 0) {
+    return {
+      code: 1,
+      reason: `tampered test-surface file(s) — a fix diff modified/deleted pre-existing test expectations — without a recorded oracle-change override: ${tamperedUncovered.join(', ')}. If the oracle change is deliberate, record it: node review-ledger-write.mjs override --json '{"loop":"${loop}","round":<n>,"scope":"oracle-change","files":${JSON.stringify(tamperedUncovered)},"reason":"<why the expectation legitimately changed>"}'`,
+    };
+  }
+
+  // Per-testId enforcement, in bound (sorted) order: the D4 verdict algebra first — QUARANTINE and
+  // red/unresolvable are probe-outcome failures regardless of receipts — then, for a green test, the
+  // red-proof chain: receipt exists (Approach-1.i) → the receipt PRECEDES the loop's latest run
+  // (anti-post-hoc, codex R2) → content custody (D5). The checker stays PURE: the current file hash
+  // IS the latest run's recorded hash (the run is fingerprint-bound to the current tree).
+  const probes = new Map(latest.testIds.map((t) => [t.id, t]));
+  const boundSet = new Set(latest.boundTestIds);
+  const receipts = loopResults.map((r, i) => ({ r, i })).filter(({ r }) => isRedProbeRecord(r));
+  for (const id of latest.boundTestIds) {
+    const t = probes.get(id);
+    const verdict = probeVerdict(t);
+    if (verdict === 'unresolvable') return { code: 1, reason: `unresolvable bound testId(s) — the pattern selects no test: ${id}` };
+    if (verdict === 'quarantine') return { code: 1, reason: `bound test in QUARANTINE — not an N/N verdict (${t.greens} green / ${t.reds} red / ${t.timeouts} timed out of ${t.runs} runs): ${id}. A flaky/timed-out probe proves nothing and has no override lane — replace or speed up the test, then re-run` };
+    if (verdict === 'red') return { code: 1, reason: `bound test(s) with a red baseline (the fold is not complete): ${id}` };
+    // D7 — a recorded red-proof override replaces the receipt + custody proof for EXACTLY this
+    // testId (green N/N was already required above; QUARANTINE was already refused — no override
+    // lane converts a flaky probe).
+    if (overrides.redProofTestIds.has(id)) continue;
+    // verdict green — the red-proof chain.
+    const own = receipts.filter(({ r }) => r.testId === id);
+    if (own.length === 0) return { code: 1, reason: `no observed-red receipt for ${id} — a test never seen failing proves nothing about the fix. BEFORE folding a fix, run: node fold-completeness-run.mjs --red "${id}"` };
+    if (!own.some(({ i }) => i < sel.index)) return { code: 1, reason: `the observed-red receipt for ${id} was minted AFTER the loop's latest run — a post-hoc red proves nothing; run fold-completeness-run.mjs once more (a fresh run after the receipt)` };
+    const { file } = splitTestId(id);
+    // Custody eligibility (D5, codex R3): the anchor is the LATEST receipt on that FILE whose own
+    // testId is in the bound set AND which precedes the latest run — an unbound throwaway receipt,
+    // or one minted post-run, never re-attests a file.
+    const eligible = receipts.filter(({ r, i }) => i < sel.index && boundSet.has(r.testId) && splitTestId(r.testId).file === file);
+    const anchor = eligible[eligible.length - 1];
+    if (!anchor || t.fileHash == null || anchor.r.fileHash !== t.fileHash) {
+      return { code: 1, reason: `custody broken for ${id}: the test file ${file} no longer matches its last observed-red content — re-observe red after the edit (node fold-completeness-run.mjs --red "<the file's newest testId>"), or record a red-proof override if the red is genuinely unestablishable` };
+    }
+  }
   if (latest.coverage.uncoveredChanged.length > 0) return { code: 1, reason: `uncovered changed line(s) — changed code no test executed: ${latest.coverage.uncoveredChanged.map(renderUncovered).join(', ')}` };
   // v1 ships NO mutation (the mutation half was shelved): the shipped runner only ever writes the
   // reserved empty shape, so a record carrying ANY mutation data was not produced by this runner
@@ -275,12 +448,19 @@ export const decideCheck = (state) => {
 
 // ── rendering ─────────────────────────────────────────────────────────────────────────────────
 
-const runLine = (r) => {
-  const tests = r.testIds.length ? r.testIds.map((t) => `${t.id}${t.resolvable ? (t.baselineGreen ? '✓' : ' red-baseline') : ' unresolvable'}`).join(', ') : '(no bound tests)';
+const testLine = (r, t) => {
+  if (r.schema === 1) return `${t.id}${t.resolvable ? (t.baselineGreen ? '✓' : ' red-baseline') : ' unresolvable'}`;
+  const v = probeVerdict(t);
+  return v === 'green' ? `${t.id} ✓ ${t.greens}/${t.runs}` : `${t.id} ${v} (${t.greens}g/${t.reds}r/${t.timeouts}t of ${t.runs})`;
+};
+
+const runLine = (r, receipts) => {
+  const tests = r.testIds.length ? r.testIds.map((t) => testLine(r, t)).join(', ') : '(no bound tests)';
   const uncov = r.coverage.uncoveredChanged.length ? r.coverage.uncoveredChanged.map(renderUncovered).join(', ') : 'none';
   return [
     `  latest run — fingerprint ${r.fingerprint}`,
     `    bound testIds: ${tests}`,
+    `    red-probe receipts: ${receipts.length ? receipts.map((p) => `${p.testId} (${p.reds}/${p.runs} red @${p.fileHash.slice(0, 8)})`).join(', ') : 'none'}`,
     `    uncovered changed: ${uncov}`,
     `    unsupported: ${r.unsupported.length ? r.unsupported.join(', ') : 'none'} · out-of-domain: ${r.outOfDomain.length ? r.outOfDomain.join(', ') : 'none'}`,
     `    mutation: ${r.mutation.total} total / ${r.mutation.killed} killed / ${r.mutation.survived.length} survived / ${r.mutation.skipped} skipped`,
@@ -300,8 +480,9 @@ const formatHuman = (state, check) => {
   lines.push(`  result ledger: ${state.resultsPath ?? '(unresolvable — no git dir)'} (${state.resultRecords.length} record(s)${state.resultMalformed ? `, ${state.resultMalformed} malformed — inspect the file` : ''})`);
   if (state.plans.length === 1) {
     const loop = state.plans[0].replace(/\.md$/, '');
-    const runs = filterLoopResults(state.resultRecords, loop);
-    if (runs.length > 0) lines.push(runLine(runs[runs.length - 1]));
+    const loopResults = filterLoopResults(state.resultRecords, loop);
+    const sel = latestRunRecord(loopResults); // kind-aware: never render a red-probe as "the run"
+    if (sel) lines.push(runLine(sel.record, loopResults.filter(isRedProbeRecord)));
   }
   lines.push(`  check: ${check.code === 0 ? 'PASS' : 'FAIL'} — ${check.reason}`);
   return lines.join('\n');
@@ -316,14 +497,23 @@ Reads the result ledger the runner writes (<git dir>/${RESULTS_BASENAME}; AW_FOL
 resolves the effective ${ACTIVITY}.${SLOT} recipe, recomputes the canonical uncommitted-state
 fingerprint, and decides whether the in-flight plan-execution loop's changed code is pinned by tests.
 
---status (default) → the human report: resolved recipe, plan-in-flight, the latest run summary, verdict.
+--status (default) → the human report: resolved recipe, plan-in-flight, the latest run summary
+  (per-testId D4 verdicts + rerun counts), the loop's red-probe receipts, verdict.
 --check → the gate exit code. The normative exit contract lives in the tool header (the single home):
   exit 0 for solo / no plan in flight / a clean tree / not-a-git-tree / a CURRENT run whose fingerprint
-  AND bound-testId set both match, with resolvable+green bound tests, 0 uncovered changed lines, 0
-  changed unsupported source, and the reserved empty mutation shape; exit 1 otherwise (stale/missing
-  run, an unresolvable/red bound test, an uncovered line, changed TS/JSX, any mutation data — v1 ships
-  no mutation, >1 plan, an unreadable/malformed ledger, or a detector failure). Out-of-domain changes
-  are listed, never blocking.
+  AND bound-testId set both match, with — per bound testId — an N/N-green probe, an observed-red
+  receipt that PRECEDES the run, and content custody (run hash == the latest custody-eligible receipt
+  hash on that file); plus 0 uncovered changed lines, 0 changed unsupported source, every tampered
+  test-surface file covered by a recorded oracle-change override, and the reserved empty mutation
+  shape. A recorded red-proof override (review-ledger-write override) waives receipt + custody for
+  exactly its testId — never green-N/N, never QUARANTINE. exit 1 otherwise (stale/missing/older-runner
+  run, an unresolvable bound test, a QUARANTINED bound test — mixed/timeout, never converted, no
+  override lane — a red baseline, a missing/post-hoc receipt, broken custody, an uncovered tampered
+  file, an uncovered line, changed TS/JSX, any mutation data, >1 plan, an unreadable/malformed
+  ledger, or a detector failure). Out-of-domain changes are listed, never blocking. The honest
+  fold-time order: classify the fixable-bug with its testId → write the test →
+  fold-completeness-run.mjs --red "<testId>" observes red BEFORE the fix → fold the fix → the
+  normal run observes green → --check.
 --json → the structured state + decision.
 
 The runner is a SEPARATE tool (fold-completeness-run.mjs) — this read-only checker never imports it.

package/tools/review-ledger-write.mjs

@@ -29,8 +29,9 @@
 import { readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
 import { writeContainedFileAtomic } from './atomic-write.mjs';
-import { computeTreeFingerprint, readReceipts, resolveReceiptsPath } from './review-state.mjs';
+import { computeTreeFingerprint, plansInFlight, readReceipts, resolveReceiptsPath } from './review-state.mjs';
 import {
   REVIEW_CAP,
   SCHEMA_VERSION,
@@ -145,6 +146,50 @@ export const recordRound = (params, deps = {}) => {
   return appendRecord(ledgerPath, record, deps);
 };
 
+// ── recordOverride (BUGFREE-1 / AD-047, D3/D7 — the loud, recorded waiver) ──────────────────────
+
+// A read-only git-root probe for the in-flight tooth (the writer's only other git query is inside
+// computeTreeFingerprint).
+const gitRoot = (cwd) => {
+  const r = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, windowsHide: true });
+  if (r.error || r.status !== 0) return null;
+  return r.stdout.toString('utf8').replace(/\r?\n$/, '');
+};
+
+// recordOverride({ cwd, env, loop, activity, round, scope, files, testId, reason, timestamp }, deps)
+// → { writtenPath, record }. Standard teeth: field validation via the schema (exact per-scope
+// payloads), fail-closed ledger read, and the IN-FLIGHT tooth — an override is a waiver, minted only
+// inside its live loop, never retro-recorded for a finished or foreign one. The fold-completeness
+// gate matches on loop + payload, never on the (audit-only) fingerprint.
+export const recordOverride = (params, deps = {}) => {
+  const { cwd = process.cwd(), env = process.env, loop, activity = DEFAULT_ACTIVITY, round, scope, files, testId, reason, timestamp } = params;
+  const ledgerPath = deps.ledgerPath ?? resolveLedgerPath(cwd, env);
+  if (ledgerPath == null) throw stop('cannot resolve the ledger path — not a git work tree and AW_REVIEW_LEDGER is unset');
+  if (!(Number.isInteger(round) && round >= 1)) throw stop(`round must be an integer >= 1 (got ${round})`);
+  // Exactly ONE in-flight plan, and it must be the named loop (codex+agy R5): a waiver minted while
+  // multiple plans are active could later cover a now-single loop — the ambiguity the rest of the
+  // family refuses everywhere (the single-plan rule).
+  const plans = deps.plansInFlight ? deps.plansInFlight() : plansInFlight(gitRoot(cwd) ?? cwd);
+  if (plans.length !== 1 || plans[0] !== `${loop}.md`) {
+    throw stop(`refusing to record an override for loop "${loop}": an override is minted only inside its SINGLE in-flight loop (in flight: ${plans.length ? plans.join(', ') : 'none'})`);
+  }
+  const fingerprint = deps.computeFingerprint ? deps.computeFingerprint(cwd) : computeTreeFingerprint(cwd);
+  const record = {
+    schema: SCHEMA_VERSION, loop, activity, kind: 'override', round, fingerprint, scope,
+    ...(files !== undefined ? { files } : {}), ...(testId !== undefined ? { testId } : {}),
+    reason, timestamp: timestamp ?? isoNow(),
+  };
+  const v = validateRecord(record);
+  if (!v.ok) throw stop(`refusing to record a malformed override: ${v.reason}`);
+  const { records, malformed, malformedReasons, readError } = readLedger(ledgerPath, deps.readFile);
+  if (readError) throw stop(`cannot read the existing ledger (${readError}) — refusing to append (fail closed)`);
+  if (malformed > 0) throw stop(`the existing ledger has ${malformed} malformed line(s) — refusing to append until they are fixed (fail closed): ${malformedReasons.join('; ')}`);
+  if (!roundSequenceIntact(filterLoopRecords(records, { activity, loop }))) {
+    throw stop(`refusing to record an override for loop "${loop}": its recorded round sequence is corrupt (not 1..n) — fix the ledger by hand first`);
+  }
+  return appendRecord(ledgerPath, record, deps);
+};
+
 // ── recordTriage (the deadlock-breaker — no teeth, no receipt binding) ──────────────────────────
 
 // recordTriage({ cwd, env, loop, activity, round, classifications, timestamp }, deps) →
@@ -186,11 +231,12 @@ export const recordTriage = (params, deps = {}) => {
 
 // ── CLI (record / classify) ──────────────────────────────────────────────────────────────────────
 
-const HELP = `review-ledger-write — the review-round ledger WRITER (agent-workflow family, AD-045).
+const HELP = `review-ledger-write — the review-round ledger WRITER (agent-workflow family, AD-045 + AD-047).
 
 Usage:
-  node review-ledger-write.mjs record   --json '<round-payload>'   [--cwd <dir>]
-  node review-ledger-write.mjs classify --json '<triage-payload>'  [--cwd <dir>]
+  node review-ledger-write.mjs record   --json '<round-payload>'    [--cwd <dir>]
+  node review-ledger-write.mjs classify --json '<triage-payload>'   [--cwd <dir>]
+  node review-ledger-write.mjs override --json '<override-payload>' [--cwd <dir>]
 
 record   appends one review round. The JSON payload carries { loop, round, origins, backends,
          findings } (activity defaults to plan-execution; timestamp defaults to now). REFUSES while
@@ -200,6 +246,12 @@ classify appends one triage record. The JSON payload carries { loop, round, clas
          { findingKey, class, accepted, testId, note }). A fixable-bug REQUIRES a testId — the
          red→green test that pins the fold, formatted "<test-file>#<test-name-pattern>" (write it
          first); inherent-layer-residual / escalate may omit it. This is what permits the next round.
+override appends one override record (schema 3) — the LOUD, durable waiver the fold-completeness
+         gate consumes. The JSON payload carries { loop, round, scope, reason } plus, per scope:
+         scope "oracle-change" → files[] (non-empty repo-relative paths whose tamper flag it lifts);
+         scope "red-proof" → testId (the exact bound testId whose observed-red receipt + custody it
+         waives — for a red that is GENUINELY unestablishable pre-fold, D7). REFUSES for a loop that
+         is not the in-flight plan. QUARANTINE (a flaky/timed-out probe) has NO override lane.
 
 The read-only checker is a SEPARATE tool: node review-ledger.mjs --check / --status / --json.
 Exit codes: 0 written; 1 a typed STOP (teeth / malformed / missing receipt / fs error); 2 usage.`;
@@ -238,14 +290,16 @@ export const main = (argv, ctx = {}) => {
   try {
     if (argv.includes('--help') || argv.includes('-h') || argv.length === 0) return { code: argv.length === 0 ? 2 : 0, stdout: HELP, stderr: '' };
     const sub = argv[0];
-    if (sub !== 'record' && sub !== 'classify') throw usageFail(`unknown subcommand "${sub}" (expected: record | classify)`);
+    if (sub !== 'record' && sub !== 'classify' && sub !== 'override') throw usageFail(`unknown subcommand "${sub}" (expected: record | classify | override)`);
     const opts = parseArgs(argv.slice(1));
     const payload = parsePayload(opts.json);
     const cwd = opts.cwd ?? cwd0;
     const result =
       sub === 'record'
         ? recordRound({ cwd, env, ...payload })
-        : recordTriage({ cwd, env, ...payload });
+        : sub === 'classify'
+          ? recordTriage({ cwd, env, ...payload })
+          : recordOverride({ cwd, env, ...payload });
     return { code: 0, stdout: `review-ledger-write: recorded a ${result.record.kind} for loop "${result.record.loop}" round ${result.record.round} → ${result.writtenPath}`, stderr: '' };
   } catch (err) {
     return { code: err.exitCode ?? 1, stdout: '', stderr: `review-ledger-write: ${err.message}` };