life-companion/docs/USABLE_IOS_V1_PLAN.md

Usable iOS V1 Delivery Plan

This plan takes Life Companion from the current implemented baseline to an iPhone build that can be used as a real local-first product. It is the approved roadmap for sequential durable Goals. Android and sound remain outside scope.

Usable Version Contract

The app is usable when a person can install it on an iPhone and complete the following without seeded data, placeholders, a backend, or mandatory HealthKit permission:

1. Meet, compare, choose, hatch, and name one permanent companion.
2. Configure an automatic, timer, manual, or custom real-life signal.
3. Record an action, see the correct companion response, inspect provenance, correct attribution, and retain the corrected result after relaunch.
4. Reveal, place, move, and reuse a discovery in the habitat.
5. Make an exploration choice and later see its consequence in placement or memory content.
6. Revisit journey and memory content after multiple local days without streak loss, guilt, fabricated activity, or absence debt.
7. Use the app offline, background and restore a timer, export local data, choose memory-share privacy, and reset all local data.
8. Use Simplified Chinese or English, Reduce Motion, haptics off, VoiceOver, and large text without losing a primary workflow.

The application remains silent, local-first, iOS-only, non-medical, and free of visible XP, rarity, paid rerolls, streak punishment, or growth acceleration.

Verified Baseline

• React Native iOS implementation, navigation, local store, migrations, domain growth, HealthKit adapter, notification service, export, reset, discovery, exploration, journey, memory, accessibility foundations, and release assets are implemented.
• Source scanning finds no product TODO, demo route, placeholder action, or unimplemented button in src/.
• Pathbud, Cloudnest, Facetlantern, and Mossspring each own all 15 semantic animation clips without fallback.
• Animation asset completion is closed as an implementation gate under ANIM-ASSET-01; physical-device motion review remains open.
• Automated source gates currently pass; physical-device acceptance remains open and cannot be replaced by simulator evidence. The latest partial Simulator evidence is recorded in art/evidence/simulator-acceptance-20260819/evidence.json: the native build and real first-encounter render pass, while automated taps and physical-device gates remain open.

Goal Sequence

Only one Goal is active at a time. Each Goal receives a focused product commit, automated evidence, a separate closure/evidence commit, and a clean worktree before the next Goal starts.

Goal 1: Complete Production Animation

Status: COMPLETE (4c65192, evidence art/evidence/mossspring-growth-memory-20260818)

Outcome:

• All four species implement all 15 semantic clips without fallback.
• Every runtime sequence passes visual identity/anatomy review, edge checks, adjacent continuity, interruption/settling behavior, and Reduced Motion.

Completion evidence:

• Exact per-species clip inventory test.
• TypeScript, ESLint, 27 Jest suites / 89 tests, a Metro iOS production bundle with 496 copied assets, and an unsigned iPhone 17 Pro iOS 26.1 Simulator build.
• Curated contacts/GIF and append-only rejection evidence for all four species.

Goal 2: End-to-End First-Use And Daily-Use Contract

Status: ACTIVE

Outcome:

• One deterministic integration harness proves the complete fresh-install path through first action, response, correction, discovery placement, exploration consequence, memory, export, relaunch, and reset.
• Time-controlled scenarios prove D0, D1, D3, D7, D14, D21, D30, monthly continuation, timezone change, and long absence without waiting in real time.

Implementation boundary:

• Add integration fixtures around the real store/domain/navigation contracts; do not add a hidden production debug menu or seeded product data.
• Close gaps revealed by the harness in the smallest owning module.

Checkpoint 2A: COMPLETE (f81344e, 24e1a7f, 41de5dc, evidence art/evidence/usable-flow-20260818/evidence.json). The durable-store fixture now covers fresh encounter through naming and first signal, factual action and correction, discovery reveal/place/reuse, seven shared days with an exploration consequence and weekly memory, export, timer relaunch recovery, reset, and sparse D0/D1/D3/D7/D14/D21/D30 dates without catch-up growth. The same matrix covers 60 shared days across eight weekly chapters and two monthly chronicles, plus a timezone-shifted imported local day without event duplication. It also fixed reset persistence retaining optional companion/timer fields.

Completion evidence:

• Fresh state and migrated state scenarios.
• Automatic-denied fallback, timer, manual, custom signal, correction, discovery conflict/reuse, exploration consequence, export cleanup, and reset.
• No persisted state survives reset; no accepted history is lost on relaunch.

Goal 3: Native Service Reliability

Outcome:

• HealthKit, local notifications, timer lifecycle, sharing, and app lifecycle recover honestly across permission denial, partial access, errors, backgrounding, termination, and relaunch.

Implementation boundary:

• iOS service adapters and their UI recovery paths only.
• No analytics, account, cloud sync, ads, remote notifications, or backend.

Checkpoint 3A: COMPLETE (0326028, c1bfbbd, evidence art/evidence/native-service-reliability-20260818/evidence.json). HealthKit authorization/background-delivery errors now remain visible and retryable; notification API failures do not create false receipts; conflicting timer routes explain how to return to the active timer; and Share Sheet fallback failures show a retry error. The full 28 Jest suites / 100 tests, TypeScript, ESLint, Metro iOS bundle, and unsigned Simulator build pass.

Completion evidence:

• Automated negative-path and idempotency tests.
• Native configuration audit and unsigned Simulator build.
• A device-ready checklist that clearly leaves HealthKit background wake-up, system permission UI, and share-sheet behavior OPEN until tested on iPhone.

Goal 4: Usability And Accessibility Candidate

Outcome:

• Every load-bearing screen and modal remains understandable and operable at narrow width, 200% Dynamic Type, VoiceOver, Reduce Motion, haptics off, offline state, denied state, empty state, and stale-route recovery.
• Companion motion, habitat content, buttons, sheets, and text never overlap or clip in supported iPhone layouts.

Implementation boundary:

• Fix demonstrated workflow or presentation defects only; do not redesign the product or add new feature categories.

Checkpoint 4A: COMPLETE (48b653a, dd887a6, ed86746, 7018ab3, 16e8f4c, 42cbf33, 7c18c13, 6e3558a, a8b19aa, 3cad2cf, 676249e, 3e45da7, evidence art/evidence/usability-feedback-20260818/evidence.json). Profile now fulfills the promised rename flow, empty Wardrobe has a usable explanation, journey signal limits are explained inline, health read errors are announced as accessibility alerts, and network changes show a non-blocking offline state. Unlocked direction actions, hotspots, and signatures can also be revisited with companion motion. The full 33 Jest suites / 105 tests, TypeScript, ESLint, Metro iOS bundle, and unsigned Simulator build pass. Habitat now also surfaces a grounded companion reflection for quiet, recent, returning, discovery, and exploration states, giving users a gentle reason to return without streaks or guilt. Memory now also summarizes recent shared days by direction and action without rewarding event volume. Thirty shared days now produce a privacy-safe monthly chronicle card that can be shared. Users can choose a reflection focus without changing growth rules, and 90 shared days now form a seasonal archive and share card. Users can add a personal note to that archive, which persists and can be shared; older seasonal archives remain browsable but collapsed by default. The square seasonal art is used as a subdued latest-archive card background rather than a full-screen crop. Users can also save individual long-term archives and open a saved-only view. A formed archive also leaves a subtle atmosphere tint and a coast-art marker in Habitat; opening the marker returns to Memory. Each archive also receives a deterministic keepsake based on its dominant direction, reused in Memory, Habitat, and sharing. Habitat markers also support a persisted, non-obligatory companion revisit animation and a separate archive-open action. The revisit uses the keepsake direction's curated response clip and bounded keepsake-specific return copy. Thirty-day chronicles now also accept a persisted personal note that exports and appears in privacy-safe sharing. Earlier chronicles are collapsed by default and can be expanded to recover older notes without duplicating latest-chronicle controls. The full suite is 44 Jest suites / 128 tests. No-data sharing excludes personal monthly and long-term notes from both the captured card and system share text. The corrected encounter capture keeps the two secondary actions fully visible at normal text size and stacks them at 200% text. Long-term archives now expose the three monthly chronicles that formed them, with the month range included in privacy-safe sharing. The full suite is 45 Jest suites / 130 tests. The latest native build and Simulator first-encounter capture are bound to revision 6dc2ad9; automated Memory bridge coverage is in __tests__/archiveChronicleBridge.test.tsx. The expanded view also explains the direction arc across those three months. Monthly chronicles can now be saved and filtered independently, and archive rows can open and highlight the exact source chronicle. The full suite is 46 Jest suites / 132 tests. After 14 shared days in an incomplete month, Habitat and Memory preview a bounded monthly mark with no countdown; at 30 days it becomes part of the chronicle and share card. The full suite is 48 Jest suites / 137 tests. The Habitat preview can be revisited with a direction response and persistent local feedback without changing growth. The full suite is 48 Jest suites / 138 tests. After D30, the latest completed monthly mark remains in Habitat until D90, when the long-term archive marker replaces it without duplication. At 360 shared days, Memory forms an annual review from four long-term archives and sharing can include its direction and archive summary. The full suite is 50 Jest suites / 141 tests. Users can add an annual personal note that persists/exports and stays out of no-data sharing. The full suite is 50 Jest suites / 142 tests. Sharing now accepts an explicit artifact target, keeping monthly, long-term, annual, and full-memory cards/messages separate. The full suite is 51 Jest suites / 150 tests. Full-memory year summaries use taller stable capture dimensions while single-artifact cards remain compact at normal and 200% text. Earlier annual reviews and their notes remain available through a collapsed, read-only history. The full suite is 50 Jest suites / 143 tests. The latest annual review tests and Simulator capture are bound to revision 8bb2dcc. Simulator host-window click injection was attempted with granted CuaDriver permissions but did not become a device touch; the unchanged result is recorded as a non-pass in the Simulator evidence instead of a completed navigation flow.

Completion evidence:

• Automated layout/accessibility scenarios and representative screenshots.
• Full user-flow review against the Usable Version Contract.
• Owner physical-device findings are recorded as pass, defect, or external gate; simulator evidence is never relabeled as device evidence.

Goal 5: Installable Release Candidate

Outcome:

• One immutable iOS candidate revision passes all automated gates and is ready for owner signing and physical-device installation.
• Release documentation, privacy claims, permission copy, app identity, version, build number, and data behavior agree with the shipped code.

Completion evidence:

• TypeScript, ESLint, complete Jest, production Metro bundle, Asset Catalog and launch compilation, privacy/entitlement lint, and unsigned iOS build at one revision.
• Clean Git worktree, no owned development server, exact candidate revision, and completed handoff instructions.
• Signed archive, TestFlight/App Store upload, HealthKit background delivery, VoiceOver focus, and the physical-device matrix remain owner/external gates until real evidence exists.

Goal Command Protocol

1. Finish and accept the current animation Goal before creating another Goal.
2. Create the next Goal from the sequence above with its exact observable outcome and evidence contract; never create a parallel product Goal.
3. Update docs/IOS_V1_EXECUTION_PLAN.md and the owning evidence directory at every accepted checkpoint.
4. Continue automatically through the approved Goal sequence. Ask the owner only for an actual product decision, credential/signing action, or physical device result that cannot be produced locally.
5. Do not mark the final Goal complete while any required implementation or automated verification remains. Report physical-device and release-owner gates separately.

Final Handoff

The final handoff must name:

• implementation and documentation revisions;
• exact automated commands and results;
• the installable Xcode workspace and configuration;
• supported iPhone/iPad and iOS versions;
• remaining device, signing, and App Store owner actions;
• every known defect, with no placeholder phrasing such as "basically done".