38 tasks · 5 phases · 4 files · 2026-08-18

The Guides Segment Is Already Built — The App You’re Running Is Ten Days Old

The missing Guides segment is not a bug in the Guides code. The running app is the Debug product built 2026-08-08 — ten days and six commits behind HEAD — and its binary still contains docs/demos/. The guard written to catch exactly this reports VERIFIED on it.

10Days stale
38Tasks
5Phases
0Guides bugs found
The gist

You reported no Guides segment and a leftover, empty Demos segment. I went looking for the rename bug and there isn’t one — the rename is complete and correct in source. The app you are looking at was built on 8 August, before the rename, before the Plans segment, before six commits of work. Its binary literally still contains the string Show docs/demos/ in Finder, and the folder it scans was deleted, which is why the segment is empty.

The finding worth your attention is the second one: scripts/verify-build-product.sh — written on 14 August specifically to stop this — prints VERIFIED when run against that ten-day-old bundle. It only compares the product against uncommitted edits, so a clean tree switches the check off entirely. It goes blind the moment you commit.

The problem

Three facts, each directly observed rather than inferred:

The source is fine

FlowMapKind.guide exists, FlowMapScanner.scannedFolders maps ("guides", .guide), FlowMapKind+UI.swift and DocumentsHubWidget.swift carry the case throughout, and docs/guides/ holds twelve well-formed HTML files. A repo-wide sweep finds no Demos segment anywhere in Swift. The rename landed in 93633aa on 14 August at 15:41.

The binary predates all of it

Product mtime 2026-08-08 21:01:29. PID 86324 was launched today at 01:34 from that bundle. Meanwhile object files in Intermediates.noindex are as recent as 17 August 09:30 — compilation has been happening for days; the link and copy into the bundle has been silently skipping.

The real defect

The guard passes the case it exists to catch

Run just now against the stale product, unmodified:

product mtime: 2026-08-08 21:01:29
newest source: (none)
RESULT: VERIFIED — product written 2026-08-08 21:01:29, newer than all modified sources.

“Newest source” comes from git diff --name-only HEAD — uncommitted changes only. A clean tree yields SRC=0, and the staleness comparison is then guarded behind [ "$SRC" -gt 0 ] and skipped outright. The script cannot see a product that is behind HEAD, only one behind your unsaved edits.

Approach

Rebuild first, because nothing else is testable until then

Quit the app (it holds the bundle being replaced — the suspected cause of the skipped copy), rebuild, and prove the product moved by checking that docs/demos/ no longer appears in the binary’s strings. That single step resolves the reported symptom.

Compare against all tracked source, not just dirty files

Derive the staleness baseline from git ls-files '*.swift' plus bundled Resources and the xcodeproj, take the max with the existing uncommitted-file check, and delete the $SRC > 0 guard that made the comparison optional. The fixed script would have surfaced this on 15 August rather than today.

Rejected: stamping the commit SHA into Info.plist

Genuinely more robust — a version the app reports about itself cannot go stale. But it needs a build-phase script, and this repo’s history with checks that fail quietly (the auto-push hook) argues for exercising the manual check by hand before automating anything. Held as the answer if this recurs a third time.

Decisions made for you

Judgment call

Amend the What’s New entry in place, no version bump

The documents-hub highlight still says “Six segments — Flowmaps, Reviews, Digests, Demos, Testing, Mockups.” It is now seven, led by Plans, with Guides replacing Demos. Correcting a wrong v1.95 entry is not a release, so WhatsNewTracker.currentVersion stays put — the same precedent set when /cr-checkin was retired.

Judgment call

Phase 1 stops rather than pushes on

If a rebuild with the app quit still writes no product, the diagnosis here is incomplete. The plan halts and captures the xcodebuild output instead of guessing past it — guessing past it is how this reached a second occurrence.

Judgment call

I did not quit your app or run a build

The running process is yours and the build would fail the same way while it holds the bundle. Everything in the diagnosis above came from reading the binary and the filesystem.

The work

Phase 1 — Get the correct binary running

6 tasks Blocks every runtime check in this plan and every item deferred since 14 August.
  • Confirm no uncommitted work is at risk: run git status and record that the tree is clean before quitting the appyou
  • Quit Code Raven completely (the running process holds the bundle being replaced; this is the suspected cause of the skipped copy step)you
  • Rebuild with the app quit: ./scripts/verify-build-product.sh Debug and confirm it prints RESULT: VERIFIED with a product mtime of today, not 2026-08-08
  • If the product mtime still does not advance, capture the full xcodebuild output to docs/reviews/ and stop
  • Verify the new binary no longer contains the old folder strings: strings … | grep -c "docs/demos/" returns 0
  • Relaunch the app and confirm verify-build-product.sh Debug --no-build reports (running this build) rather than NOT LIVE

Phase 2 — Close the hole in the staleness guard

8 tasks Independent of Phase 1, but validate against the stale product before Phase 1 replaces it.
  • Before rebuilding, capture the current stale-product state as a regression fixture in the script’s header
  • Replace the SRC derivation so it no longer depends on the tree being dirty — newest mtime of all tracked source files
  • Keep the uncommitted-changes path as well and take the max of the two
  • Promote the comparison from conditional to unconditional: delete the [ "$SRC" -gt 0 ] && guard
  • Update the failure message to distinguish “older than your uncommitted edits” from “older than committed source”
  • Rewrite the script header’s “What to stat” section to record this second incident
  • Verify the fixed script fails (exit 1) when pointed at a deliberately stale product
  • Verify the fixed script still passes cleanly on a genuinely current build after Phase 1

Phase 3 — Correct the stale in-app copy

4 tasks The one genuine source-level residue of the rename. Independent of the build problem.
  • Fix FeatureHighlight.swift — the documents-hub description still reads “…dispatches, demos, test pages…”
  • Fix the same highlight’s first capability string — “Six segments — … Demos …” is now seven, led by Plans
  • Confirm no other What’s New entry names Demos or a six-segment hub
  • Do NOT bump WhatsNewTracker.currentVersion for this

Phase 4 — Sweep the leftovers the rename left behind

6 tasks Depends on Phase 1 so the segment can actually be looked at.
  • Add a <p class="sub"> subhead to docs/guides/walkthrough.html — the only guide missing one
  • Delete the stale .claude/demos/ directory — its walkthrough still teaches the retired /cr-checkin split
  • Confirm before deleting that nothing reads .claude/demos/
  • Confirm docs/guides/_generator/ is not picked up by FlowMapScanner
  • Verify the workbench side needs no further action — CodeRaven/guides/ exists and no demos/ remains
  • Determine whether the old workbench URL was ever shared externally, and if so leave a redirect stubyou

Phase 5 — Re-run the verifications that were never possible

4 tasks Not new work — items carried as “runtime-unverified” while the binary predated the feature.
  • Re-check the Chronicle backlog for “built <date>, runtime unverified” items dated after 2026-08-08 and list which ones this plan re-opens
  • Confirm the Plans segment renders in the Documents widget — open since 14 August, never testable until now
  • Confirm the Guides segment renders with all twelve docs/guides/ files and a live count
  • Confirm the history archival tier (built 20 July) — predates the product, so genuinely testable; noted to avoid re-opening it by mistake

Manual testing

9 tasks All yours, after Phase 1 relaunches the app.
  • Quit Code Raven fully, then confirm from Activity Monitor that no Code Raven process survives before the rebuild startsyou
  • After relaunch, confirm the Documents widget shows seven segments: Plans, Flowmaps, Reviews, Digests, Guides, Testing, Mockupsyou
  • Confirm Plans is the leading segment and the default-selected tabyou
  • Confirm the Guides segment shows a count of 12 and lists the start-here index, reference card, walkthrough, and week pagesyou
  • Click one week page and confirm it opens in the browser and rendersyou
  • Use the Guides segment’s folder button and confirm it reveals docs/guides/ in Finder, not docs/demos/you
  • Confirm no Demos segment appears anywhereyou
  • Open What’s New, find “Every Document in One Place”, and confirm it no longer says Demos or six segmentsyou
  • Confirm the archived-guides disclosure appears and behaves if anything is moved into docs/guides/_archive/you

Risks & edge cases

Unproven

I have not established why the copy step skipped

The app-running-from-the-bundle theory fits the script’s own documented incident and the evidence (objects from 17 August, product from 8 August), but it is inference, not a reproduction. Phase 1 stops explicitly if a quit-app rebuild still writes nothing.

Edge case

mtimes are rewritten by clone and branch switch

The Phase 2 fix reads filesystem mtimes of tracked files. A fresh clone or a branch switch sets those to checkout time, so the script will demand a rebuild after either. Correct behaviour, but noisier than today.

Residual gap

Same-ordering, different-commit builds still slip through

Comparing mtimes cannot catch a product built from a different commit whose timestamps happen to order correctly. Only a commit SHA stamped into the bundle closes that, and that is held out of scope here.

Scope

Phase 5 may re-open more than it closes

Anything marked “built, runtime unverified” after 8 August was never actually verifiable. The list could be longer than the three items I already know about.

Out of scope

Wiring the check into a git hook or build phase

Deliberately deferred. A check that fails quietly is worse than no check — the auto-push hook taught that here already. Decide on automation only after the fixed script has been run by hand a few times.

Stamping GIT_COMMIT into Info.plist and surfacing it in the app

The robust answer, and the one to reach for if this happens a third time.

Final review

What this plan actually is. Four of its five phases are cleanup. The substance is Phase 1 and Phase 2. The reported bug does not exist in code — the fix is to run the code that was already written. The finding worth keeping is that the tooling built on 14 August to prevent exactly this reported VERIFIED on a ten-day-old product.

Where it’s strong. It fixes the real defect rather than the reported one, and the Phase 2 change is small, testable, and independently valuable. Phase 5 converts a vague sense that things were “runtime-unverified” into a specific, bounded list.

Where it’s weak. The cause of the skipped copy step is inferred, not reproduced, and I have not run a build myself — the app is running from the target bundle and quitting it is your call. If a quit-app rebuild still writes nothing, this plan is incomplete and says so rather than improvising.

What I’d adjust if pushed. Skip straight to the Info.plist commit stamp. I held it back on the argument that unexercised automation is how this class of check rots, but that argument has now been wrong twice.

92/100

High on the diagnosis, which is directly evidenced: the binary’s own strings, the product mtime, the commit timestamp, and the script’s live output all agree. It loses points only on the unproven cause of the skipped copy step and on the untested assumption that a quit-app rebuild resolves it.