feat: Phase 4 frontend — gamification, Astra identity, onboarding, referral, social types

[thomasluizon]

Phase 4 — frontend + shared (orbit-ui-mobile)

Frontend/shared half of the Phase 4 growth/social batch. Pairs with orbit-api#261 (backend).

Issues

• Moderate free-tier entitlement rebalance #186 + Recap payload endpoint (upgrade retrospective) #190 Gamification: free-tier streak/XP/level display (gated on canViewGamification), next-reward carrot (teases Pro), recap shared types/endpoint/key, infinite-level display.
• Astra conversational engine (clarify → confirm → execute) #183 + Rename "Chat" → "Astra" + visible identity #184 Astra: custom AstraMark/AstraAvatar (nav + header + meet-astra, both platforms) + shared chat-clarification types. (Astra conversational engine (clarify → confirm → execute) #183's engine was already shipped; this is the avatar/identity + shared types.)
• Starter template packs #187 Template packs (single-pack→customize→bulk-create) · First-run refresh — simpler Today + wizard + coach-marks #188 first-run (≥5 disclosure + tour-engine coach-marks, auto-tour retired) · Gamified setup checklist + onboarding achievement #189 setup checklist (auto-tracked Today card) · In-app no-card trial messaging #192 no-card trial copy.
• Surface referral (home + post-achievement prompt) #191 Referral: Profile card + dismissible Today entry (removed from About); milestone prompt (streak 7/30/100 + level-ups) routed through the existing celebration queue (no stacking).
• Social foundation — friends + cheering (backend) #193 Social: shared Zod types + endpoints + query keys (backend in chore(deps): bump the production-minor-patch group across 1 directory with 27 updates #261; no UI this phase).

Validation

type-check clean (3 workspaces) · lint 0 errors · tests shared 1119 · web 1696 · mobile 664 — all green. web/mobile parity + en/pt-BR throughout.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
orbit-ui-mobile-web	Ignored		Jun 27, 2026 7:24am

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
90.9% Coverage on New Code
1.1% Duplication on New Code

See analysis details on SonarQube Cloud

[claude]

Code Review: PR 323 - APPROVE

Summary: Phase 4 is a large well-structured batch landing gamification carrot, Astra identity, template packs, coach-marks, setup checklist, referral prompt, and social Zod types across web, mobile, and shared (98 files). Clean implementation, thorough parity, i18n fully in sync. No Critical or High findings survive adversarial review.

CRITICAL/HIGH: None.

MEDIUM-1: use-coach-mark.ts (mobile) bare catch {} swallows AsyncStorage errors silently

• location: apps/mobile/hooks/use-coach-mark.ts:36
• issue: Any AsyncStorage failure is silently discarded. Transient storage corruption suppresses all coach-marks permanently.
• fix: catch (error) { if (DEV) console.warn(error) } - same fix needed in web readSeenSections/markSectionSeen helpers.
• reference: CLAUDE.md rule 8

MEDIUM-2: sendFriendRequestSchema allows empty body - both handle and referralCode are optional

• location: packages/shared/src/types/social.ts:101-104
• issue: A {} body passes Zod validation. UI code that forgets to set either field silently passes the frontend guard.
• fix: .refine((d) => d.handle != null || d.referralCode != null, { message: "handle or referralCode required" })
• reference: CLAUDE.md rule 8

Subagents:
parity-checker: PAIRED (14 pairs verified; NextRewardCarrot props difference is valid platform adapter)
i18n-syncer: IN SYNC (all new keys in both en.json and pt-BR.json)
contract-aligner: UNVERIFIABLE (orbit-api not accessible from CI; no confirmed TS-side drifts)
security-reviewer: N/A (diff does not touch orbit-api; inline: no XSS, no auth leakage, no hardcoded secrets)

Adversarial pass:
nextReward required field (initially Critical): DOWNGRADED to non-finding. apiClient does not call Zod .parse() - it type-casts JSON. deriveNextRewardCarrot guards with canViewGamification which is optional on profileSchema and defaults to false on old API responses, so the early return fires before nextReward is accessed. Safe.
userDataExportSchema new required fields (initially High): REFUTED. Schema never invoked via .parse() in production. Export handler has catch wrapper. Not a runtime risk.

Validation: Lint PASS. Type-check PASS (3 workspaces). Tests PASS (shared 1119, web 1696, mobile 664). API build N/A.

Deferred: Contract drift (backend) unverifiable from CI - social schemas, gamification DTO new fields, recap schema not verified against orbit-api DTOs. Recommend manual spot-check of orbit-api#261 before merge.

What is good: Referral prompt store is exemplary (shared factory, platform adapters, cooldown guard, de-duplication, migration, 201-assertion tests). AstraMark/AstraAvatar are LucideProps-compatible with reduced-motion gating and correct a11y roles. Template packs compute i18n keys from stable identifiers. COACH_MARK_SECTIONS exclusion centralized in tour-store.ts. No console.log, no any in production, no narration comments, no raw slate/rgba values.

APPROVE. Two Medium findings are non-blocking follow-ups. Error-swallowing in use-coach-mark first; sendFriendRequestSchema refinement before Social UI in Phase 5.

Generated with Claude Code