How rules are written

These docs are the source of truth for what Opleet v2 does (D27). A rule is written here first, then the test that proves it, then the code that passes the test.

The format

Each rule is a level-three heading that starts with its ID, followed by a short list:

### R-XX-01 · One sentence that states the rule

- **Status:** planned
- **Example:** given …, when …, then ….
- **Refusal:** the error key raised when the rule refuses an action (D10), or none
- **Who:** the roles the rule applies to
- **Source:** the decision, spec or v1 behaviour it comes from

• One rule, one testable statement. If the sentence needs "and", it is two rules.
• IDs are R, a domain code and a two-digit number, such as R-BC-03. The Docs Engineer keeps the list of domain codes. An ID is never reused.
• Status is planned (written, not yet built), built (a test proves it and the code passes that test) or retired (no longer true, kept so its ID is not reused).

Who changes what

• The Docs Engineer writes and edits rules, through pull requests that zuki reviews.
• The Backend and Frontend Engineers change one thing in a rule: its Status, from planned to built, in the pull request that adds its test and its code.
• A rule that turns out wrong or impossible goes back to the Docs Engineer as a docs pull request, or to the register as a change request when it conflicts with a decision. It is never changed quietly to fit the code.

How tests cite rules

Every test starts its description with the ID of the rule it proves:

• pgTAP, in supabase/tests: the last argument of the assertion, for example 'R-BC-03: a second approval is refused'.
• Playwright, in apps/web/e2e: the test title, for example test('R-BC-03: a second approval is refused', …).

The check

pnpm docs:rules runs in CI on every pull request. It reads every .md and .mdx page here, skipping code blocks, and every test in supabase/tests and apps/web/e2e. It fails when:

• an ID is defined twice;
• a rule has no Status line;
• a built rule has no test that cites it;
• a test cites an ID that no rule defines;
• a test cites a retired rule.

Pages under reference/ are generated from the database and are never edited by hand.