@heretek-ai/epistemic-swarm 0.6.0 → 0.7.0

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 i 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/runner/tests/test_claude_plugin.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""Tests for Claude Code plugin surfaces: manifests, agents, modular sync, evals.
+
+Per https://code.claude.com/docs/en/plugins/create (manifest + layout),
+/components (skills/agents/hooks/MCP), and /plugin-evals (suite layout).
+Behavioral eval runs are billable and stay in CI (plugin-evals.yml); here we
+assert suite structure only.
+"""
+
+import json
+import unittest
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
+if str(PROJECT_ROOT) not in __import__("sys").path:
+    __import__("sys").path.insert(0, str(PROJECT_ROOT))
+
+MODULAR = {
+    "socratic-grilling": "grilling",
+    "research-cache": "research_cache",
+    "darkharvest": "darkharvest",
+    "factory": "factory",
+}
+
+
+def parse_frontmatter(path):
+    text = Path(path).read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return {}
+    end = text.find("---", 3)
+    if end < 0:
+        return {}
+    data = {}
+    for line in text[3:end].strip().splitlines():
+        if ":" in line:
+            k, v = line.split(":", 1)
+            data[k.strip()] = v.strip()
+    return data
+
+
+class TestClaudeManifests(unittest.TestCase):
+    def test_root_manifest_lists_all_nine_skills(self):
+        manifest = json.loads(
+            (PROJECT_ROOT / ".claude-plugin" / "plugin.json").read_text()
+        )
+        self.assertEqual(manifest["name"], "epistemic-swarm")
+        for skill in (
+            "grilling",
+            "research_cache",
+            "epistemic_search",
+            "swarm_config",
+            "code_audit",
+            "oss_scout",
+            "brainstorming",
+            "darkharvest",
+            "factory",
+        ):
+            self.assertIn(f"./skills/{skill}", manifest["skills"])
+
+    def test_marketplace_entries_resolve(self):
+        marketplace = json.loads(
+            (PROJECT_ROOT / ".claude-plugin" / "marketplace.json").read_text()
+        )
+        names = [p["name"] for p in marketplace["plugins"]]
+        for name in (
+            "epistemic-swarm",
+            "socratic-grilling",
+            "research-cache",
+            "darkharvest",
+            "factory",
+        ):
+            self.assertIn(name, names)
+        for plugin in marketplace["plugins"]:
+            if plugin["name"] == "epistemic-swarm":
+                continue
+            plugin_json = (
+                PROJECT_ROOT
+                / plugin["source"].lstrip("./")
+                / ".claude-plugin"
+                / "plugin.json"
+            )
+            self.assertTrue(plugin_json.is_file(), f"missing {plugin_json}")
+            data = json.loads(plugin_json.read_text())
+            self.assertEqual(data["name"], plugin["name"])
+
+    def test_modular_skills_in_sync(self):
+        for mod, skill in MODULAR.items():
+            src = PROJECT_ROOT / "skills" / skill
+            dst = PROJECT_ROOT / "plugins" / mod / "skills" / skill
+            self.assertTrue((dst / "SKILL.md").is_file(), f"missing {dst}")
+            src_files = {
+                p.relative_to(src)
+                for p in src.rglob("*")
+                if p.is_file() and "__pycache__" not in p.parts
+            }
+            dst_files = {
+                p.relative_to(dst)
+                for p in dst.rglob("*")
+                if p.is_file() and "__pycache__" not in p.parts
+            }
+            self.assertEqual(src_files, dst_files, f"drift in {mod}")
+            for rel in src_files:
+                self.assertEqual(
+                    (src / rel).read_bytes(),
+                    (dst / rel).read_bytes(),
+                    f"content drift: {mod}/{rel}",
+                )
+
+
+class TestClaudeAgents(unittest.TestCase):
+    AGENTS = {
+        "agents/alpha-thesis.md": "alpha-thesis",
+        "agents/beta-antithesis.md": "beta-antithesis",
+        "agents/epistemic-auditor.md": "epistemic-auditor",
+        "plugins/darkharvest/agents/harvest-proponent.md": "harvest-proponent",
+        "plugins/darkharvest/agents/harvest-redteam.md": "harvest-redteam",
+        "plugins/factory/agents/factory-manager.md": "factory-manager",
+        "plugins/factory/agents/programmer.md": "programmer",
+        "plugins/factory/agents/qa-functional.md": "qa-functional",
+        "plugins/factory/agents/qa-adversarial.md": "qa-adversarial",
+    }
+
+    def test_agent_frontmatter(self):
+        for rel, expected_name in self.AGENTS.items():
+            fm = parse_frontmatter(PROJECT_ROOT / rel)
+            self.assertEqual(fm.get("name"), expected_name, rel)
+            self.assertTrue(fm.get("description"), f"no description: {rel}")
+            self.assertIn("model", fm, f"no model: {rel}")
+            for banned in ("permissionMode", "hooks", "mcpServers", "initialPrompt"):
+                self.assertNotIn(banned, fm, f"banned field in {rel}")
+
+
+class TestClaudeEvals(unittest.TestCase):
+    CASES = {
+        "evals/grill-fires": "grilling",
+        "evals/darkharvest-fires": "darkharvest",
+        "evals/factory-gate": "factory",
+        "plugins/darkharvest/evals/teardown-verdict": "darkharvest",
+        "plugins/factory/evals/gate-halt": "factory",
+    }
+
+    def test_eval_suite_structure(self):
+        for case, skill in self.CASES.items():
+            prompt = PROJECT_ROOT / case / "prompt.md"
+            self.assertTrue(prompt.is_file(), f"missing {prompt}")
+            body = prompt.read_text(encoding="utf-8")
+            self.assertIn("allowed_tools", body)
+            graders = sorted((PROJECT_ROOT / case / "graders").glob("*.md"))
+            self.assertTrue(graders, f"no graders in {case}")
+            kinds = set()
+            for g in graders:
+                fm = parse_frontmatter(g)
+                self.assertIn(
+                    fm.get("type"),
+                    (
+                        "tool_used",
+                        "llm",
+                        "regex",
+                        "tool_order",
+                        "file_exists",
+                        "baseline",
+                    ),
+                    f"bad type in {g}",
+                )
+                kinds.add(fm.get("type"))
+            self.assertIn("tool_used", kinds, f"no Skill-fired grader in {case}")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/scripts/build_adapters.py

@@ -43,6 +43,17 @@ CANONICAL_SKILLS = [
     "factory",
 ]
 
+# Modular Claude Code plugins mirror canonical skills as full copies (Claude
+# Code loads plugin-local skills/, not the repo skills/ tree). Rule: copies
+# are generated — never hand-edit under plugins/<mod>/skills/. Rebuild with
+# `python3 scripts/build_adapters.py`; `--check` fails CI on drift.
+MODULAR_PLUGINS = {
+    "socratic-grilling": "grilling",
+    "research-cache": "research_cache",
+    "darkharvest": "darkharvest",
+    "factory": "factory",
+}
+
 # Skill -> the MCP tool(s) that now carry its programmatic surface.
 SKILL_TOOLS = {
     "grilling": ["iumbtems_socratic_frontier"],
@@ -133,9 +144,66 @@ def build():
             if _build_skill_stub(target_base, skill):
                 count += 1
     print(f"✅ Built {count} thin skill stubs across {len(TARGETS)} targets.")
+    synced = sync_modular_plugins()
+    print(f"✅ Synced {synced} modular Claude Code plugin skill copies.")
     return 0
 
 
+def _iter_modular_files(src: Path, dst: Path):
+    """Yield (relpath, src_bytes|None, dst_bytes|None) for sync/check."""
+    src_files = {}
+    for p in sorted(src.rglob("*")):
+        if p.is_file() and "__pycache__" not in p.parts:
+            src_files[p.relative_to(src)] = p
+    dst_files = {}
+    if dst.exists():
+        for p in sorted(dst.rglob("*")):
+            if p.is_file() and "__pycache__" not in p.parts:
+                dst_files[p.relative_to(dst)] = p
+    for rel in sorted(set(src_files) | set(dst_files)):
+        s = src_files.get(rel)
+        d = dst_files.get(rel)
+        yield rel, (s.read_bytes() if s else None), (d.read_bytes() if d else None)
+
+
+def sync_modular_plugins() -> int:
+    synced = 0
+    for mod, skill in MODULAR_PLUGINS.items():
+        src = PROJECT_ROOT / "skills" / skill
+        dst = PROJECT_ROOT / "plugins" / mod / "skills" / skill
+        if not (src / SKILL_FILENAME).exists():
+            print(f"[WARN] canonical skill missing: skills/{skill}", file=sys.stderr)
+            continue
+        if dst.exists():
+            shutil.rmtree(dst)
+        dst.mkdir(parents=True, exist_ok=True)
+        for rel, content, _ in _iter_modular_files(src, dst):
+            if content is None:
+                continue
+            out = dst / rel
+            out.parent.mkdir(parents=True, exist_ok=True)
+            out.write_bytes(content)
+            shutil.copymode(src / rel, out)
+        synced += 1
+    return synced
+
+
+def _check_modular_plugins() -> List[str]:
+    errors = []
+    for mod, skill in MODULAR_PLUGINS.items():
+        src = PROJECT_ROOT / "skills" / skill
+        dst = PROJECT_ROOT / "plugins" / mod / "skills" / skill
+        if not dst.exists():
+            errors.append(f"MISSING modular copy: plugins/{mod}/skills/{skill}/")
+            continue
+        for rel, s_bytes, d_bytes in _iter_modular_files(src, dst):
+            if s_bytes is None:
+                errors.append(f"STRAY FILE in plugins/{mod}/skills/{skill}/{rel}")
+            elif s_bytes != d_bytes:
+                errors.append(f"OUT OF SYNC: plugins/{mod}/skills/{skill}/{rel}")
+    return errors
+
+
 def _check_skill_stub(target_rel: str, skill: str) -> List[str]:
     errors = []
     dst = PROJECT_ROOT / target_rel / skill / SKILL_FILENAME
@@ -176,6 +244,7 @@ def check():
     for target_rel, _mode in TARGETS:
         for skill in CANONICAL_SKILLS:
             errors.extend(_check_skill_stub(target_rel, skill))
+    errors.extend(_check_modular_plugins())
     errors.extend(_check_package_json())
     if errors:
         print("❌ Adapter check failed:")