@sabaiway/agent-workflow-kit 2.1.0 → 3.1.0

package/tools/coverage-check.mjs

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+// coverage-check.mjs — the D3(c)+(d) final-run checker (strip-the-kit 2.3). ONE deterministic
+// read-only check over two evidence sources:
+//   • COVERAGE (D3(d)): the suite leaves an lcov file at ONE FIXED kit-owned path —
+//     <git dir>/agent-workflow-lcov.info (inside the git dir it sits outside the fingerprint
+//     domain and is never committable by construction). Uncovered CHANGED executable Node lines
+//     are LISTED file:line and fail; a changed file ABSENT from the coverage map is a file-level
+//     red (never "non-executable by silence"); changed out-of-domain files are LISTED (the claim
+//     is narrowed to Node executable lines — stated, never silently widened or greened); a repo
+//     with NO lcov at the path is a LOUD `skipped-no-lcov`, never a silent green; the path is
+//     lstat'd no-follow — a symlink is a refusal.
+//   • RED PROOF (D3(c)): every authoritative red-proof record at the CURRENT base must hold NOW —
+//     the bound test file exists, its content hash is unchanged (custody), the testId resolves to
+//     >=1 test and runs GREEN N/N, and the record's PRE-FIX fingerprint differs from the current
+//     tree (an equal fingerprint means nothing changed since the red — reuse/forgery, refused).
+//     Deleted-test and zero-match guards ride the same bound set. A malformed evidence store
+//     fails CLOSED (the obligations are unknown).
+// Every refusal names its locations (file:line / testId) — never a bare count.
+//
+// Read-only: never writes; spawns read-only git queries + the bound-test probes (node --test).
+// Dependency-free, Node >= 22. No side effects on import.
+
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { computeChangedSurface } from './changed-surface.mjs';
+import { lcovCoveredMap, uncoveredChangedFromLcov } from './lcov.mjs';
+import {
+  computeTreeFingerprint,
+  resolveBase,
+  resolveEvidencePath,
+  readEvidence,
+  authoritativeOfKind,
+  resolveTestFile,
+  hashFileBytes,
+  defaultBoundArgv,
+  parseProbeOutput,
+  childTestEnv,
+  probeKnobsFromEnv,
+  splitTestId,
+} from './core-evidence.mjs';
+
+export const COVERAGE_CHECK_STOP = 'COVERAGE_CHECK_STOP';
+const usageFail = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { exitCode: 2 });
+
+export const LCOV_BASENAME = 'agent-workflow-lcov.info';
+
+const GIT_MAX_BUFFER = 256 * 1024 * 1024;
+const gitLine = (args, cwd) => {
+  const r = spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+  if (r.error || r.status !== 0) return null;
+  return r.stdout.toString('utf8').replace(/\r?\n$/, '');
+};
+
+// AW_LCOV_FILE overrides (tests); else <git dir>/basename — resolved via the TRUE git dir (in a
+// worktree `.git` is a FILE, a hardcoded path would ENOTDIR); null outside a git work tree.
+export const resolveLcovPath = (cwd, env = process.env) => {
+  if (env.AW_LCOV_FILE) return env.AW_LCOV_FILE;
+  const gitDir = gitLine(['rev-parse', '--absolute-git-dir'], cwd);
+  return gitDir == null ? null : join(gitDir, LCOV_BASENAME);
+};
+
+// ── the coverage arm (D3(d)) ──────────────────────────────────────────────────────────────────────
+
+// checkCoverage({ rootTop, lcovPath }) → { failures: ["file:line"...], notes: [...], skipped,
+// lcovSha256 } — the sha is of the EXACT bytes this check consumed (read once), so the final-run
+// receipt can bind what was CHECKED, not what happens to sit on disk later (M2, round 1).
+const checkCoverage = ({ rootTop, lcovPath }) => {
+  const notes = [];
+  const failures = [];
+  let st = null;
+  try {
+    st = lstatSync(lcovPath);
+  } catch {
+    st = null;
+  }
+  if (st == null) {
+    return { failures, notes: [`skipped-no-lcov: no lcov file at ${lcovPath} — NO coverage check ran (produce it via the declared unit-tests gate cmd's lcov reporters)`], skipped: true, lcovSha256: null };
+  }
+  if (!st.isFile()) {
+    failures.push(`${lcovPath}: not a regular file (a symlink/device is never read — fail closed)`);
+    return { failures, notes, skipped: false, lcovSha256: null };
+  }
+  const surface = computeChangedSurface(rootTop);
+  const lcovBytes = readFileSync(lcovPath);
+  const lcovSha256 = createHash('sha256').update(lcovBytes).digest('hex');
+  const covered = lcovCoveredMap(lcovBytes.toString('utf8'), rootTop);
+  for (const [rel, lines] of surface.assessable) {
+    const key = keyFor(rootTop, rel);
+    const uncovered = uncoveredChangedFromLcov(covered, key, lines);
+    if (uncovered === null) {
+      failures.push(`${rel}: absent from coverage — the suite never executed this changed file`);
+      continue;
+    }
+    for (const n of uncovered) failures.push(`${rel}:${n}`);
+  }
+  if (surface.outOfDomain.length > 0) {
+    notes.push(`out-of-domain changed files (no Node-line coverage claim; covered by their own suites): ${surface.outOfDomain.join(', ')}`);
+  }
+  if (surface.unsupported.length > 0) {
+    notes.push(`unsupported-source changed files (outside the narrowed Node domain): ${surface.unsupported.join(', ')}`);
+  }
+  return { failures, notes, skipped: false, lcovSha256 };
+};
+
+// lcovCoveredMap canonicalizes SF paths with realpath — the lookup key must mirror it. On an
+// unresolvable path (deleted between the surface pass and here) the lexical abs stands in, which
+// then reads as absent-from-map → a file-level red, never a silent skip. Exported as a test seam.
+export const keyFor = (rootTop, rel) => {
+  const abs = join(rootTop, rel);
+  try {
+    return realpathSync(abs);
+  } catch {
+    return abs;
+  }
+};
+
+// ── the red-proof verification arm (D3(c)) ────────────────────────────────────────────────────────
+
+// verifyRedProofs({ rootTop, cwd, env }) → { failures: [...], verified: n } | { storeFailure }.
+const verifyRedProofs = ({ rootTop, cwd, env }) => {
+  const storePath = resolveEvidencePath(cwd, env);
+  const read = storePath ? readEvidence(storePath) : { records: [], malformed: 0, malformedReasons: [] };
+  if ((read.malformed ?? 0) > 0 || read.readError) {
+    return { storeFailure: `evidence store unavailable (${read.malformed} malformed line(s)${read.readError ? `, read error: ${read.readError}` : ''}) — the red-proof obligations are unknown (fail closed); inspect ${storePath}` };
+  }
+  const base = resolveBase(cwd);
+  const fingerprint = computeTreeFingerprint(cwd);
+  const bound = authoritativeOfKind(read.records, 'red-proof').filter((r) => r.base === base);
+  const { reruns, timeoutS } = probeKnobsFromEnv(env);
+  const failures = [];
+  for (const record of bound) {
+    const id = record.testId;
+    if (record.fingerprint === fingerprint) {
+      failures.push(`${id}: the record's pre-fix fingerprint EQUALS the current tree — nothing changed since the observed red (reuse/forgery); re-observe on the pre-fix tree`);
+      continue;
+    }
+    const resolved = resolveTestFile(rootTop, record.file);
+    if (!resolved.ok) {
+      failures.push(`${id}: the bound test file ${resolved.reason.includes('does not exist') ? 'was deleted — ' : ''}${resolved.reason}`);
+      continue;
+    }
+    const currentHash = hashFileBytes(resolved.abs);
+    if (currentHash !== record.fileHash) {
+      failures.push(`${id}: the bound test file's content changed since the observed red (hash mismatch) — re-observe red at the new expectations`);
+      continue;
+    }
+    let greens = 0;
+    let executed = 0;
+    for (let i = 0; i < reruns; i += 1) {
+      const argv = defaultBoundArgv(resolved.abs, splitTestId(id).pattern);
+      const res = spawnSync(argv[0], argv.slice(1), { cwd: rootTop, env: childTestEnv(env), encoding: 'utf8', maxBuffer: GIT_MAX_BUFFER, timeout: timeoutS * 1000 });
+      const p = parseProbeOutput({ stdout: res.stdout ?? '', code: res.error ? 1 : res.status ?? 1, fileArg: record.file });
+      executed = Math.max(executed, p.executed);
+      if (p.resolvable && p.baselineGreen) greens += 1;
+    }
+    if (executed === 0) {
+      failures.push(`${id}: the pattern selects no test (zero-match) — the declared red→green pin is gone`);
+      continue;
+    }
+    if (greens !== reruns) {
+      failures.push(`${id}: not green ${reruns}/${reruns} at the final run (${greens}/${reruns} green) — the declared fix is red`);
+    }
+  }
+  return { failures, verified: bound.length };
+};
+
+// ── the check ─────────────────────────────────────────────────────────────────────────────────────
+
+export const runCheck = ({ cwd = process.cwd(), env = process.env } = {}) => {
+  const rootTop = gitLine(['rev-parse', '--show-toplevel'], cwd);
+  if (rootTop == null) return { code: 0, lines: ['coverage-check: not a git work tree — nothing to check'] };
+  const lcovPath = resolveLcovPath(cwd, env);
+  const lines = [];
+  let failed = false;
+  const cov = checkCoverage({ rootTop, lcovPath });
+  // The machine line the final-run receipt binds (M2): the sha of the exact bytes THIS check
+  // consumed — `none` states loudly that no lcov was read.
+  lines.push(`coverage-check: lcov-sha256=${cov.lcovSha256 ?? 'none'}`);
+  if (cov.skipped) {
+    lines.push(`coverage-check: ${cov.notes[0]}`);
+  } else {
+    for (const note of cov.notes) lines.push(`coverage-check: ${note}`);
+    if (cov.failures.length > 0) {
+      failed = true;
+      lines.push('coverage-check: FAIL — uncovered/unattributed changed Node lines:');
+      for (const f of cov.failures) lines.push(`  ${f}`);
+    }
+  }
+  const red = verifyRedProofs({ rootTop, cwd, env });
+  if (red.storeFailure) {
+    failed = true;
+    lines.push(`coverage-check: FAIL — ${red.storeFailure}`);
+  } else {
+    if (red.failures.length > 0) {
+      failed = true;
+      lines.push('coverage-check: FAIL — red-proof obligations not satisfied:');
+      for (const f of red.failures) lines.push(`  ${f}`);
+    } else if (red.verified > 0) {
+      lines.push(`coverage-check: ${red.verified} red-proof record(s) verified green N/N with custody intact`);
+    }
+  }
+  if (!failed && !cov.skipped && cov.failures.length === 0) {
+    lines.push('coverage-check: PASS — every changed Node line is covered');
+  }
+  return { code: failed ? 1 : 0, lines };
+};
+
+// ── CLI ───────────────────────────────────────────────────────────────────────────────────────────
+
+const HELP = `coverage-check — the D3(c)+(d) final-run checker (agent-workflow family).
+
+Usage:
+  node coverage-check.mjs --check [--cwd <dir>]
+
+Reads the FIXED kit-owned lcov file (<git dir>/${LCOV_BASENAME}; AW_LCOV_FILE overrides —
+produced by the declared unit-tests gate cmd's --experimental-test-coverage lcov reporters and
+deleted fresh by run-gates --final), lists uncovered CHANGED executable Node lines file:line,
+lists changed out-of-domain files (the coverage claim is narrowed to Node lines), and VERIFIES
+every current-base red-proof record: bound test present, content hash unchanged, green N/N
+(AW_CORE_EVIDENCE_RERUNS, default 3), pre-fix fingerprint differing from the current tree.
+An absent lcov file is a LOUD skipped-no-lcov (exit 0 — NO coverage check ran, stated); a
+symlinked lcov path, an uncovered line, a broken red-proof obligation, or a malformed evidence
+store fails (exit 1).
+
+Sandbox-safe: no network; writes nothing; spawns read-only git queries and the bound-test
+probes (node --test, shell-free) — the D4 sandbox lane.
+Read-only. Exit codes: 0 pass/skipped-loud; 1 fail; 2 usage.`;
+
+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: '' };
+    let cwd = ctx.cwd ?? process.cwd();
+    const rest = [...argv];
+    const cwdAt = rest.indexOf('--cwd');
+    if (cwdAt !== -1) {
+      cwd = rest[cwdAt + 1];
+      if (cwd === undefined) throw usageFail('--cwd needs a directory');
+      rest.splice(cwdAt, 2);
+    }
+    const checkAt = rest.indexOf('--check');
+    if (checkAt !== -1) rest.splice(checkAt, 1);
+    if (rest.length > 0) throw usageFail(`unknown argument: ${rest[0]}`);
+    const { code, lines } = runCheck({ cwd, env });
+    return { code, stdout: lines.join('\n'), stderr: '' };
+  } catch (err) {
+    return { code: err.exitCode ?? 1, stdout: '', stderr: `coverage-check: ${err.message}` };
+  }
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+  const r = main(process.argv.slice(2));
+  if (r.stdout) process.stdout.write(r.stdout.endsWith('\n') ? r.stdout : `${r.stdout}\n`);
+  if (r.stderr) process.stderr.write(r.stderr.endsWith('\n') ? r.stderr : `${r.stderr}\n`);
+  process.exitCode = r.code;
+}

package/tools/delegation.mjs

@@ -6,7 +6,7 @@
 //   detectMemory(dir) → { delegate, reason, ... }   runs the kit's OWN validator + asset check
 //   handoffPlan(delegate) → who writes what, which stamps end up present, who owns the commit gate
 //
-// Pure (dependency-injectable validator + fs), dependency-free, Node >= 18.
+// Pure (dependency-injectable validator + fs), dependency-free, Node >= 22.
 
 import { statSync } from 'node:fs';
 import { join, resolve } from 'node:path';

package/tools/detect-backends.mjs

@@ -16,7 +16,7 @@
 // credential marker, stable setup URL) must live here. A drift-guard test keeps the registry in
 // lockstep with the in-repo manifests.
 //
-// Pure, dependency-injectable (fs/env/validator are deps), dependency-free, Node >= 18. Every fs
+// Pure, dependency-injectable (fs/env/validator are deps), dependency-free, Node >= 22. Every fs
 // probe is wrapped → an explicit `unknown` + reason, never a throw and never a nameless failure.
 
 import { existsSync, statSync, accessSync, realpathSync, constants } from 'node:fs';
@@ -91,7 +91,7 @@ const RAW_BACKENDS = [
         ],
         grounding: 'automatic — the wrapper precomputes the full working-tree change set (repo map, status, diffs, untracked contents) and codex auto-merges the root AGENTS.md; no grounding flags',
         continue: [],
-        receipt: 'side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan mode; verdict parsed from the mandated literal verdict line (schema mode: the verdict field); always fresh:true (one-shot) + grounded:true (native AGENTS.md auto-merge, factsHash null); probe = whether the run relaxed the quality guards (CODEX_PROBE=1), written on EVERY receipt so it self-declares — the kit\'s review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); a write failure warns, never fails the review',
+        receipt: 'side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan mode; verdict parsed from the mandated literal verdict line (schema mode: the verdict field); always fresh:true (one-shot) + grounded:true (native AGENTS.md auto-merge, factsHash null); probe = whether the run relaxed the quality guards (CODEX_PROBE=1), written on EVERY receipt so it self-declares — the kit\'s review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); posture = the ACTUAL run posture {model, effort, tier} (tier null on the standard tier), written on EVERY receipt (D5) — the gate rejects a receipt with an absent/invalid posture (a pre-D5 wrapper minted it; re-run the review), one stderr banner line states the same posture, and a posture value carrying control bytes refuses pre-spend in every mode; a run whose final message carries NO recognized \'Verdict: <ship|revise|rethink>\' line — empty or missing output included — exits 4 with NO receipt (D4: a FAILED review to RE-RUN, never a fatal session error); a write failure warns, never fails the review',
       },
     },
     bin: 'codex',
@@ -125,7 +125,7 @@ const RAW_BACKENDS = [
           'agy-review --continue [--decided @f] [--focus "…"]',
           'agy-review --conversation <id> [--decided @f] [--focus "…"]',
         ],
-        receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (code mode refuses pre-spend without one — no run, no receipt — unless --ungrounded/AGY_PROBE=1; in plan/diff an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); probe = whether the run relaxed the quality guards (AGY_PROBE=1), written on EVERY receipt so it self-declares — the kit's review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); a write failure warns, never fails the review",
+        receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (code mode refuses pre-spend without one — no run, no receipt — unless --ungrounded/AGY_PROBE=1; in plan/diff an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); probe = whether the run relaxed the quality guards (AGY_PROBE=1), written on EVERY receipt so it self-declares — the kit's review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); posture = the ACTUAL run posture {model} (agy has no tier), written on EVERY receipt (D5) — the gate rejects a receipt with an absent/invalid posture (a pre-D5 wrapper minted it; re-run the review), one stderr banner line states the same posture, an ATTESTING review with AGY_MODEL explicitly emptied refuses pre-spend, and a model string carrying control bytes refuses pre-spend in every mode; a run whose output carries NO recognized '### Verdict' section — empty output included — exits 4 with NO receipt (D4: a FAILED review to RE-RUN, never a fatal session error); a write failure warns, never fails the review",
         notes: [
           'pre-dispatch host-diff: before the FIRST dispatch of this bridge, diff its declared networkHosts against the live sandbox allow-list — a missing host is surfaced to the maintainer BEFORE dispatching, never fired into a known prompt',
         ],

package/tools/doc-parity.mjs

@@ -7,25 +7,21 @@
 // asserts the current value renders into every bound `references/modes/*.md` file.
 //
 // Why the modes/*.md docs and not the tool HELP strings: every tool's HELP INTERPOLATES the same
-// constant (`the ${DEFAULT_DIFF_CAP}-line diff cap`), so it can never drift from the code — there is
-// nothing to check there. The hand-authored contract prose in `references/modes/*.md` is the surface
-// that DOES drift, so that is exactly what this lint pins. The numeric/version tokens are IMPORTED
-// live from the tools (never re-typed here), and the ledger vocabulary is sourced from the schema's
-// own exported `V4_CLASSES` / `V4_OVERRIDE_SCOPES` Sets — so the registry cannot itself go stale.
+// constant, so it can never drift from the code — there is nothing to check there. The
+// hand-authored contract prose in `references/modes/*.md` is the surface that DOES drift, so that
+// is exactly what this lint pins. The tokens are IMPORTED live from the tools (never re-typed
+// here) — so the registry cannot itself go stale.
 //
 // Edit-safe by construction (the U2-DEBT closed-world lesson): adding a binding ADDS a checked entry;
 // it never widens a blocklist. A token that stops appearing, a file that cannot be read, or an
 // unknown binding all FAIL CLOSED — never a silent pass.
 //
 // Read-only: never writes, never commits, never runs a subscription CLI, spawns nothing. Dependency-
-// free, Node >= 18. No side effects on import (the isDirectRun idiom).
+// free, Node >= 22. No side effects on import (the isDirectRun idiom).
 
 import { readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { SCHEMA_VERSION, REVIEW_CAP, V4_CLASSES, V4_OVERRIDE_SCOPES } from './review-ledger.mjs';
-import { HARD_MAX, DEFAULT_DIFF_CAP } from './review-ledger-write.mjs';
-import { RESULT_SCHEMA_VERSION } from './fold-completeness.mjs';
 import { EXIT as DOCTOR_EXIT, STATUS as DOCTOR_STATUS, TRUSTED_DIRS as DOCTOR_TRUSTED_DIRS } from './autonomy-doctor.mjs';
 import {
   RECOMMENDATIONS_SECTION_HEADER,
@@ -40,8 +36,6 @@ import { SKIPPED_READONLY } from './setup-backends.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
-const REVIEW_LEDGER_DOC = 'references/modes/review-ledger.md';
-const FOLD_DOC = 'references/modes/fold-completeness.md';
 const AUTONOMY_DOCTOR_DOC = 'references/modes/autonomy-doctor.md';
 const RECOMMENDATIONS_DOC = 'references/modes/recommendations.md';
 const UPGRADE_DOC = 'references/modes/upgrade.md';
@@ -57,10 +51,6 @@ const usageFail = (message) => Object.assign(new Error(message), { exitCode: 2 }
 // prose in the named files; a value drift makes the current-value token absent → a loud failure.
 const valueBinding = (constant, value, phrase, files) => ({ constant, value, token: phrase, files });
 
-// The ledger vocabulary — sourced from the schema's own exported Sets plus the v4 `gate-run` kind,
-// so the closed set can never disagree with the code. Every word must appear in the ledger contract.
-const LEDGER_VOCAB = [...V4_CLASSES, ...V4_OVERRIDE_SCOPES, 'gate-run'];
-
 // The autonomy-doctor D7 contract (AD-044 Plan 2): the live EXIT table + every status token must
 // render into the mode's contract doc. `usage` is skipped as a bare-word token (trivially present
 // everywhere) — its exit-code phrase below pins that outcome instead.
@@ -75,12 +65,6 @@ const DOCTOR_EXIT_PHRASES = [
 ];
 
 export const BINDINGS = Object.freeze([
-  valueBinding('SCHEMA_VERSION', SCHEMA_VERSION, `schema v${SCHEMA_VERSION}`, [REVIEW_LEDGER_DOC]),
-  valueBinding('HARD_MAX', HARD_MAX, `hard-max ceiling of ${HARD_MAX}`, [REVIEW_LEDGER_DOC]),
-  valueBinding('DEFAULT_DIFF_CAP', DEFAULT_DIFF_CAP, `default ${DEFAULT_DIFF_CAP}`, [REVIEW_LEDGER_DOC]),
-  valueBinding('REVIEW_CAP', REVIEW_CAP, `cap ≤${REVIEW_CAP}`, [REVIEW_LEDGER_DOC]),
-  valueBinding('RESULT_SCHEMA_VERSION', RESULT_SCHEMA_VERSION, `schema v${RESULT_SCHEMA_VERSION}`, [FOLD_DOC]),
-  ...LEDGER_VOCAB.map((word) => valueBinding(`vocab:${word}`, word, word, [REVIEW_LEDGER_DOC])),
   ...DOCTOR_EXIT_PHRASES.map(([key, phrase]) => valueBinding(`doctor-exit:${key}`, DOCTOR_EXIT[key], phrase, [AUTONOMY_DOCTOR_DOC])),
   ...Object.values(DOCTOR_STATUS)
     .filter((token) => token !== DOCTOR_STATUS.usage)
@@ -149,12 +133,12 @@ const HELP = `doc-parity — deterministic doc-drift lint for the agent-workflow
 Usage:
   node doc-parity.mjs [--check | --json]
 
-A CLOSED, exported registry binds each live code constant (review-ledger SCHEMA_VERSION / REVIEW_CAP,
-review-ledger-write HARD_MAX / DEFAULT_DIFF_CAP, fold-completeness RESULT_SCHEMA_VERSION), the
-ledger vocabulary (V4_CLASSES / V4_OVERRIDE_SCOPES + gate-run), and the autonomy-doctor contract
-(the EXIT table, the status tokens, the trusted-dir allowlist) to the exact token its
-references/modes/*.md contract must carry, and asserts the CURRENT value renders into every bound
-file. A drifted doc, an unreadable bound file, or an absent token FAILS CLOSED.
+A CLOSED, exported registry binds each live code constant — the autonomy-doctor contract (the EXIT
+table, the status tokens, the trusted-dir allowlist), the recommendations/upgrade presentation
+contract (section header, empty line, verdict templates), the acks-store path, and the setup
+refresh degrade token — to the exact token its references/modes/*.md contract must carry, and
+asserts the CURRENT value renders into every bound file. A drifted doc, an unreadable bound file,
+or an absent token FAILS CLOSED.
 
 --check exits 0/1 as a gate (declare it in docs/ai/gates.json by hand). --json prints the structured
 result. Default prints the per-binding report.

package/tools/engine-source.mjs

@@ -11,7 +11,7 @@
 // Fail-closed: readEngineFragment never falls back to a bundled copy (there is none after the
 // mirror retirement) — when the engine is needed but absent/invalid it throws with the exact
 // remediation, so the reconcile STOPs loudly rather than silently dropping the slot (AGENTS.md:
-// no silent failures). Pure-where-possible (fs + validator injectable for tests), Node >= 18.
+// no silent failures). Pure-where-possible (fs + validator injectable for tests), Node >= 22.
 
 import { statSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';

package/tools/family-members.mjs

@@ -8,7 +8,7 @@
 // + the drift-guard (family-registry.test.mjs pins FAMILY_MEMBERS to the 5 in-repo capability.json)
 // are preserved — the table just lives in a dependency-free leaf now.
 //
-// Pure data, no imports, no side effects, Node >= 18.
+// Pure data, no imports, no side effects, Node >= 22.
 
 // ── the unified registry ───────────────────────────────────────────────────────
 // One entry per family member. `installed` is the detect.installed spec (env + home-relative default

package/tools/family-registry.mjs

@@ -13,7 +13,7 @@
 // must live here. A drift-guard test (family-registry.test.mjs) pins FAMILY_MEMBERS to the 5 in-repo
 // capability.json files, so the table cannot silently drift from the manifests it mirrors.
 //
-// Pure, dependency-injectable (fs/env/home/validator are deps), dependency-free, Node >= 18. No
+// Pure, dependency-injectable (fs/env/home/validator are deps), dependency-free, Node >= 22. No
 // side effects on import (the isDirectRun idiom) — tests import the helpers with nothing run.
 
 import { existsSync, statSync, readFileSync, lstatSync } from 'node:fs';

package/tools/fs-safe.mjs

@@ -2,7 +2,7 @@
 // (bin/install.mjs) and the backend linker (tools/setup-backends.mjs). Importing this module has NO
 // side effects: it runs nothing. Every fs primitive is injectable via `deps.*` so the guards are
 // unit-testable without touching the real filesystem; the defaults are Node's SYNC fs (matching the
-// tools/ detector style). Dependency-free, Node >= 18.
+// tools/ detector style). Dependency-free, Node >= 22.
 //
 // Five primitives:
 //   assertContainedRealPath — refuse to write through/into a symlink, or to a dest outside a root.

package/tools/gate-hook.mjs

@@ -36,7 +36,7 @@
 // gates.json — see the read-lane writer section below.
 //
 // Exit codes: 0 done / dry-run (incl. the report-only diverged-but-wired state); 1 precondition
-// STOP; 2 usage. Dependency-free beyond the kit's own internal exports, Node >= 18. No side
+// STOP; 2 usage. Dependency-free beyond the kit's own internal exports, Node >= 22. No side
 // effects on import.
 
 import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';