waggle-os/docs/ux-refactor/path-exec-phase-A2-spec-2026-07-07.md

Path-to-9 execution · PHASE A2 — complete the retrofit (R2/R3 died mid-flight) + V1/V2 findings

Continues docs/ux-refactor/path-exec-phase-A-spec-2026-07-07.md after checkpoint f2ab5896.

V1-motion reviewer FAILED acceptance with exact findings — they are the contract below.

Same house rules. Per-lane gate: related vitest + eslint 0 errors. NO benchmarks/**, NO hive-mind.

STAGE 1 (parallel — disjoint files)

Lane R2 (retry) — memory + briefing + boot + theme retrofit

Files: os/BootScreen.tsx, apps/memory/MemoryTrustManage.tsx, apps/memory/MemoryCenterTab.tsx, providers/ThemeProvider.tsx, os/overlays/LoginBriefing.tsx, tests. Do NOT touch index.css (Stage-2 Lane R3 owns it) — ThemeProvider's JS-side 420ms timer aligns to the token value via a shared constant/var read, or a comment-justified literal if the CSS var isn't readable there. V1's exact survivors to tokenize (verify each live, then migrate to --mo-*/DUR/SPRING/STAGGER):

• BootScreen.tsx L89/144/151/163/182/194 — raw 0.5/0.3/0.4/0.2s + easeIn/Out.
• MemoryTrustManage.tsx L257 'card-enter 0.32s ease-out' + L605 '0.15s'.
• MemoryCenterTab.tsx L399 '0.15s'.
• LoginBriefing.tsx L297 raw duration:0.2 + ease:'easeOut' + local ENTER_STAGGER=0.08 literal → STAGGER.brief / DUR.base / EASE_OUT imports from lib/motion/tokens. Tokenize, don't retune (values stay; only the source of truth changes). Reduced-motion behavior of every migrated site must match the REDUCED mapping (most already gate via useReducedMotion — verify, don't assume).

Lane F2 — floor residuals + runtime-gate hardening

Files: locate-and-fix the THREE real near-AA residuals (V2's list, verify each live with computed ratios before/after in the report): dark "workspace" label 4.38:1 (--text-dim over --surface — likely Sidebar workspace sublabel), light "Solo" tier label 4.47:1, light "Models" section label 3.88:1 (/settings). Informative text → --text-tertiary (or the correct existing AA token); decorative-only text may stay dim WITH a justifying comment. Plus scripts/ux-gates/contrast-runtime.mjs hardening: detect no-opaque-ancestor / animating-opacity subtrees (the TrialExpiredModal false-positive cluster at 1.15–2.09:1 and the two 'Fallback' 1.0:1 rows) and screenshot-sample those instead of CSS compositing. Do NOT seed the baseline (post-stage-2 job — the tree is still moving).

STAGE 2 (parallel — disjoint files; stage 1 merged)

Lane R3 (retry) — chat + status chrome + index.css + THE INVENTORY TRUTH

Files: apps/ChatApp.tsx, os/StatusBar.tsx, apps/WorkspaceDesktopApp.tsx, apps/web/src/index.css (reduce block + .theme-transition), pages/MotionSpec.tsx, tests. V1's exact findings to close:

1. index.css .theme-transition L698 raw 360ms → var(--mo-slow) (or a dedicated --mo-theme var if 360≠320 is deliberate — decide, justify in-comment; keep ThemeProvider's JS timer consistent, coordinate value with what R2 left there).
2. index.css reduce block gates only 5 classes: extend @media (prefers-reduced-motion) to cover EVERY in-use animated class per the REDUCED mapping — specifically honey-pulse (used by StatusBar L152 with NO guard) and float (ChatApp L1003, unconditional). Audit the rest of the @keyframes zoo: every class used in components either appears in the reduce block or its component gates via useReducedMotion.
3. Dead inventory claims: 'hex-cursor caret static' and 'send-flash instant' are table text with NO component applying those classes — either wire the real behavior or mark the rows honestly as N/A-dead-class (do not fabricate).
4. Tokenize remaining raw durations in ChatApp (finish the partial edit), StatusBar, WorkspaceDesktopApp.
5. MotionSpec inventory TRUTH (V1 blocking #3): the inventory currently claims '✓ R2' / 'ambient ✓' / 'signature ✓' for work that never landed and an honesty note stating rows are 'applied in THIS commit' falsely. Rebuild the table from the ACTUAL tree state after your own edits (grep, don't trust prior rows); every row's status must be verifiable. The inventory misrepresenting reality is worse than no inventory.

Lane R4 — the sweep: zero unjustified raw motion on judged surfaces

Files: everything under apps/web/src/components/os/** NOT owned by another lane this phase (EXCLUDED: BootScreen, MemoryTrustManage, MemoryCenterTab, LoginBriefing, ChatApp, StatusBar, WorkspaceDesktopApp, AllWorkspacesApp, SuggestedAgentCards, ExtensionCard, onboarding WelcomeStep/WhoAreYouStep) + their tests. Method: grep the scope for raw durations/easings (duration-NNN, duration-[NNNms] non-var, duration: 0.N, transition inline styles, ease-out/in literals where a token exists); migrate each to --mo-*/DUR/EASE_OUT; a site that is deliberately non-standard keeps a one-line justifying comment instead. Report the FULL before/after list. Acceptance = V1's criterion: zero UNJUSTIFIED non-token durations/easings across os/**.

VERIFY (after stage 2)

• V1'-motion (adversarial re-run): the same acceptance V1 failed — grep os/** for unjustified raw motion (report every survivor), confirm the reduce block + component guards cover every in-use animated class, confirm the MotionSpec inventory now matches the tree (spot-verify 6 rows with grep), run the motion token tests.
• V2'-runtime: run contrast-tokens + text-color-guard (must stay green); run the HARDENED contrast-runtime on /home + /settings both themes against the dev server (vite 8080 — if down, start per handoff recipe or report inability); confirm the three residuals now pass and the TrialExpiredModal cluster no longer false-positives; then SEED contrast-runtime-baseline.json from this clean run (triage: the baseline must contain only verified-acceptable rows, listed in your report) and re-run to prove exit 0.

Orchestrator after verify

tsc web + full apps/web vitest + all three ux-gates green → commit "Phase A complete" → launch Phase B (docs/ux-refactor/path-exec-phase-B-spec-2026-07-07.md).