testguard-cli 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-17
+
+The change gate: unclaimed code is now a finding.
+
+### Added
+
+- **`testguard gate --changed <ref>`** — the change gate. Every escaped
+  defect in the field reports was a *claim gap*: the feature shipped green
+  with zero claims, and `probe` is silent about unclaimed code by
+  construction. `gate` measures the files changed since
+  `merge-base(ref, HEAD)` (or in the working tree with `--include-dirty`)
+  and exits `1` when any changed source file carries no fault, does not
+  resolve as a defender (test files), and is not excused by an unexpired
+  `path` entry in `testguard.ignore.json`. Every reliance on an ignore entry
+  is printed with its reason; expired entries excuse nothing. Non-source
+  files and documented never-claimed patterns are excluded and listed
+  (`--explain`, `--exclude <glob>`); `--strict` fails a change that
+  evaluated nothing. The base branch is detected in GitHub Actions and
+  GitLab CI (`TESTGUARD_CHANGED_REF` overrides). A new spec kind,
+  `gate.schema.json`, with conformance examples.
+- **`status --changed <ref>`** — a new state `unclaimed-changes` and action
+  `claim` that precede every evidence state; `next.file` names the first
+  unclaimed file. `brief` renders unclaimed files before the findings, and
+  briefs them even when there is no evidence yet.
+- `testguard.ignore.json` at the repository root: TestGuard's own excused
+  paths (dispatch, thin command wrappers, rendering), with reasons.
+- Nine new self-claims: the gate, status and brief invariants, explicit
+  `--changed` being required, `init` idempotency, and — because the gate
+  flagged it on its own pull request — the release version-sync check,
+  which had no test before. The gate runs on this repository's own pull
+  requests.
+- GitHub Action `command: gate` with a `changed-ref` input; pre-commit hook
+  `testguard-gate`; a GitLab CI template under `packaging/gitlab/` with
+  `testguard:gate` (merge request pipelines, measured against
+  `CI_MERGE_REQUEST_DIFF_BASE_SHA`) and `testguard:probe`.
+
+## [0.4.0] - 2026-09-17
+
+### Added
+
+- **jest runner.** `--runner vitest|jest|auto` (default `auto`: the first
+  that resolves in the project). jest runs with `--ci --json --runTestsByPath`
+  so file arguments are exact paths, not regexes; its `Exceeded timeout`
+  wording is recognised as a timeout, never a kill; `__tests__/` files are
+  collected for escalation. `run.runner.name` records which runner produced
+  the evidence.
+- A CommonJS edition of the known-answer fixture (`fixtures/known-answer-jest`)
+  with the same claims and the same expected verdicts; the acceptance suite
+  and CI prove jest against it exactly as vitest is proven against the ESM
+  one.
+
+### Changed
+
+- Runners are now modules behind one interface (`src/probe/runners/`); the
+  vitest path is unchanged and still reproduces its oracle.
+
 ## [0.3.1] - 2026-09-17
 
 Dogfooding `init` and `status` on this repository.

package/README.md

@@ -52,7 +52,7 @@ tests were written against the survivors, 39/39 were killed.
 | npm | `npm i -D testguard-cli` then `npx testguard probe` |
 | pip | `pip install testguard-cli` then `testguard probe` (needs Node ≥ 20) |
 | Homebrew | `brew tap raccioly/tap && brew install testguard` |
-| GitHub Action | `uses: raccioly/testguard@v0.3.1` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.5.0` — see [`action.yml`](./action.yml) |
 | pre-commit | `repo: https://github.com/raccioly/testguard`, hooks `testguard-claims`, `testguard-probe` |
 
 Projects that set `min-release-age` in `.npmrc` cannot see a version published
@@ -68,6 +68,7 @@ npx testguard-cli claims      # what does this project claim, and is every claim
 npx testguard-cli probe       # try to falsify each claim; report what the tests missed
 npx testguard-cli baseline    # freeze today's unproven findings; from now on only new ones gate
 npx testguard-cli brief       # tell the agent where the suite is blind, before it writes
+npx testguard-cli gate --changed origin/main   # fail when a changed source file carries no claim at all
 npx testguard-cli scaffold src/x.ts   # propose faults for a file, as a draft to keep or drop
 ```
 
@@ -111,6 +112,11 @@ npx testguard-cli scaffold src/x.ts   # propose faults for a file, as a draft to
    files that import the fault's target, by relative path or resolved alias.
    `NOCOVER` then means exactly "no test file imports this source".
 
+   Runners: **vitest** and **jest** (`--runner auto` picks the first that
+   resolves; both read the same jest-compatible JSON report). Anything else
+   goes through `--runner-cmd`. Each runner is proven against its own copy
+   of the known-answer fixture.
+
    Practical loop: first pass `--no-escalate` (escalation re-runs the whole
    suite N times per survivor); iterate on one claim with `--claim <ID>` and
    either `--include-dirty` or `--in-place` (only fault target files must be
@@ -141,6 +147,54 @@ npx testguard-cli scaffold src/x.ts   # propose faults for a file, as a draft to
    `--text` prints only, and exits 0 silently when there is no evidence yet,
    so the hook can never break a session.
 
+### Every change needs a claim
+
+`probe` can only verify claims that exist. Every escaped defect in the field
+reports so far was a **claim gap**: the feature shipped green with zero
+claims, and a verifier with no claim about a feature is silent about it by
+construction. `gate` closes that hole on the delta:
+
+```bash
+npx testguard-cli gate --changed origin/main            # in a PR: the files changed since the base branch
+npx testguard-cli gate --changed HEAD --include-dirty   # before a commit: the working tree, staged or not
+```
+
+Every changed source file must carry a fault, resolve as a defender of a
+claim (test files), or be excused by an unexpired `path` entry in
+`testguard.ignore.json` — with a reason a reviewer will accept. One
+unclaimed file exits `1`; there is no percentage. Every reliance on an ignore
+entry is printed, so a reviewer sees *why* the gate passed; an expired entry
+excuses nothing. Non-source files and documented never-claimed patterns
+(`*.d.ts`, `*.config.*`, fixtures, mocks; `--explain` lists them) are
+excluded and said so; `--strict` fails a change that evaluated nothing.
+
+With a reference known, `status --changed <ref>` reports `unclaimed-changes`
+**before** any evidence state and makes the claim the next action; the brief
+lists the unclaimed files first. The claim is written before more code.
+
+**In CI the base is detected** — GitHub Actions (`GITHUB_BASE_REF`) and GitLab
+merge request pipelines (`CI_MERGE_REQUEST_DIFF_BASE_SHA`, then
+`CI_MERGE_REQUEST_TARGET_BRANCH_NAME`); `TESTGUARD_CHANGED_REF` overrides both.
+The base must exist locally: GitHub — `actions/checkout` with `fetch-depth: 0`;
+GitLab — the diff base sha needs nothing extra on a merge request pipeline,
+the branch name needs `GIT_DEPTH: 0` or a `git fetch origin <target>`. A
+detected base that does not resolve is a warning for `status` and `brief`
+(they keep working) and an error for `gate` (its whole job is the measurement).
+
+```yaml
+# GitHub Actions
+- uses: actions/checkout@v4
+  with: { fetch-depth: 0 }
+- uses: raccioly/testguard@v0.5.0
+  with: { command: gate }
+
+# GitLab CI — or include: remote: the template in packaging/gitlab/
+testguard:gate:
+  image: node:22
+  rules: [{ if: $CI_PIPELINE_SOURCE == "merge_request_event" }]
+  script: [npx -y testguard-cli gate .]
+```
+
 ### Built for agents to run
 
 TestGuard is meant to be driven by an AI agent, not typed by a person. Three
@@ -215,14 +269,15 @@ through every verdict.
 
 ## Status
 
-**v0.3.** Seven commands, vitest runner, hand-authored faults plus a
-mechanical scaffold, and an agent operating layer (`status`, `init`). The contract
-spine — six JSON Schemas shared with the other Guard tools — is under
+**v0.4.** Eight commands, vitest and jest runners, hand-authored faults plus
+a mechanical scaffold, an agent operating layer (`status`, `init`) and a
+change gate (`gate`). The contract
+spine — eight JSON Schemas shared with the other Guard tools — is under
 [`spec/`](spec/). One exact-pinned runtime dependency (`ajv`, for schema validation); Node ≥ 20.
 
-Not yet: test generation (the two-gate acceptance loop), other runners,
-AST-aware producers, and calibration of fault classes against real escaped
-bugs. Each is designed for; none is claimed.
+Not yet: test generation (the two-gate acceptance loop), runners beyond
+vitest and jest, AST-aware producers, and calibration of fault classes
+against real escaped bugs. Each is designed for; none is claimed.
 
 ## Licence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Proves a test suite defends the claims a project makes: injects the faults those claims forbid and reports every one the tests fail to detect.",
   "type": "module",
   "license": "MIT",
@@ -46,6 +46,7 @@
     "quality-gate"
   ],
   "devDependencies": {
+    "jest": "^30.5.1",
     "vitest": "^5.0.1"
   },
   "bin": {

package/spec/GATE-SEMANTICS.md

@@ -85,6 +85,57 @@ the suppress-up-to-count semantics are identical.
 - An annotation is **strictly additive**. It never changes, suppresses, or
   drops a finding. Ranking may read annotations; verdicts never do.
 
+## Claim coverage of a change
+
+`probe` asks whether the tests defend the claims that exist. It says nothing
+about code that has no claim, by construction — and every escaped defect the
+field reports share was a *claim gap*, not a defender gap: the feature shipped
+green with zero claims. A repository with ten old claims and one new,
+unclaimed module exits 0 under `probe` forever.
+
+The change gate closes that hole. Given a reference, a tool measures the
+**delta** — the files changed since `merge-base(ref, HEAD)`, or since that
+merge-base in the working tree — file by file:
+
+- A changed file is **excluded** when it is not source (by extension) or
+  matches a documented never-claimed pattern (`*.d.ts`, `*.config.*`,
+  fixtures, mocks, snapshots, the tool's own directory). Exclusions are
+  listed, never silent.
+- A changed source file is **covered** when at least one fault anchors to it,
+  when it is a test file that resolves as a defender of some claim, or when an
+  **unexpired** `path` ignore entry excuses it.
+- Anything else is **uncovered**. 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.
+
+Rules:
+
+1. **One uncovered file gates.** Exit `1`. There is no threshold and no
+   percentage; a percentage is how the gap hid before.
+2. **Every reliance on an ignore entry is reported.** The gate may pass
+   *because of* an excuse; a reviewer reads which entries carried it, with
+   their reasons and expiry. An expired entry excuses nothing and is reported
+   as expired.
+3. **A test file needs a claim too.** A test that defends no claim is the
+   authorship trap the pattern exists for; it is uncovered until a claim
+   names it in `defendedBy` (or discovery resolves it as a defender).
+4. **Never a silent pass on nothing.** A non-empty change whose files were
+   all excluded passes with an explicit "0 evaluated" line; a tool offers a
+   strict mode that fails it instead. An empty change is an honest `0`.
+5. **The reference is never guessed.** An explicit flag, or a CI-provided base
+   branch, or an error. An upstream that already contains the change has an
+   empty diff and would pass trivially.
+6. **Unclaimed changes precede every evidence state.** When the status
+   document knows a reference and finds uncovered files, its state is
+   `unclaimed-changes` and its next action is to write the claim, before any
+   `unproven` finding is surfaced. The brief renders them first. The claim is
+   written before more code.
+
+Exit codes: `0` every changed source file is claimed or excused (or nothing
+changed); `1` at least one uncovered file (or strict mode over an
+all-excluded change); `2` the change cannot be evaluated (unresolvable
+reference, invalid claims or ignore file, no repository); `3` no reference.
+
 ## Severity floor
 
 `--severity <level>` gates only findings whose claim severity is at or above

package/spec/README.md

@@ -1,6 +1,6 @@
 # Guard spec — the contract spine
 
-Six formats that tools following the Guard pattern share. They share
+Eight formats that tools following the Guard pattern share. They share
 *formats*, not code: [`docguard-cli`](https://www.npmjs.com/package/docguard-cli)
 is Node ESM, [`websec-validator`](https://pypi.org/project/websec-validator/)
 is Python, and porting one runtime into the other is not worth it. A tool
@@ -21,7 +21,8 @@ The pattern all such tools run:
 | `ignore` | [`schemas/ignore.schema.json`](schemas/ignore.schema.json) | Reviewable scoping. Every entry has a reason. |
 | `calibration` | [`schemas/calibration.schema.json`](schemas/calibration.schema.json) | P(finding is real) per bucket, with a Wilson interval and the sample size behind it. |
 | `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. |
+| `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. |
+| `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. |
 
 Shared definitions (verdicts, fault classes, provenance, annotations) live in
 [`schemas/common.schema.json`](schemas/common.schema.json). Gate behaviour —

package/spec/lib/validate.mjs

@@ -6,7 +6,7 @@ import { fingerprint } from './fingerprint.mjs';
 
 const schemaDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'schemas');
 
-export const KINDS = Object.freeze(['claims', 'evidence', 'baseline', 'ignore', 'calibration', 'brief', 'status']);
+export const KINDS = Object.freeze(['claims', 'evidence', 'baseline', 'ignore', 'calibration', 'brief', 'status', 'gate']);
 export const PASSING_VERDICTS = Object.freeze(new Set(['killed']));
 
 const ajv = new Ajv2020({ strict: true, allErrors: true });
@@ -99,8 +99,26 @@ const semantic = {
   status(doc) {
     const errors = [];
     if (['write-test', 'review-fault-change'].includes(doc.next.action) && !doc.next.target) errors.push({ path: '/next/target', message: `${doc.next.action} requires a target` });
+    if (doc.next.action === 'claim' && !doc.next.file) errors.push({ path: '/next/file', message: 'claim requires the file the claim is about' });
     if (doc.state === 'no-claims' && doc.counts.claims !== 0) errors.push({ path: '/counts/claims', message: 'no-claims with a non-zero claim count' });
     if (doc.state === 'clean' && (doc.counts.new ?? 0) > 0) errors.push({ path: '/state', message: 'clean with new findings' });
+    if (doc.state === 'unclaimed-changes' && !(doc.changes && doc.changes.uncovered.length > 0)) errors.push({ path: '/changes/uncovered', message: 'unclaimed-changes requires at least one uncovered changed file' });
+    if (doc.state === 'unclaimed-changes' && doc.next.action !== 'claim') errors.push({ path: '/next/action', message: 'unclaimed-changes requires next.action = claim' });
+    if (doc.changes && doc.changes.uncovered.length > 0 && !['no-claims', 'unclaimed-changes'].includes(doc.state)) errors.push({ path: '/state', message: 'uncovered changed files are hidden behind a later state; unclaimed-changes precedes every evidence state' });
+    return errors;
+  },
+
+  gate(doc) {
+    const errors = [];
+    if (doc.evaluated !== doc.covered.length + doc.uncovered.length) errors.push({ path: '/evaluated', message: `evaluated (${doc.evaluated}) must equal covered (${doc.covered.length}) + uncovered (${doc.uncovered.length})` });
+    if (doc.changed !== doc.evaluated + doc.excluded.length) errors.push({ path: '/changed', message: `changed (${doc.changed}) must equal evaluated (${doc.evaluated}) + excluded (${doc.excluded.length})` });
+    if (doc.uncovered.length > 0 && doc.exitCode !== 1) errors.push({ path: '/exitCode', message: 'an uncovered changed file must exit 1; the gate never passes over unclaimed code' });
+    if (doc.uncovered.length === 0 && doc.exitCode === 1 && !(doc.strict && doc.changed > 0 && doc.evaluated === 0)) errors.push({ path: '/exitCode', message: 'exit 1 without uncovered files is only valid under --strict when a non-empty change evaluated nothing' });
+    doc.covered.forEach((c, i) => {
+      if (c.by === 'ignore' && !c.pattern) errors.push({ path: `/covered/${i}/pattern`, message: 'a file covered by an ignore entry must name the pattern that excused it' });
+      if (c.by !== 'ignore' && !c.claimIds?.length) errors.push({ path: `/covered/${i}/claimIds`, message: `a file covered by a ${c.by} must name the claim(s)` });
+    });
+    for (const e of doc.expired) if (!e.expires) errors.push({ path: '/expired', message: `expired entry "${e.pattern}" has no expires instant` });
     return errors;
   },
 

package/spec/schemas/brief.schema.json

@@ -39,12 +39,22 @@
       "type": "object",
       "required": ["action", "command", "why"],
       "properties": {
-        "action": { "enum": ["scaffold", "probe", "write-test", "baseline", "review-fault-change", "none"] },
+        "action": { "enum": ["scaffold", "claim", "probe", "write-test", "baseline", "review-fault-change", "none"] },
         "command": { "type": "string", "minLength": 1, "maxLength": 1024 },
         "why": { "type": "string", "minLength": 1, "maxLength": 2000 }
       },
       "additionalProperties": false
     },
+    "unclaimed": {
+      "description": "Changed files that carry no claim, when the brief was built with a change reference. Rendered before the findings: an agent writes the claim before more code.",
+      "type": "object",
+      "required": ["ref", "files"],
+      "properties": {
+        "ref": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "files": { "type": "array", "minItems": 1, "items": { "$ref": "urn:guard-spec:v1:common#/$defs/uncoveredFile" } }
+      },
+      "additionalProperties": false
+    },
     "items": {
       "type": "array",
       "maxItems": 50,

package/spec/schemas/common.schema.json

@@ -77,6 +77,33 @@
       },
       "additionalProperties": false
     },
+    "uncoveredFile": {
+      "description": "A changed source or test file that no claim covers and no unexpired ignore entry excuses. Shared by the gate and status documents.",
+      "type": "object",
+      "required": ["file", "kind", "suggestion"],
+      "properties": {
+        "file": { "$ref": "#/$defs/repoPath" },
+        "kind": { "enum": ["source", "test"] },
+        "nearestClaimId": {
+          "description": "The claim whose fault files share the longest directory prefix with this file — where to attach, not a verdict.",
+          "$ref": "#/$defs/identifier"
+        },
+        "suggestion": { "type": "string", "minLength": 1, "maxLength": 1024 }
+      },
+      "additionalProperties": false
+    },
+    "ignoreReliance": {
+      "description": "An ignore entry the gate relied on (or would have, had it not expired), with the changed files it matched.",
+      "type": "object",
+      "required": ["pattern", "reason", "files"],
+      "properties": {
+        "pattern": { "type": "string", "minLength": 1, "maxLength": 512 },
+        "reason": { "type": "string", "minLength": 8, "maxLength": 2000 },
+        "expires": { "$ref": "#/$defs/isoDateTime" },
+        "files": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/repoPath" } }
+      },
+      "additionalProperties": false
+    },
     "annotation": {
       "description": "Strictly additive. An annotation never changes, suppresses, or drops a finding; it only attaches context to it.",
       "type": "object",

package/spec/schemas/gate.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:guard-spec:v1:gate",
+  "title": "Guard spec v1 — change gate",
+  "description": "Claim coverage of one change. `probe` asks whether the tests defend the claims that exist; `gate` asks whether the files a change touched carry any claim at all. Measured per file against the merge-base of a reference and HEAD (or the working tree). A file is covered when a fault anchors to it, when it is a test file that defends a claim, or when an unexpired ignore entry excuses it — and every reliance on an ignore entry is listed, so a reviewer sees why the gate passed.",
+  "type": "object",
+  "required": ["schemaVersion", "tool", "generatedAt", "ref", "base", "head", "includeDirty", "strict", "changed", "evaluated", "excluded", "covered", "uncovered", "reliedOn", "expired", "exitCode"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "tool": { "$ref": "urn:guard-spec:v1:common#/$defs/tool" },
+    "generatedAt": { "$ref": "urn:guard-spec:v1:common#/$defs/isoDateTime" },
+    "ref": { "description": "The reference the change was measured against, as given (a branch, a tag, a sha).", "type": "string", "minLength": 1, "maxLength": 256 },
+    "base": { "description": "merge-base(ref, HEAD): the commit the change is relative to.", "$ref": "urn:guard-spec:v1:common#/$defs/gitSha" },
+    "head": { "$ref": "urn:guard-spec:v1:common#/$defs/gitSha" },
+    "includeDirty": { "description": "True when the working tree was compared instead of HEAD.", "type": "boolean" },
+    "strict": { "description": "True when a non-empty change with zero evaluated files fails instead of passing with a note.", "type": "boolean" },
+    "changed": { "description": "Files changed inside the project directory, deletions excluded.", "type": "integer", "minimum": 0 },
+    "evaluated": { "description": "covered + uncovered: the changed files that are source and not excluded.", "type": "integer", "minimum": 0 },
+    "excluded": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["file", "by"],
+        "properties": {
+          "file": { "$ref": "urn:guard-spec:v1:common#/$defs/repoPath" },
+          "by": { "description": "`non-source`, `default:<glob>` or `exclude:<glob>`.", "type": "string", "minLength": 1, "maxLength": 600 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "covered": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["file", "by"],
+        "properties": {
+          "file": { "$ref": "urn:guard-spec:v1:common#/$defs/repoPath" },
+          "by": { "enum": ["fault", "defender", "ignore"] },
+          "claimIds": { "type": "array", "minItems": 1, "items": { "$ref": "urn:guard-spec:v1:common#/$defs/identifier" } },
+          "pattern": { "type": "string", "minLength": 1, "maxLength": 512 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "uncovered": { "type": "array", "items": { "$ref": "urn:guard-spec:v1:common#/$defs/uncoveredFile" } },
+    "reliedOn": { "description": "Unexpired ignore entries that excused at least one changed file. The gate passed *because of* these; a reviewer reads them.", "type": "array", "items": { "$ref": "urn:guard-spec:v1:common#/$defs/ignoreReliance" } },
+    "expired": { "description": "Expired ignore entries that would have matched a changed file. They excuse nothing; the files are reported as uncovered.", "type": "array", "items": { "$ref": "urn:guard-spec:v1:common#/$defs/ignoreReliance" } },
+    "exitCode": { "enum": [0, 1] }
+  },
+  "additionalProperties": false
+}

package/spec/schemas/status.schema.json

@@ -11,17 +11,21 @@
     "tool": { "$ref": "urn:guard-spec:v1:common#/$defs/tool" },
     "generatedAt": { "$ref": "urn:guard-spec:v1:common#/$defs/isoDateTime" },
     "state": {
-      "description": "no-claims: no claims file. unprobed: claims but no confirmed evidence. evidence-stale: evidence exists but a claim, fault, target or defender changed since. provisional-only: only sub-N evidence exists. unproven: current evidence has findings not covered by the baseline. clean: every finding is killed or baselined.",
-      "enum": ["no-claims", "unprobed", "evidence-stale", "provisional-only", "unproven", "clean"]
+      "description": "no-claims: no claims file. unclaimed-changes: the change measured against a reference touches source files that carry no claim and no excusing ignore entry (only computed when a reference is known; it precedes every evidence state because the claim is written before more code). unprobed: claims but no confirmed evidence. evidence-stale: evidence exists but a claim, fault, target or defender changed since. provisional-only: only sub-N evidence exists. unproven: current evidence has findings not covered by the baseline. clean: every finding is killed or baselined.",
+      "enum": ["no-claims", "unclaimed-changes", "unprobed", "evidence-stale", "provisional-only", "unproven", "clean"]
     },
     "next": {
-      "description": "The one action that moves the project forward. `command` is a shell line when the action is a tool command, or an instruction when it is not (write-test).",
+      "description": "The one action that moves the project forward. `command` is a shell line when the action is a tool command, or an instruction when it is not (write-test, claim for a test file).",
       "type": "object",
       "required": ["action", "command", "why"],
       "properties": {
-        "action": { "enum": ["scaffold", "probe", "write-test", "baseline", "review-fault-change", "none"] },
+        "action": { "enum": ["scaffold", "claim", "probe", "write-test", "baseline", "review-fault-change", "none"] },
         "command": { "type": "string", "minLength": 1, "maxLength": 1024 },
         "why": { "type": "string", "minLength": 1, "maxLength": 2000 },
+        "file": {
+          "description": "For claim (and for scaffold when a change is known): the first uncovered changed file the action is about.",
+          "$ref": "urn:guard-spec:v1:common#/$defs/repoPath"
+        },
         "target": {
           "description": "For write-test / review-fault-change: the finding the action is about.",
           "type": "object",
@@ -95,10 +99,28 @@
         "additionalProperties": false
       }
     },
+    "changes": {
+      "description": "Claim coverage of the change since `ref`, present only when a reference was given (--changed) or detected from CI. Uncovered files come first in every rendering: the claim is written before more code. Same per-file shapes as the gate document.",
+      "type": "object",
+      "required": ["ref", "base", "changed", "evaluated", "excluded", "uncovered", "reliedOn", "expired"],
+      "properties": {
+        "ref": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "base": { "$ref": "urn:guard-spec:v1:common#/$defs/gitSha" },
+        "includeDirty": { "type": "boolean" },
+        "changed": { "type": "integer", "minimum": 0 },
+        "evaluated": { "type": "integer", "minimum": 0 },
+        "excluded": { "type": "integer", "minimum": 0 },
+        "uncovered": { "type": "array", "items": { "$ref": "urn:guard-spec:v1:common#/$defs/uncoveredFile" } },
+        "reliedOn": { "type": "array", "items": { "$ref": "urn:guard-spec:v1:common#/$defs/ignoreReliance" } },
+        "expired": { "type": "array", "items": { "$ref": "urn:guard-spec:v1:common#/$defs/ignoreReliance" } }
+      },
+      "additionalProperties": false
+    },
     "paths": {
       "type": "object",
       "properties": {
         "claims": { "type": "string" },
+        "ignore": { "type": "string" },
         "evidence": { "type": "string" },
         "provisionalEvidence": { "type": "string" },
         "baseline": { "type": "string" }

package/src/brief/brief.mjs

@@ -31,7 +31,7 @@ function orderItems(a, b) {
   return (b.isNew - a.isNew) || (ORDER.indexOf(a.verdict) - ORDER.indexOf(b.verdict)) || ((b.rank ?? 0) - (a.rank ?? 0));
 }
 
-export function buildBrief(evidence, baseline, { max = 20, generatedAt = new Date().toISOString(), next } = {}) {
+export function buildBrief(evidence, baseline, { max = 20, generatedAt = new Date().toISOString(), next, changes } = {}) {
   const g = gate(evidence.records, baseline);
   const toItem = (r, isNew) => ({
     fingerprint: r.fingerprint,
@@ -54,7 +54,8 @@ export function buildBrief(evidence, baseline, { max = 20, generatedAt = new Dat
     new: g.new.length + g.belowFloor.length,
     baselined: g.baselined.length,
   };
-  const doc = { schemaVersion: 1, tool: evidence.tool, generatedAt, head: evidence.run.repo.head, heading: HEADING, summary, ...(next ? { next: { action: next.action, command: next.command, why: next.why } } : {}), items, text: '' };
+  const unclaimed = changes?.uncovered?.length ? { ref: changes.ref, files: changes.uncovered } : undefined;
+  const doc = { schemaVersion: 1, tool: evidence.tool, generatedAt, head: evidence.run.repo.head, heading: HEADING, summary, ...(next ? { next: { action: next.action, command: next.command, why: next.why } } : {}), ...(unclaimed ? { unclaimed } : {}), items, text: '' };
   doc.text = renderBriefText({ ...doc, provisional: Boolean(evidence.run.provisional) }, { hasBaseline: Boolean(baseline), total: evidence.records.length });
   return doc;
 }
@@ -68,6 +69,13 @@ export function renderBriefText(brief, { hasBaseline, total }) {
     `testguard ${brief.tool.version}${brief.head ? ` @ ${brief.head.slice(0, 12)}` : ''} — ${brief.summary.claims} claims, ${total} faults probed, ${unproven} unproven` +
       (unproven === 0 ? '.' : hasBaseline ? ` (${brief.summary.new} new since baseline).` : ' (no baseline; everything is new).'),
   ];
+  // Unclaimed changes come before everything else: the claim is written
+  // before more code, and TestGuard is silent about unclaimed code otherwise.
+  if (brief.unclaimed) {
+    const n = brief.unclaimed.files.length;
+    lines.push('', `UNCLAIMED CHANGES since ${brief.unclaimed.ref}: ${n} changed file${n === 1 ? '' : 's'} carr${n === 1 ? 'ies' : 'y'} no claim. State the claim first; nothing below can see this code.`);
+    for (const u of brief.unclaimed.files) lines.push(`  - ${u.file} (${u.kind}) → ${u.suggestion}`);
+  }
   if (brief.next) lines.push('', `NEXT [${brief.next.action}]: ${brief.next.command}`, `  why: ${brief.next.why}`);
   if (brief.items.length === 0) {
     lines.push('', 'Every probed claim is defended. Keep it that way: new claims need a fault and a test that fails on it.');
@@ -87,3 +95,19 @@ export function renderBriefText(brief, { hasBaseline, total }) {
   if (unproven > brief.items.length) lines.push('', `… and ${unproven - brief.items.length} more in the evidence file.`);
   return lines.join('\n') + '\n';
 }
+
+/**
+ * A brief for a project that has unclaimed changes but no evidence yet. The
+ * session-start hook must still tell the agent to write the claim; an empty
+ * summary is honest, silence is not.
+ */
+export function buildUnclaimedBrief({ tool, next, changes, generatedAt = new Date().toISOString() }) {
+  const summary = { claims: 0, byVerdict: {}, new: 0, baselined: 0 };
+  const doc = { schemaVersion: 1, tool, generatedAt, heading: HEADING, summary, ...(next ? { next: { action: next.action, command: next.command, why: next.why } } : {}), unclaimed: { ref: changes.ref, files: changes.uncovered }, items: [], text: '' };
+  const lines = [HEADING, '', `testguard ${tool.version} — no evidence yet; ${changes.uncovered.length} unclaimed changed file${changes.uncovered.length === 1 ? '' : 's'} since ${changes.ref}.`];
+  lines.push('', `UNCLAIMED CHANGES since ${changes.ref}: state the claim first; nothing can be probed for this code until it has one.`);
+  for (const u of changes.uncovered) lines.push(`  - ${u.file} (${u.kind}) → ${u.suggestion}`);
+  if (next) lines.push('', `NEXT [${next.action}]: ${next.command}`, `  why: ${next.why}`);
+  doc.text = lines.join('\n') + '\n';
+  return doc;
+}

package/src/cli.mjs

@@ -13,6 +13,7 @@ import { briefCommand } from './commands/brief.mjs';
 import { scaffoldCommand } from './commands/scaffold.mjs';
 import { statusCommand } from './commands/status.mjs';
 import { initCommand } from './commands/init.mjs';
+import { gateCommand } from './commands/gate.mjs';
 
 const VERSION = JSON.parse(readFileSync(join(fileURLToPath(import.meta.url), '..', '..', 'package.json'), 'utf8')).version;
 
@@ -24,6 +25,7 @@ const USAGE = `testguard ${VERSION} — proves a test suite defends the claims a
   testguard probe [dir]      inject each claim's faults, run its defenders, report what survived
   testguard baseline [dir]   freeze today's unproven findings so only new ones gate
   testguard brief [dir]      emit the blind-spot block for an agent's session-start context
+  testguard gate [dir]       fail when a changed source file carries no claim and no excusing ignore entry
   testguard scaffold <file>  propose faults mechanically for one source file, as a draft claims document
 
 probe
@@ -38,6 +40,7 @@ probe
   --include-dirty      probe the working tree (a snapshot commit) instead of HEAD; uncommitted tests count
   --verbose            also print each killed fault (default: only unproven ones, plus a count)
                        --confirm below 3 is PROVISIONAL: verdicts print with "?", evidence goes to .testguard/evidence-provisional.json
+  --runner <name>      vitest | jest | auto (default: auto — first of vitest, jest that resolves)
   --runner-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)
   --in-place           mutate the working tree instead of a scratch worktree
@@ -48,17 +51,24 @@ probe
 scaffold   --claim <ID> (put every proposal under this claim; copies it if it exists)  --out <path>  --json
            shapes: if-guard → if (false) · single-line guard/mutation removed · return <check> → return true
                    · security flag/window/cost literal weakened · verify/validate/check call removed
-status     --json (exit 0 clean · 1 unproven/stale · 2 nothing to probe yet)
+gate       --changed <ref>   measure the change since merge-base(ref, HEAD); auto-detected in GitHub Actions / GitLab CI
+           --include-dirty   compare the working tree (staged, unstaged and untracked) instead of HEAD — the pre-commit shape
+           --exclude <glob>  (repeatable) more files that never carry claims; --explain lists the defaults
+           --strict          a non-empty change that evaluates nothing is a failure, not a note
+           --ignore <path>   ignore file (default: <dir>/testguard.ignore.json; kind=path entries excuse files, with a reason)
+           exit 0 every changed source file is claimed or excused · 1 unclaimed file · 2 cannot evaluate · 3 no reference
+status     --json (exit 0 clean · 1 unproven/stale/unclaimed · 2 nothing to probe yet)
+           --changed <ref>   also compute claim coverage of the change; unclaimed-changes then precedes every evidence state
 init       --force (replace an existing skill file)  --json
 every command accepts --json; probe/baseline emit the status document plus their own result
 claims     --json
 baseline   --evidence <path>  --out <path>  --allow-provisional (freeze unconfirmed evidence; normally refused)
 brief      --evidence <path>  --baseline <path>  --max <n>  --text (print only; safe for hooks)
 
-exit codes: 0 nothing new to prove · 1 unproven claims (or claim drift) · 2 precondition failed · 3 usage
+exit codes: 0 nothing new to prove · 1 unproven claims (or claim drift, or unclaimed changes) · 2 precondition failed · 3 usage
 `;
 
-const COMMANDS = { probe: probeCommand, claims: claimsCommand, baseline: baselineCommand, brief: briefCommand, scaffold: scaffoldCommand, status: statusCommand, init: initCommand };
+const COMMANDS = { probe: probeCommand, claims: claimsCommand, baseline: baselineCommand, brief: briefCommand, scaffold: scaffoldCommand, status: statusCommand, init: initCommand, gate: gateCommand };
 
 export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n'), err: (s) => process.stderr.write(s + '\n') }) {
   let parsed;
@@ -78,10 +88,16 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
         ref: { type: 'string', default: 'HEAD' },
         claim: { type: 'string' },
         'include-dirty': { type: 'boolean', default: false },
+        changed: { type: 'string' },
+        exclude: { type: 'string', multiple: true },
+        strict: { type: 'boolean', default: false },
+        explain: { type: 'boolean', default: false },
+        ignore: { type: 'string' },
         'allow-provisional': { type: 'boolean', default: false },
         force: { type: 'boolean', default: false },
         verbose: { type: 'boolean', default: false },
         'runner-cmd': { type: 'string' },
+        runner: { type: 'string', default: 'auto' },
         'node-modules': { type: 'string' },
         'in-place': { type: 'boolean', default: false },
         'no-escalate': { type: 'boolean', default: false },
@@ -114,6 +130,10 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
     io.err(USAGE);
     return 3;
   }
+  if (!['vitest', 'jest', 'auto'].includes(values.runner)) {
+    io.err('--runner must be vitest, jest or auto');
+    return 3;
+  }
   if (!['critical', 'high', 'medium', 'low'].includes(values.severity)) {
     io.err('--severity must be one of critical, high, medium, low');
     return 3;