testguard-cli 0.9.1__tar.gz → 0.9.3__tar.gz

{testguard_cli-0.9.1 → testguard_cli-0.9.3}/.agents/skills/testguard/SKILL.md

@@ -21,6 +21,7 @@ which files exist. `state` is one of:
 | state | meaning | you do |
 |---|---|---|
 | `no-claims` | no `testguard.claims.json` | `testguard scaffold <file>` for a file with guards; replace every `TODO:` statement with what the code guarantees; keep or drop each proposal; move the claims into `testguard.claims.json` |
+| `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` |
@@ -44,6 +45,8 @@ Exit codes: `0` clean · `1` unproven claims (or drift) · `2` precondition fail
 ## The fix loop
 
 1. `testguard status --json` → take `next.target`.
+   After editing guarded code, run `testguard claims --check-anchors` before
+   any probe; repair a named fault definition without weakening its meaning.
 2. Write the test. It must **fail when the fault is applied and pass on HEAD**. To check the first half by hand: apply `find` → `replace` in the target file, run the defender, restore.
 3. `testguard probe --claim <ID> --include-dirty` — probes your uncommitted test without touching the tree. `--confirm 1` gives a fast **provisional** signal; a `?` on a verdict means unconfirmed.
 4. When it is `killed` at `--confirm 3`, commit the test.

testguard_cli-0.9.3/.github/scripts/approve-held-runs.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+
+# Clear GitHub's first-time-contributor hold from workflow runs created for a
+# GITHUB_TOKEN-authored pull request. The repository requires that approval,
+# and github-actions[bot] can never graduate from it because it does not author
+# the squash commit that lands on main.
+
+set -euo pipefail
+
+HEAD_SHA="${1:?usage: approve-held-runs.sh HEAD_SHA PR_URL}"
+PR_URL="${2:?usage: approve-held-runs.sh HEAD_SHA PR_URL}"
+: "${GITHUB_REPOSITORY:?GITHUB_REPOSITORY is required}"
+
+POLL_SECONDS="${TESTGUARD_HELD_RUN_POLL_SECONDS:-10}"
+approved=0
+
+held_ids() {
+  gh api "repos/${GITHUB_REPOSITORY}/actions/runs?head_sha=${HEAD_SHA}" \
+    --jq '[.workflow_runs[] | select(.status == "action_required" or .conclusion == "action_required") | .id] | .[]'
+}
+
+held_urls() {
+  gh api "repos/${GITHUB_REPOSITORY}/actions/runs?head_sha=${HEAD_SHA}" \
+    --jq '[.workflow_runs[] | select(.status == "action_required" or .conclusion == "action_required") | .html_url] | .[]'
+}
+
+echo "Clearing held workflow runs on $HEAD_SHA"
+for attempt in 1 2 3 4 5 6; do
+  # Fail closed. Treating an API failure as "no held runs" would report that
+  # auto-merge can proceed while leaving the PR queued forever.
+  if ! HELD=$(held_ids); then
+    echo "::error::Could not inspect workflow approval holds for $HEAD_SHA; auto-merge on $PR_URL may remain blocked."
+    exit 1
+  fi
+
+  for id in $HELD; do
+    if gh api -X POST "repos/${GITHUB_REPOSITORY}/actions/runs/${id}/approve" >/dev/null 2>&1; then
+      echo "  approved run $id"
+      approved=$((approved + 1))
+    else
+      # A run can leave action_required between the query and the POST. The
+      # final query decides whether that race is harmless.
+      echo "  run $id needed no approval"
+    fi
+  done
+
+  # Runs appear asynchronously. Once one was approved, the first empty query
+  # is terminal; when this repository gate does not apply, three empty polls
+  # are enough to establish that without paying the full minute.
+  if [ -z "$HELD" ] && { [ "$approved" -gt 0 ] || [ "$attempt" -ge 3 ]; }; then
+    break
+  fi
+  if [ "$attempt" -lt 6 ]; then sleep "$POLL_SECONDS"; fi
+done
+
+if ! STILL=$(held_urls); then
+  echo "::error::Could not verify workflow approval holds for $HEAD_SHA; auto-merge on $PR_URL may remain blocked."
+  exit 1
+fi
+if [ -n "$STILL" ]; then
+  echo "::error::Workflow runs are still held for approval, so auto-merge on $PR_URL will wait forever. Approve them, or re-run this workflow: $STILL"
+  exit 1
+fi
+echo "✅ no run is held for approval; auto-merge can complete"

{testguard_cli-0.9.1 → testguard_cli-0.9.3}/.github/workflows/ci.yml

@@ -185,6 +185,13 @@ jobs:
         if: github.event_name == 'pull_request'
         run: node cli/testguard.mjs gate . --changed "origin/${{ github.base_ref }}"
 
+      # Exact anchors and parseable replacements are knowable without a test
+      # runner. Fail here instead of spending the long self-probe merely to
+      # discover that a fault could never be applied.
+      - name: claims — fault anchors and replacements are valid
+        if: matrix.node-version == 22
+        run: node cli/testguard.mjs claims . --check-anchors
+
       # ── Self-verification: TestGuard is governed by the standard it defines.
       #    testguard.claims.json states invariants of the tool itself; every
       #    fault must be killed by the tool's own tests. Exit 0 = all defended. ──

{testguard_cli-0.9.1 → testguard_cli-0.9.3}/.github/workflows/release.yml

@@ -236,8 +236,10 @@ jobs:
     # change lands as a bot PR with native auto-merge armed, and this job
     # dispatches ci.yml on the branch itself — a PR opened with GITHUB_TOKEN
     # gets no pull_request run, but workflow_dispatch is the documented
-    # exception. That also means the merge triggers nothing here; the hourly
-    # sweep observes the merged formula and finds brew_missing=false.
+    # exception. The PR's own runs may still appear held for first-time-
+    # contributor approval, so this job clears those holds before returning.
+    # That also means the merge triggers nothing here; the hourly sweep
+    # observes the merged formula and finds brew_missing=false.
     #
     # Idempotent: an existing branch is reused, an existing open PR is left
     # alone (CI re-dispatched only if its head has no check runs), a closed
@@ -334,3 +336,4 @@ jobs:
           else
             echo "✅ $HEAD_SHA already has $RUNS check run(s)"
           fi
+          .github/scripts/approve-held-runs.sh "$HEAD_SHA" "$PR"

{testguard_cli-0.9.1 → testguard_cli-0.9.3}/.github/workflows/scheduled-release.yml

@@ -170,56 +170,10 @@ jobs:
               echo "✅ $HEAD_SHA already has $RUNS check run(s)"
             fi
 
-            # ── The third GITHUB_TOKEN wall, and the last one. ──
-            # The `pull_request` runs this PR creates are held at
-            # `action_required`: 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. Those held runs leave check suites QUEUED on the
-            # head sha forever, the status rollup never reaches a terminal
-            # state, and auto-merge waits on it even though the required
-            # contexts (test 20/22/24) are already green from the dispatched
-            # run above. v0.9.0 sat here until a human clicked Approve.
-            #
-            # GITHUB_TOKEN may clear it: `actions: write` carries the approve
-            # permission, measured 201 on a bot PR's own held run. It may not
-            # approve a REVIEW, which is a different gate and still ours alone.
-            #
-            # Runs appear asynchronously, so poll. Approving an already-running
-            # run answers 403 "not waiting for approval" — success, not failure.
-            echo "Clearing held workflow runs on $HEAD_SHA"
-            approved=0
-            for attempt in 1 2 3 4 5 6; do
-              HELD=$(gh api "repos/${GITHUB_REPOSITORY}/actions/runs?head_sha=${HEAD_SHA}" \
-                --jq '[.workflow_runs[] | select(.status == "action_required" or .conclusion == "action_required") | .id] | .[]' 2>/dev/null || true)
-              for id in $HELD; do
-                if gh api -X POST "repos/${GITHUB_REPOSITORY}/actions/runs/${id}/approve" >/dev/null 2>&1; then
-                  echo "  approved run $id"
-                  approved=$((approved + 1))
-                else
-                  echo "  run $id needed no approval"
-                fi
-              done
-              # Stop as soon as the picture is settled, rather than always
-              # paying the full poll: nothing held after something was
-              # approved means we are done, and nothing held by the third
-              # look means the gate is not applying to this run at all.
-              if [ -z "$HELD" ] && { [ "$approved" -gt 0 ] || [ "$attempt" -ge 3 ]; }; then
-                break
-              fi
-              sleep 10
-            done
-
-            # Never leave this silent: a run still held here means auto-merge
-            # will wait forever, which is the failure this whole block exists
-            # to remove. Say so, and name what to click.
-            STILL=$(gh api "repos/${GITHUB_REPOSITORY}/actions/runs?head_sha=${HEAD_SHA}" \
-              --jq '[.workflow_runs[] | select(.status == "action_required" or .conclusion == "action_required") | .html_url] | .[]' 2>/dev/null || true)
-            if [ -n "$STILL" ]; then
-              echo "::error::Workflow runs are still held for approval, so auto-merge on $PR will wait forever. Approve them, or re-run this workflow: $STILL"
-              exit 1
-            fi
-            echo "✅ no run is held for approval; auto-merge can complete"
+            # Clear the first-time-contributor holds on this bot-created PR's
+            # workflow runs. The Homebrew PR path uses the same helper so the
+            # two release automations cannot drift again.
+            .github/scripts/approve-held-runs.sh "$HEAD_SHA" "$PR"
           else
             cat /tmp/pr-err
             if grep -q 'not permitted to create or approve pull requests' /tmp/pr-err; then

{testguard_cli-0.9.1 → testguard_cli-0.9.3}/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.3] - 2026-09-19
+
+Automated weekly release — everything merged since `v0.9.2`.
+
+### Changed
+
+- fix(release): clear held Homebrew PR runs (#129)
+- chore(homebrew): sha256 for v0.9.2 (#128)
+
+
+### Fixed
+
+- Bot-created Homebrew checksum PRs now clear GitHub's first-time-contributor
+  workflow holds themselves, using the same fail-closed helper as scheduled
+  release PRs. A release no longer finishes publishing while leaving its final
+  formula update waiting for a manual Approve click.
+
+## [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`.

{testguard_cli-0.9.1 → testguard_cli-0.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: testguard-cli
-Version: 0.9.1
+Version: 0.9.3
 Summary: 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. Ships the Node.js CLI (requires Node.js 20+).
 Project-URL: Homepage, https://github.com/raccioly/testguard
 Project-URL: Documentation, https://github.com/raccioly/testguard#readme
@@ -151,9 +151,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.1` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.9.3` — 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.1/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.3/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
@@ -165,6 +165,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?
@@ -175,8 +176,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
@@ -201,6 +203,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
@@ -469,6 +475,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
@@ -483,12 +493,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.1
+- uses: raccioly/testguard@v0.9.3
   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.1/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.9.3/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
 ```
 

{testguard_cli-0.9.1 → testguard_cli-0.9.3}/README.md

@@ -127,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.1` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.9.3` — 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.1/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.3/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
@@ -141,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?
@@ -151,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
@@ -177,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
@@ -445,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
@@ -459,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.1
+- uses: raccioly/testguard@v0.9.3
   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.1/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.9.3/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
 ```
 

{testguard_cli-0.9.1 → testguard_cli-0.9.3}/action.yml

@@ -46,7 +46,7 @@ inputs:
   version:
     description: 'testguard-cli version to run'
     required: false
-    default: '0.9.1'
+    default: '0.9.3'
   node-version:
     description: 'Node.js version (20+)'
     required: false

{testguard_cli-0.9.1 → testguard_cli-0.9.3}/docs/testguard-explained.html

@@ -144,7 +144,7 @@
 <div class="page">
   <div class="masthead">
     <div class="wordmark">Test<span class="mark">Guard</span></div>
-    <div class="meta">Technical Brief · v0.9.1 · MIT</div>
+    <div class="meta">Technical Brief · v0.9.3 · MIT</div>
   </div>
 
   <h1>Your tests pass. That is not the same as your tests working.</h1>

{testguard_cli-0.9.1 → testguard_cli-0.9.3}/docs-canonical/ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 <!-- docguard:version 1.0.0 -->
 <!-- docguard:status approved -->
-<!-- docguard:last-reviewed 2026-09-18 -->
+<!-- docguard:last-reviewed 2026-09-19 -->
 <!-- docguard:owner @raccioly -->
 <!-- docguard:quality negation-load off — this tool is defined by what must not happen: no network, no telemetry, never optimistic under uncertainty. Stating those positively would misdescribe them. -->
 
@@ -35,7 +35,7 @@ code were wrong, would anything fail?*
 |---|---|---|
 | CLI dispatch | Parse argv, select a command, map errors to exit codes | `src/cli.mjs`, `cli/testguard.mjs` |
 | Commands | Thin wrappers: read flags, call a module, render output | `src/commands/*.mjs` |
-| Claims | Load and validate the claims file; reconcile `@claim` annotations; detect removed claims | `src/claims/` |
+| Claims | Load and validate the claims file; reconcile `@claim` annotations; detect removed claims; preflight exact anchors and supported replacement syntax | `src/claims/` |
 | Probe engine | Isolate, inject, run, escalate, restore, classify, rank | `src/probe/probe.mjs` |
 | Verdict function | The pure decision: runs in, verdict out | `src/probe/classify.mjs` |
 | Injector | Apply and restore a fault; anchor location | `src/probe/inject.mjs` |
@@ -131,7 +131,7 @@ to every other surface and `--check` fails the build on drift.
 
 | Stage | Where | Gate |
 |---|---|---|
-| Pull request | `ci.yml` | Suite on Node 20/22/24, syntax check of every source, install-from-tarball smoke, Python wrapper import, fixture oracles for vitest and jest, Playwright job, change gate, removed-claim check |
+| Pull request | `ci.yml` | Suite on Node 20/22/24, syntax check of every source, install-from-tarball smoke, Python wrapper import, fixture oracles for vitest and jest, Playwright job, change gate, removed-claim check, anchor/replacement preflight before self-probe |
 | Release gate | `ci.yml` | TestGuard probes its own claims; every fault must be killed |
 | Merge to main | `release.yml` | A version with no tag is tagged, released, and published to npm and PyPI over OIDC |
 | Recovery | `release.yml` | Hourly sweep; each registry is gated on its own state, so a partial publish is fixed by re-running |
@@ -141,6 +141,9 @@ to every other surface and `--check` fails the build on drift.
 ```
                     testguard.claims.json          (what must be true)
                               │
+               claims --check-anchors
+            (exact anchors + syntax, no tests)
+                              │
                               ▼
    ┌─────────── probe ────────────────────────────────────────────┐
    │  scratch git worktree  ←── isolation, never your tree        │

{testguard_cli-0.9.1 → testguard_cli-0.9.3}/docs-canonical/DATA-MODEL.md

@@ -2,7 +2,7 @@
 
 <!-- docguard:version 1.0.0 -->
 <!-- docguard:status approved -->
-<!-- docguard:last-reviewed 2026-09-18 -->
+<!-- docguard:last-reviewed 2026-09-19 -->
 <!-- docguard:owner @raccioly -->
 <!-- docguard:quality negation-load off — the data model is largely a set of prohibitions (no database, no server state, fingerprints never derived from fault text). -->
 <!-- docguard:quality passive-voice off — this document describes what happens to documents as they flow through validation, where the artifact is the subject and the actor is irrelevant. -->
@@ -86,6 +86,11 @@ status.json ◀── derived from claims + evidence + baseline + working tree
 brief.json  ◀── derived from evidence + baseline + status
 ```
 
+Status also carries `invalidFaults`, the current exact-anchor failures with
+their observed and expected hit counts. When it is non-empty, the state is
+`invalid-anchors` and the next action is `repair-fault`; evidence cannot make a
+fault that no longer applies trustworthy.
+
 A fingerprint is `sha256(claimId \n subjectId \n file \n verdict)`. It is
 derived from identity and outcome, never from the fault's text, so repairing a
 rotted anchor does not churn the baseline, while a change of verdict does

{testguard_cli-0.9.1 → testguard_cli-0.9.3}/docs-canonical/REQUIREMENTS.md

@@ -2,7 +2,7 @@
 
 <!-- docguard:version 1.0.0 -->
 <!-- docguard:status approved -->
-<!-- docguard:last-reviewed 2026-09-18 -->
+<!-- docguard:last-reviewed 2026-09-19 -->
 <!-- docguard:owner @raccioly -->
 <!-- docguard:quality passive-voice off — requirements are written in the standard "the system shall ..." register, where the agent is the system throughout. -->
 
@@ -26,6 +26,7 @@
 | FR-12 | Answer whether one test satisfies the two-gate rule for a claim (`admit`) | P2 |
 | FR-13 | Replay historical fix commits to measure whether the suite would have caught them, and calibrate by fault class | P3 |
 | FR-14 | Serve the read-only operating loop over MCP so the loop survives a change of agent harness | P3 |
+| FR-15 | Validate every exact fault anchor and the syntax of supported in-memory replacements before starting a test runner (`claims --check-anchors`), without guessing repairs | P1 |
 
 ## Non-Functional Requirements
 
@@ -99,6 +100,7 @@ fails the pull request naming the unclaimed file, and `status` reports
 | FR-12 | `src/admit/admit.mjs` | `test/admit.test.mjs`, `TG-ADMIT-NEEDS-ALL-KILLED` |
 | FR-13 | `src/replay/` | `test/replay.test.mjs`, `test/calibration.test.mjs`, `TG-REPLAY-FLAKY-IS-NEVER-CAUGHT`, `TG-CALIBRATION-COUNTS-NOCOVER-AS-A-MISS`, `TG-CALIBRATION-COUNTS-ONLY-BUGS` |
 | FR-14 | `src/mcp/` | `test/mcp.test.mjs` |
+| FR-15 | `src/claims/anchors.mjs`, `src/commands/claims.mjs`, `src/status/status.mjs` | `test/claims-anchors.test.mjs`, `test/status.test.mjs`, `TG-ANCHOR-PREFLIGHT-FAILS-FAST` |
 | NFR-01 | `src/init/init.mjs`, runner resolution | `TG-INIT-HOOK-NO-NETWORK`, `TG-README-HOOK-MATCHES-THE-CODE` (every surface, not only the README), `TG-GITIGNORE-ADVICE-IS-ONE-LIST` |
 | NFR-02 | `package.json` | `npm run test:install` in CI |
 | NFR-03 | `src/probe/inject.mjs`, `src/probe/probe.mjs` | `TG-DIRTY-DEFENDERS-REFUSED`, `TG-IGNORED-DIRTY-RECORDED`, `TG-IN-PLACE-STILL-RAISES-A-MISSING-TARGET`, `TG-CONTROL-RESTORES-THE-SUBJECT` |

{testguard_cli-0.9.1 → testguard_cli-0.9.3}/docs-canonical/TEST-SPEC.md

@@ -2,7 +2,7 @@
 
 <!-- docguard:version 1.0.0 -->
 <!-- docguard:status approved -->
-<!-- docguard:last-reviewed 2026-09-18 -->
+<!-- docguard:last-reviewed 2026-09-19 -->
 <!-- docguard:owner @raccioly -->
 <!-- docguard:quality negation-load off — the governing rule is a prohibition (a test that would pass with the behaviour broken is not a test), and the verdict rules are defined by what does not count as detection. -->
 
@@ -19,6 +19,7 @@ the test that defends it, and CI fails if any injected fault survives.
 |---|---|---|---|
 | Unit | `test/*.test.mjs` | One pure function's branches, without a runner | milliseconds |
 | Conformance | `spec/conformance/` | Every valid example validates; every must-reject document is rejected for the defect its filename names | ~1 s |
+| Anchor preflight | `test/claims-anchors.test.mjs` | Exact anchors still locate, supported replacements parse, the check stays below one second, and CI reaches it before self-probe | <1 s |
 | Fixture acceptance | `test/probe.fixture.test.mjs`, `test/probe.jest.test.mjs`, `test/probe.playwright.test.mjs` | The whole pipeline reproduces a known-answer oracle, one per runner | 10–50 s each |
 | Self-verification | `testguard.claims.json`, run by `npm run self:probe` | The tool's own invariants survive fault injection | **13.4 min** cold (measured 2026-09-18 at `cf5a083`: 96 faults, 576 defender runs, 804 s, `--serial`, idle machine); seconds when verdicts are reused, which is why CI restores the previous evidence from cache. Budgeted at 950 s in `testguard.cost-budget.json` and **gated** in CI — the figure above went 9.6 → 23.6 min across one merged change while `--cost` printed it into a log nobody read |
 | Install smoke | `.github/scripts/install-smoke.mjs` | The **packed tarball** runs with production dependencies only | ~20 s |
@@ -57,6 +58,9 @@ What is gated instead:
 4. **Every spec change ships its conformance case** — schema, semantic rule,
    valid example and must-reject document, in the same pull request.
 5. **A new fault shape needs a synthetic-file test and a README row.**
+6. **Every fault must pass the cheap preflight before self-verification.** A
+   missing or ambiguous anchor, or a supported replacement that does not
+   parse, fails CI before the long self-probe starts.
 
 ## Service-to-Test Map
 
@@ -64,6 +68,7 @@ What is gated instead:
 |---|---|
 | `src/probe/classify.mjs` | `test/classify.test.mjs`, `test/negative-control.test.mjs` |
 | `src/probe/inject.mjs` | `test/inject.test.mjs` |
+| `src/claims/anchors.mjs` | `test/claims-anchors.test.mjs` |
 | `src/probe/probe.mjs` | `test/probe.fixture.test.mjs`, `test/probe-preconditions.test.mjs`, `test/probe-error.test.mjs` |
 | `src/probe/discover.mjs`, `src/probe/mocks.mjs` | `test/discover.test.mjs`, `test/mocks.test.mjs` |
 | `src/probe/rank.mjs` | `test/rank-aliases.test.mjs`, `test/discover.test.mjs` |

{testguard_cli-0.9.1 → testguard_cli-0.9.3}/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "testguard-cli",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "testguard-cli",
-      "version": "0.9.1",
+      "version": "0.9.3",
       "license": "MIT",
       "dependencies": {
         "ajv": "8.20.0"

{testguard_cli-0.9.1 → testguard_cli-0.9.3}/package.json

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

{testguard_cli-0.9.1 → testguard_cli-0.9.3}/packaging/gitlab/testguard.gitlab-ci.yml

@@ -3,7 +3,7 @@
 # Include it from a project's .gitlab-ci.yml, pinned to a release:
 #
 #   include:
-#     - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.9.1/packaging/gitlab/testguard.gitlab-ci.yml'
+#     - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.9.3/packaging/gitlab/testguard.gitlab-ci.yml'
 #       inputs:
 #         dir: backend            # where testguard.claims.json lives (default ".")
 #         post_note: true         # post the brief as a merge-request note (needs TESTGUARD_GITLAB_TOKEN, api scope)
@@ -29,7 +29,7 @@ spec:
   inputs:
     version:
       description: testguard-cli version to run
-      default: "0.9.1"
+      default: "0.9.3"
     dir:
       description: directory whose test runner is invoked (where testguard.claims.json lives)
       default: "."

{testguard_cli-0.9.1 → testguard_cli-0.9.3}/packaging/homebrew/testguard.rb

@@ -15,8 +15,8 @@
 class Testguard < Formula
   desc "Proves a test suite defends the claims a project makes"
   homepage "https://github.com/raccioly/testguard"
-  url "https://registry.npmjs.org/testguard-cli/-/testguard-cli-0.9.1.tgz"
-  sha256 "e8ebb4e78e1d91f21a47dee1edb63ee7fac72f96d2834b08654f89c18812ef7d"
+  url "https://registry.npmjs.org/testguard-cli/-/testguard-cli-0.9.3.tgz"
+  sha256 "33e88eaa37c34744c08c581a64b4939472e22e898ce1dabf15507fd77229d4e0"
   license "MIT"
 
   depends_on "node"

{testguard_cli-0.9.1 → testguard_cli-0.9.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "testguard-cli"
-version = "0.9.1"
+version = "0.9.3"
 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. Ships the Node.js CLI (requires Node.js 20+)."
 readme = "README.md"
 license = { text = "MIT" }

{testguard_cli-0.9.1 → testguard_cli-0.9.3}/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

{testguard_cli-0.9.1 → testguard_cli-0.9.3}/spec/conformance/examples/status.json

@@ -32,6 +32,7 @@
     "baselined": 4
   },
   "stale": [],
+  "invalidFaults": [],
   "changedFaults": [
     {
       "claimId": "REDACT-002",