Architecture Fitness Functions

Architecture Fitness Functions

A fitness function is an ordinary test that enforces an architectural rule instead of a behavior. It lives in the app's own test target, runs under every existing test gate forever, and turns "the agent said it's fine" into an exit code. This is the gauntlet's answer for invariants no unit test of behavior can see: a file quietly importing a framework it must not touch, a registry drifting from its documented size, user-facing copy breaking its format contract.

When This Skill Activates

Use this skill when:

• A project hard rule exists only in prose — CLAUDE.md constraints, file-header comments, review checklists ("deck games must run fully offline", "only the sync layer may import CloudKit")
• A code review keeps re-checking the same structural rule by hand
• An /apple:review structural finding is being graduated into permanent enforcement
• A count, boundary, or content format was broken silently once already

Why a Test, Not a Lint Rule

A per-line regex (SwiftLint custom_rules) can flag a line. A fitness function can assert a set: "the files importing MusicKit are exactly these four", "the mode registry has exactly 21 entries", "every case's copy fits the format". Sets, counts, and cross-file facts need code, and putting that code in the test target means no new tooling, no CI wiring — it rides the test gate that already exists.

The Three Patterns

Pattern 1: Import-Boundary Allowlist Scan

Enforces "only these files may import X." The test walks the shipped source tree and compares the actual importer set against an allowlist — so a fifth importer fails a test, not a code review.

Key rules (learned in production):

• Resolve the source root from #filePath, never a hardcoded path — the test stays correct wherever the repo is checked out.
• Match exact trimmed lines (line == "import X"), not contains — comments documenting the contract itself must not count as hits.
• Compare full sets, not counts — the failure message then names the drifted file.
• Exclude non-shipping directories deliberately (DEBUG-only spikes, generated code) and say why in a comment: the guarantee is about what ships.
• The allowlist is a fence, not a headcount. Widening it is a legitimate, documented decision: when a new file genuinely belongs inside the boundary, the test failing is the system working — record why in the allowlist comment, then add it.
• Add a companion API-surface scan for bypass routes the import check can't see. An import-only check misses a file calling the underlying API directly (every file already imports Foundation, which is enough to reach URLSession without importing the fenced framework). Scan for the raw API strings (URLSession(, URLSession.shared) outside the boundary too.

Template: templates/ImportBoundaryTests.swift

Pattern 2: Runtime Sentinel

Enforces "this code path never attempts X" — stronger than "happens to succeed without X." The canonical case is an offline guarantee: register a URLProtocol subclass that intercepts, counts, and fails every network request, drive the real production path, and assert the counter stayed at zero.

Key rules:

• Register the sentinel per-test and unregister in defer.
• The sentinel fails requests loudly (never lets them reach the network) — a regression fails in CI instead of silently succeeding against a live server.
• Assert interceptedRequestCount == 0: the contract is zero attempts, not zero successes.