@heretek-ai/epistemic-swarm 0.7.13 → 0.7.15

package/runner/mcp_server.py

@@ -150,6 +150,8 @@ def _run_swarm_mode(mode: Optional[str], args: Dict[str, Any]) -> str:
         depth=args.get("depth"),
         domain_pack=args.get("domain_pack"),
         agent_overrides=overrides,
+        resume=bool(args.get("resume")),
+        dry_run=bool(args.get("dry_run")),
     )
     buf = io.StringIO()
     with redirect_stdout(buf):
@@ -209,9 +211,9 @@ def _handle_factory(args: Dict[str, Any]) -> str:
     import subprocess
 
     command = str(args.get("command") or "").strip()
-    if command not in ("init", "phase-add", "qa-record", "expansion", "stop"):
+    if command not in ("init", "phase-add", "qa-record", "expansion", "stop", "gate"):
         raise ValueError(
-            "command must be one of: init, phase-add, qa-record, expansion, stop"
+            "command must be one of: init, phase-add, qa-record, expansion, stop, gate"
         )
     script = Path(PROJECT_ROOT) / "skills" / "factory" / "scripts" / "factory.py"
     if not script.is_file():
@@ -412,20 +414,95 @@ def _handle_reindex_claims(args: Dict[str, Any]) -> str:
     return _tool_text(reindex(base_dir))
 
 
+def _handle_doctor(args: Dict[str, Any]) -> str:
+    """Preflight for the resolved workspace: backend, engine, write test, version."""
+    from runner.preflight import format_report, preflight
+    from skills.swarm_config.configure import load_config
+
+    base_dir = _resolve_base_dir(args)
+    cfg = load_config(str(base_dir))
+    report = preflight(
+        base_dir,
+        mode=args.get("mode") or cfg.get("mode") or "research",
+        config=cfg,
+        # Never spawn in a health check; report resolution only.
+        mock_mode=True,
+        probe=bool(args.get("probe", True)),
+    )
+    return _tool_text({"report": report, "text": format_report(report)})
+
+
+def _handle_test(args: Dict[str, Any]) -> str:
+    """Run the packaged test suite in a subprocess (timeout-bounded)."""
+    import subprocess
+
+    timeout = float(os.environ.get("IUMBTEMS_TEST_TIMEOUT", "300"))
+    try:
+        result = subprocess.run(
+            [sys.executable, "-m", "unittest", "discover", "-s", "runner/tests"],
+            cwd=str(PROJECT_ROOT),
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            stdin=subprocess.DEVNULL,
+        )
+    except subprocess.TimeoutExpired:
+        return _tool_text({"status": "timeout", "timeout_s": timeout})
+    tail = "\n".join((result.stderr or "").strip().splitlines()[-12:])
+    passed = result.returncode == 0
+    return _tool_text(
+        {
+            "status": "pass" if passed else "fail",
+            "returncode": result.returncode,
+            "tail": tail,
+        }
+    )
+
+
 def _handle_socratic_frontier(args: Dict[str, Any]) -> str:
-    """Advance or inspect the Socratic decision-tree frontier."""
-    from skills.grilling.socratic_tree import DesignTree
+    """Inspect, add to, settle, or export the Socratic decision-tree frontier."""
+    from skills.grilling.socratic_tree import DecisionNode, DesignTree
 
     file_path = Path(
         args.get("file") or args.get("frontier_file") or ".research/frontier.json"
     )
+    action = str(args.get("action") or "").strip().lower()
+    node_spec = args.get("node") if isinstance(args.get("node"), dict) else {}
+
+    def _tree():
+        if file_path.exists():
+            return DesignTree.load_from_json(file_path)
+        return DesignTree(objective=args.get("objective", ""))
+
+    # Authoring: add a node (tool-drivable, previously hand-written JSON only).
+    if action == "add" or node_spec:
+        if not node_spec.get("id") or not node_spec.get("question"):
+            return _tool_text(
+                {"status": "error", "message": "'node' needs 'id' and 'question'"}
+            )
+        tree = _tree()
+        tree.add_node(
+            DecisionNode(
+                node_id=node_spec["id"],
+                title=node_spec.get("title") or node_spec["id"],
+                question=node_spec["question"],
+                recommended=node_spec.get("recommended", ""),
+                options=node_spec.get("options") or [],
+                prerequisites=node_spec.get("depends_on") or [],
+            )
+        )
+        tree.export_frontier_json(file_path)
+        return _tool_text(
+            {"status": "added", "node_id": node_spec["id"], "file": str(file_path)}
+        )
+
+    if action == "export":
+        _tree().export_frontier_json(file_path)
+        return _tool_text({"status": "exported", "file": str(file_path)})
 
     if args.get("settle"):
         node_id, answer = args["settle"][0], args["settle"][1]
-        if file_path.exists():
-            tree = DesignTree.load_from_json(file_path)
-        else:
-            tree = DesignTree(objective=args.get("objective", ""))
+        tree = _tree()
         tree.settle_node(node_id, answer)
         tree.export_frontier_json(file_path)
         return _tool_text(
@@ -545,6 +622,10 @@ def build_tools() -> List[ToolSpec]:
                         "description": "Codebase target or audit focus",
                     },
                     "base_dir": {"type": "string"},
+                    "frontier_file": {
+                        "type": "string",
+                        "description": "Settled frontier.json from /grilling",
+                    },
                     "mock_claude": {"type": "boolean"},
                     "backend": {
                         "type": "string",
@@ -566,6 +647,10 @@ def build_tools() -> List[ToolSpec]:
                         "description": "Feature or library to scout",
                     },
                     "base_dir": {"type": "string"},
+                    "frontier_file": {
+                        "type": "string",
+                        "description": "Settled frontier.json from /grilling",
+                    },
                     "mock_claude": {"type": "boolean"},
                     "backend": {
                         "type": "string",
@@ -587,6 +672,10 @@ def build_tools() -> List[ToolSpec]:
                         "description": "Ambiguous prompt to ideate on",
                     },
                     "base_dir": {"type": "string"},
+                    "frontier_file": {
+                        "type": "string",
+                        "description": "Settled frontier.json from /grilling",
+                    },
                     "mock_claude": {"type": "boolean"},
                     "backend": {
                         "type": "string",
@@ -618,6 +707,10 @@ def build_tools() -> List[ToolSpec]:
                     },
                     "depth": {"type": "integer", "description": "Dialectic depth 1-4"},
                     "base_dir": {"type": "string"},
+                    "frontier_file": {
+                        "type": "string",
+                        "description": "Settled frontier.json from /grilling",
+                    },
                     "mock_claude": {"type": "boolean"},
                     "backend": {
                         "type": "string",
@@ -801,6 +894,15 @@ def build_tools() -> List[ToolSpec]:
                 "properties": {
                     "file": {"type": "string", "description": "Path to frontier.json"},
                     "objective": {"type": "string"},
+                    "action": {
+                        "type": "string",
+                        "enum": ["inspect", "add", "settle", "export"],
+                        "description": "inspect (default) | add a node | settle a node | export the file",
+                    },
+                    "node": {
+                        "type": "object",
+                        "description": "Node to add: {id, question, title?, recommended?, depends_on?[]}",
+                    },
                     "settle": {
                         "type": "array",
                         "items": {"type": "string"},
@@ -810,6 +912,28 @@ def build_tools() -> List[ToolSpec]:
             },
             handler=_handle_socratic_frontier,
         ),
+        ToolSpec(
+            name="iumbtems_doctor",
+            description="Preflight health check for the resolved workspace: plugin version, backend binary, search-engine reachability, and workspace writability. Run this first when anything looks wrong.",
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "base_dir": {"type": "string"},
+                    "mode": {"type": "string"},
+                    "probe": {
+                        "type": "boolean",
+                        "description": "Run a live 1-query search probe (default true)",
+                    },
+                },
+            },
+            handler=_handle_doctor,
+        ),
+        ToolSpec(
+            name="iumbtems_test",
+            description="Run the packaged IUMBTEMS test suite (subprocess, timeout-bounded) and report pass/fail with the tail of the output.",
+            input_schema={"type": "object", "properties": {}},
+            handler=_handle_test,
+        ),
     ]
 
 

package/runner/preflight.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""Preflight / doctor report for a run (Heretek-AI/IUMBTEMS#6 item 3.2).
+
+The plugin knows things the agent currently has to rediscover: which workspace
+resolves, which manifest filename is in play, which backend binary will actually
+spawn, and whether the search engine works right now. This reports all of it in
+one place, prints it at run start, records it in the manifest, and backs the
+`iumbtems_doctor` MCP tool.
+
+Everything here is best-effort and offline-safe: the search probe is
+timeout-bounded and can be skipped, and no failure raises.
+"""
+
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+
+DEFAULT_PROBE_QUERY = "iumbtems preflight probe"
+
+
+def plugin_version() -> Optional[str]:
+    try:
+        return json.loads(
+            (PROJECT_ROOT / "package.json").read_text(encoding="utf-8")
+        ).get("version")
+    except (OSError, ValueError):
+        return None
+
+
+_plugin_version = plugin_version  # backwards-compatible alias
+
+
+def _backend_report(base_dir: Path, mock_mode: bool) -> Dict[str, Any]:
+    try:
+        from runner.research_swarm import (
+            SwarmRunner,  # noqa: F401  (ensures module import side effects)
+            _default_backend_cmd,
+            _opencode_auto,
+        )
+
+        runner = SwarmRunner(base_dir=base_dir, mock_mode=mock_mode, mode="research")
+        backend, model = runner._resolve_agent_backend("alpha")
+        family = backend[0] if backend else "?"
+        resolved = shutil.which(family) or family
+        return {
+            "family": family,
+            "argv": backend,
+            "model": model,
+            "binary": resolved,
+            "binary_found": bool(shutil.which(family)),
+            "opencode_auto": _opencode_auto(runner.config),
+            "default_auto": _default_backend_cmd("auto"),
+        }
+    except Exception as exc:  # noqa: BLE001 - doctor must never raise
+        return {"error": str(exc)}
+
+
+def _engine_probe(engine: str, probe: bool, timeout: float) -> Dict[str, Any]:
+    if not probe:
+        return {"skipped": "probe disabled"}
+    if engine != "duckduckgo":
+        return {"skipped": f"no zero-key probe for engine '{engine}'"}
+    try:
+        sys.path.insert(
+            0, str(PROJECT_ROOT / "skills" / "epistemic_search" / "scripts")
+        )
+        import search  # noqa: PLC0415
+
+        results = search.search_duckduckgo(DEFAULT_PROBE_QUERY, max_results=3)
+        return {"ok": bool(results), "results": len(results)}
+    except Exception as exc:  # noqa: BLE001 - network/offline is not an error
+        return {"ok": False, "error": str(exc)}
+
+
+def _scratchpad_write_test(base_dir: Path) -> Dict[str, Any]:
+    try:
+        base_dir.mkdir(parents=True, exist_ok=True)
+        probe = base_dir / ".preflight-write-test"
+        probe.write_text("ok", encoding="utf-8")
+        probe.unlink()
+        return {"ok": True, "path": str(base_dir)}
+    except OSError as exc:
+        return {"ok": False, "path": str(base_dir), "error": str(exc)}
+
+
+def preflight(
+    base_dir: Path,
+    mode: str = "research",
+    config: Optional[Dict[str, Any]] = None,
+    mock_mode: bool = False,
+    probe: bool = True,
+    timeout: float = 5.0,
+) -> Dict[str, Any]:
+    """Assemble the preflight report. Never raises."""
+    config = config or {}
+    engine = str(config.get("search_engine") or "duckduckgo")
+    report: Dict[str, Any] = {
+        "plugin_version": _plugin_version(),
+        "python": sys.version.split()[0],
+        "node": shutil.which("node") or None,
+        "mode": mode,
+        "workspace": str(base_dir),
+        "manifest": None,
+        "project_dir": os.environ.get("IUMBTEMS_PROJECT_DIR") or None,
+        "cwd": os.getcwd(),
+        "pwd": os.environ.get("PWD") or None,
+        "engine": engine,
+        "warnings": [],
+    }
+    try:
+        from runner.state_machine import manifest_name_for_mode
+
+        report["manifest"] = manifest_name_for_mode(mode)
+    except Exception:  # noqa: BLE001
+        pass
+
+    report["backend"] = _backend_report(base_dir, mock_mode)
+    report["engine_probe"] = _engine_probe(engine, probe, timeout)
+    report["workspace_write"] = _scratchpad_write_test(base_dir)
+
+    if report["backend"].get("binary_found") is False and not mock_mode:
+        report["warnings"].append(
+            f"backend binary '{report['backend'].get('family')}' not found on PATH"
+        )
+    if report["engine_probe"].get("ok") is False:
+        report["warnings"].append("search engine probe returned no results")
+    if report["workspace_write"].get("ok") is False:
+        report["warnings"].append("workspace is not writable")
+    return report
+
+
+def format_report(report: Dict[str, Any]) -> str:
+    backend = report.get("backend", {})
+    probe = report.get("engine_probe", {})
+    probe_txt = (
+        f"{probe.get('results')} results"
+        if probe.get("ok")
+        else probe.get("skipped") or f"FAILED ({probe.get('error', '?')})"
+    )
+    lines = [
+        f"iumbtems preflight: v{report.get('plugin_version')} | mode={report.get('mode')}",
+        f"  workspace : {report.get('workspace')} | manifest: {report.get('manifest')}",
+        f"  spawn cwd : {report.get('cwd')} | PWD: {report.get('pwd')}",
+        f"  backend   : {backend.get('family')} ({backend.get('binary')})"
+        f"{'' if backend.get('binary_found') else '  ⚠️ NOT FOUND'}"
+        f"{' | --auto' if backend.get('opencode_auto') else ''}",
+        f"  engine    : {report.get('engine')} -> {probe_txt}",
+        f"  write test: {'ok' if report.get('workspace_write', {}).get('ok') else 'FAILED'}",
+    ]
+    for warning in report.get("warnings", []):
+        lines.append(f"  ⚠️ {warning}")
+    return "\n".join(lines)

package/runner/research_swarm.py

@@ -28,6 +28,7 @@ from runner.state_machine import (
     _atomic_write_json,
 )
 from runner.auditor_engine import EpistemicAuditorEngine
+from runner.errors import DossierNotFound
 from runner.retrieval_log import current_offset as _retrieval_offset
 from runner.retrieval_log import summarize as _retrieval_summary
 from skills.research_cache.hasher import SourceHasher
@@ -242,8 +243,12 @@ class SwarmRunner:
         agent_overrides: Optional[Dict[str, Dict[str, Any]]] = None,
         allocation: Optional[str] = None,
         domain_pack: Optional[str] = None,
+        resume: bool = False,
+        dry_run: bool = False,
     ):
         self.base_dir = base_dir or Path(".research")
+        self.resume = resume
+        self.dry_run = dry_run
         # Project root = the directory containing the evidence dir. Agents are
         # spawned here so the relative `.research/...` paths named by the
         # canonical prompts resolve to the RUNNER's evidence tree. Spawning in
@@ -597,6 +602,22 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
         """Extract a dossier dict from free-form agent stdout (fence-aware)."""
         return SwarmRunner._parse_json_block(text, require_key="scope_id")
 
+    @staticmethod
+    def _warn_schema_violations(dossier: Dict[str, Any], role: str) -> None:
+        """Advisory contract check — warn with the offending key, never abort (#6 2.1)."""
+        try:
+            from runner.schema_validate import check_dossier
+
+            problems = check_dossier(dossier, role)
+        except Exception:  # noqa: BLE001 - validation must never break a run
+            return
+        for problem in problems[:5]:
+            sys.stderr.write(f"[swarm] schema: {problem}\n")
+        if len(problems) > 5:
+            sys.stderr.write(
+                f"[swarm] schema: … {len(problems) - 5} more violation(s)\n"
+            )
+
     @staticmethod
     def _load_dossier_file(
         path: Path, expected_scope: Optional[str] = None
@@ -682,6 +703,7 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
                     f"  [{role}] ⚠️ Dossier found as {candidate.name}; "
                     f"normalized to {dossier_path.name}."
                 )
+            self._warn_schema_violations(data, role)
             return data
         recovered = self._parse_dossier_json(transcript or "")
         if recovered is not None:
@@ -690,8 +712,25 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
             _atomic_write_json(dossier_path, recovered)
             print(f"  [{role}] ⚠️ Dossier file missing; recovered from stdout.")
             return recovered
-        raise FileNotFoundError(
-            self._dossier_missing_message(dossier_path, scope_id, role, aliases)
+        message = self._dossier_missing_message(dossier_path, scope_id, role, aliases)
+        elsewhere = None
+        for name in [dossier_path.name, *aliases]:
+            found = self._locate_dossier_elsewhere(scope_id, name)
+            if found:
+                elsewhere = found
+                break
+        raise DossierNotFound(
+            code="DOSSIER_NOT_FOUND",
+            message=message,
+            path_searched=str(dossier_path),
+            path_written=str(elsewhere) if elsewhere else None,
+            workspace=str(self.base_dir),
+            spawn_cwd=_agent_cwd(self.project_root),
+            suggested_fix=(
+                "The agent likely wrote to a different workspace than the runner "
+                "reads. Re-run on the current plugin, or point IUMBTEMS_AGENT_CWD / "
+                "IUMBTEMS_PROJECT_DIR at the runner's workspace."
+            ),
         )
 
     def _dossier_missing_message(
@@ -1219,6 +1258,7 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
             else:
                 for scope in ready_scopes:
                     self.execute_scope_dialectic(scope)
+            self._write_progress()
 
     def _all_scopes_complete(self, manifest: Dict[str, Any]) -> bool:
         return all(
@@ -1247,10 +1287,40 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
         # Retrieval telemetry baseline: count only events from this run.
         self._retrieval_offset = _retrieval_offset(self.base_dir)
         print(f"   {self._retrieval_banner()}")
+
+        # Preflight: workspace, backend binary, engine reachability, write test.
+        from runner.preflight import format_report, preflight
+
+        self._preflight = preflight(
+            self.base_dir,
+            mode=self.mode,
+            config=self.config,
+            mock_mode=self.mock_mode,
+            probe=os.environ.get("IUMBTEMS_PREFLIGHT_PROBE", "1").strip().lower()
+            not in ("0", "false", "no", "off"),
+        )
+        print(format_report(self._preflight))
         print("=" * 70)
+        self.state_machine.record_preflight(
+            self._preflight, backend=self._preflight.get("backend", {}).get("family")
+        )
+
+        if self.dry_run:
+            print("\n🧪 [Dry Run] configuration validated; no agents spawned.")
+            return
 
-        # 1. Orchestrate
-        self.orchestrate_objective(objective, frontier_file)
+        # 1. Orchestrate (skip when resuming a session that already has scopes)
+        resumed = False
+        if self.resume:
+            try:
+                existing = self.state_machine.load_global_manifest().get("scopes") or []
+            except FileNotFoundError:
+                existing = []
+            resumed = bool(existing)
+            if resumed:
+                print(f"   ↻ resume: {len(existing)} scope(s) already recorded")
+        if not resumed:
+            self.orchestrate_objective(objective, frontier_file)
 
         # 2. Execute scopes according to DAG
         if not self._run_scope_batches():
@@ -1266,8 +1336,70 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
 
         duration = (datetime.now(timezone.utc) - start_time).total_seconds()
         print(f"   {self._retrieval_banner()}")
+        self._warn_version_drift()
+        self._report_stdout_recovery()
         print(f"\n🎉 Swarm run completed in {duration:.1f}s. Report: {report_path}")
 
+    def _write_progress(self) -> None:
+        """Per-scope status snapshot so a long run is observable while it runs."""
+        try:
+            manifest = self.state_machine.load_global_manifest()
+            rows = [
+                {
+                    "scope_id": scope["scope_id"],
+                    "status": self.state_machine.reconcile_scope_status(
+                        scope["scope_id"]
+                    ).get("status"),
+                }
+                for scope in manifest.get("scopes", [])
+            ]
+            (self.base_dir / "progress.json").write_text(
+                json.dumps(rows, indent=2), encoding="utf-8"
+            )
+        except Exception:  # noqa: BLE001 - progress must not fail a run
+            return
+
+    def _report_stdout_recovery(self) -> None:
+        """Surface dossiers salvaged from stdout — the file-write path failed (#6 2.9)."""
+        try:
+            manifest = self.state_machine.load_global_manifest()
+        except Exception:  # noqa: BLE001
+            return
+        recovered = []
+        for scope in manifest.get("scopes", []):
+            scope_dir = self.state_machine.get_scope_dir(scope["scope_id"])
+            for name in ("alpha_dossier.json", "beta_dossier.json"):
+                path = scope_dir / name
+                if not path.exists():
+                    continue
+                try:
+                    if json.loads(path.read_text(encoding="utf-8")).get(
+                        "recovered_from_stdout"
+                    ):
+                        recovered.append(f"{scope['scope_id']}/{name}")
+                except (OSError, ValueError):
+                    continue
+        if recovered:
+            print(
+                f"   ⚠️ {len(recovered)} dossier(s) recovered from stdout "
+                f"(agent file write failed): {', '.join(recovered[:4])}"
+            )
+
+    def _warn_version_drift(self) -> None:
+        """Warn when the installed plugin version changed during the run (#6 2.7)."""
+        try:
+            from runner.preflight import plugin_version
+
+            current = plugin_version()
+            recorded = self.state_machine.load_global_manifest().get("plugin_version")
+        except Exception:  # noqa: BLE001
+            return
+        if recorded and current and recorded != current:
+            print(
+                f"   ⚠️ plugin version changed mid-run: {recorded} -> {current}; "
+                "artifacts may span versions"
+            )
+
     def _write_orphan_report(self) -> None:
         """Record scope dirs absent from every manifest (mark-only, never delete)."""
         try:
@@ -1500,6 +1632,16 @@ def main():
         default=None,
         help="Agent runtime backend for both roles (default: auto = host-native; explicit beats env/config)",
     )
+    parser.add_argument(
+        "--resume",
+        action="store_true",
+        help="Continue an existing session instead of re-orchestrating",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Validate config/backends/engine and exit without spawning agents",
+    )
 
     args = parser.parse_args()
     frontier_path = Path(args.frontier) if args.frontier else None
@@ -1525,6 +1667,8 @@ def main():
         agent_overrides=agent_overrides or None,
         allocation=args.allocation,
         domain_pack=args.domain_pack,
+        resume=getattr(args, "resume", False),
+        dry_run=getattr(args, "dry_run", False),
     )
     runner.run_swarm(args.objective, frontier_file=frontier_path)
 

package/runner/schema_validate.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Dependency-free JSON Schema subset validator.
+
+The package must not pull in `jsonschema` (no auto-installing deps), so this
+supports the subset `runner/schemas.py` actually uses: `type` (incl. unions),
+`required`, `properties`, `items`, `enum`. Unknown keys are allowed on purpose —
+contracts evolve and a new optional field must not fail a run.
+
+Validation is advisory: `_load_agent_dossier` warns and keeps going (#6 item 2.1).
+"""
+
+from typing import Any, Dict, List
+
+_TYPE_MAP = {
+    "object": dict,
+    "array": list,
+    "string": str,
+    "boolean": bool,
+    "number": (int, float),
+    "integer": int,
+    "null": type(None),
+}
+
+
+def _type_matches(value: Any, expected: str) -> bool:
+    if expected == "integer":
+        return isinstance(value, int) and not isinstance(value, bool)
+    if expected == "number":
+        return isinstance(value, (int, float)) and not isinstance(value, bool)
+    if expected == "boolean":
+        return isinstance(value, bool)
+    py = _TYPE_MAP.get(expected)
+    return py is not None and isinstance(value, py)
+
+
+def validate(data: Any, schema: Dict[str, Any], path: str = "") -> List[str]:
+    """Return human-readable violations (dotted paths). Empty list == valid."""
+    if not isinstance(schema, dict):
+        return []
+    problems: List[str] = []
+
+    expected = schema.get("type")
+    if expected is not None:
+        types = expected if isinstance(expected, list) else [expected]
+        if not any(_type_matches(data, t) for t in types):
+            return [
+                f"{path or '<root>'}: expected {'|'.join(types)}, got {type(data).__name__}"
+            ]
+
+    if isinstance(data, dict):
+        for key in schema.get("required", []):
+            if key not in data:
+                problems.append(f"{path or '<root>'}: missing required key '{key}'")
+        for key, subschema in (schema.get("properties") or {}).items():
+            if key in data:
+                child = f"{path}.{key}" if path else key
+                problems.extend(validate(data[key], subschema, child))
+        additional = schema.get("additionalProperties")
+        if isinstance(additional, dict):
+            known = set((schema.get("properties") or {}).keys())
+            for key, value in data.items():
+                if key not in known:
+                    child = f"{path}.{key}" if path else key
+                    problems.extend(validate(value, additional, child))
+        enum = schema.get("enum")
+        if enum is not None and data not in enum:
+            problems.append(f"{path or '<root>'}: value {data!r} not in enum {enum}")
+
+    if isinstance(data, list) and isinstance(schema.get("items"), dict):
+        for i, item in enumerate(data):
+            problems.extend(validate(item, schema["items"], f"{path}[{i}]"))
+
+    if not isinstance(data, (dict, list)):
+        enum = schema.get("enum")
+        if enum is not None and data not in enum:
+            problems.append(f"{path or '<root>'}: value {data!r} not in enum {enum}")
+
+    return problems
+
+
+def validate_named(name: str, data: Any) -> List[str]:
+    """Validate against a named schema from runner/schemas.py."""
+    from runner.schemas import SCHEMAS
+
+    schema = SCHEMAS.get(name)
+    if schema is None:
+        return []
+    return [f"{name}: {p}" for p in validate(data, schema)]
+
+
+def check_dossier(dossier: Any, role: str) -> List[str]:
+    name = "alpha_dossier" if role.lower().startswith("alpha") else "beta_dossier"
+    return validate_named(name, dossier)