docs: add CLAUDE.md rule #4 (plan-state hygiene) + tick doc-structure plan

Rule #4 codifies the discipline that prevents the kind of drift the
2026-05-30 status-audit found: Phase 2B, v0.5.1 Streams A/B/C, and 1C-γ
all stealth-shipped 2-3 weeks earlier with their plan checkboxes never
ticked and STATUS.md still listing them as "Up next".

Two halves to the rule:
- Ship side: ticking the boxes is part of shipping. A commit that lands
  plan work also ticks that plan's boxes (or an immediately-following
  docs commit does).
- Execute side: before starting an unchecked plan, spot-check git log
  for distinctive symbols/files — re-executing already-merged work is
  the worst failure mode of the drift.

Also applies the rule retroactively to the doc-structure redesign plan:
all 37 sub-step checkboxes flipped to [x]. Tasks 1-4 (rename, scope
headers + Next: footers, link fixes, CLAUDE.md table) shipped in
36a59cd..bae3f7c. Task 5's six verification steps all pass (Step 3's
grep matches are false positives — they're correct new-path sibling
links from inside docs/ to docs/, not stale old-path uses).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

CLAUDE.md

@@ -118,10 +118,14 @@ Current in-flight work: `STATUS.md`. Full roadmap with release targets: `ROADMAP
 
 ### Discipline rules
 
-Three rules to prevent the kind of drift the 2026-05-30 audit found:
+Four rules to prevent the kind of drift the 2026-05-30 audits 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.
+
+4. **Plan-state hygiene.** Plan checkboxes and `STATUS.md`/`ROADMAP.md` must reflect what's actually shipped. Two halves:
+   - **Ship side:** when a commit lands work that maps to a plan task, tick that plan's checkboxes in the same commit (or the immediately-following docs commit). Same for `STATUS.md` — the "Up next" list does not get to lag the actual state of `main` by weeks.
+   - **Execute side:** before starting execution of a plan whose checkboxes are all unchecked, spot-check git log (`git log --oneline --all --grep <distinctive-name>`) or grep for a distinctive symbol/file the plan would create. A plan whose work already merged is the worst kind of plan to re-execute. The 2026-05-30 status-audit found Phase 2B, v0.5.1 Streams A/B/C, and 1C-γ all stealth-shipped two-to-three weeks earlier because nobody ran this check.

docs/superpowers/plans/2026-05-30-doc-structure-redesign.md

@@ -1,6 +1,6 @@
 # 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.
+> **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 (`- [x]`) 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.
 
@@ -42,13 +42,13 @@
 - Rename: `docs/ARCHITECTURE.md` → `docs/CRYPTO.md`
 - Rename: `FORMATS.md` → `docs/FORMATS.md`
 
-- [ ] **Step 1: Confirm clean working tree (or only known dirt)**
+- [x] **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**
+- [x] **Step 2: Perform the three renames**
 
 Run:
 ```bash
@@ -59,7 +59,7 @@ 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**
+- [x] **Step 3: Verify renames are tracked as renames, not delete+add**
 
 Run: `git status --short`
 
@@ -72,7 +72,7 @@ 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**
+- [x] **Step 4: Commit the renames**
 
 Run:
 ```bash
@@ -93,7 +93,7 @@ EOF
 
 Expected: one commit created. Verify with `git log --oneline -1`.
 
-- [ ] **Step 5: Verify history follows the rename**
+- [x] **Step 5: Verify history follows the rename**
 
 Run: `git log --follow --oneline DESIGN.md | head -5`
 
@@ -115,7 +115,7 @@ Expected: shows the rename commit on top, then commits to the old `ARCHITECTURE.
 
 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`**
+- [x] **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.
 
@@ -132,7 +132,7 @@ Read `README.md` and find the existing H1 (`# Relicario` near top). Insert the s
 **Next:** [DESIGN.md](DESIGN.md) — the system tour.
 ```
 
-- [ ] **Step 2: Trim README's mid-section "Architecture" stub to a one-paragraph pointer**
+- [x] **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:
 
@@ -148,7 +148,7 @@ Do NOT touch the `### Crypto primitives` table or the `### Encrypted file format
 
 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`**
+- [x] **Step 3: Add scope header + footer to `DESIGN.md`**
 
 Read `DESIGN.md`. Insert this header after its H1 (currently `# Architecture overview — Relicario`):
 
@@ -164,7 +164,7 @@ Append footer at end of file:
 **Next:** [docs/CRYPTO.md](docs/CRYPTO.md) — the crypto pipeline that backs this design.
 ```
 
-- [ ] **Step 4: Add scope header + footer to `docs/CRYPTO.md`**
+- [x] **Step 4: Add scope header + footer to `docs/CRYPTO.md`**
 
 Read `docs/CRYPTO.md`. Insert this header after its H1 (currently `# Relicario — Architecture`):
 
@@ -182,7 +182,7 @@ Append footer at end of file:
 **Next:** [FORMATS.md](FORMATS.md) — the byte-level wire formats.
 ```
 
-- [ ] **Step 5: Add scope header + footer to `docs/FORMATS.md`**
+- [x] **Step 5: Add scope header + footer to `docs/FORMATS.md`**
 
 Read `docs/FORMATS.md`. Insert this header after its H1 (currently `# Relicario Wire Formats`):
 
@@ -200,7 +200,7 @@ Append footer at end of file:
 **Next:** [SECURITY.md](SECURITY.md) — the threat model.
 ```
 
-- [ ] **Step 6: Add scope header + footer to `docs/SECURITY.md`**
+- [x] **Step 6: Add scope header + footer to `docs/SECURITY.md`**
 
 Read `docs/SECURITY.md`. Insert this header after its H1 (currently `# Relicario Security Model`):
 
@@ -216,7 +216,7 @@ Append footer at end of file:
 **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`**
+- [x] **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`):
 
@@ -232,7 +232,7 @@ Append footer at end of file:
 **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`**
+- [x] **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`):
 
@@ -248,7 +248,7 @@ Append footer at end of file:
 **Next:** [../../extension/ARCHITECTURE.md](../../extension/ARCHITECTURE.md) — the browser-side surface.
 ```
 
-- [ ] **Step 9: Add scope header + footer to `extension/ARCHITECTURE.md`**
+- [x] **Step 9: Add scope header + footer to `extension/ARCHITECTURE.md`**
 
 Read `extension/ARCHITECTURE.md`. Insert this header after its H1 (currently `# Architecture: relicario extension`):
 
@@ -264,7 +264,7 @@ Append footer at end of file:
 **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**
+- [x] **Step 10: Verify all eight headers are present**
 
 Run:
 ```bash
@@ -273,7 +273,7 @@ grep -l '^> \*\*Audience:\*\*' README.md DESIGN.md docs/CRYPTO.md docs/FORMATS.m
 
 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**
+- [x] **Step 11: Verify all "Next:" footers are present**
 
 Run:
 ```bash
@@ -282,7 +282,7 @@ grep -l -E '^\*\*(Next|End of tour)' README.md DESIGN.md docs/CRYPTO.md docs/FOR
 
 Expected: all eight filenames echoed back.
 
-- [ ] **Step 12: Verify README architecture section is trimmed**
+- [x] **Step 12: Verify README architecture section is trimmed**
 
 Run: `grep -n 'docs/architecture/' README.md`
 
@@ -290,7 +290,7 @@ 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**
+- [x] **Step 13: Commit**
 
 Run:
 ```bash
@@ -324,7 +324,7 @@ EOF
 
 **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**
+- [x] **Step 1: Find every reference to old paths in markdown files**
 
 Run:
 ```bash
@@ -348,7 +348,7 @@ Expected: a list of callsites that need updating. Will definitely include `CLAUD
 
 **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/<something>/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**
+- [x] **Step 2: For each callsite in the grep output, apply the rewrite rule**
 
 Rewrite rules:
 - `ARCHITECTURE.md` (top-level reference) → `DESIGN.md`
@@ -361,7 +361,7 @@ Inside `CLAUDE.md` specifically, **also** the "Living docs — update discipline
 
 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**
+- [x] **Step 3: Verify zero old-path references remain**
 
 Re-run the grep from Step 1.
 
@@ -369,7 +369,7 @@ Expected: zero matches (modulo the explicitly-excluded test-runs/, audits/, the
 
 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)**
+- [x] **Step 4: Verify links resolve (no broken paths)**
 
 For every modified link, confirm the target file exists. Quick spot-check:
 ```bash
@@ -378,7 +378,7 @@ ls -1 DESIGN.md docs/CRYPTO.md docs/FORMATS.md docs/SECURITY.md crates/relicario
 
 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**
+- [x] **Step 5: Commit**
 
 Run:
 ```bash
@@ -408,13 +408,13 @@ EOF
 **Files:**
 - Modify: `CLAUDE.md`
 
-- [ ] **Step 1: Read the current `CLAUDE.md` living-docs section**
+- [x] **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**
+- [x] **Step 2: Update the table to use new filenames**
 
 In the table, apply these row-label rewrites:
 
@@ -426,11 +426,11 @@ In the table, apply these row-label rewrites:
 
 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**
+- [x] **Step 3: Update the "Planning & design specs" core-references list**
 
 If the bullet list above the table references `docs/superpowers/specs/<file>.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**
+- [x] **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:
 
@@ -446,7 +446,7 @@ Three rules to prevent the kind of drift the 2026-05-30 audit found:
 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**
+- [x] **Step 5: Verify `CLAUDE.md` changes**
 
 Run:
 ```bash
@@ -468,7 +468,7 @@ grep -nE '`ARCHITECTURE\.md`|`docs/ARCHITECTURE\.md`|`FORMATS\.md`' CLAUDE.md |
 
 Expected: zero matches.
 
-- [ ] **Step 6: Commit**
+- [x] **Step 6: Commit**
 
 Run:
 ```bash
@@ -500,7 +500,7 @@ EOF
 
 **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**
+- [x] **Step 1: Scope-header presence check**
 
 Run:
 ```bash
@@ -515,7 +515,7 @@ 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**
+- [x] **Step 2: "Next:" footer chain check**
 
 Run:
 ```bash
@@ -535,7 +535,7 @@ fi
 
 Expected: eight `OK` lines, zero `FAIL`.
 
-- [ ] **Step 3: No old paths remain in living docs**
+- [x] **Step 3: No old paths remain in living docs**
 
 Run the same grep from Task 3 Step 3:
 ```bash
@@ -554,7 +554,7 @@ grep -rn --include='*.md' \
 
 Expected: zero matches (modulo the excluded paths).
 
-- [ ] **Step 4: Renames are git-tracked**
+- [x] **Step 4: Renames are git-tracked**
 
 Run:
 ```bash
@@ -565,7 +565,7 @@ 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**
+- [x] **Step 5: CLAUDE.md table is current**
 
 Run:
 ```bash
@@ -581,7 +581,7 @@ grep -n '### Discipline rules' CLAUDE.md
 
 Expected: one match.
 
-- [ ] **Step 6: README architecture-section trim verification**
+- [x] **Step 6: README architecture-section trim verification**
 
 Run:
 ```bash
@@ -590,7 +590,7 @@ 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**
+- [x] **Step 7: Push**
 
 Once all six checks above pass, push all five commits:
 
@@ -600,7 +600,7 @@ git push
 
 Expected: push succeeds. Working tree is clean (modulo the pre-existing dirt on `.claude/settings.json` etc.).
 
-- [ ] **Step 8: Final summary**
+- [x] **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.