khosra/.claude/commands/invariants.md

description

description
Check the architecture invariants against the code, not against the docs

verify.sh checks what a grep can check. This pass checks the nine invariants in docs/architecture.md, which need reading the code. Run at arc boundaries, before a freeze, and before the first deploy.

For each invariant, answer held / violated / not yet applicable, with a file and line when violated. Do not fix anything in this pass.

1. Open page object — are all fields optional in practice? Find any place a missing field causes a nil deref, an error return, or a template failure that reaches the response.
2. Trusted / untrusted modes — trace every path by which non-repo bytes could reach shortcode or template evaluation. This is the one invariant where "probably fine" is not an answer: name the check that stops it, or report it violated.
3. Identity is not language — is the bundle key free of language? Any place a language suffix leaks into a cache key, a URL, or a dependency key is a violation.
4. Request-time render behind a cache — does export walk the same code path as the server, or has a second path appeared?
5. Permalinks permanent — does any code derive a URL by a rule other than the one in content-model.md? Does every rename path emit an alias plus a permanent redirect?
6. Interactions off the content graph — can an interaction invalidate more than its own fragment?
7. Every feature is a leaf — is each internal/ext/* package deletable without touching the core? Try naming the diff that removes one.
8. Degrades with external services off — for each external client, is there a path that still serves correctly, slowly, when it is unreachable?
9. Core stops growing after Arc 2 — compare the core figure verify.sh prints against the one recorded at the freeze in state.md. Post-freeze growth is the finding, not the number.

Then: report held/violated per invariant, and for anything violated, whether it is a bug to fix now or a latent item with a trigger. A violated invariant is a stop condition (CLAUDE.md §6) — say so plainly rather than documenting it as the new normal.