testguard-cli 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -7,6 +7,131 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.2] - 2026-09-19
+
+Automated weekly release — everything merged since `v0.9.1`.
+
+### Changed
+
+- feat(claims): preflight fault anchors (#126)
+- chore(homebrew): sha256 for v0.9.1 (#125)
+
+
+### Added
+
+- `claims --check-anchors` locates every exact fault anchor and syntax-checks
+  supported in-memory JavaScript and Python replacements without starting a
+  runner or touching the tree. CI runs the sub-second preflight before the
+  self-probe, while `status` reports rotted anchors as `invalid-anchors` with
+  the precise fault to repair. Repairs remain a reviewed judgement call:
+  there is deliberately no fuzzy match or `--fix`.
+
+## [0.9.1] - 2026-09-19
+
+Automated weekly release — everything merged since `v0.9.0`.
+
+### Changed
+
+- docs: the brief catches up with the tool, and stops falling behind (#112)
+- chore(homebrew): sha256 for v0.9.0 (#110)
+- feat(cost): two ceilings, the report where it is read, and three claims off expensive defenders (#113)
+- fix(release): approve the runs GITHUB_TOKEN's own PR leaves held (#111)
+
+
+### Added
+- **A second cost ceiling, on the claim.** The total alone cannot see the
+  failure it was meant to catch: a new calibration claim cost 51 s for two
+  faults purely by being written into `replay.test.mjs` rather than
+  `calibration.test.mjs`, and re-pointing it took it to 4.9 s while the total
+  never moved. A per-fault average is worse — the regression that prompted
+  this budget raised the fault count 59 to 91 while per-fault cost barely
+  moved, so an average would have reported everything fine.
+
+  `perClaimSeconds` is 100 s, just above today's worst claim
+  (`TG-ADMIT-NEEDS-ALL-KILLED`, **87 s in CI** for one fault), so the rule
+  reads: no new claim may be worse than the worst we already have. Calibrated
+  against CI and not the local figure — 75 s, set from that claim's local
+  66.5 s, tripped on the first CI run. This file already warns about exactly
+  that for the total (950 s was 18% over local but 4.6% over CI, and the first
+  PR adding a claim tripped it); the same error applies one level down. A breach names the claim
+  and its remedy — a cheaper defender, not a bigger budget. The field is
+  optional and additive: a budget without one behaves exactly as before.
+- **The cost report goes to the CI job summary, not only the log.** The gate
+  went from 9.6 to 23.6 minutes across one merged pull request and nothing
+  said a word, because `--cost` only ever printed into a log nobody opens
+  while it is passing. The summary is read without opening anything, so the
+  number is in front of a reviewer while the change is still a change.
+
+### Performance
+- **Three claims moved off expensive shared defenders: 65 s, ~30 s and ~30 s
+  down to under 2 s each.** All three faulted a *pure* function while naming
+  an integration test file, and a claim pays for every test in the file it
+  names. `TG-SURVIVOR-PROVES-THE-SUBJECT-RUNS` faults `classify()` but was
+  defended by `negative-control.test.mjs`, which spawns real runners against
+  fixture repositories; `TG-LABEL-NEVER-GUESSES` faults `labelDiff()` and
+  `TG-REPLAY-FLAKY-IS-NEVER-CAUGHT` faults `classifyReplay()`, both defended
+  by `replay.test.mjs`, which builds a scripted git corpus.
+
+  Two were a straight move of an already-isolated `describe` block into
+  `test/label.test.mjs` and `test/replay-verdict.test.mjs`; only the `classify`
+  case needed a test written. Each was proved with `admit` — passes on HEAD and
+  fails on every fault, 3/3 — *before* the expensive defender was dropped, and
+  never the other way round. The integration files keep their remaining claims,
+  where the fixture is the point.
+
+### Changed
+- **The cost budget is 1230 s, from 1350.** 1350 was set defensively against a
+  reuse-affected 1123 s, because this budget is defined against a from-scratch
+  probe and none had run yet. `release.yml` then measured **1081 s** at 129
+  faults on the v0.9.0 release commit with no reuse — so the six field-report
+  claims cost +82 s, not the +120 s a per-fault average predicted. 1230 is
+  ~14% over 1081, the same headroom rule that set 1100 against 962. Leaving it
+  at 1350 would have let a 25% regression pass unnoticed.
+
+### Fixed
+- **The release no longer waits for a human to click Approve.** v0.9.0 sat with
+  every required check green and merged nothing. The `pull_request` runs a
+  release PR creates are held at `action_required`, because the repository
+  requires approval from first-time contributors and `github-actions[bot]` is
+  permanently one — it never authors a merged commit, so it can never
+  graduate. Held runs leave check suites QUEUED on the head sha, the status
+  rollup never reaches a terminal state, and auto-merge waits on it even though
+  `test (20/22/24)` are already green from the dispatched run.
+
+  `scheduled-release.yml` now approves those runs itself. `GITHUB_TOKEN` is
+  permitted to do this — `actions: write` carries the approve permission,
+  measured 201 against a bot PR's own held run — and the workflow already held
+  that permission, so nothing was granted and no secret was added. It may still
+  not approve a *review*, which is a different gate and remains ours alone.
+  A run left held after the poll is an `::error::` naming the run, never a
+  silent wait.
+
+  This is the third `GITHUB_TOKEN` wall in the same chain, after "raises no
+  `pull_request` event" (#105) and "its push raises no `push` event" (the
+  hourly sweep in release.yml). All three have the same root: an action taken
+  by `GITHUB_TOKEN` does not trigger the event that would normally follow it.
+
+### Documentation
+- **The technical brief describes the tool that exists.** It was last rendered
+  when it covered one verb, `probe`, and said nothing about `replay` and its
+  calibration — the empirical answer to whether an injected fault resembles a
+  real bug, which is the question a document arguing "evidence, not output"
+  can least afford to omit. A new page covers the eleven verbs and the
+  calibration, carrying the README's own framing: the greenfield transfer is
+  unproven, and `replay` is the instrument rather than the answer. The verdict
+  table, the cost formula and the prior-art section were checked against the
+  code and left alone.
+- **The brief's PDF is rendered by the release instead of by memory.** Its
+  masthead read `v0.6` through three releases because nothing ever ran
+  `build-one-pager.mjs`. The HTML masthead is now a version surface and
+  `scheduled-release.yml` re-renders the PDF in the same step as the sync —
+  the same step, because an HTML and a PDF that disagree are worse than a
+  document uniformly out of date. `--require-chrome` makes a missing browser
+  fail the release rather than silently commit a stale PDF, and every render
+  must produce exactly one sheet per `.page` div: a section a few pixels too
+  tall spills onto a second sheet with no warning from Chrome, contradicting
+  the "Page N of M" footers the document prints about itself.
+
 ## [0.9.0] - 2026-09-18
 
 Automated weekly release — everything merged since `v0.8.1`.

package/README.md

@@ -80,8 +80,9 @@ risk. TestGuard binds every fault to a **stated claim**, so the output is not
 a score but a finding: *"Your project says a missing scope fails closed.
 Nothing checks that."* That is the difference between a metric and an audit.
 
-📄 **[Read the three-page technical brief (PDF)](docs/testguard-explained.pdf)**
-— the idea on page one, mechanics and prior art after it.
+📄 **[Read the six-page technical brief (PDF)](docs/testguard-explained.pdf)**
+— the idea on page one, then the field evidence, the anatomy of a run, the
+verdicts, the loop and its calibration, and the prior art.
 
 ## Why
 
@@ -126,9 +127,9 @@ raises coverage. TestGuard admits it because it fails when the claim is false.
 | 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.9.0` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.9.2` — see [`action.yml`](./action.yml) |
 | pre-commit | `repo: https://github.com/raccioly/testguard`, hooks `testguard-claims`, `testguard-probe` |
-| GitLab CI | `include: - remote: https://raw.githubusercontent.com/raccioly/testguard/v0.9.0/packaging/gitlab/testguard.gitlab-ci.yml` with `inputs:` — see [`packaging/gitlab/`](./packaging/gitlab/testguard.gitlab-ci.yml) |
+| GitLab CI | `include: - remote: https://raw.githubusercontent.com/raccioly/testguard/v0.9.2/packaging/gitlab/testguard.gitlab-ci.yml` with `inputs:` — see [`packaging/gitlab/`](./packaging/gitlab/testguard.gitlab-ci.yml) |
 
 Projects that set `min-release-age` in `.npmrc` cannot see a version published
 less than that many days ago (`ENOVERSIONS`); install that one with
@@ -140,6 +141,7 @@ less than that many days ago (`ENOVERSIONS`); install that one with
 npx testguard-cli init                      # install the agent layer at the git root
 npx testguard-cli status --json             # where the project is, and the ONE next action
 npx testguard-cli claims                    # what does this project claim, and is each claim probeable?
+npx testguard-cli claims --check-anchors    # fail fast if an exact anchor moved or a replacement no longer parses
 npx testguard-cli scaffold src/auth.ts      # propose faults for a file, as a draft to keep or drop
 npx testguard-cli probe                     # try to falsify each claim; report what the tests missed
 npx testguard-cli admit test/auth.test.ts --claim AUTH-ADMIN   # does this test satisfy the two-gate rule?
@@ -150,8 +152,9 @@ npx testguard-cli replay --since v1.0..HEAD # would this suite have caught the b
 npx testguard-cli mcp                       # serve the read-only loop over MCP, on stdio
 ```
 
-Exit codes are the contract: `0` nothing new to prove, `1` unproven claims or
-unclaimed changes, `2` a precondition failed and nothing was probed, `3` usage.
+Exit codes are the contract: `0` nothing new to prove, `1` unproven claims,
+unclaimed changes or invalid fault anchors, `2` a precondition failed and
+nothing was probed, `3` usage.
 Every command accepts `--json`.
 
 ## How it works
@@ -176,6 +179,10 @@ npx testguard-cli admit test/x.test.ts --claim X   # is this test green on HEAD
    claim and every fault records who produced it. `testguard claims`
    validates the file and reports drift against `@claim <ID>` annotations in
    source. Test files are deliberately not scanned — a claim asserted by a test is the authorship trap the tool exists for — and annotation ids must contain a hyphen so prose is never mistaken for one.
+   `claims --check-anchors` additionally locates every exact anchor and parses
+   each in-memory JavaScript or Python replacement. It runs no tests, creates
+   no worktree and changes no file, so a moved anchor is reported before an
+   expensive probe. It reports and stops; it never guesses a new anchor.
 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
@@ -444,6 +451,10 @@ is reported as `EXPIRED`.
 With a reference known, `status --changed <ref>` reports `unclaimed-changes`
 **before** any evidence state and makes the claim the next action; the brief
 lists the unclaimed files first. The claim is written before more code.
+After claim coverage, `status` reports `invalid-anchors` before any evidence
+state when an exact fault anchor is missing or ambiguous, and points at the
+fault definition to repair. Repair preserves the fault's meaning and requires
+a re-probe; there is deliberately no `--fix`.
 
 **In CI the base is detected** — GitHub Actions (`GITHUB_BASE_REF`) and GitLab
 merge request pipelines (`CI_MERGE_REQUEST_DIFF_BASE_SHA`, then
@@ -458,12 +469,12 @@ detected base that does not resolve is a warning for `status` and `brief`
 # GitHub Actions
 - uses: actions/checkout@v4
   with: { fetch-depth: 0 }
-- uses: raccioly/testguard@v0.9.0
+- uses: raccioly/testguard@v0.9.2
   with: { command: gate }
 
 # GitLab CI — the component-shaped template: gate + probe, brief as an artifact and, opted in, as a merge-request note
 include:
-  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.9.0/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.9.2/packaging/gitlab/testguard.gitlab-ci.yml'
     inputs: { dir: backend, post_note: true }   # post_note needs TESTGUARD_GITLAB_TOKEN (api scope); one note, updated in place
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Breaks your code on purpose and reports every promise your tests did not notice breaking. Mutation testing bound to the claims a project makes — vitest, jest, Playwright, pytest and unittest.",
   "type": "module",
   "license": "MIT",

package/spec/GATE-SEMANTICS.md

@@ -395,6 +395,26 @@ changed); `1` at least one uncovered file (or strict mode over an
 all-excluded change); `2` the change cannot be evaluated (unresolvable
 reference, invalid claims or ignore file, no repository); `3` no reference.
 
+## Anchor preflight
+
+`claims --check-anchors` answers what is knowable before a runner starts. For
+every fault-injection fault it reads the target, applies the same exact
+`locate()` arithmetic as a probe, and reports `ok`, `anchor-missing` or
+`anchor-ambiguous` with the observed and expected hit counts. When a language
+has a cheap parser, it also parses the in-memory replacement (`node --check`
+semantics for JavaScript modules, `compile()` for Python). Unsupported
+languages are anchor-checked and otherwise skipped without inference.
+
+One non-`ok` anchor or non-parsing supported replacement exits `1`. The check
+runs no tests, creates no worktree, reads no git state and writes no source.
+It is not evidence that a defender detects the fault; the self-probe still
+runs after it. There is no automatic repair or fuzzy relocation: choosing a
+new anchor is a semantic edit to the claim and must be reviewed and re-probed.
+
+`invalid-anchors` precedes every evidence state in the status document (after
+`unclaimed-changes`, when a change reference is known). Its next action is
+`repair-fault`, naming the first fault and `testguard claims --check-anchors`.
+
 ## Severity floor
 
 `--severity <level>` gates only findings whose claim severity is at or above

package/spec/lib/validate.mjs

@@ -233,12 +233,15 @@ const semantic = {
 
   status(doc) {
     const errors = [];
-    if (['write-test', 'review-fault-change'].includes(doc.next.action) && !doc.next.target) errors.push({ path: '/next/target', message: `${doc.next.action} requires a target` });
+    if (['write-test', 'review-fault-change', 'repair-fault'].includes(doc.next.action) && !doc.next.target) errors.push({ path: '/next/target', message: `${doc.next.action} requires a target` });
     if (doc.next.action === 'claim' && !doc.next.file) errors.push({ path: '/next/file', message: 'claim requires the file the claim is about' });
     if (doc.state === 'no-claims' && doc.counts.claims !== 0) errors.push({ path: '/counts/claims', message: 'no-claims with a non-zero claim count' });
     if (doc.state === 'clean' && (doc.counts.new ?? 0) > 0) errors.push({ path: '/state', message: 'clean with new findings' });
     if (doc.state === 'unclaimed-changes' && !(doc.changes && doc.changes.uncovered.length > 0)) errors.push({ path: '/changes/uncovered', message: 'unclaimed-changes requires at least one uncovered changed file' });
     if (doc.state === 'unclaimed-changes' && doc.next.action !== 'claim') errors.push({ path: '/next/action', message: 'unclaimed-changes requires next.action = claim' });
+    if (doc.state === 'invalid-anchors' && !(doc.invalidFaults?.length > 0)) errors.push({ path: '/invalidFaults', message: 'invalid-anchors requires at least one invalid fault' });
+    if (doc.state === 'invalid-anchors' && doc.next.action !== 'repair-fault') errors.push({ path: '/next/action', message: 'invalid-anchors requires next.action = repair-fault' });
+    if (doc.invalidFaults?.length > 0 && doc.state !== 'invalid-anchors') errors.push({ path: '/state', message: 'invalid fault anchors are hidden behind a later state; invalid-anchors precedes every evidence state' });
     if (doc.evidenceSource && !doc.evidenceHead) errors.push({ path: '/evidenceHead', message: 'evidence was read, so the commit it describes must be recorded' });
     if (doc.changes && doc.changes.uncovered.length > 0 && !['no-claims', 'unclaimed-changes'].includes(doc.state)) errors.push({ path: '/state', message: 'uncovered changed files are hidden behind a later state; unclaimed-changes precedes every evidence state' });
     return errors;

package/spec/schemas/brief.schema.json

@@ -39,7 +39,7 @@
       "type": "object",
       "required": ["action", "command", "why"],
       "properties": {
-        "action": { "enum": ["scaffold", "claim", "probe", "write-test", "baseline", "review-fault-change", "none"] },
+        "action": { "enum": ["scaffold", "claim", "probe", "write-test", "baseline", "repair-fault", "review-fault-change", "none"] },
         "command": { "type": "string", "minLength": 1, "maxLength": 1024 },
         "why": { "type": "string", "minLength": 1, "maxLength": 2000 }
       },

package/spec/schemas/status.schema.json

@@ -26,10 +26,11 @@
       "$ref": "urn:claimspec:v1:common#/$defs/isoDateTime"
     },
     "state": {
-      "description": "no-claims: no claims file. unclaimed-changes: the change measured against a reference touches source files that carry no claim and no excusing ignore entry (only computed when a reference is known; it precedes every evidence state because the claim is written before more code). unprobed: claims but no confirmed evidence. evidence-stale: evidence exists but a claim, fault, target or defender changed since. provisional-only: only sub-N evidence exists. unproven: current evidence has findings not covered by the baseline. clean: every finding is killed or baselined.",
+      "description": "no-claims: no claims file. unclaimed-changes: the change measured against a reference touches source files that carry no claim and no excusing ignore entry (only computed when a reference is known; it precedes every evidence state because the claim is written before more code). invalid-anchors: one or more exact fault anchors are missing or ambiguous, so probing would be unable to apply them. unprobed: claims but no confirmed evidence. evidence-stale: evidence exists but a claim, fault, target or defender changed since. provisional-only: only sub-N evidence exists. unproven: current evidence has findings not covered by the baseline. clean: every finding is killed or baselined.",
       "enum": [
         "no-claims",
         "unclaimed-changes",
+        "invalid-anchors",
         "unprobed",
         "evidence-stale",
         "provisional-only",
@@ -54,6 +55,7 @@
             "write-test",
             "baseline",
             "review-fault-change",
+            "repair-fault",
             "none"
           ]
         },
@@ -188,6 +190,23 @@
         "additionalProperties": false
       }
     },
+    "invalidFaults": {
+      "description": "Faults whose exact text anchor does not locate in the current target. These precede every evidence state: a probe cannot learn anything from a fault it cannot apply.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["claimId", "subjectId", "file", "reason", "hits", "expected"],
+        "properties": {
+          "claimId": { "$ref": "urn:claimspec:v1:common#/$defs/identifier" },
+          "subjectId": { "$ref": "urn:claimspec:v1:common#/$defs/identifier" },
+          "file": { "$ref": "urn:claimspec:v1:common#/$defs/repoPath" },
+          "reason": { "enum": ["anchor-missing", "anchor-ambiguous"] },
+          "hits": { "type": "integer", "minimum": 0 },
+          "expected": { "type": "integer", "minimum": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
     "findings": {
       "description": "Unproven findings from the current evidence, ranked, new first, capped.",
       "type": "array",

package/src/claims/anchors.mjs

@@ -0,0 +1,218 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { dirname, extname, join, resolve } from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { locate, mutate } from '../probe/inject.mjs';
+import { resolveInterpreter } from '../probe/runners/python.mjs';
+
+const JS_EXTENSIONS = new Set(['.js', '.mjs', '.cjs']);
+
+const NODE_SYNTAX_CHECK = `
+const vm = require('node:vm');
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  const results = JSON.parse(input).map(({ file, source, type }) => {
+    try {
+      if (type === 'module') new vm.SourceTextModule(source, { identifier: file });
+      else new vm.Script(source, { filename: file });
+      return { status: 'ok' };
+    } catch (error) {
+      return { status: 'invalid', message: error.name + ': ' + error.message };
+    }
+  });
+  process.stdout.write(JSON.stringify(results));
+});
+`;
+
+const PYTHON_SYNTAX_CHECK = `
+import json, sys
+results = []
+for item in json.load(sys.stdin):
+    try:
+        compile(item["source"], item["file"], "exec")
+        results.append({"status": "ok"})
+    except (SyntaxError, IndentationError, TabError) as error:
+        results.append({"status": "invalid", "message": type(error).__name__ + ": " + str(error)})
+json.dump(results, sys.stdout)
+`;
+
+const isInjection = (fault) => (fault.method ?? 'fault-injection') === 'fault-injection';
+const keyOf = (claimId, faultId) => `${claimId}\0${faultId}`;
+
+/** Read each target once and locate every injection fault without touching disk. */
+function inspectLocations(projectDir, claims) {
+  const sources = new Map();
+  const work = [];
+  for (const claim of claims.claims) {
+    for (const fault of claim.faults) {
+      if (!isInjection(fault)) {
+        work.push({ claim, fault, result: { claimId: claim.id, faultId: fault.id, file: fault.file, status: 'ok', check: 'not-applicable' } });
+        continue;
+      }
+      const path = resolve(projectDir, fault.file);
+      let source;
+      if (sources.has(path)) source = sources.get(path);
+      else {
+        source = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
+        sources.set(path, source);
+      }
+      const anchor = source === undefined
+        ? { status: 'anchor-missing', hits: 0, expected: fault.expectHits ?? 1 }
+        : locate(source, fault);
+      work.push({
+        claim,
+        fault,
+        source,
+        result: { claimId: claim.id, faultId: fault.id, file: fault.file, status: anchor.status, hits: anchor.hits, expected: anchor.expected },
+      });
+    }
+  }
+  return work;
+}
+
+const summarize = (results, durationMs) => ({
+  checked: results.length,
+  ok: results.filter((r) => r.status === 'ok').length,
+  invalid: results.filter((r) => r.status !== 'ok').length,
+  durationMs: Math.round(durationMs),
+  results,
+});
+
+/** Exact anchor checks only. Synchronous so status and MCP stay synchronous. */
+export function checkAnchorLocations(projectDir, claims) {
+  const started = performance.now();
+  return summarize(inspectLocations(projectDir, claims).map((x) => x.result), performance.now() - started);
+}
+
+function firstError(stderr) {
+  const lines = stderr.split('\n').map((line) => line.trim()).filter(Boolean);
+  return lines.find((line) => /(?:Syntax|Indentation|Tab)Error:/.test(line))
+    ?? lines.find((line) => /error/i.test(line))
+    ?? lines.at(-1)
+    ?? 'replacement does not compile';
+}
+
+function runBatchCheck(command, args, items, timeoutMs = 5_000) {
+  if (!items.length) return Promise.resolve([]);
+  return new Promise((resolveRun, reject) => {
+    let child;
+    try {
+      child = spawn(command, args, { stdio: ['pipe', 'pipe', 'pipe'], env: { ...process.env, CI: '1' } });
+    } catch (error) {
+      reject(error);
+      return;
+    }
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    child.stdout.on('data', (chunk) => {
+      if (stdout.length < 16_777_216) stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+      if (stderr.length < 16_384) stderr += chunk;
+    });
+    child.on('error', reject);
+    child.stdin.on('error', () => {});
+    child.stdin.end(JSON.stringify(items));
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGKILL');
+    }, timeoutMs);
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (timedOut) reject(new Error(`${command} syntax check timed out after ${timeoutMs}ms`));
+      else if (code !== 0) reject(new Error(`${command} syntax check failed: ${firstError(stderr)}`));
+      else {
+        try {
+          const results = JSON.parse(stdout);
+          if (!Array.isArray(results) || results.length !== items.length) throw new Error('unexpected result count');
+          resolveRun(results);
+        } catch (error) {
+          reject(new Error(`${command} syntax check returned invalid output: ${error.message}`));
+        }
+      }
+    });
+  });
+}
+
+function packageType(projectDir, file, cache) {
+  if (extname(file) === '.mjs') return 'module';
+  if (extname(file) === '.cjs') return 'commonjs';
+  let dir = dirname(resolve(projectDir, file));
+  const root = resolve(projectDir);
+  while (dir.startsWith(root)) {
+    if (cache.has(dir)) return cache.get(dir);
+    const pkg = join(dir, 'package.json');
+    if (existsSync(pkg)) {
+      const type = JSON.parse(readFileSync(pkg, 'utf8')).type === 'module' ? 'module' : 'commonjs';
+      cache.set(dir, type);
+      return type;
+    }
+    if (dir === root) break;
+    dir = dirname(dir);
+  }
+  return 'commonjs';
+}
+
+/**
+ * Anchor every fault, then ask the language parser whether the in-memory
+ * replacement still compiles. Unsupported languages (and Python when no
+ * interpreter resolves) are intentionally left anchor-only.
+ */
+export async function checkAnchors(projectDir, claims, { python } = {}) {
+  const started = performance.now();
+  const work = inspectLocations(projectDir, claims);
+  const candidates = work.filter((x) => x.result.status === 'ok' && x.source !== undefined && isInjection(x.fault));
+  const hasPython = candidates.some((x) => extname(x.fault.file) === '.py');
+  const interpreter = hasPython ? await resolveInterpreter({ projectDir, python, budgetMs: 5_000 }) : undefined;
+  const packageTypes = new Map();
+  const javascript = [];
+  const pythonSources = [];
+  for (const candidate of candidates) {
+    const { fault, source } = candidate;
+    const extension = extname(fault.file);
+    const changed = mutate(source, fault);
+    if (JS_EXTENSIONS.has(extension)) {
+      javascript.push({ candidate, file: fault.file, source: changed, type: packageType(projectDir, fault.file, packageTypes) });
+    } else if (extension === '.py' && interpreter && !interpreter.error) {
+      pythonSources.push({ candidate, file: fault.file, source: changed });
+    }
+  }
+
+  // One parser process per language keeps this a cheap preflight even when a
+  // claims file has hundreds of faults. The Node VM constructors use the same
+  // V8 grammar as `node --check` and compile without linking or executing code.
+  const [javascriptResults, pythonResults] = await Promise.all([
+    runBatchCheck(process.execPath, ['--no-warnings', '--experimental-vm-modules', '-e', NODE_SYNTAX_CHECK], javascript),
+    interpreter && !interpreter.error
+      ? runBatchCheck(interpreter.path, ['-c', PYTHON_SYNTAX_CHECK], pythonSources)
+      : [],
+  ]);
+
+  const parsedByFault = new Map();
+  javascript.forEach(({ candidate }, index) => parsedByFault.set(keyOf(candidate.claim.id, candidate.fault.id), { language: 'javascript', ...javascriptResults[index] }));
+  pythonSources.forEach(({ candidate }, index) => parsedByFault.set(keyOf(candidate.claim.id, candidate.fault.id), { language: 'python', ...pythonResults[index] }));
+
+  const results = work.map(({ claim, fault, result }) => {
+    const parsed = parsedByFault.get(keyOf(claim.id, fault.id));
+    if (!parsed) return result;
+    if (parsed.status === 'invalid') return { ...result, status: 'fault-invalid', syntax: parsed };
+    return { ...result, syntax: parsed };
+  });
+  return summarize(results, performance.now() - started);
+}
+
+export function renderAnchorChecks(report) {
+  const lines = report.results.map((result) => {
+    const label = result.status.toUpperCase().padEnd(16);
+    const hits = result.hits === undefined ? 'no text anchor for this method' : `${result.hits} hit${result.hits === 1 ? '' : 's'}, expected ${result.expected}`;
+    const syntax = result.syntax?.status === 'ok'
+      ? `; ${result.syntax.language} syntax ok`
+      : result.syntax?.message ? `; ${result.syntax.language}: ${result.syntax.message}` : '';
+    return `${label} ${result.claimId}/${result.faultId}  ${result.file} — ${hits}${syntax}`;
+  });
+  lines.push(`anchor preflight: ${report.checked} faults checked, ${report.ok} ok, ${report.invalid} invalid in ${report.durationMs}ms`);
+  return lines.join('\n');
+}

package/src/cli.mjs

@@ -26,7 +26,7 @@ export const USAGE = `testguard ${VERSION} — proves a test suite defends the c
 
   testguard status [dir]     where the project is and the ONE next action; --json is the machine entry point
   testguard init [dir]       install the agent layer at the git root (skill, session-start hook, AGENTS.md section) and the .gitignore lines in [dir]
-  testguard claims [dir]     list the claims file and report drift against @claim annotations in code
+  testguard claims [dir]     list claims and drift; --check-anchors also verifies every exact anchor and replacement syntax
   testguard probe [dir]      inject each claim's faults, run its defenders, report what survived
   testguard baseline [dir]   freeze today's unproven findings so only new ones gate
   testguard brief [dir]      emit the blind-spot block for an agent's session-start context
@@ -95,7 +95,9 @@ gate       --changed <ref>   measure the change since merge-base(ref, HEAD); aut
            --strict          a non-empty change that evaluates nothing is a failure, not a note
            --ignore <path>   ignore file (default: <dir>/testguard.ignore.json; kind=path entries excuse files, with a reason)
            exit 0 every changed source file is claimed or excused · 1 unclaimed file · 2 cannot evaluate · 3 no reference
-status     --json (exit 0 clean · 1 unproven/stale/unclaimed · 2 nothing to probe yet)
+claims     --check-anchors   locate every fault without running tests; JS/MJS and Python replacements are syntax-checked in memory
+           --json includes anchorChecks; exit 1 when an anchor is missing/ambiguous or a supported replacement does not compile
+status     --json (exit 0 clean · 1 unproven/stale/unclaimed/invalid anchors · 2 nothing to probe yet)
            --evidence <path>  read this evidence instead of .testguard/evidence.json (e.g. CI's, fetched as an artifact); staleness is still computed from the recorded input hashes, and both commits are named
            --changed <ref>   also compute claim coverage of the change; unclaimed-changes then precedes every evidence state
 init       --force (replace an existing skill file)  --here (keep the agent layer in [dir] instead of the git root)  --json
@@ -163,6 +165,7 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
         text: { type: 'boolean', default: false },
         markdown: { type: 'boolean', default: false },
         cost: { type: 'boolean', default: false },
+        'check-anchors': { type: 'boolean', default: false },
         progress: { type: 'string' },
         help: { type: 'boolean', short: 'h', default: false },
         version: { type: 'boolean', short: 'v', default: false },

package/src/commands/claims.mjs

@@ -9,12 +9,16 @@ import { evidencePath } from './probe.mjs';
 import { costReport, renderCost } from '../probe/cost.mjs';
 import { readSpecDoc } from '../evidence/writer.mjs';
 import { existsSync } from 'node:fs';
+import { checkAnchors, renderAnchorChecks } from '../claims/anchors.mjs';
 
 export async function claimsCommand({ projectDir, values, version }, io) {
   const path = values.claims ? resolve(values.claims) : defaultClaimsPath(projectDir);
   const claims = loadClaims(path);
   const annotations = scanAnnotations(projectDir);
   const drift = reconcile(claims, annotations);
+  const anchorChecks = values['check-anchors']
+    ? await checkAnchors(projectDir, claims, { python: values.python ? resolve(values.python) : undefined })
+    : undefined;
 
   // A claim that disappeared is invisible to every other command; compare
   // identities against a reference when one is given.
@@ -31,7 +35,7 @@ export async function claimsCommand({ projectDir, values, version }, io) {
   }
 
   if (values.json) {
-    io.out(JSON.stringify({ path, claims, annotations, drift, ...(removed ? { removed } : {}), ...(cost ? { cost } : {}) }, null, 2));
+    io.out(JSON.stringify({ path, claims, annotations, drift, ...(anchorChecks ? { anchorChecks } : {}), ...(removed ? { removed } : {}), ...(cost ? { cost } : {}) }, null, 2));
   } else {
     const annotated = new Set(drift.annotated);
     io.out(`${claims.claims.length} claims in ${path} — ${annotated.size} carry a @claim annotation in source (test files are not scanned)`);
@@ -74,6 +78,10 @@ export async function claimsCommand({ projectDir, values, version }, io) {
       io.out('');
       io.out(renderCost(cost));
     }
+    if (anchorChecks) {
+      io.out('');
+      io.out(renderAnchorChecks(anchorChecks));
+    }
   }
-  return drift.undeclared.length || drift.stale.length || (removed?.removed.length ?? 0) > 0 ? 1 : 0;
+  return drift.undeclared.length || drift.stale.length || (removed?.removed.length ?? 0) > 0 || (anchorChecks?.invalid ?? 0) > 0 ? 1 : 0;
 }

package/src/init/templates/SKILL.md

@@ -22,6 +22,7 @@ which files exist. `state` is one of:
 |---|---|---|
 | `no-claims` | no `testguard.claims.json` | `testguard scaffold <file>` for a file with guards; replace every `TODO:` statement with what the code guarantees; keep or drop each proposal; move the claims into `testguard.claims.json` |
 | `unclaimed-changes` | files you changed carry no claim (only when a reference is known: `--changed <ref>`, or CI's base branch) | `next.file` names the first; `testguard scaffold <file>` and state the claim, or add a `testguard.ignore.json` path entry with a reason a reviewer will accept. **Before** writing more code. |
+| `invalid-anchors` | an exact fault anchor moved or became ambiguous | run `testguard claims --check-anchors`; repair `next.target` in the claims file without changing what the fault means, then re-probe. Never guess or auto-fix an anchor. |
 | `unprobed` | claims never probed | `testguard probe` |
 | `evidence-stale` | code, tests or claims changed since the evidence | `testguard probe --include-dirty` (or `--claim <ID>` for one) |
 | `provisional-only` | only `--confirm 1` evidence exists | `testguard probe --confirm 3` |
@@ -45,7 +46,10 @@ code by construction. So, for every source file you create or change:
    thin wrapper whose logic is claimed elsewhere): a `path` entry in
    `testguard.ignore.json` with a reason and, where possible, an `expires`.
    The gate prints every entry it relied on; a reviewer reads them.
-4. Then `testguard admit <test-file> --claim <ID>` for the new claim's test (or `testguard probe --claim <ID> --include-dirty` for the full report).
+4. After editing guarded code, run `testguard claims --check-anchors`. Repair
+   any named fault definition without weakening its meaning; the check never
+   relocates an anchor for you.
+5. Then `testguard admit <test-file> --claim <ID>` for the new claim's test (or `testguard probe --claim <ID> --include-dirty` for the full report).
 
 ## Verdict → action
 

package/src/probe/cost.mjs

@@ -163,18 +163,41 @@ export function renderCost(report, { limit = 10 } = {}) {
  *
  * Pure. Reads a report, returns a decision; the caller owns exit codes and I/O.
  */
-export function checkCostBudget(report, { budgetSeconds, previousMs, worst = 5 } = {}) {
+export function checkCostBudget(report, { budgetSeconds, perClaimSeconds, previousMs, worst = 5 } = {}) {
   if (typeof budgetSeconds !== 'number' || !Number.isFinite(budgetSeconds) || budgetSeconds <= 0) {
     throw new TypeError('checkCostBudget: budgetSeconds must be a positive number');
   }
   const budgetMs = budgetSeconds * 1000;
   const totalMs = report.totalMs ?? 0;
+
+  // ── Why a SECOND ceiling, on the claim. ──
+  // The total alone is a treadmill: claims should grow forever, so it can only
+  // ever be raised, and a number that always goes up stops being read. A
+  // per-FAULT average is worse — the regression that prompted this budget
+  // raised the fault count 59 -> 91 while per-fault cost barely moved, so an
+  // average would have reported everything fine.
+  //
+  // The measured pathology is per-CLAIM, and it is a claim naming an expensive
+  // SHARED defender: a claim pays for every test in the file it names, so
+  // TG-ADMIT-NEEDS-ALL-KILLED costs 67 s for ONE fault. A new calibration
+  // claim landed at 51 s for two faults purely by being written into
+  // replay.test.mjs instead of calibration.test.mjs; re-pointing it took it to
+  // 4.9 s. The total absorbed that silently. This does not.
+  //
+  // So the rule is "no new claim may be worse than the worst we already have",
+  // which stays meaningful as claims are added and tightens as they get cheaper.
+  const perClaimMs = typeof perClaimSeconds === 'number' && perClaimSeconds > 0 ? perClaimSeconds * 1000 : undefined;
+  const overPerClaim = perClaimMs === undefined ? [] : (report.claims ?? [])
+    .filter((c) => c.ms > perClaimMs)
+    .map((c) => ({ id: c.claimId, ms: c.ms, runs: c.runs }));
+
   return {
-    ok: totalMs <= budgetMs,
+    ok: totalMs <= budgetMs && overPerClaim.length === 0,
     totalMs,
     budgetMs,
     overByMs: Math.max(0, totalMs - budgetMs),
     headroomMs: Math.max(0, budgetMs - totalMs),
+    ...(perClaimMs === undefined ? {} : { perClaimMs, overPerClaim }),
     ...(typeof previousMs === 'number' ? { previousMs, deltaMs: totalMs - previousMs } : {}),
     // Named so a failure opens with which claims to look at, not just a number.
     // claimCosts emits `claimId`; reading `id` here printed "undefined" for every
@@ -189,10 +212,24 @@ export function renderCostBudget(d) {
   const delta = typeof d.deltaMs === 'number'
     ? ` (${d.deltaMs >= 0 ? '+' : ''}${secs(Math.abs(d.deltaMs))} against the previous run's ${secs(d.previousMs)})`
     : '';
-  out.push(d.ok
-    ? `cost ${secs(d.totalMs)} of a ${secs(d.budgetMs)} budget — ${secs(d.headroomMs)} to spare${delta}.`
-    : `COST BUDGET EXCEEDED: ${secs(d.totalMs)} against a ${secs(d.budgetMs)} budget, over by ${secs(d.overByMs)}${delta}.`);
-  if (!d.ok && d.worst.length) {
+  const overTotal = d.totalMs > d.budgetMs;
+  out.push(overTotal
+    ? `COST BUDGET EXCEEDED: ${secs(d.totalMs)} against a ${secs(d.budgetMs)} budget, over by ${secs(d.overByMs)}${delta}.`
+    : `cost ${secs(d.totalMs)} of a ${secs(d.budgetMs)} budget — ${secs(d.headroomMs)} to spare${delta}.`);
+
+  // A per-claim breach is its own finding and names its own remedy: the claim
+  // is not too big, it is pointed at too expensive a defender file.
+  if (d.overPerClaim?.length) {
+    out.push('');
+    out.push(`PER-CLAIM BUDGET EXCEEDED: ${d.overPerClaim.length} claim${d.overPerClaim.length === 1 ? '' : 's'} over the ${secs(d.perClaimMs)} per-claim ceiling.`);
+    for (const c of d.overPerClaim) out.push(`  ${secs(c.ms).padStart(7)}  ${c.id}  (${c.runs} runs)`);
+    out.push('');
+    out.push('A claim pays for every test in the file it names. Point it at a test that');
+    out.push('does not need the expensive setup, re-probe to confirm the fault still dies,');
+    out.push('and only then raise the ceiling if it is still over.');
+  }
+
+  if (overTotal && d.worst.length) {
     out.push('');
     out.push('most expensive claims');
     for (const c of d.worst) out.push(`  ${secs(c.ms).padStart(7)}  ${c.id}  (${c.runs} runs)`);

package/src/status/status.mjs

@@ -9,6 +9,7 @@ import { discoverDefenders } from '../probe/discover.mjs';
 import { sortForReport } from '../render.mjs';
 import { computeChangedGate, defaultIgnorePath } from '../gate/changed.mjs';
 import { headSha, isAncestor } from '../git.mjs';
+import { checkAnchorLocations } from '../claims/anchors.mjs';
 
 export const faultContentHash = (fault) => sha256(`${fault.find}\n${fault.replace}`);
 
@@ -41,6 +42,7 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
     provisional: false,
     counts: { claims: 0, faults: 0 },
     stale: [],
+    invalidFaults: [],
     changedFaults: [],
     findings: [],
     notes: [],
@@ -87,6 +89,22 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
     return doc;
   }
 
+  const anchors = checkAnchorLocations(projectDir, claims);
+  doc.invalidFaults = anchors.results
+    .filter((result) => result.status !== 'ok')
+    .map(({ claimId, faultId, file, status: reason, hits, expected }) => ({ claimId, subjectId: faultId, file, reason, hits, expected }));
+  if (doc.invalidFaults.length) {
+    const first = doc.invalidFaults[0];
+    doc.state = 'invalid-anchors';
+    doc.next = {
+      action: 'repair-fault',
+      command: 'testguard claims --check-anchors',
+      why: `${doc.invalidFaults.length} fault anchor${doc.invalidFaults.length === 1 ? '' : 's'} no longer locate exactly. Repair ${first.claimId}/${first.subjectId} in testguard.claims.json without changing what the fault means, then re-probe.`,
+      target: { claimId: first.claimId, subjectId: first.subjectId, file: first.file },
+    };
+    return doc;
+  }
+
   const evidenceFile = evidenceOverride ?? paths.evidence;
   const hasEvidence = existsSync(evidenceFile);
   const hasProvisional = existsSync(paths.provisional);
@@ -236,6 +254,7 @@ export function renderStatus(doc) {
     for (const e of c.expired) lines.push(`EXPIRED   ignore "${e.pattern}" no longer excuses ${e.files.join(', ')}`);
   }
   for (const c of doc.changedFaults) lines.push(`CHANGED   ${c.claimId}/${c.subjectId} edited since it ${c.previousVerdict} (${c.file})`);
+  for (const f of doc.invalidFaults ?? []) lines.push(`INVALID   ${f.claimId}/${f.subjectId} ${f.reason}: ${f.hits} hits, expected ${f.expected} (${f.file})`);
   for (const s of doc.stale.slice(0, 8)) lines.push(`stale     ${s}`);
   for (const n of doc.notes ?? []) lines.push(`note      ${n}`);
   lines.push(`next:     [${doc.next.action}] ${doc.next.command}`);