docs: make the specs stop lying, and number three invisible items - #30
Merged
Conversation
A survey of the tree against the docs found that this repo's debt lives almost entirely in prose. There is not one `TODO`, `FIXME`, `unimplemented!` or `todo!()` in `crates/` — but several documents contradict each other or the code, and one of them misled this session into repeating "nothing is laptop-buildable any more", which was false. **Documents that disagreed with the code** - `docs/README.md` — read-order item 0 — still called this "the blueprint and the seed" with crates "seeded with the core types and traits". The root README correctly says specification *and* implementation. Newcomers open the wrong one first. - `docs/23` Phase 1 counted "event store **PG**" as delivered. The implementors of `EventStore` are `MemoryStore`, `JsonlStore` and `SqliteStore`, and `panday-harnessd` holds an `Arc<MemoryStore>`. The PG `session_events` table is M18.6's sync *sink*. M3.3's WS resume is real; the PG backing never existed. - `docs/25`'s testing contract stated "Σ tokens per `credential_id` == Σ usage frames that named it" as an enforced property. `UsageRecord` has no `credential_id`, so it ranges over nothing. Marked pending that field. - `docs/16` put the marketplace in phase 4; `docs/23` and `docs/GOAL.md` put it in phase 6. Someone finishing phase 4 would think they owed a storefront. **"Postgres is M3.5" — a wrong pointer in seven places** M3.5 is ledger-rebuild-from-log; the PG lane was M2.3. Both are ✅, so a reader chasing the pointer concluded the work had shipped. Four were in docs, three more in code comments the first sweep missed. Two were doubly stale: `docs/20` and `tenancy.rs` both said "there is no SQL to lint yet" when the lint now walks 49 `sqlx::query` sites and 8 migrations — underselling the milestone rather than overselling it. **Three items given numbers** The count goes 104 → 107 and **no work was added**. These already existed and were invisible to anyone reading the milestone list: - **M0.2** was being *cited* in `docs/23` as though defined, with a table of Phase 2 exit clauses under it, but no bullet existed — so the tracker was uncountable and unmarkable. Exactly what CLAUDE.md §4 warns about, hiding behind a number that looked real. - **M11.10** PG-backed exact cache — specified since docs/11 was written, never owned. - **M14.8** egress proxy — without it, a plugin's `net: [host]` declaration is an all-or-nothing switch rather than an allowlist. Safe today under `--unshare-net`, but the manifest field reads like a promise. **Process rules from this session's failures** (handover §1.2) Check `gh` with `gh api user -q .login`, not by parsing `gh auth status` — the active account drifts to `hexuria`, which cannot write here, and status-parsing gave the wrong answer twice. `cfg`-gated code cannot be verified locally (`ring` needs a C cross-toolchain), so plan a CI round trip. The integration lane is not in the local gate. Never `pkill -f "cargo test"` — it reaches other repos. Claude-Session: https://claude.ai/code/session_017kFpYDqvz6sKGSkM4YKaRf
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.
Phase 1 of the approved plan. A survey of the tree against the docs found that this repo's debt lives almost entirely in prose — there is not one
TODO,FIXME,unimplemented!ortodo!()incrates/— but several documents contradict each other or the code.One of them misled this session into repeating "nothing is laptop-buildable any more", which was false.
Documents that disagreed with the code
docs/README.md(read-order item 0)docs/23Phase 1 contentsEventStoreexists — implementors are Memory/Jsonl/Sqlite,panday-harnessdholds anArc<MemoryStore>, andsession_eventsis M18.6's sync sinkdocs/25testing contractcredential_idconservation property as enforcedUsageRecordhas no such field; marked pendingdocs/16docs/23andGOAL.md"Postgres is M3.5" — wrong in seven places
M3.5 is ledger-rebuild-from-log; the PG lane was M2.3. Both are ✅, so a reader chasing the pointer concluded the work had shipped. Four were in docs; grepping after fixing those turned up three more in code comments.
Two were doubly stale:
docs/20andtenancy.rsboth claimed "there is no SQL to lint yet" when the lint now walks 49sqlx::querysites and 8 migrations — underselling the milestone rather than overselling it.Three items given numbers: 104 → 107, and no work was added
These already existed and were invisible to anyone reading the milestone list:
docs/23, with a table of Phase 2 exit clauses under it, but no bullet ever existed — the tracker was uncountable and unmarkable. Exactly the failure CLAUDE.md §4 warns about, hiding behind a number that looked real.net: [host]is an all-or-nothing switch, not an allowlist. Safe today under--unshare-net, but the manifest field reads like a promise.Both count lines now explain the increase, so it doesn't read as scope creep.
Process rules from this session's failures (handover §1.2)
ghwithgh api user -q .login, not by parsinggh auth status— the active account drifts tohexuria, which cannot write here, and status-parsing gave the wrong answer twice.cfg-gated code cannot be verified locally (ringneeds a C cross-toolchain); plan a CI round trip.pkill -f "cargo test"— it is not scoped to this repo.Local gate
fmt✅ ·clippy --workspace --all-targets -D warnings✅ ·panday-gateway✅ ·panday-sdk✅ (four crates had doc comments edited).mdbookisn't installed here, so thedocsCI job is the authority on the book building.https://claude.ai/code/session_017kFpYDqvz6sKGSkM4YKaRf