testguard-cli 0.9.0__tar.gz → 0.9.2__tar.gz

{testguard_cli-0.9.0 → testguard_cli-0.9.2}/.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.2/.github/scripts/build-one-pager.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * Render docs/testguard-explained.html to PDF with headless Chrome.
+ *
+ * Chrome rather than a library because this repository has one pinned runtime
+ * dependency and keeps it that way: a PDF renderer would be the second, and it
+ * would be needed only to build a document nobody imports.
+ *
+ * Set CHROME to override the binary.
+ *
+ *   (no flags)        render; exit 0 with a notice when no Chrome is present,
+ *                     so a checkout without one can still run every other
+ *                     script.
+ *   --require-chrome  a missing Chrome is a failure. The release uses this:
+ *                     there, "skipped the render" means shipping a PDF that
+ *                     disagrees with the HTML beside it, which is the exact
+ *                     drift this script exists to prevent — and it would pass
+ *                     silently, which is worse than failing.
+ *
+ * After a successful render the page count is checked against the number of
+ * `.page` divs in the source. That is not a nicety: `.page` sets
+ * `min-height: 279.4mm` and `page-break-after: always`, which is a request,
+ * not a constraint. A section a few pixels too tall spills onto a second
+ * physical sheet with no warning from Chrome, renumbering nothing and
+ * contradicting the "Page N of M" footers the document prints itself. It
+ * happened while updating the brief for 0.8.1 and cost two extra pages.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const src = join(root, 'docs', 'testguard-explained.html');
+const out = join(root, 'docs', 'testguard-explained.pdf');
+const requireChrome = process.argv.slice(2).includes('--require-chrome');
+
+// CHROME overrides rather than merely leads: a binary named explicitly and not
+// found is a mistake worth hearing about, not a reason to quietly render with
+// some other browser the machine happens to have.
+const candidates = process.env.CHROME ? [process.env.CHROME] : [
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/usr/bin/google-chrome',
+  '/usr/bin/chromium',
+  '/usr/bin/chromium-browser',
+];
+
+const chrome = candidates.find((c) => existsSync(c));
+if (!chrome) {
+  const how = process.env.CHROME
+    ? `CHROME=${process.env.CHROME} does not exist`
+    : 'set CHROME=<path> to force';
+  if (requireChrome) {
+    console.error(`no Chrome found and --require-chrome was given; refusing to leave a stale PDF (${how})`);
+    process.exit(1);
+  }
+  console.log(`no Chrome found; skipping PDF build (${how})`);
+  process.exit(0);
+}
+
+const r = spawnSync(chrome, [
+  '--headless',
+  '--disable-gpu',
+  '--no-sandbox',
+  '--no-pdf-header-footer',
+  `--print-to-pdf=${out}`,
+  `file://${src}`,
+], { encoding: 'utf8' });
+
+if (r.status !== 0 || !existsSync(out)) {
+  console.error(r.stderr || 'chrome produced no PDF');
+  process.exit(1);
+}
+
+/** The sheets Chrome actually produced. `/Type /Pages` is the tree node, not a sheet. */
+const sheets = (readFileSync(out).toString('latin1').match(/\/Type\s*\/Page(?![s/\w])/g) ?? []).length;
+/** The sheets the document intends: one `.page` div each. */
+const intended = (readFileSync(src, 'utf8').match(/<div class="page"[\s>]/g) ?? []).length;
+
+if (intended === 0) {
+  console.error('docs/testguard-explained.html: no `.page` divs found — the page-count guard cannot run');
+  process.exit(1);
+}
+if (sheets !== intended) {
+  console.error(
+    `docs/testguard-explained.pdf: ${sheets} sheets rendered from ${intended} \`.page\` divs.\n` +
+    'A .page taller than its sheet spills silently. Letter at margin 0 is 816x1056 CSS px: load the\n' +
+    'HTML at that viewport and look for a .page whose getBoundingClientRect().height exceeds 1056.\n' +
+    'Measuring at any other width is meaningless, because the text reflows.',
+  );
+  process.exit(1);
+}
+
+console.log(`docs/testguard-explained.pdf written with ${chrome.split('/').pop()} — ${sheets} pages, one per .page div`);

testguard_cli-0.9.2/.github/scripts/check-cost-budget.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * Fail CI when the self-probe gate outgrows its budget.
+ *
+ * The decision lives in `src/probe/cost.mjs` as a pure function, unit-tested
+ * and covered by a self-claim; this script is only wiring — read the evidence,
+ * read the budget, print, choose an exit code.
+ *
+ * usage: check-cost-budget.mjs <evidence.json> [previous-evidence.json]
+ */
+import { appendFileSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { costReport, checkCostBudget, renderCostBudget } from '../../src/probe/cost.mjs';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const [evidencePath, previousPath] = process.argv.slice(2);
+if (!evidencePath) {
+  console.error('usage: check-cost-budget.mjs <evidence.json> [previous-evidence.json]');
+  process.exit(2);
+}
+
+const read = (p) => JSON.parse(readFileSync(resolve(p), 'utf8'));
+const budget = read(join(ROOT, 'testguard.cost-budget.json'));
+
+// A previous run is informational only. Its absence must never fail the check:
+// the first run on a branch, or a cold cache, has nothing to compare against.
+let previousMs;
+if (previousPath) {
+  try {
+    previousMs = costReport(read(previousPath).records).totalMs;
+  } catch {
+    previousMs = undefined;
+  }
+}
+
+const report = costReport(read(evidencePath).records);
+const decision = checkCostBudget(report, {
+  budgetSeconds: budget.seconds,
+  perClaimSeconds: budget.perClaimSeconds,
+  previousMs,
+});
+const text = renderCostBudget(decision);
+console.log(text);
+
+// The gate's own history is the argument for writing this where it is seen:
+// the run went 9.6 -> 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. A new claim that quietly costs 51 s is the same failure one
+// size down. A job summary is read without opening anything, so the number is
+// in front of a reviewer while the change is still a change.
+if (process.env.GITHUB_STEP_SUMMARY) {
+  const rows = (report.claims ?? []).slice(0, 10)
+    .map((c) => `| \`${c.claimId}\` | ${(c.ms / 1000).toFixed(1)}s | ${c.runs} |`)
+    .join('\n');
+  appendFileSync(process.env.GITHUB_STEP_SUMMARY, [
+    `## Self-probe cost \u2014 ${decision.ok ? 'within budget' : 'OVER BUDGET'}`,
+    '',
+    '```',
+    text,
+    '```',
+    '',
+    '<details><summary>Most expensive claims</summary>',
+    '',
+    '| claim | cost | runs |',
+    '| --- | ---: | ---: |',
+    rows,
+    '',
+    'A claim pays for every test in the file it names, so the fix for an expensive',
+    'claim is usually a cheaper defender rather than a bigger budget.',
+    '</details>',
+    '',
+  ].join('\n'));
+}
+
+if (!decision.ok) {
+  console.log(`::error::${text.split('\n')[0]}`);
+  process.exit(1);
+}

{testguard_cli-0.9.0 → testguard_cli-0.9.2}/.github/scripts/sync-release-version.mjs

@@ -95,6 +95,13 @@ const surfaces = [
   ['README.md', /testguard\/v\d+\.\d+\.\d+\/packaging/g, `testguard/v${version}/packaging`],
   ['packaging/gitlab/testguard.gitlab-ci.yml', /testguard\/v\d+\.\d+\.\d+\/packaging/g, `testguard/v${version}/packaging`],
   ['packaging/gitlab/testguard.gitlab-ci.yml', /(\n    version:\n      description: [^\n]*\n      default: ")\d+\.\d+\.\d+(")/, `$1${version}$2`],
+  // The technical brief's masthead. Nothing rendered it for three releases, so
+  // it still read v0.6 while the tool shipped 0.8.1. The HTML is the surface;
+  // the PDF beside it is a build artifact of this file, which is why the
+  // release runs build-one-pager.mjs --require-chrome straight after the sync.
+  // Sync the two separately and they disagree — the failure that is worse than
+  // being stale, because the document then contradicts itself.
+  ['docs/testguard-explained.html', /(Technical Brief · v)\d+\.\d+\.\d+( · MIT)/, `$1${version}$2`],
 ];
 
 if (listSurfaces) {

{testguard_cli-0.9.0 → testguard_cli-0.9.2}/.github/workflows/auto-merge.yml

@@ -53,7 +53,7 @@ jobs:
             // three files the bump writes — test/release-sync.test.mjs fails if
             // a surface is missing, which is how the GitLab template's absence
             // (it would have held every release PR for review) was found.
-            const RELEASE_SURFACES = new Set(['package.json', 'package-lock.json', 'pyproject.toml', 'CHANGELOG.md', 'action.yml', 'packaging/homebrew/testguard.rb', 'README.md', 'packaging/gitlab/testguard.gitlab-ci.yml']);
+            const RELEASE_SURFACES = new Set(['package.json', 'package-lock.json', 'pyproject.toml', 'CHANGELOG.md', 'action.yml', 'packaging/homebrew/testguard.rb', 'README.md', 'packaging/gitlab/testguard.gitlab-ci.yml', 'docs/testguard-explained.html', 'docs/testguard-explained.pdf']);
 
             if (author === 'dependabot[bot]') {
               const m = /from (\d+)\.(\d+)\.\S+ to (\d+)\.(\d+)\./.exec(pr.title || '');

{testguard_cli-0.9.0 → testguard_cli-0.9.2}/.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.0 → testguard_cli-0.9.2}/.github/workflows/scheduled-release.yml

@@ -8,8 +8,15 @@ name: Scheduled Release
 # GITHUB_TOKEN-created PRs do not trigger `pull_request` workflows, so nothing
 # would ever start the required checks and auto-merge would wait forever. This
 # workflow therefore dispatches ci.yml on the release branch itself:
-# `workflow_dispatch` is the one event GITHUB_TOKEN may trigger. After the
-# three Node legs go green, auto-merge completes. No human step remains.
+# `workflow_dispatch` is the one event GITHUB_TOKEN may trigger.
+#
+# That is not the whole story, and v0.9.0 proved it. The `pull_request` runs
+# the PR creates anyway are held at `action_required`, because the repository
+# requires approval from first-time contributors and `github-actions[bot]` is
+# permanently one. Held runs keep check suites QUEUED on the head sha, so the
+# rollup never becomes terminal and auto-merge waits — with every required
+# check already green. This workflow now approves those runs itself, which
+# GITHUB_TOKEN is permitted to do. Only then does no human step remain.
 
 on:
   schedule:
@@ -85,6 +92,11 @@ jobs:
           } > /tmp/entry.md
           awk '/^## \[Unreleased\]/ { print; print ""; while ((getline line < "/tmp/entry.md") > 0) print line; next } { print }' CHANGELOG.md > /tmp/CHANGELOG.new && mv /tmp/CHANGELOG.new CHANGELOG.md
           node .github/scripts/sync-release-version.mjs
+          # The sync just wrote the brief's masthead; the committed PDF still
+          # shows the old one. --require-chrome because a skipped render here
+          # would ship an HTML and a PDF that disagree, silently and at exit 0.
+          # ubuntu-latest carries /usr/bin/google-chrome.
+          node .github/scripts/build-one-pager.mjs --require-chrome
           echo "NEW_VERSION=$NEW" >> "$GITHUB_ENV"
 
       - name: Verify the tree is still green
@@ -117,9 +129,11 @@ jobs:
           # DERIVED from the sync script, never retyped here: when the GitLab
           # template became a surface it was left out of the hand-written list,
           # so the first release to reach this guard would have been rejected
-          # for writing a file the release is supposed to write. The three
-          # extras are the ones the bump step writes directly.
-          ALLOWED=$(node .github/scripts/sync-release-version.mjs --list-surfaces; printf 'package.json\npackage-lock.json\nCHANGELOG.md\n')
+          # for writing a file the release is supposed to write. The four
+          # extras are the ones the bump step writes directly: three from the
+          # bump itself, plus the brief's PDF, which is rendered from a surface
+          # rather than being one.
+          ALLOWED=$(node .github/scripts/sync-release-version.mjs --list-surfaces; printf 'package.json\npackage-lock.json\nCHANGELOG.md\ndocs/testguard-explained.pdf\n')
           echo "Release surfaces allowed in this diff:"; printf '%s\n' "$ALLOWED" | sed 's/^/  /'
           CHANGED=$(git diff --name-only HEAD --)
           for f in $CHANGED; do
@@ -134,7 +148,7 @@ jobs:
           git add -A
           git commit -m "release: v${NEW_VERSION} — automated weekly batch"
           git push origin "$BRANCH"
-          printf 'Automated weekly release. Version bump + CHANGELOG entry + synced version surfaces. Merging tags and publishes to npm and PyPI via release.yml.\n\nA PR opened by GITHUB_TOKEN gets no `pull_request` run, so this workflow dispatched ci.yml on `%s` itself. Auto-merge is armed; it completes once the three Node legs pass. If the checks never appear: `gh workflow run ci.yml --ref %s`.\n' "$BRANCH" "$BRANCH" > /tmp/pr-body.md
+          printf 'Automated weekly release. Version bump + CHANGELOG entry + synced version surfaces. Merging tags and publishes to npm and PyPI via release.yml.\n\nTwo things a GITHUB_TOKEN PR needs done for it, both handled by this workflow: it raises no `pull_request` event, so ci.yml was dispatched on `%s` itself; and the `pull_request` runs it does create are held at `action_required` (github-actions[bot] is permanently a first-time contributor), so those were approved too. Auto-merge is armed and completes once the three Node legs pass.\n\nIf it sits anyway: `gh workflow run ci.yml --ref %s` for missing checks, or check for runs still awaiting approval on the head sha.\n' "$BRANCH" "$BRANCH" > /tmp/pr-body.md
           # A bare `gh pr create` failure here reads as a GraphQL error with no
           # hint of the cause, which is how v0.8.1 lost its release PR after
           # everything else in the release had succeeded.
@@ -155,6 +169,57 @@ jobs:
             else
               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"
           else
             cat /tmp/pr-err
             if grep -q 'not permitted to create or approve pull requests' /tmp/pr-err; then

{testguard_cli-0.9.0 → testguard_cli-0.9.2}/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`.

{testguard_cli-0.9.0 → testguard_cli-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: testguard-cli
-Version: 0.9.0
+Version: 0.9.2
 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
@@ -104,8 +104,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
 
@@ -150,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.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
@@ -164,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?
@@ -174,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
@@ -200,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
@@ -468,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
@@ -482,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.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
 ```
 

{testguard_cli-0.9.0 → testguard_cli-0.9.2}/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
 ```