docs: current audit, forward plan, and a corrected skins contract

[superwilso]

What this changes

Adds docs/PLAN_2026-09-14.md — a current audit of the tree at v0.3.4 with every offline gate re-run rather than quoted, an ordered forward plan, and a revised contract for the skins design system. Banners CLAUDE.md, which was seven weeks stale, and cross-links the revision from PLAN_skins.md and docs/README.md. Documentation only; no code changes.

Why

Three findings drove it.

CLAUDE.md is the most expensive stale file in the repository, because it is loaded into every session automatically — it is the first thing any new reader believes. Its banner claimed the last code change was 2026-07-03, that host tests were "39 UI + 8 DB", and that the entire critical path was blocked on one device session. Measured today: 549 Rust tests, v0.3.4 shipped, USB-DAC→LDAC executed. This is the identical failure already caught for ROADMAP.md in AUDIT_2026-09-01 §D2 — "a roadmap that is five weeks stale is worse than no roadmap, because unlike a dated audit it is supposed to be current" — and it gets the identical fix: a banner, with the old text kept verbatim below it as history.

SHORTCOMINGS.md §A1 now overstates the gap in the project's favour. Its "41% of the tree is never compiled by any automated gate" predates CI gaining the syntax check, nine self-tests, the harness, shellcheck and the launcher matrix. Since §A1 is cited by ID from other documents, leaving it overstated devalues the citations. The honest residual claim is narrower and is stated in the new §A1: nothing in CI links or executes an ARM build — host_syntax_check.sh is -fsyntax-only, so a change that parses but does not link, or that raises the glibc-2.23 floor, reaches a tag before anything notices.

PLAN_skins.md's step-2 contract would break 224 tests on contact. It specifies the hit map as populated while drawing (ui.hit(rect, Hit::Play) inside render). Measured on 7860396: of the 229 coordinate-driven interactions in nav.rs's tests, exactly 5 call render() first. The other 224 construct an App and tap it without ever painting, so they would look up taps in an empty hit map — and the headless suite is the thing that makes refactoring a 13,267-line App survivable.

The problem is not the tests; it is what they reveal. Paint-time registration means a tap before the first paint has no defined answer, a tap after a state change is tested against the previous frame's geometry, and a control under a clip silently stops being tappable. Part C keeps the actual goal — render and hit-test cannot disagree — and changes the mechanism to a pure layout(&View) -> LayoutMap that both render and tap call. render_bench on this tree puts layout at 2.3% of the frame it belongs to (up_next::layout 5.8 µs vs render_view 249 µs; a blank canvas fill alone is 42.6 µs), so resolving it on demand costs nothing measurable. It also makes the contract tests cheaper, since "every region ≥ 44 px, none overlapping" becomes an assertion on a LayoutMap rather than on a rendered frame.

Skins-only is recorded as the owner's decision; layouts-as-data stays out of scope, as PLAN_skins.md recommended.

Blast radius

• UI / drawing only (player/cinder-ui) — cannot brick anything
• Library / database (player/cinder-db)
• Installer or host tooling
• Docs only

---

• Runs as root (setuid helper, cinder-home/src/cinder-*.c)
• Boot path (launcher, crash supervisor, bad-boot counter, escape ladder)
• Sony IPC (cinder-audio/, hand-recovered vtable offsets — a wrong argument shape reboots the device)
• USB-MSC mount ordering (an ordering mistake corrupts the user's music volume)

Checks

All run on this branch. Every number quoted in the new document came from these runs, not from a previous audit.

• tools/host_syntax_check.sh — 23 files, all parse
• tools/shell_check.sh — all clear, but shellcheck was not installed in this environment, so only bash -n ran; CI's pinned shellcheck-py==0.11.0.1 is the real gate
• cinder-home/harness/run.sh — 41 scenarios passed
• bash cinder-home/tools/test_launcher.sh — 63 passed, 0 failed
• (cd player && cargo test --release) — 549 passed, 0 failed
• (cd installer && cargo test --release) — 47 passed, 0 failed
• cargo run -p cinder-host -- --check — 234 golden hashes, every preview matches

Device verification

• Tested on hardware — model and firmware:
• Not tested on hardware, and the change cannot reach the device
• Not tested on hardware, and it can — say so plainly here so it is not merged as if it were

Documentation only — nothing in this diff is compiled into a device binary.

---

One thing this document flags that is worth reading before anything else

installer/src/stage.rs's Windows SCSI pass-through path is compiled but, per STATUS.md (2026-09-12), has never been executed on Windows — and since Sony's updater was removed it is the only way a Windows user can install. It is live in v0.3.4 with 2 Windows downloads so far. DEVICE_CHECKLIST.md 11.9 already describes the test; it is re-opened and unrun. The window to test it before an audience arrives is open and small.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LqjAR2jJm1LzBYUNMqPAhg

---

Generated by Claude Code