@sabaiway/agent-workflow-kit 1.38.0 → 1.40.0

package/tools/changed-surface.mjs

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+// changed-surface.mjs — the NEUTRAL shared read-only core (BUGFREE-2 / AD-048, D4 + D8). One home
+// for the changed-surface computation that BOTH the fold-completeness runner (coverage domain) and
+// the review-ledger writer (the D4 diff-size cap) consume — one computation, so the cap and the
+// coverage gate can never drift (the probeVerdict single-home precedent, AD-047). The D8 telemetry
+// fold-ledger read path lives beside it: fold-completeness.mjs already imports review-ledger.mjs,
+// so the review-ledger telemetry must reach the fold ledger WITHOUT importing back the other
+// direction — it imports THIS module instead.
+//
+// Import-graph invariant (pinned by import-split tests): this module imports NOTHING from the
+// family — node built-ins only. Everyone may import it; it imports no one:
+//   review-ledger.mjs → changed-surface.mjs ← fold-completeness.mjs ← fold-completeness-run.mjs
+//   review-ledger-write.mjs → changed-surface.mjs (the writer NEVER imports the runner — the
+//   sole-tree-toucher boundary, codex R2)
+//
+// Read-only: never writes, never commits. It DOES spawn read-only `git` queries (diff/ls-files/
+// rev-parse). Dependency-free, Node >= 18. No side effects on import.
+
+import { readFileSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const GIT_MAX_BUFFER = 256 * 1024 * 1024; // a full-tree diff can be large; never truncate
+
+// ── the CLOSED changed-path classification rule (AD-046 Decision 5; 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';
+};
+
+// ── diff-header path unquoting (git C-quotes paths carrying quotes/control/non-ASCII bytes) ──────
+
+// Strip the quotes and decode escapes BYTE-wise (octal escapes are UTF-8 bytes) — an unparsed
+// quoted path compares unequal to its classifier/testId form and would silently escape the
+// coverage/cap surface (agy R5, AD-047).
+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');
+};
+
+// ── unified-diff → new-side changed line numbers (line numbers only; content lines 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;
+};
+
+// ── the changed surface (git-driven; the ONE computation both consumers read) ─────────────────────
+
+// The one diff-invocation shape every surface pass uses. 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.
+export const DIFF_FLAGS = ['--unified=0', '--no-color', '--no-ext-diff', '--no-renames', '--src-prefix=a/', '--dst-prefix=b/'];
+
+const runGit = (args, cwd) => spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, encoding: 'utf8', windowsHide: true });
+const gitStdout = (args, cwd) => {
+  const r = runGit(args, cwd);
+  return r.error || r.status > 1 ? null : r.stdout;
+};
+const gitLine = (args, cwd) => {
+  const r = runGit(args, cwd);
+  if (r.error || r.status !== 0) return null;
+  return r.stdout.replace(/\r?\n$/, '');
+};
+// Both leaf guards are exported for the unit tests of exactly their fail-closed edges (the
+// hashFileBytes precedent, AD-047) — internal consumers stay this module's own passes.
+export const readFileSafe = (path) => {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+};
+// A changed LEAF is read only if it is a REGULAR file. lstat (no-follow): a symlinked or non-regular
+// leaf must NEVER be read/followed — following it could read outside the work tree or HANG on a
+// FIFO/device (codex R2, AD-046). A non-regular leaf fails closed (routed to `unsupported`).
+export const isRegularLeaf = (abs) => {
+  try {
+    return lstatSync(abs).isFile();
+  } catch {
+    return false;
+  }
+};
+
+// computeChangedSurface(root) → { assessable: Map<rel, number[]>, unsupported: [rel],
+// outOfDomain: [rel], unsupportedLines: Map<rel, number[]> }.
+// 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` (new-side only —
+// pure deletions cost nothing, subtractive folds stay free); an untracked file is wholly new, so all
+// its lines are "changed". `unsupportedLines` is the D4 cap's view of the SAME pass: unsupported
+// SOURCE files carry their new-side lines too (excluding them would gift a large-TS-fold bypass,
+// codex R2 / BUGFREE-2 D4); an unreadable/non-regular leaf counts 0 lines but stays LISTED (the
+// coverage gate still fails closed on it). excluded-test and out-of-domain never carry lines.
+export const computeChangedSurface = (root) => {
+  // Unborn branch (no HEAD yet): the plain diff alone misses files STAGED for the initial commit —
+  // they sit in the index, so they are neither worktree-vs-index changes nor untracked. Merge the
+  // --cached diff (index vs the empty tree) with the plain one; parseUnifiedDiff unions per-file
+  // lines across concatenated diffs (codex R1).
+  const trackedDiff = gitStdout(['diff', 'HEAD', ...DIFF_FLAGS], root)
+    ?? `${gitStdout(['diff', '--cached', ...DIFF_FLAGS], root) ?? ''}\n${gitStdout(['diff', ...DIFF_FLAGS], root) ?? ''}`;
+  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 unsupportedLines = new Map();
+  const outOfDomain = [];
+  const markUnsupported = (rel, lines) => {
+    if (!unsupportedLines.has(rel)) unsupportedLines.set(rel, lines);
+  };
+  const place = (rel, cls, lines) => {
+    if (cls === 'excluded-test') return;
+    if (cls === 'assessable') {
+      if (isRegularLeaf(join(root, rel))) assessable.set(rel, lines);
+      else markUnsupported(rel, lines); // a symlinked / non-regular source → fail closed, never followed
+      return;
+    }
+    if (cls === 'unsupported') markUnsupported(rel, lines);
+    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 === 'excluded-test' || cls === 'out-of-domain') {
+      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)) {
+      markUnsupported(rel, []);
+      continue;
+    }
+    const src = readFileSafe(abs);
+    // Content lines only: a trailing newline terminates the last line, it does not open a phantom
+    // empty one — the cap must count real lines (git's new-side numbering does the same).
+    const parts = src == null ? [] : src.split('\n');
+    if (parts.length > 0 && parts[parts.length - 1] === '') parts.pop();
+    const all = Array.from({ length: parts.length }, (_, i) => i + 1);
+    if (cls === 'assessable') assessable.set(rel, all);
+    else markUnsupported(rel, all);
+  }
+  return { assessable, unsupported: [...unsupportedLines.keys()].sort(), outOfDomain: outOfDomain.sort(), unsupportedLines };
+};
+
+// countCapLines(surface) → the D4 counted magnitude: new-side changed lines of assessable AND
+// unsupported SOURCE files (the two counted classes, pinned by named tests); excluded-test and
+// out-of-domain never count; pure deletions already cost nothing (new-side lines only). Stated
+// consequence, INTENTIONAL (agy R1): under --no-renames a rename of a large file costs its full
+// length — the single-home invariant outweighs a rename special case.
+export const countCapLines = ({ assessable, unsupportedLines }) => {
+  let counted = 0;
+  for (const lines of assessable.values()) counted += lines.length;
+  for (const lines of unsupportedLines.values()) counted += lines.length;
+  return counted;
+};
+
+// ── the shared fail-closed positive-integer knob parser (AD-047 precedent) ───────────────────────
+
+// Zero / negative / fractional / non-numeric values are refusals by name — the parseInt(...)||default
+// idiom would silently accept bad truthy values (codex R2, AD-046). Unset → the default; set → a
+// positive integer, exactly. `makeError` lets each caller throw its OWN typed STOP.
+export const parsePositiveIntKnob = (env, name, fallback, makeError = (m) => new Error(m)) => {
+  const raw = env[name];
+  if (raw === undefined) return fallback;
+  if (!/^\d+$/.test(String(raw).trim()) || Number.parseInt(raw, 10) < 1) {
+    throw makeError(`${name} must be a positive integer (got "${raw}") — refusing to guess (fail closed)`);
+  }
+  return Number.parseInt(raw, 10);
+};
+
+// ── the D4 probe-verdict algebra (AD-047; the SINGLE home — moved here from fold-completeness.mjs,
+// which re-exports it, so the runner, the checker, AND the review-ledger telemetry read ONE algebra) ─
+
+// probeVerdict(entry) → 'green' | 'red' | 'quarantine' | 'unresolvable'. 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';
+};
+
+// ── the fold-result ledger locator + a tolerant row reader (the D8 telemetry read path) ──────────
+
+export const RESULTS_BASENAME = 'agent-workflow-fold-completeness.jsonl';
+
+// 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);
+};
+
+// readJsonlRows(path) → { rows, badLines, readError? } — the TOLERANT parse the telemetry counts
+// ride on (counts only, no judgment — D8): a row is any parsed JSON object; a bad line is counted,
+// never dropped silently. Schema validation stays with each ledger's own reader — telemetry must
+// not fork a second validator (drift) nor import one across the cycle boundary.
+export const readJsonlRows = (path, readFile = readFileSync) => {
+  let raw;
+  try {
+    raw = readFile(path, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { rows: [], badLines: 0 };
+    return { rows: [], badLines: 0, readError: (err && err.code) || (err && err.message) || 'read failed' };
+  }
+  const rows = [];
+  let badLines = 0;
+  for (const line of raw.split('\n')) {
+    if (line.trim() === '') continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) rows.push(parsed);
+      else badLines += 1;
+    } catch {
+      badLines += 1;
+    }
+  }
+  return { rows, badLines };
+};

package/tools/commands.mjs

@@ -96,7 +96,7 @@ const CATALOG = [
     invocation: invocationOf('gates'),
     group: 'Inspect',
     kind: PROJECT_EXEC,
-    oneLine: 'Run the project’s own declared gate commands (docs/ai/gates.json) as one batch — a PASS/FAIL table, one summary line. The mode itself writes nothing; a separate consent-gated seeder can propose entries from your project’s own scripts (preview first, written only on your yes).',
+    oneLine: 'Run the project’s own declared gate commands (docs/ai/gates.json) as one batch — a PASS/FAIL table, one summary line. Writes nothing by default; opt-in --record mints a gate-run record via the review-ledger writer (the segment’s green-baseline receipt). A separate consent-gated seeder can propose entries from your project’s own scripts (preview first, written only on your yes).',
   },
   {
     key: 'setup',
@@ -180,14 +180,21 @@ const CATALOG = [
     invocation: invocationOf('review-ledger'),
     group: 'Orchestrate',
     kind: WRITER,
-    oneLine: 'Record each review round, its triage, and recorded overrides (oracle-change / red-proof waivers) and read the computed crossover-stop for the plan-execution loop; --check turns it into a gate exit code and forces a triage before over-running the review.',
+    oneLine: 'Record each review round, its triage, and recorded overrides (oracle-change / red-proof / size-cap waivers) and read the computed crossover-stop for the plan-execution loop — per SEGMENT since v4 (base = HEAD; caps and teeth reset only at a gated commit; class refuted is the honest phantom lane); --check turns it into a gate exit code, --telemetry renders counts-only gate-efficacy data.',
   },
   {
     key: 'fold-completeness',
     invocation: invocationOf('fold-completeness'),
     group: 'Orchestrate',
     kind: WRITER,
-    oneLine: 'Verify the review loop’s folded fixes are pinned by HONEST tests — every changed executable line executed, and each bound test carries an observed-red receipt (--red, minted BEFORE the fix), N/N-green probes, and content custody (waivable per-testId only by a recorded red-proof override), over a test surface whose tampered files carry recorded oracle-change overrides; --check turns the result into a gate exit code.',
+    oneLine: 'Verify the review loop’s folded fixes are pinned by HONEST tests — every changed executable line executed, and each bound test carries an observed-red receipt (--red, minted BEFORE the fix), N/N-green probes, and content custody (waivable per-testId only by a recorded red-proof override), over a test surface whose tampered files carry recorded oracle-change overrides; SEGMENT-scoped since v3 (a committed phase’s custody obligations close with its commit); --check turns the result into a gate exit code.',
+  },
+  {
+    key: 'doc-parity',
+    invocation: invocationOf('doc-parity'),
+    group: 'Orchestrate',
+    kind: READ_ONLY,
+    oneLine: 'Check that the documented contract values (review caps, schema versions, ledger vocabulary) still match the live code constants they describe — a read-only lint that fails closed on drift; --check turns it into a gate exit code.',
   },
 ];
 

package/tools/doc-parity.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// doc-parity.mjs — the deterministic doc-drift lint behind `/agent-workflow-kit doc-parity`
+// (BUGFREE-3 / AD-049, economics item (b)). A whole class of BUGFREE-2 review churn came from a
+// mode-contract doc silently lagging a code constant (a `--check` doc still saying "300" after the
+// diff cap moved to 400). This tool closes it mechanically: a CLOSED, exported registry of bindings
+// each ties ONE live code constant to the exact token its contract doc must carry, and the checker
+// 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.
+//
+// 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).
+
+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';
+
+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';
+
+// A typed usage failure (exit 2) for the CLI parser — the codebase's typed-error idiom (no classes).
+const usageFail = (message) => Object.assign(new Error(message), { exitCode: 2 });
+
+// ── the closed binding registry ──────────────────────────────────────────────────────
+// Each binding: { constant, value (live), token (value rendered into the doc's exact phrasing),
+// files[] (the contract docs that MUST carry the token) }. The token phrasings match the current
+// 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'];
+
+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])),
+].map((b) => Object.freeze(b)));
+
+// ── the pure checker (readText is injectable for hermetic tests) ────────────────────────
+// checkBinding(binding, readText) → { constant, token, files: [{ rel, ok, reason }], ok }.
+// readText(rel) returns the file text or THROWS (an unreadable bound file fails closed).
+export const checkBinding = (binding, readText) => {
+  const files = binding.files.map((rel) => {
+    let text;
+    try {
+      text = readText(rel);
+    } catch (err) {
+      return { rel, ok: false, reason: `unreadable (${(err && err.code) || (err && err.message) || 'read failed'})` };
+    }
+    const present = text.includes(binding.token);
+    return { rel, ok: present, reason: present ? null : `token ${JSON.stringify(binding.token)} not found` };
+  });
+  return { constant: binding.constant, token: binding.token, files, ok: files.every((f) => f.ok) };
+};
+
+const defaultReadText = (rel) => readFileSync(resolve(KIT_ROOT, rel), 'utf8');
+
+// checkParity(bindings, readText) → [ per-binding result ]. Default reads the real modes/*.md files
+// relative to the kit root.
+export const checkParity = (bindings = BINDINGS, readText = defaultReadText) => bindings.map((b) => checkBinding(b, readText));
+
+// ── rendering ───────────────────────────────────────────────────────────────────────
+const formatHuman = (results) => {
+  const lines = ['doc-parity — code constants ⟷ references/modes/*.md contract (read-only, BUGFREE-3)'];
+  for (const r of results) {
+    for (const f of r.files) {
+      lines.push(`  ${f.ok ? '✓' : '✗'} ${r.constant} → ${f.rel}${f.ok ? '' : ` — ${f.reason}`}`);
+    }
+  }
+  const failed = results.flatMap((r) => r.files.filter((f) => !f.ok).map((f) => `${r.constant} @ ${f.rel}`));
+  lines.push(`  check: ${failed.length === 0 ? 'PASS' : 'FAIL'} — ${failed.length === 0 ? `${results.length} binding(s) consistent` : `${failed.length} drifted binding(s): ${failed.join('; ')}`}`);
+  return lines.join('\n');
+};
+
+const HELP = `doc-parity — deterministic doc-drift lint for the agent-workflow family (BUGFREE-3 / AD-049).
+
+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) and the
+ledger vocabulary (V4_CLASSES / V4_OVERRIDE_SCOPES + gate-run) 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.
+
+Read-only: never writes, never commits, spawns nothing. Exit codes: 0 pass (or plain report); 1 drift
+(under --check) or error; 2 usage.`;
+
+const KNOWN_ARGS = new Set(['--help', '-h', '--check', '--json']);
+
+export const main = (argv, ctx = {}) => {
+  const readText = ctx.readText ?? defaultReadText;
+  try {
+    if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
+    const unknown = argv.find((a) => !KNOWN_ARGS.has(a));
+    if (unknown !== undefined) throw usageFail(`unknown argument: ${unknown}`);
+    const results = checkParity(BINDINGS, readText);
+    const failed = results.filter((r) => !r.ok);
+    if (argv.includes('--json')) {
+      return { code: argv.includes('--check') && failed.length > 0 ? 1 : 0, stdout: JSON.stringify({ results, ok: failed.length === 0 }, null, 2), stderr: '' };
+    }
+    if (argv.includes('--check')) {
+      const reason = failed.length === 0 ? `${results.length} binding(s) consistent` : `${failed.length} drifted binding(s): ${failed.map((r) => r.constant).join(', ')} — update the contract doc(s) in the SAME edit as the code`;
+      return { code: failed.length === 0 ? 0 : 1, stdout: `doc-parity check: ${failed.length === 0 ? 'PASS' : 'FAIL'} — ${reason}`, stderr: '' };
+    }
+    return { code: 0, stdout: formatHuman(results), stderr: '' };
+  } catch (err) {
+    return { code: err.exitCode ?? 1, stdout: '', stderr: `doc-parity: ${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;
+}