@sabaiway/agent-workflow-kit 1.39.0 → 1.40.0

package/tools/fold-completeness.mjs

@@ -15,14 +15,16 @@
 //   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 SEGMENT — (loop, base = git rev-parse HEAD),
-//           schema v3, AD-048 D7 — has a CURRENT run record (kind-aware: the latest RUN, never a
-//           later red-probe) whose BOTH bindings match — the tree fingerprint AND the SEGMENT's
+//           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
@@ -84,8 +86,17 @@ export { probeVerdict, RESULTS_BASENAME, resolveResultsPath };
 // 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).
-export const RESULT_SCHEMA_VERSION = 3;
-export const SUPPORTED_RESULT_SCHEMAS = new Set([1, 2, 3]);
+// 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';
 
@@ -202,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
@@ -228,13 +263,27 @@ export const validateRunRecord = (obj) => {
     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
@@ -280,6 +329,9 @@ export const filterSegmentResults = (records, loop, base) =>
 // 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
@@ -295,6 +347,40 @@ export const latestRunRecord = (loopRecords) => {
 // 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 ─────────────────────────────────────────────────────────────────────
 
 // buildFoldState({ cwd, env, detect }) → everything both renders need. Pure I/O at the edges; every
@@ -424,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);
@@ -439,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(', ')}` };
@@ -518,8 +609,9 @@ 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 SEGMENT's changed code is pinned by
-tests — (loop, base = git rev-parse HEAD), schema v3 (AD-048 D7): bound testIds, receipts, custody,
-and tamper all filter to the current segment; a committed phase's obligations close with its commit.
+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.
@@ -527,7 +619,8 @@ and tamper all filter to the current segment; a committed phase's obligations cl
   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 receipt hash on that file); plus 0 uncovered changed lines, 0 changed
+  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

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.`

package/tools/lcov.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+// lcov.mjs — a dependency-free LCOV parser for the fold-completeness runner's coverage.kind:"lcov"
+// branch (BUGFREE-3, AD-049 — the language-independence contract). When a verification profile
+// declares coverage.kind:"lcov", the consumer's OWN suite leaves an LCOV file at the declared path
+// (the diff-cover / c8 --reporter=lcov pattern) and this module reads it into a per-file
+// line→hits map, keyed by the SAME canonical absolute path the V8 coverage map uses — so the
+// runner's ONE uncovered-changed loop consumes either source unchanged (computeUncoveredLines /
+// effectiveCount stay the V8-only path, D10).
+//
+// FAIL-CLOSED posture (the whole reason the fold gate exists): a malformed record can never mark a
+// line COVERED — a DA with a valid line but a non-integer HIT count reads the line UNCOVERED (hits 0,
+// the gate fails), and a DA with no valid line number is skipped (unattributable — there is no line to
+// flag), never a false green. An SF path that resolves OUTSIDE the repo — or does not resolve at all —
+// is never trusted as coverage (a wrong file could otherwise read covered). (STATED residual, inherent
+// to the LCOV data model: a CONFORMANT producer emits DA:N,0 for every uncovered executable line, so a
+// changed executable line with NO DA entry reads non-executable — LCOV carries no separate
+// executability signal; the V8 path, which reads an absent line as uncovered, differs by format.)
+//
+// Dependency-free, Node >= 18. No side effects on import.
+
+import { join, resolve, isAbsolute, sep } from 'node:path';
+import { realpathSync } from 'node:fs';
+
+// Only these three LCOV records are consulted; every other record (FN/FNDA/BRDA/LF/LH/BRF/…) is
+// ignored. LCOV groups per-file sections between an `SF:<path>` line and `end_of_record`.
+const SF_RE = /^SF:(.*)$/;
+const DA_RE = /^DA:(\d+),(.*)$/; // DA:<line>,<hits-field>… — the LINE must be an int; the hits field is
+// parsed leniently below so a truncated/malformed hit count reads UNCOVERED (fail-closed), not omitted.
+const END_RE = /^end_of_record\s*$/;
+
+// parseLcov(text) → Map<sfString, Map<lineNumber, hits>>. Raw SF strings (NOT yet canonicalized).
+// A line's hits is the MAX across duplicate DA entries within a section (some tracers emit per-test
+// sections that also repeat lines). A DA whose line or hit count is not a base-10 integer is skipped
+// (fail-closed: it can never mark a line covered). Lines with no DA entry never appear (a
+// non-executable line — blank/comment — is simply absent, mirroring the V8 blank-line skip).
+export const parseLcov = (text) => {
+  const out = new Map();
+  let current = null; // the Map<line,hits> for the SF section in progress
+  for (const rawLine of String(text).split('\n')) {
+    const line = rawLine.replace(/\r$/, '');
+    const sf = SF_RE.exec(line);
+    if (sf) {
+      const path = sf[1].trim();
+      if (path.length === 0) {
+        current = null;
+        continue;
+      }
+      current = out.get(path);
+      if (!current) {
+        current = new Map();
+        out.set(path, current);
+      }
+      continue;
+    }
+    if (END_RE.test(line)) {
+      current = null;
+      continue;
+    }
+    const da = DA_RE.exec(line);
+    if (da && current) {
+      const n = Number.parseInt(da[1], 10);
+      if (!Number.isInteger(n) || n < 1) continue; // no valid line number → unattributable, skip
+      const hitsField = da[2].split(',')[0]; // the hit count (a trailing ,checksum is ignored)
+      // FAIL-CLOSED, STRICT: the hit count must be ALL digits — a truncated `DA:42,`, a
+      // `DA:2,xyz`, a partial `DA:5,1abc`, or a fractional `DA:6,2.5` all read UNCOVERED (hits 0), never
+      // parseInt-coerced to a positive "covered" value. A covered sibling still wins (max).
+      const effHits = /^\d+$/.test(hitsField) ? Number.parseInt(hitsField, 10) : 0;
+      current.set(n, Math.max(current.get(n) ?? 0, effHits));
+    }
+  }
+  return out;
+};
+
+const defaultCanon = (p) => {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+};
+
+// Segment-safe containment ('/a' never contains '/ab'); correct at the filesystem root (mirrors
+// fold-completeness-run.mjs containsPath). Defined locally so lcov.mjs never imports the runner (the
+// runner imports THIS module).
+const containsPath = (realRoot, realAbs) =>
+  realAbs === realRoot || realAbs.startsWith(realRoot.endsWith(sep) ? realRoot : realRoot + sep);
+
+// lcovCoveredMap(text, rootTop, { canon }?) → Map<canonAbsKey, Map<line, hits>>. Each SF is resolved
+// against rootTop (a relative / ./-prefixed / absolute-in-repo SF all normalize to the same key the
+// V8 map uses), canon()-normalized, and KEPT only when it resolves strictly INSIDE the repo root; an
+// outside-tree or unresolvable SF is DROPPED (never trusted as coverage). Duplicate SF sections are
+// merged taking the max hits per line. canon is injectable for hermetic tests (default realpathSync).
+export const lcovCoveredMap = (text, rootTop, deps = {}) => {
+  const canon = deps.canon ?? defaultCanon;
+  const raw = parseLcov(text);
+  const rootCanon = canon(rootTop);
+  const out = new Map();
+  for (const [sf, lineHits] of raw) {
+    const abs = isAbsolute(sf) ? sf : resolve(rootTop, sf);
+    const key = canon(abs);
+    if (!containsPath(rootCanon, key)) continue; // outside the repo (or unresolved elsewhere) → drop
+    let m = out.get(key);
+    if (!m) {
+      m = new Map();
+      out.set(key, m);
+    }
+    for (const [line, hits] of lineHits) m.set(line, Math.max(m.get(line) ?? 0, hits));
+  }
+  return out;
+};
+
+// uncoveredChangedFromLcov(coveredMap, key, changedLines) → the sorted changed lines that the LCOV
+// records as EXECUTABLE-but-unexecuted (a DA entry with 0 hits). A file ABSENT from the map (no SF)
+// is signalled by a null return → the caller records a file-level RED (line:null), exactly like the
+// V8 "absent from coverage" case. A changed line with NO DA entry in a PRESENT file is non-executable
+// (blank/comment) and never flagged — mirroring the V8 blank-line skip.
+export const uncoveredChangedFromLcov = (coveredMap, key, changedLines) => {
+  const lineHits = coveredMap.get(key);
+  if (!lineHits) return null; // file absent from coverage → file-level RED (caller decides)
+  const uncovered = [];
+  for (const n of changedLines) {
+    const hits = lineHits.get(n);
+    if (hits === 0) uncovered.push(n); // executable, 0 hits → uncovered
+    // hits > 0 → covered; hits === undefined → non-executable line, skip
+  }
+  return [...new Set(uncovered)].sort((a, b) => a - b);
+};

package/tools/review-ledger-write.mjs

@@ -37,7 +37,7 @@ import { dirname } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { writeContainedFileAtomic } from './atomic-write.mjs';
-import { computeTreeFingerprint, plansInFlight, readReceipts, resolveReceiptsPath } from './review-state.mjs';
+import { buildState, computeTreeFingerprint, plansInFlight, readReceipts, resolveReceiptsPath } from './review-state.mjs';
 import {
   REVIEW_CAP,
   SCHEMA_VERSION,
@@ -101,6 +101,52 @@ const appendRecord = (ledgerPath, record, deps = {}) => {
   return { writtenPath: ledgerPath, record };
 };
 
+// ── (g) record --from-receipts: draft the backends[] from the current-fingerprint receipts ────────
+// (BUGFREE-3 / AD-049). The orchestrator hand-maintained each backend's { backend, verdict } beside
+// the counts every round — drift-prone busywork. --from-receipts DRAFTS the backends[] instead: for
+// each recipe-named backend it reads the review-state receipt status (verdict from the fresh grounded
+// code receipt) and computes the counts from the orchestrator's OWN supplied findings; `origins` and
+// `findings` stay explicit input. It NEVER invents a backend — a recipe-named backend with no fresh
+// grounded receipt is a LOUD STOP (run its review, or supply it explicitly as a degraded backend).
+// The assembled backends[] then rides the normal recordRound teeth (validateRound re-checks that
+// findings-by-severity equals the drafted counts — true by construction).
+export const draftBackendsFromReceipts = ({ state, findings = [], explicitBackends = [] }, deps = {}) => {
+  const stopFn = deps.stop ?? stop;
+  const explicitByName = new Map((Array.isArray(explicitBackends) ? explicitBackends : []).filter((b) => b && typeof b.backend === 'string').map((b) => [b.backend, b]));
+  const findingsArr = Array.isArray(findings) ? findings : [];
+  const countFor = (name) => {
+    const own = findingsArr.filter((f) => f && f.backend === name);
+    return {
+      blockers: own.filter((f) => f.severity === 'blocker').length,
+      majors: own.filter((f) => f.severity === 'major').length,
+      minors: own.filter((f) => f.severity === 'minor').length,
+    };
+  };
+  return state.requiredBackends.map((name) => {
+    const explicit = explicitByName.get(name);
+    if (explicit) {
+      // An explicit row is honored verbatim ONLY for a DEGRADED backend (a bridge the operator knows
+      // is down, which minted no receipt). A NON-degraded explicit row would BYPASS the
+      // receipt-derived verdict --from-receipts exists to compute (a stale hand-composed row silently
+      // winning) — a loud STOP, fail-closed (codex council R1). Drop --from-receipts to compose a
+      // non-degraded row by hand, or mark the backend degraded.
+      if (explicit.degraded !== true) {
+        throw stopFn(
+          `refusing --from-receipts: an explicit non-degraded backends[] row for ${name} would bypass the receipt-derived verdict this flag computes — mark it degraded (a bridge that is down), or drop --from-receipts and compose the round by hand`,
+        );
+      }
+      return explicit;
+    }
+    const status = state.backends.find((b) => b.backend === name);
+    if (!status || status.state !== 'current') {
+      throw stopFn(
+        `refusing --from-receipts: no fresh grounded code receipt for ${name} (state: ${status?.state ?? 'missing'}) — run its review wrapper (codex-review code / agy-review code --facts @f) first, or supply it explicitly as a degraded backend in the payload's backends[]`,
+      );
+    }
+    return { backend: name, degraded: false, ...countFor(name), verdict: status.verdict };
+  });
+};
+
 // ── recordRound (the teeth + the integrity binding) ─────────────────────────────────────────────
 
 // recordRound({ cwd, env, loop, activity, round, origins, backends, findings, timestamp }, deps) →
@@ -365,7 +411,7 @@ export const recordTriage = (params, deps = {}) => {
 const HELP = `review-ledger-write — the review-round ledger WRITER (agent-workflow family, AD-045 + AD-047 + AD-048).
 
 Usage:
-  node review-ledger-write.mjs record   --json '<round-payload>'    [--cwd <dir>]
+  node review-ledger-write.mjs record   --json '<round-payload>' [--from-receipts] [--cwd <dir>]
   node review-ledger-write.mjs classify --json '<triage-payload>'   [--cwd <dir>]
   node review-ledger-write.mjs override --json '<override-payload>' [--cwd <dir>]
 
@@ -373,7 +419,11 @@ Every verb operates on the current SEGMENT — (loop, base = git rev-parse HEAD)
 caps, and teeth reset only when a gated commit moves base (schema 4; records carry base).
 
 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
+         findings } (activity defaults to plan-execution; timestamp defaults to now). With
+         --from-receipts the backends[] is DRAFTED from the current-fingerprint grounded code
+         receipts (verdict per backend) with counts computed from the supplied findings — origins /
+         findings stay explicit; a recipe-named backend with no receipt is a LOUD stop (run its
+         review, or supply it explicitly as a degraded backend). REFUSES while
          triage is required; beyond the hard-max ceiling of ${HARD_MAX} rounds within one segment;
          while a blocking finding of the segment's previous round VANISHED unclassified (D6 —
          classify it first, "refuted" is the honest phantom lane); while the changed source surface
@@ -401,7 +451,7 @@ The read-only checker is a SEPARATE tool: node review-ledger.mjs --check / --sta
 Exit codes: 0 written; 1 a typed STOP (teeth / malformed / missing receipt / fs error); 2 usage.`;
 
 const parseArgs = (argv) => {
-  const opts = { cwd: undefined, json: undefined };
+  const opts = { cwd: undefined, json: undefined, fromReceipts: false };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--cwd') {
@@ -412,6 +462,8 @@ const parseArgs = (argv) => {
       opts.json = argv[i + 1];
       if (opts.json === undefined) throw usageFail('--json needs a JSON payload');
       i += 1;
+    } else if (a === '--from-receipts') {
+      opts.fromReceipts = true;
     } else {
       throw usageFail(`unknown argument: ${a}`);
     }
@@ -436,8 +488,15 @@ export const main = (argv, ctx = {}) => {
     const sub = argv[0];
     if (sub !== 'record' && sub !== 'classify' && sub !== 'override') throw usageFail(`unknown subcommand "${sub}" (expected: record | classify | override)`);
     const opts = parseArgs(argv.slice(1));
+    if (opts.fromReceipts && sub !== 'record') throw usageFail('--from-receipts applies only to `record`');
     const payload = parsePayload(opts.json);
     const cwd = opts.cwd ?? cwd0;
+    if (opts.fromReceipts) {
+      // Draft backends[] from the current-fingerprint receipts + the supplied findings; origins /
+      // findings stay explicit. The drafted array then rides the normal recordRound teeth.
+      const state = buildState({ cwd, env });
+      payload.backends = draftBackendsFromReceipts({ state, findings: payload.findings, explicitBackends: payload.backends ?? [] });
+    }
     const result =
       sub === 'record'
         ? recordRound({ cwd, env, ...payload })

package/tools/review-ledger.mjs

@@ -104,13 +104,15 @@ const SEVERITIES = new Set(['blocker', 'major', 'minor']);
 export const ORIGINS = ['first-draft', 'fold-induced', 'mechanics'];
 const CLASSES = new Set(['fixable-bug', 'inherent-layer-residual', 'escalate']);
 // v4 (BUGFREE-2 / D6): `refuted` — the honest lane for a phantom finding, refuted against code with
-// a MANDATORY non-empty note citing the grounds; never silently dropped, never folded.
-const V4_CLASSES = new Set([...CLASSES, 'refuted']);
+// a MANDATORY non-empty note citing the grounds; never silently dropped, never folded. Exported as
+// the code-side vocabulary source the doc-parity lint (BUGFREE-3 / AD-049) checks the contract docs
+// against — so the mode files can never drift from the schema's own class/scope lexicon.
+export const V4_CLASSES = new Set([...CLASSES, 'refuted']);
 const OVERRIDE_SCOPES = new Set(['oracle-change', 'red-proof']);
 // v4 (BUGFREE-2 / D4): `size-cap` — the recorded waiver for a changed surface beyond the diff cap;
 // exact payload carries the sanctioned magnitude, and it is SEGMENT-scoped (loop + base), unlike
 // the two loop-scoped v3 scopes.
-const V4_OVERRIDE_SCOPES = new Set([...OVERRIDE_SCOPES, 'size-cap']);
+export const V4_OVERRIDE_SCOPES = new Set([...OVERRIDE_SCOPES, 'size-cap']);
 
 // ── git-dir resolution (read-only queries; the ledger lives in the git dir, uncommittable) ──────