scenario-check

name	scenario-check
description	Validate scenario configuration files for correctness, consistency, balance, localization, and playability. Run with no arguments to check all scenarios, or pass a scenario name to check one.
argument-hint	[scenario_name]
allowed-tools	Bash Read Grep Glob Agent

Scenario Validation Skill

You are an experienced game designer and QA engineer reviewing tactical grid combat scenarios for Silicon Pantheon.

Target

• If $ARGUMENTS is empty or blank: check ALL scenarios in games/*/config.yaml (skip _test_plugin)
• If $ARGUMENTS is a scenario name (e.g., 03_thermopylae): check only that scenario

Checks to Perform

For each scenario, read the full config.yaml and the locale/zh.yaml (if it exists), then run every check below. Report each issue with severity (CRITICAL / HIGH / MEDIUM / LOW / INFO).

1. Format & Loading (CRITICAL if broken)

• Run load_scenario(name) via Python to verify the config parses and loads without errors:

  .venv/bin/python3 -c "from silicon_pantheon.server.engine.scenarios import load_scenario; s = load_scenario('SCENARIO_NAME'); print(f'{s.board.width}x{s.board.height} {len([u for u in s.units.values() if u.owner.value==\"blue\"])}b+{len([u for u in s.units.values() if u.owner.value==\"red\"])}r')"
  

• Every terrain type used in board entries must be defined in terrain_types
• move_cost on impassable terrain must be 99 (not 1 or a string)
• passable: false must accompany move_cost: 99

2. Unit Placement (CRITICAL if broken)

• No unit placed on an impassable tile (cross-reference positions against passable: false terrain)
• No unit out of bounds (x must be 0..width-1, y must be 0..height-1)
• No two units on the same tile
• Both teams have at least 3 units
• No unit has ATK 0 or HP 0

3. Glyph & ID Consistency

• No glyph collisions of any kind (HIGH severity). The map renders blue units UPPERCASE, red units lowercase, and terrain glyphs as-is. Three collision types to check:
  1. Terrain-terrain: No two terrain_types may share the same glyph — they are visually identical on the map.
  2. Unit-terrain (rendered form): A blue unit's glyph.upper() must not equal any terrain glyph. A red unit's glyph.lower() must not equal any terrain glyph. These produce identical characters on the map and the agent cannot distinguish unit from terrain.
  3. Cross-team unit-unit: No blue unit's glyph.upper() should equal any red unit's glyph.lower() (i.e., no two units across teams should share the same base letter). While case-distinguishable, this forces the agent to rely on case alone to tell units apart, which wastes reasoning tokens. Fix by changing the conflicting unit glyph to an unused letter. Prefer meaningful mnemonics (first letter of name/role).
• No color is shared between any unit_classes entry and any terrain_types entry (MEDIUM severity when violated) — otherwise a unit parked on a same-color tile becomes visually indistinguishable from the terrain. Units should use team colors (red/bright_red, cyan/bright_cyan, magenta for accents); terrain should use environmental colors (green, blue, yellow, white, bright_black, dim). Fix by changing the terrain color to a nearby unused shade.
• Win condition unit_id values must match actual units (format: u_{b|r}_{class}_{N})
• reach_tile positions must be within bounds and NOT on impassable tiles
• seize_enemy_fort requires forts to exist
• Fort entries should use owner not team

4. Localization Completeness

• locale/zh.yaml must exist
• zh.yaml must have name translated
• Every unit_classes key in config must appear in zh.yaml with display_name and description
• Every terrain_types key in config must appear in zh.yaml with at least display_name
• narrative.title, narrative.description, narrative.intro must be translated
• Every narrative.events entry must have translated text
• The zh name source tag (e.g., "— 权力的游戏") must match the English tag (e.g., "— Game of Thrones")

5. Narrative & Description Consistency

• description mentions of turn numbers must match max_turns and actual reinforcement timing
• narrative.events turn numbers must not exceed max_turns
• on_unit_killed events must reference valid unit IDs
• Plugin hooks mentioned in narrative must exist in plugin_hooks
• first_player should match the story (attackers go first in assault scenarios)
• protect_unit_survives + max_turns_draw together: check which one actually fires

6. Map Design Quality

• Map should be at least 14x12 (168 tiles) for 10+ units, or 20x14 for 12+ units
• Tile-to-unit ratio should be 10x-25x (not too cramped, not too empty)
• Terrain coverage: at least 20% of tiles should be non-plain
• Check for "dead space" — large rectangular areas (5x5+) with zero terrain features
• At least 2 distinct routing options between the two armies (not just a straight line)
• No "island" units — every unit must be able to reach at least one enemy unit via passable tiles (BFS reachability)

7. Unit Balance & Diversity

• No "god-tier" unit: HP > 50 AND ATK > 15 AND DEF > 10 (any one is fine, all three is broken)
• No unit with DEF or RES so high that no enemy can deal more than 1 damage (check: max enemy ATK - unit DEF <= 1 for ALL enemies)
• No sniper-tier unit without a symmetric counter on the opposing side. A "sniper" here is rng_max >= 3 AND atk >= 10 — a unit that can deal heavy damage from 3+ tiles away. Compute each sniper's threat as roughly atk * rng_max * (1 + move/10) * (hp/30). For each sniper on team A, team B must have at least ONE of: (a) a sniper with threat within 40% of team A's biggest sniper, (b) a fast melee (SPD >= 7) that can close the gap, (c) if the sniper is magic, a unit with RES >= 7 that can tank the magic damage, or (d) if the sniper is physical, a unit with DEF >= 7. Flag as HIGH if a sniper has NO counter; MEDIUM if counters exist but are clearly overmatched (team ratio > 2x threat). Fix by: nerfing the outlier (HP or ATK), adding a counter unit to the opposing side (narrative-appropriate counter — e.g. a scorpion ballista against a dragon), or expanding the opposing roster. A scenario with TWO sniper-tier units on the same side and ZERO on the other is almost always broken.
• Factor in map terrain when evaluating sniper balance. The threat-ratio heuristic assumes melee units can realistically close the gap. When impassable terrain (walls, river, cliffs) separates the two armies AND one side's snipers are inside a fortified zone, the effective imbalance is WORSE than the raw ratio says. Specifically, check: (1) can the outgunned side's fast melee actually reach the snipers within 2-3 turns via gap-chokepoints, or does the path take 4+ turns (during which the snipers freely kite)? (2) does the outgunned side have FLIERS (tag includes flying) matching the count of flying snipers on the other side — flying bypasses impassable terrain entirely? (3) does the outgunned side have enough range to hit the snipers from their own side of the wall? If none of (1/2/3) hold, tighten the ratio guardrail from 2× to 1.3× or add a flier/more gaps. Flag scenarios where one side has N+1 fliers and the other has N as MEDIUM — the aerial count must be symmetric when walls are involved.
• Role diversity: the scenario should have at least 3 of these 5 roles per team: melee DPS, ranged, tank (DEF >= 7), healer, fast/assassin (SPD >= 7)
• At least one unit per team should have is_magic: true OR at least one enemy should have low RES
• Check for absurd terrain bonuses: no terrain with defense_bonus > 5 or heals > 10

8. Unit Spread & Engagement Pacing

• Minimum distance between closest blue and red unit should be >= 4 tiles (Manhattan distance)
• Same-team units should not ALL be within a 3x3 box (too clustered)
• Average distance from each unit to the nearest enemy should be >= 5
• With average unit MOVE of 3-4, first contact should be turn 3+ (distance / avg_move >= 3)

9. Copyright & Metadata

• schema_version: 1 present
• license field present (one of: original, public_domain, fan_work)
• If license: fan_work, fan_work_source must be present and non-empty
• name should contain a source tag after " — " (era for historical, franchise for fiction)
• difficulty should be 1-5

9b. Non-Breaking YAML Discipline (HIGH severity when violated)

Scenario YAML is served from server to client via get_scenario_bundle. Old clients will parse YAML the new server sends, so every scenario edit is effectively a wire-format change. Most edits are safe; these patterns are breaking and require coordinating with the wire-protocol version gate in docs/VERSIONING.md:

• Renaming a field (unit_classes → classes, move_cost → mv_cost): old clients look for the old key, find nothing, unit list is empty / move costs are all 1. Breaking.
• Retyping a field (e.g. move_cost: 2 → move_cost: {base: 2, cavalry: 1}): old clients type-error or compute garbage. Breaking.
• Adding a field that REQUIRES new-client behavior to interpret correctly (e.g. a new flying tag that must bypass impassable terrain): old clients ignore the tag, compute normal movement, units get stuck or move where they shouldn't. Semantically breaking even if syntactically additive.
• Renaming/removing a tool used in scenario plugin hooks (plugin_hooks.on_turn_start: [rename_me]): old clients' plugin registry can't find it, hooks don't fire. Breaking.

These are safe (additive, default-tolerant):

• Adding a new scalar field with a meaningful default for old clients (description_long: "...", difficulty: 3): old clients ignore the extra key, keep playing.
• Adding a new unit-class stat that defaults to 0 on absent (armor_piercing: 2): old clients never read the field, compute with the default.
• Adding a new unit_class that isn't deployed anywhere yet.
• Adding a new terrain_type entry alongside existing ones.

When the check finds a breaking scenario change, flag it HIGH and recommend either:

1. Restructuring the change to be additive + default-tolerant (e.g. leave move_cost: 2 as int; add a separate move_costs_per_tag: {...} dict that old clients ignore), or
2. Accompanying it with a PROTOCOL_VERSION bump per the four-phase rollout in docs/VERSIONING.md.

10. Plugin Security (if plugin_hooks exists)

• Check that referenced plugin names correspond to a rules.py file in the scenario directory
• Read the rules.py and check for: import os, import subprocess, import socket, exec(, eval(, open( on paths outside the game directory, __import__, network calls
• Plugin should only modify game state (spawn units, modify HP, check win conditions)

Output Format

For each scenario, output:

## SCENARIO_NAME — [PASS | ISSUES FOUND]

[If issues found, list each with severity and description]

- CRITICAL: [description]
- HIGH: [description]  
- MEDIUM: [description]
- LOW: [description]

At the end, output a summary table:

| Scenario | Status | Critical | High | Medium | Low |

If fixing is straightforward (e.g., missing locale key, wrong move_cost), fix it directly and note "[FIXED]" next to the issue.