<?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-06-27-1-common-docs-reconciliation/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-06-27-1-common-docs-reconciliation/</id>
  <title>ADR: Common Docs Consolidation — Reconciliation of Metadata, Structure, Redirects, Glossary Read-Path, ADR Migration, and Curation</title>
  <updated>2026-06-27T00: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-06-27-1-common-docs-reconciliation/"/>
  <summary>Folds four documentation roots into one Common Docs tree and makes in-file frontmatter the per-page metadata source, with the page inventory regenerated as a lockfile.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Spec Kitty’s documentation has accreted into a &lt;strong&gt;multi-root, shadow-tree split-brain&lt;/strong&gt; that
the standard &lt;a href=&quot;https://github.com/velvet-tiger/common-docs&quot;&gt;Common Docs&lt;/a&gt; conventions are meant
to cure. Four defects, all measured in the research, frame this decision:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Four-root + shadow-tree split-brain.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;architecture/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;development/&lt;/code&gt;, and
&lt;code dir=&quot;auto&quot;&gt;engineering_notes/&lt;/code&gt; are four parallel documentation roots, and &lt;code dir=&quot;auto&quot;&gt;docs/{1x,2x,3x}/&lt;/code&gt; +
&lt;code dir=&quot;auto&quot;&gt;docs/architecture/&lt;/code&gt; is a &lt;em&gt;shadow duplicate&lt;/em&gt; of &lt;code dir=&quot;auto&quot;&gt;architecture/{1.x,2.x,3.x}/&lt;/code&gt;. The
“never duplicate” boundary contract in &lt;code dir=&quot;auto&quot;&gt;architecture/README.md&lt;/code&gt; is already leaking. This
is the “ongoing document sprawl” the operator objects to and the core payload to resolve.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Metadata split-brain.&lt;/strong&gt; The same lifecycle datum lives in two places. The sidecar
&lt;code dir=&quot;auto&quot;&gt;docs/development/3-2-page-inventory.yaml&lt;/code&gt; (568 rows) is SSOT for
&lt;code dir=&quot;auto&quot;&gt;path/tag/divio_type/owning_workstream/current_target/citation_refs&lt;/code&gt;, while in-file
frontmatter carries &lt;code dir=&quot;auto&quot;&gt;title&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;description&lt;/code&gt; (consumed today by &lt;code dir=&quot;auto&quot;&gt;scripts/docs/seo_postprocess.py&lt;/code&gt;
and the SEO gate). &lt;code dir=&quot;auto&quot;&gt;version_leakage_check.py&lt;/code&gt; literally enforces agreement between the two
(&lt;code dir=&quot;auto&quot;&gt;LEAK-FRONTMATTER-MISMATCH&lt;/code&gt;), and &lt;code dir=&quot;auto&quot;&gt;citation_refs&lt;/code&gt; is populated in only &lt;strong&gt;6 of 568 rows&lt;/strong&gt; —
the sidecar’s cross-reference half is effectively dead.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;DocFX-on-GitHub-Pages, no native redirects.&lt;/strong&gt; A site generator already ships
(&lt;code dir=&quot;auto&quot;&gt;docs/docfx.json&lt;/code&gt;) and publishes to &lt;a href=&quot;https://docs.spec-kitty.ai/&quot;&gt;https://docs.spec-kitty.ai/&lt;/a&gt; on every push to &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;.github/workflows/docs-pages.yml&lt;/code&gt;). DocFX on GitHub Pages has &lt;strong&gt;no native alias/redirect
mechanism&lt;/strong&gt;, and the consolidation &lt;em&gt;moves and deletes&lt;/em&gt; files across ~503 referencing files /
~1,589 link occurrences (42 in &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; — a missed rewrite is a &lt;em&gt;runtime&lt;/em&gt; break, not a dead
link). Without a redirect convention, every move is URL churn and SEO loss.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;ADR invisibility and era-less ADRs.&lt;/strong&gt; The repository holds ~117 unique ADRs (191 files),
and &lt;strong&gt;0 use YAML frontmatter&lt;/strong&gt; (~12 markdown-table, ~34 bold-inline headers) — invisible to
DocFX. Of these, &lt;strong&gt;20 ADRs live only in the flat &lt;code dir=&quot;auto&quot;&gt;architecture/adrs/&lt;/code&gt; shim&lt;/strong&gt; with no era
home, so a structural move has nowhere to put them without a decision.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The operator has chosen &lt;strong&gt;full consolidation&lt;/strong&gt; (not partial adoption). This ADR is the
&lt;strong&gt;serial spine&lt;/strong&gt; of Mission A (the governed foundation): it must record every mechanism the
consolidation depends on so that &lt;strong&gt;Mission B (the execution mission) opens with zero undecided
design&lt;/strong&gt;. The decisions below are pre-settled by the five-lens squad; this ADR records them in
canonical form — it does &lt;strong&gt;not&lt;/strong&gt; re-litigate them, and it does &lt;strong&gt;not&lt;/strong&gt; itself move, rename, or
mutate any documentation file (its own relocation is Mission B’s job; C-006).&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Resolve the split-brain by construction&lt;/strong&gt;, not by convention — one root, one SSOT per datum.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Generator-native&lt;/strong&gt;: the live DocFX site reads in-file frontmatter; the SSOT must be what the
published site already consumes.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Standard-aligned where it helps, justified deviation where it doesn’t&lt;/strong&gt; — adopt Common Docs
fully, but preserve the era-of-decision history the live site and &lt;code dir=&quot;auto&quot;&gt;llms.txt&lt;/code&gt; are built around.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Preserve every load-bearing invariant&lt;/strong&gt; — completeness rollups, the dashboard glossary
read-path, the glossary-as-doctrine extraction seam — none may be silently dropped.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No URL/SEO regression&lt;/strong&gt; across a move that touches ~503 files / ~1,589 links.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Terminology-canon clean&lt;/strong&gt; — the frontmatter status key must not collide with the WP-lane
status model (C-004).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Mission B must not start on undecided design&lt;/strong&gt; — every mechanism is decided here, ahead of
execution (C-001).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;p&gt;The squad converged on a single recommended value for each of the seven open mechanisms; the
losing alternatives are recorded per-decision in &lt;a href=&quot;#pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/a&gt;.
The headline fork was &lt;strong&gt;metadata SSOT&lt;/strong&gt;: Candidate A (in-file frontmatter SSOT, inventory
regenerated as a lockfile) versus Candidate B (sidecar inventory stays SSOT, frontmatter
generated from it).&lt;/p&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Full consolidation into a single Common Docs root, with seven binding mechanism decisions.&lt;/strong&gt;
Each decision below is recorded at its pre-settled value. Mission B executes them; it does not
re-decide them.&lt;/p&gt;
&lt;h3 id=&quot;d1--metadata-ssot-candidate-a-in-file-frontmatter-inventory-becomes-a-generated-lockfile&quot;&gt;D1 — Metadata SSOT: Candidate A (in-file frontmatter), inventory becomes a generated lockfile&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Decision:&lt;/strong&gt; &lt;strong&gt;In-file frontmatter is the per-page metadata SSOT.&lt;/strong&gt; The page-inventory
(&lt;code dir=&quot;auto&quot;&gt;docs/development/3-2-page-inventory.yaml&lt;/code&gt;) is &lt;strong&gt;regenerated FROM frontmatter&lt;/strong&gt; as a
generated/validated &lt;strong&gt;lockfile&lt;/strong&gt;: a build step walks &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt;, parses frontmatter, and emits the
rollup; the freshness gate asserts the committed rollup is in sync with a fresh generation
(drift = CI failure). The dead &lt;code dir=&quot;auto&quot;&gt;citation_refs&lt;/code&gt; field is &lt;strong&gt;dropped&lt;/strong&gt;; cross-references move to a
&lt;code dir=&quot;auto&quot;&gt;related:&lt;/code&gt; frontmatter list of resolvable repo-relative &lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt; paths, validated at build time.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Rationale:&lt;/strong&gt; generator-native (the live site already reads frontmatter, not the sidecar);
standard-aligned (Common Docs mandates in-file metadata, no sidecar concept); kills the
duplication by construction (&lt;code dir=&quot;auto&quot;&gt;version_tag&lt;/code&gt; lives in one place → &lt;code dir=&quot;auto&quot;&gt;LEAK-FRONTMATTER-MISMATCH&lt;/code&gt; is
retired); and survives agents (frontmatter-at-point-of-edit beats a remembered 568-row sidecar).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Load-bearing caveat (do not drop):&lt;/strong&gt; the sidecar’s &lt;em&gt;rollup&lt;/em&gt; semantics — completeness (“every
&lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt; inventoried”), workstream ownership, deterministic alphabetical diff — &lt;strong&gt;must be preserved
as the generated lockfile artifact&lt;/strong&gt;, not deleted. Candidate A converts the inventory from a
hand-maintained SSOT into a generated-and-asserted lockfile; it does not abolish it.&lt;/p&gt;
&lt;h3 id=&quot;d2--frontmatter-status-key-is-namespaced-as-doc_status&quot;&gt;D2 — Frontmatter status key is namespaced as &lt;code dir=&quot;auto&quot;&gt;doc_status&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Decision:&lt;/strong&gt; The frontmatter lifecycle key is &lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;doc_status&lt;/code&gt;&lt;/strong&gt; (controlled vocabulary
&lt;code dir=&quot;auto&quot;&gt;draft | active | deprecated | superseded&lt;/code&gt;), tied to a publish gate. The bare key &lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt;
&lt;strong&gt;collides with the WP-lane status model&lt;/strong&gt; (C-004 / terminology-canon) and is therefore
prohibited as a frontmatter key. &lt;code dir=&quot;auto&quot;&gt;updated: YYYY-MM-DD&lt;/code&gt; carries the freshness date.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Rationale:&lt;/strong&gt; a bare &lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt; in a &lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt; frontmatter is indistinguishable, to a reader and to
greps, from the WP-lane &lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt; term; namespacing removes the collision without losing the
controlled vocabulary the publish gate needs.&lt;/p&gt;
&lt;h3 id=&quot;d3--target-tree-is-the-13-section-common-docs-structure-with-adrera&quot;&gt;D3 — Target tree is the 13-section Common Docs structure, with &lt;code dir=&quot;auto&quot;&gt;adr/&amp;#x3C;era&gt;/&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Decision:&lt;/strong&gt; Adopt the &lt;strong&gt;13-section single-root Common Docs structure&lt;/strong&gt; under one &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; root:
&lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;context/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;architecture/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;adr/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;plans/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;api/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;configuration/&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;integrations/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;security/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;guides/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;operations/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;migrations/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;changelog/&lt;/code&gt;. Every
directory carries its own &lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Justified deviation:&lt;/strong&gt; the standard mandates a &lt;em&gt;flat&lt;/em&gt; &lt;code dir=&quot;auto&quot;&gt;adr/NNNN-&lt;/code&gt;; spec-kitty instead uses
&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;adr/&amp;#x3C;era&gt;/&lt;/code&gt;&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;adr/1.x/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;adr/2.x/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;adr/3.x/&lt;/code&gt;) to preserve the era-of-decision reasoning
across ~117 ADRs and satisfy the docsite lens’s version-stance concern &lt;em&gt;for the immutable
history only&lt;/em&gt;. The &lt;strong&gt;living architectural design collapses into a single unversioned
&lt;code dir=&quot;auto&quot;&gt;docs/architecture/&lt;/code&gt;&lt;/strong&gt; — era belongs to history, not to the current design. All ADRs are
converted to YAML frontmatter (today 0 use it → invisible to DocFX).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Amendment (2026-07-04, &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2353&quot;&gt;#2353&lt;/a&gt;):&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;release-goals/&lt;/code&gt; is promoted to a published fourteenth section (declared release-line intent) — a further justified deviation from the standard 13-section tree.&lt;/p&gt;
&lt;h3 id=&quot;d4--redirect-mechanism-generated-meta-http-equivrefresh-stub-pages-per-old-path&quot;&gt;D4 — Redirect mechanism: generated &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;meta http-equiv=&quot;refresh&quot;&gt;&lt;/code&gt; stub pages per old path&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Decision:&lt;/strong&gt; Because DocFX on GitHub Pages has &lt;strong&gt;no native redirect/alias mechanism&lt;/strong&gt;, every
moved/deleted URL is preserved by a &lt;strong&gt;generated &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;meta http-equiv=&quot;refresh&quot;&gt;&lt;/code&gt; stub page emitted
at the old path&lt;/strong&gt; into the DocFX &lt;code dir=&quot;auto&quot;&gt;_site&lt;/code&gt; output. The stubs are produced by a &lt;strong&gt;post-build step
in &lt;code dir=&quot;auto&quot;&gt;scripts/docs/&lt;/code&gt;&lt;/strong&gt; that reads a &lt;strong&gt;checked-in redirect map&lt;/strong&gt; (old-path → new-path). A
&lt;strong&gt;captured baseline URL inventory&lt;/strong&gt; (the pre-move site URL set) is the &lt;strong&gt;denominator&lt;/strong&gt; for
Mission B’s “100% of URLs resolve” NFR — every baseline URL must resolve (directly or via a
refresh stub) after the move.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Rationale:&lt;/strong&gt; a client-side &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;meta refresh&gt;&lt;/code&gt; stub is the only redirect primitive available on a
static GitHub Pages site fronting DocFX; emitting it per old path from a reviewed map makes the
URL-preservation guarantee testable and the denominator explicit.&lt;/p&gt;
&lt;h3 id=&quot;d5--glossary-read-path-preserve-the-kittifyglossariesscopeyaml-seed-read-path-load-bearing&quot;&gt;D5 — Glossary read-path: preserve the &lt;code dir=&quot;auto&quot;&gt;.kittify/glossaries/&amp;#x3C;scope&gt;.yaml&lt;/code&gt; seed read-path (load-bearing)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Decision (the load-bearing C-001 decision):&lt;/strong&gt; The dashboard’s &lt;code dir=&quot;auto&quot;&gt;GlossaryHandler&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/dashboard/handlers/glossary.py&lt;/code&gt;) reads &lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/glossaries/&amp;#x3C;scope&gt;.yaml&lt;/code&gt;
seed files&lt;/strong&gt; via &lt;code dir=&quot;auto&quot;&gt;load_seed_file()&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/glossary/scope.py:108&lt;/code&gt;) — &lt;strong&gt;not&lt;/strong&gt; the human-readable
&lt;code dir=&quot;auto&quot;&gt;glossary/contexts/*.md&lt;/code&gt;. These are two distinct artifacts on two distinct paths:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Machine read-path (must not break):&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;.kittify/glossaries/&amp;#x3C;scope&gt;.yaml&lt;/code&gt; seed files, consumed
by &lt;code dir=&quot;auto&quot;&gt;load_seed_file()&lt;/code&gt; at three call sites (the dashboard &lt;code dir=&quot;auto&quot;&gt;GlossaryHandler&lt;/code&gt;, the template
renderer, and the glossary CLI), and loaded into the store by &lt;code dir=&quot;auto&quot;&gt;glossary/pipeline.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Human narrative artifact (the one that moves):&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;glossary/contexts/*.md&lt;/code&gt;, the markdown
per-context glossary that the consolidation relocates into &lt;code dir=&quot;auto&quot;&gt;docs/context/&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Binding constraint:&lt;/strong&gt; the move of &lt;code dir=&quot;auto&quot;&gt;glossary/contexts/*.md&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;docs/context/&lt;/code&gt; &lt;strong&gt;MUST preserve or
regenerate the &lt;code dir=&quot;auto&quot;&gt;.kittify/glossaries/&amp;#x3C;scope&gt;.yaml&lt;/code&gt; seed read-path&lt;/strong&gt; so the dashboard, renderer, and
CLI keep resolving. The seed file is also the &lt;strong&gt;doctrine-extraction source&lt;/strong&gt; — the glossary stays
extractable as a doctrine artifact from the seed, not locked into a docs-only markdown location.
Concretely: only the human markdown relocates; the seed YAML stays at (or is regenerated to)
&lt;code dir=&quot;auto&quot;&gt;.kittify/glossaries/&lt;/code&gt;, and both seams (dashboard read + doctrine extraction) remain intact. Any
plan that moves the markdown without preserving the seed read-path is rejected.&lt;/p&gt;
&lt;h3 id=&quot;d6--era-less-adr-migration-the-20-flat-only-adrs--adr3x-by-date-shim-closes-after&quot;&gt;D6 — Era-less ADR migration: the 20 flat-only ADRs → &lt;code dir=&quot;auto&quot;&gt;adr/3.x/&lt;/code&gt; by date; shim closes after&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Decision:&lt;/strong&gt; The &lt;strong&gt;20 ADRs that live only in the flat &lt;code dir=&quot;auto&quot;&gt;architecture/adrs/&lt;/code&gt; shim&lt;/strong&gt; (no era home)
are &lt;strong&gt;3.x-era by date&lt;/strong&gt; → migrate them to &lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;adr/3.x/&lt;/code&gt;&lt;/strong&gt; (sorted by their dated filename). This
migration is &lt;strong&gt;executed in Mission B&lt;/strong&gt;. The flat &lt;code dir=&quot;auto&quot;&gt;architecture/adrs/&lt;/code&gt; shim &lt;strong&gt;closes only after&lt;/strong&gt;
the migration completes — it is not removed before its contents have a durable era home, so no
ADR is orphaned mid-move.&lt;/p&gt;
&lt;h3 id=&quot;d7--curation-delete-stale-policy--distil-then-retire-lifecycle&quot;&gt;D7 — Curation: delete-stale policy + distil-then-retire lifecycle&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Decision:&lt;/strong&gt; Adopt Common Docs’ &lt;strong&gt;delete-stale curation policy&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; is not a wiki; one
concern per file; stale/deprecated docs are deleted after ~6 months unreferenced; every
behaviour-changing change updates the relevant &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; files in the same commit.&lt;/p&gt;
&lt;p&gt;For &lt;strong&gt;in-flight investigations and traces&lt;/strong&gt; (today’s &lt;code dir=&quot;auto&quot;&gt;engineering_notes/&lt;/code&gt;), the home is
&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;plans/&lt;/code&gt;&lt;/strong&gt; with an explicit &lt;strong&gt;distil-then-retire lifecycle&lt;/strong&gt;, not a permanent wiki home:
&lt;code dir=&quot;auto&quot;&gt;doc_status: draft|active&lt;/code&gt; while in-flight → &lt;strong&gt;distil&lt;/strong&gt; the durable finding into &lt;code dir=&quot;auto&quot;&gt;adr/&lt;/code&gt; (a
decision) or &lt;code dir=&quot;auto&quot;&gt;architecture/&lt;/code&gt; (a design) → mark the raw investigation &lt;code dir=&quot;auto&quot;&gt;doc_status: deprecated&lt;/code&gt;
and let the delete-stale policy retire it. The discipline (distil, then retire) matters more
than the bucket; &lt;code dir=&quot;auto&quot;&gt;plans/&lt;/code&gt; is the chosen bucket because investigations are forward-looking
decision-support, which &lt;code dir=&quot;auto&quot;&gt;operations/&lt;/code&gt; (production-ops-shaped) is not.&lt;/p&gt;
&lt;h3 id=&quot;merge-boundary-c-001&quot;&gt;Merge boundary (C-001)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Mission B (the execution mission) is BLOCKED until this ADR is Accepted AND merged into
&lt;code dir=&quot;auto&quot;&gt;docs/2165-consolidation-research&lt;/code&gt;.&lt;/strong&gt; C-001 is a &lt;strong&gt;merge boundary&lt;/strong&gt;, not intra-mission ordering:
the remaining Mission A work packages and all of Mission B’s structural moves, link rewrites,
redirect-shim generation, frontmatter backfill, and ADR migration depend on the decisions
recorded here being on the integration branch first. No consolidation move may begin against an
un-merged spine.&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;&lt;strong&gt;Split-brain resolved by construction&lt;/strong&gt; — one documentation root, one SSOT per datum; the
shadow &lt;code dir=&quot;auto&quot;&gt;docs/{1x,2x,3x}&lt;/code&gt; tree and the four-root sprawl are eliminated, not perpetuated.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;LEAK-FRONTMATTER-MISMATCH&lt;/code&gt; retired&lt;/strong&gt; — under D1 the leaked datum lives in exactly one place,
so the cross-check gate becomes structurally unnecessary.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;URL/SEO preserved&lt;/strong&gt; across ~503 files / ~1,589 links via D4’s per-path refresh stubs against a
captured baseline denominator.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;ADRs become first-class on the live site&lt;/strong&gt; — D3’s YAML-frontmatter conversion makes ~117 ADRs
visible to DocFX for the first time, with era history intact via &lt;code dir=&quot;auto&quot;&gt;adr/&amp;#x3C;era&gt;/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Dashboard and doctrine glossary seams stay intact&lt;/strong&gt; — D5 keeps the seed read-path and the
doctrine-extraction source load-bearing through the move.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Mission B opens with zero undecided design&lt;/strong&gt; — every mechanism is settled here.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Bespoke enforcement weight.&lt;/strong&gt; The standard provides shape, not enforcement: the &lt;code dir=&quot;auto&quot;&gt;related:&lt;/code&gt;
path validator, the link-rewrite tooling, the redirect-shim generator, and the anti-sprawl
ratchet are all spec-kitty-bespoke and are Mission B’s real cost.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;One-time conversion churn.&lt;/strong&gt; Converting ~117 ADRs to YAML frontmatter and backfilling
frontmatter from the 568-row sidecar is mechanical but large.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Forward-only.&lt;/strong&gt; This ADR decides; it does not itself move anything. A regression that
re-introduces a second doc root or a shadow tree is only caught once Mission B’s anti-sprawl
ratchet lands (pair it with a full-gate dry-run before merge — a ratchet that only bites
post-merge cannot catch its own offenders).&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The Divio axis (tutorials/how-to/reference/explanation) folds onto Common Docs sections
(&lt;code dir=&quot;auto&quot;&gt;guides/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;api/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;architecture/&lt;/code&gt;) — a relabelling, not a loss of content.&lt;/li&gt;
&lt;li&gt;The three Common Docs Agent Skills (&lt;code dir=&quot;auto&quot;&gt;scaffold&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;write&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;find&lt;/code&gt;) shipped as &lt;strong&gt;three doctrine
tactics&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;common-docs-scaffold&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;common-docs-write&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;common-docs-find&lt;/code&gt;) rather than as
peer skills, superseding the earlier “install as peer skills” wording. &lt;code dir=&quot;auto&quot;&gt;find&lt;/code&gt;’s static lookup
table is still &lt;strong&gt;not&lt;/strong&gt; adopted — its topic→path role is backed by the richer, gated DRG +
page-inventory.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;The decisions are confirmed when, in Mission B: (1) a single &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; root exists with all 13
sections present and each carrying &lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt;, and no second doc root or &lt;code dir=&quot;auto&quot;&gt;docs/&amp;#x3C;version&gt;x&lt;/code&gt; shadow
tree survives (anti-sprawl ratchet green); (2) the page-inventory is regenerated from frontmatter
and the freshness gate asserts lockfile sync (D1); (3) no frontmatter uses a bare &lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt; key
(D2); (4) every captured-baseline URL resolves directly or via a generated refresh stub (D4
against the baseline denominator); (5) the dashboard &lt;code dir=&quot;auto&quot;&gt;GlossaryHandler&lt;/code&gt; still resolves terms via
&lt;code dir=&quot;auto&quot;&gt;load_seed_file()&lt;/code&gt; after the &lt;code dir=&quot;auto&quot;&gt;context/&lt;/code&gt; move (D5); (6) the 20 flat-only ADRs resolve under
&lt;code dir=&quot;auto&quot;&gt;adr/3.x/&lt;/code&gt; and the flat shim is closed only afterward (D6); and (7) the curation policy retires a
distilled investigation note end-to-end (D7). This ADR itself is confirmed Accepted and merged
into &lt;code dir=&quot;auto&quot;&gt;docs/2165-consolidation-research&lt;/code&gt; before any Mission B work begins (C-001).&lt;/p&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;d1--candidate-a-in-file-frontmatter-ssot-vs-candidate-b-sidecar-ssot&quot;&gt;D1 — Candidate A (in-file frontmatter SSOT) vs Candidate B (sidecar SSOT)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Candidate A (CHOSEN) — in-file frontmatter is SSOT; inventory regenerated as a lockfile.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Pros:&lt;/strong&gt; generator-native (the live site already reads frontmatter); standard-aligned;
kills duplication by construction; survives agents (edit-at-point); retires
&lt;code dir=&quot;auto&quot;&gt;LEAK-FRONTMATTER-MISMATCH&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cons:&lt;/strong&gt; must explicitly preserve the sidecar’s rollup semantics as a generated artifact,
or completeness/ownership invariants are lost.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Candidate B — sidecar inventory stays SSOT; frontmatter generated from it.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Pros:&lt;/strong&gt; keeps the existing gated sidecar as the single authority; one machine to trust.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cons:&lt;/strong&gt; a &lt;strong&gt;permanent deviation&lt;/strong&gt; from the standard the operator chose to fully adopt; the
published site still wouldn’t read the SSOT (it reads frontmatter); authors must keep a
568-row sidecar in mind — the convention that does not survive agents.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d3--flat-adr-standard-vs-adrera-chosen&quot;&gt;D3 — flat &lt;code dir=&quot;auto&quot;&gt;adr/&lt;/code&gt; (standard) vs &lt;code dir=&quot;auto&quot;&gt;adr/&amp;#x3C;era&gt;/&lt;/code&gt; (chosen)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Flat &lt;code dir=&quot;auto&quot;&gt;adr/NNNN-&lt;/code&gt; (standard):&lt;/strong&gt; simplest, standard-pure; &lt;strong&gt;but&lt;/strong&gt; erases the version-stance
axis the live site and &lt;code dir=&quot;auto&quot;&gt;llms.txt&lt;/code&gt; are built around, and flattens ~117 ADRs across three eras
into one undifferentiated list, losing era-of-decision reasoning.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;adr/&amp;#x3C;era&gt;/&lt;/code&gt; (CHOSEN):&lt;/strong&gt; a justified deviation that preserves historical reasoning for the
immutable record while the &lt;em&gt;living&lt;/em&gt; design collapses to a single unversioned location — era
where it matters (history), dropped where it confuses (current design).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d4--meta-refresh-stubs-vs-alternatives&quot;&gt;D4 — &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;meta refresh&gt;&lt;/code&gt; stubs vs alternatives&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;meta http-equiv=&quot;refresh&quot;&gt;&lt;/code&gt; stubs (CHOSEN):&lt;/strong&gt; the only redirect primitive available on a
static GitHub Pages site fronting DocFX; per-path, generated from a reviewed map, testable
against a baseline denominator.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No redirect / accept URL churn:&lt;/strong&gt; rejected — ~1,589 link occurrences and live SEO would
regress on every move.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Server-side redirects / DocFX native aliases:&lt;/strong&gt; unavailable — GitHub Pages serves static
files and DocFX has no native alias mechanism.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d7--plans-vs-operations-for-in-flight-investigations&quot;&gt;D7 — &lt;code dir=&quot;auto&quot;&gt;plans/&lt;/code&gt; vs &lt;code dir=&quot;auto&quot;&gt;operations/&lt;/code&gt; for in-flight investigations&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;plans/&lt;/code&gt; (CHOSEN):&lt;/strong&gt; forward-looking, which is what an in-flight investigation is; pairs with
the distil-then-retire lifecycle.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;operations/&lt;/code&gt;:&lt;/strong&gt; production-ops-shaped (monitoring, disaster-recovery, runbooks);
investigations fit it poorly.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Mission split:&lt;/strong&gt; This is Mission A (governed foundation); Mission B is the execution mission
(structural moves, link rewrites, redirect-shim, frontmatter backfill, ADR migration,
anti-sprawl ratchet). C-001 gates B on this ADR’s merge.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Research ground truth (pre-settled values):&lt;/strong&gt;
&lt;a href=&quot;../../../docs/plans/engineering-notes/651-docs-consolidation/README.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/plans/engineering-notes/651-docs-consolidation/index.md&lt;/code&gt;&lt;/a&gt;,
&lt;a href=&quot;../../../docs/plans/engineering-notes/651-docs-consolidation/02-common-docs-standard.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;02-common-docs-standard.md&lt;/code&gt;&lt;/a&gt;,
&lt;a href=&quot;../../../docs/plans/engineering-notes/651-docs-consolidation/03-target-structure-mapping.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;03-target-structure-mapping.md&lt;/code&gt;&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Key code/seams referenced:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;src/glossary/scope.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;load_seed_file&lt;/code&gt;),
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/dashboard/handlers/glossary.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;GlossaryHandler&lt;/code&gt;),
&lt;code dir=&quot;auto&quot;&gt;docs/development/3-2-page-inventory.yaml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;docs/docfx.json&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;.github/workflows/docs-pages.yml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;scripts/docs/seo_postprocess.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;scripts/docs/version_leakage_check.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;scripts/docs/check_docs_freshness.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Standard:&lt;/strong&gt; &lt;a href=&quot;https://github.com/velvet-tiger/common-docs&quot;&gt;https://github.com/velvet-tiger/common-docs&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cross-references:&lt;/strong&gt; &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2165&quot;&gt;#2165&lt;/a&gt;,
&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/651&quot;&gt;#651&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
