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

AGENTS.md
+49 -37
View File
@@ -89,7 +89,6 @@ What a file is called says who it is for and how it is loaded. This is a rule, n
|------|-----|--------|
| `README.md` | Humans - technical documentation and how to develop the thing in that directory | Never by an agent as instruction |
| `EVALS.md` | Humans - how telemetry and evaluation work; routes to the contracts that bind | Never by an agent as instruction |
| `DEVELOPMENT.md` | Humans - the release workflow (`version bump`/`version release`/`publish`/CI), for whoever develops this stack rather than an instance built on it | Never by an agent as instruction. Not shipped: `dist_cmd.ROOT_FILES` excludes it deliberately, the same way `instructions/dev/` (which it may link to, unlike the documents `instructions verify` holds to that rule) is excluded - a distributed instance has no release workflow to document |
| `AGENTS.md` | Agents | Always, every session |
| `CLAUDE.md` | Agents on Claude Code | Automatically by that harness, which does not load `AGENTS.md` on its own - so it imports this file, carrying no rule of its own. It also links the one remaining Claude-Code-only decision (model/effort selection), per [instructions/CONTRACT.md](instructions/CONTRACT.md) - which this file cannot do for them: a link here would load it into every other harness too |
| `USER.md` | Agents | Always, every session |
@@ -103,7 +102,8 @@ What a file is called says who it is for and how it is loaded. This is a rule, n
| `types/<name>.md` | Agents + validator | Via `tools/wikitool types describe`. Split by `root:`: a page type-spec (`root: kb`) belongs to the instance and ships as `.template`; one describing a stack artifact ships verbatim |
| `types/<name>.guidance.md` | Agents + validator | Via `tools/wikitool types describe`, composed with the `types/<name>.md` it documents. Stack-owned regardless of the type-spec's own `root:` - it ships verbatim and is optional, present only where the type-spec declares `guidance:` |
| `types/<name>.<subtype>.md` | Agents + `new` | Never as instruction: `wikitool new` copies it as the page skeleton for that one subtype value, in place of the type-spec's `## Template` block. Page material in the KB language, no frontmatter; its name is its only declaration, and `guidance` is reserved. Owned like the type-spec beside it, so it ships as `.template` |
| `docs/<name>.md` | Agents and humans | By link, or on explicit request - never automatically, and never as instruction |
| `docs/<area>/<name>.md` | Humans and agents - `<area>` is one of `tutorials`, `how-to`, `reference`, `explanation` (the four kinds of documentation), and each area's `README.md` says what belongs in it | By link, or on explicit request - never automatically, and never as instruction |
| `docs/dev/<name>.md` | Humans - for whoever develops this stack rather than an instance built on it (the release workflow, the development environment) | Never by an agent as instruction. Not shipped: `dist export` excludes `docs/dev/` the same way it excludes `instructions/dev/`, which it may therefore link to, unlike the documents `instructions verify` holds to that rule - a distributed instance has no release workflow to document |
| `INDEX.md` | Both | Generated - never hand-edited |
A stage may carry both a `README.md` and a `CONTRACT.md`: different readers, different
@@ -128,39 +128,50 @@ whether it ever leaves this checkout.
a further stage contract. Such a file is instance-owned end to end, which settles who may
change it, not who reads it - and the reader is still an agent. There is deliberately no
second language value beside `kb/CONVENTIONS.md`'s `language:`, and no instance setting that
moves this rule; [docs/language-boundaries.md](docs/language-boundaries.md) has the reasoning.
moves this rule;
[docs/explanation/language-boundaries.md](docs/explanation/language-boundaries.md) has the
reasoning.
2. **An agent speaks the instance's KB language**, whatever this file is written in. The value
lives in `kb/CONVENTIONS.md`'s `language:` and nowhere else; an instruction that models a
sentence for the user writes it in English like the rest of the control plane, and the agent
says it in that language.
3. **The stack's human documentation is written in English** - `README.md`, `INSTALL*.md`,
`EVALS.md` and everything under `docs/` - whatever an instance's `language:` says. It is the
same text in every instance, and the parts of it that are generated come from English
sources, so there is no instance whose language it could follow. `CHANGES.md` is a log, not
documentation, and is not covered.
Nothing checks either mechanically - a stop-word scan would flag the quoted vocabulary above
and miss a translated paragraph that reads cleanly. They are held up by whoever writes an
instruction, which is why [instructions/CONTRACT.md](instructions/CONTRACT.md) § "Writing an
instruction" names them at the step where that happens.
Nothing checks any of the three mechanically - a stop-word scan would flag the quoted vocabulary
above and miss a translated paragraph that reads cleanly. They are held up by whoever writes the
text, which is why [instructions/CONTRACT.md](instructions/CONTRACT.md) § "Writing an
instruction" names the first two at the step where that happens.
**`docs/` carries no normative sentence.** It holds why the stack is built the way it is -
background consulted in passing, not a rule to follow; anything that would bind belongs in a
**`docs/` carries no normative sentence.** It holds the stack's human documentation - tutorials,
how-to guides and reference, and under `docs/explanation/` why the stack is built the way it is:
background consulted in passing, not a rule to follow. Anything that would bind belongs in a
`CONTRACT.md` instead, which is what keeps invariant 8 intact here. It carries no frontmatter,
type, index, lint or provenance; `dist export` ships it verbatim and no other `tools/wikitool`
command touches it.
type, index, lint or provenance; `dist export` ships it verbatim except `docs/dev/`, `docs
verify` checks only that every file sits in one of its five subdirectories, and no other
`tools/wikitool` command touches it.
Six pages are reached from this file, each by link rather than automatically:
[docs/pipeline-rationale.md](docs/pipeline-rationale.md) (why the pipeline has four stages),
[docs/ownership-and-templates.md](docs/ownership-and-templates.md) (why a `.template` split
exists, why silent overwrite is the failure it guards against, and why an instance comes only
from a release),
[docs/language-boundaries.md](docs/language-boundaries.md) (why the control plane is English
everywhere and the KB language is a value, and why the axis is the reader rather than the
owner), [docs/why-gates-are-code.md](docs/why-gates-are-code.md) (why the five gates in
[Gates](#gates) are code rather than instruction),
[docs/version-model.md](docs/version-model.md) (why a version number answers a compatibility
question and a migration question separately), and
[docs/knowledge-and-commitment.md](docs/knowledge-and-commitment.md) (why commitments live in a
task tracker rather than in `kb/`, and why the two are joined at read time instead of synced). A
seventh, `docs/model-and-effort-selection.md`, is deliberately not linked here but from
`CLAUDE.md`: it decides something only that harness has to decide, and a link here would load it
into the other three.
Six explanation pages are reached from this file, each by link rather than automatically:
[docs/explanation/pipeline-rationale.md](docs/explanation/pipeline-rationale.md) (why the
pipeline has four stages),
[docs/explanation/ownership-and-templates.md](docs/explanation/ownership-and-templates.md) (why
a `.template` split exists, why silent overwrite is the failure it guards against, and why an
instance comes only from a release),
[docs/explanation/language-boundaries.md](docs/explanation/language-boundaries.md) (why the
control plane is English everywhere and the KB language is a value, and why the axis is the
reader rather than the owner),
[docs/explanation/why-gates-are-code.md](docs/explanation/why-gates-are-code.md) (why the five
gates in [Gates](#gates) are code rather than instruction),
[docs/explanation/version-model.md](docs/explanation/version-model.md) (why a version number
answers a compatibility question and a migration question separately), and
[docs/explanation/knowledge-and-commitment.md](docs/explanation/knowledge-and-commitment.md) (why
commitments live in a task tracker rather than in `kb/`, and why the two are joined at read time
instead of synced). A seventh, `docs/explanation/model-and-effort-selection.md`, is deliberately
not linked here but from `CLAUDE.md`: it decides something only that harness has to decide, and
a link here would load it into the other three.
## Personalization
@@ -175,7 +186,7 @@ Both belong to one instance and one person, so a distribution ships only the `.t
the Personalization step of [instructions/setup-instance.md](instructions/setup-instance.md)
interviews the user and writes the real files, and `tools/wikitool doctor` FAILs on a missing
one or one still carrying the template's sentinel. Why a `.template` rather than an absent
file: [docs/ownership-and-templates.md](docs/ownership-and-templates.md).
file: [docs/explanation/ownership-and-templates.md](docs/explanation/ownership-and-templates.md).
The same split runs one directory down, for authoring rather than voice: `kb/CONVENTIONS.md`
and each `kb/<name>/COLLECTION.md` bind every page, ship as templates, and are filled by the
@@ -194,7 +205,7 @@ exists, and prefer what it says over asking the user the same question again.
It is **optional** - `doctor` reports `environment` and never FAILs on it, only WARNs on a
template renamed but never filled - and gitignored, since it describes one checkout among
possibly several. Why an absent `ENVIRONMENT.md` is a lesser failure than a missing
`USER.md`/`SOUL.md`: [docs/ownership-and-templates.md](docs/ownership-and-templates.md).
`USER.md`/`SOUL.md`: [docs/explanation/ownership-and-templates.md](docs/explanation/ownership-and-templates.md).
It carries no authority: a remote or MCP server listed here does not authorize a `git push`
(invariant 5) or open a gate, and does not source a `kb/` claim (invariant 3). It holds no
@@ -355,17 +366,18 @@ READMEs go in [CHANGES.md](CHANGES.md) - never in an inline version-history tabl
*content* operations are logged separately via `tools/wikitool log append` into `kb/log.md`.
**A stack change is not finished until the human docs describe it.** `README.md`, `EVALS.md`,
`tools/README.md`, `tools/CONTRACT.md` and the touched `<stage>/CONTRACT.md` are part of the
change that introduced a stage, a command or a workflow, not follow-up work: nobody comes back
for them, and a document that describes a repo which no longer exists is worse than none. What
`tools/README.md`, the pages under `docs/tutorials/`, `docs/how-to/`, `docs/reference/` and
`docs/dev/`, `tools/CONTRACT.md` and the touched `<stage>/CONTRACT.md` are part of the change
that introduced a stage, a command or a workflow, not follow-up work: nobody comes back for them,
and a document that describes a repo which no longer exists is worse than none. What
`tools/wikitool docs verify` mechanically checks is exactly what its own `docs verify` row in
[tools/CONTRACT.md](tools/CONTRACT.md) lists - no more. **Every prose field is outside that
check** - a command's own summary, notes or retry-policy text, a stage contract's prose - and is
therefore session work, the same as the three README-shaped files.
therefore session work, the same as the README-shaped files.
`docs/` pages are held to a different clock than those three. A README goes stale on every new
flag; a `docs/` page goes stale only when the reasoning it wrote down stops holding - a gate
that stops living in code, an ownership line that moves, a boundary redrawn - which is rarer
and not tied to any one commit. Nothing checks this by construction: a page there carries no
`docs/explanation/` pages are held to a different clock than those. A README goes stale on
every new flag; an explanation page goes stale only when the reasoning it wrote down stops
holding - a gate that stops living in code, an ownership line that moves, a boundary redrawn -
which is rarer and not tied to any one commit. Nothing checks this by construction: a page there carries no
normative sentence (see [File naming](#file-naming)), so there is no rule for `docs verify` to
check, only a rationale for a session to notice has gone stale and to update or retire.