<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/2.x/2026-03-27-1-pytestarch-architectural-dependency-testing/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-03-27-1-pytestarch-architectural-dependency-testing/</id>
  <title>ADR: Architectural Dependency Testing &amp; Graph Infrastructure</title>
  <updated>2026-03-27T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/2.x/2026-03-27-1-pytestarch-architectural-dependency-testing/"/>
  <summary>Adopts PyTestArch so the kernel, doctrine, charter, and specify_cli dependency direction is executable, and a violating import fails a test instead of lingering.</summary>
  <content type="html">&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;The 2.x architecture defines four peer containers with a strict dependency direction:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;kernel          (zero outgoing dependencies — the true root)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;^&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;doctrine        (depends on kernel only)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;^&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;charter    (depends on doctrine + kernel, may import specify_cli.runtime)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;^&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;specify_cli     (depends on all three)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;These invariants are documented in &lt;code dir=&quot;auto&quot;&gt;architecture/2.x/00_landscape/&lt;/code&gt; and enforced by convention. However, violations can be introduced silently:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Lazy imports&lt;/strong&gt; inside method bodies (e.g., &lt;code dir=&quot;auto&quot;&gt;from specify_cli.runtime.resolver import resolve&lt;/code&gt; inside a &lt;code dir=&quot;auto&quot;&gt;doctrine&lt;/code&gt; class method) pass mypy, pass import-time checks, but violate the boundary at runtime. This was discovered during the mission 058 architectural review (AR-1).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Accidental imports&lt;/strong&gt; during refactoring — a developer moving code between packages may inadvertently introduce a backward dependency.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Transitive violations&lt;/strong&gt; — module A imports module B which imports module C, creating an indirect dependency chain that’s hard to spot in code review.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;There is no automated CI gate that catches these violations today.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;Adopt &lt;strong&gt;PyTestArch&lt;/strong&gt; (v4.0.1, Apache 2.0, &lt;a href=&quot;https://github.com/zyskarch/pytestarch&quot;&gt;github.com/zyskarch/pytestarch&lt;/a&gt;) as a dev dependency for architectural dependency testing.&lt;/p&gt;
&lt;h3 id=&quot;why-pytestarch&quot;&gt;Why PyTestArch&lt;/h3&gt;





































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Criterion&lt;/th&gt;&lt;th&gt;Assessment&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;API fit&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;LayeredArchitecture&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;LayerRule&lt;/code&gt; maps 1:1 to our C4 containers&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Detection method&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;AST parsing — sees ALL import statements including lazy/conditional imports inside method bodies&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Granularity&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Sub-module rules express “charter may import &lt;code dir=&quot;auto&quot;&gt;specify_cli.runtime&lt;/code&gt; but not &lt;code dir=&quot;auto&quot;&gt;specify_cli.cli&lt;/code&gt;”&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;pytest native&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Session-scoped fixture, &lt;code dir=&quot;auto&quot;&gt;assert_applies()&lt;/code&gt;, standard pytest assertions&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Performance&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;One-time AST parse per session; graph traversal per rule. ~500 source files is well within bounds&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Maintenance&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Active (255 commits, 27 releases, 153 stars). Python 3.9-3.13 supported&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;License&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Apache 2.0 — compatible with our MIT license&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;what-it-catches&quot;&gt;What it catches&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Direct imports across package boundaries (both module-level and lazy)&lt;/li&gt;
&lt;li&gt;Transitive dependency violations via graph traversal&lt;/li&gt;
&lt;li&gt;Regressions introduced by refactoring&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;what-it-does-not-catch&quot;&gt;What it does not catch&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;importlib.import_module()&lt;/code&gt; dynamic imports (rare in our codebase)&lt;/li&gt;
&lt;li&gt;Non-Python dependency references (YAML cross-references, etc.)&lt;/li&gt;
&lt;li&gt;Circular dependency cycles (no built-in API; addressed by networkx — see Decision 2 below)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;alternatives-considered&quot;&gt;Alternatives considered&lt;/h3&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Alternative&lt;/th&gt;&lt;th&gt;Why not&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Manual &lt;code dir=&quot;auto&quot;&gt;grep&lt;/code&gt; in CI&lt;/td&gt;&lt;td&gt;Fragile, misses transitive violations, no graph semantics&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;import-linter&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Less expressive rule API, no layer abstraction, less active maintenance&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Custom AST walker&lt;/td&gt;&lt;td&gt;Maintenance burden, reinvents what PyTestArch already provides&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;mypy plugin&lt;/td&gt;&lt;td&gt;mypy checks types not architectural boundaries; wrong tool for the job&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h2 id=&quot;implementation&quot;&gt;Implementation&lt;/h2&gt;
&lt;h3 id=&quot;test-structure&quot;&gt;Test structure&lt;/h3&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;tests/&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;architectural/&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;conftest.py          # session fixtures: evaluable, landscape&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;test_layer_rules.py  # invariant tests&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;core-invariants-encoded&quot;&gt;Core invariants encoded&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;kernel imports nothing&lt;/strong&gt; from doctrine, charter, or specify_cli&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;doctrine imports only kernel&lt;/strong&gt; — never specify_cli or charter&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;charter does not import specify_cli&lt;/strong&gt; (except &lt;code dir=&quot;auto&quot;&gt;specify_cli.runtime&lt;/code&gt;, which is permitted)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No reverse dependencies&lt;/strong&gt; — specify_cli does not import from itself through doctrine or charter&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;ci-placement&quot;&gt;CI placement&lt;/h3&gt;
&lt;p&gt;Tests are marked &lt;code dir=&quot;auto&quot;&gt;@pytest.mark.architectural&lt;/code&gt; and run at the same priority as kernel tests: fast, every PR, fail-fast. A single violation blocks the PR.&lt;/p&gt;
&lt;h2 id=&quot;decision-2-networkx-for-graph-infrastructure-consolidation&quot;&gt;Decision 2: networkx for Graph Infrastructure Consolidation&lt;/h2&gt;
&lt;h3 id=&quot;context-1&quot;&gt;Context&lt;/h3&gt;
&lt;p&gt;The codebase contains &lt;strong&gt;4 independent graph implementations&lt;/strong&gt;, each hand-rolling the same fundamental algorithms:&lt;/p&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Domain&lt;/th&gt;&lt;th&gt;Location&lt;/th&gt;&lt;th&gt;Algorithms&lt;/th&gt;&lt;th&gt;Lines&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;WP dependencies&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;specify_cli/core/dependency_graph.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;DFS 3-color cycle detection, Kahn’s topo sort&lt;/td&gt;&lt;td&gt;~170&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Doctrine references&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;charter/reference_resolver.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;DFS path-tracking cycle detection&lt;/td&gt;&lt;td&gt;~90&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Event causation&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;specify_cli/spec_kitty_events/topology.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Kahn’s topo sort + cycle detection&lt;/td&gt;&lt;td&gt;~60&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Worktree stacking&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;specify_cli/core/worktree_topology.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Delegates to WP dependency graph&lt;/td&gt;&lt;td&gt;~80&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;All four domains model directed acyclic graphs. All four need cycle detection. Three need topological ordering. None share code.&lt;/p&gt;
&lt;p&gt;Additionally, PyTestArch (Decision 1) explicitly lacks cycle detection — a gap networkx fills.&lt;/p&gt;
&lt;h3 id=&quot;decision-1&quot;&gt;Decision&lt;/h3&gt;
&lt;p&gt;Adopt &lt;strong&gt;networkx&lt;/strong&gt; (BSD license, &lt;a href=&quot;https://github.com/networkx/networkx&quot;&gt;github.com/networkx/networkx&lt;/a&gt;) as a runtime dependency at the &lt;strong&gt;kernel&lt;/strong&gt; level (zero domain-specific dependencies).&lt;/p&gt;
&lt;h3 id=&quot;why-networkx&quot;&gt;Why networkx&lt;/h3&gt;





































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Criterion&lt;/th&gt;&lt;th&gt;Assessment&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;API fit&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;DiGraph&lt;/code&gt; maps directly to all 4 existing adjacency-list graphs&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Algorithm coverage&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;topological_sort&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;topological_generations&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;simple_cycles&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;descendants&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;ancestors&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;dag_longest_path&lt;/code&gt; — all currently hand-rolled or missing&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Parallel wave scheduling&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;topological_generations()&lt;/code&gt; yields groups of independent nodes — directly models WP parallel execution waves&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Impact analysis&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;ancestors()&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;descendants()&lt;/code&gt; enable “what depends on this?” queries for doctrine artifacts and glossary terms&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Visualization&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;nx.drawing.nx_pydot.write_dot()&lt;/code&gt; exports to Graphviz for debugging doctrine DAGs and dependency trees&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Maturity&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;11k+ GitHub stars, NumFOCUS sponsored, Python 3.10-3.13, BSD license&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Size&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;~4MB installed, pure Python (no C extensions required)&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;what-it-consolidates&quot;&gt;What it consolidates&lt;/h3&gt;
&lt;p&gt;The 4 existing implementations (~400 lines total) reduce to domain-specific wrappers around &lt;code dir=&quot;auto&quot;&gt;nx.DiGraph&lt;/code&gt;:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;python&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Before: 170 lines of Kahn&apos;s + DFS in dependency_graph.py&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# After:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;G &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; nx.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;DiGraph&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;adjacency&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;order &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;list&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;nx.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;topological_sort&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;G&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;))&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;cycles &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;list&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;nx.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;simple_cycles&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;G&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;))&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;waves &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;list&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;nx.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;topological_generations&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;G&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;))  &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# NEW: parallel scheduling&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Each domain retains its own error types (&lt;code dir=&quot;auto&quot;&gt;MergeOrderError&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;DoctrineResolutionCycleError&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;CyclicDependencyError&lt;/code&gt;) wrapping networkx exceptions.&lt;/p&gt;
&lt;h3 id=&quot;what-it-enables-not-currently-possible&quot;&gt;What it enables (not currently possible)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;WP parallel wave scheduling&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;topological_generations()&lt;/code&gt; computes independent groups directly — currently inferred manually from the dependency summary&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Doctrine blast radius&lt;/strong&gt;: “If I change this tactic, which directives are affected?” — &lt;code dir=&quot;auto&quot;&gt;nx.ancestors(G, tactic_id)&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Glossary orphan detection&lt;/strong&gt;: Terms with in-degree 0 (referenced by nothing)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Critical path analysis&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;nx.dag_longest_path(G)&lt;/code&gt; for WP dependency chains — identifies the bottleneck sequence&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Subgraph extraction&lt;/strong&gt;: Isolate a feature’s dependency neighborhood for focused analysis&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;alternatives-considered-1&quot;&gt;Alternatives considered&lt;/h3&gt;





















&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Alternative&lt;/th&gt;&lt;th&gt;Why not&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Keep hand-rolled implementations&lt;/td&gt;&lt;td&gt;4 independent copies of the same algorithms; no path to wave scheduling or impact analysis&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;igraph&lt;/code&gt;&lt;/td&gt;&lt;td&gt;C extension dependency, harder to install, overkill for our graph sizes&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;graphlib&lt;/code&gt; (stdlib)&lt;/td&gt;&lt;td&gt;Python 3.9+ &lt;code dir=&quot;auto&quot;&gt;TopologicalSorter&lt;/code&gt; only — no cycle detection, no descendants/ancestors, no visualization&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;rollout&quot;&gt;Rollout&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Phase 1&lt;/strong&gt;: Add &lt;code dir=&quot;auto&quot;&gt;networkx&lt;/code&gt; as a runtime dependency. Refactor &lt;code dir=&quot;auto&quot;&gt;dependency_graph.py&lt;/code&gt; to use &lt;code dir=&quot;auto&quot;&gt;nx.DiGraph&lt;/code&gt;. This is the lowest-risk entry point — WP dependency graphs are small and well-tested.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Phase 2&lt;/strong&gt;: Migrate doctrine &lt;code dir=&quot;auto&quot;&gt;reference_resolver.py&lt;/code&gt; and event &lt;code dir=&quot;auto&quot;&gt;topology.py&lt;/code&gt;. Add visualization export for debugging.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Phase 3&lt;/strong&gt;: Expose &lt;code dir=&quot;auto&quot;&gt;topological_generations()&lt;/code&gt; in the implement workflow for automated parallel wave scheduling.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Phase 1 can be scoped as a WP within mission 058 or as a standalone follow-up mission.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;decision-1-pytestarch&quot;&gt;Decision 1 (PyTestArch)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Positive&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Package boundary violations are caught before merge, not during architectural review&lt;/li&gt;
&lt;li&gt;New contributors get immediate feedback on dependency direction&lt;/li&gt;
&lt;li&gt;The invariants are executable documentation, not just prose in &lt;code dir=&quot;auto&quot;&gt;00_landscape/&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Session-scoped fixture means near-zero overhead added to test suite&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Negative&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;One new dev dependency (&lt;code dir=&quot;auto&quot;&gt;pytestarch&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;AST parsing treats lazy imports the same as module-level imports — this is intentional for our use case but means a legitimate lazy import pattern (if one were ever needed) would require an explicit exclusion in the test&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Neutral&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The evaluable architecture is rebuilt per test session. If the codebase grows significantly (&gt;5000 files), the session fixture may need &lt;code dir=&quot;auto&quot;&gt;level_limit&lt;/code&gt; tuning.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;decision-2-networkx&quot;&gt;Decision 2 (networkx)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Positive&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Eliminates ~400 lines of duplicated graph algorithms across 4 modules&lt;/li&gt;
&lt;li&gt;Unlocks parallel wave scheduling, impact analysis, and visualization — none currently possible&lt;/li&gt;
&lt;li&gt;Battle-tested algorithms replace hand-rolled implementations&lt;/li&gt;
&lt;li&gt;kernel-level placement means all containers can use it without violating dependency direction&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Negative&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;One new runtime dependency (~4MB)&lt;/li&gt;
&lt;li&gt;Developers must learn networkx API (well-documented, widely known)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Neutral&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Existing domain error types and public APIs remain unchanged — only internal implementations change&lt;/li&gt;
&lt;li&gt;Graph sizes in spec-kitty are small (typically &amp;#x3C;50 nodes) — networkx performance characteristics are irrelevant at this scale&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
