CLAUDE.md-Importkette entdrifted, Modellwahl nach docs/ verschoben
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:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user