<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-07-26-1-drg-edges-are-the-canonical-relationship-authority/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-07-26-1-drg-edges-are-the-canonical-relationship-authority/</id>
  <title>ADR: DRG edges are the canonical artefact-relationship authority; inline `references:` blocks are pre-DRG residue to be migrated and retired</title>
  <updated>2026-07-26T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-07-26-1-drg-edges-are-the-canonical-relationship-authority/"/>
  <summary>DRG edges become the only artefact-relationship vocabulary; 559 inline `references:` entries migrate to `*.graph.yaml` fragments and the field closes to relationship growth.</summary>
  <content type="html">&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-07-26&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Operator (Stijn Dejongh), who identified the drift directly: &lt;em&gt;“the doctrine
schema and assets predate the DRG canonical system; the yaml files often contain references
to other artefacts that are to be migrated to DRG edges/relationships.”&lt;/em&gt; Recorded during
the #2935 doctrine-authoring session, after the finding invalidated an in-flight “fix”.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; raised while authoring the test-quality doctrine series
(&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2935&quot;&gt;#2935&lt;/a&gt;) on PR
&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/pull/2936&quot;&gt;#2936&lt;/a&gt;; triggered by an
asset-support finding on &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/pull/2918&quot;&gt;#2918&lt;/a&gt;.
Continues the excision begun by mission &lt;code dir=&quot;auto&quot;&gt;excise-doctrine-curation-and-inline-references-01KP54J6&lt;/code&gt;.
Sibling ADRs: &lt;a href=&quot;/adr/3.x/2026-07-18-1-charter-yaml-authoring-authority-and-extractor-retirement/&quot;&gt;2026-07-18-1&lt;/a&gt;
(the authoring-authority + extractor-retirement pattern this ADR applies to the doctrine layer),
&lt;a href=&quot;/adr/3.x/2026-07-22-1-gate-binding-content-vs-relationship/&quot;&gt;2026-07-22-1&lt;/a&gt; (content-vs-relationship
principle), &lt;a href=&quot;/adr/3.x/2026-07-21-1-in-tension-with-drg-edge/&quot;&gt;2026-07-21-1&lt;/a&gt; (tension relations).&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;The doctrine artifact &lt;strong&gt;schemas&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;src/doctrine/schemas/*.schema.yaml&lt;/code&gt;) and the &lt;strong&gt;assets&lt;/strong&gt;
layout predate the Doctrine Relationship Graph (DRG). They were designed when an artefact
declared its own relationships inline, in its own YAML body. The DRG later introduced typed,
traversable edges as the way relationships are modelled. Both surfaces are still live, and
the doctrine layer therefore has &lt;strong&gt;two authorities for one concept&lt;/strong&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Surface A — inline &lt;code dir=&quot;auto&quot;&gt;references:&lt;/code&gt; blocks.&lt;/strong&gt; 139 built-in artifact YAMLs carry a
&lt;code dir=&quot;auto&quot;&gt;references:&lt;/code&gt; list of &lt;code dir=&quot;auto&quot;&gt;{type, id, when?}&lt;/code&gt; entries. Four schemas (&lt;code dir=&quot;auto&quot;&gt;directive&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;paradigm&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;procedure&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tactic&lt;/code&gt;) bless this shape via a &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;kind&gt;_reference&lt;/code&gt; definition whose &lt;code dir=&quot;auto&quot;&gt;type&lt;/code&gt;
property carries a &lt;strong&gt;hand-copied enum of doctrine kinds&lt;/strong&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Surface B — DRG edges.&lt;/strong&gt; 14 per-kind &lt;code dir=&quot;auto&quot;&gt;*.graph.yaml&lt;/code&gt; fragments under &lt;code dir=&quot;auto&quot;&gt;src/doctrine/&lt;/code&gt;
holding ~774 typed edges over the &lt;code dir=&quot;auto&quot;&gt;Relation&lt;/code&gt; vocabulary
(&lt;code dir=&quot;auto&quot;&gt;requires&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;suggests&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;scope&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;refines&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;rejects&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;in_tension_with&lt;/code&gt;/…).&lt;/p&gt;
&lt;p&gt;Crucially, &lt;strong&gt;B is not independent of A&lt;/strong&gt;: every fragment is stamped
&lt;code dir=&quot;auto&quot;&gt;generated_by: drg-migration-v1&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;drg/migration/extractor.py&lt;/code&gt; &lt;em&gt;derives&lt;/em&gt; edges by walking
the inline &lt;code dir=&quot;auto&quot;&gt;references:&lt;/code&gt; blocks (the reference passes at lines ~387–636), supplemented by
&lt;code dir=&quot;auto&quot;&gt;drg/migration/hand_authored_overlay.py&lt;/code&gt; for edges that have no inline source. So the inline
blocks remain the de-facto authoring surface for most of the graph, and the graph is largely a
&lt;strong&gt;build output&lt;/strong&gt; of the surface it was meant to replace.&lt;/p&gt;
&lt;p&gt;A partial excision already landed: mission
&lt;code dir=&quot;auto&quot;&gt;excise-doctrine-curation-and-inline-references-01KP54J6&lt;/code&gt; hard-rejects the &lt;em&gt;scalar&lt;/em&gt; inline
ref fields (&lt;code dir=&quot;auto&quot;&gt;tactic_refs&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;styleguide_refs&lt;/code&gt;, …) with &lt;code dir=&quot;auto&quot;&gt;InlineReferenceRejectedError&lt;/code&gt;. The
&lt;strong&gt;structured&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;references:&lt;/code&gt; block survived that pass — the residue this ADR addresses.&lt;/p&gt;
&lt;p&gt;Four consequences of the split were observed empirically, not theorised:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;The duplicated kind enum has already drifted.&lt;/strong&gt; All four schema copies omit &lt;code dir=&quot;auto&quot;&gt;asset&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;glossary_pack&lt;/code&gt;; the &lt;code dir=&quot;auto&quot;&gt;tactic&lt;/code&gt; copy has drifted further still, additionally missing
&lt;code dir=&quot;auto&quot;&gt;agent_profile&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;mission_step_contract&lt;/code&gt;. So &lt;code dir=&quot;auto&quot;&gt;ArtifactKind.ASSET&lt;/code&gt; — a first-class kind
with shipped built-in artifacts — &lt;strong&gt;cannot be named from an artefact body at all&lt;/strong&gt;. On
#2918 this read as an “asset support is not end-to-end” bug. It is not: it is the legacy
surface correctly refusing to grow. Widening the enum would have entrenched the second
authority, and was abandoned mid-change once the operator named the drift.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The migration instruction the system prints is unfollowable.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;InlineReferenceRejectedError&lt;/code&gt;
tells operators to &lt;em&gt;“add edge {source, target, relation: requires} to &lt;code dir=&quot;auto&quot;&gt;src/doctrine/graph.yaml&lt;/code&gt;”&lt;/em&gt; —
but mission #2680 sharded that monolith into per-kind fragments and &lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/graph.yaml&lt;/code&gt;
no longer exists&lt;/strong&gt;. &lt;strong&gt;18 files&lt;/strong&gt; repeat the stale path — &lt;code dir=&quot;auto&quot;&gt;.py&lt;/code&gt; models, errors and exceptions,
four READMEs, a shipped tactic, and the brownfield paradigm’s own notes. The one piece of
guidance pointing from the legacy surface to the canonical one points at nothing. (An earlier
revision said “ten”; measured, it is 18. Note some mentions are &lt;em&gt;deliberate&lt;/em&gt; — this ADR and the
&lt;code dir=&quot;auto&quot;&gt;doctrine-daphne&lt;/code&gt; profile name the path in order to forbid it — so a naive grep gate would
false-red, and &lt;code dir=&quot;auto&quot;&gt;.kittify/doctrine/graph.yaml&lt;/code&gt; is a live project-tier path that must not be
swept in.)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The inline shape cannot express the modern vocabulary.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;references:&lt;/code&gt; carries only
&lt;code dir=&quot;auto&quot;&gt;type&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;id&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;when&lt;/code&gt; — there is no relation field. Every relation richer than “related to”
(&lt;code dir=&quot;auto&quot;&gt;refines&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;rejects&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;in_tension_with&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;reconciles_tension&lt;/code&gt;) is &lt;em&gt;inexpressible&lt;/em&gt; inline
and must be hand-authored as an edge. Measured on the shipped graph: &lt;code dir=&quot;auto&quot;&gt;suggests&lt;/code&gt; 332,
&lt;code dir=&quot;auto&quot;&gt;requires&lt;/code&gt; 259, &lt;code dir=&quot;auto&quot;&gt;scope&lt;/code&gt; 157, &lt;code dir=&quot;auto&quot;&gt;rejects&lt;/code&gt; 8, &lt;code dir=&quot;auto&quot;&gt;instantiates&lt;/code&gt; 8, &lt;code dir=&quot;auto&quot;&gt;specializes_from&lt;/code&gt; 4,
&lt;code dir=&quot;auto&quot;&gt;reconciles_tension&lt;/code&gt; 3, &lt;code dir=&quot;auto&quot;&gt;in_tension_with&lt;/code&gt; 2, &lt;code dir=&quot;auto&quot;&gt;applies&lt;/code&gt; 1, and &lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;refines&lt;/code&gt; 0&lt;/strong&gt; — first-class
since #2079, never yet exercised in a built-in fragment.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Relationship semantics get flattened on the way in.&lt;/strong&gt; Because an inline entry has no
relation, the extractor must &lt;em&gt;infer&lt;/em&gt; one per kind (e.g. &lt;code dir=&quot;auto&quot;&gt;_relation_for_procedure_reference&lt;/code&gt;).
The authored intent and the resulting edge type are decided in different files.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Single canonical authority&lt;/strong&gt; (charter governing principle) — one owning source per
surface. Two relationship authorities is the exact smell the principle names, and
“reconcile/extend the existing authority” means extending the DRG, not the residue.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Content vs relationship&lt;/strong&gt; (ADR 2026-07-22-1) — an artefact’s YAML body owns its
&lt;em&gt;content&lt;/em&gt;; relationships between artefacts are &lt;em&gt;edges&lt;/em&gt;. The inline block is a body field
doing a relationship’s job.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No legacy compat branches in resolvers&lt;/strong&gt; (ADR 2026-07-01-1) — the answer to a
legacy surface is retirement on a migration path, not indefinite parity.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Authoring-authority + extractor retirement&lt;/strong&gt; (ADR 2026-07-18-1) — the doctrine layer
faces structurally the same call the charter layer already made: stop deriving canonical
structure from a legacy authoring surface, and retire the extractor that does it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Intent dominates over capability&lt;/strong&gt; — fix the tooling to serve the intended model; do not
relabel artefacts, or widen a deprecated schema, to fit what currently works.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option 1 (chosen)&lt;/strong&gt; — Pin DRG edges as the sole relationship authority; fix the stale
migration hint; &lt;strong&gt;and migrate all 559 relationship entries now&lt;/strong&gt;, retiring &lt;strong&gt;all&lt;/strong&gt; edge
production behind a structured-diff proof (see the Amendment).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2&lt;/strong&gt; — Keep both surfaces, and bring the inline surface to full parity (widen the
four kind enums, add a &lt;code dir=&quot;auto&quot;&gt;relation:&lt;/code&gt; field to &lt;code dir=&quot;auto&quot;&gt;references:&lt;/code&gt;, keep deriving the graph).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3 (initially chosen, then withdrawn)&lt;/strong&gt; — Pin the direction and &lt;em&gt;freeze&lt;/em&gt; the inline
surface, but defer the migration and the pass retirement to follow-up work.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4&lt;/strong&gt; — Declare the inline blocks canonical and treat the fragments as pure build
output (invert the other way).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option: 1.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;The end state this ADR pins:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;DRG edges are the single canonical authority for artefact→artefact relationships.&lt;/strong&gt;
Relation semantics live in &lt;code dir=&quot;auto&quot;&gt;doctrine.drg.models.Relation&lt;/code&gt;. No schema, body field, or
sidecar may declare a second relationship vocabulary.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The inline &lt;code dir=&quot;auto&quot;&gt;references:&lt;/code&gt; block stops carrying artefact relationships.&lt;/strong&gt; Every one of the
559 relationship-bearing entries migrates to a hand-authored edge in the per-kind
&lt;code dir=&quot;auto&quot;&gt;*.graph.yaml&lt;/code&gt; fragment, in this mission. The field survives only for raw non-artefact
material (14 entries), and is closed to growth in every case: no new artefact adds a
relationship entry.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The four &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;kind&gt;_reference.type&lt;/code&gt; enums are frozen, not fixed.&lt;/strong&gt; A kind that cannot be
named inline is &lt;em&gt;correct&lt;/em&gt; behaviour, not a defect. Specifically: &lt;strong&gt;do not add &lt;code dir=&quot;auto&quot;&gt;asset&lt;/code&gt; (or
any kind) to those enums&lt;/strong&gt; — the pull request that tries is repeating the mistake this ADR
exists to stop. Assets are referenced via &lt;code dir=&quot;auto&quot;&gt;requires&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;suggests&lt;/code&gt; edges only.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The migration hint must point at the real layout.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;InlineReferenceRejectedError&lt;/code&gt; and
the ~10 sites repeating &lt;code dir=&quot;auto&quot;&gt;src/doctrine/graph.yaml&lt;/code&gt; are corrected to the sharded per-kind
fragment path (&lt;code dir=&quot;auto&quot;&gt;src/doctrine/&amp;#x3C;kind&gt;.graph.yaml&lt;/code&gt;). Guidance that cannot be followed is
worse than none.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The extractor’s reference passes are retired in this mission&lt;/strong&gt;, following ADR 2026-07-18-1:
migrate each file’s relationship entries into hand-authored edges (preserving the
per-kind inferred relation &lt;em&gt;explicitly&lt;/em&gt;, so authored intent and edge type stop living in
different files), then delete the reference-extraction passes so fragments are authored,
not derived. Sequenced so the proof comes first: commit the baseline manifest → migrate →
assert the structured diff → prove pass deletion by observed RED (in-process ablation).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;New doctrine artefacts are edge-native from birth.&lt;/strong&gt; An artefact authored today declares
zero inline references and all its relationships as edges.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;scope-the-migration-happens-now-in-this-mission&quot;&gt;Scope: the migration happens now, in this mission&lt;/h3&gt;
&lt;p&gt;An earlier revision of this ADR deferred the migration of the inline blocks to follow-up work,
on the grounds that it is wide and needs its own idempotency proof. &lt;strong&gt;That deferral was
withdrawn by the operator&lt;/strong&gt;, and the reasoning is worth recording because it generalises:&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;We are working on the &lt;code dir=&quot;auto&quot;&gt;3.2.6&lt;/code&gt;-unreleasable issues, and have been extreme boyscouting for over
a week. We will continue this practice and philosophy until 3.2.6 is stable, and we covered as
many of the existing “ticking timebombs” as we can. Similar to how we stopped greenwashing, we
desperately need to stop deferring structural issues.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;The deferral was also a weak argument on its own terms: “it needs a proof first” is a reason to
&lt;strong&gt;build the proof&lt;/strong&gt;, not to postpone.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Measured composition&lt;/strong&gt; (derived, never hand-counted — run
&lt;code dir=&quot;auto&quot;&gt;PYTHONPATH=src python scripts/doctrine/inline_reference_inventory.py&lt;/code&gt;; the FR-015 gate imports
that module rather than restating a literal). &lt;strong&gt;171 files carry 761 entries across six inline
surfaces&lt;/strong&gt;, in three dispositions:&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Disposition&lt;/th&gt;&lt;th&gt;Entries&lt;/th&gt;&lt;th&gt;Surfaces&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;MIGRATE&lt;/strong&gt; — denotes an artefact→artefact relationship&lt;/td&gt;&lt;td&gt;&lt;strong&gt;559&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;references&lt;/code&gt; 414 · &lt;code dir=&quot;auto&quot;&gt;steps[].references&lt;/code&gt; 15 · &lt;code dir=&quot;auto&quot;&gt;context-sources.directives&lt;/code&gt; 67 · &lt;code dir=&quot;auto&quot;&gt;directive_refs&lt;/code&gt; 34 · &lt;code dir=&quot;auto&quot;&gt;tactic-references&lt;/code&gt; 29&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;GOVERNANCE&lt;/strong&gt; — zero DRG edges; seeds the charter closure. &lt;strong&gt;Do not migrate&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;188&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;directive-references&lt;/code&gt; 68 · &lt;code dir=&quot;auto&quot;&gt;context-sources.{additional,doctrine-layers,tactics}&lt;/code&gt; 120&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;RAW_MATERIAL&lt;/strong&gt; — path strings to non-artefact files. &lt;strong&gt;Keep&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;14&lt;/td&gt;&lt;td&gt;enumerated &lt;code dir=&quot;auto&quot;&gt;(file, path)&lt;/code&gt; allowlist&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;An earlier revision of this ADR said 414, in six places. That figure was the top-level
&lt;code dir=&quot;auto&quot;&gt;references:&lt;/code&gt; row alone&lt;/strong&gt; — correct as far as it went, mistaken as a total. It missed 15
step-level entries (in 7 tactic files, &lt;strong&gt;4 of which carry no top-level block at all&lt;/strong&gt;, so a
file-driven migration would never have opened them) and it missed five sibling surfaces entirely,
including &lt;code dir=&quot;auto&quot;&gt;directive_refs&lt;/code&gt;, which mints 34 real edges and is schema-blessed in 12 paradigms.&lt;/p&gt;
&lt;p&gt;The &lt;strong&gt;GOVERNANCE&lt;/strong&gt; row is the load-bearing correction. &lt;code dir=&quot;auto&quot;&gt;directive-references&lt;/code&gt; produces no DRG
edges but is the seed set for the entire charter governance closure, so sweeping it would empty
every profile-routed prompt’s directives while byte-identical fragments, golden counts, and a
zero-structured-entries gate all stayed green. That is this ADR’s own defect class — silence —
reproduced by its remediation, and it is why the scope must name surfaces rather than say “all
inline relationships”.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The &lt;code dir=&quot;auto&quot;&gt;references:&lt;/code&gt; field is not deleted outright.&lt;/strong&gt; 14 entries point at raw reference material —
&lt;code dir=&quot;auto&quot;&gt;src/doctrine/skills/README.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;docs/adr/...&lt;/code&gt;, Divio templates, an action &lt;code dir=&quot;auto&quot;&gt;index.yaml&lt;/code&gt;. Those
denote no artefact relationship, produce no edge today (&lt;code dir=&quot;auto&quot;&gt;_resolve_path_ref&lt;/code&gt; fails closed on
them by design, NFR-003), and the doctrine README explicitly sanctions carrying raw reference
material. Forcing them into edges would invent relationships that do not exist — the same
category error as widening the kind enum.&lt;/p&gt;
&lt;p&gt;The end state is therefore &lt;strong&gt;not&lt;/strong&gt; “no &lt;code dir=&quot;auto&quot;&gt;references:&lt;/code&gt; blocks” but the sharper invariant:&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;Zero MIGRATE-class entries across all five migrating surfaces. A &lt;code dir=&quot;auto&quot;&gt;references:&lt;/code&gt; list may contain
only plain path strings to &lt;strong&gt;non-artefact&lt;/strong&gt; material. The 188 GOVERNANCE entries are untouched.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;This is gateable, and it is what the confirmation criteria below assert.&lt;/p&gt;
&lt;h3 id=&quot;amendment-2026-07-26--three-decisions-taken-after-this-adr-was-first-accepted&quot;&gt;Amendment (2026-07-26) — three decisions taken after this ADR was first accepted&lt;/h3&gt;
&lt;p&gt;This ADR was Accepted before three operator rulings that change its scope and its proof. They are
recorded here because &lt;strong&gt;this ADR, not a spec table, is the citable record&lt;/strong&gt; (DIRECTIVE_003), and an
implementer reading the original text would have built the wrong proof against a scope 26% too
small.&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Full retirement, not reference passes only.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;generate_graph&lt;/code&gt; has nine steps; the reference
passes are one. The others produce ~215 further edges — 157 &lt;code dir=&quot;auto&quot;&gt;scope&lt;/code&gt; from action indexes, 21
mission-type projection, 8 template instantiation, 13 from a &lt;em&gt;second&lt;/em&gt; hardcoded Python registry
(&lt;code dir=&quot;auto&quot;&gt;_CURATED_ARTIFACT_EDGES&lt;/code&gt;, holding all four &lt;code dir=&quot;auto&quot;&gt;specializes_from&lt;/code&gt;), plus a calibrator that
&lt;strong&gt;synthesises&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;scope&lt;/code&gt; edges from the inequality &lt;code dir=&quot;auto&quot;&gt;|review| ≥ 0.80 × |implement|&lt;/code&gt;. &lt;strong&gt;All 774
edges become authored.&lt;/strong&gt; Node discovery stays derived; the extractor becomes a node minter plus
validator. Both Python edge registries are absorbed and deleted — otherwise the surface count
holds flat at 11 while claiming consolidation.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The proof is a structured diff, not byte-identity.&lt;/strong&gt; Byte-identity was the original invariant
and it is withdrawn: preserving the 68 procedure rationales and the 219 reference labels breaks
it &lt;em&gt;by design&lt;/em&gt;, and a byte proof would therefore pressure the migrator into &lt;strong&gt;deleting authored
content to make the proof pass&lt;/strong&gt;. The invariant is now “the regenerated graph differs from the
committed pre-migration baseline manifest only by the enumerated, ledgered deviations”. Two
further corrections ride along: the baseline must be a &lt;strong&gt;committed&lt;/strong&gt; manifest written before any
YAML is edited (otherwise “regenerate and compare” degenerates into
&lt;code dir=&quot;auto&quot;&gt;regenerate(tree) == regenerate(tree)&lt;/code&gt;, a tautology of determinism blind to content loss), and
pass deletion is proven by an &lt;strong&gt;observed RED via in-process ablation&lt;/strong&gt;, because as a git
sequence it is unachievable — the extractor must be alive as the migration oracle, and once the
authored tier carries the edges the deletion is a no-op again.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Labels move to &lt;code dir=&quot;auto&quot;&gt;aliases&lt;/code&gt; on artefacts, not &lt;code dir=&quot;auto&quot;&gt;DRGEdge.label&lt;/code&gt;.&lt;/strong&gt; Measured: the 219 label
occurrences collapse to &lt;strong&gt;102 distinct artefacts&lt;/strong&gt;, and the 8 targets carrying more than one
label are genuine synonym sets. They were never edge metadata — they are artefact names repeated
at every pointer. &lt;code dir=&quot;auto&quot;&gt;aliases: list[str]&lt;/code&gt; on the artefact deduplicates them, merges the 8
disagreements into legitimate alias lists, enables grep now and semantic search later, and
removes a &lt;code dir=&quot;auto&quot;&gt;DRGEdge&lt;/code&gt; schema change with a six-consumer ripple.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Sibling: &lt;a href=&quot;/adr/3.x/2026-07-26-3-impacts-edge-subsumes-in-tension-with/&quot;&gt;ADR 2026-07-26-3&lt;/a&gt; adds
&lt;code dir=&quot;auto&quot;&gt;Relation.IMPACTS&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;is_symmetric&lt;/code&gt; to the same edge model. &lt;code dir=&quot;auto&quot;&gt;is_symmetric&lt;/code&gt; is expanded &lt;strong&gt;by the
generator&lt;/strong&gt;, so the authored tier holds one edge and the cache holds both directions — consistent
with the source-plus-cache split this ADR’s amendment relies on.&lt;/p&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;One authority for relationships; the drift class (four hand-copied enums) stops mattering
because the surface they guard is closed rather than widened.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;#2918&lt;/code&gt; “asset support” finding is correctly reclassified from &lt;em&gt;bug&lt;/em&gt; to &lt;em&gt;the deprecated
surface working as intended&lt;/em&gt;, which retires an entire strand of would-be remediation.&lt;/li&gt;
&lt;li&gt;Edge-native authoring gets the full relation vocabulary — including &lt;code dir=&quot;auto&quot;&gt;refines&lt;/code&gt;, which the
inline shape could never express.&lt;/li&gt;
&lt;li&gt;Operators receive a migration hint that names a file that exists.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Authoring relationships is now a two-file edit (artefact body + graph fragment), which is
less locally-obvious than an inline list. Accepted: it is the cost of typed relations.&lt;/li&gt;
&lt;li&gt;The migration touches 139 artefact files and the generated fragments in one change — a large
mechanical diff inside an already-wide PR. Mitigated by the structured-diff invariant plus the
inventory gate, which together make the migration verifiable by assertion rather than by
reviewing 559 individual edge moves.&lt;/li&gt;
&lt;li&gt;The 14 surviving raw-material path entries mean &lt;code dir=&quot;auto&quot;&gt;references:&lt;/code&gt; does not disappear entirely, so
a reader must know the distinction between “a path to a doc” and “a relationship”. The gate
encodes it, and this ADR explains it.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;hand_authored_overlay.py&lt;/code&gt; becomes the &lt;em&gt;primary&lt;/em&gt; authoring path rather than a supplement;
its name will read oddly once extraction retires and should be revisited then.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;Relation&lt;/code&gt; vocabulary itself is untouched by this ADR.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;immediate-application-to-2935-the-mission-that-surfaced-this&quot;&gt;Immediate application to #2935 (the mission that surfaced this)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The artefact-series proposal’s edge-based design is &lt;strong&gt;correct by construction&lt;/strong&gt; — it already
routes asset references through &lt;code dir=&quot;auto&quot;&gt;requires&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;suggests&lt;/code&gt; edges rather than a &lt;code dir=&quot;auto&quot;&gt;type: asset&lt;/code&gt;
body field. No redesign needed.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;DIRECTIVE_041&lt;/code&gt; intent split must &lt;strong&gt;not&lt;/strong&gt; add inline references. &lt;code dir=&quot;auto&quot;&gt;041&lt;/code&gt; is itself one of
the legacy carriers (5 structured entries), so those five migrate to edges with the rest;
the new &lt;code dir=&quot;auto&quot;&gt;DIRECTIVE_041 --refines--&gt; paradigm:tests-as-scaffold-not-friction&lt;/code&gt; link is
authored as an edge from the start. Note the ordering constraint: because editing &lt;code dir=&quot;auto&quot;&gt;041&lt;/code&gt; is
its own reviewed change, do its migration &lt;em&gt;with&lt;/em&gt; the intent split rather than as an
anonymous line in the bulk pass.&lt;/li&gt;
&lt;li&gt;That edge is the &lt;strong&gt;first &lt;code dir=&quot;auto&quot;&gt;refines&lt;/code&gt; edge in any built-in fragment&lt;/strong&gt; (histogram above: 0).
Round-trip verification through the org→DRG bridge on regeneration is therefore a real
risk item, not a formality — #2079 fixed a silent &lt;code dir=&quot;auto&quot;&gt;refines&lt;/code&gt;→&lt;code dir=&quot;auto&quot;&gt;applies&lt;/code&gt; downgrade, and
nothing built-in has exercised the fix.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Zero&lt;/strong&gt; structured &lt;code dir=&quot;auto&quot;&gt;{type, id}&lt;/code&gt; reference entries remain anywhere under &lt;code dir=&quot;auto&quot;&gt;src/doctrine/&lt;/code&gt;, and
&lt;strong&gt;zero&lt;/strong&gt; remaining path-string entries resolve to a built-in artefact via &lt;code dir=&quot;auto&quot;&gt;_resolve_path_ref&lt;/code&gt;.
The only surviving entries are raw non-artefact paths. Enforced by a gate, not by inspection.&lt;/li&gt;
&lt;li&gt;The regenerated graph differs from the &lt;strong&gt;committed&lt;/strong&gt; pre-migration baseline manifest only by
the enumerated, ledgered deviations (preserved rationales and labels; any relation changed by
review). Every other node, edge, relation, &lt;code dir=&quot;auto&quot;&gt;when&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;reason&lt;/code&gt; is unchanged. Completeness is
asserted separately by the inventory gate — the diff proves preservation, not completion.&lt;/li&gt;
&lt;li&gt;The four &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;kind&gt;_reference.type&lt;/code&gt; enums are byte-identical to their pre-ADR state (no kind
added), and a comment in each schema marks the definition frozen with a pointer here.&lt;/li&gt;
&lt;li&gt;No source site tells an operator to edit &lt;code dir=&quot;auto&quot;&gt;src/doctrine/graph.yaml&lt;/code&gt;; the rejection-hint
regex and its schema fixture name the per-kind fragment path.&lt;/li&gt;
&lt;li&gt;During the migration, at every increment: regenerating fragments after migrating a file produces a
&lt;strong&gt;zero diff&lt;/strong&gt;, proving the hand-authored edge preserved the previously-inferred relation
before any extraction pass is deleted.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-1--pin-edges-as-canonical-and-complete-the-migration-now-chosen&quot;&gt;Option 1 — Pin edges as canonical and complete the migration now (chosen)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; ends the two-authority condition outright rather than documenting it; the doctrine
layer has exactly one relationship authority when the PR lands, so no reader has to hold
“which surface is live?” in their head. The structured-diff invariant plus the inventory gate make
a 559-entry mechanical migration &lt;em&gt;cheaper to verify than to review&lt;/em&gt; — assertions cover every
entry. Deleting the extraction passes removes the mechanism that keeps re-deriving the legacy
surface, so the class cannot regrow. Also reclassifies the #2918 finding and unblocks #2935.
&lt;strong&gt;Cons:&lt;/strong&gt; a large mechanical diff inside an already-wide PR; relationship authoring becomes a
two-file edit; &lt;code dir=&quot;auto&quot;&gt;references:&lt;/code&gt; survives for raw material, so the field does not vanish entirely.&lt;/p&gt;
&lt;h3 id=&quot;option-2--full-parity-for-the-inline-surface&quot;&gt;Option 2 — Full parity for the inline surface&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; locally-obvious authoring; no migration debt; the #2918 finding becomes a real fix.
&lt;strong&gt;Cons:&lt;/strong&gt; entrenches two authorities permanently and &lt;em&gt;grows&lt;/em&gt; the one that is deprecated;
requires adding a &lt;code dir=&quot;auto&quot;&gt;relation:&lt;/code&gt; field, i.e. re-implementing the &lt;code dir=&quot;auto&quot;&gt;Relation&lt;/code&gt; vocabulary in schema
form — a second authority for edge semantics. Directly contradicts single-canonical-authority
and ADR 2026-07-01-1. Rejected.&lt;/p&gt;
&lt;h3 id=&quot;option-3--pin-the-direction-defer-the-migration-initially-chosen-then-withdrawn&quot;&gt;Option 3 — Pin the direction, defer the migration (initially chosen, then withdrawn)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; narrow change now; the wide mechanical migration sits behind its own proof and its
own review; the P0 and the #2935 series land sooner.
&lt;strong&gt;Cons — and these carried the decision:&lt;/strong&gt; it leaves two readable surfaces live and the
extraction passes still &lt;em&gt;actively deriving&lt;/em&gt; the deprecated one, so the class keeps regenerating
itself while the ADR asserts it is closed. “Frozen” without enforcement is the same posture that
produced nine dead files and the #2918 layout error. The stated blocker — “it needs an
idempotency proof first” — is an argument for building the proof, which turned out to be a
single byte-comparison, not a research project.&lt;/p&gt;
&lt;p&gt;Withdrawn by the operator on the explicit ground that deferring structural work is the same
failure mode as greenwashing a test: it converts a known defect into an invisible one and
relies on a future maintainer having the same context. While &lt;code dir=&quot;auto&quot;&gt;3.2.6&lt;/code&gt; is unreleasable, the
standing posture is to clear ticking timebombs in the mission that finds them.&lt;/p&gt;
&lt;h3 id=&quot;option-4--declare-inline-blocks-canonical-fragments-are-pure-build-output&quot;&gt;Option 4 — Declare inline blocks canonical; fragments are pure build output&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; matches how much of the graph is &lt;em&gt;actually&lt;/em&gt; produced today; single authoring site.
&lt;strong&gt;Cons:&lt;/strong&gt; the inline shape provably cannot express the modern relation vocabulary
(&lt;code dir=&quot;auto&quot;&gt;refines&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;rejects&lt;/code&gt;/tension), so it would cap the DRG at its weakest historical expressiveness
and require inferring relations forever. Rejected as the wrong direction of travel.&lt;/p&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Inline-ref excision precedent: mission
&lt;code dir=&quot;auto&quot;&gt;excise-doctrine-curation-and-inline-references-01KP54J6&lt;/code&gt;; negative fixtures in
&lt;code dir=&quot;auto&quot;&gt;tests/doctrine/test_inline_ref_rejection.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Extraction passes: &lt;code dir=&quot;auto&quot;&gt;src/doctrine/drg/migration/extractor.py&lt;/code&gt;; overlay:
&lt;code dir=&quot;auto&quot;&gt;src/doctrine/drg/migration/hand_authored_overlay.py&lt;/code&gt;; fragment sharding: mission #2680.&lt;/li&gt;
&lt;li&gt;Relation vocabulary: &lt;code dir=&quot;auto&quot;&gt;src/doctrine/drg/models.py::Relation&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Test-quality series proposal: &lt;code dir=&quot;auto&quot;&gt;docs/plans/doctrine/test_quality/doctrine-artefact-series-proposal.md&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
