TheLastGarden/.planning/STATE.md

---
gsd_state_version: 1.0
milestone: v1.0
milestone_name: milestone
status: in_progress
stopped_at: "Phase 2 Wave 2 final plan (Plan 02-05 letter-settings-e2e) executed in sequential mode. 4 atomic commits: 26eb77a (sim/offline + auto-harvest + letter Ink + letter-renderer), 5d58d6c (Letter overlay + Settings UI + boot save lifecycle + clock injection), dd48696 (Playwright e2e for PIPE-07), 31f8ede (compost beat toast — Plan 02-04 deferral). 312/312 vitest tests green (was 264; +48 new); Playwright PIPE-07 spec exits 0 in 1.5s test runtime / 4s end-to-end; npm run ci exits 0. UX-02 / UX-10 / CORE-03 / CORE-11 / PIPE-07 / GARD-02 / GARD-04 requirements satisfied. Phase 2 vertical slice closed end-to-end on real authored content + real save round-trip + real offline catchup — could plausibly ship as a free standalone Season-1 prologue. URL-flag FakeClock injection landed cleanly first-try, production-guarded by import.meta.env.PROD. Compost-beat UI wired as a thin transient CompostToast (minimum-viable; Ink runtime path remains compiled + loadable for Phase 4+ swap-in). gray-matter dep auto-removed (Rule 3 blocking issue surfaced via the e2e — Buffer not defined in browser; replaced with 15-line parseFrontmatter helper; bundle dropped 2.2MB → 1.9MB). All 24 Phase-2 REQ-IDs structurally satisfied across the 5-plan set. Phase 2 ready for /gsd-verify-work."
last_updated: "2026-05-09T15:08:00.000Z"
last_activity: 2026-05-09
progress:
  total_phases: 8
  completed_phases: 1
  total_plans: 8
  completed_plans: 12
  percent: 22
---

# Project State

## Project Reference

See: .planning/PROJECT.md (updated 2026-05-08)

**Core value:** Every idle mechanic must function as a metaphor that the player absorbs without being told. When economy and meaning conflict, meaning wins.
**Current focus:** Phase 02 — Season 1 Vertical Slice (Soil) — ALL 5 PLANS DONE; ready for /gsd-verify-work

## Current Position

Phase: 02 (season-1-vertical-slice-soil) — 5/5 plans complete (all waves)
Plans: 5 of 5 created (3 waves); Wave 0 (02-01) DONE; Wave 1 (02-02 + 02-03) DONE; Wave 2 (02-04 + 02-05) DONE
Status: Plan 02-05 letter-settings-e2e executed in sequential mode — 4 atomic commits (26eb77a, 5d58d6c, dd48696, 31f8ede), 48 new tests (312/312 total vitest green), npm run ci exits 0, npx playwright test exits 0 in 1.5s. UX-02 / UX-10 / CORE-03 / CORE-11 / PIPE-07 / GARD-02 / GARD-04 satisfied end-to-end. Phase 2 vertical slice closed: a player can launch, plant, grow, harvest, meet Lura, leave the tab, return ≥5min later, see the letter from the garden in voice, dismiss to the live garden — and everything persists across reload (PIPE-07 e2e proves it). All 24 Phase-2 REQ-IDs structurally satisfied across the 5-plan set. The vertical slice could plausibly ship as a free standalone Season-1 prologue (banner concern #2's escape hatch realized).
Last activity: 2026-05-09 -- Plan 02-05 execute complete; Phase 2 ready for verification

Progress: [██░░░░░░░░] 22%

## Verification Results

**Phase 1 Overall Verdict:** PASSED

| REQ-ID | Status |
|--------|--------|
| CORE-01 | PASS — scaffold builds; <5s measurement is Phase 2 |
| CORE-04 | PASS — IDB + localStorage fallback; 4 tests green |
| CORE-05 | PASS — navigator.storage.persist() all 4 scenarios |
| CORE-06 | PASS — versioned envelope + CRC-32; tamper detection |
| CORE-07 | PASS — forward-only migration chain; synthetic v0→v1 |
| CORE-08 | PASS — last-3 snapshot retention; 5-then-3 invariant |
| CORE-09 | PASS — Base64 codec + 50MB DoS cap; round-trip test |
| CORE-10 | PASS — ESLint boundaries rule + Vitest proof |
| PIPE-01 | PASS — Vite-native loader; schema violation fails build |
| PIPE-03 | PASS — asset provenance gate; refused-sample fixture |
| PIPE-05 | PASS — both doctrine docs authored + doc-lint tests |
| PIPE-06 | PASS — ci.yml; 53 tests on every push |
| AEST-08 | PASS — ProvenanceSchema 6 fields; CI gate in place |
| AEST-09 | PASS (IOU) — curation gate exists; human decision recorded |
| STRY-09 | PASS (vacuous) — /content/ convention established |
| UX-13 | PASS — anti-fomo-doctrine.md; review-enforced |

Gates run: lint (exit 0), test (53/53 green, 12 files), validate:assets (2 assets valid), build (exit 0), compile:ink (exit 0), ci (exit 0).

## Performance Metrics

**Velocity:**

- Total plans completed: 12 (1 partial — 01-05 Task 2 deferred via IOU)
- Average duration: ~7 min across all plans; Phase-2 plans are heavier (12-24min each)
- Total execution time: ~106 min across Phase 1 + Phase 2 (all 12 plans)

**By Phase:**

| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------|
| 1. Foundations & Doctrine | 7/7 (complete) | ~30 min | ~5 min |
| 2. Season 1 Vertical Slice (Soil) | 5/5 (complete; ready for /gsd-verify-work) | ~86 min | ~17 min |

**Recent Trend:**

- Last 5 plans: [02-01 foundations · 02-02 begin-plant-grow · 02-03 harvest-journal-fragments · 02-04 lura-gate-beats · 02-05 letter-settings-e2e — all green]
- Trend: → (02-05 was 20min closing plan covering boot-path rewrite + 5 new components + Playwright e2e + Rule 3 auto-fix for gray-matter Buffer issue; +48 new tests for 312/312 total green)

*Updated after each plan completion*

## Accumulated Context

### Decisions

Decisions are logged in PROJECT.md Key Decisions table.
Recent decisions affecting current work:

- Phase 1 will land all retrofit-hostile foundations (versioned saves, content/asset pipelines, sim/render firewall, anti-FOMO doctrine, Season 7 end-state design) before any feature code — research from all four researchers converged on this ordering. COMPLETE.
- Phase 2 will ship Season 1 as a complete vertical slice that could *plausibly* ship as a free standalone prologue ahead of Seasons 2-7, defending against the 7-Season scope risk.
- Plan 02-01 (Wave 0): BLOCKER 3 lastTickAt-vs-tickCount split landed — SimState carries TWO time fields with strict ownership (lastTickAt = wall-clock, app-only writes; tickCount = sim-internal monotonic). simAdapter.applyTickCount is the canonical sim → store path. Pinned by 3 store tests + 1 migrations test.
- Plan 02-01 (Wave 0): V1Payload extended in place per D-34 (no migrations[2]) — Phase-1's v1 has shipped zero production saves so adding fields with defaults in migrations[1] is cleaner. Regression-defense test asserts Object.keys(migrations).sort() === ['1'].
- Plan 02-01 (Wave 0): ESLint sim-purity rule (Block 3 of eslint.config.js) is the mechanical defense for D-33 — bans Date.now() and setInterval in src/sim/** with src/sim/scheduler/clock.ts as the lone exception. Programmatic Vitest test against the date-now-violator fixture proves the rule fires; negative test on clock.ts proves the exception holds.
- Plan 02-02 (Wave 1): GRID_LAYOUT origin-centering math corrected during execution — gridOriginX=296 / gridOriginY=168 (not the plan's 240/144 hedged "≈" values). True-centered in 1024×768.
- Plan 02-02 (Wave 1): Phaser 4 cannot be imported under happy-dom — its boot probe `checkInverseAlpha` calls `canvas.getContext('2d')` which returns null. SeedPicker test mocks src/game/event-bus to avoid pulling Phaser into the test runtime; Phaser scene behavioral coverage is the Plan 02-05 Playwright e2e's job (RESEARCH Validation Architecture explicitly states render-tier needs a real canvas).
- Plan 02-02 (Wave 1): Audio bootstrap is module-level state (not React useState) so the click handler can call it synchronously — Pitfall 5 (iOS Safari requires AudioContext construction inside the gesture, not just resume) is mitigated structurally.
- Plan 02-03 (Wave 1): Pool-exhaustion behavior chosen — sentinel fallback (`season1.soil._exhaustion`), NOT repeat-most-recent. Repeat-most-recent would silently re-grow `harvestedFragmentIds` past the corpus size, breaking the no-dup invariant downstream consumers (Journal de-dup, Lura beat counters, letter slot vocabulary) depend on. Authored warm pool ≥9 makes the sentinel structurally unreachable in normal Phase-2 play; it's a defensive structural fallback only.
- Plan 02-03 (Wave 1): Plant-type unlock thresholds finalized — rosemary @ 0 / yarrow @ 3 / winter-rose @ 6. Spaced before Lura's mid-beat (4th harvest) and farewell beat (8th harvest) per D-14, so unlocks land in tonal alignment with the arc's turns. Pitfall 10 mitigation: thresholds checked AFTER the harvest commit (3 explicit boundary tests).
- Plan 02-03 (Wave 1): Garden scene loads fragments via the EAGER `fragments` corpus filtered to Season 1, NOT via `await loadSeasonFragments(1)`. Trade-off: simpler synchronous create() vs. INEFFECTIVE_DYNAMIC_IMPORT warnings inherited from Plan 02-02. Lazy plumbing is structurally proven by `scripts/check-bundle-split.mjs`; Phase 4+ should swap to lazy when Season transitions land.
- Plan 02-03 (Wave 1): Compost beat content shipped in `content/dialogue/season1/compost-acknowledgements.ink` ahead of Plan 02-04's Ink runtime; Garden.ts compost branch carries a TODO at the wiring point. The split lets the writer iterate on voice independently of runtime work.
- Plan 02-03 (Wave 1): PIPE-02 verifier `scripts/check-bundle-split.mjs` is structured as Vitest-importable Node ESM (`runCheck()` exported, CLI gated by `import.meta.url`). Pattern reusable for Phase 4 Season-2 onboarding (extend known-content list) and Phase 8 visual-regression baselines (different filename heuristics, same export shape).
- Plan 02-04 (Wave 2): Direct binary invocation chosen over the inklecate npm wrapper API. The wrapper's executableHandler swallows non-zero exit codes silently, the stderr capture surface is undocumented. compile-ink.mjs uses `execFileSync(node_modules/inklecate/bin/inklecate{.exe})` directly so failure modes are loud (full stderr/stdout in the throw). The bundled binary IS stable; the wrapper isn't.
- Plan 02-04 (Wave 2): BLOCKER 4 mitigation — script uses `node_modules/inklecate/bin/inklecate{.exe}`, NOT the stale `inklecate-windows/`/`inklecate-mac/` per-platform-folder strings. The wrapper ships a single `bin/` directory with the .NET self-contained executable + DLLs. Verified via `ls node_modules/inklecate/bin/`. RESEARCH Assumption A6 verified first-try on Windows.
- Plan 02-04 (Wave 2): compileAllInk has a `wipe` toggle (default true for CLI; passed false from the test path) so compile-ink.test.mjs and src/content/ink-loader.test.ts don't race on the wipe step under Vitest's parallel test execution. CI's compile:ink-before-test ordering still guarantees a fully-populated directory.
- Plan 02-04 (Wave 2): compost-beat UI wiring deferred to Plan 02-05's persistence-toast surface (compost is a thinner toast variant separate from Lura's full-screen overlay; Plan 02-05 lands the toast UX alongside CORE-05's persistence-denied surface). Plan 02-04 ships the AUTHORED CONTENT (compost-acknowledgements.ink rewritten in VAR-driven branch shape) + the loadInkStory('compost-acknowledgements') path; only the toast component is missing.
- Plan 02-04 (Wave 2): STRY-07 satisfied vacuously for Phase 2 — zero .ink files contain Keeper-spoken lines. The gardener-keeper voice in compost beats acknowledges the player's actions but is never personified. Phase 7's binary choice surface (SEAS-09 / STRY-08) re-evaluates.
- Plan 02-04 (Wave 2): Cadence values: DEFAULT_DELAY_MS=1500, PER_CHAR_MS=20, MAX_DELAY_MS=4000. Calibrated against typical 80-char line (3.1s) feeling close to a thoughtful texted reply, vs short "Oh." (1.56s) feeling like a beat. Tunable in playtest by editing src/ui/dialogue/ink-runtime.ts; constants exported for the Phase 8 UX-05 reduced-motion hook.
- Plan 02-04 (Wave 2): Lura's `last_plant_type` derives from the most-recently-harvested fragment's tonal-register tag (warm → rosemary, contemplative → yarrow, heavy → winter-rose). The harvest pipeline doesn't currently store source plant type per harvest — Plan 02-05 may add that to offlineEvents. The tag-based proxy is sufficient for Phase 2's voice; Lura's branch on plant type is flavor, not a gate.
- Plan 02-05 (Wave 2): URL-flag FakeClock injection landed cleanly first-try, production-guarded by import.meta.env.PROD. Window slots `__tlgClock` / `__tlgFakeClock` / `__tlgStore` are written ONLY when `!isProd && devtime === 'fake'`; production builds silently ignore the flag. Playwright PIPE-07 spec exploits this to dispatch sim commands without pixel-precise canvas clicks — the test runs in 1.5s.
- Plan 02-05 (Wave 2): Compost-beat UI wired as a thin transient CompostToast (D-07 + GARD-04). Implementation choice surfaced in SUMMARY: minimum-viable bias chosen over the Ink runtime path. The Ink-authored richer voice in compost-acknowledgements.ink remains compiled + runtime-loadable for Phase 4+ to swap in if branching is needed. compostBeatTick monotonic counter (vs. boolean) ensures consecutive composts re-fire the toast without dedup.
- Plan 02-05 (Wave 2): Save-payload helpers extracted to src/save/payload.ts (W2 fix). Two-arg signature buildPayloadFromStore(state, nowMs) unifies Settings.tsx (passes Date.now()) and PhaserGame.tsx saveSync (passes clock.now()) without arity divergence. BLOCKER 3 — lastTickAt is the wall-clock anchor; the application layer owns the value.
- Plan 02-05 (Wave 2): 5-minute absence threshold (D-20) lives as ABSENCE_LETTER_THRESHOLD_MS constant in src/PhaserGame.tsx. Below 5min: silent resume, no overlay. ≥5min: letter Ink loads + slots bind + overlay opens. The Letter overlay's dismiss path calls bootstrapAudioContext synchronously inside the click handler (Pitfall 9 — returning player needs an audio gesture to land in the live garden).
- Plan 02-05 (Wave 2): gray-matter package replaced with a 15-line parseFrontmatter regex helper (Rule 3 — Blocking auto-fix). gray-matter pulls in Node's Buffer global which is undefined under Vite's browser bundle; the build emitted a 'Module buffer externalized' warning that masked the runtime ReferenceError surfacing only in real browsers (caught by the e2e). Bundle size dropped 2.2MB → 1.9MB as a tree-shake side effect. The dep itself remains in package.json as a deferred-items cleanup task.
- Plan 02-05 (Wave 2): Playwright dev port pinned to 5273 + --strictPort because the user's machine has another Vite project bound to 5173. reuseExistingServer false ensures the spec always launches a fresh Vite against this project. Documented in playwright.config.ts comment block.
- Phases 4-7 deliver the remaining six Seasons in mechanic-introducing pairs (Season 2 alone with prestige, Seasons 3-4, Seasons 5-6, Season 7 alone) — at most one new mechanic per Season per the scope-defense doctrine.
- Plan 01-01: scaffolded by hand (the official `npm create @phaserjs/game@latest` is interactive-only — `--template react-ts --yes` flags are silently ignored as of create-game v1.3.2); plan's documented fallback path was used. Vite 8 + TS 6 referenced-projects tsconfig layout adopted; `build` runs `tsc -b && vite build` so strict-TS gates every build. ESLint 9 installed → Plan 02 must use **flat config** (`eslint.config.js`), not legacy `.eslintrc.*`.
- Plan 01-01: pre-installed `fake-indexeddb@^6` here so Plan 03 doesn't have to re-edit `package.json`. All Phase-1 dep versions match RESEARCH.md exactly within their `^` ranges.
- Plan 01-07: minimum-viable CI workflow (49 lines) running `npm ci` + `npm run ci` on push/PR to main; ubuntu-latest only, Node 22 only, no matrix per CONTEXT user pushback against ceremony. The workflow's role is to refuse merges that break local `npm run ci`, nothing more. New CI gates (Phase 2 e2e, Phase 8 visual regression) are added by editing `package.json scripts.ci` (or new dedicated workflow files), not by editing `ci.yml` — the workflow stays stable across all future phases.
- Plan 01-07: `npm ci` (lockfile-strict) chosen over `npm install` per RESEARCH § Security Domain; `npm audit` deferred to Phase 8. `actions/setup-node@v4` with `cache: 'npm'` per RESEARCH CI Pitfall A — never cache `node_modules/` directly.
- Plan 01-05 Task 2 (north-star images): Deferred via Path C per 01-05-IOU.md. User decision: "I don't really want to deal with creating the art for this." Two placeholder PNGs committed with valid provenance sidecars. Real north-star curation deferred to Phase 5 when production-volume asset generation begins.

### Pending Todos

- **Plan 01-05 Task 2 (human curation) — Phase 5 follow-up:** 10-20 hand-curated AI generations committed to `assets/north-stars/` with provenance sidecars. Non-blocking for Phase 2 (no production AI assets until Phase 5+). Recorded in `01-05-IOU.md` with resolution path.

### Blockers/Concerns

Carry-forward banner concerns from research:

- **7-Season scope risk** is the project's biggest risk; defended by the standalone-Season-1 escape hatch (Phase 2) and the one-mechanic-per-Season cap.
- **Story ends but the loop doesn't** — Season 7 end-state design landed in Phase 1 (`.planning/season-7-end-state.md`, PIPE-05 ✓); finite Roothold ceiling enforcement deferred to Phase 4 (SEAS-04); credits/coda rest-state to Phase 7 (SEAS-10).
- **AI asset style drift** — provenance schema + CI gate + refused-sample fixture landed in Phase 1 (Plan 01-05 Task 1, PIPE-03 + AEST-08 ✓); locked 10–20-image north-star reference set deferred to Phase 5 per IOU (AEST-09 IOU); production-volume asset generation begins Phase 5+; visual regression testing in Phase 8 (PIPE-04).

## Deferred Items

Items acknowledged and carried forward:

| Category | Item | Status | Deferred At |
|----------|------|--------|-------------|
| AEST-09 | 10-20 real north-star reference images for visual regression baseline | IOU — Phase 5 follow-up | Phase 1 (01-05-IOU.md) |

## Session Continuity

Last session: 2026-05-09
Stopped at: Phase 2 Wave 2 final plan (Plan 02-05 letter-settings-e2e) executed in sequential mode — 4 atomic commits (26eb77a, 5d58d6c, dd48696, 31f8ede), 48 new tests, 312/312 total vitest green, npm run ci exits 0, Playwright PIPE-07 spec exits 0 in 1.5s test runtime / 4s end-to-end. UX-02 / UX-10 / CORE-03 / CORE-11 / PIPE-07 / GARD-02 / GARD-04 satisfied end-to-end. Phase 2 vertical slice closed: a player can launch, plant, grow, harvest, meet Lura, leave the tab, return ≥5min later, see the letter from the garden in voice, dismiss to the live garden — and everything persists across reload. URL-flag FakeClock injection production-guarded; gray-matter dep auto-removed (bundle 2.2MB → 1.9MB); compost beat wired as thin transient toast. SUMMARY at .planning/phases/02-season-1-vertical-slice-soil/02-05-letter-settings-e2e-SUMMARY.md.
Next action: `/gsd-verify-work` to UAT Phase 2. All 24 Phase-2 REQ-IDs structurally satisfied; the verifier consumes the e2e + SUMMARY for sign-off. After Phase 2 verification passes: `/gsd-discuss-phase 3` to begin the Watercolor & Cello Aesthetic phase (8 REQ-IDs: GARD-10, AEST-01..06, UX-05).