testguard-cli 0.3.1 → 0.5.0

package/src/commands/brief.mjs

@@ -1,15 +1,29 @@
 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 } 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'] }));
+  } 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) {
+      if (status?.changes?.uncovered?.length) io.out(buildUnclaimedBrief({ tool: { name: 'testguard', version }, next: status.next, changes: status.changes }).text.trimEnd());
+      return 0;
+    }
     io.err(`no evidence at ${evPath}; run \`testguard probe\` first`);
     return 2;
   }
@@ -21,13 +35,7 @@ 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 });
+  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());
   return 0;

package/src/commands/claims.mjs

@@ -1,7 +1,7 @@
 import { resolve } from 'node:path';
 import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
 import { scanAnnotations, reconcile } from '../claims/annotations.mjs';
-import { resolveDefenders } from '../probe/runner-vitest.mjs';
+import { resolveDefenders } from '../probe/runners/shared.mjs';
 import { discoverDefenders } from '../probe/discover.mjs';
 
 export async function claimsCommand({ projectDir, values }, io) {

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/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');
@@ -42,6 +43,7 @@ export async function probeCommand({ projectDir, values, version }, io) {
     mode: values['in-place'] ? 'in-place' : 'worktree',
     ref: values.ref,
     runnerCommand: values['runner-cmd'],
+    runnerName: values.runner,
     nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
     only,
     escalate: !values['no-escalate'],
@@ -57,7 +59,7 @@ export async function probeCommand({ projectDir, values, version }, io) {
 
   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'] }), 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/status.mjs

@@ -1,8 +1,9 @@
 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 doc = withChangedRef(resolveChangedRef({ explicit: values.changed }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'] }), 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/init/init.mjs

@@ -14,7 +14,7 @@ Before writing or changing tests, run \`testguard status --json\` and follow \`n
 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.
 ${AGENTS_END}`;
-const GITIGNORE_LINES = ['.testguard/evidence.json', '.testguard/evidence-provisional.json', '.testguard/evidence-partial.json', '.testguard/brief.json', '.testguard/scaffold-*.json'];
+const GITIGNORE_LINES = ['.testguard/evidence.json', '.testguard/evidence-provisional.json', '.testguard/evidence-partial.json', '.testguard/brief.json', '.testguard/gate.json', '.testguard/scaffold-*.json'];
 
 /**
  * Install the agent operating layer into a consumer project: the skill, the

package/src/init/templates/SKILL.md

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

package/src/probe/discover.mjs

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { listTestFiles } from './runner-vitest.mjs';
+import { listTestFiles } from './runners/shared.mjs';
 import { fileImports } from './rank.mjs';
 
 /**

package/src/probe/probe.mjs

@@ -6,7 +6,8 @@ import { repoRoot as gitRoot, headSha, isDirty, snapshotWorkingTree } from '../g
 import { discoverDefenders } from './discover.mjs';
 import { createScratch, inPlace, PreconditionError } from './worktree.mjs';
 import { applyFault, locate } from './inject.mjs';
-import * as vitest from './runner-vitest.mjs';
+import { resolveDefenders, parseCommandTemplate } from './runners/shared.mjs';
+import { selectRunner, RUNNERS } from './runners/index.mjs';
 import { classify, shouldStopEarly } from './classify.mjs';
 import { blastRadius, rank } from './rank.mjs';
 import { hashFile, sha256 } from '../util/hash.mjs';
@@ -14,9 +15,9 @@ import { fingerprint } from '../../spec/lib/fingerprint.mjs';
 
 const isKill = (r) => r.outcome === 'fail' && r.assertionFailures > 0;
 
-function readRunnerVersion(projectDir) {
+function readRunnerVersion(projectDir, name = 'vitest') {
   try {
-    return JSON.parse(readFileSync(createRequire(join(projectDir, 'noop.js')).resolve('vitest/package.json'), 'utf8')).version;
+    return JSON.parse(readFileSync(createRequire(join(projectDir, 'noop.js')).resolve(`${name}/package.json`), 'utf8')).version;
   } catch {
     return undefined;
   }
@@ -34,6 +35,7 @@ export async function probe({
   ref = 'HEAD',
   budgetMs = 120_000,
   runnerCommand,
+  runnerName = 'auto',
   nodeModules,
   only,
   includeDirty = false,
@@ -75,7 +77,7 @@ export async function probe({
       const watched = new Set(targets);
       for (const claim of claims.claims) {
         if (selected && !selected.has(claim.id)) continue;
-        const declared = claim.defendedBy?.length ? vitest.resolveDefenders(projectDir, claim.defendedBy) : claim.faults.flatMap((f) => discoverDefenders(projectDir, f.file));
+        const declared = claim.defendedBy?.length ? resolveDefenders(projectDir, claim.defendedBy) : claim.faults.flatMap((f) => discoverDefenders(projectDir, f.file));
         for (const d of declared) watched.add(relative(root, join(projectDir, d)));
         for (const g of claim.defendedBy ?? []) if (!g.includes('*')) watched.add(relative(root, join(projectDir, g)));
       }
@@ -89,27 +91,29 @@ export async function probe({
   const iso = mode === 'worktree' ? createScratch({ repoRoot: root, projectDir, ref: snapshot ?? ref, scratchBase, nodeModules }) : inPlace({ repoRoot: root, projectDir });
   const records = [];
   let runnerVersion;
+  let runner = RUNNERS[runnerName === 'auto' ? 'vitest' : runnerName];
   try {
-    const commandTemplate = runnerCommand ? vitest.parseCommandTemplate(runnerCommand) : undefined;
+    const commandTemplate = runnerCommand ? parseCommandTemplate(runnerCommand) : undefined;
     if (!commandTemplate) {
       // An unresolvable runner is a precondition failure, not a flaky defender.
-      const check = await vitest.checkRunner({ projectDir: iso.projectDir });
-      if (!check.ok) {
-        throw new PreconditionError(`test runner is not resolvable in the ${mode === 'worktree' ? 'scratch worktree' : 'project'} (${check.message}). ` +
+      const sel = await selectRunner({ projectDir: iso.projectDir, name: runnerName });
+      if (sel.error) {
+        throw new PreconditionError(`test runner is not resolvable in the ${mode === 'worktree' ? 'scratch worktree' : 'project'} (${sel.error}). ` +
           (mode === 'worktree' ? 'No usable node_modules was linked: pass --node-modules <path>, or run with --in-place.' : 'Install dependencies first.'));
       }
-      runnerVersion = check.version;
+      runner = sel.runner;
+      runnerVersion = sel.version;
     }
-    const allTests = vitest.listTestFiles(iso.projectDir);
+    const allTests = runner.tests(iso.projectDir);
     const baselineCache = new Map();
     const prior = previous && previous.run.confirmRuns === confirmRuns
       ? new Map(previous.records.map((r) => [`${r.claim.id}/${r.subject.id}`, r]))
       : new Map();
-    const runDefenders = (files) => vitest.runVitest({ projectDir: iso.projectDir, files, budgetMs, commandTemplate });
+    const runDefenders = (files) => runner.run({ projectDir: iso.projectDir, files, budgetMs, commandTemplate });
 
     for (const claim of claims.claims) {
       if (selected && !selected.has(claim.id)) continue;
-      const declared = claim.defendedBy?.length ? vitest.resolveDefenders(iso.projectDir, claim.defendedBy) : null;
+      const declared = claim.defendedBy?.length ? resolveDefenders(iso.projectDir, claim.defendedBy) : null;
       for (const fault of claim.faults) {
         const defenders = declared ?? discoverDefenders(iso.projectDir, fault.file);
         const stage = (name, i, n) => onStage({ claimId: claim.id, faultId: fault.id, stage: name, i, n });
@@ -130,7 +134,7 @@ export async function probe({
       startedAt,
       finishedAt: new Date().toISOString(),
       repo: { head, dirty: isDirty(root), ...(snapshot ? { snapshot } : {}) },
-      runner: { name: vitest.name, ...((runnerVersion ?? readRunnerVersion(projectDir)) ? { version: runnerVersion ?? readRunnerVersion(projectDir) } : {}) },
+      runner: { name: runner.name, ...((runnerVersion ?? readRunnerVersion(projectDir, runner.name)) ? { version: runnerVersion ?? readRunnerVersion(projectDir, runner.name) } : {}) },
       confirmRuns,
       ...(confirmRuns < 3 ? { provisional: true } : {}),
       mode,

package/src/probe/runners/index.mjs

@@ -0,0 +1,20 @@
+import * as vitest from './vitest.mjs';
+import * as jest from './jest.mjs';
+
+export const RUNNERS = { vitest, jest };
+
+/**
+ * Pick the runner: an explicit name, or the first of vitest, jest that is
+ * resolvable from the project. Returns { runner, version } or { error }.
+ */
+export async function selectRunner({ projectDir, name = 'auto' }) {
+  const candidates = name === 'auto' ? [vitest, jest] : [RUNNERS[name]];
+  if (!candidates[0]) return { error: `unknown runner "${name}"; use vitest, jest or auto` };
+  const messages = [];
+  for (const r of candidates) {
+    const c = await r.check({ projectDir });
+    if (c.ok) return { runner: r, version: c.version };
+    messages.push(`${r.name}: ${c.message}`);
+  }
+  return { error: messages.join('; ') };
+}

package/src/probe/runners/jest.mjs

@@ -0,0 +1,9 @@
+import { TEST_GLOBS, npx, runProcess, checkBinary, listTestFiles } from './shared.mjs';
+
+export const name = 'jest';
+// jest's default testMatch also collects anything under __tests__/.
+export const testGlobs = [...TEST_GLOBS, '**/__tests__/**/*.js', '**/__tests__/**/*.mjs', '**/__tests__/**/*.cjs', '**/__tests__/**/*.ts', '**/__tests__/**/*.tsx', '**/__tests__/**/*.jsx'];
+export const check = (opts) => checkBinary({ ...opts, bin: 'jest' });
+export const tests = (projectDir) => listTestFiles(projectDir, testGlobs);
+// --runTestsByPath: positionals are exact paths, not regexes — a path with `+` or `(` would otherwise silently match nothing.
+export const run = (opts) => runProcess({ ...opts, argv: (files, outFile) => [npx, 'jest', '--ci', '--json', `--outputFile=${outFile}`, '--runTestsByPath', ...files] });