@heretek-ai/epistemic-swarm 0.7.25 → 1.0.2

package/skills/epistemic_search/scripts/webcache.py

@@ -1,339 +0,0 @@
-#!/usr/bin/env python3
-"""Content-addressed WebFetch cache-through gate for Claude Code hooks.
-
-Replaces the blanket PreToolUse deny with the cache-through pattern
-(proven by theYahia/claude-webcache):
-
-  gate    (PreToolUse WebFetch): serve `.research/sources/<sha256>.md` hits
-          via deny + additionalContext (no network); allow misses/stale.
-  archive (PostToolUse WebFetch): store the live response as md + json
-          sidecar, same layout as SourceHasher (content-hash filename).
-  stats   (SessionStart): one-line cache summary via additionalContext.
-
-Fail-open everywhere: any error exits 0 with no output (allow), logging to
-stderr (visible with --debug). This is a citation-integrity control, not a
-security boundary.
-
-URL canonicalization (borrowed from webcache): lowercase host, strip default
-ports and fragments, sort query parameters — so formatting variance does not
-cause silent misses.
-
-TTL: sidecar `cached_at`; default 7 days (IUMBTEMS_FETCH_TTL_DAYS), 30 days
-for stable documentation domains. Inline cap for served hits: 12000 chars
-(IUMBTEMS_FETCH_MAX_INLINE), remainder via file pointer.
-
-Raw bodies: archived unless `IUMBTEMS_CACHE_RAW_MARKDOWN=0` (config
-`cache_raw_markdown: false`, exported by the runner to spawned children).
-"""
-
-import hashlib
-import json
-import os
-import sys
-import urllib.parse
-from datetime import datetime, timezone
-from pathlib import Path
-
-DEFAULT_TTL_DAYS = 7
-DOC_DOMAIN_TTL_DAYS = 30
-DOC_DOMAINS = (
-    "code.claude.com",
-    "docs.anthropic.com",
-    "platform.claude.com",
-    "docs.python.org",
-    "developer.mozilla.org",
-)
-DEFAULT_MAX_INLINE = 12000
-
-
-def log(msg):
-    sys.stderr.write(f"[webcache] {msg}\n")
-
-
-def canonical_url(url):
-    try:
-        p = urllib.parse.urlsplit(url.strip())
-        host = (p.hostname or "").lower()
-        if not host:
-            return None
-        port = p.port
-        if (p.scheme == "http" and port == 80) or (p.scheme == "https" and port == 443):
-            port = None
-        netloc = f"{host}:{port}" if port else host
-        query = urllib.parse.urlencode(
-            sorted(urllib.parse.parse_qsl(p.query, keep_blank_values=True))
-        )
-        return urllib.parse.urlunsplit(
-            (p.scheme or "https", netloc, p.path or "/", query, "")
-        )
-    except Exception:
-        return None
-
-
-def domain_of(url):
-    try:
-        return (urllib.parse.urlsplit(url).hostname or "").lower()
-    except Exception:
-        return ""
-
-
-def ttl_days(url):
-    try:
-        override = int(os.environ.get("IUMBTEMS_FETCH_TTL_DAYS", ""))
-        return max(override, 0)
-    except ValueError:
-        pass
-    domain = domain_of(url)
-    if any(domain == d or domain.endswith("." + d) for d in DOC_DOMAINS):
-        return DOC_DOMAIN_TTL_DAYS
-    return DEFAULT_TTL_DAYS
-
-
-def max_inline():
-    try:
-        return max(int(os.environ.get("IUMBTEMS_FETCH_MAX_INLINE", "")), 1000)
-    except ValueError:
-        return DEFAULT_MAX_INLINE
-
-
-def research_dir(stdin_data):
-    base = stdin_data.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd()
-    return Path(base) / ".research"
-
-
-def find_cached(sources_dir, url):
-    """Scan json sidecars for a matching canonical URL. Returns (md_path, meta) or None."""
-    canon = canonical_url(url)
-    if not canon or not sources_dir.is_dir():
-        return None
-    for sidecar in sources_dir.glob("*.json"):
-        try:
-            meta = json.loads(sidecar.read_text(encoding="utf-8"))
-        except (OSError, ValueError):
-            continue
-        if not isinstance(meta, dict):
-            continue
-        if canonical_url(str(meta.get("url", ""))) == canon:
-            md_path = sidecar.with_suffix(".md")
-            if md_path.exists():
-                return md_path, meta
-    return None
-
-
-def is_fresh(meta, url):
-    try:
-        cached_at = datetime.fromisoformat(str(meta.get("cached_at", "")))
-        if cached_at.tzinfo is None:
-            cached_at = cached_at.replace(tzinfo=timezone.utc)
-        age_days = (datetime.now(timezone.utc) - cached_at).total_seconds() / 86400
-        return age_days <= ttl_days(url)
-    except (ValueError, TypeError):
-        return False
-
-
-def cmd_gate(stdin_data):
-    """PreToolUse: serve fresh hits, allow everything else (fail-open)."""
-    tool_input = stdin_data.get("tool_input") or {}
-    url = tool_input.get("url", "")
-    if not url:
-        return None  # allow
-    sources_dir = research_dir(stdin_data) / "sources"
-    try:
-        found = find_cached(sources_dir, url)
-    except Exception as e:
-        log(f"cache lookup failed for {domain_of(url)}: {e}")
-        return None  # allow
-    if not found:
-        return None  # miss -> allow, PostToolUse archives
-    md_path, meta = found
-    if not is_fresh(meta, url):
-        log(
-            f"stale entry for {domain_of(url)} ({meta.get('cached_at')}); allowing live fetch"
-        )
-        return None  # stale -> allow, PostToolUse refreshes
-    try:
-        content = md_path.read_text(encoding="utf-8")
-    except OSError as e:
-        log(f"cache read failed: {e}")
-        return None  # allow
-    cap = max_inline()
-    served = content if len(content) <= cap else content[:cap] + "\n\n[... truncated]"
-    body = (
-        f"<!-- EPISTEMIC_CACHE_HIT: {md_path.name} -->\n"
-        f"**Source URL:** {url}\n"
-        f"**Cached:** {meta.get('cached_at')}  **Content SHA-256:** `{meta.get('hash')}`\n"
-        f"**Verification Tag:** `[VERIFIED: {str(meta.get('hash', ''))[:16]}]`\n\n"
-        f"{served}\n"
-    )
-    if len(content) > cap:
-        body += f"\n(Full cached text in {md_path}; cite the file for passages beyond the excerpt.)\n"
-    log(f"cache HIT for {domain_of(url)} ({len(content)} chars, {md_path.name})")
-    return {
-        "hookSpecificOutput": {
-            "hookEventName": "PreToolUse",
-            "permissionDecision": "deny",
-            "permissionDecisionReason": (
-                "Served from the epistemic content cache (.research/sources); "
-                "no network fetch needed. Cite the cached file."
-            ),
-            "additionalContext": body,
-        }
-    }
-
-
-def _text_from_value(val):
-    """Recursively pull the first non-empty text out of a response value."""
-    if isinstance(val, str) and val.strip():
-        return val
-    if isinstance(val, dict):
-        for sub in ("text", "content", "output"):
-            got = _text_from_value(val.get(sub))
-            if got:
-                return got
-    if isinstance(val, list):
-        parts = [
-            p.get("text", "")
-            for p in val
-            if isinstance(p, dict) and isinstance(p.get("text"), str)
-        ]
-        if parts:
-            return "\n".join(parts)
-    return ""
-
-
-def extract_response_text(stdin_data):
-    """Defensively locate the tool response text across field-name variants."""
-    for key in ("tool_response", "response", "tool_result", "result", "output"):
-        got = _text_from_value(stdin_data.get(key))
-        if got:
-            return got
-    return ""
-
-
-def extract_url(stdin_data):
-    tool_input = stdin_data.get("tool_input") or stdin_data.get("input") or {}
-    if isinstance(tool_input, dict):
-        url = tool_input.get("url", "")
-        if url:
-            return url
-    # Fall back to a URL already recorded in a response envelope.
-    for key in ("tool_response", "response", "tool_result"):
-        val = stdin_data.get(key)
-        if isinstance(val, dict) and val.get("url"):
-            return val["url"]
-    return ""
-
-
-def raw_markdown_enabled():
-    """Whether raw markdown bodies may be archived.
-
-    Honored env override (config `cache_raw_markdown` -> spawned children):
-    `IUMBTEMS_CACHE_RAW_MARKDOWN=0|false|no|off` disables archiving entirely.
-    Unset (the default) preserves the historical archive-everything behavior.
-    """
-    return os.environ.get("IUMBTEMS_CACHE_RAW_MARKDOWN", "1").strip().lower() not in (
-        "0",
-        "false",
-        "no",
-        "off",
-    )
-
-
-def cmd_archive(stdin_data):
-    """PostToolUse: store the live response as md + json sidecar."""
-    url = extract_url(stdin_data)
-    text = extract_response_text(stdin_data)
-    if not url or not text:
-        return None
-    if not raw_markdown_enabled():
-        log(
-            f"raw markdown caching disabled (IUMBTEMS_CACHE_RAW_MARKDOWN=0); "
-            f"not archiving {domain_of(url)}"
-        )
-        return None
-    try:
-        sources_dir = research_dir(stdin_data) / "sources"
-        sources_dir.mkdir(parents=True, exist_ok=True)
-        digest = hashlib.sha256(text.encode("utf-8")).hexdigest()
-        sources_dir.joinpath(f"{digest}.md").write_text(text, encoding="utf-8")
-        sources_dir.joinpath(f"{digest}.json").write_text(
-            json.dumps(
-                {
-                    "hash": digest,
-                    "url": url,
-                    "title": url,
-                    "tier": "WEB_DOCUMENT",
-                    "cached_at": datetime.now(timezone.utc).isoformat(),
-                    "byte_size": len(text.encode("utf-8")),
-                    "char_count": len(text),
-                    "custom_metadata": {"via": "webfetch-hook"},
-                },
-                indent=2,
-            ),
-            encoding="utf-8",
-        )
-        log(f"archived {domain_of(url)} -> {digest[:16]} ({len(text)} chars)")
-        try:
-            root = Path(__file__).resolve().parents[3]
-            if str(root) not in sys.path:
-                sys.path.insert(0, str(root))
-            from runner.retrieval_log import log_event
-
-            log_event(
-                research_dir(stdin_data), "cache", url=url, hash=digest, tool="webcache"
-            )
-        except Exception:
-            pass
-    except Exception as e:
-        log(f"archive failed for {domain_of(url)}: {e}")
-    return None
-
-
-def cmd_stats(stdin_data):
-    """SessionStart: one-line cache summary; silent when empty."""
-    try:
-        sources_dir = research_dir(stdin_data) / "sources"
-        if not sources_dir.is_dir():
-            return None
-        md_files = list(sources_dir.glob("*.md"))
-        if not md_files:
-            return None
-        return {
-            "hookSpecificOutput": {
-                "hookEventName": "SessionStart",
-                "additionalContext": (
-                    f"epistemic-cache: {len(md_files)} page(s) cached in "
-                    f".research/sources — WebFetch hits are served from cache."
-                ),
-            }
-        }
-    except Exception as e:
-        log(f"stats failed: {e}")
-        return None
-
-
-def main(argv):
-    mode = argv[1] if len(argv) > 1 else "gate"
-    try:
-        raw = sys.stdin.read() if not sys.stdin.isatty() else ""
-        stdin_data = json.loads(raw) if raw.strip() else {}
-        if not isinstance(stdin_data, dict):
-            stdin_data = {}
-    except (ValueError, OSError):
-        stdin_data = {}
-    handler = {"gate": cmd_gate, "archive": cmd_archive, "stats": cmd_stats}.get(mode)
-    if handler is None:
-        log(f"unknown mode: {mode}")
-        return 1
-    try:
-        out = handler(stdin_data)
-    except Exception as e:
-        log(f"{mode} failed: {e}")
-        return 0  # fail-open
-    if out:
-        sys.stdout.write(json.dumps(out))
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main(sys.argv))

package/skills/factory/SKILL.md

@@ -1,61 +0,0 @@
----
-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).
-
-## 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`, `gate` (`--action open|settle|approve|waive|escalate|count`), 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).
-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

@@ -1,300 +0,0 @@
-#!/usr/bin/env python3
-"""
-Factory run-state helper: phase dossiers, QA retry bounds, expansion loop guard.
-
-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>
-  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 os
-import sys
-from datetime import datetime, timezone
-from pathlib import Path
-
-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
-
-
-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}'. Pass --run <name> (or run "
-            f"`factory.py init --run <name>` 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.")
-    # Phase output goes to phase.json — a run-state helper must never clobber the
-    # author-written GOAL.md / dossier.json it is meant to track (#6 item 2.3).
-    # This check runs BEFORE any state mutation so a refusal leaves no trace.
-    phase_dir = ROADMAP_DIR / args.phase
-    authored = [
-        name for name in ("GOAL.md", "dossier.json") if (phase_dir / name).exists()
-    ]
-    if authored and not getattr(args, "force", False):
-        raise SystemExit(
-            f"Refusing to touch author-written file(s) in {phase_dir}: "
-            f"{', '.join(authored)}. phase-add now writes phase.json only; "
-            f"re-run with --force to overwrite."
-        )
-    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_dir.mkdir(parents=True, exist_ok=True)
-    (phase_dir / "phase.json").write_text(
-        json.dumps(
-            {
-                "phase": args.phase,
-                "goal": args.goal,
-                "acceptance": state["phases"][args.phase]["acceptance"],
-                "status": "briefed",
-            },
-            indent=2,
-        ),
-        encoding="utf-8",
-    )
-    print(f"✅ Phase '{args.phase}' briefed → {phase_dir / 'phase.json'}")
-
-
-def cmd_gate(args):
-    """First-class gate bookkeeping (open/settle/approve/waive/escalate/count)."""
-    state = load_state(args.run)
-    gates = state.setdefault("gates", {})
-    gate = gates.setdefault(
-        args.phase, {"status": "closed", "cycles": 0, "waivers": [], "history": []}
-    )
-    action = (args.action or "").lower()
-    if action == "open":
-        gate["status"] = "open"
-        gate["cycles"] = gate.get("cycles", 0) + 1
-        state["gate_cycles"] = state.get("gate_cycles", 0) + 1
-    elif action == "settle":
-        gate["status"] = "settled"
-    elif action == "approve":
-        gate["status"] = "approved"
-    elif action == "waive":
-        gate["status"] = "waived"
-        gate["waivers"].append(args.reason or "")
-    elif action == "escalate":
-        gate["status"] = "escalated"
-        gate["cycles"] = gate.get("cycles", 0) + 1
-        state["gate_cycles"] = state.get("gate_cycles", 0) + 1
-    elif action != "count":
-        raise SystemExit(
-            "gate --action must be one of: open, settle, approve, waive, escalate, count"
-        )
-    gate["history"].append({"action": action, "at": now(), "reason": args.reason or ""})
-    save_state(args.run, state)
-    print(json.dumps({"phase": args.phase, "gate": gate}, indent=2))
-
-
-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 _ 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 _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="")
-    p.add_argument(
-        "--force",
-        action="store_true",
-        help="Overwrite author-written GOAL.md/dossier.json if present",
-    )
-    _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)
-    p = sub.add_parser("gate")
-    p.add_argument("--run", required=True)
-    p.add_argument("--phase", required=True)
-    p.add_argument(
-        "--action",
-        required=True,
-        choices=["open", "settle", "approve", "waive", "escalate", "count"],
-    )
-    p.add_argument("--reason", default="")
-    _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,
-        "qa-record": cmd_qa_record,
-        "expansion": cmd_expansion,
-        "stop": cmd_stop,
-        "gate": cmd_gate,
-    }[args.command](args)
-    sys.exit(code if isinstance(code, int) else 0)
-
-
-if __name__ == "__main__":
-    main()