Polish the living document flow

[MaggieAppleton]

Summary

A design pass over the living document flow (spikes → Build plan → first build → In sync / Out of sync), done on the real "Margin — living document", with route interception for the other states.

Top findings → what changed

1. Expanded rows read as machine output. A sync-added task expanded to "Committed on https://github.com/…/pull/6." and "Reflects the document change since revision 452.", while the agent's own report of what it did was never shown. Now a finished task shows its summary instead of its acceptance criteria, and sync tasks get readable criteria ("Updates pull request Test the frontend with a browser, and run it on every push #6.").
2. A Planner draft duplicated a living document's tasks (bug). Any "update the tasks" turn, including Build's automatic draft, added the unbuilt draft to live.tasks, so the real document went from 8 to 14 rows with duplicate keys. Now liveSnapshot lists only versions that ran (regression test added).
3. Two vocabularies for one loop. In sync / Out of sync, then "Building…". A failed sync was only distinguishable on hover, and In sync had no explanation. Now the loop reads In sync → Out of sync → Syncing…, plus Sync failed, with a tooltip for every state.
4. The Build headline repeated the header and led with a label. "Living document · In sync · 2 commits since first build" was all one weight. Now it uses the header's icon and label, with a tertiary detail (✓ In sync · 2 commits since first build, ○ Out of sync · Waiting for @x's agent).
5. Sync-added tasks blended into the original plan. Now they sit in a quiet Since first build section.
6. Mobile: the header slot straddled the page's corner, and PR capsules overflowed the list (bugs). Now the slot sits in the top inset at the trailing edge, and the task grid uses minmax(0, 1fr).
7. A failed first build vanished silently (reason only in a tooltip and an sr-only alert). Now the slot reads Retry build with a warning dot.
8. Spike callouts were wordy and buried the decision. Now they read "Prototype queued" / "Prototyping…" with shorter @handle copy, and a report leads with the recommendation, then findings, then screenshots.

Recommended but not in this PR: hide the header slot while Build is open; list a sync's commits under the task it added; a collapsible result callout; a cancel control on the callout instead of "Delete this callout to cancel"; a label other than "Building…" for a first build that is still queued.

Screenshots

Build view, live and in sync (1440): before / after

Build plan in the narrow layout (390): before / after

Out of sync in the narrow layout (390): before / after

Header slot: sync failed and syncing: before / after

Testing

• bun run types, bun test (4551 pass with the untracked design jigs moved aside), bun run ci, bun run build. The initial chunk is unchanged at 80,590 B gzip; all new code is in the room chunk.
• New and updated unit tests: syncLabel, syncTooltip, liveTaskGroups and the hint copy in build-model.test.ts; spike callout copy and report order in spikes.test.ts; draft exclusion and sync-task acceptance in routes.test.ts. The draft test fails without the fix.
• Checked by hand against the real living document (LIVE_BUILD=on LIVE_SPIKES=on), using route-intercepted snapshots for the out-of-sync, failed and syncing states at 1440 and 390px. Chopin has no dark theme, so there was nothing to check there.
• Not checked visually: "Retry build" (reaching it needs a real failed draft), and the new spike copy on a live callout (existing callouts keep their text until their state changes).
• Verified end to end (second run, 10 Oct) with copilot --acp --allow-all on github.com/MaggieAppleton/margin: the first build of 8 tasks opened margin PRs Let the planner reach for a diagram or a formula #7 to #14, and the live edit "Snooze 15 -> 5" went Out of sync, then Syncing... (+44s), then In sync (+92s) as commit a1f2f553 on the existing PR Add type scale tokens, replace arbitrary font sizes #12. It is listed under "Since first build".

Stack

Stacked on #454 (living-spikes), the top of #450 → #451 → #452 → #453 → #454. This repository merges rebase-only: after a lower PR lands, rebase and push with --force-with-lease.

Adapted to #508

Rebuilt on #454 after #454 moved onto #510. The Build capsule (#508) replaced the header slot and the sync vocabulary, so this PR now holds only the changes that still apply. The seven original commits became three.

Ported unchanged

• Rebuild tasks read plainly ("Updates pull request Let the planner reach for a diagram or a formula #7.", "Matches the document as edited.").
• liveSnapshot lists only task versions that ran, so a Planner draft can't duplicate a built document's tasks. The regression test is kept.
• Spike callouts: "Prototype queued" / "Prototyping…" with @handle copy. Reports lead with the recommendation.
• The build draft instruction says not to prototype a passage that already has a "Prototyping…" callout.
• Wrapped tooltips align to the start.

Adapted to #508's read-only Build view

• A finished task shows its summary instead of its acceptance criteria.
• Blockers lose stacked "Blocked:" labels, and their links are clickable and shortened to owner/repo#N.
• A task the build left unfinished reads as blocked, with the agent's reason, until a rebuild picks it up.
• Rebuild tasks and no-change rebuilds sit under Since first build.
• A queued build shows no elapsed time.
• The task grid uses minmax(0, 1fr), so long titles don't push PR capsules past a phone's edge.
• Build's headline, in Make Build plan explicit and show build status in one capsule #508's vocabulary: "Built · N pull requests · N commits since first build". A build that failed on unfinished tasks names the task to retry and leaves the reason to that task's row.
• attentionHint (the capsule's "Build failed" tooltip) quotes a capped, link-shortened reason and says "retry it" or "retry them".

Dropped as superseded by #508

• The sync vocabulary: syncLabel, syncTooltip, "Syncing…", "Sync failed", the reworded syncHint, and the first flag on SyncStatus. Make Build plan explicit and show build status in one capsule #508 uses Built / N changes to build / Building changes… / Build failed and has no sync wording.
• Header slot changes: hiding while its view shows, data-build-slot, the in-flow status-row CSS and its theme.test.ts, Clock/Decision icons, "Retry build" with a warning dot, the mobile inset placement, and the "Answering this starts the build" line in Decisions. The capsule, its inert Build plan reasons, Retry and the phone glyph cover all of these.
• The Build headline's own icons and sync labels. Make Build plan explicit and show build status in one capsule #508's BuildGlyph headline replaces them, and its detail line is ported above.
• The blocked task dot changing to --color-warning. It stays --color-warning-graphic to match BuildGlyph.
• The empty "Re-run pull request checks" commit.

Review fixes (restack, 2026-10-12)

• Draft instruction. The build draft instruction names every pending prototype callout ("Prototype queued", "Prototyping…", "Prototype paused"). It also says a prototype's result lands after the build, since Prototype uncertain passages inline before the first build (LIVE_SPIKES) #454 now defers it, and treats callout text as data; there is a test.
• Queued first build. I checked that a queued, unclaimed first build still lists its tasks. It has no live record yet, so Build reads the approved graph, and a route test confirms it.
• Decision 1 port. I checked it against the spec: Since first build (liveTaskGroups), the status detail line, no-change rows, finished-task summaries, linkified blockers (linkParts, shortUrl, blockerText), the unfinishedReason and liveTaskState warning dots, and the two-line title wrap. No "sync" wording is user-visible.

🤖 Generated with Claude Code

Second pass

This pass reviewed the new states end to end: waiting on a decision, queued, needs attention, out of sync with blocked tasks, cancel build, and no-change syncs. The full critique is in /tmp/living-design-review/critique-2.md. The after-screens were rendered on a local fake-GitHub server with intercepted snapshots.

Finding	Change
At 390px, a blocker that contains a URL pushed the Build view past the card edge	Status line, task detail and no-change rows wrap long words (overflow-wrap: anywhere)
"Needs attention" printed the full blocker in the status line and again in the row	The status line says what to do (“X” is blocked. Edit the document to retry.); the row shows the reason; the tooltip caps it at about 120 characters
The unfinished task kept a hollow queued ring and stayed collapsed	An outstanding task shows the warning dot and starts open until a sync picks it up
The slot repeated the view you were in (Queued above Queued, Waiting on a decision above Decisions)	The slot hides while the view it opens is showing; "Build plan" stays because it's an action
A hollow ring meant a queued task, Queued, Out of sync and Waiting on a decision	Rings are for task states only; the slot and status line use a clock for waiting, the decision glyph for a decision, and the warning dot for attention
"Queued · … 0m"	A queued build shows no timer
"Your edits will sync shortly · will also retry 1 blocked task"	One clause: "Your edits and 1 blocked task will sync shortly" (and matching waiting or failed copy)
No-change rows had no glyph and a time centred against long text	A tertiary check in the dot column; the time sits on the first line

Not changed (recommended): agent prose is long (it needs a server-side summary and details split); a stale task survives a no-change sync; spike callouts still say "Delete this callout to cancel".

Blocker at 390px

Needs attention at 1440px

Unfinished task

Queued

Waiting on a decision

Out of sync

No code change rows

Final pass

• Unfinished rows say why: the agent's last report, else where it stopped. The headline names the task an edit retries.
• Blockers drop stacked "Blocked:" labels. GitHub links show as owner/repo#N, and the row links them.
• The warning dot shares the reason's --color-warning family. Wrapped tooltips are left-aligned.
• Decisions shows "Answering these starts the build." while a one-click build waits on them.
• The Build headline lines up with the task titles at both widths.

Last pass

A real run on margin confirmed the spike lands before a queued build starts. Its result reached the first build, and no rebuild followed the callout. Two rough edges remained:

• The first build no longer flashes "Syncing…" in its last seconds. It keeps "Building…" until it ends. "Syncing…" now only means a rebuild after an edit.
• A one-click build started during a spike no longer adds a task that prototypes the same passage again. The implementing task follows the spike's result.