Aggregate independent checks to report all failures at once (#138)

* Report every independent check failure, and gate the settled decisions

Two gaps ported from the tooling in alexkroman/agent, both about a red run
telling you everything it knows instead of one thing at a time.

check.sh aggregates its read-only checks. Everything before `swift test` is
independent and non-mutating, so there was no ordering reason for the first
failure to hide the rest — but under a plain `set -e` it did: one pending
swift-format reflow ended the run before swiftlint, actionlint, zizmor,
prettier, markdownlint, shellcheck, shfmt, ruff and pytest had said anything.
That is the same complaint PR #128's reordering comment makes about the build
("their findings arrived one red run at a time"); reordering fixed only the half
that was the build's fault. `run_check` now records a failure and continues, and
an exit trap reports the tally. The trap rather than a block at the bottom is
load-bearing: the fail-fast region sits between the two, so `swift test` failing
under errexit would exit straight past a closing summary and throw away
everything already collected. swiftlint analyze and periphery are aggregated for
the same reason at higher cost — each takes minutes, and periphery runs its own
xcodebuild. The build, coverage gate, sanitizers and integration steps stay
fail-fast, where the dependency is real.

check-invariants.sh mechanizes the grep-decidable half of AGENTS.md's "Settled
decisions" table, which until now was enforced only for as long as a reviewer
remembered it. Twelve rules: AVAudioEngine/installTap capture, a streaming or
on-device path, a client-side cleanup pass, config.language_code, config.prompt,
a keystroke-typing injector, LSUIElement, a KeyboardShortcuts import, a
self-replacing updater, the production Keychain under Tests/, and deprecated
shims. Shape is check-portability.sh's, since both answer "does this tree
contain a construct we decided against?": parallel rule arrays, a --self-test
asserting each pattern still matches its own probe, and a `// invariant-ok:`
escape hatch. Two additions to that shape — negative probes drawn from real
lines that sit one character from a rule (the Accessibility prompt dictionary
against the "prompt" wire key, the test keychain against the production one),
and a check that every rule's scope matches tracked files, because a scope typo
kills a rule as quietly as a broken regex.

Scopes do real work: KeytermsWireTests contains
`#expect(object.keys.contains("language_code") == false)` — the invariant being
enforced — so that rule reads Sources/ only. Rules that cannot separate a
violation from correct code stay prose and stay in review; the filler-word
clause is the clearest case, since CleanupInstruction's rewrite instruction
legitimately names filler sounds.

Verified with scripts/check.sh --portable (green), and against deliberately
broken trees: five simultaneous failures all reported in one run, and a
recorded failure still reported when a simulated `swift test` abort ends the
run early.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TACi7k2226no2tVcR3YJr1

* Pin each invariant rule to the prose it enforces

The gate shipped in the previous commit looks like it enforces AGENTS.md's
settled-decisions table, but nothing tied a rule to a row — and the rows move.
PR #132 rewrote the config.prompt and language entries three weeks ago. A rule
that outlives its row is the one failure this file cannot survive: it keeps
firing, keeps citing AGENTS.md, and keeps sounding authoritative while enforcing
a decision the project has reversed. That is strictly worse than the prose it
replaced — prose that no longer reflects the design gets read and ignored, a
gate that no longer reflects the design blocks the change that reflects it.

Each rule now carries a verbatim slice of its "Don't" cell and of its bullet in
the guardrails skill, and --self-test asserts both still resolve. The table
anchor is matched inside the table section only (sed-extracted), so a deleted
row cannot keep its pin alive by being mentioned in passing elsewhere in the
guide; a failed extraction reports itself as a moved heading rather than as
twelve simultaneously-unpinned rules. The skill anchors are deliberately not the
table's wording — the skill says the same things differently, and a pin that
assumed identical text would only be checking that someone had copy-pasted.

This also makes CLAUDE.md's "keep the two in agreement when you change either"
cost one grep instead of a reviewer's memory, for the twelve decisions that are
mechanized. The remaining rows stay a matter of care, and the docs now say which
is which.

The failure message asks for a decision rather than a patch: reworded row,
update the anchor; reversed decision, delete the rule with it.

Verified: deleting a row, rewording a row, dropping a skill bullet, and renaming
the table heading each fail --self-test with the right message; the clean tree
passes; scripts/check.sh --portable is green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TACi7k2226no2tVcR3YJr1

* Tighten the portable-subset paragraph in the check skill

The tool list was a slash-separated run-on inside a parenthetical that had grown
another item, wrapping mid-clause and reading as a fragment. Same facts, same
tools, split into a list and a second paragraph.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TACi7k2226no2tVcR3YJr1

* Drop the duplicated invariants list from the engine guide

The engine README carried a third copy of the settled-decisions list, after
AGENTS.md's table and the project-guardrails skill. Three copies is two chances
to drift, and this one had no mechanism keeping it honest: the rules pinned by
check-invariants.sh anchor to the AGENTS.md row and the skill bullet, so a
change here would have gone unnoticed by everything.

Nothing unique is lost. Every bullet was already covered — the Swift 6
concurrency rule near-verbatim in AGENTS.md's Conventions, dependency-freedom in
several places, and the rest are rows of the settled-decisions table. The
section stays, pointing at the single copy, because an embedder reading this
guide still needs to know the constraints exist.

The inline rationale under `MicCaptureProtocol` is deliberately kept: explaining
why capture is a fresh AVAudioRecorder per session is part of documenting that
seam, not a duplicate of the list.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TACi7k2226no2tVcR3YJr1

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: alexkroman

.claude/skills/check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: check
-description: Verify the repo is green by running scripts/check.sh — the same full health check CI runs (swift test + coverage gate, sanitizers, xcodegen drift, app build, swift-format/swiftlint/periphery/prettier/markdownlint/shellcheck/shfmt, site deployability, ruff + pytest over evals/). Use before claiming a change builds, passes, or is ready to commit/PR. Bakes in the macOS-only guard so a Linux/web sandbox flags "verify on a Mac" instead of fabricating a green result; there, scripts/check.sh --portable runs the platform-independent subset (docs/site/scripts/workflows).
+description: Verify the repo is green by running scripts/check.sh — the same full health check CI runs (swift test + coverage gate, sanitizers, xcodegen drift, app build, swift-format/swiftlint/periphery/prettier/markdownlint/shellcheck/shfmt, site deployability, settled-decision invariants, ruff + pytest over evals/). Its read-only checks report together, so a red run names every failure at the bottom rather than stopping at the first. Use before claiming a change builds, passes, or is ready to commit/PR. Bakes in the macOS-only guard so a Linux/web sandbox flags "verify on a Mac" instead of fabricating a green result; there, scripts/check.sh --portable runs the platform-independent subset (docs/site/scripts/workflows).
 ---
 
 # check — is this green?
@@ -27,19 +27,20 @@ What you CAN run there is the portable subset:
 scripts/check.sh --portable
 ```
 
-It runs the repo-integrity guards (dependencies, sound catalog, site, shell
-portability) then
-actionlint / zizmor / prettier / xmllint / markdownlint / shellcheck / shfmt /
-ruff (lint + format check) / pytest over `evals/` / `release.test.sh` (plus `swift-format lint` and `swiftlint lint` if Linux
-builds are on `PATH` — under the default web network policy they are not).
-That fully verifies docs, site, scripts, eval, and workflow changes. It is **not**
-"green" in the CI sense: the entire Swift side is skipped, and the closing
-line says so. For Swift changes, push and watch `check.yml` instead — its
-`compile` job reports a broken test build in ~2 minutes, and `format-patch`
+It runs the repo-integrity guards — dependencies, sound catalog, site, shell
+portability, and settled decisions — then actionlint, zizmor, prettier, xmllint,
+markdownlint, shellcheck, shfmt, ruff (lint + format check), pytest over
+`evals/`, and `release.test.sh`. `swift-format lint` and `swiftlint lint` join
+them when Linux builds are on `PATH`; under the default web network policy they
+are not.
+
+That fully verifies docs, site, scripts, eval, and workflow changes. It is
+**not** "green" in the CI sense: the entire Swift side is skipped, and the
+closing line says so. For Swift changes, push and watch `check.yml` instead —
+its `compile` job reports a broken test build in ~2 minutes, and `format-patch`
 publishes the exact `swift-format` reflow as an artifact so you don't have to
-reproduce it by hand. In
-Claude Code on the web, the `SessionStart` hook installs the portable
-linters automatically.
+reproduce it by hand. In Claude Code on the web, the `SessionStart` hook
+installs the portable linters automatically.
 
 Quick preflight:
 
@@ -62,6 +63,11 @@ Everything source-only runs first, then everything that builds. That ordering is
 deliberate: reversed, a compile error means the cheap checks are
 never reached and their findings arrive on the next 11-minute run instead.
 
+The read-only checks (steps 1–5, plus 12) also don't stop each other: each one
+runs, failures are tallied, and the run ends with a single `error: N check(s)
+failed:` list naming all of them. So one pending `swift-format` reflow no longer
+hides every lint finding behind it — expect to fix a batch, not a queue.
+
 1. repo-integrity guards: no external SPM dependencies; sound-catalog
    integrity (every `SoundPackCatalog` voice has both cue files, no orphans, no
    duplicate or reserved ids); and site integrity (`scripts/check-site.sh` —
@@ -70,7 +76,15 @@ never reached and their findings arrive on the next 11-minute run instead.
    no unreferenced assets). All run in `--portable` too
 2. shell portability (`scripts/check-portability.sh`): GNU-only idioms in
    `scripts/*.sh` and `.claude/hooks/*.sh`, which run on BSD userland (Mac, CI)
-   as well as GNU (Linux sandbox). `--portable` too
+   as well as GNU (Linux sandbox). Then settled decisions
+   (`scripts/check-invariants.sh`): the grep-decidable subset of AGENTS.md's
+   [Settled decisions](../../../AGENTS.md#settled-decisions--dont-reintroduce-these)
+   table — `AVAudioEngine` capture, a streaming or on-device path, a client-side
+   cleanup pass, `LSUIElement`, a keystroke-typing injector, the production
+   Keychain in tests. Each rule is pinned to its table row and its
+   `project-guardrails` bullet, so editing the prose without revisiting the rule
+   fails here rather than leaving a gate that enforces a reversed decision. Both
+   `--portable` too
 3. `swift-format lint --strict`, then `swiftlint lint --strict` (warnings are
    failures) — both source-only
 4. actionlint / zizmor (workflow security) / prettier / xmllint / markdownlint /
@@ -102,6 +116,9 @@ never reached and their findings arrive on the next 11-minute run instead.
 - **Any non-zero exit** → not green. Report the failing step and its output
   verbatim; do not soften ("mostly passes") or claim success. Fix, then re-run
   the _full_ `check.sh` — a single-file `swift test --filter` is not green.
+  A red run reports every independent failure it found, so read the closing
+  `error: N check(s) failed:` list and fix all of them before re-running —
+  stopping at the first one wastes the aggregation.
 - A `note: <tool> not installed; skipping` line means coverage of that check is
   _missing_, not satisfied. On a dev Mac, run `scripts/bootstrap.sh` to install
   the toolchain rather than accepting skips.

.claude/skills/project-guardrails/SKILL.md

@@ -10,6 +10,18 @@ These are settled decisions. Don't reintroduce them; if a task seems to require
 one, stop and ask the user first. This is the fast "don't" list; AGENTS.md's
 "Settled decisions" table is the fuller reference and the source of truth.
 
+Many of these are also enforced mechanically — `scripts/check-invariants.sh`
+(run by `check.sh`, including `--portable`) greps for the constructs that give
+each one away, so reintroducing one fails the health check rather than depending
+on this list being read. Those rules also pin a verbatim slice of the bullet
+they come from in this file, so rewording or deleting one fails the gate until
+someone decides whether the rule survives the edit — edit these entries
+knowing that, and fix the anchor in the same change. Treat that as a backstop, not the boundary: the rules
+it can't express are still here, still binding, and the reasons in this file are
+what let you tell an intended exception from a mistake. Never silence a finding
+with `// invariant-ok:` to get a build green — that marker is for a line that is
+genuinely correct, and reaching for it means it's time to stop and ask.
+
 ## Audio
 
 - **No `AVAudioEngine` / `installTap` capture path.** `MicCapture` uses

AGENTS.md

@@ -69,8 +69,8 @@ App/Blurt/
   Shared/                    UITestIdentifiers.swift — compiled into BOTH app and UI-test targets
   BlurtUITests/              XCUITest bundle (see Tests)
 Tests/BlurtEngineTests/      Swift Testing suites; Stubs/ holds the seam doubles
-scripts/                     check.sh, check-site.sh, bootstrap.sh, dev-build.sh, uitest.sh, leaks.sh,
-                             release*.sh
+scripts/                     check.sh, check-site.sh, check-portability.sh, check-invariants.sh,
+                             bootstrap.sh, dev-build.sh, uitest.sh, leaks.sh, release*.sh
                              hand-run maintainer tools — no automated caller, invoked by a
                              human, so "nothing references it" here does NOT mean dead code:
                              serve-site.sh (preview site/ locally), screenshot.swift +
@@ -327,6 +327,24 @@ In Claude Code on the web, a `SessionStart` hook installs the portable linters a
 Each was tried the other way and reverted. If a task seems to require one, stop and ask first.
 (`.claude/skills/project-guardrails` is the compressed version of this list.)
 
+`scripts/check-invariants.sh` mechanizes the subset of this table a regex can decide, so those
+entries fail `check.sh` rather than relying on a reviewer's memory: `AVAudioEngine`/`installTap`
+capture, a streaming or on-device path, a client-side cleanup pass (`StylerProtocol`, an LLM
+Gateway/LeMUR client), `config.language_code`, `config.prompt`, a keystroke-typing injector,
+`LSUIElement`, a `KeyboardShortcuts` import, a self-replacing updater, the production Keychain
+under `Tests/`, and `@available(*, deprecated)` shims. The SPM-dependency row has its own guard in
+`check.sh` (it parses `project.yml`'s `packages:` block), and the `.pbxproj` row is covered by the
+xcodegen drift check plus a Claude `PreToolUse` hook. The rest — the filler-word clause, the
+context-widening rule, the `/Applications` install path — stay prose, because no pattern separates
+them from correct code that reads the same. Add a rule when you find one that can.
+
+**Editing a mechanized row breaks the build on purpose.** Each of those rules pins a verbatim slice
+of its row here (and of its bullet in the guardrails skill), so deleting or rewording one fails
+`check-invariants.sh --self-test`. That is the intended behaviour, not an obstacle to route around:
+a rule that outlives its row keeps firing and keeps citing this table while enforcing something the
+project has already reversed. Reworded the row? Update the anchor. Reversed the decision? Delete the
+rule along with the row.
+
 | Don't                                                      | Because                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Add an external SPM dependency to the engine               | Dependency-free by rule (biggest supply-chain risk); a `check.sh` guard fails on `.package(` in `Package.swift` or a `url:`/`github:` package in `project.yml`. Extend `BlurtEngine` instead.                                                                                                                                                                                                                                                                                                                                                                                                                                |

CLAUDE.md

@@ -48,7 +48,11 @@ globs go in one invocation so `hook-lib.sh` and `release-lib.sh` are in the inpu
   portable subset. Load it before claiming a change builds or passes.
 - **`project-guardrails`** — the compressed "don't do this" list. `AGENTS.md`'s
   [Settled decisions](./AGENTS.md#settled-decisions--dont-reintroduce-these) table is the fuller
-  reference and the source of truth; keep the two in agreement when you change either.
+  reference and the source of truth; keep the two in agreement when you change either. For the
+  twelve decisions `scripts/check-invariants.sh` mechanizes, that agreement is no longer on your
+  honour: each rule pins a verbatim slice of its table row _and_ its skill bullet, so deleting or
+  rewording either fails the gate's `--self-test` until someone decides whether the rule survives
+  the edit. The rest of the list is still yours to keep in sync.
 - **`release`** — the ship pipeline (build → sign → notarize → staple → DMG → GitHub). User-invoked
   only: it has real, hard-to-undo side effects.
 - **`launch-metrics`** — read-only launch KPI snapshot from the GitHub API.

Sources/BlurtEngine/README.md

@@ -280,11 +280,4 @@ Two ways out, neither taken yet: drop it from the public product (its own target
 
 ## Invariants — don't break these
 
-Each of these was tried the other way and reverted; the longer stories are in [AGENTS.md](../../AGENTS.md) and the source comments:
-
-- **No external SPM dependencies in the engine.** Foundation/Security/AVFoundation only.
-- **No streaming STT, no local models, no client-side LLM cleanup pass.** One dictation request per utterance is the architecture; the cleanup rewrite is server-side (the request's `llm` block), and transcription steering belongs in `ConversationContext`.
-- **No `AVAudioEngine`/`installTap` capture path.** Fresh `AVAudioRecorder` per session, resolved at record time.
-- **Paste is always clipboard-based** (save → write → ⌘V → settle → restore), with the copied-to-clipboard degradation for lost targets.
-- **No English-pinning or filler-word clauses**, no reviving `config.prompt`, and no widening the conversation context past the recent dictations and the prior chunk — the app name, window title, field label and selected text stay on the machine. Key terms go on `config.word_boost`, never back into the context turns.
-- **Actors own state** (`DictationSession`, `KeyInjector`, `MicCapture`); the stateless API client stays a `Sendable` struct. Keep new code Swift 6 strict-concurrency clean.
+Each was tried the other way and reverted, and they bind engine code as much as the app's. The list is deliberately not repeated here: it lives once, in [AGENTS.md's Settled decisions](../../AGENTS.md#settled-decisions--dont-reintroduce-these) table, alongside the engine conventions those rules rest on (dependency-free by rule; actors own state; the stateless API client stays a `Sendable` struct; new code Swift 6 strict-concurrency clean). `scripts/check-invariants.sh` mechanizes the subset a regex can decide and fails `check.sh` on them, so a good number are enforced rather than remembered — and it pins each rule to the table row it came from, which only works while there is one row to pin to.