testguard-cli 0.4.0 → 0.6.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 } = {}) {
+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,20 +72,33 @@ export function buildBrief(evidence, baseline, { max = 20, generatedAt = new Dat
     new: g.new.length + g.belowFloor.length,
     baselined: g.baselined.length,
   };
-  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 } } : {}), items, text: '' };
-  doc.text = renderBriefText({ ...doc, provisional: Boolean(evidence.run.provisional) }, { hasBaseline: Boolean(baseline), total: evidence.records.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), 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
+  // before more code, and TestGuard is silent about unclaimed code otherwise.
+  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}`);
+  }
+  // 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.');
@@ -87,3 +118,60 @@ export function renderBriefText(brief, { hasBaseline, total }) {
   if (unproven > brief.items.length) lines.push('', `… and ${unproven - brief.items.length} more in the evidence file.`);
   return lines.join('\n') + '\n';
 }
+
+/**
+ * A brief for a project that has unclaimed changes but no evidence yet. The
+ * session-start hook must still tell the agent to write the claim; an empty
+ * summary is honest, silence is not.
+ */
+export function buildUnclaimedBrief({ tool, next, changes, generatedAt = new Date().toISOString() }) {
+  const summary = { claims: 0, byVerdict: {}, new: 0, baselined: 0 };
+  const doc = { schemaVersion: 1, tool, generatedAt, heading: HEADING, summary, ...(next ? { next: { action: next.action, command: next.command, why: next.why } } : {}), unclaimed: { ref: changes.ref, files: changes.uncovered }, items: [], text: '' };
+  const lines = [HEADING, '', `testguard ${tool.version} — no evidence yet; ${changes.uncovered.length} unclaimed changed file${changes.uncovered.length === 1 ? '' : 's'} since ${changes.ref}.`];
+  lines.push('', `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}`, `  why: ${next.why}`);
+  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

@@ -13,18 +13,26 @@ import { briefCommand } from './commands/brief.mjs';
 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)
@@ -33,33 +41,68 @@ 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)
                        --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 | auto (default: auto — first of vitest, jest that resolves; a defender under
+                       playwright's testDir always runs under playwright, whatever the project runner)
   --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)
+  --serial             run one test file at a time (vitest --no-file-parallelism, jest --runInBand, playwright --workers=1);
+                       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
-status     --json (exit 0 clean · 1 unproven/stale · 2 nothing to probe yet)
-init       --force (replace an existing skill file)  --json
+                   · 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
+           --strict          a non-empty change that evaluates nothing is a failure, not a note
+           --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)  --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
+           --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) · 2 precondition failed · 3 usage
+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 };
+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;
@@ -76,11 +119,24 @@ 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' },
         runner: { type: 'string', default: 'auto' },
@@ -91,6 +147,7 @@ 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 },
         help: { type: 'boolean', short: 'h', default: false },
         version: { type: 'boolean', short: 'v', default: false },
       },
@@ -116,8 +173,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 (!['vitest', 'jest', 'playwright', 'auto'].includes(values.runner)) {
+    io.err('--runner must be vitest, jest, playwright or auto');
     return 3;
   }
   if (!['critical', 'high', 'medium', 'low'].includes(values.severity)) {
@@ -125,7 +182,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');