Audit: demo deck vs what is built vs what is tested — all gaps

[ivanmkc]

Audit of the demo deck (docs/lifeboard/deck.html) against what is actually built in packages/lifeboard, and against what is actually tested. One issue, everything in it, checkboxes so it can be worked through.

How I checked

Reproducible, not impressionistic:

• Deck claims — every <h1>/<h2> in the deck: 44 pages, ~30 distinct journeys.
• Built — the routes views/focused.ts resolves, the rail items, the bundled packs, the declared capabilities and collections.
• Reachable — a script that finds every export in src/ that no other src/ file references, cross-referenced against the test files. Anything tests exercise but the app never calls is machinery with no way in.
• Tested — unit/integration suites per module, the 24 assertions in e2e/offline.e2e.mjs, and what .github/workflows/ci.yml actually enforces.

Severity summary

	Finding	Severity
1	The guides describe features the app does not have	High — docs assert things that are false
2	Six capabilities are built and unit-tested but have no runtime caller	High — including the deck's headline lifecycle claim
3	The lifeboard e2e is not in CI	Medium — the offline guarantee is unenforced
4	~13 deck journeys have no pack, no prompt guidance and no test	Medium — they render, but not as the deck shows
5	The prompt names the rich components but never says when to use them	Medium

---

1. The guides claim things the app does not do

The worst category, because someone reading the docs would believe them.

• You cannot add a family member. createProfile has zero callers outside tests. The app auto-creates one profile ("You") and there is no screen to add another. The user guide has a whole Family members section, and the QA guide's section C ("Create a second profile") cannot be performed.
• The PIN is never enforced. checkPin has zero callers. docs/lifeboard/user-guide.md says "A profile can have a PIN… a speed bump to stop a sibling poking around" — nothing checks it, and profile switching is unguarded. Either enforce it or delete the claim.
• There is no contact book. addContact / listContacts have zero callers, though contact is a collection the model may write. The outbound flow tells the model "never invent an address — use one you were given", and there is nowhere for one to have been given.
• A sender can never actually be promoted to auto. triageMessages computes promotions, but nothing renders them and setSenderRung has zero callers. The trust ladder's top rung is unreachable, so the "after three accepts" behaviour described in the user guide and QA F10 cannot happen.

2. Built, unit-tested, and unreachable

Same class as the four gaps closed in #320–#323 — this is what the orphan scan found that I had not already documented.

• Live-bound boards never refresh, and never render. probeSource, fetchSource and refreshBoard have zero callers (7 tests cover them). No route renders a pack's bound board, nothing drives a refresh policy, and probeSource is not called at authoring time even though the Packs screen is where it belongs. This is the deck's headline lifecycle claim — "boards that need no model after they are created", the When's the next bus journey — and it is not reachable.
• Source staleness is never detected. sourceChanged / flagStale have zero callers. The deck's provenance journey and the roadmap gate both say "alter the source file and see the fact flagged as stale". Nothing watches.
• cartUrls (one link per item, "which is what actually gets a basket filled") is unused; only the single combined-search cartUrl is wired.

3. Test and CI gaps

• The lifeboard e2e does not run in CI. ci.yml runs npm test and the viewer's e2e, not test:e2e --workspace @ivanmkc/termchart-lifeboard. The offline guarantee — the app's headline claim, and the thing that caught the sequence-collision and stale-build bugs — is verified only when someone runs it by hand.
• Ten routes have no e2e coverage. Covered: Today, Shopping, Practice, Activity, Packs, Connections. Not covered: Home (grid), Week, Inbox, Meals, Work, Sources, lineage:, recipe:, board:, job:.
• No test asserts the guides are true. The gaps in section 1 would all have been caught by a test that walks the QA guide's own steps. Worth one test that fails when a documented affordance has no caller.

4. Deck journeys with no specific support

Roughly 14 of ~30 journeys have dedicated support (Today, shopping, dinners/recipes, practice, mail triage, provenance, agent inbox, activity, history/undo, packs library, describe-a-board, Connections, the Portugal research job, plus the flights/trips/restock packs).

The rest would render only as a generic agent-drawn board: no pack, no prompt guidance, no test, so what you get is unpredictable and not what the deck shows.

• House card · babysitter card · sick day · clubs and kit · chores and pocket money · growing up · birthday party · half-term cover · Nan's hospital letter · cook mode · building the bookshelf · Saturday map · dishwasher carousel · recurring spend · the boiler · gift capture · Marketplace selling · returns and QR codes · financial planning · summer camp · reading log
• Not reachable at all: bus times (needs §2), dashboard editing ("Your dashboard, your way" / "Today · editing" — there is no editing anywhere), kid mode as a mode.

Not all of these deserve a pack. The decision to make, per journey: ship a pack, add prompt guidance, or remove the page from the deck. Leaving a deck page with nothing behind it is the thing to avoid.

5. The prompt names components it never explains

systemPrompt interpolates the full KNOWN_COMPONENTS list, so Map, ImageCarousel, Video, Timeline, Masonry, TileGrid and VegaLite are available. The prose guidance only covers BoardHeader, Card, SimpleGrid, Checklist, Table and Image.

• Several deck journeys depend on the unexplained ones — the Saturday map, the dishwasher carousel, cook mode's video, recurring spend's chart. Naming a component in a list is not teaching a model when to reach for it.

Suggested order

1. Section 1 — either build them or correct the documentation. A false claim in a user guide is worse than a missing feature.
2. Section 3's CI line — one line of YAML, and it protects everything else.
3. Live-bound boards (§2) — the machinery is written and tested; it needs a route, a refresh tick, and a probeSource call in the authoring flow.
4. Prompt guidance (§5) — cheap, and it lifts every journey in §4 at once.
5. §4 journeys — one at a time, each as a pack, or struck from the deck.

Audit performed on lifeboard/18-activity (the tip of the PR stack: #311 → #323 plus the five unpushed branches). The orphan-scan script is in the audit method above and can be re-run against any branch.

[ivanmkc]

One item to add here, from the review pass in #330.

A restore is not recorded anywhere. Store.restore used to take a by and drop it on the floor, so the API promised an attribution the Activity screen could never show. #330 removes the parameter rather than fake it — but the underlying gap is real and belongs on this list:

• Nothing records who restored a backup, or when. It is the most destructive action in the app (it replaces the entire log, with no undo), and afterwards there is no trace that it happened. The restored log is someone else's history, so there is nowhere honest to put the record without a place in the schema for an event about the log rather than about a record in it. Relates to S7 (no schema version on entries) in docs/lifeboard/persistence-audit.md — both want the same thing: a system-event lane the fold ignores but Activity can read.

The other three defects found in that pass — the bridge refusing the app's own serve origin, a restore swallowing an in-flight write, and packs defaulting to allow-all writes — are fixed in #330 rather than tracked here.