Rebuild the plan document and gallery design

Context

The story behind this plan — what prompted the work and why it matters now.

Every generated plan is styled by one 1930-line module, scripts/lib/plan-shell.mjs, whose CSS export has drifted into a generic default: system-ui at 15px, #2563eb blue, 4px radius, and a 1px solid #e5e7eb border on every container. A visual audit of a rendered plan, the 88-card gallery at docs/plans/index.html, and the hub at docs/index.html found six concrete failures, and two prototypes at docs/prototypes/plan-document-redesign.html and docs/prototypes/plans-site-redesign.html were built and verified against them.

The failures are structural, not cosmetic. objectiveCard and glanceBlock render as siblings, so a reader hits two abstracts before any content and cannot tell which is authoritative — plan-shell.mjs line 376 even carries a margin: -1.5rem 0 1.5rem hack to pull the second up against the first. stepCard buries the Verify: text in a <details class="step-verify-toggle">, which is the one line a reader needs while executing. Three separate devices report progress — the shimmer bar at progressBlock, the icon nav from nav(), and the .steps-list::before timeline — and none of them says which step you are on, because NAV_ENTRIES has a single steps entry rather than one per step. --subtle: #9ca3af on #ffffff measures 2.5:1 and is used for nav icons and step chips, so the page fails WCAG AA today. There is no dark mode at all.

Three test gates constrain how this can be done, and they shaped the step order.

The first is the nav regex at tests/plugins/test-build-plan-html.mjs:635: [...html.matchAll(/<a href="#([a-z-]+)">/g)] requires each section anchor's href to be its only attribute. Step links are therefore emitted with a leading class attribute and ids containing digits (#step-1), both of which that regex skips — the section-link deepEqual keeps passing without being loosened.

The second is the back-compat guard at tests/plugins/test-build-plan-html.mjs:928. It renders the sample spec through the renderer at origin/main and through the working copy, blanks the three prompt payloads and the <style> block, and asserts the two documents are byte-identical. Its stated purpose in the comment above it is narrower than what it does: presentation is expected to evolve, and what the guard protects is "the DOM contract the extractor and the gallery read". As written it fails on any intentional markup change, and the inline <script> is not blanked either, so it also fails on the theme-toggle and scroll-spy edits. It is narrowed in step 2, before the first markup change lands, rather than left red across the whole PR.

The third is the byte-identical mirror at tests/plugins/test-build-plan-html.mjs:951, which asserts the three files under kit/plugins/plan-agent/scripts/ match their repo-root counterparts under scripts/. lib/plan-spec.mjs is not edited by this plan, so only two files are re-copied.

Two hazards were designed around rather than accepted. scripts/merge-plans-index.mjs is the git merge driver for the generated gallery indexes; it splices the union of <a class="gallery-card"> blocks over the region between the first and last card, so anything sitting between cards — a static month heading, for instance — is destroyed by a merge and stays destroyed until the next regeneration. Month grouping is therefore rendered client-side from a data-month attribute on each card rather than baked into the generated markup: the driver never sees a group header, CARD_RE is untouched, tests/plugins/test-merge-gallery-index.sh is untouched, and a filtered view re-groups correctly instead of leaving empty headings behind. The same technique carries the In-flight band, which is a client-side separator over cards the generator sorts first.

The second hazard is the theme toggle. plan-shell.mjs already selects on [data-status="…"] set on <html>, so the theme attribute is a second attribute on the same element (data-theme) rather than a class, and the two compose without either winning. The stored preference is read by a small inline script in <head> before first paint, because a plan opened from file:// has no server to set a class for it and a flash of the wrong theme on every page load is worse than no dark mode.

One redundancy is knowingly left in place. The prototype folds the progress bar into the sidebar rail so the page carries a single progress device; this plan does not, because relocating progressBlock would drop progress from NAV_ENTRIES and invalidate both nav deepEqual arrays for a purely cosmetic gain. The bar keeps its position and its ids, loses its shimmer animation in step 1, and the rail is a step index rather than a second progress readout. Merging the two is a follow-up, not a prerequisite.

Phases are deliberately not in scope. The step rail groups nothing today because parseSpecMarkdown returns steps as a flat { action, why, verify } list with no phase concept anywhere in the parser, the digest, the renderer, or the extractor — see docs/plans/add-plan-phase-checkpoints.md, which adds all four. That plan already edits nav()'s neighbours, so phase grouping is added there once the rail exists, rather than building a grouping hook here for data that does not exist yet.

workflow: never is set deliberately. Steps 1 through 6 are ordered edits to the same two files, scripts/lib/plan-shell.mjs and scripts/build-plan-html.mjs, so subagents fanning out would conflict on them. The renderer's own heuristic counts files and top-level directories and would otherwise license fan-out this plan cannot use.