Repository navigation
Description
Part of the code-health epic. Evidence pinned to main @ 71b8c94.
Problem
src went from 66 to 123 modules in a month. _LAYERS has 62 entries, and 32 of them are at rank 0. Ranks 1 to 8 hold only 2, 9, 1, 2, 1, 3, 11 and 1 entries. When a third of the modules share one rank, the DAG guard can't restrict imports among them.
About 15 of the rank-0 modules are under 200 lines, and seven are under 60:
score(10)obligations(22)intents(40)feature_identity(43)_warnings(51)leader_policy(52)location_contractandmeasurement_support(56 each)
There are also three recognition_*, three recogniser_* and five *_contract modules. Several look like they were split out to break an import cycle, not because they hold a separate concept.
The documentation has drifted from the code in several places:
model/(17.2k lines) is rank 0 in_LAYERSbut listed as a "Stage module" in the agent guide.audit.pyandview_plan.py(868 lines, about 17 importers) are missing from the compact map.docs/architecture.mdis missingview_plan,annotation_layout_profile,layout_selectionandsection_recess_contract.- Only
_LAYERSis checked for completeness, so the two documents drift silently.
Proposal
- Fold modules under about 60 lines into their natural consumer, or group them into a
contracts/orrecognition/subpackage with an internal rank order. - Re-rank the leaf band so that rank 0 means "imports nothing in the package".
- Make
_LAYERSthe only module list. Cut the compact map in the agent guide down to one line per module group. Add a test that every module is named indocs/architecture.md.
Maintainer decision and progress
The maintainer chose to fold small modules into natural consumers and group any cohesive remainder. ADR text requires sign-off on exact wording before edits.
- Fold location predicates into measurement support (#1933) #1972 moved location predicates to their natural owner and kept stable import paths.
- Fold obligation policy into layout (#1933) #1976 moved obligation survival policy into
layout.py, leavingobligations.pyas a stable rank-1 reexport. Rank-0 entries fell from 32 to 31 and same-rank import occurrences from 43 to 42. - Move leader region policy into annotation layout ownership #1979 moved leader region policy into
annotation_layout_profile.py, leavingleader_policy.pyas a stable rank-1 reexport. Rank-0 entries fell by two more, from 31 to 29; a guard now rejects type-only or lazy upward exemptions from rank 0.
The strict rank-0 import boundary and documentation exit criteria remain open.
Activity
pzfreo commentedon Sep 28, 2026
Current
main4183a238rank-0 runtime import census (using the guard's own AST resolver, excluding imports within one top-level subpackage): 17 source files have a cross-module rank-0 dependency. The edges includelayout -> obligations,layout_scheme -> model/obligations/view_plan,location_contract -> measurement_support -> registry,recognition_cache -> progress,recognition_frame -> _geometry/progress, andrecognition_ownership ->six leaves. Severalmodel/files depend on other rank-0 leaves, somodelitself cannot remain rank 0 under the epic's strict “imports nothing in the package” exit rule.Suggested verified slices: (1) fold genuinely tiny leaves into their natural consumers where import fan-out allows it; (2) rank the remaining leaf graph in topological order and add an executable guard that rank 0 has no package runtime imports; (3) make architecture docs mechanically account for every
_LAYERSkey. Preserve the public compatibility shims from #1936 until their stated removal version. No ADR wording change is necessary for the census; any proposed ADR edit remains subject to the agreed specific-text sign-off.Fold location predicates into measurement support (#1933) (#1972)
pzfreo commentedon Sep 28, 2026
First reviewed slice merged in #1972 (
688aa344). Pocket/pad location applicability predicates now live with their natural measurement-support owner; compiler and lint consumers import that owner.location_contractremains an explicitly supported import path, preserving existing callers without a new warning. The independent review's import-lifecycle concern was resolved before merge. Focused boundary/location and coverage tests, static checks, and all CI jobs passed. No ADR text changed.The agent census moved rank-0 files with direct package runtime imports from 18 to 17 (direct imports 58 to 57). The strict rank-0 criterion, broader module consolidation, and complete architecture-doc map remain open.
Move leader region policy to annotation layout owner (#1933)
Move leader region policy to annotation layout owner (#1933) (#1979)
pzfreo commentedon Sep 29, 2026
Completed in #2102 after the earlier ownership slices. Rank 0 is a strict package leaf band with a fail-closed import guard (including lazy and type-only imports); every ranked module is named in docs/architecture.md, and the AGENTS map matches the grouped DAG. The 22 import-boundary/architecture-doc tests pass on merged main at 502bbc4. Stable compatibility paths remain at their ranked facade homes; no ADR text changed.