simt-dev 0.2.2 → 0.3.1

package/src/commands/tests.mjs

@@ -0,0 +1,192 @@
+// `simt tests [path]` lists the tests that exercise a file (R24, ADR-092).
+//
+// The index already stores imports, but a test import that spans lines is not
+// one of them. Test files are read back from their blobs, once, in a single
+// batch. Coverage is read only from a fixed list of paths. History is the last
+// 200 non-merge commits, which is a map and not the whole changelog.
+
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { isTestPath } from '../bench/mine.mjs';
+import { readEdges, readFiles, reindex } from '../index/store.mjs';
+import { HISTORY, importsOf, parseCoverage, testEdges, testsFor } from '../index/tests.mjs';
+
+const exec = promisify(execFile);
+
+const LANG = {
+  js: 'javascript', mjs: 'javascript', cjs: 'javascript', jsx: 'javascript',
+  ts: 'typescript', tsx: 'typescript', kt: 'kotlin', kts: 'kotlin', java: 'java',
+  py: 'python', go: 'go', rs: 'rust', swift: 'swift', dart: 'dart', rb: 'ruby', cs: 'csharp',
+};
+
+const COVERAGE_PATHS = [
+  'coverage/lcov.info',
+  'lcov.info',
+  'coverage/coverage-final.json',
+  'coverage.json',
+  'jacoco.xml',
+  'build/reports/jacoco/test/jacocoTestReport.xml',
+  'coverage.out',
+  'cover.out',
+];
+
+export async function testsCommand(args, flags) {
+  if (args.length > 1) return fail(`unknown tests argument ${args[1]}`, EXIT.USAGE, `run: ${CLI} tests [path]`);
+  const root = flags.root ?? process.cwd();
+  const loaded = await loadFiles(root);
+  if (loaded.error) return loaded.error;
+  const { files } = loaded;
+  const [stored, texts, coverage, commits] = await Promise.all([
+    readEdges(root),
+    testBlobs(root, files),
+    coverageTexts(root),
+    history(root),
+  ]);
+  const paths = new Set(files.map((file) => file.path));
+  const imports = stored.filter((edge) => edge.kind === 'import');
+  for (const file of files) {
+    if (!isTestPath(file.path)) continue;
+    const text = texts.get(file.blob);
+    if (!text) continue;
+    imports.push(...importsOf(file.path, text, langOf(file.path), paths));
+  }
+  const edges = testEdges({ files, imports, coverage, commits });
+  const target = args[0];
+  if (!target) return summarise(root, flags, edges);
+  if (!paths.has(target)) {
+    return fail(`not in the index: ${target}`, EXIT.USAGE, `pass a path ${CLI} index knows`);
+  }
+  const tests = testsFor(target, edges, { cochange: flags.cochange === true });
+  const payload = { ok: true, command: 'tests', root, path: target, tests };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  const lines = [`tests    ${tests.length}`, ...tests];
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+function summarise(root, flags, edges) {
+  let test = 0;
+  let cochange = 0;
+  for (const edge of edges) {
+    if (edge.kind === 'test') test += 1;
+    else if (edge.kind === 'cochange') cochange += 1;
+  }
+  const payload = { ok: true, command: 'tests', root, test, cochange };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  emit(`test      ${test}\ncochange  ${cochange}`, { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+async function loadFiles(root) {
+  let files = await readFiles(root);
+  if (files.length === 0) {
+    try {
+      await reindex(root);
+    } catch (error) {
+      return {
+        error: fail(
+          `could not map tests in this repository (${error.message})`,
+          EXIT.UNSUPPORTED,
+          'run this inside a git repository',
+        ),
+      };
+    }
+    files = await readFiles(root);
+  }
+  return { files };
+}
+
+async function testBlobs(root, files) {
+  const blobs = [];
+  for (const file of files) {
+    if (isTestPath(file.path) && file.blob) blobs.push(file.blob);
+  }
+  return cat(root, blobs);
+}
+
+async function coverageTexts(root) {
+  const texts = [];
+  for (const path of COVERAGE_PATHS) {
+    try {
+      const text = await readFile(join(root, path), 'utf8');
+      if (parseCoverage(text).length > 0 || text.trim() !== '') texts.push(text);
+    } catch {
+      // Absent coverage is the usual case. It is not a failed map.
+    }
+  }
+  return texts;
+}
+
+async function history(root) {
+  let stdout = '';
+  try {
+    ({ stdout } = await exec('git', ['log', '-n', String(HISTORY), '--no-merges', '--name-only', '--pretty=format:%x1e'], {
+      cwd: root,
+      maxBuffer: 16 << 20,
+    }));
+  } catch {
+    return [];
+  }
+  const commits = [];
+  for (const block of stdout.split('\x1e')) {
+    const paths = [];
+    for (const line of block.split('\n')) {
+      const path = line.trim();
+      if (path) paths.push(path);
+    }
+    if (paths.length > 0) commits.push(paths);
+  }
+  return commits;
+}
+
+async function cat(root, blobs) {
+  const unique = [...new Set(blobs)];
+  const texts = new Map();
+  if (unique.length === 0) return texts;
+  const body = await batch(root, unique);
+  let offset = 0;
+  while (offset < body.length) {
+    const nl = body.indexOf(0x0a, offset);
+    if (nl < 0) break;
+    const header = body.toString('utf8', offset, nl);
+    const parts = header.split(' ');
+    const size = Number(parts[2]);
+    if (parts[1] !== 'blob' || !Number.isFinite(size)) {
+      offset = nl + 1;
+      continue;
+    }
+    const start = nl + 1;
+    const bytes = body.subarray(start, start + size);
+    offset = start + size + 1;
+    texts.set(parts[0], bytes.includes(0) ? null : bytes.toString('utf8'));
+  }
+  return texts;
+}
+
+function batch(root, blobs) {
+  return new Promise((resolve) => {
+    const child = execFile('git', ['cat-file', '--batch'], { cwd: root, maxBuffer: 32 << 20, encoding: 'buffer' }, (error, stdout) => {
+      resolve(error ? Buffer.alloc(0) : stdout);
+    });
+    child.stdin.write(`${blobs.join('\n')}\n`);
+    child.stdin.end();
+  });
+}
+
+function langOf(path) {
+  const base = path.slice(path.lastIndexOf('/') + 1);
+  const dot = base.lastIndexOf('.');
+  if (dot <= 0) return '';
+  return LANG[base.slice(dot + 1)] ?? '';
+}

package/src/commands/tokens.mjs

@@ -33,6 +33,8 @@ import {
   mcpTools,
   totals,
 } from '../measure/context.mjs';
+import { measureSession } from '../measure/session.mjs';
+import { sharedTotals } from '../projection/shared.mjs';
 
 /** `1234567`, never `1,234,567`. `toLocaleString` output depends on the locale, and
  *  this command exists so two machines produce two numbers a pull request can diff. */
@@ -45,6 +47,36 @@ function files(n) {
 }
 
 export async function tokensCommand(positional, flags) {
+  if (flags.session !== undefined) {
+    const session = await measureSession(flags.session);
+    if (!session.ok) {
+      return fail(session.error, EXIT.CONFIG, session.remedy);
+    }
+    if (isJson(flags)) {
+      emitJson({
+        ok: true,
+        command: 'tokens',
+        mode: 'session',
+        session: session.path,
+        bytesPerToken: BYTES_PER_TOKEN,
+        rules: session.rules,
+        fileReads: session.fileReads,
+        toolOutput: session.toolOutput,
+        total: session.total,
+      });
+      return EXIT.OK;
+    }
+    const lines = [
+      `tokens   ${session.path}  (session)`,
+      `rules       ${plain(session.rules.bytes)} B  ~${plain(session.rules.tokens)} tokens  (${plain(session.rules.share)}%)`,
+      `file reads  ${plain(session.fileReads.bytes)} B  ~${plain(session.fileReads.tokens)} tokens  (${plain(session.fileReads.share)}%)`,
+      `tool output ${plain(session.toolOutput.bytes)} B  ~${plain(session.toolOutput.tokens)} tokens  (${plain(session.toolOutput.share)}%)`,
+      `total       ${plain(session.total.bytes)} B  ~${plain(session.total.tokens)} tokens`,
+    ];
+    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+
   // `targetRoot` owns the precedence, so `tokens`, `compare` and `upgrade` cannot
   // disagree about which directory was named (ADR-014).
   const target = await targetRoot(flags, positional);
@@ -78,7 +110,17 @@ export async function tokensCommand(positional, flags) {
   for (const path of roots) rows.push(await measureRoot(path));
   annotate(rows);
 
-  const summary = totals(rows);
+  const measured = totals(rows);
+  // The workspace copy, counted once (ADR-084). A figure that measured the regions and
+  // ignored the file the rules moved into would show a saving the reader's context never
+  // saw, so it is in the total from the first run rather than as an afterthought.
+  const shared = await sharedTotals(rows);
+  const summary = {
+    ...measured,
+    sharedBytes: shared.bytes,
+    estateBytes: measured.generatedBytes + shared.bytes,
+    sharedFiles: shared.files,
+  };
   const mcp = mcpTools();
 
   if (isJson(flags)) {
@@ -111,6 +153,15 @@ export async function tokensCommand(positional, flags) {
     lines.push(
       `totals   generated ${plain(summary.generatedBytes)} B  duplicate ${plain(summary.duplicateBytes)} B (${plain(share)}% of generated)  unique ${plain(summary.uniqueBytes)} B  repeat ${plain(summary.repeatBytes)} B  ~${plain(summary.tokens)} tokens`,
     );
+    // Only when there is a copy to count. The line a reader sees most is the one that
+    // says what their whole estate loads, and adding a second number to it that is
+    // usually zero is how a report stops being read.
+    if (summary.sharedBytes > 0) {
+      lines.push(
+        `shared   ${plain(summary.sharedBytes)} B carried once in ${plain(summary.sharedFiles.length)} user-level file(s)  estate total ${plain(summary.estateBytes)} B`,
+      );
+      for (const f of summary.sharedFiles) lines.push(`  ${f.path}  ${plain(f.bytes)} B  ${plain(f.rules)} rule(s)`);
+    }
   } else {
     const row = rows[0];
     lines.push(`tokens   ${row.path}`);
@@ -124,6 +175,15 @@ export async function tokensCommand(positional, flags) {
     lines.push(
       `always-on ${plain(row.generatedBytes)} B generated  ~${plain(row.generatedTokens)} tokens  budget ${plain(row.budget.bytes)} B  ${verdict}`,
     );
+    // The same reason as the `--repos` line, and it matters more here: measuring one
+    // repository is the default, so a reader who owns the workspace copy and never saw it
+    // counted would read a saving their own session does not get.
+    if (summary.sharedBytes > 0) {
+      lines.push(
+        `shared   ${plain(summary.sharedBytes)} B carried once in ${plain(summary.sharedFiles.length)} user-level file(s)  always-on for you: ${plain(summary.estateBytes)} B`,
+      );
+      for (const f of summary.sharedFiles) lines.push(`  ${f.path}  ${plain(f.bytes)} B  ${plain(f.rules)} rule(s)`);
+    }
     lines.push(
       `redundant ${plain(row.redundancy.duplicateBytes)} B repeats an earlier repository  ${plain(row.redundancy.repeatBytes)} B repeats an earlier document here  ${plain(row.redundancy.uniqueBytes)} B unique of ${plain(row.redundancy.blockBytes)} B counted in blocks`,
     );

package/src/commands/why.mjs

@@ -0,0 +1,177 @@
+// `simt why [path]` lists what governs a file (R25, ADR-093).
+//
+// With a path, one line per decision, rule, skill, gate and lesson. With no
+// path, the Affects tokens that name nothing this tree contains. The file list
+// is `git ls-files`. The index is not rebuilt: governance is the records, and
+// writing the cache to answer a question would change the tree.
+
+import { execFile } from 'node:child_process';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { CLI, MANIFEST_FILE } from '../name.mjs';
+import { FORMATTABLE, GATES } from '../hooks/gates.mjs';
+import {
+  decisionHits,
+  lessonPaths,
+  scopeHits,
+  scopePaths,
+  sortHits,
+  sourceRoots,
+  unresolvedAffects,
+} from '../index/govern.mjs';
+
+const exec = promisify(execFile);
+
+const RULE_DIRS = ['rules', 'rules/stacks', 'rules/mdc', '.simt-dev/profiles'];
+
+export async function whyCommand(args, flags, commands = []) {
+  if (args.length > 1) return fail(`unknown why argument ${args[1]}`, EXIT.USAGE, `run: ${CLI} why [path]`);
+  const root = flags.root ?? process.cwd();
+  const listed = await tracked(root);
+  if (listed.error) return listed.error;
+  const files = new Set(listed.files);
+  const ctx = { files, commands: new Set(commands), roots: sourceRoots(files) };
+  const records = await decisionRecords(root);
+  const target = args[0];
+  if (!target) return reportUnresolved(root, flags, unresolvedAffects(records, ctx));
+  if (!files.has(target)) return fail(`not in the tree: ${target}`, EXIT.USAGE, `pass a path git tracks`);
+  const corpus = await loadCorpus(root);
+  const { hits } = decisionHits(records, target, ctx);
+  const items = sortHits([...hits, ...scopeHits(target, corpus)]);
+  const payload = { ok: true, command: 'why', root, path: target, items };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  const lines = items.map((item) => `${item.kind.padEnd(10)}${item.id}  ${item.detail}`);
+  emit(lines.length > 0 ? lines.join('\n') : 'none', { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+function reportUnresolved(root, flags, unresolved) {
+  const payload = { ok: true, command: 'why', root, unresolved };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  const lines = unresolved.map((item) => `UNRESOLVED-AFFECTS  ${item.token}  ${item.id}`);
+  emit([`unresolved  ${unresolved.length}`, ...lines].join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+async function tracked(root) {
+  try {
+    const { stdout } = await exec('git', ['ls-files'], { cwd: root, maxBuffer: 16 << 20 });
+    return { files: stdout.split('\n').filter(Boolean) };
+  } catch (error) {
+    return {
+      error: fail(
+        `could not read what governs files here (${error.message})`,
+        EXIT.UNSUPPORTED,
+        'run this inside a git repository',
+      ),
+    };
+  }
+}
+
+export async function decisionRecords(root) {
+  const dir = join(root, 'docs', 'decisions');
+  let names = [];
+  try {
+    names = (await readdir(dir)).filter((name) => /^ADR-\d{3}-.*\.md$/.test(name)).sort();
+  } catch {
+    return [];
+  }
+  const records = [];
+  for (const name of names) {
+    const text = await readFile(join(dir, name), 'utf8');
+    const id = /^ADR-\d{3}/.exec(name)[0];
+    const heading = /^#\s+(.*)$/m.exec(text)?.[1] ?? id;
+    const title = heading.replace(/^ADR-\d{3}\s+[—–-]\s+/, '');
+    records.push({ id, title, text });
+  }
+  return records;
+}
+
+async function loadCorpus(root) {
+  const [rules, skills, lessons, commands] = await Promise.all([
+    ruleScopes(root),
+    skillScopes(root),
+    lessonScopes(root),
+    gateCommands(root),
+  ]);
+  const gates = Object.values(GATES).map((gate) => ({
+    id: gate.name,
+    detail: gate.why,
+    extensions: gate.kind === 'staged' ? FORMATTABLE : null,
+  }));
+  return { rules, skills, gates, lessons, commands };
+}
+
+export async function ruleScopes(root) {
+  const rules = [];
+  for (const dir of RULE_DIRS) {
+    let names = [];
+    try {
+      names = await readdir(join(root, dir));
+    } catch {
+      continue;
+    }
+    for (const name of names.sort()) {
+      if (!name.endsWith('.md') && !name.endsWith('.mdc')) continue;
+      const text = await readFile(join(root, dir, name), 'utf8');
+      const paths = scopePaths(text);
+      if (paths.length === 0) continue;
+      const id = /^simt-id:\s*(\S+)/m.exec(text)?.[1] ?? name;
+      const detail = /^simt-title:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? id;
+      rules.push({ id, detail, paths });
+    }
+  }
+  return rules;
+}
+
+async function skillScopes(root) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(join(root, 'graph', 'skills.graph.json'), 'utf8'));
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed?.skills)) return [];
+  return parsed.skills
+    .filter((skill) => Array.isArray(skill.paths) && skill.paths.length > 0)
+    .map((skill) => ({ id: String(skill.name ?? ''), detail: String(skill.summary ?? ''), paths: skill.paths }));
+}
+
+async function lessonScopes(root) {
+  const dir = join(root, 'docs', 'lessons');
+  let names = [];
+  try {
+    names = (await readdir(dir)).filter((name) => name.endsWith('.md')).sort();
+  } catch {
+    return [];
+  }
+  const lessons = [];
+  for (const name of names) {
+    const text = await readFile(join(dir, name), 'utf8');
+    const paths = lessonPaths(text);
+    if (paths.length === 0) continue;
+    const id = name.replace(/\.md$/, '');
+    const detail = /^#\s+(.*)$/m.exec(text)?.[1] ?? id;
+    lessons.push({ id, detail, paths });
+  }
+  return lessons;
+}
+
+async function gateCommands(root) {
+  try {
+    const parsed = JSON.parse(await readFile(join(root, MANIFEST_FILE), 'utf8'));
+    const commands = parsed?.gates?.commands;
+    return commands && typeof commands === 'object' ? commands : {};
+  } catch {
+    return {};
+  }
+}

package/src/decisions/index.mjs

@@ -20,6 +20,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { MANIFEST_FILE } from '../name.mjs';
 import { CLI } from '../name.mjs';
+import { PREFIX_ARGUING, TOOL_WORDS } from '../toolwords.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const DECISIONS_DIR = resolve(HERE, '..', '..', 'docs', 'decisions');
@@ -240,7 +241,7 @@ export async function loadDecisions({ all = false } = {}) {
         (m) => `ADR-${m[1]}`,
       ),
       partial,
-      summary: summarise(text, partial, { all }),
+      summary: summarise(text, partial, { all, file }),
       bytes: Buffer.byteLength(text),
     });
   }
@@ -288,7 +289,7 @@ export function byId(decisions) {
  *   answer "why is this here"; the reader who needs the rest asks.
  * @returns {{ruled: string[], rulingNumbers: (number|null)[], rulingCount: number, rejected: string[], writtenAgainst: string[]}}
  */
-function summarise(text, partial = [], { all = false } = {}) {
+function summarise(text, partial = [], { all = false, file = null } = {}) {
   // A section ends at the next `## ` — but not at one inside a fenced code block.
 // ADR-007's entire ruling is a document skeleton in a fence whose headings are `##`,
 // so the old lookahead ended the section at the first line of the ruling itself. It
@@ -446,7 +447,15 @@ const section = (name) => {
     // Named rather than stripped. A record that cites this org's repositories is still
     // the record; silently deleting the citation would hide which decisions were made in
     // response to what, and would mangle sentences mid-clause.
-    writtenAgainst: [...new Set(text.match(ESTATE) ?? [])].sort(),
+    //
+    // What is named is a repository, and the shape was wrong about that: every
+    // `simt-<word>` that was not `simt-dev` was reported as one, so the tool's own
+    // `simt-priority` was listed as a surveyed repository and the record that settled the
+    // kernel read as if it had been decided by looking at some other repository (ADR-080).
+    // A record whose subject is the prefix is arguing rather than citing, so it names none.
+    writtenAgainst: PREFIX_ARGUING.has(file)
+      ? []
+      : [...new Set((text.match(ESTATE) ?? []).filter((name) => !TOOL_WORDS.has(name)))].sort(),
   };
 }
 
@@ -458,6 +467,10 @@ const section = (name) => {
  * The skill registry's `source.repo` values are asserted to match this (S14); a name
  * the registry adds that is not `simt-*` has to be added here or that assertion fails.
  *
+ * The shape is not the whole answer, and treating it as one is what ADR-080 settles: a
+ * `simt-` name this tool owns is not a repository, and neither reader can tell that from
+ * the shape. `src/toolwords.mjs` is the list both of them share.
+ *
  * Not global: callers reuse it with `exec`, and a `/g` flag would remember `lastIndex`.
  */
 /**
@@ -486,7 +499,12 @@ export const ESTATE_NAME =
 
 /** Replace estate repository names with a phrase a reader who does not have them can use. */
 export function redactEstate(text) {
-  return text.replace(new RegExp(ESTATE_NAME.source, 'g'), 'a repository');
+  return String(text ?? '').replace(new RegExp(ESTATE_NAME.source, 'g'), (name) =>
+    // The tool's own names are left where they are. Redacting them turned a ruling about
+    // `simt-priority` into a sentence about `a repository`, which is how a reader learned
+    // that the record had surveyed something and not what it said (ADR-080).
+    TOOL_WORDS.has(name) ? name : 'a repository',
+  );
 }
 
 /**
@@ -506,7 +524,7 @@ export function redactEstate(text) {
  * Only a real verb follows, which is what keeps `simt-dev.json`, `simt-dev-check.yml` and
  * `simt-dev's` untouched - those are the project's artefacts and the project keeps its name.
  */
-const VERB = '(?:init|doctor|check|sync|upgrade|ci|compare|hooks|mcp|rules|skills|graph|--[a-z-]+)';
+const VERB = '(?:init|doctor|check|sync|upgrade|ci|compare|hooks|mcp|rules|skills|graph|tokens|harness|bench|shared|evidence|index|map|tests|why|gate|impact|--[a-z-]+)';
 
 function redactCommand(text) {
   return String(text ?? '').replace(new RegExp(`\\bsimt-dev (?=${VERB})\\b`, 'g'), `${CLI} `);

package/src/graph/spec.mjs

@@ -164,7 +164,7 @@ export function checkSkill({ directoryName, fileName = 'SKILL.md', text, at }) {
  * characters. That is the whole failure this file exists to prevent, one level down - a
  * lint that is confidently wrong about a conforming file.
  */
-function readFrontmatter(text) {
+export function readFrontmatter(text) {
   const meta = {};
   const present = [];
   const body = text.replace(/^/, '');

package/src/hooks/dispatcher.mjs

@@ -28,6 +28,7 @@ import { resolveGate } from './resolve.mjs';
 import { CLI } from '../name.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
 import { assertVersionPin } from '../package-version.mjs';
+import { recordRun } from '../ledger/index.mjs';
 
 const exec = promisify(execFile);
 
@@ -179,7 +180,21 @@ export async function runGates(event, { root, manifest }) {
       cwd = resolved;
     }
 
+    const started = Date.now();
     const outcome = await runGate(resolution, cwd);
+    // The ledger is not the gate. A tree that cannot be named leaves no line, and the
+    // claim check then finds nothing, which is the direction that cannot invent a run.
+    try {
+      const cmd = typeof resolution.command === 'string' ? resolution.command : resolution.argv.join(' ');
+      await recordRun(root, {
+        cmd,
+        exit: outcome.code,
+        ms: Date.now() - started,
+        output: `${outcome.stdout ?? ''}\n${outcome.stderr ?? ''}`,
+      });
+    } catch {
+      // Recorded by absence: the next evidence read for this tree has no line.
+    }
     results.push({
       name,
       status: outcome.code === 0 ? 'passed' : 'failed',

package/src/hooks/shim.mjs

@@ -90,6 +90,37 @@ ${renderLocator(`hooks run ${event} --root "${D}ROOT"`, {
   })}`;
 }
 
+/**
+ * The commit-msg shim. It is not a dispatcher event: those shims do not forward
+ * git's arguments, and this one has to, because the message file is `$1`.
+ *
+ * Written only when the manifest sets `gates.evidence`. An unset value does not
+ * install a hook the repository did not ask for.
+ *
+ * @param {{npm?: boolean, version?: string}} [opts]
+ * @returns {string} POSIX sh source, LF-terminated
+ */
+export function renderEvidenceShim({ npm = true, version } = {}) {
+  const v = version ?? packageVersion();
+  const install = npm ? `npm i -D ${PACKAGE_NAME}@${v}` : `npm i -g ${PACKAGE_NAME}@${v}`;
+  const D = '$';
+  return `#!/bin/sh
+${SHIM_MARKER}
+#
+# A commit message that claims a run is checked against the ledger. The message
+# file is the first argument git passes, so this shim forwards it. Reinstall with:
+# ${CLI} hooks install --yes
+
+set -eu
+
+ROOT="${D}(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+
+${renderLocator(`evidence check "${D}1" --root "${D}ROOT"`, {
+    subject: 'the claim check',
+    remedy: `REMEDY run: ${install}, or set ${BIN_ENV} to the ${CLI} binary, or unset ${HOOKS_PATH_KEY} to opt out`,
+  })}`;
+}
+
 /**
  * A line only a chained shim carries.
  *