@heretek-ai/epistemic-swarm 0.7.13 → 0.7.15

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "epistemic-swarm",
-  "version": "0.7.13",
+  "version": "0.7.15",
   "description": "High-Integrity Dialectic Research Agent Harness for Claude Code enforcing empirical evidence over parametric hallucination.",
   "author": {
     "name": "Heretek AI",

package/README.md

@@ -199,11 +199,13 @@ iumbtems adapters
 # Other utility commands
 iumbtems install      # install skills & MCP servers into ~/.claude/
 iumbtems marketplace  # print the Claude Code marketplace catalog
-iumbtems doctor       # check environment requirements
+iumbtems doctor       # environment + preflight health check
 iumbtems test         # run the automated test suite
 iumbtems help         # full usage text
 ```
 
+Run-shaping flags: `--resume` (continue a session instead of re-orchestrating) and `--dry-run` (validate config/backends/engine without spawning agents). Frontier authoring is fully tool-driven: `socratic_tree.py --add-node/--settle/--export`.
+
 Common options: `--mock-claude` (synthetic responses, zero API cost), `--frontier <file>` (settled `frontier.json`), `--mode <research|audit|scout|hybrid|brainstorm|darkharvest>`, `--engine <duckduckgo|brave|firecrawl|searxng>`, `--depth <1-4>`, `--backend <auto|claude|opencode>`, `--dir <path>`.
 
 The `epistemic-swarm` binary is an alias of `iumbtems`.
@@ -231,6 +233,8 @@ The canonical MCP server (`python3 runner/mcp_server.py`, stdio) exposes these t
 | `iumbtems_report_retraction` | Record a RETRACTED/REVISED event for a cached source; dependent `VERIFIED` claims degrade to STALE/SUSPECT on the next audit. |
 | `iumbtems_check_staleness` | One claim-degradation pass: join claims against retraction events, write the status ledger, queue re-runs for degraded scopes. Never mutates dossiers. |
 | `iumbtems_set_domain_pack` | Activate a Regulated Domain Pack (`biopharma` / `quant` / `legal` epistemic constitution) for subsequent audits. |
+| `iumbtems_doctor` | Preflight health check: plugin version, backend + resolved binary, search-engine live probe, workspace write test. Run first when something looks wrong. |
+| `iumbtems_test` | Run the packaged test suite in a subprocess and report pass/fail with the tail. |
 
 ---
 
@@ -332,7 +336,7 @@ python3 scripts/build_adapters.py --check   # CI gate: fails on drift
 python3 -m unittest discover -s runner/tests
 ```
 
-`skills/research-cache` is a symlink to `skills/research_cache`, kept so the legacy hyphenated path resolves in a checkout (the Claude Code overlay installer creates the same alias under `~/.claude/skills/`).
+The legacy hyphenated skill name is served by an alias the overlay installer creates under the user's `~/.claude/skills/` directory. It is deliberately **not** committed as an in-repo symlink: `claude plugin validate --strict` treats a symlink entry as a warning (→ error), which fails marketplace and eval validation.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "0.7.13",
+  "version": "0.7.15",
   "description": "IUMBTEMS (Epistemic Swarm) — High-Integrity Dialectic Research Agent Harness for Claude Code, OpenCode V2, Pi (pi.dev), OMP (oh-my-pi), Gemini CLI, Codex CLI, and AntiGravity",
   "main": "bin/cli.js",
   "bin": {
@@ -118,6 +118,7 @@
     "bin",
     "prompts",
     "skills",
+    "schemas",
     "hooks",
     "config",
     "runner",

package/plugins/factory/skills/factory/scripts/factory.py

@@ -55,7 +55,10 @@ def run_dir(run):
 def load_state(run):
     p = run_dir(run) / "state.json"
     if not p.exists():
-        raise SystemExit(f"No factory run '{run}'. Run `factory.py init` first.")
+        raise SystemExit(
+            f"No factory run '{run}'. Pass --run <name> (or run "
+            f"`factory.py init --run <name>` first)."
+        )
     return json.loads(p.read_text(encoding="utf-8"))
 
 
@@ -82,6 +85,19 @@ def cmd_phase_add(args):
     state = load_state(args.run)
     if args.phase in state["phases"]:
         raise SystemExit(f"Phase '{args.phase}' already exists.")
+    # Phase output goes to phase.json — a run-state helper must never clobber the
+    # author-written GOAL.md / dossier.json it is meant to track (#6 item 2.3).
+    # This check runs BEFORE any state mutation so a refusal leaves no trace.
+    phase_dir = ROADMAP_DIR / args.phase
+    authored = [
+        name for name in ("GOAL.md", "dossier.json") if (phase_dir / name).exists()
+    ]
+    if authored and not getattr(args, "force", False):
+        raise SystemExit(
+            f"Refusing to touch author-written file(s) in {phase_dir}: "
+            f"{', '.join(authored)}. phase-add now writes phase.json only; "
+            f"re-run with --force to overwrite."
+        )
     state["phases"][args.phase] = {
         "goal": args.goal,
         "acceptance": [a.strip() for a in args.accept.split(";") if a.strip()],
@@ -90,30 +106,52 @@ def cmd_phase_add(args):
         "qa_reports": [],
     }
     save_state(args.run, state)
-    # Phase output: GOAL.md + dossier.json skeleton (evidence filled by manager).
-    phase_dir = ROADMAP_DIR / args.phase
     phase_dir.mkdir(parents=True, exist_ok=True)
-    (phase_dir / "GOAL.md").write_text(
-        f"# {args.phase}: {args.goal}\n\n## Acceptance\n"
-        + "".join(f"- [ ] {a}\n" for a in state["phases"][args.phase]["acceptance"]),
-        encoding="utf-8",
-    )
-    (phase_dir / "dossier.json").write_text(
+    (phase_dir / "phase.json").write_text(
         json.dumps(
             {
                 "phase": args.phase,
                 "goal": args.goal,
-                "evidence": [],
                 "acceptance": state["phases"][args.phase]["acceptance"],
-                "brief": "",
-                "verdict": "briefed",
-                "hashes": [],
+                "status": "briefed",
             },
             indent=2,
         ),
         encoding="utf-8",
     )
-    print(f"✅ Phase '{args.phase}' briefed → {phase_dir}")
+    print(f"✅ Phase '{args.phase}' briefed → {phase_dir / 'phase.json'}")
+
+
+def cmd_gate(args):
+    """First-class gate bookkeeping (open/settle/approve/waive/escalate/count)."""
+    state = load_state(args.run)
+    gates = state.setdefault("gates", {})
+    gate = gates.setdefault(
+        args.phase, {"status": "closed", "cycles": 0, "waivers": [], "history": []}
+    )
+    action = (args.action or "").lower()
+    if action == "open":
+        gate["status"] = "open"
+        gate["cycles"] = gate.get("cycles", 0) + 1
+        state["gate_cycles"] = state.get("gate_cycles", 0) + 1
+    elif action == "settle":
+        gate["status"] = "settled"
+    elif action == "approve":
+        gate["status"] = "approved"
+    elif action == "waive":
+        gate["status"] = "waived"
+        gate["waivers"].append(args.reason or "")
+    elif action == "escalate":
+        gate["status"] = "escalated"
+        gate["cycles"] = gate.get("cycles", 0) + 1
+        state["gate_cycles"] = state.get("gate_cycles", 0) + 1
+    elif action != "count":
+        raise SystemExit(
+            "gate --action must be one of: open, settle, approve, waive, escalate, count"
+        )
+    gate["history"].append({"action": action, "at": now(), "reason": args.reason or ""})
+    save_state(args.run, state)
+    print(json.dumps({"phase": args.phase, "gate": gate}, indent=2))
 
 
 def cmd_qa_record(args):
@@ -211,6 +249,11 @@ def main():
     p.add_argument("--phase", required=True)
     p.add_argument("--goal", required=True)
     p.add_argument("--accept", default="")
+    p.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite author-written GOAL.md/dossier.json if present",
+    )
     _add_common(p)
     p = sub.add_parser("qa-record")
     p.add_argument("--run", required=True)
@@ -227,6 +270,16 @@ def main():
     p = sub.add_parser("stop")
     p.add_argument("--run", required=True)
     _add_common(p)
+    p = sub.add_parser("gate")
+    p.add_argument("--run", required=True)
+    p.add_argument("--phase", required=True)
+    p.add_argument(
+        "--action",
+        required=True,
+        choices=["open", "settle", "approve", "waive", "escalate", "count"],
+    )
+    p.add_argument("--reason", default="")
+    _add_common(p)
 
     args = ap.parse_args()
     root = resolve_project_root(args.project_dir)
@@ -238,6 +291,7 @@ def main():
         "qa-record": cmd_qa_record,
         "expansion": cmd_expansion,
         "stop": cmd_stop,
+        "gate": cmd_gate,
     }[args.command](args)
     sys.exit(code if isinstance(code, int) else 0)
 

package/plugins/opencode/index.js

@@ -111,6 +111,8 @@ export const IUMBTEMS_TOOL_NAMES = [
   'iumbtems_set_domain_pack',
   'iumbtems_export_brief',
   'iumbtems_verify_brief',
+  'iumbtems_doctor',
+  'iumbtems_test',
 ];
 
 // Deprecated misspelled alias (pre-A2b export). Remove in a semver-major.
@@ -444,6 +446,25 @@ const TOOL_CATALOG = [
       required: ['brief'],
     },
   },
+  {
+    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: {
+      type: 'object',
+      properties: {
+        base_dir: { type: 'string', description: 'Project root (default: IUMBTEMS_PROJECT_DIR or cwd)' },
+        mode: { type: 'string', description: 'Operating mode to report for' },
+        probe: { type: 'boolean', description: 'Run a live 1-query search probe (default true)' },
+      },
+    },
+  },
+  {
+    name: 'iumbtems_test',
+    description:
+      'Run the packaged IUMBTEMS test suite (subprocess, timeout-bounded) and report pass/fail with the tail of the output.',
+    input: { type: 'object', properties: {} },
+  },
 ];
 
 /** Legacy arg shims -> MCP handler contract. */

package/plugins/socratic-grilling/skills/grilling/SKILL.md

@@ -42,7 +42,20 @@ Always challenge default premises in Round 1:
 
 ## 5. FRONTIER RESOLUTION & FREEZING
 
+The frontier is fully tool-drivable (no hand-written JSON):
+
+```bash
+# author a node (prerequisites gate when it appears on the frontier)
+python3 skills/grilling/socratic_tree.py --add-node --id N1 \
+  --question "L1 or L2 for state verification?" --depends-on ""
+# settle a node
+python3 skills/grilling/socratic_tree.py --settle N1 "L1 for finality"
+# inspect / freeze
+python3 skills/grilling/socratic_tree.py --show-frontier
+python3 skills/grilling/socratic_tree.py --export
+```
+
 When every branch of the design tree has been visited and the frontier is empty:
 1. Summarize the settled constraints.
-2. Save the settled state to `.research/frontier.json` using `python3 skills/grilling/socratic_tree.py --export`.
+2. Freeze the settled state to `.research/frontier.json` (`--export`, default path).
 3. Hand off the settled frontier to the **Swarm Orchestrator** to begin empirical dialectic execution.

package/plugins/socratic-grilling/skills/grilling/socratic_tree.py

@@ -11,10 +11,17 @@ import argparse
 from pathlib import Path
 from typing import Dict, List, Optional, Any
 
+
 class DecisionNode:
-    def __init__(self, node_id: str, title: str, question: str, 
-                 recommended: str, options: Optional[List[str]] = None,
-                 prerequisites: Optional[List[str]] = None):
+    def __init__(
+        self,
+        node_id: str,
+        title: str,
+        question: str,
+        recommended: str,
+        options: Optional[List[str]] = None,
+        prerequisites: Optional[List[str]] = None,
+    ):
         self.node_id = node_id
         self.title = title
         self.question = question
@@ -34,18 +41,18 @@ class DecisionNode:
             "recommended": self.recommended,
             "options": self.options,
             "prerequisites": self.prerequisites,
-            "settled_answer": self.settled_answer
+            "settled_answer": self.settled_answer,
         }
 
     @classmethod
-    def from_dict(cls, data: Dict[str, Any]) -> 'DecisionNode':
+    def from_dict(cls, data: Dict[str, Any]) -> "DecisionNode":
         node = cls(
             node_id=data["node_id"],
             title=data["title"],
             question=data["question"],
             recommended=data["recommended"],
             options=data.get("options", []),
-            prerequisites=data.get("prerequisites", [])
+            prerequisites=data.get("prerequisites", []),
         )
         node.settled_answer = data.get("settled_answer")
         return node
@@ -82,7 +89,9 @@ class DesignTree:
             self.nodes[node_id].settled_answer = answer
 
     def is_complete(self) -> bool:
-        return len(self.compute_frontier()) == 0 and all(n.is_settled() for n in self.nodes.values())
+        return len(self.compute_frontier()) == 0 and all(
+            n.is_settled() for n in self.nodes.values()
+        )
 
     def export_frontier_json(self, output_path: Path):
         safe_path = Path(os.path.realpath(str(output_path)))
@@ -93,13 +102,13 @@ class DesignTree:
             "nodes": {k: v.to_dict() for k, v in self.nodes.items()},
             "settled_constraints": {
                 k: v.settled_answer for k, v in self.nodes.items() if v.is_settled()
-            }
+            },
         }
         with open(safe_path, "w", encoding="utf-8") as f:
             json.dump(data, f, indent=2)
 
     @classmethod
-    def load_from_json(cls, file_path: Path) -> 'DesignTree':
+    def load_from_json(cls, file_path: Path) -> "DesignTree":
         safe_path = Path(os.path.realpath(str(file_path)))
         with open(safe_path, "r", encoding="utf-8") as f:
             data = json.load(f)
@@ -111,12 +120,16 @@ class DesignTree:
 
 def _display_frontier(tree: DesignTree, frontier: list) -> None:
     print(f"\n🎯 Objective: {tree.objective}")
-    print(f"📊 Total Nodes: {len(tree.nodes)} | Settled: {sum(1 for n in tree.nodes.values() if n.is_settled())}")
+    print(
+        f"📊 Total Nodes: {len(tree.nodes)} | Settled: {sum(1 for n in tree.nodes.values() if n.is_settled())}"
+    )
     if not frontier:
         if tree.nodes and tree.is_complete():
             print("✅ Frontier is EMPTY. All prerequisite branches are fully settled!")
         else:
-            print("ℹ️ No active frontier nodes. Define new decision nodes to begin grilling.")
+            print(
+                "ℹ️ No active frontier nodes. Define new decision nodes to begin grilling."
+            )
     else:
         print(f"\n⚡ Current Active Frontier ({len(frontier)} questions ready):")
         for idx, node in enumerate(frontier, 1):
@@ -126,11 +139,49 @@ def _display_frontier(tree: DesignTree, frontier: list) -> None:
 
 
 def main():
-    parser = argparse.ArgumentParser(description="Epistemic Swarm Socratic Decision Tree")
+    parser = argparse.ArgumentParser(
+        description="Epistemic Swarm Socratic Decision Tree"
+    )
     parser.add_argument("--objective", type=str, help="Research objective")
-    parser.add_argument("--file", type=str, default=".research/frontier.json", help="Path to frontier.json")
-    parser.add_argument("--show-frontier", action="store_true", help="Print the current decision frontier")
-    parser.add_argument("--settle", nargs=2, metavar=("NODE_ID", "ANSWER"), help="Settle a decision node")
+    parser.add_argument(
+        "--file",
+        type=str,
+        default=".research/frontier.json",
+        help="Path to frontier.json",
+    )
+    parser.add_argument(
+        "--show-frontier",
+        action="store_true",
+        help="Print the current decision frontier",
+    )
+    parser.add_argument(
+        "--settle",
+        nargs=2,
+        metavar=("NODE_ID", "ANSWER"),
+        help="Settle a decision node",
+    )
+    parser.add_argument(
+        "--add-node",
+        action="store_true",
+        help="Add a decision node (with --id/--question)",
+    )
+    parser.add_argument("--id", type=str, help="Node id (with --add-node)")
+    parser.add_argument("--question", type=str, help="Node question (with --add-node)")
+    parser.add_argument(
+        "--title", type=str, default="", help="Node title (defaults to --id)"
+    )
+    parser.add_argument(
+        "--recommended", type=str, default="", help="Recommended option"
+    )
+    parser.add_argument(
+        "--depends-on",
+        type=str,
+        default="",
+        help="Comma-separated prerequisite node ids",
+    )
+    parser.add_argument(
+        "--export", action="store_true", help="Write the frontier JSON and exit"
+    )
 
     args = parser.parse_args()
     frontier_path = Path(os.path.realpath(str(args.file)))
@@ -141,14 +192,35 @@ def main():
         objective = args.objective or "Epistemic Swarm Research Objective"
         tree = DesignTree(objective=objective)
 
+    if args.add_node:
+        if not args.id or not args.question:
+            parser.error("--add-node requires --id and --question")
+        prereqs = [p.strip() for p in (args.depends_on or "").split(",") if p.strip()]
+        tree.add_node(
+            DecisionNode(
+                node_id=args.id,
+                title=args.title or args.id,
+                question=args.question,
+                recommended=args.recommended or "",
+                options=[],
+                prerequisites=prereqs,
+            )
+        )
+        tree.export_frontier_json(frontier_path)
+        print(f"Added node {args.id} -> {frontier_path}")
+
     if args.settle:
         node_id, answer = args.settle
         tree.settle_node(node_id, answer)
         tree.export_frontier_json(frontier_path)
         print(f"Settled {node_id} -> {answer}")
 
+    if args.export:
+        tree.export_frontier_json(frontier_path)
+        print(f"Exported frontier -> {frontier_path}")
+
     frontier = tree.compute_frontier()
-    if args.show_frontier or not args.settle:
+    if args.show_frontier or not (args.settle or args.add_node or args.export):
         _display_frontier(tree, frontier)
 
 

package/runner/errors.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Structured, typed errors (Heretek-AI/IUMBTEMS#6 item 3.10).
+
+The 0.7.10 diagnostic was the most valuable output in the reporter's session, so
+this generalises it: every actionable failure carries a code, the path that was
+searched, where output actually went, the resolved workspace, the spawn cwd, and
+a suggested fix. An agent can act on that; it cannot act on `FileNotFoundError`.
+"""
+
+from dataclasses import asdict, dataclass, field
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class SwarmError(Exception):
+    """Base typed error with the diagnostic fields an agent needs."""
+
+    code: str
+    message: str
+    path_searched: Optional[str] = None
+    path_written: Optional[str] = None
+    workspace: Optional[str] = None
+    spawn_cwd: Optional[str] = None
+    suggested_fix: Optional[str] = None
+    details: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        super().__init__(self.message)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {k: v for k, v in asdict(self).items() if v not in (None, {}, "")}
+
+    def __str__(self) -> str:
+        lines = [f"[{self.code}] {self.message}"]
+        for label, value in (
+            ("path_searched", self.path_searched),
+            ("path_written", self.path_written),
+            ("workspace", self.workspace),
+            ("spawn_cwd", self.spawn_cwd),
+            ("suggested_fix", self.suggested_fix),
+        ):
+            if value:
+                lines.append(f"  {label}: {value}")
+        return "\n".join(lines)
+
+
+class DossierNotFound(SwarmError, FileNotFoundError):
+    """A required role dossier is absent.
+
+    Subclasses FileNotFoundError so existing callers/tests keep working.
+    """