claude
c0f4074a5d
Nineteen of the twenty findings were open, and they lived in an untracked audit.md at the repo root that no next session would have read. The one that is closed, the unauthenticated mavgpud proxy, went out as V-673. The report is now a frozen measurement under docs/evals/, dated and never edited again — including when a finding it names gets fixed. The live state moved to docs/caveats/, one entry per limit, each carrying its Vikunja id and the condition that makes it worth fixing. A caveat with no revisit trigger is a complaint, so every entry has one. Closing a limit deletes its entry rather than editing the measurement that found it. Two directory indexes come with it. docs/CLAUDE.md states the tier rule the repo already followed by convention: living docs corrected in place, evals frozen by date, caveats deleted when fixed. docs/caveats/CLAUDE.md indexes the nineteen by claim and severity, because an index of filenames adds nothing a directory listing does not. Tasks V-675 through V-693 carry the plans. The doc line and the tracker now join in both directions. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ESv8hqNPseYt1CnotZpqDz
31 lines
1.6 KiB
Markdown
31 lines
1.6 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. | 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 | until the work lands |
|
|
| `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.
|
|
|
|
## 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.
|