simt-dev 0.4.0 → 0.6.0

package/src/agenthooks/render.mjs

@@ -1,6 +1,6 @@
 // One renderer per harness: the payload in, the decision out, and the config written.
 //
-// Four harnesses read a hook and no two agree on anything. The config path, the event
+// Five harnesses read a hook and no two agree on anything. The config path, the event
 // name, the shape of the document, the tool name for a shell command, the key holding
 // the command, and the JSON a hook answers with are all different, and none of them is
 // the same fact. So this module owns the differences and `policy.mjs` owns none of
@@ -10,15 +10,17 @@
 //   codex        .codex/hooks.json       PreToolUse      {"hooks":{E:[{matcher,hooks:[h]}]}}
 //   cursor       .cursor/hooks.json      preToolUse      {"version":1,"hooks":{E:[h]}}
 //   antigravity  .agents/hooks.json      PreToolUse      {"<name>":{E:[{matcher,hooks:[h]}]}}
+//   gemini       .gemini/settings.json   BeforeTool      {"hooks":{E:[{matcher,hooks:[h]}]}}
 //
 // The prompt-submit event (R29) is a second table, and it is shorter because the vendors
-// are: two of the four document a prompt event that can put text into the model's context,
-// and a delivery is the only thing this tool does there. Neither takes a matcher — both
+// are: three of the five document a prompt event that can put text into the model's context,
+// and a delivery is the only thing this tool does there. None takes a matcher — all
 // document that field for tool events, and a matcher a harness ignores is a matcher the
 // next person believes is filtering something.
 //
 //   claude       .claude/settings.json   UserPromptSubmit   hookSpecificOutput.additionalContext
 //   codex        .codex/hooks.json       UserPromptSubmit   hookSpecificOutput.additionalContext
+//   gemini       .gemini/settings.json   BeforeAgent        hookSpecificOutput.additionalContext
 //   cursor       .cursor/hooks.json      beforeSubmitPrompt CANNOT INJECT: block-only
 //   antigravity  .agents/hooks.json      (no prompt event documented)
 //
@@ -26,10 +28,11 @@
 // can only continue or block, so the entry would carry no packet and a broken one would
 // stop a person from typing — and its only injection point, `sessionStart.additional_context`,
 // fires once when the session is created, which is a different lifetime from the brief a
-// task needs. Gemini CLI documents `BeforeAgent`, which does inject, but the product was
-// replaced by Antigravity CLI on 2026-06-18 and its config is not in the reader table this
-// module takes its paths from; a harness this tool did not verify is a harness it does not
-// write to.
+// task needs. Gemini CLI was replaced by Antigravity CLI on 2026-06-18, which is the row
+// that covers the successor; the gemini row stays because the extension is still documented
+// and installable and R43 ships a package for it, and its hooks file is in the reader table
+// this module takes its paths from — a harness this tool did not verify is a harness it
+// does not write to.
 //
 // The paths are not written here. They come from the reader table (R14) because that is
 // where each one was verified against its vendor page, and a second copy of a verified
@@ -188,9 +191,43 @@ const ADAPTERS = {
     prompt: null,
     post: null,
   },
+  gemini: {
+    id: 'gemini',
+    event: 'BeforeTool',
+    matcher: 'run_shell_command|write_file|replace',
+    // The vendor's timeout unit is milliseconds (default 60000), not the seconds every
+    // other row uses; a bare 10 here would be a ten-millisecond budget, which is a hook
+    // that never finishes. The row carries its own value so the shared constant stays
+    // honest for the four vendors that measure in seconds.
+    timeout: 10000,
+    // The reference documents the decision JSON and an exit-2 system block; the denial
+    // travels in the JSON, as antigravity does.
+    denyExit: 0,
+    verified: 'geminicli.com/docs/hooks/reference/, read 2026-10-26',
+    root: (p) => p.cwd,
+    extract: (p) => ({
+      command: p.tool_name === 'run_shell_command' ? (p.tool_input?.command ?? null) : null,
+      writes: ['write_file', 'replace'].includes(p.tool_name) ? [p.tool_input?.file_path].filter(Boolean) : [],
+    }),
+    deny: (message) => ({ decision: 'deny', reason: message }),
+    // BeforeAgent appends text to the prompt for this turn only — the same lifetime as a
+    // brief. The documented output has no hookEventName field, unlike Claude's.
+    prompt: {
+      event: 'BeforeAgent',
+      verified: 'geminicli.com/docs/hooks/reference/, read 2026-10-26',
+      context: (text) => ({ hookSpecificOutput: { additionalContext: text } }),
+    },
+    // AfterTool appends to the tool result; its input carries tool_response, which is
+    // what the lesson recall reads.
+    post: {
+      event: 'AfterTool',
+      verified: 'geminicli.com/docs/hooks/reference/, read 2026-10-26',
+      context: (text) => ({ hookSpecificOutput: { additionalContext: text } }),
+    },
+  },
 };
 
-/** The four adapters, in the order the reader table lists them. */
+/** The five adapters, in the order the reader table lists them. */
 export function adapters() {
   return hookRows()
     .filter((r) => r.path !== null)
@@ -203,9 +240,19 @@ export function adapter(id) {
   return row && hookPath(id) !== null ? row : null;
 }
 
-/** The facts a payload carries, and the root it names. An unknown shape yields none. */
-export function factsFrom(row, payload) {
-  return { root: row.root(payload) ?? process.cwd(), ...row.extract(payload ?? {}) };
+/**
+ * The facts a payload carries, and the root it names. An unknown shape yields none.
+ *
+ * `root` is a caller-supplied override that outranks the payload: a packaged hook runs
+ * from the plugin directory and the harness's environment variable names the project, so
+ * `--root` (from `$CLAUDE_PROJECT_DIR` and friends) must win over a payload cwd that is
+ * the plugin's own working directory. An empty override is treated as absent rather than
+ * trusted: an env var the harness did not set expands to `""` in the shell, and a root of
+ * the empty string would resolve every fact against the filesystem root.
+ */
+export function factsFrom(row, payload, { root } = {}) {
+  const override = typeof root === 'string' && root.trim() !== '' ? root : null;
+  return { root: override ?? row.root(payload) ?? process.cwd(), ...row.extract(payload ?? {}) };
 }
 
 /** The document to print for a decision, or null when there is nothing to say. */
@@ -281,27 +328,33 @@ function eventsOf(row, { prompt = false, post = false } = {}) {
   return pairs;
 }
 
-/** The group this tool owns for one event, in that harness's shape. */
-function group(row, event = EVENTS[0]) {
-  const command = hookCommand(row.id, event);
+/**
+ * The group this tool owns for one event, in that harness's shape.
+ *
+ * `command` overrides the entry point for one build: a package ships a self-contained
+ * runtime and its config names that copy rather than the binary on PATH, so the shape
+ * comes from this table and only the path differs.
+ */
+function group(row, event = EVENTS[0], command = hookCommand(row.id, event)) {
+  const timeout = row.timeout ?? TIMEOUT_SECONDS;
   if (event === 'prompt-submit') {
     // No matcher: both vendors document that field for tool events, and a matcher a
     // harness ignores is a matcher the next reader believes is filtering something.
-    return { hooks: [{ type: 'command', command, timeout: TIMEOUT_SECONDS }] };
+    return { hooks: [{ type: 'command', command, timeout }] };
   }
   if (event === 'post-tool-use') {
     const matcher = row.post?.matcher;
     return matcher
-      ? { matcher, hooks: [{ type: 'command', command, timeout: TIMEOUT_SECONDS }] }
-      : { hooks: [{ type: 'command', command, timeout: TIMEOUT_SECONDS }] };
+      ? { matcher, hooks: [{ type: 'command', command, timeout }] }
+      : { hooks: [{ type: 'command', command, timeout }] };
   }
   if (row.id === 'cursor') {
     // failClosed is set because a hooks file this tool wrote should not silently
     // degrade to fail-open on its own crash: the vendor's default turns a broken hook
     // into an absent one, and the whole point of writing it is that it runs.
-    return { command, timeout: TIMEOUT_SECONDS, matcher: row.matcher, failClosed: true };
+    return { command, timeout, matcher: row.matcher, failClosed: true };
   }
-  return { matcher: row.matcher, hooks: [{ type: 'command', command, timeout: TIMEOUT_SECONDS }] };
+  return { matcher: row.matcher, hooks: [{ type: 'command', command, timeout }] };
 }
 
 /** Whether a group is this tool's, judged by the command it runs and not by position. */
@@ -335,11 +388,11 @@ export function installedIn(row, config, event = EVENTS[0]) {
  * asked for a delivered packet gets the tool hook and nothing extra, and the file it never
  * asked to change is a file this tool does not touch.
  */
-function withHook(row, config, { prompt = false, post = false } = {}) {
+function withHook(row, config, { prompt = false, post = false, command } = {}) {
   const box = container(row, config, { create: true });
   for (const [event, name] of eventsOf(row, { prompt, post })) {
     const kept = entries(row, config, event).filter((e) => !ours(e));
-    box[name] = [...kept, group(row, event)];
+    box[name] = [...kept, group(row, event, event === EVENTS[0] ? command : undefined)];
   }
   return config;
 }
@@ -359,3 +412,16 @@ export function rendered(row, existing, options = {}) {
   const text = `${JSON.stringify(withHook(row, config, options), null, 2)}\n`;
   return { text, action: text === existing ? 'unchanged' : 'updated' };
 }
+
+/**
+ * A fresh config document carrying only this tool's hooks, for a package that ships its
+ * own runtime: the shape comes from the same table `install` merges into a repository,
+ * and only the entry point differs — the package's copy of the binary, named by `command`.
+ * Returns null for a harness this tool has no adapter for or that documents no hooks file.
+ */
+export function hookDocument(id, { command, prompt = false, post = false } = {}) {
+  const row = adapter(id);
+  if (!row) return null;
+  const config = withHook(row, {}, { prompt, post, command });
+  return `${JSON.stringify(config, null, 2)}\n`;
+}

package/src/argv.mjs

@@ -80,10 +80,27 @@ 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',
+  // pack lint: reject a pack whose bench summary is missing or unmeasured.
+  // Off by default because a scaffold is born unmeasured - `pack new` writes a
+  // bench.json marked unmeasured, and a lint that failed it on arrival would make
+  // every new pack red before its author wrote the rule (plan 0003 R45).
+  'require-measured',
+  // 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',
@@ -126,6 +143,14 @@ export const VALUE_FLAGS = new Set([
   'level',
   // decide: structured supersession spec (ADR-NNN or ADR-NNN:<ruling>[:<kind>], repeatable).
   'supersedes',
+  // pack new: where the pack's bytes come from. Required, because a pack without
+  // a source is bytes nobody can obtain again - and a source nobody can act on
+  // is refused by lint rather than blessed (plan 0003 R45).
+  'source',
+  // plugin: where the generated package lands. A value rather than a boolean because
+  // "generate a package" with no destination would have to guess, and a guess about where
+  // a directory tree goes is the one failure that leaves files behind.
+  'out',
 ]);
 
 /**

package/src/bench/ablate.mjs

@@ -10,7 +10,7 @@
 import { mkdir, readFile, rm, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 
-import { CONFIG_DIR, MANIFEST_FILE } from '../name.mjs';
+import { MANIFEST_FILE, STATE_DIR } from '../name.mjs';
 import { readManifest } from '../projection/manifest.mjs';
 import { inject, parse as parseRegion } from '../projection/markers.mjs';
 import { loadMdcRules, renderMdc, ruleName } from '../projection/mdc.mjs';
@@ -27,8 +27,6 @@ import {
   loadRunRecords,
 } from './report.mjs';
 
-const STATE_DIR = `.${CONFIG_DIR}`;
-
 export const DEFAULT_CANARY_SIZE = 10;
 export const DEL_R_TOLERANCE = 0.01;
 export const CANARY_ALPHA = 0.05;

package/src/bench/grade.mjs

@@ -148,7 +148,7 @@ export async function gradeWorkspace(workDir, task, { vaultRoot, initialHead, ti
     .toString('utf8')
     .split('\n')
     .map((s) => s.trim())
-    .filter((f) => Boolean(f) && !f.startsWith('.simt-dev/'));
+    .filter((f) => Boolean(f) && !f.startsWith('.simt/'));
 
   const goldFiles = new Set(extractPatchFiles(goldPatch));
   const outsideBlastRadius =

package/src/bench/mine.mjs

@@ -8,7 +8,7 @@
 //
 // Hidden test patches live in `~/.cache/simt-dev/vault/<repo-id>/<task-id>/`
 // outside every worktree (RepoTrials / PatchGym), while deterministic task
-// descriptors live in `.simt-dev/bench/tasks/<id>.json`.
+// descriptors live in `.simt/bench/tasks/<id>.json`.
 
 import { execFile, spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
@@ -661,7 +661,7 @@ async function validateCandidate(root, worktree, candidate, { timeoutMs = 5000 }
  * Mine verified benchmark tasks from a repository's git history.
  *
  * When `apply` is false (the default without `--yes`, or under `--dry-run`),
- * candidates are discovered and reported without writing to `.simt-dev/bench/tasks/`
+ * candidates are discovered and reported without writing to `.simt/bench/tasks/`
  * or the vault. When `apply` is true, candidates are validated in isolated
  * temporary worktrees until `target` valid tasks are collected, and written
  * deterministically to disk.
@@ -685,7 +685,7 @@ export async function mineTasks(
     return { ok: false, error: listed.error };
   }
 
-  const tasksDir = join(absRoot, '.simt-dev', 'bench', 'tasks');
+  const tasksDir = join(absRoot, '.simt', 'bench', 'tasks');
   const vaultRoot = resolveVaultDir(absRoot, { env });
 
   if (!apply) {

package/src/bench/probes.mjs

@@ -25,12 +25,10 @@ import { chmod, mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 
-import { CONFIG_DIR } from '../name.mjs';
+import { STATE_DIR } from '../name.mjs';
 import { parse as parseRegion } from '../projection/markers.mjs';
 import { materialiseArm, parseArmSpec } from './run.mjs';
 
-const STATE_DIR = `.${CONFIG_DIR}`;
-
 function sanitizedEnv(extra = {}) {
   const env = { ...process.env, SIMT_DEV_WORKSPACE: 'off', ...extra };
   for (const key of Object.keys(env)) {

package/src/bench/report.mjs

@@ -8,9 +8,7 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 
-import { CONFIG_DIR } from '../name.mjs';
-
-const STATE_DIR = `.${CONFIG_DIR}`;
+import { STATE_DIR } from '../name.mjs';
 
 export const DEFAULT_BOOTSTRAP_SAMPLES = 1000;
 export const DEFAULT_BOOTSTRAP_SEED = 0x51772026;

package/src/bench/run.mjs

@@ -9,7 +9,7 @@ import { loadRegistry } from '../graph/load.mjs';
 import { extractOpenedSkills, matchSkillsForPaths } from '../graph/compile.mjs';
 import { matchGlob } from '../index/govern.mjs';
 import { formatLessonParagraph, listPromotedLessons } from '../memory/lessons.mjs';
-import { CONFIG_DIR, MANIFEST_FILE } from '../name.mjs';
+import { MANIFEST_FILE, STATE_DIR } from '../name.mjs';
 import { readManifest } from '../projection/manifest.mjs';
 import { plan } from '../projection/project.mjs';
 import { parse as parseRegion } from '../projection/markers.mjs';
@@ -17,11 +17,10 @@ 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';
 
-const STATE_DIR = `.${CONFIG_DIR}`;
-
 const BENCH_DIR = dirname(fileURLToPath(import.meta.url));
 const ADAPTERS_PATH = join(BENCH_DIR, 'adapters.json');
 
@@ -678,21 +677,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,36 @@
+// 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 { STATE_DIR } from '../name.mjs';
+
+/**
+ * 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/bench/variants.mjs

@@ -10,7 +10,7 @@ import { mkdir, readdir, readFile, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 
 import { extractVariantsFromRule, readLockedVariants } from '../kernel/variants.mjs';
-import { CONFIG_DIR, MANIFEST_FILE } from '../name.mjs';
+import { MANIFEST_FILE, STATE_DIR } from '../name.mjs';
 import { writeLockVariants } from '../projection/lock.mjs';
 import { readManifest } from '../projection/manifest.mjs';
 import { loadMdcRules } from '../projection/mdc.mjs';
@@ -27,8 +27,6 @@ import {
   loadRunRecords,
 } from './report.mjs';
 
-const STATE_DIR = `.${CONFIG_DIR}`;
-
 /**
  * Discover every `simt-variants` slot across applicable rules for `root`.
  */

package/src/brief/assemble.mjs

@@ -34,13 +34,13 @@
 // command and the tool leave it on. It is inert either way in a repository that declared no
 // servers.
 
-import { CLI } from '../name.mjs';
+import { CLI, STATE_DIR } 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';
-import { SQLITE_FILE } from '../index/persist.mjs';
 import { searchFtsBm25 } from '../index/store.mjs';
 import { testEdges, testsFor } from '../index/tests.mjs';
 import { loadRegistry } from '../graph/load.mjs';
@@ -80,7 +80,6 @@ const MAP_FACTOR = 8;
  * between two identical commands is not the packet this promises. The tool's own scratch
  * space is never part of a task's scope.
  */
-const STATE_DIR = `${SQLITE_FILE.split('/')[0]}/`;
 
 /** Every file git tracks that carries a generated region, one `git grep` away. */
 async function generatedRegions(root) {
@@ -127,7 +126,7 @@ export async function assembleBrief({
   federate = true,
 } = {}) {
   const named = paths !== null;
-  const dirty = (await dirtyPaths(root)).filter((path) => !path.startsWith(STATE_DIR));
+  const dirty = (await dirtyPaths(root)).filter((path) => !path.startsWith(`${STATE_DIR}/`));
   const scope = named ? parsePathList(paths) : dirty;
 
   const graph = await loadGraph(root, { build });
@@ -192,6 +191,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/ci/dependabot.mjs

@@ -21,7 +21,7 @@
 //     rewritten, their file from the first commit. A repo that wants a different
 //     cadence, a private registry or an `ignore` rule edits it, and the edit
 //     stays. simt-dev's own repository is the ADR-024 exception and is refreshed
-//     by `simt-dev ci`.
+//     by `simt ci`.
 //
 // The content is detection-driven, which is the ADR-013 shape: the ecosystems
 // listed are the ones this tree actually has a manifest for. Writing an `npm`

package/src/ci/workflow.mjs

@@ -1,6 +1,6 @@
 // The CI gate, as a file a repo owns.
 //
-// `simt-dev check` is the whole gate: projection drift, an unreadable rule, an
+// `simt check` is the whole gate: projection drift, an unreadable rule, an
 // unrunnable gate, a stale manifest. The pre-commit hook runs it locally, which
 // stops one person committing a broken region and stops nobody else - a hook is a
 // developer's machine, and every review is somebody else's. So the same command
@@ -28,7 +28,7 @@
 //     which is why the header says so in the file rather than in this comment.
 //
 // The own copy also RUNS something different, and that is not a variation for taste.
-// `simt-dev check` is red in this repository by design: AGENTS.md here is written by
+// `simt check` is red in this repository by design: AGENTS.md here is written by
 // hand and deliberately never self-adopted (see its own "Why this repository is not
 // self-adopted"), so the check reports it as unmanaged forever. A gate that is red on
 // the day it lands is the one thing worse than no gate - it teaches the reader to
@@ -51,6 +51,7 @@ import { PACKAGE_NAME, WORKFLOW_FILE_NAME } from '../name.mjs';
 import { renderLocator } from '../locate.mjs';
 import { CLI } from '../name.mjs';
 import { packageVersion } from '../package-version.mjs';
+import { LOCAL_BIN, LOCAL_BIN_DIR, assetNameExpr, localInstall, platformLines, releaseBase } from '../distribute/release.mjs';
 
 /** Directory whose presence means this repo runs GitHub Actions. */
 export const WORKFLOWS_DIR = '.github/workflows';
@@ -264,7 +265,7 @@ export function renderWorkflow({ own = false, npm = true, version } = {}) {
         '      - name: tests',
         '        run: npm test',
         '      - name: skill registry lint',
-        '        run: node bin/simt-dev.mjs graph lint',
+        '        run: node bin/simt.mjs graph lint',
         '      - name: the gate copy in this repo is current',
         // The drift this exception exists to prevent, checked where it would be caught.
         // Without it a template change lands with the copy still describing the old
@@ -272,7 +273,7 @@ export function renderWorkflow({ own = false, npm = true, version } = {}) {
         //
         // `--check`, and not the bare command: `ci` previews by default and exits 0,
         // so this step used to print the drift it exists to catch and pass anyway.
-        '        run: node bin/simt-dev.mjs ci --check',
+        '        run: node bin/simt.mjs ci --check',
       ].join('\n'),
       // ADR-012 says CI verifies on macOS and Linux. Until this matrix existed that
       // sentence was false in the one repository that could have made it true, and no
@@ -285,9 +286,19 @@ export function renderWorkflow({ own = false, npm = true, version } = {}) {
   const v = version ?? packageVersion();
   // The install step is the whole of S35's consumer CI: a repository with npm pins
   // simt-dev as a devDependency and `npm ci` restores it; one without (Gradle,
-  // Connect IQ) has no node_modules to pin in, so CI installs the same pinned global
-  // binary the machine remedy names. The two must agree, or the gate passes in one
-  // place and cannot start in the other.
+  // Connect IQ) has no node_modules to pin in, so CI downloads the release binary
+  // into the repository - the same pinned bytes the machine remedy names, verified
+  // against the checksum published beside it. The two must agree, or the gate
+  // passes in one place and cannot start in the other.
+  //
+  // The binary branch needs no setup-node at all: the SEA runs without a Node on
+  // PATH (ADR-098), and installing one to run a file that does not need it would be
+  // the toolchain this channel exists to remove, present in the one place it was not.
+  //
+  // The platform is derived in the shell (platformLines) and not from a
+  // `${{ runner.* }}` expression: an expression substituted into `$( … )` is a
+  // command substitution trying to execute "Linux", which set -eu refuses - the
+  // install would fail on every run in the one repository kind this channel is for.
   const install = npm
     ? [
         '      - name: install dependencies',
@@ -296,19 +307,36 @@ export function renderWorkflow({ own = false, npm = true, version } = {}) {
       ]
     : [
         '      - name: install the pinned gate binary',
-        '        # No node_modules to pin in, so a pinned global install: the same bytes',
-        '        # the machine remedy names, so the gate cannot pass locally and fail here.',
-        `        run: npm i -g ${PACKAGE_NAME}@${v}`,
+        '        # No node_modules to pin in, so the release binary into the repository:',
+        '        # the same bytes the machine remedy names, checked against the',
+        '        # checksum published beside it before anything runs them.',
+        '        run: |',
+        indent(
+          `set -eu
+${platformLines().join('\n')}
+asset="${assetNameExpr(v)}"
+base="${releaseBase(v)}"
+curl -fsSL "$base/$asset" -o "$asset"
+expected=$(curl -fsSL "$base/$asset.sha256" | awk '{print $1}')
+actual=$(openssl sha256 "$asset" | grep -oE '[0-9a-f]{64}')
+if [ "$expected" != "$actual" ]; then
+  echo "checksum mismatch for $asset: the release asset does not match its published sha256" >&2
+  exit 1
+fi
+mkdir -p ${LOCAL_BIN_DIR}
+mv "$asset" ${LOCAL_BIN}
+chmod +x ${LOCAL_BIN}`, 10),
       ];
   const remedy = npm
     ? `REMEDY run: npm i -D ${PACKAGE_NAME}   (the gate runs from the pinned dependency)`
-    : `REMEDY run: npm i -g ${PACKAGE_NAME}@${v}   (the gate runs from a pinned global install)`;
+    : `REMEDY run: ${localInstall(v)}   (the gate runs from the release binary in .simt/bin)`;
   const locator = renderLocator('check --root "$ROOT"', { remedy });
   return `${header(false)}${skeleton(
     `${CLI} check`,
     [
       uses('checkout'),
-      setupNode(nodeFloor()),
+      // The binary branch has no setup-node: see the install step above.
+      ...(npm ? [setupNode(nodeFloor())] : []),
       ...install,
       `      - name: ${CLI} check`,
       '        run: |',

package/src/commands/agenthook.mjs

@@ -1,4 +1,4 @@
-// simt-dev agent-hook <event> | agent-hooks install | agent-hooks status
+// simt agent-hook <event> | agent-hooks install | agent-hooks status
 //
 // Three commands, one subject: the rules the tool projects, enforced while the agent is
 // working rather than when git is committing. `agent-hook` is the entry point a harness
@@ -92,7 +92,11 @@ export async function agentHookCommand(args, flags) {
     return EXIT.OK;
   }
 
-  const { root, command, writes } = factsFrom(row, payload);
+  // `--root` outranks the payload: a packaged hook runs from the plugin directory and the
+  // harness's environment variable names the project, so a payload cwd that is the plugin's
+  // own working directory must not win. The repository-install path passes no flag, and the
+  // payload's cwd is what the harness reports.
+  const { root, command, writes } = factsFrom(row, payload, { root: flags.root });
   const facts = await factsFor(root, { command, writes });
   const decision = decide({ event, facts, env: process.env });