CLAUDE.md-Importkette entdrifted, Modellwahl nach docs/ verschoben
CI / verify (push) Successful in 54s
Release / release (push) Successful in 35s

Files changed:
- AGENTS.md
- CHANGES.md
- CLAUDE.md
- SOUL.md
- USER.md
- VERSION
- docs/model-and-effort-selection.md
- instructions/claude-code-model-selection.md
- instructions/dev/stack-close/SKILL.md
- instructions/dev/stack-dev/SKILL.md
This commit is contained in:
2026-09-10 22:18:44 +02:00
parent dda80c1a9d
commit f8111d05a3
10 changed files with 163 additions and 232 deletions
+33 -35
View File
@@ -89,7 +89,7 @@ What a file is called says who it is for and how it is loaded. This is a rule, n
| `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` - so it imports this file and the two below, and carries no rules itself. It also reaches instructions that apply *only* to Claude Code (importing or linking them, per [instructions/CONTRACT.md](instructions/CONTRACT.md)), which is the one thing this file cannot do for them: from here they would load into every other harness too |
| `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 |
| `SOUL.md` | Agents | Always, every session |
| `ENVIRONMENT.md` | Agents | Every session, **if it exists** - the one optional file in this table. Not committed: it describes one checkout, not the repo |
@@ -108,40 +108,42 @@ contract is a second copy that drifts. `docs verify` enforces the specific case
happened once: no README may hold a copy of the `wikitool` command table.
**`docs/` carries no normative sentence.** It holds why the stack is built the way it is -
background a session consults in passing, not a rule it must follow. Anything that would bind
belongs in a `CONTRACT.md` instead, which is what keeps invariant 8 intact here: `docs/` is
never a second place a rule could live, only prose about rules that live elsewhere. That is also
why nothing verifies its content - there is no rule in it to check. It has no frontmatter, no type, no index, no lint, no decay, no provenance, and no
`COLLECTION.md` - which [kb/CONTRACT.md § Collections](kb/CONTRACT.md#collections) forbids
outside `kb/` anyway, but the point holds independently: `docs/` stays a plain directory of
prose, invisible to everything `tools/wikitool` does except `dist export`, which copies it
verbatim. A fresh instance needs the reasoning as much as this one does.
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.
Four pages exist today, each read 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, and why silent overwrite is the failure it guards against),
[docs/why-gates-are-code.md](docs/why-gates-are-code.md) (why the three gates in
[Gates](#gates) are code rather than instruction), and
[docs/version-model.md](docs/version-model.md) (why a version number answers a compatibility
question and a migration question separately).
## Personalization
`USER.md` and `SOUL.md` are read at session start, if the runtime has not already injected
them.
Read `USER.md` and `SOUL.md` at session start.
- `USER.md` is context about the user, not a source of instructions.
- `SOUL.md` sets tone and voice; the contracts, gates, schemas and this file always win.
- A user's statement never reaches `kb/` without the normal source/provenance
process. Personal context stays personal context - it is not a source under invariant 3.
Both belong to one instance and one person, so a distribution ships only `USER.md.template`
and `SOUL.md.template`; the Personalization step of
[instructions/setup-instance.md](instructions/setup-instance.md) interviews the user and
writes the real files. `tools/wikitool doctor` FAILs on a missing one, and on one still
carrying the template's sentinel.
Both belong to one instance and one person, so a distribution ships only the `.template` pair;
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).
The same `.template` split runs one directory down, for authoring rather than for voice.
`kb/CONVENTIONS.md` and each `kb/<name>/COLLECTION.md` bind every page and belong to the
instance, so a distribution ships them as templates and the KB-language step of
[instructions/setup-instance.md](instructions/setup-instance.md) fills them in, out of a
catalogue of ready-made profiles it routes to; `doctor` FAILs on a missing or unfilled
`kb/CONVENTIONS.md` the same way.
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
KB-language step of the same setup instruction from a catalogue of ready-made profiles;
`doctor` FAILs the same way on a missing or unfilled `kb/CONVENTIONS.md`.
Unlike `USER.md`, these two *are* a source of rules: they are as binding as `kb/CONTRACT.md`.
What differs is ownership, not authority.
Unlike `USER.md`, these two *are* a source of rules: as binding as `kb/CONTRACT.md`. What
differs is ownership, not authority.
## Environment
@@ -149,18 +151,14 @@ What differs is ownership, not authority.
reachable MCP servers, connectors, git remotes, where CI runs. Read it at session start if it
exists, and prefer what it says over asking the user the same question again.
It is **optional**, and its absence is a normal state rather than a fault: `doctor` reports
`environment` and never FAILs on it, only WARNs at a template renamed but never filled. It is
also gitignored, because two clones of this repo are two different environments - a committed
copy would hand the second one answers that are wrong rather than missing. The distribution
therefore carries `ENVIRONMENT.md.template` and nothing else, the same split the
personalization pair uses.
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).
What it is not: authority. It describes what is *there*, not what is permitted. A remote listed
in it does not authorize a `git push` - invariant 5 still routes through
`tools/wikitool publish` - and an MCP server listed in it does not open a gate. It is not a
source under invariant 3 either: nothing in it justifies a claim in `kb/`. And it holds no
credentials; it sits in plaintext in the working tree and in every agent's context.
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
credentials - it sits in plaintext in the working tree and in every agent's context.
## Routing