Skip to content

ADR: the docsite is built with doc-kitty, consumed as a pinned git dependency, at directory URLs with every legacy URL redirected

The docsite is built with doc-kitty, consumed as a pinned git dependency, at directory URLs with every legacy URL redirected

Status: Proposed (2026-10-31). The operator accepts it by merging the pull request that carries it.

What was ruled and what is derived.

  • Ruled by the operator (2026-10-31, #6100 decisions comment). Numbered as in the comment; “ruling N” below refers to this list.
    1. URL scheme. Directory URLs; every current *.html URL (about 830) redirects to its new address; no baseline URL breaks.
    2. Section index file. README.md. The 56 folders whose index is index.md are renamed, and the 4 folders holding both files are resolved.
    3. Features only DocFX has. The kitty-specs mission dashboards, their JSON-LD and the template’s main.js are dropped for now. doc-kitty’s generated llms.txt 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.
    4. What is published. plans/ (restricted feeds) and development/ (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.
    5. Proposed ADRs take doc_status: active.
    6. ADR index. doc-kitty gains support for date-named ADRs in era folders, with a frontmatter status fallback; core’s era indexes stay until then.
    7. #3891 stays separate; #2358, #3914, #2361 and #2362 move under #6100.
    8. #648 stays standalone.
    9. #2302 is written after cutover, in spec-kitty-open-packs.
    10. Toolkit. The build consumes spec-kitty/doc-kitty directly; this record says how: a pinned git dependency or checkout, or the package doc-kitty publishes.
    11. Collisions. Moves and renames are allowed; each open docs PR resolves its own conflicts when it merges.
    12. Glossary. #3024 settles the source of truth first; one definitions.yaml is then generated from it.
  • Operator steer relayed with the step-1 brief (2026-10-31), not in the comment: prefer not to depend on a separately authorised package. D-2 weighs it.
  • Derived: every decision below marked (derived), and the spike results, which are evidence, not rulings.

Date: 2026-10-31

Deciders: Stijn Dejongh (operator). Derived clauses are proposed by this record for the operator’s sign-off.

Technical Story:


Context and Problem Statement

docs.spec-kitty.ai is built by DocFX (.NET) from docs/ and then post-processed by six Python scripts, in seven steps, in .github/workflows/docs-pages.yml: 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 main or 2.x 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 docs-build-pr.yml that no longer exists.

doc-kitty is Spec Kitty’s own Astro + Starlight docs toolkit. It owns the frontmatter contract, the section registry, llms.txt, 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.

Decision Drivers

  • No published URL breaks. About 830 URLs are live today: 668 current pages (derived from docfx.json’s content globs against the tree at this record’s base) plus 163 legacy URLs already redirected by scripts/docs/redirect_map.yaml.
  • One authority per concern. 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.
  • No credential that is not already in the workflow. No PAT. The operator also steered away from depending on a separately authorised package (the step-1 brief).
  • docs/ stays where it is. spec-kitty docs query reads docs/development/docs-retrieval-index.yaml, and agents, scripts and links across the repository address docs/ paths.
  • A defect is caught on the pull request, not after deploy.

Considered Options

For consuming doc-kitty (ruling 10 leaves the choice to this record):

  1. A pnpm git dependency pinned by commit, github:spec-kitty/doc-kitty#<sha>&path:/src, recorded in site/pnpm-lock.yaml.
  2. A CI checkout of spec-kitty/doc-kitty at a pinned SHA, linked as file: or link:.
  3. doc-kitty’s published package, @spec-kitty/doc-toolkit on GitHub Packages.
  4. Vendoring the toolkit source into core.

For the site’s place in the repository: a site/ sub-project reading ../docs, or moving the content under the site project.

Decision Outcome

Chosen options: a site/ sub-project that reads ../docs, 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.

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)

  • The docsite is built by doc-kitty. DocFX is retired as set out in D-13.
  • site/ holds the Astro project: package.json, pnpm-lock.yaml, astro.config.mjs, src/content.config.ts, src/pages/llms.txt.ts, public/ (with CNAME and robots.txt), url-baseline.txt, moves.yaml and redirects.json.
  • defineDocKittyIntegrations({ docsDir: '../docs', indexBasename: 'README', … }) and docKittyDocsLoader({ base: '../docs' }). The two must agree; doc-kitty requires it.
  • Index-file sequencing. DocFX emits a section page only from index.md. Renaming a folder’s index.md to README.md while DocFX still deploys would make that section’s /dir/ and /dir/index.html return 404 on the live site.
    • During the parallel run (D-13), the site sets indexBasename: ['README', 'index'], as doc-kitty’s own example does.
    • The 4 folders holding both files are resolved before the scaffold build, keeping index.md as the index, because two index files in one folder collapse to one route.
    • After DocFX retirement (D-13 step 5), all 60 index.md files become README.md (the 56 of ruling 2, plus the 4 resolved folders, which keep index.md until then); indexBasename then narrows to 'README'. The rename waits for retirement, not just cutover, so that reverting the cutover still redeploys a DocFX site whose sections all build.
    • Every dockitty-* gate is run with --astro-config astro.config.mjs. 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 README alone, so it would misread the 60 index.md files during the parallel run.
  • docs/ stays at the repository root. That keeps spec-kitty docs query, every in-repo link and every scripts/docs tool that reads docs/ working unchanged.
  • docs/_meta/sections.yaml is the section registry (doc-kitty’s shape); it is authored content, not generated.
  • Spike: a build with docsDir: '../docs' from a sibling site/ project emitted every page, with each README.md 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).

D-2: doc-kitty is consumed as a pnpm git dependency pinned by commit (derived)

site/package.json declares:

"@spec-kitty/doc-toolkit": "github:spec-kitty/doc-kitty#<40-character commit SHA>&path:/src"

pnpm records the commit, the subpath and the repository in site/pnpm-lock.yaml. CI installs with pnpm install --frozen-lockfile. Spike: this resolved from the public repository with no token, built the site, and put the toolkit’s dockitty-* gate binaries on the path.

Git dependency by commit (chosen)CI checkout at a SHAGitHub Packages (@spec-kitty/doc-toolkit)Vendoring
Pin authoritythe lockfile, one placea SHA in the workflow, plus a file: path the lockfile cannot verifythe lockfile (version + integrity)the copied tree
Local buildpnpm installneeds a second clone at the right pathneeds a PAT with read:packages in ~/.npmrcworks
CI credentialnone (public repository)none (public repository)packages: read, and package access granted to this repositorynone
Separately authorised packagenonoyes (rejected: the operator’s steer, and a PAT locally)no
Drift from upstreamnonenonenonethe copy forks

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.

Bump procedure (one pull request per bump, titled docs(site): bump doc-kitty to <tag> (<short sha>)):

  1. Choose a doc-kitty release tag (v*) and resolve it to its commit: git ls-remote https://github.com/spec-kitty/doc-kitty refs/tags/<tag>^{}. 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.
  2. Replace the SHA in site/package.json, align astro, @astrojs/starlight and @astrojs/markdown-remark with the peer ranges the new src/package.json declares, and run pnpm install in site/.
  3. Run the build and every gate of D-11 locally, and read doc-kitty’s CHANGELOG.md between the two tags for frontmatter or config changes.
  4. Open the pull request; the required build gate (D-11) must pass.

A make docs-site-bump REF=<tag> target that does steps 1 and 2 is part of the scaffold step.

D-3: CI uses no PAT (derived)

  • Install: doc-kitty is public, so pnpm install needs no credential.
  • Deploy: GitHub Pages deploys through OIDC (pages: write, id-token: write), as today.
  • Pages probe: the existing probe keeps using ${{ github.token }}.
  • If doc-kitty ever becomes private, this record is amended before any credential is added. A PAT is not the fallback.

D-4: the site deploys at the domain root (derived)

astro.config.mjs sets site: 'https://docs.spec-kitty.ai' and base: '/', and passes base: '/' to defineDocKittyIntegrations. CNAME moves to site/public/CNAME.

Redirect targets are written base-less (/guides/x/). doc-kitty’s example prefixes targets with the base; with base: '/' that produces //guides/x/, so the site does not copy that line.

D-5: the URL contract, the baseline ledger and the moves ledger (absorbs #2358) (URL shape: ruling 1; ledgers and generator: derived)

URL shape. Every page is served at a directory URL (/guides/getting-started/, Astro’s default build.format: 'directory').

Baseline ledger. site/url-baseline.txt is the committed list of every URL the site has ever published (doc-kitty’s format: one site-relative URL per line, # comments). It is a living ledger:

  • It is seeded once, before cutover, from the union of:

    • a site walk of the last DocFX build (scripts/docs/capture_baseline_urls.py --site-dir), which is the canonical capture and replaces the current 180-URL manifest;
    • every key of scripts/docs/redirect_map.yaml.

    The derive-from-source run for this record counts 668 + 163 = 831 URLs.

  • It grows on publish: a new page’s URL is appended in the pull request that publishes it.

  • An entry is removed only with a recorded amendment (date, pull request, ruling), as redirect_baseline_urls.json already does.

Moves ledger. site/moves.yaml is a standing, repository-level, append-only list of old route -> new route moves. It replaces the mission-scoped occurrence_map.yaml binding that #2358 reports.

Redirect declarations. site/redirects.json (Astro’s redirects map) is generated from the two ledgers by one script, never edited by hand:

  1. Every legacy X.html page URL redirects to the directory URL of its current page, X/, or to the page that moves.yaml says replaced it. A legacy dir/README.html (DocFX published a README.md index under its own name; 16 such URLs today) redirects to dir/.
  2. Redirect chains are collapsed: every key points at a final, live route.
  3. A legacy dir/index.html URL gets no declaration when dir/ is a live section. With the directory build format, the section’s page is always dist/dir/index.html, whether its source is index.md or README.md, and GitHub Pages serves it at that URL. A declaration there would collide with the page. A dir/index.html key whose section no longer exists is declared like any other key; 11 such keys sit in today’s map (1x/, 2x/, 3x/, archive/, archive/1x/, archive/2x/, explanation/, how-to/, recovery/, reference/, tutorials/). Spike: a key /tutorials/index.html emitted dist/tutorials/index.html/index.html, the gate covered it, and the emulation resolved it.
  4. 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 /plans/research/x.html → /plans/). 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 plans/ alone (engineering-notes 21, investigations 11, research 2). An entry leaves the baseline only by a recorded amendment that cites an operator ruling.

Spike:

  • Astro emits a .html redirect key as a directory stub, dist/a/b.html/index.html.
  • Under the documented GitHub Pages serving rules (emulated), /a/b.html returns a 301 to /a/b.html/, then the stub’s meta refresh, then the page.
  • doc-kitty’s check-redirect-coverage.mjs covers these keys, including a two-hop chain, without change.
  • The real Pages service was not exercised. The canary in D-13 confirms it before cutover, so the GitHub Pages leg is UNVERIFIED until then.

Fallback (evaluated, not chosen): flat stubs (dist/a/b.html 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.

Gate gap and interim. doc-kitty’s gate looks only for <path>/index.html, so it reports a legacy dir/index.html URL as uncovered even though the page is there. Until upstream gap (b) lands, the gate runs with a generated --redirects override mapping each dir/index.html to dir/. 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.

Full-corpus spike. The generator rules above, run on the real ~831-URL baseline against a doc-kitty build of the real docs/ 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 dir/index.html URLs needed no declaration (rule 3). The coverage gate, run without --docs, reported 831/831 covered, and the GitHub Pages emulation resolved all 831.

No silent excuse. Run with --docs 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 --docs, which excuses nothing; rule 4 makes that run pass.

Dropped dashboards. The kitty-specs dashboard URLs (/kitty-specs/**, including /kitty-specs/glossary.html) are generated, were never part of the baseline, and are not in the ~830. They are dropped (ruling 3). The site’s 404 page names the retirement for any /kitty-specs/ path.

D-6: scripts/docs keep / port / drop (derived)

“Keep” means the script stays as it is and keeps its tests. “Port” means its job moves to doc-kitty or to site/, 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.

ScriptVerdictWhere its job goes
docs_index.py, _inventory.py, inventory_lockfile.pykeepThey feed spec-kitty docs query and the page inventory, from docs/ frontmatter. Updated for README.md indexes.
freshen_adr_inventory.pykeep (until gap a)Keeps the era indexes (ruling 6); retired when doc-kitty’s ADR index lands.
check_changelog_style.py, sync_changelog.py, check_spelling.pykeepSource-level checks with no DocFX dependency.
build_cli_reference.py, check_cli_reference_freshness.py, check_slash_command_freshness.py, _typer_walker.py, _render.py, _guards.pykeepThey generate or check source pages.
check_docs_freshness.py, version_leakage_check.pykeepRe-pointed at README.md indexes.
audience_resolver.py, related_validator.py, description_length_check.pyportdockitty-validate-frontmatter (audience, related, description length).
relative_link_fixer.py (link check)portdockitty-check-links docs --strict. The one-shot fixer mode is dropped.
capture_baseline_urls.pykeep for one run, then dropSeeds site/url-baseline.txt from the last DocFX build.
redirect_stub_generator.py, redirect_map.yaml, redirect_baseline_urls.jsonportsite/redirects.json generator + doc-kitty’s check-redirect-coverage. The map and manifest feed the seed, then retire.
seo_postprocess.py, seo_verify.pyportStarlight emits description, canonical and Open Graph; dockitty-assert-no-broken-links and the build artifact checks verify the output. Any check doc-kitty lacks is an upstream gap.
glossary_linker.py, glossary_page/port (after #3024)doc-kitty’s Contextive glossary and auto-link (D-10).
plantuml_render.py, plantuml_invoke.py, plantuml_pins.jsonport, then drop at retirementdoc-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.
generate_kitty_specs_docs.pydropDashboards dropped (ruling 3).
_published_pages.pyportdocs/_meta/sections.yaml plus the publication rules of D-8.
frontmatter_backfill.py, frontmatter_backfill_sections.yaml, adr_converter.pykeep for the migration, then dropReused by the frontmatter migration of D-7.
bulk_ref_rewrite.py, rename_reconcile.py, touched_set_gates.pykeep for the README rename, then dropReused by the rename step; their binding to a closed Mission’s occurrence_map.yaml is replaced by site/moves.yaml.
docs/docfx.json, every toc.yml, docs/templates/spec-kitty/ (incl. main.js)dropAt DocFX retirement.

D-7: the frontmatter contract mapping (derived)

doc-kitty’s gate requires title, description, doc_status, updated and kind. The current corpus (913 Markdown files) maps as follows, in one mechanical migration per row group:

FieldTodayOn doc-kitty
kindabsent everywhere; 209 pages carry a lowercase Divio typekind from type (how-to → How-To, explanation → Explanation, reference → Reference, tutorial → Tutorial); section index pages get kind: Hub; ADRs get kind: ADR; the rest are classified in the migration step, and any page left unclassified is a migration failure. type stays only where it carries doc-kitty’s type meaning.
audiencea path string such as docs/context/audience/internal/maintainer.md[{ profile: internal/maintainer, guidance_text: … }], which needs nested persona slugs (gap d). Personas stay under docs/context/audience/.
doc_statusactive, deprecated, draft, superseded, durable, plus closeout, point_in_time and proposalThe five canonical values pass. closeout and point_in_time map to durable; proposal maps to draft.
updateda date ('2026-10-26') on 724 pages; absent on the restNormalised to an instant (2026-10-26T00:00:00Z); ADRs take theirs from date.
ADR metadatastatus (Accepted, Proposed, Superseded) and date, with no doc_status on all 226 ADRs that predate this recordkind: ADR; doc_status: Accepted → active, Proposed → active (ruling 5), Superseded → superseded; updated from date. status and date stay, because core’s era indexes read them. This record already carries doc_status: active.
relatedrepository paths (docs/changelog/index.md) on 413 pages, 32 of them outside docs/ (kitty-specs/, tests/, pyproject.toml)doc-kitty page slugs (changelog, adr/3.x/<file> without .md). References outside docs/ move to external_references; references to unpublished pages follow D-8.
Excluded treesarchive, reports and convergence (242 files); 31 lack title or descriptionOnly the build-schema minimum: title, description, an audience list where present (D-8).
Index filesindex.md in 60 folders; 4 also hold a README.md (adr/1.x, adr/2.x, adr/3.x, architecture)Before the scaffold, the 4 folders get one index each, index.md. The three ADR-era README.md files are redirect stubs pointing at their index.md; they are deleted, and their README.html URLs redirect to /adr/<era>/. architecture/README.md is a 131-line landing page and is folded into architecture/index.md. After DocFX retirement, all 60 index.md become README.md and indexBasename is README only (sequencing: D-1).

ADRs must gain doc_status. doc-kitty treats a page with no doc_status 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.

The immutable corpus. ADRs, plans, reports and changelog entries keep their body 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.

One body change is allowed, and it needs the operator’s sign-off with this record: a mechanical link-target rewrite driven by site/moves.yaml. 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.

D-8: what is published (derived from ruling 4)

  • docs/_meta/sections.yaml registers every published section. development is its own section. plans is registered with restricted feeds (no llms, no agent, no rss).
  • plans/engineering-notes/, plans/investigations/ and plans/research/ take doc_status: draft. The live build runs with DK_PUBLISH_DRAFTS=off, so they are not published. doc-kitty defaults the setting to on, so site/.env.production sets it to off, in one place; workflows do not repeat it.
  • An unpublished page’s old URL redirects to its section hub (D-5 rule 4).
  • archive/, reports/ and convergence/, together with the pages about the retired hosted and sync surfaces (listed in the publication step), are not published.
  • Exclusion mechanism. doc-kitty has no section exclusion (gap f). Until it does, site/src/content.config.ts wraps docKittyDocsLoader with a filter that drops those route prefixes. Spike: with the filter, an archived doc_status: deprecated page was absent from pages, hub links, the sitemap, llms.txt, the OKF export and the content graph. Without it, the same page was built and linked from two hubs.
    • Limit of the shim. The filter drops entries only after doc-kitty’s loader has validated them, so an excluded page must still pass the build schema (title, description, an audience 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.
  • related must name published pages. doc-kitty resolves every related 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 check-links judges, or drops them.
  • Gates scope. dockitty-validate-frontmatter and dockitty-check-links walk every file under docs/, 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.

D-9: llms.txt is generated (ruling 3)

site/src/pages/llms.txt.ts mounts doc-kitty’s llmsTxtRoute. 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 docs/llms.txt is deleted at cutover.

D-10: the glossary waits on #3024 (ruling 12)

The glossary step starts after #3024 settles the source (packs or docs/context). That step then generates the single .contextive/definitions.yaml doc-kitty reads. doc-kitty reads it from the site project, so it is site/.contextive/definitions.yaml, generated and not committed. Multi-file Contextive (imports:, gap e) is not needed for that. doc-kitty’s glossary integration writes generated term pages into <docsDir>/glossary/, which here is docs/glossary/, inside core’s tree. Until doc-kitty takes an output path (gap e), that folder is gitignored and excluded from docs_index.py and the page inventory. The current glossary page is a dashboard page (/kitty-specs/glossary.html), outside the baseline, so cutover does not wait for the glossary step.

D-11: a required pull-request build gate (derived)

A docs-site job runs on every pull request that touches docs/**, site/** or its own workflow. It installs with the frozen lockfile and builds with drafts off (D-8). It then runs these gates, each with --astro-config astro.config.mjs (D-1), over the published sections (D-8):

  • dockitty-validate-frontmatter;
  • dockitty-check-links --strict;
  • dockitty-check-redirect-coverage url-baseline.txt dist --docs ../docs --astro-config astro.config.mjs --declared-redirects redirects.json, plus the interim override of D-5;
  • dockitty-assert-no-broken-links dist --base / --site https://docs.spec-kitty.ai;
  • a check that redirects.json equals its generated form.

Diagrams. doc-kitty renders PlantUML at build time to static SVG against a self-hosted server, never plantuml.com. Its own CI runs plantuml/plantuml-server as a job-level services: container on localhost:8091 with a readiness wait, sets DK_PLANTUML_SERVER_URL=http://localhost:8091/svg/, and checks with plantuml-guard.mjs (used by assert-build-artifacts.mjs) that no plantuml.com 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 diagrams: true and DK_DIAGRAM_BUILD_RENDER=build, and the job installs a pinned Playwright Chromium (core has 18 Mermaid and 5 PlantUML sources). Core’s docs-site job and the deploy workflow adopt doc-kitty’s server pattern, with one change: the image is pinned by digest, not :jetty, keeping core’s practice of pinning third-party build inputs by digest. The current docker --network=none isolation does not carry over, because the server runs as a service container. A diagram’s !include 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.

The job lives in ci-router.yml, behind a path filter for docs/** and site/** registered in gate_selection.py, and is added to router-gate’s needs:. That makes it required, with no continue-on-error. It cannot join ci-aggregate.yml’s aggregate-gate: that workflow runs on workflow_run, and GitHub Actions has no cross-workflow needs:. The router’s own tests (for example tests/ci/test_docs_lint_job.py) pin the wiring. The deploy workflow builds with the same steps, so main can never deploy a site no pull request built.

D-12: invariants kept (derived)

  • Packaging. site/** is excluded from the sdist; the wheel only ships its declared packages. tests/cross_cutting/packaging/test_packaging_safety.py asserts it on the built archive.
    • The sdist’s bare README.md include is gitignore-style. Today it already ships 31 docs/**/README.md and 676 kitty-specs/**/README.md files, and the README rename would add 56 more, net. Anchoring it to /README.md is a pre-existing defect, tracked in #6926, and must land before the rename.
  • Fork guard. Every new workflow’s automated trigger (push, schedule, workflow_run) carries the core-repository guard pinned by tests/ci/test_fork_guard.py. Pull-request and dispatch runs work on forks.
  • Pages probe. The deploy workflow keeps the probe-then-configure job, the 404-skips and other-status-fails semantics, and the main-only, core-repository-only deploy pinned by tests/release/test_release_ci_ownership.py. The test is updated with the workflow, never loosened.

D-13: parallel run, rollback and DocFX retirement (derived)

A repository has one Pages site, so “parallel” means built in parallel, not served in parallel.

  1. Parallel run. From the scaffold step on, every pull request and every push to main builds the doc-kitty site and runs the D-11 gates. The deploy workflow still publishes DocFX.
  2. Canary. The deploy job may only publish from main in the core repository, so the canary is a short production window on docs.spec-kitty.ai. It is announced, and docs merges to main are frozen for its duration (a push would queue a DocFX deploy in the pages concurrency group). Before cutover, one manually dispatched run deploys the doc-kitty build, probes a sample of baseline URLs over HTTP (one .html redirect key, one chain, one dir/index.html, one dir/README.html, one directory URL), and redeploys DocFX. This is where the D-5 GitHub Pages result stops being UNVERIFIED.
  3. Cutover. One pull request switches the deploy job’s artifact to site/dist.
  4. Rollback. 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.
  5. Retirement. After one Spec Kitty release ships with the doc-kitty site live, a pull request removes DocFX: docfx.json, toc.yml, the template, the .NET setup and the scripts marked “drop” in D-6. It also updates or deletes the 26 Python files that read docfx.json or toc.yml, most of them under tests/docs/, plus tests/_support/docfx_reports_guard.py and the terminology scope helper. The README rename (D-1) follows in its own pull requests.

D-14: upstream gaps go to doc-kitty (derived)

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 llms.txt wrapper (D-9) and the gate override (D-5).

Gaps filed or to file:

  • (a) ADR index for date-named, era-foldered ADRs with a frontmatter-status fallback;
  • (b) the coverage gate resolves an exact *.html file before <path>/index.html;
  • (c) GitHub > [!NOTE] alerts (7 files use them; the spike rendered them as literal text);
  • (d) nested persona slugs;
  • (e) multi-file Contextive, imports:, and an output path for generated glossary pages;
  • (f) excluding sections from the build, before schema validation;
  • (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 (specKittyTheme, the --dk-* tokens);
  • (h) an llms.txt preamble option;
  • (i) a fixture for a docsDir outside the site project.

Consequences

Positive

  • One toolkit owns rendering, metadata and gates; seven post-processing steps leave core.
  • A pull request builds and gates the site; DocFX’s deploy-time-only verification ends.
  • No URL in the ledger breaks, and the ledger has a standing home (#2358).
  • No .NET toolchain and no credential beyond the workflow token.

Negative

  • Node and pnpm join core’s CI toolchain for the docs job.
  • The frontmatter migration touches most of the 913 Markdown files once (frontmatter only).
  • Three consumer-side shims live until their upstream gaps close.
  • .html redirects cost one extra 301 on GitHub Pages.

Neutral

  • The kitty-specs dashboards and the dashboard glossary page go dark until the hub-card work (gap g) brings mission pages back.

Confirmation

  • The D-11 gate is green on the scaffold pull request with the full ~830-URL ledger.
  • The D-13 canary probes pass on the real Pages service.
  • After cutover, #2361’s post-deploy smoketest and #2362’s nightly crawl are green.

Pros and Cons of the Options

Git dependency pinned by commit (chosen)

  • Good, because the lockfile is the one pin, local and CI builds match, and no credential is needed.
  • 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.

CI checkout at a pinned SHA

  • Good, because it needs no registry.
  • Bad, because the pin lives outside the lockfile and local builds need a second clone.

GitHub Packages

  • Good, because it is versioned and integrity-hashed.
  • Bad, because it is the separately authorised package the operator steered away from, and installing it locally needs a PAT.

Vendoring

  • Good, because it is self-contained.
  • Bad, because it forks the toolkit and hides gaps from upstream.

More Information

  • Spike evidence, reproduction steps and the GitHub Pages emulator: kitty-ops/research/01M6947JAAGSMJTM6ST9D429BG/spike-evidence.md.
  • Delivery. The remaining steps are sub-issues of #6100:
    • ledgers and the dual-index folders: #6927 (D-5, absorbs #2358 and #3914) and #6928 (D-1);
    • frontmatter: #6929, the build-blocking migration, and #6931, contract completion (D-7);
    • site: #6930, the scaffold and docs-site job (D-1, D-2, D-11); #6932, publication (D-8); #6933, redirects (D-5); #6934, llms.txt (D-9);
    • rendering: #6935, render parity, and #6936, diagrams (D-11);
    • rollout: #6937, the required gate; #6938, canary and cutover, with #2361; #6943, DocFX retirement; then #6939, the README rename (D-13);
    • after upstream work: #6940, glossary (after #3024); #6941, mission pages (gap g); #6942, ADR index (gap a);
    • packaging: #6926 (D-12).
  • The upstream doc-kitty issue drafts (a)–(i) sit in the same folder as the spike evidence.
  • doc-kitty commit the spike ran against: 494f2d878e2e4766d9859a4f073efb793ad86900 (doc-toolkit 0.5.0 plus unreleased commits).

Amendment 2026-11-09

Recorded with #6932 (publication). D-8’s text above is unchanged; this section records how it is carried out and where it drifted.

  • Folder exclusion runs through doc-kitty’s exclude option. Gap (f) closed upstream (doc-kitty ADR-0070) before #6932 started. site/astro.config.mjs passes exclude from the generated site/dockitty-contract.json, which scripts/docs/site_contract.py projects from EXCLUDED_FOLDERS in scripts/docs/_dockitty_contract.py. No loader-filter shim exists: site/src/content.config.ts does not filter. The D-14 shim list therefore no longer includes the loader filter.
  • Working-note folders are drafts. plans/engineering-notes/, plans/investigations/ and plans/research/ are named once, as DRAFT_FOLDERS in the contract module. Every page in them takes doc_status: draft (a frontmatter-only change; the bodies are history). They are not excluded folders, because exclude would also drop them from the frontmatter and link gates.
  • Retired single pages are archived. exclude takes folders only (per-file exclusion is asked upstream in spec-kitty/doc-kitty#312), 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 docs/archive/<section>/. 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 site/moves.yaml row to its section hub (D-5 rule 4).
  • One authority for the unpublished set. unpublished_routes() 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 scripts/docs/site_built_check.py reads it after the build, and so does the redirect generator (#6933). The check walks the built pages, links, sitemap, OKF export, search index, llms.txt and the agent index.
  • The link gates run with priced debt. dockitty-check-links --strict and dockitty-assert-no-broken-links run in the shared build through scripts/docs/site_link_gates.py. It fails on any problem that site/link-debt.json does not list. That file lists only problems whose source is immutable history (dated ADRs, plans/, reports/, changelog/, archive/), 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.
  • Clarification 2026-11-10: a live hub (kind: Hub) is never an immutable source, and neither is a plans/ page whose doc_status is active or durable, or whose kind or doc_status cannot be read; such a page fixes its broken links instead of pricing them in site/link-debt.json. One predicate, is_debt_eligible_source, judges both the link gates and the relative-link debt.
  • One frontmatter edit to a dated ADR. docs/adr/3.x/2026-08-16-1-pack-metadata-manifest-unification.md dropped related: plans/investigations/2026-08-pack-level-metadata-manifest. That page is now a draft (working-note folder, above), and a related entry that names an unpublished page is a build-fatal dangling reference in doc-kitty’s Related block. The ADR body is unchanged.

Amendment 2026-11-10

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 (5acb83c), and where it departs from them.

  • The map is doc-kitty’s legacyHtmlRedirects, not Astro’s redirects.

    • Every one of the 970 baseline routes ends in .html. doc-kitty refuses .html keys in Astro’s redirects on static output (doc-kitty #253), so Astro’s redirects stays empty.
    • The generated map is site/legacy-redirects.json, not D-5’s site/redirects.json. It is a flat JSON object with no comment key, because doc-kitty validates every key as a legacy .html path.
    • site/astro.config.mjs reads it, and doc-kitty writes one flat stub per key (dist/a/b.html).
  • D-5’s fallback is now the mechanism. 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.

  • The gate override is retired. Gap (b) closed upstream: the gate resolves /a/index.html to the file that /a/ serves. Both runs report 970/970 with no --redirects override, so the D-14 shim list no longer includes the gate override.

  • One generator, one authority per input. scripts/docs/site_redirects.py derives the map from three inputs:

    • the URL baseline;
    • site/moves.yaml, with chains collapsed by moves_ledger.collapse;
    • the published set: route_of of every page minus unpublished_routes().

    --check fails the build when the committed map is stale.

  • Rule 4 lives in the generator. While DocFX still publishes drafts, a moves.yaml 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 (redirect_stub_generator.py) has no rule 4 and no resource rule. That difference is accepted until the #6943 cutover.

  • Rule 5: resources. docs/assets/spec-kitty-backlog.html and docs/assets/spec-kitty-evolution-v1-to-v3.html are standalone HTML that DocFX copied as resources; doc-kitty publishes only pages.

    • Operator ruling 2026-11-10: they redirect to the /assets/ hub.
    • The generator applies this as a rule, not a list: a baseline route backed by a non-page file under docs/ goes to its nearest published ancestor.
    • Any other baseline route with no page and no move is refused.
  • Counts at this amendment. 970 baseline routes and 929 keys:

    Kind of routeCount
    its own page571
    its moved page305
    a section hub, page unpublished51
    a section hub, resource2
    no key: a live, unmoved dir/index.html (rule 3)41

    D-5’s “11 dead-section dir/index.html keys” are now 21, because more sections moved since.

  • The gate runs twice, as D-5 says, and proves itself. The shared build runs dockitty-check-redirect-coverage once with --docs 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.

  • Redirect stubs are not publications. The built-site check recognises doc-kitty’s stub through one predicate, redirect_stub_target in scripts/docs/_dockitty_contract.py. That predicate mirrors doc-kitty’s REDIRECT_STUB_RE.

    • The page and render surfaces skip stubs.
    • The link surface still reports a stub whose target is unpublished.

Amendment 2026-11-11

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.

  • The canary is a dispatch input of the deploy workflow. docs-pages.yml takes canary (boolean, off by default) on workflow_dispatch. A push to main, or a dispatch without it, runs the DocFX path as before: the same pages and build jobs, and a deploy that runs only after a successful DocFX build.
  • The canary builds through the one shared definition (D-11).
    • canary-build calls docs-site-build.yml with pages-artifact: true and its own artifact name, github-pages-canary, a new input of the shared build that defaults to github-pages. The two Pages artifacts of one run never collide.
    • So the deploy workflow and the docs-site gate now share one build definition, which was the open part of #6937.
  • The restore is ready before production changes. canary-deploy publishes the canary with actions/deploy-pages (artifact_name: github-pages-canary, environment github-pages) only when both the canary build and the DocFX build succeeded, from main of the core repository. Only this job holds pages: write and id-token: write among the canary jobs.
  • DocFX is always republished. canary-probe runs after the canary is live. The DocFX deploy job needs it and runs on !cancelled() || inputs.canary, so on a canary it republishes DocFX whatever the probe found, and also after a cancel. needs.build.result == 'success' still blocks it after a failed DocFX build. A failed canary job leaves the run red.
  • The probe’s URL classes. scripts/docs/site_live_probe.py derives one URL per class from the committed ledgers (site/url-baseline.txt, site/moves.yaml, site/legacy-redirects.json), the first in sorted order. A class with no candidate refuses. The classes are:
    • a legacy .html key to its own page;
    • a moved-chain key, whose moves.yaml destination moved again;
    • a live dir/index.html with no key (D-5 rule 3) and its directory URL;
    • a dir/README.html key;
    • the site root and /llms.txt;
    • /kitty-specs/glossary.html, which D-5 drops and which must answer 404.
  • What the probe asserts. 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 redirect_stub_target) 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.
  • The gate runs the probe too. The shared build serves site/dist 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.
  • Operation. The operator dispatches the canary on main in an announced window with docs merges frozen, because a push would queue a DocFX deploy in the pages 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.

Amendment 2026-11-11 (cutover)

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.

  • The canary passed. The operator dispatched it on main in an announced window: run 43027580608, report on #6938. 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.

  • The deploy publishes the doc-kitty build. In docs-pages.yml, build calls the shared docs-site-build.yml with pages-artifact: true, under the default artifact name github-pages. deploy publishes that artifact with actions/deploy-pages, from main of the core repository only, after a successful build. D-11’s last sentence now holds: main deploys only a site built by the definition the docs-site pull-request gate runs.

  • The Pages probe stays. The pages probe-then-configure job, its 404-skips and other-status-fails semantics, the pages concurrency group (no cancel in progress) and the fork guard are unchanged (D-12). actions/configure-pages is now pinned by commit, like every other action in the workflow.

  • Token permissions.

    • The workflow default is contents: read.
    • The pages job holds pages: read.
    • build and smoketest hold contents: read.
    • Only deploy holds pages: write and id-token: write.
  • Post-deploy smoketest (#2361).

    • What it is: a smoketest job with needs: deploy, on main of the core repository only.
    • What it runs: python3 -m scripts.docs.site_live_probe https://docs.spec-kitty.ai.
    • Which URLs: the probe and its URL classes are the canary’s (Amendment 2026-11-11 above), derived from the committed ledgers.
    • On failure: a mismatch fails the job and turns the run red.
    • No alert issue: the operator decided that the red run is the signal, so #2361’s optional auto-filed alert issue is not adopted.
  • The canary is retired into the smoketest. The canary dispatch input and the canary-build, canary-deploy and canary-probe jobs are removed. A canary of the site already live would duplicate the smoketest. A plain dispatch on main deploys and smoketests like a push; on another branch it only builds.

  • DocFX stops running in the deploy workflow. The DocFX build and deploy jobs are removed. Their sources stay until #6943 (D-13 step 5): docs/docfx.json, toc.yml, the template, the DocFX scripts and their tests. In the meantime no CI job builds DocFX.

  • docs/llms.txt is deleted (D-9). The site generates /llms.txt with the version stance (site/src/pages/llms.txt.ts), and the smoketest probes it. The test that kept the hand copy’s stance equal to LLMS_STANCE now asserts the hand copy is absent. docs/docfx.json no longer lists it as a resource. Two archived pages still link to it; their bodies are immutable, so site/link-debt.json prices both links (relative-links gate, burn-down #7489).

  • What a revert restores (D-13 step 4). Reverting the cutover pull request brings back, in docs-pages.yml:

    • the DocFX build job and its deploy;
    • the dispatch-only canary jobs and their canary input;
    • the DocFX-era push path filter and the workflow-level pages: write and id-token: write;
    • actions/configure-pages on the floating @v6 tag instead of its commit pin.

    It reverts the comment-only updates in ci-router.yml, docs-site-build.yml and tests/ci/test_docs_site_job.py that describe the cutover.

    It also brings back docs/llms.txt with its docs/docfx.json resource entry (and drops the two site/link-debt.json entries for it), and the tests that pinned the DocFX deploy (tests/release/test_release_ci_ownership.py, tests/ci/test_nightly_tooling_cache.py, tests/docs/test_docs_seo.py, tests/docs/test_dockitty_contract.py). The revert’s own push to main then deploys DocFX. It does not touch the doc-kitty build gate (docs-site). The rollback works until #6943, as D-13 says.

  • Done when (#6938). The first post-merge deploy is green and its smoketest passes on docs.spec-kitty.ai. Both can only be shown after the merge, so they are followed up on #6938.

Amendment 2026-11-12 (DocFX retired)

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.

  • The release gate is waived (operator decision, 2026-11-12). 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:
    • the production canary, run 43027580608, report on #6938;
    • the post-cutover runs of docs-pages.yml on main, green on every completed run since the merge of #7558 in all four jobs (pages, build, deploy, smoketest), for example run 43265541140.
  • What was removed.
    • The DocFX sources: docs/docfx.json, the eight toc.yml files, docs/templates/ (with main.js, main.css and its hub page, whose route was never in the URL baseline), and the static resources docs/docfx.json copied (docs/CNAME, docs/robots.txt, docs/.nojekyll) with the DocFX build-output docs/.gitignore. site/public/ carries the site’s own CNAME and robots.txt, and templates left docs/_meta/sections.yaml.
    • The D-6 “drop” scripts: plantuml_render.py, plantuml_invoke.py, plantuml_pins.json and generate_kitty_specs_docs.py. Its slugify, which docs_index.py imported, moved into docs_index.py.
    • 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: redirect_stub_generator.py with redirect_map.yaml and redirect_baseline_urls.json (ported to site_redirects.py, #6933; rename_reconcile.py now cross-checks site/legacy-redirects.json, and moves_ledger.derive_redirect_map and validate went too); seo_postprocess.py and seo_verify.py (Starlight emits the tags and site_built_check_render.py proves them); description_length_check.py and _published_pages.py (the published set is published_pages() in _dockitty_contract.py, and dockitty-validate-frontmatter enforces the description band). capture_baseline_urls.py ran its one run.
    • glossary_linker.py and glossary_page/, 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 .kittify/glossaries/spec_kitty_core.yaml stays.
    • 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 (tests/docs/test_docs_seo.py) and the guard that docs/reports/ is never published (tests/_support/reports_unpublished_guard.py, used by the three terminology tests).
    • The PlantUML-jar steps of the router’s tests (docs) job.
  • What stays. The D-6 “keep” scripts and the migration-era tools (frontmatter_backfill.py, adr_converter.py, dockitty_frontmatter_migration.py, bulk_ref_rewrite.py, rename_reconcile.py, touched_set_gates.py) keep their D-6 verdicts. The ported frontmatter readers audience_resolver.py, related_validator.py and relative_link_fixer.py read no DocFX file and keep running.
  • Gates. tests/docs/test_legacy_docsite_retired.py keeps the DocFX sources and modules absent and fails on an import of a removed module. tests/architectural/test_legacy_docsite_named_nowhere.py fails on any tracked living file that names DocFX; it excludes only immutable history (dated ADRs, docs/changelog/, CHANGELOG.md, docs/plans/, docs/reports/, docs/archive/, kitty-specs/, the append-only kitty-ops/ and .kittify/ records, the #4562 bulk-edit record and a dated timeline page) and two generated files.
  • Rollback posture. 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.
  • D-13 is complete apart from the README rename (#6939, D-1), which follows in its own pull requests with the content pass (#3891). The D-14 shim list is unchanged.

Amendment 2026-11-12 (section indexes renamed)

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.

  • 59 files, not 60. Every docs/**/index.md is now README.md, moved with git mv. D-1 counted 60; docs/templates/index.md left with the DocFX template in #6943. The 4 folders #6928 resolved (adr/1.x, adr/2.x, adr/3.x, architecture) are among the 59.
  • indexBasename is 'README' only. INDEX_BASENAMES in scripts/docs/_dockitty_contract.py is ("README",), and the generated site/dockitty-contract.json follows. tests/docs/test_section_index_basename.py fails on any index.md under docs/, with a planted control that proves the walk reports one.
  • The moves ledger records each rename. site/moves.yaml gains one entry per folder, /x/index.html -> /x/README.html (ref #6939). Eight folders had moved README.md -> index.md 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 (moves_ledger.collapse). 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.
  • Links. Every link to a renamed page was rewritten from the ledger’s own #6939 pairs (moves_ledger.source_pairs): the index.md segment of a link target that resolves to a renamed page became README.md, and nothing else in the target changed. Living pages also had exact path mentions rewritten. In immutable files (dated ADRs, plans/, reports/, changelog/, archive/) 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. site/link-debt.json follows the two rewritten targets it prices.
  • Redirects. site/legacy-redirects.json is byte-identical. A legacy dir/index.html or dir/README.html URL folds to dir/ by the legacy site’s own file names, whatever INDEX_BASENAMES holds, and D-5 rule 3 excuses a dir/index.html 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 dir/, 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 (moves_ledger.is_index_rename, read by the ledger tests and by rename_reconcile.py). The directory build still writes each section page to dist/<dir>/index.html.
  • Readers. freshen_adr_inventory.py writes the era table to README.md. It still reads a lone index.md but never writes one: adding or pruning a row there refuses with “era index not found”. check_generated_docs_untouched.py matches ADR era table rows per era folder, so a table that moves between the landing files of one era adds no row. dockitty_frontmatter_migration.py no longer skips the 4 #6928 folders’ README.md, which is their section index again, and site_built_check.py resolves a folder’s metadata route through README.md.
  • A known gap upstream. The built-in pack’s docs lint (packs/built-in/assets/docs_structural_lint.py, sourced from spec-kitty-open-packs) still reads a section’s landing page as index.md. Its check_index_completeness skips a section without one, so the curated-complete check on docs/architecture/ does not run until the asset reads README.md. Packs are not edited here; the fix belongs upstream.
  • Generated surfaces. The retrieval index and the page inventory are not edited in the pull request; the post-merge ci/regen-docs-index bot regenerates them on the new paths.
  • D-1 and D-13 are complete.