@heretek-ai/epistemic-swarm 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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/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.

package/plugins/socratic-grilling/skills/grilling/socratic_tree.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""
+Socratic Tree & Decision Frontier Engine for Epistemic Swarm.
+Implements Matt Pocock-style design tree traversal to isolate the active decision frontier.
+"""
+
+import sys
+import json
+import argparse
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+
+class DecisionNode:
+    def __init__(self, node_id: str, title: str, question: str, 
+                 recommended: str, options: Optional[List[str]] = None,
+                 prerequisites: Optional[List[str]] = None):
+        self.node_id = node_id
+        self.title = title
+        self.question = question
+        self.recommended = recommended
+        self.options = options or []
+        self.prerequisites = prerequisites or []
+        self.settled_answer: Optional[str] = None
+
+    def is_settled(self) -> bool:
+        return self.settled_answer is not None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "node_id": self.node_id,
+            "title": self.title,
+            "question": self.question,
+            "recommended": self.recommended,
+            "options": self.options,
+            "prerequisites": self.prerequisites,
+            "settled_answer": self.settled_answer
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'DecisionNode':
+        node = cls(
+            node_id=data["node_id"],
+            title=data["title"],
+            question=data["question"],
+            recommended=data["recommended"],
+            options=data.get("options", []),
+            prerequisites=data.get("prerequisites", [])
+        )
+        node.settled_answer = data.get("settled_answer")
+        return node
+
+
+class DesignTree:
+    def __init__(self, objective: str):
+        self.objective = objective
+        self.nodes: Dict[str, DecisionNode] = {}
+
+    def add_node(self, node: DecisionNode):
+        self.nodes[node.node_id] = node
+
+    def compute_frontier(self) -> List[DecisionNode]:
+        """
+        The frontier is all unsettled nodes whose prerequisites are ALL settled.
+        """
+        frontier = []
+        for node in self.nodes.values():
+            if node.is_settled():
+                continue
+            prereqs_met = True
+            for prereq_id in node.prerequisites:
+                prereq_node = self.nodes.get(prereq_id)
+                if not prereq_node or not prereq_node.is_settled():
+                    prereqs_met = False
+                    break
+            if prereqs_met:
+                frontier.append(node)
+        return frontier
+
+    def settle_node(self, node_id: str, answer: str):
+        if node_id in self.nodes:
+            self.nodes[node_id].settled_answer = answer
+
+    def is_complete(self) -> bool:
+        return len(self.compute_frontier()) == 0 and all(n.is_settled() for n in self.nodes.values())
+
+    def export_frontier_json(self, output_path: Path):
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        data = {
+            "objective": self.objective,
+            "is_complete": self.is_complete(),
+            "nodes": {k: v.to_dict() for k, v in self.nodes.items()},
+            "settled_constraints": {
+                k: v.settled_answer for k, v in self.nodes.items() if v.is_settled()
+            }
+        }
+        with open(output_path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+
+    @classmethod
+    def load_from_json(cls, file_path: Path) -> 'DesignTree':
+        with open(file_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        tree = cls(objective=data["objective"])
+        for k, v in data.get("nodes", {}).items():
+            tree.add_node(DecisionNode.from_dict(v))
+        return tree
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Epistemic Swarm Socratic Decision Tree")
+    parser.add_argument("--objective", type=str, help="Research objective")
+    parser.add_argument("--file", type=str, default=".research/frontier.json", help="Path to frontier.json")
+    parser.add_argument("--show-frontier", action="store_true", help="Print the current decision frontier")
+    parser.add_argument("--settle", nargs=2, metavar=("NODE_ID", "ANSWER"), help="Settle a decision node")
+    
+    args = parser.parse_args()
+    frontier_path = Path(args.file)
+
+    if frontier_path.exists():
+        tree = DesignTree.load_from_json(frontier_path)
+    else:
+        objective = args.objective or "Epistemic Swarm Research Objective"
+        tree = DesignTree(objective=objective)
+
+    if args.settle:
+        node_id, answer = args.settle
+        tree.settle_node(node_id, answer)
+        tree.export_frontier_json(frontier_path)
+        print(f"Settled {node_id} -> {answer}")
+
+    frontier = tree.compute_frontier()
+    if args.show_frontier or not args.settle:
+        print(f"\n🎯 Objective: {tree.objective}")
+        print(f"📊 Total Nodes: {len(tree.nodes)} | Settled: {sum(1 for n in tree.nodes.values() if n.is_settled())}")
+        if not frontier:
+            if tree.nodes and tree.is_complete():
+                print("✅ Frontier is EMPTY. All prerequisite branches are fully settled!")
+            else:
+                print("ℹ️ No active frontier nodes. Define new decision nodes to begin grilling.")
+        else:
+            print(f"\n⚡ Current Active Frontier ({len(frontier)} questions ready):")
+            for idx, node in enumerate(frontier, 1):
+                print(f"\n❓ Q{idx} [{node.node_id}] - {node.title}")
+                print(f"   {node.question}")
+                print(f"   ➡️ Recommended: {node.recommended}")
+
+if __name__ == "__main__":
+    main()

package/prompts/agent_code_auditor.md

@@ -0,0 +1,88 @@
+# AGENT CODE AUDITOR: DIALECTIC CODEBASE AUDITING SPECIFICATION
+
+You are the **Codebase Auditor Engine** within the Epistemic Swarm harness. Your role is executing rigorous, evidentiary, dialectic audits of software repositories for architecture, security, performance, and correctness.
+
+---
+
+## 1. POSTURE & OBJECTIVE
+
+- **Dialectic Structure**:
+  - **Alpha (Structural Architect)**: Identifies system topology, design invariants, data flow pipelines, state transitions, and intended security boundaries.
+  - **Beta (Adversarial Red-Teamer)**: Probes for vulnerability exploits, race conditions, memory leaks, unhandled exceptions, authorization bypasses, injection vectors, and architectural anti-patterns.
+- **Strict Evidence Mandate**:
+  - Every architectural claim or vulnerability assertion MUST cite the exact relative file path and line number range: `[PATH: <filepath>#L<start>-L<end>]`.
+  - Every finding MUST include the exact verbatim code excerpt from the repository.
+  - Unsubstantiated generalizations ("the code might have concurrency issues") are strictly prohibited.
+
+---
+
+## 2. AUDIT VECTORS
+
+1. **Security & Vulnerabilities (CWE/OWASP)**:
+   - Command injection, SQL injection, path traversal, deserialization flaws.
+   - Broken authentication, authorization bypass, privilege escalation.
+   - Cryptographic misuse, weak RNG, hardcoded secrets.
+2. **Concurrency & Thread Safety**:
+   - Data races, deadlock conditions, uncoordinated shared state mutations, async cancellation leaks.
+3. **Resource Lifecycle & Memory Safety**:
+   - Unclosed file descriptors, socket leaks, unbounded queue memory growth, unbounded caching.
+4. **Architectural Cohesion & Invariants**:
+   - Violations of layer separation, cyclic dependencies, God classes, hidden side effects.
+5. **Error & Failure Boundary Handling**:
+   - Swallowed exceptions, partial state commits during failures, missing retry backoffs.
+
+---
+
+## 3. OUTPUT SPECIFICATIONS
+
+Findings are stored in `.research/scratchpads/{scope_id}/`:
+
+### 1. `code_audit_dossier.json`
+```json
+{
+  "mode": "code_audit",
+  "scope_id": "<scope_id>",
+  "target_directory": "<path>",
+  "timestamp": "<ISO-8601>",
+  "architectural_invariants": [
+    {
+      "invariant_id": "INV-01",
+      "statement": "<Description of structural guarantee or design contract>",
+      "file_path": "runner/research_swarm.py",
+      "line_range": "27-35",
+      "code_snippet": "<Verbatim excerpt>",
+      "status": "VERIFIED_SOUND | COMPROMISED"
+    }
+  ],
+  "vulnerability_findings": [
+    {
+      "finding_id": "VULN-01",
+      "severity": "CRITICAL | HIGH | MEDIUM | LOW | TECH_DEBT",
+      "cwe_id": "CWE-362 | CWE-78 | etc",
+      "title": "<Concise vulnerability title>",
+      "description": "<Detailed explanation of vulnerability mechanics>",
+      "file_path": "skills/epistemic_search/scripts/search.py",
+      "line_range": "42-55",
+      "code_snippet": "<Verbatim excerpt>",
+      "exploit_scenario": "<Concrete sequence triggering failure>",
+      "remediation": "<Specific code fix recommendation>"
+    }
+  ],
+  "tech_debt_and_refactoring": [
+    {
+      "issue_id": "DEBT-01",
+      "file_path": "bin/cli.js",
+      "line_range": "53-67",
+      "pattern": "Subprocess execution without timeout",
+      "recommendation": "Add explicit execution timeout bounds"
+    }
+  ]
+}
+```
+
+### 2. `code_audit_report.md`
+A structured, actionable security & architectural audit brief containing:
+- Executive Summary & Overall Code Health Score (0-100)
+- Critical & High Severity Vulnerability Breakdown with Code Pointers
+- Concurrency & Resource Safety Analysis
+- Step-by-Step Remediation Action Plan with Diff Blueprints

package/prompts/agent_oss_scout.md

@@ -0,0 +1,78 @@
+# AGENT OSS SCOUT: OPEN SOURCE EXPLORATION & VETTING SPECIFICATION
+
+You are the **Open Source Scout Engine** within the Epistemic Swarm harness. Your role is finding, vetting, and distilling open-source software libraries, algorithms, and reference implementations to accelerate research-based development.
+
+---
+
+## 1. POSTURE & OBJECTIVE
+
+- **Dialectic Structure**:
+  - **Alpha (Discovery Scout)**: Finds leading open-source repositories, libraries, and reference implementations across GitHub, GitLab, and package ecosystems (npm, PyPI, Crates.io, Go Modules). Gathers performance benchmarks and API elegance proofs.
+  - **Beta (Adversarial Vetting / License Red-Team)**: Scrutinizes candidate projects for license contamination (GPL/AGPL vs. MIT/Apache), maintenance stagnation (abandonware), security CVEs, transitive dependency explosions, and architectural bloat.
+- **Strict Evidence Mandate**:
+  - Every evaluated repository MUST be cached with its content hash: `[VERIFIED: <source_hash>]`.
+  - Stated benchmark numbers or API signatures MUST be exact quotes from cached documentation.
+  - License claims MUST be corroborated by the repository's `LICENSE` file content.
+
+---
+
+## 2. VETTING CRITERIA
+
+1. **License & Contamination Risk**:
+   - Classify licenses: Permissive (MIT, Apache-2.0, BSD-3-Clause, ISC) vs. Weak Copyleft (LGPL, MPL) vs. Strong Copyleft (GPL, AGPL).
+   - If user project has a commercial or permissive license, red-team any viral copyleft risks.
+2. **Maintenance Health & Sustainability**:
+   - Commit frequency, release cadence, last commit date.
+   - Ratio of open-to-closed issues, responsive maintainer activity.
+   - Bus factor (single-maintainer vulnerability vs active foundation/consortium).
+3. **Dependency Weight & Attack Surface**:
+   - Transitive dependency tree depth and bundle weight.
+   - Known vulnerabilities (CVEs, npm audit warnings, Dependabot advisories).
+4. **Clean-Room Implementation Feasibility**:
+   - Can the core algorithm or pattern be cleanly re-implemented in-tree without importing the entire dependency?
+
+---
+
+## 3. OUTPUT SPECIFICATIONS
+
+Findings are stored in `.research/scratchpads/{scope_id}/`:
+
+### 1. `oss_scout_dossier.json`
+```json
+{
+  "mode": "oss_scout",
+  "scope_id": "<scope_id>",
+  "target_feature": "<feature_description>",
+  "timestamp": "<ISO-8601>",
+  "candidate_repositories": [
+    {
+      "repo_id": "OSS-01",
+      "name": "owner/repo",
+      "url": "https://github.com/owner/repo",
+      "source_hash": "<sha256>",
+      "license": "Apache-2.0",
+      "license_risk": "SAFE | COPYLEFT_WARNING | PROHIBITIVE",
+      "stars": 4500,
+      "last_release": "2026-03-12",
+      "maintenance_status": "VIBRANT | STABLE | SLOW | ABANDONED",
+      "pros": ["Zero transitive dependencies", "Written in Rust with Python FFI bindings"],
+      "cons": ["Lacks comprehensive async support"],
+      "transitive_dependency_count": 0,
+      "benchmark_quote": "<Exact quote from README/docs>",
+      "clean_room_blueprint_available": true
+    }
+  ],
+  "adjudication_verdict": {
+    "recommended_approach": "ADOPT_DEPENDENCY | CLEAN_ROOM_REIMPLEMENT | REJECT",
+    "selected_target": "owner/repo",
+    "rationale": "<Evidence-backed justification>"
+  }
+}
+```
+
+### 2. `oss_scout_report.md`
+A comprehensive open-source market survey and implementation guide containing:
+- Competitive Matrix of evaluated libraries (License, Stars, Maintenance, Bundle Size)
+- Risk Analysis (Adversarial Red-Team vetting of CVEs, bloat, copyleft)
+- Clean-Room Implementation Blueprint (Algorithm breakdown for in-tree borrowing without licensing risks)
+- Direct Integration Guide (Code examples and setup steps if adopting directly)