@heretek-ai/epistemic-swarm 0.7.3 → 0.7.5

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/README.md

@@ -75,19 +75,20 @@ pi install npm:@heretek-ai/epistemic-swarm
 - OMP (`omp.sh`, oh-my-pi) shares the same entry point: `omp install npm:@heretek-ai/epistemic-swarm`, project commands in `.omp/commands/` (`/swarm`, `/grill`, `/audit`, `/scout`, `/brainstorming`, `/swarm-config`), prompts in `.omp/prompts/`, hooks in `.omp/hooks/pre|post/`.
 - All commands automatically respect `.research/config.json`.
 
-### 3. OpenCode V2 (`opencode.ai`)
-Enable IUMBTEMS in your `~/.config/opencode/opencode.json` or project `opencode.jsonc`. You can configure settings declaratively:
-```json
+### 3. OpenCode V2 ([opencode.ai/v2/docs](https://opencode.ai/v2/docs))
+Enable IUMBTEMS in your `~/.config/opencode/opencode.jsonc` or project `opencode.jsonc`. You can configure settings declaratively using native OpenCode V2 syntax:
+```jsonc
 {
-  "plugin": [
-    [
-      "@heretek-ai/epistemic-swarm",
-      {
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "@heretek-ai/epistemic-swarm",
+      "options": {
         "search_engine": "duckduckgo",
         "max_iterations": 2,
         "mode": "research"
       }
-    ]
+    }
   ]
 }
 ```
@@ -197,7 +198,7 @@ Every factual claim in IUMBTEMS carries an explicit evidentiary tag:
 1. **Discovery Tier**: SearXNG (unbiased metasearch) and Brave Search API.
 2. **Extraction Tier**: Firecrawl (headless JavaScript rendering, DOM cleaning, Markdown extraction).
 3. **Academic Tier**: Semantic Scholar / arXiv MCPs for DOI citation resolution.
-4. **Caching Tier**: Content-addressed SHA-256 storage (`skills/research-cache/hasher.py`).
+4. **Caching Tier**: Content-addressed SHA-256 storage (`skills/research_cache/hasher.py`).
 
 ### Local Infrastructure (Optional)
 Run local SearXNG and Firecrawl instances via Docker Compose:

package/config/opencode-snippet.json

@@ -7,15 +7,15 @@
       "enabled": true
     }
   },
-  "plugin": [
-    [
-      "@heretek-ai/epistemic-swarm",
-      {
+  "plugins": [
+    {
+      "package": "@heretek-ai/epistemic-swarm",
+      "options": {
         "search_engine": "duckduckgo",
         "max_iterations": 2,
         "mode": "research"
       }
-    ]
+    }
   ],
   "agent": {
     "code-auditor": {

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.5",
   "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:
@@ -551,6 +577,7 @@ export const OPENCODE_COMMANDS = [
     description: 'Coding-factory Manager loop: grill-gated phased build with programmer spawns and dual QA',
     usage: '/factory <product-arena>',
     agent: 'manager',
+    subagent: false,
     subtask: false,
     template: [
       'Run the IUMBTEMS coding-factory Manager loop as the manager agent.',
@@ -558,7 +585,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'),
   },
@@ -567,12 +594,13 @@ export const OPENCODE_COMMANDS = [
     description: 'Autonomous agent-guided self-improvement loop over the codebase (count-flagged)',
     usage: '/domainexpansion <n>',
     agent: 'manager',
+    subagent: false,
     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).',
+      '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'),
@@ -593,7 +621,14 @@ export function commandCatalog() {
     if (!cmd?.name) continue;
     out[cmd.name] = { description: cmd.description, template: cmd.template };
     if (cmd.agent) out[cmd.name].agent = cmd.agent;
+    if (cmd.subagent !== undefined) out[cmd.name].subagent = cmd.subagent;
     if (cmd.subtask !== undefined) out[cmd.name].subtask = cmd.subtask;
+    if (out[cmd.name].subagent === undefined && out[cmd.name].subtask !== undefined) {
+      out[cmd.name].subagent = out[cmd.name].subtask;
+    }
+    if (out[cmd.name].subtask === undefined && out[cmd.name].subagent !== undefined) {
+      out[cmd.name].subtask = out[cmd.name].subagent;
+    }
   }
   return out;
 }
@@ -863,7 +898,12 @@ async function registerHostCommands(host) {
         name: cmd.name,
         description: cmd.description,
         ...(cmd.agent ? { agent: cmd.agent } : {}),
-        ...(cmd.subtask !== undefined ? { subtask: cmd.subtask } : {}),
+        ...(cmd.subagent !== undefined || cmd.subtask !== undefined
+          ? {
+              subagent: cmd.subagent !== undefined ? cmd.subagent : cmd.subtask,
+              subtask: cmd.subtask !== undefined ? cmd.subtask : cmd.subagent,
+            }
+          : {}),
         execute: async (input) => {
           const args = input?.prompt?.text || '';
           const prompt = (typeof input?.prompt === 'object' && input?.prompt !== null) ? input.prompt : {};

package/prompts/antigravity_repo_factcheck.md

@@ -0,0 +1,143 @@
+# IUMBTEMS REPOSITORY FACT-CHECKING REVIEW PROMPT FOR ANTIGRAVITY
+
+> **Role & Protocol**: You are operating as the **Epistemic Swarm Auditor** within Google AntiGravity. Your mission is to conduct a rigorous, evidentiary, live web-search fact-checking review of the **IUMBTEMS** repository (`https://github.com/Heretek-AI/IUMBTEMS` / local workspace).
+>
+> You are governed by the **Epistemic Integrity Protocol** defined in this repository: your internal parametric memory is strictly quarantined as untrusted heuristic guidance. You are prohibited from presenting unverified parametric recollections as established empirical facts. Every factual assertion must be verified against live reality via web searching and URL extraction.
+
+---
+
+## 1. MANDATORY TAGGING TAXONOMY
+
+Every factual statement, version assertion, API specification claim, or benchmark metric MUST carry an explicit epistemic tag:
+
+- `[VERIFIED: <URL | "verbatim quote excerpt">]`
+  - Backed by live web content fetched during this session via `search_web` or `read_url_content`.
+  - Must include the exact URL and an exact verbatim quote substring from the retrieved page.
+- `[INFERRED: <Parent Tags> -> <Deductive Reasoning>]`
+  - Deductive conclusion derived directly from cited `[VERIFIED]` premises.
+- `[HYPOTHESIS: <Measurable Falsification Condition>]`
+  - Unverified projection or speculation; requires an empirical test that would disprove it.
+- `[NEGATIVE_KNOWLEDGE: <Search Query>]`
+  - Rigorous confirmation that an exhaustive live web search yielded zero supporting evidence.
+
+---
+
+## 2. REPOSITORY AUDIT TARGETS
+
+Inspect the local codebase (`README.md`, `AGENTS.md`, `MARKETPLACE.md`, `package.json`, `prompts/`, and `plugins/`) and fact-check the following four empirical domains using `search_web` and `read_url_content`:
+
+### Domain 1: Package Registry & Release Veracity
+- **Claims in Repo**: The project is published on npm as `@heretek-ai/epistemic-swarm` under Apache-2.0, providing binary `iumbtems`.
+- **Fact-Checking Action**:
+  - Search `https://registry.npmjs.org/@heretek-ai%2Fepistemic-swarm` or search the web for npm package `@heretek-ai/epistemic-swarm`.
+  - Verify: Does the package exist on npm? What is the latest published version? Does it match `package.json`? Does it expose the `iumbtems` binary?
+
+### Domain 2: Peer Agent Harness Compatibility Claims
+- **Claims in Repo**:
+  1. **OpenCode V2**: Claims plugin integration in `plugins/opencode/index.js`, using slash commands (`/swarm`, `/grill`, `/audit`), agent profiles (`config/opencode-snippet.json`), and notes that OpenCode lacks a pre-execution webfetch hook.
+  2. **Pi & OMP**: Claims native install via `pi install npm:@heretek-ai/epistemic-swarm` and `omp install npm:@heretek-ai/epistemic-swarm` with command blocks in `package.json`.
+  3. **Claude Code**: Claims marketplace support via `claude plugin marketplace add Heretek-AI/IUMBTEMS` and `.claude-plugin/marketplace.json`.
+- **Fact-Checking Action**:
+  - Search official documentation and repos for OpenCode (`opencode.ai`), Pi (`pi.dev`), and Claude Code plugin specs.
+  - Verify: Are the configuration formats, CLI command syntaxes, and plugin manifest schemas valid against current upstream specifications?
+
+### Domain 3: Cited Academic & Algorithmic Benchmarks
+- **Claims in Repo** (found in `prompts/base_epistemic_system.md`, `prompts/orchestrator.md`, etc.):
+  1. Llama-3-70B context window (131,072 tokens) and GQA across 8 KV heads (`arXiv:2407.21783`).
+  2. Tip5 hash vs. Poseidon hash SNARK witness generation benchmarks.
+  3. Zero-dependency Raft consensus and DuckDuckGo Lite HTML scraping behavior.
+- **Fact-Checking Action**:
+  - Search arXiv and web sources for the cited papers and benchmarks.
+  - Verify: Are the numbers, citations, and DOIs authentic, or were any placeholder/synthetic examples presented as real citations?
+
+### Domain 4: License, Security & Dependency Invariants
+- **Claims in Repo**: Apache-2.0 clean-room licensing, permissive-only vendoring, no AGPL/GPL contamination.
+- **Fact-Checking Action**:
+  - Inspect dependencies in `package.json` and python scripts.
+  - Verify license status of key referenced dependencies via web search.
+
+---
+
+## 3. SINGLE-SESSION AGENTIC EXECUTION WORKFLOW
+
+Execute the fact-checking mission autonomously in three sequential phases:
+
+```
+[Phase 1: Alpha (Affirmative)] ──> [Phase 2: Beta (Adversary)] ──> [Phase 3: Epistemic Auditor]
+```
+
+### Phase 1: Alpha (The Affirmative Grounding)
+1. Read the local claims in `README.md` and `package.json` using `view_file`.
+2. Formulate targeted search queries and execute them using `search_web`.
+3. Fetch full source pages using `read_url_content` for key results.
+4. Extract verbatim evidence excerpts corroborating the repository's claims.
+5. Tag all confirmed claims with `[VERIFIED: <URL | "quote">]`.
+
+### Phase 2: Beta (The Adversarial Red Team)
+1. Execute inverted and adversarial queries to hunt for discrepancies, breaking changes, and invalid claims:
+   - `"<package> deprecated"`, `"<command> error"`, `"<paper> critique"`
+   - Check if any upstream harness APIs (OpenCode, Pi, Claude Code) have deprecated or altered the interfaces IUMBTEMS relies on.
+   - Hunt for missing packages, unfulfilled promises, or exaggerated marketing statements.
+2. If claimed features or benchmarks cannot be found online, log them as `[NEGATIVE_KNOWLEDGE: <query>]`.
+3. If an assertion is disproven by current live documentation, document the exact contradiction.
+
+### Phase 3: Epistemic Auditor & Mathematical Synthesis
+1. Perform character-for-character verification between extracted quotes and source URLs.
+2. Compute the **Epistemic Score**:
+   $$\mathcal{E} = \frac{1.0 \times N_{\text{verified}} + 0.5 \times N_{\text{neg\_knowledge}} - 2.5 \times N_{\text{rejected}}}{N_{\text{verified}} + N_{\text{inferred}} + N_{\text{hypothesis}} + N_{\text{rejected}}}$$
+   *(Threshold: $\mathcal{E} \ge 0.65$ to certify empirical grounding).*
+3. Compute the **Divergence Score**:
+   $$D = \frac{|\text{Contradicted Claims}|}{|\text{Total Scope Claims}|}$$
+4. Output the final synthesis report as a Markdown Artifact or structured response.
+
+---
+
+## 4. OUTPUT FORMAT SPECIFICATION
+
+Your final output must follow this structure:
+
+```markdown
+# Epistemic Fact-Checking Audit: IUMBTEMS Repository
+
+## Executive Summary
+- **Overall Verdict**: [CERTIFIED (Score >= 0.65) | AUDIT_WARNING: LOW_EMPIRICAL_GROUNDING]
+- **Epistemic Score ($\mathcal{E}$)**: `<score>`
+- **Dialectic Divergence ($D$)**: `<score>`
+- **Total Claims Audited**: `<count>` (Verified: `<count>`, Rejected: `<count>`, Negative Knowledge: `<count>`)
+
+---
+
+## Evidentiary Audit Ledger
+
+### 1. Package & Distribution Veracity
+- Claim: ...
+- Status: [VERIFIED | REJECTED | NEGATIVE_KNOWLEDGE]
+- Evidence: [VERIFIED: https://... | "Verbatim quote..."]
+- Notes: ...
+
+### 2. Multi-Harness Compatibility (OpenCode, Pi, OMP, Claude Code)
+...
+
+### 3. Academic & Benchmark Integrity
+...
+
+### 4. License & Contamination Safety
+...
+
+---
+
+## Divergence & Contradiction Matrix
+| Dimension | Affirmative Claim (Alpha) | Adversarial Finding (Beta) | Adjudicated Truth |
+| :--- | :--- | :--- | :--- |
+| ... | ... | ... | ... |
+
+---
+
+## Actionable Remediations
+1. [P0/P1/P2] Specific changes required in `README.md`, `package.json`, or code to align with verified live reality.
+```
+
+---
+
+## 5. EXECUTION DIRECTIVE
+Begin Phase 1 immediately: inspect local claims, invoke `search_web` to verify npm and harness registries, then proceed through Phase 2 and Phase 3 without stopping.

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)
@@ -191,8 +238,12 @@ class TestFactoryHelper(unittest.TestCase):
         self.assertEqual(res.returncode, 0, res.stderr)
         data = last_json_object(res.stdout)
         self.assertEqual(data["factory"]["agent"], "manager")
+        self.assertEqual(data["factory"]["subagent"], False)
+        self.assertEqual(data["factory"]["subtask"], False)
         self.assertIn("$ARGUMENTS", data["factory"]["template"])
         self.assertEqual(data["expansion"]["agent"], "manager")
+        self.assertEqual(data["expansion"]["subagent"], False)
+        self.assertEqual(data["expansion"]["subtask"], False)
 
 
 if __name__ == "__main__":

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,