Skip to content

docs: de-rot agent-facing docs — archive CLAUDE.md phase log, fix P30-stale entry docs - #45

Merged
tonibergholm merged 1 commit into
mainfrom
docs/cleanup-context-rot
Jul 11, 2026
Merged

tonibergholm merged 1 commit into
mainfrom
docs/cleanup-context-rot

Conversation

@tonibergholm

Copy link
Copy Markdown
Member

Why

A doc audit (all 130 markdown files, 49k lines) found the agent-entry docs both stale and structurally expensive:

  • AGENTS.md was a byte-identical fork of P30-era CLAUDE.md and drifted stale within two days — it was still teaching a dependency rule without crates/tlsio, no rustls quarantine, "no TLS", and P29's "tokens justify a non-loopback bind" (deliberately narrowed by P32).
  • README.md's security-warning box claimed sc serve --http is plaintext (no TLS) — false since P32, contradicting the THREAT-MODEL doc the same sentence links to. Also "30 shipped phases" (it's 33) and convergent-encryption wording that P33 obsoleted.
  • ARCHITECTURE.md ended at Phase 30 — P33 edits were woven into the crypto sections but P31/P32/P33 phase sections were missing, and the P26 boundary line still read "no TLS".
  • CLAUDE.md was 1,565 lines, ~75% completed-phase changelog duplicating ADRs 0015–0043 nearly verbatim, loaded into every agent session — with superseded facts arrow-patched ("(→ P33: no longer unconditionally true…)") instead of rewritten.

What

  • CLAUDE.md 1,565 → 524 lines: phase narratives replaced by a per-phase capability map (one current-fact line + ADR link each) and a "Standing boundaries & gotchas" section; all arrow-patched facts rewritten as current statements; follow-ons now point at ROADMAP.md's Deferred section instead of duplicating it. The full narrative log is archived verbatim (diff-verified) at docs/archive/claude-md-phase-log-2026-07.md.
  • AGENTS.md → a short pointer to CLAUDE.md (it had zero unique content — verified byte-identical to CLAUDE.md@7a8d6ef modulo the title), so it cannot drift again.
  • README.md → 33 phases, corrected security warning (TOFU-first-connection + pre-P33 convergent-history caveats instead of "no TLS"), tlsio in layout + dependency rule, demo count 22 → 25, Status/deferred examples matching ROADMAP.
  • ARCHITECTURE.md → adds Phase 31/32/33 sections (condensed from ADRs 0041–0043); P26 boundary line notes TLS closed by P32.
  • CONTRIBUTING.md → dependency rule gains tlsio + rustls quarantine; AGENTS.md described as a pointer.
  • docs/agents/domain.md → repoints the domain-vocabulary source at the capability map + ADRs; seven crates; 43+ ADRs.
  • docs/superpowers/README.md (new) → banners the ~25k lines of executed specs/plans as historical pre-build artifacts (code + ADRs win).

Verification

  • Archive extraction is byte-verbatim (diff against the source line range).
  • Every relative link in touched files resolves, including all 33 ADR links in the new capability map.
  • Docs-only: git status shows only the intended markdown files; no code changes.

https://claude.ai/code/session_01LhadyW9scQL95h3ag9yySB

…-stale entry docs

Diagnosed context rot hurting agent sessions and fixed it:

- CLAUDE.md 1565 -> 524 lines: the 26 "Phase N is built" narratives
  (duplicating ADRs 0015-0043) are replaced by a per-phase capability map
  + a "Standing boundaries & gotchas" section with every superseded-fact
  arrow-patch (P11/P17 rewrap + rotation notes, P26 TLS note) rewritten
  as current facts. Full narrative log archived VERBATIM at
  docs/archive/claude-md-phase-log-2026-07.md. "Remaining follow-ons"
  now points at ROADMAP.md Deferred instead of duplicating it.
- AGENTS.md: was a byte-identical fork of P30-era CLAUDE.md (missing
  crates/tlsio + its quarantine rule, P31 listener limits, P32 TLS, P33
  randomized sealing; still claimed "tokens justify a non-loopback
  bind"). Now a pointer to CLAUDE.md so it cannot drift again.
- README.md: 30 -> 33 phases; security-warning box no longer claims
  "sc serve --http is plaintext (no TLS)" (false since P32); pillar 3 no
  longer says protected paths use convergent encryption (randomized
  since P33); workspace layout + dependency rule gain tlsio; demo count
  22 -> 25; Status deferred examples match ROADMAP.
- ARCHITECTURE.md: adds the missing Phase 31/32/33 sections; P26
  boundary line now notes TLS was closed by P32.
- CONTRIBUTING.md: dependency rule gains tlsio + rustls quarantine;
  AGENTS.md described as a pointer, not a byte-identical copy.
- docs/agents/domain.md: AGENTS.md/parallel-copy claim, six->seven
  crates, 37+->43+ ADRs, repoints the vocabulary source at the
  capability map + ADRs.
- docs/superpowers/README.md (new): banners specs/ and plans/ as
  historical pre-build process artifacts — code + ADRs win.

Claude-Session: https://claude.ai/code/session_01LhadyW9scQL95h3ag9yySB
@tonibergholm
tonibergholm merged commit 12c1d1b into main Jul 11, 2026
5 checks passed
@tonibergholm
tonibergholm deleted the docs/cleanup-context-rot branch July 11, 2026 07:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant