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.

🤖 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.

[coolify-githubnext-app]

The preview deployment for chopin failed. 🔴

Open Build Logs | Open Application Logs

Last updated at: 2026-10-10 20:16:32 CET