<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/4.x/2026-10-31-1-the-docsite-is-built-with-doc-kitty/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-31-1-the-docsite-is-built-with-doc-kitty/</id>
  <title>ADR: the docsite is built with doc-kitty, consumed as a pinned git dependency, at directory URLs with every legacy URL redirected</title>
  <updated>2026-10-31T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/4.x/2026-10-31-1-the-docsite-is-built-with-doc-kitty/"/>
  <summary>doc-kitty replaces DocFX for docs.spec-kitty.ai: a site/ sub-project reads ../docs, pins doc-kitty by commit, deploys at the domain root and redirects every legacy URL.</summary>
  <content type="html">&lt;h2 id=&quot;the-docsite-is-built-with-doc-kitty-consumed-as-a-pinned-git-dependency-at-directory-urls-with-every-legacy-url-redirected&quot;&gt;The docsite is built with doc-kitty, consumed as a pinned git dependency, at directory URLs with every legacy URL redirected&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Proposed (2026-10-31). The operator accepts it by merging the pull request that carries it.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;What was ruled and what is derived.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Ruled by the operator (2026-10-31, &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6100#issuecomment-6544333324&quot;&gt;#6100 decisions comment&lt;/a&gt;).&lt;/strong&gt; Numbered as in the comment; “ruling N” below refers to this list.
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;URL scheme.&lt;/strong&gt; Directory URLs; every current &lt;code dir=&quot;auto&quot;&gt;*.html&lt;/code&gt; URL (about 830) redirects to its new address; no baseline URL breaks.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Section index file.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt;. The 56 folders whose index is &lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt; are renamed, and the 4 folders holding both files are resolved.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Features only DocFX has.&lt;/strong&gt; The kitty-specs mission dashboards, their JSON-LD and the template’s &lt;code dir=&quot;auto&quot;&gt;main.js&lt;/code&gt; are dropped for now. doc-kitty’s generated &lt;code dir=&quot;auto&quot;&gt;llms.txt&lt;/code&gt; replaces the hand-written one and keeps the version-stance text. An upstream issue asks for mission and glossary pages as a hub-style grid of cards.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;What is published.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;plans/&lt;/code&gt; (restricted feeds) and &lt;code dir=&quot;auto&quot;&gt;development/&lt;/code&gt; (its own section). Engineering-notes, investigations and research are draft or unpublished. Archive, reports, convergence and the pages about the retired hosted and sync surfaces are unpublished.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Proposed ADRs&lt;/strong&gt; take &lt;code dir=&quot;auto&quot;&gt;doc_status: active&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;ADR index.&lt;/strong&gt; doc-kitty gains support for date-named ADRs in era folders, with a frontmatter &lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt; fallback; core’s era indexes stay until then.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;#3891 stays separate&lt;/strong&gt;; &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/2358&quot;&gt;#2358&lt;/a&gt;, &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/3914&quot;&gt;#3914&lt;/a&gt;, &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/2361&quot;&gt;#2361&lt;/a&gt; and &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/2362&quot;&gt;#2362&lt;/a&gt; move under #6100.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/648&quot;&gt;#648&lt;/a&gt; stays standalone.&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/2302&quot;&gt;#2302&lt;/a&gt;&lt;/strong&gt; is written after cutover, in spec-kitty-open-packs.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Toolkit.&lt;/strong&gt; The build consumes &lt;code dir=&quot;auto&quot;&gt;spec-kitty/doc-kitty&lt;/code&gt; directly; this record says how: a pinned git dependency or checkout, or the package doc-kitty publishes.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Collisions.&lt;/strong&gt; Moves and renames are allowed; each open docs PR resolves its own conflicts when it merges.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Glossary.&lt;/strong&gt; &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/3024&quot;&gt;#3024&lt;/a&gt; settles the source of truth first; one &lt;code dir=&quot;auto&quot;&gt;definitions.yaml&lt;/code&gt; is then generated from it.&lt;/li&gt;
&lt;/ol&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Operator steer relayed with the step-1 brief (2026-10-31), not in the comment:&lt;/strong&gt; prefer not to depend on a separately authorised package. D-2 weighs it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Derived:&lt;/strong&gt; every decision below marked &lt;em&gt;(derived)&lt;/em&gt;, and the spike results, which are evidence, not rulings.&lt;/li&gt;
&lt;/ul&gt;
&lt;/blockquote&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-10-31&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (operator). Derived clauses are proposed by this record for the operator’s sign-off.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Epic &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6100&quot;&gt;#6100&lt;/a&gt; (step 1: this ADR and its spike).&lt;/li&gt;
&lt;li&gt;Absorbs &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/2358&quot;&gt;#2358&lt;/a&gt; (a standing moves ledger and a living URL baseline). Places &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/3914&quot;&gt;#3914&lt;/a&gt;, &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/2361&quot;&gt;#2361&lt;/a&gt; and &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/2362&quot;&gt;#2362&lt;/a&gt; under #6100.&lt;/li&gt;
&lt;li&gt;Builds on &lt;a href=&quot;/adr/3.x/2026-06-27-1-common-docs-reconciliation/&quot;&gt;ADR 2026-06-27-1&lt;/a&gt; (in-file frontmatter is the page-metadata authority) where it still applies.&lt;/li&gt;
&lt;li&gt;Spike evidence: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-ops/research/01M6947JAAGSMJTM6ST9D429BG/spike-evidence.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-ops/research/01M6947JAAGSMJTM6ST9D429BG/spike-evidence.md&lt;/code&gt;&lt;/a&gt; (on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; once this record merges; &lt;code dir=&quot;auto&quot;&gt;kitty-ops/&lt;/code&gt; is outside the published site).&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;docs.spec-kitty.ai&lt;/code&gt; is built by DocFX (.NET) from &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; and then post-processed by six Python scripts, in seven steps, in &lt;code dir=&quot;auto&quot;&gt;.github/workflows/docs-pages.yml&lt;/code&gt;: kitty-specs dashboard generation, SEO metadata, glossary auto-linking, PlantUML rendering, meta-refresh redirect stubs and two verifiers. The pipeline runs on a push to &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;2.x&lt;/code&gt; and on manual dispatch. No pull request builds the site, so a render defect is found after merge. The workflow’s own comments record this, and they still name a &lt;code dir=&quot;auto&quot;&gt;docs-build-pr.yml&lt;/code&gt; that no longer exists.&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;https://github.com/spec-kitty/doc-kitty&quot;&gt;doc-kitty&lt;/a&gt; is Spec Kitty’s own Astro + Starlight docs toolkit. It owns the frontmatter contract, the section registry, &lt;code dir=&quot;auto&quot;&gt;llms.txt&lt;/code&gt;, the agent and OKF exports (OKF: doc-kitty’s export of the docs as plain Markdown with metadata, for agents), and the link and redirect gates that core rebuilt piecemeal around DocFX. Epic #6100 moves the docsite onto it. This record fixes the decisions every later step of #6100 depends on: how core consumes doc-kitty, where the site lives, what URLs it serves, how no published URL breaks, and how the move is gated, run in parallel, rolled back and finished.&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;No published URL breaks.&lt;/strong&gt; About 830 URLs are live today: 668 current pages (derived from &lt;code dir=&quot;auto&quot;&gt;docfx.json&lt;/code&gt;’s content globs against the tree at this record’s base) plus 163 legacy URLs already redirected by &lt;code dir=&quot;auto&quot;&gt;scripts/docs/redirect_map.yaml&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;One authority per concern.&lt;/strong&gt; doc-kitty owns rendering and its gates; core owns its content, its URL ledger and its publication choices. Core does not fork or patch the toolkit.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No credential that is not already in the workflow.&lt;/strong&gt; No PAT. The operator also steered away from depending on a separately authorised package (the step-1 brief).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; stays where it is.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty docs query&lt;/code&gt; reads &lt;code dir=&quot;auto&quot;&gt;docs/development/docs-retrieval-index.yaml&lt;/code&gt;, and agents, scripts and links across the repository address &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; paths.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A defect is caught on the pull request&lt;/strong&gt;, not after deploy.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;p&gt;For consuming doc-kitty (ruling 10 leaves the choice to this record):&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;A pnpm git dependency pinned by commit&lt;/strong&gt;, &lt;code dir=&quot;auto&quot;&gt;github:spec-kitty/doc-kitty#&amp;#x3C;sha&gt;&amp;#x26;path:/src&lt;/code&gt;, recorded in &lt;code dir=&quot;auto&quot;&gt;site/pnpm-lock.yaml&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A CI checkout&lt;/strong&gt; of &lt;code dir=&quot;auto&quot;&gt;spec-kitty/doc-kitty&lt;/code&gt; at a pinned SHA, linked as &lt;code dir=&quot;auto&quot;&gt;file:&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;link:&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;doc-kitty’s published package&lt;/strong&gt;, &lt;code dir=&quot;auto&quot;&gt;@spec-kitty/doc-toolkit&lt;/code&gt; on GitHub Packages.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Vendoring&lt;/strong&gt; the toolkit source into core.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;For the site’s place in the repository: a &lt;code dir=&quot;auto&quot;&gt;site/&lt;/code&gt; sub-project reading &lt;code dir=&quot;auto&quot;&gt;../docs&lt;/code&gt;, or moving the content under the site project.&lt;/p&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen options:&lt;/strong&gt; a &lt;code dir=&quot;auto&quot;&gt;site/&lt;/code&gt; sub-project that reads &lt;code dir=&quot;auto&quot;&gt;../docs&lt;/code&gt;, consuming doc-kitty as a pnpm git dependency pinned by commit, deployed at the domain root with directory URLs and a generated redirect for every legacy URL. The decisions follow.&lt;/p&gt;
&lt;h3 id=&quot;d-1-doc-kitty-replaces-docfx-site-is-a-sub-project-and-docs-stays-at-the-root-replacement-ruling-10-and-the-epic-layout-derived&quot;&gt;D-1: doc-kitty replaces DocFX; &lt;code dir=&quot;auto&quot;&gt;site/&lt;/code&gt; is a sub-project and &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; stays at the root &lt;em&gt;(replacement: ruling 10 and the epic; layout: derived)&lt;/em&gt;&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The docsite is built by doc-kitty. DocFX is retired as set out in D-13.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;site/&lt;/code&gt; holds the Astro project: &lt;code dir=&quot;auto&quot;&gt;package.json&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;pnpm-lock.yaml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;astro.config.mjs&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/content.config.ts&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/pages/llms.txt.ts&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;public/&lt;/code&gt; (with &lt;code dir=&quot;auto&quot;&gt;CNAME&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;robots.txt&lt;/code&gt;), &lt;code dir=&quot;auto&quot;&gt;url-baseline.txt&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;moves.yaml&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;redirects.json&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;defineDocKittyIntegrations({ docsDir: &apos;../docs&apos;, indexBasename: &apos;README&apos;, … })&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;docKittyDocsLoader({ base: &apos;../docs&apos; })&lt;/code&gt;. The two must agree; doc-kitty requires it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Index-file sequencing.&lt;/strong&gt; DocFX emits a section page only from &lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt;. Renaming a folder’s &lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt; while DocFX still deploys would make that section’s &lt;code dir=&quot;auto&quot;&gt;/dir/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;/dir/index.html&lt;/code&gt; return 404 on the live site.
&lt;ul&gt;
&lt;li&gt;During the parallel run (D-13), the site sets &lt;code dir=&quot;auto&quot;&gt;indexBasename: [&apos;README&apos;, &apos;index&apos;]&lt;/code&gt;, as doc-kitty’s own example does.&lt;/li&gt;
&lt;li&gt;The 4 folders holding both files are resolved before the scaffold build, keeping &lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt; as the index, because two index files in one folder collapse to one route.&lt;/li&gt;
&lt;li&gt;After DocFX retirement (D-13 step 5), all 60 &lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt; files become &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt; (the 56 of ruling 2, plus the 4 resolved folders, which keep &lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt; until then); &lt;code dir=&quot;auto&quot;&gt;indexBasename&lt;/code&gt; then narrows to &lt;code dir=&quot;auto&quot;&gt;&apos;README&apos;&lt;/code&gt;. The rename waits for retirement, not just cutover, so that reverting the cutover still redeploys a DocFX site whose sections all build.&lt;/li&gt;
&lt;li&gt;Every &lt;code dir=&quot;auto&quot;&gt;dockitty-*&lt;/code&gt; gate is run with &lt;code dir=&quot;auto&quot;&gt;--astro-config astro.config.mjs&lt;/code&gt;. Without it, a gate looks for the site config in the parent of the docs root (the repository root), finds none and falls back to &lt;code dir=&quot;auto&quot;&gt;README&lt;/code&gt; alone, so it would misread the 60 &lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt; files during the parallel run.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; stays at the repository root. That keeps &lt;code dir=&quot;auto&quot;&gt;spec-kitty docs query&lt;/code&gt;, every in-repo link and every &lt;code dir=&quot;auto&quot;&gt;scripts/docs&lt;/code&gt; tool that reads &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; working unchanged.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/_meta/sections.yaml&lt;/code&gt; is the section registry (doc-kitty’s shape); it is authored content, not generated.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Spike:&lt;/strong&gt; a build with &lt;code dir=&quot;auto&quot;&gt;docsDir: &apos;../docs&apos;&lt;/code&gt; from a sibling &lt;code dir=&quot;auto&quot;&gt;site/&lt;/code&gt; project emitted every page, with each &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt; as its section index. The doc-kitty survey had flagged this layout as untested upstream, so the scaffold step adds a fixture for it upstream (gap list, D-14).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-2-doc-kitty-is-consumed-as-a-pnpm-git-dependency-pinned-by-commit-derived&quot;&gt;D-2: doc-kitty is consumed as a pnpm git dependency pinned by commit &lt;em&gt;(derived)&lt;/em&gt;&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;site/package.json&lt;/code&gt; declares:&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;json&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:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;@spec-kitty/doc-toolkit&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;github:spec-kitty/doc-kitty#&amp;#x3C;40-character commit SHA&gt;&amp;#x26;path:/src&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;pnpm records the commit, the subpath and the repository in &lt;code dir=&quot;auto&quot;&gt;site/pnpm-lock.yaml&lt;/code&gt;. CI installs with &lt;code dir=&quot;auto&quot;&gt;pnpm install --frozen-lockfile&lt;/code&gt;. &lt;strong&gt;Spike:&lt;/strong&gt; this resolved from the public repository with no token, built the site, and put the toolkit’s &lt;code dir=&quot;auto&quot;&gt;dockitty-*&lt;/code&gt; gate binaries on the path.&lt;/p&gt;















































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;&lt;/th&gt;&lt;th&gt;Git dependency by commit (chosen)&lt;/th&gt;&lt;th&gt;CI checkout at a SHA&lt;/th&gt;&lt;th&gt;GitHub Packages (&lt;code dir=&quot;auto&quot;&gt;@spec-kitty/doc-toolkit&lt;/code&gt;)&lt;/th&gt;&lt;th&gt;Vendoring&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Pin authority&lt;/td&gt;&lt;td&gt;the lockfile, one place&lt;/td&gt;&lt;td&gt;a SHA in the workflow, plus a &lt;code dir=&quot;auto&quot;&gt;file:&lt;/code&gt; path the lockfile cannot verify&lt;/td&gt;&lt;td&gt;the lockfile (version + integrity)&lt;/td&gt;&lt;td&gt;the copied tree&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Local build&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;pnpm install&lt;/code&gt;&lt;/td&gt;&lt;td&gt;needs a second clone at the right path&lt;/td&gt;&lt;td&gt;needs a PAT with &lt;code dir=&quot;auto&quot;&gt;read:packages&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;~/.npmrc&lt;/code&gt;&lt;/td&gt;&lt;td&gt;works&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;CI credential&lt;/td&gt;&lt;td&gt;none (public repository)&lt;/td&gt;&lt;td&gt;none (public repository)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;packages: read&lt;/code&gt;, and package access granted to this repository&lt;/td&gt;&lt;td&gt;none&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Separately authorised package&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;&lt;strong&gt;yes&lt;/strong&gt; (rejected: the operator’s steer, and a PAT locally)&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Drift from upstream&lt;/td&gt;&lt;td&gt;none&lt;/td&gt;&lt;td&gt;none&lt;/td&gt;&lt;td&gt;none&lt;/td&gt;&lt;td&gt;the copy forks&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;The CI checkout duplicates the pin into a place a lockfile does not see and makes local and CI builds differ. GitHub Packages is the package the operator did not want to depend on, and it needs a token locally. Vendoring forks the toolkit, against D-14.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Bump procedure&lt;/strong&gt; (one pull request per bump, titled &lt;code dir=&quot;auto&quot;&gt;docs(site): bump doc-kitty to &amp;#x3C;tag&gt; (&amp;#x3C;short sha&gt;)&lt;/code&gt;):&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Choose a doc-kitty release tag (&lt;code dir=&quot;auto&quot;&gt;v*&lt;/code&gt;) and resolve it to its commit: &lt;code dir=&quot;auto&quot;&gt;git ls-remote https://github.com/spec-kitty/doc-kitty refs/tags/&amp;#x3C;tag&gt;^{}&lt;/code&gt;. Pin a commit a release tag points at, unless a fix the site needs is not yet released; then say so in the pull request.&lt;/li&gt;
&lt;li&gt;Replace the SHA in &lt;code dir=&quot;auto&quot;&gt;site/package.json&lt;/code&gt;, align &lt;code dir=&quot;auto&quot;&gt;astro&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;@astrojs/starlight&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;@astrojs/markdown-remark&lt;/code&gt; with the peer ranges the new &lt;code dir=&quot;auto&quot;&gt;src/package.json&lt;/code&gt; declares, and run &lt;code dir=&quot;auto&quot;&gt;pnpm install&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;site/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Run the build and every gate of D-11 locally, and read doc-kitty’s &lt;code dir=&quot;auto&quot;&gt;CHANGELOG.md&lt;/code&gt; between the two tags for frontmatter or config changes.&lt;/li&gt;
&lt;li&gt;Open the pull request; the required build gate (D-11) must pass.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;A &lt;code dir=&quot;auto&quot;&gt;make docs-site-bump REF=&amp;#x3C;tag&gt;&lt;/code&gt; target that does steps 1 and 2 is part of the scaffold step.&lt;/p&gt;
&lt;h3 id=&quot;d-3-ci-uses-no-pat-derived&quot;&gt;D-3: CI uses no PAT &lt;em&gt;(derived)&lt;/em&gt;&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Install:&lt;/strong&gt; doc-kitty is public, so &lt;code dir=&quot;auto&quot;&gt;pnpm install&lt;/code&gt; needs no credential.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Deploy:&lt;/strong&gt; GitHub Pages deploys through OIDC (&lt;code dir=&quot;auto&quot;&gt;pages: write&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;id-token: write&lt;/code&gt;), as today.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Pages probe:&lt;/strong&gt; the existing probe keeps using &lt;code dir=&quot;auto&quot;&gt;${{ github.token }}&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;If doc-kitty ever becomes private, this record is amended before any credential is added. A PAT is not the fallback.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-4-the-site-deploys-at-the-domain-root-derived&quot;&gt;D-4: the site deploys at the domain root &lt;em&gt;(derived)&lt;/em&gt;&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;astro.config.mjs&lt;/code&gt; sets &lt;code dir=&quot;auto&quot;&gt;site: &apos;https://docs.spec-kitty.ai&apos;&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;base: &apos;/&apos;&lt;/code&gt;, and passes &lt;code dir=&quot;auto&quot;&gt;base: &apos;/&apos;&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;defineDocKittyIntegrations&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;CNAME&lt;/code&gt; moves to &lt;code dir=&quot;auto&quot;&gt;site/public/CNAME&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;Redirect targets are written base-less (&lt;code dir=&quot;auto&quot;&gt;/guides/x/&lt;/code&gt;). doc-kitty’s example prefixes targets with the base; with &lt;code dir=&quot;auto&quot;&gt;base: &apos;/&apos;&lt;/code&gt; that produces &lt;code dir=&quot;auto&quot;&gt;//guides/x/&lt;/code&gt;, so the site does not copy that line.&lt;/p&gt;
&lt;h3 id=&quot;d-5-the-url-contract-the-baseline-ledger-and-the-moves-ledger-absorbs-2358-url-shape-ruling-1-ledgers-and-generator-derived&quot;&gt;D-5: the URL contract, the baseline ledger and the moves ledger (absorbs #2358) &lt;em&gt;(URL shape: ruling 1; ledgers and generator: derived)&lt;/em&gt;&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;URL shape.&lt;/strong&gt; Every page is served at a directory URL (&lt;code dir=&quot;auto&quot;&gt;/guides/getting-started/&lt;/code&gt;, Astro’s default &lt;code dir=&quot;auto&quot;&gt;build.format: &apos;directory&apos;&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Baseline ledger.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;site/url-baseline.txt&lt;/code&gt; is the committed list of every URL the site has ever published (doc-kitty’s format: one site-relative URL per line, &lt;code dir=&quot;auto&quot;&gt;#&lt;/code&gt; comments). It is a living ledger:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;It is &lt;strong&gt;seeded once&lt;/strong&gt;, before cutover, from the union of:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;a site walk of the last DocFX build (&lt;code dir=&quot;auto&quot;&gt;scripts/docs/capture_baseline_urls.py --site-dir&lt;/code&gt;), which is the canonical capture and replaces the current 180-URL manifest;&lt;/li&gt;
&lt;li&gt;every key of &lt;code dir=&quot;auto&quot;&gt;scripts/docs/redirect_map.yaml&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The derive-from-source run for this record counts 668 + 163 = 831 URLs.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;It &lt;strong&gt;grows on publish&lt;/strong&gt;: a new page’s URL is appended in the pull request that publishes it.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;An entry is &lt;strong&gt;removed&lt;/strong&gt; only with a recorded amendment (date, pull request, ruling), as &lt;code dir=&quot;auto&quot;&gt;redirect_baseline_urls.json&lt;/code&gt; already does.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Moves ledger.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;site/moves.yaml&lt;/code&gt; is a standing, repository-level, append-only list of &lt;code dir=&quot;auto&quot;&gt;old route -&gt; new route&lt;/code&gt; moves. It replaces the mission-scoped &lt;code dir=&quot;auto&quot;&gt;occurrence_map.yaml&lt;/code&gt; binding that #2358 reports.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Redirect declarations.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;site/redirects.json&lt;/code&gt; (Astro’s &lt;code dir=&quot;auto&quot;&gt;redirects&lt;/code&gt; map) is generated from the two ledgers by one script, never edited by hand:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Every legacy &lt;code dir=&quot;auto&quot;&gt;X.html&lt;/code&gt; page URL redirects to the directory URL of its current page, &lt;code dir=&quot;auto&quot;&gt;X/&lt;/code&gt;, or to the page that &lt;code dir=&quot;auto&quot;&gt;moves.yaml&lt;/code&gt; says replaced it. A legacy &lt;code dir=&quot;auto&quot;&gt;dir/README.html&lt;/code&gt; (DocFX published a &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt; index under its own name; 16 such URLs today) redirects to &lt;code dir=&quot;auto&quot;&gt;dir/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Redirect chains are collapsed: every key points at a final, live route.&lt;/li&gt;
&lt;li&gt;A legacy &lt;code dir=&quot;auto&quot;&gt;dir/index.html&lt;/code&gt; URL gets &lt;strong&gt;no&lt;/strong&gt; declaration &lt;strong&gt;when &lt;code dir=&quot;auto&quot;&gt;dir/&lt;/code&gt; is a live section&lt;/strong&gt;. With the directory build format, the section’s page is always &lt;code dir=&quot;auto&quot;&gt;dist/dir/index.html&lt;/code&gt;, whether its source is &lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt;, and GitHub Pages serves it at that URL. A declaration there would collide with the page. A &lt;code dir=&quot;auto&quot;&gt;dir/index.html&lt;/code&gt; key whose section no longer exists is declared like any other key; 11 such keys sit in today’s map (&lt;code dir=&quot;auto&quot;&gt;1x/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;2x/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;3x/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;archive/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;archive/1x/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;archive/2x/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;explanation/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;how-to/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;recovery/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;reference/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tutorials/&lt;/code&gt;). &lt;strong&gt;Spike:&lt;/strong&gt; a key &lt;code dir=&quot;auto&quot;&gt;/tutorials/index.html&lt;/code&gt; emitted &lt;code dir=&quot;auto&quot;&gt;dist/tutorials/index.html/index.html&lt;/code&gt;, the gate covered it, and the emulation resolved it.&lt;/li&gt;
&lt;li&gt;A baseline URL whose page is unpublished (ruling 4: draft, excluded or retired) redirects to the nearest published page, normally its section hub (for example &lt;code dir=&quot;auto&quot;&gt;/plans/research/x.html&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;/plans/&lt;/code&gt;). Ruling 1 says no baseline URL breaks, and ruling 4 says the page is not published; a redirect to the hub satisfies both. 34 such URLs come from &lt;code dir=&quot;auto&quot;&gt;plans/&lt;/code&gt; alone (engineering-notes 21, investigations 11, research 2). An entry leaves the baseline only by a recorded amendment that cites an operator ruling.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Spike:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Astro emits a &lt;code dir=&quot;auto&quot;&gt;.html&lt;/code&gt; redirect key as a directory stub, &lt;code dir=&quot;auto&quot;&gt;dist/a/b.html/index.html&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Under the documented GitHub Pages serving rules (emulated), &lt;code dir=&quot;auto&quot;&gt;/a/b.html&lt;/code&gt; returns a 301 to &lt;code dir=&quot;auto&quot;&gt;/a/b.html/&lt;/code&gt;, then the stub’s meta refresh, then the page.&lt;/li&gt;
&lt;li&gt;doc-kitty’s &lt;code dir=&quot;auto&quot;&gt;check-redirect-coverage.mjs&lt;/code&gt; covers these keys, including a two-hop chain, without change.&lt;/li&gt;
&lt;li&gt;The real Pages service was not exercised. The canary in D-13 confirms it before cutover, so the GitHub Pages leg is &lt;strong&gt;UNVERIFIED&lt;/strong&gt; until then.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Fallback (evaluated, not chosen):&lt;/strong&gt; flat stubs (&lt;code dir=&quot;auto&quot;&gt;dist/a/b.html&lt;/code&gt; as a file) remove the 301 hop. The emulation serves them correctly, but doc-kitty’s coverage gate cannot see them, and they need a post-build step outside Astro. Use them only if the canary shows the directory 301 misbehaving; until upstream gap (b) lands they also need the gate override below.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Gate gap and interim.&lt;/strong&gt; doc-kitty’s gate looks only for &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;path&gt;/index.html&lt;/code&gt;, so it reports a legacy &lt;code dir=&quot;auto&quot;&gt;dir/index.html&lt;/code&gt; URL as uncovered even though the page is there. Until upstream gap (b) lands, the gate runs with a generated &lt;code dir=&quot;auto&quot;&gt;--redirects&lt;/code&gt; override mapping each &lt;code dir=&quot;auto&quot;&gt;dir/index.html&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;dir/&lt;/code&gt;. The override is used by the gate alone, never by the site, and the gate still checks that the target is live. The spike’s mutant run, with a dead target, failed as expected.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Full-corpus spike.&lt;/strong&gt; The generator rules above, run on the real ~831-URL baseline against a doc-kitty build of the real &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; tree (after the D-7 fixes, see the spike evidence), declared 789 redirects: 753 to the URL’s own page, 36 to a section hub (rule 4), with all 163 legacy map entries collapsed to their final page. 42 legacy &lt;code dir=&quot;auto&quot;&gt;dir/index.html&lt;/code&gt; URLs needed no declaration (rule 3). The coverage gate, run without &lt;code dir=&quot;auto&quot;&gt;--docs&lt;/code&gt;, reported &lt;strong&gt;831/831 covered&lt;/strong&gt;, and the GitHub Pages emulation resolved all 831.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;No silent excuse.&lt;/strong&gt; Run with &lt;code dir=&quot;auto&quot;&gt;--docs&lt;/code&gt; and drafts off, the gate accepts a baselined URL that ends at a draft page as “unpublished”. So the gate also runs a second time without &lt;code dir=&quot;auto&quot;&gt;--docs&lt;/code&gt;, which excuses nothing; rule 4 makes that run pass.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Dropped dashboards.&lt;/strong&gt; The kitty-specs dashboard URLs (&lt;code dir=&quot;auto&quot;&gt;/kitty-specs/**&lt;/code&gt;, including &lt;code dir=&quot;auto&quot;&gt;/kitty-specs/glossary.html&lt;/code&gt;) are generated, were never part of the baseline, and are not in the ~830. They are dropped (ruling 3). The site’s &lt;code dir=&quot;auto&quot;&gt;404&lt;/code&gt; page names the retirement for any &lt;code dir=&quot;auto&quot;&gt;/kitty-specs/&lt;/code&gt; path.&lt;/p&gt;
&lt;h3 id=&quot;d-6-scriptsdocs-keep--port--drop-derived&quot;&gt;D-6: &lt;code dir=&quot;auto&quot;&gt;scripts/docs&lt;/code&gt; keep / port / drop &lt;em&gt;(derived)&lt;/em&gt;&lt;/h3&gt;
&lt;p&gt;“Keep” means the script stays as it is and keeps its tests. “Port” means its job moves to doc-kitty or to &lt;code dir=&quot;auto&quot;&gt;site/&lt;/code&gt;, and the Python script is deleted in the step that ports it. “Drop” means it is deleted at DocFX retirement (D-13), or sooner when nothing calls it.&lt;/p&gt;































































































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Script&lt;/th&gt;&lt;th&gt;Verdict&lt;/th&gt;&lt;th&gt;Where its job goes&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;docs_index.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_inventory.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;inventory_lockfile.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;keep&lt;/td&gt;&lt;td&gt;They feed &lt;code dir=&quot;auto&quot;&gt;spec-kitty docs query&lt;/code&gt; and the page inventory, from &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; frontmatter. Updated for &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt; indexes.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;freshen_adr_inventory.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;keep (until gap a)&lt;/td&gt;&lt;td&gt;Keeps the era indexes (ruling 6); retired when doc-kitty’s ADR index lands.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;check_changelog_style.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;sync_changelog.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;check_spelling.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;keep&lt;/td&gt;&lt;td&gt;Source-level checks with no DocFX dependency.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;build_cli_reference.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;check_cli_reference_freshness.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;check_slash_command_freshness.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_typer_walker.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_render.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_guards.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;keep&lt;/td&gt;&lt;td&gt;They generate or check source pages.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;check_docs_freshness.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;version_leakage_check.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;keep&lt;/td&gt;&lt;td&gt;Re-pointed at &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt; indexes.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;audience_resolver.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;related_validator.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;description_length_check.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;port&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;dockitty-validate-frontmatter&lt;/code&gt; (audience, related, description length).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;relative_link_fixer.py&lt;/code&gt; (link check)&lt;/td&gt;&lt;td&gt;port&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;dockitty-check-links docs --strict&lt;/code&gt;. The one-shot fixer mode is dropped.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;capture_baseline_urls.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;keep for one run, then drop&lt;/td&gt;&lt;td&gt;Seeds &lt;code dir=&quot;auto&quot;&gt;site/url-baseline.txt&lt;/code&gt; from the last DocFX build.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;redirect_stub_generator.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;redirect_map.yaml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;redirect_baseline_urls.json&lt;/code&gt;&lt;/td&gt;&lt;td&gt;port&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;site/redirects.json&lt;/code&gt; generator + doc-kitty’s &lt;code dir=&quot;auto&quot;&gt;check-redirect-coverage&lt;/code&gt;. The map and manifest feed the seed, then retire.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;seo_postprocess.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;seo_verify.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;port&lt;/td&gt;&lt;td&gt;Starlight emits description, canonical and Open Graph; &lt;code dir=&quot;auto&quot;&gt;dockitty-assert-no-broken-links&lt;/code&gt; and the build artifact checks verify the output. Any check doc-kitty lacks is an upstream gap.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;glossary_linker.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;glossary_page/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;port (after #3024)&lt;/td&gt;&lt;td&gt;doc-kitty’s Contextive glossary and auto-link (D-10).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;plantuml_render.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;plantuml_invoke.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;plantuml_pins.json&lt;/code&gt;&lt;/td&gt;&lt;td&gt;port, then drop at retirement&lt;/td&gt;&lt;td&gt;doc-kitty’s build-time diagram render (its ADR-0040) against a self-hosted PlantUML server; see D-11. They and their tests are deleted with DocFX.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;generate_kitty_specs_docs.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;drop&lt;/td&gt;&lt;td&gt;Dashboards dropped (ruling 3).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;_published_pages.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;port&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;docs/_meta/sections.yaml&lt;/code&gt; plus the publication rules of D-8.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;frontmatter_backfill.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;frontmatter_backfill_sections.yaml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;adr_converter.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;keep for the migration, then drop&lt;/td&gt;&lt;td&gt;Reused by the frontmatter migration of D-7.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;bulk_ref_rewrite.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;rename_reconcile.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;touched_set_gates.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;keep for the README rename, then drop&lt;/td&gt;&lt;td&gt;Reused by the rename step; their binding to a closed Mission’s &lt;code dir=&quot;auto&quot;&gt;occurrence_map.yaml&lt;/code&gt; is replaced by &lt;code dir=&quot;auto&quot;&gt;site/moves.yaml&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;docs/docfx.json&lt;/code&gt;, every &lt;code dir=&quot;auto&quot;&gt;toc.yml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;docs/templates/spec-kitty/&lt;/code&gt; (incl. &lt;code dir=&quot;auto&quot;&gt;main.js&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;drop&lt;/td&gt;&lt;td&gt;At DocFX retirement.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;d-7-the-frontmatter-contract-mapping-derived&quot;&gt;D-7: the frontmatter contract mapping &lt;em&gt;(derived)&lt;/em&gt;&lt;/h3&gt;
&lt;p&gt;doc-kitty’s gate requires &lt;code dir=&quot;auto&quot;&gt;title&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;description&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;doc_status&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;updated&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;kind&lt;/code&gt;. The current corpus (913 Markdown files) maps as follows, in one mechanical migration per row group:&lt;/p&gt;


















































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Field&lt;/th&gt;&lt;th&gt;Today&lt;/th&gt;&lt;th&gt;On doc-kitty&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;kind&lt;/code&gt;&lt;/td&gt;&lt;td&gt;absent everywhere; 209 pages carry a lowercase Divio &lt;code dir=&quot;auto&quot;&gt;type&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;kind&lt;/code&gt; from &lt;code dir=&quot;auto&quot;&gt;type&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;how-to&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;How-To&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;explanation&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;Explanation&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;reference&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;Reference&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tutorial&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;Tutorial&lt;/code&gt;); section index pages get &lt;code dir=&quot;auto&quot;&gt;kind: Hub&lt;/code&gt;; ADRs get &lt;code dir=&quot;auto&quot;&gt;kind: ADR&lt;/code&gt;; the rest are classified in the migration step, and any page left unclassified is a migration failure. &lt;code dir=&quot;auto&quot;&gt;type&lt;/code&gt; stays only where it carries doc-kitty’s &lt;code dir=&quot;auto&quot;&gt;type&lt;/code&gt; meaning.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;audience&lt;/code&gt;&lt;/td&gt;&lt;td&gt;a path string such as &lt;code dir=&quot;auto&quot;&gt;docs/context/audience/internal/maintainer.md&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;[{ profile: internal/maintainer, guidance_text: … }]&lt;/code&gt;, which needs nested persona slugs (gap d). Personas stay under &lt;code dir=&quot;auto&quot;&gt;docs/context/audience/&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;doc_status&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;active&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;deprecated&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;draft&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;superseded&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;durable&lt;/code&gt;, plus &lt;code dir=&quot;auto&quot;&gt;closeout&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;point_in_time&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;proposal&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The five canonical values pass. &lt;code dir=&quot;auto&quot;&gt;closeout&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;point_in_time&lt;/code&gt; map to &lt;code dir=&quot;auto&quot;&gt;durable&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;proposal&lt;/code&gt; maps to &lt;code dir=&quot;auto&quot;&gt;draft&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;updated&lt;/code&gt;&lt;/td&gt;&lt;td&gt;a date (&lt;code dir=&quot;auto&quot;&gt;&apos;2026-10-26&apos;&lt;/code&gt;) on 724 pages; absent on the rest&lt;/td&gt;&lt;td&gt;Normalised to an instant (&lt;code dir=&quot;auto&quot;&gt;2026-10-26T00:00:00Z&lt;/code&gt;); ADRs take theirs from &lt;code dir=&quot;auto&quot;&gt;date&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;ADR metadata&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;Accepted&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Proposed&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Superseded&lt;/code&gt;) and &lt;code dir=&quot;auto&quot;&gt;date&lt;/code&gt;, with &lt;strong&gt;no &lt;code dir=&quot;auto&quot;&gt;doc_status&lt;/code&gt;&lt;/strong&gt; on all 226 ADRs that predate this record&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;kind: ADR&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;doc_status&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;Accepted&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;active&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Proposed&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;active&lt;/code&gt; (ruling 5), &lt;code dir=&quot;auto&quot;&gt;Superseded&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;superseded&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;updated&lt;/code&gt; from &lt;code dir=&quot;auto&quot;&gt;date&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;date&lt;/code&gt; stay, because core’s era indexes read them. This record already carries &lt;code dir=&quot;auto&quot;&gt;doc_status: active&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;related&lt;/code&gt;&lt;/td&gt;&lt;td&gt;repository paths (&lt;code dir=&quot;auto&quot;&gt;docs/changelog/index.md&lt;/code&gt;) on 413 pages, 32 of them outside &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tests/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;doc-kitty page slugs (&lt;code dir=&quot;auto&quot;&gt;changelog&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;adr/3.x/&amp;#x3C;file&gt;&lt;/code&gt; without &lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt;). References outside &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; move to &lt;code dir=&quot;auto&quot;&gt;external_references&lt;/code&gt;; references to unpublished pages follow D-8.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Excluded trees&lt;/td&gt;&lt;td&gt;archive, reports and convergence (242 files); 31 lack &lt;code dir=&quot;auto&quot;&gt;title&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;description&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Only the build-schema minimum: &lt;code dir=&quot;auto&quot;&gt;title&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;description&lt;/code&gt;, an &lt;code dir=&quot;auto&quot;&gt;audience&lt;/code&gt; list where present (D-8).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Index files&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt; in 60 folders; 4 also hold a &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&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;, &lt;code dir=&quot;auto&quot;&gt;architecture&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;Before the scaffold, the 4 folders get one index each, &lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt;. The three ADR-era &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt; files are redirect stubs pointing at their &lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt;; they are deleted, and their &lt;code dir=&quot;auto&quot;&gt;README.html&lt;/code&gt; URLs redirect to &lt;code dir=&quot;auto&quot;&gt;/adr/&amp;#x3C;era&gt;/&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;architecture/README.md&lt;/code&gt; is a 131-line landing page and is folded into &lt;code dir=&quot;auto&quot;&gt;architecture/index.md&lt;/code&gt;. After DocFX retirement, all 60 &lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt; become &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;indexBasename&lt;/code&gt; is &lt;code dir=&quot;auto&quot;&gt;README&lt;/code&gt; only (sequencing: D-1).&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;ADRs must gain &lt;code dir=&quot;auto&quot;&gt;doc_status&lt;/code&gt;.&lt;/strong&gt; doc-kitty treats a page with no &lt;code dir=&quot;auto&quot;&gt;doc_status&lt;/code&gt; as a draft, and a drafts-off build does not publish it. Without the ADR row above, every ADR would vanish from the live site.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The immutable corpus.&lt;/strong&gt; ADRs, plans, reports and changelog entries keep their &lt;strong&gt;body&lt;/strong&gt; byte for byte. A frontmatter-only change made by a recorded, mechanical migration is allowed. The migration step carries a test that hashes every immutable file’s body before and after and fails on any difference.&lt;/p&gt;
&lt;p&gt;One body change is allowed, and it needs the operator’s sign-off with this record: a &lt;strong&gt;mechanical link-target rewrite&lt;/strong&gt; driven by &lt;code dir=&quot;auto&quot;&gt;site/moves.yaml&lt;/code&gt;. The README rename alone touches links in 43 immutable files. The hash test normalises link targets through the moves ledger before comparing, so a rewritten link passes and any other change fails.&lt;/p&gt;
&lt;h3 id=&quot;d-8-what-is-published-derived-from-ruling-4&quot;&gt;D-8: what is published &lt;em&gt;(derived from ruling 4)&lt;/em&gt;&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/_meta/sections.yaml&lt;/code&gt; registers every published section. &lt;code dir=&quot;auto&quot;&gt;development&lt;/code&gt; is its own section. &lt;code dir=&quot;auto&quot;&gt;plans&lt;/code&gt; is registered with restricted &lt;code dir=&quot;auto&quot;&gt;feeds&lt;/code&gt; (no &lt;code dir=&quot;auto&quot;&gt;llms&lt;/code&gt;, no &lt;code dir=&quot;auto&quot;&gt;agent&lt;/code&gt;, no &lt;code dir=&quot;auto&quot;&gt;rss&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;plans/engineering-notes/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;plans/investigations/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;plans/research/&lt;/code&gt; take &lt;code dir=&quot;auto&quot;&gt;doc_status: draft&lt;/code&gt;. The live build runs with &lt;code dir=&quot;auto&quot;&gt;DK_PUBLISH_DRAFTS=off&lt;/code&gt;, so they are not published. doc-kitty defaults the setting to &lt;code dir=&quot;auto&quot;&gt;on&lt;/code&gt;, so &lt;code dir=&quot;auto&quot;&gt;site/.env.production&lt;/code&gt; sets it to &lt;code dir=&quot;auto&quot;&gt;off&lt;/code&gt;, in one place; workflows do not repeat it.&lt;/li&gt;
&lt;li&gt;An unpublished page’s old URL redirects to its section hub (D-5 rule 4).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;archive/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;reports/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;convergence/&lt;/code&gt;, together with the pages about the retired hosted and sync surfaces (listed in the publication step), are not published.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Exclusion mechanism.&lt;/strong&gt; doc-kitty has no section exclusion (gap f). Until it does, &lt;code dir=&quot;auto&quot;&gt;site/src/content.config.ts&lt;/code&gt; wraps &lt;code dir=&quot;auto&quot;&gt;docKittyDocsLoader&lt;/code&gt; with a filter that drops those route prefixes. &lt;strong&gt;Spike:&lt;/strong&gt; with the filter, an archived &lt;code dir=&quot;auto&quot;&gt;doc_status: deprecated&lt;/code&gt; page was absent from pages, hub links, the sitemap, &lt;code dir=&quot;auto&quot;&gt;llms.txt&lt;/code&gt;, the OKF export and the content graph. Without it, the same page was built and linked from two hubs.
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Limit of the shim.&lt;/strong&gt; The filter drops entries only after doc-kitty’s loader has validated them, so an excluded page must still pass the build schema (&lt;code dir=&quot;auto&quot;&gt;title&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;description&lt;/code&gt;, an &lt;code dir=&quot;auto&quot;&gt;audience&lt;/code&gt; list). In the full-corpus spike, 31 excluded pages (reports 24, convergence 4, archive 3) failed it. They get that minimum frontmatter in the D-7 migration until gap (f) lands.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;related&lt;/code&gt; must name published pages.&lt;/strong&gt; doc-kitty resolves every &lt;code dir=&quot;auto&quot;&gt;related&lt;/code&gt; entry against the built pages, and a dangling one is build-fatal. A published page may therefore not list a draft or excluded page there. In the full-corpus spike, 181 such entries had to go; the migration moves them into the body as ordinary links, which &lt;code dir=&quot;auto&quot;&gt;check-links&lt;/code&gt; judges, or drops them.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Gates scope.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;dockitty-validate-frontmatter&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;dockitty-check-links&lt;/code&gt; walk every file under &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt;, including the 242 files in archive, reports and convergence that are never published. They run over the published sections only; the unpublished trees get only the build-schema minimum above.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-9-llmstxt-is-generated-ruling-3&quot;&gt;D-9: &lt;code dir=&quot;auto&quot;&gt;llms.txt&lt;/code&gt; is generated &lt;em&gt;(ruling 3)&lt;/em&gt;&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;site/src/pages/llms.txt.ts&lt;/code&gt; mounts doc-kitty’s &lt;code dir=&quot;auto&quot;&gt;llmsTxtRoute&lt;/code&gt;. The route takes a title and a description only, so the version-stance block (current docs, runtime model, governance source, mission loop command, where 1.x and 2.x history lives) is inserted by a thin wrapper around its response until doc-kitty takes a preamble option (gap h). The hand-written &lt;code dir=&quot;auto&quot;&gt;docs/llms.txt&lt;/code&gt; is deleted at cutover.&lt;/p&gt;
&lt;h3 id=&quot;d-10-the-glossary-waits-on-3024-ruling-12&quot;&gt;D-10: the glossary waits on #3024 &lt;em&gt;(ruling 12)&lt;/em&gt;&lt;/h3&gt;
&lt;p&gt;The glossary step starts after #3024 settles the source (packs or &lt;code dir=&quot;auto&quot;&gt;docs/context&lt;/code&gt;). That step then generates the single &lt;code dir=&quot;auto&quot;&gt;.contextive/definitions.yaml&lt;/code&gt; doc-kitty reads. doc-kitty reads it from the site project, so it is &lt;code dir=&quot;auto&quot;&gt;site/.contextive/definitions.yaml&lt;/code&gt;, generated and not committed. Multi-file Contextive (&lt;code dir=&quot;auto&quot;&gt;imports:&lt;/code&gt;, gap e) is not needed for that. doc-kitty’s glossary integration writes generated term pages into &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;docsDir&gt;/glossary/&lt;/code&gt;, which here is &lt;code dir=&quot;auto&quot;&gt;docs/glossary/&lt;/code&gt;, inside core’s tree. Until doc-kitty takes an output path (gap e), that folder is gitignored and excluded from &lt;code dir=&quot;auto&quot;&gt;docs_index.py&lt;/code&gt; and the page inventory. The current glossary page is a dashboard page (&lt;code dir=&quot;auto&quot;&gt;/kitty-specs/glossary.html&lt;/code&gt;), outside the baseline, so cutover does not wait for the glossary step.&lt;/p&gt;
&lt;h3 id=&quot;d-11-a-required-pull-request-build-gate-derived&quot;&gt;D-11: a required pull-request build gate &lt;em&gt;(derived)&lt;/em&gt;&lt;/h3&gt;
&lt;p&gt;A &lt;code dir=&quot;auto&quot;&gt;docs-site&lt;/code&gt; job runs on every pull request that touches &lt;code dir=&quot;auto&quot;&gt;docs/**&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;site/**&lt;/code&gt; or its own workflow. It installs with the frozen lockfile and builds with drafts off (D-8). It then runs these gates, each with &lt;code dir=&quot;auto&quot;&gt;--astro-config astro.config.mjs&lt;/code&gt; (D-1), over the published sections (D-8):&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;dockitty-validate-frontmatter&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;dockitty-check-links --strict&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;dockitty-check-redirect-coverage url-baseline.txt dist --docs ../docs --astro-config astro.config.mjs --declared-redirects redirects.json&lt;/code&gt;, plus the interim override of D-5;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;dockitty-assert-no-broken-links dist --base / --site https://docs.spec-kitty.ai&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;a check that &lt;code dir=&quot;auto&quot;&gt;redirects.json&lt;/code&gt; equals its generated form.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Diagrams.&lt;/strong&gt; doc-kitty renders PlantUML at build time to static SVG against a self-hosted server, never &lt;code dir=&quot;auto&quot;&gt;plantuml.com&lt;/code&gt;. Its own CI runs &lt;code dir=&quot;auto&quot;&gt;plantuml/plantuml-server&lt;/code&gt; as a job-level &lt;code dir=&quot;auto&quot;&gt;services:&lt;/code&gt; container on &lt;code dir=&quot;auto&quot;&gt;localhost:8091&lt;/code&gt; with a readiness wait, sets &lt;code dir=&quot;auto&quot;&gt;DK_PLANTUML_SERVER_URL=http://localhost:8091/svg/&lt;/code&gt;, and checks with &lt;code dir=&quot;auto&quot;&gt;plantuml-guard.mjs&lt;/code&gt; (used by &lt;code dir=&quot;auto&quot;&gt;assert-build-artifacts.mjs&lt;/code&gt;) that no &lt;code dir=&quot;auto&quot;&gt;plantuml.com&lt;/code&gt; URL and no non-self-hosted default reaches the build. PlantUML only renders in doc-kitty’s build mode. Left alone, the mode follows whether a Playwright Chromium happens to be installed, so local and CI builds could differ. The site therefore sets &lt;code dir=&quot;auto&quot;&gt;diagrams: true&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;DK_DIAGRAM_BUILD_RENDER=build&lt;/code&gt;, and the job installs a pinned Playwright Chromium (core has 18 Mermaid and 5 PlantUML sources). Core’s &lt;code dir=&quot;auto&quot;&gt;docs-site&lt;/code&gt; job and the deploy workflow adopt doc-kitty’s server pattern, with one change: the image is pinned by digest, not &lt;code dir=&quot;auto&quot;&gt;:jetty&lt;/code&gt;, keeping core’s practice of pinning third-party build inputs by digest. The current &lt;code dir=&quot;auto&quot;&gt;docker --network=none&lt;/code&gt; isolation does not carry over, because the server runs as a service container. A diagram’s &lt;code dir=&quot;auto&quot;&gt;!include&lt;/code&gt; of a remote URL is therefore the remaining egress path, and the diagrams step restricts it in the server’s configuration or refuses such includes at source.&lt;/p&gt;
&lt;p&gt;The job lives in &lt;code dir=&quot;auto&quot;&gt;ci-router.yml&lt;/code&gt;, behind a path filter for &lt;code dir=&quot;auto&quot;&gt;docs/**&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;site/**&lt;/code&gt; registered in &lt;code dir=&quot;auto&quot;&gt;gate_selection.py&lt;/code&gt;, and is added to &lt;code dir=&quot;auto&quot;&gt;router-gate&lt;/code&gt;’s &lt;code dir=&quot;auto&quot;&gt;needs:&lt;/code&gt;. That makes it required, with no &lt;code dir=&quot;auto&quot;&gt;continue-on-error&lt;/code&gt;. It cannot join &lt;code dir=&quot;auto&quot;&gt;ci-aggregate.yml&lt;/code&gt;’s &lt;code dir=&quot;auto&quot;&gt;aggregate-gate&lt;/code&gt;: that workflow runs on &lt;code dir=&quot;auto&quot;&gt;workflow_run&lt;/code&gt;, and GitHub Actions has no cross-workflow &lt;code dir=&quot;auto&quot;&gt;needs:&lt;/code&gt;. The router’s own tests (for example &lt;code dir=&quot;auto&quot;&gt;tests/ci/test_docs_lint_job.py&lt;/code&gt;) pin the wiring. The deploy workflow builds with the same steps, so main can never deploy a site no pull request built.&lt;/p&gt;
&lt;h3 id=&quot;d-12-invariants-kept-derived&quot;&gt;D-12: invariants kept &lt;em&gt;(derived)&lt;/em&gt;&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Packaging.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;site/**&lt;/code&gt; is excluded from the sdist; the wheel only ships its declared packages. &lt;code dir=&quot;auto&quot;&gt;tests/cross_cutting/packaging/test_packaging_safety.py&lt;/code&gt; asserts it on the built archive.
&lt;ul&gt;
&lt;li&gt;The sdist’s bare &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt; include is gitignore-style. Today it already ships 31 &lt;code dir=&quot;auto&quot;&gt;docs/**/README.md&lt;/code&gt; and 676 &lt;code dir=&quot;auto&quot;&gt;kitty-specs/**/README.md&lt;/code&gt; files, and the README rename would add 56 more, net. Anchoring it to &lt;code dir=&quot;auto&quot;&gt;/README.md&lt;/code&gt; is a pre-existing defect, tracked in &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6926&quot;&gt;#6926&lt;/a&gt;, and must land before the rename.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fork guard.&lt;/strong&gt; Every new workflow’s automated trigger (push, schedule, &lt;code dir=&quot;auto&quot;&gt;workflow_run&lt;/code&gt;) carries the core-repository guard pinned by &lt;code dir=&quot;auto&quot;&gt;tests/ci/test_fork_guard.py&lt;/code&gt;. Pull-request and dispatch runs work on forks.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Pages probe.&lt;/strong&gt; The deploy workflow keeps the probe-then-configure job, the 404-skips and other-status-fails semantics, and the &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;-only, core-repository-only deploy pinned by &lt;code dir=&quot;auto&quot;&gt;tests/release/test_release_ci_ownership.py&lt;/code&gt;. The test is updated with the workflow, never loosened.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-13-parallel-run-rollback-and-docfx-retirement-derived&quot;&gt;D-13: parallel run, rollback and DocFX retirement &lt;em&gt;(derived)&lt;/em&gt;&lt;/h3&gt;
&lt;p&gt;A repository has one Pages site, so “parallel” means built in parallel, not served in parallel.&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Parallel run.&lt;/strong&gt; From the scaffold step on, every pull request and every push to &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; builds the doc-kitty site and runs the D-11 gates. The deploy workflow still publishes DocFX.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Canary.&lt;/strong&gt; The deploy job may only publish from &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; in the core repository, so the canary is a short production window on &lt;code dir=&quot;auto&quot;&gt;docs.spec-kitty.ai&lt;/code&gt;. It is announced, and docs merges to &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; are frozen for its duration (a push would queue a DocFX deploy in the &lt;code dir=&quot;auto&quot;&gt;pages&lt;/code&gt; concurrency group). Before cutover, one manually dispatched run deploys the doc-kitty build, probes a sample of baseline URLs over HTTP (one &lt;code dir=&quot;auto&quot;&gt;.html&lt;/code&gt; redirect key, one chain, one &lt;code dir=&quot;auto&quot;&gt;dir/index.html&lt;/code&gt;, one &lt;code dir=&quot;auto&quot;&gt;dir/README.html&lt;/code&gt;, one directory URL), and redeploys DocFX. This is where the D-5 GitHub Pages result stops being UNVERIFIED.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cutover.&lt;/strong&gt; One pull request switches the deploy job’s artifact to &lt;code dir=&quot;auto&quot;&gt;site/dist&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Rollback.&lt;/strong&gt; Revert the cutover pull request. The DocFX path stays intact until retirement, and the README rename waits for retirement (D-1), so the rollback works for that whole window.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Retirement.&lt;/strong&gt; After one Spec Kitty release ships with the doc-kitty site live, a pull request removes DocFX: &lt;code dir=&quot;auto&quot;&gt;docfx.json&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;toc.yml&lt;/code&gt;, the template, the .NET setup and the scripts marked “drop” in D-6. It also updates or deletes the 26 Python files that read &lt;code dir=&quot;auto&quot;&gt;docfx.json&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;toc.yml&lt;/code&gt;, most of them under &lt;code dir=&quot;auto&quot;&gt;tests/docs/&lt;/code&gt;, plus &lt;code dir=&quot;auto&quot;&gt;tests/_support/docfx_reports_guard.py&lt;/code&gt; and the terminology scope helper. The README rename (D-1) follows in its own pull requests.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;d-14-upstream-gaps-go-to-doc-kitty-derived&quot;&gt;D-14: upstream gaps go to doc-kitty &lt;em&gt;(derived)&lt;/em&gt;&lt;/h3&gt;
&lt;p&gt;Core does not patch, fork or vendor doc-kitty. A gap is filed upstream; core carries at most a thin, named, consumer-side shim with a removal trigger. The shims are the loader filter (D-8), the &lt;code dir=&quot;auto&quot;&gt;llms.txt&lt;/code&gt; wrapper (D-9) and the gate override (D-5).&lt;/p&gt;
&lt;p&gt;Gaps filed or to file:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;(a) ADR index for date-named, era-foldered ADRs with a frontmatter-status fallback;&lt;/li&gt;
&lt;li&gt;(b) the coverage gate resolves an exact &lt;code dir=&quot;auto&quot;&gt;*.html&lt;/code&gt; file before &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;path&gt;/index.html&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;(c) GitHub &lt;code dir=&quot;auto&quot;&gt;&gt; [!NOTE]&lt;/code&gt; alerts (7 files use them; the spike rendered them as literal text);&lt;/li&gt;
&lt;li&gt;(d) nested persona slugs;&lt;/li&gt;
&lt;li&gt;(e) multi-file Contextive, &lt;code dir=&quot;auto&quot;&gt;imports:&lt;/code&gt;, and an output path for generated glossary pages;&lt;/li&gt;
&lt;li&gt;(f) excluding sections from the build, before schema validation;&lt;/li&gt;
&lt;li&gt;(g) hub-style card grids for mission and glossary pages, styled with the operator’s “chromed” design system, that is doc-kitty’s site-chrome theme (&lt;code dir=&quot;auto&quot;&gt;specKittyTheme&lt;/code&gt;, the &lt;code dir=&quot;auto&quot;&gt;--dk-*&lt;/code&gt; tokens);&lt;/li&gt;
&lt;li&gt;(h) an &lt;code dir=&quot;auto&quot;&gt;llms.txt&lt;/code&gt; preamble option;&lt;/li&gt;
&lt;li&gt;(i) a fixture for a &lt;code dir=&quot;auto&quot;&gt;docsDir&lt;/code&gt; outside the site project.&lt;/li&gt;
&lt;/ul&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 toolkit owns rendering, metadata and gates; seven post-processing steps leave core.&lt;/li&gt;
&lt;li&gt;A pull request builds and gates the site; DocFX’s deploy-time-only verification ends.&lt;/li&gt;
&lt;li&gt;No URL in the ledger breaks, and the ledger has a standing home (#2358).&lt;/li&gt;
&lt;li&gt;No .NET toolchain and no credential beyond the workflow token.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Node and pnpm join core’s CI toolchain for the docs job.&lt;/li&gt;
&lt;li&gt;The frontmatter migration touches most of the 913 Markdown files once (frontmatter only).&lt;/li&gt;
&lt;li&gt;Three consumer-side shims live until their upstream gaps close.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;.html&lt;/code&gt; redirects cost one extra 301 on GitHub Pages.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The kitty-specs dashboards and the dashboard glossary page go dark until the hub-card work (gap g) brings mission pages back.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The D-11 gate is green on the scaffold pull request with the full ~830-URL ledger.&lt;/li&gt;
&lt;li&gt;The D-13 canary probes pass on the real Pages service.&lt;/li&gt;
&lt;li&gt;After cutover, #2361’s post-deploy smoketest and #2362’s nightly crawl are green.&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;git-dependency-pinned-by-commit-chosen&quot;&gt;Git dependency pinned by commit (chosen)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Good, because the lockfile is the one pin, local and CI builds match, and no credential is needed.&lt;/li&gt;
&lt;li&gt;Bad, because a bump is a hand-chosen SHA rather than a semver range, and the toolkit’s own dependencies resolve in core’s lockfile.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;ci-checkout-at-a-pinned-sha&quot;&gt;CI checkout at a pinned SHA&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Good, because it needs no registry.&lt;/li&gt;
&lt;li&gt;Bad, because the pin lives outside the lockfile and local builds need a second clone.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;github-packages&quot;&gt;GitHub Packages&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Good, because it is versioned and integrity-hashed.&lt;/li&gt;
&lt;li&gt;Bad, because it is the separately authorised package the operator steered away from, and installing it locally needs a PAT.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;vendoring&quot;&gt;Vendoring&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Good, because it is self-contained.&lt;/li&gt;
&lt;li&gt;Bad, because it forks the toolkit and hides gaps from upstream.&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;Spike evidence, reproduction steps and the GitHub Pages emulator: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-ops/research/01M6947JAAGSMJTM6ST9D429BG/spike-evidence.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-ops/research/01M6947JAAGSMJTM6ST9D429BG/spike-evidence.md&lt;/code&gt;&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Delivery.&lt;/strong&gt; The remaining steps are sub-issues of #6100:
&lt;ul&gt;
&lt;li&gt;ledgers and the dual-index folders: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6927&quot;&gt;#6927&lt;/a&gt; (D-5, absorbs #2358 and #3914) and &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6928&quot;&gt;#6928&lt;/a&gt; (D-1);&lt;/li&gt;
&lt;li&gt;frontmatter: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6929&quot;&gt;#6929&lt;/a&gt;, the build-blocking migration, and &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6931&quot;&gt;#6931&lt;/a&gt;, contract completion (D-7);&lt;/li&gt;
&lt;li&gt;site: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6930&quot;&gt;#6930&lt;/a&gt;, the scaffold and &lt;code dir=&quot;auto&quot;&gt;docs-site&lt;/code&gt; job (D-1, D-2, D-11); &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6932&quot;&gt;#6932&lt;/a&gt;, publication (D-8); &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6933&quot;&gt;#6933&lt;/a&gt;, redirects (D-5); &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6934&quot;&gt;#6934&lt;/a&gt;, &lt;code dir=&quot;auto&quot;&gt;llms.txt&lt;/code&gt; (D-9);&lt;/li&gt;
&lt;li&gt;rendering: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6935&quot;&gt;#6935&lt;/a&gt;, render parity, and &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6936&quot;&gt;#6936&lt;/a&gt;, diagrams (D-11);&lt;/li&gt;
&lt;li&gt;rollout: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6937&quot;&gt;#6937&lt;/a&gt;, the required gate; &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6938&quot;&gt;#6938&lt;/a&gt;, canary and cutover, with #2361; &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6943&quot;&gt;#6943&lt;/a&gt;, DocFX retirement; then &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6939&quot;&gt;#6939&lt;/a&gt;, the README rename (D-13);&lt;/li&gt;
&lt;li&gt;after upstream work: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6940&quot;&gt;#6940&lt;/a&gt;, glossary (after #3024); &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6941&quot;&gt;#6941&lt;/a&gt;, mission pages (gap g); &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6942&quot;&gt;#6942&lt;/a&gt;, ADR index (gap a);&lt;/li&gt;
&lt;li&gt;packaging: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6926&quot;&gt;#6926&lt;/a&gt; (D-12).&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;The upstream doc-kitty issue drafts (a)–(i) sit in the same folder as the spike evidence.&lt;/li&gt;
&lt;li&gt;doc-kitty commit the spike ran against: &lt;code dir=&quot;auto&quot;&gt;494f2d878e2e4766d9859a4f073efb793ad86900&lt;/code&gt; (doc-toolkit 0.5.0 plus unreleased commits).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-11-09&quot;&gt;Amendment 2026-11-09&lt;/h2&gt;
&lt;p&gt;Recorded with #6932 (publication). D-8’s text above is unchanged; this section records how it is carried out and where it drifted.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Folder exclusion runs through doc-kitty’s &lt;code dir=&quot;auto&quot;&gt;exclude&lt;/code&gt; option.&lt;/strong&gt; Gap (f) closed upstream (doc-kitty ADR-0070) before #6932 started. &lt;code dir=&quot;auto&quot;&gt;site/astro.config.mjs&lt;/code&gt; passes &lt;code dir=&quot;auto&quot;&gt;exclude&lt;/code&gt; from the generated &lt;code dir=&quot;auto&quot;&gt;site/dockitty-contract.json&lt;/code&gt;, which &lt;code dir=&quot;auto&quot;&gt;scripts/docs/site_contract.py&lt;/code&gt; projects from &lt;code dir=&quot;auto&quot;&gt;EXCLUDED_FOLDERS&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;scripts/docs/_dockitty_contract.py&lt;/code&gt;. No loader-filter shim exists: &lt;code dir=&quot;auto&quot;&gt;site/src/content.config.ts&lt;/code&gt; does not filter. The D-14 shim list therefore no longer includes the loader filter.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Working-note folders are drafts.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;plans/engineering-notes/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;plans/investigations/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;plans/research/&lt;/code&gt; are named once, as &lt;code dir=&quot;auto&quot;&gt;DRAFT_FOLDERS&lt;/code&gt; in the contract module. Every page in them takes &lt;code dir=&quot;auto&quot;&gt;doc_status: draft&lt;/code&gt; (a frontmatter-only change; the bodies are history). They are not excluded folders, because &lt;code dir=&quot;auto&quot;&gt;exclude&lt;/code&gt; would also drop them from the frontmatter and link gates.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Retired single pages are archived.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;exclude&lt;/code&gt; takes folders only (per-file exclusion is asked upstream in &lt;code dir=&quot;auto&quot;&gt;spec-kitty/doc-kitty#312&lt;/code&gt;), and the retired hosted and sync pages are single files spread over several sections. The operator decided on 2026-11-09 to move them under &lt;code dir=&quot;auto&quot;&gt;docs/archive/&amp;#x3C;section&gt;/&lt;/code&gt;. The move changed one thing in their bodies: 14 relative links in 7 of the 10 moved pages were re-pointed to the same targets, the path adjusted for the new location. Nothing else in a body changed. This is accepted under C-001 as part of a move. Each old route gets an append-only &lt;code dir=&quot;auto&quot;&gt;site/moves.yaml&lt;/code&gt; row to its section hub (D-5 rule 4).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;One authority for the unpublished set.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;unpublished_routes()&lt;/code&gt; in the contract module derives it: pages in an excluded folder, pages in a draft folder, and pages that are not published. The built-site check &lt;code dir=&quot;auto&quot;&gt;scripts/docs/site_built_check.py&lt;/code&gt; reads it after the build, and so does the redirect generator (#6933). The check walks the built pages, links, sitemap, OKF export, search index, &lt;code dir=&quot;auto&quot;&gt;llms.txt&lt;/code&gt; and the agent index.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The link gates run with priced debt.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;dockitty-check-links --strict&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;dockitty-assert-no-broken-links&lt;/code&gt; run in the shared build through &lt;code dir=&quot;auto&quot;&gt;scripts/docs/site_link_gates.py&lt;/code&gt;. It fails on any problem that &lt;code dir=&quot;auto&quot;&gt;site/link-debt.json&lt;/code&gt; does not list. That file lists only problems whose source is immutable history (dated ADRs, &lt;code dir=&quot;auto&quot;&gt;plans/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;reports/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;changelog/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;archive/&lt;/code&gt;), whose bodies are never rewritten (Standing Order #5, burn-down #7489). A problem in an editable page is fixed, not listed. The relative-link test reads the same file. It is not a ratchet.&lt;/li&gt;
&lt;li&gt;Clarification 2026-11-10: a live hub (&lt;code dir=&quot;auto&quot;&gt;kind: Hub&lt;/code&gt;) is never an immutable source, and neither is a &lt;code dir=&quot;auto&quot;&gt;plans/&lt;/code&gt; page whose &lt;code dir=&quot;auto&quot;&gt;doc_status&lt;/code&gt; is &lt;code dir=&quot;auto&quot;&gt;active&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;durable&lt;/code&gt;, or whose &lt;code dir=&quot;auto&quot;&gt;kind&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;doc_status&lt;/code&gt; cannot be read; such a page fixes its broken links instead of pricing them in &lt;code dir=&quot;auto&quot;&gt;site/link-debt.json&lt;/code&gt;. One predicate, &lt;code dir=&quot;auto&quot;&gt;is_debt_eligible_source&lt;/code&gt;, judges both the link gates and the relative-link debt.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;One frontmatter edit to a dated ADR.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;docs/adr/3.x/2026-08-16-1-pack-metadata-manifest-unification.md&lt;/code&gt; dropped &lt;code dir=&quot;auto&quot;&gt;related: plans/investigations/2026-08-pack-level-metadata-manifest&lt;/code&gt;. That page is now a draft (working-note folder, above), and a &lt;code dir=&quot;auto&quot;&gt;related&lt;/code&gt; entry that names an unpublished page is a build-fatal dangling reference in doc-kitty’s &lt;code dir=&quot;auto&quot;&gt;Related&lt;/code&gt; block. The ADR body is unchanged.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-11-10&quot;&gt;Amendment 2026-11-10&lt;/h2&gt;
&lt;p&gt;Recorded with #6933 (redirects). D-5’s and D-14’s text above is unchanged. This section records how the redirect layer is carried out with doc-kitty v0.7.0 (&lt;code dir=&quot;auto&quot;&gt;5acb83c&lt;/code&gt;), and where it departs from them.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The map is doc-kitty’s &lt;code dir=&quot;auto&quot;&gt;legacyHtmlRedirects&lt;/code&gt;, not Astro’s &lt;code dir=&quot;auto&quot;&gt;redirects&lt;/code&gt;.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Every one of the 970 baseline routes ends in &lt;code dir=&quot;auto&quot;&gt;.html&lt;/code&gt;. doc-kitty refuses &lt;code dir=&quot;auto&quot;&gt;.html&lt;/code&gt; keys in Astro’s &lt;code dir=&quot;auto&quot;&gt;redirects&lt;/code&gt; on static output (doc-kitty #253), so Astro’s &lt;code dir=&quot;auto&quot;&gt;redirects&lt;/code&gt; stays empty.&lt;/li&gt;
&lt;li&gt;The generated map is &lt;code dir=&quot;auto&quot;&gt;site/legacy-redirects.json&lt;/code&gt;, not D-5’s &lt;code dir=&quot;auto&quot;&gt;site/redirects.json&lt;/code&gt;. It is a flat JSON object with no comment key, because doc-kitty validates every key as a legacy &lt;code dir=&quot;auto&quot;&gt;.html&lt;/code&gt; path.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;site/astro.config.mjs&lt;/code&gt; reads it, and doc-kitty writes one flat stub per key (&lt;code dir=&quot;auto&quot;&gt;dist/a/b.html&lt;/code&gt;).&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;D-5’s fallback is now the mechanism.&lt;/strong&gt; Flat stubs, the fallback D-5 evaluated and did not choose, are what upstream writes. The coverage gate sees them (doc-kitty ADR-0071), and they remove the 301 hop D-5’s spike worried about. The D-13 canary still decides the GitHub Pages leg.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The gate override is retired.&lt;/strong&gt; Gap (b) closed upstream: the gate resolves &lt;code dir=&quot;auto&quot;&gt;/a/index.html&lt;/code&gt; to the file that &lt;code dir=&quot;auto&quot;&gt;/a/&lt;/code&gt; serves. Both runs report 970/970 with no &lt;code dir=&quot;auto&quot;&gt;--redirects&lt;/code&gt; override, so the D-14 shim list no longer includes the gate override.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;One generator, one authority per input.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;scripts/docs/site_redirects.py&lt;/code&gt; derives the map from three inputs:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the URL baseline;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;site/moves.yaml&lt;/code&gt;, with chains collapsed by &lt;code dir=&quot;auto&quot;&gt;moves_ledger.collapse&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;the published set: &lt;code dir=&quot;auto&quot;&gt;route_of&lt;/code&gt; of every page minus &lt;code dir=&quot;auto&quot;&gt;unpublished_routes()&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;--check&lt;/code&gt; fails the build when the committed map is stale.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Rule 4 lives in the generator.&lt;/strong&gt; While DocFX still publishes drafts, a &lt;code dir=&quot;auto&quot;&gt;moves.yaml&lt;/code&gt; row away from a draft page fails DocFX’s own map check. The generator therefore redirects an unpublished page’s route to its nearest published ancestor. Rule 4 moves into the ledger only once #6943 retires DocFX. Until then the two sites may answer the same legacy URL differently: DocFX’s own map (&lt;code dir=&quot;auto&quot;&gt;redirect_stub_generator.py&lt;/code&gt;) has no rule 4 and no resource rule. That difference is accepted until the #6943 cutover.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Rule 5: resources.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;docs/assets/spec-kitty-backlog.html&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;docs/assets/spec-kitty-evolution-v1-to-v3.html&lt;/code&gt; are standalone HTML that DocFX copied as resources; doc-kitty publishes only pages.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Operator ruling 2026-11-10: they redirect to the &lt;code dir=&quot;auto&quot;&gt;/assets/&lt;/code&gt; hub.&lt;/li&gt;
&lt;li&gt;The generator applies this as a rule, not a list: a baseline route backed by a non-page file under &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; goes to its nearest published ancestor.&lt;/li&gt;
&lt;li&gt;Any other baseline route with no page and no move is refused.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Counts at this amendment.&lt;/strong&gt; 970 baseline routes and 929 keys:&lt;/p&gt;





























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Kind of route&lt;/th&gt;&lt;th&gt;Count&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;its own page&lt;/td&gt;&lt;td&gt;571&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;its moved page&lt;/td&gt;&lt;td&gt;305&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;a section hub, page unpublished&lt;/td&gt;&lt;td&gt;51&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;a section hub, resource&lt;/td&gt;&lt;td&gt;2&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;no key: a live, unmoved &lt;code dir=&quot;auto&quot;&gt;dir/index.html&lt;/code&gt; (rule 3)&lt;/td&gt;&lt;td&gt;41&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;D-5’s “11 dead-section &lt;code dir=&quot;auto&quot;&gt;dir/index.html&lt;/code&gt; keys” are now 21, because more sections moved since.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The gate runs twice, as D-5 says, and proves itself.&lt;/strong&gt; The shared build runs &lt;code dir=&quot;auto&quot;&gt;dockitty-check-redirect-coverage&lt;/code&gt; once with &lt;code dir=&quot;auto&quot;&gt;--docs&lt;/code&gt; and the declared map, and once with neither. A self-test then runs the gate against a hard-linked copy of the built site with three mutants: a dead target, a missing key and a draft-excused URL. It requires each verdict, so a gate that stops failing is caught.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Redirect stubs are not publications.&lt;/strong&gt; The built-site check recognises doc-kitty’s stub through one predicate, &lt;code dir=&quot;auto&quot;&gt;redirect_stub_target&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;scripts/docs/_dockitty_contract.py&lt;/code&gt;. That predicate mirrors doc-kitty’s &lt;code dir=&quot;auto&quot;&gt;REDIRECT_STUB_RE&lt;/code&gt;.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;page&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;render&lt;/code&gt; surfaces skip stubs.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;link&lt;/code&gt; surface still reports a stub whose target is unpublished.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-11-11&quot;&gt;Amendment 2026-11-11&lt;/h2&gt;
&lt;p&gt;Recorded with #6938 (canary, first of two pull requests; the cutover is the second). D-11’s and D-13’s text above is unchanged. This section records how the D-13 canary is carried out.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;The canary is a dispatch input of the deploy workflow.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;docs-pages.yml&lt;/code&gt; takes &lt;code dir=&quot;auto&quot;&gt;canary&lt;/code&gt; (boolean, off by default) on &lt;code dir=&quot;auto&quot;&gt;workflow_dispatch&lt;/code&gt;. A push to &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;, or a dispatch without it, runs the DocFX path as before: the same &lt;code dir=&quot;auto&quot;&gt;pages&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;build&lt;/code&gt; jobs, and a &lt;code dir=&quot;auto&quot;&gt;deploy&lt;/code&gt; that runs only after a successful DocFX build.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The canary builds through the one shared definition (D-11).&lt;/strong&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;canary-build&lt;/code&gt; calls &lt;code dir=&quot;auto&quot;&gt;docs-site-build.yml&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;pages-artifact: true&lt;/code&gt; and its own artifact name, &lt;code dir=&quot;auto&quot;&gt;github-pages-canary&lt;/code&gt;, a new input of the shared build that defaults to &lt;code dir=&quot;auto&quot;&gt;github-pages&lt;/code&gt;. The two Pages artifacts of one run never collide.&lt;/li&gt;
&lt;li&gt;So the deploy workflow and the &lt;code dir=&quot;auto&quot;&gt;docs-site&lt;/code&gt; gate now share one build definition, which was the open part of #6937.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The restore is ready before production changes.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;canary-deploy&lt;/code&gt; publishes the canary with &lt;code dir=&quot;auto&quot;&gt;actions/deploy-pages&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;artifact_name: github-pages-canary&lt;/code&gt;, environment &lt;code dir=&quot;auto&quot;&gt;github-pages&lt;/code&gt;) only when both the canary build and the DocFX build succeeded, from &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; of the core repository. Only this job holds &lt;code dir=&quot;auto&quot;&gt;pages: write&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;id-token: write&lt;/code&gt; among the canary jobs.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;DocFX is always republished.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;canary-probe&lt;/code&gt; runs after the canary is live. The DocFX &lt;code dir=&quot;auto&quot;&gt;deploy&lt;/code&gt; job needs it and runs on &lt;code dir=&quot;auto&quot;&gt;!cancelled() || inputs.canary&lt;/code&gt;, so on a canary it republishes DocFX whatever the probe found, and also after a cancel. &lt;code dir=&quot;auto&quot;&gt;needs.build.result == &apos;success&apos;&lt;/code&gt; still blocks it after a failed DocFX build. A failed canary job leaves the run red.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The probe’s URL classes.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;scripts/docs/site_live_probe.py&lt;/code&gt; derives one URL per class from the committed ledgers (&lt;code dir=&quot;auto&quot;&gt;site/url-baseline.txt&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;site/moves.yaml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;site/legacy-redirects.json&lt;/code&gt;), the first in sorted order. A class with no candidate refuses. The classes are:
&lt;ul&gt;
&lt;li&gt;a legacy &lt;code dir=&quot;auto&quot;&gt;.html&lt;/code&gt; key to its own page;&lt;/li&gt;
&lt;li&gt;a moved-chain key, whose &lt;code dir=&quot;auto&quot;&gt;moves.yaml&lt;/code&gt; destination moved again;&lt;/li&gt;
&lt;li&gt;a live &lt;code dir=&quot;auto&quot;&gt;dir/index.html&lt;/code&gt; with no key (D-5 rule 3) and its directory URL;&lt;/li&gt;
&lt;li&gt;a &lt;code dir=&quot;auto&quot;&gt;dir/README.html&lt;/code&gt; key;&lt;/li&gt;
&lt;li&gt;the site root and &lt;code dir=&quot;auto&quot;&gt;/llms.txt&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;/kitty-specs/glossary.html&lt;/code&gt;, which D-5 drops and which must answer 404.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;What the probe asserts.&lt;/strong&gt; Redirects are not followed, so a 3xx fails: flat stubs exist to remove that hop. A page answers 200 and is not a stub. A key answers 200 with a stub (judged by &lt;code dir=&quot;auto&quot;&gt;redirect_stub_target&lt;/code&gt;) whose target equals the map’s, and the target answers 200 with a page. Each URL gets bounded retries for Pages propagation, under a 300 s wall-clock budget that covers the whole request.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The gate runs the probe too.&lt;/strong&gt; The shared build serves &lt;code dir=&quot;auto&quot;&gt;site/dist&lt;/code&gt; on loopback and runs the probe once with one attempt. A ledger change that drops a class, or a build that stops answering one, fails a pull request before any canary.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Operation.&lt;/strong&gt; The operator dispatches the canary on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; in an announced window with docs merges frozen, because a push would queue a DocFX deploy in the &lt;code dir=&quot;auto&quot;&gt;pages&lt;/code&gt; concurrency group. The D-5 GitHub Pages leg stays UNVERIFIED until that run passes. The post-deploy smoketest of #2361 lands with the cutover and reuses the probe.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-11-11-cutover&quot;&gt;Amendment 2026-11-11 (cutover)&lt;/h2&gt;
&lt;p&gt;Recorded with #6938 (cutover, the second of its two pull requests) and #2361 (post-deploy smoketest). D-9’s, D-11’s and D-13’s text above is unchanged. This section records how D-13 step 3 is carried out and what step 4, the rollback, restores.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The canary passed.&lt;/strong&gt; The operator dispatched it on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; in an announced window: run &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/actions/runs/43027580608&quot;&gt;43027580608&lt;/a&gt;, report on &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6938#issuecomment-6796965517&quot;&gt;#6938&lt;/a&gt;. All 8 URL classes of the probe passed on the real GitHub Pages service, and DocFX was then restored byte-identical. The D-5 GitHub Pages leg is VERIFIED.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The deploy publishes the doc-kitty build.&lt;/strong&gt; In &lt;code dir=&quot;auto&quot;&gt;docs-pages.yml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;build&lt;/code&gt; calls the shared &lt;code dir=&quot;auto&quot;&gt;docs-site-build.yml&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;pages-artifact: true&lt;/code&gt;, under the default artifact name &lt;code dir=&quot;auto&quot;&gt;github-pages&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;deploy&lt;/code&gt; publishes that artifact with &lt;code dir=&quot;auto&quot;&gt;actions/deploy-pages&lt;/code&gt;, from &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; of the core repository only, after a successful build. D-11’s last sentence now holds: &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; deploys only a site built by the definition the &lt;code dir=&quot;auto&quot;&gt;docs-site&lt;/code&gt; pull-request gate runs.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The Pages probe stays.&lt;/strong&gt; The &lt;code dir=&quot;auto&quot;&gt;pages&lt;/code&gt; probe-then-configure job, its 404-skips and other-status-fails semantics, the &lt;code dir=&quot;auto&quot;&gt;pages&lt;/code&gt; concurrency group (no cancel in progress) and the fork guard are unchanged (D-12). &lt;code dir=&quot;auto&quot;&gt;actions/configure-pages&lt;/code&gt; is now pinned by commit, like every other action in the workflow.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Token permissions.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The workflow default is &lt;code dir=&quot;auto&quot;&gt;contents: read&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;pages&lt;/code&gt; job holds &lt;code dir=&quot;auto&quot;&gt;pages: read&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;build&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;smoketest&lt;/code&gt; hold &lt;code dir=&quot;auto&quot;&gt;contents: read&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Only &lt;code dir=&quot;auto&quot;&gt;deploy&lt;/code&gt; holds &lt;code dir=&quot;auto&quot;&gt;pages: write&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;id-token: write&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Post-deploy smoketest (#2361).&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;What it is: a &lt;code dir=&quot;auto&quot;&gt;smoketest&lt;/code&gt; job with &lt;code dir=&quot;auto&quot;&gt;needs: deploy&lt;/code&gt;, on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; of the core repository only.&lt;/li&gt;
&lt;li&gt;What it runs: &lt;code dir=&quot;auto&quot;&gt;python3 -m scripts.docs.site_live_probe https://docs.spec-kitty.ai&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Which URLs: the probe and its URL classes are the canary’s (Amendment 2026-11-11 above), derived from the committed ledgers.&lt;/li&gt;
&lt;li&gt;On failure: a mismatch fails the job and turns the run red.&lt;/li&gt;
&lt;li&gt;No alert issue: the operator decided that the red run is the signal, so #2361’s optional auto-filed alert issue is not adopted.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The canary is retired into the smoketest.&lt;/strong&gt; The &lt;code dir=&quot;auto&quot;&gt;canary&lt;/code&gt; dispatch input and the &lt;code dir=&quot;auto&quot;&gt;canary-build&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;canary-deploy&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;canary-probe&lt;/code&gt; jobs are removed. A canary of the site already live would duplicate the smoketest. A plain dispatch on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; deploys and smoketests like a push; on another branch it only builds.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;DocFX stops running in the deploy workflow.&lt;/strong&gt; The DocFX &lt;code dir=&quot;auto&quot;&gt;build&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;deploy&lt;/code&gt; jobs are removed. Their sources stay until #6943 (D-13 step 5): &lt;code dir=&quot;auto&quot;&gt;docs/docfx.json&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;toc.yml&lt;/code&gt;, the template, the DocFX scripts and their tests. In the meantime no CI job builds DocFX.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;docs/llms.txt&lt;/code&gt; is deleted (D-9).&lt;/strong&gt; The site generates &lt;code dir=&quot;auto&quot;&gt;/llms.txt&lt;/code&gt; with the version stance (&lt;code dir=&quot;auto&quot;&gt;site/src/pages/llms.txt.ts&lt;/code&gt;), and the smoketest probes it. The test that kept the hand copy’s stance equal to &lt;code dir=&quot;auto&quot;&gt;LLMS_STANCE&lt;/code&gt; now asserts the hand copy is absent. &lt;code dir=&quot;auto&quot;&gt;docs/docfx.json&lt;/code&gt; no longer lists it as a resource. Two archived pages still link to it; their bodies are immutable, so &lt;code dir=&quot;auto&quot;&gt;site/link-debt.json&lt;/code&gt; prices both links (&lt;code dir=&quot;auto&quot;&gt;relative-links&lt;/code&gt; gate, burn-down #7489).&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;What a revert restores (D-13 step 4).&lt;/strong&gt; Reverting the cutover pull request brings back, in &lt;code dir=&quot;auto&quot;&gt;docs-pages.yml&lt;/code&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the DocFX &lt;code dir=&quot;auto&quot;&gt;build&lt;/code&gt; job and its &lt;code dir=&quot;auto&quot;&gt;deploy&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;the dispatch-only canary jobs and their &lt;code dir=&quot;auto&quot;&gt;canary&lt;/code&gt; input;&lt;/li&gt;
&lt;li&gt;the DocFX-era push path filter and the workflow-level &lt;code dir=&quot;auto&quot;&gt;pages: write&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;id-token: write&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;actions/configure-pages&lt;/code&gt; on the floating &lt;code dir=&quot;auto&quot;&gt;@v6&lt;/code&gt; tag instead of its commit pin.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;It reverts the comment-only updates in &lt;code dir=&quot;auto&quot;&gt;ci-router.yml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;docs-site-build.yml&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;tests/ci/test_docs_site_job.py&lt;/code&gt; that describe the cutover.&lt;/p&gt;
&lt;p&gt;It also brings back &lt;code dir=&quot;auto&quot;&gt;docs/llms.txt&lt;/code&gt; with its &lt;code dir=&quot;auto&quot;&gt;docs/docfx.json&lt;/code&gt; resource entry (and drops the two &lt;code dir=&quot;auto&quot;&gt;site/link-debt.json&lt;/code&gt; entries for it), and the tests that pinned the DocFX deploy (&lt;code dir=&quot;auto&quot;&gt;tests/release/test_release_ci_ownership.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tests/ci/test_nightly_tooling_cache.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tests/docs/test_docs_seo.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tests/docs/test_dockitty_contract.py&lt;/code&gt;). The revert’s own push to &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; then deploys DocFX. It does not touch the doc-kitty build gate (&lt;code dir=&quot;auto&quot;&gt;docs-site&lt;/code&gt;). The rollback works until #6943, as D-13 says.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Done when (#6938).&lt;/strong&gt; The first post-merge deploy is green and its smoketest passes on &lt;code dir=&quot;auto&quot;&gt;docs.spec-kitty.ai&lt;/code&gt;. Both can only be shown after the merge, so they are followed up on #6938.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-11-12-docfx-retired&quot;&gt;Amendment 2026-11-12 (DocFX retired)&lt;/h2&gt;
&lt;p&gt;Recorded with #6943. D-6’s, D-13’s and D-14’s text above is unchanged. This section records how D-13 step 5 is carried out.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;The release gate is waived (operator decision, 2026-11-12).&lt;/strong&gt; D-13 step 5 waits for one Spec Kitty release shipped with the doc-kitty site live. The last release, v4.0.0rc8, predates the cutover, so the gate is waived. The evidence that stands in for it:
&lt;ul&gt;
&lt;li&gt;the production canary, run &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/actions/runs/43027580608&quot;&gt;43027580608&lt;/a&gt;, report on &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6938#issuecomment-6796965517&quot;&gt;#6938&lt;/a&gt;;&lt;/li&gt;
&lt;li&gt;the post-cutover runs of &lt;code dir=&quot;auto&quot;&gt;docs-pages.yml&lt;/code&gt; on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;, green on every completed run since the merge of #7558 in all four jobs (&lt;code dir=&quot;auto&quot;&gt;pages&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;build&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;deploy&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;smoketest&lt;/code&gt;), for example run &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/actions/runs/43265541140&quot;&gt;43265541140&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;What was removed.&lt;/strong&gt;
&lt;ul&gt;
&lt;li&gt;The DocFX sources: &lt;code dir=&quot;auto&quot;&gt;docs/docfx.json&lt;/code&gt;, the eight &lt;code dir=&quot;auto&quot;&gt;toc.yml&lt;/code&gt; files, &lt;code dir=&quot;auto&quot;&gt;docs/templates/&lt;/code&gt; (with &lt;code dir=&quot;auto&quot;&gt;main.js&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;main.css&lt;/code&gt; and its hub page, whose route was never in the URL baseline), and the static resources &lt;code dir=&quot;auto&quot;&gt;docs/docfx.json&lt;/code&gt; copied (&lt;code dir=&quot;auto&quot;&gt;docs/CNAME&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;docs/robots.txt&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;docs/.nojekyll&lt;/code&gt;) with the DocFX build-output &lt;code dir=&quot;auto&quot;&gt;docs/.gitignore&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;site/public/&lt;/code&gt; carries the site’s own &lt;code dir=&quot;auto&quot;&gt;CNAME&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;robots.txt&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;templates&lt;/code&gt; left &lt;code dir=&quot;auto&quot;&gt;docs/_meta/sections.yaml&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The D-6 “drop” scripts: &lt;code dir=&quot;auto&quot;&gt;plantuml_render.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;plantuml_invoke.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;plantuml_pins.json&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;generate_kitty_specs_docs.py&lt;/code&gt;. Its &lt;code dir=&quot;auto&quot;&gt;slugify&lt;/code&gt;, which &lt;code dir=&quot;auto&quot;&gt;docs_index.py&lt;/code&gt; imported, moved into &lt;code dir=&quot;auto&quot;&gt;docs_index.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The D-6 “port” scripts whose port is done, removed in this step rather than in their porting steps because their only runner was the DocFX build: &lt;code dir=&quot;auto&quot;&gt;redirect_stub_generator.py&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;redirect_map.yaml&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;redirect_baseline_urls.json&lt;/code&gt; (ported to &lt;code dir=&quot;auto&quot;&gt;site_redirects.py&lt;/code&gt;, #6933; &lt;code dir=&quot;auto&quot;&gt;rename_reconcile.py&lt;/code&gt; now cross-checks &lt;code dir=&quot;auto&quot;&gt;site/legacy-redirects.json&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;moves_ledger.derive_redirect_map&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;validate&lt;/code&gt; went too); &lt;code dir=&quot;auto&quot;&gt;seo_postprocess.py&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;seo_verify.py&lt;/code&gt; (Starlight emits the tags and &lt;code dir=&quot;auto&quot;&gt;site_built_check_render.py&lt;/code&gt; proves them); &lt;code dir=&quot;auto&quot;&gt;description_length_check.py&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;_published_pages.py&lt;/code&gt; (the published set is &lt;code dir=&quot;auto&quot;&gt;published_pages()&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;_dockitty_contract.py&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;dockitty-validate-frontmatter&lt;/code&gt; enforces the description band). &lt;code dir=&quot;auto&quot;&gt;capture_baseline_urls.py&lt;/code&gt; ran its one run.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;glossary_linker.py&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;glossary_page/&lt;/code&gt;, ahead of D-6’s “port (after #3024)”. They post-processed DocFX’s rendered HTML and imported the dropped generator, and nothing has run them since the cutover. The port to doc-kitty’s Contextive glossary and auto-link (D-10) reuses no Python, and #6940 still tracks the glossary page and the auto-link; #3024 is still open. The glossary source &lt;code dir=&quot;auto&quot;&gt;.kittify/glossaries/spec_kitty_core.yaml&lt;/code&gt; stays.&lt;/li&gt;
&lt;li&gt;The tests of the removed modules. The tests that guarded a still-live rule read the contract now: the published-page title and description rule (&lt;code dir=&quot;auto&quot;&gt;tests/docs/test_docs_seo.py&lt;/code&gt;) and the guard that &lt;code dir=&quot;auto&quot;&gt;docs/reports/&lt;/code&gt; is never published (&lt;code dir=&quot;auto&quot;&gt;tests/_support/reports_unpublished_guard.py&lt;/code&gt;, used by the three terminology tests).&lt;/li&gt;
&lt;li&gt;The PlantUML-jar steps of the router’s &lt;code dir=&quot;auto&quot;&gt;tests (docs)&lt;/code&gt; job.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;What stays.&lt;/strong&gt; The D-6 “keep” scripts and the migration-era tools (&lt;code dir=&quot;auto&quot;&gt;frontmatter_backfill.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;adr_converter.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;dockitty_frontmatter_migration.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;bulk_ref_rewrite.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;rename_reconcile.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;touched_set_gates.py&lt;/code&gt;) keep their D-6 verdicts. The ported frontmatter readers &lt;code dir=&quot;auto&quot;&gt;audience_resolver.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;related_validator.py&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;relative_link_fixer.py&lt;/code&gt; read no DocFX file and keep running.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Gates.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;tests/docs/test_legacy_docsite_retired.py&lt;/code&gt; keeps the DocFX sources and modules absent and fails on an import of a removed module. &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_legacy_docsite_named_nowhere.py&lt;/code&gt; fails on any tracked living file that names DocFX; it excludes only immutable history (dated ADRs, &lt;code dir=&quot;auto&quot;&gt;docs/changelog/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;CHANGELOG.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;docs/plans/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;docs/reports/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;docs/archive/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt;, the append-only &lt;code dir=&quot;auto&quot;&gt;kitty-ops/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; records, the #4562 bulk-edit record and a dated timeline page) and two generated files.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Rollback posture.&lt;/strong&gt; D-13 step 4’s rollback, “revert the cutover pull request”, no longer works on its own. Going back to DocFX now needs a revert of the #6943 pull request and of #7558. Rolling forward is preferred.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;D-13 is complete apart from the README rename (#6939, D-1),&lt;/strong&gt; which follows in its own pull requests with the content pass (#3891). The D-14 shim list is unchanged.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-11-12-section-indexes-renamed&quot;&gt;Amendment 2026-11-12 (section indexes renamed)&lt;/h2&gt;
&lt;p&gt;Recorded with #6939. D-1’s, D-5’s, D-7’s and D-13’s text above is unchanged. This section records how D-1’s index-file sequencing and D-13 step 5’s README rename are carried out.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;59 files, not 60.&lt;/strong&gt; Every &lt;code dir=&quot;auto&quot;&gt;docs/**/index.md&lt;/code&gt; is now &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt;, moved with &lt;code dir=&quot;auto&quot;&gt;git mv&lt;/code&gt;. D-1 counted 60; &lt;code dir=&quot;auto&quot;&gt;docs/templates/index.md&lt;/code&gt; left with the DocFX template in #6943. The 4 folders #6928 resolved (&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;, &lt;code dir=&quot;auto&quot;&gt;architecture&lt;/code&gt;) are among the 59.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;indexBasename&lt;/code&gt; is &lt;code dir=&quot;auto&quot;&gt;&apos;README&apos;&lt;/code&gt; only.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;INDEX_BASENAMES&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;scripts/docs/_dockitty_contract.py&lt;/code&gt; is &lt;code dir=&quot;auto&quot;&gt;(&quot;README&quot;,)&lt;/code&gt;, and the generated &lt;code dir=&quot;auto&quot;&gt;site/dockitty-contract.json&lt;/code&gt; follows. &lt;code dir=&quot;auto&quot;&gt;tests/docs/test_section_index_basename.py&lt;/code&gt; fails on any &lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt; under &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt;, with a planted control that proves the walk reports one.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The moves ledger records each rename.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;site/moves.yaml&lt;/code&gt; gains one entry per folder, &lt;code dir=&quot;auto&quot;&gt;/x/index.html -&gt; /x/README.html&lt;/code&gt; (ref &lt;code dir=&quot;auto&quot;&gt;#6939&lt;/code&gt;). Eight folders had moved &lt;code dir=&quot;auto&quot;&gt;README.md -&gt; index.md&lt;/code&gt; before (#3914, #6928), so their new entry points back at a route with an older move away. The ledger stays append-only and now reads a later entry into a route as superseding that route’s earlier move away: the route is live again (&lt;code dir=&quot;auto&quot;&gt;moves_ledger.collapse&lt;/code&gt;). A route that moves to itself is still refused as a cycle, and a return to a route with no page is still refused by the redirect generator.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Links.&lt;/strong&gt; Every link to a renamed page was rewritten from the ledger’s own &lt;code dir=&quot;auto&quot;&gt;#6939&lt;/code&gt; pairs (&lt;code dir=&quot;auto&quot;&gt;moves_ledger.source_pairs&lt;/code&gt;): the &lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt; segment of a link target that resolves to a renamed page became &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt;, and nothing else in the target changed. Living pages also had exact path mentions rewritten. In immutable files (dated ADRs, &lt;code dir=&quot;auto&quot;&gt;plans/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;reports/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;changelog/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;archive/&lt;/code&gt;) only link targets changed, the one body change D-7 allows; a check that re-applies the rewrite to each such file’s previous body and compares the result with the new body found no other change. Prose and frontmatter that name an old path are history and stay. &lt;code dir=&quot;auto&quot;&gt;site/link-debt.json&lt;/code&gt; follows the two rewritten targets it prices.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Redirects.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;site/legacy-redirects.json&lt;/code&gt; is byte-identical. A legacy &lt;code dir=&quot;auto&quot;&gt;dir/index.html&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;dir/README.html&lt;/code&gt; URL folds to &lt;code dir=&quot;auto&quot;&gt;dir/&lt;/code&gt; by the legacy site’s own file names, whatever &lt;code dir=&quot;auto&quot;&gt;INDEX_BASENAMES&lt;/code&gt; holds, and D-5 rule 3 excuses a &lt;code dir=&quot;auto&quot;&gt;dir/index.html&lt;/code&gt; that ends at its own live directory page when it is unmoved or its collapsed move is an index rename; any other move of it that lands on &lt;code dir=&quot;auto&quot;&gt;dir/&lt;/code&gt;, for example through a hub fallback, is still refused. An index rename keeps its directory URL, so it needs no baseline entry and no redirect key (&lt;code dir=&quot;auto&quot;&gt;moves_ledger.is_index_rename&lt;/code&gt;, read by the ledger tests and by &lt;code dir=&quot;auto&quot;&gt;rename_reconcile.py&lt;/code&gt;). The directory build still writes each section page to &lt;code dir=&quot;auto&quot;&gt;dist/&amp;#x3C;dir&gt;/index.html&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Readers.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;freshen_adr_inventory.py&lt;/code&gt; writes the era table to &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt;. It still reads a lone &lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt; but never writes one: adding or pruning a row there refuses with “era index not found”. &lt;code dir=&quot;auto&quot;&gt;check_generated_docs_untouched.py&lt;/code&gt; matches ADR era table rows per era folder, so a table that moves between the landing files of one era adds no row. &lt;code dir=&quot;auto&quot;&gt;dockitty_frontmatter_migration.py&lt;/code&gt; no longer skips the 4 #6928 folders’ &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt;, which is their section index again, and &lt;code dir=&quot;auto&quot;&gt;site_built_check.py&lt;/code&gt; resolves a folder’s metadata route through &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A known gap upstream.&lt;/strong&gt; The built-in pack’s docs lint (&lt;code dir=&quot;auto&quot;&gt;packs/built-in/assets/docs_structural_lint.py&lt;/code&gt;, sourced from spec-kitty-open-packs) still reads a section’s landing page as &lt;code dir=&quot;auto&quot;&gt;index.md&lt;/code&gt;. Its &lt;code dir=&quot;auto&quot;&gt;check_index_completeness&lt;/code&gt; skips a section without one, so the curated-complete check on &lt;code dir=&quot;auto&quot;&gt;docs/architecture/&lt;/code&gt; does not run until the asset reads &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt;. Packs are not edited here; the fix belongs upstream.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Generated surfaces.&lt;/strong&gt; The retrieval index and the page inventory are not edited in the pull request; the post-merge &lt;code dir=&quot;auto&quot;&gt;ci/regen-docs-index&lt;/code&gt; bot regenerates them on the new paths.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;D-1 and D-13 are complete.&lt;/strong&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
