@sabaiway/agent-workflow-kit 1.38.0 → 1.40.0

package/tools/fold-completeness.mjs

@@ -14,19 +14,23 @@
 // 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 (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
+//           and when the in-flight plan-execution SEGMENT — (loop, base = git rev-parse HEAD),
+//           schema v3+ (v4 adds the (a) suite-execution evidence + the (c) reattest custody anchor,
+//           BUGFREE-3/AD-049), AD-048 D7 — has a CURRENT run record (kind-aware: the latest RUN, never a
+//           later red-probe or reattest) whose BOTH bindings match — the tree fingerprint AND the SEGMENT's
+//           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 SEGMENT (a committed phase's
+//           obligations closed with its commit; a receipt never crosses a commit boundary), 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
+//           recorded test-file hash equals the latest custody-eligible red-probe OR reattest hash on that
+//           file (eligible = its own testId is bound AND it precedes the run, D5; a green-only append is
+//           re-anchored by a recorded --reattest, not a red-proof waiver); 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
+//   exit 1  for any DIRTY in-flight plan-execution segment lacking such a current run record — including
 //           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) —
@@ -58,24 +62,41 @@
 // free, Node >= 18. No side effects on import (the isDirectRun idiom).
 
 import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { spawnSync } from 'node:child_process';
 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, collectOverrides, isWellFormedTestId, splitTestId } from './review-ledger.mjs';
-
-export const RESULTS_BASENAME = 'agent-workflow-fold-completeness.jsonl';
+import { resolveLedgerPath, resolveBase, readLedger, filterSegmentRecords, collectOverrides, isWellFormedTestId, splitTestId } from './review-ledger.mjs';
+// The fold-ledger locator and the D4 probe-verdict algebra live in the NEUTRAL shared module
+// (BUGFREE-2 / AD-048, D8): review-ledger.mjs telemetry reads the fold ledger through THAT module —
+// importing this checker from there would close an import cycle (this file imports review-ledger).
+// Re-exported here so the runner and every existing consumer keep their one entry point.
+import { probeVerdict, RESULTS_BASENAME, resolveResultsPath } from './changed-surface.mjs';
+
+export { probeVerdict, RESULTS_BASENAME, resolveResultsPath };
 // 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]);
+// observed-red receipt --red mints). SCHEMA v3 (BUGFREE-2 / AD-048, D7): records carry `base` — the
+// SEGMENT frame — and the gate scopes bound testIds, receipts, custody, and tamper to
+// (loop, base = current HEAD): a committed phase's custody obligations close with its commit (the
+// cross-phase-churn override class dies). 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/v2 ledgers never retroactively become malformed — but only a v3 record
+// can enter a segment, so a dirty segment whose loop holds only pre-v3 records fails with a reason
+// naming the schema upgrade (D7 legacy rule).
+// SCHEMA v4 (BUGFREE-3 / AD-049): a v4 run record carries a `suite` execution-evidence block (the (a)
+// one-suite-run credit — cmd + exit + pre/post fingerprints) AND a new record kind `reattest` joins
+// `run`/`red-probe`: an operator-minted, RECORDED custody re-attestation that anchors a bound test
+// file's custody at its CURRENT bytes WITHOUT fabricating a red-observe (the honest replacement for
+// mis-using red-proof on a green-only test-file append, item (c)). A placed pre-v4 checker (SUPPORTED
+// = {1,2,3}) rejects a v4 record outright — the version-skew guard; v1/v2/v3 rules are untouched.
+export const RESULT_SCHEMA_VERSION = 4;
+export const SUPPORTED_RESULT_SCHEMAS = new Set([1, 2, 3, 4]);
+// The v4 record kind (c): a recorded re-attestation. Named as a const so the runner, the checker, and
+// the doc-parity lint share one token (no drift).
+export const REATTEST_KIND = 'reattest';
 const ACTIVITY = 'plan-execution';
 const SLOT = 'review';
 
@@ -89,22 +110,17 @@ const gitLine = (args, cwd) => {
 
 const gitRoot = (cwd) => gitLine(['rev-parse', '--show-toplevel'], cwd);
 
-// The result-ledger path: AW_FOLD_RESULTS overrides (mirrors AW_REVIEW_LEDGER); else <git dir>/basename.
-export const resolveResultsPath = (cwd, env = process.env) => {
-  if (env.AW_FOLD_RESULTS) return env.AW_FOLD_RESULTS;
-  const gitDir = gitLine(['rev-parse', '--absolute-git-dir'], cwd);
-  return gitDir == null ? null : join(gitDir, RESULTS_BASENAME);
-};
-
 // ── the bound fixable-bug testId set (the SINGLE source of truth — runner + checker share it) ────
 
-// collectBoundTestIds(reviewRecords, { activity, loop }) → the sorted, de-duplicated testIds of the
-// loop's fixable-bug classifications. Pure over review-ledger records. Both the runner (which records
-// the set as a binding) and the checker (which recomputes it for the staleness check) call THIS, so
-// the two can never drift (Decision 9: same-fingerprint/new-testId is stale).
-export const collectBoundTestIds = (reviewRecords, { activity = ACTIVITY, loop } = {}) => {
+// collectBoundTestIds(reviewRecords, { activity, loop, base }) → the sorted, de-duplicated testIds
+// of the SEGMENT's fixable-bug classifications (D7: pass base — a committed segment's folds are
+// closed obligations; `base: undefined` would match nothing, never legacy records). Pure over
+// review-ledger records. Both the runner (which records the set as a binding) and the checker
+// (which recomputes it for the staleness check) call THIS, so the two can never drift (Decision 9:
+// same-fingerprint/new-testId is stale).
+export const collectBoundTestIds = (reviewRecords, { activity = ACTIVITY, loop, base } = {}) => {
   const ids = new Set();
-  for (const r of filterLoopRecords(reviewRecords, { activity, loop })) {
+  for (const r of filterSegmentRecords(reviewRecords, { activity, loop, base })) {
     if (r.kind !== 'triage') continue;
     for (const c of r.classifications) if (c.class === 'fixable-bug' && typeof c.testId === 'string' && c.testId.length > 0) ids.add(c.testId);
   }
@@ -120,11 +136,18 @@ const isStringArray = (v) => Array.isArray(v) && v.every((x) => typeof x === 'st
 
 const HASH_RE = /^[0-9a-f]{64}$/; // sha-256 hex — the content-custody hash shape
 
-// The shared record frame (both versions, both kinds).
+// The shared record frame (every version, both kinds). v3 adds the SEGMENT frame: base is REQUIRED
+// (null on an unborn branch); a v1/v2 record never carries it — an old record never grows new
+// surface (the review-ledger D2 discipline).
 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';
+  if (obj.schema >= 3) {
+    if (!(obj.base === null || isNonEmptyString(obj.base))) return 'a v3 record requires base — null (unborn branch) or the HEAD commit the dirty tree sits on';
+  } else if (obj.base !== undefined) {
+    return `base is a v3 frame field — a schema-${obj.schema} record never carries it`;
+  }
   return null;
 };
 
@@ -190,6 +213,30 @@ const validateRedProbe = (obj) => {
   return null;
 };
 
+// The (c) re-attest receipt (v4 only): the operator asserts a bound test file's CURRENT bytes are a
+// legitimate custody anchor (a green-only append after a --red receipt — there is no red to observe).
+// It mirrors the red-probe receipt MINUS the observation counts: testId + the file's current hash.
+// Minted only by the runner's --reattest verb (self-discipline, the same trust model as the overrides).
+const validateReattest = (obj) => {
+  if (!isWellFormedTestId(obj.testId)) return 'reattest 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 'reattest fileHash must be a 64-hex content hash';
+  return null;
+};
+
+// The (a) suite-execution evidence (v4 run records): the ONE suite spawn per fingerprint, recorded so
+// run-gates --record can CREDIT the unit-tests gate from it instead of re-spawning. Here only the SHAPE
+// is checked (a non-empty cmd, an integer-or-null exit, null-or-string before/after fingerprints); the
+// credit's fingerprint/tree/cmd-identity/exit-0 conditions live in the ledger writer (review-ledger.mjs).
+const validateSuiteEvidence = (suite) => {
+  if (!isPlainObject(suite)) return 'a v4 run records its suite-execution evidence ({ cmd, exit, fingerprintBefore, fingerprintAfter })';
+  if (!isNonEmptyString(suite.cmd)) return 'suite.cmd must be a non-empty string';
+  if (!(suite.exit === null || Number.isInteger(suite.exit))) return 'suite.exit must be an integer or null';
+  for (const k of ['fingerprintBefore', 'fingerprintAfter']) {
+    if (!(suite[k] === null || isNonEmptyString(suite[k]))) return `suite.${k} must be null or a non-empty fingerprint string`;
+  }
+  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
@@ -208,19 +255,35 @@ export const validateRunRecord = (obj) => {
   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.
+    // The tamper surface is OPTIONAL on a v2 read — a record written by the pre-tamper v2 runner
+    // stays readable (never retroactively malformed); the GATE handles the staleness. A v3 runner
+    // ALWAYS records it, so a v3 run without one is not this runner's output. When present, the
+    // shape is exact.
+    if (obj.schema >= 3 && obj.tamper === undefined) return { ok: false, reason: 'a v3 run records its tamper surface' };
     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)' };
     }
+    // v4 (a): a v4 runner ALWAYS records the suite-execution evidence, so a v4 run without one is not
+    // this runner's output (the tamper-on-v3 precedent). v1/v2/v3 runs never carry it.
+    if (obj.schema >= 4) {
+      const sr = validateSuiteEvidence(obj.suite);
+      if (sr) return { ok: false, reason: sr };
+    } else if (obj.suite !== undefined) {
+      return { ok: false, reason: `suite is a v4 field — a schema-${obj.schema} run never carries it` };
+    }
     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)})` };
+  if (obj.kind === REATTEST_KIND) {
+    // (c): a v4-only record kind — a v1/v2/v3 record never carries it (the version-skew guard).
+    if (!(obj.schema >= 4)) return { ok: false, reason: `${REATTEST_KIND} is a v4 record kind — a schema-${obj.schema} record never carries it` };
+    const r = validateReattest(obj);
+    return r ? { ok: false, reason: r } : { ok: true };
+  }
+  return { ok: false, reason: `kind must be "run", "red-probe", or "${REATTEST_KIND}" (got ${JSON.stringify(obj.kind)})` };
 };
 
 // readResults(path) → { records, malformed, malformedReasons, readError }. Absent file → empty (no run
@@ -255,11 +318,20 @@ export const readResults = (path, readFile = readFileSync) => {
 // (latest is last).
 export const filterLoopResults = (records, loop) => records.filter((r) => r.loop === loop);
 
+// filterSegmentResults(records, loop, base) → the result records of ONE segment (D7), order
+// preserved. STRICT: only a v3+ record carries base, so pre-v3 history can never enter a segment
+// (readable, never re-scoped — the review-ledger filterSegmentRecords discipline).
+export const filterSegmentResults = (records, loop, base) =>
+  filterLoopResults(records, loop).filter((r) => r.schema >= 3 && r.base === base);
+
 // ── 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';
+// (c) v4: a recorded custody re-attestation. Never read as "the latest run" (latestRunRecord uses
+// isRunRecord); consumed by the custody chain as a valid anchor for exactly the file it names.
+export const isReattestRecord = (r) => r.schema >= 4 && r.kind === REATTEST_KIND;
 
 // 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
@@ -271,16 +343,42 @@ export const latestRunRecord = (loopRecords) => {
   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';
+// probeVerdict — the D4 verdict algebra, ONE home (now the neutral changed-surface.mjs; re-exported
+// above): the runner (--red mints only on 'red'), this checker (the gate passes only on 'green'),
+// and the review-ledger telemetry (quarantine counts) all read the SAME algebra.
+
+// foldSuiteCredit({ cwd, env, fingerprint }) → { credited, evidence, reason }. Read half of the (a)
+// credit: may run-gates --record credit the unit-tests gate from the latest segment fold run's suite
+// evidence instead of re-spawning? STRICT — the evidence must be fingerprint-bound (before === after
+// === the current fingerprint, which also proves the tree unchanged) and exit 0. The cmd-identity check
+// (suite.cmd === the gate cmd — the --only-subset defense) is the caller's. Any mismatch → credited:false.
+// ENV residual (bounded, documented — maintainer-signed against Decision 7): the fold V8 suite runs under
+// NODE_V8_COVERAGE, a plain gate spawn does not. Both now strip NODE_TEST_CONTEXT (run-gates.mjs
+// spawnGateViaBash mirrors the fold suite's childTestEnv), so that divergence — the real vacuous-skip
+// false-green — is closed. The ONE remaining delta is NODE_V8_COVERAGE: a test that FAILS under coverage
+// exits nonzero and never credits (the exit-0 gate above), so only a test that PASSES *only* under
+// coverage instrumentation (e.g. asserting process.env.NODE_V8_COVERAGE is set) could credit a green the
+// plain gate would fail — an AD-047-class residual, unclosable without the double spawn (a) removes.
+export const foldSuiteCredit = ({ cwd = process.cwd(), env = process.env, fingerprint } = {}) => {
+  const plans = plansInFlight(gitRoot(cwd) ?? cwd);
+  if (plans.length !== 1) return { credited: false, reason: 'no single in-flight plan (cannot resolve the loop)' };
+  const loop = plans[0].replace(/\.md$/, '');
+  const base = resolveBase(cwd);
+  const resultsPath = resolveResultsPath(cwd, env);
+  // Fail CLOSED on an unreadable / malformed fold ledger — the SAME posture decideCheck takes (a dropped
+  // line could hide a defect); a partially-trusted ledger never credits.
+  const read = resultsPath ? readResults(resultsPath) : { records: [], malformed: 0 };
+  if (read.readError) return { credited: false, reason: `the fold ledger is unreadable (${read.readError}) — fail closed, re-spawn` };
+  if (read.malformed > 0) return { credited: false, reason: `the fold ledger has ${read.malformed} malformed line(s) — a partially-read ledger never credits (fail closed), re-spawn` };
+  const sel = latestRunRecord(filterSegmentResults(read.records, loop, base));
+  if (sel == null) return { credited: false, reason: 'no fold run recorded for the current segment' };
+  const { suite } = sel.record;
+  if (!suite) return { credited: false, reason: 'the fold run carries no suite evidence (a pre-v4 record)' };
+  if (fingerprint == null || suite.fingerprintBefore !== fingerprint || suite.fingerprintAfter !== fingerprint) {
+    return { credited: false, reason: 'the fold suite evidence is not bound to the current tree (the tree moved) — re-spawn' };
+  }
+  if (suite.exit !== 0) return { credited: false, reason: `the fold suite exited ${suite.exit} (a nonzero/red suite never credits a green gate-run) — re-spawn` };
+  return { credited: true, evidence: suite };
 };
 
 // ── the check + report core ─────────────────────────────────────────────────────────────────────
@@ -304,6 +402,7 @@ export const buildFoldState = ({ cwd, env = process.env, detect = detectBackends
   const plans = plansInFlight(root);
   const fingerprint = computeTreeFingerprint(cwd);
   const clean = fingerprint == null ? null : isTreeClean(cwd);
+  const base = resolveBase(cwd);
   const resultsPath = resolveResultsPath(cwd, env);
   const resultRead = resultsPath ? readResults(resultsPath) : { records: [], malformed: 0, malformedReasons: [] };
   const reviewPath = resolveLedgerPath(cwd, env);
@@ -315,6 +414,7 @@ export const buildFoldState = ({ cwd, env = process.env, detect = detectBackends
     plans,
     fingerprint,
     clean,
+    base,
     resultsPath,
     resultRecords: resultRead.records,
     resultMalformed: resultRead.malformed,
@@ -353,20 +453,28 @@ 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 loopResults = filterLoopResults(state.resultRecords, loop);
+  // SEGMENT scope (D7): the gate judges the current segment — (loop, base = the HEAD the dirty
+  // tree sits on). A committed phase's runs, receipts, custody chains, and tamper obligations are
+  // closed history; only v3 records at the current base enter.
+  const loopResults = filterSegmentResults(state.resultRecords, loop, state.base);
   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` };
+  if (sel == null) {
+    const allLoop = filterLoopResults(state.resultRecords, loop);
+    const legacy = allLoop.length > 0 && allLoop.every((r) => !(r.schema >= 3))
+      ? ' (the loop has only pre-v3 records, which never enter a segment — the schema upgrade requires a fresh run)'
+      : '';
+    return { code: 1, reason: `dirty plan-execution loop "${loop}" but no fold-completeness run recorded for the current segment — run fold-completeness-run.mjs${legacy}` };
+  }
   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` };
+  // No per-record schema re-checks here (agy Phase-2 nit): only a VALID v3 record can be a segment
+  // member — the reader binned anything older or tamper-less before this point (a v1 never carries
+  // base; a v3 run without a tamper surface is malformed), and a malformed line already failed the
+  // gate closed above.
 
   // 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).
   if (latest.fingerprint !== state.fingerprint) return { code: 1, reason: `no fold-completeness run for the current tree (the tree was edited after the run) — re-run fold-completeness-run.mjs after the last edit` };
-  const currentBound = collectBoundTestIds(state.reviewRecords, { activity: ACTIVITY, loop });
+  const currentBound = collectBoundTestIds(state.reviewRecords, { activity: ACTIVITY, loop, base: state.base });
   if (!sameSet(latest.boundTestIds, currentBound)) return { code: 1, reason: `a fixable-bug testId was triaged after the run (the bound-testId set changed) — re-run fold-completeness-run.mjs` };
   // Fail CLOSED if the run's probe set does not cover its bound-testId set EXACTLY. A well-formed
   // runner record always probes every bound testId (one testIds[] entry per boundTestId), but a record
@@ -402,6 +510,10 @@ export const decideCheck = (state) => {
   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));
+  // Custody ANCHORS (c): a red-probe OR a recorded re-attestation on the file re-anchors custody at
+  // its hash — the honest replacement for a red-proof waiver on a green-only append. The OBSERVED-RED
+  // requirement below stays red-probe-only (a re-attest is not a red observation).
+  const custodyAnchors = loopResults.map((r, i) => ({ r, i })).filter(({ r }) => isRedProbeRecord(r) || isReattestRecord(r));
   for (const id of latest.boundTestIds) {
     const t = probes.get(id);
     const verdict = probeVerdict(t);
@@ -417,13 +529,14 @@ export const decideCheck = (state) => {
     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);
+    // Custody eligibility (D5, codex R3): the anchor is the LATEST red-probe OR re-attest 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. A green-only append after a red-probe
+    // re-anchors here via a recorded --reattest (item (c)), not a red-proof waiver.
+    const eligible = custodyAnchors.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` };
+      return { code: 1, reason: `custody broken for ${id}: the test file ${file} no longer matches its last observed-red/re-attested content — after a green-only append, re-attest the file (node fold-completeness-run.mjs --reattest "<a bound testId in ${file}>"); after a real edit, re-observe red (--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(', ')}` };
@@ -480,9 +593,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 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)));
+    const segResults = filterSegmentResults(state.resultRecords, loop, state.base); // the current segment (D7)
+    const sel = latestRunRecord(segResults); // kind-aware: never render a red-probe as "the run"
+    if (sel) lines.push(runLine(sel.record, segResults.filter(isRedProbeRecord)));
   }
   lines.push(`  check: ${check.code === 0 ? 'PASS' : 'FAIL'} — ${check.reason}`);
   return lines.join('\n');
@@ -495,15 +608,20 @@ Usage:
 
 Reads the result ledger the runner writes (<git dir>/${RESULTS_BASENAME}; AW_FOLD_RESULTS overrides),
 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.
+fingerprint, and decides whether the in-flight plan-execution SEGMENT's changed code is pinned by
+tests — (loop, base = git rev-parse HEAD), schema v3+ (v4 adds the suite-execution evidence + the
+reattest custody anchor, BUGFREE-3/AD-049; AD-048 D7): bound testIds, receipts, custody, and tamper
+all filter to the current segment; a committed phase's obligations close with its commit.
 
 --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 — 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
+  exit 0 for solo / no plan in flight / a clean tree / not-a-git-tree / a CURRENT segment run whose
+  fingerprint AND segment bound-testId set both match, with — per bound testId — an N/N-green probe,
+  an observed-red receipt in this segment that PRECEDES the run, and content custody (run hash == the
+  latest custody-eligible red-probe OR reattest hash on that file — a green-only append is re-anchored
+  by a recorded --reattest, not a red-proof waiver); 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

package/tools/grounding.mjs

@@ -30,6 +30,13 @@ import { resolve, join, relative, isAbsolute, dirname, basename } from 'node:pat
 import { pathToFileURL } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { fail } from './orchestration-config.mjs';
+// (e) --ledger-summary (BUGFREE-3 / AD-049): a computed, loop/base-SCOPED review-ledger digest for
+// the facts payload. The review ledger is read-only here — grounding never writes it. ORIGINS +
+// computeTelemetry give the counts; the segment filter gives the scope.
+import { ORIGINS, computeTelemetry, filterSegmentRecords, readLedger, resolveLedgerPath, resolveBase } from './review-ledger.mjs';
+import { plansInFlight } from './review-state.mjs';
+
+const PLAN_EXECUTION = 'plan-execution';
 
 // The agy single-argv byte contract (mirrors agy-review.sh — the wrapper is the enforcement home).
 export const DEFAULT_MAX_PROMPT_BYTES = 120000;
@@ -104,6 +111,73 @@ export const trimToBudget = (payload, budget) => {
   return { text, trimmedBytes: bytes - keep };
 };
 
+// ── (e) --ledger-summary: a loop/base-SCOPED review-ledger digest (read-only, computed) ─────────
+// `computeTelemetry` aggregates ALL loops and is not per-round-facts-shaped, so this renders the
+// in-flight SEGMENT only (plan-execution, loop, base) — the telemetry COUNTS filtered to that
+// segment, plus a terse per-round/triage/override render. Deliberately compact + distinct from the
+// review-ledger `--status` human view (that one is indented + segment-grouped): this is a byte-
+// budgeted FACTS block that agy/codex review against, so unrelated loops are excluded by construction.
+
+const baseTag = (base) => (base === null ? '(unborn branch)' : String(base).slice(0, 12));
+const countsOf = (obj) => {
+  const keys = Object.keys(obj).sort();
+  return keys.length === 0 ? '(none)' : keys.map((k) => `${k}:${obj[k]}`).join(' ');
+};
+const summaryRoundLine = (r) =>
+  `round ${r.round} — ${r.backends.map((b) => `${b.backend} ${b.degraded ? `degraded(${b.reason})` : `${b.blockers}/${b.majors}/${b.minors} ${b.verdict}`}`).join(', ')}` +
+  (r.findings.length ? ` [${r.findings.map((f) => `${f.findingKey}(${f.severity})`).join(', ')}]` : '');
+const summaryTriageLine = (t) => `triage @round ${t.round} — ${t.classifications.map((c) => `${c.findingKey}=${c.class}`).join(', ')}`;
+const summaryOverrideLine = (o) =>
+  `override @round ${o.round} [${o.scope}] — ${o.scope === 'oracle-change' ? o.files.join(', ') : o.scope === 'size-cap' ? `sanctioned ${o.sanctionedLines} lines` : o.testId}: ${o.reason}`;
+const summaryGateRunLine = (g) => `gate-run — status=${g.summary.status} ${g.summary.passed}/${g.summary.gates} green`;
+const summaryRecordLine = (r) =>
+  r.kind === 'round' ? summaryRoundLine(r) : r.kind === 'triage' ? summaryTriageLine(r) : r.kind === 'override' ? summaryOverrideLine(r) : summaryGateRunLine(r);
+
+// renderLedgerSummary(records, { loop, base }) → the scoped facts section, or '' when the segment
+// holds no records (empty/absent → nothing to ground). Pure: the caller does the I/O.
+export const renderLedgerSummary = (records, { loop, base }) => {
+  const segment = filterSegmentRecords(records, { activity: PLAN_EXECUTION, loop, base });
+  if (segment.length === 0) return '';
+  const t = computeTelemetry(segment, []).loops[0];
+  const lines = [
+    `## Review-ledger summary — loop ${loop} @ base ${baseTag(base)}`,
+    '',
+    `rounds ${t.rounds} · divergence-rounds ${t.divergenceRounds}`,
+    `finding origins — ${ORIGINS.map((k) => `${k}:${t.origins[k]}`).join(' ')}`,
+    `classifications — ${countsOf(t.classifications)}`,
+    `backend verdicts — ${Object.keys(t.backendVerdicts).sort().map((b) => `${b}{${countsOf(t.backendVerdicts[b])}}`).join(' · ') || '(none)'}`,
+    `overrides — ${countsOf(t.overrides)}`,
+    '',
+    ...segment.map(summaryRecordLine),
+  ];
+  return `${lines.join('\n')}\n`;
+};
+
+// resolveLedgerSummary({ cwd, env }) → the scoped section text for the SINGLE in-flight plan-execution
+// segment. A loud STOP unless exactly one plan is in flight (the family's single-plan discipline —
+// never guess which loop to ground). Reads the ledger read-only.
+const gitTop = (cwd) => {
+  const r = gitLine(['rev-parse', '--show-toplevel'], cwd);
+  return r && r.status === 0 ? r.stdout.replace(/\r?\n$/, '') : cwd;
+};
+export const resolveLedgerSummary = ({ cwd, env }) => {
+  const root = gitTop(cwd);
+  const plans = plansInFlight(root);
+  if (plans.length !== 1) {
+    throw fail(1, `--ledger-summary needs exactly one in-flight plan (in flight: ${plans.length ? plans.join(', ') : 'none'}) — resolve to one active plan`);
+  }
+  const loop = plans[0].replace(/\.md$/, '');
+  const base = resolveBase(cwd);
+  const ledgerPath = resolveLedgerPath(cwd, env);
+  const { records, readError, malformed, malformedReasons } = ledgerPath ? readLedger(ledgerPath) : { records: [], malformed: 0 };
+  // Fail CLOSED like every sibling ledger reader (No-silent-failures): an unreadable OR malformed
+  // ledger must never silently render an empty/partial digest the reviewer then grounds against — an
+  // empty section would be indistinguishable from a legitimately-empty segment.
+  if (readError) throw fail(1, `--ledger-summary cannot read the ledger (${readError}) — failing closed; inspect ${ledgerPath}`);
+  if (malformed > 0) throw fail(1, `--ledger-summary: the ledger has ${malformed} malformed line(s) — failing closed (a dropped line could hide a round/finding): ${malformedReasons.join('; ')}`);
+  return renderLedgerSummary(records, { loop, base });
+};
+
 // ── the --out destination guard (gitignored / out-of-repo scratch ONLY) ────────────────
 
 const gitLine = (args, cwd) => {
@@ -157,13 +231,17 @@ export const assertScratchDestination = (outPath, cwd) => {
 const HELP = `grounding — grounded-review facts assembler for the agent-workflow family (AD-038).
 
 Usage:
-  node grounding.mjs [--constraints] [--plan <path>] [--reserve-bytes <n>] [--out <path>]
+  node grounding.mjs [--constraints] [--plan <path>] [--ledger-summary] [--reserve-bytes <n>] [--out <path>]
 
   --constraints        slice the root AGENTS.md "Hard Constraints" section verbatim
                        (exactly one matching heading, else a loud STOP)
   --plan <path>        extract the plan's decision-bearing sections verbatim + whole:
                        "## Approach" + "## Verification" (REQUIRED — STOP if missing),
                        "## Decisions (locked)" when present; a duplicate heading is a STOP
+  --ledger-summary     append a COMPUTED review-ledger digest for the SINGLE in-flight
+                       plan-execution segment (rounds · origins · classifications · verdicts ·
+                       overrides + a per-round render) — "computed, not remembered" facts; a
+                       loud STOP unless exactly one plan is in flight
   --reserve-bytes <n>  the artifact share agy-review will add around these facts — the output
                        budget becomes AGY_MAX_PROMPT_BYTES − n (loud tail-trim on overflow)
   --out <path>         write instead of stdout — gitignored / out-of-repo scratch ONLY
@@ -181,9 +259,11 @@ const parseArgs = (argv) => {
   let plan = null;
   let out = null;
   let reserve = 0;
+  let ledgerSummary = false;
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--constraints') constraints = true;
+    else if (a === '--ledger-summary') ledgerSummary = true;
     else if (a === '--plan') {
       plan = argv[i + 1];
       if (!plan || plan.startsWith('--')) throw fail(2, '--plan requires a <path>');
@@ -199,8 +279,8 @@ const parseArgs = (argv) => {
       i += 1;
     } else throw fail(2, `unknown argument: ${a}`);
   }
-  if (!constraints && plan == null) throw fail(2, 'nothing to assemble — pass --constraints and/or --plan <path>');
-  return { constraints, plan, out, reserve };
+  if (!constraints && plan == null && !ledgerSummary) throw fail(2, 'nothing to assemble — pass --constraints, --plan <path>, and/or --ledger-summary');
+  return { constraints, plan, out, reserve, ledgerSummary };
 };
 
 const resolveBudget = (env, reserve) => {
@@ -220,7 +300,7 @@ export const main = (argv, ctx = {}) => {
   const env = ctx.env ?? process.env;
   try {
     if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
-    const { constraints, plan, out, reserve } = parseArgs(argv);
+    const { constraints, plan, out, reserve, ledgerSummary } = parseArgs(argv);
     const budget = resolveBudget(env, reserve);
 
     const readOrStop = (path, label) => {
@@ -233,7 +313,14 @@ export const main = (argv, ctx = {}) => {
     const constraintsText = constraints ? readOrStop('AGENTS.md', 'root AGENTS.md') : null;
     const planText = plan != null ? readOrStop(plan, 'plan file') : null;
 
-    const payload = assembleGrounding({ constraintsText, planText, planLabel: plan ?? 'plan' });
+    const parts = [];
+    const assembled = assembleGrounding({ constraintsText, planText, planLabel: plan ?? 'plan' });
+    if (assembled) parts.push(assembled);
+    if (ledgerSummary) {
+      const summary = resolveLedgerSummary({ cwd, env });
+      if (summary) parts.push(summary);
+    }
+    const payload = parts.join('\n');
     const { text, trimmedBytes } = trimToBudget(payload, budget);
     const stderr = trimmedBytes > 0
       ? `[grounding] TRIM: assembled ${Buffer.byteLength(payload, 'utf8')} bytes > budget ${budget} (AGY_MAX_PROMPT_BYTES minus --reserve-bytes ${reserve}) — dropped ${trimmedBytes} tail bytes; the cut is marked in-band.`