simt-dev 0.7.0 → 0.8.0

package/src/bench/variants.mjs

@@ -18,20 +18,19 @@ import { plan } from '../projection/project.mjs';
 import { isEligible, loadRules, readDeclared, select } from '../projection/rules.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
 import { CANARY_ALPHA, DEFAULT_CANARY_SIZE, DEL_R_TOLERANCE, shouldEscalateCanary } from './ablate.mjs';
+import { evaluateRunRecord, loadPrices } from '../measure/metrics.mjs';
+import { loadRunRecords } from '../measure/records.mjs';
 import {
   DEFAULT_BOOTSTRAP_SAMPLES,
   DEFAULT_BOOTSTRAP_SEED,
   collapseArmByTask,
   compareArms,
-  evaluateRunRecord,
   holmAdjust,
-  loadPrices,
-  loadRunRecords,
-} from './report.mjs';
+} from '../measure/stats.mjs';
 
 /**
  * Harnesses that grade, not answer: `gold` applies the oracle patch and `noop` does
- * nothing (`src/bench/adapters.json`, `kind: "builtin"`). Their runs measure the
+ * nothing (`src/bench/adapters.json`, `kind: "oracle"`). Their runs measure the
  * grader, not the rule text, so they must never close a variant experiment by
  * writing a lock entry (Q45). A test asserts this set matches the adapter table.
  */

package/src/bench/workspace.mjs

@@ -0,0 +1,160 @@
+// Isolated workspaces for a benchmarked run.
+//
+// One base tree is exported per task and copied per run (review 0003 Q78): every arm and
+// repetition used to unpack the same `git archive` again, which made the cost of the
+// harness include the cost of exporting the repository. The copy is a fresh directory
+// with no `.git` of its own until the arm has materialised, so two runs of one task can
+// never see each other's edits.
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { STATE_DIR } from '../name.mjs';
+import { LOCAL_DIR } from '../state.mjs';
+import { sanitizedEnv, spawnBounded } from '../sys/proc.mjs';
+import { materialiseArm } from './arms.mjs';
+
+const DEFAULT_GIT_TIMEOUT_MS = 120_000;
+
+/** Run one bounded child process with a sanitised environment. */
+export function runCmd(cmd, args, { cwd, env, input = null, timeoutMs = DEFAULT_GIT_TIMEOUT_MS } = {}) {
+  return spawnBounded(cmd, args, { cwd, env: sanitizedEnv(env), input, timeoutMs });
+}
+
+/**
+ * Apply a bounded, order-preserving pool over `items`.
+ *
+ * @template T, R
+ * @param {T[]} items
+ * @param {number} concurrency
+ * @param {(item: T, index: number) => Promise<R>} fn
+ * @returns {Promise<R[]>} results in input order
+ */
+export async function mapPool(items, concurrency, fn) {
+  const results = new Array(items.length);
+  let cursor = 0;
+  async function worker() {
+    while (true) {
+      const index = cursor;
+      cursor += 1;
+      if (index >= items.length) return;
+      results[index] = await fn(items[index], index);
+    }
+  }
+  const count = Math.max(1, Math.min(concurrency, items.length));
+  await Promise.all(Array.from({ length: count }, () => worker()));
+  return results;
+}
+
+/**
+ * Export one commit into a fresh directory: the tree every run of a task starts from.
+ *
+ * @param {string} root
+ * @param {string} baseSha
+ * @param {string} parentDir
+ * @returns {Promise<string>} the directory holding the unpacked tree
+ */
+export async function prepareBaseTree(root, baseSha, parentDir) {
+  const baseDir = await mkdtemp(join(parentDir, 'base-'));
+  const archiveRes = await runCmd('git', ['archive', '--format=tar', baseSha], { cwd: root });
+  if (archiveRes.code !== 0) {
+    await rm(baseDir, { recursive: true, force: true }).catch(() => {});
+    throw new Error(`git archive failed for ${baseSha}: ${archiveRes.stderr.toString('utf8').trim()}`);
+  }
+  const tarRes = await runCmd('tar', ['-xf', '-', '-C', baseDir], {
+    cwd: baseDir,
+    input: archiveRes.stdout,
+  });
+  if (tarRes.code !== 0) {
+    await rm(baseDir, { recursive: true, force: true }).catch(() => {});
+    throw new Error(`tar unpack failed for ${baseSha}: ${tarRes.stderr.toString('utf8').trim()}`);
+  }
+  return baseDir;
+}
+
+/**
+ * Create the workspace one run is measured in: the base tree, the arm materialised over
+ * it, one commit, and no tool state.
+ *
+ * @param {string} root
+ * @param {string} baseSha
+ * @param {object} armSpec
+ * @param {object} [task]
+ * @param {{parentDir?: string, baseDir?: string}} [options]
+ * @returns {Promise<{slotDir: string, workDir: string, initialHead: string,
+ *   env: Record<string, string>, promptPrefix: string}>}
+ */
+export async function prepareIsolatedWorkspace(root, baseSha, armSpec, task = {}, { parentDir, baseDir } = {}) {
+  const slotDir = await mkdtemp(join(parentDir ?? tmpdir(), 'bench-run-'));
+  const workDir = join(slotDir, 'workspace');
+  await mkdir(workDir, { recursive: true });
+
+  if (baseDir) {
+    const copied = await runCmd('cp', ['-a', `${baseDir}/.`, workDir], { cwd: workDir });
+    if (copied.code !== 0) {
+      await rm(slotDir, { recursive: true, force: true }).catch(() => {});
+      throw new Error(`copying the base tree failed for ${baseSha}: ${copied.stderr.toString('utf8').trim()}`);
+    }
+  } else {
+    const archiveRes = await runCmd('git', ['archive', '--format=tar', baseSha], { cwd: root });
+    if (archiveRes.code !== 0) {
+      await rm(slotDir, { recursive: true, force: true }).catch(() => {});
+      throw new Error(`git archive failed for ${baseSha}: ${archiveRes.stderr.toString('utf8').trim()}`);
+    }
+    const tarRes = await runCmd('tar', ['-xf', '-', '-C', workDir], { cwd: workDir, input: archiveRes.stdout });
+    if (tarRes.code !== 0) {
+      await rm(slotDir, { recursive: true, force: true }).catch(() => {});
+      throw new Error(`tar unpack failed for ${baseSha}: ${tarRes.stderr.toString('utf8').trim()}`);
+    }
+  }
+
+  // Lessons and local profiles live outside the archived commit, so an adopted
+  // repository's memory reaches the arm without being written into its base tree.
+  const rootLessonsDir = join(root, 'docs', 'lessons');
+  const rootLessonFiles = (await readdir(rootLessonsDir).catch(() => [])).filter((f) => f.endsWith('.md'));
+  if (rootLessonFiles.length > 0) {
+    const destLessonsDir = join(workDir, 'docs', 'lessons');
+    await mkdir(destLessonsDir, { recursive: true });
+    for (const file of rootLessonFiles) {
+      const target = join(destLessonsDir, file);
+      if (!existsSync(target)) {
+        await writeFile(target, await readFile(join(rootLessonsDir, file), 'utf8'), 'utf8');
+      }
+    }
+  }
+
+  const rootProfilesDir = join(root, STATE_DIR, 'profiles');
+  const rootProfileFiles = (await readdir(rootProfilesDir).catch(() => [])).filter((f) => f.endsWith('.md'));
+  if (rootProfileFiles.length > 0) {
+    const destProfilesDir = join(workDir, STATE_DIR, 'profiles');
+    await mkdir(destProfilesDir, { recursive: true });
+    for (const file of rootProfileFiles) {
+      await writeFile(join(destProfilesDir, file), await readFile(join(rootProfilesDir, file), 'utf8'), 'utf8');
+    }
+  }
+
+  await runCmd('git', ['init', '-q'], { cwd: workDir });
+  await runCmd('git', ['config', 'user.name', 'bench'], { cwd: workDir });
+  await runCmd('git', ['config', 'user.email', 'bench@local'], { cwd: workDir });
+  await runCmd('git', ['config', 'commit.gpgsign', 'false'], { cwd: workDir });
+
+  // The repository exists before an arm materialises: the `brief` arm assembles its
+  // packet from git's answer, which a directory that is not yet a repository cannot give.
+  const { env, promptPrefix } = await materialiseArm(workDir, armSpec, task);
+  // Assembling a packet writes tool state. It belongs to no arm, and leaving it in the
+  // base commit would make the `brief` workspace differ by an index as well as by context.
+  await rm(join(workDir, LOCAL_DIR), { recursive: true, force: true }).catch(() => {});
+
+  await runCmd('git', ['add', '-A'], { cwd: workDir });
+  const commitRes = await runCmd('git', ['commit', '-qm', 'base', '--allow-empty', '--no-verify'], {
+    cwd: workDir,
+  });
+  if (commitRes.code !== 0) {
+    await rm(slotDir, { recursive: true, force: true }).catch(() => {});
+    throw new Error(`git commit failed in isolated workspace: ${commitRes.stderr.toString('utf8').trim()}`);
+  }
+
+  const headRes = await runCmd('git', ['rev-parse', 'HEAD'], { cwd: workDir });
+  return { slotDir, workDir, initialHead: headRes.stdout.toString('utf8').trim(), env, promptPrefix };
+}

package/src/brief/assemble.mjs

@@ -34,7 +34,10 @@
 // command and the tool leave it on. It is inert either way in a repository that declared no
 // servers.
 
+import { join } from 'node:path';
+
 import { CLI, STATE_DIR } from '../name.mjs';
+import { parse as parseRegion } from '../projection/markers.mjs';
 import { DEFAULT_BRIEF_BYTES, buildPacket, collect } from './packet.mjs';
 import { classifyTask, cardVerbs } from './kind.mjs';
 import { briefAdvice } from '../advice/advice.mjs';
@@ -42,15 +45,17 @@ import { commandCard } from '../kernel/card.mjs';
 import { decisionHits, scopeHits, sourceRoots } from '../index/govern.mjs';
 import { embedTaskQuery, rankFiles, renderMap } from '../index/map.mjs';
 import { searchFtsBm25 } from '../index/store.mjs';
-import { testEdges, testsFor } from '../index/tests.mjs';
+import { coverage } from '../index/coverage.mjs';
 import { loadRegistry } from '../graph/load.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
-import { closure, rankSkills, selectWithinBudget, tokenize } from '../resolve/resolve.mjs';
+import { closure, rankSkills, selectWithinBudget } from '../resolve/resolve.mjs';
+import { tokenize } from '../text/tokens.mjs';
 import { loadGraph } from '../commands/map.mjs';
 import { dirtyPaths, parsePathList } from '../commands/skills.mjs';
 import { decisionRecords, lessonScopes } from '../commands/why.mjs';
 import { readFederation } from '../federation/config.mjs';
 import { consult } from '../federation/query.mjs';
+import { gitText } from '../sys/git.mjs';
 
 /**
  * How many ranked files the packet may consider as candidates for other sections.
@@ -81,22 +86,32 @@ const MAP_FACTOR = 8;
  * space is never part of a task's scope.
  */
 
-/** Every file git tracks that carries a generated region, one `git grep` away. */
+/**
+ * Every file git tracks that carries a generated region, one `git grep` away.
+ *
+ * A file that merely mentions the marker is not carrying a region: a rule file, a review
+ * and this test all quote `simt:begin`, and warning that they are generated sends a reader
+ * to edit a source file that has no generated bytes at all (review 0003 Q52). The grep is
+ * only the candidate list; the region parser decides.
+ */
 async function generatedRegions(root) {
-  const { execFile } = await import('node:child_process');
-  const { promisify } = await import('node:util');
+  const { readFile } = await import('node:fs/promises');
+  let candidates;
   try {
-    const { stdout } = await promisify(execFile)(
-      'git',
-      ['grep', '-lF', '--', `${'simt'}:begin`],
-      { cwd: root, maxBuffer: 8 << 20 },
-    );
-    return stdout.split('\n').filter((line) => line.length > 0).sort();
+    const stdout = await gitText(root, ['grep', '-lF', '--', `${'simt'}:begin`], { maxBuffer: 8 << 20 });
+    candidates = (stdout ?? '').split('\n').filter((line) => line.length > 0).sort();
   } catch {
     // No match is exit 1, and a directory that is not a repository fails too. Both mean
     // the same thing to a reader: no generated region was found to warn about.
     return [];
   }
+  const carrying = [];
+  for (const path of candidates) {
+    const text = await readFile(join(root, path), 'utf8').catch(() => null);
+    if (text === null) continue;
+    if (parseRegion(text, 'html').status === 'ok') carrying.push(path);
+  }
+  return carrying;
 }
 
 /**
@@ -113,6 +128,9 @@ async function generatedRegions(root) {
  * @param {boolean} [options.build] whether an empty index may be built here
  * @param {boolean} [options.federate] whether a declared external server may be asked one
  *   question; a delivered packet turns it off to keep its 300 ms bar
+ * @param {string[]} [options.commands] the dispatchable command paths (`COMMANDS`). A
+ *   decision's `Affects:` token is a command only when the tool has that command, so a
+ *   packet that does not know them reports every one of them as unresolved
  * @returns a packet, or `{ error }` carrying the exit code a failure already reported, or
  *   `{ cold: true }` when the index is empty and this caller may not build one
  */
@@ -124,12 +142,13 @@ export async function assembleBrief({
   flags = {},
   build = true,
   federate = true,
+  commands = [],
 } = {}) {
   const named = paths !== null;
   const dirty = (await dirtyPaths(root)).filter((path) => !path.startsWith(`${STATE_DIR}/`));
   const scope = named ? parsePathList(paths) : dirty;
 
-  const graph = await loadGraph(root, { build });
+  const graph = await loadGraph(root, { build, task, embed: flags?.embed === true });
   if (graph.error) return { error: graph.error };
   if (graph.cold) return { cold: true };
   const graphStale = graph.stale === true;
@@ -187,6 +206,15 @@ export async function assembleBrief({
         })
       : null;
   const ranked = rankFiles({ files, symbols, edges, fts, bm25, embeddings, queryVector, task });
+  // An empty match is a different answer from a weak one: the ranking is then the graph
+  // hub, which is what a reader who asked about `zebracorn` must not read as a hit
+  // (review 0003 Q52).
+  const matched = ranked.filter((row) => (row.score ?? 0) > 0).length;
+  if (task.trim().length > 0 && matched === 0) {
+    packet.add('CAUTIONS', 'matched 0: no file or symbol mentions this task, so FILES is the graph hub rather than a match', {
+      why: ['an answer to a graph-shaped question is not an answer to this task'],
+    });
+  }
   const rendered = renderMap(ranked, symbols, { level: 'names', budget: budget > 0 ? budget * MAP_FACTOR : 0 });
   for (const line of rendered.text.split('\n')) {
     packet.add('FILES', line, { why: ['ranked by the task words against the import graph'] });
@@ -219,13 +247,15 @@ export async function assembleBrief({
   }
 
   const likely = ranked.slice(0, LIKELY_FILES).map((row) => row.path);
-  const known = testEdges({ files, imports: edges.filter((edge) => edge.kind === 'import') });
   const untested = [];
   packet.add('TESTS', `the index knows direct importers; \`${CLI} tests <path>\` is the authority for multi-line and dynamic imports`, {
     why: ['a cheap packet and an exact answer are different questions'],
   });
   for (const path of likely) {
-    const found = testsFor(path, known);
+    // The packet's own edges, walked by the same function `tests` uses (Q77).
+    const found = coverage({ files, imports: edges.filter((edge) => edge.kind === 'import') }, [path], {
+      transitive: false,
+    });
     if (found.length === 0) untested.push(path);
     else packet.add('TESTS', `${path} -> ${found.join(' ')}`, { why: ['the test imports it, or sits beside it'] });
   }
@@ -233,7 +263,10 @@ export async function assembleBrief({
   const records = await decisionRecords(root);
   const ctx = {
     files: filePaths,
-    commands: new Set(card.lines.map((line) => line.command)),
+    // The card's lines are shell commands (`npm run test`); a decision's Affects token is
+    // a command of this tool. Passing only the card's list made every `simt …` token
+    // unresolved — 47 false cautions on this repository (review 0003 Q52).
+    commands: new Set([...card.lines.map((line) => line.command), ...commands]),
     roots: sourceRoots([...filePaths]),
   };
   const decisions = new Map();

package/src/ci/dependabot.mjs

@@ -40,61 +40,30 @@ import { join } from 'node:path';
 import { fingerprint } from '../resolve/fingerprint.mjs';
 import { isOwnRepo, WORKFLOWS_DIR } from './workflow.mjs';
 import { CLI } from '../name.mjs';
+// Q70: the Dependabot entries are the records' `dependabot` facet, not a table in this
+// file. Adding an ecosystem is a new file under `ecosystems/`, not a row here.
+import { dependabotEntries } from '../ecosystem/records.mjs';
 
 /** The one file this module writes. */
 export const DEPENDABOT_FILE = '.github/dependabot.yml';
 
 /**
- * fact -> the `package-ecosystem` value Dependabot documents for it.
+ * fact/stack -> the `package-ecosystem` value Dependabot documents for it.
  *
- * The fact names are already in the fingerprint vocabulary and already carry
- * evidence, so this table adds no new observation vocabulary: it says which
- * Dependabot value watches which observable manifest. Facts absent from this
- * table are not ecosystems Dependabot updates, and adding one is a new ruling
- * about the estate rather than a code detail.
+ * Read from the ecosystem records (ADR-013: content is data, the engine is code), not
+ * written here. `dependabotEntries(root)` returns the rows in their declared order; `root`
+ * lets a repository's own `.simt/ecosystems/` supply an entry the shipped set does not have,
+ * so adding an ecosystem is a new file, not a row in a table the engine edits.
  *
- * Several facts map to one value on purpose. `has-pyproject` and
- * `has-requirements` are two ways of declaring python dependencies and
- * Dependabot reads both under `pip`; emitting two `pip` entries would be a
- * duplicate the config rejects or silently collapses, and the reader would have
- * no way to tell which one won.
- *
- * A `stack` tag is used where no fact exists and one is needed. npm is the
- * clearest case: `node` is a stack tag in `fingerprint.mjs` and `typescript` is
- * a dependency name, so a repo's package manager is either of those and adding
- * `has-node-manifest` would be a third name for one observation - the exact
- * duplication that table's own header rules out. `gradle` is the same shape:
- * the stack tag already names the build file. Every other entry below is a
- * real `has-*` fact.
- *
- * `has-build-system` is deliberately NOT mapped: Makefile, CMakeLists and
- * meson.build are build files, not dependency manifests, and Dependabot has no
- * ecosystem that reads them. Mapping it to `maven` would be a lie of exactly the
- * kind the detection-driven ruling exists to prevent.
+ * The fact names are already in the fingerprint vocabulary and already carry evidence, so
+ * the records add no new observation vocabulary: each entry says which Dependabot value
+ * watches which observable manifest. Several facts map to one value on purpose — `has-pyproject`
+ * and `has-requirements` are two ways of declaring python dependencies and Dependabot reads
+ * both under `pip`; emitting two `pip` entries would be a duplicate the config rejects. A
+ * `stack` tag stands in where no fact exists (`node`, `gradle`). `has-build-system` is
+ * deliberately NOT mapped: Makefile, CMakeLists and meson.build are build files, not
+ * dependency manifests, and Dependabot has no ecosystem that reads them.
  */
-const ECOSYSTEMS = [
-  { stack: 'node', value: 'npm', manifest: 'package.json' },
-  { stack: 'typescript', value: 'npm', manifest: 'package.json' },
-  { fact: 'has-pyproject', value: 'pip', manifest: 'pyproject.toml' },
-  { fact: 'has-requirements', value: 'pip', manifest: 'requirements.txt' },
-  { fact: 'has-go-mod', value: 'gomod', manifest: 'go.mod' },
-  { fact: 'has-cargo-toml', value: 'cargo', manifest: 'Cargo.toml' },
-  { fact: 'has-gemfile', value: 'bundler', manifest: 'Gemfile' },
-  { fact: 'has-composer', value: 'composer', manifest: 'composer.json' },
-  { fact: 'has-maven-pom', value: 'maven', manifest: 'pom.xml' },
-  { fact: 'has-dockerfile', value: 'docker', manifest: 'Dockerfile' },
-  { fact: 'has-compose', value: 'docker-compose', manifest: 'compose file' },
-  { fact: 'has-terraform', value: 'terraform', manifest: '*.tf' },
-  { stack: 'gradle', value: 'gradle', manifest: 'build.gradle' },
-  { fact: 'has-submodules', value: 'gitsubmodule', manifest: '.gitmodules' },
-  { fact: 'has-nuget', value: 'nuget', manifest: '*.csproj' },
-  { fact: 'has-pubspec', value: 'pub', manifest: 'pubspec.yaml' },
-  { fact: 'has-swift-package', value: 'swift', manifest: 'Package.swift' },
-  { fact: 'has-mix', value: 'mix', manifest: 'mix.exs' },
-  { fact: 'has-uv-lock', value: 'uv', manifest: 'uv.lock' },
-  { fact: 'has-bun-lock', value: 'bun', manifest: 'bun.lock' },
-  { fact: 'has-devcontainer', value: 'devcontainers', manifest: 'devcontainer.json' },
-];
 
 /**
  * The ecosystems this tree has a manifest for, in a stable order.
@@ -108,11 +77,11 @@ const ECOSYSTEMS = [
  * @param {Iterable<string>} [stack] emitted stack tags
  * @returns {{value: string, manifest: string}[]}
  */
-export function ecosystems(facts, stack = []) {
+export function ecosystems(facts, stack = [], root = null) {
   const seenFacts = new Set(facts);
   const seenStack = new Set(stack);
   const out = [];
-  for (const row of ECOSYSTEMS) {
+  for (const row of dependabotEntries(root)) {
     const found = row.fact ? seenFacts.has(row.fact) : seenStack.has(row.stack);
     if (!found || out.some((e) => e.value === row.value)) continue;
     out.push({ value: row.value, manifest: row.manifest });
@@ -174,8 +143,8 @@ function entry({ value }) {
  * @param {{stack?: Iterable<string>, own?: boolean}} [options]
  * @returns {string} YAML, LF-terminated
  */
-export function renderDependabot(facts, { stack = [], own = false } = {}) {
-  const found = ecosystems(facts, stack);
+export function renderDependabot(facts, { stack = [], own = false, root = null } = {}) {
+  const found = ecosystems(facts, stack, root);
   const entries = [entry({ value: 'github-actions' }), ...found.map(entry)];
   return `${header(own)}version: 2
 updates:
@@ -221,18 +190,19 @@ export async function planDependabot(root) {
   // "the file differs" instead of "the file differs from what this repo should get",
   // and those are different questions when a manifest appeared since.
   const { facts, stack } = await fingerprint(root);
-  const watched = ecosystems(facts, stack).map((e) => e.value);
+  const watched = ecosystems(facts, stack, root).map((e) => e.value);
   // Carried on the plan so the writer renders from the same observation this
   // comparison used. Re-detecting at write time would make `ci` and `check`
   // disagree whenever a manifest appeared between the two calls, and the file
-  // would be written from facts nobody ever saw in the plan.
-  const detection = { facts, stack };
+  // would be written from facts nobody ever saw in the plan. `root` rides along so
+  // the writer renders the records a repository's own `.simt/ecosystems/` overrides.
+  const detection = { facts, stack, root };
 
   if (exists) {
     // Both sides of the comparison, for the same reason as the workflow plan: a reader
     // told the file differs can be shown how, and re-rendering for a diff would let
     // the two answers disagree.
-    const desired = renderDependabot(facts, { stack, own: true });
+    const desired = renderDependabot(facts, { stack, own: true, root });
     const current = own ? text === desired : true;
     return {
       file: DEPENDABOT_FILE,

package/src/ci/workflow.mjs

@@ -167,7 +167,7 @@ function checkoutFull() {
  *  to. The own gate also varies the platforms and the Node versions, because this
  *  package is the one whose floor and whose ADR-012 claim have to hold on more than
  *  the minimum. */
-function skeleton(name, steps, { matrix = null } = {}) {
+function skeleton(name, steps, { matrix = null, timeoutMinutes = 5, gateMain = false } = {}) {
   const axes = matrix
     ? Object.entries(matrix)
         .map(([axis, values]) => `        ${axis}: [${values.map((v) => `'${v}'`).join(', ')}]`)
@@ -182,9 +182,22 @@ function skeleton(name, steps, { matrix = null } = {}) {
   // it is written escaped, the same way the `concurrency` line below spells its own two.
   const runner = matrix?.os ? '\${{ matrix.os }}' : 'ubuntu-latest';
   const job = matrix?.node ? '\${{ matrix.os }} node \${{ matrix.node }}' : name;
-  return `name: ${name}
-
-# Pull requests only, and that is a decision rather than a default.
+  // Two trigger blocks, because the two copies answer different questions. An
+  // adopting repository merges through pull requests, which is where its gate runs.
+  // This repository merges locally, so a merge never opens a pull request: without a
+  // push trigger the commit that lands on `main` is the one no gate ever ran on
+  // (review 0003 Q57). Each block ships only in the copy whose claim it states.
+  const trigger = gateMain
+    ? `# Pull requests ask whether a change may merge; a push to \`main\` asks whether
+# what already merged is sound. This repository merges locally, so a merge never
+# opens a pull request — without the second trigger the commit that lands on
+# \`main\` is the one no gate ran on.
+on:
+  pull_request:
+  push:
+    branches: [main]
+`
+    : `# Pull requests only, and that is a decision rather than a default.
 #
 # A gate that runs on every push re-runs itself for every commit that pushes a
 # branch forward, including the ones nobody asked it about, and its verdict has to
@@ -194,7 +207,10 @@ function skeleton(name, steps, { matrix = null } = {}) {
 # on \`main\` is whatever CI the repository already has there.
 on:
   pull_request:
+`;
+  return `name: ${name}
 
+${trigger}
 # Read-only is enough to check a repo, and a gate job does not need to write to it.
 permissions:
   contents: read
@@ -207,7 +223,7 @@ jobs:
   check:
     name: ${job}
     runs-on: ${runner}
-${strategy}    timeout-minutes: 5
+${strategy}    timeout-minutes: ${timeoutMinutes}
     steps:
 ${steps}`;
 }
@@ -268,7 +284,7 @@ export function renderWorkflow({ own = false, npm = true, manager = null, versio
         '      - name: tests',
         '        run: npm test',
         '      - name: skill registry lint',
-        '        run: node bin/simt.mjs graph lint',
+        '        run: npm run 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
@@ -282,7 +298,14 @@ export function renderWorkflow({ own = false, npm = true, manager = null, versio
       // sentence was false in the one repository that could have made it true, and no
       // check read it - the package declares `os` for npm to enforce, and nothing here
       // ever ran a test on a second platform.
-      { matrix: { os: ['ubuntu-latest', 'macos-latest'], node: [floor, '24', '26'] } },
+      // The slowest leg (macOS, full suite plus the registry lint) ran 4 min 28 s
+      // against a 5-minute timeout, so the timeout that was meant to bound a hang
+      // was about to fail a passing run instead. 15 leaves the hang bounded and the
+      // run alone; the sharding that would make it short again is Q92, not this row.
+      //
+      // `gateMain` because this repository merges locally: `pull_request` alone left
+      // the one commit that reached `main` ungated (review 0003 Q57).
+      { matrix: { os: ['ubuntu-latest', 'macos-latest'], node: [floor, '24', '26'] }, timeoutMinutes: 15, gateMain: true },
     )}\n`;
   }
 

package/src/cli.mjs

@@ -0,0 +1,45 @@
+// The CLI proper, imported by `bin/simt.mjs` after the runtime floor is checked.
+//
+// It lives here rather than in `bin/` because a static import in the entry point is
+// evaluated before the entry point's own code: the version check could not run first,
+// and an old Node failed inside the module graph instead of saying which version it
+// needed (review 0003 Q54).
+
+import { parse, rawJsonFlag } from './argv.mjs';
+import { EXIT, fail, jsonFailMode, jsonIndentDefault } from './output/index.mjs';
+
+try {
+  const argv = process.argv.slice(2);
+  const parsed = parse(argv);
+  if (!parsed.ok) {
+    // The flags do not exist yet, so the JSON mode is read off the raw words:
+    // a parse failure under `--json` is a JSON document on stdout, not text on
+    // stderr with an empty stdout (Q11, ADR-070 ruling 4).
+    jsonFailMode(rawJsonFlag(argv));
+    process.exit(fail(parsed.error.message, parsed.error.code));
+  }
+  const { flags, positional } = parsed.value;
+
+  // Set before anything can fail: `no command given` under `--json` is a JSON
+  // document too, and a failure that prints as text with an empty stdout breaks
+  // the same ruling the parse failure above honours (Q11, ADR-070 ruling 4).
+  jsonIndentDefault(flags.pretty === true);
+  jsonFailMode(flags.json === true);
+
+  // No arguments at all is a usage error, not a silent help dump: an agent that
+  // ran the wrong thing should be told so rather than handed 40 lines of prose.
+  if (positional.length === 0 && !flags.help && !flags.version) {
+    process.exit(fail('no command given', EXIT.USAGE));
+  }
+
+  const { dispatch } = await import('./commands/index.mjs');
+  const code = (await dispatch(argv)) ?? EXIT.OK;
+  // Assigned, not forced: a large document on stdout (a `--json --diff` over a
+  // skill-sized body exceeds the 64 KiB pipe buffer) is still draining when the
+  // command resolves, and `process.exit()` cuts it — exit 0 with half a JSON
+  // document on stdout. Letting the loop empty first makes the exit honest
+  // (plan 0003 R50; the S10 contract asserts the document parses).
+  process.exitCode = code;
+} catch (error) {
+  process.exit(fail(error?.message ?? String(error), EXIT.FAIL));
+}

package/src/commands/agent.mjs

@@ -10,7 +10,6 @@
 // parse that can fail and no partial state, which is what makes this command
 // shorter than `agent-hooks install`.
 
-import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { commitJournal } from '../journal.mjs';
@@ -27,9 +26,11 @@ import {
   rendered,
   writeAgentPlan,
 } from '../agents/render.mjs';
+import { commandRoot } from '../repo-root.mjs';
+import { readIfExists } from '../util/fs.mjs';
 
 export async function agentsCommand(sub, args, flags) {
-  const root = flags.root ?? args[0] ?? process.cwd();
+  const root = commandRoot(flags, args);
   if (sub === 'install') return installAgents(root, flags);
   if (sub === 'status') return agentsStatus(root, flags);
   return fail(`unknown agents subcommand ${sub}`, EXIT.USAGE, `run: ${CLI} agents status`);
@@ -102,7 +103,6 @@ async function installAgents(root, flags) {
         '',
         `PLAN     nothing written; apply with: ${CLI} agents install --yes`,
       ].join('\n'),
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     // After the report: the report says what, the diff shows it (R50).
     emitDiffs(diffs, flags);
@@ -135,7 +135,6 @@ async function installAgents(root, flags) {
       '',
       `WROTE    ${written.length} agent file(s)`,
     ].join('\n'),
-    { maxBytes: flags.maxBytes ?? 0 },
   );
   // After the report: the report says what, the diff shows it (R50).
   emitDiffs(diffs, flags);
@@ -193,14 +192,6 @@ async function agentsStatus(root, flags) {
     lines.push('', 'problems:');
     for (const p of problems) lines.push(`  ${p}`);
   }
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return problems.length === 0 ? EXIT.OK : EXIT.FAIL;
 }
-
-async function readIfExists(path) {
-  try {
-    return await readFile(path, 'utf8');
-  } catch {
-    return null;
-  }
-}