testguard-cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-17
+
+First release. A claim verifier, not a test generator.
+
+### Added
+
+- **Contract spine** (`spec/`): six shared JSON Schemas — claims, evidence,
+  baseline, ignore, calibration, brief — identified as `urn:guard-spec:v1:*`,
+  with a validator that enforces the semantic rules a schema cannot express,
+  a single fingerprint derivation, `GATE-SEMANTICS.md`, and a conformance
+  corpus (one valid document per kind, 22 must-reject documents).
+- **`testguard claims`** — validates the claims file and reports drift
+  against `@claim <ID>` annotations in source.
+- **`testguard probe`** — applies each fault in a scratch git worktree,
+  confirms the defenders green N times, runs them N times with the fault,
+  escalates survivors to the whole suite with N-run attribution, restores,
+  classifies into a closed verdict set (`killed`, `survived`, `nocover`,
+  `unverifiable`, `timeout`, `fault-invalid`, `flaky-defender`), ranks, and
+  writes evidence validated against the spec. `--ref` pins the probed commit.
+  Verdicts are reused when the target, defenders and N are unchanged.
+- **`testguard baseline`** — freezes every non-passing fingerprint so only
+  new findings gate; severity floor via `--severity`.
+- **`testguard brief`** — a ranked, capped `## TEST BLINDSPOT CONTEXT` block
+  for an agent's session start; `--text` is hook-safe.
+- **Known-answer fixture** with a genuine `objectContaining` blind spot and a
+  case for every verdict; probed end to end in the test suite and in CI.
+- **Self-verification**: `testguard.claims.json` states invariants of the
+  tool itself, probed by the tool in CI.
+- Distribution: npm (`testguard-cli`), PyPI wrapper (`testguard-cli`),
+  GitHub Action, Homebrew formula (staged), pre-commit hooks.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricardo Accioly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# TestGuard
+
+[![CI](https://github.com/raccioly/testguard/actions/workflows/ci.yml/badge.svg)](https://github.com/raccioly/testguard/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/testguard-cli.svg)](https://www.npmjs.com/package/testguard-cli)
+[![PyPI](https://img.shields.io/pypi/v/testguard-cli.svg)](https://pypi.org/project/testguard-cli/)
+[![node](https://img.shields.io/node/v/testguard-cli.svg)](https://nodejs.org)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![zero deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen.svg)](./package.json)
+
+> Proves that a test suite actually defends the claims a project makes — by
+> injecting the faults those claims say cannot happen, and reporting every
+> fault the tests fail to detect.
+
+**Not a test generator. A claim verifier.** Test generation is what happens
+after a claim turns out to be unfalsifiable.
+
+Third tool following the Guard pattern, alongside
+[`docguard-cli`](https://www.npmjs.com/package/docguard-cli) (docs ↔ code) and
+[`websec-validator`](https://pypi.org/project/websec-validator/) (attack
+surface ↔ code). All three run one loop:
+
+> declare what must be true → try mechanically to falsify it → freeze a
+> baseline → gate only the delta → brief the agent before it writes code.
+
+## Why
+
+Coverage cannot tell a test that pins *correct* behaviour from one that pins
+a *defect*. An agent that writes both the code and its tests encodes whatever
+it believed — including its bugs — and the suite goes green.
+
+Measured on a real, entirely AI-authored production codebase with ~4,900
+disciplined tests (no snapshots, 0.4% zero-assertion): **8 of 9 real
+historical bugs were invisible to the suite**, worst case 2,451 tests green
+on known-broken code. The largest gap was a compliance-critical path with
+100% coverage, where the one assertion that mattered used
+`expect.objectContaining({...})` and omitted the field carrying the data.
+
+## Install
+
+| How | Command |
+|---|---|
+| npx (no install) | `npx testguard-cli probe` |
+| 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.1.0` — see [`action.yml`](./action.yml) |
+| pre-commit | `repo: https://github.com/raccioly/testguard`, hooks `testguard-claims`, `testguard-probe` |
+
+## How it works
+
+```bash
+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
+npx testguard-cli brief       # tell the agent where the suite is blind, before it writes
+```
+
+1. **Claims** live in `testguard.claims.json`: a statement, where it comes
+   from, which tests supposedly defend it, and one or more *faults* — each a
+   deterministic source change that would make the statement false. Every
+   claim and every fault records who produced it. `testguard claims`
+   validates the file and reports drift against `@claim <ID>` annotations in
+   source.
+2. **Probe** confirms the defenders are green N times unmodified, applies
+   each fault in a scratch git worktree (your tree is never touched), runs
+   the defenders N times, re-runs survivors against the whole suite with
+   N-run attribution, restores, and classifies. Verdicts are a closed set:
+
+   | Verdict | Meaning |
+   |---|---|
+   | `killed` | a test body rejected the behaviour, N/N — the only pass |
+   | `SURVIVED` | the defenders stayed green while the claim was false |
+   | `NOCOVER` | no test file defends the claim at all |
+   | `UNVERIFIABLE` | the fault's anchor is missing or ambiguous — loud, never a skip |
+   | `TIMEOUT` | the defenders hung; a hang is not a detection |
+   | `FAULT-INVALID` | the replacement does not load — a bad fault, not a finding |
+   | `FLAKY-DEFENDER` | the defenders are not reliably green, or disagreed across runs |
+
+   Never a single score. Findings are ranked by severity, claim provenance
+   and blast radius, and written to `.testguard/evidence.json` — validated
+   against the spec before it is written.
+3. **Baseline** freezes every non-passing fingerprint. Later probes suppress
+   what was already known and exit non-zero only on what is new. Claims whose
+   source and defenders are unchanged reuse their prior verdict, so a probe
+   in CI costs only what changed.
+4. **Brief** turns evidence plus baseline into a ranked, capped
+   `## TEST BLINDSPOT CONTEXT` block. Wire it into an agent's session start
+   — for Claude Code, in `.claude/settings.json`:
+
+   ```json
+   { "hooks": { "SessionStart": [ { "hooks": [
+     { "type": "command", "command": "npx testguard-cli brief --text" }
+   ] } ] } }
+   ```
+
+   `--text` prints only, and exits 0 silently when there is no evidence yet,
+   so the hook can never break a session.
+
+**Commit `.testguard/baseline.json`; ignore `evidence.json` and `brief.json`.**
+The baseline is the frozen contract; the other two are regenerated per run.
+
+The fault model is the auditable artifact. You never reach 100% of
+correctness; you reach **100% of stated claims verified**, and the statement
+of claims is what an assessor reads. A claims file is code — its `replace`
+strings run under your test runner — so review it like code.
+
+## Try it
+
+The repository ships a known-answer fixture with a real blind spot:
+
+```bash
+git clone <this repo> && cd testguard && npm install
+npm test                                  # includes probing the fixture end to end
+```
+
+`fixtures/known-answer/` is a tiny project whose audit-row test asserts with
+`expect.objectContaining({...})` and omits the `content` key. Swap the
+redacted text for the raw input and the test stays green. `probe` reports it
+as `SURVIVED`; the fixture's [README](fixtures/known-answer/README.md) walks
+through every verdict.
+
+## Status
+
+**v0.1.** Four commands, vitest runner, hand-authored faults. The contract
+spine — six JSON Schemas shared with the other Guard tools — is under
+[`spec/`](spec/). Zero runtime dependencies; Node ≥ 20.
+
+Not yet: test generation (the two-gate acceptance loop), other runners,
+mechanical fault producers, and calibration of fault classes against real
+escaped bugs. Each is designed for; none is claimed.
+
+## Licence
+
+MIT.

package/cli/testguard.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.mjs';
+
+main(process.argv.slice(2)).then((code) => {
+  process.exitCode = code;
+});

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "testguard-cli",
+  "version": "0.1.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",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "cli",
+    "src",
+    "spec/schemas",
+    "spec/lib",
+    "spec/GATE-SEMANTICS.md",
+    "spec/README.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "testguard": "node cli/testguard.mjs",
+    "claims": "node cli/testguard.mjs claims",
+    "probe": "node cli/testguard.mjs probe",
+    "baseline": "node cli/testguard.mjs baseline",
+    "brief": "node cli/testguard.mjs brief",
+    "test": "vitest run",
+    "test:spec": "vitest run spec/conformance",
+    "self:probe": "node cli/testguard.mjs probe . --budget 180000",
+    "release:sync": "node .github/scripts/sync-release-version.mjs",
+    "prepublishOnly": "node cli/testguard.mjs --version && node .github/scripts/sync-release-version.mjs --check"
+  },
+  "keywords": [
+    "testing",
+    "fault-injection",
+    "mutation-testing",
+    "test-quality",
+    "claims",
+    "verification",
+    "vitest",
+    "ai-agents",
+    "test-generation",
+    "claim-verification",
+    "github-actions",
+    "quality-gate"
+  ],
+  "devDependencies": {
+    "ajv": "^8.20.0",
+    "vitest": "^5.0.1"
+  },
+  "bin": {
+    "testguard": "cli/testguard.mjs"
+  },
+  "author": "Ricardo Accioly <raccioly@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raccioly/testguard.git"
+  },
+  "homepage": "https://github.com/raccioly/testguard#readme",
+  "bugs": {
+    "url": "https://github.com/raccioly/testguard/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/spec/GATE-SEMANTICS.md

@@ -0,0 +1,89 @@
+# Gate semantics
+
+How a Guard-spec tool decides whether CI goes red. Shared by every tool that
+adopts the spec; each tool may add stricter rules, never looser ones.
+
+## Verdicts
+
+The verdict set is closed. Only one value is a pass.
+
+| Verdict | Meaning | Gates by default |
+|---|---|---|
+| `killed` | Fault applied; every one of N probe runs failed with a genuine assertion failure, on a defender set that was green N/N unmodified. | no |
+| `survived` | Fault applied; every one of N probe runs passed. The claim is **unproven**. | **yes** |
+| `nocover` | No defending test exists: the declared globs resolve to nothing, or no test imports the subject. Worse than `survived` — nothing was even tried. | **yes** |
+| `unverifiable` | The fault could not be applied: anchor missing or ambiguous. Carries a `reason`. This is a loud, gating verdict — a claim that cannot be probed is not "skipped", it is undefended until someone re-authors the fault. | **yes** |
+| `timeout` | Probe run exceeded its budget. Not counted as a kill; the pessimistic reading is the safe one because flakiness biases the metric optimistically. | **yes** |
+| `fault-invalid` | The replacement does not load or compile. A bad fault, not a detection. | **yes** |
+| `flaky-defender` | Defenders were not green N/N on unmodified source (`defenders-not-green`), or the N probe runs disagreed with each other (`inconsistent-probe`). Either way no verdict about the fault can be trusted; fix the defenders first. | **yes** |
+
+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.
+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
+   evidence that the suite defends the claim. Tools parse the runner's
+   structured report, never its exit code, because the exit code cannot tell
+   these apart.
+4. **A mixed result is not a kill.** If some of the N probe runs fail and
+   others pass, the defender's response to the fault is nondeterministic.
+   Reporting `killed` would be the optimistic bias flakiness introduces;
+   reporting `survived` would be wrong the other way. It is `flaky-defender`.
+5. **Escalation never upgrades a verdict.** A fault that survives its declared
+   defenders may be re-run against the whole suite. If the wider suite kills
+   it, the verdict stays `survived` with reason `killed-by-undeclared-tests`:
+   the claim's stated evidence chain is broken even though the suite is not
+   blind. It gates, and ranks below a true survivor.
+6. **Never a single global score.** Output is per claim, ranked. Blindness is
+   concentrated, and one number hides where.
+
+## Baseline and delta
+
+A baseline freezes the fingerprints of every non-passing finding at a point
+in time. On later runs:
+
+- A finding whose fingerprint appears in the baseline is **baselined** and
+  suppressed, up to the stored `count`.
+- Any other non-passing finding is **new** and gates.
+- `killed` findings are never fingerprinted; a baseline holds only debt.
+
+The fingerprint is `sha256(claimId \n subjectId \n file \n verdict)`. It is
+derived from identities and outcome, never from the fault's `find`/`replace`
+text, so repairing a rotted anchor does not churn the baseline — while a
+change of verdict on the same claim+subject does surface as new.
+
+Adopting tools may reconcile an existing baseline format (for example a
+`{version, fingerprints:{hash:count}}` file) by mapping it onto this shape;
+the suppress-up-to-count semantics are identical.
+
+## Ignore and annotations
+
+- An ignore entry removes a subject from *scope* before probing. Every entry
+  carries a `reason` of at least eight characters; the structured form is what
+  an auditor reads. A plain gitignore-syntax file may be accepted as shorthand
+  for reasonless `path` entries.
+- An annotation is **strictly additive**. It never changes, suppresses, or
+  drops a finding. Ranking may read annotations; verdicts never do.
+
+## Severity floor
+
+`--severity <level>` gates only findings whose claim severity is at or above
+the level. Findings below the floor are still reported and still written to
+evidence; they simply do not turn CI red.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | No new gating findings at or above the severity floor. |
+| `1` | At least one new gating finding. |
+| `2` | Precondition failed: defenders not green, working tree dirty for a target file, runner not found, claims file invalid. Nothing was probed. |
+| `3` | Usage or configuration error. |
+
+A tool must never exit `0` because it had nothing to check. If the claims
+file is empty or every claim is out of scope, that is reported explicitly and
+the exit code is `2`.

package/spec/README.md

@@ -0,0 +1,54 @@
+# Guard spec — the contract spine
+
+Six formats that tools following the Guard pattern share. They share
+*formats*, not code: [`docguard-cli`](https://www.npmjs.com/package/docguard-cli)
+is Node ESM, [`websec-validator`](https://pypi.org/project/websec-validator/)
+is Python, and porting one runtime into the other is not worth it. A tool
+conforms by emitting these shapes; it keeps its own language, CLI and UX.
+
+The pattern all such tools run:
+
+> declare what must be true → try mechanically to falsify it → freeze a
+> baseline → gate only the delta → brief the agent before it writes code.
+
+## Formats
+
+| Kind | Schema | Purpose |
+|---|---|---|
+| `claims` | [`schemas/claims.schema.json`](schemas/claims.schema.json) | What must be true, and one or more concrete faults that would make it false. Producer-agnostic: a human, an operator, an agent, or a derivation may all emit the same fault shape, and every artifact says which. |
+| `evidence` | [`schemas/evidence.schema.json`](schemas/evidence.schema.json) | One run's findings on disk, readable without the tool. Every verdict carries every run that produced it. |
+| `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. |
+
+Shared definitions (verdicts, fault classes, provenance, annotations) live in
+[`schemas/common.schema.json`](schemas/common.schema.json). Gate behaviour —
+which verdicts turn CI red, baseline and delta rules, exit codes — is in
+[`GATE-SEMANTICS.md`](GATE-SEMANTICS.md).
+
+Schemas are JSON Schema 2020-12 and identified as `urn:guard-spec:v1:<kind>`.
+
+## Conformance
+
+`lib/validate.mjs` validates a document of any kind: JSON Schema first, then
+the semantic rules a schema cannot express (unique ids, fingerprint
+derivation, N-run agreement, green-baseline requirement, interval sanity).
+`lib/fingerprint.mjs` is the single fingerprint implementation every tool
+must use.
+
+`conformance/examples/` holds one valid document per kind; `conformance/invalid/`
+holds documents that must be rejected, each named for its defect. A tool
+conforms when its output validates and its behaviour matches
+`GATE-SEMANTICS.md`.
+
+```bash
+npm run test:spec
+```
+
+## Sequencing
+
+The spec is drafted here and validated against `testguard` as its first
+consumer. It moves to its own repository only when a second tool adopts it.
+Adoption by an existing tool is one additive output writer — no rewrite, no
+behaviour change, and optional until that tool wants it.

package/spec/lib/fingerprint.mjs

@@ -0,0 +1,19 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * The one fingerprint derivation every Guard-spec tool must use.
+ *
+ * Built from identities and outcome only — never from the fault's find/replace
+ * text — so repairing a rotted anchor does not churn a baseline, while a
+ * change of verdict on the same claim+subject surfaces as a new finding.
+ *
+ * `file` is the empty string when the subject has no file (non-TestGuard adopters).
+ */
+export function fingerprint({ claimId, subjectId, file = '', verdict }) {
+  for (const [k, v] of Object.entries({ claimId, subjectId, verdict })) {
+    if (typeof v !== 'string' || v.length === 0) throw new TypeError(`fingerprint: ${k} is required`);
+  }
+  return createHash('sha256')
+    .update([claimId, subjectId, file, verdict].join('\n'))
+    .digest('hex');
+}

package/spec/lib/validate.mjs

@@ -0,0 +1,119 @@
+import Ajv2020 from 'ajv/dist/2020.js';
+import { readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+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 PASSING_VERDICTS = Object.freeze(new Set(['killed']));
+
+const ajv = new Ajv2020({ strict: true, allErrors: true });
+for (const f of readdirSync(schemaDir).filter((n) => n.endsWith('.schema.json'))) {
+  ajv.addSchema(JSON.parse(readFileSync(join(schemaDir, f), 'utf8')));
+}
+
+const schemaFor = (kind) => {
+  const v = ajv.getSchema(`urn:guard-spec:v1:${kind}`);
+  if (!v) throw new RangeError(`unknown Guard-spec kind: ${kind}`);
+  return v;
+};
+
+// Rules JSON Schema cannot express. Each returns an array of {path, message}.
+const semantic = {
+  claims(doc) {
+    const errors = [];
+    const seenClaim = new Set();
+    doc.claims.forEach((c, ci) => {
+      if (seenClaim.has(c.id)) errors.push({ path: `/claims/${ci}/id`, message: `duplicate claim id "${c.id}"` });
+      seenClaim.add(c.id);
+      const seenFault = new Set();
+      c.faults.forEach((f, fi) => {
+        const p = `/claims/${ci}/faults/${fi}`;
+        if (seenFault.has(f.id)) errors.push({ path: `${p}/id`, message: `duplicate fault id "${f.id}" in claim "${c.id}"` });
+        seenFault.add(f.id);
+        const occ = f.occurrence ?? 1;
+        const hits = f.expectHits ?? 1;
+        if (occ > hits) errors.push({ path: `${p}/occurrence`, message: `occurrence ${occ} exceeds expectHits ${hits}` });
+        if (f.find === f.replace) errors.push({ path: `${p}/replace`, message: 'replace is identical to find; the fault is a no-op' });
+      });
+    });
+    return errors;
+  },
+
+  evidence(doc) {
+    const errors = [];
+    const n = doc.run.confirmRuns;
+    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 });
+      if (r.fingerprint !== expected) errors.push({ path: `${p}/fingerprint`, message: `fingerprint does not match spec derivation (expected ${expected})` });
+
+      const { baselineRuns, probeRuns } = r.detail;
+      if (r.verdict === 'killed' || r.verdict === 'survived') {
+        if (baselineRuns.length !== n) errors.push({ path: `${p}/detail/baselineRuns`, message: `${r.verdict} requires exactly confirmRuns (${n}) baseline runs, got ${baselineRuns.length}` });
+        if (probeRuns.length !== n) errors.push({ path: `${p}/detail/probeRuns`, message: `${r.verdict} requires exactly confirmRuns (${n}) probe runs, got ${probeRuns.length}` });
+        if (baselineRuns.some((b) => b.outcome !== 'pass')) errors.push({ path: `${p}/detail/baselineRuns`, message: `${r.verdict} is only valid on a green baseline` });
+      }
+      if (r.verdict === 'killed' && !probeRuns.every((x) => x.outcome === 'fail' && (x.assertionFailures ?? 0) > 0)) {
+        errors.push({ path: `${p}/detail/probeRuns`, message: 'killed requires every probe run to fail with at least one assertion failure' });
+      }
+      if (r.verdict === 'survived' && !probeRuns.every((x) => x.outcome === 'pass')) {
+        errors.push({ path: `${p}/detail/probeRuns`, message: 'survived requires every probe run to pass' });
+      }
+      if (r.verdict === 'flaky-defender') {
+        const baselineNotGreen = baselineRuns.length === 0 || baselineRuns.some((b) => b.outcome !== 'pass');
+        const mixedProbe = probeRuns.some((x) => x.outcome === 'pass') && probeRuns.some((x) => x.outcome === 'fail');
+        if (!baselineNotGreen && !mixedProbe) {
+          errors.push({ path: `${p}/detail`, message: 'flaky-defender requires a non-green baseline or mixed pass/fail probe runs' });
+        }
+      }
+      if (r.verdict === 'nocover' && !r.defenders.nocover) {
+        errors.push({ path: `${p}/defenders/nocover`, message: 'nocover verdict requires defenders.nocover = true' });
+      }
+      if (r.verdict === 'unverifiable' && !r.detail.reason) {
+        errors.push({ path: `${p}/detail/reason`, message: 'unverifiable requires a reason (e.g. anchor-missing, anchor-ambiguous)' });
+      }
+    });
+    return errors;
+  },
+
+  calibration(doc) {
+    const errors = [];
+    for (const [key, b] of Object.entries(doc.buckets)) {
+      const p = `/buckets/${key}`;
+      if (b.positives > b.n) errors.push({ path: `${p}/positives`, message: `positives (${b.positives}) exceed n (${b.n})` });
+      const [lo, hi] = b.ci;
+      if (lo > hi) errors.push({ path: `${p}/ci`, message: `ci lower bound ${lo} exceeds upper bound ${hi}` });
+      if (b.p < lo || b.p > hi) errors.push({ path: `${p}/p`, message: `p (${b.p}) lies outside ci [${lo}, ${hi}]` });
+    }
+    return errors;
+  },
+
+  brief(doc) {
+    const errors = [];
+    if (!doc.text.startsWith(doc.heading)) errors.push({ path: '/text', message: 'text must begin with heading' });
+    const byVerdictTotal = Object.values(doc.summary.byVerdict).reduce((a, b) => a + b, 0);
+    if (doc.summary.new + doc.summary.baselined > byVerdictTotal) {
+      errors.push({ path: '/summary', message: 'new + baselined cannot exceed the total of byVerdict' });
+    }
+    return errors;
+  },
+};
+
+/**
+ * Validate a document against a Guard-spec kind: JSON Schema first, then the
+ * semantic rules for that kind. Returns { ok, errors: [{ path, message }] }.
+ */
+export function validate(kind, doc) {
+  const check = schemaFor(kind);
+  if (!check(doc)) {
+    return {
+      ok: false,
+      errors: check.errors.map((e) => ({ path: e.instancePath || '/', message: e.message ?? 'invalid' })),
+    };
+  }
+  const errors = semantic[kind] ? semantic[kind](doc) : [];
+  return { ok: errors.length === 0, errors };
+}

package/spec/schemas/baseline.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:guard-spec:v1:baseline",
+  "title": "Guard spec v1 — baseline",
+  "description": "Frozen fingerprints of findings that existed when the baseline was taken. A finding whose fingerprint appears here is suppressed up to `count` occurrences; everything else is new and gates. Only non-passing verdicts are ever fingerprinted.",
+  "type": "object",
+  "required": ["schemaVersion", "tool", "createdAt", "fingerprints"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "tool": { "$ref": "urn:guard-spec:v1:common#/$defs/tool" },
+    "createdAt": { "$ref": "urn:guard-spec:v1:common#/$defs/isoDateTime" },
+    "head": { "$ref": "urn:guard-spec:v1:common#/$defs/gitSha" },
+    "fingerprints": {
+      "type": "object",
+      "propertyNames": { "pattern": "^[a-f0-9]{64}$" },
+      "additionalProperties": { "type": "integer", "minimum": 1 }
+    }
+  },
+  "additionalProperties": false
+}

package/spec/schemas/brief.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:guard-spec:v1:brief",
+  "title": "Guard spec v1 — agent brief",
+  "description": "What to tell an agent before it writes code. `text` is the rendered block for an additionalContext payload; `items` is the same content structured so other tools can compose briefs. Ranked, capped, and never a single score.",
+  "type": "object",
+  "required": ["schemaVersion", "tool", "generatedAt", "heading", "summary", "items", "text"],
+  "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" },
+    "head": { "$ref": "urn:guard-spec:v1:common#/$defs/gitSha" },
+    "heading": {
+      "description": "The markdown heading that opens `text`, e.g. `## TEST BLINDSPOT CONTEXT`.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "summary": {
+      "type": "object",
+      "required": ["claims", "byVerdict", "new", "baselined"],
+      "properties": {
+        "claims": { "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
+    },
+    "items": {
+      "type": "array",
+      "maxItems": 50,
+      "items": {
+        "type": "object",
+        "required": ["fingerprint", "claimId", "statement", "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" },
+          "statement": { "type": "string", "minLength": 1, "maxLength": 2000 },
+          "verdict": { "$ref": "urn:guard-spec:v1:common#/$defs/verdict" },
+          "severity": { "$ref": "urn:guard-spec:v1:common#/$defs/severity" },
+          "file": { "$ref": "urn:guard-spec:v1:common#/$defs/repoPath" },
+          "rank": { "type": "number" },
+          "hint": {
+            "description": "One line the agent can act on, e.g. which assertion shape left the gap.",
+            "type": "string",
+            "maxLength": 512
+          },
+          "isNew": { "type": "boolean" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "text": { "type": "string", "minLength": 1 }
+  },
+  "additionalProperties": false
+}