simt-dev 0.3.1 → 0.4.0

package/src/commands/agenthook.mjs

@@ -11,6 +11,12 @@
 // walks the repository. A hook that measured the tree before answering would be exactly
 // the latency the plan's acceptance criterion exists to prevent.
 //
+// A second event, `prompt-submit`, delivers rather than decides: it needs the manifest,
+// the index and the packet assembly, so it is reached through a dynamic `import()` that
+// only that event takes. A tool call therefore still pays for nothing that walks the
+// repository, and the one path that does pays for it once per prompt instead of once per
+// command.
+//
 // A denial exits 2, which is what every harness in the table reads as "block". A mistake
 // in the hook's own invocation must NOT exit 2: a typo in a config would then block every
 // tool call. Failures of this command exit 1, which a harness reports as a failed hook,
@@ -60,6 +66,32 @@ export async function agentHookCommand(args, flags) {
     return EXIT.OK;
   }
 
+  // Delivery, not decision: the packet goes into the prompt and the exit code stays 0
+  // whatever happens. The module behind it is the one thing here that reads the
+  // repository, and the tool-call path above must not pay for it, so the door is a
+  // dynamic import that only this event opens.
+  if (event === 'prompt-submit') {
+    const { deliverPrompt } = await import('../agenthooks/prompt.mjs');
+    const delivered = await deliverPrompt(row, payload);
+    if (delivered.skipped) {
+      note(`note     ${id}: no packet delivered (${delivered.skipped})`);
+      return EXIT.OK;
+    }
+    emit(JSON.stringify(delivered.json));
+    return EXIT.OK;
+  }
+
+  if (event === 'post-tool-use') {
+    const { deliverLessonRecall } = await import('../memory/lessons.mjs');
+    const recalled = await deliverLessonRecall(row, payload, { root: flags.root });
+    if (recalled.skipped) {
+      note(`note     ${id}: no lesson recalled (${recalled.skipped})`);
+      return EXIT.OK;
+    }
+    emit(JSON.stringify(recalled.json));
+    return EXIT.OK;
+  }
+
   const { root, command, writes } = factsFrom(row, payload);
   const facts = await factsFor(root, { command, writes });
   const decision = decide({ event, facts, env: process.env });
@@ -77,6 +109,22 @@ export async function agentHookCommand(args, flags) {
   const json = decisionJson(row, decision);
   if (json === null) return EXIT.OK;
 
+  if (root) {
+    try {
+      const { recordHookDenial } = await import('../memory/lessons.mjs');
+      await recordHookDenial(root, {
+        harness: row.id,
+        event,
+        policies: decision.blocked,
+        messages: decision.messages,
+        command,
+        writes,
+      });
+    } catch {
+      // Recording a lesson candidate must never block or alter the hook decision.
+    }
+  }
+
   emit(JSON.stringify(json));
   for (const message of decision.messages) note(`blocked  ${message}`);
   return row.denyExit;
@@ -91,14 +139,37 @@ export async function agentHooksCommand(sub, args, flags) {
 
 async function installHooks(root, flags) {
   const mode = writeMode(flags);
+  // The delivery is a second entry in the same config, and a repository asks for it by
+  // declaring a `brief` key rather than by having the entry. Read through a dynamic
+  // import for the same reason the hook delivers through one.
+  const { promptOptIn } = await import('../agenthooks/prompt.mjs');
+  const { listPromotedLessons } = await import('../memory/lessons.mjs');
+  const [optIn, promotedLessons] = await Promise.all([
+    promptOptIn(root),
+    listPromotedLessons(root).catch(() => []),
+  ]);
+  const hasLessons = promotedLessons.length > 0;
   const plan = [];
   for (const row of adapters()) {
     const path = hookPath(row.id);
     const existing = await readIfExists(join(root, path));
-    const result = rendered(row, existing);
-    plan.push({ id: row.id, path, action: result.error ? 'refused' : result.action, error: result.error, text: result.text });
+    const result = rendered(row, existing, { prompt: optIn.optedIn, post: hasLessons });
+    plan.push({
+      id: row.id,
+      path,
+      action: result.error ? 'refused' : result.action,
+      error: result.error,
+      text: result.text,
+      prompt: row.prompt === null || row.prompt === undefined ? null : optIn.optedIn ? 'declared' : 'not declared',
+    });
   }
 
+  // One line for the repository, not one per adapter: the opt-in is a property of the
+  // repository, and someone who has not declared it is told how once.
+  const promptLine = plan.some((p) => p.prompt !== null) && !optIn.optedIn
+    ? [`PROMPT   not opted in (${optIn.why}); add "brief": {} to the manifest to deliver the packet on every prompt`]
+    : [];
+
   // The readers this tool does not write an entry for, reported rather than skipped in
   // silence: a command that writes four files and says nothing about the fifth harness
   // in the repository reads as "that one is covered too".
@@ -128,6 +199,7 @@ async function installHooks(root, flags) {
         `repo     ${root}`,
         ...plan.map((p) => `${p.action.toUpperCase().padEnd(9)} ${p.id.padEnd(12)} ${p.path}${p.error ? `  (${p.error})` : ''}`),
         ...others.map((o) => `${o.state === 'none' ? 'NO FILE ' : 'NOT OURS'} ${o.id.padEnd(12)} ${o.path ?? '(no hooks file is documented)'}`),
+        ...promptLine,
         '',
         refused.length > 0
           ? `REFUSED  ${refused.length} config file(s) could not be read; nothing written`
@@ -177,6 +249,7 @@ async function installHooks(root, flags) {
       `repo     ${root}`,
       ...plan.map((p) => `${p.action.toUpperCase().padEnd(9)} ${p.id.padEnd(12)} ${p.path}`),
       ...others.map((o) => `${o.state === 'none' ? 'NO FILE ' : 'NOT OURS'} ${o.id.padEnd(12)} ${o.path ?? '(no hooks file is documented)'}`),
+      ...promptLine,
       '',
       `WROTE    ${written.length} hooks file(s); each one runs ${CLI} agent-hook before the tool call`,
     ].join('\n'),
@@ -196,14 +269,14 @@ async function hooksStatus(root, flags) {
     const path = hookPath(row.id);
     const existing = await readIfExists(join(root, path));
     if (existing === null) {
-      rows.push({ id: row.id, path, state: 'absent', entries: 0, note: null });
+      rows.push({ id: row.id, path, state: 'absent', entries: 0, prompt: row.prompt ? 'absent' : null, note: null });
       continue;
     }
     let config;
     try {
       config = JSON.parse(existing);
     } catch (e) {
-      rows.push({ id: row.id, path, state: 'unreadable', entries: 0, note: e.message });
+      rows.push({ id: row.id, path, state: 'unreadable', entries: 0, prompt: row.prompt ? 'unknown' : null, note: e.message });
       problems.push(`${path} is not valid JSON: ${e.message}`);
       continue;
     }
@@ -211,16 +284,18 @@ async function hooksStatus(root, flags) {
     // refuses to write into one. Status has to agree with it, or one question gets two
     // answers and the quiet one is the one a reader acts on.
     if (config === null || typeof config !== 'object' || Array.isArray(config)) {
-      rows.push({ id: row.id, path, state: 'unreadable', entries: 0, note: 'not a JSON object' });
+      rows.push({ id: row.id, path, state: 'unreadable', entries: 0, prompt: row.prompt ? 'unknown' : null, note: 'not a JSON object' });
       problems.push(`${path} is not a JSON object, so this tool will not write into it`);
       continue;
     }
     const found = installedIn(row, config).length;
+    const prompts = row.prompt ? installedIn(row, config, EVENTS[1]).length : 0;
     rows.push({
       id: row.id,
       path,
       state: found > 0 ? 'present' : 'absent',
       entries: found,
+      prompt: row.prompt ? (prompts > 0 ? 'present' : 'absent') : null,
       note: found > 0 ? (row.trust ?? null) : null,
     });
   }
@@ -243,6 +318,10 @@ async function hooksStatus(root, flags) {
     const state = { present: 'PRESENT ', absent: 'ABSENT  ', unreadable: 'INVALID ', none: 'NO FILE ', other: 'NOT OURS' }[r.state];
     lines.push(`${state} ${r.id.padEnd(12)} ${r.path ?? '(no hooks file is documented)'}`);
     if (r.state === 'absent') lines.push(`          ${' '.repeat(12)} install: ${CLI} agent-hooks install --yes`);
+    // The second event is a separate answer to a separate question: a harness can carry
+    // the tool hook and not the delivery, and a reader who is told "PRESENT" would
+    // otherwise conclude the packet arrives on every prompt.
+    if (r.prompt) lines.push(`          ${' '.repeat(12)} prompt-submit: ${r.prompt}`);
     if (r.note) lines.push(`          ${' '.repeat(12)} ${r.note}`);
   }
   if (problems.length > 0) {

package/src/commands/bench.mjs

@@ -15,6 +15,7 @@ import { buildBenchReport } from '../bench/report.mjs';
 import { formatRecall, measureRecall } from '../index/map.mjs';
 import { ablateBench } from '../bench/ablate.mjs';
 import { runBenchProbes } from '../bench/probes.mjs';
+import { selectRuleVariants } from '../bench/variants.mjs';
 import { listFlag } from './skills.mjs';
 
 export async function benchMineCommand(positional, flags) {
@@ -280,16 +281,8 @@ export async function benchAblateCommand(positional, flags) {
     emitJson({
       ok: true,
       command: 'bench ablate',
-      root: result.root,
       dryRun,
-      applied: result.applied,
-      pricesLoaded: result.pricesLoaded,
-      canarySize: result.canarySize,
-      canaryTasks: result.canaryTasks,
-      totalTasks: result.totalTasks,
-      sections: result.sections,
-      ranking: result.ranking,
-      deletionCandidates: result.deletionCandidates,
+      ...result,
     });
     return EXIT.OK;
   }
@@ -340,13 +333,8 @@ export async function benchProbesCommand(positional, flags) {
     emitJson({
       ok: true,
       command: 'bench probes',
-      root: result.root,
       dryRun,
-      applied: result.applied,
-      probeCount: result.probeCount,
-      probes: result.probes,
-      arms: result.arms,
-      runs: result.runs,
+      ...result,
     });
     return EXIT.OK;
   }
@@ -367,5 +355,42 @@ export async function benchProbesCommand(positional, flags) {
   return EXIT.OK;
 }
 
+export async function benchVariantsCommand(positional, flags) {
+  const root = resolve(flags.root ?? positional[0] ?? process.cwd());
+  const { dryRun, apply } = writeMode(flags);
+  let result;
+  try {
+    result = await selectRuleVariants(root, {
+      apply,
+      harness: flags.harness ?? 'gold',
+      model: flags.model,
+      reps: flags.reps ?? 1,
+      includeAll: flags.all === true,
+    });
+  } catch (error) {
+    return fail(
+      `${root}: ${error.message ?? error}`,
+      EXIT.CONFIG,
+      `mine tasks first with \`${CLI} bench mine --yes\` and rerun \`${CLI} bench variants --yes\``,
+    );
+  }
+  if (isJson(flags)) {
+    emitJson({ ok: true, command: 'bench variants', dryRun, ...result });
+    return EXIT.OK;
+  }
+  const lines = [
+    `bench    variants  ${result.root}`,
+    `mode     ${result.applied ? 'applied' : dryRun ? 'dry-run (writes nothing)' : 'preview / stored runs (pass --yes to execute canary and lock winners)'}`,
+    `harness  ${result.harness}  model=${result.model}`,
+    `slots    ${result.slots.length}  (canary: ${result.canaryTasks}/${result.totalTasks} tasks)`,
+    ...result.slots.map(
+      (s) => `slot     ${s.slotId}  status=${s.status}  winner=${s.winner}  dR=${s.dR}  dC=${s.dC}  n=${s.n}  p=${s.p}`,
+    ),
+  ];
+  if (!result.applied) lines.push(`remedy   run: ${CLI} bench variants --yes`);
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
 
 

package/src/commands/brief.mjs

@@ -0,0 +1,78 @@
+// `simt brief "<task>"` — print the packet (plan 0003 R27).
+//
+// What this is for: an agent that has to explore a repository to find out how to run its
+// tests, which files the task will touch and what governs them spends turns discovering
+// what the repository already knows. The packet is that answer, assembled from the index
+// the repository already has, in the bytes a prompt can carry.
+//
+// The assembly itself is in `../brief/assemble.mjs`, because three doors open onto it —
+// this command, MCP's `brief` tool and the prompt-submit hook — and one implementation
+// behind three doors is the only way the three cannot disagree. This file owns the
+// command line: what a task may be, what the ceiling may be, and how the packet is
+// rendered for a terminal or for `--json`.
+//
+// One thing is deliberately missing: `skills brief` keeps its own behaviour, and MCP's
+// `skills_brief` keeps its own shape. Superseding them changes two accepted decisions
+// (ADR-035, ADR-052) and the MCP contract, and this slice carries no ADR to do it.
+
+import { CLI } from '../name.mjs';
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { DEFAULT_BRIEF_BYTES, explainPacket } from '../brief/packet.mjs';
+import { assembleBrief } from '../brief/assemble.mjs';
+
+export async function briefCommand(args, flags) {
+  if (args.length > 1) {
+    return fail(`brief takes one task, not ${args.length}`, EXIT.USAGE, `run: ${CLI} brief "<task>"`);
+  }
+  if (args.length === 1 && flags.task !== undefined) {
+    return fail('the task was passed twice, as an argument and as --task', EXIT.USAGE, `run: ${CLI} brief "<task>"`);
+  }
+  const budget = flags.budget === undefined ? DEFAULT_BRIEF_BYTES : Number(flags.budget);
+  if (!Number.isInteger(budget) || budget < 0) {
+    return fail(`--budget must be a byte count, not ${flags.budget}`, EXIT.USAGE, `run: ${CLI} brief --budget ${DEFAULT_BRIEF_BYTES}`);
+  }
+
+  const result = await assembleBrief({
+    root: flags.root ?? process.cwd(),
+    task: String(args[0] ?? flags.task ?? ''),
+    paths: flags.paths === undefined ? null : flags.paths,
+    budget,
+    flags,
+  });
+  if (result.error) return result.error;
+  // Unreachable from here — only a delivered brief asks for a cold index to be reported
+  // rather than built — but a silent empty packet would be the worst way to find out.
+  if (result.cold) {
+    return fail('the index is empty, and this command will not assemble a packet from it', EXIT.UNSUPPORTED, `run ${CLI} index`);
+  }
+  const { root, kind, basis, task, scope, budget: ceiling, items, packed, sections } = result;
+  const cut = new Set(packed.cut);
+
+  if (isJson(flags)) {
+    emitJson(
+      {
+        ok: true,
+        command: 'brief',
+        root,
+        kind,
+        basis,
+        task,
+        scope,
+        budget: ceiling,
+        bytes: packed.after,
+        before: packed.before,
+        floorHeld: packed.floorHeld,
+        cut: packed.cut,
+        sections,
+        explain: flags.explain === true ? explainPacket(items, { cut }) : undefined,
+        text: packed.text,
+      },
+      { pretty: flags.pretty === true, maxBytes: Number(flags.maxBytes ?? 0) || 0 },
+    );
+    return EXIT.OK;
+  }
+
+  const body = flags.explain === true ? [packed.text, '', 'EXPLAIN', ...explainPacket(items, { cut })] : [packed.text];
+  emit(body.join('\n'), { maxBytes: Number(flags.maxBytes ?? 0) || 0 });
+  return EXIT.OK;
+}

package/src/commands/compare.mjs

@@ -26,6 +26,7 @@ import { provenanceDigest } from '../projection/project.mjs';
 import { GATES } from '../hooks/gates.mjs';
 import { buildRow, summarise } from '../compare/row.mjs';
 import { discover } from '../compare/discover.mjs';
+import { learnAcrossEstate, renderLearningLines } from '../compare/learn.mjs';
 import { targetRoot, WORKSPACE_REMEDY } from '../workspace.mjs';
 
 /** Gate kinds, so a row can tell a command gate with no command from a script gate. */
@@ -65,6 +66,7 @@ export async function compareCommand(positional, flags) {
   // bound. Determinism of the output matters more than wall clock on a dashboard.
   const rows = [];
   for (const repo of found.repos) rows.push(await buildRow(repo, context));
+  const learning = await learnAcrossEstate(found.repos);
 
   const summary = summarise(rows, {
     root,
@@ -106,6 +108,7 @@ export async function compareCommand(positional, flags) {
         shas: summary.shas,
       },
       rows,
+      learning,
       worktrees: found.worktrees.map((w) => ({
         name: w.name,
         path: w.path,
@@ -117,7 +120,7 @@ export async function compareCommand(positional, flags) {
     return rows.some((r) => r.problems.length > 0) ? EXIT.FAIL : EXIT.OK;
   }
 
-  emit(render(rows, summary, found), { maxBytes: flags.maxBytes ?? 0 });
+  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') {
@@ -146,7 +149,7 @@ export async function compareCommand(positional, flags) {
  * the longest value, and an agent cannot tell which column is which without
  * counting spaces.
  */
-function render(rows, summary, found) {
+function render(rows, summary, found, learning = null) {
   const lines = [
     // `workspace` and `repo` are the same field with different names, and the name is the
     // honest one: a reader who sees "workspace" and gets one repo was told a lie. `root`
@@ -204,6 +207,11 @@ function render(rows, summary, found) {
     lines.push('');
   }
 
+  const learningLines = renderLearningLines(learning);
+  if (learningLines.length > 0) {
+    lines.push(...learningLines, '');
+  }
+
   return lines.join('\n').trimEnd();
 }
 

package/src/commands/decide.mjs

@@ -0,0 +1,116 @@
+// `simt decide` — scaffold an ADR with the next free number, a Status: line,
+// a rulings skeleton, and structured `simt-affects` + `simt-supersedes` frontmatter
+// (plan 0003 R34).
+
+import { join, resolve } from 'node:path';
+import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { DECISIONS_DIR } from '../decisions/index.mjs';
+import { lintDecisions, scaffoldDecision } from '../memory/decide.mjs';
+import { parsePathList } from '../argv.mjs';
+
+export async function decideCommand(args, flags) {
+  const root = flags.root ?? process.cwd();
+
+  if (flags.check === true) {
+    const decisionsDir = join(root, 'docs', 'decisions');
+    const allowHistorical = resolve(decisionsDir) === DECISIONS_DIR;
+    const res = await lintDecisions(decisionsDir, { allowHistorical });
+
+    if (isJson(flags)) {
+      emitJson({
+        ok: res.ok,
+        command: 'decide --check',
+        root,
+        findings: res.findings,
+      });
+      return res.ok ? EXIT.OK : EXIT.FAIL;
+    }
+
+    if (res.findings.length === 0) {
+      emit('decisions  ok', { maxBytes: flags.maxBytes ?? 0 });
+      return EXIT.OK;
+    }
+
+    emit(
+      res.findings
+        .flatMap((f) => [
+          `${f.status.toUpperCase()}  ${f.file}  ${f.detail}`,
+          ...(f.remedy ? [`  remedy: ${f.remedy}`] : []),
+        ])
+        .join('\n'),
+      { maxBytes: flags.maxBytes ?? 0 },
+    );
+    return EXIT.FAIL;
+  }
+
+  const mode = writeMode(flags);
+  const title = args.join(' ').trim() || flags.task || 'Untitled decision';
+  const parsedPaths = parsePathList(flags.paths);
+  const explicitPaths = flags.paths !== undefined ? parsedPaths : undefined;
+
+  const res = await scaffoldDecision(root, {
+    title,
+    affects: explicitPaths,
+    supersedes: flags.supersedes,
+    write: mode.apply,
+  });
+
+  if (!res.ok) {
+    return fail(
+      res.errors[0],
+      EXIT.USAGE,
+      `usage: ${CLI} decide "<title>" [--supersedes ADR-NNN:<ruling>] [--yes]`,
+    );
+  }
+
+  if (mode.apply) {
+    note(`wrote    ${res.relPath}`);
+  } else if (flags.dryRun === true) {
+    note('dry-run  no files written');
+  }
+
+  if (isJson(flags)) {
+    emitJson({
+      ok: true,
+      command: 'decide',
+      root,
+      id: res.id,
+      number: res.number,
+      title: res.title,
+      file: res.file,
+      path: res.relPath,
+      affects: res.affects,
+      supersedes: res.supersedes,
+      written: res.written,
+      dryRun: !mode.apply,
+    });
+    return EXIT.OK;
+  }
+
+  const supersedesLabel =
+    res.supersedes.length > 0
+      ? res.supersedes
+          .map((s) => (s.ruling !== null ? `${s.adr} ruling ${s.ruling} (${s.kind})` : s.adr))
+          .join('; ')
+      : '(none)';
+
+  const lines = [
+    `id          ${res.id}`,
+    `title       ${res.title}`,
+    `file        ${res.relPath}`,
+    `affects     ${res.affects.length > 0 ? res.affects.join(', ') : '(none)'}`,
+    `supersedes  ${supersedesLabel}`,
+    '',
+    res.text.trimEnd(),
+    '',
+    mode.apply
+      ? `wrote ${res.relPath}`
+      : flags.dryRun === true
+        ? 'dry-run; nothing written'
+        : `would write ${res.relPath}; apply with: ${CLI} decide ${JSON.stringify(res.title)} --yes`,
+  ];
+
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}

package/src/commands/help.mjs

@@ -16,6 +16,12 @@ ${CLI} upgrade                move every consumer to this simt-dev SHA, as one s
                            (dry-run unless --yes; moves a pin only - it never
                            adopts or repairs a repo; never commits or pushes)
 
+${CLI} brief "<task>"         one packet for a task: the kind, the commands, the
+                           likely files, the tests and the decisions that govern
+                           them, inside --budget bytes (default 2048; 0 is
+                           unlimited). Says how many items it cut; --explain
+                           says why each was kept or dropped
+
 ${CLI} skills index           tier-0 catalog: every skill, one line each
 ${CLI} skills brief --task    tier-1 pre-assembled brief  <- the common case
 ${CLI} skills show <name>     tier-2 body (respects --max-bytes)
@@ -28,6 +34,9 @@ ${CLI} skills eval [corpus]   measure the resolver against a gold corpus
 ${CLI} skills install <name>  pin a skill into the repo as a local override
                            (dry-run unless --yes; a multi-variant skill needs
                            --variant or --from rather than a guess)
+${CLI} skills compile [<name>] compile a skill to Agent Skills standard, flag bodies
+                           over 5000 tokens with a split plan, and report per-skill
+                           trigger recall and precision from R02 transcripts
 
 ${CLI} rules list             the rule catalogue (--root marks what applies to a repo)
 ${CLI} rules show <id>        one rule body
@@ -39,7 +48,8 @@ ${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
+${CLI} agent-hook <event>      the entry point a harness calls: pre-tool-use decides,
+                            prompt-submit delivers the packet as prompt context
                            (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
@@ -82,6 +92,17 @@ ${CLI} map [--task "<text>"] [--level outline|names|signatures]
 ${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-dev/lessons.jsonl
+                           and promoted lessons in docs/lessons/*.md
+${CLI} lessons review [<id>]   promote a lesson candidate to docs/lessons/NNNN-<slug>.md
+                           (dry-run unless --yes; writes Appendix A frontmatter)
+${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} 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} shared plan            what a workspace's repeated rules cost to carry
                            once: the shared set, its bytes, and every path that would be written
                            (read-only; touches nothing, not even your home directory)
@@ -117,6 +138,9 @@ ${CLI} bench ablate [--yes]    leave-one-out ablation across core, profile and p
 ${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} 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;
+                            re-opens when model or harness changes)
 ${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)`;
@@ -124,7 +148,8 @@ ${CLI} mcp                    the read-only surface as MCP tools over stdio
 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)
+--budget <n>            context budget for a brief (default 2048)
+                        (skills brief keeps its own default of 20480)
 --plan                  emit a fetch plan instead of inlining skill bodies
 --skill <name>          force a skill into the brief (repeatable)
 --task "<text>"         the task text used for capability resolution
@@ -142,7 +167,8 @@ const FLAGS = `--json                 structured output (compact; one document,
 --frozen                check: the lock must match this projection; an output
                         change no input change explains fails the gate
 --explain               sync: name each line dropped as already inferable, with
-                        the fact behind it
+                        the fact behind it; brief: name every item and why it
+                        was kept or cut, with its section's value
 --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
@@ -176,6 +202,11 @@ const FLAGS = `--json                 structured output (compact; one document,
 --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)
+--level <name>          map: detail level (outline, names, signatures)
+--supersedes <spec>     decide: superseded ADR or ruling (ADR-NNN or ADR-NNN:<ruling>[:<kind>]; repeatable)
+--allow-remote          local doctor: allow non-loopback model URLs (refused by default)
+--embed                 index / map / brief: compute or query optional local vector embeddings
+                        (off by default unless recall@10 gains at least 10 points)
 --help                  this text
 --version               the version, and the SHA it was built from`;
 

package/src/commands/index.mjs

@@ -25,6 +25,7 @@ import {
   whyCommand as skillsWhy,
   evalCommand as skillsEval,
 } from './skills.mjs';
+import { briefCommand } from './brief.mjs';
 import { syncCommand, checkCommand } from './sync.mjs';
 import { initCommand } from './init.mjs';
 import { ciCommand } from './ci.mjs';
@@ -34,6 +35,7 @@ import { compareCommand } from './compare.mjs';
 import { upgradeCommand } from './upgrade.mjs';
 import { mcpCommand } from './mcp.mjs';
 import { installCommand } from './skillsinstall.mjs';
+import { compileCommand } from './skillscompile.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';
@@ -43,6 +45,7 @@ import {
   benchReportCommand,
   benchAblateCommand,
   benchProbesCommand,
+  benchVariantsCommand,
 } from './bench.mjs';
 import { planCommand } from './plan.mjs';
 import { sharedPlanCommand, sharedInstallCommand, sharedWarning } from './shared.mjs';
@@ -53,7 +56,11 @@ import { testsCommand } from './tests.mjs';
 import { whyCommand } from './why.mjs';
 import { gateCommand } from './gate.mjs';
 import { impactCommand } from './impact.mjs';
+import { lessonsListCommand, lessonsReviewCommand } from './lessons.mjs';
+import { decideCommand } from './decide.mjs';
+import { localDoctorCommand } from './local.mjs';
 import { parse } from '../argv.mjs';
+import { CLI } from '../name.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
 import { resolveWorkspace } from '../workspace.mjs';
 
@@ -79,6 +86,8 @@ const GROUPS = new Map([
   // where", and `install` — the subcommand that touches a reader's home directory — is the
   // one that needs `--yes` before it does anything.
   ['shared', 'plan'],
+  ['lessons', 'list'],
+  ['local', 'doctor'],
 ]);
 
 /**
@@ -95,6 +104,7 @@ const GROUPS = new Map([
  * just correct: nothing in the map depends on the call.
  */
 export const IMPLEMENTED = {
+  brief: briefCommand,
   doctor: runDoctor,
   'graph lint': lintCommand,
   'skills index': skillsIndex,
@@ -104,6 +114,7 @@ export const IMPLEMENTED = {
   'skills why': skillsWhy,
   'skills eval': skillsEval,
   'skills install': installCommand,
+  'skills compile': compileCommand,
   'rules list': rulesList,
   'rules show': rulesShow,
   'rules why': rulesWhy,
@@ -121,6 +132,10 @@ export const IMPLEMENTED = {
   why: (args, flags) => whyCommand(args, flags, COMMANDS),
   gate: gateCommand,
   impact: (args, flags) => impactCommand(args, flags, COMMANDS),
+  'lessons list': lessonsListCommand,
+  'lessons review': lessonsReviewCommand,
+  decide: decideCommand,
+  'local doctor': localDoctorCommand,
   'evidence check': (args, flags) => evidenceCommand(['check', ...args], flags),
   init: initCommand,
   ci: ciCommand,
@@ -139,6 +154,7 @@ export const IMPLEMENTED = {
   'bench report': benchReportCommand,
   'bench ablate': benchAblateCommand,
   'bench probes': benchProbesCommand,
+  'bench variants': benchVariantsCommand,
   upgrade: upgradeCommand,
   mcp: mcpCommand,
 };
@@ -186,7 +202,7 @@ export async function dispatch(argv) {
     // simt-dev: they run this tool, not its source tree. The step number is the
     // stable handle; the file that documents it is an implementation detail.
     return fail(
-      `\`simt-dev ${path}\` is declared but not implemented`,
+      `\`${CLI} ${path}\` is declared but not implemented`,
       EXIT.UNSUPPORTED,
       `implementation step ${step} is not built yet`,
     );