testguard-cli 0.4.0 → 0.6.0

package/src/commands/brief.mjs

@@ -1,15 +1,32 @@
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { readSpecDoc, writeSpecDoc } from '../evidence/writer.mjs';
-import { buildBrief } 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';
 
 export async function briefCommand({ projectDir, values, version }, io) {
   const evPath = values.evidence ? resolve(values.evidence) : evidencePath(projectDir);
+  let status;
+  try {
+    // 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'], 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.
-    if (values.text) return 0;
+    // 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 || 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`);
     return 2;
   }
@@ -21,14 +38,11 @@ export async function briefCommand({ projectDir, values, version }, io) {
     io.err('--max must be an integer from 1 to 50');
     return 3;
   }
-  let next;
-  try {
-    next = computeStatus({ projectDir, toolVersion: version }).next;
-  } catch {
-    next = undefined; // a brief must never fail because status could not be computed
-  }
-  const brief = buildBrief(evidence, baseline, { max, next });
-  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/gate.mjs

@@ -0,0 +1,47 @@
+import { join, resolve } from 'node:path';
+import { computeChangedGate, resolveChangedRef, renderGate, DEFAULT_EXCLUDES } from '../gate/changed.mjs';
+import { writeSpecDoc } from '../evidence/writer.mjs';
+
+export const gatePath = (projectDir) => join(projectDir, '.testguard', 'gate.json');
+
+/**
+ * `testguard gate --changed <ref>`: fail when a changed source file carries
+ * no claim and no excusing ignore entry. Exit 0 covered · 1 uncovered (or
+ * --strict with nothing evaluated) · 2 cannot evaluate · 3 no reference.
+ */
+export async function gateCommand({ projectDir, values, version }, io) {
+  if (values.explain) {
+    io.out('Files that are source by extension but never carry claims (excluded by default; add more with --exclude <glob>):');
+    for (const g of DEFAULT_EXCLUDES) io.out(`  ${g}`);
+    io.out('Non-source files (anything but .js .mjs .cjs .ts .mts .cts .jsx .tsx) are excluded before these patterns apply.');
+    return 0;
+  }
+  const resolved = resolveChangedRef({ explicit: values.changed });
+  if (!resolved) {
+    io.err('gate needs a reference to measure the change against: --changed <ref> (e.g. origin/main), or set TESTGUARD_CHANGED_REF. In GitHub Actions and GitLab CI the base branch is detected automatically.');
+    return 3;
+  }
+  const ref = resolved.ref;
+  // The gate itself never degrades: a detected reference that does not resolve is exit 2 here, because the gate's whole job is the measurement.
+  if (!resolved.required && !values.json && !values.quiet) io.err(`--changed not given; using ${ref} from ${resolved.from}`);
+  const doc = computeChangedGate({
+    projectDir,
+    ref,
+    includeDirty: values['include-dirty'],
+    exclude: values.exclude ?? [],
+    strict: values.strict,
+    toolVersion: version,
+    claimsPath: values.claims ? resolve(values.claims) : undefined,
+    ignorePath: values.ignore ? resolve(values.ignore) : undefined,
+  });
+  const outPath = values.out ? resolve(values.out) : gatePath(projectDir);
+  writeSpecDoc('gate', outPath, doc);
+  if (values.json) {
+    io.out(JSON.stringify(doc, null, 2));
+  } else {
+    io.out(renderGate(doc));
+    if (doc.uncovered.length) io.out(`Next: state the claim for each UNCLAIMED file (scaffold proposes the faults), or add a testguard.ignore.json path entry with a reason that a reviewer will accept.`);
+    if (!values.quiet) io.out(`gate: ${outPath}`);
+  }
+  return doc.exitCode;
+}

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

@@ -6,6 +6,7 @@ import { writeSpecDoc, readSpecDoc } from '../evidence/writer.mjs';
 import { gate } from '../baseline/baseline.mjs';
 import { renderRecord, renderSummary, sortForReport, PROVISIONAL_WARNING } from '../render.mjs';
 import { computeStatus } from '../status/status.mjs';
+import { resolveChangedRef, withChangedRef } from '../gate/changed.mjs';
 export const provisionalEvidencePath = (projectDir) => join(projectDir, '.testguard', 'evidence-provisional.json');
 
 export const evidencePath = (projectDir) => join(projectDir, '.testguard', 'evidence.json');
@@ -29,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;
@@ -40,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,
@@ -51,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 = computeStatus({ projectDir, toolVersion: version });
+    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,8 +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 = computeStatus({ projectDir, toolVersion: version });
+  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/gate/changed.mjs

@@ -0,0 +1,222 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { extname, join, relative, resolve, dirname } from 'node:path';
+import { git, repoRoot, headSha, GitError } from '../git.mjs';
+import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
+import { readSpecDoc } from '../evidence/writer.mjs';
+import { resolveDefenders } from '../probe/runners/shared.mjs';
+import { discoverDefenders } from '../probe/discover.mjs';
+import { globToRegExp } from '../util/glob.mjs';
+
+/**
+ * Claim coverage of a change.
+ *
+ * `probe` answers "do the tests defend the claims that exist?". This answers
+ * the question every field report so far turned on: "does the code I just
+ * changed have any claim at all?". A repository with ten old claims and one
+ * new, unclaimed feature exits 0 forever under `probe`; under `gate` the
+ * delta is measured, file by file, and an uncovered file is a finding.
+ *
+ * The unit is the file, on purpose: a fault anchors to a file, so the file is
+ * the smallest unit the rest of the contract already understands.
+ */
+
+export const SOURCE_EXT = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx']);
+const TEST_RE = /\.(test|spec)\.[cm]?[jt]sx?$/;
+
+/** Files that are source by extension but never carry claims. Printed by --explain. */
+export const DEFAULT_EXCLUDES = Object.freeze([
+  '**/*.d.ts',
+  '**/*.config.*',
+  '**/*.stories.*',
+  '**/*.generated.*',
+  '**/fixtures/**',
+  '**/__fixtures__/**',
+  '**/__mocks__/**',
+  '**/__snapshots__/**',
+  '.testguard/**',
+]);
+
+export const defaultIgnorePath = (projectDir) => join(projectDir, 'testguard.ignore.json');
+
+/**
+ * The reference the change is measured against. Explicit flag first, then the
+ * environments CI sets, then nothing: a wrong default would make the gate pass
+ * trivially (an upstream that already contains the change has an empty diff),
+ * so no ref is an error the caller reports, never a silent guess.
+ */
+export function detectChangedRef(env = process.env) {
+  if (env.TESTGUARD_CHANGED_REF) return { ref: env.TESTGUARD_CHANGED_REF, from: 'TESTGUARD_CHANGED_REF' };
+  // GitHub Actions, pull_request events.
+  if (env.GITHUB_BASE_REF) return { ref: `origin/${env.GITHUB_BASE_REF}`, from: 'GITHUB_BASE_REF' };
+  // GitLab merge request pipelines. The diff base sha is exact and needs no
+  // remote-tracking ref; the target branch name is the fallback (it needs
+  // `git fetch origin <branch>` or GIT_DEPTH: 0 on the job).
+  const sha = env.CI_MERGE_REQUEST_DIFF_BASE_SHA;
+  if (sha && /^[0-9a-f]{7,40}$/i.test(sha) && !/^0+$/.test(sha)) return { ref: sha, from: 'CI_MERGE_REQUEST_DIFF_BASE_SHA' };
+  if (env.CI_MERGE_REQUEST_TARGET_BRANCH_NAME) return { ref: `origin/${env.CI_MERGE_REQUEST_TARGET_BRANCH_NAME}`, from: 'CI_MERGE_REQUEST_TARGET_BRANCH_NAME' };
+  return null;
+}
+
+/**
+ * Resolve the reference a command should measure against, and whether it may
+ * be dropped on failure. An explicit `--changed` is the user's word: if it
+ * does not resolve, that is an error. A reference detected from CI variables
+ * is a convenience: if it does not resolve (shallow clone, temp directory,
+ * no remote) the command says so on stderr and continues without a change
+ * measurement, because `status` and `brief` must keep working everywhere.
+ */
+export function resolveChangedRef({ explicit, env = process.env } = {}) {
+  if (explicit) return { ref: explicit, from: '--changed', required: true };
+  const d = detectChangedRef(env);
+  return d ? { ...d, required: false } : null;
+}
+
+/**
+ * Run `compute(ref)` for a resolved reference. A required reference propagates
+ * its error; a detected one that fails yields `undefined` after `warn(message)`.
+ */
+export function withChangedRef(resolved, compute, warn = () => {}) {
+  if (!resolved) return compute(undefined);
+  try {
+    return compute(resolved.ref);
+  } catch (e) {
+    if (resolved.required || !(e instanceof GitError)) throw e;
+    warn(`change coverage skipped: ${resolved.ref} (from ${resolved.from}) does not resolve here — ${e.message.split('. ')[0]}. Pass --changed <ref> to make this an error.`);
+    return compute(undefined);
+  }
+}
+
+/**
+ * Files changed since the merge-base of `ref` and HEAD, repo-root-relative,
+ * deletions dropped. With `includeDirty` the working tree (tracked edits,
+ * staged or not, plus untracked non-ignored files) is compared instead of HEAD.
+ */
+export function changedFiles({ root, ref, includeDirty = false }) {
+  let base;
+  try {
+    base = git(['merge-base', ref, 'HEAD'], root);
+  } catch (e) {
+    throw new GitError(`cannot resolve --changed ${ref}: ${e.message.split('\n').pop()}. In CI the base must be present locally: GitHub Actions — actions/checkout with fetch-depth: 0; GitLab — GIT_DEPTH: 0 or \`git fetch origin <target branch>\` before the job (merge request pipelines also provide CI_MERGE_REQUEST_DIFF_BASE_SHA, which needs no fetch).`);
+  }
+  const head = headSha(root);
+  const out = new Set(git(['diff', '--name-only', '--diff-filter=d', '-z', base, ...(includeDirty ? [] : ['HEAD'])], root).split('\0').filter(Boolean));
+  if (includeDirty) for (const f of git(['ls-files', '--others', '--exclude-standard', '-z'], root).split('\0').filter(Boolean)) out.add(f);
+  return { base, head, files: [...out].sort() };
+}
+
+const isExpired = (entry, now) => Boolean(entry.expires) && new Date(entry.expires).getTime() <= now.getTime();
+
+/**
+ * The claim to attach to, if any: one whose fault files live in the same
+ * directory as the changed file. A claim that merely shares `src/` is not
+ * "nearest", it is noise, and a wrong `--claim` hint is worse than none.
+ */
+function nearestClaim(file, faultFiles) {
+  const dir = dirname(file);
+  for (const [ff, ids] of faultFiles) if (dirname(ff) === dir) return ids[0];
+  return null;
+}
+
+/**
+ * Compute the gate for one change. Pure apart from reading the repository,
+ * the claims file and the ignore file; the caller decides what to print and
+ * what to write.
+ */
+export function computeChangedGate({ projectDir, ref, includeDirty = false, exclude = [], strict = false, now = new Date(), toolVersion = '0.0.0', generatedAt = now.toISOString(), claimsPath, ignorePath }) {
+  projectDir = realpathSync(resolve(projectDir));
+  const root = repoRoot(projectDir);
+  const relProject = relative(root, projectDir).split('\\').join('/');
+  const { base, head, files } = changedFiles({ root, ref, includeDirty });
+
+  // Repo-root paths → project paths; a change outside the project directory is not this project's change.
+  const changed = [];
+  for (const f of files) {
+    if (!relProject) { changed.push(f); continue; }
+    if (f.startsWith(relProject + '/')) changed.push(f.slice(relProject.length + 1));
+  }
+
+  const cPath = claimsPath ?? defaultClaimsPath(projectDir);
+  const claims = existsSync(cPath) ? loadClaims(cPath) : { claims: [] };
+  const iPath = ignorePath ?? defaultIgnorePath(projectDir);
+  const ignore = existsSync(iPath) ? readSpecDoc('ignore', iPath) : { entries: [] };
+
+  // Coverage index: which files carry a fault, which test files defend a claim.
+  const faultFiles = new Map(); // file → claimIds
+  const defenderFiles = new Map(); // test file → claimIds
+  for (const c of claims.claims) {
+    for (const f of c.faults) faultFiles.set(f.file, [...new Set([...(faultFiles.get(f.file) ?? []), c.id])]);
+    const defenders = c.defendedBy?.length ? resolveDefenders(projectDir, c.defendedBy) : [...new Set(c.faults.flatMap((f) => discoverDefenders(projectDir, f.file)))];
+    for (const d of defenders) defenderFiles.set(d, [...new Set([...(defenderFiles.get(d) ?? []), c.id])]);
+  }
+
+  const pathEntries = ignore.entries.filter((e) => e.kind === 'path').map((e) => ({ entry: e, re: globToRegExp(e.pattern), expired: isExpired(e, now), files: [] }));
+  const userExcludes = exclude.map((g) => ({ glob: g, re: globToRegExp(g) }));
+  const defaultExcludes = DEFAULT_EXCLUDES.map((g) => ({ glob: g, re: globToRegExp(g) }));
+
+  const excluded = [];
+  const covered = [];
+  const uncovered = [];
+  for (const file of changed) {
+    if (!SOURCE_EXT.has(extname(file))) { excluded.push({ file, by: 'non-source' }); continue; }
+    const ux = userExcludes.find((x) => x.re.test(file));
+    if (ux) { excluded.push({ file, by: `exclude:${ux.glob}` }); continue; }
+    const dx = defaultExcludes.find((x) => x.re.test(file));
+    if (dx) { excluded.push({ file, by: `default:${dx.glob}` }); continue; }
+
+    const isTest = TEST_RE.test(file);
+    if (faultFiles.has(file)) { covered.push({ file, by: 'fault', claimIds: faultFiles.get(file) }); continue; }
+    if (isTest && defenderFiles.has(file)) { covered.push({ file, by: 'defender', claimIds: defenderFiles.get(file) }); continue; }
+    const active = pathEntries.find((p) => !p.expired && p.re.test(file));
+    if (active) { active.files.push(file); covered.push({ file, by: 'ignore', pattern: active.entry.pattern }); continue; }
+    for (const p of pathEntries) if (p.expired && p.re.test(file)) p.files.push(file);
+
+    // Uncovered. Point at a same-directory claim so the author knows where to attach.
+    const nearest = nearestClaim(file, faultFiles);
+    const item = {
+      file,
+      kind: isTest ? 'test' : 'source',
+      ...(nearest ? { nearestClaimId: nearest } : {}),
+      suggestion: isTest
+        ? `add ${file} to the defendedBy of the claim it defends${nearest ? ` (nearest: ${nearest})` : ''}, or state a new claim for what it asserts`
+        : `testguard scaffold ${file}${nearest ? ` --claim ${nearest}` : ''}`,
+    };
+    uncovered.push(item);
+  }
+
+  const evaluated = covered.length + uncovered.length;
+  const reliedOn = pathEntries.filter((p) => !p.expired && p.files.length).map((p) => ({ pattern: p.entry.pattern, reason: p.entry.reason, ...(p.entry.expires ? { expires: p.entry.expires } : {}), files: p.files }));
+  const expired = pathEntries.filter((p) => p.expired && p.files.length).map((p) => ({ pattern: p.entry.pattern, reason: p.entry.reason, expires: p.entry.expires, files: p.files }));
+  const exitCode = uncovered.length > 0 ? 1 : strict && changed.length > 0 && evaluated === 0 ? 1 : 0;
+
+  return {
+    schemaVersion: 1,
+    tool: { name: 'testguard', version: toolVersion },
+    generatedAt,
+    ref,
+    base,
+    head,
+    includeDirty,
+    strict,
+    changed: changed.length,
+    evaluated,
+    excluded,
+    covered,
+    uncovered,
+    reliedOn,
+    expired,
+    exitCode,
+  };
+}
+
+export function renderGate(doc) {
+  const lines = [];
+  const where = doc.includeDirty ? 'working tree' : `HEAD ${doc.head.slice(0, 7)}`;
+  lines.push(`gate: ${doc.changed} file${doc.changed === 1 ? '' : 's'} changed since ${doc.ref} (merge-base ${doc.base.slice(0, 7)}) in the ${where}; ${doc.evaluated} evaluated, ${doc.excluded.length} excluded, ${doc.covered.length} covered, ${doc.uncovered.length} uncovered`);
+  for (const u of doc.uncovered) lines.push(`UNCLAIMED  ${u.file}  (${u.kind}${u.nearestClaimId ? `, nearest claim ${u.nearestClaimId}` : ''})\n           → ${u.suggestion}`);
+  for (const r of doc.reliedOn) lines.push(`excused    ${r.files.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.files.join(', ')}`);
+  if (doc.changed > 0 && doc.evaluated === 0) lines.push(`note: every changed file was excluded (${[...new Set(doc.excluded.map((x) => x.by))].join(', ')}); 0 evaluated${doc.strict ? ' — --strict makes this a failure' : ''}`);
+  if (doc.changed === 0) lines.push(`no changes since ${doc.ref}; nothing to claim`);
+  if (doc.uncovered.length === 0 && doc.exitCode === 0 && doc.evaluated > 0) lines.push('every changed source file carries a claim or an excusing ignore entry');
+  return lines.join('\n');
+}

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;