# THE MUSEUM — master plan **Rewritten 2026-07-20.** Supersedes the previous master plan of the same name and the scope in `MUSEUM_EXHIBITS_DESIGN.md`, which remains the record of how the first round of external reviews was adjudicated. Where any of the three disagree, **this file wins**. --- ## WHY THIS WAS REWRITTEN The previous plan was reviewed by Gemini and GPT, blind to each other. They reached the same verdict by different routes. > **Gemini:** *"You tore down the terminal to build a classroom, but you accidentally built a > chronological museum instead."* > > **GPT:** *"Still primarily an archive organized by artifact type, with an orientation page placed > in front. A newcomer would still have to reconstruct the method themselves."* The old plan organised itself around **artifact classes** (sessions, reviews, mockups, memory) with **releases as the spine**. That is an archive's filing system with a teaching page bolted to the front. A visitor who wants to learn how this was built would still have to do the synthesis themselves — which is the entire job the museum exists to do for them. **The fix, adopted:** organise the teaching layer around **cases and methodology**. Preserve everything; teach selectively. The archive does not shrink — it stops being the spine and becomes the **citation layer** the teaching chapters point at. This document is split into four parts so the three concerns stay separable: | Part | What it covers | | --- | --- | | **I — The teaching layer** | The spine. What a visitor reads, in order, and how it stays true. | | **II — The evidence layer** | The archive. Everything preserved, and how the teaching layer cites it. | | **III — Publication mechanics** | How it goes public without leaking, breaking or lying. | | **IV — Process** | Reviews, sequencing, rejected ideas. | --- # PART I — THE TEACHING LAYER --- ## 1. THE CLAIM — narrowed, and it governs everything The owner's ask was *"showcase the use of AI to create RobCo the best way I possibly can"* and *"a full project history so people can learn the AI usage themselves."* **It cannot teach "the best way to use AI."** The project is weeks old, has two users, and has no comparative evidence — no control group, no alternative method tried side by side, no outcome measured against a baseline. A museum claiming general best practice would be making exactly the "authoritative and quietly wrong" claim this whole system exists to avoid. **⭐ THE CLAIM, STATED AT THE TOP OF THE LOBBY AND BINDING ON EVERY PAGE:** > This is a record of how **one solo owner** used AI to build **this specific project**, under > **these constraints**, with **evidence of what worked and what failed**. Everything downstream inherits that scope. Where a chapter is tempted to generalise, it must either move the claim into the **transfer layer** (§7) and label it as such, or drop it. --- ## 2. THE LEARNER, THE OUTCOMES, AND THE COST A teaching artifact without a defined learner teaches nobody. Stated on the way in: **Who this is for.** Someone who can already use a code editor and git, is working alone or nearly alone, and wants to use AI models to build something larger than they could hold in their head. Not a beginner's programming course; not an enterprise-team process guide. **What they should be able to do afterwards** (the outcomes the museum is judged against): 1. Explain why an orchestrator that never writes code is a different role from a coding assistant. 2. Write an authority contract for their own project — what an agent may do unasked, what "done" means, when it must stop. 3. Set up isolation and a gate so that speed does not translate into breakage. 4. Read a review critically instead of adopting it, and adjudicate two reviews that disagree. 5. Recognise the failure mode this project keeps hitting: something that looks authoritative, passes its checks, and is silently doing nothing. **Prerequisites and costs, stated plainly.** What hardware this ran on (a ROG Ally — modest, and the reason a local model was rejected on measured evidence), roughly what the model usage cost, and how much time the owner actually spent. A method whose costs are hidden is not reproducible, and a reader who discovers the cost after investing a weekend has been misled by omission. **The minimal starter kit.** The smallest version someone could adopt on day one — not the full apparatus. This project has ~50 protocols, a nine-file rulebook and a multi-suite gate; presenting that as the entry point is a wall, and it also misrepresents history, because none of it existed at the start. The kit is: one authority contract, one isolation mechanism, one gate that must pass. Everything else is shown as what it is — accretion in response to specific failures, each with the failure on file. **⭐ NOVICE COMPREHENSION TEST — before scaling the build.** Fable, GPT and Dispatch all know this project too well to judge whether the entry path teaches anything. Before building out chapters beyond the first vertical slice, put the lobby and one full chapter in front of someone who has never seen the project, and ask them to state in their own words what the project is and how the work was organised. If they cannot, the entry path has failed and no amount of additional rooms fixes it. This is a **gate on the build order**, not a nice-to-have at the end. --- ## 3. THE SPINE — six methodology chapters, in this order The visitor's path. Each chapter is frozen narrative with generated evidence injected (§4), and each one **cites** the archive rather than summarising it (§6, §9). ### Chapter 1 — LOBBY: the concept What the app is. Why offline-first vanilla web technology was chosen — no framework, no build step, no backend — and what that bought and cost. The core constraints that shaped everything: phone-first owner, single developer, a modest machine, and a Fallout terminal the app has to remain believable as. Carries the narrowed claim (§1), the learner definition and the outcomes (§2). ### Chapter 2 — THE ENGINE: Dispatch and the triad The orchestrator that **never writes code**. Why that separation exists and what it produces: an orchestrator that holds the specification and the judgement, and sessions that hold the context of one task. The three-model split by role — design and creative, diagnosis and planning, implementation — and the honest account of where the split helps and where it is overhead. Cites: real task packets, and the sessions that ran them. ### Chapter 3 — THE AUTHORITY CONTRACT **⚠ This chapter was materially redirected. Gemini wanted it to be the shorthand glossary — "go", "yo", "resend", "fold that in". GPT's objection is correct and overrides: those are one person's personal vocabulary and transfer to nobody.** What actually transfers is the **authority contract underneath the vocabulary**: - What the orchestrator may do **without asking** — and why permission-asking was pushed down to near zero for a phone-first owner who cannot read terminal output. - What counts as **done** — and why "the session said it was done" is a claim, not evidence. - **When it must stop** — the irreversible steps, the spec lock, the no-concurrent-push rule. - **How corrections are absorbed** — a correction that changes only the current task versus one that becomes a standing rule, and who decides which. The glossary survives as **illustration inside this chapter, not as its point**: a handful of real short instructions mounted **beside the commits they produced**, so the reader sees a three-word message and the diff it caused. That pairing is the teaching content; the words themselves are trivia. Cites: worked case 2 or 3 (§6), and the short-instruction-to-commit pairs. ### Chapter 4 — THE SAFETY NET: git worktrees and the gate How isolation and testing let the work go fast without the speed turning into breakage. Worktree isolation per session; the gate at the commit and push boundaries; the escape-ratchet principle (every failure that escapes a layer adds a check at that layer) and its counterpart, the retirement rule that stops the ruleset growing forever. ⭐ **This chapter must include the failures of the net itself** — the cache guard that was written, hooked, tested and silently doing nothing for weeks, and the tests that asserted code *said* it escaped dangerous input rather than that it did. A safety-net chapter that only shows the net working is the exact overclaim the project keeps catching in itself. Cites: worked case 3 (§6), the bug museum's red-then-green cases (§12). ### Chapter 5 — THE ARCHIVE: case studies The three complete worked cases (§6) in full, plus the entrance to the evidence layer. **The release rooms live here, demoted from spine to citation** — they are the deep evidence for a reader who says "prove it," not the organising principle of the museum. ### Chapter 6 — THE GRAVEYARD Ruled-out ideas, each showing its **original decision record** rather than a later summary. Kept at the end, deliberately: never start the tour in the basement, and a project is not defined by its failures — but a method that shows only its successes has taught nothing about judgement. --- ## 4. ⭐ FROZEN NARRATIVE, GENERATED EVIDENCE — the key mechanism This is the mechanism that makes the whole teaching layer possible. It resolves the standing conflict between "hand-written content rots" and "generated content cannot teach." **A fully generated spine would be an autopsy.** It can report *what* happened — commits, counts, timings — but not why any of it matters, what the mental model is, or what a reader should take away. Generation cannot produce insight it was not given. **A fully hand-written spine rots.** Every specific number, filename and example in it goes stale, and the museum drifts into confidently describing a project that no longer exists — which this project has already done to itself, in its own documentation, off by a factor of forty. **⇒ THE SPLIT:** > **The narrative is FROZEN PROSE** — it teaches philosophy and mechanisms, the things that do not > change weekly. > > **Every specific noun, metric and example inside it is an INJECTION POINT** the generator fills > from the latest pinned release. So the frame is written once, and the proof is always current. Concretely, a frozen sentence reads: > "The gate runs at both the commit and push boundaries; at `{{RELEASE}}` it ran `{{GATE_SUITES}}` > suites, and the push boundary added `{{PUSH_CHECKS}}`." The teaching claim ("the gate is split at two boundaries and why") is stable. The numbers are measured at the pinned release and can never be stale, because nobody hand-copies them. **Rules on injection points:** - An injection point that cannot be resolved renders **as a visible gap with its name**, never as a blank or a silently dropped clause. A sentence that quietly loses its evidence is worse than one that admits it is missing. - Injection points carry **no AI at build time** — they are extraction and measurement only. A hallucinated summary is worse than none and would break determinism. - If a frozen sentence's *claim* stops being true (not just its numbers), that is a **delta for the release review** (§5), not a silent patch. --- ## 5. ⭐ THE ANTI-ROT ANSWER — the methodology tracks the latest SHIPPED RELEASE **The teaching layer is pinned to the latest release tag, never to `dev`.** This is the structural answer to "the workflow changes constantly, so any written description of it rots." It does not rot, because it is **tied to a static point**: > Change the workflow on a Tuesday and the museum does not care. It remains an accurate guide to how > the **published** version was built. The museum is therefore **current by definition between releases**. That sharpens the NOT CURRENT notice into something meaningful — it fires only when *a release shipped and nobody regenerated* — instead of firing permanently and becoming noise. **The release ritual.** At each release, Dispatch drafts a **delta**: what changed in the workflow since the last release, in plain English. The owner approves it. That delta becomes the new frozen manual, and the previous one is retained as the record of how the previous release was built. **⭐ This turns the methodology into a visible evolution rather than a static "how we work" page.** Read in order across releases, someone watches the rulebook go from one 100 KB file to a contract plus scoped notes; watches the trim begin; watches the audit-from-the-diff rule appear after a false "verified" pass got through. **The changes are where the lessons are.** A single always-current page would hide every one of them. --- ## 6. ⭐ THREE COMPLETE WORKED CASES — the primary citations These are the closest thing the museum has to a thesis. Each traces **one episode end to end**, with every link in the chain present: ``` owner request → what Dispatch inferred and what it delegated → the task packet actually sent → what the session reported [LABEL: session-reported] → the resulting diff [LABEL: measured fact] → the blind reviewer's claims → which were accepted or rejected, and why → gate evidence [LABEL: measured fact] → what shipped → any later correction ``` **Build exactly three, chosen to teach different things:** 1. **A clean success.** The method working as intended, start to finish. Establishes the baseline shape so the other two read as deviations from something. 2. **A review that materially changed the work.** The case for running blind reviews and adjudicating rather than averaging — including the reviewer claims that were *rejected*, which is the harder and more useful half. 3. **A confident AI or process result that repository evidence overturned.** The most important of the three. Something that was asserted, sounded right, passed its checks, and was wrong — caught by looking at the real thing. The cache guard and the silent service-worker failure are the obvious candidates. **Wiring the chapters to the cases** — this is what stops the chapters being abstract: - The blind-review material in Chapter 2 links **into the actual adjudication** in case 2, not to a description of adjudication. - The authority contract in Chapter 3 links **into a real short instruction mounted beside the commit it produced**. - The safety net in Chapter 4 links **into case 3**, where the net failed. **⭐ Release rooms survive by being the citations.** They are not deleted, not diminished in content, and not reorganised. They stop being the path and become the destination — the deep evidence a sceptical reader lands in when they follow a chapter's link and say "prove it." --- ## 7. THE TRANSFER LAYER AND CLAIM LABELS **The transfer layer.** Every chapter separates two different kinds of statement, visibly: | | | | --- | --- | | **WHAT HAPPENED HERE** | The record. Specific to this project, this owner, these constraints. Evidenced. | | **WHAT MAY GENERALISE** | The candidate lesson. Explicitly marked as *untested elsewhere*. | Keeping these unseparated is how a single-project record turns into false best-practice advice. The transfer layer is allowed to be speculative **only because it is labelled as speculative**. **⭐ CLAIM LABELS.** Every substantive claim in the museum carries one of four labels, and the label is part of the page, not a footnote: - **MEASURED FACT** — produced by the generator from the repository. Counts, diffs, timings, hashes. - **PARTICIPANT REPORT** — what a session or the owner said happened. Not independently verified. - **CONTEMPORANEOUS RATIONALE** — a reason recorded at the time the decision was made. - **CURATOR INFERENCE** — Dispatch's or the owner's later interpretation. The weakest class, and the one most likely to be flattering. This is the generalised form of the rule that claims must be literal. It also does the single most important honesty job in the museum: it stops the reader from having to guess which sentences are evidence and which are storytelling. **⭐ SESSION REPORTS ARE SELF-REPORTS.** The old plan treated a session's final report as a ready-made exhibit label — *"no summarisation step: the session already writes its own exhibit label."* That is convenient and it is wrong: a session's account of its own work is a **claim, not evidence**, and it is the exact thing the audit-from-the-diff rule exists to distrust. Session reports are preserved verbatim, labelled **PARTICIPANT REPORT**, and **selected ones are connected to the diff, the audit and the gate result** so the reader can see where the self-report was accurate and where it was not. --- # PART II — THE EVIDENCE LAYER --- ## 8. BASELINE — what exists today, measured **⚠ Measured 2026-07-20 against the built output. The figures in the previous plan and in `MUSEUM_EXHIBITS_DESIGN.md` were taken at different commits and are superseded by these.** | Property | Current measured value | Superseded figures | | --- | --- | --- | | Pages | **272** HTML pages | 264 (old plan) | | `search.html` | **7,133 bytes (7 KB)** | 3.9 MB (design doc, pre-fix) | | Internal `href`s | **3,792** | 4,206 (old plan) · 3,509 (design doc) | | `museum/site/` on disk | **18 MB** | 19 MB | | Full images referenced | **429** | — | **The search-size conflict is resolved:** the 3.9 MB figure is the *pre-fix* state recorded in the design doc; the correctness pass sharded it. **7 KB is current.** The link counts differ because they were counted at three different commits against a growing tree; **3,792 is current** and no count should be hand-copied into another document (that is the retired count-sync tax returning through a side door). Rooms as built: four release rooms (2.5.0, 2.6.0, 2.8.0, 2.8.5) · standing tools · graveyard · search · growth chart · paginated galleries with cached thumbnails. Entry point is **`museum/site/index.html`** (never `museum/index.html` — that path has never existed). Correctness pass already landed: literal integrity claims, `<a href>` navigation, sparse-room notices, draft-banner handling, the search shard, growth chart shipped-vs-in-flight, and a currency guard rendering NOT CURRENT when the newest data point disagrees with the pinned commit. The output self-stamps with an input hash and no wall-clock time, so identical inputs regenerate identically. --- ## 9. THE ARCHIVE ROOMS All preserved. All demoted from spine to citation (§6). - **Release rooms** — 2.5.0, 2.6.0, 2.8.0, 2.8.5. The deep evidence per era. - **Standing tools** — cross-release material, library docs, memory. - **Memory** — current memories, plus their git version history (the "what was believed and then corrected" view), plus deleted memories rendered **as deleted, with their reason**, plus the audit and repair log as wall text. This is one of the strongest exhibits in the building: it is a legible record of a system being wrong and being corrected. - **External reviews** — each saved verbatim, with its adjudication. The adjudication is the exhibit; the review alone is just an opinion. - **Sessions** — every session's final report plus metadata (model, task, commit, turns), labelled **PARTICIPANT REPORT** per §7. - **Decisions** — from frozen decision records (§10). - **Graveyard** — ruled-out ideas with their original decision records. - **Search** — full-text over the corpus. The archive's index, not a room. **The workflow material is no longer a per-release room.** It has been promoted into the spine as Chapters 2–4 and made release-pinned (§5), which is what the old "workflow room per release" idea was reaching for. Its source material stands: `planning/_standing/WORKFLOW_REVIEW_PROMPT.md` is a complete, incrementally-maintained written description of the setup, plus the memory files. **⚠ Vocabulary: "seated module" is dropped.** It is a hardware metaphor borrowed from the app's Module Bay, and outside that context — which the museum no longer has, since the theme is dropped (§14) — it stops meaning anything. **The distinction it named survives and is load-bearing:** > **INDIVIDUAL ARTIFACTS** get individual presentation — a thumbnail, metadata, its own space — > because they matter one at a time. > **AGGREGATE MATERIAL** gets a dense manifest, because its meaning exists only in bulk. The distinction stays **structural — density and layout — never decorative.** Layout survives a stylesheet change; badges and accent colours do not. --- ## 10. THE CURATION MECHANISM Each release account carries a **featured-artifact list**: a filename plus one line on why it matters. The generator renders those with real thumbnails, links and metadata. > **The SELECTION is frozen prose. Everything around it is generated.** **If a named artifact is missing, the page says so.** A curator's pick silently pointing at nothing is precisely the "authoritative and quietly wrong" failure. **⭐ A mechanical property must never silently override a human judgement.** The generator reports state; it does not re-curate. The origin case: a curator's pick sitting in a build that fails to boot **stays on its pedestal, showing the panic**. Demoting it would let software rot quietly rewrite the curation and bake survivorship bias into the exhibition — whatever still runs gets elevated, whatever died sinks into a list — and it would happen invisibly, with nobody witnessing the demotion. **Decision records use the same shape** — what was decided, when, why, what was rejected. Dispatch drafts, owner approves, then frozen. **Not** a formal process where every change demands a document; only the calls that would otherwise be lost. The bulk manifest below the featured picks stays **fully exposed, never collapsed**. The scroll is the scale, and the curation only reads as valuable next to the bulk it saved you from. --- ## 11. TL;DRs — EXTRACT, never generate Most summaries already exist: memory files carry a `description:` in frontmatter; planning docs state their purpose in the first line; audits open with a snapshot line. ⇒ The generator **extracts** these. **No AI at build time** — a hallucinated summary is worse than none, and it would break determinism. Where a file has no summary line, the museum says so, and that list becomes a to-do: one line added at the source improves both the file and the exhibit. --- ## 12. THE BUG MUSEUM — curated cases with red-then-green evidence **⚠ GPT's rebuttal stands and changes the design.** The old form was: ``` ANOMALY #42 TEST RECORD: <filename> STATUS: PASSING AT COMMIT <hash> ``` **"Passing at commit X" proves a test passed. It does not prove the test would catch that defect.** An inert test also passes — and this project has produced an inert guard twice. So the old form, which was adopted specifically to strip the authority claim, still smuggles one back in: the reader reasonably infers coverage from a green status, and the museum has no evidence for that inference. **⇒ Each case requires one of two things, and must render whichever it has:** 1. **RED-THEN-GREEN EVIDENCE.** The guard demonstrably fails against the defective code and passes against the fixed code. That is an actual demonstration of coverage. 2. **Or the literal admission:** *"Coverage of this historical defect is not independently demonstrated."* There is no third option and no softer wording. **Scope: five to ten failures with complete evidence chains. NOT comprehensive coverage.** An "every defect" museum was rejected on the grounds that the set is unprovable, and that rejection stands (§20). The obvious candidates are the two the project already understands deeply: **the silent service-worker failure** and **the inert cache guard**. **Why the owner wants it:** it is the only proposed exhibit that would change how he works — every guard shown beside the defect it exists to prevent is the evidence the rulebook trim needs, and that argument currently lives only in scattered audit files and orchestrator memory. --- ## 13. HISTORICAL CAPTURE — kept; the exhibit built on it is CUT **⚠ "Propositions vs Reality" as designed is CUT.** > **GPT:** *"Two unpaired blocks do not create a comparison; 'the visitor's eye does the work' is the > opposite of teaching."* That is correct and it is fatal to the design as written. The exhibit was two lists side by side — that release's mockups facing that release as it rendered — with no pairing, on the theory that the absence of curation *was* the curation. In a teaching artifact, handing the reader two unsorted piles and asking them to find the connection is precisely the synthesis burden the museum exists to lift. **Two acceptable outcomes, no middle:** 1. **A small frozen set of curated real pairs** — hand-picked, few, each with a written line on what changed between proposition and reality. This is frozen prose and cannot rot. 2. **Don't build it.** **Historical screenshot capture itself is still endorsed** — it is genuinely one-off work, not a maintenance tail. Check out a release tag into a temporary git worktree, serve it, boot it with the browser automation the project already depends on, capture, tear down. **A release commit is immutable, so each release is captured exactly once, ever, and cached against its commit hash.** Regenerating next week re-shoots nothing. **Boot the machines EMPTY.** A modern save fixture would fail to load in an old save format and could crash a genuinely healthy build, making the exhibit lie. An empty terminal is also the truthful artifact: the chrome is what was built. **⭐ CAPTURE IDENTITY IS NOT THE COMMIT HASH.** A screenshot is a function of far more than the code. Capture identity **must** include: ``` route · viewport · state contract (empty / seeded / which fixture) · capture-spec version · commit ``` **And the label must be literal:** > ✅ *"Captured from commit `a1b2c3d` at 360×800 with an empty profile."* > ❌ *"How the release actually looked."* The second is a claim the capture cannot support — it looked different on other viewports, other routes, and with real data. **Failure detection reuses the project's existing boot-smoke judgement.** Do not invent a second definition of "working"; two definitions is how the museum ends up disagreeing with the pipeline. - Navigation failed → **environmental** (worktree didn't serve). Not the artifact's fault; say so. - Uncaught error during boot → **genuine boot failure**. - Anchor present but nothing painted → **render failure**. A different fact. - All checks pass but the screen is empty → **NOT a failure.** That is the app's honest empty state, and reporting "no data" as "broken" lies about the artifact. The panic frame's contents are the **verbatim captured error** — never an invented cause. "No longer boots in a modern browser" and "dependencies lost to time" are both almost certainly false for a vanilla app this young, and the real stack trace is the better exhibit anyway: it is the actual last words of a version of the software. **Threshold:** one dead machine is meaningful; all of them dead means the automation is broken. Treat a total-failure result as a generator bug, not a finding. --- ## 14. THE DATE VIEW — cut from the teaching spine **"Archive activity on this date" is CUT from the spine.** It is owner-oriented archaeology: a newcomer does not arrive knowing a date, so it cannot be part of a path that teaches. It has no entry point for the learner defined in §2. **It may survive as an owner tool** — a diary view, generated from git history and release tags, with separate lanes (*shipped* · *first entered the archive* · *planning artifact* · *mockup*) and never conflating a git timestamp with when an idea was had. It is cheap and has no maintenance tail. But it is a utility, not a chapter, and it does not compete for build order with the spine. **The clickable growth chart follows the same logic** — deferred, and only ever navigation. If the date pages exist, the chart's points become links to them. Never a second analytical subsystem. --- # PART III — PUBLICATION MECHANICS --- ## 15. PRESENTATION — the theme is dropped Owner: *"it doesn't have to stay 100% in theme… you can also decide to drop the theme if you want, that's entirely your call."* **Decision: a gallery, not a terminal.** The reasoning: **the exhibits already ARE the RobCo aesthetic** — 429 amber phosphor mockups, 28 terminal prototypes. Framing them in more terminal chrome flattens everything into one texture. Galleries hang paintings on neutral walls for exactly this reason. - Dark and restrained (the images are dark), modern layout, real body text with real spacing. - Monospace retained for **data** — filenames, hashes, counts, stack traces — where it signals machine output. - RobCo becomes an accent, not the substrate. - **Stops inlining the app's 512 KB stylesheet.** The reuse argument was about avoiding drift; a standalone museum stylesheet has nothing to drift *from*, so this is less coupled, not more. - **Unlocks the Gource-like visual language** (§18) — radial layouts and decay-by-opacity are modern data-vis and cannot be expressed in a vocabulary of boxes and slots. - ⭐ **KEEP the theme deliberately in ONE place: failure states.** A dead build printing its real stack trace in a panic frame is where the fiction adds truth rather than decoration. Both reviewers independently called keeping the theme *only* for genuine failure states "unusually coherent." Fully reversible regardless — it is generated. --- ## 16. GENERATION MODEL **Cadence: at RELEASE, not on every sync** (owner). A room is a release; regenerating mid-round means the newest room never settles. **Pin to the RELEASE, not `dev`** — the same pin the teaching layer uses (§5), for the same reason. **Test count IS captured — at release, frozen** (owner). Consistent with retiring the count-sync protocol, which killed the *obligation to hand-sync a live number across eight files* while explicitly keeping frozen counts on released changelog entries as history. Measured by the generator, never hand-copied. **Never hand-copy a generated figure into a planning document.** §8 exists because that happened three times and produced three disagreeing numbers. --- ## 17. PUBLICATION ### 17.1 Owner decisions — LOCKED 2026-07-20 - **Timing: public AFTER the 2.8.5 release and BEFORE the 2.9.0 release.** This is **locked**, not conditional. (The previous plan contradicted itself — §8 locked it, §11 said "IF publishing at that point." It is locked.) - **Then integrated into the filesystem in 2.9.0**, when the OS round builds DIR. The app carries a **pointer** to the public museum; the archive bytes never move into the app. Since it is public by then, a plain link is sufficient. - **New repo name: `Robco-Exhibit`.** Owner's choice — the existing archive repo's history carries his real name and cannot be cleaned. - **The four release accounts are APPROVED AND FROZEN** (`MUSEUM_RELEASE_ACCOUNTS.md`, owner, 2026-07-20). Do not rewrite them. (The previous plan said both "approved and frozen" and "awaiting approval." They are approved.) - **Public, no login** — owner: *"I'm not worried about someone reading the generated data, that's the whole point in the museum."* ### 17.2 ⭐ CLOUDFLARE PAGES, not GitHub Pages GitHub project sites share the `zerckzzyHD.github.io` origin, so a museum there would share **browser origin and localStorage** with the live app — and the archive holds **28 executable HTML prototypes** that could read or overwrite the live campaign. Cloudflare serves from its own domain; the hazard vanishes. *Found by GPT-5.6 Sol. The single most valuable finding of the museum review exercise, and nobody would have found it by looking at the museum.* Because Cloudflare solves the origin problem by host choice, **`Robco-Exhibit` can live on the owner's NORMAL GitHub account.** The earlier "separate account" requirement existed *only* because of the shared GitHub Pages origin. **The existing archive repo can NEVER be made public** — git history retains the memory files regardless of later deletion. Publication is from a **separate repo containing only generated output**, with clean history. ### 17.3 ⚠⚠ THE PUBLISH GUARD MUST FAIL CLOSED — the most important fix in this document **The previous design does not fail closed, and this is the defect that matters most.** It specified: scan the output tree → push → **then** verify against the remote. That verification step was described as catching the case where the guard ran against the wrong directory — which is real, and is exactly the class of mistake this project keeps making (the museum reading whatever was checked out; the backup syncing a memory store that wasn't the real one). **But verifying AFTER a public push is not a guard. Disclosure has already happened.** By the time the remote check runs, the tree is public. Deleting the repo does not retract clones, CDN caches, GitHub's own caches, or scrapers. The prescribed remedy — "delete and recreate, do not patch" — addresses git history and does nothing about the disclosure that already occurred. **Publication is the one irreversible step in this system**, and the guard was placed after it. **⭐ CORRECT SEQUENCE — verify the exact commit privately, then expose that same commit:** ``` 1. GENERATE the public tree. 2. PUSH the exact commit to a PRIVATE remote (or a non-public staging target). 3. VERIFY THAT COMMIT — all checks in §17.5, run against the pushed tree, not local state. 4. Only on a clean pass: EXPOSE THE SAME COMMIT publicly (flip the repo to public / promote the identical commit to the public target). 5. Re-verify after exposure as a confirmation step, not as the gate. ``` The property this buys: **the artifact that was verified and the artifact that becomes public are byte-identical and the same commit** — which was the original point of checking the remote — *and* no disclosure occurs before the check. Step 5 is retained because a deployment can disagree with a repo, but it is now a confirmation, not the only line of defence. **Any failure at step 3 aborts.** No push to public, no partial publish, no "warn and continue." ### 17.4 ⚠ THE OUTPUT IS NOT SELF-CONTAINED — measured, not theorised **Verified 2026-07-20 against the built tree:** > **3,318 references inside `museum/site/` point outside it**, via `../../planning/2.8.0/mockups/…` > and `../../planning/2.8.5/mockups/…`. Two consequences the old plan missed: 1. **Copying `museum/site/` alone ships a broken museum.** Every full-size gallery image breaks. 2. **Validating links inside the private repo proves nothing about the public tree** — inside the archive those `../../` paths resolve, because the sibling directories are right there. In the published tree they will not exist. The current all-links-resolve result is therefore **not evidence about what gets published.** **⇒ REQUIRED VALIDATION — it must be done against the real thing:** - Generate **only the public tree**, into an **empty location**. - Make the private archive **unavailable** (move it, rename it, or generate on a path that cannot reach it) — so a stray `../../` cannot accidentally resolve and pass. - **Serve it and crawl it.** Verify every page, stylesheet, thumbnail, **full image**, prototype and search result loads, **with no path escaping the output root**. **⚠ Size correction.** `museum/site/` is 18 MB, but the 429 referenced full images live in `planning/2.8.0/mockups` (**103 MB**) and `planning/2.8.5/mockups` (**72 MB**). **The real public tree is on the order of 190 MB once the images are copied in, not 19 MB.** That changes hosting assumptions, deploy times and the phone-readability of gallery pages, and must be sized before the publish step is scheduled. ### 17.5 ⚠ THE THREE-STRING SCAN PROVES ONLY THREE STRINGS The previous plan concluded: *"No memory split needed — three strings, then the museum simply reads the memory."* That conclusion was already falsified inside the same document — **the App Check debug token blocker proves credentials are a separate class of exposure entirely**, one that no name-and- email scan would ever detect. **⇒ THE EXACT PUBLIC COMMIT REQUIRES ALL FOUR, at step 3 of §17.3:** 1. **PII-string scanning** — real name and surname in all case variants → `zerckzzy`; **email removed entirely** rather than substituted (a fake address that looks real is worse than absence). Deterministic string replace, not a judgement filter. Must cover **the search corpus**, which holds full document text and would otherwise leak exactly what the visible pages hid. 2. **CREDENTIAL / TOKEN-PATTERN SCANNING** — API keys, tokens, connection strings, private URLs, absolute Windows paths. Pattern-based, not a fixed string list, because the thing you are looking for is by definition one you did not anticipate. 3. **AN APPROVED PUBLICATION DIFF** — what is *newly entering the public set* since the last publish. Not a filter and it decides nothing; a notice, so the boundary is visible at the one moment it matters. This answers the ongoing-classification problem: new memories arrive continuously, and the diff makes each one visible rather than trusting a one-time classification forever. 4. **LINK VALIDATION AFTER SUBSTITUTION** — ⭐ **run last, and this ordering is the point.** Rewriting text can break references: a substituted name inside a path, filename, anchor or href silently breaks the link. Validating before substitution validates a tree that is not the one being published. **⛔ BLOCKER: the App Check debug token must be rotated before publishing.** It bypasses App Check verification. Tracked as a 2.9.0 queue item, cross-referenced from here. **One lobby line** notes that local paths show the handle rather than the account name — so the substitution is disclosed rather than passed off as the original text. ### 17.6 Two things that would defeat the clean repo 1. **COMMIT IDENTITY.** A fresh repo does not stay clean on its own. If the generator's commits use the owner's normal git identity, his real name and email enter the new history on the very first push — exactly what the new repo exists to prevent. **Set a repo-local identity** (`zerckzzy` plus a GitHub `@users.noreply.github.com` address) and **verify `git log --format='%an %ae'` on the first commit before pushing.** 2. **NO HISTORY CARRIED OVER.** Generate fresh into the new repo. Do not copy the existing museum output, its search index, or any prior commits forward — they contain the un-substituted email. ### 17.7 Post-publish order Build `Robco-Exhibit` → verify live and correct on Cloudflare → **then** remove `museum/site/` from the private archive. The generated output is derived and never needed backing up; the only reason it was committed to the archive was so the owner could see it on GitHub, and a live site replaces that. **The GENERATOR stays in the archive** — it is source, and it reads the archive. `Robco-Exhibit` is purely a publish target. **The private archive repo itself is never deleted** — it remains the only off-machine copy of `library/`, `planning/` and memory. **Link rot:** content-hash-only document URLs vanish when content changes. Generate stable aliases or retain old pages. --- # PART IV — PROCESS --- ## 18. THE VISUAL WEB — parked, wanted, reference confirmed Owner confirmed **Gource** is the look: *"yes, that's what caught my eye about gource."* Nodes radiating from a centre, organic branching, pulse-then-settle, inactive branches dimming. **He wants the FEELING, not the tool.** Gource itself is rejected — it is built for many contributors over years; here it renders as one dot orbiting a small tree, and costs two installs plus a large stale video. **Transfers to generated SVG + CSS, no framework:** radial layout · edges between related nodes · opacity by age/activity · pulse on hover/tap · colour by type. **Does not transfer:** animated playback of history. ⇒ Hand to **Fable** as *"make the RobCo-native version of this feeling"*, never *"build this tool."* --- ## 19. THE REVIEWS **⭐ FABLE MOVES EARLIER — it designs the proven vertical slice, not the finished templates.** The previous plan scheduled Fable last-but-one, after the museum was functionally complete. That is backwards: scheduling the design pass after every template already exists means the design either gets ignored or forces a rebuild of everything it touches. Design decisions are cheapest before the templates multiply. **Fable's brief, at the vertical slice:** design **one complete path** — the lobby, one methodology chapter, and one worked case — well enough to prove the teaching layer works. That slice is what the novice comprehension test (§2) is run against, and what the remaining chapters are then built to match. The brief is much stronger than it would have been: **not "style an archive like a terminal" but "design a gallery for a terminal's history,"** plus the Gource reference for the visual web. Fable authored the machine, the tempo dial, the records bay and the approved mockups — it can see the real CSS and the images it drew. This is a design job, not a review. **GPT-5.6 SOL — audit. Runs LAST, unchanged.** Work tab, connected to the repo, and **given the live Cloudflare URL** so it reviews the real thing rather than a description. Structural and interactivity review, with **"no change" explicitly allowed** — GPT is the only one of the three that has been willing to say something should not be built. Its standing warning governs the whole project: > *the eighteen-month failure is not a broken script; it is a museum that still opens, looks > authoritative, and is quietly wrong.* **Opus gets no separate reviewer slot** — that is Dispatch, which adjudicates throughout. Adding it as a reviewer would be marking its own work. **Standing note on the reviewers, recorded because it is reusable:** Gemini's instinct beat GPT's caution on buildability twice (historical-capture cost; the pivot that reframed Propositions vs Reality). GPT's rigour beat Gemini's enthusiasm on facts twice (the growth chart was numerically wrong and Gemini praised it without checking; the same-origin storage hazard). In this round they reached the same structural verdict independently. **Run both, blind, and adjudicate — do not average them.** --- ## 20. SEQUENCING **Build the vertical slice first, and test it on a novice before scaling.** The old sequencing built rooms and left the teaching path to emerge; that is the failure both reviews identified. **Phase 1 — prove the teaching layer works (before 2.8.5 release)** 1. The narrowed claim, learner and outcomes (§1, §2) written into the lobby. 2. The frozen-narrative / injection-point mechanism (§4) built. 3. Release-pinned generation, with the test count captured as a frozen release measurement (§16). 4. **Worked case 3** — the confident result overturned by evidence. Built first because it is the hardest and most valuable; if the evidence chain cannot be assembled for it, the whole worked-case design needs rethinking before three of them exist. 5. **Fable designs the vertical slice** — lobby + one chapter + that case (§19). 6. **⭐ NOVICE COMPREHENSION TEST (§2). This is a gate.** If the entry path does not teach, stop and fix it before building anything else. **Phase 2 — the rest of the spine** 7. Remaining methodology chapters (§3), with claim labels and the transfer layer (§7). 8. Worked cases 1 and 2 (§6); wire every chapter to its citations. 9. Curation mechanism (§10) → this is what turns the release rooms into usable citations. 10. TL;DR extraction (§11). 11. Session reports relabelled as PARTICIPANT REPORT and connected to diffs/audits/gate results (§7). **Phase 3 — publication** 12. Name substitution, credential scanning, publication diff, post-substitution link validation (§17.5). 13. Self-contained output validation against a genuinely isolated tree (§17.4) — and size the real ~190 MB public tree. 14. App Check token rotation (⛔ blocker). 15. **Publish via private-verify-then-expose (§17.3).** Locked: after 2.8.5, before 2.9.0. **Phase 4 — after publication** 16. Bug museum, red-then-green only, 5–10 cases (§12). 17. Historical capture + the small curated-pairs set, or drop it (§13). 18. Date view as an owner tool, if wanted (§14). 19. Clickable growth chart — navigation only, last. 20. **GPT live audit against the deployed URL (§19).** **Do not build another room before the museum is honest.** GPT's judgement, adopted and unchanged. --- ## 21. REJECTED — do not re-propose | Item | Why | | --- | --- | | **Releases or artifact classes as the organising spine** | The finding that produced this rewrite. Cases and methodology are the spine; the archive is the citation layer. | | **"Propositions vs Reality" as two unpaired blocks** | Two unpaired lists are not a comparison, and making the visitor do the synthesis is the opposite of teaching. Curated pairs or nothing (§13). | | **The date view as a teaching chapter** | A newcomer does not arrive knowing a date. Owner tool only (§14). | | **"Every defect" bug museum** | The set is unprovable. 5–10 curated cases with evidence chains (§12). | | **Coverage claimed from a passing test** | An inert test also passes; proved twice on this project. Red-then-green or an explicit admission (§12). | | **Verifying after the public push** | Disclosure has already happened and cannot be retracted (§17.3). | | **The three-string scan as sufficient** | The App Check token proved credentials are a separate class (§17.5). | | **"Seated module" as vocabulary** | A hardware metaphor that stops meaning anything without the Module Bay. The individual-vs-aggregate distinction survives; the term does not (§9). | | **Session reports as neutral exhibit labels** | They are self-reports — claims, not evidence (§7). | | **Graveyard as the front door** | Never start the tour in the basement; also misrepresents the project as defined by its failures, and publicly invites decontextualised screenshots. | | **Semantic mockup→screen mapping** | Permanent human curation obligation, and it does not map 1:1 anyway. | | **A public redaction pipeline** | A filter running every build is a second product. The boundary is drawn once, at the source. | | **Inlining CSS into every page** | Shared stylesheet is correct at 272 pages. | | **Live iframes for all prototypes** | Archived HTML is untrusted active code. | | **Running Gource** | Built for many contributors over years; here it is one dot orbiting a small tree. Take the feeling, not the tool (§18). | | **AI-generated summaries at build time** | Hallucination risk, and it breaks determinism. Extract, never generate (§11). | | **A formal ADR process on every change** | Only the calls that would otherwise be lost get decision records (§10). | | **Claiming the museum teaches "the best way to use AI"** | No comparative evidence exists. The claim is narrowed and binding (§1). |