Skip to content

docs: make the specs stop lying, and number three invisible items - #30

Merged
codeitlikemiley merged 1 commit into
mainfrom
docs-truth-pass
Aug 22, 2026
Merged

docs: make the specs stop lying, and number three invisible items#30
codeitlikemiley merged 1 commit into
mainfrom
docs-truth-pass

Conversation

@codeitlikemiley

Copy link
Copy Markdown
Owner

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! or todo!() in crates/ — 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

was now
docs/README.md (read-order item 0) "the blueprint and the seed", crates "seeded with core types and traits" matches the root README: specification and implementation
docs/23 Phase 1 contents counts "event store PG" as delivered no PG EventStore exists — implementors are Memory/Jsonl/Sqlite, panday-harnessd holds an Arc<MemoryStore>, and session_events is M18.6's sync sink
docs/25 testing contract states a credential_id conservation property as enforced UsageRecord has no such field; marked pending
docs/16 marketplace in phase 4 phase 6, matching docs/23 and GOAL.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/20 and tenancy.rs both claimed "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: 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, 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.
  • M11.10 PG-backed exact cache — specified since docs/11 was written, owned by nobody.
  • M14.8 egress proxy — without it a plugin's 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)

  • 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); plan a CI round trip.
  • The integration lane is not in the local gate.
  • Never 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). mdbook isn't installed here, so the docs CI job is the authority on the book building.

https://claude.ai/code/session_017kFpYDqvz6sKGSkM4YKaRf

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
@codeitlikemiley
codeitlikemiley merged commit 7dd4616 into main Aug 22, 2026
6 checks passed
@codeitlikemiley
codeitlikemiley deleted the docs-truth-pass branch August 22, 2026 22:27
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