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

docs/explanation/knowledge-and-commitment.md

@@ -0,0 +1,147 @@
+# Why knowledge and commitments are two layers
+
+Chemenu compiles knowledge into `kb/`, and it also tracks what its operator has committed to do.
+Those look like one subject - both are "things about my projects" - and the stack deliberately
+keeps them apart: `kb/gtd/` holds one page per initiative, an external task tracker holds the
+open items, and the only thing that crosses between them is a name. This page is about why that
+line was drawn there. The rules that follow from it live in [kb/CONTRACT.md](../../kb/CONTRACT.md)
+and the `review`, `new` and `task new` records in [tools/CONTRACT.md](../../tools/CONTRACT.md).
+
+<!-- wikitool:toc -->
+## Contents
+
+- [Different half-lives want different machinery](#different-half-lives-want-different-machinery)
+- [Pattern 4: separate ownership, no synchronization](#pattern-4-separate-ownership-no-synchronization)
+- [The join happens at read time, and stores nothing](#the-join-happens-at-read-time-and-stores-nothing)
+- [One name, carrying the duties of an identifier](#one-name-carrying-the-duties-of-an-identifier)
+- [Status has exactly one home](#status-has-exactly-one-home)
+- [A finished initiative is a state, not a location](#a-finished-initiative-is-a-state-not-a-location)
+- [Which tracker is a decision the stack does not make](#which-tracker-is-a-decision-the-stack-does-not-make)
+<!-- /wikitool:toc -->
+
+## Different half-lives want different machinery
+
+`kb/` is a compiler for durable things, and every mechanism in it assumes durability: `raw/` is
+immutable, a claim has to trace back to a source, a page's title is its identity, the indexes are
+generated, and a large change stops at a gate so a human can look at it. All of that is the right
+amount of ceremony for something that will still be true next year.
+
+A next action is the opposite kind of fact. It is unsourced - nobody cites a reason for "call the
+plumber". It changes several times a week. It is state, not knowledge: the interesting thing
+about it is whether it is still open. And it is only correct *now*.
+
+Running both through one layer does not produce a richer wiki; it produces a worse one. Every
+task-shaped page carries `provenance: general` because there is no source to bind it to, which
+drains that field of meaning for the pages where it matters. `kb/log.md` fills with "task
+checked off" entries until the audit trail of what the *wiki* learned is unreadable. Lint findings
+about orphans and stale claims start firing on pages that are supposed to be short-lived. And a
+weekly pass over the task list trips the Mass-Update Gate every single time, which is how a gate
+stops being read and starts being cleared reflexively.
+
+The GTD method this borrows from draws the same line for its own reasons: of its horizons, `kb/`
+covers the two slowest - project support material and reference - and nothing faster.
+
+## Pattern 4: separate ownership, no synchronization
+
+Four arrangements were on the table, and three of them fail in ways worth naming.
+
+**One layer** is the case above. **Export** - the wiki writes a task list the tracker imports -
+means a checkbox ticked in the tracker is a tick in a view, while the truth sits in a file the
+operator was not editing; the two disagree immediately and silently. **Bidirectional sync** works,
+at the cost of an id mapping to maintain, a conflict-resolution rule to design, and a deletion
+semantics to decide - all of it machinery whose only job is to repair a split nobody needed.
+
+What is left is **separate ownership with no sync at all**: the tracker owns the tasks, `kb/` owns
+the project memory, and the single point of contact is the project's name. Nothing is mirrored,
+so nothing can drift out of mirror.
+
+## The join happens at read time, and stores nothing
+
+Because there is no shared state, the connection between the two sides has to be made when
+somebody actually asks - which is what `wikitool review` does: it reads both sides, matches them on
+the case-normalized project name, prints what it found, and saves nothing. Not a cache, not a
+mapping file, not even a `reports/` artifact.
+
+That is the same posture `search` takes, and for the same reason: anything it wrote down would be
+a third copy of a state the two sides already hold, stale the moment either side moved, and the
+first thing to distrust in a report. A read-time join can be wrong about the present, but it
+cannot be wrong about the past, because it does not remember one.
+
+## One name, carrying the duties of an identifier
+
+Reducing the coupling to a name is cheap, and it is not free. A name that joins two systems is an
+identifier, whether or not anything enforces it, so the design had to pick up an identifier's
+obligations explicitly: uniqueness is checked before a project is created rather than discovered
+later; a rename is a deliberate, infrequent operation that touches both sides in one pass; and
+nothing tries to re-match automatically behind the operator's back.
+
+The last one is what makes the review's *both-directional* report matter. A tracker project with
+no page and a page with no tracker project are reported separately, as two findings. They are
+usually the two halves of one rename - and reporting them separately is exactly what turns a
+silent decoupling into a visible event, at the cost of the review occasionally saying the same
+thing twice.
+
+## Status has exactly one home
+
+The sharpest consequence of the split is a rule that feels like a restriction: a `kb/` page never
+summarizes its own task list. No "3 open items", no "next: call the supplier".
+
+Two places claiming to know the current status is the failure mode the whole arrangement exists
+to avoid, and a summary is a copy with a slower clock. The page says what an initiative *is* -
+its goal, its participants, its durable state, why it is worth doing. The tracker says what is
+open right now. Anyone wanting the second reads the tracker, or runs the review.
+
+This pays for itself somewhere unexpected: with the page carrying no task state, an agent has no
+reason to read the task list at all outside the weekly review. That is what keeps the command
+surface as small as it is - two read commands and three write commands - rather than growing a
+full CRUD tree over somebody's todo list. The second creation command exists because a single
+name is not always the whole story: a source can carry a piece of durable knowledge and a
+commitment to follow up on it at the same time - a complaint arriving by email is both something
+to file and something to chase - and the tracker-side half of that needs its own write path
+alongside `new project`'s pairing of a page with a tracker project. `task new` creates only the
+tracker item, never a page; a source that also carries knowledge gets that knowledge filed
+through the ordinary page-creation commands, as a separate step. The two are never one
+transaction the way `new project`'s tracker-then-page order is within a single command - they are
+two independent writes a skill sequences, tracker first, so a failure creating the item leaves no
+page and no promoted source material behind it. That holds for an ordinary source; a source large
+or broad enough to run through the large-tree procedure instead promotes ahead of its own
+per-unit commitment decision, because that procedure hands its units through a workshop directory
+that needs them already promoted to address them at all - the same raw-file-without-page state
+the ordinary case avoids becomes, there, the expected condition for as long as the run takes. And
+a failure on the knowledge side afterwards is exactly the ordinary "a source without a page" state
+`lint` already reports.
+
+The write surface stops at *creating* an item and *marking one done* - it never moves a reminder
+and never deletes anything. `task close` sets exactly the field the tracker's own "done" checkbox
+sets, nothing more: reversible, and it leaves a record in the tracker rather than removing the
+item's trace. A command that deleted would take the same shortcut through somebody's task list
+that the whole split above exists to avoid - a write this stack cannot undo, made on behalf of a
+tracker it does not own. `task list` is the one addition on the read side, and it changes nothing
+about the join itself: it exists only because closing an item needs the tracker's own id for it,
+and that id was never worth exposing before there was a write that consumed it.
+
+## A finished initiative is a state, not a location
+
+Archiving moves nothing. A completed initiative's page stays where it is and changes its `state:`
+value, because the moment an initiative finishes is the moment its page is *most* valuable -
+what was decided, what it cost, who was involved - and filing it away is how that gets lost.
+
+The state field carries the distinction the review actually needs, which is not "open vs. done"
+but "does silence here mean something is wrong". An initiative that is deliberately paused looks
+identical, from the outside, to one that quietly stalled; only the operator knows which. Without a
+value for "paused on purpose", the review reports the same untouched initiatives every week, and
+a report that is mostly noise stops being read by the third week - which would cost more than the
+findings are worth.
+
+## Which tracker is a decision the stack does not make
+
+The tracker is reached through a provider layer, and no instruction anywhere names which one it
+is. An instruction that said "open Super Productivity" would bake one instance's tool choice into
+the shared stack, and the next instance - a different context, a different employer, a different
+set of constraints - would have to edit prose to change a setting.
+
+So the provider lives in configuration (`.wikitool-tasks.json`), the adapters live behind one
+protocol, and a capability the provider lacks surfaces as an ordinary tool error rather than as a
+paragraph of instruction explaining what this particular tracker cannot do. A provider that
+cannot create a project, for instance, stops and asks the operator to do it - the same posture the
+gates take, and for the same reason: better a visible stop than an invented workaround.