testguard-cli 0.5.0 → 0.7.0

package/src/brief/brief.mjs

@@ -2,26 +2,44 @@ import { gate } from '../baseline/baseline.mjs';
 import { summarize, formatVerdict } from '../render.mjs';
 
 export const HEADING = '## TEST BLINDSPOT CONTEXT';
+/** First line of every markdown brief, so a poster can find and update its own note instead of adding another. */
+export const MARKDOWN_MARKER = '<!-- testguard:brief -->';
 const ORDER = ['survived', 'nocover', 'unverifiable', 'fault-invalid', 'timeout', 'flaky-defender'];
 
 /** One line the agent can act on. Names the mechanism, never just the verdict. */
 export function hintFor(r) {
   const defenders = r.defenders.resolved.join(', ');
+  const base = hintBase(r, defenders);
+  const mocked = (r.defenders.mocking ?? []);
+  const never = (r.defenders.signals ?? []).filter((s) => s.signal === 'mocked-never-asserted').map((s) => s.file);
+  const extra = [
+    mocked.length ? `${mocked.length} importing test${mocked.length === 1 ? '' : 's'} mock${mocked.length === 1 ? 's' : ''} the target and cannot detect this (${mocked.join(', ')})` : '',
+    never.length ? `${never.join(', ')} mock${never.length === 1 ? 's' : ''} it and never assert${never.length === 1 ? 's' : ''} on it` : '',
+  ].filter(Boolean);
+  return extra.length ? `${base} ${extra.join('; ')}.` : base;
+}
+
+function hintBase(r, defenders) {
   switch (r.verdict) {
     case 'survived':
       return r.detail.reason === 'killed-by-undeclared-tests'
         ? `Only tests outside its declared defenders (${defenders}) catch this; fix the claim's defendedBy or move the assertion.`
         : `${defenders} stayed green with this fault applied; add an assertion that fails on it and passes on HEAD. If no test's outcome can change, first check the fault is observable at all.`;
     case 'nocover':
-      return `No test file matches ${r.defenders.requested.join(', ') || '(no defenders declared)'}; nothing defends this claim.`;
+      return r.defenders.discovered
+        ? 'No test file imports the target without mocking it; nothing defends this claim.'
+        : `No test file matches ${r.defenders.requested.join(', ') || '(no defenders declared)'}; nothing defends this claim.`;
     case 'unverifiable':
       return `Anchor ${r.detail.reason}; re-author fault ${r.subject.id} in the claims file before trusting this claim.`;
     case 'fault-invalid':
       return `Replacement does not load (${r.detail.reason}); fix the fault definition, not the code.`;
     case 'timeout':
       return 'Defenders time out with this fault applied; a hang is not a detection.';
-    case 'flaky-defender':
-      return `${defenders} not reliably green (${r.detail.reason}); fix the flake before trusting any verdict here.`;
+    case 'flaky-defender': {
+      const fr = r.detail.flakeRate;
+      const rate = fr && fr.failures > 0 ? ` — failed ${fr.failures} of ${fr.runs} runs on unmodified source` : '';
+      return `${defenders} not reliably green (${r.detail.reason})${rate}; fix the flake before trusting any verdict here.`;
+    }
     default:
       return '';
   }
@@ -31,7 +49,7 @@ function orderItems(a, b) {
   return (b.isNew - a.isNew) || (ORDER.indexOf(a.verdict) - ORDER.indexOf(b.verdict)) || ((b.rank ?? 0) - (a.rank ?? 0));
 }
 
-export function buildBrief(evidence, baseline, { max = 20, generatedAt = new Date().toISOString(), next, changes } = {}) {
+export function buildBrief(evidence, baseline, { max = 20, generatedAt = new Date().toISOString(), next, changes, install } = {}) {
   const g = gate(evidence.records, baseline);
   const toItem = (r, isNew) => ({
     fingerprint: r.fingerprint,
@@ -54,19 +72,21 @@ export function buildBrief(evidence, baseline, { max = 20, generatedAt = new Dat
     new: g.new.length + g.belowFloor.length,
     baselined: g.baselined.length,
   };
+  const kills = evidence.records.filter((r) => r.verdict === 'killed');
+  const coAuthored = kills.filter((r) => r.detail.independence?.class === 'co-authored').length;
   const unclaimed = changes?.uncovered?.length ? { ref: changes.ref, files: changes.uncovered } : undefined;
   const doc = { schemaVersion: 1, tool: evidence.tool, generatedAt, head: evidence.run.repo.head, heading: HEADING, summary, ...(next ? { next: { action: next.action, command: next.command, why: next.why } } : {}), ...(unclaimed ? { unclaimed } : {}), items, text: '' };
-  doc.text = renderBriefText({ ...doc, provisional: Boolean(evidence.run.provisional) }, { hasBaseline: Boolean(baseline), total: evidence.records.length });
+  doc.text = renderBriefText({ ...doc, provisional: Boolean(evidence.run.provisional), install }, { hasBaseline: Boolean(baseline), total: evidence.records.length, independence: kills.length ? { coAuthored, kills: kills.length } : undefined });
   return doc;
 }
 
-export function renderBriefText(brief, { hasBaseline, total }) {
+export function renderBriefText(brief, { hasBaseline, total, independence }) {
   const unproven = total - (brief.summary.byVerdict.killed ?? 0);
   const lines = [
     brief.heading,
     '',
     ...(brief.provisional ? ['**PROVISIONAL** — this evidence came from fewer than three confirmation runs; treat every verdict below as unconfirmed and re-probe with --confirm 3 before acting on it.', ''] : []),
-    `testguard ${brief.tool.version}${brief.head ? ` @ ${brief.head.slice(0, 12)}` : ''} — ${brief.summary.claims} claims, ${total} faults probed, ${unproven} unproven` +
+    `testguard ${brief.tool.version}${brief.install ? ` (${brief.install})` : ''}${brief.head ? ` @ ${brief.head.slice(0, 12)}` : ''} — ${brief.summary.claims} claims, ${total} faults probed, ${unproven} unproven` +
       (unproven === 0 ? '.' : hasBaseline ? ` (${brief.summary.new} new since baseline).` : ' (no baseline; everything is new).'),
   ];
   // Unclaimed changes come before everything else: the claim is written
@@ -76,6 +96,9 @@ export function renderBriefText(brief, { hasBaseline, total }) {
     lines.push('', `UNCLAIMED CHANGES since ${brief.unclaimed.ref}: ${n} changed file${n === 1 ? '' : 's'} carr${n === 1 ? 'ies' : 'y'} no claim. State the claim first; nothing below can see this code.`);
     for (const u of brief.unclaimed.files) lines.push(`  - ${u.file} (${u.kind}) → ${u.suggestion}`);
   }
+  // L3: a kill written in the same change as the code it guards is not
+  // independent evidence. One line, no per-item noise.
+  if (independence?.coAuthored) lines.push('', `${independence.coAuthored} of ${independence.kills} kills are co-authored with the code they defend — the test and the code were written in the same change, so those kills are not independent evidence.`);
   if (brief.next) lines.push('', `NEXT [${brief.next.action}]: ${brief.next.command}`, `  why: ${brief.next.why}`);
   if (brief.items.length === 0) {
     lines.push('', 'Every probed claim is defended. Keep it that way: new claims need a fault and a test that fails on it.');
@@ -111,3 +134,44 @@ export function buildUnclaimedBrief({ tool, next, changes, generatedAt = new Dat
   doc.text = lines.join('\n') + '\n';
   return doc;
 }
+
+const cell = (v) => String(v ?? '').replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+
+/**
+ * The brief as a merge-request note: same content, same order as the text —
+ * unclaimed changes first, then `next`, then the ranked findings, capped at
+ * `--max` — in GitLab/GitHub-flavoured markdown. Rendering only; the document
+ * it renders is the validated one.
+ */
+export function renderBriefMarkdown(brief, { hasBaseline, total, install } = {}) {
+  const unproven = total - (brief.summary.byVerdict.killed ?? 0);
+  const lines = [MARKDOWN_MARKER, brief.heading, ''];
+  if (brief.provisional) lines.push('**PROVISIONAL** — fewer than three confirmation runs; nothing below is confirmed. Re-probe with `--confirm 3`.', '');
+  lines.push(`\`testguard ${brief.tool.version}${install ? ` (${install})` : ''}\`${brief.head ? ` @ \`${brief.head.slice(0, 12)}\`` : ''} — **${brief.summary.claims}** claims, **${total}** faults probed, **${unproven}** unproven` +
+    (unproven === 0 ? '.' : hasBaseline ? ` (**${brief.summary.new}** new since baseline).` : ' (no baseline; everything is new).'));
+  if (brief.unclaimed) {
+    const n = brief.unclaimed.files.length;
+    lines.push('', `### Unclaimed changes since \`${brief.unclaimed.ref}\``, '', `${n} changed file${n === 1 ? '' : 's'} carr${n === 1 ? 'ies' : 'y'} no claim. State the claim first; nothing below can see this code.`, '');
+    for (const u of brief.unclaimed.files) lines.push(`- \`${u.file}\` (${u.kind}) → \`${u.suggestion}\``);
+  }
+  if (brief.next) lines.push('', `**Next** \`[${brief.next.action}]\`: \`${brief.next.command}\``, '', `> ${brief.next.why}`);
+  if (brief.items.length === 0) {
+    lines.push('', 'Every probed claim is defended. Keep it that way: new claims need a fault and a test that fails on it.');
+    return lines.join('\n') + '\n';
+  }
+  lines.push('', 'Where the test suite is blind, ranked. A **SURVIVED** fault means its defenders stayed green while the claim was false. Do not close these by asserting current behaviour; write a test that fails on the described fault and passes on HEAD.', '');
+  lines.push('| # | verdict | claim / fault | severity | file | what to do |', '|---|---|---|---|---|---|');
+  brief.items.forEach((it, i) => {
+    lines.push(`| ${i + 1} | ${it.isNew ? '**NEW** ' : ''}${formatVerdict(it.verdict)} | \`${cell(it.claimId)}/${cell(it.subjectId ?? '?')}\`<br>${cell(it.statement)} | ${it.severity} | ${it.file ? `\`${cell(it.file)}\`` : ''} | ${cell(it.hint)} |`);
+  });
+  if (unproven > brief.items.length) lines.push('', `… and ${unproven - brief.items.length} more in the evidence file.`);
+  return lines.join('\n') + '\n';
+}
+
+/** Markdown for the no-evidence-yet, unclaimed-changes-only brief. */
+export function renderUnclaimedMarkdown({ tool, next, changes, install }) {
+  const lines = [MARKDOWN_MARKER, HEADING, '', `\`testguard ${tool.version}${install ? ` (${install})` : ''}\` — no evidence yet; **${changes.uncovered.length}** unclaimed changed file${changes.uncovered.length === 1 ? '' : 's'} since \`${changes.ref}\`.`, '', `### Unclaimed changes since \`${changes.ref}\``, '', 'State the claim first; nothing can be probed for this code until it has one.', ''];
+  for (const u of changes.uncovered) lines.push(`- \`${u.file}\` (${u.kind}) → \`${u.suggestion}\``);
+  if (next) lines.push('', `**Next** \`[${next.action}]\`: \`${next.command}\``, '', `> ${next.why}`);
+  return lines.join('\n') + '\n';
+}

package/src/claims/removed.mjs

@@ -0,0 +1,161 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { git, GitError, repoRoot } from '../git.mjs';
+import { readSpecDoc } from '../evidence/writer.mjs';
+import { defaultIgnorePath } from '../gate/changed.mjs';
+import { PreconditionError } from '../probe/worktree.mjs';
+
+/**
+ * A claim that no longer exists is invisible by construction: `probe` verifies
+ * what is there, `gate` sees the source file covered by some other claim, and
+ * `status` says clean. Deleting a claim is therefore cheaper than weakening
+ * its fault — and `changedFaults` exists precisely because weakening was the
+ * cheap escape. This closes the other half: removal is allowed, and recorded.
+ *
+ * Identities only. A fault whose text changed is `changedFaults`' business.
+ */
+const isExpired = (entry, now) => Boolean(entry.expires) && new Date(entry.expires).getTime() <= now.getTime();
+
+/** The claims document as of `ref`, or null when the file did not exist there. */
+export function claimsAt({ projectDir, ref, claimsPath }) {
+  // git reports the repository root by its real path (/private/var on macOS);
+  // a relative() that does not start from the same place yields `../../..`
+  // and `git show` then fails as if the file had never existed.
+  const root = repoRoot(realpathSync(resolve(projectDir)));
+  // The file may not exist at this ref (or at all); realpath its DIRECTORY so
+  // a missing file still resolves to a repository-relative path.
+  const p0 = resolve(claimsPath);
+  const abs = existsSync(p0) ? realpathSync(p0) : join(realpathSync(dirname(p0)), basename(p0));
+  const rel = relative(root, abs).split('\\').join('/');
+  if (rel.startsWith('..')) throw new PreconditionError(`the claims file ${claimsPath} is outside the repository at ${root}`);
+  let text;
+  try {
+    text = git(['show', `${ref}:${rel}`], root);
+  } catch (e) {
+    if (e instanceof GitError) {
+      // Distinguish "that ref is not a thing" (the caller's mistake) from
+      // "the file did not exist yet" (nothing to compare, not an error).
+      try {
+        git(['rev-parse', '--verify', `${ref}^{commit}`], root);
+      } catch {
+        throw new PreconditionError(`cannot read ${ref}: no such commit`);
+      }
+      return null;
+    }
+    throw e;
+  }
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    throw new PreconditionError(`the claims file at ${ref} is not valid JSON (${e.message})`);
+  }
+}
+
+const index = (doc) => {
+  const claims = new Map();
+  for (const c of doc?.claims ?? []) claims.set(c.id, { statement: c.statement, severity: c.severity, faults: new Set((c.faults ?? []).map((f) => f.id)) });
+  return claims;
+};
+
+/**
+ * Compare claim and fault identities at `ref` with the working file.
+ *
+ * A removed id whose statement reappears verbatim under a new id is a
+ * `renamed-claim`, not a removal: an ordinary rename must not read as an
+ * escape, or the check becomes noise nobody acts on.
+ */
+export function computeRemovedClaims({ projectDir, ref, claimsPath, current, ignorePath, evidencePath, now = new Date(), toolVersion = '0.0.0' }) {
+  const before = claimsAt({ projectDir, ref, claimsPath });
+  const beforeIdx = index(before);
+  const afterIdx = index(current);
+
+  const iPath = ignorePath ?? defaultIgnorePath(projectDir);
+  const ignore = existsSync(iPath) ? readSpecDoc('ignore', iPath) : { entries: [] };
+  const excuses = ignore.entries
+    .filter((e) => e.kind === 'claim' || e.kind === 'fault')
+    .map((e) => ({ entry: e, expired: isExpired(e, now), used: [] }));
+
+  const lastVerdict = new Map();
+  if (evidencePath && existsSync(evidencePath)) {
+    try {
+      for (const r of readSpecDoc('evidence', evidencePath).records) lastVerdict.set(`${r.claim.id}/${r.subject.id}`, r.verdict);
+    } catch {
+      // Evidence that cannot be read must not stop the check; the verdict is
+      // extra context, never the finding itself.
+    }
+  }
+
+  const statementsAfter = new Map();
+  for (const [id, c] of afterIdx) if (!beforeIdx.has(id)) statementsAfter.set(c.statement, id);
+
+  const findings = [];
+  for (const [id, c] of beforeIdx) {
+    if (!afterIdx.has(id)) {
+      const renamedTo = statementsAfter.get(c.statement);
+      if (renamedTo) {
+        findings.push({ kind: 'renamed-claim', claimId: id, renamedTo, severity: c.severity });
+        continue;
+      }
+      const verdicts = [...c.faults].map((f) => lastVerdict.get(`${id}/${f}`)).filter(Boolean);
+      findings.push({ kind: 'removed-claim', claimId: id, severity: c.severity, faults: [...c.faults].sort(), ...(verdicts.length ? { lastVerdicts: [...new Set(verdicts)].sort() } : {}) });
+      continue;
+    }
+    for (const f of c.faults) {
+      if (afterIdx.get(id).faults.has(f)) continue;
+      const v = lastVerdict.get(`${id}/${f}`);
+      findings.push({ kind: 'removed-fault', claimId: id, subjectId: f, severity: c.severity, ...(v ? { lastVerdicts: [v] } : {}) });
+    }
+  }
+
+  // An excuse applies to a removal, never to a rename: a rename is already not a finding.
+  const gating = [];
+  for (const f of findings) {
+    if (f.kind === 'renamed-claim') continue;
+    const target = f.kind === 'removed-fault' ? `${f.claimId}/${f.subjectId}` : f.claimId;
+    const active = excuses.find((e) => !e.expired && (e.entry.pattern === target || (f.kind === 'removed-fault' && e.entry.kind === 'claim' && e.entry.pattern === f.claimId)));
+    if (active) {
+      active.used.push(target);
+      f.excusedBy = active.entry.pattern;
+      continue;
+    }
+    const expired = excuses.find((e) => e.expired && (e.entry.pattern === target || (f.kind === 'removed-fault' && e.entry.kind === 'claim' && e.entry.pattern === f.claimId)));
+    if (expired) {
+      expired.used.push(target);
+      f.expiredExcuse = expired.entry.pattern;
+    }
+    gating.push(f);
+  }
+
+  const order = { 'removed-claim': 0, 'removed-fault': 1, 'renamed-claim': 2 };
+  findings.sort((a, b) => order[a.kind] - order[b.kind] || a.claimId.localeCompare(b.claimId) || (a.subjectId ?? '').localeCompare(b.subjectId ?? ''));
+
+  return {
+    ref,
+    comparedAgainst: before ? 'claims-file' : 'nothing',
+    findings,
+    removed: gating,
+    reliedOn: excuses.filter((e) => !e.expired && e.used.length).map((e) => ({ pattern: e.entry.pattern, reason: e.entry.reason, ...(e.entry.expires ? { expires: e.entry.expires } : {}), ids: e.used })),
+    expired: excuses.filter((e) => e.expired && e.used.length).map((e) => ({ pattern: e.entry.pattern, reason: e.entry.reason, expires: e.entry.expires, ids: e.used })),
+    toolVersion,
+  };
+}
+
+export function renderRemoved(doc) {
+  if (doc.comparedAgainst === 'nothing') return `no claims file at ${doc.ref}; nothing to compare`;
+  const lines = [];
+  for (const f of doc.findings) {
+    const verdicts = f.lastVerdicts?.length ? ` — last ${f.lastVerdicts.length === 1 ? 'verdict' : 'verdicts'} ${f.lastVerdicts.join(', ')}` : '';
+    if (f.kind === 'removed-claim') lines.push(`REMOVED    ${f.claimId} (${f.severity}, ${f.faults.length} fault${f.faults.length === 1 ? '' : 's'})${verdicts}${f.excusedBy ? `  [excused by ignore "${f.excusedBy}"]` : ''}${f.expiredExcuse ? `  [ignore "${f.expiredExcuse}" has EXPIRED]` : ''}`);
+    else if (f.kind === 'removed-fault') lines.push(`REMOVED    ${f.claimId}/${f.subjectId} (${f.severity})${verdicts}${f.excusedBy ? `  [excused by ignore "${f.excusedBy}"]` : ''}${f.expiredExcuse ? `  [ignore "${f.expiredExcuse}" has EXPIRED]` : ''}`);
+    else lines.push(`renamed    ${f.claimId} → ${f.renamedTo} (same statement; not a removal)`);
+  }
+  for (const r of doc.reliedOn) lines.push(`excused    ${r.ids.join(', ')}  by ignore "${r.pattern}": ${r.reason}${r.expires ? ` (expires ${r.expires})` : ''}`);
+  for (const e of doc.expired) lines.push(`EXPIRED    ignore "${e.pattern}" (expired ${e.expires}) no longer excuses ${e.ids.join(', ')}`);
+  if (doc.removed.length) {
+    lines.push('', `${doc.removed.length} claim${doc.removed.length === 1 ? '' : 's'}/fault${doc.removed.length === 1 ? '' : 's'} present at ${doc.ref} no longer exist. Removing a claim is allowed — claims can be wrong, superseded or split — but it is the cheapest way to make a finding disappear, so it is never silent.`);
+    lines.push('Either restore them, or add a `claim` entry to testguard.ignore.json with a reason a reviewer will accept.');
+  } else if (doc.findings.length === 0) {
+    lines.push(`every claim and fault present at ${doc.ref} still exists`);
+  }
+  return lines.join('\n');
+}

package/src/cli.mjs

@@ -4,6 +4,7 @@ import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ClaimsError } from './claims/load.mjs';
 import { PreconditionError } from './probe/worktree.mjs';
+import { RUNNER_NAMES } from './probe/runners/index.mjs';
 import { GitError } from './git.mjs';
 import { SpecDocError } from './evidence/writer.mjs';
 import { probeCommand } from './commands/probe.mjs';
@@ -14,19 +15,25 @@ import { scaffoldCommand } from './commands/scaffold.mjs';
 import { statusCommand } from './commands/status.mjs';
 import { initCommand } from './commands/init.mjs';
 import { gateCommand } from './commands/gate.mjs';
+import { replayCommand } from './commands/replay.mjs';
+import { mcpCommand } from './commands/mcp.mjs';
+import { admitCommand } from './commands/admit.mjs';
 
 const VERSION = JSON.parse(readFileSync(join(fileURLToPath(import.meta.url), '..', '..', 'package.json'), 'utf8')).version;
 
 const USAGE = `testguard ${VERSION} — proves a test suite defends the claims a project makes
 
   testguard status [dir]     where the project is and the ONE next action; --json is the machine entry point
-  testguard init [dir]       install the agent layer: skill, session-start hook, AGENTS.md section, .gitignore lines
+  testguard init [dir]       install the agent layer at the git root (skill, session-start hook, AGENTS.md section) and the .gitignore lines in [dir]
   testguard claims [dir]     list the claims file and report drift against @claim annotations in code
   testguard probe [dir]      inject each claim's faults, run its defenders, report what survived
   testguard baseline [dir]   freeze today's unproven findings so only new ones gate
   testguard brief [dir]      emit the blind-spot block for an agent's session-start context
   testguard gate [dir]       fail when a changed source file carries no claim and no excusing ignore entry
   testguard scaffold <file>  propose faults mechanically for one source file, as a draft claims document
+  testguard mcp              serve the read-only status/brief/claims/evidence tools over MCP on stdio, so the loop works in any agent harness
+  testguard replay [dir]     would this suite have caught the bugs that already escaped? Replays real fix commits and calibrates fault classes against them
+  testguard admit <test> --claim <ID>   the two-gate rule as one verb: is this test green on HEAD and does it fail on every fault of the claim?
 
 probe
   --claims <path>      claims file             (default: <dir>/testguard.claims.json)
@@ -35,22 +42,52 @@ probe
   --out <path>         evidence file           (default: <dir>/.testguard/evidence.json)
   --baseline <path>    baseline to gate against (default: <dir>/.testguard/baseline.json if present)
   --severity <level>   gate only at or above   (default: low)
-  --ref <commit>       probe this commit in the scratch worktree (default: HEAD)
+  --ref <commit>       probe this commit in the scratch worktree (default: HEAD). An explicit --ref is honoured even when
+                       defender/target files are dirty: a warning names them, the evidence records them (repo.ignoredDirty)
+  --ignore-dirty       probe HEAD as committed although defender/target files are dirty (same warning and record)
   --claim <ID,ID>      probe only these claims; writes .testguard/evidence-partial.json
   --include-dirty      probe the working tree (a snapshot commit) instead of HEAD; uncommitted tests count
+                       (without it, a dirty defender/target with the implicit HEAD is refused: the silent-mismatch trap)
   --verbose            also print each killed fault (default: only unproven ones, plus a count)
+  --cost               (probe, claims) report what the defenders cost, per claim and per defender file
+  --progress <mode>    auto|tty|plain|ndjson|none. auto rewrites one line at a terminal and prints
+                       append-only lines everywhere else, so a redirected log and CI see progress
+                       instead of twenty silent minutes. Always on stderr; ndjson also streams verdicts
                        --confirm below 3 is PROVISIONAL: verdicts print with "?", evidence goes to .testguard/evidence-provisional.json
-  --runner <name>      vitest | jest | auto (default: auto — first of vitest, jest that resolves)
+  --runner <name>      vitest | jest | playwright | python | pytest | unittest | auto
+                       (default: auto — first of vitest, jest, python that resolves. A defender under playwright's testDir
+                       always runs under playwright, and a .py defender always under python, whatever the project runner.
+                       python picks pytest when the interpreter can import it and stdlib unittest otherwise; pytest and
+                       unittest pin that choice and fail rather than fall back. The engine that ran is what the evidence records.)
   --runner-cmd "<cmd>" custom runner; must contain {files} and {out}, e.g. "pnpm vitest run {files} --reporter=json --outputFile={out}"
   --node-modules <dir> node_modules to link into the scratch worktree (or TESTGUARD_NODE_MODULES)
+  --python <path>      Python interpreter for .py defenders (or TESTGUARD_PYTHON; default: $VIRTUAL_ENV, then the project's
+                       .venv/venv, then python3 on PATH). Resolved against your working tree, never the scratch worktree.
+  --serial             run one test file at a time (vitest --no-file-parallelism, jest --runInBand, playwright --workers=1,
+                       pytest -p no:xdist);
+                       use it when another test runner is already running — probe warns and records the contention either way
   --in-place           mutate the working tree instead of a scratch worktree
   --no-escalate        do not re-run survivors against the whole suite
   --no-reuse           re-probe claims whose inputs have not changed
   --quiet              suppress the per-fault stream and ranked block; print only the summary and evidence path
+  --json               the status document plus this run's result (records, newSinceBaseline, exitCode)
 
 scaffold   --claim <ID> (put every proposal under this claim; copies it if it exists)  --out <path>  --json
            shapes: if-guard → if (false) · single-line guard/mutation removed · return <check> → return true
                    · security flag/window/cost literal weakened · verify/validate/check call removed
+                   · field dropped from a payload/allow-list/schema/merge · parameter-derived argument swapped for undefined/{}
+mcp        no options. JSON-RPC 2.0 over stdio; five READ-ONLY tools (status, brief, claims, evidence, next_command).
+           Nothing here runs a probe: next_command hands back the shell line for you to run where the person can see it.
+           Register it with your harness — testguard init --mcp prints the config for Claude Code, Cursor and Codex.
+replay     --since <range>   commit range to search for fix commits (HEAD~50..HEAD, a tag, origin/main..HEAD)
+           --max <n>         replay at most n fixes (they are slow: one worktree and N runs each)
+           --confirm <n>     runs per verdict (default 3); a flaky failure reads as "the suite caught it", so mixed runs are never caught
+           --out <path>       replay document (default: <dir>/.testguard/replay.json); the calibration goes beside it
+           reports, never gates: a bug that escaped is history, not a regression in this change
+                   · one-line JSX element removed · on<Event> handler prop dropped
+admit      --claim <ID> (required)  --fault <FID> (one fault only)  --confirm <n>  --json
+           ADMITTED (exit 0) only when every fault of the claim is killed N/N by defenders that are green N/N; anything else is NOT ADMITTED (exit 1) and names the first blocking fault
+           the test must be a declared or discovered defender of the claim (exit 3 otherwise); evidence goes to .testguard/evidence-partial.json
 gate       --changed <ref>   measure the change since merge-base(ref, HEAD); auto-detected in GitHub Actions / GitLab CI
            --include-dirty   compare the working tree (staged, unstaged and untracked) instead of HEAD — the pre-commit shape
            --exclude <glob>  (repeatable) more files that never carry claims; --explain lists the defaults
@@ -58,17 +95,26 @@ gate       --changed <ref>   measure the change since merge-base(ref, HEAD); aut
            --ignore <path>   ignore file (default: <dir>/testguard.ignore.json; kind=path entries excuse files, with a reason)
            exit 0 every changed source file is claimed or excused · 1 unclaimed file · 2 cannot evaluate · 3 no reference
 status     --json (exit 0 clean · 1 unproven/stale/unclaimed · 2 nothing to probe yet)
+           --evidence <path>  read this evidence instead of .testguard/evidence.json (e.g. CI's, fetched as an artifact); staleness is still computed from the recorded input hashes, and both commits are named
            --changed <ref>   also compute claim coverage of the change; unclaimed-changes then precedes every evidence state
-init       --force (replace an existing skill file)  --json
+init       --force (replace an existing skill file)  --here (keep the agent layer in [dir] instead of the git root)  --json
+           --ci-evidence github|gitlab   write .testguard/fetch-ci-evidence.sh, an ON-DEMAND helper that downloads CI's evidence artifact and briefs from it; the session-start hook stays offline
+           agent layer (skill, SessionStart hook, AGENTS.md section) → git root; project layer (.gitignore lines) → [dir]
+           the hook prefers a local install, falls back to npx --no-install, never fetches; exit 1 if a written file is gitignored
+           --mcp             print the MCP server config for Claude Code, Cursor and Codex (printed, never written: a harness config is yours)
 every command accepts --json; probe/baseline emit the status document plus their own result
 claims     --json
+           --cost            what the last probe spent, per claim and per defender file, read back from the recorded run durations. Names the files more than one claim pays for, which is where a slow gate comes from
+           --since <ref>     report every claim and fault that existed at <ref> and does not now; a claim entry in testguard.ignore.json (with a reason) excuses one. exit 1 on any unexcused removal
 baseline   --evidence <path>  --out <path>  --allow-provisional (freeze unconfirmed evidence; normally refused)
-brief      --evidence <path>  --baseline <path>  --max <n>  --text (print only; safe for hooks)
+           --restamp          move head to the commit of a later CLEAN probe that reproduced the same fingerprints
+                              (a baseline frozen from a snapshot points at the parent of the commit that carries its tests)
+brief      --evidence <path>  --baseline <path>  --max <n>  --text (print only; safe for hooks)  --markdown (print only, as a merge-request note)
 
 exit codes: 0 nothing new to prove · 1 unproven claims (or claim drift, or unclaimed changes) · 2 precondition failed · 3 usage
 `;
 
-const COMMANDS = { probe: probeCommand, claims: claimsCommand, baseline: baselineCommand, brief: briefCommand, scaffold: scaffoldCommand, status: statusCommand, init: initCommand, gate: gateCommand };
+const COMMANDS = { mcp: mcpCommand, replay: replayCommand, probe: probeCommand, claims: claimsCommand, baseline: baselineCommand, brief: briefCommand, scaffold: scaffoldCommand, status: statusCommand, init: initCommand, gate: gateCommand, admit: admitCommand };
 
 export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n'), err: (s) => process.stderr.write(s + '\n') }) {
   let parsed;
@@ -85,18 +131,27 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
         baseline: { type: 'string' },
         severity: { type: 'string', default: 'low' },
         max: { type: 'string', default: '20' },
-        ref: { type: 'string', default: 'HEAD' },
+        ref: { type: 'string' },
+        'ignore-dirty': { type: 'boolean', default: false },
+        serial: { type: 'boolean', default: false },
         claim: { type: 'string' },
+        fault: { type: 'string' },
         'include-dirty': { type: 'boolean', default: false },
         changed: { type: 'string' },
+        since: { type: 'string' },
         exclude: { type: 'string', multiple: true },
         strict: { type: 'boolean', default: false },
         explain: { type: 'boolean', default: false },
         ignore: { type: 'string' },
         'allow-provisional': { type: 'boolean', default: false },
+        restamp: { type: 'boolean', default: false },
         force: { type: 'boolean', default: false },
+        mcp: { type: 'boolean', default: false },
+        'ci-evidence': { type: 'string' },
+        here: { type: 'boolean', default: false },
         verbose: { type: 'boolean', default: false },
         'runner-cmd': { type: 'string' },
+        python: { type: 'string' },
         runner: { type: 'string', default: 'auto' },
         'node-modules': { type: 'string' },
         'in-place': { type: 'boolean', default: false },
@@ -105,6 +160,9 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
         quiet: { type: 'boolean', default: false },
         json: { type: 'boolean', default: false },
         text: { type: 'boolean', default: false },
+        markdown: { type: 'boolean', default: false },
+        cost: { type: 'boolean', default: false },
+        progress: { type: 'string' },
         help: { type: 'boolean', short: 'h', default: false },
         version: { type: 'boolean', short: 'v', default: false },
       },
@@ -130,8 +188,8 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
     io.err(USAGE);
     return 3;
   }
-  if (!['vitest', 'jest', 'auto'].includes(values.runner)) {
-    io.err('--runner must be vitest, jest or auto');
+  if (![...RUNNER_NAMES, 'auto'].includes(values.runner)) {
+    io.err(`--runner must be one of ${RUNNER_NAMES.join(', ')} or auto`);
     return 3;
   }
   if (!['critical', 'high', 'medium', 'low'].includes(values.severity)) {
@@ -139,7 +197,7 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
     return 3;
   }
   try {
-    const projectDir = command === 'scaffold' ? resolve('.') : resolve(dirArg ?? '.');
+    const projectDir = command === 'scaffold' || command === 'admit' ? resolve('.') : resolve(dirArg ?? '.');
     return await handler({ projectDir, file: dirArg, values, version: VERSION }, io);
   } catch (e) {
     if (e instanceof ClaimsError || e instanceof PreconditionError || e instanceof GitError || e instanceof SpecDocError) {

package/src/commands/admit.mjs

@@ -0,0 +1,116 @@
+import { existsSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
+import { probe } from '../probe/probe.mjs';
+import { writeSpecDoc } from '../evidence/writer.mjs';
+import { resolveDefenders } from '../probe/runners/shared.mjs';
+import { discoverDefenders } from '../probe/discover.mjs';
+import { PreconditionError } from '../probe/worktree.mjs';
+import { hintFor } from '../brief/brief.mjs';
+import { formatVerdict, PROVISIONAL_WARNING } from '../render.mjs';
+import { decideAdmission } from '../admit/admit.mjs';
+
+/** The project is wherever the claims file is, walking up from the test file; else cwd. */
+function findProjectDir(testAbs, claimsFlag) {
+  if (claimsFlag) return dirname(resolve(claimsFlag));
+  let dir = dirname(testAbs);
+  for (let hop = 0; hop < 20; hop++) {
+    if (existsSync(defaultClaimsPath(dir))) return dir;
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return resolve('.');
+}
+
+/**
+ * `testguard admit <test-file> --claim <ID>`: the two-gate rule as one verb.
+ * Sugar over `probe --claim <ID> --include-dirty`; no second engine, so the
+ * decision here can never disagree with the gate.
+ */
+export async function admitCommand({ file, values, version }, io) {
+  if (!file || !values.claim) {
+    io.err('usage: testguard admit <test-file> --claim <ID> [--fault <FID>] [--confirm <n>] [--json]');
+    return 3;
+  }
+  const confirmRuns = Number(values.confirm);
+  const budgetMs = Number(values.budget);
+  if (!Number.isInteger(confirmRuns) || confirmRuns < 1 || !Number.isInteger(budgetMs) || budgetMs < 1000) {
+    io.err('--confirm must be a positive integer and --budget at least 1000');
+    return 3;
+  }
+  const testAbs = resolve(file);
+  if (!existsSync(testAbs)) throw new PreconditionError(`no such file: ${file}`);
+  const projectDir = findProjectDir(testAbs, values.claims);
+  const testRel = relative(projectDir, testAbs);
+  if (testRel.startsWith('..')) throw new PreconditionError(`${file} is outside the project directory ${projectDir}`);
+
+  const all = loadClaims(values.claims ? resolve(values.claims) : defaultClaimsPath(projectDir));
+  const claimId = values.claim.trim();
+  const claim = all.claims.find((c) => c.id === claimId);
+  if (!claim) throw new PreconditionError(`--claim: unknown claim id ${claimId}`);
+  const faults = values.fault ? claim.faults.filter((f) => f.id === values.fault) : claim.faults;
+  if (faults.length === 0) throw new PreconditionError(`--fault: ${claimId} has no fault ${values.fault}`);
+
+  // The named test must be a defender of the claim, declared or discovered;
+  // otherwise `killed` below would be someone else's test doing the work.
+  const declared = claim.defendedBy?.length ? resolveDefenders(projectDir, claim.defendedBy) : null;
+  const isDefender = declared ? declared.includes(testRel) : faults.some((f) => discoverDefenders(projectDir, f.file).includes(testRel));
+  if (!isDefender) {
+    io.err(declared
+      ? `${testRel} is not a defender of ${claimId}. Add it: "defendedBy": [${[...claim.defendedBy, testRel].map((d) => JSON.stringify(d)).join(', ')}] in testguard.claims.json, then run admit again.`
+      : `${testRel} does not import ${[...new Set(faults.map((f) => f.file))].join(' or ')}, so it cannot be discovered as a defender of ${claimId}. Import the module under test, or declare "defendedBy": ["${testRel}"] on the claim.`);
+    return 3;
+  }
+
+  const provisional = confirmRuns < 3;
+  if (provisional && !values.quiet) io.err(PROVISIONAL_WARNING(confirmRuns));
+  const command = `testguard probe --claim ${claimId} --include-dirty --confirm ${confirmRuns} --no-escalate`;
+  const evidence = await probe({
+    projectDir,
+    claims: { ...all, claims: [{ ...claim, faults }] },
+    confirmRuns,
+    budgetMs,
+    mode: 'worktree',
+    includeDirty: true,
+    only: [claimId],
+    escalate: false,
+    runnerCommand: values['runner-cmd'],
+    runnerName: values.runner,
+    nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
+    toolVersion: version,
+    onStage: !values.quiet && !values.json && process.stderr.isTTY ? ({ claimId: c, faultId, stage, i, n }) => process.stderr.write(`\r\x1b[K  … ${c}/${faultId} ${stage} ${i}/${n}`) : undefined,
+  });
+  if (process.stderr.isTTY && !values.quiet && !values.json) process.stderr.write('\r\x1b[K');
+  const outPath = values.out ? resolve(values.out) : join(projectDir, '.testguard', 'evidence-partial.json');
+  writeSpecDoc('evidence', outPath, evidence);
+
+  const decision = decideAdmission(evidence.records);
+  const result = {
+    admitted: decision.admitted,
+    provisional,
+    claim: claimId,
+    test: testRel,
+    faults: evidence.records.map((r) => ({ id: r.subject.id, verdict: r.verdict, ...(r.detail.reason ? { reason: r.detail.reason } : {}), hint: hintFor(r) })),
+    evidence: outPath,
+    command,
+  };
+  if (values.json) {
+    io.out(JSON.stringify(result, null, 2));
+  } else {
+    for (const r of evidence.records) io.out(`  ${formatVerdict(r.verdict, provisional).padEnd(15)} ${claimId}/${r.subject.id}  ${r.subject.description}${r.detail.reason ? `  [${r.detail.reason}]` : ''}`);
+    io.out('');
+    if (decision.admitted) {
+      io.out(provisional
+        ? `ADMITTED? — ${testRel} kills ${evidence.records.length === 1 ? 'the fault' : `all ${evidence.records.length} faults`} of ${claimId} at --confirm ${confirmRuns}. Provisional: confirm with --confirm 3 before committing.`
+        : `ADMITTED — ${testRel} passes on HEAD and fails on ${evidence.records.length === 1 ? 'the fault' : `all ${evidence.records.length} faults`} of ${claimId}, ${confirmRuns}/${confirmRuns}. Commit it.`);
+    } else {
+      const b = decision.blocking;
+      io.out(`NOT ADMITTED: ${b.verdict}${b.detail.reason ? ` (${b.detail.reason})` : ''} on ${claimId}/${b.subject.id}`);
+      io.out(`  ${hintFor(b)}`);
+    }
+    io.out(`evidence: ${outPath} (partial; not the canonical evidence file)`);
+  }
+  if (provisional && !values.quiet && !values.json) io.err(PROVISIONAL_WARNING(confirmRuns));
+  return decision.admitted ? 0 : 1;
+}

package/src/commands/baseline.mjs

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { readSpecDoc, writeSpecDoc } from '../evidence/writer.mjs';
-import { buildBaseline } from '../baseline/baseline.mjs';
+import { buildBaseline, restampBaseline } from '../baseline/baseline.mjs';
 import { evidencePath, baselinePath } from './probe.mjs';
 import { computeStatus } from '../status/status.mjs';
 
@@ -16,15 +16,29 @@ export async function baselineCommand({ projectDir, values, version }, io) {
     io.err(`error: ${evPath} is provisional (confirmRuns ${evidence.run.confirmRuns} < 3); a baseline must be frozen from confirmed evidence. Re-run probe with --confirm 3, or pass --allow-provisional if you accept unconfirmed findings as the frozen contract.`);
     return 2;
   }
-  const baseline = buildBaseline(evidence);
   const outPath = values.out ? resolve(values.out) : baselinePath(projectDir);
+  if (values.restamp) {
+    if (!existsSync(outPath)) {
+      io.err(`error: no baseline at ${outPath} to re-stamp; run \`testguard baseline\` first`);
+      return 2;
+    }
+    const r = restampBaseline(readSpecDoc('baseline', outPath), evidence);
+    if (!r.ok) {
+      io.err(`error: cannot re-stamp: ${r.reason}`);
+      return 2;
+    }
+    writeSpecDoc('baseline', outPath, r.baseline);
+    io.out(values.json ? JSON.stringify({ ...computeStatus({ projectDir, toolVersion: version }), baseline: { path: outPath, restamped: r.baseline.head } }, null, 2) : `baseline: re-stamped to ${r.baseline.head.slice(0, 12)} (same fingerprints, clean tree) → ${outPath}`);
+    return 0;
+  }
+  const baseline = buildBaseline(evidence);
   writeSpecDoc('baseline', outPath, baseline);
   const n = Object.values(baseline.fingerprints).reduce((a, b) => a + b, 0);
   if (values.json) {
     io.out(JSON.stringify({ ...computeStatus({ projectDir, toolVersion: version }), baseline: { path: outPath, frozen: n } }, null, 2));
     return 0;
   }
-  io.out(`baseline: ${n} unproven finding${n === 1 ? '' : 's'} frozen at ${baseline.head.slice(0, 12)}${baseline.dirty ? ' (working tree was dirty)' : ''}${evidence.run.provisional ? ' — FROM PROVISIONAL EVIDENCE (--allow-provisional)' : ''} → ${outPath}`);
+  io.out(`baseline: ${n} unproven finding${n === 1 ? '' : 's'} frozen at ${baseline.head.slice(0, 12)}${baseline.snapshot ? ` (working-tree snapshot ${baseline.snapshot.slice(0, 7)}; after you commit, a clean probe + \`baseline --restamp\` moves head to that commit)` : baseline.dirty ? ' (working tree was dirty)' : ''}${evidence.run.provisional ? ' — FROM PROVISIONAL EVIDENCE (--allow-provisional)' : ''} → ${outPath}`);
   io.out('Commit this file; from now on only new findings gate. Ignore the regenerated ones — add to .gitignore:');
   io.out('  .testguard/evidence.json');
   io.out('  .testguard/brief.json');