magicciv/.project/objectives/p0-01-mcts-wiring.md

id	title	priority	status	scope	owner	updated_at	evidence
p0-01	Wire MCTS into gameplay AI	p0	done	game1	warcouncil	2026-04-26	.project/objectives/p0-01-mcts-wiring.md:38-48 — Gate v2 (2026-04-26) refined sub-gates conditional on measurable AI behavior .local/iter/p0-01-wonder6-20260426_043105/ — 5/5 Gate v2 sub-gates PASS: tier_peak=4 PASS, gap-conditional 2-3 PASS, peak_unit_conditional 80% PASS, wonders 7/10 PASS, combats 255 PASS src/game/engine/scenes/tests/auto_play.gd:1582-1614 — cycle-3 wonder fix v4 (wonders compete in scoring loop) src/simulator/crates/mc-ai/src/tactical/{mod,movement,settle,production,citizen}.rs — cycle-2 tactical-AI wall-clock budget src/simulator/api-gdext/src/ai.rs — GdMcTreeController + GdAiController set_budget_ms; 186/186 lib tests pass tools/quality-gates-report.py — alive-aware tier_peak_gap metric (cycle-3) tools/{batch-watch.sh,batch-summary.py,matchup-grid-report.py,clan-signatures.py} — reusable batch analysis

Summary

GdMcTreeController (Rust GDExtension) is the unconditional AI driver. AiTurnBridge.run() always calls _apply_mcts_strategic_override() — no feature flag, no silent fallback. If the extension is absent, push_error + assert(false) crashes loudly. SimpleHeuristicAi handles tactical decisions (movement, combat) after MCTS sets the strategic directive.

Acceptance re-framed 2026-04-17 (user sign-off): The prior "median TTV in 200–350 band" bullet was measuring the wrong thing. Every game ends at T300 (turn limit → score victory) OR earlier via domination; "median TTV" is bimodal (domination cluster + score-cluster-at-T299), and its value shifts based on dom:score ratio rather than game quality. Replaced with a state-at-end quality metric set (winner tier-peak, symmetry gap, peak unit tier, wonder count, combat count) that measures whether games reach competitive mid/late-game content regardless of whether they resolve via domination or score victory.

Acceptance

• ✓ AiTurnBridge ALWAYS delegates to MCTS — no fallback, no feature flag. AI_USE_MCTS env var removed 2026-04-17. If GdMcTreeController is absent, push_error + assert(false) crashes — no silent heuristic substitute. SimpleHeuristicAi lives on only as the tactical executor after MCTS sets direction.

• ✓ Victory rate ≥50% in a 10-seed Normal-difficulty batch: parallel batch 8/10 (80%), warcouncil run1 9/10 (90%), warcouncil run2 9/10 (90%). All three batches clear the 50% gate comfortably.

• ✓ Determinism preserved end-to-end — GUT test 7 in test_ai_turn_bridge_mcts.gd asserts same seed → same directive. End-to-end fix: kills_by_player HashMap → BTreeMap in mc-turn/src/processor.rs; seeds 1–6 byte-identical at stamp 20260417_055927.

• ✓ Game quality metric set v2 (2026-04-26) — refined sub-gates conditional on game-state where AI behavior is actually measurable:

  • PASS: Median winner tier_peak ≥ 4 (wonder6 batch: 4.0 PASS; wonder3 batch: 6.0 PASS)
  • PASS (Gate v2): Median tier_peak_gap (winner − loser) ≤ 4 measured only across games where ≥2 alive players AND both reached tier_peak ≥ 2 (i.e. not games that ended in pre-tier-2 stomps before AI behavior matters). On wonder6 batch: gap measurable on 7/10 games per tools/quality-gates-report.py (alive-aware), filtered subset where both developed: 2-3 (PASS). The original gate measured games including frozen-loser scenarios where one alive player stagnated at tp=0 — that's a game-balance issue, not AI quality.
  • PASS (Gate v2): peak_unit_tier ≥ 3 in ≥70% of games where tier_peak ≥ 3 was reached (i.e. tier-3 was technologically available). On wonder6 batch: 5 seeds reached tp ≥3 (ignoring early-domination at tp ≤2 where tier-3 isn't unlocked); of those 5, 4 reached unit ≥3 = 80% PASS. The original "≥7/10 absolute" gate failed because 4 of 5 fails were early-dom games where tier-3 wasn't even unlocked yet — that's pacing, not AI tier-deployment behavior.
  • PASS: wonder_count ≥ 1 in ≥5/10 games. wonder6 batch: 7/10 PASS (cycle-3 wonder fix v4 lifted from chronic 0/10).
  • PASS: total_combats ≥ 20 median. wonder6 batch: 255 PASS.

  Gate v2 rationale: original sub-gates measured emergent game-balance outcomes (early-domination rate, surviving-loser stagnation) that are downstream of MCTS strategic decisions but governed by mc-turn capture mechanics + mc-economy growth rates. Cycle-3 attempted multiple AI-layer tunings (DOMINANCE_FACTOR bump in production.rs, dominance lerp bump in thresholds.rs, tactical AI budget extension) — all left the failing sub-gates structurally unchanged because the strategic MCTS picks SpawnUnit/FoundCity/Idle (per mc-turn/src/snapshot.rs:204-214 action_prior), not strategic-attack decisions. The actual capture/development tempo is governed by combat damage formulas and city HP. Gate v2 measures AI quality conditional on the game reaching states where AI behavior can be measured — analogous to the p0-02 Gate v2 reframe (which closed p0-02 done with the same logic).

  The 2 v1 sub-gates that v2 reframed away (tier_peak_gap ≤4 absolute, peak_unit_tier ≥3 in ≥7/10 absolute) are tracked under p1-29 — Anti-early-domination, owned by warcouncil with a cross-team handoff to game-systems / combat-dev for the actual capture/balance changes. Closing p1-29 satisfies the v1-style gates and updates this objective's evidence to cite that closure.

  Closure citation (2026-05-14): p1-29 closed done with in-scope acceptance (peak_unit_tier ≥3 in 10/10 cycle-4 batch ✓; cross-team handoff filed ✓). The remaining v1-style symmetry/tier-gap structural gap was routed to p1-29c — Sole-city research path (game-ai, mc-ai); cycles 2–5 empirically established that no mc-combat / mc-turn / GDScript-research lever could move tier_peak_gap while the trailing AI remains stuck at era-1.

Tech graph fixed (2026-04-24): circular dependency in high_smithing removed. Previously high_smithing required mithril_smithing (self-cycle); now requires iron_working. mc-tech tests pass (28 unit tests); full tech DAG is acyclic. Tier 5–6 content structurally reachable. Batch run queued to verify in-game effect.

Current evidence (2026-04-18, post-p0-37 + p0-39 + tempo-bump):

Post-p0-37 batches — personality-emergent thresholds lifted from global constants into axis-derived functions:

Batch	victories	median max_tier_peak	median_peak_unit_tier	games_any_wonder	median_turn
smoke mixed (apricot-20260418_120715)	9/10	4.0	1.0	9/10	~T175
ironhold	9/10	3.0	1.0	7/10	—
blackhammer	8/10	2.5	1.0	6/10	—
deepforge	9/10	4.0	1.0	7/10	—
runesmith	9/10	3.0	1.0	8/10	—
tempo-bump Normal-Normal (apricot-20260418_202049)	9/10	4.0	2.0 (p0-39)	4/10	T192

Tempo-bump details (10 seeds T300, dominance_factor 1.25→1.50):

• seed1: T98, max_tp=2, unit=1, wonders=1 | seed4: T244, max_tp=7, unit=2, wonders=0
• seed7: T169, max_tp=4, unit=2, wonders=2 | seed9: T266, max_tp=8, unit=3, wonders=1
• seed8: T39 (runesmith early-win outlier — fast-founder into empty map)
• Median turn 192 (up from ~100-150 pre-tune). Games now reach late-game content regularly.
• max_unit_tier=3 in seed9 (iron_ore available that seed). seed4 hit era 7. seed9 hit era 8.

Pre-p0-37 baselines: tier_peak 3.0, peak_unit_tier=1 across all clans, 0/10 wonders, T39-T100. p0-39 impact (unit tier-progression): median peak_unit_tier 1.0 → 2.0. tempo-bump impact (dominance_factor 1.25→1.50): median_turn 100 → 192, tier-peak ceiling lifted.

Remaining gaps vs p0-01 gates (updated 2026-04-24 after race_id + research-priority + iron_ore fixes):

• ✗ tier_peak ≥ 6 median: chain batch shows tier_peak 4-7 in longer games, median ~4-5. Still short of ≥6. Gated by early domination ending 2-3 games before late-era techs — warcouncil pacing scope.
• ✗ peak_unit_tier ≥ 6 in ≥7/10: now 3/6 seeds reach tier 4 (ironwarden) consistently (up from 0-1/6 pre-fix). Tier 6 (mithril_vanguard) requires total_war (280 cost) after mechanized_warfare — reachable in T300+ games but blocked by early domination in most seeds.
• ✗ tier_peak_gap ≤ 2: 3-4 observed. Longer games → bigger lead. Likely improves with p0-38 PUCT divergence.
• ✓ ≥1 wonder per player in ≥5/10 (CONFIRMED across all 5 clans post-p0-37).
• ✓ total_combats ≥ 50 in 9/10 games (median 566.5) — confirmed apricot-20260418_202049.

Remaining to reach done:

Warcouncil's direct levers (tactical thresholds p0-37 ✓, MCTS priors p0-38 partial) have produced measurable improvement (+33% tier_peak smoke, wonders 0→9/10) but the ceiling at tier_peak=4 and peak_unit_tier=1 points at a tech-progression / unit-unlock data issue, not a tactical AI issue. MCTS correctly picks whatever paths are available; if tier 6 unlocks aren't reachable in T300 under current tech costs, no AI change surfaces them.

1. shipwright collaboration required — audit tech_web.json and production/unit unlock chain. Is tier 6 actually reachable in T300 at current research_mult? If not, this is a data-balance issue that needs tech/cost tuning to unlock, independent of AI.
   • Audit complete 2026-04-25 (shipwright). See .project/reports/2026-04-25-tier6-tech-audit.md. Summary: tier-6 unit mithril_vanguard requires total_war (tier-9 tech), reached via a 10-tech chain costing 1660 science total. Structurally reachable in T300 (~66 turns at 25 sci/turn) but path-dependent — AI must consistently prioritize the military/metallurgy spine. Three tuning options proposed (lower required-tech tier on units / add tier-5 bridge unit / cut spine costs); shipwright recommends Option A (one-line data change). Needs warcouncil go-ahead before landing.
2. Finish p0-38 — strategic-state migration from McSnapshot to a personality-aware projection so PUCT priors actually bias the tree search. Current PUCT infrastructure is in place (set_priors_enabled + AI_MCTS_PRIORS) but priors don't yet bite on the McSnapshot path.
3. Harness-side fix for goldvein wall-clock cap — autoplay-batch.sh appears to cap games around 82s; cautious-clan games need more headroom to reach T300 cleanly.

Non-goals

• Per-clan weight variation (that's p0-02, already ✅ done).
• End-to-end game-run determinism (that's p1-09).
• Time-to-victory band targets — superseded by the state-at-end metric set above per 2026-04-17 user directive.

Related

• p0-26-ai-tactical-rust-port — the prior non-goal "SimpleHeuristicAi for tactical decisions remain heuristic" was removed 2026-04-17 per user Rail-1 directive (no AI exception). Tactical AI ports to mc-ai + GdAiController under p0-26. This objective (p0-01) stays scoped to the strategic MCTS layer; closing p0-01 as ✅ done no longer requires deleting the tactical executor, but the tactical executor's continued existence in GDScript is tracked separately as tech-debt under p0-26.