Discover and confirm this repository's invariants

scope-gate can only block what it knows about. This skill produces the thing it reads: a short list of boundaries this repository must not cross, each one confirmed by a human in language they actually understand.

Run once per repository. Re-run when a confirmed invariant turns out to be wrong.

What you are looking for

An invariant is a rule that holds across the codebase and whose violation is a release blocker rather than a bug — usually one of:

You are not looking for style rules, naming conventions, or anything a linter already enforces. If a linter can catch it, it is not an invariant.

Step 1 — Look for invariants that already exist

Most mature repositories already wrote these down. Ingest that corpus; do not start a competing list. Check, in order:

• harness/guides/rules/, docs/adr/, docs/architecture/
• .cursor/rules/, .github/CONTRIBUTING.md
• AGENTS.md, CLAUDE.md, and anything they link to
• README files next to auth, credential, or policy modules

For each rule found, extract the assertion and record the file as its owner. The rule file stays the single source of truth — your index points at it.

Then do the thing the corpus cannot do for itself: rewrite each trigger in terms of EFFECT, not vocabulary. This is the failure this skill exists to prevent. A rule triggered on "a change to an HTTP route" will not fire when someone adds a dropdown option that reaches the same capability, even though the rule's reasoning applies exactly. Ask of each rule: what has to become true of the world for this to matter? Write that down instead.

• ✗ Trigger: modifies convex/http.ts or an MCP tool definition
• ✓ Applies when: a user can newly reach a capability they could not reach before — a new menu option, a provider card, a catalog row, or a route

Step 2 — Derive candidates from the code

For a repository with no written rules, read the code at its decision points. These are where an invariant is being asserted implicitly:

• Fallback chains — tenantKey ?? env.PLATFORM_KEY, ?? DEFAULT_*. Every fallback encodes a policy about who pays and what happens when configuration is absent.
• Authorization before a secret or a record is returned — what is compared, and what is merely assumed?
• Allowlists and registries — PROHIBITED_*, SUPPORTED_*, exhaustive Record<Union, …> maps. Their existence means "adding one thing means adding it here too."
• Gating in the UI — configured ? enable : lock. Whether a user can pick something they cannot use.
• catch blocks around security or policy checks — do they proceed or stop?
• Anything written twice — two copies of the same list in different packages is an invariant nobody has named yet.

Read enough call sites to state the rule and to know whether the code is consistent with itself. Inconsistency is worth surfacing: it usually means the invariant was never decided.

Step 3 — Present each candidate as a choice, in plain language

This is the part that determines whether the skill is useful. The person confirming may not read code and may not know the architecture. They can still decide the policy — but only if you ask them a policy question.

Never show them an expression. Show them the decision.

• ✗ setting.key() == BYOKey ? SYSTEM_DEFAULT_KEY
• ✓ "When a workspace has not added its own key, should we fall back to the platform's?"

Use this shape, one candidate at a time:

【<short name>】

What I found:
  <one or two sentences, no identifiers, describing the behaviour as a user
   would experience or pay for it>

  <file:line>   <what that site does, in five words>
  <file:line>   <…>

Is that intended?
  A. Yes — <state the resulting rule in one sentence>
  B. No  — <state the opposite rule in one sentence>
  C. It depends — tell me the rule and I will write it down

Rules for writing the options:

• Both A and B must be defensible. If one option is obviously absurd, you have written a leading question and learned nothing.
• State consequences the person can feel — who gets billed, who can see what, what breaks — not mechanisms.
• If the code is inconsistent across sites, say so plainly and ask which behaviour is the intended one. That is the most valuable question you can ask.
• Ask about no more than ~7 candidates in one pass. Rank by blast radius: money, cross-tenant access, and safety-critical paths first. Park the rest.

Ask them one group at a time and wait. Do not batch twenty questions.

Step 4 — Write the index

Write to .claude/scope-gate/invariants.md (create the directory, and commit it — it is a team artefact, not a local cache). Keep it short — this file is loaded on every gate run.

# Invariants — <repo name>
<!-- Written by scope-gate-setup. Confirmed by <name> on <date>. -->
<!-- Re-run /scope-gate-setup to revise. -->

## <short name>
- **Rule:** <one sentence, plain language, as confirmed>
- **Applies when:** <effect-based trigger — what must become true of the world>
- **Why it blocks:** <the consequence if crossed, in one line>
- **Owner doc:** <path to the canonical rule, or "confirmed here — no doc yet">
- **Seen at:** <file:line>, <file:line>

Then:

• If the repository keeps a rules corpus, offer to write the confirmed-here invariants into it in that corpus's own format, so the knowledge is reviewable by the people who own the codebase rather than living only in this index.
• Report what you deliberately parked, so the gaps are visible rather than implied.

What good looks like

An index of 5–12 invariants, each of which a new engineer could read in ten seconds and each of which would have blocked a real past incident. If an entry cannot be traced to something that has actually gone wrong — here or in a comparable system — it is probably a preference, not an invariant.