@heretek-ai/epistemic-swarm 0.4.2 → 0.4.4

package/.claude-plugin/plugin.json

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

package/hooks/hooks.json

@@ -15,7 +15,28 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"WebFetch intercepted by epistemic-swarm to enforce content-addressed caching. Use epistemic fetch (python3 ${CLAUDE_PLUGIN_ROOT}/skills/epistemic_search/scripts/fetch.py \\\"<url>\\\") which automatically stores documents in .research/sources/<sha256>.md for mathematical auditability.\"}}'"
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/skills/epistemic_search/scripts/webcache.py\" gate"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "WebFetch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/skills/epistemic_search/scripts/webcache.py\" archive"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/skills/epistemic_search/scripts/webcache.py\" stats"
           }
         ]
       }

package/install.sh

@@ -177,6 +177,31 @@ try:
             print(f"   + Added agent: {name}")
         else:
             print(f"   ℹ️ Agent already configured: {name}")
+
+    # Skills: snippet paths are repo-relative ("./skills/x") which breaks
+    # from ~/.config — merge as absolute paths, repairing relative entries.
+    import os as _os
+    wanted = []
+    for sp in snippet.get("skills", {}).get("paths", []):
+        wanted.append(sp if _os.path.isabs(sp) else str(repo / sp.lstrip("./")))
+    skills_cfg = cfg.setdefault("skills", {})
+    paths = skills_cfg.setdefault("paths", [])
+    # Repair repo-relative entries in place, then append missing absolutes.
+    for i, existing in enumerate(list(paths)):
+        for abs_sp in wanted:
+            if existing == abs_sp:
+                break
+            rel = "./" + str(Path(abs_sp).relative_to(repo)) if str(abs_sp).startswith(str(repo)) else None
+            if rel and existing == rel:
+                paths[i] = abs_sp
+                print(f"   ~ Repaired relative skill path: {rel} -> {abs_sp}")
+                break
+    for abs_sp in wanted:
+        if abs_sp not in paths:
+            paths.append(abs_sp)
+            print(f"   + Added skill path: {abs_sp}")
+        else:
+            print(f"   ℹ️ Skill path already configured: {abs_sp}")
 except Exception as e:
     print(f"   ⚠️ Non-critical warning merging agents: {e}")
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "IUMBTEMS: I Use My Brain To Express My Self — High-Integrity Dialectic Research Agent Harness for Claude Code, OpenCode V2, Pi, OMP (oh-my-pi), Gemini CLI, Codex CLI, and AntiGravity",
   "main": "bin/cli.js",
   "bin": {

package/plugins/antigravity/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://antigravity.google/schemas/v1/plugin.json",
   "name": "epistemic-swarm",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "IUMBTEMS Epistemic Swarm: dialectic research, code audit, OSS scout, and lateral brainstorming for AntiGravity.",
   "author": "Heretek AI",
   "license": "Apache-2.0",

package/plugins/gemini/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "epistemic-swarm",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "IUMBTEMS Epistemic Swarm: dialectic research, code audit, OSS scout, and lateral brainstorming for Gemini CLI.",
   "mcpServers": {
     "brave-search": {

package/plugins/opencode/index.js

@@ -11,7 +11,7 @@
  * catalog. Schemas mirror runner/mcp_server.py build_tools() — keep in sync.
  */
 
-import { spawnSync } from 'child_process';
+import { spawn } from 'child_process';
 import { readFileSync } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
@@ -30,21 +30,40 @@ try {
   // keep fallback; version is informational only
 }
 
-/** Uniform dispatch: one-shot MCP call, return OpenCode's {content, status}. */
+/**
+ * Uniform dispatch: one-shot MCP call, return OpenCode's {content, status}.
+ * Async (non-blocking spawn) so long swarms/audits never freeze the host
+ * event loop; cancellation remains the host's prerogative.
+ */
 function callMcp(tool, args = {}, cwd) {
-  const res = spawnSync(
-    'python3',
-    [MCP_SERVER, 'call', tool, JSON.stringify(args || {})],
-    {
-      encoding: 'utf-8',
-      cwd: cwd || process.cwd(),
-      env: { ...process.env, PYTHONPATH: PKG_ROOT },
+  return new Promise((resolve) => {
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const done = (content, status) => {
+      if (settled) return;
+      settled = true;
+      resolve({ content, status });
+    };
+    let child;
+    try {
+      child = spawn(
+        'python3',
+        [MCP_SERVER, 'call', tool, JSON.stringify(args || {})],
+        {
+          cwd: cwd || process.cwd(),
+          env: { ...process.env, PYTHONPATH: PKG_ROOT },
+        }
+      );
+    } catch (err) {
+      done(String((err && err.message) || err), 'error');
+      return;
     }
-  );
-  return {
-    content: res.stdout || res.stderr,
-    status: res.status === 0 ? 'success' : 'error',
-  };
+    child.stdout.on('data', (d) => { stdout += String(d); });
+    child.stderr.on('data', (d) => { stderr += String(d); });
+    child.on('error', (err) => done(String((err && err.message) || err), 'error'));
+    child.on('close', (code) => done(stdout || stderr, code === 0 ? 'success' : 'error'));
+  });
 }
 
 /** Catalog mirrors runner/mcp_server.py build_tools(). */
@@ -351,9 +370,11 @@ export const OPENCODE_COMMANDS = [
   {
     name: 'swarm',
     description: 'Run IUMBTEMS dialectic research swarm on an objective',
+    usage: '/swarm <objective>',
     template: [
       'Run an IUMBTEMS dialectic research swarm.',
       'Objective: $ARGUMENTS',
+      'If $ARGUMENTS is empty, ask the user for the research objective first; never call the tool with placeholder, empty, or literal "<objective>" arguments.',
       '1. If the objective is ambiguous, frame it first via iumbtems_socratic_frontier.',
       '2. Execute iumbtems_swarm_research with {"objective": "<objective>"} (pass "mock_mode": true only for dry runs).',
       '3. Summarize .research/final_synthesis.md, preserving [VERIFIED:<hash>] pointers.',
@@ -362,6 +383,7 @@ export const OPENCODE_COMMANDS = [
   {
     name: 'grill',
     description: 'Launch Socratic grilling and decision tree frontier exploration',
+    usage: '/grill [--objective <text>]',
     template: [
       'Launch Socratic grilling on the decision frontier.',
       'Objective: $ARGUMENTS (may be empty to inspect the current frontier)',
@@ -372,6 +394,7 @@ export const OPENCODE_COMMANDS = [
   {
     name: 'swarm-config',
     description: 'Inspect or update Epistemic Swarm parameters (engine, depth, mode)',
+    usage: '/swarm-config [--engine <e>] [--depth <d>] [--mode <m>] [--show]',
     template: [
       'Inspect or update the Epistemic Swarm configuration.',
       'Arguments: $ARGUMENTS (may be empty to inspect current settings)',
@@ -381,9 +404,11 @@ export const OPENCODE_COMMANDS = [
   {
     name: 'audit',
     description: 'Run dialectic codebase architectural and security audit with line-level proof',
+    usage: '/audit <target_path_or_scope>',
     template: [
       'Run an IUMBTEMS dialectic codebase audit (structural architect vs adversarial red-teamer).',
       'Target: $ARGUMENTS (path, component, or empty for full-repository architecture and vulnerability audit)',
+      'If $ARGUMENTS names a path that does not exist, ask the user to clarify the target first; never audit a placeholder path.',
       '1. Execute iumbtems_code_audit with {"target": "<target>"} (pass "mock_mode": true only for dry runs).',
       '2. Summarize .research/code_audit_report.md with line-level proof pointers.',
     ].join('\n'),
@@ -391,9 +416,11 @@ export const OPENCODE_COMMANDS = [
   {
     name: 'scout',
     description: 'Scout open-source libraries, audit copyleft licenses, generate clean-room blueprints',
+    usage: '/scout <feature_or_algorithm>',
     template: [
       'Scout open-source solutions for the requested capability.',
       'Feature: $ARGUMENTS',
+      'If $ARGUMENTS is empty, ask the user for the feature or algorithm first; never call the tool with placeholder, empty, or literal "<feature>" arguments.',
       '1. Execute iumbtems_oss_scout with {"feature": "<feature>"} (pass "mock_mode": true only for dry runs).',
       '2. Report mature candidates, GPL/AGPL copyleft risks, and the clean-room blueprint in .research/oss_scout_report.md.',
     ].join('\n'),
@@ -401,6 +428,7 @@ export const OPENCODE_COMMANDS = [
   {
     name: 'brainstorming',
     description: 'Lateral brainstorming: novel feature vectors, paradigm inversions, falsifiable spikes',
+    usage: '/brainstorming <ambiguous-prompt>',
     template: [
       'Run lateral brainstorming (divergent what-if ideation, never bug-fix lists).',
       'Prompt: $ARGUMENTS (defaults to "Where do we go from here?" when empty)',
@@ -411,6 +439,7 @@ export const OPENCODE_COMMANDS = [
   {
     name: 'brainstorm',
     description: 'Alias for /brainstorming',
+    usage: '/brainstorm <ambiguous-prompt>',
     template: [
       'Alias for /brainstorming: run lateral brainstorming (divergent what-if ideation, never bug-fix lists).',
       'Prompt: $ARGUMENTS (defaults to "Where do we go from here?" when empty)',
@@ -640,7 +669,7 @@ export function createOpenCodePlugin(context = {}) {
           updates.divergence_threshold = opts.divergence_threshold;
         }
         if (Object.keys(updates).length > 0) {
-          callMcp('iumbtems_config', updates, appContext?.cwd);
+          await callMcp('iumbtems_config', updates, appContext?.cwd);
         }
       }
       // Phase C: idle staleness nudge (opt out with {staleness_nudge: false}).

package/plugins/opencode/tui.js

@@ -15,6 +15,7 @@ import { readFileSync, readdirSync, statSync } from 'fs';
 import path from 'path';
 import { createElement, insert, setProp } from '@opentui/solid';
 import { createEffect, createSignal, onCleanup } from 'solid-js';
+import { OPENCODE_COMMANDS } from './index.js';
 
 const PLUGIN_ID = 'heretek.iumbtems.epistemic-swarm.tui';
 const REFRESH_MS = 5000;
@@ -172,26 +173,47 @@ function SwarmSidebar(api, root, sessionID) {
 }
 
 function SwarmKeymapLayer(api) {
+  const toast = (title, message) => {
+    try {
+      api.ui.toast.show({ title, message, variant: 'info', duration: 4000 });
+    } catch {
+      /* toast is best-effort */
+    }
+  };
+  const commands = [
+    {
+      id: 'iumbtems.swarm-status',
+      title: 'Swarm status',
+      description: 'Show IUMBTEMS workspace status (mode, reports, frontier, STALE claims)',
+      group: 'IUMBTEMS',
+      palette: true,
+      run: () => {
+        const root = resolveRoot(api);
+        toast('IUMBTEMS', summarize(readSwarmStatus(root)));
+      },
+    },
+  ];
+  // Every slash command gets a palette entry (usage toast; the host has no
+  // programmatic slash-invoke API, so discovery + usage guidance is the win).
+  for (const cmd of OPENCODE_COMMANDS || []) {
+    if (!cmd || !cmd.name) continue;
+    commands.push({
+      id: `iumbtems.command.${cmd.name}`,
+      title: `/${cmd.name}`,
+      description: cmd.description || cmd.name,
+      group: 'IUMBTEMS',
+      palette: true,
+      run: () => {
+        toast(
+          `IUMBTEMS /${cmd.name}`,
+          `${cmd.usage || cmd.description || ''} — type /${cmd.name} in the prompt to run.`
+        );
+      },
+    });
+  }
   api.keymap.layer(() => ({
     mode: 'global',
-    commands: [
-      {
-        id: 'iumbtems.swarm-status',
-        title: 'Swarm status',
-        description: 'Show IUMBTEMS workspace status (mode, reports, frontier, STALE claims)',
-        group: 'IUMBTEMS',
-        palette: true,
-        run: () => {
-          const root = resolveRoot(api);
-          api.ui.toast.show({
-            title: 'IUMBTEMS',
-            message: summarize(readSwarmStatus(root)),
-            variant: 'info',
-            duration: 4000,
-          });
-        },
-      },
-    ],
+    commands,
   }));
   return null;
 }

package/runner/tests/test_bet1_spike.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""CI-safe tests for the Bet-1 advisory spike harness (no LLM, no network)."""
+
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from scripts.bet1_advisory_spike import (  # noqa: E402
+    advisory_comment,
+    generate,
+    score_fixture,
+)
+
+
+class TestBet1Harness(unittest.TestCase):
+    def test_generate_counts_and_layout(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            manifest = generate(Path(tmp))
+            self.assertEqual(len(manifest), 20)
+            defective = [e for e in manifest if not e["clean"]]
+            clean = [e for e in manifest if e["clean"]]
+            self.assertEqual(len(defective), 16)
+            self.assertEqual(len(clean), 4)
+            for entry in manifest:
+                self.assertTrue((Path(tmp) / entry["id"] / entry["file"]).exists())
+
+    def test_generate_deterministic(self):
+        with tempfile.TemporaryDirectory() as t1, tempfile.TemporaryDirectory() as t2:
+            m1 = generate(Path(t1))
+            m2 = generate(Path(t2))
+            self.assertEqual(m1, m2)
+
+    def test_scorer_hit_and_tolerance(self):
+        entry = {"id": "x", "file": "users.py", "line": 6, "clean": False}
+        self.assertTrue(score_fixture(entry, "see users.py:6 SQLi")["hit"])
+        self.assertTrue(score_fixture(entry, "users.py L8 concat")["hit"])
+        self.assertFalse(score_fixture(entry, "users.py:40 unrelated")["hit"])
+        self.assertFalse(score_fixture(entry, "no file cited")["hit"])
+
+    def test_scorer_clean_flags_fp(self):
+        entry = {"id": "c", "file": "util.py", "line": None, "clean": True}
+        self.assertTrue(score_fixture(entry, "issue in util.py:2")["false_positive"])
+        self.assertFalse(
+            score_fixture(entry, "all clear, nothing found")["false_positive"]
+        )
+
+    def test_advisory_is_non_blocking_shape(self):
+        comment = advisory_comment("bet1-01", "findings text")
+        self.assertIn("non-blocking", comment)
+        self.assertIn("bet1-01", comment)
+        self.assertIn("findings text", comment)
+
+    def test_cli_generate_and_score_exit_zero(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            for argv in (["--generate", "--dir", tmp], ["--score", "--dir", tmp]):
+                res = subprocess.run(
+                    [
+                        sys.executable,
+                        str(PROJECT_ROOT / "scripts" / "bet1_advisory_spike.py"),
+                    ]
+                    + argv,
+                    capture_output=True,
+                    text=True,
+                    timeout=120,
+                )
+                self.assertEqual(res.returncode, 0, res.stderr)
+            summary = json.loads(
+                subprocess.run(
+                    [
+                        sys.executable,
+                        str(PROJECT_ROOT / "scripts" / "bet1_advisory_spike.py"),
+                        "--score",
+                        "--dir",
+                        tmp,
+                    ],
+                    capture_output=True,
+                    text=True,
+                    timeout=120,
+                ).stdout
+            )
+            self.assertEqual(summary["fixtures"], 20)
+            # No advisories written yet -> all misses, no false positives.
+            self.assertEqual(summary["hits"], 0)
+            self.assertEqual(summary["false_positives"], 0)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/runner/tests/test_opencode_ux.py

@@ -75,6 +75,39 @@ class TestOpenCodeCommandCatalog(unittest.TestCase):
             self.assertIn(c, data["registered"])
             self.assertTrue(data["templates"][c])
 
+    def test_empty_arg_guards(self):
+        res = run_node(
+            """
+            import { OPENCODE_COMMANDS } from "./plugins/opencode/index.js";
+            const guarded = OPENCODE_COMMANDS.filter(c => /empty/i.test(c.template) && /ask the user/i.test(c.template)).map(c => c.name);
+            const withUsage = OPENCODE_COMMANDS.filter(c => !!c.usage).map(c => c.name);
+            console.log(JSON.stringify({guarded, withUsage, total: OPENCODE_COMMANDS.length}));
+            """
+        )
+        self.assertEqual(res.returncode, 0, f"guard test failed: {res.stderr}")
+        data = last_json_object(res.stdout)
+        for c in ["swarm", "scout", "audit"]:
+            self.assertIn(c, data["guarded"])
+        self.assertEqual(len(data["withUsage"]), data["total"])
+
+    def test_async_execute_resolves(self):
+        res = run_node(
+            """
+            import plugin from "./plugins/opencode/index.js";
+            const shell = await plugin.server();
+            let ticked = false;
+            const timer = setInterval(() => { ticked = true; }, 5);
+            const r = await shell.tool.iumbtems_config.execute({});
+            clearInterval(timer);
+            console.log(JSON.stringify({status: r.status, hasContent: typeof r.content === "string" && r.content.length > 0, loopAlive: ticked}));
+            """
+        )
+        self.assertEqual(res.returncode, 0, f"async execute test failed: {res.stderr}")
+        data = last_json_object(res.stdout)
+        self.assertEqual(data["status"], "success")
+        self.assertTrue(data["hasContent"])
+        self.assertTrue(data["loopAlive"])
+
     def test_registration_never_overwrites(self):
         res = run_node(
             """
@@ -180,6 +213,13 @@ class TestInstallOpenCode(unittest.TestCase):
             cmd = cfg["mcp"]["iumbtems"]["command"]
             self.assertTrue(Path(cmd[-1]).is_absolute())
             self.assertEqual(cmd[-1], str(PROJECT_ROOT / "runner" / "mcp_server.py"))
+            # Skills merged as absolute repo paths (relative entries repaired).
+            skill_paths = cfg.get("skills", {}).get("paths", [])
+            self.assertTrue(skill_paths)
+            for sp in skill_paths:
+                self.assertTrue(Path(sp).is_absolute(), f"relative skill path: {sp}")
+            self.assertIn(str(PROJECT_ROOT / "skills" / "grilling"), skill_paths)
+            self.assertFalse(any(not Path(sp).is_absolute() for sp in skill_paths))
             # Second run changes nothing.
             before = oc_path.read_bytes()
             second = self._run_install(home)
@@ -285,6 +325,42 @@ class TestOpenCodeTui(unittest.TestCase):
             self.assertEqual(data["suspect"], 1)
             self.assertEqual(data["requeued"], 2)
 
+    def test_palette_entries_for_all_commands(self):
+        res = run_node(
+            """
+            import { setupTui } from "./plugins/opencode/tui.js";
+            import { OPENCODE_COMMANDS } from "./plugins/opencode/index.js";
+            const renders = [];
+            let factory = null;
+            const toasts = [];
+            const mock = {
+              theme: {}, directory: process.cwd(),
+              ui: { slot: (arg) => { renders.push(arg); return () => {}; }, toast: { show: (t) => toasts.push(t) }, router: { current: () => ({type: "other"}) } },
+              keymap: { layer: (fn) => { factory = fn; } }
+            };
+            setupTui(mock);
+            const appSlot = renders.find(r => r && r.append === "app");
+            if (!appSlot) throw new Error("app slot not registered");
+            appSlot.render();
+            const spec = factory();
+            const palette = spec.commands.filter(c => c.palette);
+            for (const c of palette) c.run();
+            console.log(JSON.stringify({
+              total: spec.commands.length,
+              palette: palette.length,
+              groups: [...new Set(palette.map(c => c.group))],
+              toasts: toasts.length,
+              expected: OPENCODE_COMMANDS.length + 1
+            }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, f"palette test failed: {res.stderr}")
+        data = last_json_object(res.stdout)
+        self.assertEqual(data["total"], data["expected"])
+        self.assertEqual(data["palette"], data["expected"])
+        self.assertEqual(data["groups"], ["IUMBTEMS"])
+        self.assertEqual(data["toasts"], data["expected"])
+
 
 class TestOpenCodeLifecycle(unittest.TestCase):
     @staticmethod