@heretek-ai/epistemic-swarm 0.2.0 → 0.2.3

package/config/opencode-snippet.json

@@ -1,9 +1,38 @@
 {
   "$schema": "https://opencode.ai/config.json",
   "plugin": [
-    "@heretek-ai/epistemic-swarm"
+    [
+      "@heretek-ai/epistemic-swarm",
+      {
+        "search_engine": "duckduckgo",
+        "max_iterations": 2,
+        "mode": "research"
+      }
+    ]
   ],
   "agent": {
+    "code-auditor": {
+      "description": "IUMBTEMS Codebase Auditor: Dialectic architecture mapping and vulnerability red-teaming with line-level proof.",
+      "tools": {
+        "read": true,
+        "write": true,
+        "grep": true,
+        "glob": true,
+        "iumbtems_code_audit": true,
+        "iumbtems_config": true
+      }
+    },
+    "oss-scout": {
+      "description": "IUMBTEMS Open Source Scout: Discovers mature OSS packages, audits copyleft licensing, and generates clean-room blueprints.",
+      "tools": {
+        "read": true,
+        "write": true,
+        "grep": true,
+        "glob": true,
+        "iumbtems_oss_scout": true,
+        "iumbtems_config": true
+      }
+    },
     "alpha-thesis": {
       "description": "IUMBTEMS Proponent Agent: Gathers corroborating primary sources, benchmark results, and empirical proofs.",
       "tools": {
@@ -13,7 +42,9 @@
         "grep": true,
         "glob": true,
         "task": true,
-        "iumbtems_verify_quote": true
+        "iumbtems_swarm_research": true,
+        "iumbtems_verify_quote": true,
+        "iumbtems_config": true
       }
     },
     "beta-redteam": {
@@ -25,6 +56,7 @@
         "grep": true,
         "glob": true,
         "task": true,
+        "iumbtems_swarm_research": true,
         "iumbtems_verify_quote": true
       }
     },
@@ -42,7 +74,11 @@
   "skills": {
     "paths": [
       "./skills/grilling",
-      "./skills/research-cache"
+      "./skills/research_cache",
+      "./skills/epistemic_search",
+      "./skills/swarm_config",
+      "./skills/code_audit",
+      "./skills/oss_scout"
     ]
   }
 }

package/extensions/pi/index.js

@@ -2,7 +2,8 @@
  * IUMBTEMS: I Use My Brain To Express My Self
  * Native Extension for Pi (pi.dev)
  * 
- * Exposes /grill and /swarm slash commands and epistemic verification tools in Pi.
+ * Exposes /swarm, /grill, /swarm-config, /audit, and /scout slash commands
+ * along with epistemic verification and configuration tools in Pi.
  */
 
 import { spawnSync } from 'child_process';
@@ -17,8 +18,9 @@ export default function initPiExtension(pi) {
   // Check if Pi extension API is available
   if (!pi) return;
 
-  // 1. Register /swarm slash command
+  // 1. Register Slash Commands
   if (typeof pi.registerCommand === 'function') {
+    // /swarm: autonomous dialectic research
     pi.registerCommand('swarm', {
       description: 'Run IUMBTEMS dialectic research swarm on an objective',
       usage: '/swarm <objective>',
@@ -46,7 +48,7 @@ export default function initPiExtension(pi) {
       }
     });
 
-    // 2. Register /grill slash command
+    // /grill: Socratic assumption-inversion
     pi.registerCommand('grill', {
       description: 'Launch Socratic grilling and decision tree frontier exploration',
       usage: '/grill [--objective <text>]',
@@ -61,10 +63,75 @@ export default function initPiExtension(pi) {
         ctx.output?.(res.stdout || res.stderr);
       }
     });
+
+    // /swarm-config: Inspect and tune research parameters
+    pi.registerCommand('swarm-config', {
+      description: 'Inspect or update Epistemic Swarm parameters (engine, depth, mode)',
+      usage: '/swarm-config [--engine <e>] [--depth <d>] [--mode <m>] [--show]',
+      handler: async (args, ctx) => {
+        const configScript = path.join(PKG_ROOT, 'skills/swarm_config/configure.py');
+        const rawArgs = args.trim() ? args.trim().split(/\s+/) : ['--show'];
+        const res = spawnSync('python3', [configScript, ...rawArgs], {
+          encoding: 'utf-8',
+          cwd: ctx.cwd || process.cwd(),
+          env: { ...process.env, PYTHONPATH: PKG_ROOT }
+        });
+        ctx.output?.(res.stdout || res.stderr);
+      }
+    });
+
+    // /audit: Dialectic codebase architecture & security audit
+    pi.registerCommand('audit', {
+      description: 'Run dialectic codebase architectural and security audit with line-level proof',
+      usage: '/audit <target_path_or_scope>',
+      handler: async (args, ctx) => {
+        const target = args.trim() || 'Full repository architecture and vulnerability audit';
+        ctx.output?.(`🛡️ [IUMBTEMS Audit] Launching Codebase Audit for: "${target}"...`);
+        const runnerPath = path.join(PKG_ROOT, 'runner/research_swarm.py');
+        const res = spawnSync('python3', [runnerPath, '--mode', 'audit', '--objective', target], {
+          encoding: 'utf-8',
+          cwd: ctx.cwd || process.cwd(),
+          env: { ...process.env, PYTHONPATH: PKG_ROOT }
+        });
+        if (res.status === 0) {
+          ctx.output?.(res.stdout);
+          ctx.output?.('\n✅ Audit complete! Report written to .research/code_audit_report.md');
+        } else {
+          ctx.output?.(`❌ Audit failed:\n${res.stderr || res.stdout}`);
+        }
+      }
+    });
+
+    // /scout: Open-source software discovery & clean-room harvesting
+    pi.registerCommand('scout', {
+      description: 'Scout open-source software libraries, audit copyleft licenses & generate clean-room blueprints',
+      usage: '/scout <feature_or_algorithm>',
+      handler: async (args, ctx) => {
+        const feature = args.trim();
+        if (!feature) {
+          ctx.output?.('⚠️ Please provide a feature to scout. Example: /scout "Zero-dependency Raft consensus in Rust"');
+          return;
+        }
+        ctx.output?.(`🔭 [IUMBTEMS Scout] Scouting open-source solutions for: "${feature}"...`);
+        const runnerPath = path.join(PKG_ROOT, 'runner/research_swarm.py');
+        const res = spawnSync('python3', [runnerPath, '--mode', 'scout', '--objective', feature], {
+          encoding: 'utf-8',
+          cwd: ctx.cwd || process.cwd(),
+          env: { ...process.env, PYTHONPATH: PKG_ROOT }
+        });
+        if (res.status === 0) {
+          ctx.output?.(res.stdout);
+          ctx.output?.('\n✅ Scout complete! Blueprint written to .research/oss_scout_report.md');
+        } else {
+          ctx.output?.(`❌ Scout failed:\n${res.stderr || res.stdout}`);
+        }
+      }
+    });
   }
 
-  // 3. Register tool for epistemic quote verification
+  // 2. Register Agent Tools
   if (typeof pi.registerTool === 'function') {
+    // Tool: iumbtems_verify_quote
     pi.registerTool({
       name: 'iumbtems_verify_quote',
       description: 'Verify that an empirical claim quote matches verbatim text in the source cache',
@@ -86,5 +153,41 @@ export default function initPiExtension(pi) {
         };
       }
     });
+
+    // Tool: iumbtems_config
+    pi.registerTool({
+      name: 'iumbtems_config',
+      description: 'Inspect or modify Epistemic Swarm configuration parameters (search engine, depth, mode) in .research/config.json',
+      parameters: {
+        type: 'object',
+        properties: {
+          search_engine: { type: 'string', enum: ['duckduckgo', 'brave', 'firecrawl', 'searxng'] },
+          max_iterations: { type: 'integer', minimum: 1, maximum: 4 },
+          mode: { type: 'string', enum: ['research', 'audit', 'scout', 'hybrid'] },
+          divergence_threshold: { type: 'number', minimum: 0, maximum: 1 },
+          show: { type: 'boolean', default: false }
+        }
+      },
+      execute: async (args = {}) => {
+        const configScript = path.join(PKG_ROOT, 'skills/swarm_config/configure.py');
+        const cmdArgs = [configScript];
+        if (args.show || (!args.search_engine && !args.max_iterations && !args.mode && args.divergence_threshold === undefined)) {
+          cmdArgs.push('--show');
+        } else {
+          if (args.search_engine) cmdArgs.push('--engine', args.search_engine);
+          if (args.max_iterations) cmdArgs.push('--depth', String(args.max_iterations));
+          if (args.mode) cmdArgs.push('--mode', args.mode);
+          if (args.divergence_threshold !== undefined) cmdArgs.push('--divergence', String(args.divergence_threshold));
+        }
+
+        const res = spawnSync('python3', cmdArgs, {
+          encoding: 'utf-8',
+          env: { ...process.env, PYTHONPATH: PKG_ROOT }
+        });
+        return {
+          content: [{ type: 'text', text: res.stdout || res.stderr }]
+        };
+      }
+    });
   }
 }

package/hooks/hooks.json

@@ -0,0 +1,24 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "WebSearch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"WebSearch intercepted by epistemic-swarm to enforce verified citation integrity. Use epistemic search (python3 ${CLAUDE_PLUGIN_ROOT}/skills/epistemic_search/scripts/search.py \\\"<query>\\\") instead.\"}}'"
+          }
+        ]
+      },
+      {
+        "matcher": "WebFetch",
+        "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.\"}}'"
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "IUMBTEMS: I Use My Brain To Express My Self — High-Integrity Dialectic Research Agent Harness for Claude Code, Pi (pi.dev), and OpenCode V2",
   "main": "bin/cli.js",
   "bin": {
@@ -26,17 +26,33 @@
   "homepage": "https://github.com/Heretek-AI/IUMBTEMS#readme",
   "keywords": [
     "iumbtems",
+    "i-use-my-brain-to-express-my-self",
     "pi-package",
     "opencode",
     "opencode-plugin",
     "claude-code",
     "ai-agents",
+    "autonomous-agents",
+    "multi-agent-systems",
     "dialectic-swarm",
+    "dialectic",
     "epistemic-integrity",
     "research-harness",
+    "research-agent",
     "mcp",
+    "model-context-protocol",
+    "mcp-servers",
     "deep-research",
-    "socratic-grilling"
+    "socratic-grilling",
+    "socratic-questioning",
+    "fact-checking",
+    "red-teaming",
+    "citation-validation",
+    "hallucination-prevention",
+    "swarm-intelligence",
+    "code-audit",
+    "oss-scout",
+    "clean-room-engineering"
   ],
   "pi": {
     "extensions": [
@@ -44,7 +60,11 @@
     ],
     "skills": [
       "./skills/grilling",
-      "./skills/research-cache"
+      "./skills/research_cache",
+      "./skills/epistemic_search",
+      "./skills/swarm_config",
+      "./skills/code_audit",
+      "./skills/oss_scout"
     ],
     "prompts": [
       "./prompts/*.md"
@@ -56,6 +76,7 @@
     "bin",
     "prompts",
     "skills",
+    "hooks",
     "config",
     "runner",
     "extensions",
@@ -63,6 +84,7 @@
     ".claude-plugin",
     "install.sh",
     "README.md",
+    "MARKETPLACE.md",
     "LICENSE"
   ],
   "engines": {
@@ -70,6 +92,7 @@
   },
   "scripts": {
     "test": "python3 -m unittest discover -s runner/tests",
+    "validate:claude": "claude plugin validate --strict .claude-plugin/marketplace.json && claude plugin validate --strict .",
     "prepack": "python3 -m unittest discover -s runner/tests",
     "install-local": "bash install.sh"
   }

package/plugins/opencode/index.js

@@ -2,8 +2,8 @@
  * IUMBTEMS: I Use My Brain To Express My Self
  * Native Plugin for OpenCode V2 (opencode.ai)
  * 
- * Exposes dialectic swarm research tools, Socratic decision frontier calculation,
- * and content-addressed quote verification directly into OpenCode V2 agents.
+ * Exposes dialectic swarm research tools, codebase auditing, open-source scouting,
+ * configuration management, and content-addressed quote verification directly into OpenCode V2 agents.
  */
 
 import { spawnSync } from 'child_process';
@@ -18,10 +18,150 @@ export function createOpenCodePlugin(context = {}) {
   return {
     id: "heretek.iumbtems.epistemic-swarm",
     name: "IUMBTEMS Epistemic Swarm",
-    version: "0.1.0",
-    description: "I Use My Brain To Express My Self: Dialectic research swarm enforcing empirical verification",
+    version: "0.2.3",
+    description: "I Use My Brain To Express My Self: High-integrity dialectic research, code audits, and open-source scouting",
 
     server: (toolContext) => [
+      {
+        name: "iumbtems_config",
+        description: "Inspect or modify the active Epistemic Swarm configuration (search engine, depth/iterations, operating mode, divergence threshold) in .research/config.json.",
+        input: {
+          type: "object",
+          properties: {
+            search_engine: {
+              type: "string",
+              enum: ["duckduckgo", "brave", "firecrawl", "searxng"],
+              description: "Primary search engine (duckduckgo is the zero-key free default)"
+            },
+            max_iterations: {
+              type: "integer",
+              minimum: 1,
+              maximum: 4,
+              description: "Maximum dialectic research iterations / depth (1-4)"
+            },
+            mode: {
+              type: "string",
+              enum: ["research", "audit", "scout", "hybrid"],
+              description: "Operating mode: research (literature), audit (codebase), scout (OSS), hybrid"
+            },
+            divergence_threshold: {
+              type: "number",
+              minimum: 0.0,
+              maximum: 1.0,
+              description: "Auditor divergence threshold (default 0.75)"
+            },
+            show: {
+              type: "boolean",
+              description: "Just inspect current configuration without modifying",
+              default: false
+            }
+          }
+        },
+        options: { codemode: false },
+        execute: async (args = {}) => {
+          const configScript = path.join(PKG_ROOT, "skills/swarm_config/configure.py");
+          const cmdArgs = [configScript];
+
+          if (args.show || (!args.search_engine && !args.max_iterations && !args.mode && args.divergence_threshold === undefined)) {
+            cmdArgs.push("--show");
+          } else {
+            if (args.search_engine) cmdArgs.push("--engine", args.search_engine);
+            if (args.max_iterations) cmdArgs.push("--depth", String(args.max_iterations));
+            if (args.mode) cmdArgs.push("--mode", args.mode);
+            if (args.divergence_threshold !== undefined) cmdArgs.push("--divergence", String(args.divergence_threshold));
+          }
+
+          const res = spawnSync("python3", cmdArgs, {
+            encoding: "utf-8",
+            cwd: toolContext?.cwd || process.cwd(),
+            env: { ...process.env, PYTHONPATH: PKG_ROOT }
+          });
+
+          return {
+            content: res.stdout || res.stderr,
+            status: res.status === 0 ? "success" : "error"
+          };
+        }
+      },
+
+      {
+        name: "iumbtems_code_audit",
+        description: "Run a dialectic codebase architectural and security audit pairing a structural architect with an adversarial red-teamer.",
+        input: {
+          type: "object",
+          properties: {
+            target: {
+              type: "string",
+              description: "Target directory, file, or architectural component to audit"
+            },
+            mock_mode: {
+              type: "boolean",
+              description: "Run in mock mode without invoking LLM tokens",
+              default: false
+            }
+          },
+          required: ["target"]
+        },
+        options: { codemode: false },
+        execute: async (args) => {
+          const runnerPath = path.join(PKG_ROOT, "runner/research_swarm.py");
+          const cmdArgs = [runnerPath, "--mode", "audit", "--objective", args.target];
+          if (args.mock_mode) {
+            cmdArgs.push("--mock-claude");
+          }
+
+          const res = spawnSync("python3", cmdArgs, {
+            encoding: "utf-8",
+            cwd: toolContext?.cwd || process.cwd(),
+            env: { ...process.env, PYTHONPATH: PKG_ROOT }
+          });
+
+          return {
+            content: res.stdout || res.stderr,
+            status: res.status === 0 ? "success" : "error"
+          };
+        }
+      },
+
+      {
+        name: "iumbtems_oss_scout",
+        description: "Scout open-source software libraries, benchmark candidate implementations, red-team viral copyleft (GPL/AGPL), and produce clean-room implementation blueprints.",
+        input: {
+          type: "object",
+          properties: {
+            feature: {
+              type: "string",
+              description: "The feature, algorithm, or capability to scout in open source"
+            },
+            mock_mode: {
+              type: "boolean",
+              description: "Run in mock mode without invoking LLM tokens",
+              default: false
+            }
+          },
+          required: ["feature"]
+        },
+        options: { codemode: false },
+        execute: async (args) => {
+          const runnerPath = path.join(PKG_ROOT, "runner/research_swarm.py");
+          const cmdArgs = [runnerPath, "--mode", "scout", "--objective", args.feature];
+          if (args.mock_mode) {
+            cmdArgs.push("--mock-claude");
+          }
+
+          const res = spawnSync("python3", cmdArgs, {
+            encoding: "utf-8",
+            cwd: toolContext?.cwd || process.cwd(),
+            env: { ...process.env, PYTHONPATH: PKG_ROOT }
+          });
+
+          return {
+            content: res.stdout || res.stderr,
+            status: res.status === 0 ? "success" : "error"
+          };
+        }
+      },
+
       {
         name: "iumbtems_swarm_research",
         description: "Execute an autonomous dialectic research swarm on an objective using Agent Alpha (Thesis) and Agent Beta (Red Team).",
@@ -139,7 +279,21 @@ export function createOpenCodePlugin(context = {}) {
     ],
 
     setup: async (appContext) => {
-      // OpenCode V2 lifecycle hook
+      const opts = context.options || appContext?.options;
+      if (opts && typeof opts === "object") {
+        const configScript = path.join(PKG_ROOT, "skills/swarm_config/configure.py");
+        const cmdArgs = [configScript];
+        if (opts.search_engine) cmdArgs.push("--engine", opts.search_engine);
+        if (opts.max_iterations) cmdArgs.push("--depth", String(opts.max_iterations));
+        if (opts.mode) cmdArgs.push("--mode", opts.mode);
+        if (opts.divergence_threshold !== undefined) cmdArgs.push("--divergence", String(opts.divergence_threshold));
+        if (cmdArgs.length > 1) {
+          spawnSync("python3", cmdArgs, {
+            cwd: appContext?.cwd || toolContext?.cwd || process.cwd(),
+            env: { ...process.env, PYTHONPATH: PKG_ROOT }
+          });
+        }
+      }
       return { initialized: true, platform: "opencode-v2" };
     }
   };

package/plugins/research-cache/.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "research-cache",
+  "version": "0.2.0",
+  "description": "Content-addressed SHA256 Markdown source hashing and verbatim quote verification engine.",
+  "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/research_cache"
+  ]
+}

package/plugins/socratic-grilling/.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "socratic-grilling",
+  "version": "0.2.0",
+  "description": "Matt Pocock-style Socratic interrogation, premise inversion, and lateral exploration skill for Claude Code.",
+  "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"
+  ]
+}

package/plugins/socratic-grilling/skills/grilling/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: grilling
+description: Socratic grilling and assumption-inversion skill for deep research. Uses Matt Pocock-style design trees to explore the problem frontier divergently before committing to search queries.
+---
+
+# Socratic Grilling & Divergent Research Framing
+
+Interview the user relentlessly until you reach an airtight, shared understanding of the research scope. Map the problem as a **design tree**: every foundational assumption branches into the technical decisions and empirical hypotheses that hang off it.
+
+## 1. THE FRONTIER METHODOLOGY
+
+1. Work the tree in **rounds**.
+2. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask *now* without guessing at answers you haven't heard yet.
+3. Ask the whole frontier in one round: number each question and provide your recommended answer.
+4. Then wait for the user's answers before moving to the next round.
+
+## 2. FORMATTING A ROUND
+
+```
+❓ **Q1 - <Question Title>**: <Question context, premise inversion, trade-offs, multiple options>
+
+➡️ **Recommended**: <Your recommended answer with rationale>
+
+---
+
+❓ **Q2 - <Question Title>**: <Question context, trade-offs>
+
+➡️ **Recommended**: <Your recommended answer with rationale>
+```
+
+## 3. FACTUAL VS. DECISIONAL SEPARATION
+
+- **Facts are the agent's job**: When a frontier question hinges on an empirical fact (e.g. library benchmarks, API specs, hardware limits), **DO NOT ASK THE USER**. Dispatch a tool call or subagent to look it up in the codebase or online.
+- **Decisions are the user's**: High-level trade-offs, architectural philosophy, threat models, and priority ranking belong to the user. Put each decision to them clearly.
+
+## 4. ASSUMPTION INVERSION TACTICS
+
+Always challenge default premises in Round 1:
+- *Inversion*: What if the primary objective is rendered obsolete by a radical alternative?
+- *Scale Extremes*: What breaks at 100x scale? What breaks at 0 resources?
+- *Adversarial Posture*: How would an intelligent adversary exploit or falsify this design?
+
+## 5. FRONTIER RESOLUTION & FREEZING
+
+When every branch of the design tree has been visited and the frontier is empty:
+1. Summarize the settled constraints.
+2. Save the settled state to `.research/frontier.json` using `python3 skills/grilling/socratic_tree.py --export`.
+3. Hand off the settled frontier to the **Swarm Orchestrator** to begin empirical dialectic execution.