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

{testguard_cli-0.3.1 → 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.3.1 → testguard_cli-0.5.0}/.github/workflows/ci.yml

@@ -102,6 +102,33 @@ jobs:
             console.log('fixture verdicts match expected.json:', ev.records.length);
           "
 
+      - name: probe the jest fixture (through the bin, --runner jest)
+        shell: bash
+        run: |
+          S=$(mktemp -d)
+          cp -R fixtures/known-answer-jest/. "$S/"
+          rm -rf "$S/node_modules" "$S/.flake-counter" "$S/.testguard"
+          ln -s "$GITHUB_WORKSPACE/node_modules" "$S/node_modules"
+          git -C "$S" init -q && git -C "$S" -c user.email=ci@example.invalid -c user.name=ci add -A && git -C "$S" -c user.email=ci@example.invalid -c user.name=ci commit -qm fixture
+          status=0; node cli/testguard.mjs probe "$S" --runner jest --budget 60000 --quiet --no-escalate || status=$?
+          [ "$status" -eq 1 ] || { echo "::error::expected exit 1, got $status"; exit 1; }
+          node --input-type=module -e "
+            import { readFileSync } from 'node:fs';
+            const ev = JSON.parse(readFileSync('$S/.testguard/evidence.json','utf8'));
+            const exp = JSON.parse(readFileSync('fixtures/known-answer-jest/expected.json','utf8')).expected;
+            if (ev.run.runner.name !== 'jest') { console.error('runner was', ev.run.runner.name); process.exit(1); }
+            const bad = ev.records.filter(r => exp[r.claim.id+'/'+r.subject.id].verdict !== r.verdict);
+            if (bad.length) { console.error('MISMATCH', bad.map(r => r.claim.id+'/'+r.subject.id+':'+r.verdict)); process.exit(1); }
+            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.5.0/.gitignore

@@ -0,0 +1,23 @@
+node_modules/
+dist/
+coverage/
+.DS_Store
+*.log
+# TestGuard: baseline.json and status.json ARE committed (the frozen contract and its snapshot); the rest is regenerated per run
+.testguard/evidence.json
+.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/
+.claude/
+CLAUDE.local.md
+graphify-out/
+.vitest/
+# Python build artefacts
+dist/
+build/
+*.egg-info/
+__pycache__/

{testguard_cli-0.3.1 → 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.5.0/.testguard/baseline.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "tool": {
+    "name": "testguard",
+    "version": "0.3.0"
+  },
+  "createdAt": "2026-09-17T15:24:13.597Z",
+  "head": "ac32ce504fc42f9b50389a5a8092a0e2ca1c5c9d",
+  "dirty": true,
+  "fingerprints": {}
+}

testguard_cli-0.5.0/.testguard/status.json

@@ -0,0 +1,32 @@
+{
+  "schemaVersion": 1,
+  "tool": {
+    "name": "testguard",
+    "version": "0.3.0"
+  },
+  "generatedAt": "2026-09-17T15:24:13.654Z",
+  "state": "clean",
+  "next": {
+    "action": "none",
+    "command": "testguard probe",
+    "why": "Every claim is defended. Re-probe after changing code, tests or claims; add a claim for every new invariant."
+  },
+  "provisional": false,
+  "counts": {
+    "claims": 12,
+    "faults": 12,
+    "byVerdict": {
+      "killed": 12
+    },
+    "new": 0,
+    "baselined": 0
+  },
+  "stale": [],
+  "changedFaults": [],
+  "findings": [],
+  "paths": {
+    "claims": "testguard.claims.json",
+    "evidence": ".testguard/evidence.json",
+    "baseline": ".testguard/baseline.json"
+  }
+}

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

@@ -31,6 +31,8 @@ node cli/testguard.mjs scaffold src/probe/classify.mjs --json   # what the produ
 - `fixtures/known-answer/expected.json` — the oracle. Never edit it to match output.
 - `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.3.1 → testguard_cli-0.5.0}/CHANGELOG.md

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

{testguard_cli-0.3.1 → 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.3.1 → testguard_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: testguard-cli
-Version: 0.3.1
+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.3.1` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.5.0` — see [`action.yml`](./action.yml) |
 | pre-commit | `repo: https://github.com/raccioly/testguard`, hooks `testguard-claims`, `testguard-probe` |
 
 Projects that set `min-release-age` in `.npmrc` cannot see a version published
@@ -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
 ```
 
@@ -135,6 +136,11 @@ npx testguard-cli scaffold src/x.ts   # propose faults for a file, as a draft to
    files that import the fault's target, by relative path or resolved alias.
    `NOCOVER` then means exactly "no test file imports this source".
 
+   Runners: **vitest** and **jest** (`--runner auto` picks the first that
+   resolves; both read the same jest-compatible JSON report). Anything else
+   goes through `--runner-cmd`. Each runner is proven against its own copy
+   of the known-answer fixture.
+
    Practical loop: first pass `--no-escalate` (escalation re-runs the whole
    suite N times per survivor); iterate on one claim with `--claim <ID>` and
    either `--include-dirty` or `--in-place` (only fault target files must be
@@ -165,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
@@ -239,14 +293,15 @@ through every verdict.
 
 ## Status
 
-**v0.3.** Seven commands, vitest runner, hand-authored faults plus a
-mechanical scaffold, and an agent operating layer (`status`, `init`). The contract
-spine — six JSON Schemas shared with the other Guard tools — is under
+**v0.4.** Eight commands, vitest and jest runners, hand-authored faults plus
+a mechanical scaffold, an agent operating layer (`status`, `init`) and a
+change gate (`gate`). The contract
+spine — eight JSON Schemas shared with the other Guard tools — is under
 [`spec/`](spec/). One exact-pinned runtime dependency (`ajv`, for schema validation); Node ≥ 20.
 
-Not yet: test generation (the two-gate acceptance loop), other runners,
-AST-aware producers, and calibration of fault classes against real escaped
-bugs. Each is designed for; none is claimed.
+Not yet: test generation (the two-gate acceptance loop), runners beyond
+vitest and jest, AST-aware producers, and calibration of fault classes
+against real escaped bugs. Each is designed for; none is claimed.
 
 ## Licence
 

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

{testguard_cli-0.3.1 → 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.3.1'
+    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.3.1 → 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.5.0/fixtures/known-answer-jest/.gitignore

@@ -0,0 +1,2 @@
+.flake-counter
+node_modules/

testguard_cli-0.5.0/fixtures/known-answer-jest/README.md

@@ -0,0 +1,7 @@
+# Known-answer fixture — jest edition
+
+The same nine claims and eleven faults as [`../known-answer`](../known-answer), in
+CommonJS, run by **jest** (`jest.config.js`: `testTimeout: 1000`). Every verdict in
+`expected.json` is the same. Its test suite is flaky by design (`test/flaky.test.js`).
+
+It proves the jest runner adapter reproduces the oracle; the ESM fixture proves vitest.

testguard_cli-0.5.0/fixtures/known-answer-jest/expected.json

@@ -0,0 +1,54 @@
+{
+  "confirmRuns": 3,
+  "expected": {
+    "REDACT-001/F1": {
+      "verdict": "survived",
+      "why": "The audit-row test asserts with objectContaining and omits `content`; a row carrying the raw input passes."
+    },
+    "REDACT-001/F2": {
+      "verdict": "killed",
+      "why": "The masked-output test asserts the secret is absent."
+    },
+    "REDACT-002/F1": {
+      "verdict": "killed",
+      "why": "The invalid-rule test asserts compileRules does not throw."
+    },
+    "REDACT-003/F1": {
+      "verdict": "survived",
+      "why": "No test exercises a missing scope; the fail-closed guard is undefended."
+    },
+    "REDACT-004/F1": {
+      "verdict": "timeout",
+      "why": "Tests awaiting redact() hit the 1s jest testTimeout; a timeout is not an assertion failure and is not a kill."
+    },
+    "REDACT-005/F1": {
+      "verdict": "unverifiable",
+      "reason": "anchor-missing",
+      "why": "The find string is not present in the source."
+    },
+    "REDACT-005/F2": {
+      "verdict": "unverifiable",
+      "reason": "anchor-ambiguous",
+      "why": "`return null;` occurs twice; expectHits is 1."
+    },
+    "REDACT-006/F1": {
+      "verdict": "fault-invalid",
+      "reason": "replacement-does-not-compile",
+      "why": "The replacement introduces a syntax error; the suite cannot load."
+    },
+    "EXPORT-001/F1": {
+      "verdict": "nocover",
+      "why": "test/export.test.js does not exist; no defender resolves."
+    },
+    "FLAKY-001/F1": {
+      "verdict": "flaky-defender",
+      "reason": "defenders-not-green",
+      "why": "test/flaky.test.js fails every other run; the baseline is not green N/N."
+    },
+    "DISCOVER-001/F1": {
+      "verdict": "killed",
+      "why": "No defendedBy; test/redact.test.js is discovered because it imports src/redact.js, and its masked-output test fails."
+    }
+  },
+  "runner": "jest"
+}

testguard_cli-0.5.0/fixtures/known-answer-jest/jest.config.js

@@ -0,0 +1 @@
+module.exports = { testEnvironment: 'node', testTimeout: 1000, testMatch: ['**/test/**/*.test.js'] };

testguard_cli-0.5.0/fixtures/known-answer-jest/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "testguard-known-answer-fixture-jest",
+  "private": true,
+  "version": "0.0.0",
+  "description": "The known-answer fixture in CommonJS for jest. Same claims, same expected verdicts. FLAKY BY DESIGN (test/flaky.test.js).",
+  "scripts": { "test": "jest" }
+}

testguard_cli-0.5.0/fixtures/known-answer-jest/src/export.js

@@ -0,0 +1,5 @@
+// Export of audit rows. No test file imports this module — on purpose (the `nocover` case).
+function exportRows(rows) {
+  return rows.map(({ content, ...rest }) => rest);
+}
+module.exports = { exportRows };