chemenu/instructions/migrations/9.0.0-docs-diataxis.md

type, name, description, manual, migrates_to, migration_kind, obligation

type	name	description	manual	migrates_to	migration_kind	obligation
types/instruction.md	9.0.0-docs-diataxis	Point every file this instance owns at the explanation pages' new home under docs/explanation/ - a path rewrite with no judgment call, without which docs verify reports a dead link in kb/CONVENTIONS.md.	true	9.0.0	mechanical	required

Point own files at docs/explanation/ (9.0.0)

9.0.0 sorts the stack's human documentation under docs/ into areas - docs/tutorials/, docs/how-to/, docs/reference/ and docs/explanation/ - and moves the seven pages that used to sit directly in docs/ into docs/explanation/, names unchanged. Nothing is left at the old paths: dist upgrade deletes them as files the release no longer ships.

Every file the stack ships already points at the new paths. A file this instance owns does not, because an upgrade never touches it - and one such file is in every instance: kb/CONVENTIONS.md, adopted from a template that linked language-boundaries.md at its old place directly under docs/. tools/wikitool docs verify checks every relative link in it, so after the upgrade it reports that link as not resolving. This migration rewrites the old paths, and nothing else.

It is mechanical: the seven names map one to one, and there is no per-file judgment beyond which files are in scope (§ Decision points).

Contents

• When to run
• Steps
• How to tell a migrated file from an unmigrated one
• Decision points
• Scope

When to run

After installing 9.0.0 machinery over an instance on 8.x - step 12 of upgrade-instance.md, once tools/wikitool migrate status names this document. Until it has run, docs verify reports the dead link in kb/CONVENTIONS.md; that failure is expected between the machinery swap and this migration, and nothing else depends on it.

Steps

1. Capture the baseline, before changing anything - the list of every file this instance tracks that names an old path, and what docs verify says about it now:

   git grep -nE 'docs/(pipeline-rationale|ownership-and-templates|language-boundaries|why-gates-are-code|version-model|knowledge-and-commitment|model-and-effort-selection)\.md' -- . ':!raw' ':!CHANGES.md' ':!kb/log.md' > /tmp/9.0.0-before.txt
   tools/wikitool docs verify > /tmp/9.0.0-verify-before.txt
   

   Expect at least kb/CONVENTIONS.md in the first file and its dead link in the second.

2. Decide which hits are in scope. Every hit is, except a kb/ page (a file under a collection with a type: in its frontmatter) - see § Decision points. In a typical instance the in-scope list is kb/CONVENTIONS.md alone; an instruction, a type-spec or a COLLECTION.md the instance wrote for itself may add to it.

3. Rewrite the old paths in each in-scope file:

   sed -i -E 's#docs/(pipeline-rationale|ownership-and-templates|language-boundaries|why-gates-are-code|version-model|knowledge-and-commitment|model-and-effort-selection)\.md#docs/explanation/\1.md#g' <file> ...
   

   The rewrite keeps everything before docs/ - a link's ../ stays as it was, because only the part below docs/ moved. No other line of the file changes.

4. Check it against the baseline:

   git diff --stat
   git grep -nE 'docs/(pipeline-rationale|ownership-and-templates|language-boundaries|why-gates-are-code|version-model|knowledge-and-commitment|model-and-effort-selection)\.md' -- . ':!raw' ':!CHANGES.md' ':!kb/log.md'
   tools/wikitool docs verify
   

   git diff --stat names exactly the files step 2 put in scope, one or a few lines each. The git grep prints only kb/ pages step 2 left out - none at all in a typical instance. docs verify is green; compared with /tmp/9.0.0-verify-before.txt, the dead-link lines are what disappeared.

5. Record it:

   tools/wikitool migrate done 9.0.0 --pages 0
   

   --pages 0 because no kb/ page changes. The migration is required, so this advances kb_version.

How to tell a migrated file from an unmigrated one

An unmigrated file names docs/<one of the seven names>.md; a migrated one names docs/explanation/<name>.md. Step 4's git grep lists every file still waiting, and docs verify names each unmigrated reference file by line.

Decision points

• A kb/ page mentions an old path? Leave it out of this migration: a page records what a source said at the time, docs verify does not read page bodies, and a page is changed through wiki-manage, not by sed. Update it the next time the page is worked on, if the mention is meant as a pointer rather than as evidence.
• The instance links one of the pages under a different spelling - an absolute URL into the origin repository, say? Out of scope: such a link never resolved inside the instance, and docs verify does not check it.

Scope

Files this instance tracks that name one of the seven old paths, outside raw/ (immutable), CHANGES.md and kb/log.md (records of what was true at the time) and kb/ pages. The machinery itself - the moved pages, the new area READMEs, every shipped file that links them - arrived with dist upgrade and needs nothing from this document.