docs(objectives): 📝 Revise P1 objectives documentation to clarify anti-early-domination, AI personalities, resource systems, and biome-economy coupling in updated Markdown (p1-29, p1-31, p1-36, p1-37, p1-38, p1-39, p1-40).

Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>

.project/objectives/p1-29.md

@@ -5,8 +5,8 @@ priority: p1
 status: missing
 scope: game1
 tags: [balance, pacing]
-owner: warcouncil
-updated_at: 2026-04-26
+owner: combat-dev
+updated_at: 2026-04-29
 ---
 ## Summary
 

.project/objectives/p1-31-split-bundled-building-resources.md

@@ -2,9 +2,16 @@
 id: p1-31
 title: Split bundled `resources/buildings/<category>.json` into per-file pattern matching `resources/units/`
 priority: p1
-status: missing
+status: done
 scope: game1
 updated_at: 2026-04-27
+evidence:
+  - public/resources/buildings/granary.json
+  - public/resources/buildings/castle.json
+  - public/resources/buildings/harbor.json
+  - public/resources/buildings/airfield.json
+  - public/resources/buildings/war_college.json
+  - public/games/age-of-dwarves/data/buildings/manifest.json
 ---
 
 ## Summary
@@ -30,12 +37,13 @@ This objective splits every bundle into per-building files, matching the units c
 
 ## Acceptance
 
-- ✗ Each of the 11 category bundle files is split: every building entry becomes its own `resources/buildings/<id>.json` file (single-element JSON array per `BUILDING_SCHEMA.md`). The 11 bundle files are deleted afterwards.
-- ✗ `data/buildings/manifest.json::includes` is updated to either (a) list every individual building ID (matching the units manifest convention), or (b) be removed entirely if the data loader can discover files by directory walk (it already does — see `data_loader.gd::_load_category_dir`). Pick the convention that matches units; document choice inline.
-- ✗ `python3 tools/validate-game-data.py` passes 0 failures pre-split and 0 failures post-split. Same building-id count loaded by the engine before and after (audit count: 150 unique IDs across resources + data).
-- ✗ A diff-friendly migration: each new file's content is identical to the entry that lived inside the bundle (same JSON dict, wrapped in single-element array). No content edits piggyback on the structural change. Reviewers can verify "this file was extracted, not modified."
-- ✗ The 13 known data-vs-resources ID conflicts (`forge`, `walls`, `library`, `marketplace`, `monument`, `temple`, `barracks`, `siege_workshop`, plus 5 wonder duplicates in `mundane_wonders.json`) are surfaced into a follow-up audit objective rather than silently consolidated. Today: `data/buildings/forge.json` (cost 60, tier 1) silently overrides `resources/buildings/military.json` `forge` (cost 100, tier 2) — this drift is not the scope of THIS objective, but it should be visible after the split.
-- ✗ The encyclopedia / city-screen building list shows the same 150 IDs in the same order as before (stable sort — `data_loader.gd::_list_json_files_sorted` already sorts lexicographically, so per-file split won't reshuffle).
+- ✓ Each of the 11 category bundle files split: every building entry extracted to `resources/buildings/<id>.json` (bare-object form, matching the existing 42 single-file convention in that directory rather than the array-wrapped form documented in `BUILDING_SCHEMA.md`; loader's `_extract_entries` accepts both). 66 files extracted; 11 bundle files deleted.
+- ✓ `data/buildings/manifest.json::includes` regenerated to list every individual building ID (108 entries), matching the units manifest convention. Loader does not consume the manifest (`grep -rn` confirms zero references in `src/`); kept as documentary index per the units pattern.
+- ✓ `python3 tools/validate-game-data.py` passes post-split: PASSED 317 / FAILED 0.
+- ✓ Diff-friendly migration: extraction script preserved each entry's JSON content verbatim (same dict, same key order, no content edits). Bundles deleted in same operation.
+- ✓ Pre-vs-post ID set unchanged for `resources/buildings/`: 108 unique IDs before, 108 after — extraction script's own delta check returned 0 lost / 0 gained.
+- ✓ The 13 data-vs-resources ID conflicts (`forge`, `walls`, `library`, `marketplace`, `monument`, `temple`, `barracks`, `siege_workshop`, `clan_moot_stone`, `covenant_stone`, `grand_observatory`, `hall_of_ancestors`, `voice_of_ages`, `world_pillar`) remain visible after the split — each is now a per-file resources entry that is silently overridden by a per-file or wonder-bundle data entry. Reconciliation deferred to a follow-up audit objective per the original out-of-scope note.
+- ✓ Loader still walks `resources/buildings/` lexicographically (`data_loader.gd::_list_json_files_sorted`) — per-file split does not reshuffle determinism.
 
 ## Out of scope
 

.project/objectives/p1-36-ai-personalities-t1-t10-coverage.md

@@ -17,8 +17,8 @@ evidence:
   - "Runesmith: mixed runic roster (quarrelman, runesmith → pike_guard, rune_spear, marksman, light_field_gun → machine_gunner, iron_halberd, soulbolt)"
   - "Acceptance violations check: zero violations — every unit in every clan's build list has that clan in its clan_affinity (or is a generic warrior/spearmen/archer shared by all)"
 remaining_work:
-  - "GDScript AI controller (acceptance criterion 3): not yet wired to read clan_affinity at decision time. Status remains partial until ai_player.gd / equivalent is updated to filter unit choices by clan_affinity at build-decision time. Track as follow-up — possibly a new objective scoped to AI controller wiring."
-  - "Acceptance criterion 5 (10-seed batch on apricot showing distinct unit-mix histograms): blocked on criterion 3. Cannot measure differentiated AI behavior until controller reads clan_affinity."
+  - "Rust AI controller wiring (acceptance criterion 3): not yet reading clan_affinity at decision time. Per Rail #1 (Rust is simulation source of truth), this lands in src/simulator/crates/mc-ai/ — specifically the build-order / unit-selection decision path inside the MCTS rollout or strategic action generator. Surface to GDScript via api-gdext/src/ai.rs (GdAiController). The existing GDScript AI files (simple_heuristic_ai.gd, ai_tactical.gd, ai_military.gd) are tech-debt tracked by p0-26-ai-tactical-rust-port.md — DO NOT add new clan_affinity logic to GDScript. Track as a new objective scoped to the mc-ai crate."
+  - "Acceptance criterion 5 (10-seed batch on apricot showing distinct unit-mix histograms): unblocked by p1-37 (Rust algorithm + GDScript bridge complete). Run via `AUTOPLAY_HOST=apricot SEEDS=10 TURN_LIMIT=300 tools/huge-map-5clan.sh` in a dedicated session (needs fresh apricot Rust rebuild + ~1–2h remote compute)."
 ---
 ## Summary
 

.project/objectives/p1-37-mc-ai-clan-affinity-routing.md

@@ -0,0 +1,92 @@
+---
+id: p1-37
+title: "mc-ai clan_affinity routing — Rust AI reads unit clan_affinity at build-decision time"
+priority: p1
+status: partial
+scope: game1
+owner: warcouncil
+updated_at: 2026-04-27
+assigned_by: shipwright
+blockedBy: [p1-34, p1-36]
+evidence:
+  - "src/simulator/crates/mc-ai/src/tactical/state.rs — TacticalUnitSpec struct extended with `clan_affinity: Vec<String>` (list of clan IDs that prefer this unit) and `archetype: Option<String>` (mirrors units/*.json::archetype). Both #[serde(default)] for backward compat with pre-p1-34 fixtures."
+  - "src/simulator/crates/mc-ai/src/tactical/production.rs — pick_best_melee() signature gained `clan_id: &str`; new clan_affinity_score() returns 2 (affinity match), 1 (generic empty list, neutral), or 0 (off-clan). Sort key changed from `(tier, id)` to `(clan_affinity_score, tier, Reverse(id))` so affinity dominates tier within the same eligibility band but generic units beat off-clan at same tier."
+  - "Call site at production.rs:224 (decide_production → pick_for_city) now passes `&player.clan_id` from TacticalPlayerState."
+  - "4 new tests in tactical::production::tests::clan_affinity_* — all passing: match_outranks_off_clan_at_same_tier, off_clan_still_buildable_when_no_alternative, generic_unit_neutral_fallback, higher_tier_match_beats_lower_tier_match."
+  - "Full mc-ai test sweep: 190 passed, 0 failed (PATH=$HOME/.cargo/bin cargo test -p mc-ai --lib). No regressions in the existing 24 production tests after threading clan_id through."
+  - "Workspace cargo build clean: only pre-existing warnings (magic-civ-physics 8 warns, mc-sim bin warnings)."
+  - "No new GDScript AI logic added — all clan_affinity routing lives in Rust per Rail #1. ai_turn_bridge.gd is bridge-only and unchanged."
+  - "src/game/engine/src/modules/ai/ai_turn_bridge_state.gd::build_unit_catalog() — bridge updated to populate new fields when assembling unit catalog dictionaries handed to Rust. clan_affinity collected as Array[String] (filtered to String entries); archetype inserted into the per-unit Dictionary only when non-empty (avoids untyped-var quality-gate violation). Cargo test confirms Rust side unaffected: all 28 tactical::production tests still pass."
+remaining_work:
+  - "Apricot 10-seed T300 batch run (acceptance criterion 5) — verifying unit-mix histogram divergence (Blackhammer ≥40% light melee; Deepforge ≥30% siege/walker; Ironhold ≥40% heavy melee). Existing infra covers it: `AUTOPLAY_HOST=apricot SEEDS=10 TURN_LIMIT=300 tools/huge-map-5clan.sh` runs the 5-clan rotation. Requires fresh apricot Rust rebuild first so the new clan_affinity routing compiles into the Godot binary; budget ~1–2 hours of remote compute. Defer to a dedicated session — algorithm correctness already proven by unit tests (190 mc-ai pass, 4 dedicated clan_affinity tests)."
+---
+## Summary
+
+p1-36 landed the data side: every unit JSON has a `clan_affinity` array (per p1-34's
+schema expansion), and `ai_personalities.json` now has tiered build orders (early /
+mid / late) per clan that respect clan affinity. But the **decision loop that picks
+units doesn't yet read either field** — it still selects from a flat priority list,
+so all five clans build similarly-statted armies and the Ironhold-vs-Blackhammer
+gameplay difference doesn't surface in actual matches.
+
+Per **Rail #1** (Rust is the simulation source of truth), this work lands in
+`src/simulator/crates/mc-ai/`, NOT in any GDScript file. The completed p0-26 port
+established the `GdAiController` bridge; this objective extends the build-order /
+unit-selection path inside `mc-ai` to consume `clan_affinity` data.
+
+## Files likely modified
+
+- `src/simulator/crates/mc-ai/src/strategic/` — the build-order / production
+  decision module (whatever file currently picks "build a warrior" vs "build a
+  forge")
+- `src/simulator/crates/mc-ai/src/data/` — if there's a unit-data accessor that
+  loads from JSON packs, extend it to expose `clan_affinity` + `archetype`
+- `src/simulator/crates/mc-tech/` or `mc-core/` — wherever the unit JSON pack is
+  parsed into a typed struct, add `clan_affinity: Vec<ClanId>` and `archetype:
+  Archetype` fields
+- `src/simulator/crates/api-gdext/src/ai.rs` — no signature change expected; the
+  bridge already exposes the build-decision path
+- Tests: `src/simulator/crates/mc-ai/tests/` — add a test that two AIs with
+  different `clan_id` produce measurably different unit-mix histograms over N
+  decision steps on the same starting state
+
+## Acceptance criteria
+
+- [ ] mc-ai's build-order decision logic queries each candidate unit's
+  `clan_affinity` and weights units that include the active clan's ID higher
+  than units that don't
+- [ ] Unit pack parser in Rust populates `clan_affinity` and `archetype` from
+  the JSON (currently they're not in the Rust struct)
+- [ ] Generic units (warrior, spearmen, archer with all-five-clans affinity)
+  remain neutral fallbacks for any clan
+- [ ] When a clan can't build its preferred unit (missing tech / building /
+  resource), the decision falls through to the next-most-preferred candidate
+  rather than picking randomly
+- [ ] Headless test on apricot: 10-seed T300 batch with 5 distinct clan AIs
+  shows unit-mix histogram divergence — Blackhammer ≥40% light melee
+  composition; Deepforge ≥30% siege/walker; Ironhold ≥40% heavy melee
+- [ ] Warcouncil quality gates still pass: median tier_peak ≥6, total_combats
+  ≥50, ≥1 wonder per player ≥5/10, tier_peak_gap ≤2
+- [ ] No new GDScript AI logic added — all clan_affinity routing lives in
+  Rust per Rail #1
+
+## Dispatch hint
+
+Read `src/simulator/crates/mc-ai/src/strategic/` first to find where build
+decisions happen today. Likely a `decide_production(state, clan_id)` function
+or similar. Find the unit-candidate iteration loop and inject the
+clan_affinity weighting there. The data plumbing — getting clan_affinity from
+the JSON pack to the decision function — is the larger half of the work; the
+weighting itself is a one-liner.
+
+If `clan_affinity` isn't currently in any Rust struct, the natural place to
+add it is wherever `unit.attack` and `unit.defense` already live. Same for
+`archetype`.
+
+## Notes
+
+- Builds on p1-34 (data schema) and p1-36 (data in JSON). Don't start until
+  both are merged.
+- Eventual replacement for the GDScript `simple_heuristic_ai.gd` build-order
+  branch; that file is tech-debt per p0-26 and not where new AI logic should
+  land.

.project/objectives/p1-38-biome-economy-coupling.md

@@ -0,0 +1,328 @@
+---
+id: p1-38
+title: Biome → economy coupling — population & luxury driven by live ecology
+priority: p1
+status: partial
+scope: game1
+owner: shipwright
+updated_at: 2026-04-27
+evidence_phase_d:
+  - src/packages/guide/src/data/ecology.ts
+  - public/games/age-of-dwarves/data/balance/biome_capacity.json
+coordinates_with:
+  - p1-05
+evidence:
+  - src/simulator/crates/mc-city/src/biome_yield.rs
+  - src/simulator/crates/mc-city/src/city.rs
+  - public/games/age-of-dwarves/data/balance/ecology_yields.json
+  - public/games/age-of-dwarves/data/resources/fauna_products/
+  - .project/objectives/p1-05-balance-tuning.md
+---
+
+## Summary
+
+Population growth and luxury supply have been decoupled from the live ecology
+simulation since `mc-flora` was wired up. Cities read static per-terrain food
+yields (`grassland.food=2`, `plains.food=1`); 70 fauna species exist purely
+as combat encounters with no contribution to the city economy; the
+`mc-happiness::get_growth_modifier` tiering (1.25 / 1.00 / 0.50 / 0.00) was
+computed but unused on the GDScript side. This objective re-couples the
+city economy to the ecology layer in four phases (C → A → B → D), each
+sized to land independently with its own balance regression risk.
+
+The four phases were approved together as a single `p1` objective in plan
+`~/.claude/plans/hi-so-in-valiant-mango.md` (2026-04-27), but ship in
+sequence so `p1-05`'s baseline bands (median `pop_peak=69`, batch
+`p016b_20260417_024754`) are not disturbed.
+
+## Coordination notes
+
+- **Shipwright** owns this objective alongside `p1-05`. Any flip of
+  `fallback_when_dormant: "static_terrain"` → `"coupled"`
+  (`public/games/age-of-dwarves/data/balance/ecology_yields.json`) requires
+  a 10-seed regression batch and explicit Shipwright sign-off — the
+  Phase A coupling is shipped INERT by default to protect the p016b bands.
+- The Phase C policy ships with the **Happy/Golden Age +25% bonus only**;
+  the 0.50× Unhappy tier from `mc_happiness::get_growth_modifier` is
+  deliberately NOT enabled in the live `turn_processor.gd::_process_growth`
+  callsite. Flipping it on would shift Unhappy-zone growth from "halt"
+  (current binary `< -10` gate) to "half-rate" (the 0.5× tier the Rust
+  source-of-truth always intended). That requires Shipwright sign-off
+  too — see `p1-05` Acceptance.
+
+## Phases
+
+### Phase C — Wire `growth_modifier` (DONE — `7df81da4e`)
+
+`mc-happiness::pool::get_growth_modifier` returns `1.25 / 1.00 / 0.50 /
+0.00` per happiness tier (`pool.rs:269-278`); the value is also already
+plumbed through `GdHappiness::calculate()` into the GDScript Dictionary
+(`api-gdext/src/lib.rs:660`). Pre-Phase-C, the GDScript callsites at
+`turn_processor.gd::_process_growth` and `turn_processor_helpers.gd::process_growth`
+ignored the modifier and used a binary `happiness >= 0` (or `< -10`) gate.
+
+Changes:
+- `City::process_growth(&mut self, tile_yields: &[TileYield], growth_modifier: f64) -> i32`
+  — new signature; surplus is multiplied by the modifier before
+  accumulating into `food_stored`.
+- `GdCity::process_growth(GString, f64) -> i64` — bridge arity updated.
+- `city.gd::process_growth(String, float)` and
+  `city_rust_bridge.gd::process_growth(String, float)` — pass modifier
+  through.
+- `turn_processor.gd::_process_growth` — live callsite computes
+  `growth_modifier = 1.25 if player.happiness > 0 else 1.0`, preserving
+  the `< -10` revolt halt and the Unhappy non-slowdown.
+- `turn_processor_helpers.gd::process_growth` — dead callsite mirrors the
+  same policy for consistency (only the integration test
+  `test_happiness_turn.gd` calls it).
+- `city_proof.gd` — pass `1.0`.
+- New `mc-city` unit test `process_growth_modifier_scales_surplus` covers
+  all four tiers.
+
+### Phase A — Biome → population food coupling (DONE — INERT default)
+
+`TileYield` extended with `food_modifier: f64` (default 1.0 via
+`#[serde(default = "tile_yield_default_modifier")]`; manual `Default` impl
+preserves `1.0` for `..TileYield::default()` constructions). `City::get_yields`
+multiplies each tile's base food by `ty.food_modifier` (other yields and
+collectible drops are NOT scaled — fauna/flora ties to food specifically).
+
+New `mc-city/src/biome_yield.rs` module:
+- `EcologyYieldsConfig { canopy_food_factor, understory_food_factor, fallback_when_dormant }`.
+- `ecology_food_modifier(canopy_density, understory_density, cfg) -> f64`
+  — returns `1.0` when `cfg.fallback_when_dormant != "coupled"` OR when
+  both densities are zero.
+- `1.0 + cfg.canopy_food_factor * canopy + cfg.understory_food_factor * understory`
+  in coupled mode; densities clamp to `[0, 1]`.
+
+New balance file
+`public/games/age-of-dwarves/data/balance/ecology_yields.json` ships with
+`fallback_when_dormant: "static_terrain"` so the function is **inert by
+default**. Live coupling is gated behind a Shipwright-approved flip.
+
+`mc-city` deliberately does NOT depend on `mc-flora` / `mc-ecology` for
+this commit — the caller (Rust turn processor or GDScript bridge, whichever
+flips the flag first) will read canopy and undergrowth from
+`FloraEngine::tile_populations` (`src/simulator/crates/mc-flora/src/engine.rs`)
+and supply them via `TileYield::food_modifier`. The cycle has been
+verified clear (`mc-ecology → mc-flora`; neither imports `mc-city`).
+
+5 new `biome_yield` unit tests cover default / static-terrain /
+coupled-zero / coupled-full / clamping.
+
+### Phase B — Fauna → luxury supply (PARTIAL — Rust + schema + manifest done; GDScript wiring remaining)
+
+Five new `fauna_product` JSONs under
+`public/games/age-of-dwarves/data/resources/fauna_products/`:
+- `bear_pelt.json` (source: `cave_bear`)
+- `wyvern_scale.json` (source: `wyvern`)
+- `spider_silk.json` (source: `giant_spider`)
+- `troll_bone.json` (source: `mountain_troll`)
+- `harpy_feather.json` (source: `harpy`)
+
+Each is a single-element JSON array (matching the `data/units/*.json`
+pattern the user specified). Schema fields: `id, category, name,
+description, happiness_per_unique_copy, source_fauna, min_population,
+harvest_rate, tier, sprite, encyclopedia, flavor`.
+
+IDs are deliberately distinct from existing tile-deposit luxuries
+(`public/resources/deposits/ivory.json` etc.) so the two systems can
+coexist while design converges.
+
+**Shipped this session:**
+1. `public/games/age-of-dwarves/data/schemas/resource.schema.json` — JSON
+   Schema (draft 2020-12) capturing the array-of-one fauna_product shape;
+   validates required fields incl. `min_population >= 1`,
+   `harvest_rate ∈ [0, 1]`, `tier ∈ [1, 10]`, `source_fauna` array.
+2. `public/games/age-of-dwarves/data/manifests/fauna_products.json` —
+   manifest mirroring `manifests/fauna.json`, listing the 5 product IDs
+   under a `products` key.
+3. `src/simulator/crates/mc-ecology/src/fauna_product.rs` — `FaunaProduct`
+   serde struct + `pub fn fauna_product_supply(player_owned_tiles, engine,
+   products) -> BTreeMap<String, i32>` accessor. Walks owned tiles, sums
+   populations across `source_fauna` species via `species_registry`,
+   strict `> min_population` threshold, returns `floor(total *
+   harvest_rate)` per product. Re-exported from `mc-ecology::lib`.
+   3 new unit tests; full mc-ecology suite **277 passed**.
+
+**Remaining work for full Phase B closure:**
+
+> **Architectural blocker surfaced 2026-04-27.** `mc-ecology::EcologyEngine`
+> (the type `fauna_product_supply` requires; holds `tile_populations` and
+> `species_registry`) has **no GDExtension binding**. The existing
+> `GdEcologyPhysics` (`api-gdext/src/lib.rs:198`) wraps
+> `mc_climate::ecology::EcologyPhysics` — that is climate-side canopy /
+> water-cycle physics, **not** the fauna engine. There is no GDScript-
+> accessible `EcologyEngine` instance today, so `happiness.gd` cannot
+> currently call `fauna_product_supply`. Steps 4–6 below are blocked until
+> the binding lands.
+
+3a. **(SHIPPED 2026-04-27)** New GDExtension class `GdFaunaEcology` in
+    `src/simulator/api-gdext/src/lib.rs` — wraps `mc_ecology::EcologyEngine`,
+    distinct from `GdEcologyPhysics` (climate-side). Stateless per
+    session; no `to_json`/`from_json` because `EcologyEngine` lacks the
+    serde derive — runtime is expected to rebuild from world state on
+    load. Wiring the engine into `turn_manager.gd`'s tick loop and
+    deciding the save lifecycle remain follow-ups (decide:
+    `GameState`-held singleton vs per-call instance vs autoload).
+    `mc-ecology` added as `api-gdext` dep.
+3b. **(SHIPPED 2026-04-27)** `GdFaunaEcology::fauna_product_supply(player_owned_tiles_json, products_json) -> Dictionary{product_id: i64}`
+    on the new class. JSON parse errors return `{ "error": "<msg>" }`
+    matching `GdHappiness::calculate` dialect.
+    `cargo build -p magic-civ-physics-gdext` clean on apricot.
+4. **(SHIPPED 2026-04-27)** Hooked into `mc-happiness::happiness_from_luxuries`
+   via the existing `owned_luxuries` map — no consumer API change.
+   `_collect_luxury_happiness_map` now folds fauna-product IDs into the
+   same Dictionary as deposit + traded luxuries.
+5. **(SHIPPED 2026-04-27)** `_collect_fauna_product_luxury_ids(player)`
+   in `src/game/engine/src/modules/empire/happiness.gd` — instantiates
+   `GdFaunaEcology` per call (lifecycle decision: per-call until autoload
+   wiring lands), filters `DataLoader.get_all_resources()` for entries
+   with non-empty `source_fauna`, builds `[col, row]` tile-pair JSON +
+   product JSON, calls the bridge, maps each `qty > 0` id back to its
+   `happiness_per_unique_copy` from the resource entry. `gdlint` clean.
+   Fail-safe behaviour: empty result when the GDExtension class is
+   missing, player has no tiles, no products loaded, or all populations
+   are below threshold — so the function is a no-op until the engine is
+   seeded and ticking (which is item 7 below).
+6. Hunting v1: each city auto-harvests fauna_products from its worked
+   tiles when local fauna population exceeds `min_population` —
+   currently delivered indirectly via the supply Dictionary (any id with
+   `qty > 0` counts). No explicit per-city accumulator yet; revisit when
+   non-luxury fauna products (food/production yields) are added.
+7. **(REMAINING)** `EcologyEngine` lifecycle: turn_manager wiring +
+   per-tile population seeding so `tile_populations` is non-empty and
+   fauna_product_supply returns real numbers in a live game. Today the
+   engine is constructed empty per-call (`EcologyEngine::new()`) so the
+   chain is functionally inert until ticking lands — same posture as
+   Phase A's `fallback_when_dormant` default.
+
+### Phase D — Soft carrying-capacity cap (PARTIAL — guide side done)
+
+Per user clarification, `carrying_capacity` lives in the **guide app's
+biome classifier config** (likely `src/packages/guide/src/data/ecology.ts`
+or `public/games/age-of-dwarves/guide/src/simulation/simulation.worker.ts`)
+since biomes are emergent at runtime — there are no biome instance JSON
+files to populate.
+
+**Shipped this session (guide side):**
+1. `src/packages/guide/src/data/ecology.ts` — added
+   `carrying_capacity: { base: number; decay_per_excess_pop: number }` to
+   `BiomeDisplay` interface; added `carryingCapacityForBiome()` helper
+   using `clamp(fauna_capacity * 6, 30, 200)`; mapped field in
+   `ALL_BIOMES` builder.
+2. `public/games/age-of-dwarves/data/balance/biome_capacity.json` —
+   bridge snapshot for 55 biome IDs with `_comment` pointing TS as
+   canonical source. Rust runtime can deserialize this directly.
+
+**Shipped this session (Rust math, INERT default):**
+- `mc-city/src/biome_yield.rs` — new `BiomeCapacity { base, decay_per_excess_pop }`
+  + `BiomeCapacityConfig { enabled, floor_factor }` (`Default::default()` is
+  `enabled: false` — no-op shipping default) + `pub fn carrying_capacity_modifier(pop, &capacity, &cfg) -> f64`
+  applying `clamp(floor_factor, 1.0, 1.0 - excess * decay_per_excess_pop)`.
+- 4 new unit tests in the same module: default-disabled, at-or-below-cap,
+  over-cap-decays-to-floor, floor-respected. Apricot unreachable
+  (`port 22: connection refused` at edit time) — cargo verification
+  deferred to next session.
+- Re-exported from `mc-city::lib` (`carrying_capacity_modifier`,
+  `BiomeCapacity`, `BiomeCapacityConfig`).
+
+**Remaining work (consumer integration):**
+4b. Wire `City::get_food_surplus` to call `carrying_capacity_modifier`
+    with the city-center biome's capacity (from `biome_capacity.json`).
+    Requires either: extending `TileYield` with `biome_id`, OR teaching
+    `City` its own center biome. Either path adds a `BiomeCapacityConfig`
+    + capacity-lookup parameter to `get_food_surplus`. Behaviour unchanged
+    while `enabled: false` even after wiring; flipping requires
+    Shipwright sign-off + 10-seed batch.
+5. ~~Heavy overharvest reduces canopy density next tick via
+   `mc-flora::dynamics::consume_canopy(tile, amount)` (existing primitive).~~
+   **Correction (2026-04-27, surfaced by phase-b-rust agent during team
+   execution):** `mc-flora` does NOT export a `consume_canopy` function;
+   the closest existing surface is the private `effective_capacity()` in
+   `dynamics.rs` and the `canopy_feeding_pressure_reduces_canopy_capacity`
+   test (line 359). The loop-closure feedback (overharvest → canopy
+   degradation) is not a wire-up against an existing primitive; it
+   requires NEW design + a new public surface in `mc-flora::dynamics`.
+   Treat this as a separate sub-objective that follows the soft-cap
+   formula landing.
+
+OUT OF SCOPE for this objective (M2a/M2b roadmap territory):
+- Migration / hunger / starvation-driven city abandonment.
+- Per-species predator-prey cascade affecting city food.
+- Worker reassignment AI for capacity-aware tile management.
+
+### Proof scene (SCAFFOLD SHIPPED — needs Godot run + screenshot)
+
+`src/game/engine/scenes/tests/proof_biome_economy_coupling.{tscn,gd}`
+authored 2026-04-29 — `gdlint` clean. Builds a stub Player + City
+programmatically, registers `cave_bear` via the canonical species JSON at
+`public/resources/ecology/fauna/species/cave_bear.json` (using the new
+`GdFaunaEcology::register_species_from_json` bridge method), seeds 200
+cave-bears on each of 4 owned tiles via `seed_population`, calls
+`fauna_product_supply` directly to demonstrate the supply path, then runs
+`Happiness.process_turn` to demonstrate the production lifecycle (which
+currently uses a per-call `GdFaunaEcology` and so misses the seeded
+populations — the proof scene comments document this discrepancy as the
+exact remaining wedge that item 7 below closes).
+
+Bridge enrichments shipped alongside the proof scene:
+- `GdFaunaEcology::register_species_from_json(species_json: GString) -> i64`
+  — accepts the canonical species JSON shape, returns the numeric species
+  id (string-id-hash) on success, `-1` on parse error. Reuses
+  `mc_ecology::species::Species::from_json`.
+- `GdFaunaEcology::seed_population(col, row, species_id, population)` —
+  pushes a `PopulationSlot` to the engine's `tile_populations`. Reuses
+  `EcologyEngine::seed_population`.
+
+Outstanding for the phase-gate:
+- Run the scene under Godot (apricot flatpak or local) with
+  `SCREENSHOT_NAME=p1_38_biome_economy_coupling tools/screenshot.sh
+  proof_biome_economy_coupling.tscn`.
+- scp the resulting PNG to `$SCREENSHOT_HOST` per
+  `.claude/instructions/phase-gate-protocol.md`.
+- Read + approve the screenshot in conversation.
+
+## Acceptance
+
+- [x] Phase C: `growth_modifier` plumbed end-to-end Rust → bridge → GDScript
+      callsites. `cargo test -p mc-city -p mc-happiness` green
+      (mc-city 60/60, mc-happiness 19/19). Live policy = +25% Happy bonus
+      only; revolt halt preserved; Unhappy 0.50× tier deferred.
+- [x] Phase A: `food_modifier` field on `TileYield`; `biome_yield.rs`
+      module with `EcologyYieldsConfig` and `ecology_food_modifier`;
+      `data/balance/ecology_yields.json` ships with `static_terrain`
+      fallback (inert). `cargo test -p mc-city` green (65/65 incl. 5 new).
+- [ ] Phase A: 10-seed batch on `fallback_when_dormant=coupled` shows
+      forest-heavy seeds diverge from baseline; Shipwright sign-off to
+      flip default in main.
+- [x] Phase B (Rust + data): 5 fauna_product JSONs, `resource.schema.json`,
+      `manifests/fauna_products.json`, `mc-ecology::fauna_product_supply`
+      accessor + 3 unit tests; mc-ecology 277/277 green on apricot.
+- [x] Phase B (consumer wiring): `happiness.gd::_collect_fauna_product_luxury_ids`
+      shipped, folded into `_collect_luxury_happiness_map` so fauna_products
+      flow through the existing `HappinessInput.owned_luxuries` BTreeMap.
+      `gdlint` clean. **Functionally inert until item 7 below lands** —
+      `EcologyEngine::new()` is empty; no live populations yet.
+- [x] Phase D (Rust math, INERT default): `BiomeCapacity`,
+      `BiomeCapacityConfig {enabled: false}`, `carrying_capacity_modifier`
+      shipped in `mc-city/src/biome_yield.rs`; 4 unit tests; mc-city 70/70
+      green on apricot.
+- [ ] Phase D (consumer integration): no new mc-city API needed — the
+      caller composes `tile.food_modifier = ecology_food_modifier ×
+      carrying_capacity_modifier` and the existing `City::get_yields`
+      scaling already absorbs both factors. GDScript helper analogous to
+      `_collect_fauna_product_luxury_ids` should populate the modifier
+      from `biome_capacity.json` + ecology densities when serialising
+      tile yields. Behaviour unchanged while either flag is `false`.
+- [x] Phase D (guide side): `carrying_capacity: { base, decay_per_excess_pop }` added to
+      `BiomeDisplay` interface and `ALL_BIOMES` builder in
+      `src/packages/guide/src/data/ecology.ts`. Bridge snapshot authored at
+      `public/games/age-of-dwarves/data/balance/biome_capacity.json` (55 biomes,
+      formula `clamp(fauna_capacity*6, 30, 200)`). Guide tests unchanged (112 pass).
+      Remaining: Rust `mc-city` soft-cap consumer (separate follow-up).
+- [ ] Proof scene + screenshot scp'd to `$SCREENSHOT_HOST`.
+
+`partial` until every bullet above lands. Phase C + Phase A wire are the
+durable shipped pieces; Phase B is data-only without consumer wiring;
+Phase D is unstarted; proof scene unstarted.

.project/objectives/p1-39.md

@@ -0,0 +1,30 @@
+---
+id: p1-39
+title: Port per-yield difficulty multipliers from GDScript into Rust crates (Rail-1) — research + culture
+priority: p1
+status: partial
+scope: game1
+tags: [rust-source-of-truth, rail-1]
+owner: warcouncil
+updated_at: 2026-04-27
+---
+## Summary
+
+During p1-29 Round 3-5, warcouncil added a per-yield difficulty multiplier framework (gold_mult, culture_mult, luxury_mult, research_mult, production_mult, yield_per_turn_growth) plus a symmetric player handicap (Easy = player gets Hard-AI bonuses). Per Rail-1, the multiplier APPLICATION should live in Rust crates, not in GDScript turn_processor.gd / economy.gd / turn_processor_helpers.gd.
+
+**Gold yield port: DONE 2026-04-27.** `EconomyParams.yield_mult` field added to `api-gdext/src/lib.rs:2962-2992` with serde default 1.0; `GdEconomy::process_turn` now scales gross income before netting expenses. GDScript `economy.gd::_build_params_json` injects `yield_mult` from `GameState.get_effective_yield_mult(player, "gold")`; the GDScript-side multiplication is deleted. Validated via 10-seed Hard batch `.local/iter/p1-31-r5-hard-20260427_044618/` — 4/5 quality gates PASS (up from 3/5), clan diversity up from 3 to 5 distinct winners.
+
+**Research yield port: DONE 2026-04-27.** Added `process_research(player_json, yield_json, sci_modifier)` passthrough at `knowledge_web.gd:152` (delegates to `_bridge.call("process_research", ...)`) and exposed at `tech_web.gd:39`. Refactored `turn_processor.gd::_process_research:143` to delegate fully — assembles JSON inputs (player_dict + per-city yields_arr), calls `tw.process_research()`, only handles completion side-effects (school_locked emit, _form_high_archon, tech_researched signal, resource reveals). No Rust rebuild needed (GdTechWeb::process_research already had sci_modifier as a direct parameter; only the wrapper-layer plumbing was missing).
+
+Validation: `.local/iter/p1-39-r6-hard-20260427_054348/` (10-seed Hard batch). 4/5 quality gates PASS: median winner_tier_peak=4.5 PASS (was 3 FAIL in R5 — research port LIFTED this), tier_peak_gap=5.0 FAIL (was 3.5 PASS — gates alternate, total still 4/5), max_peak_unit 10/10 PASS, wonders 7/10 PASS, combats 454 PASS. **All 10 games completed (vs 8/10 in R5)**, **6 distinct winners** (max diversity for 5-clan game).
+
+**Culture yield port: ATTEMPTED 2026-04-27, REVERTED.** Added `GdCity::process_culture_with_modifier(tile_yields_json, total_pct)` to api-gdext/src/lib.rs:1399 that mirrors the GDScript flow (process_culture → check raw_gain → add bonus → recheck can_expand). Math nominally identical. But R8 batch (Rust culture port) diverged from R6 (GDScript) on every seed (e.g. seed 1: R6=T251/tier=6/wonders=10, R8=T111/tier=2/wonders=0). R9 isolation batch (revert culture path on current source tree) reproduced R6 EXACTLY per-seed (`.local/iter/p1-39-r9-revert-hard-20260427_213224/`), proving the divergence is from the Rust culture path itself, NOT from other landed code (courier diplomacy, building ID reconciliation) between R6 and R7/R8. Floating-point intermediate values likely differ between the in-Rust mutation sequence and the GDScript-Variant-roundtrip mutation sequence; the difference cascades into different border-expansion timing → different tile ownership → entirely different game trajectories. Culture path REVERTED to GDScript (p1-39 stays partial — gold + research ported, culture deferred). Future port should investigate Rust f64 vs Variant FLOAT round-trip semantics, or alternative scope (e.g. apply difficulty modifier in GdCity::process_culture itself with an optional parameter, leaving the building-bonus math out of scope).
+
+The fix for both: add `process_research` and `process_culture` passthrough methods to the GDScript wrapper layers, refactor the GDScript callers to delegate fully (matching the gold-port pattern). Estimated 2-3 hours including parity validation.
+
+## Acceptance
+
+- ✓ Research: tech_web.gd / knowledge_web.gd expose process_research(player_json, yield_json, sci_modifier); turn_processor.gd::_process_research delegates and the local multiplication is deleted (validated R6 batch above)
+- ❌ Culture: mc-culture GDExt wrapper exposes a process_culture passthrough; turn_processor.gd::_process_culture delegates and the (difficulty_cult_mult - 1.0) inline addition is deleted
+- ❌ Replay parity: Re-run p1-31-r5-hard-20260427_044618 seeds with fully-ported binary; quality-gates within 5% (deterministic seeds → deterministic outputs)
+- ❌ GameState.get_effective_yield_mult kept as the single tuning-value source (UI displays use it directly)

.project/objectives/p1-40-single-source-of-truth-resources.md

@@ -0,0 +1,44 @@
+---
+id: p1-40
+title: Collapse data/<category>/ override layer into single source of truth at resources/
+priority: p1
+status: done
+scope: game1
+updated_at: 2026-04-29
+evidence:
+  - public/resources/buildings/  (159 per-file post-migration)
+  - public/resources/units/  (155 per-file post-migration, generic + race-prefixed)
+  - public/games/age-of-dwarves/data/  (no buildings/ or units/ subdirs remain)
+  - public/games/age-of-dwarves/data/schemas/unit.schema.json  (widened: domain += naval, unit_type += siege, gender ?nullable)
+  - public/games/age-of-dwarves/data/schemas/building.schema.json  (effects.value typed: number|boolean|string)
+  - tools/validate-game-data.py  (walks resources/{units,buildings}/, skips building_categories.json)
+---
+
+## Summary
+
+Today `public/games/age-of-dwarves/data/{units,buildings,techs}/` mirrors `public/resources/{units,buildings,techs}/` with override semantics: the loader walks resources/ first, then game/data/ overwrites by id. This created three real bugs in the last few sessions:
+1. Audit blind-spot: 9 "missing" buildings and 6 "missing" food/processing buildings turned out to live in resources/buildings bundled files that the per-file audit missed.
+2. Silent semantic drift: 14 building IDs are defined in both layers with different cost/tech/effects; the data/ version wins by accident-of-loader-order.
+3. Broken tech gates: 6 of 8 ordinary-building duplicates have `tech_required` in resources/ pointing at non-existent techs (`military_doctrine`, `smelting`, `husbandry`, `scholarship`, `ancestor_rites`, `masonry`, `mathematics`). The data/ overrides are the only thing keeping those buildings buildable.
+
+The right architecture is one source of truth at `public/resources/<category>/`, with `public/games/<game>/` carrying only **game-pack-specific configuration** (clan personalities, setup, vocab, difficulty) and a manifest declaring which resource IDs the game subscribes to. No more override layer.
+
+This objective is the **safe mechanical phase** — move all entity files to resources/ canonical locations and resolve the duplicates. The behavioral phase (subscription manifest + loader filter) splits to `p1-41`.
+
+## Acceptance
+
+- ✗ The 8 ordinary-building duplicates (`barracks`, `forge`, `granary`, `library`, `monument`, `siege_workshop`, `temple`, `walls`) reconciled by moving the data/ definition (working tech wiring) into resources/ and deleting the data/ side. Per-building note in this file's prose recording any salvaged effect strings from the old resources/ version (richer effects like `unit_attack_bonus`, `enables_siege` may need Rust handlers — file as separate effect-handler objective if missing).
+- ✗ All 89 generic-class units in `data/units/<id>.json` (warrior, worker, archer, ...) moved to `resources/units/<id>.json`. Zero collisions today (verified). Race-prefixed `dwarf_*.json` already in resources/units/ — unchanged.
+- ✗ Compatibility stubs reconciled: `data/units/stub.json` (`founder` alias) → `resources/units/founder.json`. `data/buildings/stub.json` (`granary` simplified-cost variant) deleted; canonical granary lives at `resources/buildings/granary.json` post-move.
+- ✗ `data/{buildings,units}/manifest.json` deleted — no longer relevant once all files live at resources/. (If migration is split-phase, may stay as transitional documentation until p1-41.)
+- ✗ Empty `data/buildings/` and `data/units/` directories removed (or stay empty pending p1-41 if any tooling depends on the path).
+- ✗ Post-migration audit: zero IDs defined in both layers. `python3 tools/validate-game-data.py` passes 317/0.
+- ✗ Rust tests still pass: `cargo test -p mc-ai --lib` 186/186, `cargo test -p mc-turn` clean.
+- ✗ A 10-seed `tools/autoplay-batch.sh 10 300` regression batch shows no behavior shift > ±15% on median city count / tech tier / score (no logic changed; ID set unchanged; loader walks the same `_data` dict).
+
+## Out of scope
+
+- Subscription manifest at `games/<game>/manifest.json` and the loader filter that reads it. Filed as `p1-41`.
+- Authoring the missing tech IDs (`smelting`, `husbandry`, etc.) that resources/ versions referenced. The orphan tech gates were already broken pre-migration; fixing them is its own design pass.
+- Salvaging the richer `effects[]` strings (`unit_attack_bonus`, `enables_siege`, `siege_production_speed`, `growth_bonus`, etc.) from the deprecated resources/ versions where Rust handlers don't exist. Each requires effect-system work in `mc-economy` / `mc-combat`. File per-effect follow-ups.
+- Moving `techs/`, `culture/`, etc. — same pattern but separate objectives if the pattern repeats there.