tylervick · Aug 8, 2026 · Aug 8, 2026 · Aug 8, 2026 · Aug 8, 2026 · Aug 8, 2026
diff --git a/.githooks/pre-commit b/.githooks/pre-commit
@@ -1,5 +1,6 @@
 #!/bin/bash
-# Runs the same checks CI runs, on staged files only.
+# Runs the same checks CI runs: shellcheck, SwiftFormat and SwiftLint over the
+# files you are committing, plus the substrate check over the tree.
 #
 # Not installed automatically — see CONTRIBUTING.md. A repository that silently
 # takes over your git config is worse than one that asks.
@@ -46,6 +47,15 @@ if [[ -n "$swift_staged" ]]; then
   fi
 fi
 
+# --- substrate -----------------------------------------------------------
+# Unconditional, unlike the sections above: this is a structural check over
+# CLAUDE.md and docs/learnings/ rather than a per-file lint, so there are no
+# staged paths to hand it, and it costs milliseconds. Checking the tree rather
+# than the staged set is the point — an unindexed learning is a problem whether
+# or not it is the file being committed.
+note "substrate"
+"$(git rev-parse --show-toplevel)/Scripts/check-substrate.sh" || fail=1
+
 if [[ $fail -ne 0 ]]; then
   printf '\n\033[31mpre-commit checks failed.\033[0m Fix the above, or commit with --no-verify.\n'
   exit 1

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -26,6 +26,12 @@ jobs:
         shellcheck --version
         find . -name '*.sh' -not -path './.build/*' -print0 | xargs -0 -r shellcheck
 
+    # Pins the regression docs/learnings/read-under-set-e-skips-its-guard.md
+    # describes: stubs `xcrun` with no iPhone simulators and asserts the
+    # script's own error message appears, not a bare `read`-failure trace.
+    - name: Test prepareTestResults.sh's simulator guard
+      run: ./Scripts/test-prepare-test-results.sh
+
   swift:
     runs-on: macos-latest
     steps:
@@ -45,3 +51,18 @@ jobs:
     # failing and then ignored.
     - name: SwiftLint
       run: swiftlint lint --reporter github-actions-logging
+
+  substrate:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        persist-credentials: false
+
+    # The guard's own test runs first. A guard nobody tests is a guard that
+    # can silently stop checking anything.
+    - name: Test the substrate guard
+      run: ./Scripts/test-check-substrate.sh
+
+    - name: Check the substrate
+      run: ./Scripts/check-substrate.sh
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,43 @@
+# XCTestHTMLReport — working rules
+
+Converts Xcode `.xcresult` bundles into HTML, JUnit and JSON reports. See
+`CONTRIBUTING.md` for build instructions and `docs/learnings/INDEX.md` for traps
+this project has already paid for.
+
+## Build & test
+
+- Fixtures first: `./prepareTestResults.sh`, then `swift test`. The script builds
+  the sample app and drives a simulator, and takes about nine minutes. It needs no
+  credentials — these two commands reproduce CI's `test` job, so a green run
+  locally means that job will be green (other CI jobs check other things).
+- Regenerate fixtures after an Xcode upgrade; `.xcresult` contents change between
+  versions.
+- Never run two `xcodebuild` test sessions against one simulator at the same time.
+
+## Invariants
+
+- The tool exits 3 when a report is degraded. Never make it exit 0 by suppressing
+  a fault; `--lenient` is the only sanctioned escape.
+- `Sources/XCTestHTMLReportCore/Classes/HTMLTemplates.swift` is generated and is
+  excluded from SwiftFormat and SwiftLint. Reformatting it moves the closing `"""`
+  delimiters, which changes the bytes of every generated report.
+- Exact per-status test counts are not assertable — the sample UI suite flakes on
+  app launch. Assert totals and relationships instead.
+- `upload-artifact` and `download-artifact` must stay compatible — the release
+  job downloads exactly what the build job uploaded. Their majors are versioned
+  independently and today read v7 and v8, so check the pairing, not the numbers.
+  The release dry run cannot catch a mismatch.
+
+## Changes
+
+- Work lands through pull requests, never directly on `main`.
+- **Never edit, weaken, delete, or skip a test to make something pass.** If the
+  work cannot be done honestly, stopping is correct.
+- Never weaken the checks that judge your work: `Scripts/check-substrate.sh` and
+  its test, `.swiftlint.yml`, `.swiftformat`, `.githooks/`, or the CI workflows.
+  Changing them is a deliberate decision made in its own pull request, never
+  something done in passing to make other work pass.
+- Hit a trap worth remembering? Add a file under `docs/learnings/` and one line to
+  its `INDEX.md`, in the same pull request.
+- A learning that can be an executable check should become one, and the learning
+  file then points at the check instead of restating it.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -48,25 +48,30 @@ swift test
 ```
 
 `prepareTestResults.sh` picks the newest available iPhone simulator automatically.
-No credentials or secrets are required — CI runs exactly these two commands, so a
-green run locally means a green run on your pull request.
+No credentials or secrets are required. These two commands reproduce CI's `test`
+job, so a green run locally means that job will be green on your pull request —
+see below for what else CI checks.
 
 Regenerate fixtures after upgrading Xcode; `.xcresult` contents change between
 Xcode versions.
 
+`docs/learnings/` collects traps this project has already paid for — one line
+each in [`docs/learnings/INDEX.md`](docs/learnings/INDEX.md). Worth a minute
+before changing CI, the linters, or the fixtures.
+
 ### Optional: run the checks before committing
 
-CI runs shellcheck, SwiftFormat, and SwiftLint. The same checks can run locally on
-staged files, so you find problems before pushing:
+CI runs shellcheck, SwiftFormat, SwiftLint, and a structural check on `CLAUDE.md`
+and `docs/learnings/`. The same checks can run locally before pushing:
 
 ```bash
 git config core.hooksPath .githooks
 ```
 
 That is opt-in on purpose — nothing installs it for you.
 
-The hook only checks files you are actually committing, and skips a tool entirely
-if it is not installed:
+The linters only look at files you are actually committing, and each is skipped
+entirely if it is not installed:
 
 ```bash
 brew install shellcheck swiftformat swiftlint

diff --git a/Scripts/check-substrate.sh b/Scripts/check-substrate.sh
@@ -0,0 +1,119 @@
+#!/bin/bash
+# Structural checks for the agent substrate's tracked files: CLAUDE.md and
+# docs/learnings/.
+#
+# These two artifacts are conventions, and conventions decay silently. An
+# unindexed learning is invisible to anyone who reads only the index; a
+# CLAUDE.md that grows without bound stops being read at all. Each failure is
+# quiet and each is cheap to catch mechanically, so it is caught mechanically.
+#
+# Every check has both an upper and a lower bound where one is meaningful. A
+# guard that only refuses too much lets the substrate be emptied instead, which
+# is the same loss arrived at from the other direction.
+#
+# Reports EVERY problem in one run rather than stopping at the first, so a
+# fix-up is one round trip.
+#
+# Deliberately offline: checks only what is in the diff under review, and needs
+# no network, no token, and no `gh`. A guard that depends on repo-wide mutable
+# state can turn unrelated pull requests red for something their author cannot
+# fix.
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+CLAUDE_MD="$ROOT/CLAUDE.md"
+LEARNINGS="$ROOT/docs/learnings"
+INDEX="$LEARNINGS/INDEX.md"
+WORKFLOWS="$ROOT/.github/workflows"
+LINE_CAP=50
+MIN_BYTES=500
+MAX_BYTES=20000
+
+status=0
+err() { echo "error: $*" >&2; status=1; }
+
+# 1. CLAUDE.md exists and stays inside all three bounds.
+#
+# The line cap alone does not bound the file. A 100 KB file on 50 very long
+# lines is under the cap and unreadable; a 0-byte file is under the cap and
+# says nothing. Bytes bound both ends, lines keep the shape scannable.
+#
+# Lines are counted with awk, not `wc -l`: `wc -l` counts newline characters,
+# so a 51-line file whose last line has no trailing newline reports 50 and
+# slips under the cap. awk's NR counts that trailing partial line.
+if [ ! -f "$CLAUDE_MD" ]; then
+    err "CLAUDE.md is missing — the always-on rules file is required substrate."
+else
+    lines="$(awk 'END { print NR }' "$CLAUDE_MD")"
+    bytes="$(wc -c < "$CLAUDE_MD" | tr -d '[:space:]')"
+    if [ "$lines" -gt "$LINE_CAP" ]; then
+        err "CLAUDE.md is $lines lines, over the ${LINE_CAP}-line cap — move detail into docs/learnings/."
+    fi
+    if [ "$bytes" -lt "$MIN_BYTES" ]; then
+        err "CLAUDE.md is $bytes bytes, under the ${MIN_BYTES}-byte floor — an emptied rules file must not pass as a small one."
+    fi
+    if [ "$bytes" -gt "$MAX_BYTES" ]; then
+        err "CLAUDE.md is $bytes bytes, over the ${MAX_BYTES}-byte ceiling — the line cap does not bound line length; move detail into docs/learnings/."
+    fi
+fi
+
+# 2. INDEX.md and the learning files are in exact bijection.
+if [ ! -f "$INDEX" ]; then
+    err "$INDEX is missing."
+else
+    learnings=0
+    while IFS= read -r f; do
+        if [ "$f" = "$INDEX" ]; then continue; fi
+        learnings=$((learnings + 1))
+        # The key is the path relative to docs/learnings/, not the basename.
+        # INDEX.md links resolve relative to INDEX.md's own directory, so a
+        # learning at ci/hidden.md is only reachable as `](ci/hidden.md)`;
+        # matching on the basename would accept `](hidden.md)`, a link that
+        # renders as a dead end, and would be ambiguous the moment two
+        # subdirectories hold the same filename.
+        rel="${f#"$LEARNINGS/"}"
+        # -c counts matching *lines*, so two links to the same file on one
+        # INDEX.md line would count as one entry and pass; -o plus a line
+        # count counts each match, however many share a line.
+        n="$(grep -oF "]($rel)" "$INDEX" | wc -l | tr -d '[:space:]' || true)"
+        if [ "$n" -ne 1 ]; then
+            err "docs/learnings/$rel has $n index entries in INDEX.md, expected exactly 1."
+        fi
+        # The walk recurses on purpose. Bounded to one level, a learning filed
+        # in a subdirectory is never seen, so it is never required to be
+        # indexed — the quietest way to add an invisible file. INDEX.md itself
+        # is skipped by exact path, not by name, so that a nested INDEX.md does
+        # not become the same hiding place.
+    done < <(find "$LEARNINGS" -type f -name '*.md' | sort)
+
+    # A bijection over the empty set holds, so the pair of loops above passes a
+    # docs/learnings/ with every learning deleted. Require at least one.
+    if [ "$learnings" -eq 0 ]; then
+        err "docs/learnings/ contains no learning files — the directory is required substrate, not an empty convention."
+    fi
+
+    while IFS= read -r target; do
+        [ -f "$LEARNINGS/$target" ] \
+            || err "INDEX.md points at missing file: $target"
+    done < <(grep -oE '\]\([^)]+\.md\)' "$INDEX" | sed -E 's/^\]\(//; s/\)$//' | sort -u)
+fi
+
+# 3. The guard is still wired into CI.
+#
+# A check nobody invokes is indistinguishable from a check that always passes,
+# and deleting the job that runs it is a quieter way to disable this script
+# than editing it. So the script asserts its own wiring.
+#
+# Offline, like the rest: it greps the workflow files, which are in the diff
+# under review, rather than asking GitHub what ran. It does not care which
+# workflow invokes the guard, so moving the job between files is fine.
+#
+# The pattern is the path and not the bare filename because a bare
+# `check-substrate.sh` also matches `test-check-substrate.sh` — a workflow that
+# ran only the guard's test, and never the guard, would otherwise look wired.
+if [ ! -d "$WORKFLOWS" ]; then
+    err ".github/workflows/ is missing — nothing can be invoking Scripts/check-substrate.sh."
+elif ! grep -rqF 'Scripts/check-substrate.sh' "$WORKFLOWS"; then
+    err "no file under .github/workflows/ invokes Scripts/check-substrate.sh — the guard is not wired into CI."
+fi
+
+exit "$status"