L1: month-turn engine (#612)

[PipFoweraker]

L1 — Month-turn engine (#612)

Implements the ADR-0009 plan-months / two-speeds turn structure plus the workshop #3 spec addendum. The month is the plan cadence; the day-turn is demoted to a resolution tick beneath it (badge = calendar date; days-survived scoring stays fine-grained). Built as a layer over the existing day-tick engine rather than a re-grain — the sim substrate, RNG stream, and recorded replays are untouched, so this stays green and non-degrading.

What landed (per SCOPE item)

1. Month = plan turn, day = resolution tick. Clock gains month helpers (month_index / is_month_boundary / month_ordinal / month_label). The HUD badge retires Week 12 | … | Day 3/5 (which hung attention on the day tick, violating the guard rule) for the plan-month date badge. Also fixes the latent leap-day infinite loop (Build lane L0 · Pre-L1 stabilization: one GameManager, one clock, split turn monoliths (behavior-preserving) #620 note 2) that would have hung on Feb-29 dates across the 2017–2040 window. Guard rule honoured: no routine decision hangs on the day tick.
2. Plan phase — Attention economy. New MonthPlan: founder currency Attention (~20/month, Balance.attention.per_month, not hardcoded); explicit reserve that evaporates crisply at month end (no banking); queued strategic actions with durations (nothing strategic resolves instantly). Attention is introduced alongside the legacy AP pool (L2 owns deleting AP + migrating cost dicts — seam left clean, no big-bang). Staff actions remain per-person/separate.
3. Event delivery tiers. EventTiers classifies every genre ambient / feed / window with source_id provenance on feed items; only windows demand a decision. WindowResolver implements the costed menu HANDLE-from-reserve / HANDLE-by-cannibalizing / DEFER (mints a Ledger entry, deferrable class only) / IGNORE (list price); unignorable flag supported; unanswered windows auto-resolve as IGNORE + a mild, data-driven rep penalty. Window demand budget 2–3/month → 5–6 endgame (Balance-driven) enforced in the controller.
4. Day-tick playback + auto-pause-on-window. MonthController advances ticks through TurnManager, routes events by tier, pauses on windows, resets the plan phase at month boundaries, and releases duration-elapsed WIP.
5. Save/load survives all of it. MonthPlan serialized into GameState.to_dict/from_dict; a pause→save→load smoke test proves an open window + reserve + WIP round-trip and playback resumes.
6. Replay artifact. record_window_response bumps the schema with payment_source; the league (month) id is stamped beside (seed, game_version). Format tag held at v1 (additive; unknown log keys are ignored by the v1 simulator, so pre-L1 artifacts stay verifiable).

Out of scope (left clean): ADR-0015 doom-function migration is Lane 2 — this resolver/schema never reads/writes doom directly (routes through option effects + ledger factories only). The full new plan scene UI (explicit reserve dial, four-verb window menu incl. DEFER) remains attrition work — but the month loop is now reachable from the playable scene (see below).

Playable month path (playtest follow-up)

Pip's first playtest hit the gap: the engine existed but End Turn still called end_turn() (single day-step) — zero L1 behavior reachable. Fixed (e4cd408):

• End Turn / Commit Plan now call GameManager.end_month(): commit queued actions as the month plan → implicit reserve = all unspent Attention (v1 default; the plan screen makes it a dial) → execute the open plan turn → day-tick playback (visible date advance, day_tick_seconds pacing).
• Auto-pause-on-window: windows present through the existing event_dialog (the L10 extraction built for exactly this), AP pre-stripped so displayed costs match what resolution charges. Choices route through MonthController.resolve_current_window_option: the event's ignore option → IGNORE; any other option → HANDLE paid reserve-first, then by cannibalizing — payment_source still lands in the replay artifact. (The explicit four-verb menu incl. DEFER is the plan screen's job.)
• Month boundary → review dialog → next plan phase. The boundary tick is held open as the new plan phase (month_open_pending) — never auto-executed, or its consequence steps would double-run when the plan commits. A plain month-review dialog closes into planning. Loop: plan → play → review → plan.
• Old day-step is DEV-ONLY: it survives solely as the DEV MODE overlay's "Day step (dev — old path)" button; end_turn() semantics unchanged (tests pin it). Guard rule holds: only windows pause the day ticks.
• Feed items surface as log lines with source_id; ambient stays silent.

Honest build badge (playtest follow-up)

The baked build_stamp.txt (fd60eb6 · 2026-07-11) was stale on every branch and cost the playtest session (a4e7661). Dev checkouts now read live git HEAD at runtime (git -C <repo-root> rev-parse, gated on .git existing so exported builds never shell out; cached; worktree-safe): badge reads DEV BUILD v0.11.0 · l1-month-turn-engine@a4e7661 · live. Exported/no-git builds fall back to the baked stamp explicitly marked (stamp) — no badge form can pass as something it isn't, so two checkouts can never show the same badge silently. A stale stamp prints a console note.

Window-drop fix (balance-sweep finding)

4269c0b: MonthController.resolve_current_window() (the four-verb path) popped the window off the queue before WindowResolver.resolve validated payment and never re-pushed on failure — handle_reserve with an empty reserve silently dropped the window (no effect, no charge, no window). Latent in the shipped v1 dialog (which routes through the correctly-guarded option path) but fatal to the future plan-screen UI. Fixed by mirroring the option path's guard — peek, resolve, pop only on success; skip_current_window hardened with the same shape. Regression test: failed handle_reserve leaves the window queued (and in the serialized pause point), then resolves via handle_cannibalize.

Local GUT results

CI's test gate is hollow (#629) — these are real local runs (Godot 4.5.1, after a headless --import pass):

• Full tests/unit/ run: 403/403 passing, 0 failures, 39 GUT scripts (the 40th unit file, test_verification_determinism.gd, extends Node — a pre-existing non-GUT script — so no Test suite: 14 order-dependent failures in full local run (singleton leakage), invisible to CI #590 hidden parse-failures).
• New L1 suites (49 tests): all green. test_clock_month (leap-day + month helpers), test_month_plan (Attention/reserve/durations/serialization), test_event_tiers, test_window_resolver, test_month_controller (demand budget, auto-pause, boundary hold-open, option→verb mapping, headless playable-loop smoke), test_month_save_load (pause→save→load), test_month_button_path (a headless smoke driving a FULL month through the exact End-Turn-button API: plan commit → ticks → auto-pause → review → next plan phase).
• Touched regression suites green: test_game_manager 35/35 (end_turn semantics pinned + unchanged), test_replay_verification, test_save_load_roundtrip, test_game_state, test_events, test_engine_determinism, test_salary_cadence, test_liability_ledger, test_dev_build_indicator (+2 badge-honesty tests).

Schema decisions to eyeball

• Attention alongside AP, not replacing it — L1 introduces the new currency; L2 deletes the pool. Keeps blast radius sane.
• Event schema additions: delivery_tier, event_class, source_id, unignorable, expiry_turns, and a window{ attention_cost, handle_option, ignore_option, defer{factory,amount} } block. Un-annotated legacy popups default to window (behaviour-preserving).
• Window options strip legacy action_points costs — Attention is the window decision currency.
• League id placeholder = YYYY-MM of the run start month, pending the ADR-0016 pipeline.
• months_per_turn() stays 1.0 (turn = workday) — the month is a layer, not a re-grain; this keeps risk/doom calibration and replays intact. Noted in-code for L2.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.