@heretek-ai/epistemic-swarm 0.7.12 → 0.7.14

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "epistemic-swarm",
-  "version": "0.7.12",
+  "version": "0.7.14",
   "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. |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "0.7.12",
+  "version": "0.7.14",
   "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/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/prompts/agent_darkharvest.md

@@ -33,6 +33,17 @@ partial per capability), benchmark/API quotes, and per-feature harvest
 proposals. Every cell needs `[VERIFIED: <hash>]` from
 `.research/sources/<sha256>.md` or `file://<path>#L<start>-L<end>`.
 
+Discover and cache every cited source before you cite it (zero-key, no API keys):
+
+```bash
+python3 skills/epistemic_search/scripts/search.py "<query>"
+python3 skills/research_cache/hasher.py cache --url "<URL>" --content "$(cat fetched.md)" --title "<TITLE>"
+```
+
+Confirm a repository actually exists (`owner/repo`) before citing it. A run that
+never searches caches zero sources and is flagged `WARNING_LOW_GROUNDING` — the
+runner prints `retrieval: N queries, M results, K cached` as evidence either way.
+
 ### Beta — Red Team
 License gate (LICENSE file + package metadata → SPDX), transitive weight,
 CVE/takeover notes, staleness (`⚠️ STALE` when >12mo or solo-maintainer),
@@ -51,7 +62,9 @@ AND what we lack). Gates are warn-only: badge inline, never auto-skip.
 ## 4. OUTPUT SPECIFICATION
 
 Per scope write `alpha_dossier.json` / `beta_dossier.json` with
-`candidate_repositories[]` entries:
+`candidate_repositories[]` entries. Every entry MUST carry `source_hash` **and**
+`verbatim_quote` (an exact substring of the cached `.research/sources/<hash>.md`);
+entries without both are rejected as unverified by the audit.
 
 ```json
 {
@@ -59,6 +72,7 @@ Per scope write `alpha_dossier.json` / `beta_dossier.json` with
   "name": "owner/repo",
   "url": "https://github.com/owner/repo",
   "source_hash": "<sha256>",
+  "verbatim_quote": "<exact substring of the cached source>",
   "license": "Apache-2.0",
   "license_risk": "SAFE | COPYLEFT_WARNING | PROHIBITIVE",
   "harvest_policy": "depend-or-vendor | clean-room-rebuild-only",
@@ -89,3 +103,8 @@ candidates.
 3. No unverified harvest verdicts. Metadata ranks; only VERIFIED harvests.
 4. No unbounded expansion past `--max-repos` or per-repo caps without user
    confirmation. Firecrawl missing → gap note, never abort.
+5. **Do NOT self-report audit results.** Never emit `epistemic_audit`,
+   `confidence`, `verified_*`, `unverified_*`, `mean_epistemic_score`, or any
+   `*.verified` / `*.total_sources` field. The runner computes verification from
+   cached witnesses; agent-declared counts are ignored (renamed to
+   `self_reported_*`) and only mislead a human reader.