From ac2efb514b665040fdb195ec0a62e2b57f7a5615 Mon Sep 17 00:00:00 2001 From: Daniel Meyer Date: Wed, 29 Jul 2026 14:56:07 -0700 Subject: [PATCH 1/2] docs: recover AR redesign docs onto freeze main (supersedes #245) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fresh branch from current main recovers SUPPORTING redesign map, inventory (Ember Fox runtime), IA conflicts, phased plan, north star, and MVPβ†’vision ladder. Index wiring only on freeze-era docs; no stale #245 history, no binding-law rewrite, no mesh/code changes. --- README.md | 4 +- ROADMAP.md | 4 +- docs/README.md | 6 + docs/canonical/MVP_TO_VISION_LADDER.md | 195 ++++++++++++ docs/collaboration/ACTIVE_WORK.md | 2 +- docs/design/AR_MVP_FREEZE.md | 1 + docs/design/AR_PRODUCT_REDESIGN_MAP.md | 340 ++++++++++++++++++++ docs/design/AR_SESSION_IA_CONFLICTS.md | 384 +++++++++++++++++++++++ docs/design/AR_SYSTEM_INVENTORY.md | 144 +++++++++ docs/design/CONTINUATION_PLAN.md | 2 +- docs/design/PRODUCT_VISION_NORTH_STAR.md | 156 +++++++++ docs/design/README.md | 17 +- docs/plans/AR_APP_REDESIGN_PLAN.md | 216 +++++++++++++ docs/plans/README.md | 13 + 14 files changed, 1478 insertions(+), 6 deletions(-) create mode 100644 docs/canonical/MVP_TO_VISION_LADDER.md create mode 100644 docs/design/AR_PRODUCT_REDESIGN_MAP.md create mode 100644 docs/design/AR_SESSION_IA_CONFLICTS.md create mode 100644 docs/design/AR_SYSTEM_INVENTORY.md create mode 100644 docs/design/PRODUCT_VISION_NORTH_STAR.md create mode 100644 docs/plans/AR_APP_REDESIGN_PLAN.md diff --git a/README.md b/README.md index 4727fcf..5b42402 100644 --- a/README.md +++ b/README.md @@ -86,7 +86,7 @@ Demo Mode runs the same deterministic loop without physical movement or location | Multiplayer, marketplace, LiveOps | πŸ”’ Deferred | Outside current scope | | Generalized AI Director | πŸ”’ Future reference | Not current implementation authority | -See the complete [`Current Capability Matrix`](docs/canonical/CURRENT_CAPABILITY_MATRIX.md). +See the complete [`Current Capability Matrix`](docs/canonical/CURRENT_CAPABILITY_MATRIX.md). AR redesign planning (supporting only): [`AR Product Redesign Map`](docs/design/AR_PRODUCT_REDESIGN_MAP.md) Β· long-term [`North Star`](docs/design/PRODUCT_VISION_NORTH_STAR.md) Β· [`MVP β†’ Vision Ladder`](docs/canonical/MVP_TO_VISION_LADDER.md). ## Quick Start @@ -264,4 +264,4 @@ Start with [`CONTRIBUTING.md`](CONTRIBUTING.md). Coding agents must also read [` ## License -Licensed under the [Apache License 2.0](LICENSE). \ No newline at end of file +Licensed under the [Apache License 2.0](LICENSE). diff --git a/ROADMAP.md b/ROADMAP.md index 5fec44d..2b5a351 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,7 @@ # Waykin Roadmap +> **North star (reference only):** [`docs/design/PRODUCT_VISION_NORTH_STAR.md`](docs/design/PRODUCT_VISION_NORTH_STAR.md) β€” AR companion across walks/runs/rides + fitness; later worldbuilding and user-designed companions/experiences. Gated path: [`docs/canonical/MVP_TO_VISION_LADDER.md`](docs/canonical/MVP_TO_VISION_LADDER.md). Near-term AR session redesign planning: [`docs/design/AR_PRODUCT_REDESIGN_MAP.md`](docs/design/AR_PRODUCT_REDESIGN_MAP.md) (**SUPPORTING**). This roadmap remains evidence-gated engineering for the **current** binding MVP. + Waykin advances by proving one bounded layer before promoting the next. This roadmap is directional; GitHub issues and accepted milestone documents authorize implementation. ## Status Legend @@ -131,4 +133,4 @@ A future capability becomes implementable only when: 3. Canonical scope and architecture documents are updated when necessary. 4. Architecture review or an ADR approves material boundary changes. -See `WAYKIN_SPEC.md`, `docs/design/AI_DIRECTOR_RELEASE_CANDIDATES.md`, `docs/design/HEALTHKIT.md`, `docs/canonical/CURRENT_CAPABILITY_MATRIX.md`, and `docs/governance/DOCUMENT_AUTHORITY.md`. \ No newline at end of file +See `WAYKIN_SPEC.md`, `docs/design/AI_DIRECTOR_RELEASE_CANDIDATES.md`, `docs/design/HEALTHKIT.md`, `docs/canonical/CURRENT_CAPABILITY_MATRIX.md`, and `docs/governance/DOCUMENT_AUTHORITY.md`. diff --git a/docs/README.md b/docs/README.md index 71121a0..7ac41f0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -29,6 +29,12 @@ Waykin documentation is organized by **authority**, **maturity**, and **evidence | [`SOLO_MVP_SCOPE.md`](SOLO_MVP_SCOPE.md) | Constraints that keep Waykin implementable by one person | | [`../ROADMAP.md`](../ROADMAP.md) | Evidence-gated progression from physical-loop proof to future systems | | [`canonical/CURRENT_CAPABILITY_MATRIX.md`](canonical/CURRENT_CAPABILITY_MATRIX.md) | What is implemented, under validation, deferred, or future-only | +| [`design/AR_PRODUCT_REDESIGN_MAP.md`](design/AR_PRODUCT_REDESIGN_MAP.md) | AR product redesign master map β€” **SUPPORTING** (not binding) | +| [`plans/AR_APP_REDESIGN_PLAN.md`](plans/AR_APP_REDESIGN_PLAN.md) | Phased AR-app redesign plan β€” supporting | +| [`design/AR_SYSTEM_INVENTORY.md`](design/AR_SYSTEM_INVENTORY.md) | File-level AR system inventory β€” supporting | +| [`design/AR_SESSION_IA_CONFLICTS.md`](design/AR_SESSION_IA_CONFLICTS.md) | Active Session IA conflicts (C1–C11) β€” supporting | +| [`design/PRODUCT_VISION_NORTH_STAR.md`](design/PRODUCT_VISION_NORTH_STAR.md) | Long-term vision β€” **REFERENCE_ONLY** | +| [`canonical/MVP_TO_VISION_LADDER.md`](canonical/MVP_TO_VISION_LADDER.md) | Gated ladder MVP β†’ north star (R0–R8) β€” supporting | | [`../KNOWN_LIMITATIONS.md`](../KNOWN_LIMITATIONS.md) | Validated, partial, deferred, and `NOT_COMPUTABLE` gates | ## Engineering diff --git a/docs/canonical/MVP_TO_VISION_LADDER.md b/docs/canonical/MVP_TO_VISION_LADDER.md new file mode 100644 index 0000000..3721845 --- /dev/null +++ b/docs/canonical/MVP_TO_VISION_LADDER.md @@ -0,0 +1,195 @@ +# Waykin MVP β†’ Vision Ladder + +```yaml +document_id: WAYKIN-MVP-TO-VISION-LADDER-001 +version: 1.0 +date: 2026-07-29 +status: SUPPORTING +authority: SUPPORTING +maturity: NEAR_TERM +north_star: docs/design/PRODUCT_VISION_NORTH_STAR.md +does_not_override: [docs/SOLO_MVP_SCOPE.md, WAYKIN_SPEC.md] +``` + +## 1. Purpose + +Translate the [north star](../design/PRODUCT_VISION_NORTH_STAR.md) into a **gated ladder** so the team can build toward: + +- AR companion on **walks β†’ runs β†’ rides** (+ fitness depth) +- then **worldbuilding** +- then **user-designed companions & experiences** + +…without breaking the current architecture or shipping excluded scope early. + +**Lower rungs do not unlock upper rungs by aspiration alone.** Each gate needs evidence + explicit promotion. + +## 2. Ladder overview + +```text +R0 Binding MVP (today) +R1 AR-designed walk identity + session +R2 Outdoor AR walk proof +R3 Fitness depth (still walk-primary) +R4 Multi-activity framework (run, then ride) +R5 First-party worldbuilding content systems +R6 Experience pack runtime (first-party packs) +R7 User-designed experiences +R8 User-designed companions (+ marketplace only if ever ratified) +``` + +```text +R0 ──▢ R1 ──▢ R2 ──▢ R3 ──▢ R4 ──▢ R5 ──▢ R6 ──▢ R7 ──▢ R8 + walk AR outdoor fitness multi world packs UGC UGC + law law AR depth activity build first exp. companions + UX PASS party +``` + +## 3. Rung detail + +### R0 β€” Binding MVP (current law) + +| Field | Content | +| ----- | ------- | +| **Product** | Solo adaptive **walk**; one companion **Lira**; Bond; bounded pursuit; semantic audio; local memory | +| **AR** | Presentation adapter; optional cover; MVP frozen for feature creep | +| **Fitness** | Soft HealthKit reads only | +| **Creator / multi-companion / multi-activity** | Excluded or deferred | +| **Authority** | `SOLO_MVP_SCOPE`, `WAYKIN_SPEC`, capability matrix | +| **Exit** | N/A β€” baseline | + +### R1 β€” AR-designed walk (near-term redesign) + +| Field | Content | +| ----- | ------- | +| **Product** | Same walk MVP; identity = **AR-designed** (not audio-first); AR primary session surface when capable | +| **Work** | Phase 0 law + Phase 2 session IA ([`AR_APP_REDESIGN_PLAN`](../plans/AR_APP_REDESIGN_PLAN.md), [`AR_SESSION_IA_CONFLICTS`](../design/AR_SESSION_IA_CONFLICTS.md)) | +| **Must not** | Multi-activity, multi-companion, creator, AR gameplay authority | +| **Exit gate** | Binding docs + UIUX amended; skills/agents aligned; isolation + tests green | + +### R2 β€” Outdoor AR walk proof + +| Field | Content | +| ----- | ------- | +| **Work** | #41 outdoor re-walk; continuity, thermal, battery, safety; honest receipts | +| **Exit gate** | Outdoor AR evidence policy satisfied for claims you want to make; no PASS invented from sim | +| **Unlocks** | Credible AR marketing; confidence for multi-activity planning | + +### R3 β€” Fitness depth (walk still primary) + +| Field | Content | +| ----- | ------- | +| **Work** | Harden HK lifecycle evidence; optional workout write; Watch **only** via promoted issues; effort as soft context | +| **Must not** | Medical claims; effort selecting events/Bond coercively | +| **Exit gate** | Device evidence for each promoted fitness surface; capability matrix rows flipped with issues | + +### R4 β€” Multi-activity framework (run, then ride) + +| Field | Content | +| ----- | ------- | +| **Work** | Activity profiles on shared movement engine; integrity thresholds per mode; AR/HUD safety for speed contexts; copy and onboarding | +| **Order** | **Run** before **ride** unless product reorders with ADR | +| **Must not** | Separate app forks; activity-specific gameplay authorities that bypass Core | +| **Exit gate per activity** | Integrity + outdoor sessions + return-intent signal; spec lists activity as authorized | + +### R5 β€” First-party worldbuilding systems + +| Field | Content | +| ----- | ------- | +| **Work** | Content/lore systems, arcs, place-linked memories, seasonal pressure β€” **still** deterministic-capable core; presentation via existing channels | +| **Must not** | AI-owned gameplay state; unbounded generative world as required loop | +| **Exit gate** | Content pipeline + validation; no scope leak into multiplayer/marketplace | + +### R6 β€” Experience pack runtime (first-party) + +| Field | Content | +| ----- | ------- | +| **Work** | Promote deferred Experience Pack seam: pack format, load, offline fallback, validation | +| **Content** | First-party packs only | +| **Exit gate** | Runtime + at least one first-party pack shippable; security/safety review | + +### R7 β€” User-designed experiences + +| Field | Content | +| ----- | ------- | +| **Work** | Creator tools or structured authoring; moderation; rate limits; safety | +| **Depends on** | R6 stable | +| **Exit gate** | Policy + technical gates; binding docs promote creator experiences | + +### R8 β€” User-designed companions (+ optional marketplace) + +| Field | Content | +| ----- | ------- | +| **Work** | Companion identity model versioning; user-defined look/behavior **bounds**; AR presentation of third-party companions; optional marketplace | +| **Depends on** | R1–R2 quality bar for β€œa companion in AR”; R6–R7 governance lessons | +| **Must not** | Unbounded behavior that violates safety or movement authority | +| **Exit gate** | Explicit legal/product/security ratification; multi-companion ban lifted in binding scope | + +## 4. Mapping north-star pillars β†’ earliest rung + +| North-star pillar | Earliest rung | +| ----------------- | ------------- | +| AR companion presence | R1 (design), R2 (proof) | +| Real movement | R0+ | +| Multi-activity fitness | R4 (framework); R3 (fitness depth on walk) | +| Bond relationship | R0+ (deepen ongoing) | +| Worldbuilding | R5 | +| Creator companions & experiences | R7–R8 (packs R6) | + +## 5. What each horizon may claim + +| Horizon | OK to say | Not OK | +| ------- | --------- | ------ | +| R0–R1 | AR companion for walking (with honest capability limits) | Multi-sport app; make your own companion | +| R2+ | Outdoor AR walk claims per receipt | Universal outdoor AR quality | +| R3+ | Fitness-connected walk companion | Medical/clinical | +| R4+ | Run/ride companion (per shipped modes) | β€œAll sports” without list | +| R5+ | Deeper world / story of Lira’s world | User-generated world as default | +| R6+ | Official experience packs | App Store β€œUGC platform” | +| R7–R8 | Design experiences / companions | Unmoderated marketplace | + +## 6. Architecture seams to keep open (without implementing early) + +| Seam | Already / planned | Serves rungs | +| ---- | ----------------- | ------------ | +| `ARWorldCommand` + matrix | Shipped | R1–R8 presentation | +| Movement engine + integrity | Shipped | R0–R4 | +| Activity enrichment (HK) | Soft reads shipped | R3–R4 | +| Watch / wearable contracts | Reference | R3–R4 | +| Experience pack (deferred) | Seam only | R6–R7 | +| Companion identity persistence | Lira singleton | R8 needs versioning | + +**Do not** invent parallel runtimes per activity or per creator pack that bypass Core. + +## 7. Relationship to binding exclusions + +Until a rung is promoted, these remain **out of force for implementation** even though they appear in the north star: + +- Run / cycle / hike / climb expansion +- Multi-companion +- Marketplace / creator SDK +- Downloadable experience packs (runtime deferred) +- Multiplayer +- Generalized AI world director + +## 8. Suggested promotion checklist (any rung) + +- [ ] Outdoor / device evidence named and attached +- [ ] Capability matrix row updates +- [ ] `WAYKIN_SPEC` / `SOLO_MVP_SCOPE` diff (if product law changes) +- [ ] ADR if boundaries change +- [ ] UIUX / agent context updated +- [ ] Explicit non-goals restated so agents don’t overbuild + +## 9. Related + +| Doc | Role | +| --- | ---- | +| [`../design/PRODUCT_VISION_NORTH_STAR.md`](../design/PRODUCT_VISION_NORTH_STAR.md) | Destination | +| [`../design/AR_PRODUCT_REDESIGN_MAP.md`](../design/AR_PRODUCT_REDESIGN_MAP.md) | R1 architecture map | +| [`../plans/AR_APP_REDESIGN_PLAN.md`](../plans/AR_APP_REDESIGN_PLAN.md) | R1 execution | +| [`CURRENT_CAPABILITY_MATRIX.md`](CURRENT_CAPABILITY_MATRIX.md) | What is shipped vs deferred | +| [`../../ROADMAP.md`](../../ROADMAP.md) | Evidence-gated engineering roadmap | + +--- + +*Ladder v1.0 β€” supporting. Does not override binding MVP law.* diff --git a/docs/collaboration/ACTIVE_WORK.md b/docs/collaboration/ACTIVE_WORK.md index 5844a3a..3564719 100644 --- a/docs/collaboration/ACTIVE_WORK.md +++ b/docs/collaboration/ACTIVE_WORK.md @@ -16,7 +16,7 @@ Last updated: 2026-07-29 (**FREEZE MERGED** β€” #249; device indoor next; no red | Issue #41 β€” outdoor / physical validation | Human device | **Parked** β€” scaffold [OUTDOOR_QA_RECEIPT_20260729T191500Z_7df3a16_PENDING.md](../design/receipts/OUTDOOR_QA_RECEIPT_20260729T191500Z_7df3a16_PENDING.md); walk after indoor preferred | [DEFERRED_RECOMMENDATIONS.md](../design/DEFERRED_RECOMMENDATIONS.md) | | Issue #247 β€” TF archive hold | Product / dist | **Softened, not closed** β€” Prabu photo shows authored mesh on *some* build; still need OBSERVED on **exact freeze/archive SHA** before TF | [#247](https://github.com/scrimshawlife-ctrl/Waykin/issues/247) | | Internal TestFlight RC | Human (signing / ASC) | **Blocked** β€” freeze + #247 + fresh validate first | [TESTFLIGHT_RC_CHECKLIST.md](../design/TESTFLIGHT_RC_CHECKLIST.md) | -| PR #245 AR redesign docs | Docs lane | **Parked behind freeze** β€” SUPPORTING only; recover onto freeze tip later; do **not** merge stale branch | [#245](https://github.com/scrimshawlife-ctrl/Waykin/pull/245) | +| AR redesign docs recovery | Docs lane | **In progress** β€” fresh branch from current main (Ember Fox inventory); supersedes stale [#245](https://github.com/scrimshawlife-ctrl/Waykin/pull/245) history | SUPPORTING only; no Phase 0 binding edits | | AR session redesign PRs / Phase 0 law | β€” | **Not started** β€” build-on-top only after freeze + device honesty | Continuation plan steps 9–12 | ## Tip identity diff --git a/docs/design/AR_MVP_FREEZE.md b/docs/design/AR_MVP_FREEZE.md index 9b1a4b1..9cc9a0e 100644 --- a/docs/design/AR_MVP_FREEZE.md +++ b/docs/design/AR_MVP_FREEZE.md @@ -84,6 +84,7 @@ When this freeze is accepted: ## Related - [CONTINUATION_PLAN.md](CONTINUATION_PLAN.md) v5.0 +- [AR_PRODUCT_REDESIGN_MAP.md](AR_PRODUCT_REDESIGN_MAP.md) β€” SUPPORTING redesign planning (does not lift freeze) - [LIRA_AR_PRODUCTION_RIG.md](LIRA_AR_PRODUCTION_RIG.md) - [AR_REPLAY_VALIDATION.md](../AR_REPLAY_VALIDATION.md) - [ACTIVE_WORK.md](../collaboration/ACTIVE_WORK.md) diff --git a/docs/design/AR_PRODUCT_REDESIGN_MAP.md b/docs/design/AR_PRODUCT_REDESIGN_MAP.md new file mode 100644 index 0000000..e766301 --- /dev/null +++ b/docs/design/AR_PRODUCT_REDESIGN_MAP.md @@ -0,0 +1,340 @@ +# Waykin AR Product Redesign Map + +```yaml +document_id: WAYKIN-AR-PRODUCT-REDESIGN-MAP-001 +version: 1.1 +date: 2026-07-29 +status: SUPPORTING_DESIGN_MAP +authority: SUPPORTING +maturity: NEAR_TERM +evidence_class: CODE_AND_DOC_AUDIT +does_not_override: [SOLO_MVP_SCOPE, WAYKIN_SPEC, AR_MVP_FREEZE] +recovered_from_pr: 245 +recovered_on_main_base: 28bea09 +companion_runtime: MESHY_EMBER_FOX_WALK_V1 +mesh_authority_pr: 246 +operator_intent: "No longer audio-first; design for AR" +north_star: docs/design/PRODUCT_VISION_NORTH_STAR.md +ladder: docs/canonical/MVP_TO_VISION_LADDER.md +constraint: "Respect current architecture; do not break the repo" +related: + - docs/plans/AR_APP_REDESIGN_PLAN.md + - docs/design/AR_SYSTEM_INVENTORY.md + - docs/design/AR_SESSION_IA_CONFLICTS.md + - docs/design/AR_MVP_FREEZE.md + - docs/design/REAL_WALK_TO_AR_MAPPING.md + - WAYKIN_SPEC.md + - docs/SOLO_MVP_SCOPE.md + - ARCHITECTURE.md + - docs/canonical/CURRENT_CAPABILITY_MATRIX.md + - docs/governance/DOCUMENT_AUTHORITY.md +``` + +## 0. North star vs this map + +| Doc | Horizon | +| ---- | ------- | +| [`PRODUCT_VISION_NORTH_STAR.md`](PRODUCT_VISION_NORTH_STAR.md) | **Eventual:** AR companion on walks/runs/rides + fitness; worldbuilding; user-designed companions & experiences | +| [`../canonical/MVP_TO_VISION_LADDER.md`](../canonical/MVP_TO_VISION_LADDER.md) | Gated rungs R0–R8 from MVP β†’ north star | +| **This map** | **Near-term only:** AR-designed **walk** MVP (R1), architecture-preserving | + +This map is **chapter one**, not the full vision. + +## 1. Purpose + +This document **maps the entire AR product redesign space** for Waykin: + +- what is already built +- what the architecture allows and forbids +- how product identity must change (audio-first β†’ AR-designed) +- phased work that will not break Core isolation or freeze discipline +- which binding docs must be updated before agents treat AR-first as law + +It does **not** by itself rewrite binding product law. Promotion of identity language still requires edits to `docs/SOLO_MVP_SCOPE.md` and `WAYKIN_SPEC.md` (see Phase 0 in the plan). + +## 2. Operator decision (ratified for planning) + +| Decision | Statement | +| -------- | --------- | +| Product direction | Waykin is **designed for AR** as the primary session surface | +| Deprecated identity | **Audio-first** is no longer the product genus | +| Architecture stance | Keep movement-first **gameplay authority**; AR remains **presentation** | +| Safety | Do not break Core isolation, freeze, determinism, or Pause/End | + +**Proposed product line (for Phase 0 law PR):** + +> Waykin is an **AR-designed adaptive walking experience**: one companion, Lira, meets you in the world as you walk. Movement is the game; AR, audio, map, and HUD are presentation channels β€” with **AR the primary designed surface** when the device allows. + +## 3. Document authority (how this map sits) + +Precedence (from `docs/governance/DOCUMENT_AUTHORITY.md`): + +1. `docs/SOLO_MVP_SCOPE.md` β€” **BINDING** +2. `WAYKIN_SPEC.md` β€” **BINDING** +3. `README.md` +4. `ARCHITECTURE.md` +5. ADRs +6. … lower tiers … + +This map and `docs/plans/AR_APP_REDESIGN_PLAN.md` are **SUPPORTING / NEAR_TERM**. They cannot silently override binding audio-first language until Phase 0 lands. + +## 4. Whole-product map + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ WAYKIN PRODUCT β”‚ +β”‚ Solo walk Β· one companion (Lira) Β· Bond Β· bounded pursuit β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β–Ό β–Ό β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ GAMEPLAY β”‚ β”‚ SEMANTIC STATE β”‚ β”‚ PRESENTATION β”‚ +β”‚ AUTHORITY β”‚ β”‚ (Core) β”‚ β”‚ CHANNELS β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ MovementEngine│────▢│ WorldState │────▢│ β˜… AR (primary β”‚ +β”‚ Integrity β”‚ β”‚ Events β”‚ β”‚ design target) β”‚ +β”‚ Session outcomeβ”‚ β”‚ CompanionRuntimeβ”‚ β”‚ Audio (support) β”‚ +β”‚ Bond / Memory β”‚ β”‚ Pursuit β”‚ β”‚ 2D presence β”‚ +β”‚ β”‚ β”‚ Path progress β”‚ β”‚ Map / HUD β”‚ +β”‚ NEVER owned β”‚ β”‚ Presentation β”‚ β”‚ Glasses glance β”‚ +β”‚ by AR/audio β”‚ β”‚ Matrix β”‚ β”‚ (flag-off) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β–²β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ + β”‚ ARWorldCommand β”‚ + β”‚ SpatialIntent β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + App AR adapter only +``` + +### 4.1 Identity transition + +| Layer | Historical (shipped docs) | Target (AR-designed) | +| ----- | ------------------------- | -------------------- | +| Genus | Audio-first walking app | **AR-designed** walking companion | +| Primary session surface | 2D presence; AR optional cover | **AR canvas when available** | +| Audio | Product identity | Required **supporting** channel (pocket, eyes-up, a11y) | +| Map / path | Secondary | Secondary spatial support | +| Gameplay truth | Movement | **Unchanged: movement** | + +## 5. Architecture map (do not break) + +### 5.1 Runtime flow (OBSERVED) + +```text +Core Location sample / Demo tick + ↓ +MovementIntegrityProcessor (real only) + ↓ +MovementEngine β†’ MovementSnapshot + ↓ +CompanionWalkExperience + β”œβ”€ WorldState + β”œβ”€ WorldEventGenerator β†’ WorldEvent? (0–1 / tick) + β”œβ”€ CompanionPresentationMatrix β†’ behavior + distance + AR string + β”œβ”€ AudioExperienceLayer (event β†’ behavior β†’ AR-presentation β†’ path soft) + └─ ExperienceUpdate commands / semanticAudioCues + ↓ +WaykinAppModel + β”œβ”€ CompanionRuntime apply + β”œβ”€ PathProgressEngine + β”œβ”€ AppAudioCuePlayer + β”œβ”€ Session map presentation + └─ CanonicalARWorldCommandMapper β†’ [ARWorldCommand] + ↓ (only if handler attached) + CanonicalARSessionRuntime / ARWorldCommandRenderer + ↓ + RealityKit (world plant + continuity re-plant) +``` + +### 5.2 Boundary law + +| May | Must not | +| --- | -------- | +| Core emit semantic state + matrix strings | Core import ARKit / RealityKit / MapKit / filenames | +| App map state β†’ `ARWorldCommand` | AR select events, accept GPS, change Bond, write memories | +| Tracking gate AR UI quality | Tracking invent walk / world truth | +| Audio + AR + 2D share matrix | Divergent behavior vocabularies per surface | +| Degrade AR on limited tracking | Fail Pause/End or block safety | + +### 5.3 Placement policy (ratified #125) + +| Rule | Detail | +| ---- | ------ | +| Default | World-plane plant (ground raycast β†’ `AnchorEntity`) | +| Fallback | Camera-anchor if raycast fails | +| Continuity | Re-plant if missing / detached / > ~6 m from camera | +| `.follow` | Local pose only β€” **not** continuous walker re-anchor | +| Expansion | Continuous escort requires **new product issue + ADR** | + +## 6. System inventory (index) + +Full file-level inventory: [`AR_SYSTEM_INVENTORY.md`](AR_SYSTEM_INVENTORY.md). + +| Subsystem | Location | Status | +| --------- | -------- | ------ | +| AR contracts | `Sources/WaykinCore/Presentation/` | Binding semantics | +| Presentation matrix | `Sources/WaykinCore/Engines/CompanionPresentationMatrix.swift` | Shared authority | +| Walk experience | `Sources/WaykinCore/Experiences/` | No AR commands | +| Command mapper | `App/AR/CanonicalARWorldCommandMapper.swift` | Demo + real | +| AR session UI | `App/AR/CanonicalARSessionView.swift` | fullScreenCover | +| Renderer / plant | `App/AR/ARWorldCommandRenderer.swift`, `ARPlacementResolver.swift` | Frozen MVP | +| Mesh / skeletal | `App/AR/Companion/*` | Mid-LOD + fallback | +| Orchestration | `App/WaykinApp.swift` (`WaykinAppModel`) | Attach/detach handler | +| 2D presence | `App/CompanionPresenceView.swift` | Fallback / chrome | +| Map | `App/SessionMapViews.swift` | Semantic, not nav | +| Audio adapter | `App/AppAudioCuePlayer.swift` | Filenames + session | +| Freeze contract | `docs/design/AR_MVP_FREEZE.md` | Maintenance-only | +| Walkβ†’AR map | `docs/design/REAL_WALK_TO_AR_MAPPING.md` | OBSERVED | + +## 7. Capability matrix slice (AR-relevant) + +From `docs/canonical/CURRENT_CAPABILITY_MATRIX.md`: + +| Capability | Status | Redesign note | +| ---------- | ------ | ------------- | +| Semantic audio | Implemented | Keep as supporting channel | +| AR semantic contracts | Implemented | Keep | +| AR app adapter (MVP) | **Implemented (frozen)** | Unfreeze only by issue | +| Real-walkβ†’AR commands | Implemented | Keep spine | +| Path progress | Implemented | HUD / soft coupling | +| Outdoor physical AR QA | **Partial** | Gate marketing claims (#41) | +| Glasses glance | Flag-off | Not AR-product core | +| Multiplayer / marketplace / AR gameplay | Excluded | Still excluded | + +## 8. Freeze rings (redesign envelope) + +```text +RING A β€” Safe without freeze lift + Docs identity, agent context, comments, evidence collection, + outdoor re-walk, UX copy, fallback messaging + +RING B β€” Controlled unfreeze (named issue) + Session-default AR, entry flow, chrome/HUD in AR, + degraded-tracking UX, placement coach marks + Still: commands-only, no new gameplay, no Core ARKit + +RING C β€” Architecture change (ADR + scope rewrite) + Continuous walker re-anchor, AR-owned mechanics, + multi-entity world sim, glasses-required product + β†’ high break risk; not required for β€œAR app” v1 +``` + +**Default path:** Ring A β†’ evidence β†’ Ring B. Avoid Ring C. + +## 9. Target session IA (AR-designed) + +```text +Home + β”œβ”€ Begin Walk (REAL β€” primary) + β”œβ”€ Demo Walk (secondary) + β”œβ”€ Memory / Settings + └─ … + +Active Session + β”œβ”€ β˜… PRIMARY: AR canvas (when capability available + authorized) + β”‚ Lira world-planted Β· discovery/threat Β· mirrored Pause/End + β”œβ”€ SECONDARY: compact HUD (Bond, path phrase, pressure, continuity) + β”œβ”€ TERTIARY: semantic audio (policy-on for walks) + └─ FALLBACK: 2D presence Β± map (camera denied / unsupported / user choice) + +Session Summary β†’ Memory β†’ Home +``` + +### Capability fallback table + +| Capability state | Default surface | +| ---------------- | --------------- | +| `available` / `active` | AR primary | +| `trackingLimited` | AR degraded + continuity HUD; no gameplay change | +| `cameraDenied` / `unsupported` | 2D presence primary + clear copy | +| Demo, no camera | 2D + audio; AR if device allows | + +## 10. Conflict map + +| Conflict | Severity | Resolution owner | +| -------- | -------- | ---------------- | +| Binding **audio-first** vs AR design intent | High | Phase 0 binding docs | +| **AR MVP freeze** vs redesign work | High | Ring A vs issue-scoped Ring B | +| UIUX β€œpresence OR AR not both animating” | Med | Keep; AR cover replaces active 2D animation | +| Outdoor PARTIAL vs AR marketing | High | #41 before PASS claims | +| Skills `REPO_CONTEXT` audio-first | Med | Phase 0 agent pack | +| Continuous follow expectation vs world-plant | Med | Product education + optional later ADR | + +## 11. Binding doc delta map (Phase 0) + +| Document | Today | Target edit | +| -------- | ----- | ----------- | +| `docs/SOLO_MVP_SCOPE.md` | audio-first promise; audio-only presentation path | AR-designed promise; multi-channel presentation with AR primary design target | +| `WAYKIN_SPEC.md` | audio-first contract; AR as #8 | AR-designed contract; AR presentation elevated; audio remains MVP system | +| `README.md` | β€œaudio-first” hero | AR-designed hero + pillars | +| `ARCHITECTURE.md` | neutral / audio-centric narration | Presentation stack: AR primary design target | +| `docs/legal/TERMS.md` | audio-first experience | Match product line | +| `skills/**/REPO_CONTEXT.md` | Audio-first walking companion | AR-designed walking companion | +| `docs/design/AR_MVP_FREEZE.md` | freeze only | Add pointer to this map + unfreeze process | +| Design art docs `audio_first: true` | YAML flags | Historical or update to `ar_designed: true` | + +## 12. Test & evidence map + +| Proof | Suite / artifact | Guards | +| ----- | ---------------- | ------ | +| Command bridge | `CanonicalARRuntimeIntegrationTests`, real movement handler tests | Mapper lifecycle | +| Determinism | `ARCommandReplaySoakTests` | No wall-clock in core tests | +| Core isolation | `scripts/check_core_framework_isolation.sh` | No ARKit in Core | +| Outdoor AR | #41 + outdoor receipts | Continuity / thermal / battery | +| UI safety | UIUX #126 | Pause/End in AR cover | +| Validate | `make build && make test && make validate` | Repo health | + +## 13. Explicit non-goals (redesign v1) + +- RealityKit **gameplay** (combat, physics puzzles as authority) +- Multi-companion AR +- Marketplace / UGC assets +- Mandatory AR glasses +- Cloud / multiplayer +- Continuous walker re-anchor without ADR +- Dropping semantic audio entirely +- Importing AR frameworks into `WaykinCore` +- Claiming outdoor AR PASS from simulator alone + +## 13b. Session IA conflicts (summary) + +Active Session today is **2D-rooted** with AR as optional cover. AR-designed product inverts root/fallback. Full register: [`AR_SESSION_IA_CONFLICTS.md`](AR_SESSION_IA_CONFLICTS.md) (C1–C11: law vs tree, exclusive Lira, dual covers, a11y spine, pocket vs eyes-up, authority deadlock). + +## 14. Related documents (full web) + +| Topic | Doc | +| ----- | --- | +| Phased execution | [`../plans/AR_APP_REDESIGN_PLAN.md`](../plans/AR_APP_REDESIGN_PLAN.md) | +| File inventory | [`AR_SYSTEM_INVENTORY.md`](AR_SYSTEM_INVENTORY.md) | +| Session IA conflicts | [`AR_SESSION_IA_CONFLICTS.md`](AR_SESSION_IA_CONFLICTS.md) | +| North star vision | [`PRODUCT_VISION_NORTH_STAR.md`](PRODUCT_VISION_NORTH_STAR.md) | +| MVP β†’ vision ladder | [`../canonical/MVP_TO_VISION_LADDER.md`](../canonical/MVP_TO_VISION_LADDER.md) | +| Freeze | [`AR_MVP_FREEZE.md`](AR_MVP_FREEZE.md) | +| Walkβ†’AR | [`REAL_WALK_TO_AR_MAPPING.md`](REAL_WALK_TO_AR_MAPPING.md) | +| UI modality | [`WAYKIN_UIUX_SPEC.md`](WAYKIN_UIUX_SPEC.md) | +| Art / mesh | [`LIRA_AR_PRODUCTION_RIG.md`](LIRA_AR_PRODUCTION_RIG.md), [`LIRA_AR_SCULPT_PLAN.md`](LIRA_AR_SCULPT_PLAN.md) | +| Outdoor | [`OUTDOOR_QA_CHECKLIST.md`](OUTDOOR_QA_CHECKLIST.md), [`CONTINUATION_PLAN.md`](CONTINUATION_PLAN.md) | +| Path | [`PATHFINDING.md`](PATHFINDING.md) | +| Audio contract | [`../AUDIO_ASSET_CONTRACT.md`](../AUDIO_ASSET_CONTRACT.md) | +| Capability truth | [`../canonical/CURRENT_CAPABILITY_MATRIX.md`](../canonical/CURRENT_CAPABILITY_MATRIX.md) | + +## 15. Claim labels (audit residue) + +| Label | Claim | +| ----- | ----- | +| OBSERVED | AR command spine, freeze, optional fullScreenCover entry, audio-first binding language | +| INFERRED | Product feels multi-modal; audio-first under-describes ship | +| NOT_COMPUTABLE | Whether session-default AR will increase return intent (needs outdoor/device product evidence; not inventable) | +| NOT_COMPUTABLE | Outdoor AR quality PASS until #41 re-walk | + +## 16. Change control + +- Product-intent changes (identity, default modality) β†’ binding docs first, then agents, then UX. +- `App/AR/**` feature work β†’ cite freeze exception issue. +- Placement model change β†’ ADR. +- Any Core boundary change β†’ isolation script + architecture review. + +--- + +*End of map v1.0 β€” supports planning only until Phase 0 binding promotion.* diff --git a/docs/design/AR_SESSION_IA_CONFLICTS.md b/docs/design/AR_SESSION_IA_CONFLICTS.md new file mode 100644 index 0000000..29ffcad --- /dev/null +++ b/docs/design/AR_SESSION_IA_CONFLICTS.md @@ -0,0 +1,384 @@ +# AR Session IA Conflicts + +```yaml +document_id: WAYKIN-AR-SESSION-IA-CONFLICTS-001 +version: 1.0 +date: 2026-07-29 +status: SUPPORTING_AUDIT +authority: SUPPORTING +maturity: NEAR_TERM +evidence_class: CODE_AND_DOC_AUDIT +tip_audited: 850fe7b +parent_map: docs/design/AR_PRODUCT_REDESIGN_MAP.md +parent_plan: docs/plans/AR_APP_REDESIGN_PLAN.md +related: + - docs/design/WAYKIN_UIUX_SPEC.md + - docs/design/AR_MVP_FREEZE.md + - docs/design/REAL_WALK_TO_AR_MAPPING.md + - App/WaykinApp.swift (ActiveSessionView) + - WAYKIN_SPEC.md + - docs/SOLO_MVP_SCOPE.md +``` + +## 1. Purpose + +Register **information-architecture conflicts** for the Active Session when product direction is **AR-designed** (no longer audio-first) while shipped UI and UIUX still treat **2D presence as session root** and **AR as optional full-screen cover**. + +This document does **not** change binding product law or implement UX. It feeds Phase 0 (law) and Phase 2 (session UX) in [`../plans/AR_APP_REDESIGN_PLAN.md`](../plans/AR_APP_REDESIGN_PLAN.md). + +## 2. Current session IA (specified + shipped) + +```text +Home + └─ Begin Walk / Demo + ↓ push +Active Session (PRIMARY SURFACE = 2D) + β”œβ”€ State chip + relation chip + β”œβ”€ CompanionPresenceView ← Lira stills (main stage) + β”œβ”€ Pause | End | AR ← AR is a control, not the stage + β”œβ”€ GPS chip (live) + └─ CompactSessionMap β†’ full map cover + ↓ optional fullScreenCover + AR Companion (SECONDARY IMMERSION) + chrome: status Β· continuity Β· βœ• Β· Pause/End mirrored + ↓ dismiss βœ• + back to 2D session + ↓ End +Session Summary +``` + +| Layer | Role today | Code / doc | +| ----- | ---------- | ---------- | +| **2D presence** | Default session home; a11y spine | `CompanionPresenceView` in `ActiveSessionView` | +| **AR** | Opt-in cover (`showsARCompanion`) | `CanonicalARSessionView` fullScreenCover | +| **Map** | Compact inline + peer fullScreenCover | `showsFullMap` / `SessionMapFullView` | +| **Audio** | Not a screen; UIUX B1 still β€œprimary channel” | `AppAudioCuePlayer` + Core cues | + +**UIUX stance (B4):** β€œThe shipped session screen is fundamentally right” β€” consolidation, not redesign; AR entry position + cover safety only. + +## 3. Conflict register + +### C1 β€” Product genus vs session tree + +| Severity | High | +| -------- | ---- | +| Type | Law vs IA | + +| Source | Says | +| ------ | ---- | +| Binding law (`SOLO_MVP_SCOPE`, `WAYKIN_SPEC`) | Audio-first product | +| UIUX B1 | β€œAudio is the primary channel; the screen confirms” | +| UIUX B2 + shipped | Screen-first session; AR optional | +| Operator + redesign map | AR-designed; AR primary session surface | + +**Conflict:** Three competing β€œprimaries” (audio / 2D screen / AR) without one ordered channel stack. + +**Resolution direction:** Phase 0 law + UIUX B1 rewrite: AR primary **designed** surface when capable; audio required **support**; 2D fallback/HUD. + +--- + +### C2 β€” β€œPresence OR AR, never both animating” vs AR-default + +| Severity | High | +| -------- | ---- | +| Type | Principle vs redesign | + +UIUX B1.3: Lira never duplicated β€” **presence surface OR AR, never both animating at once**. + +| Today | AR-default target | +| ----- | ----------------- | +| 2D animates; AR off | AR animates; 2D may still update under cover | +| Rule holds if user attention is exclusive | Under-cover 2D animation semantics undefined | + +**Resolution options (pick one in Phase 2 issue):** + +1. **Exclusive stages** β€” while AR open, 2D figure is static/non-animating snapshot. +2. **AR owns Lira** β€” under AR, 2D shows HUD only (no figure). +3. **Relax B1.3** β€” multi-surface Lira (weakens β€œone truth”; not preferred). + +**Recommended:** option **2** for AR-primary; option **1** as minimal change. + +--- + +### C3 β€” Session root is 2D; AR is a leaf cover + +| Severity | High | +| -------- | ---- | +| Type | Structure vs AR app | + +```text +Target (redesign map) Shipped +───────────────────── ─────── +AR canvas = session root 2D presence = root +2D = fallback / HUD AR = optional cover +Map = overlay/tertiary Map = peer cover +``` + +Full-screen cover is correct for **safety** (#126: no accidental dismiss, Pause/End mirrored) but encodes **β€œAR is immersion on top of the real session,”** not **β€œAR is the session.”** + +**Resolution direction:** Keep cover/chrome safety; invert **default entry** and mental model so AR is home when capability allows; 2D is fallback stage (Phase 2). + +--- + +### C4 β€” Dual fullScreenCover: AR vs Map + +| Severity | Medium | +| -------- | ------ | +| Type | Competing immersion | + +`ActiveSessionView` holds independent: + +- `showsARCompanion` β†’ AR cover +- `showsFullMap` β†’ map cover + +| Issue | Detail | +| ----- | ------ | +| Peer immersions | Both can own the full screen | +| No mutual exclusion | Stacking / priority undefined in IA | +| Thumb competition | Compact map + AR + Pause/End | + +**Resolution direction:** Under AR stage, map is **peek/sheet** (or HUD chip), not a peer cover. Full map remains available on 2D fallback stage. + +--- + +### C5 β€” A11y traversal vs AR-primary + +| Severity | Medium–High | +| -------- | ----------- | +| Type | Contract collision | + +UIUX B10 order: + +```text +identity β†’ presence β†’ phrase β†’ metrics β†’ status β†’ controls β†’ map +``` + +AR is **outside** this spine; AR chrome is separate. + +| Conflict | Effect | +| -------- | ------ | +| A11y law is 2D-shaped | Outdoor VO path assumes presence surface | +| AR-primary walk | Needs AR order: tracking Β· Lira Β· phrase Β· Pause/End Β· exit stage | +| Reduce Motion | 2D stills vs AR skeletal motion = different channels | + +**NOT_COMPUTABLE:** physical VoiceOver + outdoor AR until receipts exist. + +**Resolution direction:** Document dual spines (2D stage / AR stage) in UIUX; do not claim single traversal for both. + +--- + +### C6 β€” βœ• returns to 2D β€œhome base” + +| Severity | Medium | +| -------- | ------ | +| Type | Mental model | + +#126: AR cover, `interactiveDismissDisabled`, Pause/End mirrored β€” **keep**. + +Still: + +- βœ• means β€œleave immersion β†’ 2D session” +- Outdoor PARTIAL: menu/entry awkward (`REAL_WALK_TO_AR_MAPPING`, outdoor receipt) + +**Conflict:** AR-primary users should not need 2D as emotional home. βœ• should mean β€œswitch stage,” not β€œabandon the real product.” + +**Resolution direction:** Copy + optional β€œprefer 2D this walk” control; End remains end-of-walk only. + +--- + +### C7 β€” Pocket-first vs eyes-up AR + +| Severity | High | +| -------- | ---- | +| Type | Principle collision | + +| UIUX B1 Pocket-first | AR session | +| -------------------- | ---------- | +| Glances, one hand, phone not product | Camera up, longer visual attention | +| Audio primary while walking | Visual primary when AR open | + +**Resolution direction:** **Mode-aware IA**, not one tree for all moments: + +| Mode | Primary channel | Stage | +| ---- | --------------- | ----- | +| Pocket / eyes-down | Audio + glance/HUD | 2D or compact HUD | +| Eyes-up | AR canvas | AR stage | +| Capability fail | Audio + 2D | 2D fallback | + +--- + +### C8 β€” Multi-channel attention on one tick + +| Severity | Medium | +| -------- | ------ | +| Type | Cognitive load | + +One tick can drive 2D still, AR entity, audio, path chip, map, pressure ring. Matrix keeps **semantic** unity; IA lacks **attention priority**. + +**Example:** path `offPath` + pursuit `close` + AR open β†’ what first? + +**Resolution direction:** Document AR-stage attention order, e.g.: + +1. Safety controls always reachable +2. Threat / discovery entity +3. Continuity / tracking chrome +4. Path / Bond HUD +5. Audio reinforcement + +--- + +### C9 β€” Capability fallback missing from session IA + +| Severity | High | +| -------- | ---- | +| Type | AR app gap | + +| State | Shipped | Gap | +| ----- | ------- | --- | +| AR never opened | Full 2D product | OK as fallback | +| Camera denied / unsupported | Button may still offer AR | Need disabled+reason / auto 2D | +| Tracking limited | Continuity only if already in AR | Need degraded AR policy | +| Default-open AR (Phase 2) | Not implemented | Need first-class branch in B2 | + +UIUX B2 has **no fallback branch**. Redesign map defines one; promote into UIUX in Phase 0/2. + +--- + +### C10 β€” Glasses glance + AR + 2D + +| Severity | Low–Med | +| -------- | ------- | +| Type | Future pile-up | + +Glance adapter publishes from `activePresencePresentation` when enabled, independent of AR cover. + +**Conflict with B1.3** if flag-on + AR-default (three Lira surfaces). + +**Resolution direction:** When AR stage active, glance mirrors AR/HUD phrase only; no second animated companion narrative. + +--- + +### C11 β€” Document authority deadlock + +| Severity | High | +| -------- | ---- | +| Type | Process | + +| Doc class | Session stance | +| ---------- | -------------- | +| BINDING scope/spec | Audio-first | +| DESIGN_REFERENCE UIUX | 2D root; AR cover; β€œdon’t redesign session” | +| SUPPORTING redesign map + this file | AR root when capable | +| AR MVP freeze | No silent `App/AR/**` feature expansion | + +Agents and PRs will follow UIUX/binding until Phase 0 + UIUX B1–B4 amendment. + +## 4. Conflict graph + +```text + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Product law β”‚ audio-first + β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ C1 + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β–Ό β–Ό β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ UIUX B1 β”‚ β”‚ Shipped β”‚ β”‚ Redesign β”‚ + β”‚ pocket+ β”‚ β”‚ 2D root β”‚ β”‚ AR root β”‚ + β”‚ audio β”‚ β”‚ AR leaf β”‚ β”‚ β”‚ + β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ + β”‚ C7 β”‚ C3 β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β–Ό + Session reality + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β–Ό β–Ό β–Ό + Presence AR cover Map cover + β”‚ β”‚ β”‚ + └──── C2 ────┴──── C4 β”€β”€β”€β”€β”˜ + exclusive Lira? + β”‚ + C5 a11y spine (2D-only) + C9 no fallback branch + C11 authority deadlock +``` + +## 5. Non-conflicts (preserve) + +| Stable | Why | +| ------ | --- | +| Push = walk lifecycle | Correct | +| Settings = sheet | Correct | +| AR non-accidental dismiss + mirrored Pause/End | Safety law (#126) β€” keep even if AR-default | +| One companion ID + B7 crosswalk / matrix | Semantic unity | +| Map not navigation-grade | Scope | +| `ARWorldCommand` only when handler attached | Architecture | +| Presentation β‰  gameplay | Binding | + +## 6. Target session IA (conflict-resolving sketch) + +Proposal for Phase 0/2 docs β€” **not shipped**: + +```text +Active Walk + β”‚ + β”œβ”€ IF ar_capability ∈ {available, active} + β”‚ STAGE = AR canvas (session root chrome) + β”‚ HUD: phrase Β· path Β· bond Β· continuity + β”‚ Controls: Pause Β· End Β· (Map peek) Β· (Switch to 2D) + β”‚ Lira: AR only (2D figure suppressed) ← C2 + β”‚ + β”œβ”€ ELSE + β”‚ STAGE = 2D presence (today’s root) + β”‚ Controls: Pause Β· End Β· AR (disabled+reason) Β· Map + β”‚ + └─ Audio: always policy-on (supporting), not a stage + +Map: sheet/peek under current stage β€” not peer cover to AR ← C4 +Modes: pocket (audio+HUD) vs eyes-up (AR) explicit ← C7 +``` + +## 7. Resolution priority + +| Order | Conflict | Action | Phase | +| ----: | -------- | ------ | ----- | +| 1 | C1, C11 | Binding law + UIUX B1/B2 amendment | 0 | +| 2 | C3, C9 | Session IA: default stage + fallback branch | 0 docs / 2 code | +| 3 | C2 | Exclusive Lira under AR (prefer HUD-only 2D) | 2 issue | +| 4 | C4 | Map modality under AR | 2 issue | +| 5 | C5 | Dual a11y spines | 2 docs + impl | +| 6 | C6 | Exit copy / stage switch | 2 | +| 7 | C7 | Mode policy pocket vs eyes-up | 0–2 | +| 8 | C8 | Attention priority table | 0 docs | +| 9 | C10 | Glance policy when AR open | later / flag-on | + +## 8. Implementation constraints + +- Do **not** break Core isolation or turn AR into gameplay authority. +- Phase 2 requires a **scoped freeze exception issue** for session-default AR UX. +- Keep Demo completable without camera. +- Outdoor AR PASS still gated on #41 β€” IA changes must not invent quality claims. + +## 9. Claim labels + +| Label | Claim | +| ----- | ----- | +| OBSERVED | 2D session root; AR/map independent covers; B1.3 exclusive Lira; B4 anti-redesign; #126 safety chrome | +| INFERRED | AR-default without IA rewrite will fight UIUX and a11y spine | +| NOT_COMPUTABLE | Whether mode-aware IA improves outdoor completion without raising gameplay scope (needs device product evidence) | +| NOT_COMPUTABLE | Outdoor VO+AR; default-AR completion rate | + +## 10. Related + +| Doc | Role | +| --- | ---- | +| [`AR_PRODUCT_REDESIGN_MAP.md`](AR_PRODUCT_REDESIGN_MAP.md) | Master redesign map | +| [`../plans/AR_APP_REDESIGN_PLAN.md`](../plans/AR_APP_REDESIGN_PLAN.md) | Phases | +| [`AR_SYSTEM_INVENTORY.md`](AR_SYSTEM_INVENTORY.md) | Files | +| [`WAYKIN_UIUX_SPEC.md`](WAYKIN_UIUX_SPEC.md) | Current session IA law (design reference) | +| [`AR_MVP_FREEZE.md`](AR_MVP_FREEZE.md) | Feature freeze | +| [`REAL_WALK_TO_AR_MAPPING.md`](REAL_WALK_TO_AR_MAPPING.md) | Command + entry gaps | + +--- + +*End of AR session IA conflicts v1.0* diff --git a/docs/design/AR_SYSTEM_INVENTORY.md b/docs/design/AR_SYSTEM_INVENTORY.md new file mode 100644 index 0000000..82d2d10 --- /dev/null +++ b/docs/design/AR_SYSTEM_INVENTORY.md @@ -0,0 +1,144 @@ +# Waykin AR System Inventory + +```yaml +document_id: WAYKIN-AR-SYSTEM-INVENTORY-001 +version: 1.1 +date: 2026-07-29 +status: SUPPORTING +parent: docs/design/AR_PRODUCT_REDESIGN_MAP.md +recovered_on: main_after_freeze_249 +companion_runtime: MESHY_EMBER_FOX_WALK_V1 +mesh_authority_pr: 246 +does_not_override: [SOLO_MVP_SCOPE, WAYKIN_SPEC, AR_MVP_FREEZE] +``` + +Complete file-level map of AR-related code and contracts. Paths relative to repo root. + +**Runtime note (post-#246):** packaged companion is **Ember Fox** (`MESHY_EMBER_FOX_WALK_V1`) with versioned async template load, procedural fallback, live authored replacement, and explicit scene-anchor detach. Artist-blend / DCC mid-LOD is **historical**, not the active default. + +## 1. Core (platform-neutral semantics) + +| Path | Role | +| ---- | ---- | +| `Sources/WaykinCore/Presentation/ARPresentationContracts.swift` | `ARCapabilityState`, `CompanionPresentation`, `DiscoveryPresentation`, `ThreatPresentation`, `ARWorldCommand` | +| `Sources/WaykinCore/Presentation/SpatialIntent.swift` | Placement mode, distance band, bearing, scale, persistence hints | +| `Sources/WaykinCore/Engines/CompanionPresentationMatrix.swift` | Shared behavior + distance + AR behavior strings | +| `Sources/WaykinCore/Engines/AudioExperienceLayer.swift` | Semantic cue kinds; AR presentation-transition cues when higher priority silent | +| `Sources/WaykinCore/Path/PathAudioCoupling.swift` | Path soft cues onto same cue kinds | +| `Sources/WaykinCore/Experiences/Experiences.swift` | `CompanionWalkExperience` β€” walk loop; **does not** emit `ARWorldCommand` | +| `Sources/WaykinCore/Experiences/ExperienceProtocol.swift` | Experience protocol surface | +| `Sources/WaykinCore/Diagnostics/AudioPlaybackDiagnostic.swift` | Audio diagnostics | + +**Isolation rule:** no ARKit, RealityKit, MapKit, or audio filenames under `Sources/WaykinCore`. + +## 2. App orchestration + +| Path | Role | +| ---- | ---- | +| `App/WaykinApp.swift` | `WaykinAppModel`: walk/demo lifecycle, `emitARWorldCommands`, attach/detach handler, `showsARCompanion` fullScreenCover | +| `App/AppAudioCuePlayer.swift` | Cue kind β†’ WAV + AVAudioSession | +| `App/CompanionPresenceView.swift` | 2D presence surface | +| `App/SessionMapPresentation.swift` | Map presentation state | +| `App/SessionMapViews.swift` | Session map UI | +| `App/WalkRoutePlanning.swift` | Route planning presentation helpers | + +## 3. App AR stack (`App/AR/`) + +### Session & commands + +| Path | Role | +| ---- | ---- | +| `App/AR/CanonicalARWorldCommandMapper.swift` | Companion/pursuit/event/path β†’ `[ARWorldCommand]`; stable discovery/threat UUIDs | +| `App/AR/CanonicalARSessionView.swift` | Production AR SwiftUI + `CanonicalARSessionRuntime`; command attach protocol | +| `App/AR/ARWorldCommandRenderer.swift` | Execute spawn/update/remove/clear; escort mode; skins | +| `App/AR/ARPlacementResolver.swift` | World-plane plant; assumed-ground placement fallback when raycast fails; camera fallback; continuity re-plant | +| `App/AR/ARSessionCoordinator.swift` | ARSession lifecycle | +| `App/AR/ARCapabilityMonitor.swift` | World tracking support + camera auth β†’ capability | +| `App/AR/AREntityRegistry.swift` | Entity ID registry | +| `App/AR/ARContinuityHint.swift` | Continuity HUD copy | +| `App/AR/WaykinARView.swift` | `ARView` representable shell | + +### Companion visuals + +| Path | Role | +| ---- | ---- | +| `App/AR/Companion/CompanionEntityFactory.swift` | Procedural Living Familiar (bounded load fallback only) | +| `App/AR/Companion/CompanionPresentationState.swift` | Renderer state enum + reducer | +| `App/AR/Companion/CompanionVisualConfiguration.swift` | Visual config payload | +| `App/AR/Companion/LiraARAssetLoader.swift` | Versioned async USDZ template load; procedural fallback; live authored replace; base-transform preserve | +| `App/AR/Companion/LiraARAssetCatalog.swift` | Bundled asset names + `MESHY_EMBER_FOX_WALK_V1` evidence class | +| `App/AR/Companion/LiraARAnimationLibrary.swift` | Non-skeletal animation helpers | +| `App/AR/Companion/LiraARMotion.swift` | Ambient motion pure functions | +| `App/AR/Companion/LiraMeshGeometry.swift` | Procedural mesh descriptors (fallback path) | +| `App/AR/Companion/LiraSkeletalRig.swift` | Joint hierarchy contract | +| `App/AR/Companion/LiraSkeletalAnimationLibrary.swift` | Skeletal clips | +| `App/AR/Companion/LiraSkeletalPlayer.swift` | RealityKit skeletal driver; authored walk targets skeleton; stands down multi-part DCC when authored clip active | + +### Diagnostics & lab + +| Path | Role | +| ---- | ---- | +| `App/AR/Diagnostics/` | AR diagnostic recorder / validation hooks | +| `App/AR/Debug/` | AR lab / debug surfaces | +| `ARLab/` (target) | Isolated engineering target (if present) | + +## 4. Assets + +| Path | Role | +| ---- | ---- | +| `App/Resources/Lira_AR_Base.usdz` | **Ember Fox** packaged runtime (primary; xcodegen) | +| `App/Resources/Companion/Lira/Lira_AR_Base.usdz` | Nested mirror (byte-identical) | +| `docs/assets/companion/ar/Lira_AR_Base.usdz` | Docs mirror (byte-identical) | +| `docs/assets/companion/ar/artist/EXPORT_OK` | Evidence marker `MESHY_EMBER_FOX_WALK_V1` | +| `App/Resources/Companion/Lira/Clips/*.usdz` | Six per-state sidecars (catalog/fallback; not bound while authored walk active) | +| `App/Resources/Assets.xcassets/LiraStills/**` | Session 2D stills matrix | +| `App/Resources/Assets.xcassets/LiraGlyph/**` | Glyphs | +| `App/Resources/Audio/**` | Produced WAV cues | +| `ArtSource/**` | Artist provenance sources (historical packages may remain; not runtime default) | + +## 5. Tests / gates (AR-related) + +| Area | Examples (names may evolve) | +| ---- | --------------------------- | +| Package mesh scale | `LiraPackagedMeshScaleTests` | +| Skinned USDZ | `LiraSkinnedUSDZTests` | +| Embodiment / motion | `ARCompanionEmbodimentTests`, `LiraARMotionTests` | +| World event pressure | `WorldEventCadenceTests` (gameplay; PR #248) | +| Integration | `CanonicalARRuntimeIntegrationTests` | +| Real walk handler | `RealMovementSessionTests` (handler batches) | +| Soak / replay | `ARCommandReplaySoakTests` | +| Isolation | `scripts/check_core_framework_isolation.sh` | +| USDZ integrity | `make check-lira-usdz` / `scripts/check_lira_usdz_integrity.sh` | +| CI | `validate`, `swift-package`, `native-ios` | + +**Superseded mesh PRs:** #242 / #243 closed; do not merge. Mesh authority: **#246**. + +## 6. Lifecycle mapping (commands) + +| Walk event | Commands | +| ---------- | -------- | +| Demo/real start | `spawnCompanion` | +| Accepted tick / demo advance | `updateCompanion` (+ discovery/threat per pursuit/event) | +| End / fail / clear | `clearSession` | + +Stable IDs: discovery `…D15C`, threat `…7A11` (see mapper). + +## 7. Presentation triangle (shared matrix) + +| Concern | Owner | +| ------- | ----- | +| Behavior vocabulary | `CompanionPresentationMatrix` | +| AR behavior strings | same (`idle` / `follow` / `investigate` / `alert` / `celebrate`) | +| 2D pose lean | same β†’ presence stills | +| Audio soft coupling | `AudioExperienceLayer` + path coupling after event/behavior silence | + +## 8. Docs that govern this inventory + +| Doc | Governs | +| --- | ------- | +| `docs/design/AR_MVP_FREEZE.md` | What may change in `App/AR/**` | +| `docs/design/REAL_WALK_TO_AR_MAPPING.md` | Emission rules | +| `docs/design/AR_PRODUCT_REDESIGN_MAP.md` | Product redesign envelope | +| `docs/plans/AR_APP_REDESIGN_PLAN.md` | Phased work | +| `ARCHITECTURE.md` | Ownership | +| `WAYKIN_SPEC.md` | Product contract | diff --git a/docs/design/CONTINUATION_PLAN.md b/docs/design/CONTINUATION_PLAN.md index 15d97a2..0ba30a2 100644 --- a/docs/design/CONTINUATION_PLAN.md +++ b/docs/design/CONTINUATION_PLAN.md @@ -42,7 +42,7 @@ Remaining value is **documentation accuracy**, **fresh automated baseline**, and | Phase A laptop validate (post-mesh) | **Required** on current tip (pre-mesh receipts are historical) | | Indoor device smoke | **Human β€” next** (Ember Fox protocol) | | Outdoor #41 COH | **Human β€” daylight** on post-mesh tip | -| AR redesign docs (#245) | Supporting only; recover onto current main β€” do not merge stale branch | +| AR redesign docs | Supporting only; recover via fresh branch from freeze tip (replaces stale #245 history) | ## Completed eng waves (recent) diff --git a/docs/design/PRODUCT_VISION_NORTH_STAR.md b/docs/design/PRODUCT_VISION_NORTH_STAR.md new file mode 100644 index 0000000..319e708 --- /dev/null +++ b/docs/design/PRODUCT_VISION_NORTH_STAR.md @@ -0,0 +1,156 @@ +# Waykin Product Vision β€” North Star + +```yaml +document_id: WAYKIN-PRODUCT-VISION-NORTH-STAR-001 +version: 1.0 +date: 2026-07-29 +status: FUTURE_REFERENCE +authority: REFERENCE_ONLY +maturity: FUTURE +evidence_class: OPERATOR_INTENT +does_not_authorize: implementation +parent_ladder: docs/canonical/MVP_TO_VISION_LADDER.md +related: + - docs/design/AR_PRODUCT_REDESIGN_MAP.md + - docs/plans/AR_APP_REDESIGN_PLAN.md + - WAYKIN_SPEC.md + - docs/SOLO_MVP_SCOPE.md + - docs/canonical/CURRENT_CAPABILITY_MATRIX.md + - ROADMAP.md +``` + +## 1. Purpose + +State the **long-term product idea** for Waykin so planning, AR redesign, and fitness/worldbuilding work share one north star. + +**This document does not authorize implementation.** +Binding law remains `docs/SOLO_MVP_SCOPE.md` and `WAYKIN_SPEC.md` until explicitly promoted. See [`../canonical/MVP_TO_VISION_LADDER.md`](../canonical/MVP_TO_VISION_LADDER.md) for the gated path from MVP β†’ this vision. + +## 2. North-star statement + +> **Waykin is an AR companion platform for real-world movement.** +> A persistent companion accompanies you on **walks, runs, rides, and other fitness activities** β€” present in AR when you look up, supportive when you don’t. Over time the world around that companion deepens (**worldbuilding**), and people can **design their own companions and experiences**. + +### One-liner variants + +| Context | Line | +| ------- | ---- | +| Consumer | Your AR companion for every mile. | +| Product | AR companion + fitness movement + eventual worldbuilding and creator experiences. | +| Engineering | Movement-authoritative sessions; AR-primary presentation; extensible activity, companion, and experience seams. | + +## 3. Vision pillars + +| Pillar | Intent | +| ------ | ------ | +| **1. AR companion presence** | The companion is the emotional and visual center β€” designed for AR first, with audio/HUD/map as supporting channels. | +| **2. Real movement** | The product is lived outdoors (and on real routes), not a couch game. Movement is gameplay authority. | +| **3. Multi-activity fitness** | Walk is the proven beachhead; **run, ride, and further activities** expand once integrity, safety, and return-intent are proven per mode. | +| **4. Relationship (Bond)** | Long-term progression is relationship with the companion, not a generic XP treadmill. | +| **5. Worldbuilding** | The companion’s world deepens: lore, places, rituals, pursuit/pressure mythos, memory β€” still presentation- and content-bounded, not open MMO sim by default. | +| **6. Creator eventual** | Users (and partners) eventually **design companions and experiences** through governed tools/packs β€” after first-party loop and platform seams are stable. | + +## 4. Experience shape (eventual) + +```text +User moves (walk / run / ride / …) + ↓ +Movement integrity + activity profile + ↓ +World + events + companion runtime + Bond + ↓ +Presentation + β˜… AR companion in the world (when capable) + Β· Audio / haptics support + Β· HUD / glance / Watch (when shipped) + Β· Map / path (semantic, not nav-cert) + ↓ +Session memory β†’ long-arc relationship + world state + ↓ +(Later) Experience packs Β· user-designed companions Β· deeper world arcs +``` + +## 5. Activity model (eventual) + +| Activity | Role in vision | MVP status (binding today) | +| -------- | -------------- | -------------------------- | +| **Walk** | Beachhead; prove loop + AR outdoor | **Only authorized launch activity** | +| **Run** | High-intensity companion pacing | Deferred until walk proven | +| **Ride** (bike / similar) | Speed/distance context; safety-first UI | Deferred | +| Other (hike, etc.) | Only after multi-activity framework exists | Deferred | + +**Rule:** New activities are **profiles** on shared movement + companion + AR seams β€” not separate apps β€” and each requires integrity thresholds, outdoor evidence, and safety copy. + +## 6. Fitness model (eventual) + +| Layer | Vision | Today | +| ----- | ------ | ----- | +| Session metrics | Distance, duration, effort context | Distance/time + soft HK reads | +| HealthKit | Optional enrichment + later workout write | Read enrichment implemented; write deferred | +| Watch | Glance + workout session mirror | Deferred (reference only) | +| Live effort (e.g. HR) | Soft context; must not coerce pressure | Deferred | +| Coaching/medical | **Out of vision** as claims | Never claim medical device | + +Fitness **serves the companion relationship and movement honesty** β€” it is not a pure metrics dashboard product. + +## 7. Companion & worldbuilding (eventual) + +| Horizon | Companion | World | +| ------- | --------- | ----- | +| **MVP** | One first-party companion (**Lira**) | Deterministic events, Bond, bounded pursuit, session memories | +| **Near** | Deeper Lira presentation (AR-primary, art, continuity) | Richer first-party mythos **as content**, not new gameplay authorities | +| **Mid** | Cosmetics / variants still first-party governed | Places, arcs, seasonal world pressure (still offline-capable core) | +| **Eventual** | **User-designed companions** (identity, look, behavior bounds) | **User/partner-designed experiences** (packs), with safety and anti-slop gates | + +**Non-negotiables even at north star:** + +- Presentation (including AR) does not own movement truth. +- Safety, pause, stop beat dramatic pressure. +- Offline-capable core loop remains; network features are additive. +- Creator systems cannot ship as unbounded gameplay mutation without governance. + +## 8. Creator / platform eventual (explicitly late) + +| Capability | Earliest conceptual gate | +| ---------- | ------------------------ | +| Experience pack **runtime seam** | After walk AR loop proven; pack format + offline fallback | +| First-party pack content | After runtime + validation | +| User-designed **experiences** | After moderation, safety, and economic policy (if any) | +| User-designed **companions** | After single-companion AR quality + identity model versioning | +| Marketplace | Only with legal, safety, and anti-abuse design β€” not MVP | + +Binding docs today **exclude** marketplace, creator SDK, multi-companion, and downloadable packs. This section is **foresight only**. + +## 9. What the north star is *not* + +- AR glasses-required day-one product +- Multiplayer social MMO +- Medical / clinical fitness claims +- Generative AI as required core loop +- Navigation-certified turn-by-turn authority +- Unlimited user content without gates + +## 10. Relationship to AR redesign docs + +| Doc | Role vs north star | +| ---- | ------------------ | +| This file | Long-term **why** and destination | +| [`MVP_TO_VISION_LADDER.md`](../canonical/MVP_TO_VISION_LADDER.md) | **Gates** from now β†’ destination | +| [`AR_PRODUCT_REDESIGN_MAP.md`](AR_PRODUCT_REDESIGN_MAP.md) | Near-term **AR-designed walk MVP** architecture envelope | +| [`AR_APP_REDESIGN_PLAN.md`](../plans/AR_APP_REDESIGN_PLAN.md) | Near-term execution phases for AR walk identity/UX | +| [`AR_SESSION_IA_CONFLICTS.md`](AR_SESSION_IA_CONFLICTS.md) | Session IA conflicts for AR-primary walk | + +Near-term redesign is **chapter one** of this north star (AR companion on **walks**), not the whole book. + +## 11. Promotion rule + +To move any north-star item into binding scope: + +1. Ladder gate for that rung is green (evidence + product decision). +2. Update `SOLO_MVP_SCOPE` / `WAYKIN_SPEC` / capability matrix. +3. ADR when boundaries (activity model, companion roster, creator, placement) change. +4. No silent implementation from this file alone. + +--- + +*North star v1.0 β€” REFERENCE_ONLY. Operator intent captured 2026-07-29.* diff --git a/docs/design/README.md b/docs/design/README.md index 1cf1d90..c5d1e33 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -2,6 +2,21 @@ Visual system imports and production follow-ons for the app repository. +## AR product redesign (SUPPORTING β€” recovered post-freeze) + +| Doc | Purpose | Class | +| --- | ------- | ----- | +| [AR_PRODUCT_REDESIGN_MAP.md](AR_PRODUCT_REDESIGN_MAP.md) | Master map: identity, architecture envelope, freeze rings, target IA | SUPPORTING / NEAR_TERM | +| [AR_SYSTEM_INVENTORY.md](AR_SYSTEM_INVENTORY.md) | File-level AR / presentation inventory (Ember Fox runtime) | SUPPORTING | +| [AR_SESSION_IA_CONFLICTS.md](AR_SESSION_IA_CONFLICTS.md) | Active Session IA conflicts (C1–C11) | SUPPORTING | +| [PRODUCT_VISION_NORTH_STAR.md](PRODUCT_VISION_NORTH_STAR.md) | Long-term multi-activity / worldbuilding / creators vision | REFERENCE_ONLY / FUTURE | +| [../canonical/MVP_TO_VISION_LADDER.md](../canonical/MVP_TO_VISION_LADDER.md) | Gated R0–R8 MVP β†’ vision ladder | SUPPORTING | +| [../plans/AR_APP_REDESIGN_PLAN.md](../plans/AR_APP_REDESIGN_PLAN.md) | Phased plan (Phase 0 law β†’ evidence β†’ AR-default UX) | SUPPORTING | + +**Authority:** these docs **do not** override binding product law or AR MVP freeze. Phase 0 binding edits are a separate PR. Implementation waits for freeze + device honesty (see CONTINUATION_PLAN). + +**Operator direction (intent):** design for **AR** as primary session surface when capable; movement remains gameplay authority; audio is supporting/fallback. Binding docs may still say audio-first until Phase 0. + ## UI product vs engineering practice | Doc | Purpose | Class | @@ -39,7 +54,7 @@ Visual system imports and production follow-ons for the app repository. | [LIRA_AR_PRODUCTION_RIG.md](LIRA_AR_PRODUCTION_RIG.md) | AR mid-LOD + USDZ async load | | [LIRA_AR_SCULPT_PLAN.md](LIRA_AR_SCULPT_PLAN.md) | **Production sculpt** AR package (issue #220; replace Meshy interim) | | [LIRA_ANIMATION_PLAN.md](LIRA_ANIMATION_PLAN.md) | Session + AR animation draft plan | -| [CONTINUATION_PLAN.md](CONTINUATION_PLAN.md) | v4.1 device evidence lane (indoor β†’ TF β†’ outdoor #41) | +| [CONTINUATION_PLAN.md](CONTINUATION_PLAN.md) | Freeze-then-build continuation (device evidence β†’ optional redesign) | | [AR_MVP_FREEZE.md](AR_MVP_FREEZE.md) | AR presentation frozen for engineering | | [REAL_WALK_TO_AR_MAPPING.md](REAL_WALK_TO_AR_MAPPING.md) | Real/demo walk β†’ AR commands | | [PATHFINDING.md](PATHFINDING.md) | Semantic path progress + summary surfacing | diff --git a/docs/plans/AR_APP_REDESIGN_PLAN.md b/docs/plans/AR_APP_REDESIGN_PLAN.md new file mode 100644 index 0000000..6ffb0e6 --- /dev/null +++ b/docs/plans/AR_APP_REDESIGN_PLAN.md @@ -0,0 +1,216 @@ +# Waykin AR App Redesign Plan + +```yaml +document_id: WAYKIN-AR-APP-REDESIGN-PLAN-001 +version: 1.0 +date: 2026-07-29 +status: SUPPORTING_PLAN +authority: SUPPORTING +parent_map: docs/design/AR_PRODUCT_REDESIGN_MAP.md +inventory: docs/design/AR_SYSTEM_INVENTORY.md +constraint: "Do not break Core isolation, freeze discipline, determinism, or safety controls" +``` + +## Goal + +Near-term goal is **R1** on the [`MVP β†’ vision ladder`](../canonical/MVP_TO_VISION_LADDER.md): AR-designed **walk** companion. +Long-term destination: [`PRODUCT_VISION_NORTH_STAR.md`](../design/PRODUCT_VISION_NORTH_STAR.md) (multi-activity, fitness, worldbuilding, creators) β€” **not** implemented by this plan alone. + +## Goal (plan scope) + +Redesign Waykin as an **AR-designed walking companion app** while **preserving** the existing architecture: + +- movement = gameplay authority +- `ARWorldCommand` = presentation boundary +- single companion, Bond, bounded pursuit +- solo local MVP + +## Non-goals + +- RealityKit gameplay authority +- Multi-companion / marketplace +- Continuous walker re-anchor without ADR +- ARKit inside `WaykinCore` +- Dropping semantic audio +- Outdoor quality claims without #41 PASS + +## Phase overview + +| Phase | Name | Break risk | Freeze lift? | Binding law change? | +| ----- | ---- | ---------- | ------------ | ------------------- | +| **0** | Product law & agent context | Low | No | **Yes** | +| **1** | Evidence (#41, sim regression) | Low | No | No | +| **2** | AR-default session UX | Med | **Issue-scoped** | No (uses Phase 0 law) | +| **3** | Controlled AR polish unfreeze | Med | Named items only | Only if placement policy changes | +| **4** | Optional architecture expansions | High | ADR required | Yes | + +--- + +## Phase 0 β€” Product law (docs / agents only) + +**Objective:** Make β€œAR-designed” the written product contract so humans and agents stop optimizing for audio-first identity. + +### Work items + +| ID | Task | Files | +| -- | ---- | ----- | +| P0.1 | Rewrite product promise | `docs/SOLO_MVP_SCOPE.md` | +| P0.2 | Rewrite product contract + MVP systems narrative | `WAYKIN_SPEC.md` | +| P0.3 | Hero + pillars | `README.md` | +| P0.4 | Presentation stack narrative | `ARCHITECTURE.md` (intro / primary systems) | +| P0.5 | User-facing terms | `docs/legal/TERMS.md` | +| P0.6 | Agent pack one-liner | `skills/**/references/REPO_CONTEXT.md`, `.grok/skills/**/REPO_CONTEXT.md` | +| P0.7 | Audio skill wording | `skills/waykin-audio/SKILL.md` β€” audio = channel not genus | +| P0.8 | Pointer from freeze + continuation | `AR_MVP_FREEZE.md`, `CONTINUATION_PLAN.md` β†’ this plan + map | +| P0.9 | Design YAML flags | e.g. `LIRA_ANIMATION_PLAN.md` `audio_first` β†’ document historical / `ar_designed` | +| P0.10 | Code comments only | `AppAudioCuePlayer.swift`, `project.yml` β€” β€œpocket-safe audio” not β€œproduct is audio-first” | + +### Acceptance + +```bash +# After Phase 0, product-identity hits should be gone or historical: +rg -n -i 'audio-first|audio first' --glob '!**/receipts/**' +# Allowed: historical ADR notes, "PRIOR", or pocket-audio reliability wording clearly not product genus +``` + +- Document authority order unchanged +- No Swift behavior change required in Phase 0 +- `make validate` still green if code comments-only + +### Exit criteria + +Binding docs no longer define Waykin as audio-first; AR is primary **designed** session surface; audio remains a required **supporting** presentation system. + +--- + +## Phase 1 β€” Evidence (no feature expansion) + +**Objective:** Prove AR quality claims are honest before UX defaults hard to AR. + +| ID | Task | Evidence | +| -- | ---- | -------- | +| P1.1 | Keep integration/soak tests green on tip | CI / local `make test` | +| P1.2 | Indoor AR smoke human receipt | `INDOOR_AR_HYBRID_SMOKE.md` | +| P1.3 | Outdoor #41 re-walk COH | Outdoor receipt on tip SHA | +| P1.4 | Continuity notes reviewed | `ok_present` / re-plant rates | + +### Exit criteria + +- No new outdoor PASS claim without receipt +- Failures filed as defects (freeze allows defects) + +--- + +## Phase 2 β€” AR-default session UX (Ring B) + +**Objective:** Product *feels* like an AR app when the device can do AR. + +**Requires:** Phase 0 merged + GitHub issue unfreezing **UX-only** items (not new mechanics). + +**IA conflicts to close:** [`../design/AR_SESSION_IA_CONFLICTS.md`](../design/AR_SESSION_IA_CONFLICTS.md) (especially C2 exclusive Lira, C3 session root, C4 map modality, C9 fallback). + +| ID | Task | Constraint | +| -- | ---- | ---------- | +| P2.1 | Default present AR when capability available at walk start (or stronger primary CTA) | Mirrored Pause/End; no swipe-dismiss trap (#126) | +| P2.2 | First-class fallback when camera denied/unsupported | 2D presence + copy; walk still succeeds | +| P2.3 | Compact HUD over AR | Bond, path phrase, pressure, continuity β€” presentation only | +| P2.4 | Entry flow polish | Settings / permission / re-open AR | +| P2.5 | Demo parity | Deterministic; AR optional if no camera in sim | + +### Acceptance + +- Walk completable without AR +- Walk with AR: spawn/update/clear still via mapper +- Isolation script pass +- No new `ARWorldCommand` cases unless separate issue +- UI change receipt if material (`UI_CHANGE_VALIDATION_RECEIPT.md`) + +### Exit criteria + +Capability-available devices land in AR as the normal active session; fallback path documented and tested. + +--- + +## Phase 3 β€” Controlled AR polish (optional) + +Only after Phase 2, still presentation-only: + +| ID | Examples | Still forbidden | +| -- | -------- | --------------- | +| P3.1 | Placement coach marks | Gameplay hooks | +| P3.2 | Degraded-tracking UX copy/visuals | Tracking as truth | +| P3.3 | Art package swaps per #220 process | Hero-only runtime without issue | +| P3.4 | Performance LOD tuning | New companion mechanics | + +Each item needs its own issue citing `AR_MVP_FREEZE.md` exception scope. + +--- + +## Phase 4 β€” Architecture expansions (optional, high risk) + +**Do not schedule by default.** Requires ADR + binding scope edit. + +| Candidate | Why risky | +| --------- | --------- | +| Continuous walker re-anchor | Contradicts #125 world-plant decision | +| AR-owned encounter logic | Breaks presentationβ‰ gameplay | +| Multi-entity environment sim | Scope + freeze | +| Glasses-required mode | Explicit non-goal today | + +--- + +## Dependency graph + +```text +Phase 0 (law) + β”‚ + β–Ό +Phase 1 (evidence) ── parallel with early design mocks + β”‚ + β–Ό +Phase 2 issue filed (UX unfreeze scope) + β”‚ + β–Ό +Phase 2 implementation PRs (small, testable) + β”‚ + β–Ό +Phase 3 optional polish issues + β”‚ + β–Ό +Phase 4 only if product ratifies +``` + +## PR slicing rules (don’t break the repo) + +1. **One concern per PR** (law vs UX vs mesh vs evidence). +2. **No Core AR imports** β€” enforced by isolation script. +3. **Prefer adapter/UX changes** over experience rewrites. +4. **Keep Demo CI-green** without camera. +5. **Cite freeze issue** on any `App/AR/**` feature diff. +6. **Update map/plan version** when phases complete. + +## Rollback + +| If | Then | +| -- | ---- | +| Phase 0 confuses external readers | Revert docs PR; map remains historical | +| Phase 2 harms completion rate | Feature-flag default AR; keep optional cover | +| Continuity regresses outdoors | Defect fix under freeze; disable default AR | + +## Success metrics (product) + +| Metric | Signal | +| ------ | ------ | +| Identity coherence | Binding docs + README + skills agree | +| AR-native feel | Capability-available sessions open AR by default (Phase 2) | +| Architecture integrity | Isolation + soak + no gameplay-from-tracking | +| Honesty | Outdoor claims match receipts | + +## References + +- Map: [`../design/AR_PRODUCT_REDESIGN_MAP.md`](../design/AR_PRODUCT_REDESIGN_MAP.md) +- Inventory: [`../design/AR_SYSTEM_INVENTORY.md`](../design/AR_SYSTEM_INVENTORY.md) +- Session IA conflicts: [`../design/AR_SESSION_IA_CONFLICTS.md`](../design/AR_SESSION_IA_CONFLICTS.md) +- Freeze: [`../design/AR_MVP_FREEZE.md`](../design/AR_MVP_FREEZE.md) +- Walk mapping: [`../design/REAL_WALK_TO_AR_MAPPING.md`](../design/REAL_WALK_TO_AR_MAPPING.md) +- UIUX: [`../design/WAYKIN_UIUX_SPEC.md`](../design/WAYKIN_UIUX_SPEC.md) diff --git a/docs/plans/README.md b/docs/plans/README.md index 72c31e5..47bacfe 100644 --- a/docs/plans/README.md +++ b/docs/plans/README.md @@ -6,3 +6,16 @@ - [Persistence Hardening Checklist](PERSISTENCE_HARDENING_CHECKLIST.md) Persistence implementation is sequenced as WP-DB1 through WP-DB6. CloudKit remains a decision gate rather than an active implementation workstream. + +## AR product redesign (SUPPORTING) + +| Doc | Purpose | +| --- | ------- | +| [AR_APP_REDESIGN_PLAN.md](AR_APP_REDESIGN_PLAN.md) | Phased AR-app redesign plan (law β†’ evidence β†’ UX) | +| [../design/AR_PRODUCT_REDESIGN_MAP.md](../design/AR_PRODUCT_REDESIGN_MAP.md) | Master redesign map | +| [../design/AR_SYSTEM_INVENTORY.md](../design/AR_SYSTEM_INVENTORY.md) | System inventory (Ember Fox runtime) | +| [../design/AR_SESSION_IA_CONFLICTS.md](../design/AR_SESSION_IA_CONFLICTS.md) | Session IA conflicts | +| [../design/PRODUCT_VISION_NORTH_STAR.md](../design/PRODUCT_VISION_NORTH_STAR.md) | North-star vision (REFERENCE_ONLY) | +| [../canonical/MVP_TO_VISION_LADDER.md](../canonical/MVP_TO_VISION_LADDER.md) | MVP β†’ vision ladder | + +These plans **do not** authorize implementation until Phase 0 binding promotion and freeze/device gates in CONTINUATION_PLAN. From 77c650b24703c57fca1e8eefdbe4e19e0c77bf81 Mon Sep 17 00:00:00 2001 From: Daniel Meyer Date: Wed, 29 Jul 2026 15:05:10 -0700 Subject: [PATCH 2/2] docs: address Codex review on redesign recovery (#251) Require Phase 1 indoor+outdoor device evidence before Phase 2 AR-default UX; document assumed-ground then camera placement fallback; mark recovery as landing via #251 (complete after merge). --- docs/collaboration/ACTIVE_WORK.md | 2 +- docs/design/AR_PRODUCT_REDESIGN_MAP.md | 3 ++- docs/plans/AR_APP_REDESIGN_PLAN.md | 9 ++++++--- 3 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/collaboration/ACTIVE_WORK.md b/docs/collaboration/ACTIVE_WORK.md index 3564719..ae9593d 100644 --- a/docs/collaboration/ACTIVE_WORK.md +++ b/docs/collaboration/ACTIVE_WORK.md @@ -16,7 +16,7 @@ Last updated: 2026-07-29 (**FREEZE MERGED** β€” #249; device indoor next; no red | Issue #41 β€” outdoor / physical validation | Human device | **Parked** β€” scaffold [OUTDOOR_QA_RECEIPT_20260729T191500Z_7df3a16_PENDING.md](../design/receipts/OUTDOOR_QA_RECEIPT_20260729T191500Z_7df3a16_PENDING.md); walk after indoor preferred | [DEFERRED_RECOMMENDATIONS.md](../design/DEFERRED_RECOMMENDATIONS.md) | | Issue #247 β€” TF archive hold | Product / dist | **Softened, not closed** β€” Prabu photo shows authored mesh on *some* build; still need OBSERVED on **exact freeze/archive SHA** before TF | [#247](https://github.com/scrimshawlife-ctrl/Waykin/issues/247) | | Internal TestFlight RC | Human (signing / ASC) | **Blocked** β€” freeze + #247 + fresh validate first | [TESTFLIGHT_RC_CHECKLIST.md](../design/TESTFLIGHT_RC_CHECKLIST.md) | -| AR redesign docs recovery | Docs lane | **In progress** β€” fresh branch from current main (Ember Fox inventory); supersedes stale [#245](https://github.com/scrimshawlife-ctrl/Waykin/pull/245) history | SUPPORTING only; no Phase 0 binding edits | +| AR redesign docs recovery | Docs lane | **Landing via [#251](https://github.com/scrimshawlife-ctrl/Waykin/pull/251)** β€” recovered SUPPORTING docs on freeze main; supersedes stale [#245](https://github.com/scrimshawlife-ctrl/Waykin/pull/245). After merge: treat recovery **complete**; close #245 | SUPPORTING only; no Phase 0 binding edits | | AR session redesign PRs / Phase 0 law | β€” | **Not started** β€” build-on-top only after freeze + device honesty | Continuation plan steps 9–12 | ## Tip identity diff --git a/docs/design/AR_PRODUCT_REDESIGN_MAP.md b/docs/design/AR_PRODUCT_REDESIGN_MAP.md index e766301..f0f8326 100644 --- a/docs/design/AR_PRODUCT_REDESIGN_MAP.md +++ b/docs/design/AR_PRODUCT_REDESIGN_MAP.md @@ -162,7 +162,8 @@ WaykinAppModel | Rule | Detail | | ---- | ------ | | Default | World-plane plant (ground raycast β†’ `AnchorEntity`) | -| Fallback | Camera-anchor if raycast fails | +| Fallback 1 | If raycast fails: **assumed-ground** world anchor at estimated floor height (`ARPlacementResolver.placeCompanion`) | +| Fallback 2 | If assumed-ground also fails: **camera-anchor** placement | | Continuity | Re-plant if missing / detached / > ~6 m from camera | | `.follow` | Local pose only β€” **not** continuous walker re-anchor | | Expansion | Continuous escort requires **new product issue + ADR** | diff --git a/docs/plans/AR_APP_REDESIGN_PLAN.md b/docs/plans/AR_APP_REDESIGN_PLAN.md index 6ffb0e6..61cb1b7 100644 --- a/docs/plans/AR_APP_REDESIGN_PLAN.md +++ b/docs/plans/AR_APP_REDESIGN_PLAN.md @@ -96,8 +96,11 @@ Binding docs no longer define Waykin as audio-first; AR is primary **designed** ### Exit criteria -- No new outdoor PASS claim without receipt -- Failures filed as defects (freeze allows defects) +- **P1.2 indoor Ember Fox smoke** filled with tip-bound `evidence_class: OBSERVED` (or PARTIAL with filed defects) β€” not SKIPPED by default +- **P1.3 outdoor #41** filled with tip-bound COH PASS/PARTIAL/FAIL (OBSERVED only) β€” not inventable from sim/indoor +- No new outdoor PASS claim without outdoor receipt on the tested SHA +- Failures filed as **narrow defects** (freeze allows defects; no broad redesign from a single FAIL) +- Phase 1 does **not** exit while indoor and outdoor device rows remain NOT_COMPUTABLE without an explicit product waiver issue --- @@ -105,7 +108,7 @@ Binding docs no longer define Waykin as audio-first; AR is primary **designed** **Objective:** Product *feels* like an AR app when the device can do AR. -**Requires:** Phase 0 merged + GitHub issue unfreezing **UX-only** items (not new mechanics). +**Requires:** Phase 0 merged + **Phase 1 exit criteria met** (indoor smoke + outdoor #41 tip-bound receipts, or explicit waiver issue) + GitHub issue unfreezing **UX-only** items (not new mechanics). **IA conflicts to close:** [`../design/AR_SESSION_IA_CONFLICTS.md`](../design/AR_SESSION_IA_CONFLICTS.md) (especially C2 exclusive Lira, C3 session root, C4 map modality, C9 fallback).