Repository navigation
docs: de-rot agent-facing docs — archive CLAUDE.md phase log, fix P30-stale entry docs - #45
Merged
Merged
Conversation
…-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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
A doc audit (all 130 markdown files, 49k lines) found the agent-entry docs both stale and structurally expensive:
crates/tlsio, no rustls quarantine, "no TLS", and P29's "tokens justify a non-loopback bind" (deliberately narrowed by P32).sc serve --httpis 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.What
docs/archive/claude-md-phase-log-2026-07.md.CLAUDE.md@7a8d6efmodulo the title), so it cannot drift again.tlsioin layout + dependency rule, demo count 22 → 25, Status/deferred examples matching ROADMAP.tlsio+ rustls quarantine; AGENTS.md described as a pointer.Verification
diffagainst the source line range).git statusshows only the intended markdown files; no code changes.https://claude.ai/code/session_01LhadyW9scQL95h3ag9yySB