Chapter 12 — Traceability Graphs: The Big Picture📋

A bipartite traceability graph that only exists as text is a graph that only machines read. This chapter renders it seven ways.

The previous eleven chapters of this series worked at the unit of the decorator, the Requirement, the Feature, and the Style. Each of them named one edge of a graph and held it still long enough to photograph. This chapter does the opposite. It lets go of any single edge and renders the whole thing — all 22 Requirements, all 25 Features, all 54 test classes — as one global picture, then carves six slices out of it to answer six distinct questions.

Seven diagrams. Prose between them is pacing rather than density. The reader is expected to look at each diagram as long as looking rewards — the dense global one is a reference, not a teaching diagram, and most readers will spend a minute on it and move on — and to slow down on the clusters, where the questions are sharper.

Why seven, and why these seven📋

One global diagram says here is the shape of the whole. Six cluster diagrams each say here is the shape of one question. A reasonable objection is: why not one per Requirement? Twenty-two slices, each showing what satisfies a single Requirement and what verifies those Features. That would be a reference atlas, not a chapter. The cluster selection here is deliberately non-uniform: each cluster is picked because it answers a question the others cannot.

• The dog-food cluster answers what does a super-connector look like? — the node whose fan-out touches every Feature.
• The refactor-safety cluster answers what does a small, tightly-scoped Requirement family look like? — three Requirements, four Features, one coherent concern (the codemod / schema / sync chain).
• The TUI/visual cluster answers what does the reader-facing surface of the package look like? — explorer, renderer, watch-mode, and the Requirements that justify their existence.
• The scenarii cluster answers what does a high-density internal cluster look like? — seven Features, two tightly-coupled Requirements, and an FSM orchestrator at the centre.
• The scaffold cluster answers what does a many-to-many showcase Feature look like? — FEATURE-NEW-COMMAND and its seven @Satisfies parents.
• The styles cluster answers what does the M2 plumbing look like? — the small ring of Features that exist so that all the others can be written.

The global diagram exists to prove these six are slices of one object. Without it, a reader could reasonably suspect the clusters were curated to hide drift. The global diagram is the proof they were not.

Diagram 1 — Global REQ → FEAT → TEST graph📋

The numbers the global diagram has to carry: 22 Requirement classes on the left, 25 Feature classes in the middle, 54 test classes on the right. Around 110 @Satisfies edges between the first two columns (total Requirement-satisfier count across the Feature files). Around 220 @FeatureTest+@Verifies edges between the last two columns (roughly the count of decorated test methods — compressed at the class level). The diagram is visually dense. That is the point. The aesthetic goal is not legibility per-edge; it is the shape of the whole.

Three things to notice without zooming in.

First, the left column has a clear top-heavy shape. Three nodes at the top — REQ-DOG-FOOD, REQ-PARALLEL-DELIVERABLE, REQ-DSL-COMPLETE — carry a visibly larger share of the outgoing edges than the rest. These are the super-connectors. They are the Requirements that apply to the whole of the package rather than to any single deliverable. The middle cluster of Requirements — REFACTOR-SAFE, SPEC-IS-SOURCE-OF-TRUTH, TUI-MODERN, VISUAL-TRACEABILITY — carries the bulk of the semantic load: these are the Requirements that tell the package what it is for. The bottom — VERSIONED-TRACEABILITY, AUDIT-TRAIL-HOOKS, PROPERTY-INVARIANTS, ORTHOGONAL-TOGGLING — are narrow leaves, each with exactly one or two satisfiers. That banding is not an accident of layout. It is the Requirement taxonomy drawn.

Second, the middle column has a visible sub-cluster around the scenario Features. SCENARIO-PLAY, SCENARIO-RECORD, SCENARIO-ORCHESTRATOR, SCENARIO-AI-ADAPTER and the list/inspect/export/validate ring are knotted into a tight neighbourhood by the REQ-SCENARIO-DRIVEN-WORKFLOW, REQ-MULTI-FSM-ORCHESTRATION, REQ-AI-AS-IMPLEMENTER-ADAPTER triad. Diagram 5 zooms there.

Third, the right column is compressed to a single summary node. At the global scale, 54 tests with ~780 @Verifies methods would turn the rightmost column into a wall of ink and tell the reader nothing. The compressed TESTS node is honest: it says there is a roughly 1-to-1 (sometimes 1-to-2) relation from Feature to test class, and per-method edges exist but are not the point of this view. The cluster diagrams below expand that column where it matters.

This diagram is a reference. The rest of the chapter walks through six sharper views.

Diagram 2 — Dog-food cluster📋

REQ-DOG-FOOD is the largest fan-out in the package. Pull it out of the global graph, follow every @Satisfies edge leaving it, and collect the tests of every Feature at the other end.

A super-connector is a Requirement whose arrows spray across the middle column rather than terminate at a handful of Features. REQ-DOG-FOOD is the extreme case. Roughly every Feature that produces runtime code — and therefore produces tests that must be audited — carries ReqDogFoodRequirement in its @Satisfies list. The exceptions are exactly the Features that do not produce runtime code of their own, and hence have no test obligation of the form REQ-DOG-FOOD is worded to catch: BASE-TYPES (the abstract M2 vocabulary), COMPLIANCE-CORE (indirectly audited by its own product: if the scanner passed, REQ-DOG-FOOD was already enforced), TEST-BINDINGS-SCANNER and TRACE-CORE (the machinery the scanner consumes), and SCAFFOLD-CORE (interface-only, the concrete Scaffolders are where the dog-food test burden lands).

What does a high-connectivity node mean for compliance? Three things.

It sets the compliance budget. The compliance scanner reports, for each Requirement, a list of satisfying Features and, for each Feature, the test coverage of its ACs. For a super-connector like REQ-DOG-FOOD, the report is effectively a package-wide audit. If any single Feature in its fan-out fails to use @FeatureTest/@Verifies on its tests, the Requirement is in violation — not at the Feature level, at the package level. One leak anywhere in the fan-out invalidates the policy globally.

It resists partial migration. If REQ-DOG-FOOD were a ticket-scale Requirement — "the SmokeFeature must use @FeatureTest" — it could be satisfied Feature-by-Feature. Because it is a policy-scale Requirement with a fan-out of 22, it cannot. Introducing a single Feature written against Vitest's describe/it would break it. The graph visibly forbids that: any new Feature added to the middle column must be reachable from REQ-DOG-FOOD, and so must carry its decorator. The graph is the policy, not the documentation of the policy.

It turns the scanner into a dog-food witness. The compliance scanner is itself a Feature (COMPLIANCE-CORE) that satisfies REQ-DISCOVERABLE-TRACEABILITY and REQ-VISUAL-TRACEABILITY but, notably, does not carry REQ-DOG-FOOD in its own @Satisfies — because the scanner is the observer of dog-food, not one of its subjects. The test-bindings scanner and trace-core are in the same position. These are three of the five Features missing from the cluster above, and their absence is structurally correct: the observer cannot appear inside its own report without a regress. The other two absences (BASE-TYPES, SCAFFOLD-CORE) are interface-only Features whose test obligation is held by their concrete satisfiers.

Read the diagram once more. The fan-out is not a convenience. It is a shape that only became expressible in the DSL after REQ was promoted from rhetoric to type, and it is the reason a policy Requirement differs structurally from a ticket Requirement. In typed-specs, REQ-DOG-FOOD could not have been modelled: there was no Requirement stratum for a policy-scale entity to live in. Here, it fans out, and the fan-out is the compliance gate.

Chapter 13 will walk through the scanner's compliance gate machinery; chapter 14 will define the boundary between a super-connector and a narrow Requirement, with the fan-out threshold that marks the shift.

Diagram 3 — Refactor-safety cluster📋

Three Requirements, four Features, one concern: the codemod / schema / sync chain that lets specifications be edited in more than one direction without drift.

The question this cluster answers is what does a small, coherent Requirement family look like? Three Requirements are linked by what they constrain — the editability of the spec artefacts — but not by @Refines. None of the three refines another, because none is a generalisation of another: refactor-safe is about identifier-level change, spec-is-source-of-truth is about which artefact wins during apply, round-trip-editable is about the .ts ↔ .json conversion preserving structure. They are siblings, not parents and children.

What the cluster diagram shows that the global one cannot: the pairwise overlap of their satisfier sets. FEATURE-SCHEMA-COMMAND satisfies REQ-SPEC-IS-SOURCE-OF-TRUTH. FEATURE-SYNC-COMMAND satisfies the same Requirement, plus REQ-TUI-MODERN via the preview UI (not shown here to keep the cluster tight; see the TUI cluster below). FEATURE-BIDIRECTIONAL-SYNC is the one Feature that produces round-trip evidence: a spec is serialised to JSON, the JSON is re-parsed back to TypeScript, and the two representations are compared for structural equality. In the global diagram, these overlaps are buried in the density of the middle column. Here they are visible as two Features each drawing edges from two Requirements.

A second observation: this cluster has no super-connector. The three Requirements each have one to two satisfiers, and the four Features each have one to two parents in this slice. It is a dense local cluster, not a high-fan-out cluster. That density matters for compliance in a different way than dog-food's breadth: when the codemod is changed, all four tests must continue to pass, because the four Features are tightly coupled through the data layer (SyncPlan, the JSON Schema, the round-trip serialiser). The density is the coupling.

A third observation: the Requirement REQ-ROUND-TRIP-EDITABLE has exactly one satisfier — FEATURE-BIDIRECTIONAL-SYNC. A narrow leaf on the Requirement side, satisfied by a narrow leaf on the Feature side. In the global diagram this looks like a single thread; at cluster scale it is legible as the minimal evidence the Requirement demands. If that thread ever breaks — if FEATURE-BIDIRECTIONAL-SYNC loses its @Satisfies(ReqRoundTripEditableRequirement) decorator, or if its test class stops decorating its methods — the Requirement becomes an orphan, unsatisfied. The scanner catches this. The cluster diagram anticipates it.

Chapter 07 drew the sync command in isolation; here the same Feature sits inside its cluster, with the Requirements that justify its existence and the sibling Features that cover the same ground from adjacent angles.

Diagram 4 — TUI and visual cluster📋

Where the running example lives. REQ-TUI-MODERN, REQ-VISUAL-TRACEABILITY, REQ-DISCOVERABLE-TRACEABILITY — the three Requirements that shape the reader-facing surface of the package — and the six Features that sit in their joint fan-in.

The running example — FEATURE-TRACE-EXPLORER-TUI — is the middle-left node in this cluster. Its immediate parents in this slice are REQ-DISCOVERABLE-TRACEABILITY (the direct, semantic parent) and, through the dashed edge from the external super-connector, REQ-DOG-FOOD. The third Requirement the Feature satisfies — REQ-PARALLEL-DELIVERABLE — is shared with every Feature in the package and is suppressed in this cluster for the same reason the dashed line is dashed: it is a scaffold-level constraint, not a semantic-level one.

Three distinct Requirements shape three distinct faces of the reader-facing surface.

REQ-TUI-MODERN constrains how the user interacts with the package at the command line. The Prompt port (behind CLACK-ADAPTER) standardises the shape of prompts, spinners, and cancel signals so that every interactive command in the package — the sync preview, the new-command wizard, the requirement-edit flow — looks and behaves the same. In the cluster it has one direct satisfier (CLACK-ADAPTER), with indirect satisfiers visible in other clusters (FEATURE-SYNC-COMMAND, FEATURE-NEW-COMMAND, REQUIREMENT-COMMANDS — all of which carry ReqTuiModernRequirement in their @Satisfies because they use the port). The cluster intentionally shows only the direct one; the global diagram preserves the indirect edges.

REQ-VISUAL-TRACEABILITY constrains what the graph looks like on paper or on screen. FEATURE-MERMAID-GRAPH is the primary satisfier — the thing that emits the diagrams this chapter renders — and COMPLIANCE-CORE plus COMPLIANCE-REPORT are the tabular and narrative counterparts. The three Features together answer the question how does a human see the graph? in three distinct registers: as a network (mermaid), as a matrix (the compliance table), and as prose (the compliance report text).

REQ-DISCOVERABLE-TRACEABILITY constrains how a human finds their way in the graph without prior knowledge of the vocabulary. This is the Requirement the running example most directly satisfies — the explorer TUI exists precisely so that a newcomer can sit down at a terminal, type npx requirements trace explore, and discover the relations by arrow-key navigation instead of by reading a schema. Three other Features are in this Requirement's satisfier list: TRACE-CORE (the graph data structure), TEST-BINDINGS-SCANNER (the part that populates it), and the compliance core and report (which expose it in another form). The Requirement is broader than the running example, but the running example is its most visible realisation.

A note on the running example, structurally. FEATURE-TRACE-EXPLORER-TUI has ten @Verifies methods on its test class — four behavioural (build graph, arrow-key nav, drill-down, help overlay), three hardening (refuse non-TTY, exit clean on ctrl-C, backspace pops), two port-contract (uses FileSystem port, uses Prompt port), one end-to-end. The test column on the right shows the Feature's single test class collapsed into one node, but each of its ten methods is a @Verifies<FeatureTraceExplorerTuiFeature>('acName') edge back to one AC of the Feature. At the cluster scale those ten edges are collapsed into the single Feature→Test edge; at the AC scale they fan out; at the global scale they disappear into the summary node. Three levels of zoom, three different things to look at.

A second note on the running example, compositionally. It is the Feature in the series that most cleanly shows the many Requirements, one Feature shape. Three parent Requirements, each semantically distinct (discoverability, dog-food, parallel-delivery). No single Requirement tells the explorer what to be; the explorer's specification is the intersection of its parents. This is the shape typed-specs could not express: in typed-specs, each of the three parents would have had to be folded into the Feature name — an unreadable DiscoverableDogFoodedParallelDeliverableTraceExplorerTuiFeature — or silently dropped. Here the decoupling is the design.

Chapters 06 and 07 walked through the explorer TUI and the mermaid renderer in depth; this cluster puts them side by side and shows the Requirement stratum above them.

Diagram 5 — Scenarii cluster📋

Seven Features, two tight Requirements, one orchestrator at the centre. The densest internal sub-graph in the package.

This is the cluster with the highest internal density in the package. Three Requirements, each with its own semantic footprint:

• REQ-SCENARIO-DRIVEN-WORKFLOW is the breadth Requirement: scenarios must be recordable, listable, inspectable, exportable, validatable, replayable. It has eight satisfiers, one per scenario Feature. Every scenario Feature is under this Requirement.

• REQ-MULTI-FSM-ORCHESTRATION is the depth Requirement: when a scenario is played, the orchestrator fans it out across a per-AC FSM grid, and the inspect command reveals that grid. It has three satisfiers: the play command (the entry), the inspect command (the observer), and the orchestrator itself (the mechanism).

• REQ-AI-AS-IMPLEMENTER-ADAPTER is the integration Requirement: a PerAcFsm can delegate its implementation step to an AI, gated by an explicit --ai flag. Three satisfiers: play (exposes the flag), the orchestrator (honours it in the FSM transition), the AI adapter itself (implements the delegation contract).

The three Requirements overlap at one Feature: SCENARIO-ORCHESTRATOR. It is the only Feature in the cluster that sits at the triple intersection — it satisfies all three Requirements simultaneously. That triple intersection is meaningful. It marks the orchestrator as the pivot of the cluster: the mechanism through which the workflow breadth, the FSM depth, and the AI adapter integration all pass. A change to the orchestrator's contract is a change that touches three Requirements at once, not one. In compliance terms, the orchestrator's test coverage is under triple audit — every AC of its Feature class is verified against all three Requirements through the satisfier chain.

Another dense intersection: SCENARIO-PLAY sits at the intersection of all three Requirements too, though through the orchestrator rather than directly. Read the edges: play satisfies SCENARIO-DRIVEN-WORKFLOW directly; satisfies MULTI-FSM-ORCHESTRATION by dispatching to the orchestrator; satisfies AI-AS-IMPLEMENTER-ADAPTER by exposing the --ai flag. One Feature, three distinct justifications, each expressed in its @Satisfies list with a comment explaining the joint role.

The breadth Features — list, export, record, validate — sit on a single Requirement edge (REQ-SCENARIO-DRIVEN-WORKFLOW) plus the two super-connectors (DOG-FOOD and PARALLEL-DELIVERABLE, suppressed in this slice). They are the Features that make the workflow visible and auditable but do not themselves move FSMs or delegate to the AI. Their test coverage is narrower in scope because their Requirement count is narrower.

A compliance observation. In a cluster this dense, the scanner's job is not merely to check that every Feature has a satisfier list. It has to check that each Requirement in each satisfier list has a test that verifies at least one AC of the Feature. For SCENARIO-ORCHESTRATOR, that means three Requirement-level checks per AC. If one of the three Requirements has no verifying test — because the AC doesn't name that Requirement in its implementation — the scanner flags a satisfaction-without-verification diagnostic. This class of diagnostic is unique to the multi-Requirement shape and chapter 13 walks through the scanner's emitting rule in detail.

Typed-specs could not model this cluster at all. Each scenario Feature would have had to be a single flat class with an over-loaded name. The orchestrator-as-triple-intersection shape — the structural observation that one deliverable sits at the meeting point of three policies — would have been unrepresentable, and therefore unaudited.

Diagram 6 — Scaffold cluster📋

The showcase Feature — FEATURE-NEW-COMMAND with its seven @Satisfies parents — lives here.

Three Requirements sit in the core of the cluster:

• REQ-SCAFFOLD-EXTENSIBILITY is the port/adapter Requirement: the scaffolding surface must be open to new generators without touching existing ones. Two satisfiers: SCAFFOLD-CORE (the port) and SCAFFOLDER-REGISTRY (the adapter ring).
• REQ-BOOTSTRAP-ZERO-FRICTION is the onboarding Requirement: a new user must be able to go from git init to a validated spec in under sixty seconds. One satisfier: FEATURE-NEW-COMMAND (the wizard).
• REQ-LOW-FRICTION-ACS is the AC-ergonomics Requirement: naming an AC should feel closer to naming a variable than to filling a form. One satisfier: FEATURE-HEURISTIC-SUGGESTER (the name-suggestion heuristic).

Each of these is a narrow Requirement with one or two satisfiers. Nothing unusual so far. What makes the cluster worth rendering separately is the showcase Feature at its centre: FEATURE-NEW-COMMAND carries seven Requirements in its @Satisfies list:

@Satisfies(
  ReqBootstrapZeroFrictionRequirement,   // primary
  ReqSpecIsSourceOfTruthRequirement,     // joint: preview before write
  ReqEditorFirstClassRequirement,        // joint: emits $schema key
  ReqTuiModernRequirement,               // joint: uses Prompt port
  ReqDslCompleteRequirement,             // joint: wizard asks which Requirement(s)
  ReqParallelDeliverableRequirement,     // joint: one of the parallel streams
  ReqDogFoodRequirement,                 // joint: tests use @FeatureTest
)

That is the highest @Satisfies arity in the package. Seven parent Requirements, each justifying a different aspect of the Feature:

• Primary: REQ-BOOTSTRAP-ZERO-FRICTION is the Requirement that exists to justify the Feature's existence. If the new-command did not exist, this Requirement would have no satisfier and the scanner would flag it.
• Joint: REQ-SPEC-IS-SOURCE-OF-TRUTH because the wizard previews the spec before writing; REQ-EDITOR-FIRST-CLASS because the generated spec emits a $schema key; REQ-TUI-MODERN because the wizard uses the Prompt port; REQ-DSL-COMPLETE because one of the wizard's prompts asks which parent Requirement(s) the new Feature satisfies — so the wizard itself is a consumer of the Requirement stratum it is generating into.
• Scaffold: REQ-PARALLEL-DELIVERABLE and REQ-DOG-FOOD are the super-connectors, present on every Feature.

Seven parents means seven independent reasons the Feature is in the package, and seven independent obligations on the Feature's test coverage. Each of the seven Requirements, when the scanner cross-references, demands that at least one AC of the Feature have a verifying test that exercises the dimension the Requirement constrains. Seven independent dimensions. One Feature.

This is the many-to-many shape at its loudest. Typed-specs would have had to fold all seven into one name (BootstrapZeroFrictionSpecIsSourceOfTruthEditorFirstClassTuiModernDslCompleteParallelDeliverableDogFoodedNewCommandFeature) or drop six of the seven. Here, the @Satisfies list carries them as type-valued arguments, each importable, each inspectable, each with its own rationale, fit criteria, and verification method.

A specific point about the comments inside the @Satisfies list. In most Feature files the list is a bare sequence of class references. In FEATURE-NEW-COMMAND, the author — the scanner's consumer, not the scanner — has annotated each entry with a one-line reason: preview before write, emits $schema key, uses Prompt port. Those comments are not consumed by the compliance scanner (they are not decorated arguments), but they are essential for human reading. The cluster diagram makes the same information visible as edge labels. The graph is the machine version of the comments; the comments are the human version of the graph.

A corollary: a reader who approaches the package for the first time through FEATURE-NEW-COMMAND is seeing, in a single Feature, the whole Requirement taxonomy applied. The new-command is the least summarisable Feature in the package in that sense — it does not cleanly live in one cluster, and every cluster that exists is touched by one of its @Satisfies parents. It is the test case for whether the many-to-many shape is worth the book-keeping.

Chapter 14 opens with this Feature; this cluster diagram is its map.

Diagram 7 — Styles cluster📋

The small ring of Features that exist so all the others can be written. REQ-VOCAB-INDUSTRY-ALIGNED and REQ-DSL-COMPLETE are the two Requirements, and the five Features in their joint fan-in make up the M2 plumbing of the package.

The two Requirements in this cluster do different jobs.

REQ-DSL-COMPLETE is the existence Requirement: every M2 relation the DSL claims — Feature, Requirement, @Satisfies, @Refines, @Verifies, FitCriterion, Rationale, RequirementStyle — must have a typed vocabulary in the package and a test that constructs at least one instance. Its five satisfiers span the whole M2 surface: BASE-TYPES (the abstract classes), DECORATORS (the three decorators), SMART-CONSTRUCTORS (the builders that enforce invariants at construction time), REQUIREMENT-COMMANDS (the CLI surface that lets users author Requirements), FEATURE-NEW-COMMAND (the wizard that lets users author Features referencing Requirements).

REQ-VOCAB-INDUSTRY-ALIGNED is the naming Requirement: the three decorators must carry the names SysML / Volere / ISO 29148 would use. @Satisfies (not @Covers), @Refines (not @Extends), @Verifies (not @Tests, not @Implements). Two satisfiers: DECORATORS (the one Feature that provides the names) and REQUIREMENT-COMMANDS (which generates Requirements using the same vocabulary in its output templates, completing the loop).

The Styles axis (chapter 08) fits into this cluster at a level the diagram does not fully show: each style adapter — IndustrialStyleAdapter, LeanStyleAdapter, AgileStyleAdapter, KanbanStyleAdapter, DefaultStyleAdapter — is technically a satisfier of REQ-DSL-COMPLETE, because each extends the vocabulary in a different register. In the global diagram they are nested inside BASE-TYPES (they implement the RequirementStyle type parameter) and SMART-CONSTRUCTORS (they parameterise the builders). The cluster diagram collapses them to keep the shape legible; chapter 09 through chapter 11 unpack each adapter in isolation.

A compliance observation unique to this cluster: the M2 plumbing is the only part of the package where the satisfier count is allowed to be low (one or two per Requirement) without triggering a scanner warning. A narrow Requirement with one satisfier is fine when the Requirement is narrow. REQ-DSL-COMPLETE is not narrow in intent, but its satisfiers are few because each one covers a large chunk of the M2 surface. The scanner's fan-out budget is therefore not count the satisfiers but sum the AC coverage of the satisfiers — a richer metric that chapter 13 will walk through.

Reading the graphs: what to look for📋

Three habits, applicable across all seven diagrams.

Habit one: super-connectors are policies.

A super-connector is a Requirement with high fan-out — a Requirement that points at many Features rather than a few. In this package, three Requirements consistently carry super-connector shape: REQ-DOG-FOOD (22 satisfiers), REQ-PARALLEL-DELIVERABLE (21 satisfiers), REQ-DSL-COMPLETE (five satisfiers, but each covering a large surface). A super-connector is not a Feature-scale Requirement. It is a policy — a rule that applies across deliverables.

The test for whether a Requirement is a policy or a ticket is the fan-out. If the Requirement has one or two satisfiers and the satisfiers do one concrete thing (e.g. REQ-AUDIT-TRAIL-HOOKS → AUDIT-TRAIL-HOOKS Feature), it is a ticket-scale Requirement. If the Requirement has a dozen or more satisfiers and each carries its decorator as a joint, it is a policy-scale Requirement. Expect the policy-scale ones to appear in every cluster, even when they are not the cluster's centre.

This is why the clusters above explicitly show REQ-DOG-FOOD as a dashed external node in the TUI cluster and the scaffold cluster: policy Requirements cut through every cluster, and suppressing them entirely would misrepresent the cluster. Drawing them as external dashed nodes acknowledges their scope without letting them dominate.

Habit two: leaves are orphans-in-waiting.

A leaf in the Requirement column is a Requirement with exactly one satisfier (or none). A leaf in the Feature column is a Feature with exactly one parent Requirement (or none). In a well-formed package, leaves are rare at the Requirement end — every Requirement should have at least one satisfying Feature — and common at the Feature end — most Features satisfy their primary Requirement plus the scaffold super-connectors.

The or none cases are the interesting ones. A Feature with no @Satisfies is a Feature that exists without a justifying Requirement, which means either (a) the Requirement is missing and should be added, (b) the Feature is misplaced and should be removed, or (c) the Feature is genuinely scaffolding and needs an explicit @Satisfies(REQ-PARALLEL-DELIVERABLE, REQ-DOG-FOOD) at minimum.

The scanner reports all three cases as orphan diagnostics. In the global graph, an orphan Feature would appear as a node with no left-ward edges; an orphan Requirement would appear as a node with no right-ward edges. A well-maintained package has zero of both.

In this package, one Feature — REQUIREMENTS-SMOKE — has no @Satisfies decorator, because it is a one-AC health check whose failure indicates a fundamental broken assumption, not a Requirement violation. The scanner has a hard-coded allow-list for this single case, documented in the scanner source. Every other Feature in the package carries at least one @Satisfies.

Drawing a diagram from the text of the decorators and then asking are there leaves I did not expect? is a quick audit. The rendered diagrams above have none, which is a small but real verification that the scanner's allow-list is correct.

Habit three: long chains signal decomposition.

A long chain is a path from a high-level Requirement to a concrete test that threads through intermediate nodes: REQ-A @Refines REQ-B → FEAT-C @Satisfies REQ-B → AC-D on FEAT-C → TEST-E @Verifies AC-D. Five nodes, four edges, four different link semantics (refines, satisfies, belongs-to, verifies). A package with many such long chains is a package where policies have been decomposed into increasingly concrete sub-policies until the bottom of the chain bottoms out in a test that actually runs.

A package with only short chains — REQ directly to FEAT to TEST, with no @Refines intermediates — is a package where the Requirement stratum is flat. Either the package's policies are genuinely flat, or the author has not yet done the decomposition work.

This package is in an intermediate state. @Refines exists in the DSL (chapter 04 demonstrates it) and a handful of Requirements carry it — the Style adapter Requirements refine the default style Requirement — but most Requirements are currently leaves in the refinement graph. The chapter on the @Refines relation (chapter 15) will make that case directly; here it is enough to observe that a future version of the global diagram will have longer chains through the left column, and the diagram above should be read as a snapshot of the current state of decomposition, not a claim that the current state is final.

A useful discipline: when adding a new Requirement, ask does this refine an existing Requirement, or does it stand alone? If it refines, the parent edge makes the chain longer. If it stands alone, the Requirement taxonomy widens. Both are valid; neither is automatic. The diagram will show the shape either way, and the shape is evidence of the author's taxonomic choices.

Running-example recap📋

FEATURE-TRACE-EXPLORER-TUI appeared explicitly in Diagram 4 (TUI/visual cluster), with its direct Requirement parents REQ-DISCOVERABLE-TRACEABILITY drawn in and REQ-DOG-FOOD shown as a dashed external super-connector. The third parent, REQ-PARALLEL-DELIVERABLE, was suppressed in that slice because it is a package-wide scaffold constraint.

In the global diagram (12.1) the same Feature appears as one of twenty-five middle-column nodes, with @Satisfies edges coming in from three Requirement nodes and a @FeatureTest edge going out to the compressed TESTS node. At that scale its individuality is lost — which is correct. The whole point of the global diagram is to show the whole, not the parts.

In the dog-food cluster (12.2) it appears as one of 22 satisfier Features of REQ-DOG-FOOD, indistinguishable in shape from the other 21 — precisely the point the cluster makes: the dog-food policy applies uniformly across producing Features.

Three diagrams, three zoom levels, one Feature. The Feature is the same in all three; what changes is what the diagram is for. This is the point of rendering the graph seven ways rather than once.

Related Reading📋

• Chapter 06 — The Compliance Scanner as a Feature — reads the scanner as a Feature that consumes the diagrams this chapter renders; gives the algorithms behind the cluster diagnostics.
• Chapter 07 — The Mermaid Renderer — the Feature whose output this chapter is made of; the graph-to-mermaid transformer that turns the in-memory trace structure into the mermaid text above.
• Chapter 13 — Quality Gates and Compliance — the scanner's gate emitting rules, satisfaction-without-verification diagnostics, per-Requirement fan-out budgets; the next chapter after this one.
• Chapter 14 — The New-Command Feature in Depth — the seven-Requirement showcase Feature that appeared in Diagram 6; walks the wizard and shows how the seven parents shape the prompts.
• Chapter 18 — The Meta-Circle, in Diagrams — later chapter that draws the dog-food meta-circle as a closed loop through the diagrams this chapter opens; the complement to diagram 12.2.

Previous: Chapter 11 — Style Deep Dive: EARS, Agile, Kanban

Next: Chapter 13 — Quality Gates and Compliance