#854 EPIC: 50 source files exceed the 550-line hard cap - split without module shadowing
Description
EditEARS SPEC (program-level):
- Every source file in the Highway stack shall be at most 500 lines (soft) and shall NEVER exceed 550 lines (hard cap).
- When a file is split, the module path callers already import shall keep working unchanged.
- The split shall NEVER produce module shadowing: a package and a module of the same name shall not coexist on the same path (e.g. workflows.py alongside workflows/), because the import that resolves is then ambiguous and silently version-dependent.
- After every split, the API route table, the tool registry and the CLI command tree shall be byte-identical to the pre-split baseline.
SCOPE: 50 source files exceed the 550-line hard cap. Tests, generated models and SQL dumps are
excluded per the rule (not code). Full inventory and per-file tickets are children of this epic.
REGRESSION ORACLES captured BEFORE any change (2026-08-22), to be re-checked after each split:
routes: 283 (rule + endpoint + methods, from api.app.create_app().url_map)
tools: 126 (enterprise.tools.registry.get_tool_registry().list_tools())
cli: 50 (enterprise.cli.hwe.cli command tree)
A split that changes any of these three counts, or any entry within them, is a regression.
ANTI-SHADOWING RULE (explicit, this is the trap):
Do NOT create `foo/` next to an existing `foo.py`. Either
(a) keep `foo.py` as the public surface and extract into SIBLING modules with DISTINCT names
(foo_queries.py, foo_handlers.py), which foo.py imports; or
(b) convert `foo.py` INTO `foo/__init__.py` + submodules and DELETE `foo.py`.
Never both. Option (a) is preferred for Quart blueprint files, because route registration order
and the `v1_bp` decorator surface stay obvious.
NOTE ON MEASUREMENT: the inventory uses raw `wc -l` (includes blanks, comments, docstrings).
If the cap is intended against logical LOC the list shrinks; confirm before mass-refactoring.
Comments
Loading comments...
Context
Loading context...
Audit History
View AllLoading audit history...