diff --git a/docs/superpowers/plans/2026-05-30-doc-structure-redesign.md b/docs/superpowers/plans/2026-05-30-doc-structure-redesign.md new file mode 100644 index 0000000..21b7028 --- /dev/null +++ b/docs/superpowers/plans/2026-05-30-doc-structure-redesign.md @@ -0,0 +1,611 @@ +# Doc Structure Redesign Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Rename the three overlapping `ARCHITECTURE.md` files into topic-named docs, move `FORMATS.md` into `docs/`, and pin every tour doc with a scope header + a "Next:" footer so the reading order is canonical and the drift surface shrinks. + +**Architecture:** Five sequential commits, each mechanical. No content is rewritten — the drift audit already cleaned the content in `210232d`, `cf7478d`, `fa659eb`. This plan only renames files, adds scope headers + "Next:" footers, fixes incoming links to old paths, and updates `CLAUDE.md`'s living-docs table and discipline rules. + +**Tech Stack:** Markdown, `git mv` (so blame/history follow), `grep -rn` for link verification, `git log --follow` for rename verification. + +**Source spec:** `docs/superpowers/specs/2026-05-30-doc-structure-redesign-design.md` — refer back when ambiguity arises. + +--- + +## File Structure + +**Renamed (Task 1):** +- `ARCHITECTURE.md` → `DESIGN.md` (top-level system tour) +- `docs/ARCHITECTURE.md` → `docs/CRYPTO.md` (crypto pipeline + flows) +- `FORMATS.md` → `docs/FORMATS.md` (wire formats) + +**Modified (Tasks 2-4):** +- `README.md` — trim mid-section "Architecture" stub to a one-paragraph pointer, add header + "Next:" footer. +- `DESIGN.md` — add scope header + "Next:" footer (no content rewrite of the tour itself). +- `docs/CRYPTO.md` — add scope header + "Next:" footer. +- `docs/FORMATS.md` — add scope header + "Next:" footer. +- `docs/SECURITY.md` — add scope header + "Next:" footer. +- `crates/relicario-core/ARCHITECTURE.md` — add scope header + "Next:" footer. +- `crates/relicario-cli/ARCHITECTURE.md` — add scope header + "Next:" footer. +- `extension/ARCHITECTURE.md` — add scope header + "Next:" footer (End of tour). +- `CLAUDE.md` — update the "Living docs — update discipline" table with new filenames; update the "Planning & design specs" core-references list if it references old paths; add three new discipline rules. +- Various callsites in `docs/superpowers/specs/*.md` and the per-crate / extension `ARCHITECTURE.md` files that link to old paths. + +**Unchanged:** `STATUS.md`, `ROADMAP.md`, `CHANGELOG.md`, `LICENSE`, `docs/superpowers/{specs,plans,audits,coordination,reviews,test-runs,MULTI-AGENT.md}`. + +--- + +## Task 1: Rename files + +**Files:** +- Rename: `ARCHITECTURE.md` → `DESIGN.md` +- Rename: `docs/ARCHITECTURE.md` → `docs/CRYPTO.md` +- Rename: `FORMATS.md` → `docs/FORMATS.md` + +- [ ] **Step 1: Confirm clean working tree (or only known dirt)** + +Run: `git status` + +Expected: only pre-existing modifications (`.claude/settings.json`, `docs/superpowers/plans/2026-04-22-relicario-extension-1c-beta1.md`, `docs/superpowers/specs/2026-04-11-relicario-design.md`, `extension/src/vault/vault.ts`). No other unstaged changes. If anything else is modified, stop and ask the user. + +- [ ] **Step 2: Perform the three renames** + +Run: +```bash +git mv ARCHITECTURE.md DESIGN.md +git mv docs/ARCHITECTURE.md docs/CRYPTO.md +git mv FORMATS.md docs/FORMATS.md +``` + +Expected: no errors. `git status` should now show three renamed files staged. + +- [ ] **Step 3: Verify renames are tracked as renames, not delete+add** + +Run: `git status --short` + +Expected output includes three lines starting with `R` (rename), not `D` (delete) + `??` (new): +``` +R ARCHITECTURE.md -> DESIGN.md +R docs/ARCHITECTURE.md -> docs/CRYPTO.md +R FORMATS.md -> docs/FORMATS.md +``` + +If git shows `D` + new file instead, stop and investigate — likely means the file content changed enough that git can't see the rename. (For this commit we changed nothing, so renames should be clean.) + +- [ ] **Step 4: Commit the renames** + +Run: +```bash +git commit -m "$(cat <<'EOF' +docs: rename for doc-structure redesign — DESIGN / CRYPTO / docs/FORMATS + +Mechanical renames only; no content changes. Tracked as renames so +git blame / git log --follow survive intact. + +- ARCHITECTURE.md → DESIGN.md (top-level system tour) +- docs/ARCHITECTURE.md → docs/CRYPTO.md (crypto pipeline) +- FORMATS.md → docs/FORMATS.md (wire formats; aligns with docs/ layout) + +Spec: docs/superpowers/specs/2026-05-30-doc-structure-redesign-design.md +EOF +)" +``` + +Expected: one commit created. Verify with `git log --oneline -1`. + +- [ ] **Step 5: Verify history follows the rename** + +Run: `git log --follow --oneline DESIGN.md | head -5` + +Expected: shows the rename commit on top, then commits to the old `ARCHITECTURE.md` underneath. Same idea for `docs/CRYPTO.md` and `docs/FORMATS.md` (`git log --follow --oneline docs/CRYPTO.md | head -5`). + +--- + +## Task 2: Add scope headers + "Next:" footers + trim README architecture section + +**Files (all modified):** +- `README.md` +- `DESIGN.md` +- `docs/CRYPTO.md` +- `docs/FORMATS.md` +- `docs/SECURITY.md` +- `crates/relicario-core/ARCHITECTURE.md` +- `crates/relicario-cli/ARCHITECTURE.md` +- `extension/ARCHITECTURE.md` + +Convention: scope header sits as a blockquote *immediately under the H1 title*, separated by a blank line. The "Next:" footer sits as the very last line of the file (with a blank line above it). + +- [ ] **Step 1: Add scope header + footer to `README.md`** + +Read `README.md` and find the existing H1 (`# Relicario` near top). Insert the scope blockquote on the line immediately after the H1's blank-line separator, then add the footer at the very end of the file. + +**Header (insert after H1):** +```markdown +> **Audience:** users + evaluators. This doc owns the pitch, security-model summary, quick-start commands, reference-image explanation, recovery-QR overview, and roadmap teaser. Goes no deeper — for the system tour see [DESIGN.md](DESIGN.md), for crypto see [docs/CRYPTO.md](docs/CRYPTO.md). +``` + +**Footer (append at very end of file):** +```markdown + +--- + +**Next:** [DESIGN.md](DESIGN.md) — the system tour. +``` + +- [ ] **Step 2: Trim README's mid-section "Architecture" stub to a one-paragraph pointer** + +In `README.md`, locate the `## Architecture` section (it's the one containing a tree diagram of `relicario/` and references to `docs/architecture/`). Replace the entire section content (from the heading through the end of the tree diagram, but BEFORE the next H2) with: + +```markdown +## Architecture + +A short tour of the four codebases and how they fit together lives in [DESIGN.md](DESIGN.md). Crypto pipeline diagrams are in [docs/CRYPTO.md](docs/CRYPTO.md); the wire format reference is [docs/FORMATS.md](docs/FORMATS.md); the threat model is [docs/SECURITY.md](docs/SECURITY.md). + +`relicario-core` is the platform-agnostic bytes-in/bytes-out heart — no filesystem, no network. The CLI binary and the browser-extension WASM bridge both consume it. See per-codebase deep-dives in `crates/*/ARCHITECTURE.md` and `extension/ARCHITECTURE.md`. +``` + +Do NOT touch the `### Crypto primitives` table or the `### Encrypted file format` block if they come immediately after — those are reader-friendly summaries that belong in the README. Only the codebase tree + the broken `docs/architecture/` reference go. + +Verify by reading the README from start to finish to confirm the flow still reads naturally. + +- [ ] **Step 3: Add scope header + footer to `DESIGN.md`** + +Read `DESIGN.md`. Insert this header after its H1 (currently `# Architecture overview — Relicario`): + +```markdown +> **Audience:** anyone wanting to understand the system at the cross-codebase level. This doc owns the four-codebase map, inter-codebase contracts, the secrets map (what secret lives where), the build matrix, and the global code-map index. **Does NOT own:** crypto pipeline details (see [docs/CRYPTO.md](docs/CRYPTO.md)), wire formats (see [docs/FORMATS.md](docs/FORMATS.md)), threat model (see [docs/SECURITY.md](docs/SECURITY.md)), per-crate module maps (see [crates/relicario-core/ARCHITECTURE.md](crates/relicario-core/ARCHITECTURE.md), [crates/relicario-cli/ARCHITECTURE.md](crates/relicario-cli/ARCHITECTURE.md), and [extension/ARCHITECTURE.md](extension/ARCHITECTURE.md)). +``` + +Append footer at end of file: +```markdown + +--- + +**Next:** [docs/CRYPTO.md](docs/CRYPTO.md) — the crypto pipeline that backs this design. +``` + +- [ ] **Step 4: Add scope header + footer to `docs/CRYPTO.md`** + +Read `docs/CRYPTO.md`. Insert this header after its H1 (currently `# Relicario — Architecture`): + +```markdown +> **Audience:** anyone evaluating or auditing the crypto. This doc owns Argon2id parameters and rationale, XChaCha20-Poly1305 rationale, vault creation/unlock flow diagrams, DCT-steganography embed and extract flows, and the high-level encrypted-file-format diagram. **Does NOT own:** byte-level schemas or JSON shapes (see [FORMATS.md](FORMATS.md)), attacker scenarios (see [SECURITY.md](SECURITY.md)), or per-module crypto implementation (see [../crates/relicario-core/ARCHITECTURE.md](../crates/relicario-core/ARCHITECTURE.md)). +``` + +Also update the H1 itself from `# Relicario — Architecture` to `# Relicario — Crypto Pipeline` so the file's title matches its renamed scope. + +Append footer at end of file: +```markdown + +--- + +**Next:** [FORMATS.md](FORMATS.md) — the byte-level wire formats. +``` + +- [ ] **Step 5: Add scope header + footer to `docs/FORMATS.md`** + +Read `docs/FORMATS.md`. Insert this header after its H1 (currently `# Relicario Wire Formats`): + +```markdown +> **Audience:** anyone implementing a compatible client or reading raw vault bytes. This doc owns the `.enc` blob layout, `params.json` / `salt` / `devices.json` / `revoked.json` shapes, the manifest JSON schema, the `.relbak` envelope, item-ID formats, and the settings JSON schema. **Does NOT own:** why these formats look this way (see [CRYPTO.md](CRYPTO.md)), threat model around them (see [SECURITY.md](SECURITY.md)), or Rust struct internals (see [../crates/relicario-core/ARCHITECTURE.md](../crates/relicario-core/ARCHITECTURE.md)). +``` + +The existing intro blockquote (`> Quick-reference for the load-bearing binary and JSON formats. …`) was a partial scope statement — leave it in place as a useful summary sentence, but the new scope blockquote above it is the canonical one. Place the new blockquote between H1 and the existing quick-reference blockquote. + +Append footer at end of file: +```markdown + +--- + +**Next:** [SECURITY.md](SECURITY.md) — the threat model. +``` + +- [ ] **Step 6: Add scope header + footer to `docs/SECURITY.md`** + +Read `docs/SECURITY.md`. Insert this header after its H1 (currently `# Relicario Security Model`): + +```markdown +> **Audience:** auditors and curious users. This doc owns the threat model, attacker-scenarios table, device-authentication model, env-var trust surface, and known limitations. **Does NOT own:** crypto primitive details (see [CRYPTO.md](CRYPTO.md)), wire formats (see [FORMATS.md](FORMATS.md)), or implementation (see [../crates/relicario-core/ARCHITECTURE.md](../crates/relicario-core/ARCHITECTURE.md)). +``` + +Append footer at end of file: +```markdown + +--- + +**Next:** [../crates/relicario-core/ARCHITECTURE.md](../crates/relicario-core/ARCHITECTURE.md) — implementation, starting with the platform-agnostic core. +``` + +- [ ] **Step 7: Add scope header + footer to `crates/relicario-core/ARCHITECTURE.md`** + +Read `crates/relicario-core/ARCHITECTURE.md`. Insert this header after its H1 (currently `# Architecture: relicario-core`): + +```markdown +> **Audience:** contributors editing or extending `relicario-core`. This doc owns the module map for this crate, module-level invariants (e.g., no filesystem, no network), key flows at the module level, and the crate's test architecture. **Does NOT own:** crypto primitives or threat model (see [../../docs/CRYPTO.md](../../docs/CRYPTO.md), [../../docs/SECURITY.md](../../docs/SECURITY.md)), wire formats (see [../../docs/FORMATS.md](../../docs/FORMATS.md)). +``` + +Append footer at end of file: +```markdown + +--- + +**Next:** [../relicario-cli/ARCHITECTURE.md](../relicario-cli/ARCHITECTURE.md) — how the CLI wraps the core. +``` + +- [ ] **Step 8: Add scope header + footer to `crates/relicario-cli/ARCHITECTURE.md`** + +Read `crates/relicario-cli/ARCHITECTURE.md`. Insert this header after its H1 (currently `# Architecture: relicario-cli`): + +```markdown +> **Audience:** contributors editing the CLI. This doc owns the CLI module map, the clap command surface, per-command key flows, session/unlock semantics, and helpers. **Does NOT own:** crypto, wire formats, or threat model (see [../../docs/CRYPTO.md](../../docs/CRYPTO.md), [../../docs/FORMATS.md](../../docs/FORMATS.md), [../../docs/SECURITY.md](../../docs/SECURITY.md)). +``` + +Append footer at end of file: +```markdown + +--- + +**Next:** [../../extension/ARCHITECTURE.md](../../extension/ARCHITECTURE.md) — the browser-side surface. +``` + +- [ ] **Step 9: Add scope header + footer to `extension/ARCHITECTURE.md`** + +Read `extension/ARCHITECTURE.md`. Insert this header after its H1 (currently `# Architecture: relicario extension`): + +```markdown +> **Audience:** contributors editing the browser extension. This doc owns the bundle structure (popup, vault tab, background SW, content scripts), the SW ↔ popup message contract, the component / pane architecture, routing, and the build pipeline. **Does NOT own:** WASM crypto internals (see [../crates/relicario-core/ARCHITECTURE.md](../crates/relicario-core/ARCHITECTURE.md)), wire formats (see [../docs/FORMATS.md](../docs/FORMATS.md)), or threat model (see [../docs/SECURITY.md](../docs/SECURITY.md)). +``` + +Append footer at end of file: +```markdown + +--- + +**End of tour.** For roadmap and in-flight work see [../STATUS.md](../STATUS.md) and [../ROADMAP.md](../ROADMAP.md). +``` + +- [ ] **Step 10: Verify all eight headers are present** + +Run: +```bash +grep -l '^> \*\*Audience:\*\*' README.md DESIGN.md docs/CRYPTO.md docs/FORMATS.md docs/SECURITY.md crates/relicario-core/ARCHITECTURE.md crates/relicario-cli/ARCHITECTURE.md extension/ARCHITECTURE.md +``` + +Expected: all eight filenames echoed back. If any file is missing from the output, its header didn't land — go back and add it. + +- [ ] **Step 11: Verify all "Next:" footers are present** + +Run: +```bash +grep -l -E '^\*\*(Next|End of tour)' README.md DESIGN.md docs/CRYPTO.md docs/FORMATS.md docs/SECURITY.md crates/relicario-core/ARCHITECTURE.md crates/relicario-cli/ARCHITECTURE.md extension/ARCHITECTURE.md +``` + +Expected: all eight filenames echoed back. + +- [ ] **Step 12: Verify README architecture section is trimmed** + +Run: `grep -n 'docs/architecture/' README.md` + +Expected: zero matches (the broken `docs/architecture/` reference is gone). + +Also run: `awk '/^## Architecture/,/^## [^A]/' README.md | wc -l` and inspect — the section between `## Architecture` and the next `##` heading should now be small (under ~15 lines), not the old multi-tree diagram. + +- [ ] **Step 13: Commit** + +Run: +```bash +git add README.md DESIGN.md docs/CRYPTO.md docs/FORMATS.md docs/SECURITY.md crates/relicario-core/ARCHITECTURE.md crates/relicario-cli/ARCHITECTURE.md extension/ARCHITECTURE.md +git commit -m "$(cat <<'EOF' +docs: add scope headers + Next: footers to all tour docs + +Each of the eight tour docs (README, DESIGN, docs/CRYPTO, +docs/FORMATS, docs/SECURITY, crates/relicario-core/ARCHITECTURE, +crates/relicario-cli/ARCHITECTURE, extension/ARCHITECTURE) now +declares its scope in a blockquote under its H1 and ends with a +single-line "Next:" pointer to the next doc in the canonical +reading order: README → DESIGN → CRYPTO → FORMATS → SECURITY → +core → cli → extension. + +Also trimmed README's mid-section "Architecture" stub to a one- +paragraph pointer at DESIGN.md (was duplicating cross-codebase +content and referencing a non-existent docs/architecture/ tree). + +Renamed docs/CRYPTO.md's H1 from "Relicario — Architecture" to +"Relicario — Crypto Pipeline" to match the file's renamed scope. + +Spec: docs/superpowers/specs/2026-05-30-doc-structure-redesign-design.md +EOF +)" +``` + +--- + +## Task 3: Fix incoming links to old paths + +**Files (modified as needed):** `CLAUDE.md`, plus whatever other files reference the old paths. + +- [ ] **Step 1: Find every reference to old paths in markdown files** + +Run: +```bash +grep -rn --include='*.md' \ + -e '](ARCHITECTURE\.md' \ + -e '](\./ARCHITECTURE\.md' \ + -e '](docs/ARCHITECTURE\.md' \ + -e '](FORMATS\.md' \ + -e '](\./FORMATS\.md' \ + -e '`ARCHITECTURE\.md`' \ + -e '`docs/ARCHITECTURE\.md`' \ + -e '`FORMATS\.md`' \ + . 2>/dev/null \ + | grep -v 'docs/superpowers/test-runs/' \ + | grep -v 'docs/superpowers/audits/' \ + | grep -v 'docs/superpowers/specs/2026-05-30-doc-structure-redesign-design.md' \ + | grep -v 'docs/superpowers/plans/2026-05-30-doc-structure-redesign.md' +``` + +Expected: a list of callsites that need updating. Will definitely include `CLAUDE.md` (the living-docs table and the planning-references list). May include per-crate ARCHITECTURE.md files and some specs in `docs/superpowers/specs/`. + +**Important caveat:** the bare token `ARCHITECTURE.md` is also a valid filename suffix for `crates/X/ARCHITECTURE.md` and `extension/ARCHITECTURE.md` (the per-crate docs we are NOT renaming). The grep above uses the `](` (markdown link prefix) and backtick patterns to limit matches to references that look like file paths in prose. If a hit references `crates//ARCHITECTURE.md` or `extension/ARCHITECTURE.md` — leave that one alone (it's a legitimate per-crate reference). + +- [ ] **Step 2: For each callsite in the grep output, apply the rewrite rule** + +Rewrite rules: +- `ARCHITECTURE.md` (top-level reference) → `DESIGN.md` +- `./ARCHITECTURE.md` → `./DESIGN.md` +- `docs/ARCHITECTURE.md` → `docs/CRYPTO.md` +- `FORMATS.md` (top-level reference) → `docs/FORMATS.md` +- `./FORMATS.md` → `./docs/FORMATS.md` + +Inside `CLAUDE.md` specifically, **also** the "Living docs — update discipline" table row labels need updating — that's part of Task 4, not Task 3. Task 3 only fixes link references. + +For each file with hits, use `Edit` (or `Edit` with `replace_all`) to apply the rewrites. Show your work in a brief summary at the end of this step: "Updated N references across M files." + +- [ ] **Step 3: Verify zero old-path references remain** + +Re-run the grep from Step 1. + +Expected: zero matches (modulo the explicitly-excluded test-runs/, audits/, the spec, and this plan). + +If any matches remain, examine and fix (or, if you determine a hit is a legitimate per-crate reference that was caught by the regex, document why it's allowed and move on). + +- [ ] **Step 4: Verify links resolve (no broken paths)** + +For every modified link, confirm the target file exists. Quick spot-check: +```bash +ls -1 DESIGN.md docs/CRYPTO.md docs/FORMATS.md docs/SECURITY.md crates/relicario-core/ARCHITECTURE.md crates/relicario-cli/ARCHITECTURE.md extension/ARCHITECTURE.md +``` + +Expected: all seven files listed (none missing). For relative links inside non-root docs, mentally trace the relative path or `ls` it. + +- [ ] **Step 5: Commit** + +Run: +```bash +git add -u +git commit -m "$(cat <<'EOF' +docs: fix incoming links to renamed/moved doc paths + +Rewrites every markdown reference to the old paths: +- ARCHITECTURE.md → DESIGN.md +- docs/ARCHITECTURE.md → docs/CRYPTO.md +- FORMATS.md → docs/FORMATS.md + +Touches CLAUDE.md (living-docs table + planning-references list), +per-crate ARCHITECTURE.md cross-refs, and any specs in +docs/superpowers/specs/ that referenced the old paths. Audit +history and test-run logs intentionally left untouched. + +Spec: docs/superpowers/specs/2026-05-30-doc-structure-redesign-design.md +EOF +)" +``` + +--- + +## Task 4: Update `CLAUDE.md` living-docs table + add three discipline rules + +**Files:** +- Modify: `CLAUDE.md` + +- [ ] **Step 1: Read the current `CLAUDE.md` living-docs section** + +Read `CLAUDE.md` and locate two sections: +1. The "Living docs — update discipline" table (the table starting with `| File | What it documents | Update when... |`). +2. The "Planning & design specs" paragraph + "Core references" bullet list (above the table). + +- [ ] **Step 2: Update the table to use new filenames** + +In the table, apply these row-label rewrites: + +| Current row label | New row label | +|---|---| +| `` `ARCHITECTURE.md` `` | `` `DESIGN.md` `` | +| `` `docs/ARCHITECTURE.md` `` | `` `docs/CRYPTO.md` `` | +| `` `FORMATS.md` `` | `` `docs/FORMATS.md` `` | + +The "What it documents" and "Update when..." cells for `DESIGN.md` and `docs/CRYPTO.md` and `docs/FORMATS.md` should be reviewed and lightly polished if they reference the old filename or scope — but the existing wording is already mostly correct, so only edit if a cell explicitly contradicts the new scope. Don't rewrite for the sake of rewriting. + +- [ ] **Step 3: Update the "Planning & design specs" core-references list** + +If the bullet list above the table references `docs/superpowers/specs/.md` with a specific old path or doc name, leave the bullets alone (those are spec citations, not docs being renamed). If the bullet list references `ARCHITECTURE.md`, `docs/ARCHITECTURE.md`, or `FORMATS.md` in prose, apply the same rewrites as Task 3 Step 2. + +- [ ] **Step 4: Add three new discipline rules** + +Add a new section to `CLAUDE.md` immediately *after* the "Living docs — update discipline" table, titled `### Discipline rules`. Insert this content: + +```markdown +### 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. +``` + +- [ ] **Step 5: Verify `CLAUDE.md` changes** + +Run: +```bash +grep -n 'DESIGN.md\|docs/CRYPTO.md\|docs/FORMATS.md' CLAUDE.md +``` + +Expected: at least three matches (one for each renamed file in the table). Also: + +```bash +grep -n 'Discipline rules' CLAUDE.md +``` + +Expected: one match (the new section heading). + +Also verify zero old-path references remain in `CLAUDE.md`: +```bash +grep -nE '`ARCHITECTURE\.md`|`docs/ARCHITECTURE\.md`|`FORMATS\.md`' CLAUDE.md | grep -v 'crates/.*ARCHITECTURE\.md' | grep -v 'extension/ARCHITECTURE\.md' +``` + +Expected: zero matches. + +- [ ] **Step 6: Commit** + +Run: +```bash +git add CLAUDE.md +git commit -m "$(cat <<'EOF' +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 +EOF +)" +``` + +--- + +## Task 5: Final verification gate + +**Files:** none modified in this task — pure verification. If a check fails, fix the relevant earlier commit (don't add a new commit just to patch up missing wording from an earlier task). + +- [ ] **Step 1: Scope-header presence check** + +Run: +```bash +for f in README.md DESIGN.md docs/CRYPTO.md docs/FORMATS.md docs/SECURITY.md crates/relicario-core/ARCHITECTURE.md crates/relicario-cli/ARCHITECTURE.md extension/ARCHITECTURE.md; do + if grep -q '^> \*\*Audience:\*\*' "$f"; then + echo "OK $f" + else + echo "FAIL $f (no scope header)" + fi +done +``` + +Expected: eight `OK` lines, zero `FAIL`. If any FAIL, fix the file's header and amend the Task 2 commit (or add a follow-up commit if amending would be too disruptive). + +- [ ] **Step 2: "Next:" footer chain check** + +Run: +```bash +for f in README.md DESIGN.md docs/CRYPTO.md docs/FORMATS.md docs/SECURITY.md crates/relicario-core/ARCHITECTURE.md crates/relicario-cli/ARCHITECTURE.md; do + if grep -q -E '^\*\*Next:\*\*' "$f"; then + echo "OK $f" + else + echo "FAIL $f (no Next: footer)" + fi +done +if grep -q -E '^\*\*End of tour' extension/ARCHITECTURE.md; then + echo "OK extension/ARCHITECTURE.md" +else + echo "FAIL extension/ARCHITECTURE.md (no End of tour footer)" +fi +``` + +Expected: eight `OK` lines, zero `FAIL`. + +- [ ] **Step 3: No old paths remain in living docs** + +Run the same grep from Task 3 Step 3: +```bash +grep -rn --include='*.md' \ + -e '](ARCHITECTURE\.md' \ + -e '](\./ARCHITECTURE\.md' \ + -e '](docs/ARCHITECTURE\.md' \ + -e '](FORMATS\.md' \ + -e '](\./FORMATS\.md' \ + . 2>/dev/null \ + | grep -v 'docs/superpowers/test-runs/' \ + | grep -v 'docs/superpowers/audits/' \ + | grep -v 'docs/superpowers/specs/2026-05-30-doc-structure-redesign-design.md' \ + | grep -v 'docs/superpowers/plans/2026-05-30-doc-structure-redesign.md' +``` + +Expected: zero matches (modulo the excluded paths). + +- [ ] **Step 4: Renames are git-tracked** + +Run: +```bash +git log --follow --oneline DESIGN.md | tail -3 +git log --follow --oneline docs/CRYPTO.md | tail -3 +git log --follow --oneline docs/FORMATS.md | tail -3 +``` + +Expected: each shows commits *before* the rename (i.e., when the file was `ARCHITECTURE.md` / `docs/ARCHITECTURE.md` / `FORMATS.md`). If any shows only the rename commit and nothing else, `git log --follow` is not picking up the history — likely because of how the rename commit was made. Investigate and fix. + +- [ ] **Step 5: CLAUDE.md table is current** + +Run: +```bash +grep -nE '\| `(DESIGN|docs/CRYPTO|docs/FORMATS)\.md` \|' CLAUDE.md +``` + +Expected: three matches (one for each renamed file). If fewer, the table row was missed in Task 4 Step 2. + +Also run: +```bash +grep -n '### Discipline rules' CLAUDE.md +``` + +Expected: one match. + +- [ ] **Step 6: README architecture-section trim verification** + +Run: +```bash +awk '/^## Architecture/,/^## [^A]/' README.md | head -20 +``` + +Expected: short paragraph (around 5-8 lines of prose), no codebase tree diagram, and a link to `DESIGN.md`. If the old tree diagram still shows, Task 2 Step 2 didn't land — go back and trim. + +- [ ] **Step 7: Push** + +Once all six checks above pass, push all five commits: + +```bash +git push +``` + +Expected: push succeeds. Working tree is clean (modulo the pre-existing dirt on `.claude/settings.json` etc.). + +- [ ] **Step 8: Final summary** + +Echo a short summary of what landed: 5 commits, file count by category, anything that needed amending. This is for the user's reading pleasure, not a code change. + +--- + +## Done + +Verify with the user that all tour docs flow naturally when read in order: `README → DESIGN → docs/CRYPTO → docs/FORMATS → docs/SECURITY → crates/relicario-core/ARCHITECTURE.md → crates/relicario-cli/ARCHITECTURE.md → extension/ARCHITECTURE.md`. If anything reads awkwardly, that's a content polish for a future pass, not a structural problem with this redesign.