testguard-cli 0.5.0 → 0.6.0

package/src/commands/brief.mjs

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { readSpecDoc, writeSpecDoc } from '../evidence/writer.mjs';
-import { buildBrief, buildUnclaimedBrief } from '../brief/brief.mjs';
+import { buildBrief, buildUnclaimedBrief, renderBriefMarkdown, renderUnclaimedMarkdown } from '../brief/brief.mjs';
 import { computeStatus } from '../status/status.mjs';
 import { evidencePath, baselinePath } from './probe.mjs';
 import { resolveChangedRef, withChangedRef } from '../gate/changed.mjs';
@@ -13,15 +13,18 @@ export async function briefCommand({ projectDir, values, version }, io) {
     // A detected base that does not resolve is silent here: the brief is a
     // session-start hook's output and must never add noise; `status` and
     // `gate` are where that warning is printed.
-    status = withChangedRef(resolveChangedRef({ explicit: values.changed }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'] }));
+    status = withChangedRef(resolveChangedRef({ explicit: values.changed }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'], evidence: values.evidence ? evPath : undefined }));
   } catch {
     status = undefined; // a brief must never fail because status could not be computed
   }
   if (!existsSync(evPath)) {
     // A missing brief must never break an agent's session start — but unclaimed
     // changes are still said, because the claim comes before the probe.
-    if (values.text) {
-      if (status?.changes?.uncovered?.length) io.out(buildUnclaimedBrief({ tool: { name: 'testguard', version }, next: status.next, changes: status.changes }).text.trimEnd());
+    if (values.text || values.markdown) {
+      if (status?.changes?.uncovered?.length) {
+        const args = { tool: { name: 'testguard', version }, next: status.next, changes: status.changes };
+        io.out((values.markdown ? renderUnclaimedMarkdown(args) : buildUnclaimedBrief(args).text).trimEnd());
+      }
       return 0;
     }
     io.err(`no evidence at ${evPath}; run \`testguard probe\` first`);
@@ -35,8 +38,11 @@ export async function briefCommand({ projectDir, values, version }, io) {
     io.err('--max must be an integer from 1 to 50');
     return 3;
   }
-  const brief = buildBrief(evidence, baseline, { max, next: status?.next, changes: status?.changes });
-  if (!values.text) writeSpecDoc('brief', values.out ? resolve(values.out) : join(projectDir, '.testguard', 'brief.json'), brief);
-  io.out(values.json ? JSON.stringify(brief, null, 2) : brief.text.trimEnd());
+  // Where this binary came from, so a stale install is visible in the session-start context.
+  const install = /[\\/]node_modules[\\/]/.test(process.argv[1] ?? '') ? 'local install' : 'global';
+  const brief = buildBrief(evidence, baseline, { max, next: status?.next, changes: status?.changes, install });
+  if (!values.text && !values.markdown) writeSpecDoc('brief', values.out ? resolve(values.out) : join(projectDir, '.testguard', 'brief.json'), brief);
+  if (values.markdown) io.out(renderBriefMarkdown({ ...brief, provisional: Boolean(evidence.run.provisional) }, { hasBaseline: Boolean(baseline), total: evidence.records.length, install }).trimEnd());
+  else io.out(values.json ? JSON.stringify(brief, null, 2) : brief.text.trimEnd());
   return 0;
 }

package/src/commands/claims.mjs

@@ -2,29 +2,58 @@ import { resolve } from 'node:path';
 import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
 import { scanAnnotations, reconcile } from '../claims/annotations.mjs';
 import { resolveDefenders } from '../probe/runners/shared.mjs';
-import { discoverDefenders } from '../probe/discover.mjs';
+import { discoverDefendersDetailed } from '../probe/discover.mjs';
+import { classifyDefenders } from '../probe/mocks.mjs';
+import { computeRemovedClaims, renderRemoved } from '../claims/removed.mjs';
+import { evidencePath } from './probe.mjs';
 
-export async function claimsCommand({ projectDir, values }, io) {
+export async function claimsCommand({ projectDir, values, version }, io) {
   const path = values.claims ? resolve(values.claims) : defaultClaimsPath(projectDir);
   const claims = loadClaims(path);
   const annotations = scanAnnotations(projectDir);
   const drift = reconcile(claims, annotations);
 
+  // A claim that disappeared is invisible to every other command; compare
+  // identities against a reference when one is given.
+  const removed = values.since
+    ? computeRemovedClaims({ projectDir, ref: values.since, claimsPath: path, current: claims, ignorePath: values.ignore ? resolve(values.ignore) : undefined, evidencePath: evidencePath(projectDir), toolVersion: version })
+    : undefined;
+
   if (values.json) {
-    io.out(JSON.stringify({ path, claims, annotations, drift }, null, 2));
+    io.out(JSON.stringify({ path, claims, annotations, drift, ...(removed ? { removed } : {}) }, null, 2));
   } else {
     const annotated = new Set(drift.annotated);
     io.out(`${claims.claims.length} claims in ${path} — ${annotated.size} carry a @claim annotation in source (test files are not scanned)`);
     io.out('');
+    const signalLines = [];
     for (const c of claims.claims) {
       const declared = c.defendedBy?.length > 0;
-      const defenders = declared ? resolveDefenders(projectDir, c.defendedBy) : [...new Set(c.faults.flatMap((f) => discoverDefenders(projectDir, f.file)))];
-      const cover = defenders.length ? `${defenders.length} ${declared ? 'defender' : 'discovered'}${defenders.length === 1 ? '' : 's'}` : 'NO DEFENDER';
+      const targets = [...new Set(c.faults.map((f) => f.file))];
+      let cover;
+      if (declared) {
+        const defenders = resolveDefenders(projectDir, c.defendedBy);
+        const mocking = new Set();
+        for (const t of targets) { const m = classifyDefenders(projectDir, t, defenders); m.mocking.forEach((f) => mocking.add(f)); for (const s of m.signals) signalLines.push({ claim: c.id, target: t, ...s }); }
+        cover = defenders.length ? `${defenders.length} defender${defenders.length === 1 ? '' : 's'}${mocking.size ? ` (${mocking.size} mock the target)` : ''}` : 'NO DEFENDER';
+      } else {
+        const importing = new Set(); const mocking = new Set(); const can = new Set();
+        for (const t of targets) { const d = discoverDefendersDetailed(projectDir, t); d.importing.forEach((f) => importing.add(f)); d.mocking.forEach((f) => mocking.add(f)); d.canDetect.forEach((f) => can.add(f)); for (const s of d.signals) signalLines.push({ claim: c.id, target: t, ...s }); }
+        cover = can.size ? `${importing.size} import · ${mocking.size} mock · ${can.size} can detect` : importing.size ? `NO DEFENDER (${importing.size} import, all mock the target)` : 'NO DEFENDER';
+      }
       io.out(`${annotated.has(c.id) ? '@ ' : '  '}${c.id.padEnd(14)} ${c.severity.padEnd(8)} ${c.source.kind.padEnd(10)} ${String(c.faults.length).padStart(2)} fault${c.faults.length === 1 ? ' ' : 's'}  ${cover.padEnd(12)}  ${c.statement}`);
     }
+    if (signalLines.length) io.out('');
+    for (const s of signalLines) {
+      if (s.signal === 'mocked-never-asserted') io.out(`MOCKED-NEVER-ASSERTED  ${s.file} mocks ${s.target} and never asserts on it (${s.claim}) — assert on the mocked call, drive the real module, or annotate the mock \`// unasserted: <why>\``);
+      else io.out(`unasserted (annotated)  ${s.file} mocks ${s.target}: ${s.reason} (${s.claim})`);
+    }
     if (drift.undeclared.length || drift.stale.length) io.out('');
     for (const a of drift.undeclared) io.out(`UNDECLARED   @claim ${a.id} at ${a.file}:${a.line} has no entry in the claims file — a claim with no fault model`);
     for (const c of drift.stale) io.out(`STALE        ${c.id} is annotation-sourced but no source file carries @claim ${c.id}`);
+    if (removed) {
+      io.out('');
+      io.out(renderRemoved(removed));
+    }
   }
-  return drift.undeclared.length || drift.stale.length ? 1 : 0;
+  return drift.undeclared.length || drift.stale.length || (removed?.removed.length ?? 0) > 0 ? 1 : 0;
 }

package/src/commands/init.mjs

@@ -1,15 +1,28 @@
 import { initProject } from '../init/init.mjs';
 
 export async function initCommand({ projectDir, values }, io) {
-  const { done, skipped } = initProject({ projectDir, force: values.force });
+  const r = initProject({ projectDir, force: values.force, here: values.here, ciEvidence: values['ci-evidence'], mcp: values.mcp });
+  const { done, skipped, warnings, agentRoot, dir, mcpConfig } = r;
   if (values.json) {
-    io.out(JSON.stringify({ done, skipped }, null, 2));
-    return 0;
+    io.out(JSON.stringify({ done, skipped, warnings, agentRoot, dir, ...(mcpConfig ? { mcpConfig } : {}) }, null, 2));
+    return warnings.length ? 1 : 0;
   }
   for (const d of done) io.out(`+ ${d}`);
   for (const s of skipped) io.out(`= ${s}`);
+  for (const w of warnings) io.out(`! ${w}`);
   io.out('');
-  io.out('Agents in this project now start with the blind-spot brief and can run `testguard status --json` to learn what to do next.');
-  io.out(done.length ? 'Commit these files.' : 'Nothing to change.');
-  return 0;
+  if (dir !== '.') io.out(`Agent layer (skill, session-start hook, AGENTS.md section) installed at the git root ${agentRoot}, where agent sessions run; the project layer stays in ${dir}/. Use --here to keep everything in ${dir}/.`);
+  io.out(`Agents now start with the blind-spot brief and can run \`testguard status --json${dir === '.' ? '' : ` ${dir}`}\` to learn what to do next. The hook prefers a local install and never fetches from the network.`);
+  io.out(warnings.length ? 'Some written files are ignored by git — fix that before committing.' : done.length ? 'Commit these files.' : 'Nothing to change.');
+  if (mcpConfig) {
+    io.out('');
+    io.out('MCP — five READ-ONLY tools (status, brief, claims, evidence, next_command), so the loop survives a change of harness. Nothing there runs a probe. Add ONE of these:');
+    for (const [where, snippet] of Object.entries(mcpConfig)) {
+      io.out('');
+      io.out(`  ${where}`);
+      const text = typeof snippet === 'string' ? snippet : JSON.stringify(snippet, null, 2);
+      for (const line of text.split('\n')) io.out(`    ${line}`);
+    }
+  }
+  return warnings.length ? 1 : 0;
 }

package/src/commands/mcp.mjs

@@ -0,0 +1,12 @@
+import { serve } from '../mcp/server.mjs';
+
+export async function mcpCommand({ values, version }, io) {
+  if (values.json) {
+    // Not a JSON command: it is a long-lived server on stdio, and printing
+    // anything to stdout would corrupt the protocol stream.
+    io.err('mcp speaks JSON-RPC on stdin/stdout; there is no --json mode');
+    return 3;
+  }
+  await serve({ version });
+  return 0;
+}

package/src/commands/probe.mjs

@@ -30,6 +30,7 @@ export async function probeCommand({ projectDir, values, version }, io) {
   // Provisional and partial runs never overwrite the canonical evidence: only confirmed, complete runs may feed a baseline.
   const outPath = values.out ? resolve(values.out) : only ? join(projectDir, '.testguard', 'evidence-partial.json') : provisional ? provisionalEvidencePath(projectDir) : evidencePath(projectDir);
   if (provisional && !values.quiet) io.err(PROVISIONAL_WARNING(confirmRuns));
+  const discoveryNoted = new Set();
   const previous = !values['no-reuse'] && existsSync(outPath) ? readSpecDoc('evidence', outPath) : undefined;
   const basePath = values.baseline ? resolve(values.baseline) : baselinePath(projectDir);
   const baseline = existsSync(basePath) ? readSpecDoc('baseline', basePath) : undefined;
@@ -41,7 +42,11 @@ export async function probeCommand({ projectDir, values, version }, io) {
     confirmRuns,
     budgetMs,
     mode: values['in-place'] ? 'in-place' : 'worktree',
-    ref: values.ref,
+    ref: values.ref ?? 'HEAD',
+    refExplicit: values.ref !== undefined,
+    ignoreDirty: values['ignore-dirty'],
+    serial: values.serial,
+    onWarn: (m) => io.err(`warning: ${m}`),
     runnerCommand: values['runner-cmd'],
     runnerName: values.runner,
     nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
@@ -52,14 +57,17 @@ export async function probeCommand({ projectDir, values, version }, io) {
     onStage: !values.quiet && !values.json && process.stderr.isTTY ? ({ claimId, faultId, stage, i, n }) => process.stderr.write(`\r\x1b[K  … ${claimId}/${faultId} ${stage} ${i}/${n}`) : undefined,
     onProgress: values.quiet || values.json ? undefined : (r) => {
       if (process.stderr.isTTY) process.stderr.write('\r\x1b[K');
-      if (values.verbose || r.verdict !== 'killed') io.out(renderRecord(r, { provisional }) + (r.reusedFrom ? '  (reused)' : ''));
+      // The discovery note is a property of the claim, not of each fault: say it once.
+      const firstOfClaim = !discoveryNoted.has(r.claim.id);
+      if (r.defenders.discovered) discoveryNoted.add(r.claim.id);
+      if (values.verbose || r.verdict !== 'killed') io.out(renderRecord(r, { provisional, showDiscovered: firstOfClaim }) + (r.reusedFrom ? '  (reused)' : ''));
     },
   });
   writeSpecDoc('evidence', outPath, evidence);
 
   const g = gate(evidence.records, baseline, { severityFloor: values.severity });
   if (values.json) {
-    const status = withChangedRef(resolveChangedRef({ explicit: values.changed }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'] }), io.err);
+    const status = withChangedRef(resolveChangedRef({ explicit: values.changed }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'], evidence: outPath }), io.err);
     io.out(JSON.stringify({ ...status, run: { id: evidence.run.id, evidence: outPath, provisional, records: evidence.records.length, newSinceBaseline: g.new.length, exitCode: g.new.length > 0 ? 1 : 0 } }, null, 2));
     return g.new.length > 0 ? 1 : 0;
   }

package/src/commands/replay.mjs

@@ -0,0 +1,63 @@
+import { dirname, join, resolve } from 'node:path';
+import { replay, calibrationFrom, renderReplay } from '../replay/replay.mjs';
+import { writeSpecDoc } from '../evidence/writer.mjs';
+
+export const replayPath = (projectDir) => join(projectDir, '.testguard', 'replay.json');
+export const calibrationPath = (projectDir) => join(projectDir, '.testguard', 'calibration.json');
+
+export async function replayCommand({ projectDir, values, version }, io) {
+  const range = values.since ?? values.changed;
+  if (!range) {
+    io.err('usage: testguard replay [dir] --since <range>   (e.g. --since HEAD~50..HEAD, or a tag)');
+    return 3;
+  }
+  const confirmRuns = Number(values.confirm);
+  const budgetMs = Number(values.budget);
+  const limit = values.max ? Number(values.max) : undefined;
+  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 doc = await replay({
+    projectDir,
+    range,
+    confirmRuns,
+    budgetMs,
+    runnerCommand: values['runner-cmd'],
+    runnerName: values.runner,
+    nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
+    limit,
+    toolVersion: version,
+    onStage: !values.quiet && !values.json && process.stderr.isTTY ? ({ commit, i, n, stage }) => process.stderr.write(`\r\x1b[K  … ${commit.slice(0, 9)} (${i}/${n}) ${stage}`) : undefined,
+    onProgress: values.quiet || values.json ? undefined : () => {
+      if (process.stderr.isTTY) process.stderr.write('\r\x1b[K');
+    },
+  });
+
+  const outPath = values.out ? resolve(values.out) : replayPath(projectDir);
+  writeSpecDoc('replay', outPath, doc);
+  const calibration = calibrationFrom(doc, { toolVersion: version });
+  // Beside the replay document, whatever --out says: the two are one result,
+  // and splitting them across directories loses the pairing — and leaves a
+  // file behind in a repository the run is only meant to read.
+  const calPath = values.baseline ? resolve(values.baseline) : values.out ? join(dirname(outPath), 'calibration.json') : calibrationPath(projectDir);
+  writeSpecDoc('calibration', calPath, calibration);
+
+  if (values.json) {
+    io.out(JSON.stringify({ replay: doc, calibration, paths: { replay: outPath, calibration: calPath } }, null, 2));
+  } else {
+    io.out(renderReplay(doc));
+    io.out('');
+    for (const [cls, b] of Object.entries(calibration.buckets).sort((a, b2) => b2[1].n - a[1].n)) {
+      io.out(`  ${cls.padEnd(22)} blind ${String(b.positives).padStart(3)}/${String(b.n).padEnd(3)}  p=${b.p.toFixed(2)}  ci [${b.ci[0].toFixed(2)}, ${b.ci[1].toFixed(2)}]`);
+    }
+    if (Object.keys(calibration.buckets).length === 0) io.out('  no measurable bug in this range: nothing to calibrate from yet.');
+    io.out('');
+    io.out(`replay: ${outPath}`);
+    io.out(`calibration: ${calPath}`);
+  }
+  // Replay reports; it never gates. A bug that escaped is history, not a
+  // regression in this change, and a gate on history is a gate nobody can pass.
+  return 0;
+}

package/src/commands/status.mjs

@@ -1,9 +1,11 @@
+import { resolve } from 'node:path';
 import { computeStatus, renderStatus } from '../status/status.mjs';
 import { validate } from '../../spec/lib/validate.mjs';
 import { resolveChangedRef, withChangedRef } from '../gate/changed.mjs';
 
 export async function statusCommand({ projectDir, values, version }, io) {
-  const doc = withChangedRef(resolveChangedRef({ explicit: values.changed }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'] }), io.err);
+  const evidence = values.evidence ? resolve(values.evidence) : undefined;
+  const doc = withChangedRef(resolveChangedRef({ explicit: values.changed }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'], evidence }), io.err);
   const result = validate('status', doc);
   if (!result.ok) throw new Error(`status document does not conform: ${result.errors.map((e) => `${e.path}: ${e.message}`).join('; ')}`);
   io.out(values.json ? JSON.stringify(doc, null, 2) : renderStatus(doc));

package/src/git.mjs

@@ -23,6 +23,11 @@ export function headSha(dir, ref = 'HEAD') {
   }
 }
 
+/** Is `ancestor` reachable from `ref`? False when either does not resolve. */
+export function isAncestor(dir, ancestor, ref = 'HEAD') {
+  return spawnSync('git', ['merge-base', '--is-ancestor', ancestor, ref], { cwd: dir }).status === 0;
+}
+
 /** True when any of `paths` (repo-relative; empty = whole tree) has uncommitted changes. */
 export const isDirty = (dir, paths = []) => git(['status', '--porcelain', '--', ...paths], dir).length > 0;
 

package/src/init/init.mjs

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

package/src/init/templates/SKILL.md

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