@heretek-ai/epistemic-swarm 0.5.0 → 0.6.0

package/.agents/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/`.

package/.omp/commands/domainexpansion.md

@@ -0,0 +1,9 @@
+---
+description: Autonomous agent-guided self-improvement loop (count-flagged)
+---
+
+Run the IUMBTEMS domain-expansion loop for `$1` 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 $1`.

package/.omp/commands/factory.md

@@ -0,0 +1,9 @@
+---
+description: Coding-factory Manager loop with grill-gated phased builds
+---
+
+Run the IUMBTEMS coding-factory Manager loop for `$1`:
+
+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 tracked via `python3 skills/factory/scripts/factory.py` (3 failures escalate).

package/README.md

@@ -149,6 +149,13 @@ iumbtems brainstorm "Where do we go from here?"
 # Product competitor teardown with per-feature harvest verdicts
 iumbtems darkharvest "Paseo-class agent harness competitor" --seeds https://github.com/a/b,https://github.com/c/d --max-repos 6 --mock-claude
 
+# Coding-factory run-state helper (init, phase-add, qa-record, expansion, stop)
+iumbtems factory init --run arena
+iumbtems factory phase-add --run arena --phase 01-handoff --goal "Session handoff" --accept "round-trips;STOP kills loop"
+iumbtems factory expansion --run arena --loops 10
+
+# OpenCode slash commands (also Pi/OMP/Gemini): /factory, /domainexpansion, /darkharvest, /scout, /audit, /grill, /swarm
+
 # Run Socratic grilling and decision frontier calculation
 iumbtems grill --objective "L1 vs L2 state verification trade-offs"
 
@@ -164,6 +171,8 @@ iumbtems test
 - **`/code-audit`**: Dialectic codebase review pairing a Structural Architect (thesis) with a Vulnerability Red-Teamer (antithesis) enforcing line-number proofs (`file:///path#L10-25`).
 - **`/oss-scout`**: Evaluates GitHub repositories, package ecosystems (npm, crates.io, PyPI), license contamination (GPL/AGPL copyleft vs MIT/Apache), and outputs clean-room re-implementation blueprints.
 - **`/darkharvest`**: Product competitor teardown (seed inspirations + prompt, expand to adjacents). Competitor × capability matrix, both-ways white-space gaps, per-feature `depend|vendor|clean-room-rebuild|skip` verdicts with SPDX attribution. Permissive-only vendoring; GPL/AGPL spec-rebuild only.
+- **`/factory`**: Coding-factory Manager loop — grill-gated phased build (manager profile), per-phase programmer spawns, dual QA (3 retries then escalate), explicit sign-off per phase.
+- **`/domainexpansion`**: Autonomous agent-guided self-improvement loop (`/domainexpansion <n>`, max 10); bypasses gates, stops on count OR `.factory/STOP` OR user kill.
 - **`/grilling`**: Socratic assumption-inversion and Matt Pocock-style design tree frontier discovery.
 - **`epistemic_search`**: Zero-key DuckDuckGo Lite search and content-addressed fetch with automatic SHA-256 caching.
 

package/bin/cli.js

@@ -50,6 +50,7 @@ Commands:
   run "<objective>"     Run the dialectic multi-agent research swarm
   brainstorm "<prompt>"  Run lateral brainstorming (feature vectors + spikes)
   darkharvest "<arena>"  Product competitor teardown with harvest verdicts
+  factory <subcommand>  Factory run-state helper (init, phase-add, qa-record, expansion, stop)
   grill                 Launch interactive Socratic decision tree framing
   adapters              Rebuild harness adapter mirrors (skills -> plugins/*, .agents)
   install               Install skills & MCP servers into ~/.claude/
@@ -82,6 +83,7 @@ Examples:
   iumbtems run "Verify sub-millisecond ZK prover latency"
   iumbtems brainstorm "Where do we go from here?"
   iumbtems darkharvest "Paseo-class agent harness competitor" --seeds https://github.com/a/b,https://github.com/c/d --max-repos 6 --mock-claude
+  iumbtems factory init --run arena && iumbtems factory phase-add --run arena --phase 01-x --goal "..." --accept "a;b"
   iumbtems grill --objective "Rollup architecture trade-offs"
   iumbtems doctor
 `);
@@ -174,6 +176,25 @@ switch (command) {
     break;
   }
 
+  case 'factory': {
+    // Factory run-state helper: forward subcommands to skills/factory/scripts/factory.py
+    // e.g. iumbtems factory init --run arena
+    //      iumbtems factory qa-record --run arena --phase 01-x --seat qa-a --verdict pass
+    if (args[1] === '--help' || !args[1]) {
+      console.log([
+        'Usage: iumbtems factory <init|phase-add|qa-record|expansion|stop> [options]',
+        '  init --run <name>',
+        '  phase-add --run <name> --phase <id> --goal "<goal>" --accept "a;b"',
+        '  qa-record --run <name> --phase <id> --seat <qa-a|qa-b> --verdict <pass|fail|conditional> [--reason "..."]',
+        '  expansion --run <name> --loops <n> [--max-loops 10]',
+        '  stop --run <name>   (writes .factory/STOP kill-file)',
+      ].join('\n'));
+      break;
+    }
+    runPython('skills/factory/scripts/factory.py', args.slice(1));
+    break;
+  }
+
   case 'grill': {
     runPython('skills/grilling/socratic_tree.py', args.slice(1));
     break;

package/config/opencode-snippet.json

@@ -99,6 +99,92 @@
         "iumbtems_verify_quote": true,
         "iumbtems_config": true
       }
+    },
+    "manager": {
+      "description": "IUMBTEMS Factory Manager: grill-gated phased builds. Owns gates, swarm dispatch, roadmap synthesis, QA tiebreaks. Never writes code.",
+      "mode": "primary",
+      "temperature": 0.2,
+      "permission": {
+        "edit": "deny",
+        "bash": "ask",
+        "task": {
+          "*": "deny",
+          "factory-*": "allow",
+          "programmer": "allow",
+          "qa-a": "allow",
+          "qa-b": "allow",
+          "brainstormer": "allow",
+          "darkharvester": "allow"
+        }
+      },
+      "tools": {
+        "read": true,
+        "write": true,
+        "grep": true,
+        "glob": true,
+        "task": true,
+        "iumbtems_brainstorm": true,
+        "iumbtems_darkharvest": true,
+        "iumbtems_verify_quote": true,
+        "iumbtems_socratic_frontier": true,
+        "iumbtems_config": true
+      }
+    },
+    "programmer": {
+      "description": "IUMBTEMS Factory Programmer: implements exactly one phase brief per spawn. Cites phase evidence hashes. Never invokes swarms or other programmers.",
+      "mode": "subagent",
+      "temperature": 0.3,
+      "permission": {
+        "edit": "allow",
+        "bash": "ask",
+        "task": {
+          "*": "deny"
+        }
+      },
+      "tools": {
+        "read": true,
+        "write": true,
+        "bash": true,
+        "grep": true,
+        "glob": true,
+        "iumbtems_verify_quote": true
+      }
+    },
+    "qa-a": {
+      "description": "IUMBTEMS Factory QA (functional): verifies phase acceptance criteria pass on the real surface. Read-only plus test execution. Diverged prompt from qa-b.",
+      "mode": "subagent",
+      "temperature": 0.1,
+      "permission": {
+        "edit": "deny",
+        "bash": "ask",
+        "task": {
+          "*": "deny"
+        }
+      },
+      "tools": {
+        "read": true,
+        "bash": true,
+        "grep": true,
+        "glob": true
+      }
+    },
+    "qa-b": {
+      "description": "IUMBTEMS Factory QA (adversarial): hunts edge cases, regressions, and acceptance loopholes the functional pass missed. Read-only plus test execution. Diverged prompt from qa-a.",
+      "mode": "subagent",
+      "temperature": 0.4,
+      "permission": {
+        "edit": "deny",
+        "bash": "ask",
+        "task": {
+          "*": "deny"
+        }
+      },
+      "tools": {
+        "read": true,
+        "bash": true,
+        "grep": true,
+        "glob": true
+      }
     }
   },
   "skills": {
@@ -110,7 +196,8 @@
       "./skills/code_audit",
       "./skills/oss_scout",
       "./skills/brainstorming",
-      "./skills/darkharvest"
+      "./skills/darkharvest",
+      "./skills/factory"
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "IUMBTEMS: I Use My Brain To Express My Self — High-Integrity Dialectic Research Agent Harness for Claude Code, OpenCode V2, Pi, OMP (oh-my-pi), Gemini CLI, Codex CLI, and AntiGravity",
   "main": "bin/cli.js",
   "bin": {
@@ -80,7 +80,8 @@
       "./skills/code_audit",
       "./skills/oss_scout",
       "./skills/brainstorming",
-      "./skills/darkharvest"
+      "./skills/darkharvest",
+      "./skills/factory"
     ],
     "prompts": [
       "./prompts/*.md"
@@ -98,7 +99,8 @@
       "./skills/code_audit",
       "./skills/oss_scout",
       "./skills/brainstorming",
-      "./skills/darkharvest"
+      "./skills/darkharvest",
+      "./skills/factory"
     ],
     "prompts": [
       "./prompts/*.md"

package/plugins/antigravity/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/`.

package/plugins/codex/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/`.

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/`.

package/plugins/opencode/index.js

@@ -512,6 +512,37 @@ export const OPENCODE_COMMANDS = [
       '3. Legal rule: permissive-only vendor; GPL/AGPL clean-room-rebuild only; workflows clonable, assets never.',
     ].join('\n'),
   },
+  {
+    name: 'factory',
+    description: 'Coding-factory Manager loop: grill-gated phased build with programmer spawns and dual QA',
+    usage: '/factory <product-arena>',
+    agent: 'manager',
+    subtask: false,
+    template: [
+      'Run the IUMBTEMS coding-factory Manager loop as the manager agent.',
+      'Arena: $ARGUMENTS',
+      'If $ARGUMENTS is empty, ask the user what to build first; never proceed on placeholder input.',
+      '1. Grill the user until .factory/frontier.json is settled (max 5 brainstorm+darkharvest swarm cycles per gate); explicit user approve advances each gate.',
+      '2. Per gate run iumbtems_brainstorm and iumbtems_darkharvest (mock_mode only for dry runs), then synthesize .roadmap/<phase>/ GOAL.md + dossier.json (goal/evidence/acceptance/brief/verdict/hashes; every claim needs a VERIFIED hash).',
+      '3. Spawn the programmer subagent per phase with the phase dossier (cite phase hashes); run qa-a and qa-b (diverged prompts) per phase; track retries with skills/factory/scripts/factory.py (3 failures escalate to manager).',
+      '4. Manager tiebreaks QA disagreements; explicit user sign-off closes each phase.',
+    ].join('\n'),
+  },
+  {
+    name: 'domainexpansion',
+    description: 'Autonomous agent-guided self-improvement loop over the codebase (count-flagged)',
+    usage: '/domainexpansion <n>',
+    agent: 'manager',
+    subtask: false,
+    template: [
+      'Run the IUMBTEMS domain-expansion loop as the manager agent.',
+      'Loops: $ARGUMENTS (integer count, max 10)',
+      'If $ARGUMENTS is not a positive integer, ask the user for the loop count first.',
+      '1. Bypass per-loop gates; stop on count OR .factory/STOP file OR user kill, whichever first (enforce via skills/factory/scripts/factory.py expansion).',
+      '2. Each loop: agents propose direction, quick iumbtems_brainstorm/iumbtems_darkharvest check, implement via programmer spawn, dual-QA verify.',
+      '3. All expansion proposals carry the strict VERIFIED evidence bar; log every loop to .factory/state.json.',
+    ].join('\n'),
+  },
 ];
 
 /**
@@ -527,6 +558,8 @@ export function commandCatalog() {
   for (const cmd of OPENCODE_COMMANDS) {
     if (!cmd?.name) continue;
     out[cmd.name] = { description: cmd.description, template: cmd.template };
+    if (cmd.agent) out[cmd.name].agent = cmd.agent;
+    if (cmd.subtask !== undefined) out[cmd.name].subtask = cmd.subtask;
   }
   return out;
 }
@@ -785,6 +818,8 @@ async function registerHostCommands(host) {
       draft.add({
         name: cmd.name,
         description: cmd.description,
+        ...(cmd.agent ? { agent: cmd.agent } : {}),
+        ...(cmd.subtask !== undefined ? { subtask: cmd.subtask } : {}),
         execute: async (input) => {
           const args = input?.prompt?.text || '';
           const prompt = (typeof input?.prompt === 'object' && input?.prompt !== null) ? input.prompt : {};

package/runner/tests/test_factory.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""Tests for the factory loop: run-state helper, QA retry bounds, plugin surface."""
+
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+
+def run_node(code):
+    return subprocess.run(
+        ["node", "--input-type=module", "-e", code],
+        capture_output=True,
+        text=True,
+        cwd=str(PROJECT_ROOT),
+    )
+
+
+def last_json_object(stdout):
+    lines = [l.strip() for l in stdout.strip().split("\n") if l.strip().startswith("{")]
+    return json.loads(lines[-1])
+
+
+class TestFactoryHelper(unittest.TestCase):
+    def test_qa_retry_escalates_after_three(self):
+        import shutil
+
+        with tempfile.TemporaryDirectory() as tmp:
+            # Redirect factory state + roadmap into tmp via cwd-independent paths:
+            # factory.py anchors to PROJECT_ROOT, so sandbox by copying is
+            # overkill — exercise the pure bound logic through CLI on a run
+            # name, then clean up the created dirs.
+            run = "test-escalation-run"
+            try:
+                subprocess.run(
+                    [
+                        sys.executable,
+                        "skills/factory/scripts/factory.py",
+                        "init",
+                        "--run",
+                        run,
+                    ],
+                    check=True,
+                    capture_output=True,
+                    cwd=str(PROJECT_ROOT),
+                )
+                subprocess.run(
+                    [
+                        sys.executable,
+                        "skills/factory/scripts/factory.py",
+                        "phase-add",
+                        "--run",
+                        run,
+                        "--phase",
+                        "01-x",
+                        "--goal",
+                        "g",
+                        "--accept",
+                        "a",
+                    ],
+                    check=True,
+                    capture_output=True,
+                    cwd=str(PROJECT_ROOT),
+                )
+                codes = []
+                for _ in range(3):
+                    r = subprocess.run(
+                        [
+                            sys.executable,
+                            "skills/factory/scripts/factory.py",
+                            "qa-record",
+                            "--run",
+                            run,
+                            "--phase",
+                            "01-x",
+                            "--seat",
+                            "qa-a",
+                            "--verdict",
+                            "fail",
+                            "--reason",
+                            "t",
+                        ],
+                        capture_output=True,
+                        cwd=str(PROJECT_ROOT),
+                    )
+                    codes.append(r.returncode)
+                self.assertEqual(codes, [0, 0, 2])  # 3rd failure escalates
+                state = json.loads(
+                    (PROJECT_ROOT / ".factory" / run / "state.json").read_text()
+                )
+                self.assertEqual(state["phases"]["01-x"]["status"], "escalated")
+            finally:
+                shutil.rmtree(PROJECT_ROOT / ".factory" / run, ignore_errors=True)
+                shutil.rmtree(PROJECT_ROOT / ".roadmap" / "01-x", ignore_errors=True)
+
+    def test_expansion_respects_stop_file(self):
+        import shutil
+
+        run = "test-expansion-run"
+        try:
+            subprocess.run(
+                [
+                    sys.executable,
+                    "skills/factory/scripts/factory.py",
+                    "init",
+                    "--run",
+                    run,
+                ],
+                check=True,
+                capture_output=True,
+                cwd=str(PROJECT_ROOT),
+            )
+            subprocess.run(
+                [
+                    sys.executable,
+                    "skills/factory/scripts/factory.py",
+                    "stop",
+                    "--run",
+                    run,
+                ],
+                check=True,
+                capture_output=True,
+                cwd=str(PROJECT_ROOT),
+            )
+            r = subprocess.run(
+                [
+                    sys.executable,
+                    "skills/factory/scripts/factory.py",
+                    "expansion",
+                    "--run",
+                    run,
+                    "--loops",
+                    "10",
+                ],
+                capture_output=True,
+                text=True,
+                cwd=str(PROJECT_ROOT),
+            )
+            self.assertEqual(r.returncode, 0)
+            self.assertIn("halting after 0/10", r.stdout)
+        finally:
+            shutil.rmtree(PROJECT_ROOT / ".factory" / run, ignore_errors=True)
+
+    def test_skill_and_commands_exist(self):
+        self.assertTrue((PROJECT_ROOT / "skills" / "factory" / "SKILL.md").exists())
+        self.assertTrue(
+            (PROJECT_ROOT / "skills" / "factory" / "scripts" / "factory.py").exists()
+        )
+        self.assertTrue((PROJECT_ROOT / ".omp" / "commands" / "factory.md").exists())
+        self.assertTrue(
+            (PROJECT_ROOT / ".omp" / "commands" / "domainexpansion.md").exists()
+        )
+        self.assertTrue(
+            (PROJECT_ROOT / "plugins" / "gemini" / "commands" / "factory.toml").exists()
+        )
+        with open(PROJECT_ROOT / "package.json") as f:
+            pkg = json.load(f)
+        self.assertIn("./skills/factory", pkg["pi"]["skills"])
+        self.assertIn("./skills/factory", pkg["omp"]["skills"])
+
+    def test_snippet_factory_roster(self):
+        with open(PROJECT_ROOT / "config" / "opencode-snippet.json") as f:
+            snippet = json.load(f)
+        for agent in ("manager", "programmer", "qa-a", "qa-b"):
+            self.assertIn(agent, snippet["agent"])
+        manager = snippet["agent"]["manager"]
+        self.assertEqual(manager["mode"], "primary")
+        task = manager["permission"]["task"]
+        self.assertEqual(task["*"], "deny")
+        for allowed in ("programmer", "qa-a", "qa-b", "brainstormer", "darkharvester"):
+            self.assertEqual(task[allowed], "allow")
+        self.assertEqual(snippet["agent"]["qa-a"]["permission"]["edit"], "deny")
+        self.assertEqual(snippet["agent"]["qa-b"]["permission"]["edit"], "deny")
+
+    def test_factory_commands_carry_agent_subtask(self):
+        res = run_node(
+            """
+            import { OPENCODE_COMMANDS, commandCatalog } from "./plugins/opencode/index.js";
+            const catalog = commandCatalog();
+            console.log(JSON.stringify({
+              factory: catalog.factory, expansion: catalog.domainexpansion
+            }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, res.stderr)
+        data = last_json_object(res.stdout)
+        self.assertEqual(data["factory"]["agent"], "manager")
+        self.assertIn("$ARGUMENTS", data["factory"]["template"])
+        self.assertEqual(data["expansion"]["agent"], "manager")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/runner/tests/test_opencode_ux.py

@@ -26,6 +26,8 @@ EXPECTED_COMMANDS = [
     "brainstorming",
     "brainstorm",
     "darkharvest",
+    "factory",
+    "domainexpansion",
 ]
 
 
@@ -282,6 +284,10 @@ class TestInstallOpenCode(unittest.TestCase):
                 "epistemic-auditor",
                 "brainstormer",
                 "darkharvester",
+                "manager",
+                "programmer",
+                "qa-a",
+                "qa-b",
             ]:
                 self.assertIn(agent, cfg.get("agent", {}))
             self.assertIn("iumbtems", cfg.get("mcp", {}))
@@ -606,6 +612,8 @@ class TestOpenCodeV2Transforms(unittest.TestCase):
             "brainstorming",
             "brainstorm",
             "darkharvest",
+            "factory",
+            "domainexpansion",
         ]:
             self.assertIn(c, data["commands"])
         self.assertNotIn("goal", data["commands"])

package/runner/tests/test_swarm.py

@@ -402,6 +402,8 @@ In our experiments, the 70B parameter model was trained on 15.0 trillion tokens.
             "brainstorming",
             "brainstorm",
             "darkharvest",
+            "factory",
+            "domainexpansion",
         ]:
             self.assertIn(c, data_oc["commands"])
 

package/scripts/build_adapters.py

@@ -40,6 +40,7 @@ CANONICAL_SKILLS = [
     "oss_scout",
     "brainstorming",
     "darkharvest",
+    "factory",
 ]
 
 # Skill -> the MCP tool(s) that now carry its programmatic surface.
@@ -52,6 +53,11 @@ SKILL_TOOLS = {
     "oss_scout": ["iumbtems_oss_scout"],
     "brainstorming": ["iumbtems_brainstorm"],
     "darkharvest": ["iumbtems_darkharvest"],
+    "factory": [
+        "iumbtems_brainstorm",
+        "iumbtems_darkharvest",
+        "iumbtems_socratic_frontier",
+    ],
 }
 
 SKILL_TITLES = {
@@ -63,6 +69,7 @@ SKILL_TITLES = {
     "oss_scout": "OSS Scout",
     "brainstorming": "Brainstorming",
     "darkharvest": "Darkharvest",
+    "factory": "Factory",
 }
 
 # (target dir relative to root, mode). All targets are stubs since A2b.

package/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/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()