claude
7f804b84e7
docs/CLAUDE.md defined four tiers and docs/capabilities/ and docs/architecture/ were neither of them. Both are now declared as generated: rebuilt from a source, never corrected in place. A wrong row in either is a bug in the generator or in one of its hand-written inputs, and editing the output makes the next rebuild silently undo the fix. The eval index gains the 2026-08-19 CPT+SFT measurement and the 2026-08-26 baseline, and marks the 2026-08-13 capability audit superseded. The 2026-08-19 file lands with them: it is the direct evidence that the deployed maven-instruct-b2 routes better than Qwen3-1.7B and cannot hold a Russian sentence, which is the first item on the gaps.md priority list. Its header records Vikunja as returning 503. That reading was wrong and the 2026-08-26 baseline says so, but a dated eval is not edited after the day. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
37 lines
2.5 KiB
Markdown
37 lines
2.5 KiB
Markdown
# docs/
|
|
|
|
Everything an agent needs that is not a rule and not code. `CLAUDE.md` at the
|
|
root carries the rules and points here. Nothing here restates a rule.
|
|
|
|
The tier is the path, so staleness is visible from the filename.
|
|
|
|
| path | holds | lifetime |
|
|
| --- | --- | --- |
|
|
| `docs/*.md` | living. One file per subsystem: the reasoning, corrected in place. Each carries `Last verified: <date> @ <sha>`. | until it is wrong |
|
|
| `docs/evals/` | dated measurements, one file per measurement. **Never edited after the day.** A newer number is a new file. Indexed in `docs/evals/CLAUDE.md`, which marks each one live or superseded. | forever |
|
|
| `docs/caveats/` | known limits, one entry per limit, each with a task id and a revisit trigger. Indexed in `docs/caveats/CLAUDE.md`. | until fixed, then deleted |
|
|
| `docs/plans/` | the plan for one piece of work, frozen once it starts. Indexed in `docs/plans/CLAUDE.md`. | until the work lands |
|
|
| `docs/capabilities/` | generated. The capability ledger and its probe harness, regenerated from `docs/spec.md` plus a named eval. **Never hand-edited**, except `domains.yaml`, `probes_field.json` and the scripts, which are its sources. Indexed in `docs/capabilities/README.md`. | until the spec or the measurement moves |
|
|
| `docs/architecture/` | generated. The architecture observation and its evidence pack, rebuilt from source by the scripts beside it. Indexed in `docs/architecture/README.md`. | until the shape changes |
|
|
| `docs/archive/` | dead. Read by nobody by default. | forever |
|
|
|
|
## Rules for this directory
|
|
|
|
* One fact, one home. A measurement is cited from a living doc, never copied
|
|
into it. The two drift the moment they are both edited.
|
|
* A living doc is corrected in place and its `Last verified` line moves with the
|
|
correction. Do not append a changelog to it.
|
|
* A number in prose with no `docs/evals/` file behind it is an opinion.
|
|
* Fixing something deletes its caveat. It does not edit the eval that found it.
|
|
* **A generated tier is rebuilt, never corrected.** A wrong row in
|
|
`docs/capabilities/` or `docs/architecture/` is a bug in the generator or in
|
|
one of its hand-written inputs. Editing the output makes the next rebuild
|
|
silently undo the fix.
|
|
|
|
## Where a subsystem's reasoning lives
|
|
|
|
`routing.md`, `language.md`, `world.md`, `offload.md`, `deployment.md`,
|
|
`ecosystem.md`, `workflow.md`, `design.md`, `rearchitecture.md`,
|
|
`determinism.md`, `protocol.md`, `handler-wiring.md`, `operations.md`, `qa.md`.
|
|
The root `CLAUDE.md` says which one to read before touching what.
|