docs: triage mobile feedback and close phase 1b

Author: backnotprop

adr/research/SPIKE-mobile-web-compatibility-20260812.md

@@ -291,12 +291,12 @@ Five of eight checks fail clearly on phone:
 
 | ID | Priority | Evidence | Finding | Impact | Direction, not specification |
 |---|---|---|---|---|---|
-| MOB-010 | P1 | Physical iPhone + WebKit-confirmed; bottom behavior passed, top correction awaiting retest | Roots follow the observed visual viewport and the primary composers consume shared reactive bounds. Compact coarse-pointer Plan now uses the actual document scroller, propagates that viewport through navigation/selection consumers, and allows the document to continue behind Safari's collapsing bottom controls; the physical iPhone pass confirmed the bottom controls dismiss and the former cutoff is gone. That pass exposed the matching top-edge issue: the 48 px Plannotator header remained `position: sticky; top: 0`, so it was partly obscured and Safari preserved an opaque extension instead of the softer page-under-chrome treatment. WebKit explains that this solid extension is deliberately applied when fixed/sticky content borders an obscured viewport edge ([WebKit #301756](https://bugs.webkit.org/show_bug.cgi?id=301756#c2)). Compact touch Plan now lets the app header scroll in normal flow and disables both duplicate sticky Plan action treatments; desktop keeps all incumbent sticky behavior. | Bottom document reachability now matches ordinary Safari sites. The top correction must still prove that both Safari bars contract normally, the Plan is not clipped, and no sticky product chrome recreates the opaque extension. Code Review remains a separate phase because its multi-panel workspace cannot inherit Plan's reading-page composition unchanged. | Retest upward/downward page scrolling with attention to the shrinking top address bar and content visible beneath it, then repeat composer/keyboard/rotation checks before passing 1B. |
+| MOB-010 | P1 | Physical iPhone + WebKit-confirmed; Checkpoint 1B passed | Roots follow the observed visual viewport and the primary composers consume shared reactive bounds. Compact coarse-pointer Plan uses the actual document scroller, propagates that viewport through navigation/selection consumers, and allows the document to continue behind Safari's collapsing controls. The compact touch header now scrolls in normal flow and both duplicate sticky Plan action treatments are disabled; desktop keeps all incumbent sticky behavior. The final physical pass confirmed that both Safari chrome regions contract normally, the prior bottom cutoff is gone, the top is no longer obscured by a sticky application edge, and the artifact remains visible beneath the browser's translucent controls. This matches WebKit's documented distinction between body scrolling and nested scrolling ([WebKit #240861](https://bugs.webkit.org/show_bug.cgi?id=240861)) and its solid extension around fixed/sticky edge content ([WebKit #301756](https://bugs.webkit.org/show_bug.cgi?id=301756#c2)). | The Plan reading surface now behaves like an ordinary Mobile Safari page instead of a fixed desktop application viewport. Code Review remains a separate phase because its multi-panel workspace cannot inherit Plan's reading-page composition unchanged. | Preserve the document-scroll/sticky-edge contract during later Plan work; apply an independently designed mobile workspace contract to Code Review. |
 | MOB-011 | P1 | Measured platform risk, Medium; primary fix implemented, physical gate pending | `data-pn-mobile-editable` now makes the primary Plan and Code Review authoring inputs compute to 16 px on compact/coarse surfaces without enlarging desktop labels or diff text. Deferred search, Settings, Ask AI, prompts, and source editing remain inventoried. | The primary Safari focus-zoom trigger is removed; unconverted secondary authoring inputs can still destabilize their later flows. | Verify no focus zoom on iPhone/iPad, then adopt the same marker as each deferred surface is implemented. |
 | MOB-012 | P2 | Source-confirmed platform risk, Medium; shared contract implemented, physical gate pending | Entry viewports now opt into `viewport-fit=cover`; CSS-owned safe-area variables protect the application stage and the primary portaled comment overlays. Historical secondary fixed panels remain inventoried for their owning phases. | Converted primary paths have one inset owner; unconverted secondary chrome can still overlap landscape notches or the home indicator. | Verify the primary overlays on notched iPhone/iPad hardware, then migrate later bottom-edge surfaces without double-counting root insets. |
 | MOB-013 | P2 | Observed + source-confirmed, High | `useIsMobile()` is `<768`; exactly 768 px is desktop. Plan also defaults the right panel open at `window.innerWidth >= 768`. | iPad portrait receives a 288 px empty rail and a squeezed document. | Base composition on available artifact width and input capability, not a single phone/desktop cutoff. |
 | MOB-014 | P2 | Source-confirmed, High | Settings is a centered desktop dialog; at 320 px its tab nav is 286 px wide with 585 px scroll content and its identity input is 13 px. | Settings are technically reachable but clipped/discoverability- and zoom-prone. | Treat settings as a mobile route/sheet with explicit section navigation and 16 px inputs. |
-| MOB-031 | P1 | Physical iPhone, High; Checkpoint 1B implemented, physical rerun pending | The primary Plan and Code Review composers now use the visible viewport, 16 px compact/coarse editables, non-forcing touch focus, reachable dismiss/submit controls, and draft recovery. Responsive browser checks passed down to 320×568 and a 390×500 keyboard-sized viewport. | The original phone failure is addressed in implementation, but Mobile Safari software-keyboard, safe-area, rotation, and background/return behavior are not proven by Chromium. | Repeat the full comment journey over Tailscale on iPhone and iPad; physical evidence wins over the responsive preflight. |
+| MOB-031 | P1 | Physical iPhone, High; Checkpoint 1B accepted | The primary Plan and Code Review composers use the visible viewport, 16 px compact/coarse editables, non-forcing touch focus, reachable dismiss/submit controls, and draft recovery. Responsive browser checks passed down to 320×568 and a 390×500 keyboard-sized viewport. The physical iPhone pass confirmed legible Plan input, intentional keyboard opening, no Safari focus zoom, successful save, and stable browser-chrome behavior; the user accepted the remaining previously exercised input behaviors without requesting a redundant rerun. | The primary phone composition contract is accepted. A separate physical iPad matrix and secondary authoring surfaces remain unproven and keep their own inventory entries. | Carry the shared editable/viewport contract into each later authoring surface and complete the iPad pass during 1C/final Phase 1 validation. |
 
 ### Hierarchy and noise issues
 

adr/research/synthesis-mobile-feedback-triage-20260812.md

@@ -0,0 +1,185 @@
+# Synthesis: Mobile Feedback Triage and Phase Sequence
+
+Date: 2026-08-12
+Status: Phase 1B accepted; Phase 1C scoped for implementation review
+Source dossier: [`SPIKE-mobile-web-compatibility-20260812.md`](./SPIKE-mobile-web-compatibility-20260812.md)
+Foundation spec: [`mobile-platform-foundation-phase1-20260812.md`](../specs/mobile-platform-foundation-phase1-20260812.md)
+
+## Decision
+
+The accumulated physical-device review is sufficient. Do not ask the reviewer
+to repeat the Phase 1B composer checklist. The Safari stage failure was the
+blocking defect, and the final iPhone pass confirmed its correction.
+
+Work now proceeds in this order:
+
+1. **Phase 1C — shared touch and dialog contract.** Finish the small,
+   capability-gated foundation without rearranging either product surface.
+2. **Phase 2A — mobile Code Review shell and arrival.** Replace the minified
+   desktop composition with one primary phone surface and transient secondary
+   navigation/context.
+3. **Phase 2B — mobile Plan shell and navigation.** Reduce persistent Plan
+   chrome, restore the blocked folder/multi-file path, and stabilize edit and
+   completion controls.
+4. **Phase 3 — touch selection and annotation semantics.** Prototype and
+   validate multi-block Plan selection and multi-line Pierre selection as
+   dedicated interactions.
+
+This order is not a ranking of product importance alone. It separates shared
+mechanical safety from information architecture, then separates layout from
+the harder selection semantics. That keeps every review gate understandable
+and prevents a phone workaround from mutating desktop preferences.
+
+## Closed or already moving in parallel
+
+| Area | Disposition | Evidence / constraint |
+|---|---|---|
+| Tailscale installation and HTTPS Serve | Working | Physical iPhone sessions opened through the tailnet and returned real Plan and Review feedback. |
+| Mobile Safari page stage | Closed in 1B | Body scrolling and non-sticky compact Plan chrome now allow both Safari control regions to collapse; the user passed the result. |
+| Primary comment composition | Closed in 1B | 16 px authoring text, deliberate touch focus, visible-viewport bounds, draft recovery, and explicit Save are implemented. |
+| Release / first-use noise | Parallel stack already implemented | The release promo became a compact Grid/Clean decision; Vim, Ask AI, and analysis-layer startup announcements no longer mount. Features remain in Settings and their real surfaces. |
+| New-user Code Review panel default | Merged independently | `origin/main` includes the Tree-first change. Mobile presentation must not overwrite that desktop-first product default. |
+| Guided Review intro | Preserve | The reviewer found the initial Guide explanation useful. Guide is a strong candidate for mobile comprehension, not noise to remove. |
+| Edit Code to Suggest | Preserve | The tested dialog was acceptable; suggestion editing is not pulled into the next layout phase. |
+| All Files | Preserve and learn from | It was the cleanest Code Review presentation observed on the phone. |
+
+## Triage matrix
+
+`Now` means the next implementation checkpoint. `Next` is the first structural
+surface phase. `Later` means deliberately deferred, not forgotten.
+
+| Owner | Findings | Severity | Why grouped here | Disposition |
+|---|---|---:|---|---|
+| Closed in Phase 1B | MOB-010, MOB-031 | P1 | Safari page-stage and primary composer defects passed the physical iPhone gate. They remain regression contracts, not open design work. | **Closed / protect** |
+| Phase 1C: shared touch/dialog | MOB-005, shared portion of MOB-012, shared dialog portion of MOB-014/MOB-030/MOB-032 | P1 | Undersized shared controls and unbounded shared dialogs are mechanical platform defects. Fixing the primitives first gives later layouts safe components without deciding their IA. | **Now** |
+| Phase 2A: Review shell/arrival | MOB-002, MOB-003, MOB-017, MOB-020, MOB-021, MOB-030, MOB-032, MOB-033 | P1 | These are one failure: desktop workspace regions remain simultaneous on a phone. Fixing panels separately would preserve the wrong composition. | **Next** |
+| Phase 2B: Plan shell/navigation | MOB-001, MOB-004, MOB-013, MOB-015, MOB-016, MOB-018, MOB-019, MOB-028 | P0/P1 | Plan reading now works, but navigation, editing completion, auxiliary arrival state, and persistent annotation chrome still fail or dominate. Folder navigation is the only current P0. | **After 2A** |
+| Phase 3A: Plan touch selection | MOB-008, MOB-009, MOB-029 | P1 | Pinpoint proves tap targeting can work, but ordinary native selection conflicts with Safari and multi-block intent has no interaction model. This needs prototypes, not CSS. | **Later, prototype first** |
+| Phase 3B: Review touch selection | MOB-006, MOB-007 | P1 | Single-line selection works; extending a range does not. Pierre rendering and line mapping are regression-sensitive and need their own guarded physical-device gate. | **Later, Pierre-guarded** |
+| Surface hardening | MOB-011 secondary inputs, MOB-014 Settings, MOB-022 HTML, MOB-024 diagnostics | P2 | These are real but should adopt the shared contract within their owning surfaces rather than expanding the first structural phase. | **Later** |
+| Delivery/performance/trust | MOB-023, MOB-025, MOB-026, MOB-027 | P1/P2 | Payload, tailnet trust, hook handoff, and reconnect behavior are cross-cutting delivery work, not layout work. They can be researched in parallel without changing current mobile IA. | **Independent track** |
+
+## Immediate next implementation: Phase 1C
+
+### Outcome
+
+Shared buttons and shared dialog close controls are physically safe to touch,
+shared dialogs remain reachable inside the visible Safari viewport, and fine-
+pointer desktop geometry is unchanged.
+
+### In scope
+
+- Introduce the shared `--pn-touch-target` token and
+  `data-pn-touch-target` marker.
+- Apply coarse-pointer 44×44 minimum hit regions to the two incumbent shared
+  button primitives and the shared dialog close control.
+- Bound the shared dialog primitive to the visible viewport and safe-area
+  contract established in 1A/1B.
+- Gate hover-only effects to hover-capable fine pointers in touched primitives.
+- Provide immediate, restrained press feedback and a reduced-motion path.
+- Convert only representative shared dialogs needed to prove the contract.
+- Verify iPhone and iPad geometry, including hybrid iPad touch plus pointer.
+
+### Explicitly out of scope
+
+- No mass expansion of every hand-authored Plan or Review toolbar control.
+- No Plan toolstrip redesign, bottom action bar, or mobile navigation.
+- No Code Review panel, Dockview, header, Guide, or diff composition change.
+- No Split/Unified preference write based on viewport.
+- No Pierre, `DiffViewer`, line-selection, or suggestion-editing changes.
+- No new sheet system or visual language.
+
+### Implementation seam
+
+The expected source boundary remains:
+
+- `packages/ui/theme.css`
+- `packages/ui/components/ui/button.tsx`
+- `packages/ui/components/core/button.tsx`
+- `packages/ui/components/ui/dialog.tsx`
+- focused component and geometry tests
+
+If a correct 44 px target breaks a dense hand-authored row, record it for its
+surface phase rather than introducing an undocumented compact exception.
+
+### Gate for the next joint review
+
+The checkpoint is ready for review when:
+
+- representative button and dialog-close hit boxes measure at least 44×44 on
+  a coarse pointer and do not overlap;
+- a shared dialog at 320×568, 390×844, and keyboard-reduced height keeps its
+  close control and primary action reachable;
+- press feedback appears on touch-down without leaving sticky hover styling;
+- reduced-motion and hardware-keyboard dismissal remain functional;
+- iPad portrait/landscape and a touch-plus-trackpad path remain usable;
+- desktop screenshots and computed geometry show no layout change under a
+  fine pointer;
+- production Plan and Review builds, focused tests, and typecheck pass.
+
+The reviewer should expect a short physical-device check of representative
+controls and one shared dialog—not another end-to-end Plan or Code Review
+critique.
+
+## Phase 2A preview: mobile Code Review shell and arrival
+
+Phase 2A is the first structural redesign. Its job is to make the review
+artifact, not the desktop workspace, own the phone viewport.
+
+### Fixed principles
+
+- One primary full-width surface at a time on phone.
+- Tree remains the best new-user desktop default and is never overwritten by a
+  mobile presentation decision.
+- File navigation, PR context, annotations, AI, and agents become transient
+  phone surfaces instead of flex siblings that squeeze the diff.
+- Empty PR sections do not render structure merely to announce absence.
+- The phone header exposes location, navigation, and one contextual action;
+  desktop-only controls move behind progressive disclosure.
+- A phone-friendly Unified presentation may be a session/device override, but
+  it must not rewrite the user's desktop Split preference.
+- Guide and All Files are the two strongest observed mobile starting points.
+  The entry decision should be made through working prototypes and physical
+  review, not assumed from responsive screenshots.
+
+### Phase 2A review gate
+
+Before implementation is accepted, the reviewer will compare at least two
+working phone compositions using the same GitHub PR:
+
+1. artifact-first All Files / Unified arrival;
+2. Guide-first arrival with a direct route to the raw diff.
+
+The chosen composition must preserve desktop behavior, make file/PR context
+reachable without narrowing the artifact, keep the destination decision fully
+visible, and support a complete single-line comment and approve/send journey.
+Multi-line touch selection is explicitly evaluated in Phase 3, not used as a
+gate for the shell.
+
+## Why selection is not bundled into layout
+
+The user's Plan feedback established that Pinpoint is currently the only
+reliable touch path. A tap opens its contextual toolbar; Comment then opens the
+composer. Ordinary Select taps do nothing, native drag selection invokes the
+iOS Copy / Find Selection menu, and neither Plan nor Code Review offers a
+credible way to accumulate several logical targets.
+
+This is not a hit-box bug. It is an unresolved gesture and state model. The
+selection phase must prototype explicit accumulation, visible range state,
+cancel/undo, scroll coexistence, and assistive-technology behavior. Review
+selection must additionally preserve Pierre's line mapping and desktop mouse
+range selection. Treating it as incidental work inside a layout PR would make
+both changes harder to review and easier to regress.
+
+## Desktop preservation contract
+
+Every phase keeps these invariants:
+
+- mobile presentation state is ephemeral or device/session-scoped;
+- desktop Tree/Split/panel preferences are never rewritten by phone width;
+- fine-pointer geometry and keyboard shortcuts remain incumbent unless the
+  phase explicitly names a desktop defect;
+- shared changes are capability-gated and tested in a strict
+  `@plannotator/ui` consumer;
+- no existing working surface is deleted until physical and desktop parity is
+  confirmed.