@sabaiway/agent-workflow-kit 1.38.0 → 1.40.0

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/procedures.mjs

@@ -212,7 +212,7 @@ const reviewLoopAdvice = (slots, activity) =>
         '  • At the cap, classify every surviving blocking finding: fixable-bug (fold ONCE as a red→green test, re-review) / inherent-layer-residual (document + raise to an acceptance criterion) / escalate (the maintainer decides); a minor never forces triage.',
         ...(activity === 'plan-execution'
           ? [
-              '  • The computed instrument for THIS loop: record each round + triage via review-ledger (record / classify); read the stop with review-ledger --status (its render replaces the hand-composed tally); gate the commit with review-ledger --check.',
+              '  • The computed instrument for THIS loop: run the FULL gate matrix with run-gates --record BEFORE recording a round (the green-baseline receipt the writer demands), then record each round + triage via review-ledger (record / classify); rounds, caps, and teeth are per SEGMENT (base = HEAD — the counter resets only at a gated commit); read the stop with review-ledger --status (its render replaces the hand-composed tally); gate the commit with review-ledger --check.',
             ]
           : []),
       ]

package/tools/review-ledger-write.mjs

@@ -7,17 +7,23 @@
 // shared hardened atomic-write core (tools/atomic-write.mjs — exclusive-create tmp + rename, TOCTOU
 // re-check, symlink STOPs). The ledger lives in the git dir (uncommittable by construction).
 //
-// Two record kinds, one JSONL ledger:
+// Record kinds, one JSONL ledger. Every verb evaluates the current SEGMENT — (activity, loop,
+// base = `git rev-parse HEAD`), BUGFREE-2 / AD-048 D1: round numbering, the caps, and every tooth
+// are per segment; a segment closes only through a gated commit, so a counter reset is earned:
 //   recordRound   — one review round: per-backend counts + verdict + degraded, finding-origin tally,
-//                   findings[]. Binds to the canonical tree fingerprint. THE TEETH (Decision 5):
-//                   REFUSES (typed STOP) while decideStop on the existing records is `triage-required`
-//                   (an unclassified surviving blocking finding at/after the cap), and refuses ANY
-//                   round beyond the hard-max ceiling unconditionally. Integrity binding (Decision 7):
+//                   findings[]. Binds to the canonical tree fingerprint + base. THE TEETH (Decision 5
+//                   + AD-048): REFUSES (typed STOP) while decideStop on the segment's records is
+//                   `triage-required`; refuses ANY round beyond the per-segment hard-max ceiling
+//                   unconditionally; refuses while a blocking finding of the segment's previous
+//                   round VANISHED unclassified (D6 — no-repro-no-fold; `refuted` is the honest
+//                   phantom lane); refuses while the changed source surface exceeds the diff cap
+//                   without a recorded segment size-cap override (D4). Integrity binding (Decision 7):
 //                   each NON-degraded backend needs a grounded code receipt for the current tree, so a
 //                   round cannot be recorded for a tree no bridge reviewed.
-//   recordTriage  — the classification that BREAKS the deadlock: each surviving blocking finding
-//                   classified fixable-bug / inherent-layer-residual / escalate. No teeth (a triage is
-//                   exactly what lets the next round proceed), no receipt binding (it reviews nothing).
+//   recordTriage  — the classification that BREAKS the deadlock: each surviving blocking finding of a
+//                   SEGMENT round classified fixable-bug / inherent-layer-residual / escalate /
+//                   refuted (v4). No teeth (a triage is exactly what lets the next round proceed),
+//                   no receipt binding (it reviews nothing).
 //
 // HONEST residual (stated, accepted — like review-state's): the ledger attests a review occurred; it
 // does NOT prove the recorded COUNTS are truthful nor that a self-reported `degraded:true` is real.
@@ -31,21 +37,37 @@ 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,
   resolveLedgerPath,
+  resolveBase,
   readLedger,
-  filterLoopRecords,
+  filterSegmentRecords,
+  collectSizeCapLimit,
+  isQualityGreenGateRun,
   roundSequenceIntact,
   decideStop,
   validateRecord,
 } from './review-ledger.mjs';
+// The NEUTRAL shared changed-surface computation (BUGFREE-2 / D4): the D4 diff-cap and the
+// fold-completeness coverage gate consume ONE computation, so they can never drift. The writer
+// imports the NEUTRAL module, never the runner (the sole-tree-toucher boundary, codex R2 — an
+// import-split test pins that this file never imports fold-completeness-run.mjs).
+import { computeChangedSurface, countCapLines, parsePositiveIntKnob } from './changed-surface.mjs';
 
 // The absolute WRITER ceiling (Decision 5): hard-max lives ONLY here — it is NOT a decideStop input.
-// Even a fully-classified resolved-residual loop cannot reach a round beyond this.
+// Even a fully-classified resolved-residual loop cannot reach a round beyond this. Since AD-048 it
+// is scoped per SEGMENT (D3 — value unchanged, scope corrected): round numbers restart when a gated
+// commit moves base, so a multiphase plan records fully while round 4 within ONE segment stays
+// refused — that ceiling is the point (the 2026-06-30 six-round incident class).
 export const HARD_MAX = 3;
+// The D4 diff-size review cap (default 400 changed source lines; AW_REVIEW_DIFF_CAP overrides
+// through the shared fail-closed positive-integer parser). Counted classes are pinned in
+// changed-surface.mjs: assessable + unsupported SOURCE lines count; tests and out-of-domain never
+// do; pure deletions are free.
+export const DEFAULT_DIFF_CAP = 400;
 const DEFAULT_ACTIVITY = 'plan-execution';
 
 // A typed STOP — a deliberate refusal we surface (the teeth / a malformed record / a missing
@@ -79,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) →
@@ -90,11 +158,13 @@ export const recordRound = (params, deps = {}) => {
   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})`);
   // The hard-max ceiling: refuse ANY round beyond it, independent of triage state (Decision 5).
+  // Per SEGMENT since AD-048 (D3): the round number is the segment round number.
   if (round > HARD_MAX) {
-    throw stop(`refusing to record round ${round}: beyond the hard-max ceiling of ${HARD_MAX} rounds — the loop must converge or the surviving finding must escalate, never another round`);
+    throw stop(`refusing to record round ${round}: beyond the hard-max ceiling of ${HARD_MAX} rounds within one segment — the segment must converge (or its surviving finding escalate) and ship through a gated commit; the counter resets only at the commit boundary, never by declaration`);
   }
 
   const fingerprint = deps.computeFingerprint ? deps.computeFingerprint(cwd) : computeTreeFingerprint(cwd);
+  const base = deps.resolveBase ? deps.resolveBase(cwd) : resolveBase(cwd);
 
   // The teeth: refuse a new round WHILE decideStop on the existing records is triage-required. Once
   // the surviving blocking finding is classified (recordTriage), decideStop is no longer
@@ -107,25 +177,79 @@ export const recordRound = (params, deps = {}) => {
   // the teeth OPEN (codex R1). Refuse to append until the ledger is sound.
   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('; ')}`);
-  const existingLoop = filterLoopRecords(records, { activity, loop });
-  // Sequence integrity + sequentiality (codex R2+R3): the EXISTING rounds must already be exactly
-  // 1..n (never trust a hand-corrupted [2]/[1,1]/[2,1] to compute "latest"), AND the incoming round
-  // must be exactly the next (n+1). A duplicate, decreasing, or gapped round would let a fabricated
-  // "later" round become the latest that decideStop reads, bypassing the "latest round" teeth.
-  const priorRounds = existingLoop.filter((r) => r.kind === 'round').map((r) => r.round);
-  if (!roundSequenceIntact(existingLoop)) {
-    throw stop(`refusing to append to loop "${loop}": its recorded round sequence is corrupt (${priorRounds.join(',') || 'empty'}, not 1..n) — fix the ledger by hand before recording another round`);
+  // EVERY tooth below evaluates the current SEGMENT (activity, loop, base) — D1: records of earlier
+  // segments (other bases, or pre-v4 records with no base) are closed history; the field-proven
+  // 11-round / 4-base loop records completely while round 4 within ONE segment stays refused.
+  const segment = filterSegmentRecords(records, { activity, loop, base });
+  // Sequence integrity + sequentiality (codex R2+R3): the EXISTING segment rounds must already be
+  // exactly 1..n (never trust a hand-corrupted [2]/[1,1]/[2,1] to compute "latest"), AND the
+  // incoming round must be exactly the next (n+1). A duplicate, decreasing, or gapped round would
+  // let a fabricated "later" round become the latest that decideStop reads, bypassing the teeth.
+  const priorRounds = segment.filter((r) => r.kind === 'round').map((r) => r.round);
+  if (!roundSequenceIntact(segment)) {
+    throw stop(`refusing to append to loop "${loop}": its recorded round sequence for the current segment is corrupt (${priorRounds.join(',') || 'empty'}, not 1..n) — fix the ledger by hand before recording another round`);
   }
   const nextRound = priorRounds.length + 1;
   if (round !== nextRound) {
-    throw stop(`refusing to record round ${round}: rounds must be sequential — the next round for loop "${loop}" is ${nextRound} (a duplicate, out-of-order, or gapped round would corrupt the crossover computation)`);
+    throw stop(`refusing to record round ${round}: rounds must be sequential within the segment — the next round for loop "${loop}" at the current base is ${nextRound} (a duplicate, out-of-order, or gapped round would corrupt the crossover computation)`);
   }
-  const pre = decideStop(existingLoop, { cap: REVIEW_CAP });
+  const pre = decideStop(segment, { cap: REVIEW_CAP });
   if (pre.state === 'triage-required') {
     throw stop(`refusing to record a new round while triage is required — ${pre.reason}. Classify the surviving blocking finding(s) with the "classify" command first (a fixable-bug classification permits the fix round).`);
   }
 
-  const record = { schema: SCHEMA_VERSION, loop, activity, kind: 'round', round, fingerprint, origins, backends, findings, timestamp: timestamp ?? isoNow() };
+  // D6 — no-repro-no-fold: no blocking finding of the segment's previous round may VANISH
+  // unclassified. Present-again is fine (still live); classified is fine (fixable-bug folded with
+  // its red→green testId at the round it was folded — late binding restored; inherent-layer-residual
+  // documented; escalate handed over; refuted — the honest phantom lane, grounds mandatory). A
+  // silent disappearance is exactly the sycophancy hole this pillar closes. Minors stay exempt.
+  const previous = segment.find((r) => r.kind === 'round' && r.round === nextRound - 1);
+  if (previous) {
+    // "Present" means present AS BLOCKING: a blocker/major re-reported as a minor did not survive —
+    // it was softened, and the silent-soften lane is exactly the bypass D6 closes (codex R1).
+    const incoming = new Set(
+      Array.isArray(findings)
+        ? findings.filter((f) => f && (f.severity === 'blocker' || f.severity === 'major')).map((f) => f.findingKey)
+        : [],
+    );
+    // A classification CLEARS the vanish only when it actually resolves the finding's fate:
+    // fixable-bug (folded, testId bound), inherent-layer-residual (documented), refuted (grounds
+    // cited), or an ACCEPTED escalate — a pending escalate (accepted:false) is still undecided and
+    // must not disappear into a clean round (codex R1).
+    const clearsVanish = (c) =>
+      c.class === 'fixable-bug' || c.class === 'inherent-layer-residual' || c.class === 'refuted' || (c.class === 'escalate' && c.accepted === true);
+    const classified = new Set();
+    for (const t of segment) {
+      if (t.kind === 'triage' && t.round === previous.round) for (const c of t.classifications) if (clearsVanish(c)) classified.add(c.findingKey);
+    }
+    const vanished = [...new Set(
+      previous.findings
+        .filter((f) => f.severity === 'blocker' || f.severity === 'major')
+        .map((f) => f.findingKey)
+        .filter((k) => !incoming.has(k) && !classified.has(k)),
+    )];
+    if (vanished.length > 0) {
+      throw stop(`refusing to record round ${round}: blocking finding(s) of round ${previous.round} vanished without a classification: ${vanished.join(', ')} (D6 — no blocking finding disappears silently). Classify each with the "classify" command first: fixable-bug (bind the red→green testId), inherent-layer-residual, escalate, or refuted (a phantom finding — cite the refuting grounds in note).`);
+    }
+  }
+
+  // D4 — the diff-size cap over the ONE shared changed-surface computation (changed-surface.mjs):
+  // a round is refused while the changed source surface exceeds the cap, unless the SEGMENT carries
+  // a recorded size-cap override sanctioning at least the counted magnitude. Subtractive folds are
+  // free (new-side lines only); tests and out-of-domain files never count.
+  const cap = parsePositiveIntKnob(env, 'AW_REVIEW_DIFF_CAP', DEFAULT_DIFF_CAP, stop);
+  const counted = deps.countChangedLines ? deps.countChangedLines(cwd) : countCapLines(computeChangedSurface(gitRoot(cwd) ?? cwd));
+  if (counted > cap) {
+    const sanctioned = collectSizeCapLimit(records, { activity, loop, base });
+    if (sanctioned === null || counted > sanctioned) {
+      throw stop(
+        `refusing to record round ${round}: the changed source surface is ${counted} lines — over the ${cap}-line review cap (AW_REVIEW_DIFF_CAP)${sanctioned !== null ? ` and over the segment's recorded size-cap sanction of ${sanctioned}` : ''}. ` +
+          `Split the change into reviewable units (commit a converged part first), or record the LOUD waiver: node review-ledger-write.mjs override --json '{"loop":"${loop}","round":${round},"scope":"size-cap","sanctionedLines":${counted},"reason":"<why this surface must review as one unit>"}'`,
+      );
+    }
+  }
+
+  const record = { schema: SCHEMA_VERSION, loop, activity, kind: 'round', round, base, fingerprint, origins, backends, findings, timestamp: timestamp ?? isoNow() };
   const v = validateRecord(record);
   if (!v.ok) throw stop(`refusing to record a malformed round: ${v.reason}`);
 
@@ -143,6 +267,53 @@ export const recordRound = (params, deps = {}) => {
     }
   }
 
+  // D5 — the green-baseline tooth (armed at Step 2.3, AFTER run-gates --record exists — the
+  // bootstrap order): a round records only over a tree whose FULL declared non-process gate set
+  // was proven green by a recorded gate-run at the CURRENT fingerprint. "Gates ran before review"
+  // is now computed, never remembered. A `--only` subset is recorded honestly but never satisfies
+  // this (the R1 converged subset-bypass hole); a run whose tree changed under it attests no
+  // particular tree (codex R2); process-gate failures never block (the closed carve-out).
+  const gateRuns = segment.filter((r) => r.kind === 'gate-run');
+  if (!gateRuns.some((g) => g.fingerprint === fingerprint && isQualityGreenGateRun(g))) {
+    throw stop(`refusing to record round ${round}: no quality-green gate-run for the current tree in this segment (D5 — gates run before review is computed, not remembered). Run the FULL declared matrix with a recorded receipt first: node agent-workflow-kit/tools/run-gates.mjs --record (a --only subset never satisfies this; a run whose tree changed under it never counts).`);
+  }
+
+  return appendRecord(ledgerPath, record, deps);
+};
+
+// ── recordGateRun (BUGFREE-2 / AD-048, D5 — the green-baseline receipt run-gates --record mints) ──
+
+// recordGateRun({ cwd, env, activity, declared, results, summary, fingerprintBefore,
+// fingerprintAfter, timestamp }, deps) → { writtenPath, record }. The SOLE ledger entry point for
+// run-gates (`--record` DELEGATES here — the runner never opens the ledger file itself; an
+// import/structure pin holds the boundary). The loop is DERIVED from the single in-flight plan
+// (the recordOverride precedent — a gate-run is minted only inside its live loop, never
+// retro-recorded); the record carries the segment frame and NO round number (per-kind frame, D5).
+// A red run records honestly (telemetry fuel — consecutive red gate-runs are the revert-first
+// visibility); quality-green is judged at read time, never stored.
+export const recordGateRun = (params, deps = {}) => {
+  const { cwd = process.cwd(), env = process.env, activity = DEFAULT_ACTIVITY, declared, results, summary, fingerprintBefore, fingerprintAfter, 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');
+  const plans = deps.plansInFlight ? deps.plansInFlight() : plansInFlight(gitRoot(cwd) ?? cwd);
+  if (plans.length !== 1) {
+    throw stop(`refusing to record a gate-run: it is minted only inside the SINGLE in-flight loop (in flight: ${plans.length ? plans.join(', ') : 'none'})`);
+  }
+  const loop = plans[0].replace(/\.md$/, '');
+  const base = deps.resolveBase ? deps.resolveBase(cwd) : resolveBase(cwd);
+  const record = {
+    schema: SCHEMA_VERSION, loop, activity, kind: 'gate-run', base,
+    fingerprint: fingerprintBefore, fingerprintAfter, declared, results, summary,
+    timestamp: timestamp ?? isoNow(),
+  };
+  const v = validateRecord(record);
+  if (!v.ok) throw stop(`refusing to record a malformed gate-run: ${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(filterSegmentRecords(records, { activity, loop, base }))) {
+    throw stop(`refusing to record a gate-run for loop "${loop}": its recorded round sequence for the current segment is corrupt (not 1..n) — fix the ledger by hand first`);
+  }
   return appendRecord(ledgerPath, record, deps);
 };
 
@@ -162,7 +333,7 @@ const gitRoot = (cwd) => {
 // 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 { cwd = process.cwd(), env = process.env, loop, activity = DEFAULT_ACTIVITY, round, scope, files, testId, sanctionedLines, 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})`);
@@ -174,9 +345,11 @@ export const recordOverride = (params, deps = {}) => {
     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 base = deps.resolveBase ? deps.resolveBase(cwd) : resolveBase(cwd);
   const record = {
-    schema: SCHEMA_VERSION, loop, activity, kind: 'override', round, fingerprint, scope,
+    schema: SCHEMA_VERSION, loop, activity, kind: 'override', round, base, fingerprint, scope,
     ...(files !== undefined ? { files } : {}), ...(testId !== undefined ? { testId } : {}),
+    ...(sanctionedLines !== undefined ? { sanctionedLines } : {}),
     reason, timestamp: timestamp ?? isoNow(),
   };
   const v = validateRecord(record);
@@ -184,8 +357,8 @@ export const recordOverride = (params, deps = {}) => {
   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`);
+  if (!roundSequenceIntact(filterSegmentRecords(records, { activity, loop, base }))) {
+    throw stop(`refusing to record an override for loop "${loop}": its recorded round sequence for the current segment is corrupt (not 1..n) — fix the ledger by hand first`);
   }
   return appendRecord(ledgerPath, record, deps);
 };
@@ -200,27 +373,31 @@ export const recordTriage = (params, deps = {}) => {
   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})`);
   const fingerprint = deps.computeFingerprint ? deps.computeFingerprint(cwd) : computeTreeFingerprint(cwd);
+  const base = deps.resolveBase ? deps.resolveBase(cwd) : resolveBase(cwd);
   // Normalize each classification: an absent testId → null, an absent note → '' — an absent optional
   // field is FILLED, never rejected as malformed (agy R3). Under schema v2 (M2/AD-046) a fixable-bug
   // normalized to a null testId then FAILS validateRecord below (a typed STOP naming the rule + the
-  // red-test-first fix) — the test-per-fold binding rides the existing validate path. A non-array is
-  // left as-is for validateRecord to reject with a typed STOP (never a raw .map TypeError).
+  // red-test-first fix) — the test-per-fold binding rides the existing validate path; a `refuted`
+  // classification normalized to an empty note fails the same way (D6 — the grounds are mandatory).
+  // A non-array is left as-is for validateRecord to reject with a typed STOP (never a raw .map TypeError).
   const normalized = Array.isArray(classifications) ? classifications.map((c) => ({ ...c, testId: c?.testId ?? null, note: c?.note ?? '' })) : classifications;
-  const record = { schema: SCHEMA_VERSION, loop, activity, kind: 'triage', round, fingerprint, classifications: normalized, timestamp: timestamp ?? isoNow() };
+  const record = { schema: SCHEMA_VERSION, loop, activity, kind: 'triage', round, base, fingerprint, classifications: normalized, timestamp: timestamp ?? isoNow() };
   const v = validateRecord(record);
   if (!v.ok) throw stop(`refusing to record a malformed triage: ${v.reason}`);
 
-  // Bind the triage to a REAL round: the referenced round must exist and every classified findingKey
-  // must be a surviving blocking finding (blocker or major) of THAT round — a classification for a
-  // nonexistent/future round, or for a key the round never raised, must not satisfy resolved-residual
-  // downstream (codex R1). Fail CLOSED on an unreadable / malformed ledger.
+  // Bind the triage to a REAL round of the current SEGMENT: the referenced round must exist there
+  // and every classified findingKey must be a surviving blocking finding (blocker or major) of THAT
+  // round — a classification for a nonexistent/future/other-segment round, or for a key the round
+  // never raised, must not satisfy resolved-residual downstream (codex R1; D1 — a committed
+  // segment's rounds are closed, the cross-segment lane is the D7 red-proof override). Fail CLOSED
+  // on an unreadable / malformed ledger.
   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('; ')}`);
-  const loopRecords = filterLoopRecords(records, { activity, loop });
-  if (!roundSequenceIntact(loopRecords)) throw stop(`refusing to classify loop "${loop}": its recorded round sequence is corrupt (not 1..n) — fix the ledger by hand first`);
-  const targetRound = loopRecords.find((r) => r.kind === 'round' && r.round === round);
-  if (!targetRound) throw stop(`refusing to classify round ${round} of loop "${loop}": no such recorded round — classify a round that exists`);
+  const segment = filterSegmentRecords(records, { activity, loop, base });
+  if (!roundSequenceIntact(segment)) throw stop(`refusing to classify loop "${loop}": its recorded round sequence for the current segment is corrupt (not 1..n) — fix the ledger by hand first`);
+  const targetRound = segment.find((r) => r.kind === 'round' && r.round === round);
+  if (!targetRound) throw stop(`refusing to classify round ${round} of loop "${loop}": no such recorded round in the current segment — classify a round that exists at the current base`);
   const survivingKeys = new Set(targetRound.findings.filter((f) => f.severity === 'blocker' || f.severity === 'major').map((f) => f.findingKey));
   for (const c of classifications) {
     if (!survivingKeys.has(c.findingKey)) throw stop(`refusing to classify "${c.findingKey}": it is not a surviving blocking finding of round ${round} (classify only that round's blockers/majors)`);
@@ -231,33 +408,50 @@ export const recordTriage = (params, deps = {}) => {
 
 // ── CLI (record / classify) ──────────────────────────────────────────────────────────────────────
 
-const HELP = `review-ledger-write — the review-round ledger WRITER (agent-workflow family, AD-045 + AD-047).
+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>]
 
+Every verb operates on the current SEGMENT — (loop, base = git rev-parse HEAD): round numbers,
+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
-         triage is required, beyond the hard-max ceiling of ${HARD_MAX} rounds, or when a non-degraded
-         backend lacks a grounded code receipt for the current tree.
+         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
+         exceeds the ${DEFAULT_DIFF_CAP}-line diff cap (AW_REVIEW_DIFF_CAP) without a recorded
+         segment size-cap override (D4); while the segment lacks a quality-green gate-run at the
+         current fingerprint (D5 — run the FULL matrix first: run-gates.mjs --record; a --only
+         subset or a tree-changed run never satisfies; red PROCESS gates never block); or when a
+         non-degraded backend lacks a grounded code receipt for the current tree.
 classify appends one triage record. The JSON payload carries { loop, round, classifications } (each
          { 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:
+         first); refuted REQUIRES a non-empty note citing the refuting grounds;
+         inherent-layer-residual / escalate may omit the testId. This is what permits the next round.
+override appends one override record — the LOUD, durable waiver the gates consume. 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.
+         waives — for a red that is GENUINELY unestablishable pre-fold, D7);
+         scope "size-cap" → sanctionedLines (the exact changed-surface magnitude the waiver
+         sanctions, SEGMENT-scoped — it dies at the next commit, D4).
+         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.
+The read-only checker is a SEPARATE tool: node review-ledger.mjs --check / --status / --json / --telemetry.
 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') {
@@ -268,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}`);
     }
@@ -292,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 })