simt-dev 0.7.0 → 0.7.1

package/src/commands/compare.mjs

@@ -21,7 +21,7 @@
 
 import { basename, resolve } from 'node:path';
 
-import { EXIT, emit, emitJson, fail, isJson, note } from '../output/index.mjs';
+import { EXIT, fail, note, present } from '../output/index.mjs';
 import { provenanceDigest } from '../projection/project.mjs';
 import { GATES } from '../hooks/gates.mjs';
 import { buildRows, resolveConcurrency, summarise } from '../compare/row.mjs';
@@ -78,50 +78,50 @@ export async function compareCommand(positional, flags) {
     directories: found.directories.length,
   });
 
-  if (isJson(flags)) {
-    emitJson({
-      ok: !rows.some((r) => r.problems.length > 0),
-      command: 'compare',
-      root: summary.root,
-      shape: summary.shape,
-      source: summary.source,
-      expectedSha: summary.expectedSha,
-      // Spread, not a hand-listed copy. A copy is a second place to forget: a field
-      // added to `summarise` renders in the text output and silently vanishes from
-      // `--json`, which is the combination automation trusts most. That is not
-      // hypothetical — `withOwnHooks` and `staleRuleFiles` both did it, and both
-      // were caught only because a test asserts the two shapes agree.
-      summary: {
-        repos: summary.repos,
-        adopted: summary.adopted,
-        unmanaged: summary.unmanaged,
-        broken: summary.broken,
-        drifted: summary.drifted,
-        current: summary.current,
-        noRegion: summary.noRegion,
-        malformed: summary.malformed,
-        staleRuleFiles: summary.staleRuleFiles,
-        packageRegions: summary.packageRegions,
-        stalePackages: summary.stalePackages,
-        hooksRouted: summary.hooksRouted,
-        withProblems: summary.withProblems,
-        withOwnHooks: summary.withOwnHooks,
-        shas: summary.shas,
-      },
-      rows,
-      learning,
-      worktrees: found.worktrees.map((w) => ({
-        name: w.name,
-        path: w.path,
-        owner: w.ownerName,
-        ownerMatchesDirName: w.ownerMatches,
-      })),
-      directories: found.directories.map((d) => basename(d)),
-    });
+  const payload = {
+    ok: !rows.some((r) => r.problems.length > 0),
+    command: 'compare',
+    root: summary.root,
+    shape: summary.shape,
+    source: summary.source,
+    expectedSha: summary.expectedSha,
+    // Spread, not a hand-listed copy. A copy is a second place to forget: a field
+    // added to `summarise` renders in the text output and silently vanishes from
+    // `--json`, which is the combination automation trusts most. That is not
+    // hypothetical — `withOwnHooks` and `staleRuleFiles` both did it, and both
+    // were caught only because a test asserts the two shapes agree.
+    summary: {
+      repos: summary.repos,
+      adopted: summary.adopted,
+      unmanaged: summary.unmanaged,
+      broken: summary.broken,
+      drifted: summary.drifted,
+      current: summary.current,
+      noRegion: summary.noRegion,
+      malformed: summary.malformed,
+      staleRuleFiles: summary.staleRuleFiles,
+      packageRegions: summary.packageRegions,
+      stalePackages: summary.stalePackages,
+      hooksRouted: summary.hooksRouted,
+      withProblems: summary.withProblems,
+      withOwnHooks: summary.withOwnHooks,
+      shas: summary.shas,
+    },
+    rows,
+    learning,
+    worktrees: found.worktrees.map((w) => ({
+      name: w.name,
+      path: w.path,
+      owner: w.ownerName,
+      ownerMatchesDirName: w.ownerMatches,
+    })),
+    directories: found.directories.map((d) => basename(d)),
+  };
+
+  if (present(payload, () => render(rows, summary, found, learning), flags) === 'json') {
     return rows.some((r) => r.problems.length > 0) ? EXIT.FAIL : EXIT.OK;
   }
 
-  emit(render(rows, summary, found, learning), { maxBytes: flags.maxBytes ?? 0 });
   if (summary.shape === 'repo') {
     note('note     one repository compared; pass --root at a workspace directory to compare its siblings');
   } else if (target.source === 'none') {

package/src/commands/completions.mjs

@@ -5,7 +5,7 @@
 // `$fpath`. A report line above it would be a report line in the user's shell
 // config.
 
-import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { EXIT, fail, present } from '../output/index.mjs';
 import { SHELLS, renderCompletions } from '../completions.mjs';
 
 export async function completionsCommand(args, flags, commands) {
@@ -18,10 +18,6 @@ export async function completionsCommand(args, flags, commands) {
   }
 
   const script = renderCompletions(shell, commands);
-  if (isJson(flags)) {
-    emitJson({ ok: true, command: 'completions', shell, script });
-    return EXIT.OK;
-  }
-  emit(script, { maxBytes: flags.maxBytes ?? 0 });
+  present({ ok: true, command: 'completions', shell, script }, () => script, flags);
   return EXIT.OK;
 }

package/src/commands/decide.mjs

@@ -10,9 +10,10 @@ import { lintDecisions, scaffoldDecision } from '../memory/decide.mjs';
 import { commitJournal } from '../journal.mjs';
 import { diffField, emitDiffs } from '../diff.mjs';
 import { parsePathList } from '../argv.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 export async function decideCommand(args, flags) {
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
 
   if (flags.check === true) {
     // Q55: one resolution — the manifest key, then the detected directory —
@@ -31,7 +32,7 @@ export async function decideCommand(args, flags) {
     }
 
     if (res.findings.length === 0) {
-      emit('decisions  ok', { maxBytes: flags.maxBytes ?? 0 });
+      emit('decisions  ok');
       return EXIT.OK;
     }
 
@@ -42,7 +43,6 @@ export async function decideCommand(args, flags) {
           ...(f.remedy ? [`  remedy: ${f.remedy}`] : []),
         ])
         .join('\n'),
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     return EXIT.FAIL;
   }
@@ -123,7 +123,7 @@ export async function decideCommand(args, flags) {
         : `would write ${res.relPath}; apply with: ${CLI} decide ${JSON.stringify(res.title)} --yes`,
   ];
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   // After the report: the report says what, the diff shows it (R50).
   emitDiffs(diffs, flags);
   return EXIT.OK;

package/src/commands/distill.mjs

@@ -16,7 +16,7 @@ export async function distillCommand(args, flags) {
   if (typeof result === 'number') return result;
 
   if (isJson(flags)) {
-    emitJson(result, { maxBytes: flags.maxBytes ?? 0 });
+    emitJson(result);
     return EXIT.OK;
   }
 
@@ -27,10 +27,11 @@ export async function distillCommand(args, flags) {
       `engine    ${result.engine}`,
       `budget    ${result.budget} bytes`,
       `citations ${result.citations}`,
-      ...(result.verified === true ? [] : result.faults.map((f) => `unverified ${f}`)),
+      // A cached proposal predates this field; `?? []` keeps the report from crashing on
+      // the file the command wrote one release ago (review 0003 Q52).
+      ...(result.verified === true ? [] : (result.faults ?? []).map((f) => `unverified ${f}`)),
       `proposal  ${result.proposal.path}  (${result.proposal.state}, ${result.proposal.bytes} bytes)`,
     ].join('\n'),
-    { maxBytes: flags.maxBytes ?? 0 },
   );
   return EXIT.OK;
 }

package/src/commands/doctor.mjs

@@ -22,18 +22,20 @@
 // `--yes` previews: it names what it would apply and lists the rest.
 
 import { join } from 'node:path';
+import { repoContext } from '../context.mjs';
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
 import { CLI, MANIFEST_FILE } from '../name.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
 import { resolveWorkspace } from '../workspace.mjs';
 import { sharedWarning } from './shared.mjs';
 import { diffField, emitDiffs, readBefore } from '../diff.mjs';
-import { manifestPath, readManifest, writeManifest } from '../projection/manifest.mjs';
+import { manifestPath, writeManifest } from '../projection/manifest.mjs';
 import { planManifestRepair } from './sync.mjs';
 import { provenanceDigest } from '../projection/project.mjs';
 import { applyHooksInstall, plannedDiffs, planHooksInstall } from './hooks.mjs';
 import { fileFor } from '../hooks/shim.mjs';
 import { commitJournal, ignoreJournal, journalHygiene, journalIgnoreNext } from '../journal.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 /**
  * One config-health finding: what is wrong, how to fix it, and whether
@@ -47,7 +49,7 @@ import { commitJournal, ignoreJournal, journalHygiene, journalIgnoreNext } from
 // finding creation, before any fix is applied, so the before side is true in
 // preview and in apply alike. Only safe findings carry pairs: an unsafe finding
 // is never applied, so there is no write to preview.
-async function collectFindings(root, { result, ws, shared, withDiffs = false }) {
+async function collectFindings(root, { result, ws, shared, withDiffs = false, ctx }) {
   const findings = [];
   if (result.error) {
     // Nothing else can be asked: classification failed, so every check built on
@@ -63,7 +65,7 @@ async function collectFindings(root, { result, ws, shared, withDiffs = false })
     return findings;
   }
 
-  const { manifest, exists, error: manifestError } = await readManifest(root);
+  const { manifest, exists, error: manifestError } = await ctx.manifest();
   if (manifestError !== null) {
     // An unreadable manifest is a hand-edit, not a repair: re-rendering it
     // would destroy whatever the other tool was saying.
@@ -232,7 +234,10 @@ function findingLines(findings, { fixMode, applying }) {
 //
 // See the module header: classification first, because everything else is a guess without it.
 export async function diagnose(root, args = {}) {
-  const result = await fingerprint(root);
+  // One context for the whole diagnosis, so a caller that already holds one (a UI, a
+  // harness, an MCP request) does not pay for a second fingerprint (review 0003 Q67).
+  const ctx = args.ctx ?? repoContext(root);
+  const result = await ctx.fingerprint();
   // Which source answered the workspace question, and where it looked. A tool
   // that silently fell back to the wrong directory would make every downstream
   // answer confidently wrong, so the answer is reported rather than inferred
@@ -246,7 +251,7 @@ export async function diagnose(root, args = {}) {
   const shared = await sharedWarning(root, result.manifest ?? null, args);
 
   const withDiffs = args.fix === true && args.diff === true;
-  const findings = await collectFindings(root, { result, ws, shared, withDiffs });
+  const findings = await collectFindings(root, { result, ws, shared, withDiffs, ctx });
   // Under `--json` the document is the whole report, so it has to carry both
   // failures the text path reports AND the workspace answer the text prints.
   const failure = result.error
@@ -276,7 +281,7 @@ export function serialisedFindings(findings) {
 }
 
 export async function runDoctor(positional, flags) {
-  const root = flags.root ?? positional[0] ?? process.cwd();
+  const root = commandRoot(flags, positional);
   const { result, ws, shared, findings, failure, code: diagnosisCode } = await diagnose(root, flags);
 
   const fixMode = flags.fix === true;
@@ -344,7 +349,6 @@ export async function runDoctor(positional, flags) {
       ...(shared.declared ? [`shared    ${shared.state}  ${shared.detail}`] : []),
       ...findingLines(findings, { fixMode, applying: mode.apply }),
     ].join('\n'),
-    { maxBytes: flags.maxBytes ?? 0 },
   );
   // After the report: the report says what, the diff shows it (R50). Only the
   // fix plan is diffed, so without --fix there is nothing to show.

package/src/commands/evidence.mjs

@@ -6,7 +6,7 @@
 
 import { readFile } from 'node:fs/promises';
 
-import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { EXIT, emit, emitJson, fail, isJson, present } from '../output/index.mjs';
 import { readManifest } from '../projection/manifest.mjs';
 import { CLI, MANIFEST_FILE } from '../name.mjs';
 import {
@@ -17,9 +17,10 @@ import {
   readLedger,
   treeId,
 } from '../ledger/index.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 export async function evidenceCommand(args, flags) {
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   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`);
@@ -42,7 +43,7 @@ async function showEvidence(root, flags) {
   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 });
+    emitJson(payload);
     return errors.length === 0 ? EXIT.OK : EXIT.FAIL;
   }
   const lines = [`tree     ${tree}`];
@@ -51,7 +52,7 @@ async function showEvidence(root, flags) {
     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 });
+  emit(lines.join('\n'));
   return errors.length === 0 ? EXIT.OK : EXIT.FAIL;
 }
 
@@ -97,10 +98,6 @@ async function checkClaim(root, file, flags) {
   }
   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 });
+  present({ ...payload, detail, remedy }, () => `${mode === 'block' ? 'BLOCKED' : 'WARNING'}  ${detail}\n         remedy: ${remedy}`, flags);
   return mode === 'block' ? EXIT.FAIL : EXIT.OK;
 }

package/src/commands/explain.mjs

@@ -46,7 +46,6 @@ export async function explainCommand(positional, flags) {
   }
   emit(
     [`code     ${code}`, '', row.what, '', `Why: ${row.why}`, '', `Fix: ${row.fix}`, '', `Example: ${row.example}`].join('\n'),
-    { maxBytes: flags.maxBytes ?? 0 },
   );
   return EXIT.OK;
 }

package/src/commands/gate.mjs

@@ -7,22 +7,26 @@
 
 import { execFile } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { promisify } from 'node:util';
 
-import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { EXIT, emit, emitJson, fail, isJson, present } 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 { langOf, packageOf } from '../index/store.mjs';
 import { localRel } from '../state.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 const exec = promisify(execFile);
 
+/** How many raw gate logs the state directory keeps. */
+const RAW_LOG_KEEP = 5;
+
 export async function gateCommand(args, flags) {
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   const listed = await tracked(root);
   if (listed.error) return listed.error;
   let changed = args.filter(Boolean);
@@ -38,10 +42,9 @@ export async function gateCommand(args, flags) {
       if (isJson(flags)) {
         emitJson(
           { ok: true, command: 'gate', root, selected: [], unmatched: [], graph: 'resolved', verdict: 'nothing-selected', code: 0 },
-          { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 },
         );
       } else {
-        emit('selected  0\nverdict  nothing-selected', { maxBytes: flags.maxBytes ?? 0 });
+        emit('selected  0\nverdict  nothing-selected');
       }
       return EXIT.OK;
     }
@@ -74,13 +77,13 @@ export async function gateCommand(args, flags) {
   if (selected.length === 0) {
     const payload = { ok: true, command: 'gate', root, selected, unmatched, graph, verdict: 'nothing-selected', code: 0 };
     if (isJson(flags)) {
-      emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+      emitJson(payload);
       return EXIT.OK;
     }
     const lines = ['selected  0', 'verdict  nothing-selected'];
     if (unmatched.length > 0) lines.push(`unmatched  ${unmatched.join(', ')}`);
     if (graph === 'unresolved') lines.push('graph  unresolved');
-    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    emit(lines.join('\n'));
     return EXIT.OK;
   }
   return runSelected(root, flags, selected, { unmatched, graph });
@@ -170,11 +173,7 @@ async function runSelected(root, flags, selected, { unmatched = [], graph = 'res
     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 });
+  present(payload, () => text.filter((line) => line !== undefined).join('\n'), flags);
   return code === 0 ? EXIT.OK : EXIT.FAIL;
 }
 
@@ -185,6 +184,11 @@ async function writeRaw(root, body) {
     const dir = join(root, dirname(rel));
     await mkdir(dir, { recursive: true });
     await writeFile(join(root, rel), body);
+    // Keep the newest few: raw gate output is machine-local state (Q19), and a file per
+    // run with no bound is a directory that grows on every command (Q83).
+    const kept = await readdir(dir).catch(() => []);
+    const logs = kept.filter((name) => /^gate-\d+\.log$/.test(name)).sort().reverse();
+    for (const name of logs.slice(RAW_LOG_KEEP)) await unlink(join(dir, name)).catch(() => {});
     return rel;
   } catch {
     return '';

package/src/commands/graph.mjs

@@ -71,7 +71,6 @@ export async function lintCommand(positional, flags) {
         errors,
         warnings,
       },
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     return finalOk ? EXIT.OK : EXIT.REGISTRY;
   }
@@ -109,11 +108,11 @@ export async function lintCommand(positional, flags) {
   if (errors.length > 0) {
     lines.push('', `FAIL ${errors.length}`);
     for (const error of errors) lines.push(`  ${error}`);
-    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    emit(lines.join('\n'));
     return EXIT.REGISTRY;
   }
 
   lines.push('', verified ? 'OK no findings' : 'OK structural checks only');
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }

package/src/commands/harness.mjs

@@ -27,6 +27,7 @@ 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';
+import { commandRoot } from '../repo-root.mjs';
 
 /**
  * `simt harness detect`. The subcommand is validated by dispatch, which rejects a
@@ -39,7 +40,7 @@ import { viewAll } from '../measure/loaderView.mjs';
  * @returns {Promise<number>} process exit code
  */
 export async function harnessCommand(positional, flags) {
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
 
   // MCP evidence is project-scope by construction: the loader table carries repo-root
   // paths (.mcp.json, .codex/config.toml, …), and the same path means different scopes
@@ -256,7 +257,7 @@ function block(scan, pad) {
  * do" in a repository where the answer is not about bytes.
  */
 export async function harnessLoadersCommand(positional, flags) {
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   const wanted = typeof flags.reader === 'string' ? flags.reader : null;
   const rows = wanted === null ? LOADERS : [loader(wanted)].filter(Boolean);
 

package/src/commands/help.mjs

@@ -1,4 +1,5 @@
-import { emit, fail, jsonFailMode } from '../output/index.mjs';
+import { emit, emitJson, fail, jsonFailMode } from '../output/index.mjs';
+import { SPEC, SPEC_PATHS, tierOf } from './spec.mjs';
 import { parse, rawJsonFlag } from '../argv.mjs';
 import { CLI, MANIFEST_FILE, STATE_DIR } from '../name.mjs';
 import { SESSION_ENV } from '../agenthooks/policy.mjs';
@@ -145,7 +146,7 @@ ${CLI} lessons list            deterministic lesson candidates in .simt/local/le
                            and promoted lessons in docs/lessons/*.md (reads nothing else)
 ${CLI} lessons capture         scan the ledger and git history for new candidates (the write half of list)
 ${CLI} lessons review [<id>]   promote a lesson candidate to docs/lessons/NNNN-<slug>.md
-                           (dry-run unless --yes; writes Appendix A frontmatter)
+                           (dry-run unless --yes; writes the lesson frontmatter)
 ${CLI} explain <CODE>        what a check finding means: the decision behind it, how
                            to fix it, and a concrete trigger (DRIFT, UNMANAGED,
                            PACK-DIGEST-MISMATCH, ...; case-insensitive)
@@ -168,7 +169,7 @@ ${CLI} distill <skill|doc>     a budgeted proposal summary of a skill body or do
                            from the configured chat model instead; the cache is
                            keyed by source digest and budget, --refresh regenerates)
 ${CLI} review [--local]        an ADR-008 verdict skeleton for the staged diff,
-                           the brief listing everything that governs it (R25)
+                           the brief listing everything that governs it
                            (deterministic without --local: the brief and its
                            governing ids only; --local proposes from the
                            configured chat model and writes
@@ -219,6 +220,16 @@ ${CLI} bench critic          precision and recall of the local critic over a lab
                             overrides --labels; labels are human-written verdicts
                             under ADR-008; the critic is advisory until precision
                             reaches 0.8 on 30 labelled diffs)
+${CLI} bench export <file> [--yes]
+                            sealed export of the mined corpus: every task
+                            descriptor and both hidden patches in one signed
+                            JSON file, for import on another machine
+                            (dry-run unless --yes; --root selects the repository)
+${CLI} bench import <file> [--yes]
+                            import a sealed corpus: verify the seal, then write
+                            the task descriptors and hidden patches into the
+                            repository's vault (dry-run unless --yes; --root
+                            selects the repository)
 ${CLI} pack new <name> --source <spec>
                            scaffold a versioned pack: pack.json, an unmeasured
                            bench.json, and one stack rule (dry-run unless --yes;
@@ -322,8 +333,14 @@ const FLAGS = `--json                 structured output (compact; one document,
 --embed                 index / map / brief: compute or query optional local vector embeddings
                         (off by default unless recall@10 gains at least 10 points)
 --labels <path>         bench critic: the labelled set of historical diffs to score
+--cross-group           bench ablate: compare across harness, model and experiment
+                        groups instead of refusing the comparison
+--expires <when>        lessons capture: how long a captured candidate stays eligible
                         (default .simt/critic-labels.jsonl; one human-written
                         {sha, verdict} pair per line)
+--replace               bench mine: delete task files the current mine does not
+                        reproduce (off by default: mining is append-only; a
+                        re-mine adds, it does not replace the corpus)
 --refresh               distill / review: regenerate a proposal that is already cached
 --local                 distill / review: propose the answer from the configured
                          local chat model (local.chat); off by default, which
@@ -338,17 +355,69 @@ const PRINCIPLES = `design rules:
   zero dependencies   a DX tool that needs an install step fails on a fresh machine
   bounded output      one fact per line, fixed field order, explicit TRUNCATED lines`;
 
-export async function help(argv) {
-  const parsed = parse(argv);
+export async function help(argv, dispatched) {
+  // `dispatched` is what `dispatch` already parsed. Called from a test or another
+  // command with only argv, help parses it itself.
+  const parsed =
+    dispatched === undefined
+      ? parse(argv)
+      : dispatched.parseError === undefined
+        ? { ok: true, value: { flags: dispatched.flags, positional: dispatched.positional } }
+        : { ok: false, error: dispatched.parseError };
   if (!parsed.ok) {
     jsonFailMode(rawJsonFlag(argv));
     return fail(parsed.error.message, parsed.error.code);
   }
-  const { flags } = parsed.value;
+  const { flags, positional } = parsed.value;
   if (flags.version) {
     emit((await version()).trim());
     return 0;
   }
+  // A reader who names one command gets that command, not the whole surface (review
+  // 0003 Q61): `simt help gate` and `simt gate --help` both printed 23 KB, so the one
+  // fact being asked for was 40 screens down.
+  const asked = commandFromHelp(positional);
+  if (asked !== null) {
+    emit(commandPage(asked));
+    return 0;
+  }
+  if (flags.json === true) {
+    emitJson(SPEC.map(specRow));
+    return 0;
+  }
+  // `--all` prints every command and every flag; the default page lists the core tier and
+  // says where the rest is. A reader asking "what can this do" needs the shape, not 23 KB
+  // of flag reference (review 0003 Q61).
+  if (flags.all === true) {
+    emit(
+      [
+        'simt-dev - shared agent rules, skills and gates for a repo ecosystem',
+        '',
+        `usage: ${CLI} <command> [args] [flags]`,
+        '',
+        'commands:',
+        COMMANDS,
+        '',
+        'flags:',
+        FLAGS,
+        '',
+        PRINCIPLES,
+        '',
+        `rulings  ${CLI} rules list   the decisions behind the rules you just read`,
+      ].join('\n'),
+    );
+    return 0;
+  }
+  // One line per group and one per bare command: listing every subcommand with its
+  // summary does not fit in the 2 KB a reader will actually read (review 0003 Q61).
+  const groups = new Map();
+  const bare = [];
+  for (const row of SPEC) {
+    if (tierOf(row.path) !== 'core') continue;
+    const [head, sub] = row.path.split(' ');
+    if (sub === undefined) bare.push(row);
+    else groups.set(head, [...(groups.get(head) ?? []), sub]);
+  }
   emit(
     [
       'simt-dev - shared agent rules, skills and gates for a repo ecosystem',
@@ -356,19 +425,12 @@ export async function help(argv) {
       `usage: ${CLI} <command> [args] [flags]`,
       '',
       'commands:',
-      COMMANDS,
-      '',
-      'flags:',
-      FLAGS,
+      ...[...groups].map(([group, subs]) => `  ${CLI} ${group} <${subs.join('|')}>`),
+      ...bare.map((row) => `  ${CLI} ${row.path.padEnd(8)} ${row.summary.length > 46 ? `${row.summary.slice(0, 43)}...` : row.summary}`),
       '',
-      PRINCIPLES,
-      '',
-      // The plans ship inside the installed package but have no command that surfaces
-      // them, so naming the path would again be advice the reader cannot take. They
-      // are an implementation record; the rulings are the part a reader can act on.
-      `rulings  ${CLI} rules list   the decisions behind the rules you just read`,
+      `more      ${CLI} help --all (every command and flag), ${CLI} help <command>`,
+      `rulings   ${CLI} rules list (the decisions behind the rules)`,
     ].join('\n'),
-    { maxBytes: flags.maxBytes ?? 0 },
   );
   return 0;
 }
@@ -377,3 +439,49 @@ async function version() {
   const { describeVersion } = await import('../package-version.mjs');
   return `${describeVersion()}\n`;
 }
+
+/** The command a help request names, or null when it names none. */
+function commandFromHelp(positional) {
+  const words = positional[0] === 'help' ? positional.slice(1) : positional;
+  const two = words.slice(0, 2).join(' ');
+  if (SPEC_PATHS.includes(two)) return two;
+  return SPEC_PATHS.includes(words[0]) ? words[0] : null;
+}
+
+/** One spec row as the JSON a UI or a harness reads. */
+function specRow(row) {
+  return { path: row.path, summary: row.summary, ...(row.defaultFor === undefined ? {} : { defaultFor: row.defaultFor }) };
+}
+
+const PAGE_WIDTH = 78;
+
+/** The summary broken to the page width, so a narrow terminal keeps it readable. */
+function wrapped(text) {
+  const lines = [];
+  let line = '';
+  for (const word of text.split(' ')) {
+    if (line !== '' && line.length + 1 + word.length > PAGE_WIDTH) {
+      lines.push(line);
+      line = word;
+    } else {
+      line = line === '' ? word : `${line} ${word}`;
+    }
+  }
+  if (line !== '') lines.push(line);
+  return lines;
+}
+
+/**
+ * One command's page: what it is, and where the rest of the answers are. The flags a
+ * single command declares arrive with the spec's `flags` field (Q62); until then the
+ * page points at the global list rather than inventing one per command.
+ */
+export function commandPage(path) {
+  const row = SPEC.find((r) => r.path === path);
+  if (row === undefined) return '';
+  const lines = [`${CLI} ${path} [args] [flags]`, '', ...wrapped(row.summary), ''];
+  if (row.defaultFor !== undefined) lines.push(`default  ${CLI} ${row.defaultFor} runs this command`);
+  lines.push(`flags    --json --pretty --root --max-bytes, and every global flag`);
+  lines.push(`all      ${CLI} --help   every command, and every flag it takes`);
+  return `${lines.join('\n')}\n`;
+}