@sabaiway/agent-workflow-kit 1.39.0 → 1.41.0

package/references/scripts/check-docs-size.mjs

@@ -15,6 +15,8 @@
 //
 // CLI overrides:
 //   --today=YYYY-MM-DD (default today UTC) — useful for tests / reproducible runs
+//   --root=<dir>       run against another project root (default this deployment) — the ADR-rotation
+//                      hook passes it so a rotation regenerates the right project's index
 //   --quiet            print only failures (and final summary)
 
 import { readFile, writeFile, readdir, stat } from 'node:fs/promises';
@@ -28,6 +30,12 @@ const ROOT = resolve(__dirname, '..');
 const DOCS_DIR = resolve(ROOT, 'docs/ai');
 const INDEX_PATH = resolve(DOCS_DIR, 'index.md');
 
+// Root-parameterized (BUGFREE-3 / AD-049, item (h)): the module ROOT constants are the CLI DEFAULT
+// (this deployment's own root); `--root=<dir>` and the exported `regenerateIndex(root, today)`
+// override them so the ADR-rotation hook (archive-decisions.mjs) and hermetic tests can regenerate
+// an arbitrary root's index without ever touching the real repo tree.
+const pathsFor = (root) => ({ root, docsDir: resolve(root, 'docs/ai'), indexPath: resolve(root, 'docs/ai/index.md') });
+
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
 
 // Project-name + footer links for the index are auto-discovered (no hardcoding):
@@ -56,18 +64,18 @@ const walkForName = async (dir, name, acc = [], depth = 0) => {
   return acc;
 };
 
-export const discoverMeta = async () => {
-  let projectName = basename(ROOT);
+export const discoverMeta = async (root = ROOT) => {
+  let projectName = basename(root);
   try {
-    const pkg = JSON.parse(await readFile(resolve(ROOT, 'package.json'), 'utf8'));
+    const pkg = JSON.parse(await readFile(resolve(root, 'package.json'), 'utf8'));
     if (pkg.name) projectName = pkg.name;
   } catch {
     /* no package.json — keep dir basename */
   }
-  const agentsFiles = await walkForName(ROOT, 'AGENTS.md');
-  const claudeFiles = await walkForName(ROOT, 'CLAUDE.md');
-  const rootAgents = resolve(ROOT, 'AGENTS.md');
-  const rootClaude = resolve(ROOT, 'CLAUDE.md');
+  const agentsFiles = await walkForName(root, 'AGENTS.md');
+  const claudeFiles = await walkForName(root, 'CLAUDE.md');
+  const rootAgents = resolve(root, 'AGENTS.md');
+  const rootClaude = resolve(root, 'CLAUDE.md');
   // A subdir typically holds AGENTS.md plus a CLAUDE.md symlink to it — list each
   // dir once (prefer AGENTS.md, drop its sibling CLAUDE.md alias).
   const agentsDirs = new Set(agentsFiles.map((file) => dirname(resolve(file))));
@@ -78,12 +86,12 @@ export const discoverMeta = async () => {
     ),
   ];
   const hierarchicalLinks = nestedFiles
-    .map((file) => relative(ROOT, file))
+    .map((file) => relative(root, file))
     .sort()
     .map((rel) => `[\`${rel}\`](../../${rel})`);
   let onDemandLinks = [];
   try {
-    const skillDirs = await readdir(resolve(ROOT, '.agents/skills'), { withFileTypes: true });
+    const skillDirs = await readdir(resolve(root, '.agents/skills'), { withFileTypes: true });
     onDemandLinks = skillDirs
       .filter((dirent) => dirent.isDirectory() && /-(patterns|commands)$/.test(dirent.name))
       .map((dirent) => dirent.name)
@@ -97,16 +105,17 @@ export const discoverMeta = async () => {
 
 const parseArgs = (argv) => {
   const flags = { report: false, writeIndex: false, checkIndex: false, quiet: false };
-  const opts = { today: null };
+  const opts = { today: null, root: null };
   for (const arg of argv.slice(2)) {
     if (arg === '--report') flags.report = true;
     else if (arg === '--write-index') flags.writeIndex = true;
     else if (arg === '--check-index') flags.checkIndex = true;
     else if (arg === '--quiet') flags.quiet = true;
     else if (arg.startsWith('--today=')) opts.today = arg.slice('--today='.length);
+    else if (arg.startsWith('--root=')) opts.root = arg.slice('--root='.length);
     else if (arg === '--help' || arg === '-h') {
       console.log(
-        'Usage: check-docs-size.mjs [--report|--write-index|--check-index] [--today=YYYY-MM-DD] [--quiet]',
+        'Usage: check-docs-size.mjs [--report|--write-index|--check-index] [--today=YYYY-MM-DD] [--root=<dir>] [--quiet]',
       );
       process.exit(0);
     } else {
@@ -161,11 +170,11 @@ export const computeToday = (todayStr) =>
     ? new Date(`${todayStr}T00:00:00Z`)
     : new Date(new Date().toISOString().slice(0, 10) + 'T00:00:00Z');
 
-export const inspectFile = async (filePath, today) => {
+export const inspectFile = async (filePath, today, root = ROOT) => {
   const text = await readFile(filePath, 'utf8');
   const lineCount = text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
   const fm = parseFrontmatter(text);
-  const rel = relative(ROOT, filePath);
+  const rel = relative(root, filePath);
 
   if (!fm) {
     return {
@@ -301,24 +310,41 @@ export const checkIndexFreshness = (rows, onDiskText, meta = {}) => {
   return { fresh: expected === onDiskText, expected };
 };
 
-const writeIndex = async (rows, today, meta) => {
+const writeIndex = async (rows, today, meta, indexPath = INDEX_PATH) => {
   const body = buildIndex(rows, today.toISOString().slice(0, 10), meta);
-  await writeFile(INDEX_PATH, body, 'utf8');
+  await writeFile(indexPath, body, 'utf8');
+};
+
+// regenerateIndex(root, todayStr) — the ONE reused generator, root-parameterized (item (h)). It runs
+// the SAME walk → inspect → discoverMeta → writeIndex pipeline as `--write-index`, against `root`
+// (default this deployment). The ADR-rotation hook reaches it via the CLI (`--write-index --root=…`);
+// hermetic tests call it directly. `todayStr` is 'YYYY-MM-DD' (null → today). Returns the written
+// index path + row count. No second index implementation exists.
+export const regenerateIndex = async (root, todayStr = null) => {
+  const { docsDir, indexPath } = pathsFor(root);
+  const today = computeToday(todayStr);
+  const files = (await walkMarkdownFiles(docsDir)).sort();
+  const inspected = await Promise.all(files.map((f) => inspectFile(f, today, root)));
+  const rows = inspected.map(formatRow);
+  const meta = await discoverMeta(root);
+  await writeIndex(rows, today, meta, indexPath);
+  return { indexPath, files: rows.length };
 };
 
 const main = async () => {
   const { flags, opts } = parseArgs(process.argv);
+  const { root, docsDir, indexPath } = pathsFor(opts.root ? resolve(opts.root) : ROOT);
   const today = computeToday(opts.today);
-  const files = (await walkMarkdownFiles(DOCS_DIR)).sort();
-  const inspected = await Promise.all(files.map((f) => inspectFile(f, today)));
+  const files = (await walkMarkdownFiles(docsDir)).sort();
+  const inspected = await Promise.all(files.map((f) => inspectFile(f, today, root)));
   const rows = inspected.map(formatRow);
 
-  const meta = flags.writeIndex || flags.checkIndex ? await discoverMeta() : null;
+  const meta = flags.writeIndex || flags.checkIndex ? await discoverMeta(root) : null;
 
   if (flags.writeIndex) {
-    await writeIndex(rows, today, meta);
-    console.log(`Wrote ${relative(ROOT, INDEX_PATH)}`);
-    const after = await stat(INDEX_PATH);
+    await writeIndex(rows, today, meta, indexPath);
+    console.log(`Wrote ${relative(root, indexPath)}`);
+    const after = await stat(indexPath);
     if (after.size === 0) {
       console.error('index.md was written empty');
       process.exit(2);
@@ -326,16 +352,16 @@ const main = async () => {
   }
 
   if (flags.checkIndex) {
-    const onDisk = existsSync(INDEX_PATH) ? await readFile(INDEX_PATH, 'utf8') : null;
+    const onDisk = existsSync(indexPath) ? await readFile(indexPath, 'utf8') : null;
     const { fresh } = checkIndexFreshness(rows, onDisk, meta);
     if (!fresh) {
       console.error(
-        `[check-docs-size] FAIL: ${relative(ROOT, INDEX_PATH)} is stale (out of sync with source frontmatter). Regenerate the index (--write-index) and commit the regenerated file.`,
+        `[check-docs-size] FAIL: ${relative(root, indexPath)} is stale (out of sync with source frontmatter). Regenerate the index (--write-index) and commit the regenerated file.`,
       );
       process.exit(1);
     }
     console.log(
-      `[check-docs-size] OK — ${relative(ROOT, INDEX_PATH)} is in sync with source frontmatter.`,
+      `[check-docs-size] OK — ${relative(root, indexPath)} is in sync with source frontmatter.`,
     );
     return;
   }

package/references/scripts/check-docs-size.test.mjs

@@ -1,8 +1,11 @@
 import { describe, it, beforeEach, afterEach } from 'node:test';
 import { expect } from './_expect-shim.mjs';
-import { mkdtemp, writeFile, rm } from 'node:fs/promises';
+import { mkdtemp, writeFile, mkdir, readFile, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import {
   parseFrontmatter,
   parseStaleAfter,
@@ -11,6 +14,7 @@ import {
   buildIndex,
   checkIndexFreshness,
   walkMarkdownFiles,
+  regenerateIndex,
 } from './check-docs-size.mjs';
 
 describe('parseFrontmatter', () => {
@@ -202,3 +206,71 @@ describe('checkIndexFreshness', () => {
     expect(checkIndexFreshness(rows, onDisk).fresh).toBe(true);
   });
 });
+
+// ── (h) — root-parameterization: the ADR-rotation hook regenerates ANOTHER root's index ────
+// The generator's module ROOT is the CLI default only; --root / regenerateIndex(root) target an
+// arbitrary tree so the rotation hook (and hermetic tests) never touch the real repo.
+describe('root parameterization (item (h))', () => {
+  let root;
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'check-docs-root-'));
+    await mkdir(join(root, 'docs', 'ai'), { recursive: true });
+  });
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  const seedDoc = (name, extra = '') =>
+    writeFile(join(root, 'docs', 'ai', name), `---\ntype: reference\nlastUpdated: 2026-07-08\nscope: permanent\nstaleAfter: 30d\nowner: none\nmaxLines: 100\n---\n\n# ${name}\n${extra}`);
+
+  it('inspectFile computes the file path RELATIVE to the passed root (not the module ROOT)', async () => {
+    await seedDoc('handover.md');
+    const result = await inspectFile(join(root, 'docs', 'ai', 'handover.md'), computeToday('2026-07-08'), root);
+    expect(result.path).toBe('docs/ai/handover.md');
+  });
+
+  it('regenerateIndex(root, today) writes THAT root\'s docs/ai/index.md from its frontmatter', async () => {
+    await seedDoc('a.md');
+    await seedDoc('b.md');
+    const res = await regenerateIndex(root, '2026-07-08');
+    expect(res.indexPath).toBe(join(root, 'docs', 'ai', 'index.md'));
+    expect(existsSync(res.indexPath)).toBe(true);
+    const index = await readFile(res.indexPath, 'utf8');
+    expect(index).toMatch(/lastUpdated: 2026-07-08/); // header date is the argument
+    expect(index).toMatch(/a\.md/);
+    expect(index).toMatch(/b\.md/);
+    expect(index).not.toMatch(/\[`index\.md`\]/); // the index never lists itself
+  });
+
+  it('a re-run with unchanged sources is byte-identical (deterministic, --check-index safe)', async () => {
+    await seedDoc('a.md');
+    const first = await regenerateIndex(root, '2026-07-08');
+    const bytesA = await readFile(first.indexPath, 'utf8');
+    await regenerateIndex(root, '2026-07-08');
+    const bytesB = await readFile(first.indexPath, 'utf8');
+    expect(bytesB).toBe(bytesA);
+  });
+
+  // The CLI entry (main) over --root — a subprocess smoke so the --help usage + the --check-index
+  // fresh/stale branches (root-parameterized) are exercised end-to-end.
+  const SCRIPT = fileURLToPath(new URL('./check-docs-size.mjs', import.meta.url));
+  const runCli = (args) => spawnSync(process.execPath, [SCRIPT, ...args], { encoding: 'utf8' });
+
+  it('--help prints the usage (naming --root) and exits 0', () => {
+    const r = runCli(['--help']);
+    expect(r.status).toBe(0);
+    expect(r.stdout).toMatch(/--root=/);
+  });
+
+  it('--check-index --root: a fresh index is OK (exit 0); a drifted one is stale (exit 1)', async () => {
+    await seedDoc('a.md');
+    expect(runCli(['--write-index', `--root=${root}`]).status).toBe(0);
+    const fresh = runCli(['--check-index', `--root=${root}`]);
+    expect(fresh.status).toBe(0);
+    expect(fresh.stdout).toMatch(/in sync/);
+    await seedDoc('b.md'); // a new source row drifts the on-disk index
+    const stale = runCli(['--check-index', `--root=${root}`]);
+    expect(stale.status).toBe(1);
+    expect(stale.stderr).toMatch(/stale/);
+  });
+});

package/references/templates/agent_rules.md

@@ -53,6 +53,7 @@ Before proposing changes or committing, review against:
 ### 2.2. Clean Code
 - **No magic literals** — extract string/numeric constants to named consts at module level.
 - **DRY** — no duplicated logic.
+- **Minimal comments (a BASELINE this project may tighten)** — if this project sets a stricter rule (e.g. comments forbidden entirely), that stricter rule ALWAYS wins; this is only a floor. Otherwise comment only where vitally necessary (a non-obvious invariant, a fail-closed rationale, a subtle edge). Make the code self-explaining first — clear variable/function names and compact-but-unambiguous test descriptions replace most comments; never restate what the code already says.
 
 ### 2.3. Strict Compliance
 - Only `const` (no `let`); no classes — pure functions, closures, modules.

package/references/templates/verification-profile.json

@@ -0,0 +1,10 @@
+{
+  "_README": "Optional per-project VERIFICATION PROFILE for the fold-completeness gate (the language-independence contract). DELETE this file to reproduce the exact default behaviour (V8 line coverage + node:test TAP on stdout) — an absent profile is fully supported. Present, it GENERALIZES three inputs so a consumer on another language/runner can drive the same gate: (1) coverage.kind is \"v8\" (default) or \"lcov\" — with lcov, set coverage.lcovPath to where your suite leaves an LCOV file; (2) singleTest.argv is the shell-free command template for probing ONE test (placeholders {file} and {pattern} are required; a file-based resultFormat also requires {resultPath}), and singleTest.resultFormat is \"tap-stdout\" (default), \"tap-file\", or \"junit-xml\"; (3) findings.sarifPath (optional) points at a SARIF file for advisory-only findings (never gate-blocking). The suite COMMAND is NOT declared here — it stays your docs/ai/gates.json unit-tests gate (so the fold run and the gate share command-identity). Every DECLARED path (coverage.lcovPath, findings.sarifPath) MUST be gitignored or outside the repo (a symlink is refused): an in-tree, non-ignored file the suite writes would move the review fingerprint. Env knobs still override (AW_FOLD_SUITE_CMD / AW_FOLD_BOUND_CMD / AW_FOLD_RESULTS). Strict JSON — no comments.",
+  "schema": 1,
+  "coverage": { "kind": "v8" },
+  "singleTest": {
+    "argv": ["node", "--test", "--test-reporter", "tap", "--test-name-pattern={pattern}", "{file}"],
+    "resultFormat": "tap-stdout"
+  },
+  "findings": {}
+}

package/tools/commands.mjs

@@ -189,6 +189,13 @@ const CATALOG = [
     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; 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.',
+  },
 ];
 
 // Deep-freeze: freeze the array AND every entry, so the catalog is genuinely immutable at runtime

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;
+}