simt-dev 0.2.2 → 0.3.1

package/src/commands/evidence.mjs

@@ -0,0 +1,96 @@
+// `simt evidence` — the proof block for this tree, and the commit-message check.
+//
+// The read answers "what has actually been run against what is on disk". The check
+// answers the other half: a message that says the tests passed, when nothing in the
+// ledger was run against this tree (ADR-087).
+
+import { readFile } from 'node:fs/promises';
+
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { readManifest } from '../projection/manifest.mjs';
+import { CLI, MANIFEST_FILE } from '../name.mjs';
+import { claimsVerification, evidenceMode, readLedger, treeId } from '../ledger/index.mjs';
+
+export async function evidenceCommand(args, flags) {
+  const root = flags.root ?? process.cwd();
+  if (args[0] === 'check') return checkClaim(root, args[1], flags);
+  if (args[0] !== undefined) {
+    return fail(`unknown evidence subcommand ${args[0]}`, EXIT.USAGE, `run: ${CLI} evidence`);
+  }
+  return showEvidence(root, flags);
+}
+
+async function showEvidence(root, flags) {
+  let tree;
+  try {
+    tree = await treeId(root);
+  } catch (error) {
+    return fail(
+      `could not name this tree (${error.message})`,
+      EXIT.UNSUPPORTED,
+      'run this inside a git repository',
+    );
+  }
+  const { entries, errors } = await readLedger(root);
+  const mine = entries.filter((e) => e.tree === tree);
+  const payload = { ok: errors.length === 0, command: 'evidence', root, tree, entries: mine, errors };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return errors.length === 0 ? EXIT.OK : EXIT.FAIL;
+  }
+  const lines = [`tree     ${tree}`];
+  if (mine.length === 0) lines.push('none     no run is recorded for this tree');
+  for (const e of mine) {
+    lines.push(`${e.exit === 0 ? 'pass' : 'fail'}     ${e.cmd}  exit ${e.exit}  ${e.summary}`);
+  }
+  for (const error of errors) lines.push(`error    ${error}`);
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return errors.length === 0 ? EXIT.OK : EXIT.FAIL;
+}
+
+async function checkClaim(root, file, flags) {
+  if (!file) return fail('evidence check needs the commit message file', EXIT.USAGE, `run: ${CLI} evidence check <file>`);
+  let message;
+  try {
+    message = await readFile(file, 'utf8');
+  } catch (error) {
+    return fail(`could not read ${file} (${error.message})`, EXIT.USAGE, `pass the path git gives commit-msg`);
+  }
+  const { manifest, error } = await readManifest(root);
+  if (error) return fail(`${MANIFEST_FILE}: ${error}`, EXIT.CONFIG, `fix ${MANIFEST_FILE} so it parses`);
+  const mode = evidenceMode(manifest);
+  if (mode === null) {
+    return fail(
+      `${MANIFEST_FILE} gates.evidence must be "warn" or "block"`,
+      EXIT.CONFIG,
+      `set gates.evidence to "warn" or "block", or remove it`,
+    );
+  }
+  const claim = claimsVerification(message);
+  if (!claim) {
+    const payload = { ok: true, command: 'evidence check', claim: false, mode };
+    if (isJson(flags)) emitJson(payload, { pretty: flags.pretty === true });
+    return EXIT.OK;
+  }
+  let tree;
+  try {
+    tree = await treeId(root);
+  } catch (error) {
+    return fail(`could not name this tree (${error.message})`, EXIT.UNSUPPORTED, 'run this inside a git repository');
+  }
+  const { entries } = await readLedger(root);
+  const supported = entries.some((e) => e.tree === tree && e.exit === 0);
+  const payload = { ok: supported || mode === 'warn', command: 'evidence check', claim: true, supported, mode, tree };
+  if (supported) {
+    if (isJson(flags)) emitJson(payload, { pretty: flags.pretty === true });
+    return EXIT.OK;
+  }
+  const detail = 'the message claims a run this tree does not have';
+  const remedy = `run the command, then commit, or take the claim out of the message`;
+  if (isJson(flags)) {
+    emitJson({ ...payload, detail, remedy }, { pretty: flags.pretty === true });
+    return mode === 'block' ? EXIT.FAIL : EXIT.OK;
+  }
+  emit(`${mode === 'block' ? 'BLOCKED' : 'WARNING'}  ${detail}\n         remedy: ${remedy}`, { maxBytes: flags.maxBytes ?? 0 });
+  return mode === 'block' ? EXIT.FAIL : EXIT.OK;
+}

package/src/commands/gate.mjs

@@ -0,0 +1,165 @@
+// `simt gate` runs the tests a change reaches (R16, ADR-094).
+//
+// Paths name the change. `--changed` reads the diff instead. The tests are the
+// ones that import a changed file, directly or through other files, and the
+// runner is the one the package already uses. Nothing else runs. A report
+// this tool knows how to read is compacted; the raw log is kept.
+
+import { execFile } from 'node:child_process';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { detectTestRunner } from '../bench/mine.mjs';
+import { compactOutput } from '../index/compact.mjs';
+import { readImportEdges, selectTests } from '../index/gate.mjs';
+import { packageOf } from '../index/store.mjs';
+
+const exec = promisify(execFile);
+
+export async function gateCommand(args, flags) {
+  const root = flags.root ?? process.cwd();
+  const listed = await tracked(root);
+  if (listed.error) return listed.error;
+  let changed = args.filter(Boolean);
+  if (flags.changed === true) {
+    const diff = await changedFiles(root);
+    if (diff.error) return diff.error;
+    changed = [...new Set([...changed, ...diff.files])].sort();
+  }
+  if (changed.length === 0) {
+    if (flags.changed === true) {
+      if (isJson(flags)) {
+        emitJson({ ok: true, command: 'gate', root, selected: [], code: 0 }, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+      } else {
+        emit('selected  0', { maxBytes: flags.maxBytes ?? 0 });
+      }
+      return EXIT.OK;
+    }
+    return fail(`nothing changed`, EXIT.USAGE, `pass a path, or ${CLI} gate --changed`);
+  }
+  const files = new Set(listed.files);
+  for (const file of changed) files.add(file);
+  const selected = selectTests(changed, await readImportEdges(root, files));
+  if (selected.length === 0) {
+    const payload = { ok: true, command: 'gate', root, selected, code: 0 };
+    if (isJson(flags)) {
+      emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+      return EXIT.OK;
+    }
+    emit('selected  0', { maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  return runSelected(root, flags, selected);
+}
+
+async function runSelected(root, flags, selected) {
+  const cache = new Map();
+  const groups = new Map();
+  for (const file of selected) {
+    const pkg = await packageOf(root, file, cache);
+    const list = groups.get(pkg);
+    if (list) list.push(file);
+    else groups.set(pkg, [file]);
+  }
+  const runs = [];
+  let code = 0;
+  const text = [];
+  const rawParts = [];
+  for (const [pkg, files] of [...groups.entries()].sort((a, b) => cmp(a[0], b[0]))) {
+    const relative = files.map((file) => (pkg && file.startsWith(`${pkg}/`) ? file.slice(pkg.length + 1) : file));
+    const cwd = join(root, pkg);
+    const runner = await detectTestRunner(cwd, relative);
+    if (!runner) {
+      return fail(
+        `no runner for ${files.length} test${files.length === 1 ? '' : 's'} in ${pkg || 'this repository'}`,
+        EXIT.UNSUPPORTED,
+        'declare a package manifest the test runner can see',
+      );
+    }
+    const built = runner.buildExec(cwd);
+    text.push(`selected  ${files.length}`, ...files, '', runner.displayCmd);
+    // A parent `node --test` puts NODE_TEST_CONTEXT in the environment. Left
+    // there, the child reports to that parent and exits 0 whether or not it failed.
+    const env = { ...process.env };
+    for (const key of Object.keys(env)) {
+      if (key.startsWith('NODE_TEST')) delete env[key];
+    }
+    const result = await exec(built.cmd, built.args, { cwd, env, maxBuffer: 32 << 20 }).then(
+      (out) => ({ code: 0, stdout: out.stdout, stderr: out.stderr }),
+      (error) => ({
+        code: typeof error.code === 'number' ? error.code : 1,
+        stdout: error.stdout ?? '',
+        stderr: error.stderr ?? '',
+      }),
+    );
+    if (result.code !== 0) code = result.code;
+    const stdout = String(result.stdout ?? '');
+    const stderr = String(result.stderr ?? '');
+    const body = stderr ? `${stdout}\n${stderr}` : stdout;
+    rawParts.push(body);
+    const compact = compactOutput(body);
+    runs.push({ package: pkg, command: runner.displayCmd, code: result.code, stdout, stderr });
+    text.push(compact ?? body);
+  }
+  const raw = await writeRaw(root, rawParts.join('\n'));
+  if (raw) text.push('', `raw  ${raw}`);
+  const payload = { ok: code === 0, command: 'gate', root, selected, code, raw, runs };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return code === 0 ? EXIT.OK : EXIT.FAIL;
+  }
+  emit(text.filter((line) => line !== undefined).join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return code === 0 ? EXIT.OK : EXIT.FAIL;
+}
+
+async function writeRaw(root, body) {
+  try {
+    const dir = join(root, '.simt-dev', 'gate');
+    await mkdir(dir, { recursive: true });
+    const name = `gate-${Date.now()}.log`;
+    await writeFile(join(dir, name), body);
+    return `.simt-dev/gate/${name}`;
+  } catch {
+    return '';
+  }
+}
+
+async function tracked(root) {
+  try {
+    const { stdout } = await exec('git', ['ls-files'], { cwd: root, maxBuffer: 16 << 20 });
+    return { files: stdout.split('\n').filter(Boolean) };
+  } catch (error) {
+    return {
+      error: fail(
+        `could not read the change (${error.message})`,
+        EXIT.UNSUPPORTED,
+        'run this inside a git repository',
+      ),
+    };
+  }
+}
+
+async function changedFiles(root) {
+  try {
+    const { stdout } = await exec('git', ['diff', '--name-only', 'HEAD'], { cwd: root, maxBuffer: 8 << 20 });
+    const untracked = await exec('git', ['ls-files', '--others', '--exclude-standard'], { cwd: root, maxBuffer: 8 << 20 });
+    return { files: [...new Set([...stdout.split('\n'), ...untracked.stdout.split('\n')].filter(Boolean))].sort() };
+  } catch (error) {
+    return {
+      error: fail(
+        `could not read the diff (${error.message})`,
+        EXIT.UNSUPPORTED,
+        'run this inside a git repository that has a commit',
+      ),
+    };
+  }
+}
+
+function cmp(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}

package/src/commands/harness.mjs

@@ -16,10 +16,12 @@
 
 import { stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { isAbsolute, join } from 'node:path';
 
-import { EXIT, emit, emitJson, isJson, note } from '../output/index.mjs';
+import { EXIT, emit, emitJson, fail, isJson, note } from '../output/index.mjs';
 import { SURFACES, CANDIDATE_DIRS } from '../projection/surfaces.mjs';
+import { LOADERS, LOADER_IDS, caps, loader } from '../projection/loaders.mjs';
+import { viewAll } from '../measure/loaderView.mjs';
 
 /**
  * `simt-dev harness detect`. The subcommand is validated by dispatch, which rejects a
@@ -88,7 +90,9 @@ async function scan(root) {
     }
   }
   for (const c of CANDIDATE_DIRS) {
-    if (await present(root, c.dir)) rows.push(row(c.dir, c.harness, {}));
+    if (await present(root, c.dir)) {
+      rows.push(row(c.dir, c.harness, { readsAgentsMd: c.readsAgentsMd ?? null, verified: c.verified ?? null }));
+    }
   }
   rows.sort((a, b) => (a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : 0));
   return { root, rows };
@@ -120,7 +124,9 @@ function row(dir, label, surface) {
 }
 
 function countUnclaimed(scan) {
-  return scan.rows.filter((r) => r.surface === null).length;
+  // A candidate that cites a document and reads AGENTS.md is covered by the standard
+  // region. One that cites nothing is the case the note exists for (ADR-067).
+  return scan.rows.filter((r) => r.surface === null && r.readsAgentsMd == null).length;
 }
 
 /**
@@ -143,8 +149,153 @@ function render(root, repo, user) {
 function block(scan, pad) {
   if (scan.rows.length === 0) return [`${pad}(none present)`];
   return scan.rows.map((r) => {
-    const through = r.surface === null ? 'no rule channel in this release' : r.channel ? 'projected rule file' : 'AGENTS.md';
+    const through =
+      r.surface === null
+        ? r.readsAgentsMd === 'all'
+          ? 'AGENTS.md'
+          : 'no rule channel in this release'
+        : r.channel
+          ? 'projected rule file'
+          : 'AGENTS.md';
     const agents = r.readsAgentsMd === 'all' ? ' (reads AGENTS.md)' : r.readsAgentsMd === 'some' ? ' (some readers read AGENTS.md)' : '';
     return `${pad}${r.dir.padEnd(12)} ${r.label.padEnd(38)} ${through}${agents}`;
   });
 }
+
+// `simt harness loaders` - what each reader loads at session start, and the vendor
+// document every claim in that answer came from.
+//
+// It exists because `simt tokens` answers a question about files and this one answers a
+// question about a reader, and the two disagree in ways that matter: Antigravity scans
+// `.agents/rules/` flat and ignores nested files, and Codex stops merging at 32 KiB
+// across the chain rather than per file. A byte count that ignores those is not
+// pessimistic, it is wrong, and it was wrong in the meter this slice unblocked.
+//
+// It exits 0 whatever it finds, for the same reason `harness detect` does: a reader that
+// loads nothing here is a fact about this repository, not a defect in it.
+
+/**
+ * `simt harness loaders [--root <path>] [--reader <id>] [--table]`.
+ *
+ * With no flags it prints one block per reader: what it loads, what the cap leaves out,
+ * and the sentence it was read from. `--reader` narrows it. `--table` prints the
+ * vendor facts without measuring anything, which is the answer to "what does this reader
+ * do" in a repository where the answer is not about bytes.
+ */
+export async function harnessLoadersCommand(positional, flags) {
+  const root = flags.root ?? process.cwd();
+  const wanted = typeof flags.reader === 'string' ? flags.reader : null;
+  const rows = wanted === null ? LOADERS : [loader(wanted)].filter(Boolean);
+
+  if (rows.length === 0) {
+    return fail(
+      `unknown reader "${wanted}"`,
+      EXIT.USAGE,
+      `known readers: ${LOADER_IDS.join(', ')}`,
+    );
+  }
+
+  if (flags.table === true) {
+    const payload = rows.map((row) => ({
+      id: row.id,
+      label: row.label,
+      readers: row.readers,
+      order: row.order,
+      nested: row.nested,
+      start: row.start,
+      alsoReads: row.alsoReads ?? [],
+      imports: row.imports,
+      caps: caps(row),
+      skills: row.skills ?? [],
+      hooks: row.hooks,
+      hooksNote: row.hooksNote ?? null,
+      mcp: row.mcp,
+      verified: row.verified,
+      note: row.note ?? null,
+    }));
+    if (isJson(flags)) {
+      emitJson({ ok: true, command: 'harness loaders', rows: payload });
+      return EXIT.OK;
+    }
+    emit(rows.map((row) => loaderTable(row)).join('\n'));
+    return EXIT.OK;
+  }
+
+  // `--at` asks what a reader loading from a subdirectory would get, which is the only
+  // way the chain rows mean anything: Codex merges the project root down to the working
+  // directory, so the same repository costs a different reader a different total
+  // depending on where that reader is standing.
+  const views = await viewAll(root, rows, flags.at ? { cwd: isAbsolute(flags.at) ? flags.at : join(root, flags.at) } : {});
+  if (isJson(flags)) {
+    emitJson({ ok: true, command: 'harness loaders', root, rows: views });
+    return EXIT.OK;
+  }
+  emit(`${views.map((view) => renderView(view)).join('\n')}`);
+  return EXIT.OK;
+}
+
+/**
+ * One reader's measured view of the repository.
+ *
+ * The dropped rows come first under a heading of their own. A total that quietly
+ * excludes a file past the cap reads as a total, and the reader who is about to lose the
+ * tail of their deepest instruction file to a merge is exactly the person who needs to
+ * see it named.
+ */
+function renderView(view) {
+  const lines = [`${view.reader.padEnd(11)} ${view.label}  ${view.files.length} file(s) at start, ${view.totalBytes} B`];
+  lines.push(`            order     ${view.order}`);
+  for (const file of view.files) {
+    const state = file.beyondCap
+      ? '  BEYOND CAP - not read'
+      : file.truncated
+        ? `  TRUNCATED to ${file.keptBytes} B`
+        : file.overCap
+          ? `  OVER CAP (${file.countedBytes} B)`
+          : '';
+    lines.push(`            ${file.file.padEnd(44)} ${String(file.countedBytes).padStart(7)} B${state}`);
+  }
+  if (view.cap) {
+    lines.push(`            cap       ${view.cap.bytes} B over ${view.cap.appliesTo} (${view.cap.config ?? 'fixed'})`);
+  } else if (!view.perFileCap && !view.budget) {
+    lines.push('            cap       none published');
+  }
+  if (view.perFileCap) {
+    lines.push(`            file cap  ${view.perFileCap.bytes} B per rule file (${view.perFileCap.config ?? 'fixed'})`);
+  }
+  if (view.budget) {
+    lines.push(`            budget    ${view.budget.tokens} tokens (${view.budget.bytes} B approx) over ${view.budget.appliesTo}`);
+  }
+  if (view.imports?.syntax) {
+    lines.push(`            imports   ${view.imports.syntax}, ${view.imports.depth} hop(s)`);
+  }
+  if (view.userScope.length > 0) {
+    lines.push(`            user      ${view.userScope.join(', ')} (not measured: your bytes, not the repo's)`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/** The vendor facts, without a repository — the part of the answer that is not a measurement. */
+function loaderTable(row) {
+  const lines = [`${row.id}  ${row.label}  (${row.readers})`];
+  lines.push(`  order     ${row.order}`);
+  lines.push(`  nested    ${row.nested}`);
+  for (const entry of row.start) {
+    const where = entry.scope === 'user' ? 'user' : 'project';
+    lines.push(`  start     ${where} ${entry.path}${entry.atStart ? '' : ' (on demand)'}`);
+  }
+  for (const extra of row.alsoReads ?? []) {
+    lines.push(`  also      ${extra.what}${extra.atStart ? '' : ' (on demand)'}`);
+  }
+  for (const c of caps(row)) {
+    lines.push(`  cap       ${c.bytes} ${c.scope === 'tokens' ? 'tokens' : 'B'} over ${c.appliesTo ?? c.scope}`);
+  }
+  if (row.cap === null) lines.push(`  cap       none published — ${row.capNote ?? 'checked'}`);
+  lines.push(`  skills    ${(row.skills ?? []).join(', ') || 'none documented'}`);
+  lines.push(`  hooks     ${row.hooks?.path ?? 'none documented'}${row.hooksNote ? ` — ${row.hooksNote}` : ''}`);
+  lines.push(
+    `  mcp       ${row.mcp?.path ?? (row.mcp?.key ? `profile ${row.mcp.key}` : 'none documented')}`,
+  );
+  lines.push(`  source    ${row.verified}`);
+  return lines.join('\n');
+}

package/src/commands/help.mjs

@@ -1,6 +1,7 @@
 import { emit } from '../output/index.mjs';
 import { parse } from '../argv.mjs';
-import { CLI } from '../name.mjs';
+import { CLI, MANIFEST_FILE } from '../name.mjs';
+import { DEFAULT_DIRECTORIES, DEFAULT_TEMPLATE } from '../plan/template.mjs';
 
 const COMMANDS = `${CLI} init [path]            adopt or scaffold a repo into the ecosystem
                            (dry-run unless --yes; conflicts block without
@@ -38,6 +39,20 @@ ${CLI} hooks install [--yes]   install the shared dispatcher; report what it wou
 ${CLI} hooks status            what each git event routes to, and whether it is wired
 ${CLI} hooks run <event>       run one event's gates now, as git would
                            (pre-commit, pre-push, post-merge, ...)
+${CLI} agent-hook <event>      the entry point a harness calls before a tool call
+                           (reads one JSON payload on stdin and answers in that
+                            harness's dialect; exit 2 blocks; needs --harness)
+${CLI} agent-hooks install     write this repo's policies into the harnesses that
+                            read a hooks file
+                           (dry-run unless --yes; merges into the file, keeps every
+                            key it does not own; Codex needs the hook trusted)
+${CLI} agent-hooks status      what each harness will run, and what is not trusted yet
+${CLI} plan status             count tracker rows
+                           (${MANIFEST_FILE} key plans when set, otherwise
+                           the ${DEFAULT_TEMPLATE} template:
+                           ${DEFAULT_DIRECTORIES.join(' and ')})
+${CLI} plan next [<id>]        one ready slice's section, or the one named; ~1 KB
+${CLI} plan done <id> [<sha>]  mark one row; dry-run unless --yes
 ${CLI} graph lint              check the skill registry against the skills on disk
                            (byte counts, dangling edges, unresolvable variants)
 ${CLI} ci                     simt-dev's own .github files: create or refresh them
@@ -46,6 +61,35 @@ ${CLI} ci                     simt-dev's own .github files: create or refresh th
 ${CLI} compare                org-wide matrix across every sibling repo
                            (read-only; exits non-zero on defects, not on
                            repos that have not adopted yet)
+${CLI} index                   rebuild the local file index from git blob hashes
+${CLI} why [path]            what governs a file: a decision whose Affects line names
+                           it, a rule whose scope matches it, a skill, a gate
+                           or a lesson. With no path, the Affects tokens this
+                           tree cannot resolve (UNRESOLVED-AFFECTS)
+${CLI} tests [path]          the tests that exercise a file: an import, the conventional
+                           source beside the test, or a coverage record that
+                           names both (--cochange adds files that only share
+                           commits, and only those)
+${CLI} gate [path...]        the tests a change reaches, and only those
+                           (--changed reads the diff instead of the paths)
+${CLI} impact <file|symbol>  who a change reaches: importers, their tests,
+                           what governs it, and a contract another repository references
+${CLI} map [--task "<text>"] [--level outline|names|signatures]
+                           the files this task is most likely to touch, within
+                           --budget bytes (default 2048; 0 is unlimited). outline
+                           is paths, names adds exports, signatures adds the line.
+                           --recall reports gold-file recall@10 on mined tasks
+${CLI} evidence                the runs recorded against the tree on disk
+${CLI} evidence check <file>   a commit message that claims a run this tree does not
+                           have: a warning, or a block when gates.evidence is "block"
+${CLI} shared plan            what a workspace's repeated rules cost to carry
+                           once: the shared set, its bytes, and every path that would be written
+                           (read-only; touches nothing, not even your home directory)
+${CLI} shared install [--yes] carry those rules once per reader, at user level,
+                           and declare the delta in each repo's manifest (dry-run unless
+                           --yes; copies land in files the vendors' own docs name, and a reader
+                           with no such file gets the block printed to paste; ${CLI} doctor
+                           reports a copy that is missing or stale)
 ${CLI} tokens [--repos]       what a reader loads at session start, in bytes
                            (read-only; exits 0 whatever it finds, because a
                            measurement is not a verdict; --repos measures every
@@ -54,6 +98,25 @@ ${CLI} harness detect         which harnesses this repo (and, with --user, you)
                            are set up for, and which have a rule channel here
                            (presence only: a directory found is not a claim about
                            what its owner reads; exits 0 whatever it finds)
+${CLI} harness loaders        what each reader loads at session start, in bytes,
+                            and what its size cap drops
+                            (--table prints the vendor facts without measuring;
+                            --reader <id> narrows it; every claim cites its source)
+${CLI} bench mine [--yes]     mine verified benchmark tasks from git history
+                            (dry-run unless --yes; validates RED and GOLD twice in
+                            a temp worktree and stores test patches in the vault)
+${CLI} bench run [--yes]      run benchmark tasks across arms in isolated one-commit exports
+                            (dry-run unless --yes; grades against vault test patches
+                            and declared gates; --regrade <run> verifies stored runs)
+${CLI} bench report           statistical report across benchmark arms (R, Q, C, CPI, cache)
+                            (read-only; paired bootstrap 95% CIs; --compare <a> <b>
+                            prints deltas with McNemar and Wilcoxon p-values)
+${CLI} bench ablate [--yes]    leave-one-out ablation across core, profile and process sections
+                            (dry-run unless --yes; 10-task canary with escalation,
+                            value-per-KB ranking and deletion candidates)
+${CLI} bench probes [--yes]    12 synthetic rule-compliance probes with deterministic graders
+                            (dry-run unless --yes; grades git state, transcript and ledger,
+                            and reports compliance per arm)
 ${CLI} mcp                    the read-only surface as MCP tools over stdio
                            (--list prints it without reading stdin; init, sync,
                            upgrade and the installers stay CLI-only by design)`;
@@ -76,6 +139,10 @@ const FLAGS = `--json                 structured output (compact; one document,
 --dry-run               report what would change, change nothing
 --yes                   assume yes; required in automation, never prompts
 --check                 report drift and write nothing (sync, ci)
+--frozen                check: the lock must match this projection; an output
+                        change no input change explains fails the gate
+--explain               sync: name each line dropped as already inferable, with
+                        the fact behind it
 --all                   ignore a cap: every ruling of a record, or the skills budget
 --variant <id>          which body of a multi-variant skill to use
 --from <repo/path>      install from a declared source by name
@@ -88,6 +155,27 @@ const FLAGS = `--json                 structured output (compact; one document,
 --user                  harness detect: also report the directories in your home
 --repos                 tokens: measure every repository under the root, not
                         just the one, and report what repeats an earlier one
+--session <path>        tokens: split a local Claude Code or Codex transcript
+                        into rules, file reads and tool output
+--reader <id>           harness loaders: report one reader (opencode, claude, codex,
+                         cursor, antigravity, copilot, deepseek)
+--table                 harness loaders: print order, caps, imports, skill dirs and
+                         the hook and MCP config files, without measuring a repo
+--at <path>             harness loaders: measure as if the agent were working in
+                         this directory (default: the root; readers that merge the
+                         project root down to the working directory cost more here)
+--arm <spec>            bench run: arm to evaluate (bare, current, kernel, brief,
+                         or name=path/to/arm.json; repeatable)
+--harness <id>          bench run: adapter to invoke (claude, codex, gemini, opencode,
+                         cursor, aider, gold, noop; default: gold);
+                         agent-hook: which dialect to answer in (claude, cursor,
+                         codex, antigravity)
+--model <id>            bench run: model identifier recorded and passed to the adapter
+--reps <n>              bench run: repetitions per task and arm (default: 3)
+--regrade <run>         bench run: re-grade a stored run from its archived agent patch
+--compare <a> <b>       bench report: compare two arms with deltas and p-values
+--test <cmd>            plan done: the test command that closes the row
+--state <name>          plan done: target state (default: Complete)
 --help                  this text
 --version               the version, and the SHA it was built from`;