@heretek-ai/epistemic-swarm 0.2.0 → 0.2.3

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)