<?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-2-doctrine-artefact-pack-layout-convention/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-07-26-2-doctrine-artefact-pack-layout-convention/</id>
  <title>ADR: doctrine artefacts live at `&lt;type&gt;/&lt;pack&gt;/[&lt;category&gt;/]&lt;name&gt;` — misplacement is an error, not invisibility</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-2-doctrine-artefact-pack-layout-convention/"/>
  <summary>Doctrine artefacts must sit at `&lt;type&gt;/&lt;pack&gt;/[&lt;category&gt;/]&lt;name&gt;`; a file placed directly under `&lt;type&gt;/` is a loud error rather than silently invisible to the loader.</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 named both the convention and its future form:
&lt;em&gt;“I would expect it to be &lt;code dir=&quot;auto&quot;&gt;assets/built-in/audiences&lt;/code&gt;, as per &lt;code dir=&quot;auto&quot;&gt;type/pack/&amp;#x3C;name&gt;&lt;/code&gt; repository
convention. After extract of our doctrine packs to a secondary repository (future scope),
that would become &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;pack id&gt;/type/name&lt;/code&gt;.”&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; surfaced while triaging an asset-discovery finding on
&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/pull/2918&quot;&gt;#2918&lt;/a&gt; during the #2935
doctrine-authoring session (PR &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/pull/2936&quot;&gt;#2936&lt;/a&gt;).
Sibling ADR &lt;a href=&quot;/adr/3.x/2026-07-26-1-drg-edges-are-the-canonical-relationship-authority/&quot;&gt;2026-07-26-1&lt;/a&gt;
covers the &lt;em&gt;relationship&lt;/em&gt; axis of the same “doctrine layer predates its own canonical model”
problem; this one covers the &lt;em&gt;physical layout&lt;/em&gt; axis.&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;Doctrine artefacts resolve from a three-part path: the &lt;strong&gt;type&lt;/strong&gt; (plural kind directory), the
&lt;strong&gt;pack&lt;/strong&gt; (provenance layer), and the artefact &lt;strong&gt;name&lt;/strong&gt;, with an optional &lt;strong&gt;category&lt;/strong&gt; grouping
in between. The shipped built-in tree follows it — &lt;code dir=&quot;auto&quot;&gt;tactics/built-in/testing/&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;toolguides/built-in/system_tools/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;styleguides/built-in/writing/&lt;/code&gt; — and both resolvers
depend on it:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the per-kind repositories scan &lt;strong&gt;only&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;type&gt;/built-in&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;_default_builtin_dir()&lt;/code&gt; →
&lt;code dir=&quot;auto&quot;&gt;Path(__file__).parent / &quot;built-in&quot;&lt;/code&gt;);&lt;/li&gt;
&lt;li&gt;DRG node discovery (&lt;code dir=&quot;auto&quot;&gt;_discover_built_in_artifact_nodes&lt;/code&gt;) scans &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;plural&gt;/built-in&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;rglob&lt;/code&gt;s beneath it, so categories &lt;em&gt;inside&lt;/em&gt; the pack layer are found automatically.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Nothing enforces the layout.&lt;/strong&gt; An artefact placed outside &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;type&gt;/&amp;#x3C;pack&gt;/&lt;/code&gt; is not rejected —
it is simply never loaded, never registered as a DRG node, and therefore never resolvable and
never a legal edge target. The failure mode is &lt;strong&gt;silent invisibility&lt;/strong&gt;, which is the worst
available outcome: the file looks authored, passes review, and does nothing.&lt;/p&gt;
&lt;p&gt;Three classes of evidence, all found by inspection rather than by any gate:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;#2918 inverted pack and category.&lt;/strong&gt; It ships assets at &lt;code dir=&quot;auto&quot;&gt;assets/audiences/built-in/*.asset.yaml&lt;/code&gt;
instead of &lt;code dir=&quot;auto&quot;&gt;assets/built-in/audiences/&lt;/code&gt;. Because the base directory is fixed at
&lt;code dir=&quot;auto&quot;&gt;assets/built-in&lt;/code&gt;, those artefacts are invisible to node discovery. This was initially
diagnosed as an extractor bug (“the extractor misses &lt;code dir=&quot;auto&quot;&gt;assets/&amp;#x3C;subdir&gt;/built-in/**&lt;/code&gt;”) and a
widening of the scan was drafted. That diagnosis was wrong: the extractor is correct and the
directory is misplaced.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Nine pre-existing artefacts sit outside any pack layer&lt;/strong&gt;, all confirmed dead (nothing loads
them, by id or by path — &lt;code dir=&quot;auto&quot;&gt;tests/doctrine/paradigms/conftest.py&lt;/code&gt; builds its own copy in a tmp
dir):
&lt;ul&gt;
&lt;li&gt;&lt;em&gt;three byte-identical duplicates&lt;/em&gt; of live built-ins — &lt;code dir=&quot;auto&quot;&gt;tactics/tdd-red-green-refactor&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;tactics/zombies-tdd&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;styleguides/writing/kitty-glossary-writing&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;&lt;em&gt;two stale divergent copies&lt;/em&gt; — &lt;code dir=&quot;auto&quot;&gt;tactics/acceptance-test-first&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;tactics/glossary-curation-interview&lt;/code&gt; differ from their built-in twins (the strays lack the
inline &lt;code dir=&quot;auto&quot;&gt;references:&lt;/code&gt; blocks their twins carry). Two files claiming one artefact id with
different content is an &lt;strong&gt;edit-the-wrong-file trap&lt;/strong&gt;;&lt;/li&gt;
&lt;li&gt;&lt;em&gt;four seed stubs&lt;/em&gt; from the framework’s first commit — &lt;code dir=&quot;auto&quot;&gt;directives/test-first&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;TEST_FIRST&lt;/code&gt;),
&lt;code dir=&quot;auto&quot;&gt;paradigms/test-first&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;styleguides/python-implementation&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;toolguides/powershell-syntax&lt;/code&gt;. The first three are content-free placeholders superseded by
real built-ins; the fourth points at a genuine 245-line guide that has been unreachable the
whole time.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The kind READMEs document a pack layer that does not exist&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;src/doctrine/toolguides/README.md&lt;/code&gt;
and &lt;code dir=&quot;auto&quot;&gt;src/doctrine/paradigms/README.md&lt;/code&gt; describe &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;type&gt;/shipped/*.yaml&lt;/code&gt;, and
&lt;code dir=&quot;auto&quot;&gt;tests/glossary/test_seed_schema.py&lt;/code&gt; names &lt;code dir=&quot;auto&quot;&gt;src/doctrine/tactics/shipped/...&lt;/code&gt;. On disk the pack
layer is always &lt;code dir=&quot;auto&quot;&gt;built-in&lt;/code&gt;. A third name for one slot.&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;Silent invisibility is unacceptable&lt;/strong&gt; — a misplaced artefact must fail loudly. This is the
charter’s architectural-gate standing order (close the defect class by construction with a
non-vacuous gate) applied to layout.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Single canonical authority&lt;/strong&gt; — one artefact id, one file. The two divergent duplicates are a
direct violation.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Forward compatibility with pack extraction&lt;/strong&gt; — doctrine packs will move to their own
repository; the layout decided now should survive that move as a rotation, not a redesign.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Campsite cleaning&lt;/strong&gt; — the litter class is small enough (9 files) to clear in the same change
that lands the gate, so the gate ships with nothing to allowlist.&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 &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;type&gt;/&amp;#x3C;pack&gt;/[&amp;#x3C;category&gt;/]&amp;#x3C;name&gt;&lt;/code&gt;, clear the 9, land a
non-vacuous gate with an empty allowlist.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2&lt;/strong&gt; — Widen the resolvers to accept &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;type&gt;/&amp;#x3C;category&gt;/&amp;#x3C;pack&gt;/&lt;/code&gt; too (the shape #2918
used), making both layouts legal.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3&lt;/strong&gt; — Pin the convention in docs only; no gate.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4&lt;/strong&gt; — Land the gate with the 9 frozen as a shrink-only baseline; clear them later.&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 layout this ADR pins:&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;text&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;src/doctrine/&amp;#x3C;type&gt;/&amp;#x3C;pack&gt;/[&amp;#x3C;category&gt;/]&amp;#x3C;name&gt;.&amp;#x3C;kind&gt;.yaml&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 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;│       │            └─ artefact file, id matches its content&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;│       └─ OPTIONAL grouping, nests INSIDE the pack&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;└─ provenance layer: `built-in` today (org/project layers overlay it)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;type&gt;/&amp;#x3C;pack&gt;/&lt;/code&gt; is mandatory.&lt;/strong&gt; An artefact directly under &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;type&gt;/&lt;/code&gt; is misplaced.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Categories nest inside the pack, never above it.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;assets/built-in/audiences/&lt;/code&gt; is correct;
&lt;code dir=&quot;auto&quot;&gt;assets/audiences/built-in/&lt;/code&gt; is not. This is the #2918 correction.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;built-in&lt;/code&gt; is the only spelling of the built-in pack layer.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;shipped/&lt;/code&gt; is a phantom — the
README and test references to it are stale and get corrected.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Misplacement is an error.&lt;/strong&gt; A gate rejects any &lt;code dir=&quot;auto&quot;&gt;*.&amp;#x3C;kind&gt;.yaml&lt;/code&gt; under &lt;code dir=&quot;auto&quot;&gt;src/doctrine/&lt;/code&gt; that is
not at a legal path, so the failure mode becomes a red test rather than a silently dead file.
The gate is non-vacuous (a self-mutation case proves it fails on a planted violation) and its
allowlist is &lt;strong&gt;empty&lt;/strong&gt; — there is nothing to grandfather, because the 9 are cleared in the same
change.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Mission-tier kinds are outside this rule&lt;/strong&gt;, because they resolve from their own
documented locations rather than from the artifact-tier shape: &lt;code dir=&quot;auto&quot;&gt;template&lt;/code&gt; (mission-tier,
empty glob), &lt;code dir=&quot;auto&quot;&gt;anti_pattern&lt;/code&gt; (hand-authored inside graph fragments, no standalone file), and
&lt;code dir=&quot;auto&quot;&gt;mission_step_contract&lt;/code&gt; — which lives at &lt;code dir=&quot;auto&quot;&gt;missions/built_in_step_contracts/&lt;/code&gt;, the path
&lt;code dir=&quot;auto&quot;&gt;extractor.py::_iter_step_contract_data&lt;/code&gt; documents as &lt;em&gt;authoritative&lt;/em&gt;; there is no
&lt;code dir=&quot;auto&quot;&gt;mission_step_contracts/&lt;/code&gt; directory at all. This carve-out was discovered &lt;em&gt;by&lt;/em&gt; the gate
(17 step contracts flagged on its first run) and is pinned &lt;strong&gt;positively&lt;/strong&gt; — the gate also
asserts step contracts exist at that path and appear nowhere else — so “it’s mission-tier”
cannot become a hiding place for a genuine stray.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Future form, after packs are extracted to their own repository:&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;pack id&gt;/&amp;#x3C;type&gt;/[&amp;#x3C;category&gt;/]&amp;#x3C;name&gt;&lt;/code&gt;. The pack becomes the outermost segment (it is the repo
root), so the migration is a &lt;strong&gt;rotation of the first two segments&lt;/strong&gt;, not a re-layout — the
type/category/name tail is unchanged. Recorded so the extraction mission inherits a decision
instead of re-litigating one.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;disposition-of-the-nine&quot;&gt;Disposition of the nine&lt;/h3&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Artefact&lt;/th&gt;&lt;th&gt;Action&lt;/th&gt;&lt;th&gt;Why&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;tactics/tdd-red-green-refactor&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tactics/zombies-tdd&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;styleguides/writing/kitty-glossary-writing&lt;/code&gt;&lt;/td&gt;&lt;td&gt;delete&lt;/td&gt;&lt;td&gt;byte-identical to the live built-in&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;tactics/acceptance-test-first&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tactics/glossary-curation-interview&lt;/code&gt;&lt;/td&gt;&lt;td&gt;delete&lt;/td&gt;&lt;td&gt;stale strays; the built-in twin is authoritative and richer&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;directives/test-first&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;paradigms/test-first&lt;/code&gt;&lt;/td&gt;&lt;td&gt;delete&lt;/td&gt;&lt;td&gt;content-free stubs; the live tests-doctrine authority is &lt;code dir=&quot;auto&quot;&gt;DIRECTIVE_041&lt;/code&gt; + the #2935 series&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;styleguides/python-implementation&lt;/code&gt;&lt;/td&gt;&lt;td&gt;delete&lt;/td&gt;&lt;td&gt;superseded by built-in &lt;code dir=&quot;auto&quot;&gt;python-conventions&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;toolguides/powershell-syntax&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;POWERSHELL_SYNTAX.md&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;strong&gt;promote&lt;/strong&gt; into &lt;code dir=&quot;auto&quot;&gt;built-in/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;245 lines of real guidance; the toolguide tests already name the &lt;code dir=&quot;auto&quot;&gt;built-in/&lt;/code&gt; path&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Note on the two &lt;code dir=&quot;auto&quot;&gt;test-first&lt;/code&gt; stubs: the #2935 decision was to &lt;em&gt;reconcile&lt;/em&gt; them into the new
&lt;code dir=&quot;auto&quot;&gt;paradigm:tests-as-scaffold-not-friction&lt;/code&gt; rather than drop them blind. On inspection there is
nothing to fold — between them they carry an id, a title, and a one-line summary, with no
procedures, steps, or rules. The reconciliation is therefore honestly a no-op, and recorded as
such rather than dressed up as a merge.&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;Misplaced artefacts fail at test time instead of disappearing.&lt;/li&gt;
&lt;li&gt;One artefact id → one file; the divergent-duplicate trap is removed.&lt;/li&gt;
&lt;li&gt;A real 245-line PowerShell guide becomes reachable for the first time.&lt;/li&gt;
&lt;li&gt;Pack extraction inherits a pinned target layout.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The gate constrains where future artefacts may live, and contributors adding a new category
must put it inside the pack layer — the opposite of the intuition #2918 followed. The gate’s
failure message must therefore state the correct shape, not merely reject.&lt;/li&gt;
&lt;li&gt;Promoting the PowerShell toolguide makes a previously-dead artefact live. That is the point,
but it is a behavioural change riding along with a layout cleanup, and is called out in the PR.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Org/project pack layers overlay the same &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;type&gt;/&amp;#x3C;pack&gt;/&lt;/code&gt; shape and are unaffected.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;assets/&lt;/code&gt; tree keeps its loose-contract sidecar convention; only its directory nesting is
constrained.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The layout gate fails on a planted misplaced artefact (self-mutation case) and passes on the
shipped tree with an &lt;strong&gt;empty&lt;/strong&gt; allowlist.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;find src/doctrine -name &apos;*.&amp;#x3C;kind&gt;.yaml&apos;&lt;/code&gt; yields only paths matching
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;type&gt;/&amp;#x3C;pack&gt;/[&amp;#x3C;category&gt;/]&amp;#x3C;name&gt;&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;TerminologyGuard&lt;/code&gt;-style README/test references to &lt;code dir=&quot;auto&quot;&gt;shipped/&lt;/code&gt; are corrected to &lt;code dir=&quot;auto&quot;&gt;built-in/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The promoted PowerShell toolguide loads through &lt;code dir=&quot;auto&quot;&gt;ToolguideRepository&lt;/code&gt; and appears as a DRG node.&lt;/li&gt;
&lt;li&gt;Regenerating the DRG fragments after the cleanup produces no unexpected node loss (the deleted
strays were never nodes).&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-the-layout-clear-the-litter-gate-it-chosen&quot;&gt;Option 1 — Pin the layout, clear the litter, gate it (chosen)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; removes the silent-invisibility class outright; gate ships with an empty allowlist, so
it can never be read as “the violations are acceptable”; corrects #2918’s diagnosis before the
wrong fix (widening the extractor scan) is built.
&lt;strong&gt;Cons:&lt;/strong&gt; widens this PR by a cleanup; makes one dormant artefact live.&lt;/p&gt;
&lt;h3 id=&quot;option-2--accept-both-layouts-in-the-resolvers&quot;&gt;Option 2 — Accept both layouts in the resolvers&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; #2918 needs no change; contributors cannot get it wrong.
&lt;strong&gt;Cons:&lt;/strong&gt; two legal shapes for one concept — the same two-authority smell as the sibling ADR,
and it doubles the scan surface for every kind forever. It also makes the pack layer’s &lt;em&gt;position&lt;/em&gt;
meaningless, which breaks the clean rotation to &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;pack id&gt;/&amp;#x3C;type&gt;/...&lt;/code&gt; on extraction. Rejected.&lt;/p&gt;
&lt;h3 id=&quot;option-3--document-only-no-gate&quot;&gt;Option 3 — Document only, no gate&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; zero risk to the current tree.
&lt;strong&gt;Cons:&lt;/strong&gt; documentation already exists and is already wrong (the &lt;code dir=&quot;auto&quot;&gt;shipped/&lt;/code&gt; phantom). Convention
without enforcement is exactly how nine dead files and #2918 happened. Rejected.&lt;/p&gt;
&lt;h3 id=&quot;option-4--gate-with-the-9-frozen-as-a-baseline&quot;&gt;Option 4 — Gate with the 9 frozen as a baseline&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; narrower change; standard charter fallback for a litter class too big to clear.
&lt;strong&gt;Cons:&lt;/strong&gt; the class is nine files and five of them are provable duplicates — small enough that a
baseline would be ceremony, and a frozen list of dead files invites a future reader to assume
they matter. Rejected on size, not on principle.&lt;/p&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Resolver scan paths: &lt;code dir=&quot;auto&quot;&gt;src/doctrine/*/repository.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;_default_builtin_dir&lt;/code&gt;);
&lt;code dir=&quot;auto&quot;&gt;src/doctrine/drg/migration/extractor.py::_discover_built_in_artifact_nodes&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Sibling axis: ADR 2026-07-26-1 (DRG edges as the relationship authority).&lt;/li&gt;
&lt;li&gt;Originating finding: PR #2918 review; corrected diagnosis recorded in this ADR’s context.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
