ADR-0006: Tiered module-size policy + enforced quality stack¶

Status¶

Accepted, implemented in EPIC #2046 PR 1 (issue #2047).

Context¶

SynthOrg is 100% AI-written and AI-maintained. The convention-gate culture is strong: 51 custom check_*.py gates plus 21 check_*.sh PreToolUse hooks, a meta-gate enforcing MANDATORY-to-gate parity, and a manifest-driven ghost-wiring tracker for 118 components. Yet architecture-level smells escape every existing gate:

• 54 files >800 lines in src/synthorg/. The <800 line in CLAUDE.md was a guideline, not a gate. api/state.py (2313), api/app.py (2152), api/controllers/providers.py (1530), meta/mcp/handlers/infrastructure.py (1345).
• God-modules at the centre keep growing even when periphery features stay clean. PR #2045 (charter feature, just merged) added +113 LOC to api/app.py, +16 to core/enums.py, +12 to events/persistence.py, +2 to api/state.py. Every new charter file stayed under ~570 LOC: clean periphery, growing god-modules at the centre.
• Junk drawers: core/enums.py (57 unrelated StrEnums across 8 domains), observability/events/persistence.py (895 LOC of cross-sub-domain event constants).
• Ruff thresholds default: max-complexity implicit; max-statements, max-branches, max-public-methods not set. File-level fan-in / cohesion / god-objects invisible to ruff.
• No declarative import-layering beyond three custom gates that partially cover.

This ADR records the tiered module-size policy and the enforced quality stack landing alongside it.

Decision¶

Tiered module-size policy¶

A new # module-kind: <tier> header on the first non-blank, non-shebang, non-encoding-declaration line of a file declares its tier. The header position is strict: headers after the module docstring or interleaved with imports are ignored. Tiers:

LOC counting matches check_baseline_growth.py::_count_text_entries: physical lines excluding blank lines and #-prefixed comment-only lines. Inline trailing comments DO count.

The shared helper scripts/_module_size_lib.py centralises LOC counting, tier resolution, the tier table, and the generated-glob set so the gate and the baseline generator cannot drift.

Existing offenders are absorbed via scripts/_module_size_baseline.json. A baselined file may stay at or below its recorded LOC; growth past the baseline fails. New files may not exceed their tier cap regardless of baseline. Baselines shrink monotonically (enforced by check_baseline_growth.py).

In addition, an explicit god-module allowlist (core/enums.py) must net-shrink on every PR. This gate (check_no_growth_in_god_modules.py) prevents the central files from absorbing more responsibility while PR 4 decomposes them. The five api/ entries (app.py, state.py, auto_wire.py, lifecycle.py, lifecycle_builder.py) drained from the allowlist in PR 3 (#2049) once the controller decomposition brought each under its tier cap; they are now governed by check_module_size_budget.py.

Complex-service tier¶

complex_service (cap 1100) is the audit-verdict tier: a single cohesive responsibility expressed across more features than the 600 / 700 caps allow. It exists because the #2052 cohesion audit confirmed a set of files as one responsibility each, at 642 to 1051 LOC. The standard caps (service / orchestrator 600, adapter / integration 700) cannot express "this file is cohesive AND larger than 700", so the verdict could not be honoured under them: a 948-LOC file tagged # module-kind: service stays over its cap and therefore stays in the baseline. The 1100 cap lets a confirmed-cohesive file drop out of the baseline while still imposing a real ceiling.

A cohesion verdict resolves to one of three states:

1. Cohesive AND <= 1100 LOC -- tag # module-kind: complex_service. The file falls under cap and drops from _module_size_baseline.json on the next regeneration.
2. Cohesive BUT > 1100 LOC -- tag # module-kind: complex_service. The file stays in the baseline and is enforced against the 1100 ceiling with baseline absorption, exactly like any other tier. The 1100 cap binds even here, so the tier is not a way to exempt a file from a ceiling.
3. Two or more responsibilities -- not eligible. The file is reclassified as a decomposition target with a follow-up issue filed.

The tier is reserved for audit verdicts. It is assigned by a cohesion-audit verdict, not opted into by new code. New service, adapter, and controller files still hit their strict caps (600 / 700 / 400). A contributor facing an over-cap new file fixes the cohesion or shrinks the file; reaching for complex_service to silence the gate is a misuse of the tier.

Ten new custom gates¶

All baseline-driven, all wired into .pre-commit-config.yaml:

1. check_module_size_budget.py -- the tier-cap enforcer above.
2. check_no_growth_in_god_modules.py -- god-module net-shrink rule.
3. check_no_central_junk_drawer.py -- the dissolved core/enums.py must not be recreated. (The former AppState.__slots__ count was drained to zero; that invariant now lives in check_no_implicit_state_attribute.py.) Dissolution tracked in #2051.
4. check_no_circular_imports.py -- AST-driven Tarjan SCC detection across src/synthorg/. Excludes TYPE_CHECKING and function-local imports.
5. check_module_depth.py -- package-nesting depth ceiling (4 today).
6. check_protocol_documented.py -- every Protocol class carries a non-trivial docstring (>=10 chars, not TODO/TBD/FIXME/...).
7. check_no_module_level_io.py -- no open()/subprocess/ requests/httpx/socket/urllib.urlopen/Path.{read,write}_* at import time. Function bodies and if __name__ == "__main__": are exempt.
8. check_state_slice_immutability.py -- state-slice classes must declare ConfigDict(frozen=True, extra="forbid"). Empty baseline in PR 1 (state slices arrive in PR 2); the gate is in place so PR 2 cannot land slices that violate.
9. check_strategy_protocol_injection.py -- factory-registered strategies must be referenced by Protocol type at callsites, not concrete impl.
10. check_settings_namespace_complete.py -- every SettingNamespace enum value has a corresponding settings/definitions/<name>.py file.

Ruff tightening¶

[tool.ruff.lint.pylint]
max-args = 5
max-public-methods = 12
max-statements = 30
max-branches = 10
max-returns = 5
max-locals = 15
max-nested-blocks = 4

[tool.ruff.lint.mccabe]
max-complexity = 8

New selects: BLE, G, ERA, INP, DOC. DOC201/202/501 were introduced under a broad per-file-ignore on src/synthorg/**, since drained so they enforce across all of src/synthorg/ (Exemption Ledger Section F).

Mypy strict++¶

disallow_any_explicit = true
disallow_any_generics = true
disallow_subclassing_any = true
no_implicit_reexport = true
warn_unreachable = true
extra_checks = true
strict_concatenate = true
enable_error_code = [
    "ignore-without-code", "redundant-cast", "truthy-bool",
    "narrowed-type-not-subtype", "unused-awaitable", "explicit-override",
    "possibly-undefined", "deprecated",
]

Legacy packages with non-trivial Any usage carried minimal [[tool.mypy.overrides]] blocks turning off only the flag that fires; the override list was the technical-debt register that later typing PRs lifted one package at a time. That drain is complete: no package carries a disallow_any_explicit = false override any more. The synthorg.* surface was drained by EPIC #2056 and the tests.* surface by #2121, so tests.* now inherits the global disallow_any_explicit = true with no Any-disabling override.

Pyright¶

Added as a CI artefact via .github/workflows/pyright.yml. The job runs pyright --outputjson, uploads the report, and continue-on-error: true. No pre-push gate.

New Python tools¶

Added to [dependency-groups.dev] and .pre-commit-config.yaml: deptry (dependency hygiene), vulture (dead code), interrogate (docstring coverage threshold), codespell (spelling), sqlfluff (SQL lint, per-dialect).

Typeguard intentionally not landed in PR 1. It surfaces 200-500 TYPE_CHECKING-import sites that crash at runtime (typeguard resolves annotations at runtime; TYPE_CHECKING-guarded names are unavailable then). Fixing each site requires moving the import to runtime (risking circular-import cycles) or rewriting the annotation as a string forward-ref. The full fix-volume would blow the 10k LOC / 200 file caps that bound this PR. PR 2 (feature-manifest substrate) restructures the import graph anyway: feature modules become runtime-importable so typeguard has far less to break on. Typeguard was deferred to a dedicated multi-PR programme; #2182 (WARN activation) and #2183 (ERROR hardening, via the EPIC #2303 decomposition) both landed, so typeguard runs at the ERROR forward-ref policy across the full synthorg package. The realised scope -- ~1,500 resolved-type mismatches plus ~1,055 TYPE_CHECKING-guarded modules -- proved far larger than this PR-1 estimate. This was a deliberate scope choice, not a TODO.

New web tools¶

web/package.json gains knip, dpdm, madge, size-limit, @lhci/cli. Per-route bundle cap 200 KB gzipped. Lighthouse aggressive budgets (perf >= 90, a11y >= 95, CLS <= 0.05, LCP <= 2500ms, TBT <= 300ms), hard-blocking from day one. ESLint tightened to match Python tier values (complexity 8, max-lines 400, max-lines-per-function 80, max-params 5, no-restricted-imports for feature isolation).

Tightened Go lint¶

cli/.golangci.yml enables gocyclo (min-complexity 10), funlen (80/60), gocognit (15), nestif (4), stricter revive, and gosec (security scanner; scoped exclusions for test files, the Windows unsafe disk-free system call (G103), and the shell-completion installer's perm/path findings (G301/G302/G304/G306)).

New docs / SQL / YAML tools¶

Landed: markdownlint, yamllint, sqlfluff, lychee (Markdown link check). Deferred (see Exemption ledger): vale (Google style + British dictionary).

Consequences¶

Positive¶

• Architectural badness has at least one mechanical gate. AI agents cannot grow god-modules unintentionally; the gate fires at pre-push.
• Baselines absorb today's reality so existing code passes. The day this merges, the bleeding stops.
• The codebase's enforcement substrate matches the discipline the team already practises in periphery features.
• PR 2 can land the manifest substrate on top without first having to land its own enforcement layer.

Negative¶

• Twelve new tools and ten new gates land in one PR. The pre-push surface grows; CI wall-clock grows by at most the longest new job (Lighthouse, ~2-3 min).
• Mypy [[tool.mypy.overrides]] block list creates explicit technical debt that later typing PRs must drain (RESOLVED: EPIC #2056 drained the synthorg.* surface and #2121 drained tests.*; no disallow_any_explicit override remains anywhere).
• DOC per-file-ignore creates implicit technical debt that later docstring PRs must drain (RESOLVED by #2065: the brace-expansion ignore is deleted and DOC201/202/501 enforced across src/synthorg/).
• Typeguard was wired but NOT activated in PR 1; activation (and the ~1,500 resolved-type mismatches plus ~1,055 TYPE_CHECKING-guarded modules it surfaces) was deferred to a dedicated programme. #2182 (WARN) and #2183 (ERROR, via EPIC #2303) both landed.

Neutral¶

• Header rollout in PR 1 covers only a small allowlist of obviously declarative files (core/enums.py, events/persistence.py, settings/definitions/*.py >500 LOC). Group-F audit (#2052) tags the rest.
• Dissolution of core/enums.py into per-domain files is tracked in #2051 (out of scope of this EPIC).

Alternatives considered¶

Blanket <N LOC ceiling¶

A single global file-size cap was the status quo (<800 lines in CLAUDE.md). It false-positives on legitimate declarative blobs (event constants, schema definitions) and forces real services to fragment gratuitously. Rejected.

Tier-less ratchet via baseline alone¶

Capture today's max LOC per file, lock it, ratchet. Works for existing files but provides no signal for new files: a new 2000-line god-controller passes because nothing baselines it. Rejected.

Ruff config alone¶

Ruff measures function-level complexity. File-level fan-in / cohesion / god-objects are invisible to it. Tightening ruff is necessary but not sufficient; the custom gates fill the gap.

<800 guideline kept and enforced via reviewer attention¶

Existing data refutes this: PR #2045 grew api/app.py by 113 LOC under reviewer attention. AI-generated code is too high-volume for reviewer attention alone to enforce architecture. Rejected.

Exemption ledger¶

PR 1 declares many rules but cannot fix every existing violation in one PR. Each exemption below carries which subsequent PR or follow-up issue lifts it. Completing the EPIC #2046 sub-issues + the follow-ups below is the contract for "100% enforced".

A. Lifted naturally by PR 2 (#2048)¶

B. Lifted naturally by PR 3 (#2049)¶

Status: LIFTED in PR 3 (#2049). api/app.py is a <200-LOC discovery-based composition root (147 LOC); the eight multi-controllers, api/auth/controller.py, and the two MCP-handler god-modules decomposed into per-sub-domain packages; api/auto_wire.py, api/lifecycle.py, and api/lifecycle_builder.py reduced to under-cap dispatchers/runners. The five api/ entries (app.py, state.py, auto_wire.py, lifecycle.py, lifecycle_builder.py) drained from the check_no_growth_in_god_modules.py allowlist and are now governed at their tier cap by check_module_size_budget.py; core/enums.py was deleted by #2051 and dropped from the (now empty) allowlist. api/state.py (354 LOC) is governed by the code-tier 500 cap (the EPIC's <150 figure was descriptive, not a #2049 gate). The decomposed sub-package files carry no baseline entries, so they are enforced at the controller-tier 400 cap directly; the stale baseline entries for the nine deleted monolith files plus the four reduced api/ modules are dropped by the operator's check_module_size_budget.py --update-baseline regeneration, the one remaining mechanical step (the gate is green either way, since every file is already under its cap). See ADR-0008.

C. Lifted naturally by PR 4 (#2050)¶

Status: LIFTED in PR 4 (#2050). The six per-entity repository decompositions (Task / CostRecord / Message repositories, the decision repos, the two backends slimmed to thin assemblers -- now 179 / 315 LOC, far under cap) and the three service / recording decompositions (workers/execution_service, infrastructure/services, observability/prometheus_recording) landed; the synthorg.persistence.* mypy override is dropped (the package is disallow_any_explicit-clean). The three runtime import cycles are broken, so _circular_imports_baseline.txt drains to 0. The nine decomposed-file _module_size_baseline.json entries (seven deleted monoliths + the two slimmed backends) are dropped via the operator's check_module_size_budget.py --update-baseline regeneration (the gate is green either way once the deleted files are gone). The synthorg.{communication, engine, observability}.* overrides are NOT dropped here: PR 4 only decomposed / cycle-broke structurally within those packages and did not Any-drain them; their per-package disallow_any_explicit drain is EPIC #2056's charter (Section F), not PR 4's. Import-layering contracts (ADR-0009) and the architectural feedback loop (ADR-0011) also land in PR 4.

D. Lifted by #2051 (junk-drawer dissolution)¶

E. Lifted by #2052 (Group-F audit)¶

F. Requires NEW follow-up issues (no existing PR lifts)¶

These exemptions are not addressed by any existing PR in the EPIC. Each entry below maps to a separate tracking issue that must be filed and closed for the project to reach 100% strict enforcement.

F.1. Issue #2061 partial landing¶

The first #2061 PR narrowed the original tests.* mypy override block and tightened ~150 test files to the full strict++ bar individually (foundation helpers, fakes hubs, settings, observability, core, config, persistence, scripts, monitoring, telemetry, providers, security, budget, memory, knowledge, communication, hr, integrations, notifications, templates, workers, a2a, backup, client, plus most of the meta and tools tiers). The residual override lifted only the error codes that mapped to specific remaining cleanup work, each tracked by its own follow-up issue. All of them have now landed: with #2121 the tests.* override block is removed entirely and tests.* inherits the global strict++ configuration with no Any-disabling override.

The table below records each lifted error code and the sub-issue that ratcheted it off; every entry is now closed.

G. Permanent design decisions (NOT exemptions to lift)¶

• God-module net-shrink rule (check_no_growth_in_god_modules.py). The allowlist itself is permanent; entries drain as PR 3 decomposes each file.
• Generated-glob exemption (*.gen.*, *_pb2.py): generated code is by definition out of scope for source-level lint.
• declarative tier exemption: declarative data files don't have a meaningful LOC ceiling; junk-drawer growth is gated separately.

Related¶

• EPIC #2046: the umbrella program this PR opens.
• Sub-issues #2048 (manifest substrate), #2049 (controller decomposition), #2050 (repos/services + import-layering).
• Follow-up #2051 (dissolve core/enums.py).
• Follow-up #2052 (audit Group-F legitimately-complex files).
• Follow-ups required by Section F of the Exemption Ledger above; filed under the EPIC #2046 master ledger.