v1.19 — Critical Path: Full Product Launch
Moved Critical Path from a pilot feature (localStorage, mocked XP) into a first-class daily mini-game with server-authoritative state, Stim XP progression, cosmetic unlocks, and opt-in reminders.
Summary
v1.19 graduated Critical Path from a single-device pilot into a production-grade product experience. The daily puzzle game had been live for months on localStorage with no cross-device state and no real progression. This milestone transformed it: server-backed completion tracking, real percentile ranking computed from daily player times, Stim XP ledger with four cosmetic theme unlocks, WCAG 2.1 AA accessibility, full PostHog instrumentation, opt-in daily reminders, and a 14-day gradual rollout via PostHog feature flag.
The work kept the anti-engagement design intact—one puzzle per day, no FOMO mechanics on reminders, cosmetics earned purely by consistent play, Stim XP isolated from goal-tracking metrics. Every user-visible string passed brand-voice audit. The milestone shipped 7 engineering phases (82–87) plus a documentation close (88).
Goal
Graduate Critical Path from a single-device pilot into a first-class daily mini-game that earns its place on the dashboard. Six engineering phases turn five pilot-grade behaviors (localStorage state, mocked XP, local-heuristic percentile, no a11y, no instrumentation) into the production-grade feature pair the PRD demands (server-authoritative state, real percentile, separate Stim XP ledger with cosmetic unlocks, WCAG 2.1 AA, full PostHog funnel, opt-in reminder, generator hardening, gradual rollout flag).
Scope — What Shipped
- Backend persistence —
critical_path_playstable;RecordPlayandFetchTodayinteractions with real percentile viaPERCENT_RANK()window function;PERCENT_RANK()scoped to same-day plays. - Stim XP ledger —
stim_xp_ledgertable; cached aggregates (stim_xp_total,stim_streak_current,stim_streak_longest) onUser;AwardStimXpinteraction triggered fromRecordPlay(50 base + ≤50 speed bonus). - Cosmetic themes — Four themes (Default, Forest, Midnight, Solar) as catalog-as-code; unlock thresholds at Stim Streaks 0 / 7 / 30 / 100 days; per-user active-theme preference on
UserDetail.data;CriticalPathGraph.vueapplies theme colors. - Frontend persistence —
PlayView.vueserver-first for authenticated users; silent localStorage fallback on network error; sign-in gate for unauthenticated users (no guest play path). - Share card — Completion share card with date, elapsed time, percentile (or "One of the first today" when <10 daily plays), Objectuve logo; native share sheet on mobile; clipboard fallback on web; deep-link to
/play. - PostHog instrumentation — 8 events from PRD R5 (
tile_tapped,puzzle_started,puzzle_completed,puzzle_abandoned,tutorial_viewed,undo_tapped,theme_changed,share_tapped) with full property payloads; funnel defined. - Accessibility (WCAG 2.1 AA) — Keyboard navigation (Tab cycles valid next nodes; Enter/Space activates), screen reader announcements per tap, focus-trap overlays, ≥44×44px touch targets, contrast ratios verified on all 4 themes + default/tapped/invalid/complete states.
- Daily reminders — Opt-in toggle in Settings (defaults OFF); 9:00 AM default time per user's timezone; suppressed when today's puzzle is already complete; respects existing quiet-hours setting; copy: "Today's Critical Path is ready — 2 minutes to map the path." (no FOMO variants).
- Generator hardening — Fallback puzzle pool expanded 5 → 20 hand-validated puzzles; solution-uniqueness validation; Sentry alert on >5 fallback uses per 24h; 500ms deadline with 100ms warning;
Number.MAX_SAFE_INTEGERoverflow handled. - Gradual rollout — PostHog feature flag
critical-path-full-productwith 10% → 50% → 100% stage-gate schedule; stable per-user assignment viadistinct_idhashing; rollback path tested (flag OFF reverts authenticated users to pilot localStorage, server data preserved). - Documentation — Player-facing feature guide (
docs/features/critical-path.md), analytics reference, data-model docs, GraphQL API reference, milestone narrative, CHANGELOG entries.
Phases
| Phase | Name | Status | PR | Shipped |
|---|---|---|---|---|
| 82 | Backend persistence + real percentile | Shipped | #643, #642 | v3.9.133 |
| 83 | Stim XP ledger + cosmetic theme model | Shipped | — | v3.9.133 |
| 84 | Stim XP UI + cosmetic theme picker | Shipped | — | v3.9.137 |
| 85 | Completion share card | Shipped | — | v3.9.135 |
| 86a | PostHog instrumentation | Shipped | — | v3.9.146 |
| 86b | WCAG 2.1 AA a11y polish | Shipped | #693 | v3.9.137 |
| 87 | Daily reminder + generator hardening + rollout flag | Shipped | — | v3.9.145 |
Key Decisions
- Server-authoritative percentile via
PERCENT_RANK()— Real percentile computed from actual player times each day (minimum 10 players to show; below that, "One of the first today"). Avoids heuristic guessing and gives players accurate ranking. - Stim XP isolated from goal XP — Dedicated ledger table and cached aggregates; never summed into
User#xpor displayed alongside goal rank. Protects the north-star metric (cumulative goals completed) and prevents gamification contamination of goal tracking. - Sign-in required to play — Unauthenticated users see a sign-in gate; no localStorage-only guest play path. Ensures percentile cohort is stable and share analytics are correctly attributed.
- Opt-in reminders, off by default — Reminder toggle in Settings defaults OFF; no affirmative-only copy ("Today's puzzle is ready") with no guilt mechanics. Aligns with PBC dark-pattern audit.
- Cosmetics earned via consistent play — Four themes unlock at Stim Streak thresholds (0 / 7 / 30 / 100 days); all free, no paywall, no store. Rewards sustained engagement without introducing purchase friction.
- Gradual rollout over 14 days — Three-stage PostHog flag roll (10% / 50% / 100%) with explicit gates (fallback rate <1%, completion >30%, no P0 bugs) to catch problems early; rollback path verified.
Requirements Coverage
All 10 PRD requirements satisfied.
| Category | Count | Status |
|---|---|---|
| R1–R4 | 4 | Backend persistence, Stim XP, share card ✅ |
| R5–R6 | 2 | PostHog instrumentation, WCAG 2.1 AA ✅ |
| R7–R10 | 4 | Daily reminder, generator hardening, rollout, docs ✅ |
Full requirements list: v1.19-REQUIREMENTS.md on GitHub.
Outcomes
Users now have a complete daily puzzle experience with persistent progression. Puzzle completions award Stim XP, which unlocks cosmetic themes as streaks grow. Cross-device state is server-backed and syncs automatically. Share cards let players celebrate and invite friends without spoiling the puzzle. Daily reminders (opt-in) help form a consistent habit. Full analytics visibility lets the team measure retention and engagement. The feature is accessible to keyboard and screen-reader users.
Tech Debt
- (Phase 86a deferred) PostHog event instrumentation shipped in v3.9.146; minimal deferred nits captured in the Phase 86b section of the ROADMAP.
Related Artifacts
- Roadmap: v1.19-ROADMAP.md
- Requirements: v1.19-REQUIREMENTS.md
- Milestone Audit: v1.19-MILESTONE-AUDIT.md
- Phase artifacts: .planning/milestones/v1.19-phases/
- PRD: Critical Path — Full Product Launch
- Git tag: v1.19
Related Commits
Notable commits from the v1.19 milestone:
- Phase 82 (backend persistence): PR #643
bf843aeb—critical_path_playstable, percentile interaction, GraphQL surface - Phase 82 (frontend copy): PR #642
b50b33e0— null-percentile copy variants inPlayView.vueandCompletionModal.vue - Phase 86b (a11y polish): PR #693
ea775b61— keyboard navigation, screen reader announcements, contrast fixes - Phase 87 (final shipping): see
.planning/milestones/v1.19-phases/PHASE-87-PLAN.mdfor the complete bundle
Last updated: 2026-05-23 (Dori, Phase 88 milestone close)