testguard-cli 0.4.0 → 0.6.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/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

@@ -21,13 +21,31 @@ which files exist. `state` is one of:
 | state | meaning | you do |
 |---|---|---|
 | `no-claims` | no `testguard.claims.json` | `testguard scaffold <file>` for a file with guards; replace every `TODO:` statement with what the code guarantees; keep or drop each proposal; move the claims into `testguard.claims.json` |
+| `unclaimed-changes` | files you changed carry no claim (only when a reference is known: `--changed <ref>`, or CI's base branch) | `next.file` names the first; `testguard scaffold <file>` and state the claim, or add a `testguard.ignore.json` path entry with a reason a reviewer will accept. **Before** writing more code. |
 | `unprobed` | claims never probed | `testguard probe` |
 | `evidence-stale` | code, tests or claims changed since the evidence | `testguard probe --include-dirty` (or `--claim <ID>` for one) |
 | `provisional-only` | only `--confirm 1` evidence exists | `testguard probe --confirm 3` |
 | `unproven` | a finding is not covered by the baseline | `next.target` names it; see the verdict table |
 | `clean` | everything killed or baselined | `testguard baseline` if `next` says so; otherwise nothing |
 
-Exit codes: `0` clean · `1` unproven claims (or drift) · `2` precondition failed / nothing to do yet · `3` usage.
+Exit codes: `0` clean · `1` unproven claims (or drift, or unclaimed changes) · `2` precondition failed / nothing to do yet · `3` usage.
+
+## Every change needs a claim
+
+`probe` verifies only the claims that exist; it is silent about unclaimed
+code by construction. So, for every source file you create or change:
+
+1. `testguard gate --changed HEAD --include-dirty` (the pre-commit shape; in a
+   PR, `--changed origin/<base>`). One unclaimed file exits `1`.
+2. For each `UNCLAIMED` file: `testguard scaffold <file>` proposes faults;
+   state what the code guarantees; add the claim, its faults and its
+   `defendedBy` to `testguard.claims.json`. A new test file must be named in
+   some claim's `defendedBy`, or it is unclaimed too.
+3. Only when a file genuinely carries nothing to claim (generated code, a
+   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 admit <test-file> --claim <ID>` for the new claim's test (or `testguard probe --claim <ID> --include-dirty` for the full report).
 
 ## Verdict → action
 
@@ -45,8 +63,8 @@ Exit codes: `0` clean · `1` unproven claims (or drift) · `2` precondition fail
 
 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/contention.mjs

@@ -0,0 +1,60 @@
+import { spawnSync } from 'node:child_process';
+
+/**
+ * Concurrent test runners (issue #26).
+ *
+ * A probe runs the defenders 3× clean and 3× with each fault applied. Heavy
+ * suites time out under parallel CPU load, and a timeout is a verdict —
+ * `TIMEOUT` or `FLAKY-DEFENDER` — that says nothing about the claim. A field
+ * report serialised everything by hand for exactly this reason. We cannot
+ * prevent the contention, but we can name it: warn before the first run, and
+ * record it on the evidence so a later reader of a flaky verdict knows the
+ * run was contended.
+ *
+ * Best effort by design: the detector never fails a probe, and a process list
+ * it cannot read is simply no detection.
+ */
+
+const RUNNER_RE = /\b(vitest|jest|playwright|mocha|ava|karma|cypress)\b/i;
+// Our own child processes and this process are not contention.
+const SELF_RE = /testguard/i;
+
+/** Rows of the process table as `{ pid, command }`, or [] when it cannot be read. */
+export function processList({ platform = process.platform, run = spawnSync } = {}) {
+  try {
+    const r = platform === 'win32'
+      ? run('wmic', ['process', 'get', 'ProcessId,CommandLine', '/format:csv'], { encoding: 'utf8', timeout: 5000 })
+      : run('ps', ['-Ao', 'pid=,args='], { encoding: 'utf8', timeout: 5000 });
+    if (r.status !== 0 || !r.stdout) return [];
+    return r.stdout.split('\n').map((line) => {
+      const m = platform === 'win32' ? /^[^,]*,(.*),(\d+)\s*$/.exec(line) : /^\s*(\d+)\s+(.*)$/.exec(line);
+      if (!m) return null;
+      const [pid, command] = platform === 'win32' ? [m[2], m[1]] : [m[1], m[2]];
+      return { pid: Number(pid), command: command.trim() };
+    }).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Test runners already running, other than ours. Returns
+ * `{ detected, runners: [{ pid, command }] }`; `detected` is false when
+ * nothing was found or the process list could not be read.
+ */
+export function detectContention({ self = process.pid, ...opts } = {}) {
+  const rows = processList(opts);
+  const runners = rows
+    .filter((p) => p.pid !== self && RUNNER_RE.test(p.command) && !SELF_RE.test(p.command))
+    // `ps` lists the grep/ps itself and any shell wrapper; a runner's command
+    // line always names its own binary, so require it to look like an exec.
+    .filter((p) => !/^\s*(ps|grep|wmic)\b/.test(p.command))
+    .map((p) => ({ pid: p.pid, command: p.command.length > 200 ? p.command.slice(0, 197) + '…' : p.command }));
+  return { detected: runners.length > 0, runners };
+}
+
+/** One line for the operator: what is running, and what it costs. */
+export const contentionWarning = (c) =>
+  `${c.runners.length} test runner${c.runners.length === 1 ? ' is' : 's are'} already running (${c.runners.map((r) => `pid ${r.pid}`).join(', ')}); ` +
+  'defenders run N times each here, and a suite that times out under parallel load yields TIMEOUT or FLAKY-DEFENDER — verdicts about the load, not the claim. ' +
+  'Wait for it to finish, or pass --serial to run one test file at a time.';

package/src/probe/discover.mjs

@@ -1,12 +1,21 @@
 import { join } from 'node:path';
 import { listTestFiles } from './runners/shared.mjs';
 import { fileImports } from './rank.mjs';
+import { classifyDefenders } from './mocks.mjs';
 
 /**
  * When a claim declares no defenders: the test files that import the fault's
- * target file, directly, by relative path or through a resolved alias. This
- * is what `nocover` measures against — no test file even imports the source.
+ * target file — directly, by relative path or through a resolved alias — and
+ * do NOT mock it. A file that mocks the target cannot detect any fault in it;
+ * counting it would make `nocover` under-report and waste probe runs on files
+ * that cannot fail. `nocover` therefore means exactly "no test file imports
+ * this source without mocking it".
  */
+export function discoverDefendersDetailed(projectDir, targetRel) {
+  const importing = listTestFiles(projectDir).filter((t) => fileImports(projectDir, join(projectDir, t), targetRel));
+  return { importing, ...classifyDefenders(projectDir, targetRel, importing) };
+}
+
 export function discoverDefenders(projectDir, targetRel) {
-  return listTestFiles(projectDir).filter((t) => fileImports(projectDir, join(projectDir, t), targetRel));
+  return discoverDefendersDetailed(projectDir, targetRel).canDetect;
 }