testguard-cli 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **Provisional verdicts** (#5). A run with `--confirm` below 3 declares
+  `run.provisional: true` — a spec field whose equivalence with
+  `confirmRuns < 3` the validator enforces both ways. Provisional verdicts
+  print with a `?`, the summary is prefixed `PROVISIONAL`, a warning is
+  printed on stderr, evidence is written to `.testguard/evidence-provisional.json`
+  so the canonical file only ever holds confirmed runs, `brief` warns at the
+  top, and `baseline` refuses provisional evidence unless
+  `--allow-provisional`. A confirmed prior verdict is never reused by a
+  provisional run, nor the reverse.
+
 ## [0.2.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.2.0` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.3.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
@@ -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
@@ -112,7 +114,10 @@ npx testguard-cli scaffold src/x.ts   # propose faults for a file, as a draft to
    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
-   clean there; test files may be dirty); final pass with defaults. By default
+   clean there; test files may be dirty), optionally `--confirm 1` for a fast
+   **provisional** signal — verdicts print with a `?`, evidence goes to
+   `evidence-provisional.json`, and `baseline` refuses it; final pass with
+   defaults. By default
    the stream shows only unproven faults plus a killed count — `--verbose`
    shows every fault. A custom
    runner (`pnpm --filter`, a specific config) goes in
@@ -136,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
@@ -189,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.
 

package/package.json

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

@@ -22,7 +22,11 @@ Rules that follow from the table:
 1. **Green baseline first.** Defenders run N times unmodified before any fault
    is applied. Anything short of N/N pass is `flaky-defender` and stops there.
 2. **Confirm over N runs.** `killed` and `survived` both require exactly N
-   probe runs, all agreeing. Default N is 3.
+   probe runs, all agreeing. Default N is 3. **Fewer than three runs is
+   provisional**: the evidence declares `run.provisional: true`, every
+   rendering marks the verdicts as unconfirmed, and a provisional run is
+   never frozen into a baseline. Provisional runs exist for the fix loop —
+   a fast signal while writing a test — not for a gate.
 3. **Only a test body rejecting the behaviour kills.** A test that fails by
    assertion — or by an exception the fault provoked inside it — counts. A
    timeout does not, and a suite that fails to load does not: neither is
@@ -46,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
 

package/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 —

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']);
+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 });
@@ -45,6 +45,8 @@ const semantic = {
   evidence(doc) {
     const errors = [];
     const n = doc.run.confirmRuns;
+    if (n < 3 && doc.run.provisional !== true) errors.push({ path: '/run/provisional', message: `confirmRuns ${n} is below 3; the run must declare provisional: true` });
+    if (n >= 3 && doc.run.provisional === true) errors.push({ path: '/run/provisional', message: `confirmRuns ${n} is confirmed; provisional must be absent or false` });
     doc.records.forEach((r, i) => {
       const p = `/records/${i}`;
       const expected = fingerprint({ claimId: r.claim.id, subjectId: r.subject.id, file: r.subject.file ?? '', verdict: r.verdict });
@@ -94,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' });

package/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,

package/spec/schemas/evidence.schema.json

@@ -43,6 +43,10 @@
           "type": "integer",
           "minimum": 1
         },
+        "provisional": {
+          "description": "True iff confirmRuns < 3. A provisional run's verdicts are not confirmed: they must not be frozen into a baseline and must be rendered as provisional wherever they appear. Validators enforce the equivalence in both directions.",
+          "type": "boolean"
+        },
         "mode": {
           "description": "`worktree` = faults were applied in a scratch git worktree (default). `in-place` = the user's working tree was mutated and restored.",
           "enum": ["worktree", "in-place"]
@@ -122,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
         },

package/spec/schemas/status.schema.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:guard-spec:v1:status",
+  "title": "Guard spec v1 — status",
+  "description": "The single machine-readable answer to 'where is this project and what should happen next'. Every human rendering (CLI text, agent brief, skill instructions) derives from this document so they cannot disagree. Computed from the claims file, the evidence, the baseline and the current working tree; never from a cached verdict alone.",
+  "type": "object",
+  "required": ["schemaVersion", "tool", "generatedAt", "state", "next", "counts"],
+  "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" },
+    "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"]
+    },
+    "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).",
+      "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 },
+        "target": {
+          "description": "For write-test / review-fault-change: the finding the action is about.",
+          "type": "object",
+          "required": ["claimId", "subjectId"],
+          "properties": {
+            "claimId": { "$ref": "urn:guard-spec:v1:common#/$defs/identifier" },
+            "subjectId": { "$ref": "urn:guard-spec:v1:common#/$defs/identifier" },
+            "file": { "$ref": "urn:guard-spec:v1:common#/$defs/repoPath" },
+            "verdict": { "$ref": "urn:guard-spec:v1:common#/$defs/verdict" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "provisional": { "type": "boolean" },
+    "counts": {
+      "type": "object",
+      "required": ["claims", "faults"],
+      "properties": {
+        "claims": { "type": "integer", "minimum": 0 },
+        "faults": { "type": "integer", "minimum": 0 },
+        "byVerdict": {
+          "type": "object",
+          "propertyNames": { "enum": ["killed", "survived", "nocover", "unverifiable", "timeout", "fault-invalid", "flaky-defender"] },
+          "additionalProperties": { "type": "integer", "minimum": 0 }
+        },
+        "new": { "type": "integer", "minimum": 0 },
+        "baselined": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "stale": {
+      "description": "Why the evidence no longer describes the working tree. Empty when it does.",
+      "type": "array",
+      "items": { "type": "string", "minLength": 1, "maxLength": 512 }
+    },
+    "changedFaults": {
+      "description": "Faults whose find/replace content differs from what the evidence probed. A changed fault that previously survived is the cheapest way to make a finding disappear without a test; it is surfaced, never hidden.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["claimId", "subjectId", "previousVerdict"],
+        "properties": {
+          "claimId": { "$ref": "urn:guard-spec:v1:common#/$defs/identifier" },
+          "subjectId": { "$ref": "urn:guard-spec:v1:common#/$defs/identifier" },
+          "previousVerdict": { "$ref": "urn:guard-spec:v1:common#/$defs/verdict" },
+          "file": { "$ref": "urn:guard-spec:v1:common#/$defs/repoPath" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "findings": {
+      "description": "Unproven findings from the current evidence, ranked, new first, capped.",
+      "type": "array",
+      "maxItems": 50,
+      "items": {
+        "type": "object",
+        "required": ["fingerprint", "claimId", "subjectId", "verdict", "severity", "isNew"],
+        "properties": {
+          "fingerprint": { "$ref": "urn:guard-spec:v1:common#/$defs/sha256" },
+          "claimId": { "$ref": "urn:guard-spec:v1:common#/$defs/identifier" },
+          "subjectId": { "$ref": "urn:guard-spec:v1:common#/$defs/identifier" },
+          "verdict": { "$ref": "urn:guard-spec:v1:common#/$defs/verdict" },
+          "reason": { "type": "string", "maxLength": 256 },
+          "severity": { "$ref": "urn:guard-spec:v1:common#/$defs/severity" },
+          "file": { "$ref": "urn:guard-spec:v1:common#/$defs/repoPath" },
+          "rank": { "type": "number" },
+          "isNew": { "type": "boolean" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "paths": {
+      "type": "object",
+      "properties": {
+        "claims": { "type": "string" },
+        "evidence": { "type": "string" },
+        "provisionalEvidence": { "type": "string" },
+        "baseline": { "type": "string" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

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() } = {}) {
+export function buildBrief(evidence, baseline, { max = 20, generatedAt = new Date().toISOString(), next } = {}) {
   const g = gate(evidence.records, baseline);
   const toItem = (r, isNew) => ({
     fingerprint: r.fingerprint,
@@ -54,8 +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, items, text: '' };
-  doc.text = renderBriefText(doc, { hasBaseline: Boolean(baseline), total: evidence.records.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: '' };
+  doc.text = renderBriefText({ ...doc, provisional: Boolean(evidence.run.provisional) }, { hasBaseline: Boolean(baseline), total: evidence.records.length });
   return doc;
 }
 
@@ -64,9 +64,11 @@ export function renderBriefText(brief, { hasBaseline, total }) {
   const lines = [
     brief.heading,
     '',
+    ...(brief.provisional ? ['**PROVISIONAL** — this evidence came from fewer than three confirmation runs; treat every verdict below as unconfirmed and re-probe with --confirm 3 before acting on it.', ''] : []),
     `testguard ${brief.tool.version}${brief.head ? ` @ ${brief.head.slice(0, 12)}` : ''} — ${brief.summary.claims} claims, ${total} faults probed, ${unproven} unproven` +
       (hasBaseline ? ` (${brief.summary.new} new since baseline).` : ' (no baseline; everything is new).'),
   ];
+  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.');
     return lines.join('\n') + '\n';

package/src/cli.mjs

@@ -11,11 +11,15 @@ import { claimsCommand } from './commands/claims.mjs';
 import { baselineCommand } from './commands/baseline.mjs';
 import { briefCommand } from './commands/brief.mjs';
 import { scaffoldCommand } from './commands/scaffold.mjs';
+import { statusCommand } from './commands/status.mjs';
+import { initCommand } from './commands/init.mjs';
 
 const VERSION = JSON.parse(readFileSync(join(fileURLToPath(import.meta.url), '..', '..', 'package.json'), 'utf8')).version;
 
 const USAGE = `testguard ${VERSION} — proves a test suite defends the claims a project makes
 
+  testguard status [dir]     where the project is and the ONE next action; --json is the machine entry point
+  testguard init [dir]       install the agent layer: skill, session-start hook, AGENTS.md section, .gitignore lines
   testguard claims [dir]     list the claims file and report drift against @claim annotations in code
   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
@@ -33,6 +37,7 @@ probe
   --claim <ID,ID>      probe only these claims; writes .testguard/evidence-partial.json
   --include-dirty      probe the working tree (a snapshot commit) instead of HEAD; uncommitted tests count
   --verbose            also print each killed fault (default: only unproven ones, plus a count)
+                       --confirm below 3 is PROVISIONAL: verdicts print with "?", evidence goes to .testguard/evidence-provisional.json
   --runner-cmd "<cmd>" custom runner; must contain {files} and {out}, e.g. "pnpm vitest run {files} --reporter=json --outputFile={out}"
   --node-modules <dir> node_modules to link into the scratch worktree (or TESTGUARD_NODE_MODULES)
   --in-place           mutate the working tree instead of a scratch worktree
@@ -43,14 +48,17 @@ 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)
+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>
+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
 `;
 
-const COMMANDS = { probe: probeCommand, claims: claimsCommand, baseline: baselineCommand, brief: briefCommand, scaffold: scaffoldCommand };
+const COMMANDS = { probe: probeCommand, claims: claimsCommand, baseline: baselineCommand, brief: briefCommand, scaffold: scaffoldCommand, status: statusCommand, init: initCommand };
 
 export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n'), err: (s) => process.stderr.write(s + '\n') }) {
   let parsed;
@@ -70,6 +78,8 @@ 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 },
+        'allow-provisional': { type: 'boolean', default: false },
+        force: { type: 'boolean', default: false },
         verbose: { type: 'boolean', default: false },
         'runner-cmd': { type: 'string' },
         'node-modules': { type: 'string' },

package/src/commands/baseline.mjs

@@ -3,19 +3,28 @@ import { resolve } from 'node:path';
 import { readSpecDoc, writeSpecDoc } from '../evidence/writer.mjs';
 import { buildBaseline } from '../baseline/baseline.mjs';
 import { evidencePath, baselinePath } from './probe.mjs';
+import { computeStatus } from '../status/status.mjs';
 
-export async function baselineCommand({ projectDir, values }, io) {
+export async function baselineCommand({ projectDir, values, version }, io) {
   const evPath = values.evidence ? resolve(values.evidence) : evidencePath(projectDir);
   if (!existsSync(evPath)) {
     io.err(`no evidence at ${evPath}; run \`testguard probe\` first`);
     return 2;
   }
   const evidence = readSpecDoc('evidence', evPath);
+  if (evidence.run.provisional && !values['allow-provisional']) {
+    io.err(`error: ${evPath} is provisional (confirmRuns ${evidence.run.confirmRuns} < 3); a baseline must be frozen from confirmed evidence. Re-run probe with --confirm 3, or pass --allow-provisional if you accept unconfirmed findings as the frozen contract.`);
+    return 2;
+  }
   const baseline = buildBaseline(evidence);
   const outPath = values.out ? resolve(values.out) : baselinePath(projectDir);
   writeSpecDoc('baseline', outPath, baseline);
   const n = Object.values(baseline.fingerprints).reduce((a, b) => a + b, 0);
-  io.out(`baseline: ${n} unproven finding${n === 1 ? '' : 's'} frozen at ${baseline.head.slice(0, 12)}${baseline.dirty ? ' (working tree was dirty)' : ''} → ${outPath}`);
+  if (values.json) {
+    io.out(JSON.stringify({ ...computeStatus({ projectDir, toolVersion: version }), baseline: { path: outPath, frozen: n } }, null, 2));
+    return 0;
+  }
+  io.out(`baseline: ${n} unproven finding${n === 1 ? '' : 's'} frozen at ${baseline.head.slice(0, 12)}${baseline.dirty ? ' (working tree was dirty)' : ''}${evidence.run.provisional ? ' — FROM PROVISIONAL EVIDENCE (--allow-provisional)' : ''} → ${outPath}`);
   io.out('Commit this file; from now on only new findings gate. Ignore the regenerated ones — add to .gitignore:');
   io.out('  .testguard/evidence.json');
   io.out('  .testguard/brief.json');

package/src/commands/brief.mjs

@@ -2,9 +2,10 @@ 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 { computeStatus } from '../status/status.mjs';
 import { evidencePath, baselinePath } from './probe.mjs';
 
-export async function briefCommand({ projectDir, values }, io) {
+export async function briefCommand({ projectDir, values, version }, io) {
   const evPath = values.evidence ? resolve(values.evidence) : evidencePath(projectDir);
   if (!existsSync(evPath)) {
     // A missing brief must never break an agent's session start.
@@ -20,8 +21,14 @@ export async function briefCommand({ projectDir, values }, io) {
     io.err('--max must be an integer from 1 to 50');
     return 3;
   }
-  const brief = buildBrief(evidence, baseline, { max });
+  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 });
   if (!values.text) writeSpecDoc('brief', values.out ? resolve(values.out) : join(projectDir, '.testguard', 'brief.json'), brief);
-  io.out(brief.text.trimEnd());
+  io.out(values.json ? JSON.stringify(brief, null, 2) : brief.text.trimEnd());
   return 0;
 }

package/src/commands/init.mjs

@@ -0,0 +1,15 @@
+import { initProject } from '../init/init.mjs';
+
+export async function initCommand({ projectDir, values }, io) {
+  const { done, skipped } = initProject({ projectDir, force: values.force });
+  if (values.json) {
+    io.out(JSON.stringify({ done, skipped }, null, 2));
+    return 0;
+  }
+  for (const d of done) io.out(`+ ${d}`);
+  for (const s of skipped) io.out(`= ${s}`);
+  io.out('');
+  io.out('Agents in this project now start with the blind-spot brief and can run `testguard status --json` to learn what to do next.');
+  io.out(done.length ? 'Commit these files.' : 'Nothing to change.');
+  return 0;
+}

package/src/commands/probe.mjs

@@ -4,7 +4,9 @@ import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
 import { probe } from '../probe/probe.mjs';
 import { writeSpecDoc, readSpecDoc } from '../evidence/writer.mjs';
 import { gate } from '../baseline/baseline.mjs';
-import { renderRecord, renderSummary, sortForReport } from '../render.mjs';
+import { renderRecord, renderSummary, sortForReport, PROVISIONAL_WARNING } from '../render.mjs';
+import { computeStatus } from '../status/status.mjs';
+export const provisionalEvidencePath = (projectDir) => join(projectDir, '.testguard', 'evidence-provisional.json');
 
 export const evidencePath = (projectDir) => join(projectDir, '.testguard', 'evidence.json');
 export const baselinePath = (projectDir) => join(projectDir, '.testguard', 'baseline.json');
@@ -23,7 +25,10 @@ export async function probeCommand({ projectDir, values, version }, io) {
   }
   const only = values.claim ? values.claim.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
   // A --claim run is partial evidence; keep it away from the canonical file unless --out says otherwise.
-  const outPath = values.out ? resolve(values.out) : only ? join(projectDir, '.testguard', 'evidence-partial.json') : evidencePath(projectDir);
+  const provisional = confirmRuns < 3;
+  // Provisional and partial runs never overwrite the canonical evidence: only confirmed, complete runs may feed a baseline.
+  const outPath = values.out ? resolve(values.out) : only ? join(projectDir, '.testguard', 'evidence-partial.json') : provisional ? provisionalEvidencePath(projectDir) : evidencePath(projectDir);
+  if (provisional && !values.quiet) io.err(PROVISIONAL_WARNING(confirmRuns));
   const previous = !values['no-reuse'] && existsSync(outPath) ? readSpecDoc('evidence', outPath) : undefined;
   const basePath = values.baseline ? resolve(values.baseline) : baselinePath(projectDir);
   const baseline = existsSync(basePath) ? readSpecDoc('baseline', basePath) : undefined;
@@ -42,19 +47,24 @@ export async function probeCommand({ projectDir, values, version }, io) {
     escalate: !values['no-escalate'],
     toolVersion: version,
     includeDirty: values['include-dirty'],
-    onStage: !values.quiet && process.stderr.isTTY ? ({ claimId, faultId, stage, i, n }) => process.stderr.write(`\r\x1b[K  … ${claimId}/${faultId} ${stage} ${i}/${n}`) : undefined,
-    onProgress: values.quiet ? undefined : (r) => {
+    onStage: !values.quiet && !values.json && process.stderr.isTTY ? ({ claimId, faultId, stage, i, n }) => process.stderr.write(`\r\x1b[K  … ${claimId}/${faultId} ${stage} ${i}/${n}`) : undefined,
+    onProgress: values.quiet || values.json ? undefined : (r) => {
       if (process.stderr.isTTY) process.stderr.write('\r\x1b[K');
-      if (values.verbose || r.verdict !== 'killed') io.out(renderRecord(r) + (r.reusedFrom ? '  (reused)' : ''));
+      if (values.verbose || r.verdict !== 'killed') io.out(renderRecord(r, { provisional }) + (r.reusedFrom ? '  (reused)' : ''));
     },
   });
   writeSpecDoc('evidence', outPath, evidence);
 
   const g = gate(evidence.records, baseline, { severityFloor: values.severity });
+  if (values.json) {
+    const status = computeStatus({ projectDir, toolVersion: version });
+    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;
+  }
   if (!values.quiet && baseline) {
     io.out('');
     const tag = (r) => (g.new.includes(r) ? '[NEW]      ' : g.baselined.includes(r) ? '[baseline] ' : '[below floor] ');
-    for (const r of sortForReport(evidence.records).filter((x) => x.verdict !== 'killed')) io.out('  ' + tag(r) + renderRecord(r));
+    for (const r of sortForReport(evidence.records).filter((x) => x.verdict !== 'killed')) io.out('  ' + tag(r) + renderRecord(r, { provisional }));
   }
   io.out('');
   if (!values.quiet && !values.verbose) {
@@ -62,6 +72,7 @@ export async function probeCommand({ projectDir, values, version }, io) {
     if (killed) io.out(`  ${killed} killed (not listed; --verbose to see them)`);
   }
   io.out(renderSummary(evidence.records, evidence.run) + (baseline ? ` ${g.new.length} new since baseline, ${g.baselined.length} baselined.` : ' No baseline.'));
-  io.out(`evidence: ${outPath}${only ? ` (partial: --claim ${only.join(',')}; not the canonical evidence file)` : ''}`);
+  io.out(`evidence: ${outPath}${only ? ` (partial: --claim ${only.join(',')}; not the canonical evidence file)` : provisional ? ' (provisional; not the canonical evidence file)' : ''}`);
+  if (provisional && !values.quiet) io.err(PROVISIONAL_WARNING(confirmRuns));
   return g.new.length > 0 ? 1 : 0;
 }

package/src/commands/status.mjs

@@ -0,0 +1,10 @@
+import { computeStatus, renderStatus } from '../status/status.mjs';
+import { validate } from '../../spec/lib/validate.mjs';
+
+export async function statusCommand({ projectDir, values, version }, io) {
+  const doc = computeStatus({ projectDir, toolVersion: version });
+  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));
+  return doc.state === 'clean' ? 0 : doc.state === 'no-claims' || doc.state === 'unprobed' ? 2 : 1;
+}

package/src/init/init.mjs

@@ -0,0 +1,78 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const TEMPLATES = join(dirname(fileURLToPath(import.meta.url)), 'templates');
+const HOOK_CMD = 'npx -y testguard-cli brief --text';
+const AGENTS_BEGIN = '<!-- testguard:begin -->';
+const AGENTS_END = '<!-- testguard:end -->';
+const AGENTS_BLOCK = `${AGENTS_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.
+${AGENTS_END}`;
+const GITIGNORE_LINES = ['.testguard/evidence.json', '.testguard/evidence-provisional.json', '.testguard/evidence-partial.json', '.testguard/brief.json', '.testguard/scaffold-*.json'];
+
+/**
+ * Install the agent operating layer into a consumer project: the skill, the
+ * session-start hook, an AGENTS.md section and the .gitignore lines.
+ * Idempotent: re-running changes nothing unless --force replaces the skill.
+ */
+export function initProject({ projectDir, force = false }) {
+  const done = [];
+  const skipped = [];
+
+  const skillDir = join(projectDir, '.claude', 'skills', 'testguard');
+  const skillPath = join(skillDir, 'SKILL.md');
+  if (!existsSync(skillPath) || force) {
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(skillPath, readFileSync(join(TEMPLATES, 'SKILL.md'), 'utf8'));
+    done.push(`.claude/skills/testguard/SKILL.md${force && existsSync(skillPath) ? ' (replaced)' : ''}`);
+  } else {
+    skipped.push('.claude/skills/testguard/SKILL.md exists (use --force to replace)');
+  }
+
+  const settingsPath = join(projectDir, '.claude', 'settings.json');
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    } catch (e) {
+      throw new Error(`.claude/settings.json is not valid JSON (${e.message}); fix it before init can add the hook`);
+    }
+  }
+  settings.hooks ??= {};
+  settings.hooks.SessionStart ??= [];
+  const already = JSON.stringify(settings.hooks.SessionStart).includes(HOOK_CMD);
+  if (already) {
+    skipped.push('SessionStart hook already present in .claude/settings.json');
+  } else {
+    settings.hooks.SessionStart.push({ hooks: [{ type: 'command', command: HOOK_CMD }] });
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    done.push('.claude/settings.json: SessionStart hook → brief --text');
+  }
+
+  const agentsPath = join(projectDir, 'AGENTS.md');
+  const agents = existsSync(agentsPath) ? readFileSync(agentsPath, 'utf8') : '';
+  if (agents.includes(AGENTS_BEGIN)) {
+    skipped.push('AGENTS.md already has the TestGuard section');
+  } else {
+    writeFileSync(agentsPath, (agents ? agents.replace(/\s*$/, '\n\n') : '# Agent instructions\n\n') + AGENTS_BLOCK + '\n');
+    done.push(agents ? 'AGENTS.md: TestGuard section appended' : 'AGENTS.md created with the TestGuard section');
+  }
+
+  const giPath = join(projectDir, '.gitignore');
+  const gi = existsSync(giPath) ? readFileSync(giPath, 'utf8') : '';
+  const missing = GITIGNORE_LINES.filter((l) => !gi.split('\n').some((x) => x.trim() === l));
+  if (missing.length) {
+    writeFileSync(giPath, (gi ? gi.replace(/\s*$/, '\n') : '') + '# TestGuard: regenerated per run (baseline.json IS committed)\n' + missing.join('\n') + '\n');
+    done.push(`.gitignore: ${missing.length} line${missing.length === 1 ? '' : 's'} added`);
+  } else {
+    skipped.push('.gitignore already ignores the regenerated files');
+  }
+  return { done, skipped };
+}

package/src/init/templates/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: testguard
+description: Prove the test suite defends this project's claims. Use before writing or changing tests, after changing guarded code, and whenever a session starts with a TEST BLINDSPOT CONTEXT block.
+---
+
+# TestGuard — how an agent runs it
+
+TestGuard injects the faults a project's claims forbid and reports every one
+the tests fail to detect. It is a **claim verifier**, not a test generator.
+You operate it through one loop and one source of truth.
+
+## The one source of truth
+
+```bash
+testguard status --json
+```
+
+Read `state` and `next`. Do what `next.command` says. Never infer state from
+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` |
+| `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.
+
+## Verdict → action
+
+| verdict | what it means | the only acceptable fix |
+|---|---|---|
+| `SURVIVED` | the defenders stayed green while the claim was false | **write a test** in the defender file that fails with the fault applied and passes on HEAD |
+| `SURVIVED [killed-by-undeclared-tests: …]` | other tests catch it | add those files to the claim's `defendedBy` |
+| `NOCOVER` | no test file imports the target | write a new test file that imports it and asserts the claim |
+| `UNVERIFIABLE` | the fault's anchor no longer matches, or the defenders fail to load | fix the **fault definition** (or the defenders' import); never the code |
+| `FAULT-INVALID` | the replacement does not compile | fix the fault definition |
+| `TIMEOUT` | the fault makes the code hang | write an assertion that fails on it; a hang is not a detection |
+| `FLAKY-DEFENDER` | defenders not green 3/3, or disagreed across runs | fix the flake first; no verdict is trustworthy until then |
+
+## The fix loop
+
+1. `testguard status --json` → take `next.target`.
+2. Write the test. It must **fail when the fault is applied and pass on HEAD**. To check the first half by hand: apply `find` → `replace` in the target file, run the defender, restore.
+3. `testguard probe --claim <ID> --include-dirty` — probes your uncommitted test without touching the tree. `--confirm 1` gives a fast **provisional** signal; a `?` on a verdict means unconfirmed.
+4. When it is `killed` at `--confirm 3`, commit the test.
+5. When everything is killed or baselined, `testguard baseline` if `next` says so, and commit `.testguard/baseline.json`.
+
+## Rules that are not yours to bend
+
+- **Never make a fault die by editing the claims file.** Editing a claim is allowed when the claim was wrong — but the evidence records every fault's content hash, and `status` lists any fault edited after it survived, with its previous verdict, as `changedFaults`. The change is permitted; it is never invisible. Say why in the commit.
+- **A test that asserts current behaviour is not a fix.** If the test would pass with the fault applied, it defends nothing.
+- **Never re-implement the code under test inside the test.** Drive the real function; assert the outcome, not that a function was called.
+- `--confirm 1` results are provisional: they print with `?`, go to `evidence-provisional.json`, and cannot be baselined.
+- Worktree mode probes a **commit**. If `probe` refuses because defenders are dirty, use `--include-dirty`; do not commit half-written tests to satisfy it.
+- Do not add `.testguard/evidence.json` or `brief.json` to git; do commit `baseline.json`.
+
+## Reading the numbers
+
+`N unproven faults across M claims` counts faults and the claims they belong to. There is no single score on purpose: blindness is concentrated, and one number hides where.

package/src/probe/probe.mjs

@@ -132,6 +132,7 @@ export async function probe({
       repo: { head, dirty: isDirty(root), ...(snapshot ? { snapshot } : {}) },
       runner: { name: vitest.name, ...((runnerVersion ?? readRunnerVersion(projectDir)) ? { version: runnerVersion ?? readRunnerVersion(projectDir) } : {}) },
       confirmRuns,
+      ...(confirmRuns < 3 ? { provisional: true } : {}),
       mode,
     },
     records,
@@ -232,7 +233,7 @@ async function probeOne({ claim, fault, defenders, discovered, allTests, iso, co
   return {
     fingerprint: fingerprint({ claimId: claim.id, subjectId: fault.id, file: fault.file, verdict }),
     claim: { id: claim.id, statement: claim.statement, severity: claim.severity, source: claim.source, producedBy: claim.producedBy },
-    subject: { kind: 'fault', id: fault.id, description: fault.description, file: fault.file, faultClass: fault.faultClass, producedBy: fault.producedBy },
+    subject: { kind: 'fault', id: fault.id, description: fault.description, file: fault.file, faultClass: fault.faultClass, producedBy: fault.producedBy, contentHash: sha256(`${fault.find}\n${fault.replace}`) },
     verdict,
     detail,
     defenders: { requested: claim.defendedBy ?? [], resolved: defenders, nocover: defenders.length === 0, ...(discovered ? { discovered: true } : {}) },

package/src/render.mjs

@@ -1,10 +1,12 @@
 const ORDER = ['survived', 'nocover', 'unverifiable', 'fault-invalid', 'timeout', 'flaky-defender', 'killed'];
 
 /** Non-passing verdicts shout; the one pass does not. */
-export const formatVerdict = (v) => (v === 'killed' ? 'killed' : v.toUpperCase());
+export const formatVerdict = (v, provisional = false) => (v === 'killed' ? 'killed' : v.toUpperCase()) + (provisional ? '?' : '');
 
-export function renderRecord(r) {
-  const head = `${formatVerdict(r.verdict).padEnd(15)} ${r.claim.id}/${r.subject.id}`.padEnd(38);
+export const PROVISIONAL_WARNING = (n) => `PROVISIONAL — confirmRuns ${n} (< 3): nothing below is confirmed. Verdicts carry a "?"; this evidence cannot be frozen into a baseline. Re-run with --confirm 3 before trusting it.`;
+
+export function renderRecord(r, { provisional = false } = {}) {
+  const head = `${formatVerdict(r.verdict, provisional).padEnd(15)} ${r.claim.id}/${r.subject.id}`.padEnd(38);
   let why = '';
   if (r.detail.reason === 'killed-by-undeclared-tests' && r.detail.undeclaredKillers?.length) {
     const files = [...new Set(r.detail.undeclaredKillers.map((k) => k.split('::')[0]))];
@@ -26,11 +28,11 @@ export function summarize(records) {
 
 export function renderSummary(records, run) {
   const byVerdict = summarize(records);
-  const parts = ORDER.filter((v) => byVerdict[v]).map((v) => `${byVerdict[v]} ${formatVerdict(v)}`);
+  const parts = ORDER.filter((v) => byVerdict[v]).map((v) => `${byVerdict[v]} ${formatVerdict(v, run?.provisional)}`);
   const unproven = records.filter((r) => r.verdict !== 'killed');
   const claims = new Set(unproven.map((r) => r.claim.id)).size;
   const where = run ? ` Probed ${run.repo.snapshot ? `working tree (snapshot ${run.repo.snapshot.slice(0, 7)} of ${run.repo.head.slice(0, 7)})` : run.mode === 'in-place' ? `in place at ${run.repo.head.slice(0, 7)}${run.repo.dirty ? ' (dirty)' : ''}` : run.repo.head.slice(0, 7)}.` : '';
-  return `${records.length} faults probed: ${parts.join(', ')}. ${unproven.length} unproven fault${unproven.length === 1 ? '' : 's'} across ${claims} claim${claims === 1 ? '' : 's'}.${where}`;
+  return `${run?.provisional ? 'PROVISIONAL: ' : ''}${records.length} faults probed: ${parts.join(', ')}. ${unproven.length} unproven fault${unproven.length === 1 ? '' : 's'} across ${claims} claim${claims === 1 ? '' : 's'}.${where}`;
 }
 
 /** Survivors first, then by rank score; killed last. */

package/src/status/status.mjs

@@ -0,0 +1,163 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { readSpecDoc } from '../evidence/writer.mjs';
+import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
+import { gate } from '../baseline/baseline.mjs';
+import { hashFile, sha256 } from '../util/hash.mjs';
+import { resolveDefenders } from '../probe/runner-vitest.mjs';
+import { discoverDefenders } from '../probe/discover.mjs';
+import { sortForReport } from '../render.mjs';
+
+export const faultContentHash = (fault) => sha256(`${fault.find}\n${fault.replace}`);
+
+const P = (projectDir) => ({
+  claims: defaultClaimsPath(projectDir),
+  evidence: join(projectDir, '.testguard', 'evidence.json'),
+  provisional: join(projectDir, '.testguard', 'evidence-provisional.json'),
+  baseline: join(projectDir, '.testguard', 'baseline.json'),
+});
+
+/**
+ * The single answer to "where is this project and what happens next".
+ * 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 }) {
+  const rel = (p) => relative(projectDir, p) || '.';
+  const doc = {
+    schemaVersion: 1,
+    tool: { name: 'testguard', version: toolVersion },
+    generatedAt,
+    state: 'no-claims',
+    next: { action: 'scaffold', command: 'testguard scaffold <source-file>', why: 'No testguard.claims.json in this project. Scaffold proposes faults for a file; state what each guarantees, then probe.' },
+    provisional: false,
+    counts: { claims: 0, faults: 0 },
+    stale: [],
+    changedFaults: [],
+    findings: [],
+    paths: {},
+  };
+  if (!existsSync(paths.claims)) return doc;
+  doc.paths.claims = rel(paths.claims);
+
+  const claims = loadClaims(paths.claims);
+  doc.counts.claims = claims.claims.length;
+  doc.counts.faults = claims.claims.reduce((n, c) => n + c.faults.length, 0);
+  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 });
+
+  const hasEvidence = existsSync(paths.evidence);
+  const hasProvisional = existsSync(paths.provisional);
+  if (hasProvisional) doc.paths.provisionalEvidence = rel(paths.provisional);
+  if (!hasEvidence) {
+    if (hasProvisional) {
+      doc.state = 'provisional-only';
+      doc.provisional = true;
+      doc.next = { action: 'probe', command: 'testguard probe --confirm 3', why: 'Only provisional (sub-N) evidence exists; nothing is confirmed until the defenders agree three times.' };
+    } else {
+      doc.state = 'unprobed';
+      doc.next = { action: 'probe', command: 'testguard probe', why: `${doc.counts.claims} claims / ${doc.counts.faults} faults have never been probed.` };
+    }
+    return doc;
+  }
+  doc.paths.evidence = rel(paths.evidence);
+  const evidence = readSpecDoc('evidence', paths.evidence);
+  const baseline = existsSync(paths.baseline) ? readSpecDoc('baseline', paths.baseline) : undefined;
+  if (baseline) doc.paths.baseline = rel(paths.baseline);
+
+  // ── Staleness: does the evidence still describe this claims file and this tree? ──
+  const probed = new Map(evidence.records.map((r) => [`${r.claim.id}/${r.subject.id}`, r]));
+  for (const key of faultIndex.keys()) if (!probed.has(key)) doc.stale.push(`fault ${key} has never been probed`);
+  for (const [key, r] of probed) {
+    const cur = faultIndex.get(key);
+    if (!cur) { doc.stale.push(`fault ${key} was probed but is no longer in the claims file`); continue; }
+    if (r.subject.contentHash && r.subject.contentHash !== faultContentHash(cur.fault)) {
+      doc.changedFaults.push({ claimId: cur.claim.id, subjectId: cur.fault.id, previousVerdict: r.verdict, file: cur.fault.file });
+      doc.stale.push(`fault ${key} changed since it was probed (was ${r.verdict})`);
+    }
+    const target = join(projectDir, cur.fault.file);
+    if (existsSync(target) && hashFile(target) !== r.inputs.targetHash) doc.stale.push(`${cur.fault.file} changed since ${key} was probed`);
+    const defenders = cur.claim.defendedBy?.length ? resolveDefenders(projectDir, cur.claim.defendedBy) : discoverDefenders(projectDir, cur.fault.file);
+    for (const d of defenders) {
+      const h = r.inputs.defenderHashes[d];
+      if (!h) doc.stale.push(`${d} now defends ${key} but was not probed`);
+      else if (existsSync(join(projectDir, d)) && hashFile(join(projectDir, d)) !== h) doc.stale.push(`${d} changed since ${key} was probed`);
+    }
+  }
+  doc.stale = [...new Set(doc.stale)];
+
+  // ── Findings, gated against the baseline ──
+  const g = gate(evidence.records, baseline);
+  const counts = {};
+  for (const r of evidence.records) counts[r.verdict] = (counts[r.verdict] ?? 0) + 1;
+  doc.counts.byVerdict = counts;
+  doc.counts.new = g.new.length + g.belowFloor.length;
+  doc.counts.baselined = g.baselined.length;
+  const ranked = sortForReport([...g.new, ...g.belowFloor, ...g.baselined]);
+  doc.findings = ranked.slice(0, max).map((r) => ({
+    fingerprint: r.fingerprint, claimId: r.claim.id, subjectId: r.subject.id, verdict: r.verdict,
+    ...(r.detail.reason ? { reason: r.detail.reason } : {}), severity: r.claim.severity,
+    ...(r.subject.file ? { file: r.subject.file } : {}), ...(r.rank ? { rank: r.rank.score } : {}),
+    isNew: !g.baselined.includes(r),
+  }));
+
+  // ── State and next ──
+  const changedSurvivor = doc.changedFaults.find((c) => c.previousVerdict !== 'killed');
+  if (changedSurvivor) {
+    doc.state = 'evidence-stale';
+    doc.next = {
+      action: 'review-fault-change',
+      command: `testguard probe --claim ${changedSurvivor.claimId} --include-dirty`,
+      why: `Fault ${changedSurvivor.claimId}/${changedSurvivor.subjectId} was edited after it ${changedSurvivor.previousVerdict}. Editing a claim is allowed, but a weakened fault is the cheapest way to make a finding vanish without a test — confirm the edit is a correction, then re-probe.`,
+      target: { claimId: changedSurvivor.claimId, subjectId: changedSurvivor.subjectId, file: changedSurvivor.file, verdict: changedSurvivor.previousVerdict },
+    };
+    return doc;
+  }
+  if (doc.stale.length) {
+    doc.state = 'evidence-stale';
+    doc.next = { action: 'probe', command: 'testguard probe --include-dirty', why: `${doc.stale.length} input${doc.stale.length === 1 ? '' : 's'} changed since the evidence was taken: ${doc.stale.slice(0, 3).join('; ')}${doc.stale.length > 3 ? '; …' : ''}.` };
+    return doc;
+  }
+  const top = doc.findings.find((f) => f.isNew);
+  if (top) {
+    doc.state = 'unproven';
+    const cur = faultIndex.get(`${top.claimId}/${top.subjectId}`);
+    const defenders = cur.claim.defendedBy?.length ? resolveDefenders(projectDir, cur.claim.defendedBy) : discoverDefenders(projectDir, cur.fault.file);
+    const where = defenders[0] ?? `a new test file that imports ${cur.fault.file}`;
+    const whyByVerdict = {
+      survived: `${top.claimId}/${top.subjectId} (${top.severity}) survived: "${cur.claim.statement}" can be false with the suite green.`,
+      nocover: `${top.claimId}/${top.subjectId} (${top.severity}) has no defender: no test file imports ${cur.fault.file}.`,
+      unverifiable: `${top.claimId}/${top.subjectId} cannot be probed (${top.reason ?? 'anchor'}); fix the fault definition in testguard.claims.json, not the code.`,
+      'fault-invalid': `${top.claimId}/${top.subjectId}'s replacement does not load; fix the fault definition.`,
+      timeout: `${top.claimId}/${top.subjectId} makes the defenders hang; a hang is not a detection — write an assertion that fails on it.`,
+      'flaky-defender': `${top.claimId}/${top.subjectId}'s defenders are not reliably green (${top.reason ?? ''}); fix the flake before any verdict can be trusted.`,
+    };
+    const fixClaim = ['unverifiable', 'fault-invalid'].includes(top.verdict);
+    doc.next = {
+      action: fixClaim ? 'probe' : 'write-test',
+      command: fixClaim
+        ? `edit ${top.claimId}/${top.subjectId} in testguard.claims.json, then: testguard probe --claim ${top.claimId} --include-dirty`
+        : `write a test in ${where} that fails on ${top.claimId}/${top.subjectId} and passes on HEAD, then: testguard probe --claim ${top.claimId} --include-dirty`,
+      why: whyByVerdict[top.verdict] ?? `${top.claimId}/${top.subjectId} is ${top.verdict}.`,
+      target: { claimId: top.claimId, subjectId: top.subjectId, ...(top.file ? { file: top.file } : {}), verdict: top.verdict },
+    };
+    return doc;
+  }
+  doc.state = 'clean';
+  const unprovenTotal = evidence.records.filter((r) => r.verdict !== 'killed').length;
+  if (unprovenTotal > 0 && !baseline) {
+    doc.next = { action: 'baseline', command: 'testguard baseline', why: `${unprovenTotal} unproven finding${unprovenTotal === 1 ? '' : 's'} with no baseline; freeze them so only new ones gate from here.` };
+  } else {
+    doc.next = { action: 'none', command: 'testguard probe', why: unprovenTotal ? `${unprovenTotal} baselined finding${unprovenTotal === 1 ? '' : 's'} remain; nothing new. Re-probe after changing code, tests or claims.` : 'Every claim is defended. Re-probe after changing code, tests or claims; add a claim for every new invariant.' };
+  }
+  return doc;
+}
+
+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` : '')];
+  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}`);
+  lines.push(`why:      ${doc.next.why}`);
+  return lines.join('\n');
+}