testguard-cli 0.4.0__tar.gz → 0.5.0__tar.gz

{testguard_cli-0.4.0 → testguard_cli-0.5.0}/.github/scripts/sync-release-version.mjs

@@ -5,6 +5,7 @@
  *   - pyproject.toml         `version = "x.y.z"`
  *   - action.yml             default of the `version` input
  *   - packaging/homebrew/*.rb the tarball URL (sha256 is set after publish)
+ *   - packaging/gitlab/*.yml  the include URL tag and TESTGUARD_VERSION
  *
  * `--check` verifies instead of writing (used by release.yml).
  */
@@ -21,6 +22,8 @@ const surfaces = [
   ['action.yml', /(\n  version:\n    description: [^\n]*\n    required: false\n    default: ')[^']*(')/, `$1${version}$2`],
   ['packaging/homebrew/testguard.rb', /testguard-cli-\d+\.\d+\.\d+\.tgz/g, `testguard-cli-${version}.tgz`],
   ['README.md', /raccioly\/testguard@v\d+\.\d+\.\d+/g, `raccioly/testguard@v${version}`],
+  ['packaging/gitlab/testguard.gitlab-ci.yml', /testguard\/v\d+\.\d+\.\d+\/packaging/g, `testguard/v${version}/packaging`],
+  ['packaging/gitlab/testguard.gitlab-ci.yml', /TESTGUARD_VERSION: "\d+\.\d+\.\d+"/, `TESTGUARD_VERSION: "${version}"`],
 ];
 
 let drift = 0;

{testguard_cli-0.4.0 → testguard_cli-0.5.0}/.github/workflows/ci.yml

@@ -122,6 +122,13 @@ jobs:
             console.log('jest fixture verdicts match expected.json:', ev.records.length);
           "
 
+      # ── Every change needs a claim: the gate runs on this repository's own
+      #    pull requests. A new source file without a claim (or an excusing
+      #    ignore entry with a reason) turns the PR red. ──
+      - name: gate — every changed source file carries a claim
+        if: github.event_name == 'pull_request'
+        run: node cli/testguard.mjs gate . --changed "origin/${{ github.base_ref }}"
+
       # ── Self-verification: TestGuard is governed by the standard it defines.
       #    testguard.claims.json states invariants of the tool itself; every
       #    fault must be killed by the tool's own tests. Exit 0 = all defended. ──

{testguard_cli-0.4.0 → testguard_cli-0.5.0}/.gitignore

@@ -8,6 +8,7 @@ coverage/
 .testguard/evidence-provisional.json
 .testguard/evidence-partial.json
 .testguard/brief.json
+.testguard/gate.json
 .testguard/scaffold-*.json
 # Local agent tooling — not part of the public project
 .wolf/

{testguard_cli-0.4.0 → testguard_cli-0.5.0}/.pre-commit-hooks.yaml

@@ -10,6 +10,7 @@
 #         rev: v0.1.0
 #         hooks:
 #           - id: testguard-claims        # fast: validates the claims file + drift
+#           - id: testguard-gate          # fast: every changed source file must carry a claim
 #           - id: testguard-probe         # slow: pre-push stage, runs the faults
 #
 #     # install the push-stage hook once per clone:
@@ -23,6 +24,14 @@
   pass_filenames: false
   always_run: true
 
+- id: testguard-gate
+  name: TestGuard gate (every change needs a claim)
+  description: Fails when a source file in this commit carries no claim, does not defend one, and is not excused by testguard.ignore.json. Fast; runs no tests.
+  entry: testguard gate --changed HEAD --include-dirty --quiet
+  language: node
+  pass_filenames: false
+  always_run: true
+
 - id: testguard-probe
   name: TestGuard probe (pre-push)
   description: Injects every claim's faults and fails on any the tests miss. Gated by the committed baseline.

{testguard_cli-0.4.0 → testguard_cli-0.5.0}/AGENTS.md

@@ -32,6 +32,7 @@ node cli/testguard.mjs scaffold src/probe/classify.mjs --json   # what the produ
 - `testguard.claims.json` — claims about this codebase, probed in CI.
 - `src/scaffold/producers.mjs` — the five fault shapes. Deterministic line heuristics; no AST, no LLM. A new shape needs a synthetic-file test and a README row.
 - `src/probe/runners/` — one module per runner (`name`, `testGlobs`, `check`, `tests`, `run`) over `shared.mjs` (jest-compatible report parsing, budgeted process runner). A new runner needs its own fixture copy with the same `expected.json`.
+- `src/gate/changed.mjs` — claim coverage of a change (`gate --changed`). File-level, delta-only; an uncovered file exits 1; every ignore reliance is reported. Its rules are a section of `GATE-SEMANTICS.md`.
 - `src/status/status.mjs` — the state machine every rendering derives from. A new state or action is a spec change (`status.schema.json`) and a skill-template change (`src/init/templates/SKILL.md`) in the same PR.
 
 ## Rules

{testguard_cli-0.4.0 → testguard_cli-0.5.0}/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

{testguard_cli-0.4.0 → testguard_cli-0.5.0}/CONTRIBUTING.md

@@ -24,7 +24,7 @@ Node ≥ 20. Python ≥ 3.8 only if you touch `testguard_cli/`.
 | `spec/lib/` | the validator and the one fingerprint implementation |
 | `spec/conformance/` | one valid example per kind; must-reject documents named for their defect |
 | `src/probe/` | worktree isolation, injector, runner adapter, classifier, ranker, orchestrator |
-| `src/claims/`, `src/baseline/`, `src/brief/` | the other three commands |
+| `src/claims/`, `src/baseline/`, `src/brief/`, `src/gate/` | the other commands: claims, baseline, brief, and the change gate |
 | `src/commands/`, `src/cli.mjs`, `cli/` | argument parsing and dispatch |
 | `fixtures/known-answer/` | the oracle: a project with a known verdict for every value in the verdict set |
 | `testguard.claims.json` | TestGuard's claims about itself, probed in CI |

{testguard_cli-0.4.0 → testguard_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: testguard-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: Proves a test suite actually defends the claims a project makes: injects the faults those claims forbid and reports every one the tests miss. Python wrapper for the Node.js CLI (requires Node.js 20+).
 Project-URL: Homepage, https://github.com/raccioly/testguard
 Project-URL: Documentation, https://github.com/raccioly/testguard#readme
@@ -76,7 +76,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
@@ -92,6 +92,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
 ```
 
@@ -170,6 +171,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
@@ -244,9 +293,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

{testguard_cli-0.4.0 → testguard_cli-0.5.0}/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

{testguard_cli-0.4.0 → testguard_cli-0.5.0}/action.yml

@@ -8,7 +8,7 @@ branding:
 
 inputs:
   command:
-    description: 'Command to run: probe, claims, baseline, brief'
+    description: 'Command to run: probe, claims, baseline, brief, gate'
     required: false
     default: 'probe'
   working-directory:
@@ -35,10 +35,18 @@ inputs:
     description: 'Skip re-running survivors against the whole suite'
     required: false
     default: 'false'
+  changed-ref:
+    description: 'gate only: the reference the change is measured against (default: origin/<base branch> of the pull request). Check out with fetch-depth: 0 so it resolves.'
+    required: false
+    default: ''
+  strict:
+    description: 'gate only: fail a change whose files were all excluded instead of passing with a note'
+    required: false
+    default: 'false'
   version:
     description: 'testguard-cli version to run'
     required: false
-    default: '0.4.0'
+    default: '0.5.0'
   node-version:
     description: 'Node.js version (20+)'
     required: false
@@ -68,5 +76,14 @@ runs:
           [ "${{ inputs.no-escalate }}" = "true" ] && ARGS+=(--no-escalate)
         fi
         [ "${{ inputs.command }}" = "brief" ] && ARGS+=(--text)
+        if [ "${{ inputs.command }}" = "gate" ]; then
+          REF="${{ inputs.changed-ref }}"
+          if [ -z "$REF" ] && [ -n "${GITHUB_BASE_REF:-}" ]; then
+            git fetch --no-tags --quiet origin "$GITHUB_BASE_REF" || true
+            REF="origin/${GITHUB_BASE_REF}"
+          fi
+          [ -n "$REF" ] && ARGS+=(--changed "$REF")
+          [ "${{ inputs.strict }}" = "true" ] && ARGS+=(--strict)
+        fi
         echo "evidence=$(pwd)/.testguard/evidence.json" >> "$GITHUB_OUTPUT"
         npx -y "testguard-cli@${{ inputs.version }}" "${{ inputs.command }}" . "${ARGS[@]}"

{testguard_cli-0.4.0 → testguard_cli-0.5.0}/bench/README.md

@@ -44,3 +44,22 @@ it, and runs `testguard` against the project by path.
 | `flaky-defender` | the defenders are not green N/N unmodified — the project's flake, not the tool's; nothing about the fault can be concluded |
 | `killed` where `survived` was expected | either the suite was hardened since, or the previous measurement ran once and a flake read as a detection |
 | `survived` where `killed` was expected | the declared defenders are not the tests that actually catch it; escalation will say whether anything does |
+
+## What a field report should carry
+
+The two reports that shaped 0.1.2 and 0.1.3 were written from the human
+table. Since 0.3.0 the tool also states, in machine-readable form, where a
+project is and what it would tell an agent to do next. Capture both, from
+the project directory, after the final probe:
+
+```bash
+testguard status --json  > ~/bench/<project>/status.json     # state, next action, changed faults, findings
+testguard brief --text   > ~/bench/<project>/brief.txt       # exactly what an agent sees at session start
+testguard status --json --changed <base-ref> > ~/bench/<project>/status-changed.json   # 0.5.0+: unclaimed changed files
+```
+
+and include them with the evidence. They answer the questions a report
+otherwise has to argue in prose: *was anything stale when the numbers were
+taken? did the tool point at the right next fix? would an agent have known
+what to do?* If `status.next` disagrees with what you did next, that
+disagreement is the most useful line in the report.

{testguard_cli-0.4.0 → testguard_cli-0.5.0}/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "testguard-cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "testguard-cli",
-      "version": "0.4.0",
+      "version": "0.5.0",
       "license": "MIT",
       "dependencies": {
         "ajv": "8.20.0"

{testguard_cli-0.4.0 → testguard_cli-0.5.0}/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",

testguard_cli-0.5.0/packaging/gitlab/testguard.gitlab-ci.yml

@@ -0,0 +1,47 @@
+# TestGuard for GitLab CI. Include it from a project's .gitlab-ci.yml:
+#
+#   include:
+#     - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.5.0/packaging/gitlab/testguard.gitlab-ci.yml'
+#
+# Two jobs. `testguard:gate` runs on every merge request pipeline and fails
+# when a changed source file carries no claim (and no excusing ignore entry).
+# `testguard:probe` runs the faults against the tests and is gated by the
+# committed baseline. Override TESTGUARD_VERSION / TESTGUARD_DIR as needed.
+#
+# The gate measures the change against CI_MERGE_REQUEST_DIFF_BASE_SHA, which
+# GitLab provides on merge request pipelines and which needs no extra fetch.
+# On other pipelines set TESTGUARD_CHANGED_REF (and fetch that ref).
+
+variables:
+  TESTGUARD_VERSION: "0.5.0"
+  TESTGUARD_DIR: "."
+  GIT_DEPTH: "0" # the probe builds a scratch worktree from HEAD; full history is the safe default
+
+.testguard:
+  image: node:22
+  before_script:
+    - cd "$TESTGUARD_DIR"
+    - npm ci --ignore-scripts
+
+testguard:gate:
+  extends: .testguard
+  stage: test
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  script:
+    - npx -y "testguard-cli@${TESTGUARD_VERSION}" gate .
+  artifacts:
+    when: always
+    paths: [".testguard/gate.json"]
+
+testguard:probe:
+  extends: .testguard
+  stage: test
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+  script:
+    - npx -y "testguard-cli@${TESTGUARD_VERSION}" probe . --quiet
+  artifacts:
+    when: always
+    paths: [".testguard/evidence.json"]

{testguard_cli-0.4.0 → testguard_cli-0.5.0}/packaging/homebrew/testguard.rb

@@ -13,7 +13,7 @@
 class Testguard < Formula
   desc "Proves a test suite defends the claims a project makes"
   homepage "https://github.com/raccioly/testguard"
-  url "https://registry.npmjs.org/testguard-cli/-/testguard-cli-0.4.0.tgz"
+  url "https://registry.npmjs.org/testguard-cli/-/testguard-cli-0.5.0.tgz"
   sha256 "385d69f9d3c153b934d9c1cb6a2c754eb9b221b0a8c0ba8b805858384d2d4678"
   license "MIT"
 

{testguard_cli-0.4.0 → testguard_cli-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "testguard-cli"
-version = "0.4.0"
+version = "0.5.0"
 description = "Proves a test suite actually defends the claims a project makes: injects the faults those claims forbid and reports every one the tests miss. Python wrapper for the Node.js CLI (requires Node.js 20+)."
 readme = "README.md"
 license = { text = "MIT" }

{testguard_cli-0.4.0 → testguard_cli-0.5.0}/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

{testguard_cli-0.4.0 → testguard_cli-0.5.0}/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 —

testguard_cli-0.5.0/spec/conformance/examples/gate.json

@@ -0,0 +1,38 @@
+{
+  "schemaVersion": 1,
+  "tool": { "name": "testguard", "version": "0.4.0" },
+  "generatedAt": "2026-09-17T02:00:00Z",
+  "ref": "origin/main",
+  "base": "0f2a4c6e8b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a",
+  "head": "9a7c5e3b1d0f8e6c4a2b0d8f6e4c2a0b8d6f4e2c",
+  "includeDirty": false,
+  "strict": false,
+  "changed": 5,
+  "evaluated": 3,
+  "excluded": [
+    { "file": "README.md", "by": "non-source" },
+    { "file": "vitest.config.mjs", "by": "default:**/*.config.*" }
+  ],
+  "covered": [
+    { "file": "src/redact.mjs", "by": "fault", "claimIds": ["REDACT-001", "REDACT-003"] },
+    { "file": "src/legacy/format.mjs", "by": "ignore", "pattern": "src/legacy/**" }
+  ],
+  "uncovered": [
+    {
+      "file": "src/export.mjs",
+      "kind": "source",
+      "nearestClaimId": "REDACT-001",
+      "suggestion": "testguard scaffold src/export.mjs --claim REDACT-001"
+    }
+  ],
+  "reliedOn": [
+    {
+      "pattern": "src/legacy/**",
+      "reason": "Scheduled for deletion in Q4; no new claims will be authored against it.",
+      "expires": "2026-12-31T00:00:00Z",
+      "files": ["src/legacy/format.mjs"]
+    }
+  ],
+  "expired": [],
+  "exitCode": 1
+}

testguard_cli-0.5.0/spec/conformance/invalid/gate.counts-disagree.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": 1,
+  "tool": { "name": "testguard", "version": "0.4.0" },
+  "generatedAt": "2026-09-17T02:00:00Z",
+  "ref": "origin/main",
+  "base": "0f2a4c6e8b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a",
+  "head": "9a7c5e3b1d0f8e6c4a2b0d8f6e4c2a0b8d6f4e2c",
+  "includeDirty": false,
+  "strict": false,
+  "changed": 4,
+  "evaluated": 1,
+  "excluded": [],
+  "covered": [
+    { "file": "src/redact.mjs", "by": "fault", "claimIds": ["REDACT-001"] }
+  ],
+  "uncovered": [],
+  "reliedOn": [],
+  "expired": [],
+  "exitCode": 0
+}

testguard_cli-0.5.0/spec/conformance/invalid/gate.exit-zero-with-uncovered.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": 1,
+  "tool": { "name": "testguard", "version": "0.4.0" },
+  "generatedAt": "2026-09-17T02:00:00Z",
+  "ref": "origin/main",
+  "base": "0f2a4c6e8b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a",
+  "head": "9a7c5e3b1d0f8e6c4a2b0d8f6e4c2a0b8d6f4e2c",
+  "includeDirty": false,
+  "strict": false,
+  "changed": 1,
+  "evaluated": 1,
+  "excluded": [],
+  "covered": [],
+  "uncovered": [
+    { "file": "src/export.mjs", "kind": "source", "suggestion": "testguard scaffold src/export.mjs" }
+  ],
+  "reliedOn": [],
+  "expired": [],
+  "exitCode": 0
+}

testguard_cli-0.5.0/spec/conformance/invalid/gate.ignore-cover-without-pattern.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": 1,
+  "tool": { "name": "testguard", "version": "0.4.0" },
+  "generatedAt": "2026-09-17T02:00:00Z",
+  "ref": "origin/main",
+  "base": "0f2a4c6e8b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a",
+  "head": "9a7c5e3b1d0f8e6c4a2b0d8f6e4c2a0b8d6f4e2c",
+  "includeDirty": false,
+  "strict": false,
+  "changed": 1,
+  "evaluated": 1,
+  "excluded": [],
+  "covered": [
+    { "file": "src/legacy/format.mjs", "by": "ignore" }
+  ],
+  "uncovered": [],
+  "reliedOn": [],
+  "expired": [],
+  "exitCode": 0
+}