testguard-cli 0.1.0

package/spec/schemas/calibration.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:guard-spec:v1:calibration",
+  "title": "Guard spec v1 — calibration",
+  "description": "P(finding is real) per bucket, with a confidence interval and the sample size behind it. A label without n is a vibe; this is the format that stops it being one.",
+  "type": "object",
+  "required": ["schemaVersion", "tool", "computedAt", "method", "confidence", "bucketBy", "source", "buckets"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "tool": { "$ref": "urn:guard-spec:v1:common#/$defs/tool" },
+    "computedAt": { "$ref": "urn:guard-spec:v1:common#/$defs/isoDateTime" },
+    "method": {
+      "description": "Interval method. `wilson` is the only method defined in v1.",
+      "enum": ["wilson"]
+    },
+    "confidence": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1 },
+    "bucketBy": {
+      "description": "The field findings are bucketed on, e.g. `faultClass` or `severity`.",
+      "$ref": "urn:guard-spec:v1:common#/$defs/identifier"
+    },
+    "source": {
+      "description": "Where the ground-truth labels came from.",
+      "type": "object",
+      "required": ["kind"],
+      "properties": {
+        "kind": { "enum": ["bug-replay", "human-label", "mixed"] },
+        "ref": { "type": "string", "maxLength": 512 }
+      },
+      "additionalProperties": false
+    },
+    "buckets": {
+      "type": "object",
+      "propertyNames": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$" },
+      "additionalProperties": {
+        "type": "object",
+        "required": ["n", "positives", "p", "ci"],
+        "properties": {
+          "n": { "type": "integer", "minimum": 0 },
+          "positives": { "type": "integer", "minimum": 0 },
+          "p": { "type": "number", "minimum": 0, "maximum": 1 },
+          "ci": {
+            "type": "array",
+            "minItems": 2,
+            "maxItems": 2,
+            "items": { "type": "number", "minimum": 0, "maximum": 1 }
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/spec/schemas/claims.schema.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:guard-spec:v1:claims",
+  "title": "Guard spec v1 — claims file",
+  "description": "What must be true, and how to try to falsify it. A claim is a statement the project makes; each fault is one concrete way that statement could be false, expressed as a deterministic source change. This file is code: its `replace` strings execute under the test runner. Treat it with the same review discipline as source.",
+  "type": "object",
+  "required": ["schemaVersion", "claims"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "claims": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/claim" }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "claim": {
+      "type": "object",
+      "required": ["id", "statement", "source", "severity", "producedBy", "faults"],
+      "properties": {
+        "id": {
+          "description": "Stable identifier. Renaming it changes every fingerprint derived from it.",
+          "$ref": "urn:guard-spec:v1:common#/$defs/identifier"
+        },
+        "statement": {
+          "description": "The claim in plain language, as the project states it.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2000
+        },
+        "source": {
+          "description": "Where the claim comes from. Spec- and ADR-sourced claims are human-governed; annotation- and comment-sourced claims may have been written by the same agent that wrote the tests, and should be ranked accordingly.",
+          "type": "object",
+          "required": ["kind"],
+          "properties": {
+            "kind": { "enum": ["spec", "adr", "annotation", "comment", "manual"] },
+            "ref": { "type": "string", "maxLength": 512 }
+          },
+          "additionalProperties": false
+        },
+        "severity": { "$ref": "urn:guard-spec:v1:common#/$defs/severity" },
+        "producedBy": { "$ref": "urn:guard-spec:v1:common#/$defs/provenance" },
+        "defendedBy": {
+          "description": "Globs (repo-relative) for the test files that supposedly defend this claim. Empty or absent means: let the runner discover related tests. If the globs resolve to zero files the verdict is `nocover`.",
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
+        "faults": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/fault" }
+        },
+        "tags": {
+          "type": "array",
+          "items": { "$ref": "urn:guard-spec:v1:common#/$defs/identifier" },
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "fault": {
+      "description": "One concrete way the claim could be false. Applied as an exact-string substitution; the schema is producer-agnostic — a human, an operator, an agent, or a derivation may all emit this shape.",
+      "type": "object",
+      "required": ["id", "description", "faultClass", "file", "find", "replace", "producedBy"],
+      "properties": {
+        "id": {
+          "description": "Unique within the claim.",
+          "$ref": "urn:guard-spec:v1:common#/$defs/identifier"
+        },
+        "description": { "type": "string", "minLength": 1, "maxLength": 2000 },
+        "faultClass": { "$ref": "urn:guard-spec:v1:common#/$defs/faultClass" },
+        "file": { "$ref": "urn:guard-spec:v1:common#/$defs/repoPath" },
+        "find": {
+          "description": "Exact text to locate in `file`. Must occur exactly `expectHits` times or the fault is `unverifiable`.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 20000
+        },
+        "replace": {
+          "description": "Exact replacement text. May be empty.",
+          "type": "string",
+          "maxLength": 20000
+        },
+        "occurrence": {
+          "description": "Which occurrence of `find` to replace (1-based).",
+          "type": "integer",
+          "minimum": 1,
+          "default": 1
+        },
+        "expectHits": {
+          "description": "How many times `find` must occur in `file`. Any other count means the anchor has rotted or is ambiguous → `unverifiable`, never a silent skip.",
+          "type": "integer",
+          "minimum": 1,
+          "default": 1
+        },
+        "producedBy": { "$ref": "urn:guard-spec:v1:common#/$defs/provenance" }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/spec/schemas/common.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:guard-spec:v1:common",
+  "title": "Guard spec v1 — shared definitions",
+  "description": "Definitions shared by every Guard-spec format. Referenced as urn:guard-spec:v1:common#/$defs/<name>.",
+  "$defs": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "gitSha": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{7,40}$"
+    },
+    "isoDateTime": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$"
+    },
+    "identifier": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
+      "maxLength": 128
+    },
+    "repoPath": {
+      "description": "Path relative to the repository root. Absolute paths and parent traversal are rejected.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?![/\\\\])(?!\\.\\.(?:[/\\\\]|$))(?!.*[/\\\\]\\.\\.(?:[/\\\\]|$)).*$"
+    },
+    "severity": {
+      "enum": ["critical", "high", "medium", "low"]
+    },
+    "verdict": {
+      "description": "Closed set. Only `killed` is a pass. Every other verdict gates by default (see GATE-SEMANTICS.md).",
+      "enum": [
+        "killed",
+        "survived",
+        "nocover",
+        "unverifiable",
+        "timeout",
+        "fault-invalid",
+        "flaky-defender"
+      ]
+    },
+    "faultClass": {
+      "description": "Taxonomy of the injected change. Required on every fault so calibration (fault class → real-bug predictiveness) can be computed later.",
+      "enum": [
+        "guard-removed",
+        "condition-forced",
+        "statement-deleted",
+        "variable-swap",
+        "literal-changed",
+        "call-removed",
+        "return-altered",
+        "exception-swallowed",
+        "other"
+      ]
+    },
+    "provenance": {
+      "description": "Who or what produced an artifact. `human` = authored by a person; `agent` = proposed by an LLM agent; `operator` = emitted by a mechanical mutation operator; `derived` = computed from another artifact (e.g. a bug log).",
+      "type": "object",
+      "required": ["producer"],
+      "properties": {
+        "producer": { "enum": ["human", "agent", "operator", "derived"] },
+        "by": { "type": "string", "maxLength": 256 },
+        "reviewedBy": { "type": "string", "maxLength": 256 },
+        "at": { "$ref": "#/$defs/isoDateTime" }
+      },
+      "additionalProperties": false
+    },
+    "tool": {
+      "type": "object",
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "$ref": "#/$defs/identifier" },
+        "version": { "type": "string", "minLength": 1, "maxLength": 64 }
+      },
+      "additionalProperties": false
+    },
+    "annotation": {
+      "description": "Strictly additive. An annotation never changes, suppresses, or drops a finding; it only attaches context to it.",
+      "type": "object",
+      "required": ["kind", "text"],
+      "properties": {
+        "kind": { "enum": ["note", "accepted-risk", "false-positive", "tracked", "wontfix"] },
+        "text": { "type": "string", "minLength": 1, "maxLength": 4000 },
+        "by": { "type": "string", "maxLength": 256 },
+        "at": { "$ref": "#/$defs/isoDateTime" },
+        "ref": { "type": "string", "maxLength": 512 }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/spec/schemas/evidence.schema.json

@@ -0,0 +1,206 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:guard-spec:v1:evidence",
+  "title": "Guard spec v1 — evidence file",
+  "description": "One run's findings, on disk, in a shape an auditor can read without the tool. Each record binds a claim to a subject (for TestGuard, an injected fault) and a verdict, with every run that produced the verdict.",
+  "type": "object",
+  "required": ["schemaVersion", "tool", "run", "records"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "tool": { "$ref": "urn:guard-spec:v1:common#/$defs/tool" },
+    "run": {
+      "type": "object",
+      "required": ["id", "startedAt", "repo", "confirmRuns", "mode"],
+      "properties": {
+        "id": { "$ref": "urn:guard-spec:v1:common#/$defs/identifier" },
+        "startedAt": { "$ref": "urn:guard-spec:v1:common#/$defs/isoDateTime" },
+        "finishedAt": { "$ref": "urn:guard-spec:v1:common#/$defs/isoDateTime" },
+        "repo": {
+          "type": "object",
+          "required": ["head", "dirty"],
+          "properties": {
+            "head": { "$ref": "urn:guard-spec:v1:common#/$defs/gitSha" },
+            "dirty": { "type": "boolean" }
+          },
+          "additionalProperties": false
+        },
+        "runner": {
+          "type": "object",
+          "required": ["name"],
+          "properties": {
+            "name": { "$ref": "urn:guard-spec:v1:common#/$defs/identifier" },
+            "version": { "type": "string", "maxLength": 64 }
+          },
+          "additionalProperties": false
+        },
+        "confirmRuns": {
+          "description": "N — how many times the defenders were run both unmodified (baseline) and with each fault applied.",
+          "type": "integer",
+          "minimum": 1
+        },
+        "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"]
+        }
+      },
+      "additionalProperties": false
+    },
+    "records": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/record" }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "testRun": {
+      "type": "object",
+      "required": ["outcome", "durationMs"],
+      "properties": {
+        "outcome": {
+          "description": "`fail` means at least one test failed with the suite otherwise loading and running. `error` means the suite could not load or run (import/syntax error). `timeout` means the runner exceeded its budget.",
+          "enum": ["pass", "fail", "timeout", "error"]
+        },
+        "tests": {
+          "type": "object",
+          "required": ["total", "passed", "failed"],
+          "properties": {
+            "total": { "type": "integer", "minimum": 0 },
+            "passed": { "type": "integer", "minimum": 0 },
+            "failed": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        "assertionFailures": {
+          "description": "Test-level failures that are neither timeouts nor load failures: the test body ran and rejected the behaviour, whether by an assertion or by an exception the fault caused. Only these count toward `killed`. A timeout or a suite that fails to load is not evidence that the suite defends the claim.",
+          "type": "integer",
+          "minimum": 0
+        },
+        "durationMs": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "record": {
+      "type": "object",
+      "required": ["fingerprint", "claim", "subject", "verdict", "detail", "defenders", "inputs"],
+      "properties": {
+        "fingerprint": {
+          "description": "sha256 of `<claim.id>\\n<subject.id>\\n<subject.file>\\n<verdict>`. Derived from identities and outcome, never from `find`/`replace`, so repairing a rotted anchor does not churn the baseline.",
+          "$ref": "urn:guard-spec:v1:common#/$defs/sha256"
+        },
+        "claim": {
+          "type": "object",
+          "required": ["id", "statement", "severity", "source"],
+          "properties": {
+            "id": { "$ref": "urn:guard-spec:v1:common#/$defs/identifier" },
+            "statement": { "type": "string", "minLength": 1, "maxLength": 2000 },
+            "severity": { "$ref": "urn:guard-spec:v1:common#/$defs/severity" },
+            "source": {
+              "type": "object",
+              "required": ["kind"],
+              "properties": {
+                "kind": { "enum": ["spec", "adr", "annotation", "comment", "manual"] },
+                "ref": { "type": "string", "maxLength": 512 }
+              },
+              "additionalProperties": false
+            },
+            "producedBy": { "$ref": "urn:guard-spec:v1:common#/$defs/provenance" }
+          },
+          "additionalProperties": false
+        },
+        "subject": {
+          "description": "What was tried against the claim. For TestGuard `kind` is `fault`. Other adopters use their own kinds (e.g. `doc-statement`, `finding`); extra properties are permitted here and nowhere else.",
+          "type": "object",
+          "required": ["kind", "id"],
+          "properties": {
+            "kind": { "$ref": "urn:guard-spec:v1:common#/$defs/identifier" },
+            "id": { "$ref": "urn:guard-spec:v1:common#/$defs/identifier" },
+            "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" }
+          },
+          "additionalProperties": true
+        },
+        "verdict": { "$ref": "urn:guard-spec:v1:common#/$defs/verdict" },
+        "detail": {
+          "type": "object",
+          "required": ["baselineRuns", "probeRuns"],
+          "properties": {
+            "reason": {
+              "description": "Machine-readable qualifier, e.g. `anchor-missing`, `anchor-ambiguous`, `defenders-not-green`, `replacement-does-not-compile`.",
+              "type": "string",
+              "maxLength": 256
+            },
+            "baselineRuns": {
+              "description": "Defenders run on unmodified source, N times. Anything short of N/N pass is `flaky-defender`.",
+              "type": "array",
+              "items": { "$ref": "#/$defs/testRun" }
+            },
+            "probeRuns": {
+              "description": "Defenders run with the fault applied, N times.",
+              "type": "array",
+              "items": { "$ref": "#/$defs/testRun" }
+            },
+            "escalated": {
+              "description": "True when the fault survived its declared defenders and a broader test set was then run.",
+              "type": "boolean"
+            },
+            "escalationRuns": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/testRun" }
+            }
+          },
+          "additionalProperties": false
+        },
+        "defenders": {
+          "type": "object",
+          "required": ["requested", "resolved", "nocover"],
+          "properties": {
+            "requested": { "type": "array", "items": { "type": "string" } },
+            "resolved": { "type": "array", "items": { "$ref": "urn:guard-spec:v1:common#/$defs/repoPath" } },
+            "nocover": { "type": "boolean" }
+          },
+          "additionalProperties": false
+        },
+        "inputs": {
+          "description": "Content hashes of everything the verdict depends on, so an unchanged claim can reuse its prior verdict.",
+          "type": "object",
+          "required": ["targetHash", "defenderHashes"],
+          "properties": {
+            "targetHash": { "$ref": "urn:guard-spec:v1:common#/$defs/sha256" },
+            "defenderHashes": {
+              "type": "object",
+              "additionalProperties": { "$ref": "urn:guard-spec:v1:common#/$defs/sha256" }
+            }
+          },
+          "additionalProperties": false
+        },
+        "reusedFrom": {
+          "description": "Run id whose verdict was reused because `inputs` were unchanged.",
+          "$ref": "urn:guard-spec:v1:common#/$defs/identifier"
+        },
+        "rank": {
+          "description": "Additive ordering signal. Never alters `verdict`.",
+          "type": "object",
+          "required": ["score"],
+          "properties": {
+            "score": { "type": "number" },
+            "blastRadius": {
+              "description": "Number of source files that import the subject's file, transitively or directly as the tool documents.",
+              "type": "integer",
+              "minimum": 0
+            },
+            "tier": { "type": "string", "maxLength": 64 }
+          },
+          "additionalProperties": false
+        },
+        "annotations": {
+          "type": "array",
+          "items": { "$ref": "urn:guard-spec:v1:common#/$defs/annotation" }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/spec/schemas/ignore.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:guard-spec:v1:ignore",
+  "title": "Guard spec v1 — structured ignore",
+  "description": "Reviewable scoping. Every entry carries a reason. Tools may also accept a plain gitignore-syntax text file as shorthand for path entries without reasons; this structured form is what an auditor reads.",
+  "type": "object",
+  "required": ["schemaVersion", "entries"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["kind", "pattern", "reason"],
+        "properties": {
+          "kind": {
+            "description": "`path` = glob over repo paths; `claim` = claim id; `fault` = `<claimId>/<faultId>`; `fingerprint` = an evidence fingerprint.",
+            "enum": ["path", "claim", "fault", "fingerprint"]
+          },
+          "pattern": { "type": "string", "minLength": 1, "maxLength": 512 },
+          "reason": { "type": "string", "minLength": 8, "maxLength": 2000 },
+          "by": { "type": "string", "maxLength": 256 },
+          "at": { "$ref": "urn:guard-spec:v1:common#/$defs/isoDateTime" },
+          "expires": {
+            "description": "After this instant the entry no longer applies. Tools warn on expired entries.",
+            "$ref": "urn:guard-spec:v1:common#/$defs/isoDateTime"
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/src/baseline/baseline.mjs

@@ -0,0 +1,34 @@
+const SEVERITY_RANK = { low: 0, medium: 1, high: 2, critical: 3 };
+
+/** Freeze every non-passing finding. `killed` is never debt, so it is never fingerprinted. */
+export function buildBaseline(evidence, { createdAt = new Date().toISOString() } = {}) {
+  const fingerprints = {};
+  for (const r of evidence.records) {
+    if (r.verdict === 'killed') continue;
+    fingerprints[r.fingerprint] = (fingerprints[r.fingerprint] ?? 0) + 1;
+  }
+  return { schemaVersion: 1, tool: evidence.tool, createdAt, head: evidence.run.repo.head, fingerprints };
+}
+
+/**
+ * Split records into what gates and what does not. Baseline suppression is
+ * up-to-count per fingerprint; the severity floor only decides whether a
+ * new finding turns CI red, never whether it is reported.
+ */
+export function gate(records, baseline, { severityFloor = 'low' } = {}) {
+  const remaining = { ...(baseline?.fingerprints ?? {}) };
+  const out = { new: [], baselined: [], belowFloor: [], killed: [] };
+  for (const r of records) {
+    if (r.verdict === 'killed') {
+      out.killed.push(r);
+    } else if ((remaining[r.fingerprint] ?? 0) > 0) {
+      remaining[r.fingerprint]--;
+      out.baselined.push(r);
+    } else if (SEVERITY_RANK[r.claim.severity] < SEVERITY_RANK[severityFloor]) {
+      out.belowFloor.push(r);
+    } else {
+      out.new.push(r);
+    }
+  }
+  return out;
+}

package/src/brief/brief.mjs

@@ -0,0 +1,87 @@
+import { gate } from '../baseline/baseline.mjs';
+import { summarize, formatVerdict } from '../render.mjs';
+
+export const HEADING = '## TEST BLINDSPOT CONTEXT';
+const ORDER = ['survived', 'nocover', 'unverifiable', 'fault-invalid', 'timeout', 'flaky-defender'];
+
+/** One line the agent can act on. Names the mechanism, never just the verdict. */
+export function hintFor(r) {
+  const defenders = r.defenders.resolved.join(', ');
+  switch (r.verdict) {
+    case 'survived':
+      return r.detail.reason === 'killed-by-undeclared-tests'
+        ? `Only tests outside its declared defenders (${defenders}) catch this; fix the claim's defendedBy or move the assertion.`
+        : `${defenders} stayed green with this fault applied; add an assertion that fails on it and passes on HEAD.`;
+    case 'nocover':
+      return `No test file matches ${r.defenders.requested.join(', ') || '(no defenders declared)'}; nothing defends this claim.`;
+    case 'unverifiable':
+      return `Anchor ${r.detail.reason}; re-author fault ${r.subject.id} in the claims file before trusting this claim.`;
+    case 'fault-invalid':
+      return `Replacement does not load (${r.detail.reason}); fix the fault definition, not the code.`;
+    case 'timeout':
+      return 'Defenders time out with this fault applied; a hang is not a detection.';
+    case 'flaky-defender':
+      return `${defenders} not reliably green (${r.detail.reason}); fix the flake before trusting any verdict here.`;
+    default:
+      return '';
+  }
+}
+
+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() } = {}) {
+  const g = gate(evidence.records, baseline);
+  const toItem = (r, isNew) => ({
+    fingerprint: r.fingerprint,
+    claimId: r.claim.id,
+    subjectId: r.subject.id,
+    statement: r.claim.statement,
+    verdict: r.verdict,
+    severity: r.claim.severity,
+    ...(r.subject.file ? { file: r.subject.file } : {}),
+    ...(r.rank ? { rank: r.rank.score } : {}),
+    hint: hintFor(r),
+    isNew,
+  });
+  const items = [...g.new.map((r) => toItem(r, true)), ...g.belowFloor.map((r) => toItem(r, true)), ...g.baselined.map((r) => toItem(r, false))]
+    .sort(orderItems)
+    .slice(0, max);
+  const summary = {
+    claims: new Set(evidence.records.map((r) => r.claim.id)).size,
+    byVerdict: summarize(evidence.records),
+    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 });
+  return doc;
+}
+
+export function renderBriefText(brief, { hasBaseline, total }) {
+  const unproven = total - (brief.summary.byVerdict.killed ?? 0);
+  const lines = [
+    brief.heading,
+    '',
+    `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.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';
+  }
+  lines.push(
+    '',
+    'Where the test suite is blind, ranked. A SURVIVED fault means its defenders stayed green while the claim was false.',
+    'Do not close these by asserting current behaviour; write a test that fails on the described fault and passes on HEAD.',
+    '',
+  );
+  brief.items.forEach((it, i) => {
+    lines.push(`${i + 1}. ${it.isNew ? '[NEW] ' : ''}${formatVerdict(it.verdict)}  ${it.claimId}/${it.subjectId ?? '?'} (${it.severity})${it.file ? ` ${it.file}` : ''}`);
+    lines.push(`   claim: ${it.statement}`);
+    if (it.hint) lines.push(`   ${it.hint}`);
+  });
+  if (unproven > brief.items.length) lines.push('', `… and ${unproven - brief.items.length} more in the evidence file.`);
+  return lines.join('\n') + '\n';
+}