@heretek-ai/epistemic-swarm 0.5.0 → 0.7.0

package/plugins/darkharvest/skills/darkharvest/scripts/harvest.py

@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""
+Darkharvest fetch helper: clone-to-temp + allowlisted scan + SHA-256 cache.
+
+Read-only. Never installs dependencies. Never writes outside .research/
+(except the temp clone, which is dropped). Enforces per-repo caps so
+`--max-repos 10 --depth 3` style defaults cannot OOM the host.
+
+Usage:
+  python3 skills/darkharvest/scripts/harvest.py --repo <url> [--show-context]
+  python3 skills/darkharvest/scripts/harvest.py --repo <url> --export <path>
+
+Closed / non-cloneable targets: prints a metadata-only stub with a
+[NEGATIVE_KNOWLEDGE] gap note instead of failing.
+"""
+
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent.parent
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from skills.research_cache.hasher import SourceHasher  # noqa: E402
+
+SKIP_DIRS = {
+    ".git",
+    "node_modules",
+    "__pycache__",
+    ".venv",
+    "venv",
+    "dist",
+    "build",
+    "target",
+    ".next",
+    ".research",
+    "coverage",
+}
+MANIFEST_FILES = [
+    "package.json",
+    "pyproject.toml",
+    "Cargo.toml",
+    "go.mod",
+    "requirements.txt",
+    "LICENSE",
+    "LICENSE.md",
+    "README.md",
+]
+TEXT_EXTS = {".md", ".json", ".toml", ".yaml", ".yml", ".txt", ".py", ".js", ".ts"}
+
+DEFAULT_MAX_FILES = 120
+DEFAULT_MAX_BYTES = 400_000
+DEFAULT_TIMEOUT = 120
+
+SPDX_MAP = {
+    "mit": "MIT",
+    "apache-2.0": "Apache-2.0",
+    "apache 2.0": "Apache-2.0",
+    "bsd-3-clause": "BSD-3-Clause",
+    "bsd 3-clause": "BSD-3-Clause",
+    "isc": "ISC",
+    "gpl": "GPL",
+    "agpl": "AGPL",
+    "mpl": "MPL",
+    "lgpl": "LGPL",
+}
+
+
+def sh(cmd, cwd=None, timeout=DEFAULT_TIMEOUT):
+    try:
+        r = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            cwd=str(cwd or PROJECT_ROOT),
+            timeout=timeout,
+        )
+        return r.returncode, (r.stdout or "").strip()
+    except Exception as exc:  # noqa: BLE001
+        return 1, f"error: {exc}"
+
+
+def detect_license(text):
+    low = (text or "").lower()
+    for key, spdx in SPDX_MAP.items():
+        if key in low:
+            return spdx
+    return "UNKNOWN"
+
+
+def scan_tree(root, max_files=DEFAULT_MAX_FILES, max_bytes=DEFAULT_MAX_BYTES):
+    entries = []
+    total_bytes = 0
+    manifests = {}
+    license_text = ""
+    readme_head = ""
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        rel = Path(dirpath).relative_to(root)
+        depth = len(rel.parts) if str(rel) != "." else 0
+        if depth > 3:
+            dirnames[:] = []
+            continue
+        for f in sorted(filenames):
+            if len(entries) >= max_files or total_bytes >= max_bytes:
+                return entries, manifests, license_text, readme_head, True
+            fp = Path(dirpath) / f
+            try:
+                size = fp.stat().st_size
+            except OSError:
+                continue
+            if size > 100_000:
+                continue
+            rel_p = str(rel / f) if str(rel) != "." else f
+            entries.append(rel_p)
+            if f in MANIFEST_FILES or Path(f).suffix in TEXT_EXTS:
+                try:
+                    content = fp.read_text(encoding="utf-8", errors="replace")
+                except OSError:
+                    continue
+                total_bytes += len(content.encode("utf-8", errors="replace"))
+                if f in MANIFEST_FILES and f not in manifests:
+                    manifests[f] = content[:4000]
+                if f.lower().startswith("license") and not license_text:
+                    license_text = content[:4000]
+                if f.lower() == "readme.md" and not readme_head:
+                    readme_head = content[:4000]
+    return entries, manifests, license_text, readme_head, False
+
+
+def harvest_repo(
+    url,
+    max_files=DEFAULT_MAX_FILES,
+    max_bytes=DEFAULT_MAX_BYTES,
+    timeout=DEFAULT_TIMEOUT,
+    base_dir=".research",
+):
+    started = datetime.now(timezone.utc).isoformat()
+    tmp = tempfile.mkdtemp(prefix="darkharvest-")
+    try:
+        code, out = sh(["git", "clone", "--depth", "1", url, tmp], timeout=timeout)
+        if code != 0:
+            return {
+                "url": url,
+                "status": "metadata-only",
+                "generated_at": started,
+                "negative_knowledge": (
+                    f"[NEGATIVE_KNOWLEDGE: clone failed for {url}; "
+                    f"used metadata-only row. Detail: {out[:200]}]"
+                ),
+            }
+        entries, manifests, license_text, readme_head, truncated = scan_tree(
+            Path(tmp), max_files=max_files, max_bytes=max_bytes
+        )
+        spdx = detect_license(license_text + manifests.get("package.json", ""))
+        harvestable = (
+            "depend-or-vendor"
+            if spdx in ("MIT", "Apache-2.0", "BSD-3-Clause", "ISC")
+            else "clean-room-rebuild-only"
+        )
+        hasher = SourceHasher(Path(base_dir))
+        cache_blob = (
+            f"# {url}\n\nSPDX: {spdx}\n\n"
+            f"## README head\n{readme_head[:2000]}\n\n"
+            f"## Tree sample ({len(entries)} entries)\n" + "\n".join(entries[:60])
+        )
+        source_hash = hasher.store_source(url, cache_blob, f"Darkharvest {url}")
+        warnings = []
+        if spdx in ("GPL", "AGPL"):
+            warnings.append(
+                "⚠️ LICENSE: strong copyleft — spec rebuild only, never vendor"
+            )
+        elif spdx == "UNKNOWN":
+            warnings.append("⚠️ LICENSE: unknown — treat as clean-room-rebuild-only")
+        if truncated:
+            warnings.append(
+                "⚠️ SCAN: truncated by file/byte caps; treat as partial evidence"
+            )
+        return {
+            "url": url,
+            "status": "scanned",
+            "generated_at": started,
+            "spdx": spdx,
+            "harvest_policy": harvestable,
+            "tree_entries": len(entries),
+            "truncated": truncated,
+            "source_hash": source_hash,
+            "readme_head": readme_head[:1500],
+            "manifests_seen": sorted(manifests.keys()),
+            "warnings": warnings,
+        }
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Darkharvest competitor fetch helper")
+    ap.add_argument("--repo", required=True, help="Competitor repo URL to scan")
+    ap.add_argument("--show-context", action="store_true")
+    ap.add_argument("--export", default="")
+    ap.add_argument("--max-files", type=int, default=DEFAULT_MAX_FILES)
+    ap.add_argument("--max-bytes", type=int, default=DEFAULT_MAX_BYTES)
+    ap.add_argument("--timeout", type=int, default=DEFAULT_TIMEOUT)
+    ap.add_argument("--dir", default=".research")
+    args = ap.parse_args()
+
+    if not re.match(r"^https?://", args.repo):
+        print(f"WARN: {args.repo} is not an http(s) URL; metadata-only stub emitted.")
+        result = {
+            "url": args.repo,
+            "status": "metadata-only",
+            "generated_at": datetime.now(timezone.utc).isoformat(),
+            "negative_knowledge": (
+                f"[NEGATIVE_KNOWLEDGE: non-cloneable target {args.repo}]"
+            ),
+        }
+    else:
+        result = harvest_repo(
+            args.repo,
+            max_files=args.max_files,
+            max_bytes=args.max_bytes,
+            timeout=args.timeout,
+            base_dir=args.dir,
+        )
+
+    if args.show_context or not args.export:
+        print(f"\n🌑 [Darkharvest] {result['url']} → {result['status']}")
+        for key in ("spdx", "harvest_policy", "tree_entries", "source_hash"):
+            if key in result:
+                print(f"  {key}: {result[key]}")
+        for w in result.get("warnings", []):
+            print(f"  {w}")
+        if result.get("negative_knowledge"):
+            print(f"  {result['negative_knowledge'][:200]}")
+
+    if args.export:
+        out = Path(os.path.realpath(args.export))
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(json.dumps(result, indent=2), encoding="utf-8")
+        print(f"✅ Harvest scan exported to {out}")
+
+
+if __name__ == "__main__":
+    main()

package/plugins/factory/.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "factory",
+  "version": "0.1.0",
+  "description": "Coding-factory Manager loop with grill-gated phased builds and dual QA for Claude Code.",
+  "author": {
+    "name": "Heretek AI",
+    "email": "dev@heretek.ai"
+  },
+  "license": "Apache-2.0",
+  "repository": "https://github.com/Heretek-AI/IUMBTEMS",
+  "homepage": "https://github.com/Heretek-AI/IUMBTEMS#readme",
+  "skills": [
+    "./skills/factory"
+  ]
+}

package/plugins/factory/agents/factory-manager.md

@@ -0,0 +1,22 @@
+---
+name: factory-manager
+description: Coding-factory Manager. Owns grill gates, swarm dispatch, roadmap synthesis, and QA tiebreaks. Never writes code. Use to drive /factory runs.
+model: sonnet
+---
+
+You are the Factory Manager in the factory plugin.
+
+Loop: grill the user until `.factory/frontier.json` is settled (max 5
+brainstorm+darkharvest swarm cycles per gate); explicit user approve advances
+each gate. Per gate, dispatch both swarms (mock-first on fixtures), then
+synthesize `.roadmap/<phase>/` as GOAL.md plus dossier.json
+(goal/evidence/acceptance/brief/verdict/hashes — every claim needs a VERIFIED
+hash or file pointer). Spawn the programmer subagent per phase with the phase
+dossier (cite phase hashes). Run qa-a and qa-b per phase; track retries with
+`skills/factory/scripts/factory.py` (3 failures escalate back to you with both
+QA reports). Tiebreak QA disagreements; require explicit user sign-off per phase.
+
+Never write implementation code yourself. Never bypass gates outside an
+active `/domainexpansion` count. Never accept unverified harvest verdicts.
+
+Full specification: `skills/factory/SKILL.md` in the plugin root.

package/plugins/factory/agents/programmer.md

@@ -0,0 +1,16 @@
+---
+name: programmer
+description: Factory implementer. Implements exactly one phase brief per spawn and cites phase evidence hashes. Never invokes swarms or other programmers. Use per .roadmap phase.
+model: sonnet
+---
+
+You are the Factory Programmer in the factory plugin.
+
+You receive one phase dossier (GOAL.md + dossier.json). Implement exactly what
+the brief specifies — no scope expansion, no drive-by refactors. Cite the
+phase evidence hashes for any borrowed pattern. If the brief is ambiguous or
+its acceptance criteria are untestable, stop and return questions to the
+manager instead of guessing. Never invoke brainstorm/darkharvest swarms, never
+spawn other agents, never edit outside the phase scope.
+
+Full specification: `skills/factory/SKILL.md` in the plugin root.

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

@@ -0,0 +1,17 @@
+---
+name: qa-adversarial
+description: Factory QA, adversarial seat. Hunts edge cases, regressions, and acceptance loopholes the functional pass missed. Read-only plus test execution. Use alongside qa-functional per phase.
+model: sonnet
+---
+
+You are QA-B (adversarial seat) in the factory plugin.
+
+Assume the functional pass missed something. Attack the phase: edge-case
+inputs, regressions in neighboring behavior, acceptance criteria that are
+vacuously satisfiable, error paths, and resource/timeout boundaries. Read-only
+plus test execution — never edit code. Verdicts: `pass | fail(reason) |
+conditional(note)`, each with a reproduction. Your prompt is deliberately
+diverged from qa-functional: it proves what works, you hunt what breaks.
+Disagreements go to the factory-manager tiebreak.
+
+Full specification: `skills/factory/SKILL.md` in the plugin root.

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 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/plugins/gemini/commands/domainexpansion.toml

@@ -0,0 +1,7 @@
+description = "Autonomous agent-guided self-improvement loop (count-flagged)"
+prompt = """Run the IUMBTEMS domain-expansion loop for {{args}} loops (max 10).
+
+Bypasses per-loop gates; stops on count OR .factory/STOP file OR user kill.
+Each loop: agents propose direction, quick swarm check, implement, dual-QA verify.
+Enforce via: python3 skills/factory/scripts/factory.py expansion --run <run> --loops {{args}}.
+"""

package/plugins/gemini/commands/factory.toml

@@ -0,0 +1,8 @@
+description = "Coding-factory Manager loop with grill-gated phased builds"
+prompt = """Run the IUMBTEMS coding-factory Manager loop for: {{args}}.
+
+1. Grill until .factory/frontier.json is settled (max 5 swarm cycles per gate); explicit user approve advances each gate.
+2. Per gate: python3 runner/research_swarm.py --mode brainstorm plus --mode darkharvest (mock-first), then synthesize .roadmap/<phase>/ GOAL.md + dossier.json.
+3. Programmer subagent per phase; qa-a plus qa-b per phase; retries via python3 skills/factory/scripts/factory.py (3 failures escalate).
+Report: .roadmap/ phases plus .factory/state.json.
+"""

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

@@ -0,0 +1,13 @@
+# Factory (thin adapter stub)
+
+This file is a POINTER, not the implementation. It exists so harness skill
+discovery finds an entry; the real skill lives in the IUMBTEMS repo.
+
+- Canonical prose & scripts: `skills/factory/`
+- Canonical programmatic surface: `python3 runner/mcp_server.py` (stdio MCP),
+  or one-shot: `python3 runner/mcp_server.py call <tool> '{...json...}'`
+- MCP tools for this skill: `iumbtems_brainstorm`, `iumbtems_darkharvest`, `iumbtems_socratic_frontier`
+
+Epistemic rules apply regardless of harness: tag claims as
+`[VERIFIED: <hash>]`, `[INFERRED: <reasoning>]`, `[HYPOTHESIS: <test>]`, or
+`[NEGATIVE_KNOWLEDGE: <query>]`. Writes go only to `.research/`.