testguard-cli 0.18.3 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.18.3",
+  "version": "0.19.0",
   "description": "Breaks your code on purpose and reports every promise your tests did not notice breaking. Mutation testing bound to the claims a project makes — vitest, jest, Playwright, pytest and unittest.",
   "type": "module",
   "license": "MIT",

package/spec/GATE-SEMANTICS.md

@@ -254,7 +254,12 @@ Rules that follow from the table:
    decided and leave a caller with an exit code this document does not define,
    which is strictly worse than one loud unverifiable claim. A `probe-error`
    record is never reused by a later run: it says something about the run, not
-   about the code. The one exception is a **precondition** failure — the
+   about the code. The same holds for a record whose reason is
+   `defenders-failed-to-load`: a broken `--runner-cmd`, a missing dependency or
+   an interpreter without the test requirements changes none of the hashed
+   inputs, so fixing the environment would otherwise leave the failure
+   reported as the current answer. Re-measuring it costs one baseline run per
+   defender set. The one exception is a **precondition** failure — the
    interpreter loading the source from outside the probed tree, a runner that
    does not resolve — which is a statement about every verdict in the run and
    still refuses it outright.
@@ -306,6 +311,11 @@ Rules that follow from the table:
    files; creating or editing any of them forces remeasurement. Evidence that
    predates this hash, or whose hash
    changed, is readable but never reusable for a current native discovery run.
+   A custom `--runner-cmd` has no native listing; its `testUniverseHash` binds
+   the static file set **and the parsed command argv**, so a changed command
+   is a changed universe and never reuses a verdict the old command measured.
+   Reformatting whitespace that parses to the same argv is not a change. Only
+   the hash is recorded, never the command text.
    When several configured runners list defenders, exact manifest membership
    assigns each file. An owned runner takes precedence over the project runner;
    competing owned runners or a declared defender absent from every manifest
@@ -578,12 +588,42 @@ Adopting tools may reconcile an existing baseline format (for example a
 `{version, fingerprints:{hash:count}}` file) by mapping it onto this shape;
 the suppress-up-to-count semantics are identical.
 
+A baseline command's machine output is the status document plus an optional
+`baseline` result, exactly as a probe's is the status document plus `run`:
+`{path, frozen}` when it froze one (`frozen` counts the unproven findings it
+holds), `{path, restamped}` when it moved an existing baseline's head (the
+commit it now names). The document is validated before it is printed. One
+document carries at most one invocation result, never both `run` and
+`baseline`.
+
 ## Ignore and annotations
 
-- An ignore entry removes a subject from *scope* before probing. Every entry
+- An ignore entry excuses a *coverage* or *removal* finding; it never
+  removes anything from a probe and never touches a verdict. A probe reads no
+  ignore file: a claim that is in the claims file is probed, so an excuse can
+  never hide a survivor. A known finding is accepted in a baseline (above),
+  which is fingerprinted, counted and reported as baselined. Every entry
   carries a `reason` of at least eight characters; the structured form is what
-  an auditor reads. A plain gitignore-syntax file may be accepted as shorthand
-  for reasonless `path` entries.
+  an auditor reads. An entry past its `expires` excuses nothing and is
+  reported as expired. The kinds, and the only thing each does:
+  - `path` — a glob over project paths. Excuses a changed source file from
+    the change gate (below); every reliance is reported.
+  - `claim` — exactly one claim id. Excuses the removal of that claim, and of
+    any of its faults, when claims are compared against an earlier reference.
+  - `fault` — exactly `<claimId>/<faultId>`. Excuses the removal of that one
+    fault in the same comparison.
+
+  There is no fingerprint kind: suppressing a finding by fingerprint is what a
+  baseline does, and a second, uncounted channel for it would let debt be
+  accepted where no baseline report shows it. A `claim` or `fault` pattern
+  that is not an exact identity is invalid, because it would excuse nothing —
+  or, for a `fault` entry without its fault id, the whole claim. A plain
+  gitignore-syntax file may be accepted as shorthand for reasonless `path`
+  entries.
+- A concerns file is read like every other spec document: one that does not
+  parse or does not conform fails the command that reads it (exit `2`). It
+  never degrades to a concern that matches nothing — a sweep aimed at nothing
+  reports clean.
 - An annotation is **strictly additive**. It never changes, suppresses, or
   drops a finding. Ranking may read annotations; verdicts never do.
 - A **signal** is a static, annotation-grade fact about a defender, recorded
@@ -792,6 +832,25 @@ evidence; they simply do not turn CI red.
 
 ## Exit codes
 
+| Code | Meaning |
+|---|---|
+| `0` | No new gating findings at or above the severity floor. |
+| `1` | At least one new gating finding. |
+| `2` | Precondition failed: test runner not resolvable (e.g. no `node_modules` linked into the scratch worktree), working tree dirty for a fault target file, claims file invalid, no commits. Nothing was probed. |
+| `3` | Usage or configuration error. |
+
+A tool must never exit `0` because it had nothing to check. If the claims
+file is empty or every claim is out of scope, that is reported explicitly and
+the exit code is `2`.
+
+`probe --allow-empty` is an explicit adoption exception for a valid claims
+file containing zero claims, with no `--claim` selection. It exits `0`, says
+that verification was skipped, and writes no evidence or baseline. Its JSON
+output is the existing `no-claims` status document, without run metadata;
+it never reports a clean measurement. Missing or invalid claims still fail,
+and selected claims cannot be silently skipped. Run `gate` separately to
+enforce coverage of changed files during adoption. Integrations must opt in.
+
 ### Explicit declared-origin policy result contract
 
 Optional `originPolicy` on evidence, status and brief (and status's probe `run`)
@@ -803,7 +862,8 @@ It requires a complete current-project run with confirm >= 3 and refuses
 before loading or writing. No policy is inferred when the option is absent.
 After measurement, the command reloads current claims and collects the current
 native runner universe under the same command budget, then binds targets,
-resolved defenders and current discovery dependencies. Missing bindings or
+resolved defenders, current discovery dependencies and the recorded runner
+identities (name, version and source). Missing bindings or
 discovery failure yields unavailable; custom/static runner universes cannot
 certify this boundary. Expired command budgets still write no partial result.
 This is point-in-time admission, not an atomic filesystem snapshot. Stored
@@ -834,25 +894,6 @@ Completed probe JSON with unavailable policy exits 2; failed policy or ordinary
 new findings exits 1; passed policy without ordinary findings exits 0.
 Partial/provisional invocations cannot carry an origin policy.
 
-| Code | Meaning |
-|---|---|
-| `0` | No new gating findings at or above the severity floor. |
-| `1` | At least one new gating finding. |
-| `2` | Precondition failed: test runner not resolvable (e.g. no `node_modules` linked into the scratch worktree), working tree dirty for a fault target file, claims file invalid, no commits. Nothing was probed. |
-| `3` | Usage or configuration error. |
-
-A tool must never exit `0` because it had nothing to check. If the claims
-file is empty or every claim is out of scope, that is reported explicitly and
-the exit code is `2`.
-
-`probe --allow-empty` is an explicit adoption exception for a valid claims
-file containing zero claims, with no `--claim` selection. It exits `0`, says
-that verification was skipped, and writes no evidence or baseline. Its JSON
-output is the existing `no-claims` status document, without run metadata;
-it never reports a clean measurement. Missing or invalid claims still fail,
-and selected claims cannot be silently skipped. Run `gate` separately to
-enforce coverage of changed files during adoption. Integrations must opt in.
-
 ## Read-only authoring input (candidate)
 
 `authoring-input` is metadata-only inspection, never claims or evidence. Its
@@ -916,6 +957,13 @@ worker ceiling and must be one for serial execution; custom commands omit it.
 Native evidence reuse requires the same recorded worker ceiling and serial policy.
 Older native evidence with no worker ceiling is remeasured; native and opaque
 custom-command policies are not interchangeable.
+Every reuse also requires the same recorded `run.runner`: name (the engine that
+ran, so pytest and unittest differ), version and `source`. `source` is recorded
+for every resolved runner — `project` (the project's package, its virtualenv,
+or an interpreter named by path), `path` (an executable found on PATH,
+including a bare command name given to `--python`) or `builtin` — and is absent
+only for a custom command, which resolves nothing. Evidence that recorded no
+runner, or a different one, is remeasured.
 `status.cost.measurements` copies these measurements when available. Historical
 `totalMs` and cost gates retain their existing record attribution, including
 reused durations and repeated shared baseline durations. Older evidence has no

package/spec/README.md

@@ -34,14 +34,16 @@ that carry claims, baselines, scoping and briefs do not care.
 | `claims` | [`schemas/claims.schema.json`](schemas/claims.schema.json) | What must be true, and one or more concrete faults that would make it false. Producer-agnostic: a human, an operator, an agent, or a derivation may all emit the same fault shape, and every artifact says which. |
 | `evidence` | [`schemas/evidence.schema.json`](schemas/evidence.schema.json) | One run's findings on disk, readable without the tool. Every verdict carries every run that produced it. |
 | `baseline` | [`schemas/baseline.schema.json`](schemas/baseline.schema.json) | Frozen fingerprints of existing debt. Gate only what is new. |
-| `ignore` | [`schemas/ignore.schema.json`](schemas/ignore.schema.json) | Reviewable scoping. Every entry has a reason. |
+| `ignore` | [`schemas/ignore.schema.json`](schemas/ignore.schema.json) | Reviewable excuses: a `path` entry excuses a changed file from the change gate, a `claim` or `fault` entry excuses a removal. Every entry has a reason; none removes a claim from a probe or touches a verdict — accepted findings belong in a baseline. |
 | `calibration` | [`schemas/calibration.schema.json`](schemas/calibration.schema.json) | The observed rate of a bucket's outcome — what it measures is in the document — with a Wilson interval and the sample size behind it. Every number is recomputable and the validator recomputes it; provenance, a producer floor, backoff tiers and a labelled fallback ride along so a second tool's honesty survives translation. |
 | `brief` | [`schemas/brief.schema.json`](schemas/brief.schema.json) | What to tell an agent before it writes code — ranked, capped, never a single score, and carrying the one next action. |
 | `status` | [`schemas/status.schema.json`](schemas/status.schema.json) | Where the project is and what happens next — the single machine-readable truth every human rendering derives from. Surfaces faults whose content changed since they were probed, and changed files that carry no claim. |
 | `replay` | [`schemas/replay.schema.json`](schemas/replay.schema.json) | Would this suite have caught the bugs that already escaped? Replays real fix commits: revert the source, remove the test the fix shipped, run what remains. A replayed bug is ground truth — a human already confirmed it was a defect — which is what a fault model is calibrated against. |
 | `gate` | [`schemas/gate.schema.json`](schemas/gate.schema.json) | Claim coverage of one change: which changed files carry a claim, which are excused (and by which ignore entry), which are unclaimed. The delta gate for code that has no claim yet. |
 | `annotations` | [`schemas/annotations.schema.json`](schemas/annotations.schema.json) | Explicit file-header authoring preview/apply, refusals and recoverable partial failures. Never verification, a probe verdict, or authentication of intent; internal source contents are excluded. |
-| `authoring-input` | [`schemas/authoring-input.schema.json`](schemas/authoring-input.schema.json) | Candidate metadata-only document/fix input handoff. No source text, origin assignment, claims or verification; historical partitions retain excluded/deleted/unsupported counts. CLI exposure remains pending. |
+| `authoring-input` | [`schemas/authoring-input.schema.json`](schemas/authoring-input.schema.json) | Candidate metadata-only document/fix input handoff. No source text, origin assignment, claims or verification; historical partitions retain excluded/deleted/unsupported counts. Emitted by `scaffold --from-document` and `scaffold --from-fix`. |
+| `concerns` | [`schemas/concerns.schema.json`](schemas/concerns.schema.json) | A named kind of promise and where to look for it: a statement, target globs and the fault classes that are relevant. Aims a sweep; never becomes a claim by itself. |
+| `sweep` | [`schemas/sweep.schema.json`](schemas/sweep.schema.json) | Proposed faults for unclaimed changed files (or a concern, or the storage-write surface), the bounded selection probed, and what no test noticed. Drafts only; never replaces evidence. |
 
 Shared definitions (verdicts, fault classes, provenance, annotations) live in
 [`schemas/common.schema.json`](schemas/common.schema.json). Gate behaviour —

package/spec/lib/validate.mjs

@@ -112,8 +112,23 @@ function originErrors(kind, doc) {
 }
 
 // Rules JSON Schema cannot express. Each returns an array of {path, message}.
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const semantic = {
   'authoring-input': authoringInputErrors,
+  // A claim or fault entry is matched exactly against an identity, so a
+  // pattern that is not one excuses nothing — or, for a `fault` entry without
+  // its `/<faultId>`, excuses the whole claim. Neither is what a reviewer read.
+  ignore(doc) {
+    const errors = [];
+    doc.entries.forEach((e, i) => {
+      if (e.kind === 'claim' && !IDENTIFIER.test(e.pattern)) errors.push({ path: `/entries/${i}/pattern`, message: 'a claim entry names one claim id exactly; globs and paths are not matched' });
+      if (e.kind === 'fault') {
+        const parts = e.pattern.split('/');
+        if (parts.length !== 2 || !parts.every((p) => IDENTIFIER.test(p))) errors.push({ path: `/entries/${i}/pattern`, message: 'a fault entry names one fault exactly, as <claimId>/<faultId>' });
+      }
+    });
+    return errors;
+  },
   annotations(doc) {
     const errors = [];
     const fail = (path, message) => errors.push({ path, message });
@@ -419,6 +434,10 @@ const semantic = {
       const requested = new Set(scope.requestedClaims);
       if (scope.probedClaims.some((id) => !requested.has(id))) errors.push({ path: '/run/scope/probedClaims', message: 'every probed claim must have been requested' });
     }
+    // One invocation result per document: `run` is what a probe measured,
+    // `baseline` is what a baseline command wrote. A document carrying both
+    // would attribute one command's result to the other.
+    if (doc.run && doc.baseline) errors.push({ path: '/baseline', message: 'a status document carries at most one invocation result: run (probe) or baseline (baseline), never both' });
     return errors;
   },
 
@@ -588,7 +607,9 @@ export function validate(kind, doc) {
   if (!check(doc)) {
     return {
       ok: false,
-      errors: check.errors.map((e) => ({ path: e.instancePath || '/', message: e.message ?? 'invalid' })),
+      // A closed set names its members: "must be equal to one of the allowed
+      // values" alone sends the reader to the schema to find out what they are.
+      errors: check.errors.map((e) => ({ path: e.instancePath || '/', message: `${e.message ?? 'invalid'}${e.keyword === 'enum' ? `: ${e.params.allowedValues.join(', ')}` : ''}` })),
     };
   }
   const errors = semantic[kind] ? semantic[kind](doc) : [];

package/spec/schemas/evidence.schema.json

@@ -81,7 +81,7 @@
               "maxLength": 64
             },
             "source": {
-              "description": "`project`: the runner package resolved from the project. `path`: an executable on PATH ran instead. `builtin`: the explicitly selected node-test engine uses the Node executable running TestGuard; its version is required.",
+              "description": "Where the runner was resolved from; recorded for every resolved runner and absent only for a custom command. `project`: the runner package resolved from the project, the project's virtualenv, or an interpreter named by path. `path`: an executable found on PATH ran instead (including a bare command name given to --python). `builtin`: the explicitly selected node-test engine uses the Node executable running TestGuard; its version is required. Reuse requires the same name, version and source.",
               "enum": [
                 "project",
                 "path",
@@ -677,7 +677,7 @@
               }
             },
             "testUniverseHash": {
-              "description": "Canonical hash of the runner-native test universe and the configuration files that produced it. Optional for backward compatibility; current probes emit it, and evidence without it is never reusable against a configured discovery run.",
+              "description": "Canonical hash of the runner-native test universe and the configuration files that produced it; for a custom --runner-cmd, of the static file set and the parsed command argv. Optional for backward compatibility; current probes emit it, and evidence without it is never reusable against a configured discovery run.",
               "$ref": "urn:claimspec:v1:common#/$defs/sha256"
             },
             "discoveryHashes": {

package/spec/schemas/ignore.schema.json

@@ -15,8 +15,8 @@
         "required": ["kind", "pattern", "reason"],
         "properties": {
           "kind": {
-            "description": "`path` = glob over repo paths; `claim` = claim id; `fault` = `<claimId>/<faultId>`; `fingerprint` = an evidence fingerprint.",
-            "enum": ["path", "claim", "fault", "fingerprint"]
+            "description": "`path` = glob over repo paths: excuses a changed source file from the change gate. `claim` = claim id: excuses the removal of that claim and of its faults. `fault` = `<claimId>/<faultId>`: excuses the removal of that one fault. No kind removes anything from a probe or changes a verdict; a known finding is accepted in a baseline, never here.",
+            "enum": ["path", "claim", "fault"]
           },
           "pattern": { "type": "string", "minLength": 1, "maxLength": 512 },
           "reason": { "type": "string", "minLength": 8, "maxLength": 2000 },

package/spec/schemas/status.schema.json

@@ -189,6 +189,29 @@
       },
       "additionalProperties": false
     },
+    "baseline": {
+      "description": "Present on baseline --json: the validated status document plus what this invocation wrote. `frozen` when a baseline was frozen (the number of unproven findings it holds), `restamped` when an existing baseline's head was moved (the commit it now names). A status document carries at most one invocation result, so it never has both `baseline` and `run`.",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["path", "frozen"],
+          "properties": {
+            "path": { "type": "string", "minLength": 1, "maxLength": 4096 },
+            "frozen": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["path", "restamped"],
+          "properties": {
+            "path": { "type": "string", "minLength": 1, "maxLength": 4096 },
+            "restamped": { "$ref": "urn:claimspec:v1:common#/$defs/gitSha" }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
     "cost": {
       "description": "Present when probe --json --cost is requested; derived only from the runs in the emitted evidence.",
       "type": "object",

package/src/brief/brief.mjs

@@ -7,6 +7,24 @@ export const HEADING = '## TEST BLINDSPOT CONTEXT';
 export const MARKDOWN_MARKER = '<!-- testguard:brief -->';
 const ORDER = ['survived', 'nocover', 'unverifiable', 'fault-invalid', 'timeout', 'flaky-defender'];
 
+const RUNNER_CACHES = [
+  [/[\\/]_npx[\\/]/, 'npx cache'],
+  [/[\\/]pnpm[\\/]dlx[\\/]/, 'pnpm dlx cache'],
+  [/[\\/]bunx-[^\\/]*[\\/]/, 'bunx cache'],
+];
+/**
+ * Where the running CLI came from, for the brief's first line, so a stale
+ * binary is visible in the session-start context. A package runner's cache is
+ * checked first: it also sits under node_modules/, and calling it a local
+ * install hid exactly the stale copy the label exists to show — npx reuses
+ * whatever version it cached until that cache is cleared.
+ */
+export function installLabel(scriptPath) {
+  const path = scriptPath ?? '';
+  for (const [pattern, label] of RUNNER_CACHES) if (pattern.test(path)) return label;
+  return /[\\/]node_modules[\\/]/.test(path) ? 'local install' : 'global';
+}
+
 /** One line the agent can act on. Names the mechanism, never just the verdict. */
 export function hintFor(r) {
   const defenders = r.defenders.resolved.join(', ');

package/src/cli.mjs

@@ -71,12 +71,13 @@ probe
                        unittest pin that choice and fail rather than fall back. The engine that ran is what the evidence records.)
   --runner-cmd "<cmd>" custom runner; must contain {files} and {out}, e.g. "pnpm vitest run {files} --reporter=json --outputFile={out}"
   --node-modules <dir> node_modules to link into the scratch worktree (or TESTGUARD_NODE_MODULES)
-  --python <path>      Python interpreter for .py defenders (or TESTGUARD_PYTHON; default: $VIRTUAL_ENV, then the project's
-                       .venv/venv, then python3 on PATH). Resolved against your working tree, never the scratch worktree.
+  --python <path>      Python interpreter for .py defenders (or TESTGUARD_PYTHON); a bare name is looked up on PATH.
+                       Default: $VIRTUAL_ENV, then the project's .venv, venv, .env, then python3, then python on PATH.
+                       Resolved against your working tree, never the scratch worktree.
   --workers <n>        maximum built-in runner workers (default: 1); Python remains serial
-  --serial             run one test file at a time (vitest --no-file-parallelism, jest --runInBand, playwright --workers=1,
-                       pytest -p no:xdist);
-                       use it when another test runner is already running — probe warns and records the contention either way
+  --serial             one worker, even when --workers is higher (vitest --no-file-parallelism, jest --runInBand,
+                       playwright --workers=1; pytest never loads xdist either way). The default --workers 1 is already
+                       serial, so it only changes a run that raised --workers; probe warns and records contention either way
   --in-place           mutate the working tree instead of a scratch worktree
   --no-escalate        do not re-run survivors against the whole suite
   --no-reuse           re-probe claims whose inputs have not changed
@@ -98,24 +99,32 @@ sweep      --changed <ref> (required unless --save-paths; CI bases and a safe lo
                              denominator: "120 writes across 38 files, swept 12". A clean sweep over an unstated
                              denominator is a sample of unknown size, not a guarantee that saving works
            --include-dirty  --exclude <glob>  --confirm <n>  --budget <ms>  --command-budget <ms>  --workers <n>  --serial  --max <n>  --out <path>  --json
+           --runner <name>  --runner-cmd "<cmd>"  --node-modules <dir>   runner selection, as for probe
+           --python <path>   Python interpreter for .py defenders (or TESTGUARD_PYTHON); a bare name is looked up on PATH
            the cold start: no claim and no concern needed. Everything it proposes is a DRAFT — it never writes testguard.claims.json,
            and its evidence never replaces .testguard/evidence.json. exit 1 on a fault that survived, or a file no test imports
            shapes: if-guard → if (false) · single-line guard/mutation removed · return <check> → return true
                    · security flag/window/cost literal weakened · verify/validate/check call removed
                    · field dropped from a payload/allow-list/schema/merge · parameter-derived argument swapped for undefined/{}
+                   · one-line JSX element removed · on<Event> handler prop dropped
 mcp        no options. JSON-RPC 2.0 over stdio; five READ-ONLY tools (status, brief, claims, evidence, next_command).
            Nothing here runs a probe: next_command hands back the shell line for you to run where the person can see it.
            Register it with your harness — testguard init --mcp prints the config for Claude Code, Cursor and Codex.
 replay     --workers <n> (default 1)  --serial  --budget <ms> (per run)
-           --since <range>   commit range to search for fix commits (HEAD~50..HEAD, a tag, origin/main..HEAD)
-           --max <n>         replay at most n fixes (they are slow: one worktree and N runs each)
+           --since <range>   commit range to search for fix commits (HEAD~50..HEAD, a tag, origin/main..HEAD);
+                             --changed <range> is accepted as an alias
+           --max <n>         replay at most n fixes (default 20; they are slow: one worktree and N runs each)
            --confirm <n>     runs per verdict (default 3); a flaky failure reads as "the suite caught it", so mixed runs are never caught
            --command-budget <ms> cooperative measurement deadline; expiry writes neither replay nor calibration, so an unmeasured suffix cannot look clean
            --out <path>       replay document (default: <dir>/.testguard/replay.json); the calibration goes beside it
+           --calibration-out <path>  write the calibration document here instead of beside the replay document
+           --runner <name>  --runner-cmd "<cmd>"  --node-modules <dir>   runner selection, as for probe
+           --python <path>   Python interpreter for .py defenders (or TESTGUARD_PYTHON); a bare name is looked up on PATH
            reports, never gates: a bug that escaped is history, not a regression in this change
-                   · one-line JSX element removed · on<Event> handler prop dropped
 admit      --workers <n> (default 1)  --serial  --budget <ms>  --command-budget <ms>
            --claim <ID> (required)  --fault <FID> (one fault only)  --confirm <n>  --json
+           --runner <name>  --runner-cmd "<cmd>"  --node-modules <dir>   runner selection, as for probe
+           --python <path>   Python interpreter for .py defenders (or TESTGUARD_PYTHON); a bare name is looked up on PATH
            ADMITTED (exit 0) only when every fault of the claim is killed N/N by defenders that are green N/N; anything else is NOT ADMITTED (exit 1) and names the first blocking fault
            the test must be a declared or discovered defender of the claim (exit 3 otherwise); evidence goes to .testguard/evidence-partial.json
 gate       --changed <ref>   measure the change since merge-base(ref, HEAD); auto-detected in GitHub Actions / GitLab CI
@@ -137,7 +146,7 @@ init       --force (replace an existing skill file)  --here (keep the agent laye
            agent layer (skill, SessionStart hook, AGENTS.md section) → git root; project layer (.gitignore lines) → [dir]
            the hook prefers a local install, then a testguard already on PATH, then nothing; it never reaches the network. exit 1 if a written file is gitignored
            --mcp             print the MCP server config for Claude Code, Cursor and Codex (printed, never written: a harness config is yours)
-every command accepts --json; probe/baseline emit the status document plus their own result
+every command except mcp accepts --json (mcp speaks JSON-RPC on stdio and refuses it); probe/baseline emit the status document plus their own result
 claims     --json
            --cost            what the last probe spent, per claim and per defender file, read back from the recorded run durations. Names the files more than one claim pays for, which is where a slow gate comes from
            --since <ref>     report every claim and fault that existed at <ref> and does not now; a claim entry in testguard.ignore.json (with a reason) excuses one. exit 1 on any unexcused removal
@@ -169,7 +178,9 @@ export function commandUsage(command) {
     scaffold: 'scaffold src/example.mjs --json', replay: 'replay . --since HEAD~10..HEAD --max 3',
     admit: 'admit test/example.test.mjs --claim EXAMPLE-001', sweep: 'sweep . --changed origin/main --cap 10',
   };
-  return `${lines[0]}\n\n${overview}\n\n${sections.join('\n').trim()}\n\nCommon: --json, --help, --version\nExample: testguard ${examples[command] ?? `${command}${command === 'mcp' ? '' : ' .'}`}\n`;
+  // mcp refuses --json (stdout is its protocol stream), so its help does not offer it.
+  const common = command === 'mcp' ? '--help, --version' : '--json, --help, --version';
+  return `${lines[0]}\n\n${overview}\n\n${sections.join('\n').trim()}\n\nCommon: ${common}\nExample: testguard ${examples[command] ?? `${command}${command === 'mcp' ? '' : ' .'}`}\n`;
 }
 
 export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n'), err: (s) => process.stderr.write(s + '\n') }) {
@@ -190,6 +201,7 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
         out: { type: 'string' },
         evidence: { type: 'string' },
         baseline: { type: 'string' },
+        'calibration-out': { type: 'string' },
         severity: { type: 'string', default: 'low' },
         max: { type: 'string', default: '20' },
         ref: { type: 'string' },
@@ -263,6 +275,18 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
     io.out(commandUsage(command));
     return 0;
   }
+  // replay once took --baseline as the calibration output path, undocumented,
+  // sharing probe's flag for "the baseline to gate against". Refused rather
+  // than ignored: a silently dropped path would write the calibration where
+  // the caller did not ask.
+  if (command === 'replay' && values.baseline !== undefined) {
+    io.err('replay has no --baseline: a baseline gates probe findings, and replay never gates. To choose where the calibration is written, use --calibration-out <path>.');
+    return 3;
+  }
+  if (values['calibration-out'] !== undefined && command !== 'replay') {
+    io.err('--calibration-out is only valid on replay');
+    return 3;
+  }
   if ((values.annotate || values.apply) && command !== 'claims') {
     io.err('--annotate and --apply are only valid on claims');
     return 3;

package/src/commands/admit.mjs

@@ -11,6 +11,7 @@ import { PreconditionError } from '../probe/worktree.mjs';
 import { hintFor } from '../brief/brief.mjs';
 import { formatVerdict, PROVISIONAL_WARNING } from '../render.mjs';
 import { decideAdmission } from '../admit/admit.mjs';
+import { runnerOptions } from './runner-options.mjs';
 
 /** The project is wherever the claims file is, walking up from the test file; else cwd. */
 function findProjectDir(testAbs, claimsFlag) {
@@ -44,6 +45,11 @@ export async function admitCommand({ file, values, version }, io) {
     io.err('--claim must name one claim id');
     return 3;
   }
+  const runner = runnerOptions(values);
+  if (runner.error) {
+    io.err(runner.error);
+    return 3;
+  }
   const confirmRuns = Number(values.confirm);
   const budgetMs = Number(values.budget);
   const commandBudgetMs = parseCommandBudget(values['command-budget']);
@@ -100,9 +106,10 @@ export async function admitCommand({ file, values, version }, io) {
     includeDirty: true,
     only: [claimId],
     escalate: false,
-    runnerCommand: values['runner-cmd'],
+    runnerCommand: runner.runnerCommand,
     runnerName: values.runner,
     nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
+    python: runner.python,
     toolVersion: version,
     onStage: !values.quiet && !values.json && process.stderr.isTTY ? ({ claimId: c, faultId, stage, i, n }) => process.stderr.write(`\r\x1b[K  … ${c}/${faultId} ${stage} ${i}/${n}`) : undefined,
   });

package/src/commands/baseline.mjs

@@ -4,6 +4,7 @@ import { readSpecDoc, writeSpecDoc } from '../evidence/writer.mjs';
 import { buildBaseline, restampBaseline } from '../baseline/baseline.mjs';
 import { evidencePath, baselinePath } from './probe.mjs';
 import { computeStatus } from '../status/status.mjs';
+import { validate } from '../../spec/lib/validate.mjs';
 import { isGitIgnored, GITIGNORE_LINES, COMMITTED_OUTPUTS } from '../init/init.mjs';
 
 /**
@@ -20,6 +21,19 @@ function unignoredOutputs(projectDir) {
   return GITIGNORE_LINES.filter((l) => !isGitIgnored(projectDir, l.replace('*', 'x')));
 }
 
+/**
+ * The status document plus what this invocation wrote, validated before it is
+ * printed — the same contract `probe --json` keeps for its `run`. A JSON mode
+ * whose output its own schema refuses is a parser failure handed to every
+ * integration that trusted the exit code.
+ */
+function statusWith(projectDir, version, baseline) {
+  const doc = { ...computeStatus({ projectDir, toolVersion: version }), baseline };
+  const result = validate('status', doc);
+  if (!result.ok) throw new Error(`baseline JSON document does not conform: ${result.errors.map((e) => `${e.path}: ${e.message}`).join('; ')}`);
+  return JSON.stringify(doc, null, 2);
+}
+
 export async function baselineCommand({ projectDir, values, version }, io) {
   const evPath = values.evidence ? resolve(values.evidence) : evidencePath(projectDir);
   if (!existsSync(evPath)) {
@@ -43,14 +57,14 @@ export async function baselineCommand({ projectDir, values, version }, io) {
       return 2;
     }
     writeSpecDoc('baseline', outPath, r.baseline);
-    io.out(values.json ? JSON.stringify({ ...computeStatus({ projectDir, toolVersion: version }), baseline: { path: outPath, restamped: r.baseline.head } }, null, 2) : `baseline: re-stamped to ${r.baseline.head.slice(0, 12)} (same fingerprints, clean tree) → ${outPath}`);
+    io.out(values.json ? statusWith(projectDir, version, { path: outPath, restamped: r.baseline.head }) : `baseline: re-stamped to ${r.baseline.head.slice(0, 12)} (same fingerprints, clean tree) → ${outPath}`);
     return 0;
   }
   const baseline = buildBaseline(evidence);
   writeSpecDoc('baseline', outPath, baseline);
   const n = Object.values(baseline.fingerprints).reduce((a, b) => a + b, 0);
   if (values.json) {
-    io.out(JSON.stringify({ ...computeStatus({ projectDir, toolVersion: version }), baseline: { path: outPath, frozen: n } }, null, 2));
+    io.out(statusWith(projectDir, version, { path: outPath, frozen: n }));
     return 0;
   }
   io.out(`baseline: ${n} unproven finding${n === 1 ? '' : 's'} frozen at ${baseline.head.slice(0, 12)}${baseline.snapshot ? ` (working-tree snapshot ${baseline.snapshot.slice(0, 7)}; after you commit, a clean probe + \`baseline --restamp\` moves head to that commit)` : baseline.dirty ? ' (working tree was dirty)' : ''}${evidence.run.provisional ? ' — FROM PROVISIONAL EVIDENCE (--allow-provisional)' : ''} → ${outPath}`);

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, renderBriefMarkdown, renderUnclaimedMarkdown } from '../brief/brief.mjs';
+import { buildBrief, buildUnclaimedBrief, renderBriefMarkdown, renderUnclaimedMarkdown, installLabel } from '../brief/brief.mjs';
 import { computeStatus } from '../status/status.mjs';
 import { evidencePath, baselinePath } from './probe.mjs';
 import { resolveChangedRef, withChangedRef } from '../gate/changed.mjs';
@@ -39,7 +39,7 @@ export async function briefCommand({ projectDir, values, version }, io) {
     return 3;
   }
   // 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 install = installLabel(process.argv[1]);
   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());

package/src/commands/claims.mjs

@@ -41,7 +41,7 @@ export async function claimsCommand({ projectDir, values, suppliedOptions, versi
   const drift = reconcile(claims, annotations);
   const advisory = annotationAdvisory(claims, annotations, { customClaims: Boolean(values.claims) });
   const anchorChecks = values['check-anchors']
-    ? await checkAnchors(projectDir, claims, { python: values.python ? resolve(values.python) : undefined })
+    ? await checkAnchors(projectDir, claims, { python: values.python || undefined }) // a bare name is a PATH lookup; see explicitInterpreter
     : undefined;
 
   // A claim that disappeared is invisible to every other command; compare

package/src/commands/concerns.mjs

@@ -1,6 +1,5 @@
 import { resolve } from 'node:path';
 import { loadConcerns, renderConcerns } from '../supply/concerns.mjs';
-import { validate } from '../../spec/lib/validate.mjs';
 
 /**
  * `testguard concerns [dir]`: the one-sentence scopes a sweep can be aimed by.
@@ -13,16 +12,9 @@ import { validate } from '../../spec/lib/validate.mjs';
  */
 export async function concernsCommand({ projectDir, values, version }, io) {
   const path = values.concerns ? resolve(values.concerns) : undefined;
+  // A file that does not parse or does not conform throws a SpecDocError
+  // naming it, which the CLI reports as exit 2: wrong with the FILE.
   const loaded = loadConcerns(projectDir, { path });
-
-  if (loaded.source) {
-    const result = validate('concerns', { schemaVersion: 1, concerns: loaded.raw });
-    if (!result.ok) {
-      io.err(`${loaded.source} does not conform to the spec:`);
-      for (const e of result.errors) io.err(`  ${e.path}: ${e.message}`);
-      return 2;
-    }
-  }
   if (values.json) {
     io.out(JSON.stringify({ schemaVersion: 1, tool: { name: 'testguard', version }, source: loaded.source, shadowed: loaded.shadowed, concerns: loaded.concerns }, null, 2));
   } else {

package/src/commands/gate.mjs

@@ -1,5 +1,5 @@
 import { join, resolve } from 'node:path';
-import { computeChangedGate, resolveChangedRef, renderGate, DEFAULT_EXCLUDES } from '../gate/changed.mjs';
+import { computeChangedGate, resolveChangedRef, renderGate, explainExclusions } from '../gate/changed.mjs';
 import { writeSpecDoc } from '../evidence/writer.mjs';
 
 export const gatePath = (projectDir) => join(projectDir, '.testguard', 'gate.json');
@@ -11,9 +11,7 @@ export const gatePath = (projectDir) => join(projectDir, '.testguard', 'gate.jso
  */
 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.');
+    for (const line of explainExclusions()) io.out(line);
     return 0;
   }
   const resolved = resolveChangedRef({ explicit: values.changed, projectDir });

package/src/commands/init.mjs

@@ -1,7 +1,17 @@
-import { initProject } from '../init/init.mjs';
+import { initProject, InitUsageError } from '../init/init.mjs';
 
 export async function initCommand({ projectDir, values }, io) {
-  const r = initProject({ projectDir, force: values.force, here: values.here, ciEvidence: values['ci-evidence'], mcp: values.mcp });
+  let r;
+  try {
+    r = initProject({ projectDir, force: values.force, here: values.here, ciEvidence: values['ci-evidence'], mcp: values.mcp });
+  } catch (e) {
+    // A bad option is the caller's to fix, and init has written nothing yet:
+    // every option is checked before the first write.
+    if (!(e instanceof InitUsageError)) throw e;
+    io.err(e.message);
+    io.err("Run 'testguard init --help' for its options. Nothing was written.");
+    return 3;
+  }
   const { done, skipped, warnings, agentRoot, dir, mcpConfig } = r;
   if (values.json) {
     io.out(JSON.stringify({ done, skipped, warnings, agentRoot, dir, ...(mcpConfig ? { mcpConfig } : {}) }, null, 2));