simt-dev 0.4.0 → 0.5.0

package/src/advice/advice.mjs

@@ -0,0 +1,229 @@
+// Model and effort advice, read from the repository's own bench history (plan 0003 R40).
+//
+// The mapping the design row asks for — task features to the cheapest tier that resolved
+// similar tasks — is data, not opinion: the records `bench run` stored on disk already say
+// which model classes resolved which mined tasks and what those runs cost. So the tier
+// ladder is the estate's own evidence sorted by price, and no vendor name is written into
+// the code: a repository whose history has one class of run gets advice about that class,
+// and one whose history has three gets a ladder with three steps.
+//
+// The properties this exists to keep:
+//
+//   * Advice, never a choice. The output is a sentence in the brief header along with the
+//     bench numbers behind it; the agent (or the human) names the model, not simt-dev
+//     (P2). Nothing here writes a model id into a config, a lock or a command.
+//   * Deterministic. No model, no network, no clock (P1): the same runs directory yields
+//     the same advice, so a reviewable claim about cost is possible.
+//   * Quiet in thin evidence. A neighborhood with no resolved run yields a caution, not a
+//     made-up tier; a history with no runs at all yields no advice line.
+//
+// The measure of "cheapest" follows the bench's own report: cost in dollars when the run
+// records or a prices table price the tokens, total tokens otherwise. Ordering by a number
+// that does not exist for any run would be nondeterminism, not economics.
+import { classifyTask } from '../brief/kind.mjs';
+import { computeRunCost, isRunResolved, loadPrices, loadRunRecords } from '../bench/report.mjs';
+import { loadTasks } from '../bench/tasks.mjs';
+import { CONFIG_DIR } from '../name.mjs';
+
+/**
+ * Every advice report carries its row's accept bar (ADR-076: a metric is a measurement or
+ * it is not claimed).
+ */
+export const METRIC_NOTE =
+  'advice is advisory until a held-out bench shows >= 25% cost cut at delta R >= -2 (plan 0003 R40)';
+
+const TIERS = ['small', 'default', 'frontier'];
+
+/**
+ * The ladder can specialize beyond kind only while there is still evidence to stand on:
+ * below this many same-kind tasks the kind is the whole neighborhood, and a narrower
+ * window makes evidence worse, not "more similar".
+ */
+const NARROW_MIN_POOL = 6;
+
+/** The narrowed window needs at least these resolved runs or it is not evidence either. */
+const NARROW_MIN_RESOLVED = 3;
+
+/** A file window is a step from the estimate in either direction — a factor of two in size. */
+const WINDOW_HALF = 2;
+
+function median(values) {
+  const sorted = [...values].sort((a, b) => a - b);
+  if (sorted.length === 0) return 0;
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+
+/**
+ * Tier for a rank in the cheapest-first ladder: thirds, not absolute cost — an estate's
+ * "frontier" relative to its own history means more than a number the code guessed.
+ * The cheapest of two observed classes is 'small' and the dearer one 'default'; a class
+ * is 'frontier' only once a ladder has three steps, because a two-step ladder cannot
+ * name a top third honestly.
+ */
+export function tierOfRank(rank, count) {
+  if (count < 3) return rank === 0 ? TIERS[0] : TIERS[1];
+  if (rank * 3 < count) return TIERS[0];
+  if (rank * 3 >= count * 2) return TIERS[2];
+  return TIERS[1];
+}
+
+/**
+ * Total tokens a usage report carries — the measure that exists even with no prices file.
+ */
+function tokensOf(usage = {}) {
+  const num = (v) => Number(v ?? 0);
+  return num(usage.input) + num(usage.cacheWrite ?? usage.cache_write) + num(usage.cacheRead ?? usage.cache_read) + num(usage.output);
+}
+
+/**
+ * Load bench history as advice-ready run rows.
+ *
+ * A descriptor missing for a run leaves the row with `kind: null`; such a run can join no
+ * neighborhood, which is the honest answer — a task whose prompt was never mined is a
+ * task whose kind would be a guess.
+ */
+export async function loadHistory(root) {
+  const [records, prices, tasks] = await Promise.all([
+    loadRunRecords(root),
+    // An unreadable prices file would throw out of a brief, whose callers only asked for
+    // a packet; the bench has its own report for surfacing a broken prices file loudly.
+    loadPrices(root).catch(() => null),
+    loadTasks(root),
+  ]);
+  const byId = new Map(tasks.map((task) => [task.id, task]));
+  const runs = records.map((record) => {
+    const descriptor = byId.get(record.task) ?? null;
+    return {
+      task: record.task,
+      model: record.model,
+      resolved: isRunResolved(record),
+      cost: computeRunCost(record, prices),
+      tokens: tokensOf(record.usage),
+      toolCalls: Number(record?.usage?.toolCalls ?? record?.usage?.tool_calls ?? 0),
+      files: Number(descriptor?.gold?.files ?? record?.diff?.files ?? 0),
+      kind: descriptor ? classifyTask(descriptor.prompt ?? '', { paths: [] }).kind : null,
+    };
+  });
+  return { runs };
+}
+
+/**
+ * Advise from bench history for one task's features.
+ *
+ * @param {{kind: string, files: number}} features the task kind, and the estimate of how
+ *   many files it will touch (the brief's scope size; a history run carries the mined
+ *   task's gold stat in the same role)
+ * @param {{runs: object[]}} history rows from loadHistory
+ * @returns null when the history holds no runs; otherwise `{ picked, caution }` where
+ *   `picked` is `{ line, basis, metric }` when a tier was named (and `caution` null), and
+ *   `caution` explains the missing neighborhood when no tier can honestly be named
+ */
+export function advise(features, history) {
+  const runs = history?.runs ?? [];
+  if (runs.length === 0) return null;
+  const kind = features.kind;
+  const sameKind = runs.filter((run) => run.kind === kind);
+  const taskCount = new Set(sameKind.map((run) => run.task)).size;
+  if (sameKind.length === 0) {
+    return {
+      picked: null,
+      caution: `bench history holds no ${kind} task, so no cheap tier was advised`,
+    };
+  }
+
+  // The measure is chosen once, across all resolved history: a ladder built on dollars
+  // while the pick ran on tokens would compare a number with a different number's name.
+  const measure = runs.some((run) => run.resolved && run.cost > 0) ? 'cost' : 'tokens';
+
+  // Kind decides the neighborhood. The file window only specializes a neighborhood that
+  // has already got evidence to spare (NARROW_MIN_*): a factor-of-two window around the
+  // estimate refines "bugfix" to "small bugfix" when the kind has runs to lend, and says
+  // nothing when it has not.
+  let pool = sameKind;
+  if (features.files > 0 && sameKind.length >= NARROW_MIN_POOL) {
+    const near = sameKind.filter(
+      (run) =>
+        run.files > 0 &&
+        run.files >= Math.ceil(features.files / WINDOW_HALF) &&
+        run.files <= features.files * WINDOW_HALF,
+    );
+    if (near.filter((run) => run.resolved).length >= NARROW_MIN_RESOLVED) pool = near;
+  }
+  const poolTaskCount = new Set(pool.map((run) => run.task)).size;
+
+  // The ladder orders every model class the estate ever ran, cheapest first, so the
+  // advice can say where its pick sits in the estate's whole history. Uncost evidence is
+  // still cost position: a class that never resolved one of these tasks occupies a rung
+  // in the price ladder, and the resolved floor below — not the ladder — decides whether
+  // the pick is allowed to stand on it.
+  const ladderValues = new Map();
+  for (const run of runs) {
+    const values = ladderValues.get(run.model) ?? [];
+    values.push(measure === 'cost' ? run.cost : run.tokens);
+    ladderValues.set(run.model, values);
+  }
+  const ladderNames = [...ladderValues.keys()].sort(
+    (a, b) => median(ladderValues.get(a)) - median(ladderValues.get(b)) || a.localeCompare(b),
+  );
+
+  const resolvedByModel = new Map();
+  for (const run of pool) {
+    if (!run.resolved) continue;
+    const values = resolvedByModel.get(run.model) ?? [];
+    values.push(measure === 'cost' ? run.cost : run.tokens);
+    resolvedByModel.set(run.model, values);
+  }
+
+  // "Resolved similar tasks" is a floor, not a style: a class that never resolved one of
+  // these tasks is cheaper because it failed for less money.
+  const qualifying = ladderNames.filter((model) => resolvedByModel.has(model));
+  if (qualifying.length === 0) {
+    return {
+      picked: null,
+      caution: `no model resolved any of the ${taskCount} ${kind} task${taskCount === 1 ? '' : 's'} in bench history, so no cheap tier was advised`,
+    };
+  }
+
+  // Ties break on the model name, so the same history always yields the same pick (P4).
+  const cheapest = [...qualifying].sort(
+    (a, b) => median(resolvedByModel.get(a)) - median(resolvedByModel.get(b)) || a.localeCompare(b),
+  )[0];
+  const ladderRank = ladderNames.indexOf(cheapest);
+  const tier = tierOfRank(ladderRank, ladderNames.length);
+
+  // Effort advice is relative to the estate too: heavier turns of tool use than the
+  // estate's own resolved median is what "plan first" means here.
+  const resolvedRuns = runs.filter((run) => run.resolved);
+  const estateToolCalls = median(resolvedRuns.map((run) => run.toolCalls));
+  const resolvedRunsOfCheapest = pool.filter((run) => run.resolved && run.model === cheapest);
+  const pickToolCalls = median(resolvedRunsOfCheapest.map((run) => run.toolCalls));
+  const effort = estateToolCalls > 0 && pickToolCalls > estateToolCalls ? 'plan first' : 'no plan mode';
+
+  const pickMedian = median(resolvedByModel.get(cheapest));
+  const pickUnit = measure === 'cost' ? `cost $${pickMedian.toFixed(4)}` : `tokens ${Math.round(pickMedian)}`;
+
+  return {
+    picked: {
+      line: `${tier} model, ${effort}`,
+      basis: `from ${poolTaskCount} ${kind} task${poolTaskCount === 1 ? '' : 's'} in bench history; cheapest that resolved: ${cheapest} (median ${pickUnit}); a human picks the model, this only ranks classes`,
+      metric: METRIC_NOTE,
+    },
+    caution: null,
+  };
+}
+
+/**
+ * The brief's door into advice (plan 0003 R40): history on disk in, advice out, or null
+ * when the history has no runs at all — a brief in a repository without bench history
+ * carries every other section and no made-up opinion about models.
+ *
+ * `kind` comes in already classified when the caller is the brief itself, so the packet
+ * never carries two opinions about one task.
+ */
+export async function briefAdvice(root, { task = '', scope = [], kind = null } = {}) {
+  const history = await loadHistory(root);
+  if (history.runs.length === 0) return null;
+  const known = kind ?? classifyTask(task, { paths: scope }).kind;
+  return advise({ kind: known, files: scope.length }, history);
+}

package/src/argv.mjs

@@ -80,10 +80,22 @@ export const BOOL_FLAGS = new Set([
   // index / map / brief: opt into local vector embeddings configured under local.embed
   // (plan 0003 R28, R37). Off by default unless recall@10 gains at least 10 points.
   'embed',
+  // distill: regenerate a proposal that is already cached. Off by default because
+  // the cache is the point - the same source at the same budget is the same answer,
+  // and re-reading it is cheaper than re-deriving it (plan 0003 R38).
+  'refresh',
+  // distill: propose the summary from the configured local chat model instead of
+  // the deterministic outline. Off by default: no model in the default path (P1),
+  // and a model that is not asked for should not be opened against (ADR-090).
+  'local',
 ]);
 
 export const VALUE_FLAGS = new Set([
   'budget',
+  // bench critic: the labelled set of historical diffs to score (plan 0003 R39).
+  // A path, not a switch, because the labels themselves come from a human under
+  // ADR-008 — the tool never annotates for them.
+  'labels',
   'max-bytes',
   'paths',
   'skill',

package/src/bench/run.mjs

@@ -17,6 +17,7 @@ import { fingerprint } from '../resolve/fingerprint.mjs';
 import { rankSkills, tokenize } from '../resolve/resolve.mjs';
 import { gradeWorkspace } from './grade.mjs';
 import { resolveVaultDir } from './mine.mjs';
+import { loadTasks } from './tasks.mjs';
 import { ablateSectionInWorkspace, parseAblationArmName } from './ablate.mjs';
 import { applyVariantInWorkspace, parseVariantArmName } from './variants.mjs';
 
@@ -678,21 +679,8 @@ async function executeAdapter(adapter, workDir, task, { vaultRoot, model, maxTur
   return { ...parseAdapterUsage(adapter, stdoutText, analyticsText), transcript: `${stdoutText}\n${analyticsText}` };
 }
 
-async function loadTasks(root, filterIds = []) {
-  const tasksDir = join(root, STATE_DIR, 'bench', 'tasks');
-  const entries = (await readdir(tasksDir).catch(() => []))
-    .filter((f) => f.endsWith('.json'))
-    .sort();
-
-  const filterSet = new Set(filterIds);
-  const tasks = [];
-  for (const entry of entries) {
-    const data = JSON.parse(await readFile(join(tasksDir, entry), 'utf8'));
-    if (filterSet.size > 0 && !filterSet.has(data.id)) continue;
-    tasks.push(data);
-  }
-  return tasks.sort((a, b) => a.id.localeCompare(b.id));
-}
+// loadTasks lives in tasks.mjs (the advice engine became a second reader, so the loader
+// was extracted rather than copied — ADR-002).
 
 function runIdFor(harness, armName, rep) {
   return `${harness}-${armName}-r${rep}`;

package/src/bench/tasks.mjs

@@ -0,0 +1,38 @@
+// Mined task descriptors, read back from the tool state's `bench/tasks/` directory (plan 0003 R01).
+//
+// Extracted from bench/run.mjs on its second real reader (ADR-002): the R40 advice engine
+// needs the two facts a run record does not carry — the prompt, which classifies the task,
+// and the gold stat, which says how many files the change touched. A second private loader
+// beside the first would drift the first time one learned a filter the other lacked.
+//
+// Deterministic by construction: the directory is read sorted, the filter is exact, and no
+// part of this touches a model, a network or a clock.
+import { readdir, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { CONFIG_DIR } from '../name.mjs';
+
+const STATE_DIR = `.${CONFIG_DIR}`;
+
+/**
+ * Load mined benchmark task descriptors.
+ *
+ * @param {string} root the repository
+ * @param {string[]} [filterIds] exact task ids to keep; empty means load them all
+ * @returns descriptor objects sorted by id (id, base, sourceCommit, prompt, testCmd,
+ *   f2p, p2p, gold {files, linesAdded, linesRemoved}, vault)
+ */
+export async function loadTasks(root, filterIds = []) {
+  const tasksDir = join(resolve(root), STATE_DIR, 'bench', 'tasks');
+  const entries = (await readdir(tasksDir).catch(() => []))
+    .filter((f) => f.endsWith('.json'))
+    .sort();
+
+  const filterSet = new Set(filterIds);
+  const tasks = [];
+  for (const entry of entries) {
+    const data = JSON.parse(await readFile(join(tasksDir, entry), 'utf8'));
+    if (filterSet.size > 0 && !filterSet.has(data.id)) continue;
+    tasks.push(data);
+  }
+  return tasks.sort((a, b) => a.id.localeCompare(b.id));
+}

package/src/brief/assemble.mjs

@@ -37,6 +37,7 @@
 import { CLI } from '../name.mjs';
 import { DEFAULT_BRIEF_BYTES, buildPacket, collect } from './packet.mjs';
 import { classifyTask, cardVerbs } from './kind.mjs';
+import { briefAdvice } from '../advice/advice.mjs';
 import { commandCard } from '../kernel/card.mjs';
 import { decisionHits, scopeHits, sourceRoots } from '../index/govern.mjs';
 import { embedTaskQuery, rankFiles, renderMap } from '../index/map.mjs';
@@ -192,6 +193,27 @@ export async function assembleBrief({
     });
   }
 
+  // Model and effort advice comes from the repository's bench history, not from anything a
+  // model produced, so it stays deterministic. The tier exists only if the history resolved
+  // a similar task, and the claim travels with its own numbers and its unmeasured accept
+  // bar; simt-dev never selects the model an agent runs (plan 0003 R40).
+  const advice = await briefAdvice(root, { task, scope, kind });
+  if (advice?.picked) {
+    packet.add('ADVICE', advice.picked.line, {
+      why: ['the tier is the estate’s own bench ladder, and a human still names the model'],
+    });
+    packet.add('ADVICE', advice.picked.basis, {
+      why: ['an advice claim names the neighborhood that backs it, so the reader can re-derive it'],
+    });
+    packet.add('ADVICE', advice.picked.metric, {
+      why: ['the row has an accept bar, and nothing in a packet may claim the bar was met'],
+    });
+  } else if (advice?.caution) {
+    packet.add('CAUTIONS', advice.caution, {
+      why: ['advice without a neighborhood is a guess dressed as history'],
+    });
+  }
+
   const likely = ranked.slice(0, LIKELY_FILES).map((row) => row.path);
   const known = testEdges({ files, imports: edges.filter((edge) => edge.kind === 'import') });
   const untested = [];

package/src/brief/packet.mjs

@@ -30,7 +30,7 @@ export const PROMPT_CAP_BYTES = 2048;
  * The order is fixed and identical in every packet. A reader who has to search for the
  * command is paying the cost the packet exists to remove.
  */
-const SECTIONS = ['TASK', 'COMMANDS', 'FILES', 'TESTS', 'DECISIONS', 'FEDERATION', 'SKILLS', 'LESSONS', 'CAUTIONS'];
+const SECTIONS = ['TASK', 'ADVICE', 'COMMANDS', 'FILES', 'TESTS', 'DECISIONS', 'FEDERATION', 'SKILLS', 'LESSONS', 'CAUTIONS'];
 
 /**
  * What each section is worth when something has to go.
@@ -49,6 +49,9 @@ const SECTIONS = ['TASK', 'COMMANDS', 'FILES', 'TESTS', 'DECISIONS', 'FEDERATION
  */
 const SECTION_VALUE = {
   CAUTIONS: 1,
+  // Bench evidence, but advice rather than fact: losing it costs an opinion, not a
+  // command or a path to check (plan 0003 R40).
+  ADVICE: 2,
   LESSONS: 2,
   SKILLS: 3,
   DECISIONS: 4,

package/src/commands/bench.mjs

@@ -16,6 +16,7 @@ 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 { criticBench } from '../review/critic.mjs';
 import { listFlag } from './skills.mjs';
 
 export async function benchMineCommand(positional, flags) {
@@ -394,3 +395,34 @@ export async function benchVariantsCommand(positional, flags) {
 
 
 
+
+// `simt bench critic` (plan 0003 R39).
+//
+// The row's acceptance measured, or reported missing rather than inferred: the
+// critic runs over a labelled set of historical diffs and the bench reports
+// precision and recall for the BLOCK binary. The metric never gates the critic —
+// the row says precision >= 0.8 on >= 30 labelled diffs promotes it to a gate,
+// and until a bench here shows that, every report calls the critic advisory.
+export async function benchCriticCommand(positional, flags, commands = []) {
+  const root = resolve(flags.root ?? positional[0] ?? process.cwd());
+  const labelsPath = flags.labels ?? '.simt-dev/critic-labels.jsonl';
+  const result = await criticBench(root, { labelsPath, flags, commands });
+  if (typeof result === 'number') return result;
+
+  if (isJson(flags)) {
+    emitJson(result, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  const lines = [
+    `bench    critic  ${root}`,
+    `labels   ${result.labels} (${labelsPath})  measured ${result.measured}  errors ${result.errors.length}`,
+    `counts   tp=${result.tp} fp=${result.fp} fn=${result.fn} tn=${result.tn}`,
+    `precision ${result.precision === null ? 'unmeasured' : result.precision.toFixed(3)}`,
+    `recall    ${result.recall === null ? 'unmeasured' : result.recall.toFixed(3)}`,
+    `gated    ${result.gated ? 'yes' : 'no'}`,
+  ];
+  if (result.labelsNote) lines.push(`labels   ${result.labelsNote}`);
+  for (const error of result.errors) lines.push(`error    ${error}`);
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}

package/src/commands/distill.mjs

@@ -0,0 +1,36 @@
+// `simt distill <skill|doc>` (plan 0003 R38).
+//
+// A budgeted summary with citations to source line ranges, written to
+// `.simt-dev/distilled/` as a proposal a human merges. The deterministic engine
+// is the default; a local model proposes only when the caller asks for it and the
+// manifest names one (ADR-090, ADR-075). Model output never lands anywhere
+// projected or committed text does — that is the direction this command cannot
+// take (principle P2).
+
+import { CLI } from '../name.mjs';
+import { EXIT, emit, emitJson, isJson } from '../output/index.mjs';
+import { distillTarget } from '../distill/distill.mjs';
+
+export async function distillCommand(args, flags) {
+  const result = await distillTarget(args, flags);
+  if (typeof result === 'number') return result;
+
+  if (isJson(flags)) {
+    emitJson(result, { maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+
+  emit(
+    [
+      `source    ${result.target.kind}  ${result.target.source} (${result.target.bytes} bytes, ${result.target.lines} lines)`,
+      `digest    ${result.digest}`,
+      `engine    ${result.engine}`,
+      `budget    ${result.budget} bytes`,
+      `citations ${result.citations}`,
+      ...(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/help.mjs

@@ -103,6 +103,21 @@ ${CLI} decide [<title>]        scaffold an ADR with the next free number, a Stat
 ${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-dev/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)
+                           (deterministic without --local: the brief and its
+                           governing ids only; --local proposes from the
+                           configured chat model and writes
+                           .simt-dev/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
                            once: the shared set, its bytes, and every path that would be written
                            (read-only; touches nothing, not even your home directory)
@@ -141,6 +156,11 @@ ${CLI} bench probes [--yes]    12 synthetic rule-compliance probes with determin
 ${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} bench critic          precision and recall of the local critic over a labelled
+                            set of historical diffs (.simt-dev/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} 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)`;
@@ -204,9 +224,17 @@ const FLAGS = `--json                 structured output (compact; one document,
 --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)
+--allow-remote          local doctor / distill / review: 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)
+--labels <path>         bench critic: the labelled set of historical diffs to score
+                        (default .simt-dev/critic-labels.jsonl; one human-written
+                        {sha, verdict} pair per line)
+--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
+                         uses the deterministic path instead
 --help                  this text
 --version               the version, and the SHA it was built from`;
 

package/src/commands/index.mjs

@@ -46,6 +46,7 @@ import {
   benchAblateCommand,
   benchProbesCommand,
   benchVariantsCommand,
+  benchCriticCommand,
 } from './bench.mjs';
 import { planCommand } from './plan.mjs';
 import { sharedPlanCommand, sharedInstallCommand, sharedWarning } from './shared.mjs';
@@ -58,7 +59,9 @@ import { gateCommand } from './gate.mjs';
 import { impactCommand } from './impact.mjs';
 import { lessonsListCommand, lessonsReviewCommand } from './lessons.mjs';
 import { decideCommand } from './decide.mjs';
+import { reviewCommand } from './review.mjs';
 import { localDoctorCommand } from './local.mjs';
+import { distillCommand } from './distill.mjs';
 import { parse } from '../argv.mjs';
 import { CLI } from '../name.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
@@ -135,6 +138,10 @@ export const IMPLEMENTED = {
   'lessons list': lessonsListCommand,
   'lessons review': lessonsReviewCommand,
   decide: decideCommand,
+  distill: distillCommand,
+  // R25 machinery needs the runnable command names for Affects command tokens,
+  // same wiring `why` and `impact` get through their lambdas.
+  review: (args, flags) => reviewCommand(args, flags, COMMANDS),
   'local doctor': localDoctorCommand,
   'evidence check': (args, flags) => evidenceCommand(['check', ...args], flags),
   init: initCommand,
@@ -155,6 +162,11 @@ export const IMPLEMENTED = {
   'bench ablate': benchAblateCommand,
   'bench probes': benchProbesCommand,
   'bench variants': benchVariantsCommand,
+  // plan 0003 R39. The critic's acceptance bench measures BLOCK-precision and
+  // recall over a labelled set; until it reports its floor, the critic entries
+  // stay advisory and no gate reads them. COMMANDS rides along so the brief
+  // resolves Affects command tokens the way `simt why` does.
+  'bench critic': (args, flags) => benchCriticCommand(args, flags, COMMANDS),
   upgrade: upgradeCommand,
   mcp: mcpCommand,
 };

package/src/commands/review.mjs

@@ -0,0 +1,65 @@
+// `simt review [--local]` (plan 0003 R39).
+//
+// The critic's report layer: the deterministic path prints the brief (staged diff
+// plus what governs it); `--local` adds the model verdict, which always arrives as
+// a proposal a human reads — nothing here is a gate, and the exit code never
+// carries the verdict, because a critic that fails the run would be a gate by
+// another name (ADR-090, principle P2: the reply's text is model output and never
+// lands in projected or committed text).
+
+import { CLI } from '../name.mjs';
+import { EXIT, emit, emitJson, isJson } from '../output/index.mjs';
+import { reviewTarget } from '../review/critic.mjs';
+
+function governsLine(items) {
+  if (items.length === 0) return 'none';
+  const ids = items.slice(0, 8).map((item) => item.id);
+  const more = items.length > ids.length ? ` …+${items.length - ids.length}` : '';
+  return ids.join(', ') + more;
+}
+
+export async function reviewCommand(args, flags, commands = []) {
+  const result = await reviewTarget(args, flags, { commands });
+  if (typeof result === 'number') return result;
+
+  if (isJson(flags)) {
+    emitJson(result, { maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+
+  const lines = [
+    `staged    ${result.staged.files.length} files, ${result.staged.bytes} bytes`,
+    `governs   ${governsLine(result.governs)}`,
+  ];
+  // The branch keys on the path, not on the verdict: a local run whose reply
+  // lacked a verdict line still carries faults and a proposal, and hiding them
+  // behind the "needs --local" reading would erase the model's failure.
+  if (result.brief !== undefined) {
+    // The nothing-staged run is a plain answer, not an invitation to rerun with
+    // --local: there is no brief yet, so there is nothing for the critic to read.
+    if (result.staged.files.length === 0) {
+      lines.push('verdict   none (nothing is staged)');
+    } else {
+      lines.push(
+        `verdict   needs ${CLI} review --local  (advisory; a critic is never a gate)`,
+      );
+    }
+  } else {
+    if (result.verdict !== null) {
+      lines.push(
+        `verdict   ${result.verdict} (${result.verified ? 'verified' : 'unverified'})`,
+        `findings  ${result.findings}`,
+      );
+    } else {
+      lines.push('verdict   absent (unverified)');
+    }
+    if (!result.verified) {
+      for (const fault of result.faults) lines.push(`unverified ${fault}`);
+    }
+    lines.push(`proposal  ${result.proposal.path}  (${result.proposal.state}, ${result.proposal.bytes} bytes)`);
+  }
+  if (result.metric) lines.push(`metric    ${result.metric.note}`);
+
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}