testguard-cli 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -7,12 +7,640 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-09-18
+
+Python, and a fault that cannot hide.
+
+TestGuard now probes Python projects with nothing installed into them, and it
+no longer takes a green suite at its word: a fault applied to code the tests
+never execute used to be reported as SURVIVED — an audit finding that reads as
+devastating and is entirely false — and is now `unverifiable`, because the
+defenders are made to prove they can fail because of that file before a
+survival about it is allowed to stand.
+
+Alongside: the shared spec is named `claimspec` and no longer assumes fault
+injection is the only way to falsify a claim, one bad fault can no longer cost
+the evidence for the whole run, and the self-probe gate was measured rather
+than guessed at.
+
+### Upgrading
+
+**Some claims that were `survived` will become `unverifiable`, and your frozen
+baseline will not suppress them.** This is the intended consequence of the
+negative control, and it is worth reading before you re-freeze anything.
+
+A fingerprint is derived from the claim, the subject, the file and **the
+verdict**. A claim whose subject the defenders never execute was reported
+`survived`; it is now `unverifiable` with reason `subject-not-executed`. That
+is a different fingerprint, so a baseline frozen before this release does not
+contain it, and it gates as new.
+
+**The finding is real.** It says the defenders do not execute that file at all,
+so every earlier verdict about it was a statement about their reach rather than
+their assertions — including the `survived` your baseline was suppressing. A
+`survived` you had accepted as known debt was, in these cases, not a measurement
+of anything.
+
+What to do, in order:
+
+1. `testguard probe` and read the records carrying
+   `detail.negativeControl: "not-reached"`. Each names a file no defender
+   loads.
+2. **Prefer fixing the defenders.** A claim whose subject is never imported is
+   the cheapest blind spot you will ever find — cheaper than a survivor,
+   because nothing was even tried.
+3. If you are accepting it as existing debt for now, `testguard baseline`
+   re-freezes today's findings so only newer ones gate. Do this **after**
+   looking at them, not instead of.
+
+`baseline --restamp` is **not** the command for this: it moves a baseline's
+`head` onto a clean identical probe, and it requires the same fingerprints.
+
+Nothing else in this release requires migration. The `claimspec` rename changes
+no emitted document, the `method` field defaults to `fault-injection` so every
+existing claims and evidence file stays valid, and the gate work changed which
+tests defend which claims, never a verdict.
+
+### Added
+
+- **A five-page technical brief**, [`docs/testguard-explained.pdf`](docs/testguard-explained.pdf):
+  the whole idea on page one, the field measurements on page two, then
+  mechanics, architecture and prior art. Six diagrams, including a dot matrix
+  of the 39 injected faults from the second field report — 21 survived a fully
+  green suite, 39/39 killed after tests were written against the survivors. Built from
+  `docs/testguard-explained.html` with `node .github/scripts/build-one-pager.mjs`
+  (headless Chrome, so the one pinned runtime dependency stays one).
+
+### Changed
+- **A probe says which method produced it, and fault injection is no longer
+  assumed** (#81). `claims` required `file`, `find` and `replace` on every
+  fault; `evidence` required `confirmRuns`, `mode`, `defenders`, `inputs` and
+  the baseline and probe runs on every record. All of those are what *fault
+  injection* means by showing its work — and DocGuard verifies claims by
+  reading code while websec-validator scans a surface, so neither could
+  conform without emitting empty arrays, which is lying, and the one thing
+  this format exists to make impossible.
+  A probe now carries `method`, and a run says which method produced it.
+  **It defaults to `fault-injection`, so every document written before the
+  field existed validates unchanged** — verified against this repository's own
+  88-claim file and every conformance example, none of which carries the field.
+  The injection requirements did not disappear, they moved: the schema asks
+  for them only under `fault-injection`, and the validator enforces them there
+  in full. Relaxing the schema so a scanning tool can conform is not a licence
+  for an injecting tool to stop showing its work, and a self-claim now says so.
+  `assertion` and `scan` are **reserved**: their required fields are
+  deliberately unspecified, to be defined by their first real consumer with
+  conformance examples written from the shape that tool actually has.
+  Designing them for an absent tool is exactly the mistake that made this
+  change necessary — the spec was drafted against a single consumer and
+  hard-coded its assumptions as requirements.
+- **The self-probe gate, re-measured and cut** (#73). `--cost` at `ffaaa81`
+  reported **1414 s across 546 defender runs for 91 faults** — back where #67
+  started, because #77 took the corpus from 59 faults to 91. The gate did not
+  decay; the workload grew, and nothing gated on that.
+  The issue's original table pointed at `test/replay.test.mjs`. Measurement
+  disagreed: that file is 138 s across *six* claims, about 23 s each, the
+  cheapest per-claim cost in the top ten — the table had read a cumulative
+  column as a per-claim one. The real cost was four claims paying an
+  end-to-end fixture probe, 33 to 37 s a run, to falsify decisions that are
+  pure functions.
+  Each was re-pointed at a test that does not need the expensive setup, and
+  **each was then re-probed rather than assumed**: 7 faults, 7 killed, 92 s
+  where they had cost about 860 s.
+  - `checkProvenance` is now exported and unit-tested. It was already a
+    standalone function, and only a 33 s Python fixture probe could falsify it.
+  - `argvFor` is pure, and its own comment says it is "exported so it is
+    falsifiable without spawning anything" — while the claim still paid two
+    fixture probes. `test/runner-argv.test.mjs` asserts the argv directly in
+    126 ms, and covers `selectRunner`'s unknown-name guard too.
+  - The isolation fault needed new work before it could move: forcing
+    isolation to in-place left every fast test green, because they all probe
+    in place anyway, so only the 37 s fixture noticed. Caught by injecting the
+    fault by hand before trusting the re-point — the same trap that made two
+    of five claims survive in #67.
+- **`TG-PIPELINE-REPRODUCES-THE-ORACLE` is restated as
+  `TG-PROBE-NEVER-EDITS-THE-TREE-IT-MEASURES`**, both faults carried over
+  unchanged, the old id retired through the ignore file with a reason.
+  The old statement promised that a probe "reproduces the known-answer
+  fixture's verdicts exactly", and **no fault in it ever falsified that
+  half**: one removes the restore, the other forces in-place isolation, and
+  both are about tree safety. A claim that is defended and still over-promises
+  is the one thing a probe cannot catch, so the statement was narrowed to what
+  its faults actually prove — swapping the defender alone would have kept the
+  over-promise and merely made it cheaper. The fixture oracle still runs on
+  every `npm test` and in CI; it is no longer the defender of a claim whose
+  cost it dominated.
+- **The shared spec is named `claimspec`.** Schemas are now identified as
+  `urn:claimspec:v1:<kind>` rather than `urn:guard-spec:v1:<kind>`.
+  **No emitted document changes**: the identifier lives only in the schemas'
+  own `$id`/`$ref`, the validator's registry and the documentation, so every
+  evidence file, baseline, brief and status already written stays valid and
+  keeps validating. Nothing needs migrating.
+  The old name said which family of tools the formats came from. The name that
+  matters is what they are *for* — claims, the evidence that tried to falsify
+  them, and gating only the delta — and most of the tools that could adopt
+  them (a scanner with an existing-violations problem, a mutation tester, an
+  agent harness that needs `brief` and `status`) do no fault injection at all.
+  `spec/README.md` now says so, and says plainly which kinds a second tool can
+  adopt today and which cannot (#81).
+- **The README leads with the plain explanation.** The research evidence is
+  still there and still matters, but it is not the first thing a newcomer
+  meets: an "In one minute" section now opens with what coverage cannot tell
+  you, the `objectContaining` exhibit, killed vs SURVIVED, the seven verdicts,
+  and — stated plainly — that mutation testing is from the 1970s and the novel
+  part is binding every fault to a claim.
+- The one-line descriptions on npm, PyPI and the GitHub Action now say what the
+  tool does rather than what category it belongs to.
+
+### Fixed
+- **A vanished scratch worktree no longer costs the whole probe** (#64). A
+  parallel session cleaning up its *own* leaked scratch worktrees deleted this
+  run's while it was mid-fault; `restore()` then tried to write the original
+  back into a directory that was gone, threw `ENOENT` out of a `finally`, and
+  the probe died with no evidence file at all — every verdict already decided
+  thrown away, and an exit code `GATE-SEMANTICS.md` does not define.
+  In worktree mode the restore is belt-and-braces: the mutation only ever
+  existed inside a scratch worktree that is discarded at the end of the run, so
+  a target that has vanished is already restored in every sense that matters.
+  It is now recorded as `detail.restoreSkipped: "target-missing"` — a reader
+  can still see that the tree moved underneath the run — and the probe
+  continues. Under `--in-place` the same condition is the user's own file gone
+  and is still raised, loudly; so is any other failure to write the original
+  back, in both modes, because a permission error can mean a mutated file left
+  on disk.
+  More generally, **one bad fault no longer costs the evidence for the other
+  forty**. An unexpected throw inside a fault's probe ends *that fault* as
+  `unverifiable` with reason `probe-error` and a `detail.message` naming what
+  threw; the run finishes and writes its document. The verdict gates, so the
+  failure is loud rather than absorbed into a green run, and a `probe-error`
+  record is never reused by a later run — it says something about the run, not
+  about the code. A **precondition** failure is the deliberate exception: the
+  interpreter loading the source from outside the probed tree, or a runner that
+  does not resolve, is a statement about every verdict in the run and still
+  refuses it outright.
+- **A prior verdict is no longer reused across a fault edit.** `probe` decided
+  reuse from the source hash, the defender hashes and the defender set — never
+  from the fault itself. So editing a fault's `find` or `replace` kept the
+  verdict measured against the fault it replaced: a weakened fault held the
+  `survived` it earned before, and a repaired anchor held `unverifiable`, with
+  the evidence reporting a result nobody had measured against the file's
+  current contents. `status` flagged the changed hash afterwards, but by then
+  the evidence had already said something untrue — and for a tool whose
+  premise is that a fault edit can never be invisible, that was the wrong
+  default. Reuse is now also keyed on the fault's content hash; a prior record
+  that carries none is probed again, because the cost of re-measuring is a run
+  and the cost of the other direction is a verdict nobody took.
+  Found by using the tool on itself: repairing two rotted anchors left both
+  claims reporting `UNVERIFIABLE (reused)` on the next probe.
+
+### Added
+
+- **A survivor now has to prove the defenders execute the subject** (#74). A
+  green baseline makes one failure mode structurally impossible — a misread
+  runner cannot flatter the suite, because a kill requires the defenders to
+  pass on unmodified source first. It says nothing about the opposite
+  direction. If the fault is applied to code the test process never executes,
+  the baseline is green, every probe run is green, and **every claim is
+  reported SURVIVED**. That output reads as a devastating audit finding and is
+  entirely false, and nothing in the run contradicts it, because every
+  individual check passed.
+  This is not hypothetical: a strict editable Python install registers a meta
+  path finder that is consulted before `sys.path`, so the interpreter loads the
+  original module while TestGuard faults the copy in its scratch worktree.
+  Measured, not argued — a fault independently verified to fail 2 of 4 tests
+  reported `4 passed`.
+  A would-be `survived` is now charged one more run: the subject is replaced
+  with content its loader cannot parse, and the defenders run once. Going red
+  proves they execute it (`detail.negativeControl: "reached"`) and the verdict
+  stands. Staying green proves they do not, and the verdict becomes
+  `unverifiable` with reason `subject-not-executed`. Charged **only** on a
+  survivor — a kill already proves the defenders reached the code — and cached
+  per subject and defender set. Each runner supplies what "cannot compile"
+  means for its language; one that cannot say does not guess, and no control is
+  run.
+  The predicate is *"the run did not stay green"*, not *"a test failed"*: an
+  unparseable module usually fails to **load**, which the runner reports as an
+  error with no tests run at all.
+
+- **A runner pinned to one engine keeps every capability the module has.**
+  `pinned()` rebuilt the runner as an explicit allow-list of properties, so
+  `--runner pytest` and `--runner unittest` silently lost the negative control
+  that `--runner python` has: a survivor probed through either flag was never
+  checked, and an unreachable subject reported `survived` exactly as before.
+  Found by the Python fixture, not by the unit test, which iterated the four
+  runner modules rather than the registry the tool actually resolves through —
+  it was checking the code that was written instead of the code that runs. The
+  test now iterates `RUNNERS`, which is what makes the next capability added to
+  a runner fail loudly instead of quietly.
+
+- **`--progress auto|tty|plain|ndjson|none` on `probe`** (#68). A probe used
+  to print its stage line only when `stderr` was a terminal, so CI, a
+  redirected log and an agent harness saw nothing at all for the whole run —
+  indistinguishable from a hang, and a gate you cannot tell from a hang is a
+  gate people start killing.
+  The carriage-return rewriting is a *rendering* choice, not a reason to
+  withhold the information. `auto` (the default) keeps the rewritten line at a
+  terminal and prints append-only lines everywhere else. `ndjson` emits one
+  JSON object per line for stages **and** for verdicts as they land, so a
+  machine can watch a probe without waiting for the document at the end.
+  Progress always goes to **stderr**, so `--json` leaves stdout as one
+  parseable document. `--quiet` and `--json` imply `none`; an explicit
+  `--progress` overrides both, because an operator who asks for a stream of
+  events has said what they want.
+  Self-claims `TG-PROGRESS-NOT-ONLY-FOR-A-TTY`, `TG-PROGRESS-NEVER-ON-STDOUT`
+  and `TG-PROGRESS-EXPLICIT-WINS`, all probed and killed.
+
+
+- **`--cost`, on `probe` and `claims`** — what the defenders actually cost,
+  per claim and per defender file, read back out of the `durationMs` the
+  probe already records. It re-measures nothing and spawns nothing.
+  A probe's wall clock is `(baseline runs + faults × --confirm) × the cost of
+  the claim's defender SET`, per claim, so one slow acceptance test named by
+  five claims is paid for thirty times — and until now nothing in the output
+  said which file that was. The report names it, under **shared defenders**,
+  with the claims that pay for it.
+  Per-file figures are an **upper bound, not a share**: a run executes the
+  whole defender set at once, so the runner never says how much belonged to
+  which file. They overlap by construction and do not sum to the total, which
+  the report says on its own face. Only `totalMs` is additive.
+
+- **DocGuard governs this repository's documentation.** Six canonical
+  documents under `docs-canonical/` — architecture, data model, security,
+  test spec, environment and requirements — written against v0.6.0 rather
+  than generated as templates, plus `DRIFT-LOG.md` for deliberate,
+  recorded deviations. Every validator passes: structure, doc sections,
+  changelog, test spec, environment, security, freshness, traceability,
+  docs-coverage, document lifecycle and TODO tracking. Structural maturity
+  99/100.
+- **Requirements are traceable to tests.** Fourteen functional and eight
+  non-functional requirements, each carrying an `@req` annotation in the
+  test that verifies it, and a traceability matrix that must agree with
+  those annotations. 27/27 traceability checks pass.
+- **Doc drift is caught automatically, not reviewed by hand.** `ci.yml`
+  runs `docguard guard` on every pull request — authoritative, unbypassable
+  and visible in review — and reports the maturity score without gating on
+  it. `.pre-commit-config.yaml` gives contributors the same checks locally,
+  opt-in per clone, alongside the claims check, the change gate and the
+  probe on pre-push.
+- Every configuration file in the repository is now documented in
+  `ARCHITECTURE.md`, including the distinction between
+  `.pre-commit-hooks.yaml` (what we publish for consumers) and
+  `.pre-commit-config.yaml` (what contributors to this repository use).
+  README gains the `Usage` section the Standard README spec expects.
+- **A Python runner** (`--runner python|pytest|unittest`, and `auto` when no
+  JavaScript runner resolves). `pytest` when the project's interpreter can
+  import it, stdlib `unittest` when it cannot; the engine that actually ran is
+  what `run.runner.name` records, and `--runner pytest` / `--runner unittest`
+  pin the choice and fail rather than fall back. **Nothing is installed into
+  the project under test**: the reporters ship inside TestGuard and reach the
+  interpreter through `PYTHONPATH`, so a codebase whose test dependencies are
+  the standard library stays one. A `.py` defender runs under Python whatever
+  the project runner is, so one claim can be defended by a vitest test and a
+  pytest test at once.
+- `--python <path>` (or `TESTGUARD_PYTHON`) names the interpreter. Otherwise:
+  the active `VIRTUAL_ENV`, then the project's `.venv`/`venv`/`.env`, then
+  `python3` on PATH. An interpreter you name is the only one tried — TestGuard
+  never quietly substitutes another, which would change what the tests ran
+  against without changing anything the evidence says.
+- **An import-provenance precondition, and `detail.targetNotImported`.** A
+  green baseline proves the harness is not reporting everything as broken. It
+  proves nothing about the opposite direction, and Python can reach it: a
+  strict editable install puts an import hook ahead of `sys.path`, so the
+  interpreter loads the original file while TestGuard faults the copy. The
+  baseline stays green, every claim is reported `SURVIVED`, and the result
+  reads as a devastating finding while being entirely false. With the fault
+  applied, TestGuard now asks which file was actually imported: loaded from
+  outside the tree being probed **refuses the run**; never imported at all is
+  recorded as `detail.targetNotImported` and warned about, because an import
+  in a branch the fault does not reach is legitimate.
+- **`target-attribute-patched`**, a new defender signal. `patch("pkg.mod.fn")`
+  is not `vi.mock("./mod")`: it replaces one attribute, so the file still
+  detects a fault anywhere else in that module. Applying the JavaScript rule
+  would have dropped such files and reported `nocover` for well-defended
+  claims. Only a patch of the module itself removes a defender; an attribute
+  patch keeps it and names the attributes.
+- Python fault producers for `testguard scaffold`: `condition-forced`,
+  `statement-deleted`, `return-altered`, `literal-changed`, `call-removed`,
+  `field-dropped` and `argument-swapped`, in Python syntax. A statement is
+  removed by replacing it with `pass` rather than deleting the line, and a line
+  that leaves a bracket open is never removed — both because a fault that
+  cannot compile is a probe run that says nothing about the tests.
+- Python defender discovery, mock-awareness and blast radius: matched by module
+  name, the way Python itself matches, so `import`, `from … import`, aliases,
+  relative imports and `importlib.import_module` all resolve.
+- `fixtures/known-answer-python/`: sixteen faults covering every verdict, each
+  verified by hand before it became the oracle, and reproduced under **both**
+  engines.
+
+### Changed
+
+- **The self-probe gate no longer runs a fifty-second acceptance test thirty
+  times.** Five claims named `test/probe.fixture.test.mjs` as their only
+  defender, which is what made the release gate take ~24 minutes. The
+  decisions those claims are about — how escalation attributes an undeclared
+  killer, what counts as a measurable run for the flake rate, which binary a
+  runner invokes, what makes a fault edit visible — are rules you can state in
+  three lines, and none of them needs a fixture to falsify. They are now pure
+  functions in `src/probe/attribution.mjs` and exported `argvFor` builders in
+  the runners, unit-tested in `test/attribution.test.mjs` (~0.5s).
+  This mirrors why `classify()` has always been pure: the order of its checks
+  *is* the spec, and every branch should be falsifiable without a runner.
+  No claim was weakened to get there. Each re-pointed claim was re-probed and
+  still **kills** its faults; two of them SURVIVED on the first narrowing
+  attempt, which is exactly the failure mode `--cost` now makes visible before
+  someone ships a cheaper, weaker gate.
+  **Measured on the same machine, serially, from scratch: 24.1 min → 9.6 min**
+  (68 faults, 68 killed, 0 unproven). `--cost` names what is left: the jest
+  and replay suites now dominate, at 207s and 148s of defender time.
+
+- Style exceptions in the canonical documents are declared with a reason
+  (`docguard:quality ... off — why`) rather than satisfied by rewording.
+  This tool is defined by what must not happen — no network, no telemetry,
+  never optimistic under uncertainty — and stating those positively would
+  misdescribe them. A declared, reasoned exception is auditable; contorted
+  prose is not.
+- `--runner` accepts `python`, `pytest` and `unittest`; `--runner auto` tries
+  vitest, then jest, then python. A JavaScript project with neither vitest nor
+  jest installed now also reports why Python did not resolve.
+- The GitHub Action and the GitLab template take `runner` and `python` inputs.
+
+### Fixed
+
+- `gate --changed` treated a changed `.py` file as `non-source` and excluded it,
+  so it could never be reported as uncovered. Python is source; Python test
+  files (`test_*.py`, `*_test.py`) are tests.
+- `walk()` descended into `.venv`, `venv`, `site-packages`, `__pycache__`,
+  `.tox`, `.nox` and the pytest/mypy/ruff caches. Every `test_*.py` of every
+  installed package was collected as a test file of the project under probe.
+- `testguard claims` printed a JavaScript comment marker (`// unasserted:`)
+  when suggesting how to annotate a mock in a Python file.
+- A `--runner-cmd` whose reporter emits something other than the jest-compatible
+  JSON shape produced `unverifiable / defenders-failed-to-load` with no message
+  at all. The verdict was already safe — a report with no recognised tests is a
+  non-green baseline, never a pass — but nothing said why. It now names the
+  mismatch.
+
+## [0.6.0] - 2026-09-17
+
+Everything the field asked for. Two independent field reports on private
+AI-authored codebases drove eleven issues; this release closes all of them,
+alongside the roadmap work that landed beside it.
+
+**Read this before upgrading.** Defender discovery is now mock-aware: a test
+that `vi.mock`s or `jest.mock`s the subject can detect no fault in it and is
+no longer counted. Claims defended only by such tests therefore move to
+`NOCOVER`, which is the truth those verdicts always should have told. Expect
+new findings on the first probe after upgrading, and re-freeze your baseline
+once you have read them — they are not regressions in your code, they are
+blind spots that were previously invisible.
+
+### Added
+
+- **`testguard mcp`** — the operating loop, served over the Model Context
+  Protocol on stdio, so it survives a change of agent harness. The loop has
+  lived in a Claude Code skill and a session-start hook, and both vanish the
+  moment the harness is Cursor, Codex or whatever comes next. Five tools,
+  all **read-only**: `testguard_status`, `testguard_brief`,
+  `testguard_claims`, `testguard_evidence` and `testguard_next_command`.
+  **No tool runs a probe** — a probe is long-running, budgeted and the
+  person should see it happen, so `next_command` returns the shell line
+  instead; and no tool writes a file, because editing a claims file through
+  a connector would defeat recording every fault edit. The server declares
+  only a `tools` capability, and a tool that throws returns an `isError`
+  tool result rather than a protocol error, so one bad call never costs the
+  connection.
+  Hand-written against a pinned protocol version rather than built on the
+  official SDK: this tool keeps its single exact-pinned runtime dependency,
+  and the surface is three methods that will not grow. The tests speak the
+  wire format to a real child process and check every tool against the CLI's
+  own `--json` output, so the two cannot drift.
+  `init --mcp` prints the config for Claude Code, Cursor and Codex — printed,
+  never written, because a harness config is the person's file. Self-claims
+  `TG-MCP-IS-READ-ONLY` and
+  `TG-MCP-TOOL-FAILURE-IS-NOT-A-PROTOCOL-ERROR`. (#30)
+
+- **Contention detection and `--serial`** (#26). `probe` looks for other test
+  runners before the first run, warns naming their pids, and records them on
+  the evidence (`run.contention`) — a contended machine turns a slow suite
+  into a `TIMEOUT` or `FLAKY-DEFENDER` verdict about the load, not the claim,
+  and a later reader of that verdict can now tell. `--serial` runs one test
+  file at a time (`--no-file-parallelism`, `--runInBand`, `--workers=1`) and
+  is recorded as `run.serial`. Best effort by design: an unreadable process
+  list is no detection and never fails a probe.
+
+- **`claims --since <ref>`** — a claim that disappeared was invisible to every
+  other check: `probe` verifies what is there, `gate` sees the file covered by
+  another claim, `status` says clean. Since deleting a claim is cheaper than
+  weakening its fault (which `changedFaults` already surfaces), removal is now
+  reported: `removed-claim` and `removed-fault` gate, a rename that keeps the
+  statement verbatim is `renamed-claim` and does not, and where evidence exists
+  the finding names the verdict the claim last had. Excused by a `claim` entry
+  in `testguard.ignore.json` with a reason, with expiry honoured as everywhere
+  else. This repository's CI runs it on its own pull requests. Found the hard
+  way: a `--theirs` conflict resolution dropped two self-claims during this
+  release and nothing noticed. Self-claim `TG-REMOVED-CLAIM-IS-A-FINDING`. (#57)
+
+- **`testguard replay --since <range>`** — would this suite have caught the
+  bugs that already escaped? For each fix commit in the range (one that
+  changes source *and* a test together), it reverts only the source to the
+  parent in a scratch worktree, removes the test the fix shipped, and runs the
+  tests that import the reverted code: `caught`, `blind`, `nocover`, `flaky`
+  or `unverifiable`. One patch counts once (`git patch-id`). It reports and
+  never gates — a bug that escaped is history, not a regression in this
+  change. An injected fault is one somebody thought of; a bug that shipped is
+  ground truth, with no equivalent-mutant argument to have about it.
+- **Fault-class labelling and the first calibration.** Each replayed bug is
+  labelled with the injected-fault class its diff most resembles — the
+  scaffold producers read in reverse, deterministic, `other` rather than a
+  guess — and a `calibration` document is written beside the replay one:
+  per class, the share of real escaped bugs the suite missed, with a Wilson
+  interval and n. Only `caught` and `blind` carry information; the rest are
+  excluded from both sides. `calibration.schema.json` has had no producer
+  until now. The open question it exists to answer — does a calibration
+  learned on a repository with history transfer to a greenfield one — stays
+  open; this is the instrument, not the answer. (#35)
+- New spec kind **`replay`** (`replay.schema.json`), with semantic rules:
+  `caught` needs every run to fail by assertion, `blind` needs every run to
+  pass, `flaky` needs runs that disagree, `nocover` cannot have run tests,
+  and a duplicate patch-id is rejected. Conformance example plus two
+  must-reject documents. Self-claims
+  `TG-REPLAY-FLAKY-IS-NEVER-CAUGHT`, `TG-REPLAY-DEDUPES-BY-PATCH`,
+  `TG-CALIBRATION-EXCLUDES-UNINFORMATIVE` and `TG-LABEL-NEVER-GUESSES`.
+
+- **`baseline --restamp`** (#25). A baseline frozen from `--include-dirty`
+  evidence now records the snapshot commit and, once you commit, a clean
+  `probe` plus `--restamp` moves its `head` to that commit — only when the
+  fingerprints are identical and the tree is clean; a frozen contract is
+  never silently rewritten. `status` gains informational `notes` (never a
+  state): a baseline frozen from a snapshot or a dirty tree that predates
+  HEAD, or one whose head is not an ancestor of HEAD.
+
+
+- **Mock-aware defender discovery** (#20). A test file that `vi.mock`s /
+  `jest.mock`s the target cannot detect any fault in it and is no longer a
+  discovered defender; `NOCOVER` now means "no test imports this source
+  without mocking it". The evidence lists such files under
+  `defenders.mocking` (a *declared* defender that mocks the subject stays,
+  and is listed, as a broken evidence chain); `claims` prints the split
+  (`18 import · 16 mock · 2 can detect`).
+- **`mocked-never-asserted`** (#21): a static signal for a test that mocks
+  the target and never `expect(...)`s anything imported from it — the exact
+  signature of an escaped bug in a field report. Recorded on the evidence
+  (`defenders.signals`), printed by `claims`, carried into the brief's hints.
+  `// unasserted: <why>` above the mock silences it visibly
+  (`unasserted-annotated` with the reason).
+- Alias resolution follows tsconfig `references` (the Vite layout, where
+  `paths` live in `tsconfig.app.json`) and reads vite/vitest `resolve.alias`
+  as text, so importers from nested `__tests__/` directories are found.
+- Both known-answer fixtures gain a claim whose only importing test mocks
+  the module: expected `NOCOVER`, with the mocking file and the signal
+  recorded.
+
+- **`testguard admit <test-file> --claim <ID>`** — the two-gate rule as a
+  named verb. Sugar over `probe --claim <ID> --include-dirty --no-escalate`:
+  the named test must be a declared or discovered defender of the claim
+  (exit `3` otherwise, with the `defendedBy` line to add); `ADMITTED`
+  (exit `0`) only when every fault of the claim is `killed` N/N on defenders
+  that were green N/N unmodified; anything else is `NOT ADMITTED` (exit `1`)
+  and names the first blocking fault with the hint the brief would give.
+  `--fault <FID>` judges one fault, `--confirm 1` gives a provisional
+  `ADMITTED?`, `--json` returns `{admitted, provisional, faults[], evidence,
+  command}`. Evidence goes to `.testguard/evidence-partial.json`; nothing new
+  in the evidence schema. The market's acceptance signal for a generated
+  test is "compiles, passes, raises coverage"; this one is "fails when the
+  claim is false", and it is now one command. `status.next` for `unproven`
+  and the installed skill's fix loop point at it. Self-claim
+  `TG-ADMIT-NEEDS-ALL-KILLED`.
+
+### Changed
+
+- **`init` installs the agent layer at the git root** (#23): the skill,
+  the session-start hook and the `AGENTS.md` section go where agent
+  sessions run; the `.gitignore` lines stay beside the claims file. A
+  second project in the same repository adds a hook line and an
+  `AGENTS.md` bullet; `--here` keeps the old placement. A written file
+  that `.gitignore` swallows is reported (exit 1), never offered for
+  commit.
+- **The session-start hook resolves an installed `testguard` and contains no
+  form of `npx`** (#24): the project's `node_modules/.bin`, then the git
+  root's, then `command -v testguard`, then nothing — it exits 0 with no
+  output rather than break a session. Any earlier npx hook, `-y` or
+  `--no-install`, is replaced on the next `init`. The brief's first line
+  names the install that answered.
+
+  `--no-install` is **quiet, not offline**, which is why it is gone too:
+  measured, `npx --no-install --loglevel=http testguard-cli --version` in a
+  project with nothing installed logs
+  `npm http fetch GET 200 https://registry.npmjs.org/testguard-cli`, and
+  against an unreachable registry it exits non-zero. npm resolves the
+  packument before deciding not to install.
+
+- `probe` honours an explicit `--ref` (even `--ref HEAD`) when defender or
+  target files are dirty, and gains `--ignore-dirty` for the implicit HEAD
+  (#19). Both warn with the file names and record them in the evidence as
+  `repo.ignoredDirty` (spec: new optional field; a snapshot run can never
+  carry it). The refusal stays for the implicit HEAD without the flag — that
+  is the silent-mismatch trap the check exists for.
+
+- CI: TestGuard's self-probe runs on one Node leg instead of three, without
+  escalation, and restores the previous run's evidence from the cache so
+  unchanged claims reuse their verdicts. The verdicts do not depend on the
+  Node minor; the from-scratch probe was ~14 minutes per leg.
+
+### Fixed
+
+- **The README described a hook the code no longer writes.** Three passages
+  still documented the `npx --no-install` fallback that this release removes,
+  one of them repeating the "never fetches from the network" wording the
+  measurement above disproves — in the security-relevant paragraph, in a
+  release about detection power. Corrected, and now checked mechanically:
+  every `||`-chained `brief --text` command in the README must be one
+  `hookCommand()` actually emits, and the phrase "falls back to npx" is
+  banned outright. Both regressions were verified to fail the check before it
+  was accepted. Self-claim `TG-README-HOOK-MATCHES-THE-CODE`.
+- **A claim can be defended and still over-promise, and no probe can catch
+  that.** `TG-INIT-HOOK-NO-NETWORK` was killed 3/3 on every run while the
+  code it guarded could still reach the registry: the fault matched the
+  code, the code matched the test, and the *statement* was the thing that
+  was wrong. Fault injection measures whether a test would notice the code
+  changing; it cannot measure whether the sentence a human wrote is true of
+  the world. That is the standing limit of this method, and the only remedy
+  is reading claims against reality — which is what happened here. The
+  statement and its fault were corrected together.
+- **The session-start hook now contains no form of `npx`.** It fell back to
+  `npx --no-install`, and `--no-install` is quiet rather than offline:
+  measured, `npx --no-install --loglevel=http testguard-cli --version` in a
+  project with nothing installed logs
+  `npm http fetch GET 200 https://registry.npmjs.org/testguard-cli`, and
+  against an unreachable registry it exits non-zero. npm resolves the
+  packument before deciding not to install. The fallback is now a
+  `command -v` lookup, which covers a global install with no network at all.
+  `TG-INIT-HOOK-NO-NETWORK` was defended while its statement over-promised;
+  the statement and its fault are corrected together.
+- The PATH branch is braced. `a || b && c` binds as `(a || b) && c` in sh, so
+  the unbraced form printed the brief **twice** whenever the local binary
+  succeeded. The tests now execute the hook in all three cases (local, PATH,
+  neither) rather than matching its text.
+- `init` recognises an earlier `npx --no-install` hook as well as `npx -y`,
+  and its which-project check no longer mistakes `brief --text 2>/dev/null`
+  for a hook belonging to a directory — that misfire meant a legacy root hook
+  was never replaced.
+
+
+- **`replay` scopes to the project directory.** In a monorepo a fix commit
+  routinely touches several packages; the harness kept the out-of-project
+  files in the revert, so every cross-package fix came back
+  `revert-did-not-apply` — a tooling failure wearing the costume of a
+  verdict. Found on a real corpus, where it was two of the first three
+  commits. A commit with no source-and-test pair inside the project is no
+  longer a candidate at all. Self-claim `TG-REPLAY-SCOPES-TO-THE-PROJECT`.
+- **`replay` reverts a file the fix ADDED by removing it**, and calls a commit
+  whose source is entirely new `no-prior-version` rather than a failed revert.
+  A fix routinely adds a helper as well as changing a module, and a file that
+  did not exist at the parent cannot be checked out of it: on a real corpus
+  this turned **nineteen of forty** commits into `revert-did-not-apply` — a
+  tooling failure reading as a verdict and hiding every real result behind it.
+  An addition is not a bug the suite could have caught, so it never enters a
+  calibration. Self-claim
+  `TG-REPLAY-ADDED-FILE-IS-REMOVED-NOT-CHECKED-OUT`.
+- `replay --out <path>` now writes the calibration beside it rather than into
+  the project's `.testguard/`: the two documents are one result and splitting
+  them loses the pairing.
+
 ## [0.5.0] - 2026-09-17
 
 The change gate: unclaimed code is now a finding.
 
 ### Added
 
+- **Playwright runner, selected per file** (#15). A defender under
+  `playwright.config.*`'s `testDir` runs under Playwright whatever the
+  project runner is; one claim may list a unit test and a browser spec, and
+  the evidence records `defenders.byRunner` and `run.runners`. Playwright's
+  statuses map onto the verdict rules: `timedOut` is a timeout, never a
+  kill; `flaky` (failed, passed on retry) is a non-green run, so a defender
+  that only passes on retry is `FLAKY-DEFENDER` even though Playwright exits
+  0. Runs from several runners merge pessimistically. `--runner playwright`
+  selects it for a whole project. A browserless mixed fixture
+  (`fixtures/known-answer-playwright`, with its own dependencies) is the
+  oracle, verified by hand; a dedicated CI job runs it.
+- **Two UI `scaffold` shapes**: `element-removed` (a one-line JSX element,
+  self-closing or paired) and `handler-dropped` (an `on<Event>={…}` prop, on
+  its own line or inline). Never inside tests, fixtures or migrations.
+
+- **Two `scaffold` shapes and two fault classes.** `field-dropped` (#14):
+  a field removed from an object that is returned, built by an arrow,
+  assigned to a payload-ish name, passed to a persistence/transport call,
+  or is a schema; an entry removed from an allow-list; a spread base dropped
+  from a merge. Only lines that can go on their own; never inside tests,
+  fixtures or migrations. `argument-swapped` (#22): a call kept with its
+  parameter-derived first argument swapped for `undefined` (and `{}` when
+  the argument is a call) — the seam fault a field report found behind an
+  escaped bug that no earlier shape could express. The known-answer fixture
+  gains one of each, verified by hand: the dropped `content` field
+  **survives** (the same `objectContaining` blind spot as the exhibit), the
+  swapped argument is killed.
+
 - **`testguard gate --changed <ref>`** — the change gate. Every escaped
   defect in the field reports was a *claim gap*: the feature shipped green
   with zero claims, and `probe` is silent about unclaimed code by