@heretek-ai/epistemic-swarm 0.7.17 → 0.7.18

package/plugins/antigravity/antigravity_hooks.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""
+Antigravity Lifecycle Hook Interceptor & Epistemic Gate Bridge.
+
+Binds Antigravity's lifecycle events (PreToolUse, PreInvocation, PostToolUse, Stop)
+to IUMBTEMS's epistemic evidence verification pipeline.
+
+Contract Invariants:
+- Input is received as JSON on stdin (camelCase per Antigravity hook protojson).
+- Output is emitted as JSON on stdout.
+- Zero-failure tolerance: any unexpected internal error falls back safely without
+  blocking the agent loop.
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Dict
+
+
+def _get_workspace_dir(payload: Dict[str, Any]) -> Path:
+    workspaces = payload.get("workspacePaths", [])
+    if workspaces:
+        return Path(workspaces[0]).resolve()
+    if "IUMBTEMS_WORKSPACE" in os.environ:
+        return Path(os.environ["IUMBTEMS_WORKSPACE"]).resolve()
+    if "IUMBTEMS_ROOT" in os.environ:
+        return Path(os.environ["IUMBTEMS_ROOT"]).resolve()
+    curr = Path.cwd().resolve()
+    for p in [curr] + list(curr.parents):
+        if (p / ".research").exists() or (p / ".git").exists():
+            return p
+    return curr
+
+
+def _read_stdin_payload() -> Dict[str, Any]:
+    try:
+        content = sys.stdin.read()
+        if not content.strip():
+            return {}
+        return json.loads(content)
+    except Exception:
+        return {}
+
+
+def handle_pre_tool(payload: Dict[str, Any]) -> Dict[str, Any]:
+    """Intercept ungrounded search/fetch and redirect to epistemic cache tools."""
+    tool_call = payload.get("toolCall", {})
+    name = str(tool_call.get("name", "")).lower()
+
+    if "search_web" in name or "websearch" in name:
+        return {
+            "decision": "deny",
+            "reason": (
+                "Intercepted by IUMBTEMS epistemic-swarm: Web searches must be "
+                "verifiable. Use epistemic search (python3 skills/epistemic_search/scripts/search.py "
+                '"<query>") or MCP tool brave_web_search for SHA-256 cached verification.'
+            ),
+        }
+
+    if "read_url_content" in name or "webfetch" in name:
+        return {
+            "decision": "deny",
+            "reason": (
+                "Intercepted by IUMBTEMS epistemic-swarm: Web fetches must be "
+                "content-addressed. Use epistemic fetch (python3 skills/epistemic_search/scripts/fetch.py "
+                '"<url>") to cache sources into .research/sources/<sha256>.md.'
+            ),
+        }
+
+    return {"decision": "allow"}
+
+
+def handle_pre_invocation(payload: Dict[str, Any]) -> Dict[str, Any]:
+    """Inject ephemeral evidence tagging constraints before model reasoning."""
+    return {
+        "injectSteps": [
+            {
+                "ephemeralMessage": (
+                    "[EPISTEMIC INTEGRITY] Every factual claim must carry "
+                    "[VERIFIED: <sha256>] (verbatim quote in .research/sources/<hash>.md), "
+                    "[INFERRED: <parents>], [HYPOTHESIS: <test>], or [NEGATIVE_KNOWLEDGE: <query>]. "
+                    "Unverified parametric recall is strictly quarantined."
+                )
+            }
+        ]
+    }
+
+
+def handle_post_tool(payload: Dict[str, Any]) -> Dict[str, Any]:
+    """Log tool completions and record negative knowledge on failures."""
+    try:
+        workspace_dir = _get_workspace_dir(payload)
+        research_dir = workspace_dir / ".research"
+
+        error = payload.get("error")
+        if error and research_dir.exists():
+            log_file = research_dir / "retrieval.jsonl"
+            entry = {
+                "stepIdx": payload.get("stepIdx"),
+                "error": str(error),
+                "status": "tool_failure",
+            }
+            with log_file.open("a", encoding="utf-8") as f:
+                f.write(json.dumps(entry) + "\n")
+    except Exception:
+        pass
+    return {}
+
+
+def handle_stop(payload: Dict[str, Any]) -> Dict[str, Any]:
+    """Prevent agent from terminating if an active swarm run has unverified claims."""
+    try:
+        workspace_dir = _get_workspace_dir(payload)
+        research_dir = workspace_dir / ".research"
+
+        # If a STOP signal file was placed by user or factory, respect it immediately
+        factory_stop = (workspace_dir / ".factory" / "STOP")
+        if factory_stop.exists():
+            return {"decision": "allow"}
+
+        # Check if living dossier retractions require human/agent re-review
+        ledger_path = research_dir / "ledger" / "claim_status.json"
+        if ledger_path.exists():
+            try:
+                ledger = json.loads(ledger_path.read_text(encoding="utf-8"))
+                stale_claims = [
+                    c for c in ledger.get("claims", [])
+                    if c.get("status") in ("STALE", "SUSPECT")
+                ]
+                if stale_claims:
+                    return {
+                        "decision": "continue",
+                        "reason": (
+                            f"Epistemic audit warning: {len(stale_claims)} claims are degraded "
+                            "(STALE/SUSPECT) due to source retractions. Review before finishing."
+                        ),
+                    }
+            except Exception:
+                pass
+    except Exception:
+        pass
+    return {"decision": "allow"}
+
+
+def main() -> None:
+    action = sys.argv[1] if len(sys.argv) > 1 else "pre_tool"
+    payload = _read_stdin_payload()
+
+    if action == "pre_tool":
+        result = handle_pre_tool(payload)
+    elif action == "pre_invocation":
+        result = handle_pre_invocation(payload)
+    elif action == "post_tool":
+        result = handle_post_tool(payload)
+    elif action == "stop":
+        result = handle_stop(payload)
+    else:
+        result = {"decision": "allow"}
+
+    sys.stdout.write(json.dumps(result))
+    sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()

package/plugins/antigravity/commands/audit.md

@@ -0,0 +1,10 @@
+---
+description: Dialectic codebase architecture and security audit with line-level proof
+---
+
+Run the IUMBTEMS dialectic codebase audit on `$1`:
+
+`python3 runner/research_swarm.py --mode audit --objective "$1"`
+
+Report: `.research/code_audit_report.md` with `file:///path#Lstart-Lend` pointers
+and verbatim snippets. Every vulnerability needs a concrete patch blueprint.

package/plugins/antigravity/commands/brainstorming.md

@@ -0,0 +1,12 @@
+---
+description: Lateral brainstorming — novel feature vectors and speculative spikes
+---
+
+Run IUMBTEMS lateral brainstorming on `$1` (see `skills/brainstorming/SKILL.md`
+and `prompts/agent_brainstormer.md`):
+
+1. Ingest workspace context read-only (`python3 skills/brainstorming/scripts/brainstorm.py --objective "$1" --show-context`).
+2. Thesis / Radical Antithesis / Synthesis — never bug-fix lists.
+3. Output Novel Feature Vectors (3-5), Lateral Architectural Moves (2-3),
+   Experimental Hypotheses (2-3 with `[HYPOTHESIS:<falsification test>]`).
+4. Write `.research/brainstorm_report.md` (or run `python3 runner/research_swarm.py --mode brainstorm --objective "$1"`).

package/plugins/antigravity/commands/darkharvest.md

@@ -0,0 +1,11 @@
+---
+description: Product competitor teardown with per-feature harvest verdicts
+---
+
+Run a product competitor teardown for `$1`:
+
+`python3 runner/research_swarm.py --mode darkharvest --objective "$1"`
+
+Seeds may be embedded as repo URLs; cap live runs at `--max-repos 6`.
+Permissive-only vendor; GPL/AGPL clean-room-rebuild only; workflows clonable, assets never.
+Report: `.research/darkharvest_report.md` (matrix + white-space gaps + SPDX backlog).

package/plugins/antigravity/commands/domainexpansion.md

@@ -0,0 +1,9 @@
+---
+description: Autonomous agent-guided self-improvement loop (count-flagged)
+---
+
+Run the IUMBTEMS domain-expansion loop for `$1` loops (max 10):
+
+Bypasses per-loop gates; stops on count OR `.factory/STOP` file OR user kill.
+Each loop: agents propose direction, quick swarm check, implement, dual-QA verify.
+Enforce via the `iumbtems_factory` tool (expansion command with loops/max_loops).

package/plugins/antigravity/commands/factory.md

@@ -0,0 +1,9 @@
+---
+description: Coding-factory Manager loop with grill-gated phased builds
+---
+
+Run the IUMBTEMS coding-factory Manager loop for `$1`:
+
+1. Grill until `.factory/frontier.json` is settled (max 5 swarm cycles per gate); explicit user approve advances each gate.
+2. Per gate: `python3 runner/research_swarm.py --mode brainstorm` plus `--mode darkharvest` (mock-first), then synthesize `.roadmap/<phase>/` GOAL.md + dossier.json.
+3. Programmer subagent per phase; qa-a plus qa-b per phase; retries tracked via the `iumbtems_factory` tool (phase-add / qa-record; 3 failures escalate). Never invoke factory helper scripts by relative path.

package/plugins/antigravity/commands/grill.md

@@ -0,0 +1,9 @@
+---
+description: Socratic grilling and decision frontier exploration
+---
+
+Launch IUMBTEMS Socratic grilling for `$1`.
+
+Follow `skills/grilling/SKILL.md` (rounds, frontier, assumption inversion,
+factual vs decisional separation). Persist with
+`python3 skills/grilling/socratic_tree.py --export`.

package/plugins/antigravity/commands/scout.md

@@ -0,0 +1,10 @@
+---
+description: Scout open-source libraries and build clean-room blueprints
+---
+
+Scout open-source solutions for `$1`:
+
+`python3 runner/research_swarm.py --mode scout --objective "$1"`
+
+Flag GPL/AGPL contamination, solo-maintainer risk, dependency weight, CVEs.
+Report: `.research/oss_scout_report.md` plus a clean-room re-implementation blueprint.

package/plugins/antigravity/commands/swarm-config.md

@@ -0,0 +1,10 @@
+---
+description: Inspect or tune Epistemic Swarm parameters (engine, depth, mode)
+---
+
+Inspect or tune IUMBTEMS swarm parameters: `$1`.
+
+`python3 skills/swarm_config/configure.py $1`
+
+Engines: `duckduckgo` (zero-key default), `brave`, `firecrawl`, `searxng`.
+Modes: `research`, `audit`, `scout`, `hybrid`, `brainstorm`. Depth: 1-4.

package/plugins/antigravity/commands/swarm.md

@@ -0,0 +1,9 @@
+---
+description: Run IUMBTEMS dialectic research swarm on an objective
+---
+
+Run the IUMBTEMS dialectic research swarm on `$1`.
+
+1. If the objective is ambiguous, follow `skills/grilling/SKILL.md` first.
+2. Execute `python3 runner/research_swarm.py --objective "$1" $@[2:]`.
+3. Summarize `.research/final_synthesis.md`, preserving `[VERIFIED:<hash>]` pointers.

package/plugins/antigravity/hooks.json

@@ -1,22 +1,43 @@
 {
-  "hooks": {
-    "pre_tool": [
+  "epistemic-query-interceptor": {
+    "PreToolUse": [
       {
-        "matcher": "WebSearch",
-        "action": "deny",
-        "reason": "Intercepted by epistemic-swarm: use epistemic search (python3 skills/epistemic_search/scripts/search.py \"<query>\") for SHA-256 cached verification."
-      },
-      {
-        "matcher": "WebFetch",
-        "action": "deny",
-        "reason": "Intercepted by epistemic-swarm: use epistemic fetch (python3 skills/epistemic_search/scripts/fetch.py \"<url>\") for content-addressed caching."
+        "matcher": "search_web|read_url_content",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 antigravity_hooks.py pre_tool || echo '{\"decision\": \"allow\"}'",
+            "timeout": 15
+          }
+        ]
       }
     ],
-    "post_tool": [
+    "PreInvocation": [
+      {
+        "type": "command",
+        "command": "python3 antigravity_hooks.py pre_invocation || echo '{}'",
+        "timeout": 15
+      }
+    ]
+  },
+  "epistemic-claim-auditor": {
+    "PostToolUse": [
       {
         "matcher": "*",
-        "action": "log",
-        "reason": "Epistemic audit trail: verify [VERIFIED:<hash>] quotes against .research/sources/<sha256>.md."
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 antigravity_hooks.py post_tool || echo '{}'",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "type": "command",
+        "command": "python3 antigravity_hooks.py stop || echo '{\"decision\": \"allow\"}'",
+        "timeout": 20
       }
     ]
   }

package/plugins/antigravity/mcp_config.json

@@ -1,33 +1,33 @@
 {
   "mcpServers": {
+    "iumbtems": {
+      "command": "python3",
+      "args": ["${extensionPath}/mcp_launcher.py", "iumbtems"],
+      "env": {
+        "IUMBTEMS_WORKSPACE": "${workspacePath}"
+      }
+    },
     "brave-search": {
       "command": "python3",
-      "args": ["${pluginPath}/../../config/mcp_launcher.py", "brave-search"],
+      "args": ["${extensionPath}/mcp_launcher.py", "brave-search"],
       "env": {
         "BRAVE_SEARCH_API_KEY": "${BRAVE_SEARCH_API_KEY}"
       }
     },
     "firecrawl": {
       "command": "python3",
-      "args": ["${pluginPath}/../../config/mcp_launcher.py", "firecrawl"],
+      "args": ["${extensionPath}/mcp_launcher.py", "firecrawl"],
       "env": {
         "FIRECRAWL_API_KEY": "${FIRECRAWL_API_KEY}",
-        "FIRECRAWL_API_URL": "${FIRECRAWL_API_URL:-http://localhost:3002}"
+        "FIRECRAWL_API_URL": "${FIRECRAWL_API_URL:-https://api.firecrawl.dev}"
       }
     },
     "searxng": {
       "command": "python3",
-      "args": ["${pluginPath}/../../config/mcp_launcher.py", "searxng"],
+      "args": ["${extensionPath}/mcp_launcher.py", "searxng"],
       "env": {
         "SEARXNG_URL": "${SEARXNG_URL:-http://localhost:8080}"
       }
-    },
-    "iumbtems": {
-      "command": "python3",
-      "args": ["${pluginPath}/../../runner/mcp_server.py"],
-      "env": {
-        "PYTHONPATH": "${pluginPath}/../.."
-      }
     }
   }
 }

package/plugins/antigravity/mcp_launcher.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""
+Antigravity MCP Server Launcher & Epistemic Fallback Proxy.
+
+Binds Antigravity's MCP server declarations to:
+- runner/mcp_server.py (canonical 17 iumbtems_* tools)
+- config/mcp_launcher.py (brave-search, firecrawl, searxng with zero-key fallback)
+"""
+
+import os
+import sys
+from pathlib import Path
+import runpy
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+
+def find_project_root() -> Path:
+    candidates = []
+    if "IUMBTEMS_WORKSPACE" in os.environ:
+        candidates.append(Path(os.environ["IUMBTEMS_WORKSPACE"]).resolve())
+    if "IUMBTEMS_ROOT" in os.environ:
+        candidates.append(Path(os.environ["IUMBTEMS_ROOT"]).resolve())
+
+    curr = Path.cwd().resolve()
+    candidates.extend([curr] + list(curr.parents))
+
+    for c in candidates:
+        if (c / "runner" / "mcp_server.py").is_file():
+            return c
+    return curr
+
+def main():
+    service = sys.argv[1] if len(sys.argv) > 1 else "iumbtems"
+    root = find_project_root()
+
+    if str(root) not in sys.path:
+        sys.path.insert(0, str(root))
+
+    if service == "iumbtems":
+        server_script = root / "runner" / "mcp_server.py"
+        if server_script.is_file():
+            # Run runner/mcp_server.py directly in this process
+            sys.argv = [str(server_script)]
+            runpy.run_path(str(server_script), run_name="__main__")
+        else:
+            sys.stderr.write(f"IUMBTEMS mcp_server.py not found under project root: {root}\n")
+            sys.exit(1)
+    else:
+        launcher = root / "config" / "mcp_launcher.py"
+        if launcher.is_file():
+            sys.argv = [str(launcher), service]
+            runpy.run_path(str(launcher), run_name="__main__")
+        else:
+            sys.stderr.write(f"IUMBTEMS config/mcp_launcher.py not found under project root: {root}\n")
+            sys.exit(1)
+
+if __name__ == "__main__":
+    main()

package/plugins/antigravity/plugin.json

@@ -1,23 +1,13 @@
 {
   "$schema": "https://antigravity.google/schemas/v1/plugin.json",
   "name": "epistemic-swarm",
-  "version": "0.4.8",
-  "description": "IUMBTEMS Epistemic Swarm: dialectic research, code audit, OSS scout, and lateral brainstorming for AntiGravity.",
-  "author": "Heretek AI",
+  "version": "0.7.18",
+  "description": "IUMBTEMS (Epistemic Swarm) \u2014 High-Integrity Dialectic Research, Architecture Auditing, Competitor Teardowns, and Socratic Planning for Antigravity.",
+  "author": {
+    "name": "Heretek AI",
+    "email": "dev@heretek.ai"
+  },
   "license": "Apache-2.0",
   "repository": "https://github.com/Heretek-AI/IUMBTEMS",
-  "homepage": "https://github.com/Heretek-AI/IUMBTEMS#readme",
-  "skills": [
-    "./skills/grilling",
-    "./skills/research_cache",
-    "./skills/epistemic_search",
-    "./skills/swarm_config",
-    "./skills/code_audit",
-    "./skills/oss_scout",
-    "./skills/brainstorming",
-    "./skills/darkharvest",
-    "./skills/factory"
-  ],
-  "agents": ["./agents"],
-  "rules": ["./rules"]
+  "homepage": "https://github.com/Heretek-AI/IUMBTEMS#readme"
 }

package/plugins/antigravity/rules/AGENTS.md

@@ -0,0 +1,125 @@
+# AGENTS.md — IUMBTEMS contributor guide
+
+## Evidence first
+Every factual claim carries a tag: `[VERIFIED: <sha256>]` (verbatim quote in
+`.research/sources/<hash>.md`), `[INFERRED: <parents>]`, `[HYPOTHESIS: <test>]`,
+or `[NEGATIVE_KNOWLEDGE: <query>]`. Never present parametric recall as verified.
+
+## Naming
+- **IUMBTEMS** is the project/brand; **Epistemic Swarm** is the product/technical
+  name (npm `@heretek-ai/epistemic-swarm`, Claude plugin `epistemic-swarm`). Keep
+  user-facing docs IUMBTEMS-led and use "Epistemic Swarm" for the package/plugin.
+
+## Canonical surfaces (single source of truth)
+- `skills/*/SKILL.md` + `prompts/*.md` — canonical prose and specs.
+- Hand-maintained (NOT generated): `README.md`, `MARKETPLACE.md`, `AGENTS.md`,
+  `docs/*.md`, `.omp/*`, `.claude/*`, `plugins/*/README.md`, and the OpenCode
+  plugin source `plugins/opencode/index.js`.
+- `python3 runner/mcp_server.py` — canonical programmatic surface (17 `iumbtems_*`
+  tools: `config`, `swarm_research`, `code_audit`, `oss_scout`, `brainstorm`,
+  `darkharvest`, `factory`, `verify_quote`, `socratic_frontier`, `export_brief`,
+  `verify_brief`, `reindex_claims`, `report_retraction`, `check_staleness`,
+  `set_domain_pack`, `doctor`, `test`).
+- GENERATED — never hand-edit: `plugins/{antigravity,gemini,codex}/skills/**`,
+  `.agents/skills/**`, and the modular copies under
+  `plugins/{research-cache,socratic-grilling,darkharvest,factory}/skills/**`.
+  Edit the canonical skill, then run `python3 scripts/build_adapters.py`.
+
+## Commands
+- `iumbtems run|audit|scout|brainstorm|darkharvest|grill|config|doctor|test`
+- `iumbtems adapters|install|marketplace|help` — regenerate adapter stubs, install
+  the Claude Code overlay, print the marketplace catalog, print usage.
+- `iumbtems factory <init|phase-add|qa-record|expansion|stop|gate>` — factory
+  run-state helper (state in `.factory/`, output in `.roadmap/`, evidence in
+  `.research/`). Run-shaping flags: `--resume` (continue a session), `--dry-run`
+  (validate without spawning).
+- OpenCode slash commands: `/swarm /grill /swarm-config /audit /scout
+  /brainstorming /darkharvest /factory /domainexpansion`.
+
+## Skills quick map
+- `grilling` — Socratic assumption-inversion, decision frontier.
+- `brainstorming` — divergent ideation (never bug fixes); scaffold via
+  `skills/brainstorming/scripts/brainstorm.py`.
+- `oss_scout` — library discovery, license red-team, clean-room blueprints.
+- `darkharvest` — product competitor teardown; helper
+  `skills/darkharvest/scripts/harvest.py`. Permissive-only vendoring;
+  GPL/AGPL spec-rebuild only; workflows clonable, assets never.
+- `factory` — Manager loop roles/gates/QA bounds; helper
+  `skills/factory/scripts/factory.py` (3 QA failures escalate; expansion capped,
+  STOP-file kill).
+- `research_cache` — content-addressed SHA-256 source cache + quote verification
+  (`hasher.py`).
+- `epistemic_search` — zero-key DuckDuckGo search, fetch, and cache-through
+  (`search.py`, `webcache.py`).
+- `swarm_config` — inspect/tune/persist research parameters
+  (`skills/swarm_config/configure.py`).
+- `code_audit` — structural architecture mapping + vulnerability red-teaming.
+
+## Contract invariants (do not break; detail lives in `docs/SYSTEM_ARCHITECTURE.md`)
+
+| Invariant | Detail |
+| :--- | :--- |
+| Manifests are per mode (`manifest.json` for research, `manifest.<mode>.json` otherwise) | §6.2.2 |
+| Manifest writes use unique temp names + `fcntl` lock (`.research/.manifest.lock`); readers use `find_any_manifest` | §6.2.2 |
+| Role dossier contract: agents get the **exact** dossier path; completion is **derived from files on disk** (`reconcile_scope_status`) | §6.2.3 |
+| Loader tolerates bounded mode aliases + manifest `outputs`, normalizing to the canonical name | §6.2.3 |
+| Grounding is observable (`.research/retrieval.jsonl` + `retrieval:` banner); scoring is per mode; only `source_hash` + `verbatim_quote` claims count toward Verified | §6.3 |
+| Darkharvest license cross-check is a safety control (`WARNING_LICENSE_CONFLICT`); `self_reported_*` fields are never counted | §6.4 |
+| Contracts are generated (`runner/schemas.py` → `schemas/`); validation is warn-on-load | §6.5 |
+| Agent runtime is host-native; spawned agents get matching OS `cwd` and `PWD`; `opencode run` passes `--auto` | §6.1–6.2 |
+| Config deep-merges `agents` per role; legacy `["claude", "-p"]` pins migrate to `null` unless `backend` is `"claude"` | §6.6 |
+| Preflight auto-runs at every swarm start (`iumbtems_doctor`); mode-aware fail-fast halts before spawning (exit 3) | §6.5 |
+| Frontier is tool-drivable (`--add-node/--settle/--export`); frontier writes are atomic + locked | §5, §6.5 |
+| Run-scoped layout is opt-in (`IUMBTEMS_RUN_SCOPED=1`); default is flat | §6.5 |
+| `factory` writes `phase.json` (never `GOAL.md`/`dossier.json`, refused unless `--force`); `gate open|settle|approve|waive|escalate|count` | §10 |
+
+## Workflow rules
+- Writes go only to `.research/`, `.factory/` (runtime state), `.roadmap/`
+  (phase output). Never auto-install dependencies.
+- After touching `skills/*`, `package.json` (pi/omp blocks), or OpenCode plugin
+  surface: run `python3 scripts/build_adapters.py --check` and
+  `python3 -m unittest discover -s runner/tests`. Both must be green.
+- After touching `runner/schemas.py`: run `python3 scripts/gen_schemas.py`
+  (regenerates `schemas/*.schema.json`); `--check` must be green.
+- Docs changes: `python3 scripts/check_docs.py` must resolve every repo-relative
+  reference.
+- OpenCode V2 is the first-class target: agent profiles + commands live in
+  `config/opencode-snippet.json` and `plugins/opencode/index.js`
+  (`OPENCODE_COMMANDS`, `commandCatalog()`); commands may pin `agent:` and
+  `subagent:` (`subtask:` legacy alias) per https://opencode.ai/v2/docs/commands/.
+- The plugin registers through the V2 domains at setup: `tool.transform` and
+  `command.transform` (catalog), plus `agent.transform` (the snippet's role
+  profiles, incl. manager/programmer/qa-a/qa-b) and `skill.transform` (bundled
+  `skills/*/SKILL.md`). This removes the config-snippet install dependency —
+  without it a `/factory` run executed as the generic `build` agent and the
+  agent hunted the filesystem for its own skill prose. Commands that pin an
+  agent also call `session.switchAgent` (best-effort, shape-tolerant) so the
+  pinned role is actually active.
+- V2 `AgentEditor` has NO `add()` — only `list/get/default/update/remove`, and
+  `update(id, mutate)` upserts (seeded from `Agent.Info.default(id)`; the
+  first-party `opencode.config.agent` uses the same path). The plugin registers
+  profiles with `update`; calling `add` made opencode v2.0.18 disable the whole
+  plugin (`disabled plugin after transform failure`, state=agent). The shipped
+  snippet is V2-shaped: `agents` (plural), `skills` as a list, `mcp.servers`.
+- Dual QA gates the loop: diverged `qa-a` (functional) and `qa-b`
+  (adversarial) seats, manager tiebreak, 3 failures escalate. Waivers carry
+  conditions. When a fix's precondition changes, re-verify its blast radius
+  (see #7/#8).
+- You drive the installed package, not the worktree: fixes authored here take
+  effect only after release + reinstall.
+
+## Releases
+- Bump `package.json` (+ lockfile sync) **and `.claude-plugin/plugin.json`**
+  (0.7.5 shipped with a stale plugin manifest — keep all three in lockstep),
+  commit, push to `main`, then
+  `gh release create vX.Y.Z`. The `Publish to npm` workflow (OIDC trusted
+  publishing) runs on release-published. Verify with
+  `curl https://registry.npmjs.org/@heretek-ai%2Fepistemic-swarm`
+  (allow propagation time).
+- **After every push to `main` or release, check *all* workflows, not just the
+  publisher:** `gh run list --limit 10` and inspect `Validate All Harnesses`,
+  `Validate Claude Code Marketplace`, `Plugin Evals`, `CodeQL`, and
+  `Publish to npm`. A green `Publish to npm` alone hid real failures for several
+  releases (a committed symlink under `skills/` broke `plugin validate --strict`,
+  and an OpenCode tool-parity gap went unnoticed) — the release is not done until
+  every workflow is green.

package/plugins/antigravity/rules/epistemic-integrity.md

@@ -1,6 +1,16 @@
-# Epistemic Integrity (AntiGravity workspace rule)
+# Epistemic Integrity Invariant (AntiGravity Workspace Rule)
 
-All factual claims MUST carry `[VERIFIED:<hash>]`, `[INFERRED:<chain>]`,
-`[HYPOTHESIS:<falsification>]`, or `[NEGATIVE_KNOWLEDGE:<query>]` tags
-(see `prompts/base_epistemic_system.md`). Unverified parametric recollection
-is quarantined. Fetch, verify, then assert.
+## Evidence-First Invariant
+Every factual claim made by any agent MUST carry an empirical attribution tag:
+- `[VERIFIED: <sha256>]`: Verbatim quote matching content in `.research/sources/<sha256>.md`.
+- `[INFERRED: <parents>]`: Logical derivation explicitly citing verified parent claims.
+- `[HYPOTHESIS: <test>]`: Falsifiable proposition paired with an empirical verification test.
+- `[NEGATIVE_KNOWLEDGE: <query>]`: Recorded failure or absence of evidence for a specific query.
+
+Never present unverified parametric recollection as fact. Quarantined parametric recall must be verified against cached sources before assertion.
+
+## Directory Isolation & Write Boundaries
+- Agents write ONLY to `.research/` (evidence, dossiers, retrieval logs), `.factory/` (runtime execution state), and `.roadmap/` (phase outputs).
+- Never modify existing dossiers in-place; dossiers form an immutable historical record.
+- Claim status transitions must be appended to `.research/ledger/claim_status.json`.
+- Never install external dependencies or packages without explicit user authorization.

package/plugins/antigravity/skills/brainstorming/SKILL.md

@@ -1,3 +1,9 @@
+---
+name: brainstorming
+description: >-
+  Lateral creative brainstorming and divergent ideation skill. Use when exploring what-if features, lateral architectures, speculative product directions, or when user invokes /brainstorming. Generates novel feature vectors, paradigm inversions, and falsifiable spike hypotheses instead of bug fixes.
+---
+
 # Brainstorming (thin adapter stub)
 
 This file is a POINTER, not the implementation. It exists so harness skill

package/plugins/antigravity/skills/code_audit/SKILL.md

@@ -1,3 +1,9 @@
+---
+name: code-audit
+description: >-
+  Deep dialectic codebase auditing skill. Deploys architectural thesis vs adversarial red-team antithesis to discover security vulnerabilities, race conditions, resource leaks, and architectural flaws with exact line-level proof.
+---
+
 # Code Audit (thin adapter stub)
 
 This file is a POINTER, not the implementation. It exists so harness skill

package/plugins/antigravity/skills/darkharvest/SKILL.md

@@ -1,3 +1,9 @@
+---
+name: darkharvest
+description: >-
+  Product-level competitor teardown and clean-room harvest engine. Use when user wants to compete with or learn from existing products (e.g. Paseo, OpenChambers). Seed with inspiration URLs plus prompt, auto-expand to adjacents, clone-scan competitors, compare product plus code, and emit per-feature depend/vendor/clean-room/skip verdicts with SPDX attribution. Never copies GPL/AGPL code or UI assets.
+---
+
 # Darkharvest (thin adapter stub)
 
 This file is a POINTER, not the implementation. It exists so harness skill

package/plugins/antigravity/skills/epistemic_search/SKILL.md

@@ -1,3 +1,9 @@
+---
+name: epistemic_search
+description: >-
+  High-integrity web search and document fetch skill with automatic SHA-256 content caching. Use when searching the web, retrieving primary sources, or fetching documentation while enforcing epistemic integrity.
+---
+
 # Epistemic Search (thin adapter stub)
 
 This file is a POINTER, not the implementation. It exists so harness skill