Stream Deck: phase-aware review dials — canvas navigation reuses the diff dials (deck half; bridge is #1401)

[amrmelsayed]

Context

Revised 2026-08-12 per owner direction, unifying with the #1410 two-zone grammar. Supersedes the original reserved-headroom layout (separate canvas actions squeezed into reserved slots on the fleet layout).

The owner's insight driving the revision: when the selected builder is in spec or plan state there is no diff yet, so the two diff dials (Files / Changes) are idle exactly when the artifact canvas is the thing being reviewed. Reuse them.

The canvas's keyboard-first review (#1237/PR #1344) and horizontal reading mode (#1380/PR #1398) define the navigation vocabulary; #1401 builds the bridge (Tower relay + sendCanvasCommand on the sdk controller subpath) that lets the deck drive it.

The unifying rule

The review dials always review the selected builder's current work; the builder's phase determines its form. Gesture roles are constant: rotate = navigate, press = give feedback at the current position, tap = jump. Only the artifact form changes:

Selected builder's state	Coarse dial (today: Files)	Fine dial (today: Changes)	Press	Tap
implement / review, or blocked at dev-approval / pr	files (unchanged)	hunks (unchanged)	forward file/hunk as feedback (unchanged)	jump to first (unchanged)
specify / plan, or blocked at spec-approval / plan-approval	heading step	block step	composer-open on the focused block	jump (first commented block vs doc start: spec decision)

Phase/gate resolution uses the same wire-value source as #1404's Automatic press (blockedGate beats protocolPhase; never guessed strings) — reuse that resolver family.

Requirements

1. Phase-aware dial semantics per the table above, keyed to the selected builder (the shared cursor that Stream Deck: merge Fleet Slot into Builder Action (phase-aware press) #1404's press sets).
2. Legibility rule (hard requirement): each dial's touchstrip always names its current semantic (e.g. Headings / Blocks vs Files / Changes). A gesture must never be a surprise. Shared grammar with Stream Deck SD+: two-zone builder workflow (selectors + action palette, dial-driven feedback queue) #1410 requirement 4.
3. Targeting: file-qualified to the selected builder's artifact via sendCanvasCommand's file selector — coherent with semantics following the selection; a no-canvas result renders on the dial (the artifact isn't open; press the builder's key to open it). The workspace-MRU alternative (drive what you see) is the fallback position; the spec/plan phase records the final choice with rationale. In practice they converge because Stream Deck: merge Fleet Slot into Builder Action (phase-aware press) #1404's press opens the selected builder's artifact.
4. Reading-mode toggle placement is a spec-time layout call (touchstrip tap, a Row 2 slot when Stream Deck SD+: two-zone builder workflow (selectors + action palette, dial-driven feedback queue) #1410 lands, or deferred).
5. Column paging in horizontal mode: spec-time mapping (candidate: coarse dial while reading mode is on).
6. Text entry stays on the keyboard. Composer typing, submit, and cancel are keyboard acts (deck-driven submit/cancel is a spec-time decision; default no).
7. Built on artifact-canvas: remote command channel for review navigation (Tower relay + sdk route) #1401's sendCanvasCommand; no bridge changes (both targeting modes are already supported by the spec'd selector).

Layout consequence

No reserved keys on the fleet layout are needed anymore — this resolves the eight-key conflict noted on #1410 (see its architect review). At most one small affordance (reading-mode toggle) remains a layout question.

Out of scope

• The bridge itself (artifact-canvas: remote command channel for review navigation (Tower relay + sdk route) #1401).
• The fleet action palette and feedback queue (Stream Deck SD+: two-zone builder workflow (selectors + action palette, dial-driven feedback queue) #1410).
• The vscode builder-diff comment queue (vscode: codelens-driven review comments in the unified diff editor — per-builder queue with batched submit to PTY (follow-up to #789) #1037/vscode: codelens-driven review comments in the builder diff — per-builder queue with batched submit to PTY (#1037) #1382/vscode: contextual bottom panel that adapts to active editor (mode resolver + Attention fallback) #1049).

Sequencing

After #1401's sdk call exists (unchanged). Independent of #1410's delivery — this ships on the existing dial layout.

Suggested protocol

PIR: the phase-switching dial flows and touchstrip legibility need hardware verification before a PR.

[amrmelsayed]

Prioritized by the owner (2026-08-11): this is the streamdeck lane's next build. #1381's 15-key profile is parked behind it (see #1381).

Critical path is therefore #1401's sdk call. Per the split agreement, the streamdeck lane reviews that call's surface shape at design time; requesting the bridge move to spec so this can spawn.

[amrmelsayed]

On it! Working on this with the PIR protocol (plan + dev-approval gates before PR).

[amrmelsayed]

Targeting decision (2026-08-12): workspace-MRU for v1. Requirement 3's file-qualified preference is superseded; MRU (the recorded fallback) is the v1 behavior, decided jointly: streamdeck architect (this lane) + main as codev-types stakeholder (wire-contract verdict on their verification that OverviewBuilder carries worktreePath only — file-qualified targeting genuinely needs an additive Tower-computed wire field, out of this issue's scope).

Grounds: (1) convergence — #1404's press opens and focuses the selected builder's artifact, making it the MRU view, so 'drive the MRU' IS 'drive the selected builder's artifact' in the real workflow; (2) the mental model is clean — the selected builder's phase picks the dial mode; the dials drive the canvas you're looking at; (3) the upgrade path is additive and preserved — a future OverviewBuilder.specPath/.planPath field (specced with main when pursued) plus a one-line deck change flips targeting to file-qualified with no redesign.

This is architect wire-contract input folded into the plan question; plan-approval remains the human gate.