@event4u/agent-config 5.7.0 → 5.9.0

package/scripts/install.py

@@ -58,6 +58,28 @@ SETTINGS_FILE = ".agent-settings.yml"
 LEGACY_SETTINGS_FILE = ".agent-settings"
 LEGACY_BACKUP_FILE = ".agent-settings.backup.key-value"
 
+# Canonical project settings live in the settings layer (agents/settings/),
+# not at the repo root (ADR-038). The repo-root .agent-settings.yml is a
+# back-compat read-fallback that install migrates into the canonical
+# location. Kept inline (no package import) — install.py runs standalone.
+SETTINGS_SUBDIR = ("agents", "settings")
+
+
+def _canonical_settings_target(project_root: Path) -> Path:
+    """Canonical write target: <root>/agents/settings/.agent-settings.yml."""
+    return project_root.joinpath(*SETTINGS_SUBDIR, SETTINGS_FILE)
+
+
+def _resolve_settings_read(project_root: Path) -> Path:
+    """Canonical if present, else legacy repo-root file if present, else canonical."""
+    canonical = _canonical_settings_target(project_root)
+    if canonical.exists():
+        return canonical
+    legacy = project_root / SETTINGS_FILE
+    if legacy.exists():
+        return legacy
+    return canonical
+
 # Maps legacy flat keys (.agent-settings, key=value) to the new dotted YAML
 # paths in .agent-settings.yml. Applied once during auto-migration.
 LEGACY_RENAME_MAP = {
@@ -567,7 +589,7 @@ def ensure_agent_settings(
     user_type: str = "",
     packs: "list[str] | None" = None,
 ) -> None:
-    target = project_root / SETTINGS_FILE
+    target = _canonical_settings_target(project_root)
     profile_source = package_root / "config" / "profiles" / f"{profile}.ini"
     template_source = package_root / "config" / "agent-settings.template.yml"
 
@@ -592,6 +614,17 @@ def ensure_agent_settings(
     template_body = _render_template(template, profile_values)
     template_body = _inject_packs(template_body, packs or [])
 
+    # ADR-038: relocate an existing repo-root .agent-settings.yml into the
+    # canonical agents/settings/ location, preserving the developer's content
+    # (never clobber an already-canonical file).
+    legacy_root = project_root / SETTINGS_FILE
+    if legacy_root.is_file() and not target.exists():
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(legacy_root.read_text(encoding="utf-8"), encoding="utf-8")
+        legacy_root.unlink()
+        success(f"Migrated {SETTINGS_FILE} → agents/settings/{SETTINGS_FILE} (ADR-038)")
+        return
+
     legacy_target = project_root / LEGACY_SETTINGS_FILE
     if legacy_target.is_file() and target.exists():
         warn(
@@ -611,6 +644,7 @@ def ensure_agent_settings(
         skip(f"{SETTINGS_FILE} already exists")
         return
 
+    target.parent.mkdir(parents=True, exist_ok=True)
     write_file(target, template_body)
     user_type_value = profile_values.get("user_type", "")
     suffix = f", user_type={user_type_value}" if user_type_value else ""
@@ -2128,6 +2162,41 @@ def _enforce_consumer_global_only(scope: str) -> None:
     )
 
 
+def _enforce_not_source_repo(scope: str, project_root: Path) -> None:
+    """Refuse a non-global install into the agent-config source repo.
+
+    Python-side mirror of the bash orchestrator's "Source-repo guard"
+    (``scripts/install``). The bash guard only covers the headless
+    ``init`` front door; the wizard reaches the apply engine directly via
+    ``install.py --apply-payload`` (and maintainers can call
+    ``python3 scripts/install.py``), so without this the GUI path could
+    write the ``.augment/`` / ``.claude/`` / ``.cursor/`` projection trees
+    back into the checkout. Both front doors converge on ``main()`` here, so
+    this is the single chokepoint that makes the floor uniform.
+
+    ``--global`` only writes user-scope paths and never the source tree, so
+    it is exempt. Unlike :func:`_enforce_consumer_global_only`, dev-mode does
+    NOT lift this guard — dogfooding bridges into the source tree is an
+    explicit action gated by its own ``AGENT_CONFIG_ALLOW_SELF_INSTALL=1``
+    override (same flag the bash guard honours).
+    """
+    if scope == "global":
+        return
+    if os.environ.get("AGENT_CONFIG_ALLOW_SELF_INSTALL") == "1":
+        return
+    is_source, signature = _is_agent_config_source_repo(project_root)
+    if not is_source:
+        return
+    fail(
+        "Refusing to install agent-config into its own source checkout "
+        f"(detected: {signature}). The source repo is global-only — a "
+        "project-scope install would recreate the .augment/ .claude/ .cursor/ "
+        "projection trees in the repo (double token cost). Run `task sync` to "
+        "regenerate them from .agent-src.uncondensed/ instead, or set "
+        "AGENT_CONFIG_ALLOW_SELF_INSTALL=1 to force."
+    )
+
+
 # --- road-to-global-only-install § Phase 2.2 — three-layer settings reader ---
 #
 # Merge order (per ADR-020 / D9):
@@ -2219,7 +2288,7 @@ def read_layered_settings(
     merged = _load_default_settings(package_root)
     merged = deep_merge(merged, _load_yaml_doc(GLOBAL_AGENT_SETTINGS_PATH))
     if project_root is not None:
-        project_file = project_root / SETTINGS_FILE
+        project_file = _resolve_settings_read(project_root)
         merged = deep_merge(merged, _load_yaml_doc(project_file))
     return merged
 
@@ -2354,7 +2423,7 @@ def detect_scope(cwd: Path) -> tuple[str, str]:
     ``.git/`` is explicitly NOT a signal — monorepos, dotfile managers,
     and non-Git workspaces all break it. Pure function; no side effects.
     """
-    if (cwd / SETTINGS_FILE).exists():
+    if _resolve_settings_read(cwd).exists():
         return "project", f"existing {SETTINGS_FILE}"
 
     has_manifest = next(
@@ -3524,7 +3593,7 @@ def install_global(
     # `.agent-settings.yml` and the manifest would be untracked noise.
     if (
         project_root is not None
-        and (project_root / SETTINGS_FILE).exists()
+        and _resolve_settings_read(project_root).exists()
         and not (project_root / ".agent-src.uncondensed").is_dir()
     ):
         # Collect deployed/marker paths per tool so the manifest records
@@ -3989,7 +4058,7 @@ def install_minimal(target_root: Path, force: bool, user_type: str = "") -> int:
     # the source of truth per ADR-020 § D2; a fresh `--minimal` run
     # without user_type does not write a project-local settings file.
     if user_type:
-        settings_dst = target_root / SETTINGS_FILE
+        settings_dst = _canonical_settings_target(target_root)
         if settings_dst.exists() and not force:
             skip(f"{SETTINGS_FILE} already exists (use --force to overwrite)")
         else:
@@ -3998,6 +4067,7 @@ def install_minimal(target_root: Path, force: bool, user_type: str = "") -> int:
                 "personal:\n"
                 f"  user_type: {user_type}\n"
             )
+            settings_dst.parent.mkdir(parents=True, exist_ok=True)
             settings_dst.write_text(body, encoding="utf-8")
             success(f"Wrote {SETTINGS_FILE} (user_type={user_type})")
 
@@ -4657,6 +4727,7 @@ def main(argv: list[str]) -> int:
     custom_path: Path | None = Path(opts.custom_path).resolve() if opts.custom_path else None
     scope = _resolve_scope(opts, detected, detect_reason, custom_path)
     _enforce_consumer_global_only(scope)
+    _enforce_not_source_repo(scope, detect_root)
 
     # Scope validation runs before filesystem / package detection so
     # --tools=X / --scope conflicts fail fast with a directive error

package/scripts/inventory_abstraction_budget.py

@@ -45,7 +45,12 @@ try:
 except ImportError:
     script_output = None  # graceful fallback when running outside repo
 
-CORE_SRC = REPO_ROOT / "packages" / "core" / ".agent-src.uncondensed"
+from _lib.agent_src import resolve_package_core_path  # noqa: E402
+
+CORE_SRC = resolve_package_core_path(".agent-src.uncondensed")
+# Enforced packages/core targets — read by scripts/check_gate_paths.py so a
+# future move that desyncs this path fails CI instead of silently no-opping.
+GATE_CORE_PATHS = (CORE_SRC,)
 DIRECTIVES_ROOT = CORE_SRC / "templates" / "scripts" / "work_engine" / "directives"
 EVIDENCE_DIR = REPO_ROOT / "agents" / "evidence" / "analysis"
 

package/scripts/lint_agents_md.py

@@ -23,8 +23,18 @@ from dataclasses import dataclass
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / "scripts"))
+from _lib.agent_src import resolve_package_core_path  # noqa: E402
+
 QUIET = "--quiet" in sys.argv
 
+_CONSUMER_TEMPLATE = resolve_package_core_path(".agent-src.uncondensed/templates/AGENTS.md")
+# Enforced packages/core target — read by scripts/check_gate_paths.py so a
+# future move that desyncs this path fails CI instead of silently no-opping.
+# Only the consumer-template lives under packages/core; the package-root
+# AGENTS.md sits at the repo root and is intentionally excluded.
+GATE_CORE_PATHS = (_CONSUMER_TEMPLATE,)
+
 LINK_RE = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
 PATH_BACKTICK_RE = re.compile(r"`[^`]*/[^`]*`")
 BULLET_RE = re.compile(r"^\s*[-*+]\s+")
@@ -64,10 +74,7 @@ class Target:
 
 TARGETS = [
     Target(ROOT / "AGENTS.md", "package-root", 3000, 2800, template=False),
-    Target(
-        ROOT / "packages" / "core" / ".agent-src.uncondensed" / "templates" / "AGENTS.md",
-        "consumer-template", 2500, 2300, template=True,
-    ),
+    Target(_CONSUMER_TEMPLATE, "consumer-template", 2500, 2300, template=True),
 ]
 
 

package/scripts/lint_hook_concern_budget.py

@@ -49,10 +49,14 @@ import argparse
 import re
 import sys
 from pathlib import Path
+try:  # invocation-agnostic import (repo-root-on-path vs scripts-on-path)
+    from scripts._lib.agent_settings import project_settings_path
+except ModuleNotFoundError:  # pragma: no cover
+    from _lib.agent_settings import project_settings_path
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 DEFAULT_MANIFEST = REPO_ROOT / "scripts" / "hook_manifest.yaml"
-DEFAULT_SETTINGS = REPO_ROOT / ".agent-settings.yml"
+DEFAULT_SETTINGS = project_settings_path(REPO_ROOT)
 
 DEFAULT_MAX_PER_EVENT = 8
 DEFAULT_TIER1: list[str] = []

package/scripts/lint_marketplace.py

@@ -25,7 +25,14 @@ from pathlib import Path
 ROOT = Path(".")
 MARKETPLACE = ROOT / ".claude-plugin" / "marketplace.json"
 PACKAGE_JSON = ROOT / "package.json"
-CLAUDE_SKILLS_DIR = ROOT / ".claude" / "skills"
+# Committed marketplace skill sources (git-consumed): real skills resolve to
+# .agent-src/skills/<name>; command-as-skill entries to the committed
+# .claude-plugin/skills/<slug> projection. .claude/skills/ is a gitignored
+# local channel and is intentionally NOT a marketplace source.
+SKILL_SOURCE_DIRS = (
+    ROOT / ".agent-src" / "skills",
+    ROOT / ".claude-plugin" / "skills",
+)
 
 
 def fail(errors: list[str]) -> int:
@@ -124,9 +131,10 @@ def main() -> int:
             if not skill_md.exists():
                 errors.append(f"{entry} has no SKILL.md: `{path}`")
 
-    # Reverse-completeness: every SKILL.md on disk under .claude/skills/
-    # must appear in some plugin's skills[]. Catches the drift where new
-    # skills are generated but never added to the marketplace manifest.
+    # Reverse-completeness: every SKILL.md on disk under the committed skill
+    # sources (.agent-src/skills/ + .claude-plugin/skills/) must appear in some
+    # plugin's skills[]. Catches the drift where new skills/commands are
+    # generated but never added to the marketplace manifest.
     listed: set[str] = set()
     for plugin in plugins:
         if not isinstance(plugin, dict):
@@ -135,13 +143,16 @@ def main() -> int:
             if isinstance(path, str):
                 listed.add(path.removeprefix("./"))
 
-    if CLAUDE_SKILLS_DIR.exists():
-        for skill_dir in sorted(CLAUDE_SKILLS_DIR.iterdir()):
+    for source_dir in SKILL_SOURCE_DIRS:
+        if not source_dir.exists():
+            continue
+        prefix = source_dir.relative_to(ROOT).as_posix()
+        for skill_dir in sorted(source_dir.iterdir()):
             if not skill_dir.is_dir():
                 continue
             if not (skill_dir / "SKILL.md").exists():
                 continue
-            rel = f".claude/skills/{skill_dir.name}"
+            rel = f"{prefix}/{skill_dir.name}"
             if rel not in listed:
                 errors.append(
                     f"skill exists on disk but is not listed in marketplace.json: "

package/scripts/lint_roadmap_ci_steps.py

@@ -22,12 +22,16 @@ from __future__ import annotations
 import re
 import sys
 from pathlib import Path
+try:  # invocation-agnostic import (repo-root-on-path vs scripts-on-path)
+    from scripts._lib.agent_settings import project_settings_path
+except ModuleNotFoundError:  # pragma: no cover
+    from _lib.agent_settings import project_settings_path
 
 QUIET = "--quiet" in sys.argv
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 ROADMAP_GLOB = "agents/roadmaps/*.md"
-SETTINGS_FILE = REPO_ROOT / ".agent-settings.yml"
+SETTINGS_FILE = project_settings_path(REPO_ROOT)
 LOCAL_AUTO_RUN_PAT = re.compile(
     r"^\s*local_auto_run:\s*(true|false)\s*(?:#.*)?$", re.MULTILINE
 )

package/scripts/lint_roadmap_complexity.py

@@ -23,6 +23,10 @@ from __future__ import annotations
 import re
 import sys
 from pathlib import Path
+try:  # invocation-agnostic import (repo-root-on-path vs scripts-on-path)
+    from scripts._lib.agent_settings import project_settings_path
+except ModuleNotFoundError:  # pragma: no cover
+    from _lib.agent_settings import project_settings_path
 
 QUIET = "--quiet" in sys.argv
 
@@ -30,7 +34,7 @@ REPO_ROOT = Path(__file__).resolve().parent.parent
 ROADMAP_GLOB = "agents/roadmaps/*.md"
 LIGHTWEIGHT_LINE_CAP = 600
 LIGHTWEIGHT_PHASE_CAP = 6
-SETTINGS_FILE = REPO_ROOT / ".agent-settings.yml"
+SETTINGS_FILE = project_settings_path(REPO_ROOT)
 HORIZON_WEEKS_PAT = re.compile(
     r"^\s*horizon_weeks:\s*(\d+)\s*(?:#.*)?$", re.MULTILINE
 )

package/scripts/mcp_server/prompts.py

@@ -21,6 +21,10 @@ from __future__ import annotations
 import dataclasses
 from dataclasses import dataclass, field
 from pathlib import Path
+try:  # invocation-agnostic import (repo-root-on-path vs scripts-on-path)
+    from scripts._lib.agent_settings import project_settings_path
+except ModuleNotFoundError:  # pragma: no cover
+    from _lib.agent_settings import project_settings_path
 from typing import Any, Literal
 
 # Phase 1 hand-picked skills — kept for the Phase-1 entrypoint
@@ -128,7 +132,7 @@ def _load_active_user_type(root: Path) -> str:
     the loader (consistent with `_strip_frontmatter`). Only matches
     `user_type:` directly under the top-level `personal:` block.
     """
-    settings = root / ".agent-settings.yml"
+    settings = project_settings_path(root)
     if not settings.is_file():
         return ""
     try:

package/scripts/prediction-pool/pool_winsim.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+"""Field model + P(finish 1st) simulator for prediction-pool-optimizer.
+
+Honest operationalisation of the large-pool strategy note: in a big pool the
+target is **P(finish ahead of the whole field)**, not E(points). Maximizing EV
+makes your tip-set converge with everyone else's EV-max set, so you cannot open
+the gap you need. This script measures that — and greedily finds the few tips
+worth flipping off EV-max to manufacture upside.
+
+What it does:
+
+  1. Models the FIELD: each opponent commits one tip per match, drawn from a
+     softmax over the per-match EV table (temperature controls spread — low =
+     the crowd clusters tightly on EV-max, high = noisy). This is a model of
+     the crowd, stated as such; feed a real field distribution if you have one.
+  2. Pre-draws R outcome scenarios from the Poisson grids and pre-scores every
+     opponent once, so evaluating any of MY tip-sets is cheap.
+  3. Reports P(win) for the EV-max-everywhere baseline, then runs a greedy
+     flip search: repeatedly flip the single tip that most raises P(win),
+     reporting the EV cost and the P(win) gain per flip, up to --max-flips.
+
+The lesson it makes concrete: with small N the EV-max set already wins often
+and flips do not help (don't add variance you don't need); with large N and a
+deficit, a handful of calculated flips can lift P(win) materially at a small
+EV cost. The crossover is empirical — run it.
+
+It is an APPROXIMATION: the field is a softmax-EV model, not your real pool's
+tips, and the Poisson grids are only as good as the lambdas you feed (de-vigged
+consensus odds — see reference/odds-and-bonus.md). Outcomes and EV are exact
+for that model; the field shape is a prior.
+
+Input JSON:
+{
+  "rule": {"exact": 5, "diff": 3, "tendency": 2},
+  "participants": 120,            # field size N; opponents modelled = N-1 (capped by --max-opponents)
+  "my_lead": 0,                   # my current points minus the rival-to-beat's (negative = behind)
+  "field_temperature": 0.6,       # softmax temp for crowd spread around EV-max
+  "matches": [
+    {"match": "A", "lh": 2.0, "la": 0.7},
+    {"match": "B", "lh": 0.6, "la": 2.1}
+  ]
+}
+
+Usage:
+  python3 scripts/prediction-pool/pool_winsim.py pool.json --runs 4000 --max-flips 4 [--seed 1]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import random
+import sys
+from pathlib import Path
+
+# Reuse the exact-score engine.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from score_ev import ev_table, grid, _score  # noqa: E402
+
+
+def _parse_tip(s: str) -> tuple[int, int]:
+    h, a = s.split(":")
+    return int(h), int(a)
+
+
+def _flat_grid(g):
+    """Flatten a joint grid into (prob, (h,a)) pairs for sampling."""
+    flat = []
+    for h in range(len(g)):
+        for a in range(len(g[h])):
+            p = g[h][a]
+            if p > 0:
+                flat.append((p, (h, a)))
+    return flat
+
+
+def _sample_outcome(flat, rng: random.Random) -> tuple[int, int]:
+    r = rng.random()
+    acc = 0.0
+    for p, ha in flat:
+        acc += p
+        if r <= acc:
+            return ha
+    return flat[-1][1]
+
+
+def _softmax_pick(rows, temperature: float, rng: random.Random) -> tuple[int, int]:
+    """Pick a tip (h,a) from EV rows via softmax(EV / temperature)."""
+    if temperature <= 0:
+        h, a, _ = rows[0]
+        return h, a
+    top = rows[:24]  # the tail has negligible mass; cap for speed
+    mx = top[0][2]
+    weights = [math.exp((ev - mx) / temperature) for _, _, ev in top]
+    tot = sum(weights)
+    r = rng.random() * tot
+    acc = 0.0
+    for (h, a, _), w in zip(top, weights):
+        acc += w
+        if r <= acc:
+            return h, a
+    h, a, _ = top[-1]
+    return h, a
+
+
+def run(cfg: dict, runs: int, max_flips: int, max_opponents: int, top_flip: int,
+        seed: int):
+    rng = random.Random(seed)
+    rule = cfg.get("rule", {"exact": 4, "diff": 3, "tendency": 2})
+    pe, pd, pt = float(rule["exact"]), float(rule["diff"]), float(rule["tendency"])
+    n = int(cfg.get("participants", 20))
+    my_lead = float(cfg.get("my_lead", 0))
+    temp = float(cfg.get("field_temperature", 0.6))
+    matches = cfg["matches"]
+    n_opp = max(0, min(n - 1, max_opponents))
+
+    # Per match: EV table + sampling grid.
+    per = []
+    for m in matches:
+        rows, _ = ev_table(m["lh"], m["la"], pe, pd, pt, max_tip=6)
+        g = grid(m["lh"], m["la"])
+        per.append({"name": m.get("match", "?"), "rows": rows, "flat": _flat_grid(g)})
+
+    # Pre-draw R outcome scenarios (one actual scoreline per match per run).
+    scenarios = [[_sample_outcome(p["flat"], rng) for p in per] for _ in range(runs)]
+
+    # Model the field: each opponent commits a fixed tip per match (softmax-EV),
+    # then score each opponent across all scenarios. Keep the per-scenario field
+    # MAX so any of my tip-sets can be evaluated against it cheaply.
+    field_max = [(-1e9) for _ in range(runs)]
+    for _ in range(n_opp):
+        opp_tips = [_softmax_pick(p["rows"], temp, rng) for p in per]
+        for s_idx, sc in enumerate(scenarios):
+            tot = 0.0
+            for (th, ta), (ah, aa) in zip(opp_tips, sc):
+                tot += _score(th, ta, ah, aa, pe, pd, pt)
+            if tot > field_max[s_idx]:
+                field_max[s_idx] = tot
+
+    def my_total(tipset, s_idx):
+        sc = scenarios[s_idx]
+        tot = 0.0
+        for (th, ta), (ah, aa) in zip(tipset, sc):
+            tot += _score(th, ta, ah, aa, pe, pd, pt)
+        return tot
+
+    def p_win(tipset):
+        wins = 0
+        for s_idx in range(runs):
+            if my_total(tipset, s_idx) + my_lead > field_max[s_idx]:
+                wins += 1
+        return wins / runs
+
+    # Baseline: EV-max on every match.
+    ev_max_set = [(p["rows"][0][0], p["rows"][0][1]) for p in per]
+    base_pwin = p_win(ev_max_set)
+
+    # Greedy flips: repeatedly flip the one tip that most raises P(win),
+    # considering each match's top-`top_flip` EV candidates.
+    current = list(ev_max_set)
+    flips = []
+    used = set()
+    for _ in range(max_flips):
+        best = None
+        for mi, p in enumerate(per):
+            if mi in used:
+                continue
+            for h, a, ev in p["rows"][:top_flip]:
+                if (h, a) == current[mi]:
+                    continue
+                trial = list(current)
+                trial[mi] = (h, a)
+                pw = p_win(trial)
+                ev_cost = p["rows"][0][2] - ev
+                if best is None or pw > best["pwin"]:
+                    best = {"mi": mi, "tip": (h, a), "pwin": pw, "ev_cost": ev_cost,
+                            "name": p["name"]}
+        if best is None or best["pwin"] <= (flips[-1]["pwin"] if flips else base_pwin):
+            break
+        current[best["mi"]] = best["tip"]
+        used.add(best["mi"])
+        flips.append(best)
+
+    return {
+        "participants": n, "opponents_modelled": n_opp, "runs": runs,
+        "my_lead": my_lead, "field_temperature": temp,
+        "rule": {"exact": pe, "diff": pd, "tendency": pt},
+        "ev_max_set": [f"{per[i]['name']}={h}:{a}" for i, (h, a) in enumerate(ev_max_set)],
+        "p_win_ev_max": round(base_pwin, 4),
+        "flips": [
+            {"match": f["name"], "to": f"{f['tip'][0]}:{f['tip'][1]}",
+             "ev_cost": round(f["ev_cost"], 3), "p_win_after": round(f["pwin"], 4)}
+            for f in flips
+        ],
+        "p_win_after_flips": round((flips[-1]["pwin"] if flips else base_pwin), 4),
+    }
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Field model + P(win) simulator.")
+    ap.add_argument("config", help="JSON config (rule, participants, my_lead, matches)")
+    ap.add_argument("--runs", type=int, default=4000, help="outcome scenarios (default 4000)")
+    ap.add_argument("--max-flips", type=int, default=4, help="max tips to flip off EV-max")
+    ap.add_argument("--max-opponents", type=int, default=300,
+                    help="cap opponents modelled (default 300)")
+    ap.add_argument("--top-flip", type=int, default=4,
+                    help="EV candidates per match to consider when flipping")
+    ap.add_argument("--seed", type=int, default=1)
+    ap.add_argument("--json", action="store_true", help="emit JSON instead of text")
+    args = ap.parse_args(argv)
+
+    cfg = json.loads(Path(args.config).read_text())
+    res = run(cfg, args.runs, args.max_flips, args.max_opponents, args.top_flip, args.seed)
+
+    if args.json:
+        print(json.dumps(res, indent=2))
+        return 0
+
+    print(f"participants {res['participants']} (modelled {res['opponents_modelled']})  "
+          f"runs {res['runs']}  my_lead {res['my_lead']}  field_temp {res['field_temperature']}")
+    print(f"EV-max set: {', '.join(res['ev_max_set'])}")
+    print(f"P(win) all-EV-max : {res['p_win_ev_max']:.4f}")
+    if not res["flips"]:
+        print("greedy flips: none improved P(win) — EV-max is already best (small/easy field).")
+    else:
+        print("suggested flips (greedy, each raises P(win) most):")
+        for f in res["flips"]:
+            print(f"  flip {f['match']} -> {f['to']}  (EV cost {f['ev_cost']:+.3f})  "
+                  f"P(win) {f['p_win_after']:.4f}")
+        print(f"P(win) after flips: {res['p_win_after_flips']:.4f}  "
+              f"(+{res['p_win_after_flips'] - res['p_win_ev_max']:.4f})")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())