Maintainability refactor contract

LeapView favors explicit capability ownership and behavior-preserving extraction over arbitrary file-size limits. A large file is a refactor candidate when it combines several reasons to change, independent state machines, optional production dependencies, or unrelated side effects. Cohesive state machines and exhaustive translators may remain large when splitting them would hide their invariants.

Required workflow

For a structural refactor:

1. Identify the public API, generated contract, transaction boundary, lifecycle ordering, and observable diagnostics that must remain stable.
2. Add characterization coverage before moving behavior that is only tested indirectly.
3. Extract along a domain family, state-machine boundary, lifecycle collaborator, or generation phase. Prefer another file in the owning package before creating another package.
4. Keep authoritative transitions in their owning coordinator. Do not distribute a state machine among generic helpers.
5. Run the focused package or browser tests, generated checks when contracts are involved, git diff --check, and task ci.

Every refactor must preserve capability ownership, the declared acyclic dependency graph, CSRF and authorization boundaries, deterministic generation, error contracts, and exactly-once cleanup.

Audited extraction boundaries

Review signals

Useful review signals are reduced reasons to change, narrower test setup, explicit dependencies, locally visible transitions, and smaller diffs for ordinary product work. Line count alone is not an acceptance criterion. Generated files are evaluated at their source generator, not as handwritten hotspots.

Ratcheting engineering-quality budgets

task quality:budget:check scans tracked and newly authored Go and TypeScript/JavaScript files. Generated, compiled, and vendored sources are excluded. The required Go-package CI lane runs the same check for every pull request and merge-queue candidate.

The policy in .quality/engineering-budget.json measures three dimensions for each source category:

For every category, CI rejects increases in the number of files over the threshold, total lines above the threshold, or the largest authored file. Existing hotspots remain visible as debt; they are not retroactively declared well-sized. The gate also rejects increases in reviewed quality suppressions such as nolint, nosec, eslint-disable, and TypeScript ignore directives.

This is a ratchet, not an instruction to split code mechanically. A file may cross a review threshold only through an explicit policy change that explains why its invariants are clearer together. Reducing one hotspot does not silently authorize growing another: run task quality:budget:update after an improvement to tighten the committed baseline. The update command refuses increases by default.

When the gate fails:

1. Read the reported category and hotspot list.
2. Prefer extracting a purpose-owned collaborator or removing the new suppression.
3. Run focused characterization coverage and task quality:budget:check.
4. If cohesion genuinely requires a larger surface, review the policy increase explicitly; do not use the normal update task to hide it.

The budget intentionally does not grade naming, domain cohesion, or architectural correctness. Those remain review responsibilities backed by the ownership and behavior-preservation contracts on this page.

task quality:trends:report complements the fail-closed budgets with the ten highest Go decision-point counts and the most frequently changed authored source files across the last 200 first-parent commits. The report is diagnostic evidence: complexity and author count trigger boundary review, but do not mechanically reject a cohesive implementation.

Reviewed exceptions

.quality/engineering-exceptions.json is the durable record for a cohesive authored file that intentionally remains above its review threshold. Every entry is path-scoped and must name its architectural kind, accountable owner, specific reason, review date, next review deadline, and a hard maximum line count. task quality:exceptions:check fails when the file grows past that ceiling, disappears without policy cleanup, or passes its review deadline.

Generated sources do not use authored-file exceptions. They are excluded only when their generated suffix, generated directory, or leading generated-file header makes the source boundary independently verifiable; the generator remains the reviewed implementation surface.

Current decomposition evidence

The first governed extraction moves bootstrap, connection-scope, command-failure, and delivery-authorization policy from internal/app/runtime_router.go into internal/app/runtime_router_policy.go. The code remains in package app, so the change introduces no new dependency edge; existing bootstrap and canonical-authorization characterization tests protect behavior. On the PostgreSQL target branch where the policy landed, the router hotspot falls from 2,583 to 2,121 lines, reducing that file's excess-line contribution by 462 lines.

Engineering-quality delivery plan

The current baseline supports five independently verifiable milestones:

The milestones are ordered dependencies. Measurement and exception rules land before structural extraction so each decomposition tightens an observable baseline. Coverage floors run in the pull-request package lane. Race expectations run in the full merge lane because the tagged compiler race suite takes roughly 106 seconds on the revalidated baseline.