Initial PuGa toolkit: data layer, econ, depth-aware scan, state sync, plan push

- puga/: cached FIO + PRUNplanner clients, market view with order-book walk,
  econ formulas ported from PRUNplanner (tested against its suite and live FIO),
  saturation model v1 (reviewed by Opus)
- tools/: scan (depth-aware), price, book, chain, state sync, plan_push
  (dry run default, [PuGa]-prefixed plans only), legacy prun_scan/prun_cxarb
- docs/: mechanics (PRUNplanner is source of truth), roadmap, decisions,
  saturation design, archived handoff
- secrets stay in .env (gitignored); ref/ holds PRUNplanner source (ignored)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

tests/test_plan_push.py

@@ -0,0 +1,36 @@
+import importlib.util, sys
+from pathlib import Path
+import pytest
+
+spec = importlib.util.spec_from_file_location("plan_push", Path(__file__).resolve().parent.parent / "tools" / "plan_push.py")
+pp_tool = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(pp_tool)
+
+R = [
+    {"recipe_id": "SME#6xALO 1xO 1xC=>3xAL", "building_ticker": "SME", "inputs": [{"material_ticker": t} for t in ("ALO", "O", "C")], "outputs": [{"material_ticker": "AL"}]},
+    {"recipe_id": "SME#6xALO 1xO 1xC 1xFLX=>4xAL", "building_ticker": "SME", "inputs": [{"material_ticker": t} for t in ("ALO", "O", "C", "FLX")], "outputs": [{"material_ticker": "AL"}]},
+]
+
+
+def test_resolve_by_ticker_sets_distinguishes_flux():
+    assert pp_tool.resolve_recipe("ALO,FLX,C,O=>AL", "SME", R).endswith("=>4xAL")
+    assert pp_tool.resolve_recipe("ALO,C,O=>AL", "SME", R).endswith("=>3xAL")
+    assert pp_tool.resolve_recipe("EXT#ALO", "EXT", R) == "EXT#ALO"
+    with pytest.raises(ValueError):
+        pp_tool.resolve_recipe("ALO=>AL", "SME", R)
+
+
+def _spec(**kw):
+    s = dict(name="[PuGa] x", planet="ZV-759c", permits=1, cogc="METALLURGY", buildings=[{"building": "SME", "amount": 1, "recipes": ["ALO,C,O=>AL"]}])
+    s.update(kw)
+    return s
+
+
+def test_guardrail_requires_prefix_and_validates():
+    ok = pp_tool.build_payload(_spec(), R, {"SME"})
+    assert ok["plan_cogc"] == "METALLURGY" and len(ok["plan_data"]["experts"]) == 9 and len(ok["plan_data"]["workforce"]) == 5
+    for bad in (dict(name="My plan"), dict(planet="ZV759c"), dict(permits=4), dict(cogc="FOO")):
+        with pytest.raises(ValueError):
+            pp_tool.build_payload(_spec(**bad), R, {"SME"})
+    with pytest.raises(ValueError):
+        pp_tool.build_payload(_spec(buildings=[{"building": "ZZZ", "amount": 1}]), R, {"SME"})