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

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

@@ -31,6 +31,7 @@ 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/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
 
@@ -55,3 +56,12 @@ node cli/testguard.mjs scaffold src/probe/classify.mjs --json   # what the produ
 Dependabot minor/patch PRs and automated release PRs auto-merge when the exact
 CI run is green on all three Node legs. Majors and anything else wait for a
 human. Release publishing is OIDC-only; there are no tokens in this repo.
+
+<!-- testguard:begin -->
+## TestGuard
+
+This project's tests are verified by [TestGuard](https://github.com/raccioly/testguard).
+Before writing or changing tests, run `testguard status --json` and follow `next`.
+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.
+<!-- testguard:end -->

{testguard_cli-0.2.1 → testguard_cli-0.3.1}/CHANGELOG.md

@@ -7,6 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-09-17
+
+Dogfooding `init` and `status` on this repository.
+
+### Fixed
+
+- `init` no longer adds per-file `.gitignore` lines to a project that already
+  ignores `.testguard/` wholesale; it notes instead that `baseline.json` is
+  meant to be committed.
+- The brief no longer says "everything is new" when nothing is unproven.
+
+### Changed
+
+- This repository now carries its own `AGENTS.md` TestGuard section, written
+  by `testguard init`.
+
+## [0.3.0] - 2026-09-17
+
+The agent operating layer. TestGuard is meant to be run by AI agents; this
+release gives them one source of truth, an installable loop, and makes the
+one cheap way to game it visible.
+
+### Added
+
+- **`testguard status --json`** — the machine entry point. A new spec kind
+  (`status.schema.json`): `state` (no-claims · unprobed · evidence-stale ·
+  provisional-only · unproven · clean) and the one `next` action, computed
+  from claims, evidence, baseline and the working tree. Exit 0 clean, 1
+  unproven/stale, 2 nothing to probe yet.
+- **`testguard init`** — installs `.claude/skills/testguard/SKILL.md`, the
+  `brief --text` SessionStart hook (merged into an existing
+  `.claude/settings.json`), an `AGENTS.md` section and the `.gitignore`
+  lines. Idempotent; `--force` replaces the skill.
+- **Fault edits are visible.** Evidence records `subject.contentHash`;
+  `status` lists `changedFaults` (a fault edited after it was probed, with
+  its previous verdict) and makes `review-fault-change` the next action when
+  the edited fault had survived. Gate rule 8. Self-claim
+  `TG-FAULT-EDIT-VISIBLE`.
+- `--json` on every command; `probe` and `baseline` emit the status document
+  plus their result. `brief` carries `next` and prints it.
+
 ## [0.2.1] - 2026-09-17
 
 ### Added

{testguard_cli-0.2.1 → testguard_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: testguard-cli
-Version: 0.2.1
+Version: 0.3.1
 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.2.1` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.3.1` — 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
@@ -86,6 +86,8 @@ less than that many days ago (`ENOVERSIONS`); install that one with
 ## How it works
 
 ```bash
+npx testguard-cli init        # install the agent layer: skill, session-start hook, AGENTS.md section
+npx testguard-cli status --json   # where the project is and the ONE next action — the machine entry point
 npx testguard-cli claims      # what does this project claim, and is every claim probeable?
 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
@@ -163,6 +165,27 @@ 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.
 
+### Built for agents to run
+
+TestGuard is meant to be driven by an AI agent, not typed by a person. Three
+things make that safe:
+
+- **One source of truth.** `testguard status --json` computes `state` and the
+  one `next` action from the claims file, the evidence, the baseline and the
+  working tree. Every human rendering — the CLI text, the session-start
+  brief, the skill — derives from it, so they cannot disagree. Every command
+  accepts `--json`.
+- **An installable operating loop.** `testguard init` writes
+  `.claude/skills/testguard/SKILL.md` (state → action, verdict → the only
+  acceptable fix, the two-gate rule for any test the agent writes), the
+  `brief --text` session-start hook, an `AGENTS.md` section and the
+  `.gitignore` lines. Idempotent.
+- **Gaming is visible.** The cheapest way to make a survivor disappear is to
+  weaken its fault, not to write a test. Evidence records every fault's
+  content hash; `status` lists any fault edited after it survived, with its
+  previous verdict, and makes reviewing that edit the next action. Editing a
+  claim is allowed — claims can be wrong — but it is never invisible.
+
 ### Authoring faults mechanically
 
 Writing faults by hand means reading the code to find exact anchors. Two
@@ -216,8 +239,8 @@ through every verdict.
 
 ## Status
 
-**v0.2.** Five commands, vitest runner, hand-authored faults plus a
-mechanical scaffold for the five common shapes. The contract
+**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
 [`spec/`](spec/). One exact-pinned runtime dependency (`ajv`, for schema validation); Node ≥ 20.
 

{testguard_cli-0.2.1 → testguard_cli-0.3.1}/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.2.1` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.3.1` — 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
@@ -62,6 +62,8 @@ less than that many days ago (`ENOVERSIONS`); install that one with
 ## How it works
 
 ```bash
+npx testguard-cli init        # install the agent layer: skill, session-start hook, AGENTS.md section
+npx testguard-cli status --json   # where the project is and the ONE next action — the machine entry point
 npx testguard-cli claims      # what does this project claim, and is every claim probeable?
 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
@@ -139,6 +141,27 @@ 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.
 
+### Built for agents to run
+
+TestGuard is meant to be driven by an AI agent, not typed by a person. Three
+things make that safe:
+
+- **One source of truth.** `testguard status --json` computes `state` and the
+  one `next` action from the claims file, the evidence, the baseline and the
+  working tree. Every human rendering — the CLI text, the session-start
+  brief, the skill — derives from it, so they cannot disagree. Every command
+  accepts `--json`.
+- **An installable operating loop.** `testguard init` writes
+  `.claude/skills/testguard/SKILL.md` (state → action, verdict → the only
+  acceptable fix, the two-gate rule for any test the agent writes), the
+  `brief --text` session-start hook, an `AGENTS.md` section and the
+  `.gitignore` lines. Idempotent.
+- **Gaming is visible.** The cheapest way to make a survivor disappear is to
+  weaken its fault, not to write a test. Evidence records every fault's
+  content hash; `status` lists any fault edited after it survived, with its
+  previous verdict, and makes reviewing that edit the next action. Editing a
+  claim is allowed — claims can be wrong — but it is never invisible.
+
 ### Authoring faults mechanically
 
 Writing faults by hand means reading the code to find exact anchors. Two
@@ -192,8 +215,8 @@ through every verdict.
 
 ## Status
 
-**v0.2.** Five commands, vitest runner, hand-authored faults plus a
-mechanical scaffold for the five common shapes. The contract
+**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
 [`spec/`](spec/). One exact-pinned runtime dependency (`ajv`, for schema validation); Node ≥ 20.
 

{testguard_cli-0.2.1 → testguard_cli-0.3.1}/action.yml

@@ -38,7 +38,7 @@ inputs:
   version:
     description: 'testguard-cli version to run'
     required: false
-    default: '0.2.1'
+    default: '0.3.1'
   node-version:
     description: 'Node.js version (20+)'
     required: false

{testguard_cli-0.2.1 → testguard_cli-0.3.1}/package-lock.json

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

{testguard_cli-0.2.1 → testguard_cli-0.3.1}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "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.2.1 → testguard_cli-0.3.1}/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.2.1.tgz"
+  url "https://registry.npmjs.org/testguard-cli/-/testguard-cli-0.3.1.tgz"
   sha256 "385d69f9d3c153b934d9c1cb6a2c754eb9b221b0a8c0ba8b805858384d2d4678"
   license "MIT"
 

{testguard_cli-0.2.1 → testguard_cli-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "testguard-cli"
-version = "0.2.1"
+version = "0.3.1"
 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.2.1 → testguard_cli-0.3.1}/spec/GATE-SEMANTICS.md

@@ -50,6 +50,12 @@ Rules that follow from the table:
    snapshot the working tree — otherwise the answer looks right and is not.
 7. **Never a single global score.** Output is per claim, ranked. Blindness is
    concentrated, and one number hides where.
+8. **A changed fault is a finding.** Editing a claim is legitimate — claims
+   can be wrong — but the cheapest way to make a survivor disappear without
+   writing a test is to weaken its fault. Evidence records each fault's
+   content hash; the status document lists every fault whose content
+   changed since it was probed, with its previous verdict. The change is
+   allowed; it is never invisible.
 
 ## Baseline and delta
 

{testguard_cli-0.2.1 → testguard_cli-0.3.1}/spec/README.md

@@ -20,7 +20,8 @@ The pattern all such tools run:
 | `baseline` | [`schemas/baseline.schema.json`](schemas/baseline.schema.json) | Frozen fingerprints of existing debt. Gate only what is new. |
 | `ignore` | [`schemas/ignore.schema.json`](schemas/ignore.schema.json) | Reviewable scoping. Every entry has a reason. |
 | `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. |
+| `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. |
 
 Shared definitions (verdicts, fault classes, provenance, annotations) live in
 [`schemas/common.schema.json`](schemas/common.schema.json). Gate behaviour —

{testguard_cli-0.2.1 → testguard_cli-0.3.1}/spec/conformance/examples/brief.json

@@ -44,5 +44,10 @@
       "isNew": true
     }
   ],
-  "text": "## TEST BLINDSPOT CONTEXT\n\nSource: testguard 0.1.0 @ deadbeefcafe. 2 claims; 1 killed, 1 survived, 1 unverifiable, 1 nocover, 1 flaky-defender. 1 new since baseline.\n\n1. [NEW] REDACT-002 unverifiable (high) src/redact.mjs — Anchor not found; re-author the fault.\n2. REDACT-001 SURVIVED (critical) src/redact.mjs — test/redact.test.mjs asserts with objectContaining and omits the `content` key.\n"
+  "text": "## TEST BLINDSPOT CONTEXT\n\nSource: testguard 0.1.0 @ deadbeefcafe. 2 claims; 1 killed, 1 survived, 1 unverifiable, 1 nocover, 1 flaky-defender. 1 new since baseline.\n\n1. [NEW] REDACT-002 unverifiable (high) src/redact.mjs — Anchor not found; re-author the fault.\n2. REDACT-001 SURVIVED (critical) src/redact.mjs — test/redact.test.mjs asserts with objectContaining and omits the `content` key.\n",
+  "next": {
+    "action": "write-test",
+    "command": "write a test in test/redact.test.mjs that fails on REDACT-001/F1 and passes on HEAD, then: testguard probe --claim REDACT-001 --include-dirty",
+    "why": "REDACT-001/F1 (critical) survived: the audit row can carry the raw input and no test notices."
+  }
 }

{testguard_cli-0.2.1 → testguard_cli-0.3.1}/spec/conformance/examples/evidence-provisional.json

@@ -48,7 +48,8 @@
           "producer": "human",
           "by": "maintainer",
           "at": "2026-09-17T02:00:00Z"
-        }
+        },
+        "contentHash": "f232f31d9e6eecc8e952f0da1fb0878c5060e1a4dc19724874b041a4ab265aaf"
       },
       "verdict": "survived",
       "detail": {
@@ -142,7 +143,8 @@
         "id": "F2",
         "description": "Redaction skipped.",
         "file": "src/redact.mjs",
-        "faultClass": "statement-deleted"
+        "faultClass": "statement-deleted",
+        "contentHash": "f232f31d9e6eecc8e952f0da1fb0878c5060e1a4dc19724874b041a4ab265aaf"
       },
       "verdict": "killed",
       "detail": {
@@ -203,7 +205,8 @@
         "id": "F1",
         "description": "Invalid pattern rethrows.",
         "file": "src/redact.mjs",
-        "faultClass": "exception-swallowed"
+        "faultClass": "exception-swallowed",
+        "contentHash": "f232f31d9e6eecc8e952f0da1fb0878c5060e1a4dc19724874b041a4ab265aaf"
       },
       "verdict": "unverifiable",
       "detail": {
@@ -247,7 +250,8 @@
         "id": "F1",
         "description": "Invalid pattern rethrows.",
         "file": "src/redact.mjs",
-        "faultClass": "exception-swallowed"
+        "faultClass": "exception-swallowed",
+        "contentHash": "f232f31d9e6eecc8e952f0da1fb0878c5060e1a4dc19724874b041a4ab265aaf"
       },
       "verdict": "nocover",
       "detail": {

{testguard_cli-0.2.1 → testguard_cli-0.3.1}/spec/conformance/examples/evidence.json

@@ -47,7 +47,8 @@
           "producer": "human",
           "by": "maintainer",
           "at": "2026-09-17T02:00:00Z"
-        }
+        },
+        "contentHash": "f232f31d9e6eecc8e952f0da1fb0878c5060e1a4dc19724874b041a4ab265aaf"
       },
       "verdict": "survived",
       "detail": {
@@ -181,7 +182,8 @@
         "id": "F2",
         "description": "Redaction skipped.",
         "file": "src/redact.mjs",
-        "faultClass": "statement-deleted"
+        "faultClass": "statement-deleted",
+        "contentHash": "f232f31d9e6eecc8e952f0da1fb0878c5060e1a4dc19724874b041a4ab265aaf"
       },
       "verdict": "killed",
       "detail": {
@@ -282,7 +284,8 @@
         "id": "F1",
         "description": "Invalid pattern rethrows.",
         "file": "src/redact.mjs",
-        "faultClass": "exception-swallowed"
+        "faultClass": "exception-swallowed",
+        "contentHash": "f232f31d9e6eecc8e952f0da1fb0878c5060e1a4dc19724874b041a4ab265aaf"
       },
       "verdict": "unverifiable",
       "detail": {
@@ -326,7 +329,8 @@
         "id": "F1",
         "description": "Invalid pattern rethrows.",
         "file": "src/redact.mjs",
-        "faultClass": "exception-swallowed"
+        "faultClass": "exception-swallowed",
+        "contentHash": "f232f31d9e6eecc8e952f0da1fb0878c5060e1a4dc19724874b041a4ab265aaf"
       },
       "verdict": "nocover",
       "detail": {
@@ -368,7 +372,8 @@
         "id": "F2",
         "description": "Redaction skipped.",
         "file": "src/redact.mjs",
-        "faultClass": "statement-deleted"
+        "faultClass": "statement-deleted",
+        "contentHash": "f232f31d9e6eecc8e952f0da1fb0878c5060e1a4dc19724874b041a4ab265aaf"
       },
       "verdict": "flaky-defender",
       "detail": {
@@ -444,7 +449,8 @@
         "id": "F3",
         "description": "Rule order reversed.",
         "file": "src/redact.mjs",
-        "faultClass": "other"
+        "faultClass": "other",
+        "contentHash": "f232f31d9e6eecc8e952f0da1fb0878c5060e1a4dc19724874b041a4ab265aaf"
       },
       "verdict": "flaky-defender",
       "detail": {

testguard_cli-0.3.1/spec/conformance/examples/status.json

@@ -0,0 +1,60 @@
+{
+  "schemaVersion": 1,
+  "tool": {
+    "name": "testguard",
+    "version": "0.1.0"
+  },
+  "generatedAt": "2026-09-17T02:00:00Z",
+  "state": "unproven",
+  "next": {
+    "action": "write-test",
+    "command": "write a test in test/redact.test.mjs that fails on REDACT-001/F1 and passes on HEAD, then: testguard probe --claim REDACT-001 --include-dirty",
+    "why": "REDACT-001/F1 (critical) survived.",
+    "target": {
+      "claimId": "REDACT-001",
+      "subjectId": "F1",
+      "file": "src/redact.mjs",
+      "verdict": "survived"
+    }
+  },
+  "provisional": false,
+  "counts": {
+    "claims": 2,
+    "faults": 6,
+    "byVerdict": {
+      "killed": 1,
+      "survived": 1,
+      "unverifiable": 1,
+      "nocover": 1,
+      "flaky-defender": 2
+    },
+    "new": 1,
+    "baselined": 4
+  },
+  "stale": [],
+  "changedFaults": [
+    {
+      "claimId": "REDACT-002",
+      "subjectId": "F1",
+      "previousVerdict": "unverifiable",
+      "file": "src/redact.mjs"
+    }
+  ],
+  "findings": [
+    {
+      "fingerprint": "01876384493be6809da455cb1a1c4bc92e7564e9898506d790b9589200502163",
+      "claimId": "REDACT-001",
+      "subjectId": "F1",
+      "verdict": "survived",
+      "severity": "critical",
+      "file": "src/redact.mjs",
+      "rank": 9.5,
+      "isNew": true
+    }
+  ],
+  "paths": {
+    "claims": "testguard.claims.json",
+    "evidence": ".testguard/evidence.json",
+    "baseline": ".testguard/baseline.json"
+  }
+}

testguard_cli-0.3.1/spec/conformance/invalid/status.clean-with-new-findings.json

@@ -0,0 +1,60 @@
+{
+  "schemaVersion": 1,
+  "tool": {
+    "name": "testguard",
+    "version": "0.1.0"
+  },
+  "generatedAt": "2026-09-17T02:00:00Z",
+  "state": "clean",
+  "next": {
+    "action": "write-test",
+    "command": "write a test in test/redact.test.mjs that fails on REDACT-001/F1 and passes on HEAD, then: testguard probe --claim REDACT-001 --include-dirty",
+    "why": "REDACT-001/F1 (critical) survived.",
+    "target": {
+      "claimId": "REDACT-001",
+      "subjectId": "F1",
+      "file": "src/redact.mjs",
+      "verdict": "survived"
+    }
+  },
+  "provisional": false,
+  "counts": {
+    "claims": 2,
+    "faults": 6,
+    "byVerdict": {
+      "killed": 1,
+      "survived": 1,
+      "unverifiable": 1,
+      "nocover": 1,
+      "flaky-defender": 2
+    },
+    "new": 1,
+    "baselined": 4
+  },
+  "stale": [],
+  "changedFaults": [
+    {
+      "claimId": "REDACT-002",
+      "subjectId": "F1",
+      "previousVerdict": "unverifiable",
+      "file": "src/redact.mjs"
+    }
+  ],
+  "findings": [
+    {
+      "fingerprint": "01876384493be6809da455cb1a1c4bc92e7564e9898506d790b9589200502163",
+      "claimId": "REDACT-001",
+      "subjectId": "F1",
+      "verdict": "survived",
+      "severity": "critical",
+      "file": "src/redact.mjs",
+      "rank": 9.5,
+      "isNew": true
+    }
+  ],
+  "paths": {
+    "claims": "testguard.claims.json",
+    "evidence": ".testguard/evidence.json",
+    "baseline": ".testguard/baseline.json"
+  }
+}

testguard_cli-0.3.1/spec/conformance/invalid/status.write-test-without-target.json

@@ -0,0 +1,54 @@
+{
+  "schemaVersion": 1,
+  "tool": {
+    "name": "testguard",
+    "version": "0.1.0"
+  },
+  "generatedAt": "2026-09-17T02:00:00Z",
+  "state": "unproven",
+  "next": {
+    "action": "write-test",
+    "command": "write a test in test/redact.test.mjs that fails on REDACT-001/F1 and passes on HEAD, then: testguard probe --claim REDACT-001 --include-dirty",
+    "why": "REDACT-001/F1 (critical) survived."
+  },
+  "provisional": false,
+  "counts": {
+    "claims": 2,
+    "faults": 6,
+    "byVerdict": {
+      "killed": 1,
+      "survived": 1,
+      "unverifiable": 1,
+      "nocover": 1,
+      "flaky-defender": 2
+    },
+    "new": 1,
+    "baselined": 4
+  },
+  "stale": [],
+  "changedFaults": [
+    {
+      "claimId": "REDACT-002",
+      "subjectId": "F1",
+      "previousVerdict": "unverifiable",
+      "file": "src/redact.mjs"
+    }
+  ],
+  "findings": [
+    {
+      "fingerprint": "01876384493be6809da455cb1a1c4bc92e7564e9898506d790b9589200502163",
+      "claimId": "REDACT-001",
+      "subjectId": "F1",
+      "verdict": "survived",
+      "severity": "critical",
+      "file": "src/redact.mjs",
+      "rank": 9.5,
+      "isNew": true
+    }
+  ],
+  "paths": {
+    "claims": "testguard.claims.json",
+    "evidence": ".testguard/evidence.json",
+    "baseline": ".testguard/baseline.json"
+  }
+}

{testguard_cli-0.2.1 → testguard_cli-0.3.1}/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']);
+export const KINDS = Object.freeze(['claims', 'evidence', 'baseline', 'ignore', 'calibration', 'brief', 'status']);
 export const PASSING_VERDICTS = Object.freeze(new Set(['killed']));
 
 const ajv = new Ajv2020({ strict: true, allErrors: true });
@@ -96,6 +96,14 @@ const semantic = {
     return errors;
   },
 
+  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.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' });
+    return errors;
+  },
+
   brief(doc) {
     const errors = [];
     if (!doc.text.startsWith(doc.heading)) errors.push({ path: '/text', message: 'text must begin with heading' });

{testguard_cli-0.2.1 → testguard_cli-0.3.1}/spec/schemas/brief.schema.json

@@ -34,6 +34,17 @@
       },
       "additionalProperties": false
     },
+    "next": {
+      "description": "The one action that moves the project forward, as computed by the status document; the brief carries it so an agent reading its session-start context knows what to do, not only what is wrong.",
+      "type": "object",
+      "required": ["action", "command", "why"],
+      "properties": {
+        "action": { "enum": ["scaffold", "probe", "write-test", "baseline", "review-fault-change", "none"] },
+        "command": { "type": "string", "minLength": 1, "maxLength": 1024 },
+        "why": { "type": "string", "minLength": 1, "maxLength": 2000 }
+      },
+      "additionalProperties": false
+    },
     "items": {
       "type": "array",
       "maxItems": 50,

{testguard_cli-0.2.1 → testguard_cli-0.3.1}/spec/schemas/evidence.schema.json

@@ -126,7 +126,11 @@
             "description": { "type": "string", "maxLength": 2000 },
             "file": { "$ref": "urn:guard-spec:v1:common#/$defs/repoPath" },
             "faultClass": { "$ref": "urn:guard-spec:v1:common#/$defs/faultClass" },
-            "producedBy": { "$ref": "urn:guard-spec:v1:common#/$defs/provenance" }
+            "producedBy": { "$ref": "urn:guard-spec:v1:common#/$defs/provenance" },
+            "contentHash": {
+              "description": "sha256 of the subject's content (for a fault: find + newline + replace). Excluded from the fingerprint on purpose, so repairing an anchor does not churn a baseline — and recorded here on purpose, so weakening a fault to make a finding disappear is visible.",
+              "$ref": "urn:guard-spec:v1:common#/$defs/sha256"
+            }
           },
           "additionalProperties": true
         },