Rules Catalog

Canonical source: rules/README.md — this page is rendered from it on every publish; edit the source.

ClawAI Rules Catalog

This directory is the authoritative constraint catalog for every contribution to the ClawAI monorepo — human or AI. It is part of the AI-native engineering operating system: rules here are written to be read by agents (Claude, Codex, Cursor, any other) as well as people, and most are backed by an automated enforcement mechanism so that "the rule" and "the check" never drift apart.

Do not skim. Read 00-non-negotiable-rules.md before touching any code, then the numbered file(s) for your task domain.

Authority hierarchy (higher wins on conflict)

When two documents disagree, the higher tier is correct and the lower one is a bug to be fixed. Resolve up, never down.

1. CLAUDE.md (repo root) — the master project reference and agent operating manual.
2. rules/00-non-negotiable-rules.md — the hard blockers.
3. context/architecture-map.md — the canonical service/route/event map.
4. context/stack-and-toolchain.md — the canonical toolchain contract.
5. Numbered rules/*.md (this catalog, 01–40).
6. skills/*.md — operational runbooks (how-to; rules are the what/why).
7. context/* + memory/* — supporting context and durable agent memory.
8. .ai/ manifests (.ai/manifests/*.json, .ai/BOOTSTRAP.md, .ai/packs/*.md) — machine-readable derived facts.
9. Compact AI routers (CODEX.md, cursor.md and other per-tool entrypoints) — mirrors, never originals.

The legacy rules/00-master-rules.md … 09-refactor-rules.md set remains valid and is not superseded; this numbered 00-40 catalog is the finer-grained, enforcement-tagged expansion that lives alongside it. The full one-line index of every numbered file lives in 00-master-rules.md.

Money and entitlement rules

Two rules govern the paths that move money, and they compose rather than overlap:

Rule	Governs
28-billing-integrity-and-api-contracts.md	Charging for something already delivered: prices, invoices, refunds, subscription entitlement, quota windows
37-payg-credit-integrity.md	Spending a customer's money before they see a result: PAYG reservation, the affordability clamp, the credit ledger, top-ups

Verification and QA rules

Two rules govern proving a change works, and they compose rather than overlap:

Rule	Governs
44-live-verification-before-done.md	Whether the change was seen running at all: the API lane, the browser lane, and the stale-container traps that fake a pass
49-qa-team-discipline-and-test-evidence.md	Who you must be while verifying and what you must produce: every QA hat, the device matrix, and evidence for every claim

Abuse limits on public auth routes

Rule	Governs
58-auth-route-rate-limits.md	Per-route budgets on sign-in / sign-up (auth-service + agent-service), hashed keys, fail-open, nginx zone

Rule file format

Every numbered file uses the same sections, in this order:

• Purpose — the one-paragraph reason the rule exists.
• Applies to — which workspaces / file globs / layers it governs.
• Mandatory rules — numbered MUSTs.
• Prohibited patterns — the specific anti-patterns that fail review.
• Correct pattern — a short, ClawAI-grounded path or code example.
• Enforcement — the mechanism that catches a violation (see below).
• Related skills — pointers into skills/.
• Related context — pointers into CLAUDE.md, docs/, .ai/.
• Definition of done — the checklist for "this rule is satisfied."

Enforcement mechanisms

Each rule declares how it is enforced. A rule with no automatable check says so explicitly and falls back to review. The mechanism vocabulary:

Mechanism	What it means
ESLint	Flat-config rule (eslint.config.*), often no-restricted-syntax.
TS config	tsconfig strictness / TypeScript 7 typecheck (npm run typecheck).
Unit test	Vitest assertion (every workspace).
Architecture test	A test that asserts structure (layering, boundaries, no cross-DB import).
Knowledge check	npm run knowledge:check / knowledge:verify against .ai/manifests/.
CI job	A .github/workflows/ci.yml job (lint / typecheck / test / build).
Git hook	Pre-commit / pre-push hook (the per-folder gate).
Review checklist	Human/agent review — used only when no automated check is feasible.

Enforcement points to a real gate. npm run release:preflight runs the full gate set; the per-touched-folder gate (npm run affected:*) is the routine bar before every commit.

Exceptions and waivers

Rules are strict but not infinite. When a rule genuinely cannot be met, follow the documented waiver process in 25-exceptions-and-waivers.md. No silent bypasses: an undocumented eslint-disable, @ts-expect-error, or --no-verify is a defect, not a waiver. | 59-chat-surfaces-are-one-pipeline.md | Compare/Consensus/Escalation/labs/judge are surfaces over normal chat: shared gateways, thread resolver, DTO fragments and composer spread; unavailable Judge output is never verified; guard spec | | 60-qa-evidence-is-mandatory-and-machine-checked.md | STRICT: fifteen QA lanes (unit, manual API, manual browser, e2e, RBAC+plans, device matrix, UAT, product, business, regression, security, perf, i18n, docs) recorded per batch in docs/qa-evidence and checked by CI | | 61-threads-account-deletion.md | Auth outbox, typed deletion event, idempotent service consumers, hashed tombstones, anonymous public retention, and private artifact erasure | | 62-portal-shell-must-never-scroll-as-a-document.md | PortalShell stays relative h-dvh overflow-clip; absolute/sr-only content must not stretch the document; responsive audit checks scrollHeight and scrollWidth | | 63-docs-move-with-code.md | NON-NEGOTIABLE: every doc that describes a change is accurate in the same commit; Docs: trailer on every commit; docs:impact, docs:refs, counts and duplication checks in the hooks and CI (ADR-170) | | 64-subagent-model-selection.md | NON-NEGOTIABLE: Haiku 5.5 for read-only audit/context subagents; main model for code and QA (Playwright, manual, API, automation); gate ladder Haiku 5.5 → Sonnet 5.5 → high effort → Opus 5.5 low/medium → ask the owner; never Fable-class or xhigh/max as subagents. | | 65-akinator-runs-on-every-change.md | NON-NEGOTIABLE: the full Akinator pass (ask, resolve, audit, plan, implement, document, skillify, rule, contextify, memoize, index+sync, verify) runs on every change, every agent, every tool, with no command; the in-repo skills/akinator is the source (ADR-207) | | 66-every-flagship-feature-ships-a-public-marketing-page.md | NON-NEGOTIABLE: a new flagship/core/big feature or product introduction ships, in the same change, an indexable public marketing page: registries, footer, sitemap, llms.txt, video, real screenshots, 13 locales, RTL, Lighthouse, QA checklist (ADR-208) |