Every long-lived codebase has a few files everyone is a little afraid of. They started reasonable, then every new feature added "just a few more lines," and now they're two thousand lines deep — the kind of file where a small change can break something three screens away, and where anyone opening it has to hold far too much in their head at once. Those files are where bugs go to hide.

NAOMS is built by an unusual number of hands — many separate working sessions, much of it agent-written — and that makes the swamp problem worse, not better. A file no single person fully holds is exactly the file that quietly grows out of control. So we don't rely on discipline to prevent it. We rely on a gate.

flowchart LR
  A["A source file grows
past 800 lines"] --> B["The build flags it"]
  B --> C["We lift a cohesive group
into its own focused module"]
  C --> D{"Check: smaller?
behavior unchanged?"}
  D -->|no| C
  D -->|yes| E["The split lands"]

The rule, and the move it forces

The rule is blunt: a source file over 800 lines is a failure the build reports, the same way it reports a broken type. There's no "we'll clean it up later," because later never comes — the gate simply won't let an overgrown file sit there unaddressed.

What the rule forces is a particular, careful move. You don't rewrite the big file — rewriting is where behavior quietly changes and new bugs sneak in. Instead you find a cohesive group inside it — a cluster of functions that already belong together — and lift it, almost verbatim, into its own focused module next door. Then a check has to pass twice over: the original file is genuinely smaller, and the behavior is unchanged. Only then does the split land. It's surgery, not demolition.

What that looks like at our scale

This has been running as a steady campaign across the whole system. The numbers are real and a little relentless: over a hundred distinct parts of NAOMS have been through it — the part that talks to other devices, the part that handles secure group messaging, the file browser, the identity layer, the planning engine. A file that was 905 lines is now 383. One at 1,034 is 539. The largest single target was a planning file that had reached 8,828 lines — a genuine swamp — now being drained a cohesive piece at a time.

And it is deliberately not finished. This isn't a one-time cleanup we'll announce as done; it's a permanent ratchet. The gate stays on. The moment a file creeps back over the line, it gets flagged again, and we split it again.

Why this is worth telling you about

It would be easy to dismiss this as housekeeping. It isn't — it's load-bearing, and it ties straight back to how we think the whole system should work.

It serves Wholeness: a system made of small, self-contained parts that each make sense on their own is a system you can actually reason about, the same instinct behind keeping a clear seam between the core and its plugins. It serves honesty: the gate proves each split preserves behavior rather than asking you to trust that it did — the same reflex as insisting on one audited path for every write. And in a system this much of which is built by agents, it's practical survival: a focused module is something a person — or a model — can hold entirely in mind, and the things you can hold entirely in mind are the things that don't surprise you later.

You will never see any of this. But the next feature lands a little safer, and the bug that never happened never happened, because the file it would have hidden in was too small to hide in.

Written by AI agents from real project logs; owned and edited by Mujo.