docs(CLAUDE.md): update living-docs table + add discipline rules
Table row labels now reference DESIGN.md / docs/CRYPTO.md /
docs/FORMATS.md. Adds three new discipline rules attacking the
structural causes of the 2026-05-30 drift audit findings:
1. Scope-boundary check — content goes in the doc whose scope
header claims it; if it doesn't fit, move it instead of
stretching the header.
2. Code-constant pinning — docs that cite code constants must
cite source file + line; constant changes update doc and
code in the same commit.
3. New-doc rule — adding a tour doc also requires updating
DESIGN's code-map, the Next: footer chain, and this table.
Spec: docs/superpowers/specs/2026-05-30-doc-structure-redesign-design.md
This commit is contained in:
18
CLAUDE.md
18
CLAUDE.md
@@ -95,7 +95,7 @@ Core references (read before touching crypto, data model, or architecture):
|
|||||||
- `docs/superpowers/specs/2026-04-18-relicario-typed-items-design.md` — typed-item data model and envelope
|
- `docs/superpowers/specs/2026-04-18-relicario-typed-items-design.md` — typed-item data model and envelope
|
||||||
- `docs/superpowers/specs/2026-04-30-relicario-fullscreen-ux-redesign-design.md` — fullscreen UX phase plan
|
- `docs/superpowers/specs/2026-04-30-relicario-fullscreen-ux-redesign-design.md` — fullscreen UX phase plan
|
||||||
|
|
||||||
After completing any dev iteration, update `STATUS.md` to reflect what shipped and what's now in flight. Update the component `ARCHITECTURE.md` for any area you changed (see table below).
|
After completing any dev iteration, update `STATUS.md` to reflect what shipped and what's now in flight. Update the component doc for any area you changed (see table below).
|
||||||
|
|
||||||
## Roadmap & status
|
## Roadmap & status
|
||||||
|
|
||||||
@@ -105,13 +105,23 @@ Current in-flight work: `STATUS.md`. Full roadmap with release targets: `ROADMAP
|
|||||||
|
|
||||||
| File | What it documents | Update when... |
|
| File | What it documents | Update when... |
|
||||||
|---|---|---|
|
|---|---|---|
|
||||||
| `ARCHITECTURE.md` | Cross-codebase structure: four codebases, contracts, secrets map, build matrix, test strategy | Adding a codebase, changing inter-codebase contracts, new build targets |
|
| `DESIGN.md` | Cross-codebase structure: four codebases, contracts, secrets map, build matrix, test strategy | Adding a codebase, changing inter-codebase contracts, new build targets |
|
||||||
| `docs/ARCHITECTURE.md` | Crypto pipeline diagrams, vault creation/unlock flows, DCT embedding, encrypted file format | Changing crypto primitives, format version byte, or file format |
|
| `docs/CRYPTO.md` | Crypto pipeline diagrams, vault creation/unlock flows, DCT embedding, encrypted file format | Changing crypto primitives, format version byte, or file format |
|
||||||
| `crates/relicario-core/ARCHITECTURE.md` | Module map, invariants, key flows, test architecture for `relicario-core` | Adding/changing modules, item types, or crypto invariants in core |
|
| `crates/relicario-core/ARCHITECTURE.md` | Module map, invariants, key flows, test architecture for `relicario-core` | Adding/changing modules, item types, or crypto invariants in core |
|
||||||
| `crates/relicario-cli/ARCHITECTURE.md` | Module map, invariants, key flows (init, unlock, all commands) for `relicario-cli` | Adding/changing CLI commands, helpers, or session behavior |
|
| `crates/relicario-cli/ARCHITECTURE.md` | Module map, invariants, key flows (init, unlock, all commands) for `relicario-cli` | Adding/changing CLI commands, helpers, or session behavior |
|
||||||
| `extension/ARCHITECTURE.md` | Bundle structure, SW↔popup contract, component architecture | Adding bundles, changing the SW message protocol, or major UI flows |
|
| `extension/ARCHITECTURE.md` | Bundle structure, SW↔popup contract, component architecture | Adding bundles, changing the SW message protocol, or major UI flows |
|
||||||
| `docs/SECURITY.md` | Threat model, device auth, env-var trust surface | Adding env vars, changing auth model, new security-relevant config |
|
| `docs/SECURITY.md` | Threat model, device auth, env-var trust surface | Adding env vars, changing auth model, new security-relevant config |
|
||||||
| `FORMATS.md` | Wire formats: `.enc` blobs, `params.json`, `devices.json`, manifest schema | Changing any serialized format, version number, or on-disk layout |
|
| `docs/FORMATS.md` | Wire formats: `.enc` blobs, `params.json`, `devices.json`, manifest schema | Changing any serialized format, version number, or on-disk layout |
|
||||||
| `STATUS.md` | In-flight work, recent landings, what's next | End of every dev iteration |
|
| `STATUS.md` | In-flight work, recent landings, what's next | End of every dev iteration |
|
||||||
| `ROADMAP.md` | Full roadmap with release targets | When milestones shift or new work is scoped |
|
| `ROADMAP.md` | Full roadmap with release targets | When milestones shift or new work is scoped |
|
||||||
| `CHANGELOG.md` | User-facing release history | When tagging a release |
|
| `CHANGELOG.md` | User-facing release history | When tagging a release |
|
||||||
|
|
||||||
|
### Discipline rules
|
||||||
|
|
||||||
|
Three rules to prevent the kind of drift the 2026-05-30 audit found:
|
||||||
|
|
||||||
|
1. **Scope-boundary check.** When editing a tour doc, verify the change fits the doc's scope header. If it doesn't, the change belongs in a different doc — move it instead of stretching the scope. Concretely: a sentence about crypto added to `DESIGN.md` belongs in `docs/CRYPTO.md`; a wire-format table added to `docs/CRYPTO.md` belongs in `docs/FORMATS.md`.
|
||||||
|
|
||||||
|
2. **Code-constant pinning.** When a tour doc cites a code constant (`VERSION_BYTE = 0x02`, `QUANT_STEP = 50.0`, `MIN_COPIES = 5`, `MANIFEST_SCHEMA_VERSION = 2`, etc.), the doc must cite the source file + line. When the underlying constant changes, grep for the citation pattern and update the docs together with the code change in the same commit. Most drift the audit found was code-constant drift — this rule attacks it at the source.
|
||||||
|
|
||||||
|
3. **New-doc rule.** When adding a tour doc, also update (a) `DESIGN.md`'s code-map, (b) the reading-order sequence (the "Next:" footer chain), and (c) the living-docs table above. A new doc that doesn't appear in all three is not done.
|
||||||
|
|||||||
Reference in New Issue
Block a user