simt-dev 0.3.0 → 0.4.0

package/src/ci/workflow.mjs

@@ -148,6 +148,16 @@ function uses(action) {
   return `      - uses: ${repo}@${commit} # ${release}`;
 }
 
+/** This repository's own gate runs `npm test`, and two of those tests read
+ *  history. A consumer's gate does not, so its checkout stays shallow. */
+function checkoutFull() {
+  return `${uses('checkout')}
+        with:
+          # \`bench mine\` counts commits, and the Affects snapshot reads
+          # 4c27514. A depth-1 checkout fails both, and both run in \`npm test\`.
+          fetch-depth: 0`;
+}
+
 /** The YAML every copy shares, so the two cannot drift on triggers, permissions or
  *  concurrency. Only `name`, the runner and `steps` vary, and only because they have
  *  to. The own gate also varies the platforms and the Node versions, because this
@@ -246,7 +256,7 @@ export function renderWorkflow({ own = false, npm = true, version } = {}) {
     return `${header(true)}${skeleton(
       'simt-dev own gate',
       [
-        uses('checkout'),
+        checkoutFull(),
         setupNode('${{ matrix.node }}'),
         // The two checks `.githooks/pre-push` runs, named here rather than discovered,
         // because a reader of this file has to be able to answer "what stops a merge"

package/src/commands/agenthook.mjs

@@ -11,6 +11,12 @@
 // walks the repository. A hook that measured the tree before answering would be exactly
 // the latency the plan's acceptance criterion exists to prevent.
 //
+// A second event, `prompt-submit`, delivers rather than decides: it needs the manifest,
+// the index and the packet assembly, so it is reached through a dynamic `import()` that
+// only that event takes. A tool call therefore still pays for nothing that walks the
+// repository, and the one path that does pays for it once per prompt instead of once per
+// command.
+//
 // A denial exits 2, which is what every harness in the table reads as "block". A mistake
 // in the hook's own invocation must NOT exit 2: a typo in a config would then block every
 // tool call. Failures of this command exit 1, which a harness reports as a failed hook,
@@ -60,6 +66,32 @@ export async function agentHookCommand(args, flags) {
     return EXIT.OK;
   }
 
+  // Delivery, not decision: the packet goes into the prompt and the exit code stays 0
+  // whatever happens. The module behind it is the one thing here that reads the
+  // repository, and the tool-call path above must not pay for it, so the door is a
+  // dynamic import that only this event opens.
+  if (event === 'prompt-submit') {
+    const { deliverPrompt } = await import('../agenthooks/prompt.mjs');
+    const delivered = await deliverPrompt(row, payload);
+    if (delivered.skipped) {
+      note(`note     ${id}: no packet delivered (${delivered.skipped})`);
+      return EXIT.OK;
+    }
+    emit(JSON.stringify(delivered.json));
+    return EXIT.OK;
+  }
+
+  if (event === 'post-tool-use') {
+    const { deliverLessonRecall } = await import('../memory/lessons.mjs');
+    const recalled = await deliverLessonRecall(row, payload, { root: flags.root });
+    if (recalled.skipped) {
+      note(`note     ${id}: no lesson recalled (${recalled.skipped})`);
+      return EXIT.OK;
+    }
+    emit(JSON.stringify(recalled.json));
+    return EXIT.OK;
+  }
+
   const { root, command, writes } = factsFrom(row, payload);
   const facts = await factsFor(root, { command, writes });
   const decision = decide({ event, facts, env: process.env });
@@ -77,6 +109,22 @@ export async function agentHookCommand(args, flags) {
   const json = decisionJson(row, decision);
   if (json === null) return EXIT.OK;
 
+  if (root) {
+    try {
+      const { recordHookDenial } = await import('../memory/lessons.mjs');
+      await recordHookDenial(root, {
+        harness: row.id,
+        event,
+        policies: decision.blocked,
+        messages: decision.messages,
+        command,
+        writes,
+      });
+    } catch {
+      // Recording a lesson candidate must never block or alter the hook decision.
+    }
+  }
+
   emit(JSON.stringify(json));
   for (const message of decision.messages) note(`blocked  ${message}`);
   return row.denyExit;
@@ -91,14 +139,37 @@ export async function agentHooksCommand(sub, args, flags) {
 
 async function installHooks(root, flags) {
   const mode = writeMode(flags);
+  // 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
+  // import for the same reason the hook delivers through one.
+  const { promptOptIn } = await import('../agenthooks/prompt.mjs');
+  const { listPromotedLessons } = await import('../memory/lessons.mjs');
+  const [optIn, promotedLessons] = await Promise.all([
+    promptOptIn(root),
+    listPromotedLessons(root).catch(() => []),
+  ]);
+  const hasLessons = promotedLessons.length > 0;
   const plan = [];
   for (const row of adapters()) {
     const path = hookPath(row.id);
     const existing = await readIfExists(join(root, path));
-    const result = rendered(row, existing);
-    plan.push({ id: row.id, path, action: result.error ? 'refused' : result.action, error: result.error, text: result.text });
+    const result = rendered(row, existing, { prompt: optIn.optedIn, post: hasLessons });
+    plan.push({
+      id: row.id,
+      path,
+      action: result.error ? 'refused' : result.action,
+      error: result.error,
+      text: result.text,
+      prompt: row.prompt === null || row.prompt === undefined ? null : optIn.optedIn ? 'declared' : 'not declared',
+    });
   }
 
+  // One line for the repository, not one per adapter: the opt-in is a property of the
+  // repository, and someone who has not declared it is told how once.
+  const promptLine = plan.some((p) => p.prompt !== null) && !optIn.optedIn
+    ? [`PROMPT   not opted in (${optIn.why}); add "brief": {} to the manifest to deliver the packet on every prompt`]
+    : [];
+
   // The readers this tool does not write an entry for, reported rather than skipped in
   // silence: a command that writes four files and says nothing about the fifth harness
   // in the repository reads as "that one is covered too".
@@ -128,6 +199,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})` : ''}`),
         ...others.map((o) => `${o.state === 'none' ? 'NO FILE ' : 'NOT OURS'} ${o.id.padEnd(12)} ${o.path ?? '(no hooks file is documented)'}`),
+        ...promptLine,
         '',
         refused.length > 0
           ? `REFUSED  ${refused.length} config file(s) could not be read; nothing written`
@@ -177,6 +249,7 @@ async function installHooks(root, flags) {
       `repo     ${root}`,
       ...plan.map((p) => `${p.action.toUpperCase().padEnd(9)} ${p.id.padEnd(12)} ${p.path}`),
       ...others.map((o) => `${o.state === 'none' ? 'NO FILE ' : 'NOT OURS'} ${o.id.padEnd(12)} ${o.path ?? '(no hooks file is documented)'}`),
+      ...promptLine,
       '',
       `WROTE    ${written.length} hooks file(s); each one runs ${CLI} agent-hook before the tool call`,
     ].join('\n'),
@@ -196,14 +269,14 @@ async function hooksStatus(root, flags) {
     const path = hookPath(row.id);
     const existing = await readIfExists(join(root, path));
     if (existing === null) {
-      rows.push({ id: row.id, path, state: 'absent', entries: 0, note: null });
+      rows.push({ id: row.id, path, state: 'absent', entries: 0, prompt: row.prompt ? 'absent' : null, note: null });
       continue;
     }
     let config;
     try {
       config = JSON.parse(existing);
     } catch (e) {
-      rows.push({ id: row.id, path, state: 'unreadable', entries: 0, note: e.message });
+      rows.push({ id: row.id, path, state: 'unreadable', entries: 0, prompt: row.prompt ? 'unknown' : null, note: e.message });
       problems.push(`${path} is not valid JSON: ${e.message}`);
       continue;
     }
@@ -211,16 +284,18 @@ async function hooksStatus(root, flags) {
     // refuses to write into one. Status has to agree with it, or one question gets two
     // answers and the quiet one is the one a reader acts on.
     if (config === null || typeof config !== 'object' || Array.isArray(config)) {
-      rows.push({ id: row.id, path, state: 'unreadable', entries: 0, note: 'not a JSON object' });
+      rows.push({ id: row.id, path, state: 'unreadable', entries: 0, prompt: row.prompt ? 'unknown' : null, note: 'not a JSON object' });
       problems.push(`${path} is not a JSON object, so this tool will not write into it`);
       continue;
     }
     const found = installedIn(row, config).length;
+    const prompts = row.prompt ? installedIn(row, config, EVENTS[1]).length : 0;
     rows.push({
       id: row.id,
       path,
       state: found > 0 ? 'present' : 'absent',
       entries: found,
+      prompt: row.prompt ? (prompts > 0 ? 'present' : 'absent') : null,
       note: found > 0 ? (row.trust ?? null) : null,
     });
   }
@@ -243,6 +318,10 @@ async function hooksStatus(root, flags) {
     const state = { present: 'PRESENT ', absent: 'ABSENT  ', unreadable: 'INVALID ', none: 'NO FILE ', other: 'NOT OURS' }[r.state];
     lines.push(`${state} ${r.id.padEnd(12)} ${r.path ?? '(no hooks file is documented)'}`);
     if (r.state === 'absent') lines.push(`          ${' '.repeat(12)} install: ${CLI} agent-hooks install --yes`);
+    // The second event is a separate answer to a separate question: a harness can carry
+    // the tool hook and not the delivery, and a reader who is told "PRESENT" would
+    // otherwise conclude the packet arrives on every prompt.
+    if (r.prompt) lines.push(`          ${' '.repeat(12)} prompt-submit: ${r.prompt}`);
     if (r.note) lines.push(`          ${' '.repeat(12)} ${r.note}`);
   }
   if (problems.length > 0) {

package/src/commands/bench.mjs

@@ -12,8 +12,10 @@ import { EXIT, emit, emitJson, fail, isJson, writeMode } from '../output/index.m
 import { DEFAULT_MINE_TARGET, mineTasks } from '../bench/mine.mjs';
 import { regradeRun, runBench } from '../bench/run.mjs';
 import { buildBenchReport } from '../bench/report.mjs';
+import { formatRecall, measureRecall } from '../index/map.mjs';
 import { ablateBench } from '../bench/ablate.mjs';
 import { runBenchProbes } from '../bench/probes.mjs';
+import { selectRuleVariants } from '../bench/variants.mjs';
 import { listFlag } from './skills.mjs';
 
 export async function benchMineCommand(positional, flags) {
@@ -223,6 +225,8 @@ export async function benchReportCommand(positional, flags) {
     );
   }
 
+  const mapRecall = await recallOrUnmeasured(root);
+
   if (isJson(flags)) {
     emitJson({
       ok: true,
@@ -232,14 +236,23 @@ export async function benchReportCommand(positional, flags) {
       runCount: report.runCount,
       arms: report.arms,
       comparison: report.comparison,
+      mapRecall,
     });
     return EXIT.OK;
   }
 
-  emit(report.markdown, { maxBytes: flags.maxBytes ?? 0 });
+  emit(`${report.markdown}\n\n### Map\n\n${formatRecall(mapRecall)}`, { maxBytes: flags.maxBytes ?? 0 });
   return EXIT.OK;
 }
 
+async function recallOrUnmeasured(root) {
+  try {
+    return await measureRecall(root);
+  } catch {
+    return { measured: false, reason: 'not run', tasks: 0, missing: 0, recall: null };
+  }
+}
+
 export async function benchAblateCommand(positional, flags) {
   const root = resolve(flags.root ?? positional[0] ?? process.cwd());
   const { dryRun, apply } = writeMode(flags);
@@ -268,16 +281,8 @@ export async function benchAblateCommand(positional, flags) {
     emitJson({
       ok: true,
       command: 'bench ablate',
-      root: result.root,
       dryRun,
-      applied: result.applied,
-      pricesLoaded: result.pricesLoaded,
-      canarySize: result.canarySize,
-      canaryTasks: result.canaryTasks,
-      totalTasks: result.totalTasks,
-      sections: result.sections,
-      ranking: result.ranking,
-      deletionCandidates: result.deletionCandidates,
+      ...result,
     });
     return EXIT.OK;
   }
@@ -328,13 +333,8 @@ export async function benchProbesCommand(positional, flags) {
     emitJson({
       ok: true,
       command: 'bench probes',
-      root: result.root,
       dryRun,
-      applied: result.applied,
-      probeCount: result.probeCount,
-      probes: result.probes,
-      arms: result.arms,
-      runs: result.runs,
+      ...result,
     });
     return EXIT.OK;
   }
@@ -355,5 +355,42 @@ export async function benchProbesCommand(positional, flags) {
   return EXIT.OK;
 }
 
+export async function benchVariantsCommand(positional, flags) {
+  const root = resolve(flags.root ?? positional[0] ?? process.cwd());
+  const { dryRun, apply } = writeMode(flags);
+  let result;
+  try {
+    result = await selectRuleVariants(root, {
+      apply,
+      harness: flags.harness ?? 'gold',
+      model: flags.model,
+      reps: flags.reps ?? 1,
+      includeAll: flags.all === true,
+    });
+  } catch (error) {
+    return fail(
+      `${root}: ${error.message ?? error}`,
+      EXIT.CONFIG,
+      `mine tasks first with \`${CLI} bench mine --yes\` and rerun \`${CLI} bench variants --yes\``,
+    );
+  }
+  if (isJson(flags)) {
+    emitJson({ ok: true, command: 'bench variants', dryRun, ...result });
+    return EXIT.OK;
+  }
+  const lines = [
+    `bench    variants  ${result.root}`,
+    `mode     ${result.applied ? 'applied' : dryRun ? 'dry-run (writes nothing)' : 'preview / stored runs (pass --yes to execute canary and lock winners)'}`,
+    `harness  ${result.harness}  model=${result.model}`,
+    `slots    ${result.slots.length}  (canary: ${result.canaryTasks}/${result.totalTasks} tasks)`,
+    ...result.slots.map(
+      (s) => `slot     ${s.slotId}  status=${s.status}  winner=${s.winner}  dR=${s.dR}  dC=${s.dC}  n=${s.n}  p=${s.p}`,
+    ),
+  ];
+  if (!result.applied) lines.push(`remedy   run: ${CLI} bench variants --yes`);
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
 
 

package/src/commands/brief.mjs

@@ -0,0 +1,78 @@
+// `simt brief "<task>"` — print the packet (plan 0003 R27).
+//
+// What this is for: an agent that has to explore a repository to find out how to run its
+// tests, which files the task will touch and what governs them spends turns discovering
+// what the repository already knows. The packet is that answer, assembled from the index
+// the repository already has, in the bytes a prompt can carry.
+//
+// The assembly itself is in `../brief/assemble.mjs`, because three doors open onto it —
+// this command, MCP's `brief` tool and the prompt-submit hook — and one implementation
+// behind three doors is the only way the three cannot disagree. This file owns the
+// command line: what a task may be, what the ceiling may be, and how the packet is
+// rendered for a terminal or for `--json`.
+//
+// One thing is deliberately missing: `skills brief` keeps its own behaviour, and MCP's
+// `skills_brief` keeps its own shape. Superseding them changes two accepted decisions
+// (ADR-035, ADR-052) and the MCP contract, and this slice carries no ADR to do it.
+
+import { CLI } from '../name.mjs';
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { DEFAULT_BRIEF_BYTES, explainPacket } from '../brief/packet.mjs';
+import { assembleBrief } from '../brief/assemble.mjs';
+
+export async function briefCommand(args, flags) {
+  if (args.length > 1) {
+    return fail(`brief takes one task, not ${args.length}`, EXIT.USAGE, `run: ${CLI} brief "<task>"`);
+  }
+  if (args.length === 1 && flags.task !== undefined) {
+    return fail('the task was passed twice, as an argument and as --task', EXIT.USAGE, `run: ${CLI} brief "<task>"`);
+  }
+  const budget = flags.budget === undefined ? DEFAULT_BRIEF_BYTES : Number(flags.budget);
+  if (!Number.isInteger(budget) || budget < 0) {
+    return fail(`--budget must be a byte count, not ${flags.budget}`, EXIT.USAGE, `run: ${CLI} brief --budget ${DEFAULT_BRIEF_BYTES}`);
+  }
+
+  const result = await assembleBrief({
+    root: flags.root ?? process.cwd(),
+    task: String(args[0] ?? flags.task ?? ''),
+    paths: flags.paths === undefined ? null : flags.paths,
+    budget,
+    flags,
+  });
+  if (result.error) return result.error;
+  // Unreachable from here — only a delivered brief asks for a cold index to be reported
+  // rather than built — but a silent empty packet would be the worst way to find out.
+  if (result.cold) {
+    return fail('the index is empty, and this command will not assemble a packet from it', EXIT.UNSUPPORTED, `run ${CLI} index`);
+  }
+  const { root, kind, basis, task, scope, budget: ceiling, items, packed, sections } = result;
+  const cut = new Set(packed.cut);
+
+  if (isJson(flags)) {
+    emitJson(
+      {
+        ok: true,
+        command: 'brief',
+        root,
+        kind,
+        basis,
+        task,
+        scope,
+        budget: ceiling,
+        bytes: packed.after,
+        before: packed.before,
+        floorHeld: packed.floorHeld,
+        cut: packed.cut,
+        sections,
+        explain: flags.explain === true ? explainPacket(items, { cut }) : undefined,
+        text: packed.text,
+      },
+      { pretty: flags.pretty === true, maxBytes: Number(flags.maxBytes ?? 0) || 0 },
+    );
+    return EXIT.OK;
+  }
+
+  const body = flags.explain === true ? [packed.text, '', 'EXPLAIN', ...explainPacket(items, { cut })] : [packed.text];
+  emit(body.join('\n'), { maxBytes: Number(flags.maxBytes ?? 0) || 0 });
+  return EXIT.OK;
+}

package/src/commands/compare.mjs

@@ -26,6 +26,7 @@ import { provenanceDigest } from '../projection/project.mjs';
 import { GATES } from '../hooks/gates.mjs';
 import { buildRow, summarise } from '../compare/row.mjs';
 import { discover } from '../compare/discover.mjs';
+import { learnAcrossEstate, renderLearningLines } from '../compare/learn.mjs';
 import { targetRoot, WORKSPACE_REMEDY } from '../workspace.mjs';
 
 /** Gate kinds, so a row can tell a command gate with no command from a script gate. */
@@ -65,6 +66,7 @@ export async function compareCommand(positional, flags) {
   // bound. Determinism of the output matters more than wall clock on a dashboard.
   const rows = [];
   for (const repo of found.repos) rows.push(await buildRow(repo, context));
+  const learning = await learnAcrossEstate(found.repos);
 
   const summary = summarise(rows, {
     root,
@@ -106,6 +108,7 @@ export async function compareCommand(positional, flags) {
         shas: summary.shas,
       },
       rows,
+      learning,
       worktrees: found.worktrees.map((w) => ({
         name: w.name,
         path: w.path,
@@ -117,7 +120,7 @@ export async function compareCommand(positional, flags) {
     return rows.some((r) => r.problems.length > 0) ? EXIT.FAIL : EXIT.OK;
   }
 
-  emit(render(rows, summary, found), { maxBytes: flags.maxBytes ?? 0 });
+  emit(render(rows, summary, found, learning), { maxBytes: flags.maxBytes ?? 0 });
   if (summary.shape === 'repo') {
     note('note     one repository compared; pass --root at a workspace directory to compare its siblings');
   } else if (target.source === 'none') {
@@ -146,7 +149,7 @@ export async function compareCommand(positional, flags) {
  * the longest value, and an agent cannot tell which column is which without
  * counting spaces.
  */
-function render(rows, summary, found) {
+function render(rows, summary, found, learning = null) {
   const lines = [
     // `workspace` and `repo` are the same field with different names, and the name is the
     // honest one: a reader who sees "workspace" and gets one repo was told a lie. `root`
@@ -204,6 +207,11 @@ function render(rows, summary, found) {
     lines.push('');
   }
 
+  const learningLines = renderLearningLines(learning);
+  if (learningLines.length > 0) {
+    lines.push(...learningLines, '');
+  }
+
   return lines.join('\n').trimEnd();
 }
 

package/src/commands/decide.mjs

@@ -0,0 +1,116 @@
+// `simt decide` — scaffold an ADR with the next free number, a Status: line,
+// a rulings skeleton, and structured `simt-affects` + `simt-supersedes` frontmatter
+// (plan 0003 R34).
+
+import { join, resolve } from 'node:path';
+import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { DECISIONS_DIR } from '../decisions/index.mjs';
+import { lintDecisions, scaffoldDecision } from '../memory/decide.mjs';
+import { parsePathList } from '../argv.mjs';
+
+export async function decideCommand(args, flags) {
+  const root = flags.root ?? process.cwd();
+
+  if (flags.check === true) {
+    const decisionsDir = join(root, 'docs', 'decisions');
+    const allowHistorical = resolve(decisionsDir) === DECISIONS_DIR;
+    const res = await lintDecisions(decisionsDir, { allowHistorical });
+
+    if (isJson(flags)) {
+      emitJson({
+        ok: res.ok,
+        command: 'decide --check',
+        root,
+        findings: res.findings,
+      });
+      return res.ok ? EXIT.OK : EXIT.FAIL;
+    }
+
+    if (res.findings.length === 0) {
+      emit('decisions  ok', { maxBytes: flags.maxBytes ?? 0 });
+      return EXIT.OK;
+    }
+
+    emit(
+      res.findings
+        .flatMap((f) => [
+          `${f.status.toUpperCase()}  ${f.file}  ${f.detail}`,
+          ...(f.remedy ? [`  remedy: ${f.remedy}`] : []),
+        ])
+        .join('\n'),
+      { maxBytes: flags.maxBytes ?? 0 },
+    );
+    return EXIT.FAIL;
+  }
+
+  const mode = writeMode(flags);
+  const title = args.join(' ').trim() || flags.task || 'Untitled decision';
+  const parsedPaths = parsePathList(flags.paths);
+  const explicitPaths = flags.paths !== undefined ? parsedPaths : undefined;
+
+  const res = await scaffoldDecision(root, {
+    title,
+    affects: explicitPaths,
+    supersedes: flags.supersedes,
+    write: mode.apply,
+  });
+
+  if (!res.ok) {
+    return fail(
+      res.errors[0],
+      EXIT.USAGE,
+      `usage: ${CLI} decide "<title>" [--supersedes ADR-NNN:<ruling>] [--yes]`,
+    );
+  }
+
+  if (mode.apply) {
+    note(`wrote    ${res.relPath}`);
+  } else if (flags.dryRun === true) {
+    note('dry-run  no files written');
+  }
+
+  if (isJson(flags)) {
+    emitJson({
+      ok: true,
+      command: 'decide',
+      root,
+      id: res.id,
+      number: res.number,
+      title: res.title,
+      file: res.file,
+      path: res.relPath,
+      affects: res.affects,
+      supersedes: res.supersedes,
+      written: res.written,
+      dryRun: !mode.apply,
+    });
+    return EXIT.OK;
+  }
+
+  const supersedesLabel =
+    res.supersedes.length > 0
+      ? res.supersedes
+          .map((s) => (s.ruling !== null ? `${s.adr} ruling ${s.ruling} (${s.kind})` : s.adr))
+          .join('; ')
+      : '(none)';
+
+  const lines = [
+    `id          ${res.id}`,
+    `title       ${res.title}`,
+    `file        ${res.relPath}`,
+    `affects     ${res.affects.length > 0 ? res.affects.join(', ') : '(none)'}`,
+    `supersedes  ${supersedesLabel}`,
+    '',
+    res.text.trimEnd(),
+    '',
+    mode.apply
+      ? `wrote ${res.relPath}`
+      : flags.dryRun === true
+        ? 'dry-run; nothing written'
+        : `would write ${res.relPath}; apply with: ${CLI} decide ${JSON.stringify(res.title)} --yes`,
+  ];
+
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}

package/src/commands/evidence.mjs

@@ -0,0 +1,96 @@
+// `simt evidence` — the proof block for this tree, and the commit-message check.
+//
+// The read answers "what has actually been run against what is on disk". The check
+// answers the other half: a message that says the tests passed, when nothing in the
+// ledger was run against this tree (ADR-087).
+
+import { readFile } from 'node:fs/promises';
+
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { readManifest } from '../projection/manifest.mjs';
+import { CLI, MANIFEST_FILE } from '../name.mjs';
+import { claimsVerification, evidenceMode, readLedger, treeId } from '../ledger/index.mjs';
+
+export async function evidenceCommand(args, flags) {
+  const root = flags.root ?? process.cwd();
+  if (args[0] === 'check') return checkClaim(root, args[1], flags);
+  if (args[0] !== undefined) {
+    return fail(`unknown evidence subcommand ${args[0]}`, EXIT.USAGE, `run: ${CLI} evidence`);
+  }
+  return showEvidence(root, flags);
+}
+
+async function showEvidence(root, flags) {
+  let tree;
+  try {
+    tree = await treeId(root);
+  } catch (error) {
+    return fail(
+      `could not name this tree (${error.message})`,
+      EXIT.UNSUPPORTED,
+      'run this inside a git repository',
+    );
+  }
+  const { entries, errors } = await readLedger(root);
+  const mine = entries.filter((e) => e.tree === tree);
+  const payload = { ok: errors.length === 0, command: 'evidence', root, tree, entries: mine, errors };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return errors.length === 0 ? EXIT.OK : EXIT.FAIL;
+  }
+  const lines = [`tree     ${tree}`];
+  if (mine.length === 0) lines.push('none     no run is recorded for this tree');
+  for (const e of mine) {
+    lines.push(`${e.exit === 0 ? 'pass' : 'fail'}     ${e.cmd}  exit ${e.exit}  ${e.summary}`);
+  }
+  for (const error of errors) lines.push(`error    ${error}`);
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return errors.length === 0 ? EXIT.OK : EXIT.FAIL;
+}
+
+async function checkClaim(root, file, flags) {
+  if (!file) return fail('evidence check needs the commit message file', EXIT.USAGE, `run: ${CLI} evidence check <file>`);
+  let message;
+  try {
+    message = await readFile(file, 'utf8');
+  } catch (error) {
+    return fail(`could not read ${file} (${error.message})`, EXIT.USAGE, `pass the path git gives commit-msg`);
+  }
+  const { manifest, error } = await readManifest(root);
+  if (error) return fail(`${MANIFEST_FILE}: ${error}`, EXIT.CONFIG, `fix ${MANIFEST_FILE} so it parses`);
+  const mode = evidenceMode(manifest);
+  if (mode === null) {
+    return fail(
+      `${MANIFEST_FILE} gates.evidence must be "warn" or "block"`,
+      EXIT.CONFIG,
+      `set gates.evidence to "warn" or "block", or remove it`,
+    );
+  }
+  const claim = claimsVerification(message);
+  if (!claim) {
+    const payload = { ok: true, command: 'evidence check', claim: false, mode };
+    if (isJson(flags)) emitJson(payload, { pretty: flags.pretty === true });
+    return EXIT.OK;
+  }
+  let tree;
+  try {
+    tree = await treeId(root);
+  } catch (error) {
+    return fail(`could not name this tree (${error.message})`, EXIT.UNSUPPORTED, 'run this inside a git repository');
+  }
+  const { entries } = await readLedger(root);
+  const supported = entries.some((e) => e.tree === tree && e.exit === 0);
+  const payload = { ok: supported || mode === 'warn', command: 'evidence check', claim: true, supported, mode, tree };
+  if (supported) {
+    if (isJson(flags)) emitJson(payload, { pretty: flags.pretty === true });
+    return EXIT.OK;
+  }
+  const detail = 'the message claims a run this tree does not have';
+  const remedy = `run the command, then commit, or take the claim out of the message`;
+  if (isJson(flags)) {
+    emitJson({ ...payload, detail, remedy }, { pretty: flags.pretty === true });
+    return mode === 'block' ? EXIT.FAIL : EXIT.OK;
+  }
+  emit(`${mode === 'block' ? 'BLOCKED' : 'WARNING'}  ${detail}\n         remedy: ${remedy}`, { maxBytes: flags.maxBytes ?? 0 });
+  return mode === 'block' ? EXIT.FAIL : EXIT.OK;
+}