TheLastGarden/.planning/STATE.md

gsd_state_version, milestone, milestone_name, status, stopped_at, last_updated, last_activity, progress

gsd_state_version	milestone	milestone_name	status	stopped_at	last_updated	last_activity	progress
1.0	v1.0	milestone	gaps_found	Phase 2 executed end-to-end (5/5 plans, 312/312 vitest, Playwright PIPE-07 green, npm run ci exits 0). gsd-verifier scored 24/24 REQ-IDs structurally PASS and routed 6 tone/live-loop items to HUMAN-UAT.md. Live UAT (user dev-server walkthrough) surfaced 4 first-impression UX gaps that block phase sign-off — these are NOT Phase-3 aesthetic deferrals, they are minimum-viable functional UX gaps: G1 no global page CSS (white halo around dark canvas), G2 no first-run prompt after Begin (player confused — A Dark Room rule violated), G3 dim tile outlines (grid reads as 'gray check block'), G4 isolated gate visual (no surrounding wall context). Gaps documented in 02-VERIFICATION.md frontmatter (status: gaps_found). Phase 3 watercolor + cello deferral preserved — every G-fix uses Phaser primitives or one CSS file, no painted assets. HUMAN-UAT.md tone items (Lura voice, letter cadence) remain pending below the structural gaps and will be re-reviewed after gap closure. Next: /gsd-plan-phase 2 --gaps.	2026-05-09T15:55:00.000Z	2026-05-09	total_phases completed_phases total_plans completed_plans percent 8 1 12 12 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) — 5/5 plans done + verifier 24/24 PASS, but live UAT found 4 first-impression UX gaps. Awaiting /gsd-plan-phase 2 --gaps.

Current Position

Phase: 02 (season-1-vertical-slice-soil) — 5/5 plans executed; verifier 24/24 PASS; live UAT found 4 blocking/high gaps; status: gaps_found 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; gap-closure plan pending Status: All 5 Phase-2 plans executed cleanly (12 atomic feature commits + 5 doc commits). 312/312 vitest green; Playwright PIPE-07 e2e green in 1.6s; npm run ci exits 0. gsd-verifier scored 24/24 REQ-IDs structurally PASS and surfaced 6 inherently subjective tone/live-loop items in HUMAN-UAT.md. User ran the dev server (first live UAT) and reported 4 first-impression UX gaps that the test suite cannot detect: G1 white halo around dark canvas (no global page CSS), G2 no first-run prompt after Begin (A Dark Room rule violated), G3 tile outlines too dim against canvas bg, G4 gate visual stands alone with no wall context. All 4 are minimum-viable functional UX gaps — Phase 3 watercolor deferral preserved (every fix uses Phaser primitives or one CSS file). VERIFICATION.md updated to status: gaps_found with structured gap entries. The HUMAN-UAT.md tone items remain pending below the structural gaps. Last activity: 2026-05-09 -- Phase 2 execute complete; live UAT surfaced 4 UX gaps; awaiting /gsd-plan-phase 2 --gaps

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).