@heretek-ai/epistemic-swarm 0.6.0 → 0.7.2

package/plugins/factory/agents/qa-functional.md

@@ -0,0 +1,17 @@
+---
+name: qa-functional
+description: Factory QA, functional seat. Verifies phase acceptance criteria pass on the real surface. Read-only plus test execution. Use alongside qa-adversarial per phase.
+model: sonnet
+---
+
+You are QA-A (functional seat) in the factory plugin.
+
+Verify each acceptance criterion in the phase dossier by executing it on the
+real surface (run the tests, exercise the feature, inspect the output).
+Read-only plus test execution — never edit code to make a check pass. Verdicts:
+`pass | fail(reason) | conditional(note)`, each tied to a specific criterion.
+Record via the manager; three failures on one phase escalate it back to the
+manager with both QA reports attached. Your prompt is deliberately diverged
+from qa-adversarial: you prove what works, it hunts what breaks.
+
+Full specification: `skills/factory/SKILL.md` in the plugin root.

package/plugins/factory/evals/gate-halt/graders/gates-first.md

@@ -0,0 +1,6 @@
+---
+type: llm
+---
+
+PASS if the reply proposes phased scope with explicit approval gates (or asks gate/phase-clarifying questions first) instead of writing implementation code immediately.
+FAIL if the reply starts implementing code with no phase breakdown and no user sign-off step.

package/plugins/factory/evals/gate-halt/graders/skill-fired.md

@@ -0,0 +1,5 @@
+---
+type: tool_used
+tool: Skill
+input_match: '"skill"\s*:\s*"(?:[\w-]+:)?factory"'
+---

package/plugins/factory/evals/gate-halt/prompt.md

@@ -0,0 +1,6 @@
+---
+max_turns: 10
+allowed_tools: [Read, Glob, Grep, Skill]
+---
+
+I want to build a small session-handoff feature across agent harnesses, broken into reviewable phases with QA on each phase. Set up the gated build loop.

package/plugins/factory/skills/factory/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: factory
+description: Coding-factory Manager loop. Use when user invokes /factory or /domainexpansion, or wants grill-gated phased builds with programmer spawns and dual QA. Manager grills until frontier settled, runs brainstorm plus darkharvest swarms per gate, synthesizes .roadmap phases, spawns programmer per phase, and enforces dual-QA retry bounds. Never writes code itself; never bypasses explicit user sign-off (except inside /domainexpansion count).
+---
+
+# Factory — Manager Loop & Domain Expansion
+
+## 1. Roles (OpenCode profiles in `config/opencode-snippet.json`)
+
+- **manager** (primary): owns gates, grilling, swarm dispatch, roadmap synthesis, tiebreaks.
+  Task allowlist: `factory-*`, `programmer`, `qa-a`, `qa-b`, `brainstormer`, `darkharvester` deny `*` otherwise.
+- **programmer** (subagent): implements exactly one phase brief. May call `iumbtems_verify_quote`; may NOT invoke swarms or other programmers.
+- **qa-a / qa-b** (subagents): same model, DIVERGED prompts (functional-correctness vs adversarial edge-case). Read-only plus test execution; never edit.
+- **researcher** = existing `iumbtems_brainstorm` + `iumbtems_darkharvest` swarms (no new profile).
+
+## 2. Gate protocol (max 5 swarm cycles per gate)
+
+1. Grill until `.factory/frontier.json` settled (grilling skill).
+2. Run brainstorm + darkharvest swarms (mock-first on fixtures).
+3. Manager synthesizes `.roadmap/<phase>/` (GOAL.md + dossier.json).
+4. Explicit user `approve` advances; anything else regrills (cycle counter in `.factory/state.json`).
+
+## 3. Phase contract (`.roadmap/<phase>/`)
+
+- `GOAL.md`: human-readable goal + acceptance criteria.
+- `dossier.json`: `{phase, goal, evidence:[{hash, quote}], acceptance[], brief, verdict, hashes}`. Every harvest/claim entry needs a SHA-256 source hash or `file://` pointer or it is purged to NEGATIVE_KNOWLEDGE.
+- Programmer receives the phase dossier (Manager chooses freeform vs strict brief but MUST cite phase hashes).
+
+## 4. QA protocol (3 retries, then escalate)
+
+- Both QA seats run per phase; disagreements go to manager tiebreak.
+- `skills/factory/scripts/factory.py` tracks `qa_retries` per phase in `.factory/state.json`. On 3rd rejection: halt phase, return to manager with both QA reports (retry loop per plan; manager may regrill scope or escalate to user).
+- QA verdicts: `pass | fail(reason) | conditional(note)`.
+
+## 5. Domain expansion (`/domainexpansion <n>`)
+
+- Bypasses per-loop gates; stops on count OR `.factory/STOP` file OR user kill, whichever first.
+- Each loop: agents propose direction → quick swarm check → implement → QA → next.
+- `factory.py` enforces: refuse `n < 1`, cap `n` at `--max-loops` default 10, check STOP file before every loop.
+
+## 6. State layout (three dirs, distinct jobs)
+
+- `.factory/`: run state (`state.json`, `frontier.json`, `STOP` kill-file). Gitignored runtime state.
+- `.roadmap/`: output (phase dirs). Committed.
+- `.research/`: evidence (swarm dossiers, source cache). Gitignored (existing rule).
+
+## 7. Anti-patterns
+
+- No code writes by manager; no swarm invocation by programmer; no edits by QA.
+- No gate bypass outside `/domainexpansion`; no uncapped loops.
+- No VERIFIED claims without hashes, even in expansion proposals.

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

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""
+Factory run-state helper: phase dossiers, QA retry bounds, expansion loop guard.
+
+All state lives under .factory/ (gitignored runtime state). Phase output goes
+to .roadmap/<phase>/. Evidence stays in .research/. Read-only w.r.t. repo code.
+
+Usage:
+  python3 skills/factory/scripts/factory.py init --run <name>
+  python3 skills/factory/scripts/factory.py phase-add --run <name> --phase 01-auth --goal "..." --accept "..."
+  python3 skills/factory/scripts/factory.py qa-record --run <name> --phase 01-auth --seat qa-a --verdict fail --reason "..."
+  python3 skills/factory/scripts/factory.py expansion --run <name> --loops 10 [--max-loops 10]
+  python3 skills/factory/scripts/factory.py stop --run <name>   # write STOP kill-file
+"""
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent.parent
+FACTORY_DIR = PROJECT_ROOT / ".factory"
+ROADMAP_DIR = PROJECT_ROOT / ".roadmap"
+
+MAX_QA_RETRIES = 3
+MAX_EXPANSION_LOOPS = 10
+
+
+def now():
+    return datetime.now(timezone.utc).isoformat()
+
+
+def run_dir(run):
+    return FACTORY_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.")
+    return json.loads(p.read_text(encoding="utf-8"))
+
+
+def save_state(run, state):
+    p = run_dir(run) / "state.json"
+    p.write_text(json.dumps(state, indent=2), encoding="utf-8")
+
+
+def cmd_init(args):
+    d = run_dir(args.run)
+    d.mkdir(parents=True, exist_ok=True)
+    state = {
+        "run": args.run,
+        "created_at": now(),
+        "gate_cycles": 0,
+        "phases": {},
+        "expansion": {"loops_done": 0, "loops_planned": 0},
+    }
+    save_state(args.run, state)
+    print(f"✅ Factory run '{args.run}' initialised at {d}")
+
+
+def cmd_phase_add(args):
+    state = load_state(args.run)
+    if args.phase in state["phases"]:
+        raise SystemExit(f"Phase '{args.phase}' already exists.")
+    state["phases"][args.phase] = {
+        "goal": args.goal,
+        "acceptance": [a.strip() for a in args.accept.split(";") if a.strip()],
+        "status": "briefed",
+        "qa_retries": 0,
+        "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(
+        json.dumps(
+            {
+                "phase": args.phase,
+                "goal": args.goal,
+                "evidence": [],
+                "acceptance": state["phases"][args.phase]["acceptance"],
+                "brief": "",
+                "verdict": "briefed",
+                "hashes": [],
+            },
+            indent=2,
+        ),
+        encoding="utf-8",
+    )
+    print(f"✅ Phase '{args.phase}' briefed → {phase_dir}")
+
+
+def cmd_qa_record(args):
+    state = load_state(args.run)
+    phase = state["phases"].get(args.phase)
+    if phase is None:
+        raise SystemExit(f"Unknown phase '{args.phase}'.")
+    if args.verdict not in ("pass", "fail", "conditional"):
+        raise SystemExit("verdict must be pass|fail|conditional.")
+    phase["qa_reports"].append(
+        {
+            "seat": args.seat,
+            "verdict": args.verdict,
+            "reason": args.reason or "",
+            "at": now(),
+        }
+    )
+    if args.verdict == "fail":
+        phase["qa_retries"] += 1
+        if phase["qa_retries"] >= MAX_QA_RETRIES:
+            phase["status"] = "escalated"
+            save_state(args.run, state)
+            print(
+                f"🛑 Phase '{args.phase}' ESCALATED after "
+                f"{MAX_QA_RETRIES} QA failures — back to manager."
+            )
+            return 2
+        phase["status"] = "retrying"
+    elif args.verdict == "pass":
+        phase["status"] = "signed-off"
+    else:
+        phase["status"] = "conditional"
+    save_state(args.run, state)
+    print(
+        f"✅ QA recorded: {args.phase} [{args.seat}] → {args.verdict} "
+        f"(status={phase['status']}, retries={phase['qa_retries']})"
+    )
+
+
+def stop_requested(run):
+    return (run_dir(run) / "STOP").exists()
+
+
+def cmd_expansion(args):
+    state = load_state(args.run)
+    n = args.loops
+    if n < 1:
+        raise SystemExit("loops must be >= 1.")
+    cap = args.max_loops or MAX_EXPANSION_LOOPS
+    n = min(n, cap)
+    state["expansion"]["loops_planned"] = n
+    save_state(args.run, state)
+    done = 0
+    for _ in range(1, n + 1):
+        if stop_requested(args.run):
+            print(f"🛑 STOP file present — halting after {done}/{n} loops.")
+            break
+        done += 1
+        print(
+            f"🔁 Expansion loop {done}/{n}: agents propose → swarm check → "
+            f"implement → QA (Manager drives each step)."
+        )
+    state = load_state(args.run)
+    state["expansion"]["loops_done"] += done
+    save_state(args.run, state)
+    print(f"✅ Expansion finished {done} loop(s).")
+
+
+def cmd_stop(args):
+    (run_dir(args.run)).mkdir(parents=True, exist_ok=True)
+    (run_dir(args.run) / "STOP").write_text(
+        f"stop requested at {now()}\n", encoding="utf-8"
+    )
+    print(f"🛑 STOP file written for run '{args.run}'.")
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Factory run-state helper")
+    sub = ap.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("init")
+    p.add_argument("--run", required=True)
+    p = sub.add_parser("phase-add")
+    p.add_argument("--run", required=True)
+    p.add_argument("--phase", required=True)
+    p.add_argument("--goal", required=True)
+    p.add_argument("--accept", default="")
+    p = sub.add_parser("qa-record")
+    p.add_argument("--run", required=True)
+    p.add_argument("--phase", required=True)
+    p.add_argument("--seat", required=True)
+    p.add_argument("--verdict", required=True)
+    p.add_argument("--reason", default="")
+    p = sub.add_parser("expansion")
+    p.add_argument("--run", required=True)
+    p.add_argument("--loops", type=int, required=True)
+    p.add_argument("--max-loops", type=int, default=MAX_EXPANSION_LOOPS)
+    p = sub.add_parser("stop")
+    p.add_argument("--run", required=True)
+
+    args = ap.parse_args()
+    code = {
+        "init": cmd_init,
+        "phase-add": cmd_phase_add,
+        "qa-record": cmd_qa_record,
+        "expansion": cmd_expansion,
+        "stop": cmd_stop,
+    }[args.command](args)
+    sys.exit(code if isinstance(code, int) else 0)
+
+
+if __name__ == "__main__":
+    main()

package/plugins/opencode/index.js

@@ -71,7 +71,16 @@ function callMcp(tool, args = {}, cwd = undefined) {
         [MCP_SERVER, 'call', tool, JSON.stringify(args || {})],
         {
           cwd: cwd || process.cwd(),
-          env: { ...process.env, PYTHONPATH: PKG_ROOT },
+          // Host hint: the runner defaults to the host-native backend
+          // (opencode run here), unless the caller passes backend explicitly.
+          // Project root: evidence defaults under <project>/.research instead
+          // of the server process cwd.
+          env: {
+            ...process.env,
+            PYTHONPATH: PKG_ROOT,
+            IUMBTEMS_HOST: 'opencode',
+            IUMBTEMS_PROJECT_DIR: cwd || process.cwd(),
+          },
         }
       );
     } catch (err) {
@@ -160,6 +169,11 @@ const TOOL_CATALOG = [
           description: 'Run in mock/dry-run mode without external API charges',
           default: false,
         },
+        backend: {
+          type: 'string',
+          enum: ['auto', 'claude', 'opencode'],
+          description: 'Agent runtime backend (default auto = host-native)',
+        },
       },
       required: ['objective'],
     },
@@ -180,6 +194,11 @@ const TOOL_CATALOG = [
           description: 'Run in mock mode without invoking LLM tokens',
           default: false,
         },
+        backend: {
+          type: 'string',
+          enum: ['auto', 'claude', 'opencode'],
+          description: 'Agent runtime backend (default auto = host-native)',
+        },
       },
       required: ['target'],
     },
@@ -200,6 +219,11 @@ const TOOL_CATALOG = [
           description: 'Run in mock mode without invoking LLM tokens',
           default: false,
         },
+        backend: {
+          type: 'string',
+          enum: ['auto', 'claude', 'opencode'],
+          description: 'Agent runtime backend (default auto = host-native)',
+        },
       },
       required: ['feature'],
     },
@@ -220,6 +244,11 @@ const TOOL_CATALOG = [
           description: 'Run in mock/dry-run mode without external API charges',
           default: false,
         },
+        backend: {
+          type: 'string',
+          enum: ['auto', 'claude', 'opencode'],
+          description: 'Agent runtime backend (default auto = host-native)',
+        },
       },
       required: ['objective'],
     },
@@ -253,6 +282,11 @@ const TOOL_CATALOG = [
           description: 'Run in mock mode without invoking LLM tokens',
           default: false,
         },
+        backend: {
+          type: 'string',
+          enum: ['auto', 'claude', 'opencode'],
+          description: 'Agent runtime backend (default auto = host-native)',
+        },
       },
       required: ['objective'],
     },
@@ -852,6 +886,12 @@ async function registerHostCommands(host) {
 
 async function registerHostTools(host) {
   if (typeof host?.tool?.transform !== 'function') return [];
+  // Accepted asymmetry (parity spec section 5): this plugin shape
+  // (command/tool transform + session hooks + event subscriptions) has no
+  // tool.execute.before registration point, so host webfetch/websearch calls
+  // cannot be intercepted the way Claude Code's hooks/hooks.json does.
+  // Steering lives in command templates (epistemic search first); a host API
+  // for pre-execution guards would close this for real.
   const registration = await host.tool.transform((draft) => {
     for (const [name, spec] of Object.entries(buildToolMap())) {
       draft.add({

package/plugins/opencode/tui.js

@@ -48,6 +48,68 @@ function readJson(file) {
   }
 }
 
+/** Config-derived status fields; nulls when config is absent/invalid. */
+function configFields(research) {
+  const out = { mode: null, searchEngine: null, maxIterations: null };
+  const cfg = readJson(path.join(research, 'config.json'));
+  if (cfg && typeof cfg === 'object') {
+    out.mode = cfg.mode ?? null;
+    out.searchEngine = cfg.search_engine ?? null;
+    out.maxIterations = cfg.max_iterations ?? null;
+  }
+  return out;
+}
+
+const REPORT_NAMES = [
+  'final_synthesis.md',
+  'brainstorm_report.md',
+  'code_audit_report.md',
+  'oss_scout_report.md',
+];
+
+/** Report files present in the workspace, with mtimes. */
+function presentReports(research) {
+  const reports = [];
+  for (const name of REPORT_NAMES) {
+    try {
+      const st = statSync(path.join(research, name));
+      reports.push({ name, mtimeMs: st.mtimeMs });
+    } catch {
+      /* absent report */
+    }
+  }
+  return reports;
+}
+
+/** Count of frontier nodes not yet settled/closed, or null when absent. */
+function openFrontierCount(research) {
+  const frontier = readJson(path.join(research, 'frontier.json'));
+  if (!frontier || typeof frontier !== 'object') return null;
+  const nodes = Array.isArray(frontier.nodes)
+    ? frontier.nodes
+    : Object.values(frontier.nodes || {});
+  return nodes.filter((n) => n && n.status !== 'settled' && n.status !== 'closed').length;
+}
+
+/** Degraded-claim counts from the ledger + requeue sidecar. */
+function degradedCounts(research) {
+  const out = { stale: 0, suspect: 0, requeued: 0 };
+  const ledger = readJson(path.join(research, 'ledger', 'claim_status.json'));
+  if (Array.isArray(ledger)) {
+    const last = new Map();
+    for (const e of ledger) {
+      if (e && typeof e.claim_id === 'string') last.set(e.claim_id, e.to_status);
+    }
+    for (const s of last.values()) {
+      if (s === 'STALE') out.stale += 1;
+      else if (s === 'SUSPECT') out.suspect += 1;
+    }
+  }
+  const requeue = readJson(path.join(research, 'requeue.json'));
+  if (Array.isArray(requeue)) out.requeued = requeue.length;
+  return out;
+}
+
 /**
  * Snapshot the workspace status. Pure fs reads; safe on missing workspace.
  * Exported for tests.
@@ -71,44 +133,10 @@ export function readSwarmStatus(root) {
   } catch {
     return status;
   }
-  const cfg = readJson(path.join(research, 'config.json'));
-  if (cfg && typeof cfg === 'object') {
-    status.mode = cfg.mode ?? null;
-    status.searchEngine = cfg.search_engine ?? null;
-    status.maxIterations = cfg.max_iterations ?? null;
-  }
-  for (const name of [
-    'final_synthesis.md',
-    'brainstorm_report.md',
-    'code_audit_report.md',
-    'oss_scout_report.md',
-  ]) {
-    try {
-      const st = statSync(path.join(research, name));
-      status.reports.push({ name, mtimeMs: st.mtimeMs });
-    } catch {
-      /* absent report */
-    }
-  }
-  const frontier = readJson(path.join(research, 'frontier.json'));
-  if (frontier && typeof frontier === 'object') {
-    const nodes = Array.isArray(frontier.nodes) ? frontier.nodes : Object.values(frontier.nodes || {});
-    const open = nodes.filter((n) => n && n.status !== 'settled' && n.status !== 'closed');
-    status.frontierOpen = open.length;
-  }
-  const ledger = readJson(path.join(research, 'ledger', 'claim_status.json'));
-  if (Array.isArray(ledger)) {
-    const last = new Map();
-    for (const e of ledger) {
-      if (e && typeof e.claim_id === 'string') last.set(e.claim_id, e.to_status);
-    }
-    for (const s of last.values()) {
-      if (s === 'STALE') status.stale += 1;
-      else if (s === 'SUSPECT') status.suspect += 1;
-    }
-  }
-  const requeue = readJson(path.join(research, 'requeue.json'));
-  if (Array.isArray(requeue)) status.requeued = requeue.length;
+  Object.assign(status, configFields(research));
+  status.reports = presentReports(research);
+  status.frontierOpen = openFrontierCount(research);
+  Object.assign(status, degradedCounts(research));
   return status;
 }
 

package/runner/claim_store.py

@@ -52,9 +52,15 @@ def _has_fts5(conn: sqlite3.Connection) -> bool:
 class ClaimStore:
     def __init__(self, base_dir: Path, db_path: Optional[Path] = None):
         self.base_dir = Path(os.path.realpath(str(base_dir)))
-        self.db_path = Path(os.path.realpath(str(db_path))) if db_path else (self.base_dir / "claims.sqlite")
+        self.db_path = (
+            Path(os.path.realpath(str(db_path)))
+            if db_path
+            else (self.base_dir / "claims.sqlite")
+        )
         self.db_path.parent.mkdir(parents=True, exist_ok=True)
-        self.conn = sqlite3.connect(str(self.db_path))
+        # uri=False is explicit: a plain filesystem path must never be
+        # interpreted as a SQLite URI connection string (S8706).
+        self.conn = sqlite3.connect(str(self.db_path), uri=False)
         self.conn.row_factory = sqlite3.Row
         self.fts5 = _has_fts5(self.conn)
         self._create_schema()
@@ -115,7 +121,10 @@ class ClaimStore:
             );
             """
         )
-        cur.execute("INSERT OR IGNORE INTO meta(key, value) VALUES ('schema_version', ?)", (str(SCHEMA_VERSION),))
+        cur.execute(
+            "INSERT OR IGNORE INTO meta(key, value) VALUES ('schema_version', ?)",
+            (str(SCHEMA_VERSION),),
+        )
         if self.fts5:
             cur.execute(
                 """
@@ -338,7 +347,9 @@ def reindex(base_dir: Path, store: Optional[ClaimStore] = None) -> Dict[str, Any
 
 def main(argv: Optional[List[str]] = None) -> int:
     parser = argparse.ArgumentParser(description="IUMBTEMS derived claim index")
-    parser.add_argument("--dir", default=".research", help="Path to .research workspace")
+    parser.add_argument(
+        "--dir", default=".research", help="Path to .research workspace"
+    )
     sub = parser.add_subparsers(dest="command")
     sub.add_parser("reindex", help="Rebuild claims.sqlite from flat files")
     search_p = sub.add_parser("search", help="Search claim statements")