{"row":{"id":"ADR-023","title":"File modularity discipline: 800 LOC warn / 1500 fail / 3000 fail-with-LOC-EXEMPT-allowlist","file":"adr-023-file-modularity-discipline.md","status":"accepted","date":"2026-04-16","cites":6,"supersedes":[],"superseded_by":[],"layers":["L0","L0.5","L1","L2","L3","L4","L5"],"tags":["hygiene","file-loc","modularity","discipline"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-023: File modularity discipline","id":"adr-023-file-modularity-discipline"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"Current rule: max 1500 LOC per file (hard cap). 4-agent audit (2026-04-16)\nrevealed:"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Current P90 ≈ 600 LOC (well under cap)"}],[{"k":"text","text":"nika-catalog/build.rs at 1386 LOC and data/models.rs at 1248 LOC are\nuncomfortably close"}],[{"k":"text","text":"rust-analyzer P90 = 900 LOC, helix P90 = 700 LOC, oxc P90 = 500 LOC"}],[{"k":"text","text":"Mature workspaces routinely ship 2k+ LOC files (codegen output, generated\nlookup tables)"}]]},{"k":"p","inline":[{"k":"text","text":"Two opposing views:"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Agent 1 (rust-architect): tighten to 800/1200 — match SOTA Rust P90"}],[{"k":"text","text":"Agent 2 (web-researcher SOTA): NO workspace enforces hard limits — relax to\n1500/3000"}]]},{"k":"p","inline":[{"k":"text","text":"Both have merit. Cap discipline matters; codegen reality matters."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"strong","text":"Three-tier file LOC policy:"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Threshold · Action · Mode"}],[{"k":"text","text":"**800 LOC** · warning · hygiene vector 27 emits YELLOW"}],[{"k":"text","text":"**1500 LOC** · hard fail · hygiene vector 27 fails RED — cannot commit"}],[{"k":"text","text":"**3000 LOC** · absolute hard fail with allow-list exemption only · hygiene vector 27 fails CRITICAL — exempt ONLY via per-file marker"}]]},{"k":"p","inline":[{"k":"strong","text":"`// LOC-EXEMPT: <reason> [<owner>]` marker"},{"k":"text","text":" at top of file allows bypassing\nthe 1500 cap up to 3000 LOC. Reasons must be one of:"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"codegen"},{"k":"text","text":" — auto-generated by build.rs / proc-macro"}],[{"k":"code","text":"lookup-table"},{"k":"text","text":" — large compile-time static data table"}],[{"k":"code","text":"enum-mega"},{"k":"text","text":" — single mega-enum (e.g., 200+ variants of EventKind aggregator)"}]]},{"k":"p","inline":[{"k":"strong","text":"Per-function cap"},{"k":"text","text":": 100 LOC soft warn ("},{"k":"code","text":"clippy::too_many_lines = \"warn\""},{"k":"text","text":").\nCurrently unenforced — enable in workspace lints."}]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"✅ 800 warn discipline keeps cohesion tight (we're already there at P90 ~600)"}],[{"k":"text","text":"✅ 1500 fail catches genuine sprawl"}],[{"k":"text","text":"✅ 3000-with-exemption preserves codegen reality"}],[{"k":"text","text":"✅ Marker enforces conscious decision (not silent growth)"}],[{"k":"text","text":"❌ +1 hygiene vector (27) — implementation cost ~1h"}],[{"k":"text","text":"❌ One-time refactor of catalog/build.rs (1386) + data/models.rs (1248) to\nhonor 800 warn — handled in Phase B'"}]]},{"k":"h","depth":2,"text":"Implementation","id":"implementation"},{"k":"code","lang":"bash","text":"# scripts/hygiene/check-file-loc.sh (vector 27)\n#  - For each .rs file in crates/*/src/ and crates/*/build.rs:\n#    - count LOC\n#    - if > 3000:\n#        check for // LOC-EXEMPT: marker; fail if absent\n#    - elif > 1500:\n#        fail (no exemption above 1500 except via 3000 path)\n#    - elif > 800:\n#        warn (yellow)"},{"k":"p","inline":[{"k":"text","text":"Workspace "},{"k":"code","text":"Cargo.toml"},{"k":"text","text":" lint section:"}]},{"k":"code","lang":"toml","text":"[workspace.lints.clippy]\ntoo_many_lines = { level = \"warn\", priority = -1 }"},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Relax to 1500/3000"},{"k":"text","text":" (Agent 2's pure recommendation) — loses discipline"}],[{"k":"strong","text":"Tighten to 800/1200"},{"k":"text","text":" (Agent 1's pure recommendation) — fails under codegen"}],[{"k":"strong","text":"Per-crate cap"},{"k":"text","text":" instead of per-file — moves the problem one level up"}],[{"k":"strong","text":"Hard 1500 with no exemptions"},{"k":"text","text":" — current rule, breaks under generated code"}]]}]

ADR-023

File modularity discipline: 800 LOC warn / 1500 fail / 3000 fail-with-LOC-EXEMPT-allowlist

accepted · 2026-04-16 · L0 L0.5 L1 L2 L3 L4 L5 · cites 6

ADR-023: File modularity discipline #

Context #

Current rule: max 1500 LOC per file (hard cap). 4-agent audit (2026-04-16) revealed:

Current P90 ≈ 600 LOC (well under cap)
nika-catalog/build.rs at 1386 LOC and data/models.rs at 1248 LOC are uncomfortably close
rust-analyzer P90 = 900 LOC, helix P90 = 700 LOC, oxc P90 = 500 LOC
Mature workspaces routinely ship 2k+ LOC files (codegen output, generated lookup tables)

Two opposing views:

Agent 1 (rust-architect): tighten to 800/1200 — match SOTA Rust P90
Agent 2 (web-researcher SOTA): NO workspace enforces hard limits — relax to 1500/3000

Both have merit. Cap discipline matters; codegen reality matters.

Decision #

Three-tier file LOC policy:

Threshold · Action · Mode
**800 LOC** · warning · hygiene vector 27 emits YELLOW
**1500 LOC** · hard fail · hygiene vector 27 fails RED — cannot commit
**3000 LOC** · absolute hard fail with allow-list exemption only · hygiene vector 27 fails CRITICAL — exempt ONLY via per-file marker

`// LOC-EXEMPT: <reason> [<owner>]` marker at top of file allows bypassing the 1500 cap up to 3000 LOC. Reasons must be one of:

codegen — auto-generated by build.rs / proc-macro
lookup-table — large compile-time static data table
enum-mega — single mega-enum (e.g., 200+ variants of EventKind aggregator)

Per-function cap: 100 LOC soft warn (clippy::too_many_lines = "warn"). Currently unenforced — enable in workspace lints.

Consequences #

✅ 800 warn discipline keeps cohesion tight (we're already there at P90 ~600)
✅ 1500 fail catches genuine sprawl
✅ 3000-with-exemption preserves codegen reality
✅ Marker enforces conscious decision (not silent growth)
❌ +1 hygiene vector (27) — implementation cost ~1h
❌ One-time refactor of catalog/build.rs (1386) + data/models.rs (1248) to honor 800 warn — handled in Phase B'

Implementation #

bash

1# scripts/hygiene/check-file-loc.sh (vector 27)2#  - For each .rs file in crates/*/src/ and crates/*/build.rs:3#    - count LOC4#    - if > 3000:5#        check for // LOC-EXEMPT: marker; fail if absent6#    - elif > 1500:7#        fail (no exemption above 1500 except via 3000 path)8#    - elif > 800:9#        warn (yellow)

Workspace Cargo.toml lint section:

toml

1[workspace.lints.clippy]2too_many_lines = { level = "warn", priority = -1 }

Alternatives considered #

Relax to 1500/3000 (Agent 2's pure recommendation) — loses discipline
Tighten to 800/1200 (Agent 1's pure recommendation) — fails under codegen
Per-crate cap instead of per-file — moves the problem one level up
Hard 1500 with no exemptions — current rule, breaks under generated code

read at v0.107.0 · the decision record ships with the engine

Every decision, with its status This one in the repo