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

testguard_cli-0.9.1/.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.1/.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.8.1 → testguard_cli-0.9.1}/.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.8.1 → testguard_cli-0.9.1}/.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.8.1 → testguard_cli-0.9.1}/.github/workflows/release.yml

@@ -118,15 +118,43 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
+          set -o pipefail
           TAG="v${{ needs.detect-version.outputs.version }}"
           if git ls-remote --tags origin | grep -q "refs/tags/$TAG$"; then
             echo "✅ Tag $TAG already exists on remote"
-          else
-            git config user.name "github-actions[bot]"
-            git config user.email "github-actions[bot]@users.noreply.github.com"
-            git tag -a "$TAG" -m "Release $TAG"
-            git push origin "$TAG"
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "$TAG" -m "Release $TAG"
+          if git push origin "$TAG" 2>/tmp/tag-err; then
+            echo "✅ Pushed $TAG"
+            exit 0
+          fi
+          cat /tmp/tag-err
+          # A GitHub App may not PUSH a ref whose .github/workflows differ from
+          # the CURRENT default branch. That is not a property of this release:
+          # it becomes true the moment any workflow change merges to main while
+          # the release is in flight, which is exactly how v0.8.1 lost its tag
+          # ("refusing to allow a GitHub App to create or update workflow
+          # .github/workflows/release.yml without `workflows` permission")
+          # seven minutes after an unrelated workflow PR merged.
+          #
+          # So fall back to the API. It adds a ref to a commit that is ALREADY
+          # in the repository and creates no file content, so the restriction
+          # does not apply. The push is tried first on purpose: it is the path
+          # every previous release took, and this fallback only has to cover
+          # the case that currently fails outright.
+          if ! grep -q 'workflows. permission' /tmp/tag-err; then
+            echo "::error::git push of $TAG failed for a reason other than the workflow-permission restriction — see above."
+            exit 1
           fi
+          echo "::warning::Pushing $TAG was refused because main's workflows moved during this release; creating the tag through the API instead."
+          TAG_SHA=$(gh api -X POST "repos/${GITHUB_REPOSITORY}/git/tags" -f tag="$TAG" -f message="Release $TAG" -f object="$GITHUB_SHA" -f type=commit --jq .sha) || {
+            echo "::error::Could not create the tag object for $TAG. Create it by hand: git tag -a $TAG $GITHUB_SHA -m 'Release $TAG' && git push origin $TAG"; exit 1; }
+          gh api -X POST "repos/${GITHUB_REPOSITORY}/git/refs" -f ref="refs/tags/$TAG" -f sha="$TAG_SHA" --jq .ref || {
+            echo "::error::Could not create refs/tags/$TAG from tag object $TAG_SHA. Create it by hand: git tag -a $TAG $GITHUB_SHA -m 'Release $TAG' && git push origin $TAG"; exit 1; }
+          echo "✅ Created $TAG through the API at $GITHUB_SHA"
       - name: Release notes from CHANGELOG
         run: |
           VERSION="${{ needs.detect-version.outputs.version }}"

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

@@ -5,10 +5,18 @@ name: Scheduled Release
 # tree is green, and open a release PR with auto-merge armed. Once merged, the
 # hourly sweep in release.yml tags and publishes.
 #
-# GITHUB_TOKEN-created PRs do not trigger `pull_request` workflows, so CI on
-# the release PR must be started by the maintainer:
-#     gh workflow run ci.yml --ref release/vX.Y.Z
-# After it goes green, auto-merge completes.
+# 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.
+#
+# 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:
@@ -84,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
@@ -116,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
@@ -133,13 +148,78 @@ 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\nCI does not start automatically on PRs opened by GITHUB_TOKEN. Run:\n\n    gh workflow run ci.yml --ref %s\n\nAuto-merge is armed; it completes once the required checks pass.\n' "$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.
           if PR=$(gh pr create --base main --head "$BRANCH" --title "release: v${NEW_VERSION} — automated weekly batch" --body-file /tmp/pr-body.md 2>/tmp/pr-err); then
             gh pr merge --auto --squash "$PR"
             echo "Release PR: $PR"
+            # Nothing else will start the required checks: a PR opened by
+            # GITHUB_TOKEN raises no `pull_request` event, so auto-merge would
+            # sit on three checks that never run. `workflow_dispatch` is the
+            # one event GITHUB_TOKEN may trigger, and this job already holds
+            # the `actions: write` it needs. Guarded so a re-run of an
+            # already-tested branch does not queue a second identical run.
+            HEAD_SHA=$(git rev-parse HEAD)
+            RUNS=$(gh api "repos/${GITHUB_REPOSITORY}/commits/${HEAD_SHA}/check-runs" --jq '.total_count')
+            if [ "${RUNS:-0}" = "0" ]; then
+              gh workflow run ci.yml --ref "$BRANCH"
+              echo "Dispatched ci.yml on $BRANCH ($HEAD_SHA)"
+            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.8.1 → testguard_cli-0.9.1}/CHANGELOG.md

@@ -7,7 +7,177 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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`.
+
+### Changed
+
+- fix: the five findings from the 0.8.1 pocket-archive field report (#107)
+- chore(deps): jest 30.5.1 -> 30.5.2 (#106)
+- feat(release): the release PR starts its own CI (#105)
+- fix(release): tag through the API when the push is refused (#104)
+- chore(homebrew): sha256 for v0.8.1, from the published tarball (#103)
+- fix(release): a blocked pull request says which setting blocks it (#102)
+
+
+### Fixed
+- **`scaffold` no longer dies on a zero-valued window literal, and proposes a
+  real fault for one.** The window producer weakened a literal by ×1000, and
+  ×1000 of `0` is `0` — the replacement equalled its find, which the schema
+  rejects outright, so a single `expired: 0` aborted the whole file and printed
+  a raw Node stack. A 725-line source was unscaffoldable for this reason. The
+  same defect sat in the work-factor producer, where `rounds = 1` collapsed to
+  `1`, and in both Python producers, where `timeout=0` is PEP 8 spacing and so
+  the common form. The two cases are not the same, and are not fixed the same
+  way: a zero window is exactly the window worth widening, so it now widens to
+  a real value; a work factor already at 1 has nothing weaker to become, so it
+  proposes nothing rather than proposing itself. `usableProposal()` refuses a
+  no-op whatever a producer hands it, which makes the rule structural instead
+  of remembered.
+- **`if (…) continue;` and `if (…) break;` are guards.** Only `return` and
+  `throw` were read as guard bodies, so pure selection-over-rows — the shape
+  the "pure logic, caller does the IO" advice produces — got no proposals at
+  all. Two fully-claimed files of seven such guards each returned nothing,
+  while the hand-written faults on those same lines all killed: the shape
+  `scaffold` skipped was the one demonstrably worth proposing. Both the
+  single-line and the block form, in JavaScript and Python.
+- **An unexpected exception is named as our bug and keeps its trace.** Four
+  error classes became `error: …`; everything else reached the user as a Node
+  stack trace ending in `Node.js v24.18.0`, which reads as "your repository
+  broke the tool" and gives the operator nothing to do. It now says whose
+  defect it is and where to report it, and still prints the trace — a framed
+  error without one cannot be reported.
+- **Every surface that describes the session-start hook is held to the code,
+  not just the README.** 0.6.0 banned "falls back to npx" in README.md and
+  added a mechanical check there. The same sentence lived in the line `init`
+  prints as it installs the hook and in the `--help` entry, and both went on
+  promising an `npx --no-install` fallback that `hookCommand()` had stopped
+  emitting — the sentence the user reads at the moment the hook is installed
+  described the network-reaching mechanism that was removed for reaching the
+  network. `TG-README-HOOK-MATCHES-THE-CODE` is now a claim about the
+  property, over all four surfaces. The fourth, `docs-canonical/SECURITY.md`,
+  was found by DocGuard while this claim was being widened from one to
+  three; it is correct today, and is checked because that is where the
+  sentence lives, not because a defect had been found there.
+- **A test runner that has already exited is not reported as contention.**
+  `ps` is a snapshot, and a suite that finished between the snapshot and the
+  warning produced "1 test runner is already running (pid 65751)" for a process
+  the operator could not find. Liveness is re-checked immediately before
+  reporting. Detection stays best-effort: `EPERM` means running, not gone.
+- **A release can tag itself even when `main` moves underneath it.** A GitHub
+  App may not *push* a ref whose `.github/workflows` differ from the current
+  default branch, so v0.8.1's tag was refused seven minutes after an unrelated
+  workflow PR merged — a release that was otherwise complete. `create-release`
+  still pushes first, and now falls back to creating the tag through the API,
+  which adds a ref to a commit already in the repository and so is not subject
+  to that restriction. Any other push failure is still fatal and says so.
 - **A release that cannot open its pull request says why.** `GITHUB_TOKEN`
   cannot call `createPullRequest` unless "Allow GitHub Actions to create and
   approve pull requests" is enabled, and v0.8.1 hit exactly that: the branch,
@@ -19,6 +189,79 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   The failure is still a failure: the branch exists without a PR, and for the
   formula `detect-version` keeps reporting the hash owed on every sweep.
 
+### Changed
+- **The calibration counts escaped bugs, not every commit that changed source
+  and a test together.** `p` is P(the suite misses it | a *bug* of this class
+  escapes), but the corpus was every commit with a source-and-test pair — which
+  in a conventional-commits repository is every feature, since a feature ships
+  with its tests as a matter of course. One run reported "12 of 12 measurable
+  bugs invisible — 100%" over five `feat:`, a `refactor:`, a `style:` and a
+  commit whose entire purpose was adding a test; only four were `fix:`. The
+  finding survived the correction — all four real fixes came back `blind` — and
+  is stronger stated over the four honestly than over the twelve loosely.
+
+  Selection is unchanged: the source-and-test pairing is still all that can be
+  judged without reading a subject line, and replaying a feature still measures
+  something. What narrows is the estimator. Where a majority of replayed
+  subjects carry a conventional type, `p` is computed over the `fix:`/`revert:`
+  records; `replay` prints both rates and the type breakdown so the narrowing
+  can be checked; and `calibration.json` records which rule produced it in
+  `source.detail`, so two calibrations from two populations can never be
+  compared by accident. A conventional repository with no `fix:` in range
+  calibrates nothing and says to widen the range, rather than silently counting
+  features as bugs.
+- **`baseline` stops printing advice that rots, and stops repeating it.** It
+  named `.testguard/evidence.json` and `.testguard/brief.json` long after the
+  tool had grown to ten regenerated outputs, and printed them every run whether
+  or not the project already ignored them. The list now lives in one place,
+  owned by `init`, and only the outputs a project does not yet ignore are
+  printed — asked of git, so `.testguard/*` with negated exceptions, a global
+  ignore file and `.git/info/exclude` all answer correctly. `replay.json`,
+  `calibration.json`, `ci-self-evidence.json` and `.testguard/ci/` were missing
+  from the list `init` writes and have been added.
+- **The weekly release starts its own CI, so no human step is left.** A pull
+  request opened by `GITHUB_TOKEN` raises no `pull_request` event, so the three
+  required Node legs never started and auto-merge sat on checks that would
+  never run — the workflow simply printed `gh workflow run ci.yml --ref
+  release/vX.Y.Z` and waited for someone to read it. It now dispatches that
+  run itself, as `release.yml`'s `homebrew-sha` job already did, guarded so a
+  re-run does not queue a second identical run. With
+  "Allow GitHub Actions to create and approve pull requests" enabled, a
+  release now needs no manual step at all.
+- **The cost budget records a from-scratch release measurement.** 999 s for
+  115 faults on the v0.8.1 release commit, corroborated at 988 s on the
+  commit before it, against the unchanged 1100 s ceiling. The previous record
+  was 962 s at 96 faults.
+
+### Performance
+- **The self-probe cost budget is 1350 s, from 1100.** Six new claims and 14
+  new faults took the gate from 115 to 129 faults and 690 to 774 runs, and CI
+  measured 1123 s against the 1100 ceiling. The budget exists to make exactly
+  this visible rather than let it pass, so the raise is recorded with its
+  measurement and its reason in `testguard.cost-budget.json`. Two caveats are
+  written down there: the 1123 s run restored a cache under the fallback key
+  and so reused some verdicts, which makes it a floor rather than the
+  from-scratch figure this budget is defined against; and the number is
+  expected to come back down, because 44% of the gate is two shared defender
+  files re-run once per claim that names them. A third is recorded too: the
+  reported total is modelled rather than wall clock, because a reused record
+  contributes what it cost when it was last probed, so the same commit
+  measured 1123 s and then 1025 s depending on what the cache restored.
+- **The new calibration claim costs 4.9 s instead of 51 s.** Its tests are
+  pure — no git, no fixture corpus, no scratch worktree — but they were added
+  to `replay.test.mjs`, whose scripted-corpus setup costs tens of seconds a
+  run, and a claim pays for every test in the file it names. Moved to
+  `calibration.test.mjs`, which exists for exactly this, and the claim
+  re-pointed. Same two faults, still killed 2/2.
+
+### Documentation
+- The README shows an ignore-file entry. It was mentioned twice without one,
+  so the field name (`pattern`, not `value`) and the fact that `expires` is a
+  full timestamp rather than a date had to be discovered from a validator
+  refusal.
+- `--help` shows `gate --changed HEAD --include-dirty`. `--include-dirty` needs
+  a reference, and that combination is the one form a pre-commit hook wants.
+
 ## [0.8.1] - 2026-09-18
 
 Automated weekly release — everything merged since `v0.8.0`.