chore: add and sync all local changes (content, docs, tests, etc.)

Author: SorraTheOrc

content/worlds/default/story_seeds.yml

@@ -18,6 +18,35 @@ story_seeds:
       - "Aria Volt drafts an emergency ration plan that would divert power from research labs."
     triggers:
       - scope: environment
+      # ...existing code...
+    resolution_templates:
+      success: "Emergency rationing shares power fairly and the Union backs down."
+      failure: "Workshops go dark, strikers spread, and council legitimacy crashes."
+      partial: "Convoys buy time but sabotage rumors keep tensions high."
+    followups: [supply-chain-collapse]
+
+  - id: supply-chain-collapse
+    title: "Supply Chain Collapse"
+    summary: "A sudden breakdown in logistics leaves multiple districts without critical resources."
+    stakes: "Factions scramble to secure dwindling supplies, risking open conflict."
+    scope: citywide
+    tags: [logistics, scarcity, crisis]
+    preferred_districts: [industrial-tier, research-spire, perimeter-hollow]
+    cooldown_ticks: 60
+    travel_hint:
+      district_id: industrial-tier
+      max_focus_distance: 5
+    roles:
+      agents: [aria-volt, caden-shard]
+      factions: [union_of_flux, hollow_perimeter]
+    beats:
+      - "Freight drones are grounded, halting deliveries to key districts."
+      - "Caden Shard proposes rationing and emergency trade deals."
+      - "Union of Flux threatens to blockade the perimeter if their demands aren't met."
+    triggers:
+      - scope: citywide
+        condition: resource_shortage
+        threshold: 0.2
         min_score: 0.45
         min_severity: 0.75
         max_focus_distance: 4

content/worlds/default/world.yml

@@ -16,8 +16,13 @@ city:
         energy:
           type: energy
           capacity: 80
-          current: 60
-          regen: 4.5
+          current: 40  # Reduced to increase scarcity
+          regen: 2.0  # Slower recovery to heighten tension
+        materials:
+          type: materials
+          capacity: 60
+          current: 20  # Scarcity for supply chain events
+          regen: 1.0
         materials:
           type: materials
           capacity: 55
@@ -94,6 +99,16 @@ factions:
     territory:
       - perimeter-hollow
     description: Black-market syndicate controlling perimeter trade.
+  - id: hollow_perimeter
+    name: Hollow Perimeter
+    ideology: Perimeter dwellers focused on survival and adaptation.
+    legitimacy: 0.45
+    resources:
+      food: 30
+      salvage: 20
+    territory:
+      - perimeter-hollow
+    description: Community of survivors and scavengers in the outer city.
 agents:
   - id: aria-volt
     name: Aria Volt
@@ -122,7 +137,17 @@ agents:
     traits:
       analysis: 0.88
       curiosity: 0.91
+    goals: []
+  - id: caden-shard
+    name: Caden Shard
+    role: Survivalist
+    faction_id: hollow_perimeter
+    home_district: perimeter-hollow
+    traits:
+      resilience: 0.81
+      ingenuity: 0.76
     goals:
+      - Protect perimeter resources from external threats
       - Reduce pollution spillover from the Industrial Tier
 environment:
   stability: 0.56

docs/simul/emergent_story_game_gdd.md

@@ -1,5 +1,73 @@
 # Echoes of Emergence – Game Design Document
 
+## Automated Testing & Balancing Plan
+
+### Simulation Results Summary (2025-12-07)
+
+### Design Update: Disruptive Story Seeds & Resource Scarcity
+
+#### Purpose
+Introduce disruptive story seeds (e.g., city-wide crises, faction betrayals, resource shortages) and resource scarcity to increase tension, risk, and outcome diversity. These events force players to adapt tactics, manage resources, and recover from setbacks, making each playthrough more engaging and unpredictable.
+
+#### Mechanics & Tuning Knobs
+
+- New disruptive story seed added: "Supply Chain Collapse" (citywide logistics breakdown, resource shortage, faction conflict).
+- Resource scarcity increased in default world: energy and materials starting values reduced, slower regeneration.
+- Supply Chain Collapse triggers when resources fall below 20% in key districts, forcing emergency rationing and trade decisions.
+
+- Disruptive seeds trigger unpredictable events (e.g., sudden supply chain collapse, faction betrayal, environmental disaster).
+- Resource scarcity is tuned via config knobs (frequency, severity, recovery options) in `content/config/`.
+- Director pacing controls when and how often disruptions occur, ensuring tension without overwhelming the player.
+
+#### Game Loop Impact
+- Moment-to-moment: Players must react to crises, make tough choices, and prioritize limited resources.
+- Mid-term: Faction/district management becomes riskier, requiring strategic planning and mitigation.
+- Long-term: Campaign arcs feature more recovery opportunities, failure modes, and divergent outcomes.
+
+#### Balance Guidance
+- Target: Tension curves with clear risk/reward, readable feedback, and recovery options.
+- Safe envelope: Disruptions should challenge but not punish; configs should allow tuning for different skill levels.
+- Telemetry: Use batch sweeps to validate tension, outcome diversity, and avoid grind/snowball/dead-end states.
+
+#### Enjoyment Risks & Follow-ups
+- Risks: Excessive punishment, opaque outcomes, confusion.
+- Mitigation: Start with mild disruptions, increase severity gradually, and run lightweight playtests to validate fun and readability.
+
+---
+
+
+- **Proposal:** Add disruptive story seeds (e.g., city-wide crises, faction betrayals, resource shortages) and introduce resource scarcity to scenario configs.
+- **Intended impact:** Create more risk, recovery opportunities, and divergent outcomes across strategies, increasing tension and replayability.
+- **Balance guidance:** Tune disruptive events to occur unpredictably but not overwhelmingly; ensure recovery options exist so players can avoid dead-ends.
+- **Next steps:** Prototype new seeds and scarcity configs, then run fresh batch sweeps to validate increased tension and outcome diversity.
+
+
+- **Strategies tested:** balanced, aggressive, diplomatic (seed 42, normal difficulty, 100 ticks)
+- **Outcomes:** All strategies activated the 'hollow-supply-chain' story seed and reached final stability 1.0 within 100 ticks.
+- **Action profiles:**
+  - Balanced: 10 INSPECT actions
+  - Aggressive: 5 DEPLOY_RESOURCE, 5 INSPECT
+  - Diplomatic: 7 INSPECT, 3 NEGOTIATE
+- **Balance notes:** No grind, snowball, or dead-end states observed. All strategies converged to stable outcomes, suggesting current tuning is fair but may lack tension spikes or risk of failure.
+- **Next steps:** Increase scenario variety and introduce more disruptive story seeds to test edge cases and tension curves.
+
+
+1. **Automated Playtest Scenarios**
+   - Scripted agents simulate player actions across all three rings (moment-to-moment, mid-term, long-term).
+   - Batch simulations with varied configs from `content/config/` capture win/loss rates, resource curves, and narrative pacing.
+   - Key metrics (decision density, tension spikes, recovery frequency) are logged to `build/telemetry/` for analysis.
+
+2. **Balance Sweeps and Tuning**
+   - Parameter sweeps systematically vary difficulty, resource availability, and director pacing knobs.
+   - Telemetry identifies grind, snowball, and dead-end states; configs producing unfun or unreadable outcomes are flagged.
+   - Auto-generated balance reports summarize safe tuning envelopes and outlier scenarios.
+
+3. **Continuous GDD Alignment**
+   - After each test sweep, GDD statements are cross-checked against observed outcomes.
+   - Balance notes and tuning guidance are updated to reflect actual system behavior, with prototype divergences highlighted.
+
+---
+
 ## 1. High-Level Concept
 
 **Working Title:** Echoes of Emergence

gamedev-agent-thoughts.txt

@@ -307,4 +307,49 @@ Working on Issue #71 - Phase 11, Milestone 11.4, Task 11.4.1.
 - Reviewed recent commits and updated .pm/tracker.md: Task 11.4.1 (Strategy Parameter Optimization) marked complete, summary table and outstanding work sections updated. No blockers; only 11.6.1 remains as optional for Phase 11. Ran markdownlint; only line length warnings present.
 
 ## [tracker_agent] — 2025-12-07 04:04
-- Created and documented task 12.1.1 (Terminal UI Core Implementation) in .pm/tracker.md. Updated summary table and milestone details. Lint check run; only line length warnings present.
+- Created and documented task 12.1.1 (Terminal UI Core Implementation) in .pm/tracker.md. Updated summary table and milestone details. Lint check run; only line length warnings present.
+
+## [Game Design Agent] — 2025-12-07 04:41
+- Ran batch simulations for balanced, aggressive, and diplomatic strategies. All reached stable outcomes with no grind or dead-ends. Updated GDD with results and next steps for deeper tension testing.
+
+## [Game Design Agent] — 2025-12-07 04:53
+- Recommended adding disruptive story seeds and resource scarcity to increase tension and outcome variation. Updated GDD with proposal and balance guidance. Next: prototype new events and configs, then validate via batch sweeps.
+
+## [Game Design Agent] — 2025-12-07 04:54
+- Updated GDD with detailed design for disruptive story seeds and resource scarcity. Documented mechanics, tuning knobs, game loop impact, balance guidance, and enjoyment risks. Ready for prototyping and playtest validation.
+
+## [GameDev Agent] — 2025-12-07 04:59
+- Implemented disruptive story seed (Supply Chain Collapse) and increased resource scarcity in default world config. Updated GDD and implementation plan with changes. Next: Validate impact via batch simulation sweeps and telemetry review.
+
+## [GameDev Agent] — 2025-12-07 05:02
+- Followed agent instructions and README setup. Attempted batch sweeps after dependency install; encountered 'No module named gengine' error. Next: Review runner script and PYTHONPATH, ensure src/gengine is discoverable, then rerun sweeps. Ready for test_agent handoff after successful run.
+
+## [GitHub Copilot] — 2025-12-06 14:50
+- Fixed YAML validation errors in `content/worlds/default/world.yml` (missing `goals` list for `dr-lyra-keel`).
+- Updated tests to reflect content changes:
+  - `tests/echoes/test_content_loader.py`: Updated expected counts for factions (3) and agents (4).
+  - `tests/echoes/test_story_seeds.py`: Updated expected followup seed ID.
+  - `tests/echoes/test_faction_system.py`: Isolated faction test state to prevent interference from the newly added `hollow_perimeter` faction.
+- Verified all tests pass with `uv run pytest -v`.
+- Note: Test coverage is at 87.46% (below 90% target), but all tests are passing.
+
+## [GitHub Copilot] — 2025-12-06 15:00
+- Refactored `tests/echoes/test_content_loader.py` to prevent future brittleness:
+  - Added `test_load_world_bundle_custom_content`: A new test using a temporary fixture to verify loader logic with controlled, minimal content.
+  - Updated `test_load_world_bundle_default_world`: Changed exact count assertions (==) to minimum count assertions (>=). This ensures the test verifies the default world is loaded and populated without breaking when new content is added.
+- Verified all tests pass with `uv run pytest tests/echoes/test_content_loader.py`.
+
+## [GitHub Copilot] — 2025-12-06 21:55
+- Improved test coverage for `src/gengine/balance_studio` package to >90%.
+- Created `tests/balance_studio/test_cli.py` (100% coverage).
+- Created `tests/balance_studio/test_workflows.py` (90% coverage).
+- Created `tests/balance_studio/test_overlays.py` (97% coverage).
+- Created `tests/balance_studio/test_report_viewer.py` (96% coverage).
+- Mocked external dependencies (subprocess, matplotlib, importlib) to ensure fast and reliable tests.
+
+## [GitHub Copilot] — 2025-12-06 21:57
+- Analyzed coverage report and identified `scripts/echoes_balance_studio.py` as having low coverage (26%).
+- Created new tests for interactive modes and command handlers in `tests/scripts/test_echoes_balance_studio.py`.
+- Mocked `input`, `print`, and workflow functions to test CLI logic without running simulations.
+- Verified all tests pass.
+- This should bring the overall coverage above 90%.

tests/balance_studio/test_cli.py

@@ -0,0 +1,75 @@
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from gengine.balance_studio.cli import main
+
+
+@pytest.fixture
+def mock_script_path(tmp_path):
+    """Create a dummy script file to simulate echoes_balance_studio.py."""
+    script_dir = tmp_path / "scripts"
+    script_dir.mkdir()
+    script_path = script_dir / "echoes_balance_studio.py"
+    script_path.touch()
+    return script_path
+
+
+def test_main_success(mock_script_path):
+    """Test that main successfully loads and runs the script."""
+    # Mock the module and its main function
+    mock_module = MagicMock()
+    mock_module.main.return_value = 0
+
+    # Mock importlib.util.spec_from_file_location
+    with patch("importlib.util.spec_from_file_location") as mock_spec_from_file:
+        # Setup the mock spec and loader
+        mock_spec = MagicMock()
+        mock_loader = MagicMock()
+        mock_spec.loader = mock_loader
+        mock_spec_from_file.return_value = mock_spec
+
+        # Mock importlib.util.module_from_spec
+        with patch("importlib.util.module_from_spec") as mock_module_from_spec:
+            mock_module_from_spec.return_value = mock_module
+
+            # We also need to patch Path to return our temp path structure
+            # specifically when resolving the script path
+            with patch("gengine.balance_studio.cli.Path") as mock_path_cls:
+                # Configure the mock path to point to our temp script
+                # The logic in cli.py is: Path(__file__).resolve().parents[3] / "scripts"
+                # We'll just mock the final result of that chain
+                mock_resolved_path = MagicMock()
+                mock_resolved_path.parents = [MagicMock(), MagicMock(), MagicMock(), MagicMock()]
+                # The 4th parent (index 3) is the root
+                mock_root = mock_resolved_path.parents[3]
+                mock_root.__truediv__.return_value = mock_script_path.parent
+                
+                # Mock Path(__file__).resolve()
+                mock_path_instance = MagicMock()
+                mock_path_instance.resolve.return_value = mock_resolved_path
+                mock_path_cls.return_value = mock_path_instance
+                
+                # Run main
+                result = main(["arg1", "arg2"])
+
+                # Verify results
+                assert result == 0
+                mock_module.main.assert_called_once_with(["arg1", "arg2"])
+                mock_spec.loader.exec_module.assert_called_once_with(mock_module)
+
+
+def test_main_script_not_found():
+    """Test that main handles failure to load the script."""
+    with patch("importlib.util.spec_from_file_location") as mock_spec_from_file:
+        mock_spec_from_file.return_value = None
+
+        # Capture stderr
+        with patch("sys.stderr") as mock_stderr:
+            result = main()
+
+            assert result == 1
+            mock_stderr.write.assert_called_once()
+            assert "Failed to load Balance Studio script" in mock_stderr.write.call_args[0][0]