@sabaiway/agent-workflow-kit 2.1.0 → 3.1.0

package/tools/{seed-gates.mjs → gates-init.mjs}

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
-// seed-gates.mjs — the consent-gated docs/ai/gates.json seeder (AD-042). Reached ONLY through
-// explicitly-consenting prose (the bootstrap accelerators block and the gates.md consent-seed
-// section) — it is NOT a routable mode token, it sits OUTSIDE every velocity allowlist tier
-// (a consent-per-run writer is never pre-approved), and the shipped gates.json TEMPLATE stays
-// EMPTY (AD-021/AD-038): a populated declaration is per-entry maintainer consent recorded through
-// this preview, never auto-seeding.
+// gates-init.mjs — the consented docs/ai/gates.json FILL preview (D9; the pure derivation carried
+// from the retired standalone seeder, AD-042/AD-052 invariants intact). Reached ONLY through
+// explicitly-consenting prose (the init/bootstrap flows and the gates.md consent-fill section) —
+// it is NOT a routable mode token, it sits OUTSIDE every velocity allowlist tier (a
+// consent-per-run writer is never pre-approved), and the shipped gates.json TEMPLATE stays EMPTY
+// (AD-021/AD-038): a populated declaration is per-entry maintainer consent recorded through this
+// preview, never auto-seeding. ONE lifecycle contract: this preview runs at INIT; at UPGRADE the
+// only gates.json writer is the consented legacy migration.
 //
 // What it offers (the derivation invariants, test-pinned) — CLOSED-WORLD since AD-052: an entry
 // is offered only when every axis is proven safe by MEMBERSHIP in a finite, test-guarded set,
@@ -29,7 +31,7 @@
 //     executes project-controlled tooling (a node_modules/.bin PATH shim intercepts under every
 //     form) — the documented residual, disclosed in the preview, bounded by the two consents;
 //   • ids derive kebab-case from script names (build:prod → build-prod) and every offered entry
-//     passes the runner's validateDeclaration (the seeder imports the validator — NEVER the
+//     passes the runner's validateDeclaration (this module imports the validator — NEVER the
 //     reverse: run-gates.mjs stays a runner that writes nothing);
 //   • the review-state candidate appears ONLY when docs/ai/orchestration.json DECLARES
 //     reviewed/council on plan-execution.review — the slot the checker enforces — with the
@@ -44,7 +46,7 @@
 // .workflow-version == lineage-head stamp gate on --apply only (the velocity/gate-hook precedent).
 //
 // Exit codes: 0 done / dry-run; 1 precondition STOP (no deployment, stamp, symlink, malformed
-// declaration, id collision); 2 usage. Dependency-free, Node >= 18. No side effects on import.
+// declaration, id collision); 2 usage. Dependency-free, Node >= 22. No side effects on import.
 
 import { existsSync, lstatSync, readFileSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
@@ -58,39 +60,40 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 const KIT_ROOT = resolve(HERE, '..');
 const TEMPLATE_PATH = join(KIT_ROOT, 'references', 'templates', 'gates.json');
 const REVIEW_STATE_TOOL = join(KIT_ROOT, 'tools', 'review-state.mjs');
-const REVIEW_LEDGER_TOOL = join(KIT_ROOT, 'tools', 'review-ledger.mjs');
+const COVERAGE_CHECK_TOOL = join(KIT_ROOT, 'tools', 'coverage-check.mjs');
 const STAMP_REL = join('docs', 'ai', '.workflow-version');
 
 const EXIT_OK = 0;
 const EXIT_PRECONDITION = 1;
 const EXIT_USAGE = 2;
 
-export const SEED_GATES_STOP = 'SEED_GATES_STOP';
+export const GATES_INIT_STOP = 'GATES_INIT_STOP';
 const stop = (message) =>
-  Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'SeedGatesStop', code: SEED_GATES_STOP, exitCode: EXIT_PRECONDITION });
+  Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'GatesInitStop', code: GATES_INIT_STOP, exitCode: EXIT_PRECONDITION });
 const usageFail = (message) =>
   Object.assign(new Error(`[agent-workflow-kit] ${message}`), { exitCode: EXIT_USAGE });
 
 // The trust-chain disclosure (AD-042) — printed with EVERY preview, token-pinned by the tests: a
 // consent-seeded command becomes auto-approvable only after TWO explicit consents.
 export const TRUST_CHAIN_DISCLOSURE =
-  'Disclosure: once the optional approval hook is wired (/agent-workflow-kit hook), it ' +
-  'auto-approves byte-exact declared gate commands from the project root — seeding (this consent) ' +
-  'and hook wiring (its own consent) are two separate yeses. A script gate runs the project\'s ' +
-  'own tooling, which executes project-controlled code (the seeder does not sandbox it; the two ' +
-  'consents bound it).';
-
-const USAGE = `usage: seed-gates [--dry-run | --apply] [--only <id>]... [--cwd <dir>] [--help]
-
-Consent-gated seeder for the project's own docs/ai/gates.json. Default is --dry-run: prints the
-derived { id, title, cmd } entries and writes NOTHING. --apply APPENDS exactly the consented
-entries (--only <id> selects a subset; append-only — existing entries are never modified or
-removed, an id collision is refused). The offer is CLOSED-WORLD: only a terminating-class script
-name (test / lint / type-check / build — never release/publish/deploy, never watch/serve, never a
-write-mode variant) whose BODY is a member of the literal runner allowlist is offered, as the
-hook-free \`COREPACK_ENABLE_NETWORK=0 <pm> exec -- <body>\` form for the detected package manager. A gate-class script whose
-body is NOT in the allowlist is screened out with a note naming it (a command you trust can still
-be declared by hand); non-gate-class names are excluded silently, as always.
+  'Disclosure: gates.json is a PRIVILEGED file — once the optional approval hook is wired ' +
+  '(/agent-workflow-kit hook), it auto-approves byte-exact declared gate commands from the ' +
+  'project root — filling (this consent) and hook wiring (its own consent) are two separate ' +
+  'yeses. A script gate runs the project\'s own tooling, which executes project-controlled code ' +
+  '(this preview does not sandbox it; the two consents bound it).';
+
+const USAGE = `usage: gates-init [--dry-run | --apply] [--only <id>]... [--cwd <dir>] [--help]
+
+The consented FILL preview for the project's own docs/ai/gates.json (D9). Default is --dry-run:
+prints the derived { id, title, cmd } entries and writes NOTHING. --apply APPENDS exactly the
+consented entries (--only <id> selects a subset; append-only — existing entries are never
+modified or removed, an id collision is refused). The offer is CLOSED-WORLD: only a
+terminating-class script name (test / lint / type-check / build — never release/publish/deploy,
+never watch/serve, never a write-mode variant) whose BODY is a member of the literal runner
+allowlist is offered, as the hook-free \`COREPACK_ENABLE_NETWORK=0 <pm> exec -- <body>\` form for
+the detected package manager. A gate-class script whose body is NOT in the allowlist is screened
+out with a note naming it (a command you trust can still be declared by hand); non-gate-class
+names are excluded silently, as always.
 ${TRUST_CHAIN_DISCLOSURE}`;
 
 // ── candidate classification: the NAME screens (the LOCKED derivation invariants) ──────
@@ -310,12 +313,14 @@ export const reviewStateCandidate = (cwd, deps = {}) => {
   }
 };
 
-// The conditional review-LEDGER candidate (AD-045) — the SAME consent + conditional rule as the
-// review-state candidate (offered ONLY when plan-execution.review is reviewed/council), keyed on the
-// same slot, path resolved + QUOTED. It gates the review-ROUND ledger (converged / resolved-residual);
-// review-state gates receipt PRESENCE. Both may be offered together — distinct axes.
-export const reviewLedgerCandidate = (cwd, deps = {}) => {
-  const toolPath = deps.reviewLedgerTool ?? REVIEW_LEDGER_TOOL;
+// The conditional COVERAGE-CHECK candidate (D3(a)) — the SAME consent + conditional rule as the
+// review-state candidate (offered ONLY when plan-execution.review is reviewed/council), keyed on
+// the same slot, path resolved + QUOTED. Together they are the canonical core pair `run-gates
+// --final` requires (the checker declared LAST — buildOffer appends it last so a whole-offer
+// apply lands final-ready); review-state gates receipt satisfaction, coverage-check verifies the
+// consumed lcov + the red-proof declarations.
+export const coverageCheckCandidate = (cwd, deps = {}) => {
+  const toolPath = deps.coverageCheckTool ?? COVERAGE_CHECK_TOOL;
   try {
     const { config } = loadConfig(resolve(cwd), deps.readFile ?? readFileSync, deps.lstat ?? lstatSync);
     const declared = config?.['plan-execution']?.review;
@@ -324,15 +329,15 @@ export const reviewLedgerCandidate = (cwd, deps = {}) => {
       return {
         candidate: null,
         note:
-          `the review-ledger candidate was withheld: the resolved kit path contains shell ` +
+          `the coverage-check candidate was withheld: the resolved kit path contains shell ` +
           `metacharacters that do not survive double-quoting (${toolPath}) — declare the gate ` +
-          `by hand per references/modes/review-ledger.md`,
+          `by hand per references/modes/coverage-check.md`,
       };
     }
     return {
       candidate: {
-        id: 'review-ledger',
-        title: 'Review-round ledger: the in-flight loop is converged or resolved-residual',
+        id: 'coverage-check',
+        title: 'Changed-line coverage + red-proof verification (the final-run checker)',
         cmd: `node "${toolPath}" --check`,
       },
       note: null,
@@ -340,7 +345,7 @@ export const reviewLedgerCandidate = (cwd, deps = {}) => {
   } catch (err) {
     return {
       candidate: null,
-      note: `orchestration config unreadable (${err.message}) — the review-ledger candidate was not evaluated`,
+      note: `orchestration config unreadable (${err.message}) — the coverage-check candidate was not evaluated`,
     };
   }
 };
@@ -356,22 +361,23 @@ const assertOnlyIdsOffered = (offer, onlyIds = []) => {
   }
 };
 
-// The full offer: script entries + the conditional review-state + review-ledger candidates (last),
-// plus loud notes. Both review candidates key on the same slot (plan-execution.review reviewed/council)
-// but gate distinct axes (receipt presence vs review-round convergence) — offered together.
+// The full offer: script entries + the conditional review-state + coverage-check candidates
+// (coverage-check LAST — the `run-gates --final` declaration-shape rule requires the checker as
+// the last declared gate, so a whole-offer apply is final-ready by construction). Both key on the
+// same slot (plan-execution.review reviewed/council) but gate distinct axes.
 export const buildOffer = (cwd, deps = {}) => {
   const scripts = deriveScripts(cwd, deps);
   const rs = reviewStateCandidate(cwd, deps);
-  const rl = reviewLedgerCandidate(cwd, deps);
-  const candidates = [rs.candidate, rl.candidate].filter(Boolean);
+  const cc = coverageCheckCandidate(cwd, deps);
+  const candidates = [rs.candidate, cc.candidate].filter(Boolean);
   return {
     entries: [...scripts.entries, ...candidates],
-    notes: [...scripts.notes, rs.note, rl.note].filter(Boolean),
+    notes: [...scripts.notes, rs.note, cc.note].filter(Boolean),
   };
 };
 
 // The RUNNABLE apply invocation for a given project — this tool has no bin and no mode token, so
-// the consent step must print the real command, never a bare `seed-gates`. Consent integrity: a
+// the consent step must print the real command, never a bare `gates-init`. Consent integrity: a
 // previewed --only subset is carried into the hint VERBATIM (ids are shell-safe by construction —
 // kebabIdOf output / the fixed `review-state`), so following the hint can never widen the consent.
 // Paths that do not survive double-quoting (the reviewStateCandidate screen, same pattern) make
@@ -386,7 +392,7 @@ export const applyInvocationFor = (cwd, onlyIds = []) => {
 const GENERIC_APPLY_HINT = 're-run this same command with --apply [--only <id>]...';
 
 export const formatPreview = (offer, applyInvocation = null, { explicitOnly = false } = {}) => {
-  const lines = ['[agent-workflow-kit] gates seeding preview (dry-run — nothing was written):'];
+  const lines = ['[agent-workflow-kit] gates fill preview (dry-run — nothing was written):'];
   if (!offer.entries.length) {
     lines.push('  nothing to offer — no seedable terminating verification scripts were found.');
   }
@@ -418,14 +424,14 @@ const loadExistingDeclaration = (cwd, deps = {}) => {
     try {
       return JSON.parse(String(read(full, 'utf8')));
     } catch (err) {
-      throw stop(`${GATES_REL}: malformed JSON (${err.message}) — fix it by hand; the seeder never writes over a declaration it cannot parse`);
+      throw stop(`${GATES_REL}: malformed JSON (${err.message}) — fix it by hand; this preview never writes over a declaration it cannot parse`);
     }
   })();
   const gates = (() => {
     try {
       return validateDeclaration(parsed);
     } catch (err) {
-      throw stop(`${err.message} — fix it by hand; the seeder never writes over an invalid declaration`);
+      throw stop(`${err.message} — fix it by hand; this preview never writes over an invalid declaration`);
     }
   })();
   return { outcome: 'loaded', readme: typeof parsed._README === 'string' ? parsed._README : undefined, gates };
@@ -453,7 +459,7 @@ const readStampValue = (cwd, deps = {}) => {
 };
 
 // ── apply (append exactly the consented entries) ───────────────────────────────────────
-export const applySeed = ({ cwd, onlyIds = [] }, deps = {}) => {
+export const applyFill = ({ cwd, onlyIds = [] }, deps = {}) => {
   assertDocsAiDeployment(cwd, deps, { stop, noun: 'a gate declaration', rel: GATES_REL });
   const stampValue = readStampValue(cwd, deps);
   if (stampValue !== EXPECTED_WORKFLOW_VERSION) {
@@ -474,7 +480,7 @@ export const applySeed = ({ cwd, onlyIds = [] }, deps = {}) => {
   if (collisions.length) {
     throw stop(
       `id collision — already declared in ${GATES_REL}: ${collisions.join(', ')} (append-only: the ` +
-        `seeder never modifies or removes an existing entry; pick the others with --only, or edit by hand)`,
+        `fill never modifies or removes an existing entry; pick the others with --only, or edit by hand)`,
     );
   }
 
@@ -539,7 +545,7 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
       log(formatPreview(filtered, applyInvocationFor(cwd, args.only), { explicitOnly: args.only.length > 0 }));
       return EXIT_OK;
     }
-    const result = applySeed({ cwd, onlyIds: args.only }, deps);
+    const result = applyFill({ cwd, onlyIds: args.only }, deps);
     if (result.outcome === 'nothing') {
       log('[agent-workflow-kit] nothing to offer — no seedable terminating verification scripts were found; wrote nothing.');
       for (const note of result.notes) log(`  note: ${note}`); // the user learns WHY (same note as the preview)

package/tools/grounding.mjs

@@ -23,7 +23,7 @@
 // not-ignored path (a new untracked file would itself move the review fingerprint the facts are
 // about to ground). stdout is the default. It never commits and never runs a subscription CLI.
 //
-// Dependency-free, Node >= 18. No side effects on import (the isDirectRun idiom).
+// Dependency-free, Node >= 22. No side effects on import (the isDirectRun idiom).
 
 import { readFileSync, writeFileSync, lstatSync, realpathSync } from 'node:fs';
 import { resolve, join, relative, isAbsolute, dirname, basename, sep } from 'node:path';
@@ -31,11 +31,6 @@ import { tmpdir } from 'node:os';
 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';
 // (f) --autonomy (AD-044 Plan 3): the effective per-project autonomy policy for the facts payload.
 // READ core only — never autonomy-write.mjs (the import-split invariant).
 import { AUTONOMY_REL, loadAutonomy, resolveAutonomy, isSparseSeedConfig } from './autonomy-config.mjs';
@@ -107,7 +102,7 @@ export const assembleGrounding = ({ constraintsText = null, autonomyText = null,
 // Trim `payload` to `budget` bytes, tail-first, with a loud in-band marker. The budget is a HARD
 // ceiling: when it is smaller than the marker itself, the marker is truncated too (the output may
 // never exceed `budget` — a facts file over the reserved share would push the final wrapper prompt
-// past the argv ceiling; codex R1 finding). Returns { text, trimmedBytes }. Never a silent cut.
+// past the argv ceiling). Returns { text, trimmedBytes }. Never a silent cut.
 export const trimToBudget = (payload, budget) => {
   const bytes = Buffer.byteLength(payload, 'utf8');
   if (bytes <= budget) return { text: payload, trimmedBytes: 0 };
@@ -119,72 +114,10 @@ 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 });
-};
 
 // ── (f) --autonomy: the effective autonomy policy as a computed facts block (AD-044 Plan 3) ─────
 // The ONE shared resolver (resolveAutonomy) renders the FULL effective policy — every red-line and
@@ -231,17 +164,17 @@ const gitLine = (args, cwd) => {
 // EXISTING in-repo file, even gitignored, is a project file — the .env clobber class). Refused:
 // tracked paths, in-repo not-ignored paths (a new untracked file would move the fingerprint),
 // every other outside-repo destination, symlink and existing non-regular leaves, and any
-// unverifiable lstat. The check runs on the REAL destination, never the lexical path (codex R1):
+// unverifiable lstat. The check runs on the REAL destination, never the lexical path:
 // the parent directory is realpath-resolved first, so a symlink can never route the write onto a
 // tracked/in-repo file. Returns { path, kind: 'temp' | 'repo-fresh' } — a repo-fresh caller MUST
-// write with the exclusive flag ('wx'), sealing the guard→write race (codex R11).
+// write with the exclusive flag ('wx'), sealing the guard→write race.
 export const assertScratchDestination = (outPath, cwd) => {
   const lexical = isAbsolute(outPath) ? outPath : resolve(cwd, outPath);
   let leaf = null;
   try {
     leaf = lstatSync(lexical);
   } catch (err) {
-    // ONLY an absent leaf is a fresh file; any other lstat failure fails CLOSED (codex R9 — this
+    // ONLY an absent leaf is a fresh file; any other lstat failure fails CLOSED (this
     // writer is bridge-tier auto-allowable, so an unverifiable leaf must never be written).
     if (err?.code !== 'ENOENT') {
       throw fail(1, `--out cannot inspect the destination (${outPath}: ${err?.code ?? err?.message ?? err}) — refusing to write an unverifiable leaf`);
@@ -252,7 +185,7 @@ export const assertScratchDestination = (outPath, cwd) => {
     throw fail(1, `--out refuses a symlink destination (${outPath}) — the write would follow it onto another file; name the real scratch path`);
   }
   if (leaf != null && !leaf.isFile()) {
-    throw fail(1, `--out refuses an existing non-regular destination (${outPath}) — a FIFO/device/directory write would hang or land on a non-file (codex R9); name a fresh or regular scratch path`);
+    throw fail(1, `--out refuses an existing non-regular destination (${outPath}) — a FIFO/device/directory write would hang or land on a non-file; name a fresh or regular scratch path`);
   }
   let realParent;
   try {
@@ -261,8 +194,8 @@ export const assertScratchDestination = (outPath, cwd) => {
     throw fail(1, `--out parent directory does not exist (${dirname(lexical)}) — create the scratch dir first`);
   }
   const full = join(realParent, basename(lexical));
-  // An out-of-repo (or no-repo) destination is scratch ONLY under a system temp root (codex R8
-  // blocker): the bridge tier auto-allows this tool with an args wildcard, so "anything outside
+  // An out-of-repo (or no-repo) destination is scratch ONLY under a system temp root: the bridge
+  // tier auto-allows this tool with an args wildcard, so "anything outside
   // the repo is scratch" would let an unattended run overwrite e.g. ~/.bashrc promptless.
   // $TMPDIR / os.tmpdir() / /tmp are the scratch surface; everything else refuses loudly.
   const assertTempScratch = () => {
@@ -282,7 +215,7 @@ export const assertScratchDestination = (outPath, cwd) => {
   if (top == null || top.status !== 0) return { path: assertTempScratch().path, kind: 'temp' }; // no git tree → temp-only scratch
   const root = top.stdout.replace(/\r?\n$/, '');
   const rel = relative(root, full);
-  // Segment-safe outside test (the Issue-004 class, codex R5): an in-repo file literally named
+  // Segment-safe outside test (the Issue-004 class): an in-repo file literally named
   // `..facts` has rel `..facts` — `startsWith('..')` would misread it as outside and BYPASS the
   // tracked/ignored refusals below. Only `..` exactly or a `..${sep}`-prefixed rel is outside.
   if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return { path: assertTempScratch().path, kind: 'temp' };
@@ -294,11 +227,11 @@ export const assertScratchDestination = (outPath, cwd) => {
   if (ignored == null || ignored.status !== 0) {
     throw fail(1, `--out refuses an in-repo path that is not gitignored (${rel}) — a new untracked file would move the review fingerprint; use a gitignored path or a location outside the repo`);
   }
-  // An in-repo destination must be a FRESH file (codex R10): even a gitignored existing file is a
+  // An in-repo destination must be a FRESH file: even a gitignored existing file is a
   // project file (.env is the canonical victim) — an auto-allowable writer must never clobber one.
   // The rewritable scratch surface is the system temp; in-repo gitignored writes are create-only —
   // the CALLER must open with the exclusive flag ('wx'): the kind seals the pre-check against the
-  // guard→write race (codex R11).
+  // guard→write race.
   if (leaf != null) {
     throw fail(1, `--out refuses to OVERWRITE an existing in-repo file (${rel}) — even gitignored, it is a project file (the .env class); write rewritable scratch under $TMPDIR//tmp, or remove the file first`);
   }
@@ -310,7 +243,7 @@ export const assertScratchDestination = (outPath, cwd) => {
 const HELP = `grounding — grounded-review facts assembler for the agent-workflow family (AD-038).
 
 Usage:
-  node grounding.mjs [--constraints] [--autonomy] [--plan <path>] [--ledger-summary] [--reserve-bytes <n>] [--out <path>]
+  node grounding.mjs [--constraints] [--autonomy] [--plan <path>] [--reserve-bytes <n>] [--out <path>]
 
   --constraints        slice the root AGENTS.md "Hard Constraints" section verbatim
                        (exactly one matching heading, else a loud STOP)
@@ -322,10 +255,6 @@ Usage:
   --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 — system-temp scratch (rewritable), or a FRESH
@@ -345,12 +274,10 @@ 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 === '--autonomy') autonomy = 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>');
@@ -366,10 +293,10 @@ const parseArgs = (argv) => {
       i += 1;
     } else throw fail(2, `unknown argument: ${a}`);
   }
-  if (!constraints && !autonomy && plan == null && !ledgerSummary) {
-    throw fail(2, 'nothing to assemble — pass --constraints, --autonomy, --plan <path>, and/or --ledger-summary');
+  if (!constraints && !autonomy && plan == null) {
+    throw fail(2, 'nothing to assemble — pass --constraints, --autonomy, and/or --plan <path>');
   }
-  return { constraints, autonomy, plan, out, reserve, ledgerSummary };
+  return { constraints, autonomy, plan, out, reserve };
 };
 
 const resolveBudget = (env, reserve) => {
@@ -389,7 +316,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, autonomy, plan, out, reserve, ledgerSummary } = parseArgs(argv);
+    const { constraints, autonomy, plan, out, reserve } = parseArgs(argv);
     const budget = resolveBudget(env, reserve);
 
     const readOrStop = (path, label) => {
@@ -401,7 +328,7 @@ export const main = (argv, ctx = {}) => {
     };
     const constraintsText = constraints ? readOrStop('AGENTS.md', 'root AGENTS.md') : null;
     const autonomyText = autonomy ? resolveAutonomyFacts({ cwd }) : null;
-    // --plan is CONFINED to the git work tree (codex R4): the bridge tier auto-allows this tool
+    // --plan is CONFINED to the git work tree: the bridge tier auto-allows this tool
     // with an args wildcard, so an unattended invocation could otherwise point --plan at ANY
     // readable file and ship it into the facts payload. Plans are in-repo by contract
     // (docs/plans); an outside-tree path is a loud refusal, never a silent read.
@@ -424,10 +351,6 @@ export const main = (argv, ctx = {}) => {
     const parts = [];
     const assembled = assembleGrounding({ constraintsText, autonomyText, 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
@@ -437,7 +360,7 @@ export const main = (argv, ctx = {}) => {
     if (out != null) {
       const dest = assertScratchDestination(out, cwd);
       // repo-fresh writes are EXCLUSIVE ('wx'): the create-only pre-check would otherwise race a
-      // file created between the guard and this write (codex R11); temp scratch stays rewritable.
+      // file created between the guard and this write; temp scratch stays rewritable.
       // ctx.writeFile is a TEST seam (the EEXIST race arm is not constructible without it).
       const writeFile = ctx.writeFile ?? writeFileSync;
       try {
@@ -457,7 +380,7 @@ export const main = (argv, ctx = {}) => {
 const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (isDirectRun) {
   const r = main(process.argv.slice(2));
-  // Exact writes + a natural exit (codex R2): console.log would append a stray newline to the
+  // Exact writes + a natural exit: console.log would append a stray newline to the
   // byte-exact facts payload, and process.exit() can truncate large piped stdout before Node
   // flushes. The payload already ends with '\n' (sliceSection normalizes); only a non-payload
   // message (help / the --out report) gains the terminating newline it lacks.

package/tools/hide-footprint.mjs

@@ -17,7 +17,7 @@
 // path). Add-local-first, then DETECT + REPORT the residual legacy global block — removal is the
 // explicit, ASK-gated `--remove-global` (prints a restorable backup), never a default (an arbitrary
 // host's OTHER hidden repo may rely on the same root-anchored global lines). Windows is supported (text
-// edit; forward-slash patterns; CRLF preserved via EOL detection). Dependency-free, Node >= 18.
+// edit; forward-slash patterns; CRLF preserved via EOL detection). Dependency-free, Node >= 22.
 
 import {
   readFileSync, writeFileSync, statSync, readdirSync,