Security invariants registry
The big picture: .claude/security-invariants.md is a registry of security rules
that have to hold on every surface that can reach them — REST, WebSocket, a
background job, an import path, an MCP server — not just the one surface a given
diff touches. architect, rbac-check, security-review, and threat-model all
read it.
Why it matters: A code reviewer, human or agent, only sees the diff in front of them. A fix to a permission check on REST that doesn’t also fix the same check on WebSocket is a complete fix of the diff and an incomplete fix of the rule — and nothing points the reviewer at the surface they aren’t looking at. The registry is where that second surface gets written down, once, so every future review of a touched rule walks the whole row instead of re-discovering it.
How it works
Section titled “How it works”- Each rule is a
##section: a plain-language statement of what must hold, why, and a table of every surface that must enforce it — with the file and function where that surface’s enforcement lives today. - A reviewer (agent or human) who touches a listed rule checks every row in that rule’s table, not only the surface in the diff, and reports a surface that falls behind as a finding — the same severity as any other finding in that review.
threat-modelruns before code exists. It uses the registry the other direction: when a new feature’s design introduces a boundary, grant mechanism, or revocation path the registry doesn’t cover yet, it proposes a new row forarchitectto confirm before implementation starts.
It ships empty, on purpose
Section titled “It ships empty, on purpose”Blueprint has no application code, so the registry ships with two worked
examples — a deactivation rule and a single-use-token rule — clearly marked
[EXAMPLE], showing the table shape without claiming to describe your code. A
third, under “How to add a rule”, walks through writing a grant-parity rule
(every path that grants a role holds the same cap) at the moment a fix caps one
grant path, so the fix leaves a rule behind instead of closing one instance. Add
your project’s real rules as you find cross-surface behavior worth protecting; “How
to add a rule” at the bottom of the file walks through it. An empty or
examples-only registry is a normal, temporary state. The failure mode this file
guards against isn’t an empty registry — it’s an example row nobody replaced, read
later as if it described real enforcement.
What it is not
Section titled “What it is not”It is not a place to track known gaps — “surface X doesn’t enforce this yet” is an
issue, not a row annotation; the registry records what’s true today. It is also not
a substitute for rbac-check or security-review’s normal per-diff review — it’s
the piece those reviews were missing: the sibling surfaces a single diff can’t show
them.