feat!: docs/ sorted into tutorials, how-to, reference, explanation plus unshipped docs/dev/; explanation pages and developer guide moved, human docs English (#187)
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
This commit is contained in:
torbenandClaude Opus 5.5 committed
1 parent
0e15972ee7
commit
d66a3f65f4
43 files changed
+756
-324
No files matched your search
@@ -15,7 +15,7 @@ mechanism-level advice such as citation and provenance rules - in the same file
|
||||
configuration and its `## Template` block. Adopting the type-spec at setup meant adopting all of
|
||||
it at once, and an upgrade never touched the adopted file again: the prose an instance received
|
||||
was frozen at the day it ran `setup-instance.md`, while every later improvement shipped only in
|
||||
the `.template` beside it (`docs/ownership-and-templates.md` § "Where the file boundary used to
|
||||
the `.template` beside it (`docs/explanation/ownership-and-templates.md` § "Where the file boundary used to
|
||||
strain").
|
||||
|
||||
6.0.0 splits that prose into a separate, stack-owned `types/<name>.guidance.md`, linked from the
|
||||
|
||||
@@ -0,0 +1,114 @@
|
||||
---
|
||||
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.
|
||||
Reference in new issue
Block a user