torben/chemenu
1
1 Fork 0
Code Issues 40 Pull Requests Actions Packages Releases 41 Wiki Activity

feat!: docs/ sorted into tutorials, how-to, reference, explanation plus unshipped docs/dev/; explanation pages and developer guide moved, human docs English (#187)
CI / verify (push) Successful in 6m1s
Details
CI / pwsh (push) Successful in 2m0s
Details
Release / release (push) Successful in 34s
Details

Browse Source 
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 2026-10-06 20:45:09 +02:00
1 parent 0e15972ee7
commit d66a3f65f4
43 files changed
+756 -324
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

instructions/CONTRACT.md
+1 -1
View File
@@ -234,7 +234,7 @@ new skill is written to match the ones around it.
Three prefixes exist today, each naming the subject domain a skill operates on, not the
distribution boundary it ships behind: `wiki-` for the knowledge pipeline (`wiki-ingest`,
`wiki-lint`, `wiki-manage`, `wiki-query`, `wiki-status`), `gtd-` for the commitment layer
(`gtd-weekly-review` - see `kb/gtd/COLLECTION.md` and `docs/knowledge-and-commitment.md` for why
(`gtd-weekly-review` - see `kb/gtd/COLLECTION.md` and `docs/explanation/knowledge-and-commitment.md` for why
that layer is named GTD rather than folded into `wiki-`), and `stack-` for the stack's own
development, nested under `instructions/dev/` and therefore never present in a distributed
instance (`instructions/dev/` above).
instructions/dev/dev-setup.md
+2 -2
View File
@@ -39,7 +39,7 @@ development material under `instructions/dev/` and `commonplace/`, and no
| No `.wikitool-release.json`: telemetry is **on** - the traces are the stack's measuring instrument (`EVALS.md` § "Whether it runs at all") | Telemetry is off until the operator turns it on |
| `USER.md`/`SOUL.md` describe a demo operator and persona | Written by the operator during setup |
| `tools/wikitool dist upgrade` refuses: there is no stamp to compare against. The checkout follows `main` with `tools/wikitool sync` | Updated with `dist upgrade --latest` |
| `instructions/dev/`, `commonplace/`, `DEVELOPMENT.md` and `.gitea/` are present | Never shipped |
| `instructions/dev/`, `docs/dev/`, `commonplace/` and `.gitea/` are present | Never shipped |
5. **Use `dist export` as a build and test tool.** It writes exactly the tree a release ships, so
it is how a change to the shipped surface is looked at before it is released:
@@ -68,6 +68,6 @@ development material under `instructions/dev/` and `commonplace/`, and no
## Scope
Not for operating an instance, and not for the release workflow itself (`DEVELOPMENT.md` for
Not for operating an instance, and not for the release workflow itself (`docs/dev/development.md` for
humans, [version-parts.md](version-parts.md) for the version part). Not shipped: `dist export`
prunes `instructions/dev/` wholesale.
instructions/dev/doc-pull-through.md
+7 -7
View File
@@ -36,21 +36,21 @@ touched; a row that does not apply needs no action.
| A `wikitool` command's behaviour, flags, or interface | Its `cli_contract.CommandRecord` (name, synopsis, properties, exit status, retry policy - `tools/chemenu/cli_contract.py`), then `wikitool docs contract --apply` to regenerate its copy in [tools/CONTRACT.md](../../tools/CONTRACT.md) |
| A stage's authoring rules (`raw/`, `kb/`, `types/`, `reports/`, `work/`, `tools/`, `instructions/`) | The touched `<stage>/CONTRACT.md` |
| A rule, gate, or invariant `AGENTS.md` itself states | The relevant `AGENTS.md` section (Invariants, Gates, File naming, Routing, ...) |
| A workflow, stage, or command a human operates by hand | Whichever of `README.md`, `EVALS.md`, `tools/README.md`, `INSTALL.md`, `DEVELOPMENT.md` names it - AGENTS.md § File naming says which document is for which reader |
| The reasoning behind a gate, boundary, or design decision | The `docs/` page that carries it, if one exists (AGENTS.md § File naming lists all six reached from AGENTS.md itself, plus a seventh reached only from CLAUDE.md). **A decision with no page yet is the gap worth closing**: reasoning that lives only in a Gitea issue never ships - `dist export` carries `docs/` and no issue tracker, so a distributed instance gets the mechanism without the why |
| A workflow, stage, or command a human operates by hand | Whichever of `README.md`, `EVALS.md`, `tools/README.md`, `INSTALL.md`, `INSTALL-MCP.md` or the pages under `docs/tutorials/`, `docs/how-to/` and `docs/reference/` names it - AGENTS.md § File naming says which document is for which reader. A new page goes into the area its kind of documentation belongs to; that area's `README.md` says which |
| The reasoning behind a gate, boundary, or design decision | The `docs/explanation/` page that carries it, if one exists (AGENTS.md § File naming lists all six reached from AGENTS.md itself, plus a seventh reached only from CLAUDE.md). **A decision with no page yet is the gap worth closing**: reasoning that lives only in a Gitea issue never ships - `dist export` carries `docs/explanation/` and no issue tracker, so a distributed instance gets the mechanism without the why |
| A task-tracker adapter (`tools/chemenu/tasks/`), its recorded fixtures, or the live suite | [instructions/dev/tracker-testing.md](tracker-testing.md), and `MANIFEST.json` beside the fixtures when they were re-recorded |
| A skill's own step sequence or catalogue | The skill's `SKILL.md` source under `instructions/<name>/` or `instructions/dev/<name>/` |
| A per-checkout configuration file an instance owns (`.wikitool-tasks.json`, `.wikitool-telemetry.json`, `.wikitool-remotes.json`, `.wikitool-upload.json`) | [INSTALL.md](../../INSTALL.md) § Konfiguration, where an operator looks the shape up; the [setup-instance.md](../setup-instance.md) decision point that offers it during setup; and `doctor`'s own row in [tools/CONTRACT.md](../../tools/CONTRACT.md), since `doctor` is what reports the file's state |
| An installation instruction - [preflight.md](../preflight.md), [setup-instance.md](../setup-instance.md), [bootstrap.md](../bootstrap.md), [upgrade-instance.md](../upgrade-instance.md) - or `tools/prerequisites.txt` | [INSTALL.md](../../INSTALL.md), the human guide to the same procedure. Read it against the instruction: what to prepare, the sentence for the agent, what the agent asks, where it stops and why. `docs verify` checks only the two enumerable overlaps - the prerequisites lists, which `wikitool docs prerequisites --apply` regenerates from the manifest, and the setup questions: a question the agent asks the user carries `<!-- setup-question: <key> -->` where it is asked in `setup-instance.md`, and `INSTALL.md` § "Was der Agent dich fragt" names it with the same marker. Every other sentence is this session's to compare. `INSTALL.md` does not retell the steps, so a change to their order or wording alone moves nothing there |
| [dev-setup.md](dev-setup.md) | [DEVELOPMENT.md](../../DEVELOPMENT.md), read against it the same way - nothing checks this pair at all |
| [dev-setup.md](dev-setup.md), the release workflow (`version bump`/`version release`/`publish`/CI), or another developer-facing process | [docs/dev/development.md](../../docs/dev/development.md), read against it the same way - nothing checks this pair at all. A page under `docs/dev/` is never shipped, so it may link into `instructions/dev/` and cite issue numbers |
| A new page type the stack requires, or a new collection | Its type-spec and `COLLECTION.md` (both as the `.template` an instance adopts), the collection table in [kb/CONTRACT.md](../../kb/CONTRACT.md), and **both adoption paths**: [setup-instance.md](../setup-instance.md) for a fresh instance and [upgrade-instance.md](../upgrade-instance.md) for an existing one, where an unadopted template is what `docs verify` refuses |
3. **A heading you changed means a table of contents to regenerate - by the tool, never by
hand.** Every reference file over 100 lines carries one (`AGENTS.md`, the stage contracts,
`kb/CONVENTIONS.md`, each `COLLECTION.md`, the flat `instructions/**.md` form, the
type-specs, the `docs/` pages - each with the `<name>.template` it ships as, where one
exists, and a `SKILL.md` the one exception). Adding, renaming,
reordering or deleting a `##`/`###` heading in one of them makes its region stale, and
type-specs, the `docs/` pages in all five areas - each with the `<name>.template` it ships
as, where one exists, and a `SKILL.md` the one exception). Adding, renaming, reordering or
deleting a `##`/`###` heading in one of them makes its region stale, and
`docs verify` fails on stale exactly as it fails on missing:
```bash
@@ -73,7 +73,7 @@ touched; a row that does not apply needs no action.
- **The change touched no document in the table?** Nothing to do - not every stack change moves
a claim. A pure bugfix with an unchanged interface is the common case.
- **Unsure whether a `docs/` page's reasoning moved?** Read it. A `docs/` page carries no
- **Unsure whether a `docs/explanation/` page's reasoning moved?** Read it. A `docs/` page carries no
normative sentence and nothing verifies it by construction (AGENTS.md § File naming), so an
unsure guess defaults to reading the page rather than skipping the question -
[`stack-close`](stack-close/SKILL.md) step 3 asks it again in the closing phase as a
instructions/dev/stack-close/SKILL.md
+2 -2
View File
@@ -23,7 +23,7 @@ phases this one ends; read it first when this session started cold.
The phases around the checked middle of a work package have no mechanical guard at all -
`pytest`, `docs verify`, `instructions verify` and CI cover the code and tests in between, and
nothing covers a changelog entry's accuracy, a `docs/` page's staleness, or an issue body's final
state (see `docs/model-and-effort-selection.md`). Asking the same session to notice it has
state (see `docs/explanation/model-and-effort-selection.md`). Asking the same session to notice it has
crossed into that unchecked stretch - as a prose break inside one long skill - failed twice in a
row on this stack (Gitea #42, then #30): both times the session knew the rule and skipped past
it anyway, because nothing in the moment forced the question. The first split (Gitea #47) moved
@@ -71,7 +71,7 @@ always will.
naming) - the same is true of `tools/CONTRACT.md`'s generated command records and any touched
`<stage>/CONTRACT.md`, whose prose `docs verify` checks only for presence and record
membership, never for what a field or a section actually says
(`instructions/dev/doc-pull-through.md`); of `README.md`/`INSTALL.md`/`DEVELOPMENT.md`
(`instructions/dev/doc-pull-through.md`); of `README.md`/`INSTALL.md`/`docs/`
prose; and of a new instruction's own wording, which `instructions verify` checks structurally
but never for what it claims. If the change this package shipped moved the reasoning or the
behaviour one of these documents describes, update it now; if none did, say so rather than
instructions/dev/stack-mode.md
+1 -1
View File
@@ -118,4 +118,4 @@ next phase's slash command in a session started on the right model - and the tra
what carries the work across it.
Which model suits which phase, and the reasoning, is
`docs/model-and-effort-selection.md`.
`docs/explanation/model-and-effort-selection.md`.
instructions/gtd-weekly-review/SKILL.md
+1 -1
View File
@@ -30,7 +30,7 @@ item outright - stays the user's own action in their tracker: that is a delibera
in the command surface waiting to be filled. Do not reach for a tracker-specific tool or API to
"just do it faster" for either half. The reasoning behind keeping the tracker and `kb/gtd/` on
separate write paths, and behind stopping at "create" and "mark done" rather than a fuller CRUD
surface, lives in `docs/knowledge-and-commitment.md`, which this skill does not repeat.
surface, lives in `docs/explanation/knowledge-and-commitment.md`, which this skill does not repeat.
## Steps
instructions/ingest-queue.md
+1 -1
View File
@@ -38,7 +38,7 @@ this when a submission is already waiting and a decision is due.
prints filename, size, sha256, submitter, and - as important as the
submitter's name - `submitter_source`: the *header* the value came from,
naming where the claim rests rather than asserting it as fact. Read
[docs/why-gates-are-code.md](../docs/why-gates-are-code.md) once for why
[docs/explanation/why-gates-are-code.md](../docs/explanation/why-gates-are-code.md) once for why
this gate exists as code rather than as this paragraph alone.
2. **Read the file itself before promoting anything.** The quarantine holds
instructions/migrations/6.0.0-type-guidance-split.md
+1 -1
View File
@@ -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
instructions/migrations/9.0.0-docs-diataxis.md
+114
View File
@@ -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.
instructions/upgrade-instance.md
+5 -1
View File
@@ -209,7 +209,10 @@ a further checkout of this one ([bootstrap.md](bootstrap.md)).
and filled is never touched. The `.template` files stay where they are - they are the source for the next upgrade's
comparison. Any other failure is read against step 2's **Breaking Change:** line: if the
release predicted it, the notes also say what fixes it; if it did not, stop and report it
rather than improvising.
rather than improvising. Where the fix they name is a required migration document - a
machinery-side file this instance owns, such as `kb/CONVENTIONS.md`, still pointing at a
path the release moved - leave the failure standing here: step 12 runs that document, and
step 13's `docs verify` is where it has to be gone.
10. **Publish the machinery swap.** A release swap is far above the Mass-Update Gate's threshold,
so expect exit 42. That is not an error and not yours to clear: reproduce the file breakdown
@@ -254,6 +257,7 @@ a further checkout of this one ([bootstrap.md](bootstrap.md)).
```bash
tools/wikitool migrate verify --from <pre-swap commit>
tools/wikitool lint
tools/wikitool docs verify
```
`migrate verify` is the only check that sees a page which lost a citation, a wikilink or a