@heretek-ai/epistemic-swarm 0.7.3 → 0.7.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "epistemic-swarm",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "description": "High-Integrity Dialectic Research Agent Harness for Claude Code enforcing empirical evidence over parametric hallucination.",
   "author": {
     "name": "Heretek AI",

package/.omp/commands/domainexpansion.md

@@ -6,4 +6,4 @@ 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`.
+Enforce via the `iumbtems_factory` tool (expansion command with loops/max_loops).

package/.omp/commands/factory.md

@@ -6,4 +6,4 @@ 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).
+3. Programmer subagent per phase; qa-a plus qa-b per phase; retries tracked via the `iumbtems_factory` tool (phase-add / qa-record; 3 failures escalate). Never invoke factory helper scripts by relative path.

package/extensions/pi/index.js

@@ -210,8 +210,7 @@ export default function initPiExtension(pi) {
     } catch { /* alias is best-effort across pi/omp versions */ }
 
     // /darkharvest: Product competitor teardown with harvest verdicts
-    pi.registerCommand('darkharvest', {
-      description: 'Product competitor teardown: seed inspirations, expand to adjacents, emit harvest verdicts',
+    pi.registerCommand('darkharvest', {      description: 'Product competitor teardown: seed inspirations, expand to adjacents, emit harvest verdicts',
       usage: '/darkharvest <product-arena> [--seeds <urls>]',
       handler: async (args, ctx) => {
         const objective = args.trim();
@@ -316,6 +315,33 @@ export default function initPiExtension(pi) {
         return { content: [{ type: 'text', text: r.text }] };
       }
     });
+
+    // Tool: iumbtems_factory (run-state helper, no script paths)
+    pi.registerTool({
+      name: 'iumbtems_factory',
+      description: 'Drive factory run state: init / phase-add / qa-record / expansion / stop',
+      parameters: {
+        type: 'object',
+        properties: {
+          command: { type: 'string', enum: ['init', 'phase-add', 'qa-record', 'expansion', 'stop'] },
+          run: { type: 'string', description: 'Factory run name' },
+          phase: { type: 'string' },
+          goal: { type: 'string' },
+          accept: { type: 'string' },
+          seat: { type: 'string' },
+          verdict: { type: 'string', enum: ['pass', 'fail', 'conditional'] },
+          reason: { type: 'string' },
+          loops: { type: 'integer' },
+          max_loops: { type: 'integer' },
+          project_dir: { type: 'string' }
+        },
+        required: ['command']
+      },
+      execute: async (args = {}) => {
+        const r = callMcp('iumbtems_factory', args, {});
+        return { content: [{ type: 'text', text: r.text }] };
+      }
+    });
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "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": {

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

@@ -13,6 +13,16 @@ description: Coding-factory Manager loop. Use when user invokes /factory or /dom
 - **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).
 
+## 1b. Driving run state (no filesystem paths)
+
+Use the **`iumbtems_factory` MCP tool** for all run-state changes — never a
+relative `skills/factory/scripts/factory.py` path (the toolchain lives in the
+npm cache in consuming projects, and relative paths broke live: the manager
+agent ran `find / -name factory.py`). The tool wraps the same helper and
+resolves the project via `project_dir` argument, `IUMBTEMS_PROJECT_DIR`, or
+the session cwd. It supports `init`, `phase-add`, `qa-record`, `expansion`,
+`stop`, and returns `status: escalated` (exit 2) on the 3rd QA failure.
+
 ## 2. Gate protocol (max 5 swarm cycles per gate)
 
 1. Grill until `.factory/frontier.json` settled (grilling skill).

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

@@ -2,8 +2,13 @@
 """
 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.
+All state lives under <project>/.factory/ (gitignored runtime state). Phase
+output goes to <project>/.roadmap/<phase>/. Evidence stays in <project>/
+.research/. Read-only w.r.t. repo code.
+
+Project directory resolution: --project-dir > IUMBTEMS_PROJECT_DIR env > the
+toolchain repo root (local-dev default). A consuming project must never leak
+state into the IUMBTEMS checkout.
 
 Usage:
   python3 skills/factory/scripts/factory.py init --run <name>
@@ -15,13 +20,25 @@ Usage:
 
 import argparse
 import json
+import os
 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"
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent.parent
+
+
+def resolve_project_root(cli_value=None):
+    """--project-dir > IUMBTEMS_PROJECT_DIR > repo root (local-dev default)."""
+    for candidate in (cli_value, os.environ.get("IUMBTEMS_PROJECT_DIR")):
+        if candidate and Path(candidate).is_dir():
+            return Path(candidate).resolve()
+    return REPO_ROOT
+
+
+PROJECT_DIR = resolve_project_root()
+FACTORY_DIR = PROJECT_DIR / ".factory"
+ROADMAP_DIR = PROJECT_DIR / ".roadmap"
 
 MAX_QA_RETRIES = 3
 MAX_EXPANSION_LOOPS = 10
@@ -173,31 +190,48 @@ def cmd_stop(args):
     print(f"🛑 STOP file written for run '{args.run}'.")
 
 
+def _add_common(parser):
+    parser.add_argument(
+        "--project-dir",
+        default=None,
+        help="Project the factory state belongs to (default: IUMBTEMS_PROJECT_DIR env, else repo root)",
+    )
+
+
 def main():
+    global FACTORY_DIR, ROADMAP_DIR
     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)
+    _add_common(p)
     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="")
+    _add_common(p)
     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="")
+    _add_common(p)
     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)
+    _add_common(p)
     p = sub.add_parser("stop")
     p.add_argument("--run", required=True)
+    _add_common(p)
 
     args = ap.parse_args()
+    root = resolve_project_root(args.project_dir)
+    FACTORY_DIR = root / ".factory"
+    ROADMAP_DIR = root / ".roadmap"
     code = {
         "init": cmd_init,
         "phase-add": cmd_phase_add,

package/plugins/gemini/commands/domainexpansion.toml

@@ -3,5 +3,5 @@ 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}}.
+Enforce via the iumbtems_factory tool (command: expansion, with loops/max_loops).
 """

package/plugins/gemini/commands/factory.toml

@@ -3,6 +3,6 @@ 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).
+3. Programmer subagent per phase; qa-a plus qa-b per phase; retries via the iumbtems_factory tool (phase-add / qa-record; 3 failures escalate). Never invoke factory helper scripts by relative path.
 Report: .roadmap/ phases plus .factory/state.json.
 """

package/plugins/opencode/index.js

@@ -102,6 +102,7 @@ export const IUMBTEMS_TOOL_NAMES = [
   'iumbtems_oss_scout',
   'iumbtems_brainstorm',
   'iumbtems_darkharvest',
+  'iumbtems_factory',
   'iumbtems_verify_quote',
   'iumbtems_socratic_frontier',
   'iumbtems_reindex_claims',
@@ -291,6 +292,31 @@ const TOOL_CATALOG = [
       required: ['objective'],
     },
   },
+  {
+    name: 'iumbtems_factory',
+    description:
+      'Drive factory run state: init / phase-add / qa-record / expansion / stop. State goes to <project>/.factory and <project>/.roadmap; no helper-script path needed.',
+    input: {
+      type: 'object',
+      properties: {
+        command: {
+          type: 'string',
+          enum: ['init', 'phase-add', 'qa-record', 'expansion', 'stop'],
+        },
+        run: { type: 'string', description: 'Factory run name' },
+        phase: { type: 'string', description: 'Phase id (e.g. 01-auth)' },
+        goal: { type: 'string' },
+        accept: { type: 'string', description: 'Semicolon-separated acceptance criteria' },
+        seat: { type: 'string', description: 'QA seat (qa-a | qa-b)' },
+        verdict: { type: 'string', enum: ['pass', 'fail', 'conditional'] },
+        reason: { type: 'string' },
+        loops: { type: 'integer', description: 'Expansion loop count (1-10)' },
+        max_loops: { type: 'integer' },
+        project_dir: { type: 'string', description: 'Project root (default: IUMBTEMS_PROJECT_DIR or cwd)' },
+      },
+      required: ['command'],
+    },
+  },
   {
     name: 'iumbtems_verify_quote',
     description:
@@ -558,7 +584,7 @@ export const OPENCODE_COMMANDS = [
       '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).',
+      '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 the iumbtems_factory tool (command: phase-add / qa-record; 3 failures escalate to manager). Never invoke factory helper scripts by relative path.',
       '4. Manager tiebreaks QA disagreements; explicit user sign-off closes each phase.',
     ].join('\n'),
   },
@@ -572,7 +598,7 @@ export const OPENCODE_COMMANDS = [
       '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).',
+      '1. Bypass per-loop gates; stop on count OR .factory/STOP file OR user kill, whichever first (enforce via the iumbtems_factory tool, command: expansion, with loops/max_loops).',
       '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'),

package/runner/mcp_server.py

@@ -192,6 +192,87 @@ def _handle_darkharvest(args: Dict[str, Any]) -> str:
     return _run_swarm_mode("darkharvest", args)
 
 
+def _handle_factory(args: Dict[str, Any]) -> str:
+    """Drive factory run state (init / phase-add / qa-record / expansion / stop).
+
+    Wraps skills/factory/scripts/factory.py so agents never need a filesystem
+    path to the helper: the npm-installed toolchain lives outside the project,
+    and relative `skills/...` paths broke in consuming projects (observed
+    live: the manager agent ran `find / -name factory.py`).
+    """
+    import subprocess
+
+    command = str(args.get("command") or "").strip()
+    if command not in ("init", "phase-add", "qa-record", "expansion", "stop"):
+        raise ValueError(
+            "command must be one of: init, phase-add, qa-record, expansion, stop"
+        )
+    script = Path(PROJECT_ROOT) / "skills" / "factory" / "scripts" / "factory.py"
+    if not script.is_file():
+        raise FileNotFoundError(f"factory helper not found at {script}")
+
+    project = (
+        args.get("project_dir") or os.environ.get("IUMBTEMS_PROJECT_DIR") or os.getcwd()
+    )
+    cmd = [sys.executable, str(script), command, "--project-dir", str(project)]
+    if command == "init":
+        cmd += ["--run", str(args.get("run") or "")]
+    elif command == "phase-add":
+        cmd += [
+            "--run",
+            str(args.get("run") or ""),
+            "--phase",
+            str(args.get("phase") or ""),
+            "--goal",
+            str(args.get("goal") or ""),
+            "--accept",
+            str(args.get("accept") or ""),
+        ]
+    elif command == "qa-record":
+        cmd += [
+            "--run",
+            str(args.get("run") or ""),
+            "--phase",
+            str(args.get("phase") or ""),
+            "--seat",
+            str(args.get("seat") or ""),
+            "--verdict",
+            str(args.get("verdict") or ""),
+        ]
+        if args.get("reason"):
+            cmd += ["--reason", str(args["reason"])]
+    elif command == "expansion":
+        cmd += [
+            "--run",
+            str(args.get("run") or ""),
+            "--loops",
+            str(int(args.get("loops") or 1)),
+        ]
+        if args.get("max_loops"):
+            cmd += ["--max-loops", str(int(args["max_loops"]))]
+    elif command == "stop":
+        cmd += ["--run", str(args.get("run") or "")]
+
+    proc = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        shell=False,
+        stdin=subprocess.DEVNULL,
+        cwd=str(project),
+    )
+    payload = {
+        "status": "ok" if proc.returncode == 0 else "error",
+        "command": command,
+        "returncode": proc.returncode,
+        "project_dir": str(project),
+        "output": (proc.stdout or proc.stderr or "").strip()[-4000:],
+    }
+    if proc.returncode == 2:
+        payload["status"] = "escalated"
+    return _tool_text(payload)
+
+
 def _handle_verify_quote(args: Dict[str, Any]) -> str:
     """Verify a verbatim quote against the content-addressed source cache."""
     from skills.research_cache.hasher import SourceHasher
@@ -541,6 +622,46 @@ def build_tools() -> List[ToolSpec]:
             },
             handler=_handle_darkharvest,
         ),
+        ToolSpec(
+            name="iumbtems_factory",
+            description="Drive factory run state: init / phase-add / qa-record / expansion / stop. State goes to <project>/.factory and <project>/.roadmap; no filesystem path to helper scripts required.",
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "command": {
+                        "type": "string",
+                        "enum": ["init", "phase-add", "qa-record", "expansion", "stop"],
+                    },
+                    "run": {"type": "string", "description": "Factory run name"},
+                    "phase": {
+                        "type": "string",
+                        "description": "Phase id (e.g. 01-auth)",
+                    },
+                    "goal": {"type": "string"},
+                    "accept": {
+                        "type": "string",
+                        "description": "Semicolon-separated acceptance criteria",
+                    },
+                    "seat": {"type": "string", "description": "QA seat (qa-a | qa-b)"},
+                    "verdict": {
+                        "type": "string",
+                        "enum": ["pass", "fail", "conditional"],
+                    },
+                    "reason": {"type": "string"},
+                    "loops": {
+                        "type": "integer",
+                        "description": "Expansion loop count (1-10)",
+                    },
+                    "max_loops": {"type": "integer"},
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project root (default: IUMBTEMS_PROJECT_DIR or cwd)",
+                    },
+                },
+                "required": ["command"],
+            },
+            handler=_handle_factory,
+        ),
         ToolSpec(
             name="iumbtems_verify_quote",
             description="Audit a verbatim citation against the SHA-256 source cache (.research/sources/<hash>.md).",

package/runner/tests/test_factory.py

@@ -2,6 +2,7 @@
 """Tests for the factory loop: run-state helper, QA retry bounds, plugin surface."""
 
 import json
+import os
 import subprocess
 import sys
 import tempfile
@@ -164,6 +165,52 @@ class TestFactoryHelper(unittest.TestCase):
         self.assertIn("./skills/factory", pkg["pi"]["skills"])
         self.assertIn("./skills/factory", pkg["omp"]["skills"])
 
+    def test_project_dir_env_resolution(self):
+        """Factory state must land in the target project, never the checkout."""
+        with tempfile.TemporaryDirectory() as tmp:
+            env = dict(os.environ, IUMBTEMS_PROJECT_DIR=tmp)
+            r = subprocess.run(
+                [
+                    sys.executable,
+                    "skills/factory/scripts/factory.py",
+                    "init",
+                    "--run",
+                    "env-run",
+                ],
+                capture_output=True,
+                text=True,
+                cwd=str(PROJECT_ROOT),
+                env=env,
+            )
+            self.assertEqual(r.returncode, 0, r.stderr)
+            self.assertTrue(
+                (Path(tmp) / ".factory" / "env-run" / "state.json").exists()
+            )
+
+    def test_mcp_factory_tool_project_dir(self):
+        """iumbtems_factory drives state in the given project (no script path)."""
+        with tempfile.TemporaryDirectory() as tmp:
+            r = subprocess.run(
+                [
+                    sys.executable,
+                    "runner/mcp_server.py",
+                    "call",
+                    "iumbtems_factory",
+                    json.dumps(
+                        {"command": "init", "run": "mcp-run", "project_dir": tmp}
+                    ),
+                ],
+                capture_output=True,
+                text=True,
+                cwd=str(PROJECT_ROOT),
+            )
+            self.assertEqual(r.returncode, 0, r.stderr)
+            payload = json.loads(r.stdout)
+            self.assertEqual(payload["status"], "ok")
+            self.assertTrue(
+                (Path(tmp) / ".factory" / "mcp-run" / "state.json").exists()
+            )
+
     def test_snippet_factory_roster(self):
         with open(PROJECT_ROOT / "config" / "opencode-snippet.json") as f:
             snippet = json.load(f)

package/runner/tests/test_mcp_server.py

@@ -28,6 +28,7 @@ EXPECTED_TOOLS = [
     "iumbtems_oss_scout",
     "iumbtems_brainstorm",
     "iumbtems_darkharvest",
+    "iumbtems_factory",
     "iumbtems_verify_quote",
     "iumbtems_socratic_frontier",
     "iumbtems_reindex_claims",

package/runner/tests/test_opencode_ux.py

@@ -214,7 +214,7 @@ class TestOpenCodeCommandCatalog(unittest.TestCase):
         self.assertEqual(res.returncode, 0, f"tool map test failed: {res.stderr}")
         data = last_json_object(res.stdout)
         self.assertEqual(sorted(data["keys"]), sorted(data["canonical"]))
-        self.assertEqual(len(data["keys"]), 14)
+        self.assertEqual(len(data["keys"]), 15)
         self.assertTrue(all(data["ok"]))
 
 
@@ -618,7 +618,7 @@ class TestOpenCodeV2Transforms(unittest.TestCase):
             self.assertIn(c, data["commands"])
         self.assertNotIn("goal", data["commands"])
         self.assertEqual(data["cmdExec"], "function")
-        self.assertEqual(len(data["tools"]), 14)
+        self.assertEqual(len(data["tools"]), 15)
         self.assertIn("iumbtems_brainstorm", data["tools"])
         self.assertIn("iumbtems_darkharvest", data["tools"])
         self.assertEqual(data["toolExec"], "function")

package/runner/tests/test_swarm.py

@@ -381,6 +381,7 @@ In our experiments, the 70B parameter model was trained on 15.0 trillion tokens.
             "iumbtems_oss_scout",
             "iumbtems_brainstorm",
             "iumbtems_darkharvest",
+            "iumbtems_factory",
             "iumbtems_verify_quote",
             "iumbtems_socratic_frontier",
             "iumbtems_reindex_claims",

package/skills/factory/SKILL.md

@@ -13,6 +13,16 @@ description: Coding-factory Manager loop. Use when user invokes /factory or /dom
 - **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).
 
+## 1b. Driving run state (no filesystem paths)
+
+Use the **`iumbtems_factory` MCP tool** for all run-state changes — never a
+relative `skills/factory/scripts/factory.py` path (the toolchain lives in the
+npm cache in consuming projects, and relative paths broke live: the manager
+agent ran `find / -name factory.py`). The tool wraps the same helper and
+resolves the project via `project_dir` argument, `IUMBTEMS_PROJECT_DIR`, or
+the session cwd. It supports `init`, `phase-add`, `qa-record`, `expansion`,
+`stop`, and returns `status: escalated` (exit 2) on the 3rd QA failure.
+
 ## 2. Gate protocol (max 5 swarm cycles per gate)
 
 1. Grill until `.factory/frontier.json` settled (grilling skill).

package/skills/factory/scripts/factory.py

@@ -2,8 +2,13 @@
 """
 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.
+All state lives under <project>/.factory/ (gitignored runtime state). Phase
+output goes to <project>/.roadmap/<phase>/. Evidence stays in <project>/
+.research/. Read-only w.r.t. repo code.
+
+Project directory resolution: --project-dir > IUMBTEMS_PROJECT_DIR env > the
+toolchain repo root (local-dev default). A consuming project must never leak
+state into the IUMBTEMS checkout.
 
 Usage:
   python3 skills/factory/scripts/factory.py init --run <name>
@@ -15,13 +20,25 @@ Usage:
 
 import argparse
 import json
+import os
 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"
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent.parent
+
+
+def resolve_project_root(cli_value=None):
+    """--project-dir > IUMBTEMS_PROJECT_DIR > repo root (local-dev default)."""
+    for candidate in (cli_value, os.environ.get("IUMBTEMS_PROJECT_DIR")):
+        if candidate and Path(candidate).is_dir():
+            return Path(candidate).resolve()
+    return REPO_ROOT
+
+
+PROJECT_DIR = resolve_project_root()
+FACTORY_DIR = PROJECT_DIR / ".factory"
+ROADMAP_DIR = PROJECT_DIR / ".roadmap"
 
 MAX_QA_RETRIES = 3
 MAX_EXPANSION_LOOPS = 10
@@ -173,31 +190,48 @@ def cmd_stop(args):
     print(f"🛑 STOP file written for run '{args.run}'.")
 
 
+def _add_common(parser):
+    parser.add_argument(
+        "--project-dir",
+        default=None,
+        help="Project the factory state belongs to (default: IUMBTEMS_PROJECT_DIR env, else repo root)",
+    )
+
+
 def main():
+    global FACTORY_DIR, ROADMAP_DIR
     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)
+    _add_common(p)
     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="")
+    _add_common(p)
     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="")
+    _add_common(p)
     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)
+    _add_common(p)
     p = sub.add_parser("stop")
     p.add_argument("--run", required=True)
+    _add_common(p)
 
     args = ap.parse_args()
+    root = resolve_project_root(args.project_dir)
+    FACTORY_DIR = root / ".factory"
+    ROADMAP_DIR = root / ".roadmap"
     code = {
         "init": cmd_init,
         "phase-add": cmd_phase_add,