testguard-cli 0.10.1__tar.gz → 0.10.3__tar.gz

testguard_cli-0.10.3/.github/scripts/publish-homebrew-tap.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+fail() {
+  echo "::error::$*" >&2
+  exit 1
+}
+
+VERSION="${1:-}"
+[[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || fail "usage: publish-homebrew-tap.sh <stable-semver>"
+
+SOURCE_FORMULA="${HOMEBREW_TAP_SOURCE:-packaging/homebrew/testguard.rb}"
+TAP_REMOTE="${HOMEBREW_TAP_REMOTE:-git@github.com:raccioly/homebrew-tap.git}"
+[[ -f "$SOURCE_FORMULA" ]] || fail "source formula not found: $SOURCE_FORMULA"
+
+FORMULA_VERSION=$(sed -nE 's#^[[:space:]]*url ".*testguard-cli-([0-9]+\.[0-9]+\.[0-9]+)\.tgz"#\1#p' "$SOURCE_FORMULA")
+FORMULA_SHA=$(sed -nE 's/^[[:space:]]*sha256 "([0-9a-f]+)"/\1/p' "$SOURCE_FORMULA")
+[[ "$FORMULA_VERSION" = "$VERSION" ]] || fail "formula version $FORMULA_VERSION does not match release $VERSION"
+[[ "$FORMULA_SHA" =~ ^[0-9a-f]{64}$ ]] || fail "formula sha256 is not 64 lowercase hex characters"
+
+TEMP_ROOT="${RUNNER_TEMP:-${TMPDIR:-/tmp}}"
+[[ -d "$TEMP_ROOT" ]] || fail "temporary root does not exist: $TEMP_ROOT"
+WORK_DIR=$(mktemp -d "$TEMP_ROOT/testguard-homebrew-tap.XXXXXX")
+
+cleanup() {
+  case "$WORK_DIR" in
+    "$TEMP_ROOT"/testguard-homebrew-tap.*) rm -rf -- "$WORK_DIR" ;;
+    *) echo "::warning::refusing to remove unexpected temporary path: $WORK_DIR" >&2 ;;
+  esac
+}
+trap cleanup EXIT
+
+if [[ "$TAP_REMOTE" = git@github.com:* ]]; then
+  [[ -n "${HOMEBREW_TAP_DEPLOY_KEY:-}" ]] || fail "HOMEBREW_TAP_DEPLOY_KEY is required for the GitHub tap"
+  command -v gh >/dev/null || fail "gh is required to verify GitHub's SSH host keys"
+  KEY_FILE="$WORK_DIR/deploy_key"
+  KNOWN_HOSTS="$WORK_DIR/known_hosts"
+  umask 077
+  printf '%s\n' "$HOMEBREW_TAP_DEPLOY_KEY" > "$KEY_FILE"
+  gh api meta --jq '.ssh_keys[] | "github.com " + .' > "$KNOWN_HOSTS"
+  [[ -s "$KNOWN_HOSTS" ]] || fail "GitHub API returned no SSH host keys"
+  export GIT_SSH_COMMAND="ssh -i \"$KEY_FILE\" -o IdentitiesOnly=yes -o UserKnownHostsFile=\"$KNOWN_HOSTS\" -o StrictHostKeyChecking=yes"
+fi
+
+TAP_DIR="$WORK_DIR/tap"
+git clone --quiet --depth 1 "$TAP_REMOTE" "$TAP_DIR"
+TAP_FORMULA="$TAP_DIR/Formula/testguard.rb"
+[[ -f "$TAP_FORMULA" ]] || fail "tap is missing Formula/testguard.rb"
+
+if cmp -s "$SOURCE_FORMULA" "$TAP_FORMULA"; then
+  echo "✅ raccioly/tap already carries TestGuard v$VERSION ($FORMULA_SHA)"
+  exit 0
+fi
+
+install -m 0644 "$SOURCE_FORMULA" "$TAP_FORMULA"
+ruby -c "$TAP_FORMULA" >/dev/null
+git -C "$TAP_DIR" diff --check
+git -C "$TAP_DIR" config user.name "github-actions[bot]"
+git -C "$TAP_DIR" config user.email "github-actions[bot]@users.noreply.github.com"
+git -C "$TAP_DIR" add Formula/testguard.rb
+git -C "$TAP_DIR" commit --quiet -m "testguard $VERSION" -m "Published from raccioly/testguard's release workflow."
+git -C "$TAP_DIR" push --quiet origin HEAD:main
+git -C "$TAP_DIR" fetch --quiet origin main
+cmp "$SOURCE_FORMULA" <(git -C "$TAP_DIR" show origin/main:Formula/testguard.rb) \
+  || fail "live tap does not match the validated source formula after push"
+
+echo "✅ published TestGuard v$VERSION to raccioly/tap ($FORMULA_SHA)"

{testguard_cli-0.10.1 → testguard_cli-0.10.3}/.github/workflows/release.yml

@@ -1,8 +1,9 @@
-name: Auto Release — Tag, GitHub Release, npm, PyPI
+name: Auto Release — GitHub, npm, PyPI, Homebrew
 
 # TAG-DRIVEN and idempotent: a version needs releasing iff no tag v<version>
-# exists. Re-runs never double-publish. No long-lived secrets anywhere —
-# npm and PyPI both authenticate with OIDC Trusted Publishing.
+# exists. Re-runs never double-publish. npm and PyPI authenticate with OIDC
+# Trusted Publishing. Homebrew uses one long-lived SSH deploy key scoped only
+# to the distribution tap; it cannot access this repository or any other one.
 #
 # ONE-TIME SETUP (maintainer, cannot be automated):
 #   npm:  the first `npm publish` of testguard-cli is manual (Trusted Publishing
@@ -12,6 +13,9 @@ name: Auto Release — Tag, GitHub Release, npm, PyPI
 #   PyPI: pypi.org → Your account → Publishing → add a PENDING publisher for
 #         project testguard-cli: owner raccioly, repo testguard, workflow
 #         release.yml, environment pypi. The first release creates the project.
+#   Brew: add a write deploy key named testguard-release-homebrew-tap to
+#         raccioly/homebrew-tap and store its private half here as the Actions
+#         secret HOMEBREW_TAP_DEPLOY_KEY.
 
 on:
   workflow_dispatch: # manual recovery
@@ -231,15 +235,17 @@ jobs:
     # for byte from `npm pack` — after npm serves it (a publish is `PUT 202`;
     # the file can take minutes to appear, so the script polls, bounded).
     #
-    # It cannot commit to main: branch protection requires the three CI legs
-    # on every commit and github-actions[bot] is no admin. So the one-line
-    # 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. 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.
+    # The validated formula is also copied to the live raccioly/homebrew-tap
+    # repository with a write deploy key scoped only to that tap. The source
+    # copy cannot commit to main directly: branch protection requires the
+    # three CI legs on every commit and github-actions[bot] is no admin. So
+    # that one-line 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. 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 source 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
@@ -265,9 +271,10 @@ jobs:
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: 24
-      - name: Set sha256 from the published tarball; land it as an auto-merging PR
+      - name: Set sha256, publish the live tap, and land the source formula PR
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HOMEBREW_TAP_DEPLOY_KEY: ${{ secrets.HOMEBREW_TAP_DEPLOY_KEY }}
         run: |
           set -euo pipefail
           VERSION="${{ needs.detect-version.outputs.version }}"
@@ -290,6 +297,11 @@ jobs:
           # other surface drifted. Nothing is pushed unless this passes.
           node .github/scripts/sync-release-version.mjs --check --online
 
+          # Homebrew users install from raccioly/homebrew-tap, not this staged
+          # copy. Publish the exact formula that passed the online check. The
+          # helper is idempotent and fails closed if the tap cannot be updated.
+          .github/scripts/publish-homebrew-tap.sh "$VERSION"
+
           if git diff --quiet -- packaging/homebrew/testguard.rb; then
             echo "✅ $BRANCH already carries the published sha256"
           else

{testguard_cli-0.10.1 → testguard_cli-0.10.3}/.github/workflows/scheduled-release.yml

@@ -148,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\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
+          printf 'Automated weekly release. Version bump + CHANGELOG entry + synced version surfaces. Merging tags and publishes to GitHub, npm, PyPI, and Homebrew 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.

{testguard_cli-0.10.1 → testguard_cli-0.10.3}/AGENTS.md

@@ -1,6 +1,6 @@
 # AI Agent Instructions — TestGuard
 
-<!-- docguard:last-reviewed 2026-09-18 -->
+<!-- docguard:last-reviewed 2026-09-19 -->
 
 Read this before changing anything. It is short on purpose.
 
@@ -63,7 +63,9 @@ node cli/testguard.mjs scaffold src/probe/classify.mjs --json   # what the produ
 
 Dependabot minor/patch PRs and automated release PRs auto-merge when the exact
 CI run is green on all three Node legs. Majors and anything else wait for a
-human. Release publishing is OIDC-only; there are no tokens in this repo.
+human. npm and PyPI publishing is OIDC-only; Homebrew uses a dedicated SSH
+deploy key scoped only to `raccioly/homebrew-tap`. There are no personal or
+registry tokens in this repo.
 
 <!-- testguard:begin -->
 ## TestGuard

{testguard_cli-0.10.1 → testguard_cli-0.10.3}/CHANGELOG.md

@@ -7,6 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.3] - 2026-09-20
+
+Automated weekly release — everything merged since `v0.10.2`.
+
+### Changed
+
+- fix(gate): infer safe local change base (#145)
+- chore(homebrew): sha256 for v0.10.2 (#144)
+
+
+### Fixed
+
+- Bare `testguard gate` now discovers an ordinary clone's remote default
+  branch and reports how it chose the comparison. It still fails closed on
+  ambiguous Git state: the default branch is not compared to itself, and a
+  feature branch's same-name tracking ref is never accepted as its base.
+
+## [0.10.2] - 2026-09-20
+
+Automated weekly release — everything merged since `v0.10.1`.
+
+### Changed
+
+- fix(release): publish the live Homebrew tap (#142)
+- chore(homebrew): sha256 for v0.10.1 (#141)
+
+
+### Fixed
+
+- Releases now publish the registry-verified Homebrew formula to the live
+  `raccioly/tap` repository with a dedicated, tap-scoped deploy key. The
+  release fails closed if that copy cannot be made, instead of updating only
+  the staging formula in this repository while users remain on an old version.
+
+### Changed
+
+- The self-probe cost budget is 1440 s, from 1230. The cold v0.10.1 release
+  measured 1210 s before the four-fault live-tap claim added about 53 s; 1440
+  restores the established ~14% CI headroom. The 100 s per-claim ceiling is
+  unchanged, so an individually expensive claim still fails the gate.
+
 ## [0.10.1] - 2026-09-19
 
 Automated weekly release — everything merged since `v0.10.0`.

{testguard_cli-0.10.1 → testguard_cli-0.10.3}/CONTRIBUTING.md

@@ -79,12 +79,16 @@ on the fault.
 `package.json` is the single source of truth for the version;
 `.github/scripts/sync-release-version.mjs` propagates it. A weekly workflow
 opens a release PR; merging it tags and publishes to npm and PyPI via OIDC
-Trusted Publishing. There are no tokens to rotate.
+Trusted Publishing. There are no npm or PyPI tokens to rotate. Homebrew uses a
+dedicated SSH deploy key that can write only to `raccioly/homebrew-tap`; its
+private half is stored as the `HOMEBREW_TAP_DEPLOY_KEY` Actions secret.
 
 The Homebrew formula's `sha256` is the one surface that cannot be known before
 publishing: `release.yml` sets it after `npm publish`, from the registry
-tarball (`sync-release-version.mjs --sha256`), and lands it as a bot PR with
-auto-merge armed — `main` is protected, so no job commits to it directly.
+tarball (`sync-release-version.mjs --sha256`), copies that verified formula
+byte-for-byte to the live tap, and lands the source copy as a bot PR with
+auto-merge armed — this repository's `main` is protected, so no job commits to
+it directly.
 `--check` (offline) refuses a placeholder hash; `--check --online` compares
 against the tarball and is what decides, on every hourly sweep, whether the
 formula is still owed.

{testguard_cli-0.10.1 → testguard_cli-0.10.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: testguard-cli
-Version: 0.10.1
+Version: 0.10.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.10.1` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.10.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.10.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.10.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
@@ -484,9 +484,17 @@ 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
+**The base is detected when Git records it.** An explicit `--changed` wins,
+then `TESTGUARD_CHANGED_REF`, GitHub Actions (`GITHUB_BASE_REF`) and GitLab
 merge request pipelines (`CI_MERGE_REQUEST_DIFF_BASE_SHA`, then
-`CI_MERGE_REQUEST_TARGET_BRANCH_NAME`); `TESTGUARD_CHANGED_REF` overrides both.
+`CI_MERGE_REQUEST_TARGET_BRANCH_NAME`). In an ordinary clone on a feature
+branch, bare `testguard gate` uses the configured remote's symbolic default
+branch (normally `origin/main`) and says how it chose it. If that symbolic ref
+is absent, a configured upstream is used only when its branch name differs
+from the current branch. A feature branch's same-name tracking ref and the
+default branch itself are never selected: either could produce a misleading
+empty diff. In those ambiguous cases, pass `--changed` explicitly.
+
 The base must exist locally: GitHub — `actions/checkout` with `fetch-depth: 0`;
 GitLab — the diff base sha needs nothing extra on a merge request pipeline,
 the branch name needs `GIT_DEPTH: 0` or a `git fetch origin <target>`. A
@@ -497,12 +505,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.10.1
+- uses: raccioly/testguard@v0.10.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.10.1/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.10.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.10.1 → testguard_cli-0.10.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.10.1` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.10.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.10.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.10.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
@@ -460,9 +460,17 @@ 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
+**The base is detected when Git records it.** An explicit `--changed` wins,
+then `TESTGUARD_CHANGED_REF`, GitHub Actions (`GITHUB_BASE_REF`) and GitLab
 merge request pipelines (`CI_MERGE_REQUEST_DIFF_BASE_SHA`, then
-`CI_MERGE_REQUEST_TARGET_BRANCH_NAME`); `TESTGUARD_CHANGED_REF` overrides both.
+`CI_MERGE_REQUEST_TARGET_BRANCH_NAME`). In an ordinary clone on a feature
+branch, bare `testguard gate` uses the configured remote's symbolic default
+branch (normally `origin/main`) and says how it chose it. If that symbolic ref
+is absent, a configured upstream is used only when its branch name differs
+from the current branch. A feature branch's same-name tracking ref and the
+default branch itself are never selected: either could produce a misleading
+empty diff. In those ambiguous cases, pass `--changed` explicitly.
+
 The base must exist locally: GitHub — `actions/checkout` with `fetch-depth: 0`;
 GitLab — the diff base sha needs nothing extra on a merge request pipeline,
 the branch name needs `GIT_DEPTH: 0` or a `git fetch origin <target>`. A
@@ -473,12 +481,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.10.1
+- uses: raccioly/testguard@v0.10.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.10.1/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.10.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.10.1 → testguard_cli-0.10.3}/SECURITY.md

@@ -4,7 +4,7 @@
 
 | Version | Supported |
 |---------|-----------|
-| 0.1.x   | ✅ current |
+| 0.10.x  | ✅ current |
 
 ## Reporting a vulnerability
 
@@ -27,9 +27,11 @@ TestGuard is a local CLI with a deliberately small surface:
   scratch git worktrees under the system temp directory, which are removed
   after each run. With `--in-place`, the mutated files are restored — on
   success, on failure, and on `SIGINT`/`SIGTERM`.
-- **Publishing uses OIDC Trusted Publishing** to npm and PyPI. The release
-  pipeline holds no long-lived tokens; npm provenance attestations are
-  generated automatically.
+- **Publishing uses OIDC Trusted Publishing** to npm and PyPI, so the release
+  pipeline holds no registry tokens and npm provenance attestations are
+  generated automatically. Homebrew publishing uses a dedicated SSH deploy
+  key scoped only to `raccioly/homebrew-tap`; it cannot access this repository
+  or any other repository.
 
 ## The claims file is code
 

{testguard_cli-0.10.1 → testguard_cli-0.10.3}/action.yml

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

{testguard_cli-0.10.1 → testguard_cli-0.10.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.10.1 · MIT</div>
+    <div class="meta">Technical Brief · v0.10.3 · MIT</div>
   </div>
 
   <h1>Your tests pass. That is not the same as your tests working.</h1>

{testguard_cli-0.10.1 → testguard_cli-0.10.3}/docs-canonical/ARCHITECTURE.md

@@ -85,7 +85,7 @@ other tools, and it must remain portable out of this repository.
 | Supported runners | vitest, jest (project runners); Playwright (per file) | They share a JSON report shape; Playwright is selected per file, not per project |
 | Schemas | JSON Schema 2020-12 | Readable without the tool; portable to other languages |
 | Distribution | npm, PyPI, Homebrew, GitHub Action, pre-commit, GitLab component | Meet teams in the pipeline they already run |
-| Publishing | OIDC Trusted Publishing | No long-lived tokens exist to leak or rotate |
+| Publishing | OIDC for npm/PyPI; tap-scoped SSH deploy key for Homebrew | Registry credentials remain tokenless; the only stored publishing secret cannot access any repository except the tap |
 
 ## Configuration Files
 
@@ -101,7 +101,7 @@ appears here but not on disk, or on disk but not here, is drift.
 | `.pre-commit-hooks.yaml` | Hook definitions **we publish for consumers** of TestGuard — a different file for a different audience | consumers' `.pre-commit-config.yaml` |
 | `action.yml` | The GitHub Action surface; `version` input synced from `package.json` | consumers' workflows |
 | `packaging/gitlab/testguard.gitlab-ci.yml` | The GitLab component; tag and `TESTGUARD_VERSION` synced | consumers' pipelines |
-| `packaging/homebrew/testguard.rb` | The Homebrew formula; tarball URL synced | `raccioly/homebrew-tap` |
+| `packaging/homebrew/testguard.rb` | The staged Homebrew formula; tarball URL and registry-derived hash synced, then copied byte-for-byte | `raccioly/homebrew-tap` |
 | `.docguard.json`, `.docguardignore` | Which canonical documents exist and which validators run | DocGuard, in CI and pre-commit |
 | `.npmrc`, `.npmignore`, `.gitattributes` | Packaging and line-ending hygiene | npm, git |
 
@@ -115,7 +115,7 @@ and no license server.
 | `ajv` (npm, bundled) | Validate every document against the spec | none — local | Install-time only; the install smoke gate catches a missing runtime dep |
 | `git` (system binary) | Worktree isolation, diffs, snapshots, patch ids | none — local | Precondition failure with a stated reason, exit 2 |
 | The project's test runner | Runs the defenders | none — local | Precondition failure, exit 2; never a verdict about a claim |
-| npm / PyPI registries | Distribution only | build time | A publish fails; the tool itself never calls them at run time |
+| npm / PyPI registries and Homebrew tap | Distribution only | build time | A publish fails; the tool itself never calls them at run time |
 
 ## Infrastructure (IaC)
 
@@ -133,8 +133,8 @@ to every other surface and `--check` fails the build on drift.
 |---|---|---|
 | 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 |
+| Merge to main | `release.yml` | A version with no tag is tagged, released, and published to npm and PyPI over OIDC; the verified formula is pushed to the live Homebrew tap with its repository-scoped deploy key |
+| Recovery | `release.yml` | Hourly sweep; each registry and the formula hash are gated on their own state, so a partial publish is fixed by re-running |
 
 ## Diagrams
 

{testguard_cli-0.10.1 → testguard_cli-0.10.3}/docs-canonical/ENVIRONMENT.md

@@ -2,7 +2,7 @@
 
 <!-- docguard:version 1.0.0 -->
 <!-- docguard:status approved -->
-<!-- docguard:last-reviewed 2026-09-18 -->
+<!-- docguard:last-reviewed 2026-09-20 -->
 <!-- docguard:owner @raccioly -->
 <!-- docguard:quality negation-load off — the environment is defined by absences: no required variables, no secrets, no network, no service. -->
 <!-- docguard:quality passive-voice off — setup steps describe what is read and written, not who reads and writes it. -->
@@ -28,7 +28,7 @@ None are required. All are optional overrides.
 | Variable | Read by | Effect |
 |---|---|---|
 | `TESTGUARD_NODE_MODULES` | `probe` | `node_modules` to link into the scratch worktree; same as `--node-modules` |
-| `TESTGUARD_CHANGED_REF` | `gate`, `status --changed` | The reference a change is measured against; overrides CI detection |
+| `TESTGUARD_CHANGED_REF` | `gate`, `status --changed` | The reference a change is measured against; overrides CI and local Git detection |
 | `GITHUB_BASE_REF` | `gate` | GitHub Actions pull requests: the base branch |
 | `CI_MERGE_REQUEST_DIFF_BASE_SHA` | `gate` | GitLab merge request pipelines: exact diff base, needs no fetch |
 | `CI_MERGE_REQUEST_TARGET_BRANCH_NAME` | `gate` | GitLab fallback when the diff base sha is absent |
@@ -37,6 +37,16 @@ None are required. All are optional overrides.
 The tool sets `PLAYWRIGHT_JSON_OUTPUT_FILE` and `FORCE_COLOR=0` on the
 processes it spawns. It reads no secret, no token and no credential.
 
+## Local Git Discovery
+
+Without an explicit, environment or CI reference, TestGuard reads only local
+Git metadata. On a feature branch it prefers the configured remote's symbolic
+default branch, such as `origin/main`. If that ref is absent, it accepts the
+branch's configured upstream only when the upstream branch name differs from
+the current branch name. It never contacts the remote, never compares the
+default branch to itself, and never treats `origin/feature` as the base of a
+local `feature` branch; those ambiguous cases require `--changed`.
+
 ## Configuration Files
 
 | File | Owner | Committed | Purpose |

{testguard_cli-0.10.1 → testguard_cli-0.10.3}/docs-canonical/SECURITY.md

@@ -2,9 +2,9 @@
 
 <!-- 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 — a security posture is a list of things that must not happen: no network, no secrets, no tokens, no telemetry. Stating them positively would weaken them. -->
+<!-- docguard:quality negation-load off — a security posture is a list of things that must not happen: no runtime network, no CLI secrets, no registry tokens, no telemetry. Stating them positively would weaken them. -->
 <!-- docguard:quality passive-voice off — threat and control statements name what is protected, not who protects it; the actor is the system throughout. -->
 
 > Canonical. Code that contradicts this document is drift.
@@ -27,8 +27,14 @@ happens in CI, never on a developer machine:
 | npm | OIDC Trusted Publishing | none |
 | PyPI | OIDC Trusted Publishing (environment `pypi`) | none |
 | GitHub releases | `GITHUB_TOKEN`, scoped to the run | none stored |
+| Homebrew tap | SSH deploy key scoped to `raccioly/homebrew-tap` | `HOMEBREW_TAP_DEPLOY_KEY` |
 
-There are no tokens in this repository to rotate or leak.
+npm and PyPI have no registry tokens to rotate or leak. Homebrew publishing
+uses one stored credential: a dedicated Ed25519 deploy key whose public half
+has write access only to `raccioly/homebrew-tap` and whose private half is the
+`HOMEBREW_TAP_DEPLOY_KEY` Actions secret in this repository. It is not a
+personal key and cannot access another repository. Rotate it by replacing both
+the tap deploy key and the Actions secret.
 
 ## Authorization
 
@@ -53,8 +59,11 @@ guarantees are about **what the tool is allowed to touch**:
 
 ## Secrets Management
 
-TestGuard neither reads nor stores secrets. It has no credential file, no
-keychain access and no environment variable holding a secret.
+The TestGuard CLI neither reads nor stores secrets. It has no credential file,
+no keychain access and no environment variable holding a secret. The release
+workflow is the deliberate exception: its Homebrew step receives the
+tap-scoped deploy key only while it copies a registry-verified formula to the
+distribution repository. npm and PyPI publishing remain OIDC-only.
 
 Two consequences worth stating for reviewers:
 

{testguard_cli-0.10.1 → testguard_cli-0.10.3}/docs-canonical/TEST-SPEC.md

@@ -21,7 +21,7 @@ the test that defends it, and CI fails if any injected fault survives.
 | 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 |
+| Self-verification | `testguard.claims.json`, run by `npm run self:probe` | The tool's own invariants survive fault injection | **20.2 min** cold (measured by the v0.10.1 release job on 2026-09-19 at `70e9d61`: 154 faults, 924 defender runs, 1210 s); seconds when verdicts are reused, which is why PR CI restores previous evidence from cache. Budgeted at 1440 s in `testguard.cost-budget.json` for the additional four-fault live-tap claim and **gated** in CI — cost growth is reviewed instead of disappearing into a passing log |
 | Install smoke | `.github/scripts/install-smoke.mjs` | The **packed tarball** runs with production dependencies only | ~20 s |
 | Runtime budget | `ci.yml` | The suite has not silently started walking the wrong tree | gate, not a test |
 

{testguard_cli-0.10.1 → testguard_cli-0.10.3}/package-lock.json

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

{testguard_cli-0.10.1 → testguard_cli-0.10.3}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.10.1",
+  "version": "0.10.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.10.1 → testguard_cli-0.10.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.10.1/packaging/gitlab/testguard.gitlab-ci.yml'
+#     - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.10.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.10.1"
+      default: "0.10.3"
     dir:
       description: directory whose test runner is invoked (where testguard.claims.json lives)
       default: "."

{testguard_cli-0.10.1 → testguard_cli-0.10.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.10.1.tgz"
-  sha256 "ebb9e4ac0370e0b2cbc52b3e5f24e8426020fd3b5ff9db6b2776ab2744874dab"
+  url "https://registry.npmjs.org/testguard-cli/-/testguard-cli-0.10.3.tgz"
+  sha256 "073d225733ecf5ba3da9fecc5952236a3fa22c46cb5981def3f568d08e1ca044"
   license "MIT"
 
   depends_on "node"

{testguard_cli-0.10.1 → testguard_cli-0.10.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "testguard-cli"
-version = "0.10.1"
+version = "0.10.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.10.1 → testguard_cli-0.10.3}/spec/GATE-SEMANTICS.md

@@ -402,9 +402,14 @@ Rules:
 4. **Never a silent pass on nothing.** A non-empty change whose files were
    all excluded passes with an explicit "0 evaluated" line; a tool offers a
    strict mode that fails it instead. An empty change is an honest `0`.
-5. **The reference is never guessed.** An explicit flag, or a CI-provided base
-   branch, or an error. An upstream that already contains the change has an
-   empty diff and would pass trivially.
+5. **The reference is inferred only from recorded intent.** Resolution stops
+   at the first available source: an explicit flag, `TESTGUARD_CHANGED_REF`, a
+   CI-provided base, the configured remote's symbolic default branch, then a
+   configured upstream whose branch name differs from the current branch.
+   Local discovery never compares a branch to its same-name remote-tracking
+   ref: that ref may already contain the whole change and yield a false empty
+   diff. It also declines to compare the default branch to itself. When Git
+   records no safe local base, the gate exits `3` and asks for `--changed`.
 6. **Unclaimed changes precede every evidence state.** When the status
    document knows a reference and finds uncovered files, its state is
    `unclaimed-changes` and its next action is to write the claim, before any

{testguard_cli-0.10.1 → testguard_cli-0.10.3}/src/commands/brief.mjs

@@ -13,7 +13,7 @@ export async function briefCommand({ projectDir, values, version }, io) {
     // A detected base that does not resolve is silent here: the brief is a
     // session-start hook's output and must never add noise; `status` and
     // `gate` are where that warning is printed.
-    status = withChangedRef(resolveChangedRef({ explicit: values.changed }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'], evidence: values.evidence ? evPath : undefined }));
+    status = withChangedRef(resolveChangedRef({ explicit: values.changed, projectDir }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'], evidence: values.evidence ? evPath : undefined }));
   } catch {
     status = undefined; // a brief must never fail because status could not be computed
   }