@sabaiway/agent-workflow-kit 1.38.0 → 1.39.0

package/tools/fold-completeness-run.mjs

@@ -15,8 +15,9 @@
 //   4. probe each of the loop's fixable-bug bound testIds N times (Decision 3 / 10 + D4, shell-free,
 //      per-run timeout) for resolvability + an N/N-green baseline, hashing each bound test file
 //      (the D5 custody anchor);
-//   5. append ONE machine-only v2 run record, bound to BOTH the tree fingerprint AND the sorted
-//      fixable-bug testId set (Decision 9), to <git dir>/agent-workflow-fold-completeness.jsonl.
+//   5. append ONE machine-only v3 run record — segment-framed (base = git rev-parse HEAD, AD-048 D7)
+//      and bound to BOTH the tree fingerprint AND the SEGMENT's sorted fixable-bug testId set
+//      (Decision 9) — to <git dir>/agent-workflow-fold-completeness.jsonl.
 // A SECOND verb, --red "<testId>" (BUGFREE-1 / AD-047), observes a testId RED on the current
 // (pre-fold) tree and mints a red-probe receipt — the observed-red half of the honest red→green
 // proof; observed-green / unresolvable / mixed / timed-out are distinguished refusals, nothing written.
@@ -35,7 +36,7 @@ import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { writeContainedFileAtomic } from './atomic-write.mjs';
 import { computeTreeFingerprint, plansInFlight } from './review-state.mjs';
-import { resolveLedgerPath, readLedger, isWellFormedTestId, splitTestId } from './review-ledger.mjs';
+import { resolveLedgerPath, resolveBase, readLedger, isWellFormedTestId, splitTestId } from './review-ledger.mjs';
 import {
   RESULT_SCHEMA_VERSION,
   resolveResultsPath,
@@ -43,6 +44,13 @@ import {
   collectBoundTestIds,
   probeVerdict,
 } from './fold-completeness.mjs';
+// The changed-surface computation lives in the NEUTRAL shared module (BUGFREE-2 / AD-048, D4): the
+// review-ledger writer's diff-size cap and this runner's coverage domain consume ONE computation,
+// and the writer never imports this runner (the sole-tree-toucher boundary — import-split pinned).
+// Re-exported below so the runner's tests (and any consumer) keep one entry point per concern.
+import { classifyChangedPath, parseUnifiedDiff, unquoteDiffPath, computeChangedSurface, DIFF_FLAGS, parsePositiveIntKnob } from './changed-surface.mjs';
+
+export { classifyChangedPath, parseUnifiedDiff, unquoteDiffPath, computeChangedSurface };
 
 const ACTIVITY = 'plan-execution';
 const GIT_MAX_BUFFER = 256 * 1024 * 1024; // a full-tree diff / full-suite TAP can be large; never truncate
@@ -67,65 +75,6 @@ const childTestEnv = (env, extra = {}) => {
   return out;
 };
 
-// ── Decision 5: the CLOSED changed-path classification rule (no heuristics) ───────────────────────
-
-const TEST_FILE_RE = /\.(test|spec)\.[^./]+$/; // a.test.mjs, b.spec.js, c.test.cjs, d.spec.ts
-const ASSESSABLE_EXT = new Set(['.mjs', '.cjs', '.js']);
-const UNSUPPORTED_EXT = new Set(['.ts', '.tsx', '.jsx', '.mts', '.cts']);
-
-// classifyChangedPath(rel) → 'assessable' | 'unsupported' | 'out-of-domain' | 'excluded-test'.
-export const classifyChangedPath = (rel) => {
-  const base = rel.split('/').pop();
-  if (TEST_FILE_RE.test(base)) return 'excluded-test';
-  const dot = base.lastIndexOf('.');
-  const ext = dot >= 0 ? base.slice(dot) : '';
-  if (ASSESSABLE_EXT.has(ext)) return 'assessable';
-  if (UNSUPPORTED_EXT.has(ext)) return 'unsupported';
-  return 'out-of-domain';
-};
-
-// ── unified-diff → new-side changed line numbers (line numbers only; content lines are ignored) ───
-
-const DIFF_HUNK_RE = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
-
-// parseUnifiedDiff(diffText) → Map<rel, number[]>. Robust against a content line that happens to look
-// like a `+++ ` header: a `+++ ` line is a FILE header only in the header region (right after a
-// `diff --git`, before any `@@`); inside a hunk body it is ignored. New-side lines come purely from the
-// `@@` headers, so no content-line disambiguation is needed for the line numbers themselves.
-export const parseUnifiedDiff = (diffText) => {
-  const map = new Map();
-  let current = null;
-  let inHeader = false;
-  for (const line of String(diffText).split('\n')) {
-    if (line.startsWith('diff --git ')) {
-      current = null;
-      inHeader = true;
-      continue;
-    }
-    if (inHeader && line.startsWith('--- ')) continue;
-    if (inHeader && line.startsWith('+++ ')) {
-      const p = unquoteDiffPath(line.slice(4).replace(/[\t\r]+$/, '')); // TAB/CR are git artifacts, never filename bytes (agy R6)
-      current = p === '/dev/null' ? null : p.startsWith('b/') ? p.slice(2) : p;
-      inHeader = false;
-      continue;
-    }
-    const m = DIFF_HUNK_RE.exec(line);
-    if (m) {
-      inHeader = false;
-      if (current == null) continue;
-      const start = Number(m[1]);
-      const count = m[2] === undefined ? 1 : Number(m[2]);
-      if (count > 0) {
-        const arr = map.get(current) ?? [];
-        for (let i = 0; i < count; i += 1) arr.push(start + i);
-        map.set(current, arr);
-      }
-    }
-  }
-  for (const [k, v] of map) map.set(k, [...new Set(v)].sort((a, b) => a - b));
-  return map;
-};
-
 // ── Decision 6: V8 coverage → uncovered changed lines (innermost-range-wins) ──────────────────────
 
 // lineStartOffsets(sourceText) → char offset of each line start (index i == line i+1). Splitting on
@@ -216,8 +165,12 @@ export const parseProbeOutput = ({ stdout, code, fileArg }) => {
   return { resolvable, executed: matched, baselineGreen: resolvable && code === 0 && fails === 0 };
 };
 
-// defaultBoundArgv(file, pattern) → the shell-free node:test argv (testId content never reaches a shell).
-export const defaultBoundArgv = (file, pattern) => ['node', '--test', '--test-reporter', 'tap', '--test-name-pattern', pattern, file];
+// defaultBoundArgv(file, pattern) → the shell-free node:test argv (testId content never reaches a
+// shell). The pattern rides in the `=`-joined form: as a SEPARATE argv token a pattern beginning
+// with "-"/"--" (a test name like "--telemetry refuses …") parses as an OPTION and the probe
+// silently selects no test — the pattern-half sibling of the AD-047 dash-spawn file fix (found
+// live by this plan's own --red loop).
+export const defaultBoundArgv = (file, pattern) => ['node', '--test', '--test-reporter', 'tap', `--test-name-pattern=${pattern}`, file];
 
 // ── the shared safe test-file resolver (BUGFREE-1, codex R1+R2) ───────────────────────────────────
 // Custody hashing and every probe spawn go through THIS one resolver — the testId format itself is
@@ -291,12 +244,7 @@ export const resolveBoundArgv = (env = process.env) => {
   return (file, pattern) => tmpl.map((a) => a.replace(/\{file\}/g, () => file).replace(/\{pattern\}/g, () => pattern));
 };
 
-// ── the changed surface (git-driven) ──────────────────────────────────────────────────────────────
-
-// The one diff-invocation shape both surface passes use. The a/ b/ prefixes are pinned EXPLICITLY
-// (agy R6): a user's global diff.noprefix=true would otherwise drop them and the parsers would eat
-// a real directory named "a" — user git config must never bend the parse.
-const DIFF_FLAGS = ['--unified=0', '--no-color', '--no-ext-diff', '--no-renames', '--src-prefix=a/', '--dst-prefix=b/'];
+// ── read-only git plumbing (the changed-surface computation itself lives in changed-surface.mjs) ──
 
 const runGit = (args, cwd) => spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, encoding: 'utf8', windowsHide: true });
 const gitStdout = (args, cwd) => {
@@ -317,101 +265,10 @@ const canon = (path) => {
     return path;
   }
 };
-// A changed assessable LEAF is assessed only if it is a REGULAR file. lstat (no-follow): a symlinked
-// or non-regular *.mjs must NEVER be read/canonicalized — following it could read outside the work
-// tree or HANG on a FIFO/device (codex R2). A non-regular leaf fails closed (routed to `unsupported`).
-const isRegularLeaf = (abs) => {
-  try {
-    return lstatSync(abs).isFile();
-  } catch {
-    return false;
-  }
-};
-
-// computeChangedSurface(root) → { assessable: Map<rel, number[]>, unsupported: [rel], outOfDomain: [rel] }.
-// Domain = the review-payload domain (tracked working-vs-HEAD changes + untracked-not-ignored files),
-// classified by the CLOSED rule. Tracked changed lines come from `git diff HEAD -U0`; an untracked file
-// is wholly new, so all its lines are "changed".
-export const computeChangedSurface = (root) => {
-  const trackedDiff = gitStdout(['diff', 'HEAD', ...DIFF_FLAGS], root)
-    ?? gitStdout(['diff', ...DIFF_FLAGS], root) // no HEAD yet (unborn branch)
-    ?? '';
-  const trackedLines = parseUnifiedDiff(trackedDiff);
-  const untrackedZ = gitStdout(['ls-files', '--others', '--exclude-standard', '-z'], root) ?? '';
-  const untracked = untrackedZ.split('\0').filter(Boolean);
-
-  const assessable = new Map();
-  const unsupported = [];
-  const outOfDomain = [];
-  const place = (rel, cls, lines) => {
-    if (cls === 'excluded-test') return;
-    if (cls === 'assessable') {
-      if (isRegularLeaf(join(root, rel))) assessable.set(rel, lines);
-      else unsupported.push(rel); // a symlinked / non-regular source → fail closed, never followed
-      return;
-    }
-    if (cls === 'unsupported') unsupported.push(rel);
-    else outOfDomain.push(rel);
-  };
-  for (const [rel, lines] of trackedLines) place(rel, classifyChangedPath(rel), lines);
-  for (const rel of untracked) {
-    const cls = classifyChangedPath(rel);
-    if (cls !== 'assessable') {
-      place(rel, cls, []);
-      continue;
-    }
-    // Guard the leaf BEFORE reading — never follow a symlink to count an untracked file's lines.
-    const abs = join(root, rel);
-    if (!isRegularLeaf(abs)) {
-      unsupported.push(rel);
-      continue;
-    }
-    const src = readFileSafe(abs);
-    const count = src == null || src.length === 0 ? 0 : src.split('\n').length;
-    assessable.set(rel, Array.from({ length: count }, (_, i) => i + 1));
-  }
-  return { assessable, unsupported: unsupported.sort(), outOfDomain: outOfDomain.sort() };
-};
-
 // ── the oracle-tamper surface (BUGFREE-1 Phase 2.2, Approach-3) ───────────────────────────────────
 
 const DIFF_HUNK_OLD_RE = /^@@ -\d+(?:,(\d+))? \+\d+(?:,\d+)? @@/;
 
-// Git C-quotes diff-header paths carrying quotes/control/non-ASCII bytes ("a/\321\202….mjs") — an
-// unparsed quoted path compares unequal to its classifier/testId form and would silently escape the
-// tamper/coverage surface (agy R5). Strip the quotes and decode escapes BYTE-wise (octal escapes
-// are UTF-8 bytes). Space-only paths are not quoted (they carry a trailing TAB — trimmed upstream).
-const CQUOTE_SIMPLE = { n: 10, t: 9, r: 13, f: 12, v: 11, b: 8, a: 7, '"': 34, '\\': 92 };
-export const unquoteDiffPath = (p) => {
-  if (!(p.length >= 2 && p.startsWith('"') && p.endsWith('"'))) return p;
-  const inner = p.slice(1, -1);
-  const bytes = [];
-  for (let i = 0; i < inner.length; i += 1) {
-    const c = inner[i];
-    if (c !== '\\') {
-      // Consume a full CODE POINT — 16-bit-unit iteration would split a surrogate pair (an
-      // unescaped non-BMP char, reachable under core.quotepath=false) into replacement bytes (agy R6).
-      const ch = String.fromCodePoint(inner.codePointAt(i));
-      for (const b of Buffer.from(ch, 'utf8')) bytes.push(b);
-      i += ch.length - 1;
-      continue;
-    }
-    const rest = inner.slice(i + 1);
-    const oct = /^[0-7]{1,3}/.exec(rest);
-    if (oct) {
-      bytes.push(Number.parseInt(oct[0], 8) & 0xff);
-      i += oct[0].length;
-    } else if (rest[0] in CQUOTE_SIMPLE) {
-      bytes.push(CQUOTE_SIMPLE[rest[0]]);
-      i += 1;
-    } else if (rest[0] !== undefined) {
-      for (const b of Buffer.from(rest[0], 'utf8')) bytes.push(b);
-      i += 1;
-    }
-  }
-  return Buffer.from(bytes).toString('utf8');
-};
-
 // parseDiffOldSide(diffText) → Map<oldRel, { removals: boolean }> — the OLD-side view of a -U0
 // tracked diff: which pre-existing (HEAD) files carry any removed/modified line (a hunk whose
 // old-count > 0). A file ADDED by the diff (--- /dev/null) has no old side and never appears; a
@@ -549,26 +406,15 @@ const appendRecord = (resultsPath, record) => {
 
 // ── the run ───────────────────────────────────────────────────────────────────────────────────────
 
-// The shared fail-closed integer parser for the D4 probe knobs: zero / negative / fractional /
-// non-numeric values are typed refusals by name — the parseInt(...)||default idiom would silently
-// accept bad truthy values (codex R2). Unset → the default; set → a positive integer, exactly.
-const parsePositiveIntKnob = (env, name, fallback) => {
-  const raw = env[name];
-  if (raw === undefined) return fallback;
-  if (!/^\d+$/.test(String(raw).trim()) || Number.parseInt(raw, 10) < 1) {
-    throw stop(`${name} must be a positive integer (got "${raw}") — refusing to guess (fail closed)`);
-  }
-  return Number.parseInt(raw, 10);
-};
-
 export const budgetsFromEnv = (env) => ({
   mutantsMax: Number.parseInt(env.AW_FOLD_MUTANTS_MAX ?? '200', 10) || 200,
   hunkMutantsMax: Number.parseInt(env.AW_FOLD_HUNK_MUTANTS_MAX ?? '25', 10) || 25,
   timeBudgetS: Number.parseInt(env.AW_FOLD_TIME_BUDGET_S ?? '600', 10) || 600,
   // D4: N reruns per probe side; the per-RUN probe timeout (each of the N runs gets its own budget,
-  // never one shared series budget — agy R1). Probes only: the suite run keeps the no-timeout status quo.
-  foldReruns: parsePositiveIntKnob(env, 'AW_FOLD_RERUNS', 3),
-  probeTimeoutS: parsePositiveIntKnob(env, 'AW_FOLD_PROBE_TIMEOUT_S', 120),
+  // never one shared series budget — agy R1). Probes only: the suite run keeps the no-timeout status
+  // quo. The fail-closed parser is the shared one (changed-surface.mjs), thrown as THIS tool's STOP.
+  foldReruns: parsePositiveIntKnob(env, 'AW_FOLD_RERUNS', 3, stop),
+  probeTimeoutS: parsePositiveIntKnob(env, 'AW_FOLD_PROBE_TIMEOUT_S', 120, stop),
 });
 
 // ── the shared N-rerun probe (D4) — ONE helper for both the run's green side and the --red verb ───
@@ -656,10 +502,13 @@ export const runFoldCompleteness = ({ cwd = process.cwd(), env = process.env, su
     for (const n of computeUncoveredLines({ perProcessRanges: perProc, sourceText: src, changedLines: lines })) uncoveredChanged.push({ file: rel, line: n });
   }
 
-  // Decision 3 / 10 + D4: probe each fixable-bug bound testId N times (shell-free, per-run timeout).
+  // Decision 3 / 10 + D4: probe each of the SEGMENT's fixable-bug bound testIds N times
+  // (shell-free, per-run timeout). Segment scope (D7): a committed phase's folds are closed
+  // obligations — only triages recorded at the current base bind.
   const ledgerPath = resolveLedgerPath(cwd, env);
   const { records: reviewRecords } = ledgerPath ? readLedger(ledgerPath) : { records: [] };
-  const boundTestIds = collectBoundTestIds(reviewRecords, { activity: ACTIVITY, loop });
+  const base = resolveBase(cwd);
+  const boundTestIds = collectBoundTestIds(reviewRecords, { activity: ACTIVITY, loop, base });
   const testIds = boundTestIds.map(
     (id) => probeBound({ id, rootTop, env, boundArgv, reruns: budgets.foldReruns, timeoutS: budgets.probeTimeoutS }).entry,
   );
@@ -672,6 +521,7 @@ export const runFoldCompleteness = ({ cwd = process.cwd(), env = process.env, su
     schema: RESULT_SCHEMA_VERSION,
     kind: 'run',
     loop,
+    base,
     fingerprint,
     boundTestIds,
     testIds,
@@ -743,6 +593,7 @@ export const runRedProbe = ({ cwd = process.cwd(), env = process.env, testId } =
     schema: RESULT_SCHEMA_VERSION,
     kind: 'red-probe',
     loop,
+    base: resolveBase(cwd), // the SEGMENT frame (D7): a receipt attests red within its segment
     testId,
     fileHash: entry.fileHash,
     runs: entry.runs,
@@ -766,15 +617,17 @@ Usage:
   node fold-completeness-run.mjs --red "<test-file>#<test-name-pattern>" [--cwd <dir>]
 
 The default run: runs the in-flight plan-execution loop's suite ONCE under coverage, maps every
-changed executable line to covered/uncovered, probes each fixable-bug bound testId N times
-(AW_FOLD_RERUNS, default 3) for resolvability + an N/N-green baseline, records each bound test file's
-content hash (custody), and appends one v2 run record to
+changed executable line to covered/uncovered, probes each of the SEGMENT's fixable-bug bound testIds
+N times (AW_FOLD_RERUNS, default 3) for resolvability + an N/N-green baseline, records each bound test
+file's content hash (custody), and appends one v3 run record — segment-framed (base = git rev-parse
+HEAD; the bound set is the current segment's, AD-048 D7) — to
 <git dir>/${'agent-workflow-fold-completeness.jsonl'} (AW_FOLD_RESULTS overrides).
 
 --red observes a testId RED on the CURRENT (pre-fold) tree — the honest fold-time order is: classify
 the fixable-bug with its testId → write the test → --red observes it FAIL (N/N) BEFORE the fix is
 applied → fold the fix → the normal run observes green → the gate checks receipt + order + custody.
-An N/N red mints a red-probe receipt (testId, counts, content hash, fingerprint); observed-green /
+An N/N red mints a red-probe receipt (testId, counts, content hash, fingerprint, and base — the
+current SEGMENT frame: a receipt never crosses a commit boundary); observed-green /
 unresolvable / mixed / timed-out are DISTINGUISHED typed refusals and nothing is written
 (mixed/timeout = QUARANTINE — never converts, no override lane).
 

package/tools/fold-completeness.mjs

@@ -14,10 +14,12 @@
 // 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, 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
+//           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
@@ -26,7 +28,7 @@
 //           (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 +60,32 @@
 // 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).
+export const RESULT_SCHEMA_VERSION = 3;
+export const SUPPORTED_RESULT_SCHEMAS = new Set([1, 2, 3]);
 const ACTIVITY = 'plan-execution';
 const SLOT = 'review';
 
@@ -89,22 +99,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 +125,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;
 };
 
@@ -208,9 +220,11 @@ 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)' };
     }
@@ -255,6 +269,12 @@ 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".
@@ -271,17 +291,9 @@ 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.
 
 // ── the check + report core ─────────────────────────────────────────────────────────────────────
 
@@ -304,6 +316,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 +328,7 @@ export const buildFoldState = ({ cwd, env = process.env, detect = detectBackends
     plans,
     fingerprint,
     clean,
+    base,
     resultsPath,
     resultRecords: resultRead.records,
     resultMalformed: resultRead.malformed,
@@ -353,20 +367,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
@@ -480,9 +502,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 +517,18 @@ 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 (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 receipt hash on that file); plus 0 uncovered changed lines, 0 changed
+  unsupported source, every tampered
   test-surface file covered by a recorded oracle-change override, and the reserved empty mutation
   shape. A recorded red-proof override (review-ledger-write override) waives receipt + custody for
   exactly its testId — never green-N/N, never QUARANTINE. exit 1 otherwise (stale/missing/older-runner

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.',
             ]
           : []),
       ]