type: meta

slug: zync-os-mobile

base_branch: master

gate0_mode: strict

preset: codex

land_mode: merge-to-main


type: goal

text: Plan B: mobile OS shell (home/dock/drawer/fullscreen apps/recents/shade) + module migration sweep so every in-scope module opens windowed on desktop and full-screen on mobile. Spec docs/specs/2026-07-11-zync-os-mobile-design.md is source of truth (SHIPPED after 9 codex gpt-5.6-sol/high review rounds).


type: methodology

text: Spec pins contracts; plan doc pins files/waves/acceptance; tasks POINT to spec sections, never restate. Premium-feel physics live ONLY in .claude/skills/zc-ui-ux-designer (SKILL.md + references/mobile.md + desktop.md) — REQUIRED READING for every UI task; vision judge (codex models, never Claude) grades against it. TDD per task; verify subagent claims by opening files; re-audit before firing any stale work-list.


type: intent

text: Ship the OS experience to mobile users and finish the module migration so classic shell becomes legacy-fallback-only, completing Phase 3-4 of the Zync OS vision on the landed Plan A foundation.


type: direction

verbatim: make sure that all the physics of the premium feel are actually in the specs, since cheaper models cant think like that


verbatim: if it's IN the spec, fully implement; don't ask whether to build spec'd scope


type: gated

category: policy

needs: confirm base branch

why: Plan A landed on master (merge a37d90d1); verify it is an ancestor of origin/master at pre-flight

status: RESOLVED

answer: proceed

resolved_by: user

source: author


type: anchor

what: design doctrine (+ references/mobile.md, references/desktop.md)


type: task

seat: coder

tier: low

desc: Read docs/plans/2026-07-11-zync-os-mobile.md Task 1 (Layout schema unification) for the full contract; spec §6. Shared zod source in packages/modules imported by server route + client; device desktop|mobile; principal-keyed localStorage mirrors + legacy key migration. Acceptance: pnpm --filter zync-api test -- shell-layout PASS + desktop suites green. Commit only: packages/modules/src/shell-layout-schema.ts, apps/zync-api/src/routes/shell-layout.ts (+tests), apps/zync-app/src/os/shell-layout-schema.ts, apps/zync-app/src/os/OsShell.tsx.


tier: high

desc: Read docs/plans/2026-07-11-zync-os-mobile.md Task 2 (canDiscard blocker signal plane) for the full contract; spec §3. ShellBlockerContext + useShellBlocker + useAppMutation in packages/ui; guards.ts registry + canDiscard. Acceptance: pnpm --filter zync-app test -- guards PASS (full unit matrix). Commit only: packages/ui/src/shell/*, apps/zync-app/src/os/guards.ts (+test), apps/zync-app/src/os/window-router.tsx, packages/ui form/dialog wiring files.


desc: Read docs/plans/2026-07-11-zync-os-mobile.md Task 4 (Manifest metadata single owner) for the full contract; spec §2 NORMATIVE table. All os+mobile metadata + UNOWNED allowlist + ownership invariant test; manifest.ts + registry-os.ts then FROZEN. Acceptance: ownership completeness vitest green + typecheck. Commit only: packages/modules/src/manifest.ts, apps/zync-app/src/os/registry-os.ts (+invariant test file).


desc: Read docs/plans/2026-07-11-zync-os-mobile.md Task 5 (Audit) for the full contract; spec §7(a). Verify §2 table vs live route registry (conflict → ESCALATE, never re-decide); violation counts; ad-hoc dirty-editor work-list; cluster partition for t16-t25. Acceptance: artifact complete, zero unresolved conflicts. Commit only: docs/plans/audit/zync-os-mobile-sweep-audit.md.


desc: Read docs/plans/2026-07-11-zync-os-mobile.md Task 6 (Skill alignment) for the full contract; spec §7(a2). Amend references/mobile.md: registry presentation fullscreen-only; sheet language = dialog adaptation only. Acceptance: grep for registry-level sheet claims → 0. Commit only: .claude/skills/zc-ui-ux-designer/references/mobile.md.


desc: Read docs/plans/2026-07-11-zync-os-mobile.md Task 7 (SW cache isolation BLOCKER fix) for the full contract; spec §8. /api/* + authed files/images NetworkOnly; static-assets-v2 build-asset allowlist; legacy caches deleted; purge message with MessageChannel ack. Acceptance: cross-user offline e2e PASS. Commit only: apps/zync-app/src/sw.ts, apps/zync-app/src/hooks/useServiceWorker.ts, logout call site, new e2e spec.


desc: Read docs/plans/2026-07-11-zync-os-mobile.md Task 8 (BottomSheet + presentation context + dialog adapter) for the full contract; spec §4+§7(c), physics per references/mobile.md detents. Acceptance: adapter fixture PASS incl. modal passthrough + destructive annotations. Commit only: packages/ui/src/sheet/*, packages/ui/src/shell/presentation-context.ts, packages/ui Dialog/Modal files, annotated destructive call sites.


desc: Read docs/plans/2026-07-11-zync-os-mobile.md Task 3 (Mutation codemod sweep) for the full contract; spec §3. useMutation → useAppMutation across apps/zync-app/src (EXCLUDING src/os/**) + ESLint no-restricted-imports gate. Acceptance: grep 0 direct call sites; lint+typecheck+tests green. Commit only: swept files + eslint config.


desc: Read docs/plans/2026-07-11-zync-os-mobile.md Task 9 (Shell mode × device class) for the full contract; spec §1. Delete classic early-return; predicate becomes class fork; ui_shell_device pref (migration + PATCH + settings UI); no hot-swap. Acceptance: shell-mode unit matrix PASS. Commit only: apps/zync-app/src/os/shell-mode.ts (+test), new migration, preferences route, Interface Settings file.


desc: Read docs/plans/2026-07-11-zync-os-mobile.md Task 10 (Mobile shell store) for the full contract; spec §3 shapes verbatim. Cap 6 + LRU via canDiscard + cap-exhaustion reject. Acceptance: store unit matrix PASS. Commit only: apps/zync-app/src/os/mobile/mobile-shell-store.ts (+test).


desc: Read docs/plans/2026-07-11-zync-os-mobile.md Task 11 (url-sync mobile branch) for the full contract; spec §5. zync-wrapped union + surface; /home dedup; popstate matrix; cold-entry replaceState. NOTE: shell-mode.ts alias rewrite may fold into t9 if line conflict. Acceptance: url-sync unit matrix PASS. Commit only: apps/zync-app/src/os/url-sync.ts (+test), apps/zync-app/src/os/OsShell.tsx, shell-mode.ts alias lines.


desc: Read docs/plans/2026-07-11-zync-os-mobile.md Task 12 (Mobile surfaces — shell core) for the full contract; spec §4 + REQUIRED READING references/mobile.md. MobileShell/Home/Icon/Dock/Drawer/AppFrame/NavBar. Acceptance: behavioral probes PASS + axe clean. Commit only: apps/zync-app/src/os/mobile/{MobileShell,MobileHome,MobileAppIcon,MobileDock,AppDrawer,MobileAppFrame,MobileNavigationBar}.tsx (+probe specs).


desc: Read docs/plans/2026-07-11-zync-os-mobile.md Task 13 (Mobile surfaces — panels) for the full contract; spec §4 + references/mobile.md. Recents/shade/top strip + command-center fullscreen variant + top toasts. Acceptance: probes PASS + axe clean. Commit only: apps/zync-app/src/os/mobile/{RecentApps,NotificationShade,MobileTopStrip}.tsx, command-center panel variant, toast adapter (+probe specs).


desc: Read docs/plans/2026-07-11-zync-os-mobile.md Task 14 (Verification scaffold) for the full contract; spec §Verification program. 6 mobile playwright projects incl. WebKit, gesture probes, baselines, slopgate globs, PWA named checks. Acceptance: mobile suite green on built shell; baselines recorded. Commit only: playwright config, new test/probe/baseline files, slopgate config.


desc: Read docs/plans/2026-07-11-zync-os-mobile.md Task 15 (Boot wiring + lazy split + usability) for the full contract; spec §1 boot + §Usability. MobileShell lazy chunk + build assertion; coach marks; escape hatches; telemetry. Acceptance: build assertion green + coach-marks e2e PASS. Commit only: apps/zync-app/src/main.tsx, coach-mark/escape-hatch/telemetry files, build assertion script.


desc: Read docs/plans/2026-07-11-zync-os-mobile.md Tasks 16-25 (Module sweep) — cluster PROJECTS. Spec §7 DONE definition (4 items) + audit artifact partition. Acceptance: cluster playwright spec PASS desktop+mobile + violation greps 0 + classic suites green. Commit only: apps/zync-app/src/os/bindings/projects.ts, projects route dirs, cluster spec.


desc: Same contract as t16 — cluster CALENDAR. Commit only: bindings/calendar.ts, calendar route dirs, cluster spec.


desc: Same contract as t16 — cluster TIME_MANAGEMENT (/time-track, /time/approvals). Commit only: bindings/time_management.ts, time route dirs, cluster spec.


desc: Same contract as t16 — cluster INVOICES (+/receipts,/payments). Commit only: bindings/invoices.ts, invoices/receipts/payments route dirs, cluster spec.


desc: Same contract as t16 — cluster EXPENSES (+/vendors). Commit only: bindings/expenses.ts, expenses/vendors route dirs, cluster spec.


desc: Same contract as t16 — cluster CRM. Commit only: bindings/crm.ts, crm route dirs, cluster spec.


desc: Same contract as t16 — cluster MARKETING (+/proposals,/contracts). Commit only: bindings/marketing.ts, marketing/proposals/contracts route dirs, cluster spec.


desc: Same contract as t16 — cluster KB. Commit only: bindings/kb.ts, kb route dirs, cluster spec.


desc: Same contract as t16 — cluster REPORTS (+/analytics). Commit only: bindings/reports.ts, reports/analytics route dirs, cluster spec.


desc: Same contract as t16 — clusters CONTRACTOR_PAYOUTS (+/payouts) and SETTINGS-EXTRAS (integrations/profile/billing deep link). Commit only: bindings/contractor_payouts.ts, bindings/settings extras, their route dirs, cluster specs.


desc: Read docs/plans/2026-07-11-zync-os-mobile.md Task 26 (Final gate). Walk spec Acceptance criteria 1-12 with evidence; vision-judge batch (codex models); record iOS manual checklist artifact for the user; fault injection. Acceptance: all 12 criteria evidenced in run log. Commit only: evidence/checklist artifacts under docs/plans/audit/.