hugoduncan/gordian/namespace-structure

λ ideal(codebase). no_cycles ∧ stability_gradient ∧ minimal_entry_points ∧ lens_coherence ∧ family_surfaces ∧ test_leaves ∧ stable_trend

λ stability_gradient(graph). ∀ edge(A→B): A less_stable_than B depend toward stability

λ roles(ns). core → stable foundation | depended on by many | depends on few peripheral → entry-point ∨ leaf | depended on by few | depends on many | ≤1 per subsystem shared → god-module candidate | depended on by many ∧ depends on many | must justify isolated → vestigial unless intentional leaf

λ topology(ideal). one(peripheral) | all_others(core) | star

λ cycles(rule). cycles = 0 first-order violation; fix before all else

λ lens_coherence(pair). explicit_dep ∧ shared_vocab ∧ co-evolves → confirmed | consider merge if inseparable explicit_dep ∧ shared_vocab ∧ independent → expected | none explicit_dep ∧ unrelated ∧ independent → vestigial | remove implicit ∧ shared_vocab ∧ co-evolves → missing_abstraction | extract — highest priority implicit ∧ shared_vocab ∧ independent → vocabulary_sibling | monitor implicit ∧ unrelated ∧ co-evolves → implicit_data_contract | investigate

λ family(prefix). facade(ns) ← many external dependents ∧ few external dependencies ∧ delegates internally

noise(pair) ← shared vocabulary ⊆ naming_convention

signal(pair)← shared vocabulary ∩ domain_concepts ≠ ∅

λ tests(ns). no production code depends on test code tests depend on a small slice of production code → unit tests depend on an entry point → integration | justified unexpected broad test dependencies → grown unintentionally | isolate adding tests should not dramatically widen the blast radius of a change

λ health(principles). a change should touch a small fraction of the codebase no cycles stable things must not depend on unstable things