testguard-cli 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,42 @@ 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

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.4.0` — 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
 ```
 
@@ -146,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
@@ -220,9 +269,10 @@ through every verdict.
 
 ## Status
 
-**v0.4.** Seven commands, vitest and jest runners, 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), runners beyond

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.4.0",
+  "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",

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
@@ -49,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;
@@ -79,6 +88,11 @@ 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 },

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/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');
@@ -58,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/status/status.mjs

@@ -7,6 +7,7 @@ import { hashFile, sha256 } from '../util/hash.mjs';
 import { resolveDefenders } from '../probe/runners/shared.mjs';
 import { discoverDefenders } from '../probe/discover.mjs';
 import { sortForReport } from '../render.mjs';
+import { computeChangedGate, defaultIgnorePath } from '../gate/changed.mjs';
 
 export const faultContentHash = (fault) => sha256(`${fault.find}\n${fault.replace}`);
 
@@ -22,7 +23,7 @@ const P = (projectDir) => ({
  * Reads the claims file, evidence, baseline and the working tree; never
  * trusts a cached verdict whose inputs have changed.
  */
-export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt = new Date().toISOString(), paths = P(projectDir), max = 20 }) {
+export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt = new Date().toISOString(), paths = P(projectDir), max = 20, changedRef, includeDirty = false }) {
   const rel = (p) => relative(projectDir, p) || '.';
   const doc = {
     schemaVersion: 1,
@@ -37,7 +38,32 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
     findings: [],
     paths: {},
   };
-  if (!existsSync(paths.claims)) return doc;
+  // ── Claim coverage of the change, when a reference is known ──
+  // Computed before anything about evidence: a change that touches unclaimed
+  // code is the finding every field report shared, and TestGuard is silent
+  // about unclaimed code by construction. The claim is written first.
+  // The reference is the caller's: this function never reads the environment,
+  // so a library caller or a test in a temp directory is never surprised by CI.
+  const ref = changedRef;
+  let changes;
+  if (ref) {
+    const g = computeChangedGate({ projectDir, ref, includeDirty, toolVersion });
+    changes = { ref: g.ref, base: g.base, includeDirty: g.includeDirty, changed: g.changed, evaluated: g.evaluated, excluded: g.excluded.length, uncovered: g.uncovered, reliedOn: g.reliedOn, expired: g.expired };
+    doc.changes = changes;
+    if (existsSync(defaultIgnorePath(projectDir))) doc.paths.ignore = rel(defaultIgnorePath(projectDir));
+  }
+  const unclaimedWhy = () => {
+    const files = changes.uncovered.map((u) => u.file);
+    return `${files.length} changed file${files.length === 1 ? '' : 's'} since ${changes.ref} carr${files.length === 1 ? 'ies' : 'y'} no claim and no excusing ignore entry: ${files.slice(0, 3).join(', ')}${files.length > 3 ? ', …' : ''}. State the claim before writing more code — TestGuard is silent about unclaimed code by construction.`;
+  };
+
+  if (!existsSync(paths.claims)) {
+    if (changes?.uncovered.length) {
+      const u = changes.uncovered[0];
+      doc.next = { action: 'scaffold', command: `testguard scaffold ${u.file}`, why: `No testguard.claims.json in this project, and ${unclaimedWhy()}`, file: u.file };
+    }
+    return doc;
+  }
   doc.paths.claims = rel(paths.claims);
 
   const claims = loadClaims(paths.claims);
@@ -46,6 +72,13 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
   const faultIndex = new Map();
   for (const c of claims.claims) for (const f of c.faults) faultIndex.set(`${c.id}/${f.id}`, { claim: c, fault: f });
 
+  if (changes && changes.uncovered.length > 0) {
+    const u = changes.uncovered[0];
+    doc.state = 'unclaimed-changes';
+    doc.next = { action: 'claim', command: u.suggestion, why: unclaimedWhy(), file: u.file };
+    return doc;
+  }
+
   const hasEvidence = existsSync(paths.evidence);
   const hasProvisional = existsSync(paths.provisional);
   if (hasProvisional) doc.paths.provisionalEvidence = rel(paths.provisional);
@@ -155,6 +188,13 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
 
 export function renderStatus(doc) {
   const lines = [`state: ${doc.state}${doc.provisional ? ' (provisional)' : ''} — ${doc.counts.claims} claims / ${doc.counts.faults} faults` + (doc.counts.byVerdict ? `; ${Object.entries(doc.counts.byVerdict).map(([k, v]) => `${v} ${k}`).join(', ')}; ${doc.counts.new ?? 0} new, ${doc.counts.baselined ?? 0} baselined` : '')];
+  if (doc.changes) {
+    const c = doc.changes;
+    lines.push(`changes:  ${c.changed} file${c.changed === 1 ? '' : 's'} since ${c.ref}; ${c.evaluated} evaluated, ${c.excluded} excluded, ${c.uncovered.length} unclaimed`);
+    for (const u of c.uncovered) lines.push(`UNCLAIMED ${u.file} (${u.kind}) → ${u.suggestion}`);
+    for (const r of c.reliedOn) lines.push(`excused   ${r.files.join(', ')} by ignore "${r.pattern}": ${r.reason}`);
+    for (const e of c.expired) lines.push(`EXPIRED   ignore "${e.pattern}" no longer excuses ${e.files.join(', ')}`);
+  }
   for (const c of doc.changedFaults) lines.push(`CHANGED   ${c.claimId}/${c.subjectId} edited since it ${c.previousVerdict} (${c.file})`);
   for (const s of doc.stale.slice(0, 8)) lines.push(`stale     ${s}`);
   lines.push(`next:     [${doc.next.action}] ${doc.next.command}`);