simt-dev 0.6.3 → 0.7.1

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';
@@ -47,6 +48,7 @@ ${CLI} rules list             the rule catalogue (--root marks what applies to a
 ${CLI} rules show <id>        one rule body
 ${CLI} rules why <id|ADR-NNN> the decision that settled it, and whether it is still in force
                            (--all prints every ruling, not the first two)
+${CLI} rules decisions       every known decision, shipped and repo, and which layer each came from
 ${CLI} hooks install [--yes]   install the shared dispatcher; report what it would run
                            (dry-run unless --yes; refuses to take over routing git
                             already uses, and --yes is that consent)
@@ -58,11 +60,16 @@ ${CLI} agent-hook <event>      the entry point a harness calls: pre-tool-use dec
                            (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
+                            read a hooks file (--harness <id> writes one, not all)
                            (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} plugin <claude|gemini|cursor>  generate a harness package from the same tables
+${CLI} agents install          write the Simt-Agent into the harnesses that read an
+                            agents file (--harness <id> writes one, not all; dry-run
+                            unless --yes; markdown with a frontmatter the harness
+                            documents, TOML for Codex)
+${CLI} agents status           what each harness carries, and what is not installed yet
+${CLI} plugin <claude|gemini|cursor|opencode>  generate a harness package from the same tables
                            (dry-run unless --yes; writes a self-contained runtime, the
                            hooks and MCP registration, and for cursor the kernel rules;
                            the skill registry is workspace data and is not shipped)
@@ -77,17 +84,24 @@ ${CLI} plan status             count tracker rows
 ${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} slice start <id>     give a slice its own worktree and branch, preload the
-                           brief, and mark the row In progress (dry-run unless
-                           --yes; the worktree is ${STATE_DIR}/worktrees/<id> on
-                           branch slice/<id>, the brief ${STATE_DIR}/brief.md in it)
+                           brief, and mark the row started (dry-run unless
+                           --yes; the worktree is ${STATE_DIR}/local/worktrees/<id>
+                           on branch slice/<id>, the brief ${STATE_DIR}/local/briefs/<id>.md
+                           beside it; --session <id> leases the slice)
 ${CLI} slice finish <id>    run the pre-commit gates, commit what is staged with a
                            Conventional subject from the row's title, then record
                            the SHA and the --test command on the row (dry-run
-                           unless --yes; --type picks the type, default feat)
+                           unless --yes; --type picks the type, default feat;
+                           refuses unless HEAD is the slice branch; gates the
+                           ledger already proves for this tree are not re-run)
+${CLI} slice abandon <id>   remove the worktree, delete the branch, and return
+                           the row to ready (dry-run unless --yes; refuses from
+                           inside the worktree)
 ${CLI} lease [<paths>...]    claim files for one session and a TTL, or list the
                            claims (dry-run unless --yes; the session is --session
                            <id> or ${SESSION_ENV}; a pre-edit hook refuses an edit
-                           to a path another session holds — ADR-101)
+                           to a path another session holds — ADR-101;
+                           release and renew end and extend your own claims)
 ${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
@@ -100,7 +114,8 @@ ${CLI} ignore [--yes]         render the one .simtignore list into .cursorignore
                            Claude settings file is merged, never replaced)
 ${CLI} compare                org-wide matrix across every sibling repo
                            (read-only; exits non-zero on defects, not on
-                           repos that have not adopted yet)
+                           repos that have not adopted yet;
+                           --concurrency <n> caps the rows built at once)
 ${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
@@ -127,10 +142,11 @@ ${CLI} pr-body [--base <ref>]  a pull request body: the evidence block for this
 ${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} lessons list            deterministic lesson candidates in .simt/lessons.jsonl
-                           and promoted lessons in docs/lessons/*.md
+${CLI} lessons list            deterministic lesson candidates in .simt/local/lessons.jsonl
+                           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)
@@ -147,17 +163,17 @@ ${CLI} local doctor            probe configured local model endpoints (chat and
                            unset; refuses non-loopback URLs without --allow-remote)
 ${CLI} distill <skill|doc>     a budgeted proposal summary of a skill body or doc,
                            every claim citing the source line range it rests on
-                           (writes .simt/distilled/<digest>.md; a proposal a
+                           (writes .simt/local/distilled/<digest>.md; a proposal a
                            human merges - never projected or committed;
                            deterministic outline by default; --local proposes
                            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
-                           .simt/reviews/<digest>.md — a proposal a human
+                           .simt/local/reviews/<digest>.md — a proposal a human
                            reads, verified against the verdict vocabulary and
                            the brief's ids; advisory always, never a gate)
 ${CLI} shared plan            what a workspace's repeated rules cost to carry
@@ -197,13 +213,23 @@ ${CLI} bench probes [--yes]    12 synthetic rule-compliance probes with determin
                             (dry-run unless --yes; grades git state, transcript and ledger,
                             and reports compliance per arm)
 ${CLI} bench variants [--yes]  evaluate simt-variants rule slots on the canary suite and lock
-                            winning variants in simt-dev.lock.json (dry-run unless --yes;
+                            winning variants in simt.lock.json (dry-run unless --yes;
                             re-opens when model or harness changes)
 ${CLI} bench critic          precision and recall of the local critic over a labelled
-                            set of historical diffs (.simt/critic-labels.jsonl;
+                            set of historical diffs (.simt/local/critic-labels.jsonl;
                             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;
@@ -240,6 +266,12 @@ const FLAGS = `--json                 structured output (compact; one document,
 --workspace <path>      where the skill sources live; "off" declines it
                         (default: SIMT_DEV_WORKSPACE, then the user config
                         file, then the sibling heuristic if it verifies)
+--registry <path>       which skill registry to read (skills commands and
+                        graph lint; default: SIMT_REGISTRY, then the checkout's
+                        own graph/skills.graph.json, then the one member of the
+                        workspace that holds one)
+--concurrency <n>       compare: rows built at once (default 4, or
+                        SIMT_CONCURRENCY; order-preserving whatever it is)
 --dry-run               report what would change, change nothing
 --yes                   assume yes; required in automation, never prompts
 --check                 report drift and write nothing (sync, ci)
@@ -301,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
@@ -317,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',
@@ -335,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;
 }
@@ -356,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`;
+}