Goldpine Valley iOS

Goldpine Valley is a landscape-first iOS cozy frontier homestead management MVP.

Current Status

This repo now contains both the planning documents and a runnable SwiftUI iOS prototype.

Implemented:

• Landscape-first SwiftUI iOS app shell.
• Main Menu, Meadow Valley selection, and founder selection flow.
• First playable week for Meadow Valley.
• Day 1 playable field and Eli worker loop.
• Day 1-7 story arc with daily reports.
• Reusable event card system with centralized event resolution.
• Optional Day 2 Missing Goat and Day 3 Wolf/Mae events with ignored paths.
• Required Day 4 Medicine, Day 5 Fence, and Day 6 Soup events with End Day gating.
• Day 7 town vote with player-facing Council Confidence / Confidence labels, result tier, explanation bullets, and first-week completion screen. Raw vote score remains internal only.
• Terminal GameSessionPhase.weekComplete(VoteResult) flow after Day 7.
• Persistent Field A / Field B farming foundation with planting costs, day-based growth, harvesting, Farmer advantage, and report lines.
• Persistent homestead object condition foundation for Storage Shed, Fence Line, Lookout, Worker Tent, Town Board, Market Wagon, Forest Edge, and Creek Crossing.
• Timed Week 1 Work Order loop built from the 12A Storage Shed foundation. Storage Shed, Fence Line, food work, scouting, wood gathering, store organization, and Eli rest now share the protected Work Order path.
• Fence Line repair is now a timed Work Order. Starting it spends wood and assigns Eli, but the fence condition/flag changes only on completion.
• Food-production Work Orders for Fish Creek and Harvest Ready Field apply food only on completion.
• Lightweight event-driven wolf disposition, including Wary/Friendly story state and map marker behavior.
• SwiftUI map status tokens for repairs, damage, crop readiness, wolf state, required/optional events, public pressure, and vote readiness.
• Painted PNG-backed main menu hero and homestead map backgrounds in the asset catalog.
• Hero-backed setup, event, worker, report, vote, and completion presentation screens with safe image fallbacks.
• Homestead navigation architecture standardized around MapObjectID.
• HomesteadLocationCatalog as the source of truth for POI labels, normalized map positions, focused-scene backgrounds, and default panels.
• MapObject.placeholderObjects bridged from the location catalog for compatibility.
• HomesteadMapMarker status state anchored to MapObjectID locations instead of independent raw screen coordinates.
• activeLocationScene state separate from activePanel.
• Pannable homestead map with bounded pan/light zoom and POIs/status tokens inside one transformed canvas.
• Focused POI storybook scenes for Cabin, Farm Fields, Storage Shed, Fence Line, Lookout, Worker Tent, Town Board, Market Wagon, Forest Edge, and Creek Crossing.
• Shared Cabin-style focused scene ledger card template with compact location title plaques and aligned overlays/action areas across POIs.
• Minimal Storage Shed Work Order UI showing available, active, carried-over, and completed states without adding a full Work Ledger, clock HUD, or worker roster UI.
• Week 2 campaign prototype through Batch B: explicit Begin Week 2 entry, minimal ration/upkeep/weekly ledger backend shell, Day 8 Pantry Count, Day 9 Ration Policy, Day 10 Mae's limited ledger offer, Day 11 Missing Measure/Jonah foreshadowing, Day 12 Creek usefulness hook, Day 13 Public Doubt, and Day 14 Week 2 Ledger terminal outcome.
• Week 3 Batch B closes the bounded creek week after Week 2 architecture lock: explicit Begin Week 3 from the terminal Week 2 outcome, playable Day 15-20 Creek Crossing anchors, Day 20 Hidden Camp story reveal with Clara/Tate/Nell names only, public outsider stance memory, Day 21 Week 3 Ledger terminal outcome, route/camp/stance public status shell, and DEBUG checkpoints for Day 15/17/18/19/20/21.
• Week 1, Week 2, Week 3, and Week 4 architecture are locked through local commit 5e4dfe7. The Week 3 locked baseline remains pushed to origin/main and archived locally as GoldpineValley-iOS_baseline_week3_locked_ebed19c.zip.
• Week 4 full-week batch is committed at a374133: explicit Begin Week 4 from the Week 3 terminal outcome, Day 22-28 Willow Lake/sickness anchors, focused Willow Lake POI state, minimal spoilage/sickness/care-policy state, limited Week 4 Work Orders, Day 28 terminal Week 4 ledger, and a terminal post-Week-4 screen with no Begin Week 5.
• Week 4 QA patch is committed at 5e4dfe7: it adds DEBUG checkpoint week4_day23_big_catch_ready, refreshes README/GPT_HANDOFF stale Week 4 wording, and the follow-up QA recheck returned LOCK_WEEK4_ARCHITECTURE.
• Week 5 architecture is locked through the Day 35 terminal outcome.
• Week 6 architecture is locked through the Day 42 terminal outcome.
• Week 7 architecture is locked through local commit d254a41 after the Day 46 reachability / Week 7 label QA patch and recheck.
• Week 8 full-week batch implements the bounded Charter Judgment finale: explicit Begin Week 8 from terminal Week 7, Day 50-56 charter/testimony/Jonah judgment anchors, minimal Week 8 ending-axis state, limited final Work Orders, Day 56 Charter Vote, and campaign-complete terminal outcome with Menu/New Game only.
• Event-card layout now keeps tall choice lists inside the modal with a right-side scroll region for landscape iPhone screens.
• Stable NPC source/reference model sheets in ArtSource/NPC_Models/Raw/ for future portrait prep. These are not app assets and are not imported into Assets.xcassets.
• DEBUG-only checkpoint autoload harness for QA and Codex runs.
• Environmental memory presentation labels such as Thin Stores, Watchful, Risk Nearby, Worn Rails, Patched, Market Strained, Quiet, and Not Yet Open.

Not implemented yet:

• Final large-map art pass beyond current/fallback map assets.
• Final secondary POI background art pass for every location.
• SpriteKit map.
• Save/load.
• Marketplace/economy simulation beyond current story choices and the single Week 2 limited Mae offer.
• Combat or wildlife battle mechanics.
• Full Work Ledger UI, full market shop, full survival/weather/medical/court/refugee-management systems, free-travel Willow Lake/Pinebreak/Stonecap/region content, post-campaign freeplay, and New Game Plus.
• New regions beyond Meadow Valley.
• Complex animation, monetization, live services, or full final-art coverage for every optional screen-specific PNG slot.
• Import-ready cropped NPC portrait PNGs. ART1 is not ready until those files exist and human review approves the final import list.

Build

xcodebuild -project GoldpineValley.xcodeproj -target GoldpineValley -configuration Debug -sdk iphonesimulator CODE_SIGNING_ALLOWED=NO build

In sandboxed Codex runs, this command may fail on CoreSimulator or DerivedData cache permissions. If the error is simulator/cache access rather than Swift compilation, rerun the identical build with approval/escalation so Xcode can use its normal simulator and cache directories.

When using the Build iOS Apps plugin, call session_show_defaults before the first build/run in a session. Use build_run_sim for compile/install/launch, then launch_app_sim with -GPVDevCheckpoint <id> for rapid checkpoint cycling.

Simulator Verification

Known working setup:

• Xcode 26.5
• iOS Simulator runtime 26.5
• Device: iPhone 17
• Bundle id: com.exorobotics.GoldpineValley

Typical local run:

xcrun simctl install booted build/Debug-iphonesimulator/GoldpineValley.app
xcrun simctl launch booted com.exorobotics.GoldpineValley

DEBUG Checkpoint Launches

The app has a DEBUG-only checkpoint autoload harness. It is guarded from Release behavior and exists for QA/Codex speed only.

Supported checkpoints:

• day1_fresh_start
• day3_storage_pressure
• forest_gather_available
• storage_organized_available
• rest_eli_needed
• fence_completion_ready
• day7_vote_ready_balanced
• week2_start_balanced
• week2_day8_start
• week2_day13_public_doubt
• week2_day14_ledger_ready
• week3_day15_start
• week3_day17_smoke_ready
• week3_day18_jonah_repair_ready
• week3_day19_abel_ready
• week3_day20_hidden_camp_ready
• week3_day21_ledger_ready
• week4_day22_willow_lake_start
• week4_day23_big_catch_ready
• week4_day24_sour_barrel_ready
• week4_day25_quill_warning_ready
• week4_day26_nell_broth_ready
• week4_day27_mae_price_ready
• week4_day28_ledger_ready
• week5_day29_pinebreak_start
• week5_day30_wolf_sign_ready
• week5_day31_mabel_bells_ready
• week5_day32_abel_trail_ready
• week5_day33_wood_allocation_ready
• week5_day34_night_fence_ready
• week5_day35_ledger_ready
• week6_day36_stonecap_start
• week6_day37_fuel_count_ready
• week6_day38_medicine_shortfall_ready
• week6_day39_eli_fatigue_ready
• week6_day40_pass_rescue_ready
• week6_day41_storm_repair_ready
• week6_day42_ledger_ready
• week7_day43_stores_start
• week7_day44_records_ready
• week7_day45_jonah_cornered_ready
• week7_day46_camp_revealed_ready
• week7_day47_public_hearing_ready
• week7_day48_famine_line_ready
• week7_day49_ledger_ready
• week8_day50_charter_notice_start
• week8_day51_last_repair_ready
• week8_day52_food_count_ready
• week8_day53_testimony_ready
• week8_day54_jonah_judgment_ready
• week8_day55_charter_prep_ready
• week8_day56_charter_vote_ready
• campaign_complete_ready

Launch with an argument:

xcrun simctl launch --terminate-running-process booted com.exorobotics.GoldpineValley -GPVDevCheckpoint day3_storage_pressure

Or with an environment variable via simctl:

SIMCTL_CHILD_GPV_DEV_CHECKPOINT=day3_storage_pressure xcrun simctl launch --terminate-running-process booted com.exorobotics.GoldpineValley

GPV_DEV_RESET_SAVE=1 is currently accepted as a DEBUG-only reserved no-op. Save/load and save reset are not implemented yet.

Invalid checkpoint IDs should fall back to normal startup.

When checking UI behavior, use screenshots from the Simulator instead of relying only on code inspection. The app is landscape-first, and several acceptance checks depend on visible overlay flow, disabled buttons, and HUD privacy.

For plugin-driven UI QA, prefer snapshot_ui followed by tap on the latest element refs. Refresh the snapshot after every launch, modal open/close, tap, scroll, or route transition; element refs are only valid for the current screen. Use desktop Computer Use only when MCP element refs are unavailable or when checking the full Simulator window with OS-level screenshots/clicks.

For visual QA, prefer macOS screencapture over app-only simctl screenshots when checking the Simulator frame or landscape composition:

screencapture -x /private/tmp/gpv_check.png

xcrun simctl io booted screenshot can still be useful for app-only capture, but it may show the simulator framebuffer in a way that does not match what the user is inspecting on screen.

iPhone 17 Landscape Preset Clicks

These are absolute macOS screen coordinates from the current iPhone 17 landscape Simulator placement used during 11D-C visual QA. If the Simulator window is moved or scaled, recapture one screenshot and recalibrate before using them.

Use the local Computer Use click helper:

<codex-home>/skills/computer-use/scripts/system_events_click.sh --activate-app Simulator X Y

Setup route:

• Main Menu New Game: 638 636
• Region Select Meadow Valley: 1025 501
• Founder Select Start: 514 759

Homestead POI taps:

• Cabin: 646 366
• Farm Fields: 955 425
• Storage Shed: 1392 405
• Fence Line: 1530 576
• Lookout: 1570 296
• Worker Tent: 590 637
• Town Board: 1000 687
• Market Wagon: 1320 678
• Forest Edge: 1700 505
• Creek Crossing: 265 577

Focused scene control:

• Back to Map: 1694 312

First Week Navigation Tips

The intended complete route is:

Main Menu -> New Game -> Meadow Valley -> Founder -> Day 1 loop -> Day 1 report -> Day 2 Missing Goat -> Day 2 report -> Day 3 Wolf/Mae events -> Day 3 report -> Day 4 Medicine -> Day 4 report -> Day 5 Fence -> Day 5 report -> Day 6 Soup -> Day 6 report -> Day 7 Town Vote -> First Week Complete.

Useful QA paths:

• Generous/responsible: help Minnie, respect Abel's wolf warning, avoid starving the homestead, help or carefully stretch June's medicine, repair/share fence work, feed town or make a reasonable soup compromise. This should land around Narrow Approval or Strong provisional leader.
• Neglectful/self-protective: ignore goat, ignore wolf/Mae pressure, save medicine, refuse fence dispute, refuse soup credit. This should remain Rejected.
• Mixed: combine helpful and selfish choices. This should usually land in Conditional approval.

Fast checkpoint QA:

• day1_fresh_start: verify normal Week 1 HUD, homestead map, POI navigation, bottom bar, and no debug UI.
• day3_storage_pressure: verify Storage Shed focused scene shows Thin Stores / Watchful plus the Storage Shed Work Order state. Before start it should show cost, duration, Eli assignment, and Start Patch Storage Shed; after start wood is spent, storage is not patched immediately, and the repeated action is disabled as Patching Storage Shed. This route is also useful for Fence Line, Fish Creek, Harvest Ready Field, Tend Rows, and Scout Forest Edge smoke checks.
• forest_gather_available: verify Forest Edge opens directly to Gather Wood without a wolf/story action occupying the primary slot.
• storage_organized_available: verify Storage opens directly to Organize Stores because Patch Storage Shed is not the primary action in this checkpoint.
• rest_eli_needed: verify Worker Tent shows Rest Eli as valid through story-facing tired/risk copy without exposing raw fatigue values.
• fence_completion_ready: verify Fence Line shows active paid Repair Fence Line progress near completion and can complete through normal dusk advancement.
• day7_vote_ready_balanced: verify Town Board is Vote Ready, Begin Town Vote opens the vote result, and the result shows Council Confidence / Confidence rather than raw score.
• week2_start_balanced: verify it lands on terminal First Week Complete. Begin Week 2 must still require explicit player action.
• week2_day8_start: verify it opens playable Day 8 at Storage with Pantry Count available, Week 2 HUD privacy intact, and no debug UI.
• week2_day13_public_doubt: verify Day 13 opens at the Town Board with Public Doubt available and no Week 3 route.
• week2_day14_ledger_ready: verify Day 14 opens at the Town Board with Week 2 Ledger available and closes to a terminal Week 2 outcome.
• week3_day15_start: verify Day 15 opens at Creek Crossing with Creek Takes a Board available, no travel map, and no hidden camp.
• week3_day17_smoke_ready: verify Day 17 opens at Creek Crossing with Smoke Past Bend available as setup only.
• week3_day18_jonah_repair_ready: verify Day 18 opens at Creek Crossing with Jonah's Odd Repair available; Jonah is useful/suspicious but not revealed or assignable.
• week3_day19_abel_ready: verify Day 19 opens at Creek Crossing with Abel Reads the Bend available; no Day 20 Hidden Camp is present.
• week3_day20_hidden_camp_ready: verify Day 20 opens at Creek Crossing with Hidden Camp available as story/location state only. Clara, Tate, and Nell are names in event/report text only; no portraits, travel region, or refugee management UI exist.
• week3_day21_ledger_ready: verify Day 21 opens at the Town Board with Week 3 Ledger available and closes to a terminal Week 3 outcome with explicit Begin Week 4. No Week 4 content appears before that player action.
• week4_day22_willow_lake_start: verify Day 22 opens at Willow Lake with Willow Lake Shines available as food relief plus risk. It must remain a focused POI/story surface, not free travel.
• week4_day23_big_catch_ready: verify Day 23 opens at Willow Lake with Big Catch available as storage/preservation/limited Mae pressure. It must remain an event surface, not a shop or travel region.
• week4_day24_sour_barrel_ready: verify Day 24 opens at Storage with Sour Barrel available and public spoilage/sickroom warning only.
• week4_day25_quill_warning_ready: verify Day 25 opens at Worker Tent with Quill's Warning available and care policy choices, without portraits or medical simulation UI.
• week4_day26_nell_broth_ready: verify Day 26 opens at Worker Tent with Broth for Nell available and Clara/Nell mercy pressure through story text only.
• week4_day27_mae_price_ready: verify Day 27 opens at Market Wagon with Mae Changes Price available as limited in-game market pressure, not a shop.
• week4_day28_ledger_ready: verify Day 28 opens at Town Board with Week 4 Ledger available and closes to a terminal Week 4 outcome with explicit Begin Week 5. No Week 5 content appears before that action.
• week5_day29_pinebreak_start: verify Day 29 opens at Pinebreak Woods with Pinebreak Opens available as wood relief plus predator warning. It must remain a focused POI/story surface, not free travel.
• week5_day30_wolf_sign_ready: verify Day 30 opens at Fence Line with Fresh Wolf Sign available and public warning ladder only.
• week5_day31_mabel_bells_ready: verify Day 31 opens at Fence Line with Mabel's Bells available and livestock pressure as story state only.
• week5_day32_abel_trail_ready: verify Day 32 opens at Pinebreak with Abel's Dangerous Trail available; Abel is a story owner/scout label, not a roster worker.
• week5_day33_wood_allocation_ready: verify Day 33 opens at Town Board with Every Log Has Three Owners available and no full economy/inventory system.
• week5_day34_night_fence_ready: verify Day 34 opens at Fence Line with Night Fence Test available and deterministic warning-based consequences.
• week5_day35_ledger_ready: verify Day 35 opens at Town Board with Week 5 Ledger available and closes to a terminal Week 5 outcome with explicit Begin Week 6. No Week 6 content appears before that action.
• week6_day36_stonecap_start: verify Day 36 opens at Stonecap Pass with Stonecap Wind available as cold/fuel/pass warning. It must remain a focused POI/story surface, not free travel.
• week6_day37_fuel_count_ready: verify Day 37 opens at Storage with Fuel Count available and existing Wood/public fuel policy labels only.
• week6_day38_medicine_shortfall_ready: verify Day 38 opens at Worker Tent with Medicine Shortfall available through Dr. Quill, without a patient roster or medical sim.
• week6_day39_eli_fatigue_ready: verify Day 39 opens at Worker Tent with Eli's Hands Shake available as public fatigue warning only.
• week6_day40_pass_rescue_ready: verify Day 40 opens at Stonecap Pass with Pass Rescue Rumor available and no travel map/pathfinding.
• week6_day41_storm_repair_ready: verify Day 41 opens at Worker Tent with Storm Repair Window available and deterministic storm consequences.
• week6_day42_ledger_ready: verify Day 42 opens at Town Board with Week 6 Ledger available and closes to a terminal Week 6 outcome with explicit Begin Week 7.
• week7_day43_stores_start: verify Day 43 opens at Storage with Stores Don't Add Up available and evidence pressure as public state only.
• week7_day44_records_ready: verify Day 44 opens at Town Board with Percy Demands Records available and no legal system or ledger tab.
• week7_day45_jonah_cornered_ready: verify Day 45 opens at Worker Tent with Jonah Cornered available; reveal is partial/contextual, not final judgment, and Jonah remains non-assignable.
• week7_day46_camp_revealed_ready: verify Day 46 opens at Creek Crossing with Camp Revealed available and refugee pressure as story/event state only.
• week7_day47_public_hearing_ready: verify Day 47 opens at Town Board with Public Hearing available and no court/trial UI.
• week7_day48_famine_line_ready: verify Day 48 opens at Market Wagon with Famine Line available and no market/economy simulation.
• week7_day49_ledger_ready: verify Day 49 opens at Town Board with Week 7 Ledger available and closes to a terminal Week 7 outcome with explicit Begin Week 8.

Week 2 Batch A/B verification notes:

• Build verification passed after the Day 8-12 Batch A implementation.
• week2_start_balanced was visually checked at First Week Complete; Begin Week 2 is explicit and reaches Day 8.
• week2_day8_start was visually checked at Storage Shed with the corrected Week 2 scene badge, Pantry Count available, food demand/ledger status rows visible, and no full Work Ledger UI.
• Batch A smoke QA visually clicked Day 8 Pantry Count, Day 9 Ration Policy, Day 10 Mae's Ledger, Day 11 Missing Measure, and Day 12 Creek Errand.
• Batch B adds Day 13 Public Doubt and Day 14 Week 2 Ledger terminal outcome; verify them with week2_day13_public_doubt and week2_day14_ledger_ready.

Required events block End Day until resolved:

• Day 4 Medicine
• Day 5 Fence
• Day 6 Soup
• Day 8 Pantry Count
• Day 9 Ration Policy
• Day 10 Mae's Ledger
• Day 11 Missing Measure
• Day 12 Creek Errand
• Day 13 Public Doubt
• Day 15 Creek Takes a Board
• Day 16 Footprints Facing Both Ways
• Day 17 Smoke Past Bend
• Day 18 Jonah's Odd Repair
• Day 19 Abel Reads the Bend
• Day 20 Hidden Camp
• Day 21 Week 3 Ledger closes immediately to a terminal outcome from the Town Board instead of advancing to a new day.
• Day 22 Willow Lake Shines
• Day 23 Big Catch
• Day 24 Sour Barrel
• Day 25 Quill's Warning
• Day 26 Broth for Nell
• Day 27 Mae Changes Price
• Day 28 Week 4 Ledger closes immediately to a terminal Week 4 outcome from the Town Board. There is no Begin Week 5 action.

Optional events can be ignored and should apply ignore consequences once:

• Day 2 Missing Goat
• Day 3 Wolf warning
• Day 3 Mae market pressure

Completed events should show their resolved state and must not resolve twice.

Farming And Homestead QA Tips

Milestone 8 farming is intentionally small:

• Field A and Field B persist across day advancement.
• Planting costs resources and uses one crop type only.
• Crops grow deterministically over day advancement.
• Ready crops can be harvested for food.
• Farmer should feel better at farming without adding a shop or inventory system.

Milestone 9 homestead state is object condition and repair only, with the later 12A/12B-C Work Order loop layered on top:

• Storage Shed and Fence Line show player-facing environmental labels/risk language and repair actions.
• Storage Shed repair is no longer instant. It starts storageShedPatch, spends wood at start, carries progress through day advancement, and applies storagePatched only when the Work Order completes.
• Fence Line repair is no longer instant. It starts repair_fence_line, spends wood at start, carries progress through day advancement, and applies fencePatched only when the Work Order completes.
• Protector repair discount still applies through Work Order cost calculation for Storage Shed and Fence Line.
• Lookout, Worker Tent, Town Board, Market Wagon, Forest Edge, and Creek Crossing are readable panels, not new management systems.
• Forest Edge wolf behavior is lightweight and event-driven. A Friendly wolf is story/consequence state, not a pet, combat unit, or animal simulation.
• Creek Crossing is display-only foreshadowing. It must not unlock travel or new regions.
• Object condition labels are okay in object panels. The top HUD must remain public-only.
• Storage Shed and Fence Line both use the timed Work Order path.

Week 1 Work Order QA Tips

Protected timed Work Orders now use stable IDs:

• storage_shed_patch
• repair_fence_line
• tend_field_rows
• harvest_ready_field
• fish_creek
• scout_forest_edge
• gather_wood
• organize_stores
• rest_eli

The 12A regression path remains storageShedPatch.

• Available state: the Storage Shed scene should show Work Order Available, worker Eli Calder, cost 4 Wood, duration 90m, and a readable start action.
• Starting state: pressing the action spends wood immediately and deterministically, but does not mark storage as patched.
• Active state: the scene should show Patching, remaining/progress text, and a disabled/repeat-blocked action.
• Carryover state: if End Day advances only part of the 90m duration, the report should say the patch is half-finished and the next day should preserve progress without charging wood again.
• Completed state: completion should happen once, show Patched, show 90/90m, and leave the action disabled as Storage Shed Patched.
• This UI is intentionally narrow. It is not the full Work Ledger, not a clock HUD, and not a worker roster screen.

12B/12C smoke findings:

• Week 1 Management RC is accepted with documented reachability gaps; the DEBUG checkpoint set now covers those gaps without adding gameplay systems.
• Fence Line should show Repair Fence Line, 5 Wood, 120m, and Eli assignment. Starting it should drop Wood by 5, show Repairing, keep Rails as Worn Rails, and block duplicate start.
• Fish Creek should show no cost and complete at dusk with a food report line. It must not open travel or a new region.
• Harvest Ready Field starts from the Field scene Harvest button and completes at dusk with the +Food report line. The food output should not apply on click.
• Tend Rows is visible in the Field scene, but is disabled when there are no growing vegetables to tend.
• Scout Forest Edge is exposed from the Lookout scene and should complete with story-facing report text, not raw hidden values.
• Gather Wood is only exposed when Forest Edge has no active story action. Day 3 and Day 7 checkpoint routes may show wolf/story actions instead, so source inspection may be required there.
• Organize Stores is only exposed after the Storage Shed no longer needs patching. Checkpoints that still show Patch Storage Shed will not expose it.
• Rest Eli uses existing Eli fatigue/injury state only. If checkpoints show Eli as Steady, the action is correctly disabled.
• Use forest_gather_available, storage_organized_available, rest_eli_needed, and fence_completion_ready for focused visual reachability checks.

Next Gameplay Scope

Current implemented gameplay stage:

WEEK8_CHARTER_FINAL_LEDGER_FULL_WEEK_IMPLEMENT_AND_COMMIT is implemented at app baseline commit 33c908f. Week 1 through Week 8 architecture is locked, Day 1-56 is implemented, and WEEK8_QA_AND_ARCHITECTURE_LOCK returned LOCK_WEEK8_ARCHITECTURE. Final baseline commit 3faa9b9 is pushed to origin/main, and the committed-HEAD archive exists at <local-archive-dir>/GoldpineValley-iOS_MVP_campaign_complete_3faa9b9.zip.

Use Goal File 04:

Docs/Planning_Bundles/GoldpineValley_5_Gated_Goal_Files_v3_BackendAligned_Quality/GoldpineValley_GoalFile_04_Weeks3_8_Campaign_v2_quality.md

Concrete Week 3 structure reference:

Docs/Planning_Bundles/GoldpineValley_5_Gated_Goal_Files_v3_BackendAligned_Quality/Story_Bibles/10_Week3_Creek_Crossing_Full_Structure_v1.md

Current scope decision:

• Week 1 Management RC remains accepted and protected.
• Week 2 architecture is locked through Day 14 with a terminal ledger outcome.
• Week 3 architecture is locked through Day 21 with a terminal ledger outcome at committed baseline ebed19c.
• Week 4 implementation is committed at a374133 through Day 28 terminal outcome: explicit Begin Week 4, Day 22-28 Willow Lake/sickness anchors, focused Willow Lake POI state, minimal sickness/spoilage/care-policy state, limited Week 4 Work Orders, Day 28 terminal ledger, and explicit Begin Week 5 only after the terminal Week 4 outcome.
• Week 4 QA patch is committed at 5e4dfe7, adding direct Day 23 Big Catch visual coverage and refreshing stale handoff wording. The architecture recheck returned LOCK_WEEK4_ARCHITECTURE. DEBUG checkpoints now include week4_day22_willow_lake_start, week4_day23_big_catch_ready, week4_day24_sour_barrel_ready, week4_day25_quill_warning_ready, week4_day26_nell_broth_ready, week4_day27_mae_price_ready, and week4_day28_ledger_ready.
• Week 5 architecture is locked through Day 35 and terminal GameSessionPhase.weekFiveComplete(WeekFiveOutcome) at committed baseline 68ce242.
• Week 6 architecture is locked through Day 42 and terminal GameSessionPhase.weekSixComplete(WeekSixOutcome).
• Week 7 architecture is locked through Day 49 and terminal GameSessionPhase.weekSevenComplete(WeekSevenOutcome) after the d254a41 focused-panel routing patch.
• Week 8 implementation covers only Charter Judgment finale scope: Day 50 Charter Notice, Day 51 Last Repair Window, Day 52 Last Food Count, Day 53 Testimony Day, Day 54 Jonah's Judgment, Day 55 Charter Site Prep, and Day 56 Charter Vote.
• Week 8 resolves to terminal GameSessionPhase.campaignComplete(CampaignOutcome) with public ending labels/factors only and Menu/New Game actions only.
• Week 8 architecture is locked after QA: normal startup, invalid checkpoint fallback, Week 1-7 regression checkpoints, Day 50-56 route, campaign_complete_ready, and terminal Menu/New Game-only campaign-complete screen were verified.
• Week 5 DEBUG checkpoints now include week5_day29_pinebreak_start, week5_day30_wolf_sign_ready, week5_day31_mabel_bells_ready, week5_day32_abel_trail_ready, week5_day33_wood_allocation_ready, week5_day34_night_fence_ready, and week5_day35_ledger_ready.
• Week 6 DEBUG checkpoints now include week6_day36_stonecap_start, week6_day37_fuel_count_ready, week6_day38_medicine_shortfall_ready, week6_day39_eli_fatigue_ready, week6_day40_pass_rescue_ready, week6_day41_storm_repair_ready, and week6_day42_ledger_ready.
• Week 7 DEBUG checkpoints now include week7_day43_stores_start, week7_day44_records_ready, week7_day45_jonah_cornered_ready, week7_day46_camp_revealed_ready, week7_day47_public_hearing_ready, week7_day48_famine_line_ready, and week7_day49_ledger_ready.
• Week 8 DEBUG checkpoints now include week8_day50_charter_notice_start, week8_day51_last_repair_ready, week8_day52_food_count_ready, week8_day53_testimony_ready, week8_day54_jonah_judgment_ready, week8_day55_charter_prep_ready, week8_day56_charter_vote_ready, and campaign_complete_ready.
• Jonah receives bounded final Week 8 story judgment but remains non-assignable.
• Post-campaign freeplay, New Game Plus, Week 9+, broad ending-family systems, and post-campaign systems remain deferred/out of scope.
• Defer visible clock HUD and Pause / 1x / 2x controls unless a later prompt explicitly authorizes a dedicated clock/speed stage.
• Keep Week 1 Work Orders on the existing backend timing model: Work Order minutes, End Day/dusk advancement, carryover/resume, and focused-scene/panel progress display.
• Do not add a real-time day clock to the top HUD. The HUD remains Day, Coins, Food, Wood, and Reputation only.
• Avoid a full Work Ledger UI unless a later stage explicitly authorizes a derived presentation surface. Week 2 through Week 8 use only backend/report/focused-scene state plus terminal outcome screens.
• Preserve cost-on-start, output-on-completion, duplicate-completion guards, and hidden-value privacy.
• Remaining dirty Docs/Planning_Bundles files and untracked Docs reference assets are pre-existing planning/reference materials and are not part of the final committed app baseline.
• Current post-lock polish stage is MVP_POSTLOCK_QA_POLISH_IMPLEMENT_AND_COMMIT: copy/readability polish only, with no gameplay, scoring, route, checkpoint, asset, or system changes. After this polish commit, push/snapshot is recommended as a separate authorized stage.

Still forbidden unless separately authorized:

• Post-campaign freeplay, New Game Plus, Week 9+, or post-campaign systems
• broad ending-family systems beyond bounded MVP public labels/factors
• Jonah as assignable worker
• full court/trial or refugee-management simulation
• Creek Crossing, Willow Lake, Pinebreak Woods, or Stonecap Pass as a new free-travel region beyond existing POI/focused-scene surfaces
• clock HUD / Pause / 1x / 2x controls
• random event director
• full market shop or full economy
• full survival/weather/temperature system
• full medical simulation or patient roster
• save/load
• walking animation, SpriteKit, or character movement
• NPC portrait import or Assets.xcassets changes
• full refugee management system
• hidden-value HUD/readouts

NPC Source Reference Notes

NPC source/reference prep is committed through 20f6cbe.

Useful files:

• Docs/Asset_Manifests/NPC_Asset_Manifest_Reference_Lock_v1.md
• Docs/Asset_Manifests/NPC_ART1_Human_Review_Checklist_v1.md
• Docs/Asset_Manifests/NPC_Model_To_Canonical_Cast_Assignment_v1.md
• ArtSource/NPC_Models/README.md
• ArtSource/NPC_Models/Raw/

Rules for future agents:

• ArtSource/NPC_Models/Raw/ contains stable repo-local source/reference JPG sheets only.
• These files are not app assets and are not import-ready portraits.
• Do not import the JPG sheets directly into Assets.xcassets.
• Do not crop/export/rename source images unless a later prompt explicitly authorizes a portrait crop/export stage.
• ART1 requires individual human-approved cropped PNG portrait files before app import.
• Use registry-pure future asset names, not source filenames.
• Tate and Nell remain missing/deferred until source images are provided or explicitly deferred.

Visual QA Tips

Milestone 10B/10C intentionally uses real PNG backgrounds instead of coded SwiftUI scenery for the identity and presentation screens.

• Main menu background: GoldpineValley/Assets.xcassets/Backgrounds/bg_main_menu_hero.imageset/bg_main_menu_hero.png.
• Homestead map background: GoldpineValley/Assets.xcassets/Backgrounds/bg_homestead_map.imageset/bg_homestead_map.png.
• Use GoldpineAssetBackground for background art and keep SwiftUI fallback styling restrained.
• Use GoldpineAsset for background, marker, and portrait asset-name constants instead of scattering new raw image strings.
• Setup, event, worker, report, vote, and completion screens should keep the hero-backed art treatment rather than reverting to flat parchment quiz/report cards.
• Do not replace painted backgrounds with SwiftUI triangle trees, flat mountains, fake fields, or geometric barns.
• The homestead map PNG should fill the playable surface. Avoid placing it inside a green band, framed card, or extra border.
• POI labels should be subtle map pins over the art, not large parchment object cards. Keep labels short and preserve larger invisible tap targets.
• Overview status should light up the POI pill itself: red for danger/work-needed states and green for harvest/task-ready states. Do not add separate floating text pills like Patch, Patch Rails, or Thin Watch.
• POI positions live in HomesteadLocationCatalog.normalizedMapPosition; do not reintroduce separate hard-coded map coordinates.
• MapObject.placeholderObjects should remain generated from HomesteadLocationCatalog, not edited as a competing coordinate source.
• Marker state should remain HomesteadMapMarker values anchored by anchorLocationID; the overview map renders that state through the POI token color.
• Focused POI scenes use a shared Cabin-style ledger card template. Keep the compact location title plaque small enough to avoid the HUD, and keep the ledger/action card above the bottom bar.

Codex Plugin Notes

• The Build iOS Apps plugin is the preferred path for simulator QA. Use build_run_sim, launch_app_sim, snapshot_ui, and tap before falling back to coordinate clicks.
• Runtime snapshot_ui output is enough to verify most Goldpine routes because it exposes visible text, buttons, scroll containers, and tap targets. Still use screenshots when visual composition, overlap, or Simulator-window placement matters.
• Refresh snapshot_ui after every navigation, modal transition, route change, scroll, or terminal screen. Do not reuse stale element refs.
• wait_for_ui can be ambiguous when a label appears in both static text and a button. For this app, direct snapshot inspection plus element-ref taps has been more reliable.
• The desktop Computer Use plugin is mainly a fallback for operating the Simulator window itself, full-window screenshots, or OS-level coordinate clicks. It was not needed for the Week 3 lock once XcodeBuildMCP element refs were available.
• For clean local baselines when the working tree contains dirty planning/reference docs, use git archive from HEAD instead of zipping the working tree.

Contributor Guardrails

• Treat Docs/ as source material. Do not edit docs unless explicitly asked.
• Keep the top HUD limited to Day, Coins, Food, Wood, and Reputation.
• Do not expose trust values, wolf threat, feud intensity, Eli fatigue, vote score before the vote, internal flags, storage condition, fence condition, or medicine stock in the HUD.
• Keep milestone changes narrow. Do not add SpriteKit, save/load, monetization, final art, Week 8+ campaign systems, free-travel regions, or new regions unless explicitly requested.
• Farming and homestead work should stay within the current simple foundations unless the user explicitly expands scope.
• Visual polish should use PNG-backed 2D art assets where possible; do not code faux final background art when a bitmap asset belongs in the catalog.
• Build artifacts under build/ should stay uncommitted.
• GPT_HANDOFF.md is the operational handoff for future agents and should be updated when project status or verification tricks change.