simt-dev 0.7.1 → 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

@@ -45,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.
@@ -93,17 +95,11 @@ const MAP_FACTOR = 8;
  * 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 },
-    );
-    candidates = 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.
@@ -152,7 +148,7 @@ export async function assembleBrief({
   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;
@@ -251,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'] });
   }

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/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';
@@ -28,6 +27,7 @@ import {
   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 = commandRoot(flags, args);
@@ -195,11 +195,3 @@ async function agentsStatus(root, flags) {
   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;
-  }
-}

package/src/commands/agenthook.mjs

@@ -25,7 +25,8 @@
 import { existsSync } from 'node:fs';
 import { mkdir, readFile } from 'node:fs/promises';
 import { dirname, isAbsolute, join } from 'node:path';
-import { commitJournal, journaledWriteFile } from '../journal.mjs';
+import { commitJournal } from '../journal.mjs';
+import { applyPlan, change } from '../write/plan.mjs';
 import { AGENT_HOOK_SHIM, renderAgentHookShim } from '../agenthooks/shim.mjs';
 import { diffField, emitDiffs, readBefore } from '../diff.mjs';
 
@@ -179,18 +180,26 @@ export async function agentHooksCommand(sub, args, flags) {
 // `skipped` was an adapter the caller did not ask for (ADR-107).
 const OTHER_LABEL = { none: 'NO FILE ', other: 'NOT OURS', skipped: 'SKIPPED ' };
 
-async function installHooks(root, flags) {
-  const mode = writeMode(flags);
+/**
+ * The agent-hooks install, split from `installHooks` into the plan and the apply so
+ * `init` can run the same writes inside its own journal (ADR-002: a second real use).
+ *
+ * The plan is pure: it reads each documented config, renders the entry, and returns the
+ * shim the same way, so a preview and an apply describe the same set of files. A config
+ * this tool cannot parse lands in `refused` with its action set to `refused`, and the
+ * caller decides what that means — this command blocks on it, and `init` inherits the
+ * refusal because writing the other configs while one is unreadable would leave the
+ * repository in a state where the report it printed is no longer true.
+ */
+export async function planAgentHooks(root, { harness }) {
   // `--harness` narrows the install to one reader (ADR-107). The id is validated
   // against the same table the loop reads, so a typo fails before anything is
   // planned; the remedy names the ids the way `agent-hook` does.
-  const selected = flags.harness;
-  if (selected !== undefined && adapter(selected) === null) {
-    return fail(
-      `unknown harness \`${selected}\``,
-      EXIT.USAGE,
-      `--harness <id>, one of: ${adapters().map((a) => a.id).join(', ')}`,
-    );
+  if (harness !== undefined && adapter(harness) === null) {
+    return {
+      error: `unknown harness \`${harness}\``,
+      remedy: `--harness <id>, one of: ${adapters().map((a) => a.id).join(', ')}`,
+    };
   }
   // The delivery is a second entry in the same config, and a repository asks for it by
   // declaring a `brief` key rather than by having the entry. Read through a dynamic
@@ -202,7 +211,7 @@ async function installHooks(root, flags) {
     listPromotedLessons(root).catch(() => []),
   ]);
   const hasLessons = promotedLessons.length > 0;
-  const rows = selected === undefined ? adapters() : adapters().filter((r) => r.id === selected);
+  const rows = harness === undefined ? adapters() : adapters().filter((r) => r.id === harness);
   const plan = [];
   for (const row of rows) {
     const path = hookPath(row.id);
@@ -232,7 +241,7 @@ async function installHooks(root, flags) {
   for (const r of hookRows()) {
     if (r.path === null) others.push({ id: r.id, path: null, state: 'none', note: r.note });
     else if (adapter(r.id) === null) others.push({ id: r.id, path: r.path, state: 'other', note: r.note });
-    else if (selected !== undefined && r.id !== selected) {
+    else if (harness !== undefined && r.id !== harness) {
       others.push({ id: r.id, path: r.path, state: 'skipped', note: 'not requested; install without --harness to write every harness' });
     }
   }
@@ -240,13 +249,48 @@ async function installHooks(root, flags) {
   const refused = plan.filter((p) => p.error);
 
   // The shim every harness config points at: without it the entries above name a
-  // binary no harness has on PATH (review 0003 Q21). Its remedy installs the
-  // dependency the same way the git shims' does — a devDependency where the
-  // repository has a package.json, the release binary where it does not.
+  // binary no harness has on PATH (review 0003 Q21).
   const shimText = renderAgentHookShim({ npm: (await readIfExists(join(root, 'package.json'))) !== null });
   const shimBefore = await readBefore(join(root, AGENT_HOOK_SHIM));
   const shimAction = shimBefore === null ? 'create' : shimBefore === shimText ? 'unchanged' : 'update';
-  const shimRow = { id: 'shim', path: AGENT_HOOK_SHIM, action: shimAction };
+  const shim = { text: shimText, before: shimBefore, action: shimAction, row: { id: 'shim', path: AGENT_HOOK_SHIM, action: shimAction } };
+
+  return { plan, shim, others, promptLine, refused };
+}
+
+/**
+ * Write the planned agent-hooks entries and the shim into the caller's journal. Nothing
+ * is committed here: the caller commits its own journal under its own label, which is
+ * what separates this command's run (a standalone `agent-hooks install`) from `init`'s
+ * absorbed one (part of the adoption, committed with the rest of it).
+ */
+export async function applyAgentHooks(root, journal, { plan, shim, owner }) {
+  const written = [];
+  const hookChanges = [];
+  for (const p of plan.filter((x) => x.action !== 'unchanged')) {
+    const path = join(root, p.path);
+    hookChanges.push(change({ path, before: await readBefore(path), after: p.text, owner, reason: p.action }));
+    written.push(p);
+  }
+  // The shim is a file like the configs: unchanged installs leave it alone, and a
+  // changed one is journaled so `undo` removes or restores it with the configs.
+  let shimWritten = false;
+  if (shim.action !== 'unchanged') {
+    const shimPath = join(root, AGENT_HOOK_SHIM);
+    hookChanges.push(change({ path: shimPath, before: await readBefore(shimPath), after: shim.text, owner, reason: shim.action, mode: 0o755 }));
+    shimWritten = true;
+  }
+  await applyPlan(root, hookChanges, { mode: { apply: true }, journal, commit: false });
+  return { written, shimWritten };
+}
+
+async function installHooks(root, flags) {
+  const mode = writeMode(flags);
+  const planned = await planAgentHooks(root, { harness: flags.harness });
+  if (planned.error) {
+    return fail(planned.error, EXIT.USAGE, planned.remedy);
+  }
+  const { plan, shim, others, promptLine, refused } = planned;
 
   // The `--diff` pairs, read before anything is written so the before side is
   // true in preview and in apply alike (R50).
@@ -256,7 +300,7 @@ async function installHooks(root, flags) {
         plan
           .filter((p) => p.action !== 'unchanged')
           .map(async (p) => ({ path: p.path, before: await readBefore(join(root, p.path)), after: p.text }))
-          .concat(shimAction === 'unchanged' ? [] : [{ path: AGENT_HOOK_SHIM, before: shimBefore, after: shimText }]),
+          .concat(shim.action === 'unchanged' ? [] : [{ path: AGENT_HOOK_SHIM, before: shim.before, after: shim.text }]),
       )
       : [];
 
@@ -268,7 +312,7 @@ async function installHooks(root, flags) {
         root,
         dryRun: true,
         plan: plan.map(({ text, ...rest }) => rest),
-        shim: shimRow,
+        shim: shim.row,
         notWritten: others,
         filesWritten: false,
         ...diffField(diffs, flags),
@@ -279,7 +323,7 @@ async function installHooks(root, flags) {
       [
         `repo     ${root}`,
         ...plan.map((p) => `${p.action.toUpperCase().padEnd(9)} ${p.id.padEnd(12)} ${p.path}${p.error ? `  (${p.error})` : ''}`),
-        `${shimAction.toUpperCase().padEnd(9)} shim         ${AGENT_HOOK_SHIM}`,
+        `${shim.action.toUpperCase().padEnd(9)} shim         ${AGENT_HOOK_SHIM}`,
         ...others.map((o) => `${OTHER_LABEL[o.state]} ${o.id.padEnd(12)} ${o.path ?? '(no hooks file is documented)'}`),
         ...promptLine,
         '',
@@ -302,20 +346,7 @@ async function installHooks(root, flags) {
 
   // Journaled so `undo` restores this run (R49).
   const journal = [];
-  const written = [];
-  for (const p of plan.filter((x) => x.action !== 'unchanged')) {
-    await mkdir(join(root, dirname(p.path)), { recursive: true });
-    await journaledWriteFile(root, journal, join(root, p.path), p.text);
-    written.push(p);
-  }
-  // The shim is a file like the configs: unchanged installs leave it alone, and a
-  // changed one is journaled so `undo` removes or restores it with the configs.
-  let shimWritten = false;
-  if (shimAction !== 'unchanged') {
-    await mkdir(join(root, dirname(AGENT_HOOK_SHIM)), { recursive: true });
-    await journaledWriteFile(root, journal, join(root, AGENT_HOOK_SHIM), shimText, { mode: 0o755 });
-    shimWritten = true;
-  }
+  const { written, shimWritten } = await applyAgentHooks(root, journal, { plan, shim, owner: 'agent-hooks install' });
   await commitJournal(root, 'agent-hooks install', journal);
 
   const notes = [];
@@ -331,7 +362,7 @@ async function installHooks(root, flags) {
       command: 'agent-hooks install',
       root,
       plan: plan.map(({ text, ...rest }) => rest),
-      shim: { ...shimRow, written: shimWritten },
+      shim: { ...shim.row, written: shimWritten },
       notWritten: others,
       written: written.map((p) => p.path),
       filesWritten: true,
@@ -344,7 +375,7 @@ async function installHooks(root, flags) {
     [
       `repo     ${root}`,
       ...plan.map((p) => `${p.action.toUpperCase().padEnd(9)} ${p.id.padEnd(12)} ${p.path}`),
-      `${shimAction.toUpperCase().padEnd(9)} shim         ${AGENT_HOOK_SHIM}`,
+      `${shim.action.toUpperCase().padEnd(9)} shim         ${AGENT_HOOK_SHIM}`,
       ...others.map((o) => `${OTHER_LABEL[o.state]} ${o.id.padEnd(12)} ${o.path ?? '(no hooks file is documented)'}`),
       ...promptLine,
       '',

package/src/commands/bench.mjs

@@ -11,7 +11,7 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { CLI } from '../name.mjs';
 import { EXIT, emit, emitJson, fail, isJson, writeMode } from '../output/index.mjs';
 import { DEFAULT_MINE_TARGET, mineTasks } from '../bench/mine.mjs';
-import { buildCorpusDocument, verifyCorpusDocument, writeCorpusDocument } from '../bench/corpus.mjs';
+import { buildCorpusDocument, verifyCorpusDocument, writeCorpusDocument } from '../measure/corpus.mjs';
 import { regradeRun, runBench } from '../bench/run.mjs';
 import { buildBenchReport } from '../bench/report.mjs';
 import { formatRecall, measureRecall } from '../index/map.mjs';
@@ -233,7 +233,7 @@ export async function benchReportCommand(positional, flags) {
     );
   }
 
-  const root = resolve(flags.root ?? pos[0] ?? process.cwd());
+  const root = resolve(commandRoot(flags, pos));
   const arms = listFlag(flags.arm);
 
   let report;