simt-dev 0.2.1 → 0.3.0

package/src/commands/graph.mjs

@@ -6,11 +6,18 @@
 // Output is line-oriented and bounded (plan 0002 section 6). A lint failure names
 // the offending node, the file it disagrees with, and both numbers.
 
-import { EXIT, emit, fail, isJson } from '../output/index.mjs';
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
 import { loadRegistry } from '../graph/load.mjs';
+import { lintSpec } from '../graph/speccheck.mjs';
+import { SPEC, SPEC_SOURCE } from '../graph/spec.mjs';
 import { CLI } from '../name.mjs';
 
 export async function lintCommand(positional, flags) {
+  const spec = flags.spec ?? null;
+  if (spec !== null && spec !== SPEC) {
+    return fail(`unknown --spec "${spec}"`, EXIT.USAGE, `the one specification this lints is: ${SPEC}`);
+  }
+
   // The resolved path comes back from the loader, because when no positional is given it
   // falls back to the member that holds the registry in this workspace (ADR-061) - and the
   // reader should see where it actually looked, not a constant that no longer exists.
@@ -19,27 +26,38 @@ export async function lintCommand(positional, flags) {
     flags,
   );
 
+  // The conformance pass is separate from the registry pass on purpose. The registry
+  // answers "does the bookkeeping match the files"; the specification answers "would a
+  // client accept these files", and the second question needs no registry at all. A
+  // reader with no registry can still lint a skill directory, so the two are additive
+  // rather than one gating the other.
+  const specReport = registry && workspace?.root
+    ? await lintSpec(registry, workspace.root)
+    : { errors: [], warnings: [], checked: 0 };
+  errors.push(...specReport.errors);
+  warnings.push(...specReport.warnings);
+
   if (isJson(flags)) {
-    emit(
-      `${JSON.stringify(
-        {
-          ok,
-          registry: path,
-          capabilities: registry?.capabilities?.length ?? 0,
-          skills: registry?.skills?.length ?? 0,
-          // `verified: false` means the byte counts in the registry were NOT
-          // checked against files on disk. It is not a failure - it is the difference
-          // between "the registry is right" and "the registry could not be checked",
-          // and an agent that cannot see the difference will trust a number nobody
-          // measured (ADR-014).
-          verified,
-          workspace,
-          errors,
-          warnings,
-        },
-        null,
-        2,
-      )}\n`,
+    emitJson(
+      {
+        ok,
+        registry: path,
+        capabilities: registry?.capabilities?.length ?? 0,
+        skills: registry?.skills?.length ?? 0,
+        // `verified: false` means the byte counts in the registry were NOT
+        // checked against files on disk. It is not a failure - it is the difference
+        // between "the registry is right" and "the registry could not be checked",
+        // and an agent that cannot see the difference will trust a number nobody
+        // measured (ADR-014).
+        verified,
+        workspace,
+        // Present only when asked for, so a reader of the default output is not told
+        // about a pass that never ran. `null` is the honest value; `true` would be a
+        // claim about conformance nobody checked.
+        spec: spec === null ? null : { name: SPEC, source: SPEC_SOURCE, checked: specReport.checked },
+        errors,
+        warnings,
+      },
       { maxBytes: flags.maxBytes ?? 0 },
     );
     return ok ? EXIT.OK : EXIT.REGISTRY;
@@ -57,6 +75,12 @@ export async function lintCommand(positional, flags) {
     `nodes     ${registry.skills.length} skills, ${registry.capabilities.length} capabilities`,
     `verified  ${verified ? 'byte counts checked against disk' : 'NOT checked - see WARN below'}`,
   ];
+  if (spec !== null) {
+    lines.push(
+      `spec      ${specReport.checked} skills checked against ${SPEC_SOURCE}` +
+        `${specReport.checked === 0 ? ' (none had a readable SKILL.md)' : ''}`,
+    );
+  }
 
   const deferred = registry.skills.filter((s) => s.deferred);
   lines.push(

package/src/commands/harness.mjs

@@ -0,0 +1,301 @@
+// `simt harness detect` - which harnesses this repository (and this user) is set up
+// for, and which of them simt-dev has a channel for.
+//
+// Why this is a command and not a sentence in the docs: the question "which harness
+// reads my rules" has two halves that used to be answered in different places, and the
+// second half was answered by a reader's guess. What is present on disk is observable
+// and belongs to the tool; what a given harness actually loads is a vendor fact, and a
+// vendor fact is only trustworthy when it names its source. So the table that says "we
+// have a channel for this" and the table that says "we have not verified one" are kept
+// apart, and this command reports both without collapsing them into a verdict.
+//
+// It exits 0 whatever it finds. A harness with no channel is a fact about coverage, not
+// a defect in the repository: the rules in AGENTS.md still reach whichever harnesses
+// read that file, and a reader who wanted a failing command could not tell the
+// difference between "no channel" and "broken".
+
+import { stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+
+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
+ * second token that is not in the group registry rather than silently routing to the
+ * default; this function therefore has exactly one thing to do and no second spelling
+ * to keep in step with it.
+ *
+ * @param {string[]} positional arguments after the command path
+ * @param {object} flags
+ * @returns {Promise<number>} process exit code
+ */
+export async function harnessCommand(positional, flags) {
+  const root = flags.root ?? process.cwd();
+
+  const repo = await scan(root);
+  // Only on request. The home directory is the reader's, not the repository's, and a
+  // command that reports both by default is a command whose output changes because
+  // somebody installed something elsewhere.
+  const user = flags.user === true ? await scan(homedir()) : null;
+
+  if (isJson(flags)) {
+    emitJson({
+      ok: true,
+      command: 'harness detect',
+      root,
+      repo,
+      ...(user === null ? {} : { user }),
+    });
+    return EXIT.OK;
+  }
+
+  emit(render(root, repo, user));
+  if (repo.rows.length === 0) {
+    note(
+      `note     no harness configuration directory found in ${root}. That is a repository ` +
+        'nobody has set an agent up in - not a finding.',
+    );
+  }
+  const unclaimed = countUnclaimed(repo);
+  if (unclaimed > 0) {
+    note(
+      `note     ${unclaimed} present configur${unclaimed === 1 ? 'ation has' : 'ations have'} ` +
+        'no rule channel in this release. Each one is reported as present, not as ' +
+        'unsupported: whether it reads AGENTS.md is a vendor question this tool does not ' +
+        'answer without a source, and a guess here would be the reader\'s problem later.',
+    );
+  }
+  return EXIT.OK;
+}
+
+/**
+ * Every harness directory present under one root, sorted by directory name.
+ *
+ * A directory whose stat fails for any reason other than absence is treated as absent
+ * rather than raised: a permissions error on one candidate must not make the whole
+ * command fail, and the difference between "could not look" and "not there" is one
+ * note in the output rather than a second failure mode nobody asked for.
+ */
+async function scan(root) {
+  const rows = [];
+  for (const s of SURFACES) {
+    for (const dir of s.configDirs ?? []) {
+      if (await present(root, dir)) {
+        rows.push(row(dir, s.label, { id: s.id, verified: s.verified ?? null, readsAgentsMd: s.readsAgentsMd, rule: s.rule }));
+      }
+    }
+  }
+  for (const c of CANDIDATE_DIRS) {
+    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 };
+}
+
+async function present(root, dir) {
+  try {
+    return (await stat(join(root, dir))).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** One present directory, and what - if anything - this tool can project into it. */
+function row(dir, label, surface) {
+  const id = surface.id ?? null;
+  return {
+    dir,
+    label,
+    surface: id,
+    // `channel: false` is the honest half of the answer: the directory exists and this
+    // release has no rule file to write there. Reported as its own field rather than
+    // left implicit, because "we found it and did nothing" and "we found nothing" look
+    // identical in a list of names.
+    channel: id !== null && surface.rule != null,
+    readsAgentsMd: surface.readsAgentsMd ?? null,
+    verified: surface.verified ?? null,
+  };
+}
+
+function countUnclaimed(scan) {
+  // 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;
+}
+
+/**
+ * One line per present directory, in the order the scanner found them.
+ *
+ * `surface` is printed when there is one, and `AGENTS.md` is named when the surface
+ * loads it - because the answer a reader actually wants is "do my rules reach this",
+ * and the channel column alone does not answer it.
+ */
+function render(root, repo, user) {
+  const lines = [`repo     ${root}`];
+  lines.push(...block(repo, '        '));
+  if (user !== null) {
+    lines.push(`user     ${user.root}`);
+    lines.push(...block(user, '        '));
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function block(scan, pad) {
+  if (scan.rows.length === 0) return [`${pad}(none present)`];
+  return scan.rows.map((r) => {
+    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,11 +61,39 @@ ${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} 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
+                           repository under the root and what repeats an earlier)
+${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)`;
 
-const FLAGS = `--json                 structured output
+const FLAGS = `--json                 structured output (compact; one document, one line)
+--pretty                indent --json for a human
 --max-bytes <n>         hard ceiling on emitted bytes (0 = unlimited, default 0)
 --budget <n>            context budget for skills brief (default 20480)
 --plan                  emit a fetch plan instead of inlining skill bodies
@@ -67,6 +110,8 @@ const FLAGS = `--json                 structured output
 --dry-run               report what would change, change nothing
 --yes                   assume yes; required in automation, never prompts
 --check                 report drift and write nothing (sync, ci)
+--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
@@ -74,6 +119,32 @@ const FLAGS = `--json                 structured output
 --accept-conflicts      init: adopt rules that collide with hand-written ones
 --backup                init: tag the pre-adoption commit and branch onto
                         simt-dev/adopt before writing (the undo path)
+--spec <name>           graph lint: also check every skill against a named
+                        specification (one exists: agentskills)
+--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`;
 

package/src/commands/index.mjs

@@ -6,7 +6,15 @@
 // succeeds. An agent that calls `simt-dev compare` on an unreleased build must get a
 // failure, not an empty result it will read as "no drift".
 
-import { EXIT, emit, fail, isJson } from '../output/index.mjs';
+import {
+  EXIT,
+  emit,
+  emitJson,
+  fail,
+  isJson,
+  jsonFailMode,
+  jsonIndentDefault,
+} from '../output/index.mjs';
 import { help } from './help.mjs';
 import { lintCommand } from './graph.mjs';
 import {
@@ -21,11 +29,22 @@ import { syncCommand, checkCommand } from './sync.mjs';
 import { initCommand } from './init.mjs';
 import { ciCommand } from './ci.mjs';
 import { hooksCommand } from './hooks.mjs';
+import { agentHookCommand, agentHooksCommand } from './agenthook.mjs';
 import { compareCommand } from './compare.mjs';
 import { upgradeCommand } from './upgrade.mjs';
 import { mcpCommand } from './mcp.mjs';
 import { installCommand } from './skillsinstall.mjs';
 import { listCommand as rulesList, showCommand as rulesShow, whyCommand as rulesWhy } from './rules.mjs';
+import { tokensCommand } from './tokens.mjs';
+import { harnessCommand, harnessLoadersCommand } from './harness.mjs';
+import {
+  benchMineCommand,
+  benchRunCommand,
+  benchReportCommand,
+  benchAblateCommand,
+  benchProbesCommand,
+} from './bench.mjs';
+import { planCommand } from './plan.mjs';
 import { parse } from '../argv.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
 import { resolveWorkspace } from '../workspace.mjs';
@@ -43,6 +62,10 @@ const GROUPS = new Map([
   ['graph', 'lint'],
   ['rules', 'list'],
   ['hooks', 'status'],
+  ['plan', 'status'],
+  ['agent-hooks', 'status'],
+  ['harness', 'detect'],
+  ['bench', 'mine'],
 ]);
 
 /**
@@ -58,7 +81,7 @@ const GROUPS = new Map([
  * Module scope so `test/cli.test.mjs` can assert help against it. Module scope is also
  * just correct: nothing in the map depends on the call.
  */
-const IMPLEMENTED = {
+export const IMPLEMENTED = {
   doctor: runDoctor,
   'graph lint': lintCommand,
   'skills index': skillsIndex,
@@ -73,12 +96,26 @@ const IMPLEMENTED = {
   'rules why': rulesWhy,
   sync: syncCommand,
   check: checkCommand,
+  'plan status': (args, flags) => planCommand('status', args, flags),
+  'plan next': (args, flags) => planCommand('next', args, flags),
+  'plan done': (args, flags) => planCommand('done', args, flags),
   init: initCommand,
   ci: ciCommand,
   'hooks install': (args, flags) => hooksCommand('install', args, flags),
   'hooks status': (args, flags) => hooksCommand('status', args, flags),
   'hooks run': (args, flags) => hooksCommand('run', args, flags),
+  'agent-hook': agentHookCommand,
+  'agent-hooks install': (args, flags) => agentHooksCommand('install', args, flags),
+  'agent-hooks status': (args, flags) => agentHooksCommand('status', args, flags),
   compare: compareCommand,
+  tokens: tokensCommand,
+  'harness detect': harnessCommand,
+  'harness loaders': harnessLoadersCommand,
+  'bench mine': benchMineCommand,
+  'bench run': benchRunCommand,
+  'bench report': benchReportCommand,
+  'bench ablate': benchAblateCommand,
+  'bench probes': benchProbesCommand,
   upgrade: upgradeCommand,
   mcp: mcpCommand,
 };
@@ -92,6 +129,17 @@ export const COMMANDS = Object.keys(IMPLEMENTED).sort();
 export async function dispatch(argv) {
   const { flags, positional } = parseOrExit(argv);
 
+  // The JSON shape is decided once, here, and every command inherits it. Threading a
+  // `--pretty` through twenty-five call sites would mean twenty-five places to forget,
+  // and the one that forgot would be the one a reader pipes into a script.
+  //
+  // Both halves are set before anything can fail, because a command that fails under
+  // `--json` has still produced a result: the reason it failed. Set here, an unknown
+  // command answers in the same shape a working one does, and the caller's parse
+  // never sees an empty document.
+  jsonIndentDefault(flags.pretty === true);
+  jsonFailMode(flags.json === true);
+
   // Help is shown only when explicitly asked for. An unknown command must fail with
   // a usage code, not print 40 lines of prose and exit 0 — an agent that mistyped
   // needs to be told so, not handed a wall of text it may misread as output.
@@ -191,29 +239,23 @@ async function runDoctor(positional, flags) {
   const code = failure ? EXIT.CONFIG : EXIT.OK;
 
   if (isJson(flags)) {
-    emit(
-      `${JSON.stringify(
-        {
-          ok: code === EXIT.OK,
-          command: 'doctor',
-          root,
-          ...result,
-          // The workspace answer is a fact about which directory the tool would
-          // act on next (ADR-014). It is printed in the text report; leaving it
-          // out of the JSON meant a machine-readable caller could not see it at
-          // all, which is the one-question-two-answers defect again.
-          workspace: {
-            root: ws.root ?? null,
-            source: ws.source,
-            detail: ws.detail,
-            error: ws.error ?? null,
-          },
-          ...(failure ?? {}),
-        },
-        null,
-        2,
-      )}\n`,
-    );
+    emitJson({
+      ok: code === EXIT.OK,
+      command: 'doctor',
+      root,
+      ...result,
+      // The workspace answer is a fact about which directory the tool would
+      // act on next (ADR-014). It is printed in the text report; leaving it
+      // out of the JSON meant a machine-readable caller could not see it at
+      // all, which is the one-question-two-answers defect again.
+      workspace: {
+        root: ws.root ?? null,
+        source: ws.source,
+        detail: ws.detail,
+        error: ws.error ?? null,
+      },
+      ...(failure ?? {}),
+    });
     return code;
   }
   if (result.error) {