Four tasks: the guard and its hermetic test first, then CLAUDE.md, then
docs/learnings/ seeded from the 3.0 work, then CI wiring. The guard comes
first so the artifacts it governs are validated as they are written.

Scoped to the substrate alone. It is useful for supervised agent work
immediately and does not depend on doom-ios-2026 PR #58 landing, unlike
the loop protocol.

Two steps deliberately prove a check can fail rather than only that it
passes: Task 3 Step 4 confirms the hermetic test still passes once a real
substrate exists, and Task 4 Step 3 removes an indexed learning to confirm
the CI job actually goes red.

NOTE: committed unsigned because the 1Password SSH agent was locked.
Re-sign before pushing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

CLAUDE.md and docs/learnings/ are conventions, and conventions decay
silently: an unindexed learning is invisible to anyone reading only the
index, and a CLAUDE.md that grows without bound stops being read.

Ported from doom-ios-2026 and copied rather than shared, since the two
repositories' rules and traps will diverge. Deliberately offline, so it
cannot turn an unrelated pull request red for repo-wide state its author
cannot change.

The guard has its own hermetic test, which builds a fake repo in a temp
dir and never touches the real substrate.

Case 5 (duplicate on separate lines) would pass with either grep -c or
grep -oF, so it doesn't test the implementation choice. Case 5b adds the
scenario the guard's grep -oF exists for: two links to the same file on
ONE line. grep -c would count that as one matching line and wrongly pass.

This test ensures the bijection check correctly counts each occurrence,
not each matching line.

The always-on rules any agent working in this repository is bound by:
how to build and test, the invariants that are easy to break silently,
and the guardrail files that must never be modified by the thing they
judge.

Capped at 50 lines by Scripts/check-substrate.sh so it keeps being read;
detail belongs in docs/learnings/

Six traps that each cost real time during the 3.0 release, written as
traps with their evidence rather than as narrative: runner images
dropping Xcode versions, SwiftLint reading .build when unscoped,
HTMLTemplates.swift being generated, the sample UI suite's launch flake,
the release job being unreachable by the dry run, and read under set -e
skipping its own guard.

Where a check already enforces the lesson, the file points at the check
rather than restating it.

swiftlint-lints-dependencies-unscoped.md claimed the scoped run reports
"65 and 24". It reports 26 warnings and 0 errors. The 65/24 figure was an
interim measurement taken before two violations were fixed and the config
was finalised, so it never described the shipped state — in a file whose
closing line tells the reader to run that very command.

Also adds SwiftFormat to the list of dependencies producing the unscoped
noise, and corrects release-job-is-unreachable-by-dry-run.md, which said
the artifact-version mismatch "bit once already". It was caught inside
PR #404 before merge — a near-miss, not a realised incident.

Runs the guard's own test before the guard itself — a guard nobody tests
is one that can silently stop checking anything, which is the same
failure mode it exists to prevent.

Verified the job can actually go red by removing an indexed learning and
confirming a non-zero exit, not just that it passes today.

CLAUDE.md forbade modifying anything under .github/workflows/ outright,
which the same plan's CI-wiring task does. The rule was lifted from a
sibling repository's loop protocol, where it binds unattended runs
specifically, not from its CLAUDE.md, which carries no such rule.

Rewritten to forbid weakening the checks that judge the work, while
allowing deliberate changes made in their own pull request. Also drops
CLAUDE.md from the list, since a file cannot coherently forbid its own
editing while asking agents to keep it current.

docs/superpowers/ held the spec and plan that produced this branch. They are
stale against the code in the same commit range in several places — including a
figure this branch corrected and a guardrail rule this branch narrowed — so an
agent replaying the plan would reintroduce both. Nothing in the tree references
them.

The working rules that survive are in CLAUDE.md and docs/learnings/, which are
guarded by Scripts/check-substrate.sh. The design documents are not, and an
unguarded document that contradicts the code is worse than no document.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The file claimed a bare `swiftlint lint` reports 7,285 warnings and 2,570
errors. Reconstructing the condition — the tree at this commit, the same
Package.resolved, `.swiftlint.yml` removed, `swift package resolve`, then
`swiftlint lint` — measures 12,577 violations, 3,192 serious across 1,031
files. Neither claimed number reproduces.

The exact count moves with dependency and SwiftLint versions, so pinning a new
one just schedules the next correction. The lesson is the magnitude: a count in
the thousands means the tool is reading `.build`, and 12,484 of those 12,577 are
from `.build/checkouts`. The file closes by telling the reader to run the
command, so a headline number they cannot reproduce teaches distrust of the
whole directory.

The scoped half — 26 warnings and 0 errors with the committed config — was
re-run and still holds.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The guard enforced an upper bound and a bijection, and neither is enough. Six
ways to leave it green were demonstrated against the real tree: a 100 KB
CLAUDE.md on 50 lines, 51 lines with the trailing newline deleted, a learning
filed in a subdirectory, every learning deleted, CLAUDE.md truncated to zero
bytes, and the CI job that runs the guard deleted.

Each is quiet, and each is the shape of failure this script exists to catch —
the substrate decaying without anyone noticing.

CLAUDE.md now has bounds on both ends. Bytes bound size (500..20000; the file
is 2061), lines keep the shape scannable, and lines are counted with awk's NR
rather than `wc -l` because `wc -l` counts newline characters and reports 50
for a 51-line file that lacks a trailing one.

The learnings walk recurses, so a subdirectory is no longer a hiding place. The
bijection key is therefore the path relative to docs/learnings/ rather than the
basename: INDEX.md links resolve relative to its own directory, so ci/hidden.md
is reachable only as `](ci/hidden.md)`. A basename key would accept a link that
renders as a dead end, and would be ambiguous once two subdirectories held the
same filename. Top-level learnings are unaffected — their relative path is their
basename. A floor of one learning file closes the emptied-directory case, which
a bijection cannot: it holds over the empty set.

The guard asserts its own wiring by grepping .github/workflows/ for an
invocation. A check nobody runs is indistinguishable from a check that always
passes, and deleting the job is quieter than editing the script. It matches the
path and not the bare filename, because `check-substrate.sh` is a substring of
`test-check-substrate.sh` — a workflow running only the test would otherwise
look wired. It stays offline like the rest of the script, and survives the job
moving to a different workflow file.

Every new check has a case that makes it fail, plus two positive cases pinning
the relative-path key and the move-the-job-anywhere behaviour. The suite counts
its own cases now, 9 to 18, so the closing line cannot go stale.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Four statements that a reader can check and find wrong.

The pre-commit hook said it "runs the same checks CI runs" while CI had grown a
fourth. Adding Scripts/check-substrate.sh to the hook is the better repair: it
costs milliseconds, takes no staged-path argument, and catches an unindexed
learning at commit time instead of on the pull request. It runs unconditionally
because it is a structural check over the tree, not a per-file lint — which also
means a docs-only commit, the exact commit that adds a learning, is now checked
rather than skipped. CONTRIBUTING's neighbouring sentence about the hook only
looking at staged files is narrowed to the linters, which is what it describes.

CONTRIBUTING listed the CI checks as three.

Neither README nor CONTRIBUTING mentioned docs/learnings/, so the traps were
reachable only by agents that auto-load CLAUDE.md. CONTRIBUTING's build section
now points at the index, where a human looking at CI or fixtures will pass it.

CLAUDE.md called upload-artifact and download-artifact "a matched pair" that
"must move together". They are independently versioned actions and the tree
reads v7 and v8, so a reader checking for equal numbers concludes the invariant
is already violated and learns to discount the list. The requirement is that the
release job can read what the build job wrote; the wording now says that.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

CLAUDE.md and CONTRIBUTING.md both said CI runs "exactly these two
commands" (prepareTestResults.sh, swift test). That stopped being true
once the substrate and lint jobs landed — CI now runs four required
checks plus shellcheck/SwiftFormat/SwiftLint. Reword both to say what is
actually true: the two commands reproduce CI's `test` job locally.