torbenandClaude Opus 5.5
d66a3f65f4
The seven explanation pages move to docs/explanation/ without a stub, DEVELOPMENT.md becomes docs/dev/development.md (translated to English), dist export leaves docs/dev/ out, docs verify rejects a file outside the five areas, and AGENTS.md states that the stack's human documentation is English. Required migration 9.0.0-docs-diataxis rewrites the old path in an instance's own kb/CONVENTIONS.md. Files changed: - .wikitool-kb.json - AGENTS.md - CHANGES.md - CLAUDE.md - DEVELOPMENT.md - INSTALL.md - README.md - VERSION - docs/dev/development.md - docs/explanation/README.md - docs/explanation/knowledge-and-commitment.md - docs/explanation/language-boundaries.md - docs/explanation/model-and-effort-selection.md - docs/explanation/ownership-and-templates.md - docs/explanation/pipeline-rationale.md - docs/explanation/version-model.md - docs/explanation/why-gates-are-code.md - docs/how-to/README.md - docs/knowledge-and-commitment.md - docs/language-boundaries.md - docs/model-and-effort-selection.md - docs/ownership-and-templates.md - docs/pipeline-rationale.md - docs/reference/README.md - docs/tutorials/README.md - docs/version-model.md - docs/why-gates-are-code.md - instructions/CONTRACT.md - instructions/dev/dev-setup.md - instructions/dev/doc-pull-through.md - instructions/dev/stack-close/SKILL.md - instructions/dev/stack-mode.md - instructions/gtd-weekly-review/SKILL.md - instructions/ingest-queue.md - instructions/migrations/6.0.0-type-guidance-split.md - instructions/migrations/9.0.0-docs-diataxis.md - instructions/upgrade-instance.md - kb/CONVENTIONS.md - kb/CONVENTIONS.md.template - tools/CONTRACT.md - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/new_page.py - tools/chemenu/commands/task_cmd.py - tools/chemenu/tasks/protocol.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_docs_verify.py - tools/chemenu/tests/test_git_publish.py - tools/chemenu/tests/test_toc.py - types/type-guidance.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
115 lines
5.3 KiB
Markdown
115 lines
5.3 KiB
Markdown
---
|
|
type: types/instruction.md
|
|
name: 9.0.0-docs-diataxis
|
|
description: 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.
|
|
manual: true
|
|
migrates_to: 9.0.0
|
|
migration_kind: mechanical
|
|
obligation: 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).
|
|
|
|
<!-- wikitool:toc -->
|
|
## Contents
|
|
|
|
- [When to run](#when-to-run)
|
|
- [Steps](#steps)
|
|
- [How to tell a migrated file from an unmigrated one](#how-to-tell-a-migrated-file-from-an-unmigrated-one)
|
|
- [Decision points](#decision-points)
|
|
- [Scope](#scope)
|
|
<!-- /wikitool:toc -->
|
|
|
|
## When to run
|
|
|
|
After installing 9.0.0 machinery over an instance on 8.x - step 12 of
|
|
[upgrade-instance.md](../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:
|
|
|
|
```bash
|
|
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:**
|
|
|
|
```bash
|
|
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:**
|
|
|
|
```bash
|
|
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:**
|
|
|
|
```bash
|
|
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.
|