simt-dev 0.6.2 → 0.7.0

package/src/commands/help.mjs

@@ -1,13 +1,18 @@
-import { emit } from '../output/index.mjs';
-import { parse } from '../argv.mjs';
-import { CLI, MANIFEST_FILE } from '../name.mjs';
+import { emit, fail, jsonFailMode } from '../output/index.mjs';
+import { parse, rawJsonFlag } from '../argv.mjs';
+import { CLI, MANIFEST_FILE, STATE_DIR } from '../name.mjs';
+import { SESSION_ENV } from '../agenthooks/policy.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
                            --accept-conflicts; in place unless --backup;
                            never commits or pushes)
-${CLI} doctor                 classify a repo and check config health
+${CLI} doctor [--fix]        classify a repo and check config health (with --fix:
+                           apply the remedies flagged safe and list the rest;
+                           dry-run unless --yes)
+${CLI} status --line         one line from the last check, for prompts and tmux
+                           (as of the last check; STALE after new commits)
 ${CLI} check                  the gate: projection drift, manifest validity, policy
 ${CLI} sync [--yes]           regenerate the projection (idempotent)
                            (prints the plan and exits 1 on drift without --yes,
@@ -42,6 +47,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)
@@ -53,28 +59,62 @@ ${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
-                            (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)
+${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)
+${CLI} completions <shell>    print a bash, zsh or fish completion script
+                           (generated from the command registry, so every command
+                           completes; deterministic bytes; stdout only - redirect
+                           or source it)
 ${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} slice start <id>     give a slice its own worktree and branch, preload the
+                           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;
+                           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;
+                           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
                            (dry-run unless --yes; refreshes the templates' own copies
                             and no repository else's)
+${CLI} ignore [--yes]         render the one .simtignore list into .cursorignore,
+                           .aiderignore, .geminiignore and Claude's
+                           permissions.deny Read(...) entries (dry-run unless
+                           --yes; --diff prints the plan as unified diffs; the
+                           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
@@ -93,23 +133,36 @@ ${CLI} map [--task "<text>"] [--level outline|names|signatures]
                            --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} pr-body [--base <ref>]  a pull request body: the evidence block for this tree,
+                           the decision records the diff touches, the gate
+                           state from the last check, and the residual risk
+                           in ADR-008 vocabulary (read-only; the exit code
+                           never carries the verdict)
 ${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)
+${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)
 ${CLI} decide [<title>]        scaffold an ADR with the next free number, a Status: line,
                            a rulings skeleton, and structured simt-affects +
                            simt-supersedes frontmatter (dry-run unless --yes;
                            --check lints ADRs for prose-only partial supersessions)
+${CLI} undo                  restore the last journaled set of writes, but only
+                           when every file in it is untouched since (dry-run
+                           unless --yes; a touched file refuses the whole undo
+                           and nothing is restored)
 ${CLI} local doctor            probe configured local model endpoints (chat and embed)
                            (reads local in ${MANIFEST_FILE}; opens no socket when
                            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
@@ -119,7 +172,7 @@ ${CLI} review [--local]        an ADR-008 verdict skeleton for the staged diff,
                            (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
@@ -159,10 +212,10 @@ ${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)
@@ -192,6 +245,9 @@ const FLAGS = `--json                 structured output (compact; one document,
 --task "<text>"         the task text used for capability resolution
 --paths <globs>         comma-separated path globs used for path resolution
 --root <path>           repository root (default: cwd)
+--base <ref>           pr-body: the ref the body diffs against
+                        (default: origin/main, then main; falls back to the
+                        worktree diff against HEAD when neither exists)
 --out <path>            plugin: where the generated package lands (required)
 --surfaces <ids>        comma-separated editors to write rule files for;
                          "" means AGENTS.md only (default: every surface,
@@ -199,9 +255,22 @@ 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)
+--diff                  print the plan as unified diffs (every writer;
+                        changes nothing about what the run writes)
+--line                  status: print the one-line gate summary from the last
+                        check (the only mode status has)
+--fix                   doctor: apply the remedies flagged safe (local,
+                        idempotent, journaled); list the rest (dry-run
+                        unless --yes)
 --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
@@ -238,8 +307,10 @@ const FLAGS = `--json                 structured output (compact; one document,
 --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
+--test <cmd>            plan done / slice finish: the test command that closes the row
 --state <name>          plan done: target state (default: Complete)
+--type <name>           slice finish: the Conventional Commits type (default: feat)
+--ttl <seconds>         lease: how long a claim lasts (default: 3600)
 --level <name>          map: detail level (outline, names, signatures)
 --supersedes <spec>     decide: superseded ADR or ruling (ADR-NNN or ADR-NNN:<ruling>[:<kind>]; repeatable)
 --source <spec>         pack new: where the pack's bytes come from
@@ -268,9 +339,12 @@ const PRINCIPLES = `design rules:
   bounded output      one fact per line, fixed field order, explicit TRUNCATED lines`;
 
 export async function help(argv) {
-  const { ok, value } = parse(argv);
-  if (!ok) return value.code;
-  const { flags } = value;
+  const parsed = parse(argv);
+  if (!parsed.ok) {
+    jsonFailMode(rawJsonFlag(argv));
+    return fail(parsed.error.message, parsed.error.code);
+  }
+  const { flags } = parsed.value;
   if (flags.version) {
     emit((await version()).trim());
     return 0;
@@ -300,10 +374,6 @@ export async function help(argv) {
 }
 
 async function version() {
-  const { readFile } = await import('node:fs/promises');
-  const { fileURLToPath } = await import('node:url');
-  const { dirname, join } = await import('node:path');
-  const root = join(dirname(fileURLToPath(import.meta.url)), '..');
-  const pkg = JSON.parse(await readFile(join(root, '..', 'package.json'), 'utf8'));
-  return `simt-dev ${pkg.version}\n`;
+  const { describeVersion } = await import('../package-version.mjs');
+  return `${describeVersion()}\n`;
 }