Where the Rules Live: Specs
Rumoca keeps one source of truth per rule: the specs in
spec/.
AGENTS.md is a
thin routing index from “what you are touching” to “which spec to read” —
it contains no rules itself, and neither does this book.
The Map
| If you are touching… | Read |
|---|---|
| Compiler pipeline / any IR / any phase | SPEC_0007 |
| Crate dependencies, foundation types, re-exports | SPEC_0029 |
| Modelica semantics (anything MLS-affecting) | SPEC_0022 |
Name lookup, scopes, DefId | SPEC_0001, SPEC_0002 |
| Diagnostics, spans, error codes, tracing | SPEC_0008 |
Tool config (rumoca-tool-*, env-var policy) | SPEC_0018 |
| Function length, nesting, file size, determinism | SPEC_0021 |
| Opening a PR | SPEC_0025 |
| Scope/philosophy questions (“should this live in the compiler?”) | SPEC_0031 |
Start at
spec/README.md
for the full index with statuses;
SPEC_0000
explains how specs themselves work.
Working With Specs
- Active specs (
ACCEPTED/REFERENCE) are mandatory; archived ones are history. - If a change you want violates a spec, propose the spec change first — architecture tests enforce important boundaries, and bypassing a test is never the move.
- If you cannot find the spec for what you are about to change, stop and ask: the rule either exists somewhere you have not looked, or it needs to be written before the code.
- Do not duplicate spec content into other documents (including this one); one source of truth per rule is what keeps the spec set trustworthy.
House Norms Worth Knowing Early
These recur in review and each traces to a spec:
- Prefer the correct long-term fix over a short-term hack; fix root causes in the owning phase rather than weakening checks downstream.
- No
clippyallowattributes; address the lint. - No behavior-changing
RUMOCA_*environment variables — knobs are documented CLI flags or config keys. - Debugging is
tracing-based, noteprintln!behind env vars. - Deterministic collections and complexity limits per SPEC_0021.