testguard-cli 0.5.0 → 0.7.0

package/src/init/init.mjs

@@ -1,68 +1,198 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, realpathSync } from 'node:fs';
+import { join, dirname, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
 
 const TEMPLATES = join(dirname(fileURLToPath(import.meta.url)), 'templates');
-const HOOK_CMD = 'npx -y testguard-cli brief --text';
 const AGENTS_BEGIN = '<!-- testguard:begin -->';
 const AGENTS_END = '<!-- testguard:end -->';
-const AGENTS_BLOCK = `${AGENTS_BEGIN}
+const GITIGNORE_LINES = ['.testguard/evidence.json', '.testguard/evidence-provisional.json', '.testguard/evidence-partial.json', '.testguard/brief.json', '.testguard/gate.json', '.testguard/scaffold-*.json'];
+
+/**
+ * The session-start hook command. It runs from the git root (where the agent
+ * session lives) and must never fetch from the network: a local install of
+ * the project (or of the root) is preferred, then a `testguard` already on
+ * PATH, then nothing — the hook exits 0 with no output rather than break a
+ * session.
+ *
+ * No form of `npx` appears here, and `--no-install` is not an exception.
+ * Measured: in a project with nothing installed,
+ * `npx --no-install --loglevel=http testguard-cli --version` logs
+ * `npm http fetch GET 200 https://registry.npmjs.org/testguard-cli`, and
+ * against an unreachable registry it exits non-zero. npm resolves the
+ * packument before it decides not to install, so `--no-install` is quiet, not
+ * offline. A `command -v` lookup covers the global-install case with no
+ * network at all, which is the whole point in a repository that pins and
+ * audits its dependencies.
+ */
+export function hookCommand(dir) {
+  const arg = dir === '.' ? '' : ` ${dir}`;
+  const candidates = dir === '.' ? ['node_modules/.bin/testguard'] : [`${dir}/node_modules/.bin/testguard`, 'node_modules/.bin/testguard'];
+  // The PATH branch is braced: `a || b && c` binds as `(a || b) && c` in sh,
+  // so an unbraced `&&` would run the brief a second time whenever the local
+  // binary succeeded.
+  const onPath = `{ command -v testguard >/dev/null 2>&1 && testguard brief --text${arg} 2>/dev/null; }`;
+  return [...candidates.map((c) => `${c} brief --text${arg} 2>/dev/null`), onPath, 'true'].join(' || ');
+}
+
+function agentsBlock(entries) {
+  const lines = entries.map((dir) => (dir === '.'
+    ? '- This project: claims in `testguard.claims.json`; run `testguard status --json` and follow `next`.'
+    : `- \`${dir}/\`: claims in \`${dir}/testguard.claims.json\`; run \`testguard status --json ${dir}\` and follow \`next\`.`));
+  return `${AGENTS_BEGIN}
 ## TestGuard
 
-This project's tests are verified by [TestGuard](https://github.com/raccioly/testguard).
-Before writing or changing tests, run \`testguard status --json\` and follow \`next\`.
+This repository's tests are verified by [TestGuard](https://github.com/raccioly/testguard).
+Before writing or changing tests, run \`testguard status --json [dir]\` and follow \`next\`.
 The full operating loop and the verdict table are in \`.claude/skills/testguard/SKILL.md\`.
 Never make a fault die by editing \`testguard.claims.json\`; write the test. Claim edits are recorded in the evidence.
+
+${lines.join('\n')}
 ${AGENTS_END}`;
-const GITIGNORE_LINES = ['.testguard/evidence.json', '.testguard/evidence-provisional.json', '.testguard/evidence-partial.json', '.testguard/brief.json', '.testguard/gate.json', '.testguard/scaffold-*.json'];
+}
+
+/** The git root of `dir`, or null outside a repository. */
+export function gitRoot(dir) {
+  const r = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd: dir, encoding: 'utf8' });
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+/** Is `file` (absolute) ignored by git in `root`? False outside a repository. */
+export function isGitIgnored(root, file) {
+  if (!root) return false;
+  return spawnSync('git', ['check-ignore', '-q', '--', file], { cwd: root }).status === 0;
+}
 
 /**
- * Install the agent operating layer into a consumer project: the skill, the
- * session-start hook, an AGENTS.md section and the .gitignore lines.
- * Idempotent: re-running changes nothing unless --force replaces the skill.
+ * Install the operating layer.
+ *
+ * Two layers, two places. The AGENT layer — the skill, the session-start
+ * hook, the AGENTS.md section — goes to the git root, because that is where
+ * an agent session runs; installed in a subdirectory it never fires and is
+ * never read (a field report installed it in a backend/ folder and got
+ * nothing). The PROJECT layer — the `.gitignore` lines beside the claims
+ * file — stays in the project directory. `here: true` keeps everything in
+ * the project directory for a subdirectory that is its own agent root.
+ *
+ * Idempotent per project: a second project in the same repository adds a
+ * hook line and an AGENTS.md bullet, never duplicates. Every written file is
+ * checked against .gitignore; an ignored file is reported as ignored, never
+ * as something to commit.
  */
-export function initProject({ projectDir, force = false }) {
+const CI_EVIDENCE_HELPERS = {
+  github: `#!/bin/sh
+# Fetch the evidence CI wrote on a branch, then brief from it. Run it when you
+# want it: the session-start hook never touches the network, and this script
+# exits 0 with a message whenever anything is missing.
+BRANCH="\${1:-main}"
+OUT=.testguard/ci
+command -v gh >/dev/null 2>&1 || { echo "gh is not installed; see README > Read CI's evidence locally" >&2; exit 0; }
+command -v testguard >/dev/null 2>&1 || { echo "testguard is not on PATH; install it or run npx testguard-cli brief --evidence <file>" >&2; exit 0; }
+mkdir -p "$OUT" || exit 0
+gh run download --name "testguard-evidence-$BRANCH" --dir "$OUT" >/dev/null 2>&1 || { echo "no testguard-evidence-$BRANCH artifact to download" >&2; exit 0; }
+exec testguard brief . --text --evidence "$OUT/ci-self-evidence.json"
+`,
+  gitlab: `#!/bin/sh
+# Fetch the evidence CI wrote on a branch, then brief from it. Run it when you
+# want it: the session-start hook never touches the network, and this script
+# exits 0 with a message whenever anything is missing.
+BRANCH="\${1:-main}"
+OUT=.testguard/ci
+command -v glab >/dev/null 2>&1 || { echo "glab is not installed; see README > Read CI's evidence locally" >&2; exit 0; }
+command -v testguard >/dev/null 2>&1 || { echo "testguard is not on PATH; install it or run npx testguard-cli brief --evidence <file>" >&2; exit 0; }
+mkdir -p "$OUT" || exit 0
+glab ci artifact "$BRANCH" testguard:probe --path "$OUT/" >/dev/null 2>&1 || { echo "no testguard:probe artifact to download for $BRANCH" >&2; exit 0; }
+exec testguard brief . --text --evidence "$OUT/.testguard/evidence.json"
+`,
+};
+
+export function initProject({ projectDir, force = false, here = false, ciEvidence, mcp = false }) {
+  projectDir = realpathSync(resolve(projectDir));
+  const root = here ? null : gitRoot(projectDir);
+  const agentRoot = root ?? projectDir;
+  const ignoreRoot = root ?? gitRoot(projectDir);
+  const dir = (relative(agentRoot, projectDir).split(sep).join('/')) || '.';
   const done = [];
+  const notes = [];
+  let mcpConfig;
   const skipped = [];
+  const warnings = [];
+  const rel = (p) => relative(agentRoot, p).split(sep).join('/');
+  const note = (p) => { if (isGitIgnored(ignoreRoot, p)) warnings.push(`${rel(p)} is ignored by .gitignore — it was written, but git will not track it and agents in a fresh clone will never see it; unignore it or move it`); };
 
-  const skillDir = join(projectDir, '.claude', 'skills', 'testguard');
+  const skillDir = join(agentRoot, '.claude', 'skills', 'testguard');
   const skillPath = join(skillDir, 'SKILL.md');
   if (!existsSync(skillPath) || force) {
+    const replaced = force && existsSync(skillPath);
     mkdirSync(skillDir, { recursive: true });
     writeFileSync(skillPath, readFileSync(join(TEMPLATES, 'SKILL.md'), 'utf8'));
-    done.push(`.claude/skills/testguard/SKILL.md${force && existsSync(skillPath) ? ' (replaced)' : ''}`);
+    done.push(`${rel(skillPath)}${replaced ? ' (replaced)' : ''}`);
+    note(skillPath);
   } else {
-    skipped.push('.claude/skills/testguard/SKILL.md exists (use --force to replace)');
+    skipped.push(`${rel(skillPath)} exists (use --force to replace)`);
   }
 
-  const settingsPath = join(projectDir, '.claude', 'settings.json');
+  const settingsPath = join(agentRoot, '.claude', 'settings.json');
   let settings = {};
   if (existsSync(settingsPath)) {
     try {
       settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
     } catch (e) {
-      throw new Error(`.claude/settings.json is not valid JSON (${e.message}); fix it before init can add the hook`);
+      throw new Error(`${rel(settingsPath)} is not valid JSON (${e.message}); fix it before init can add the hook`);
     }
   }
   settings.hooks ??= {};
   settings.hooks.SessionStart ??= [];
-  const already = JSON.stringify(settings.hooks.SessionStart).includes(HOOK_CMD);
-  if (already) {
-    skipped.push('SessionStart hook already present in .claude/settings.json');
+  const cmd = hookCommand(dir);
+  const hasCmd = settings.hooks.SessionStart.some((e) => JSON.stringify(e).includes(cmd));
+  // Any earlier hook that reached for npx — `-y` fetched outright, and
+  // `--no-install` still resolves the packument from the registry — is replaced.
+  // Which project a hook is for is the token right after `brief --text`, if
+  // that token is an argument rather than a redirect or a shell operator.
+  // Testing for any non-space there mistook `brief --text 2>/dev/null` for a
+  // hook belonging to a directory, so a legacy root hook was never replaced.
+  const hookDir = (text) => {
+    const m = /brief --text(?:\s+([^\s"|;&]+))?/.exec(text);
+    const token = m?.[1];
+    return !token || token.startsWith('2>') || token.startsWith('>') ? '.' : token;
+  };
+  const legacy = settings.hooks.SessionStart.findIndex((e) => {
+    const text = JSON.stringify(e);
+    return /npx\s+(-y|--no-install)[^"]*brief --text/.test(text) && hookDir(text) === dir;
+  });
+  if (hasCmd) {
+    skipped.push(`SessionStart hook for ${dir === '.' ? 'this project' : dir} already present in ${rel(settingsPath)}`);
   } else {
-    settings.hooks.SessionStart.push({ hooks: [{ type: 'command', command: HOOK_CMD }] });
+    if (legacy !== -1) {
+      settings.hooks.SessionStart.splice(legacy, 1);
+      done.push(`${rel(settingsPath)}: replaced the network-reaching npx hook with a local-then-PATH one`);
+    }
+    settings.hooks.SessionStart.push({ hooks: [{ type: 'command', command: cmd }] });
     mkdirSync(dirname(settingsPath), { recursive: true });
     writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
-    done.push('.claude/settings.json: SessionStart hook → brief --text');
+    done.push(`${rel(settingsPath)}: SessionStart hook → brief --text${dir === '.' ? '' : ` ${dir}`} (local install first, npx --no-install fallback, never a fetch)`);
+    note(settingsPath);
   }
 
-  const agentsPath = join(projectDir, 'AGENTS.md');
+  const agentsPath = join(agentRoot, 'AGENTS.md');
   const agents = existsSync(agentsPath) ? readFileSync(agentsPath, 'utf8') : '';
-  if (agents.includes(AGENTS_BEGIN)) {
-    skipped.push('AGENTS.md already has the TestGuard section');
+  const begin = agents.indexOf(AGENTS_BEGIN);
+  const end = agents.indexOf(AGENTS_END);
+  if (begin !== -1 && end !== -1) {
+    const block = agents.slice(begin, end + AGENTS_END.length);
+    const entries = [...block.matchAll(/^- (?:This project|`([^`]+)\/`)/gm)].map((m) => m[1] ?? '.');
+    const legacyBlock = entries.length === 0; // a pre-0.6 section with no project list
+    if (entries.includes(dir)) {
+      skipped.push(`AGENTS.md already has the TestGuard section for ${dir === '.' ? 'this project' : dir}`);
+    } else {
+      writeFileSync(agentsPath, agents.slice(0, begin) + agentsBlock([...entries, dir]) + agents.slice(end + AGENTS_END.length));
+      done.push(legacyBlock ? `AGENTS.md: TestGuard section rewritten to list ${dir}` : `AGENTS.md: TestGuard section now lists ${dir}`);
+      note(agentsPath);
+    }
   } else {
-    writeFileSync(agentsPath, (agents ? agents.replace(/\s*$/, '\n\n') : '# Agent instructions\n\n') + AGENTS_BLOCK + '\n');
+    writeFileSync(agentsPath, (agents ? agents.replace(/\s*$/, '\n\n') : '# Agent instructions\n\n') + agentsBlock([dir]) + '\n');
     done.push(agents ? 'AGENTS.md: TestGuard section appended' : 'AGENTS.md created with the TestGuard section');
+    note(agentsPath);
   }
 
   const giPath = join(projectDir, '.gitignore');
@@ -71,12 +201,35 @@ export function initProject({ projectDir, force = false }) {
   const dirIgnored = entries.some((x) => /^\/?\.testguard\/?$/.test(x));
   const missing = dirIgnored ? [] : GITIGNORE_LINES.filter((l) => !entries.includes(l));
   if (dirIgnored) {
-    skipped.push('.gitignore ignores .testguard/ entirely — note that baseline.json should be committed; ignore only the regenerated files if you adopt a baseline');
+    skipped.push(`${rel(giPath)} ignores .testguard/ entirely — note that baseline.json should be committed; ignore only the regenerated files if you adopt a baseline`);
   } else if (missing.length) {
     writeFileSync(giPath, (gi ? gi.replace(/\s*$/, '\n') : '') + '# TestGuard: regenerated per run (baseline.json IS committed)\n' + missing.join('\n') + '\n');
-    done.push(`.gitignore: ${missing.length} line${missing.length === 1 ? '' : 's'} added`);
+    done.push(`${rel(giPath)}: ${missing.length} line${missing.length === 1 ? '' : 's'} added`);
   } else {
-    skipped.push('.gitignore already ignores the regenerated files');
+    skipped.push(`${rel(giPath)} already ignores the regenerated files`);
+  }
+  if (ciEvidence) {
+    const helperPath = join(projectDir, '.testguard', 'fetch-ci-evidence.sh');
+    const body = CI_EVIDENCE_HELPERS[ciEvidence];
+    if (!body) throw new Error(`--ci-evidence must be github or gitlab, not ${ciEvidence}`);
+    if (!existsSync(helperPath) || force) {
+      mkdirSync(dirname(helperPath), { recursive: true });
+      writeFileSync(helperPath, body, { mode: 0o755 });
+      done.push(`.testguard/fetch-ci-evidence.sh (${ciEvidence}) — run it on demand; the session-start hook stays offline`);
+    } else {
+      skipped.push('.testguard/fetch-ci-evidence.sh exists (use --force to replace)');
+    }
+  }
+  if (mcp) {
+    // Printed, never written: a harness's own config is the person's file
+    // (and often global), so init shows the snippet and lets them place it.
+    const cmd = { command: 'npx', args: ['-y', 'testguard-cli', 'mcp'] };
+    mcpConfig = {
+      'Claude Code — .mcp.json in the project root, or `claude mcp add`': { mcpServers: { testguard: cmd } },
+      'Cursor — .cursor/mcp.json': { mcpServers: { testguard: cmd } },
+      'Codex CLI — ~/.codex/config.toml': '[mcp_servers.testguard]\ncommand = "npx"\nargs = ["-y", "testguard-cli", "mcp"]',
+    };
+    notes.push('MCP: five read-only tools (status, brief, claims, evidence, next_command). Nothing there runs a probe.');
   }
-  return { done, skipped };
+  return { done, skipped, warnings, agentRoot, projectDir, dir, ...(mcpConfig ? { mcpConfig } : {}) };
 }

package/src/init/templates/SKILL.md

@@ -45,7 +45,7 @@ code by construction. So, for every source file you create or change:
    thin wrapper whose logic is claimed elsewhere): a `path` entry in
    `testguard.ignore.json` with a reason and, where possible, an `expires`.
    The gate prints every entry it relied on; a reviewer reads them.
-4. Then `testguard probe --claim <ID> --include-dirty` for the new claim.
+4. Then `testguard admit <test-file> --claim <ID>` for the new claim's test (or `testguard probe --claim <ID> --include-dirty` for the full report).
 
 ## Verdict → action
 
@@ -63,8 +63,8 @@ code by construction. So, for every source file you create or change:
 
 1. `testguard status --json` → take `next.target`.
 2. Write the test. It must **fail when the fault is applied and pass on HEAD**. To check the first half by hand: apply `find` → `replace` in the target file, run the defender, restore.
-3. `testguard probe --claim <ID> --include-dirty` — probes your uncommitted test without touching the tree. `--confirm 1` gives a fast **provisional** signal; a `?` on a verdict means unconfirmed.
-4. When it is `killed` at `--confirm 3`, commit the test.
+3. `testguard admit <test-file> --claim <ID>` — the two gates as one verb, on your uncommitted test, without touching the tree: `ADMITTED` (exit 0) means the test is green on HEAD and fails on every fault of the claim, 3/3; `NOT ADMITTED` (exit 1) names the first blocking fault and what to do. `--fault <FID>` judges one fault; `--confirm 1` gives a fast **provisional** `ADMITTED?` that must be confirmed at 3 before you commit. (`testguard probe --claim <ID> --include-dirty` is the same run with the full report.)
+4. When it is `ADMITTED` at `--confirm 3`, commit the test.
 5. When everything is killed or baselined, `testguard baseline` if `next` says so, and commit `.testguard/baseline.json`.
 
 ## Rules that are not yours to bend

package/src/mcp/server.mjs

@@ -0,0 +1,104 @@
+import { TOOLS } from './tools.mjs';
+
+/**
+ * A Model Context Protocol server over stdio, hand-rolled.
+ *
+ * Why not the official SDK: this tool has one exact-pinned runtime dependency
+ * and intends to keep it that way (AGENTS.md rule 8). The surface here is
+ * three methods and five read-only tools and will not grow, so the protocol
+ * is written out rather than imported. The version is pinned below and the
+ * conformance is covered by tests that speak the wire format.
+ *
+ * JSON-RPC 2.0 framing: one message per line (newline-delimited JSON), which
+ * is what stdio transports use. A notification (no `id`) is never answered.
+ */
+export const PROTOCOL_VERSION = '2025-06-18';
+
+const ERROR = { parse: -32700, invalidRequest: -32600, methodNotFound: -32601, invalidParams: -32602, internal: -32603 };
+
+const ok = (id, result) => ({ jsonrpc: '2.0', id, result });
+const err = (id, code, message, data) => ({ jsonrpc: '2.0', id, error: { code, message, ...(data ? { data } : {}) } });
+
+/** Everything an agent may ask for, with the version stamped onto each call. */
+export function handle(message, { version = '0.0.0' } = {}) {
+  if (message === null || typeof message !== 'object' || Array.isArray(message)) return err(null, ERROR.invalidRequest, 'a request must be a JSON object');
+  const { id, method, params } = message;
+  const isNotification = id === undefined || id === null;
+
+  switch (method) {
+    case 'initialize':
+      return isNotification ? null : ok(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        // Read-only: no prompts, no resources, no sampling. Saying so is part
+        // of the contract — nothing here can change a claims file.
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: 'testguard', version },
+        instructions: 'Read testguard_status first: it carries the one next action. Run the command it names in your own terminal — these tools never run a probe, because a probe is long-running, budgeted, and the person should see it happen.',
+      });
+
+    case 'notifications/initialized':
+    case 'notifications/cancelled':
+      return null;
+
+    case 'ping':
+      return isNotification ? null : ok(id, {});
+
+    case 'tools/list':
+      return isNotification ? null : ok(id, { tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema, annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false } })) });
+
+    case 'tools/call': {
+      if (isNotification) return null;
+      const tool = TOOLS.find((t) => t.name === params?.name);
+      if (!tool) return err(id, ERROR.invalidParams, `unknown tool: ${params?.name}`);
+      try {
+        const result = tool.handler({ ...(params?.arguments ?? {}), __version: version });
+        return ok(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], structuredContent: result, isError: false });
+      } catch (e) {
+        // A tool failure is a tool result, not a protocol error: the agent
+        // should read the reason and act, not lose the connection.
+        return ok(id, { content: [{ type: 'text', text: `${tool.name} failed: ${e.message}` }], isError: true });
+      }
+    }
+
+    default:
+      return isNotification ? null : err(id, ERROR.methodNotFound, `unknown method: ${method}`);
+  }
+}
+
+/**
+ * Speak the protocol on a pair of streams. Resolves when input ends, so the
+ * caller can await a clean shutdown.
+ */
+export function serve({ input = process.stdin, output = process.stdout, version = '0.0.0' } = {}) {
+  return new Promise((resolveDone) => {
+    let buffer = '';
+    const write = (msg) => {
+      if (msg) output.write(JSON.stringify(msg) + '\n');
+    };
+    input.setEncoding?.('utf8');
+    input.on('data', (chunk) => {
+      buffer += chunk;
+      let nl;
+      while ((nl = buffer.indexOf('\n')) !== -1) {
+        const line = buffer.slice(0, nl).trim();
+        buffer = buffer.slice(nl + 1);
+        if (!line) continue;
+        let message;
+        try {
+          message = JSON.parse(line);
+        } catch {
+          write(err(null, ERROR.parse, 'invalid JSON'));
+          continue;
+        }
+        try {
+          write(handle(message, { version }));
+        } catch (e) {
+          // The server outlives any single bad request.
+          write(err(message?.id ?? null, ERROR.internal, e.message));
+        }
+      }
+    });
+    input.on('end', () => resolveDone(0));
+    input.on('close', () => resolveDone(0));
+  });
+}

package/src/mcp/tools.mjs

@@ -0,0 +1,114 @@
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { computeStatus } from '../status/status.mjs';
+import { buildBrief, buildUnclaimedBrief } from '../brief/brief.mjs';
+import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
+import { scanAnnotations, reconcile } from '../claims/annotations.mjs';
+import { computeRemovedClaims } from '../claims/removed.mjs';
+import { readSpecDoc } from '../evidence/writer.mjs';
+import { resolveChangedRef, withChangedRef } from '../gate/changed.mjs';
+
+/**
+ * The read-only surface an agent needs, in any harness.
+ *
+ * TestGuard's operating loop currently lives in a Claude Code skill and a
+ * session-start hook, and both vanish the moment the harness is something
+ * else. These tools expose the documents the tool already computes, so the
+ * loop survives that change.
+ *
+ * Every tool is read-only and none of them probes. A probe is long-running
+ * and budgeted, and the human should see it happen: `next_command` hands back
+ * the exact shell line for the agent to run in its own terminal instead.
+ */
+const projectOf = (args) => resolve(args?.dir ?? '.');
+const evidenceOf = (args) => (args?.evidence ? resolve(args.evidence) : undefined);
+
+const DIR = { type: 'string', description: 'Project directory (where testguard.claims.json lives). Defaults to the current directory.' };
+const EVIDENCE = { type: 'string', description: "Read this evidence document instead of the project's own — CI's, fetched as an artifact." };
+const CHANGED = { type: 'string', description: 'A git reference to measure the change against, so claim coverage of the change is included.' };
+
+const statusFor = (args) => {
+  const projectDir = projectOf(args);
+  return withChangedRef(resolveChangedRef({ explicit: args?.changed }), (changedRef) =>
+    computeStatus({ projectDir, toolVersion: args?.__version ?? '0.0.0', changedRef, evidence: evidenceOf(args) }));
+};
+
+export const TOOLS = [
+  {
+    name: 'testguard_status',
+    description: 'Where this project stands and the ONE next action, as the machine-readable status document: state, next {action, command, why}, counts, stale inputs, faults edited since they were probed, and the ranked findings. This is the single source of truth every other rendering derives from — read it before deciding anything.',
+    inputSchema: { type: 'object', properties: { dir: DIR, changed: CHANGED, evidence: EVIDENCE }, additionalProperties: false },
+    handler: (args) => statusFor(args),
+  },
+  {
+    name: 'testguard_brief',
+    description: 'Where the test suite is blind, ranked and capped, with one actionable hint per finding and unclaimed changed files first. Read this before writing or changing code, which is what the session-start hook does for harnesses that have one.',
+    inputSchema: { type: 'object', properties: { dir: DIR, changed: CHANGED, evidence: EVIDENCE, max: { type: 'integer', minimum: 1, maximum: 50 } }, additionalProperties: false },
+    handler: (args) => {
+      const projectDir = projectOf(args);
+      const evPath = evidenceOf(args) ?? join(projectDir, '.testguard', 'evidence.json');
+      const status = (() => {
+        try {
+          return statusFor(args);
+        } catch {
+          return undefined; // a brief must never fail because status could not be computed
+        }
+      })();
+      if (!existsSync(evPath)) {
+        if (status?.changes?.uncovered?.length) {
+          return buildUnclaimedBrief({ tool: { name: 'testguard', version: args?.__version ?? '0.0.0' }, next: status.next, changes: status.changes });
+        }
+        return { note: `no evidence at ${evPath}: nothing has been probed yet`, next: status?.next };
+      }
+      const evidence = readSpecDoc('evidence', evPath);
+      const basePath = join(projectDir, '.testguard', 'baseline.json');
+      const baseline = existsSync(basePath) ? readSpecDoc('baseline', basePath) : undefined;
+      return buildBrief(evidence, baseline, { max: args?.max ?? 20, next: status?.next, changes: status?.changes });
+    },
+  },
+  {
+    name: 'testguard_claims',
+    description: "What this project claims must be true, each with its faults and defenders, plus drift against `@claim` annotations in source and — when `since` is given — every claim or fault that existed at that reference and does not now. A claim that disappeared is invisible to every other check.",
+    inputSchema: { type: 'object', properties: { dir: DIR, since: { type: 'string', description: 'A git reference: report claims and faults removed since it.' } }, additionalProperties: false },
+    handler: (args) => {
+      const projectDir = projectOf(args);
+      const path = defaultClaimsPath(projectDir);
+      if (!existsSync(path)) return { path, claims: [], note: 'no claims file in this project yet' };
+      const claims = loadClaims(path);
+      const drift = reconcile(claims, scanAnnotations(projectDir));
+      const removed = args?.since
+        ? computeRemovedClaims({ projectDir, ref: args.since, claimsPath: path, current: claims, evidencePath: join(projectDir, '.testguard', 'evidence.json'), toolVersion: args?.__version ?? '0.0.0' })
+        : undefined;
+      return { path, claims, drift, ...(removed ? { removed } : {}) };
+    },
+  },
+  {
+    name: 'testguard_evidence',
+    description: 'One run\'s findings on disk: every verdict with the runs that produced it. Pass `claim` (and optionally `fault`) for a single record instead of the whole document, which can be large.',
+    inputSchema: {
+      type: 'object',
+      properties: { dir: DIR, evidence: EVIDENCE, claim: { type: 'string', description: 'Return only this claim\'s records.' }, fault: { type: 'string', description: 'With `claim`: only this fault\'s record.' } },
+      additionalProperties: false,
+    },
+    handler: (args) => {
+      const projectDir = projectOf(args);
+      const evPath = evidenceOf(args) ?? join(projectDir, '.testguard', 'evidence.json');
+      if (!existsSync(evPath)) return { note: `no evidence at ${evPath}: run a probe first`, path: evPath };
+      const doc = readSpecDoc('evidence', evPath);
+      if (!args?.claim) return doc;
+      const records = doc.records.filter((r) => r.claim.id === args.claim && (!args.fault || r.subject.id === args.fault));
+      return { ...doc, records, filtered: { claim: args.claim, ...(args.fault ? { fault: args.fault } : {}) } };
+    },
+  },
+  {
+    name: 'testguard_next_command',
+    description: 'The exact shell command to run next, with the reason. Run it yourself in a terminal: a probe is long-running and budgeted, and the person should see it happen. This tool never runs anything.',
+    inputSchema: { type: 'object', properties: { dir: DIR, changed: CHANGED, evidence: EVIDENCE }, additionalProperties: false },
+    handler: (args) => {
+      const doc = statusFor(args);
+      return { state: doc.state, action: doc.next.action, command: doc.next.command, why: doc.next.why, ...(doc.next.target ? { target: doc.next.target } : {}), ...(doc.next.file ? { file: doc.next.file } : {}) };
+    },
+  },
+];
+
+export const TOOL_NAMES = TOOLS.map((t) => t.name);

package/src/probe/attribution.mjs

@@ -0,0 +1,123 @@
+/**
+ * The decisions escalation and flake measurement make, as pure functions.
+ *
+ * These used to live inline in `probeOne`, which meant the only thing that
+ * could falsify them was a full fixture probe — a 50-second acceptance test
+ * standing in for a rule you can state in three lines. `classify()` has always
+ * been pure for this reason: the order of its checks *is* the spec, and every
+ * branch is unit-testable without a runner. Same principle here.
+ *
+ * Nothing in this file runs a test, touches the filesystem, or knows what a
+ * worktree is. Everything it needs is passed in.
+ */
+
+const isKill = (r) => r.outcome === 'fail' && (r.assertionFailures ?? 0) > 0;
+
+/**
+ * Fold one escalation run into the running attribution state.
+ *
+ * A test is an undeclared killer only if it fails in **every** run: a single
+ * run cannot say, because a test that is flaky elsewhere in the suite would
+ * take the credit. So the killer set is an intersection, seeded by the first
+ * run rather than by the empty set.
+ *
+ * Once the intersection is empty no further run can name a killer, so the
+ * caller may stop early. Stopping can only fail to *name* a killer, never
+ * upgrade a verdict, which is the pessimistic side and therefore the safe one.
+ */
+export function foldEscalationRun(state, { run, failedTests }) {
+  const runs = [...state.runs, run];
+  const killers = state.killers === null ? new Set(failedTests) : new Set([...state.killers].filter((t) => failedTests.includes(t)));
+  return { runs, killers, stoppedEarly: killers.size === 0 ? 'no-common-failure' : undefined };
+}
+
+/** The initial attribution state, before any escalation run. */
+export const escalationStart = () => ({ runs: [], killers: null, stoppedEarly: undefined });
+
+/**
+ * What escalation concluded. `undeclaredKillers` is named only when a test
+ * failed in all N runs AND every run was a genuine kill (an assertion
+ * failure). A suite that errored or timed out proves nothing about the fault,
+ * so it never earns an attribution.
+ */
+export function escalationResult(state, confirmRuns) {
+  const complete = state.runs.length === confirmRuns;
+  const attributable = state.killers !== null && state.killers.size > 0 && complete && state.runs.every(isKill);
+  return {
+    escalated: true,
+    escalationRuns: state.runs,
+    ...(state.stoppedEarly ? { escalationStoppedEarly: state.stoppedEarly } : {}),
+    ...(attributable ? { reason: 'killed-by-undeclared-tests', undeclaredKillers: [...state.killers].sort() } : {}),
+  };
+}
+
+/**
+ * The defenders' flake rate on unmodified source.
+ *
+ * Only runs that **actually ran** carry information. A load error or a timeout
+ * measures the environment, not the suite's stability, and counting either as
+ * a "failure" would invent flakiness that was never observed. Returns
+ * `undefined` when nothing was measurable, so the caller omits the field
+ * rather than recording a rate of zero it cannot support.
+ */
+export function flakeRate(runs) {
+  const measured = runs.filter((r) => r.outcome === 'pass' || r.outcome === 'fail');
+  if (!measured.length) return undefined;
+  return { runs: measured.length, failures: measured.filter((r) => r.outcome === 'fail').length };
+}
+
+/**
+ * The tests that actually failed on the fault, by file. Only these are its
+ * killers; everything else in a run is noise for attribution purposes.
+ */
+export function killersFromRuns(probeRuns) {
+  return [...new Set(probeRuns.flatMap((r) => r.failedTests ?? []).map((t) => t.split('::')[0]).filter(Boolean))];
+}
+
+/**
+ * The `subject` of an evidence record. `contentHash` is what makes a fault edit
+ * visible: weakening a fault after it survived changes this hash, and `status`
+ * reports the change with the verdict the fault used to have. It is deliberately
+ * NOT part of the fingerprint — repairing a rotted anchor must not churn the
+ * baseline — which is exactly why it has to be recorded separately.
+ */
+export function subjectOf(fault, sha256) {
+  return {
+    kind: 'fault',
+    id: fault.id,
+    description: fault.description,
+    file: fault.file,
+    faultClass: fault.faultClass,
+    producedBy: fault.producedBy,
+    contentHash: sha256(`${fault.find}\n${fault.replace}`),
+  };
+}
+
+/**
+ * May a prior record stand in for this one, or must the fault be probed again?
+ *
+ * Same source, same defenders, same N — and the SAME FAULT. The last is not a
+ * refinement: a verdict is an answer about one specific `find`/`replace`, and
+ * once those change the old answer is not an answer to the new question.
+ * Without it, weakening a fault that survived keeps its old verdict, and
+ * repairing a rotted anchor keeps `unverifiable` — the evidence reporting a
+ * result that was never measured against the fault the file now contains.
+ * `status` flags the changed hash afterwards, but by then the evidence has
+ * already said something untrue.
+ *
+ * A prior that predates `contentHash` cannot be compared, so it is re-probed.
+ * The cost of re-measuring is a run; the cost of the other direction is a
+ * verdict nobody measured.
+ */
+export function isReusable(prior, current) {
+  if (!prior || !prior.subject?.contentHash) return false;
+  // A record that exists because the probe threw is a statement about the run,
+  // not about the code. Reusing it would make one disturbed run permanent.
+  if (prior.detail?.reason === 'probe-error') return false;
+  const same = (x, y) => JSON.stringify(x) === JSON.stringify(y);
+  return prior.inputs.targetHash === current.inputs.targetHash
+    && same(prior.inputs.defenderHashes, current.inputs.defenderHashes)
+    && same(prior.defenders.requested, current.requested)
+    && same(prior.defenders.resolved, current.resolved)
+    && prior.subject.contentHash === current.contentHash;
+}