mindforge-cc 3.0.0 → 4.3.0

package/bin/models/model-broker.js

@@ -0,0 +1,110 @@
+/**
+ * MindForge — ModelBroker (Pillar V: Autonomous FinOps Hub)
+ * Calculates C2C (Confidence-to-Cost) and routes tasks to optimal models.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class ModelBroker {
+  constructor(config = {}) {
+    this.projectRoot = config.projectRoot || process.cwd();
+    this.defaults = {
+      EXECUTOR_MODEL: 'claude-3-5-sonnet',
+      PLANNER_MODEL: 'claude-3-5-sonnet',
+      SECURITY_MODEL: 'claude-3-opus',
+      QA_MODEL: 'claude-3-5-sonnet',
+      RESEARCH_MODEL: 'claude-3-5-sonnet',
+      DEBUG_MODEL: 'claude-3-5-sonnet',
+      QUICK_MODEL: 'claude-3-haiku',
+    };
+  }
+
+  /**
+   * Resolves the optimal model for a given task.
+   * @param {Object} context - Task context (persona, difficulty, tier)
+   * @returns {Object} - Resolved model details (modelId, costTier, reasoning)
+   */
+  resolveModel(context) {
+    const { persona, difficulty, tier } = context;
+    let modelId = this.defaults.EXECUTOR_MODEL;
+    let reasoning = 'Default executor model.';
+
+    // 1. Check Security Tier (T3 requires premium models)
+    if (tier === 3) {
+      modelId = this.defaults.SECURITY_MODEL;
+      reasoning = 'Tier 3 (Principal) action requires high-trust model (Opus).';
+      return { modelId, costTier: 'high', reasoning };
+    }
+
+    // 2. Map Persona to Base Model
+    const personaMap = {
+      'executor': 'EXECUTOR_MODEL',
+      'planner': 'PLANNER_MODEL',
+      'security-reviewer': 'SECURITY_MODEL',
+      'qa-engineer': 'QA_MODEL',
+      'researcher': 'RESEARCH_MODEL',
+      'debug-specialist': 'DEBUG_MODEL',
+    };
+
+    if (personaMap[persona]) {
+      modelId = this.defaults[personaMap[persona]];
+      reasoning = `Routed to ${persona} specialist model.`;
+    }
+
+    // 3. Calculate C2C (Confidence-to-Cost)
+    // If difficulty is low (< 2.0), route to Quick Model (Haiku) to save costs.
+    if (difficulty < 2.0 && difficulty !== undefined) {
+      const originalModel = modelId;
+      modelId = this.defaults.QUICK_MODEL;
+      reasoning = `Low difficulty (${difficulty}) - C2C Optimization: Switched ${originalModel} to Haiku.`;
+      return { modelId, costTier: 'low', reasoning };
+    }
+
+    // 4. Handle Complex Tasks (Difficulty > 4.0)
+    if (difficulty > 4.0) {
+      modelId = this.defaults.SECURITY_MODEL; // Use Opus for high complexity
+      reasoning = `High difficulty (${difficulty}) - Complexity routing: Upgraded to Opus.`;
+      return { modelId, costTier: 'high', reasoning };
+    }
+
+    return { modelId, costTier: 'medium', reasoning };
+  }
+
+  /**
+   * Tracks the "Agentic ROI" for a completed task.
+   * @param {Object} report - Task execution report (tokens, duration, status)
+   */
+  trackROI(report) {
+    const roiPath = path.join(this.projectRoot, '.planning', 'ROI.jsonl');
+    const entry = {
+      timestamp: new Date().toISOString(),
+      planId: report.planId,
+      task: report.taskName,
+      model: report.modelId,
+      costTier: report.costTier,
+      inputTokens: report.inputTokens,
+      outputTokens: report.outputTokens,
+      durationMs: report.durationMs,
+      status: report.status,
+      goalAchieved: report.status === 'completed' ? 1 : 0,
+      estimatedCostUSD: this.estimateCost(report.modelId, report.inputTokens, report.outputTokens),
+    };
+
+    fs.appendFileSync(roiPath, JSON.stringify(entry) + '\n');
+  }
+
+  estimateCost(modelId, input, output) {
+    // Mock cost estimation logic per 1M tokens
+    const rates = {
+      'claude-3-opus': { in: 15, out: 75 },
+      'claude-3-5-sonnet': { in: 3, out: 15 },
+      'claude-3-haiku': { in: 0.25, out: 1.25 },
+    };
+
+    const rate = rates[modelId] || rates['claude-3-5-sonnet'];
+    return (input / 1_000_000) * rate.in + (output / 1_000_000) * rate.out;
+  }
+}
+
+module.exports = ModelBroker;

package/docs/INTELLIGENCE-MESH.md

@@ -0,0 +1,32 @@
+# MindForge Global Intelligence Mesh (Memory)
+v4.2.5 — Cross-Repository Knowledge Sharing
+
+## 1. Overview
+The **Global Intelligence Mesh** elevates MindForge from a repository-local assistant to an organization-wide intelligence asset. It enables multiple projects to share architectural insights, past failure patterns ("Ghost Patterns"), and success-verified designs without manual intervention.
+
+## 2. Architecture
+The mesh consists of two primary components residing in `.mindforge/memory/engine/`:
+
+### A. The Semantic Hub (`semantic-hub.js`)
+- **Role:** Synchronizes local project memory with a global, repository-agnostic store located at `~/.mindforge/memory/global`.
+- **Deduplication:** Uses cryptographic ID-based matching to ensure only unique observations are moved to the global hub.
+- **Privacy:** Sync is opt-in for sensitive data, but architectural patterns and "failure context" are pushed by default to prevent organizational redundancy.
+
+### B. Ghost Pattern Detector (`ghost-pattern-detector.js`)
+- **Role:** A proactive risk mitigation engine that scans incoming proposals against known "Ghost Patterns" (past failures from other projects).
+- **Triggers:** Automatically invoked during the `plan` phase of any mission-critical task (Tier 2-3).
+- **Risk Levels:**
+    - **CRITICAL:** High similarity with a past p0 security failure or environment leak.
+    - **HIGH:** Similarity with a performance regression or architectural anti-pattern.
+
+## 3. Workflow Hook
+1. **Capture:** When a task results in a significant learning, `mf-memory` flags it as a `decision` or `pattern`.
+2. **Push:** The `SemanticHub` periodically syncs these to the global store.
+3. **Pull/Scan:** When starting a new project or task, the `GhostPatternDetector` queries the global hub to check if the proposed approach has "ghosts" (failed elsewhere).
+
+## 4. Usage in Enterprise
+- **Zero-Redundancy Research:** If one team spends 10k tokens researching a specific library integration, the resulting "Knowledge Item" is immediately available to every other project in the mesh.
+- **Organization-Wide Self-Healing:** Security fixes in one repo become proactive warnings in all others.
+
+---
+*Status: Foundation Implemented & Verified (v4.2.5)*

package/docs/PERSONAS.md

@@ -35,6 +35,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:init-project`, `/mindforge:plan-phase`, `/mindforge:agent analyst` |
 | **Tools** | Read, Write, Bash, Grep |
 | **Color** | `blue` |
+| **Trust Tier** | `1` |
 | **Produces** | `.planning/REQUIREMENTS.md`, `.planning/PROJECT.md` |
 
 **Capabilities:**
@@ -53,6 +54,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:plan-phase`, `/mindforge:agent architect` |
 | **Tools** | Read, Write, Bash, Grep, Glob |
 | **Color** | `purple` |
+| **Trust Tier** | `3` |
 | **Produces** | `.planning/ARCHITECTURE.md`, `.planning/decisions/ADR-*.md` |
 
 **Capabilities:**
@@ -72,6 +74,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:execute-phase`, `/mindforge:agent developer` |
 | **Tools** | Read, Write, Bash, Grep, Glob, CommandStatus, Context7 |
 | **Color** | `green` |
+| **Trust Tier** | `2` |
 | **Produces** | Source code, Unit tests, Implementation Summaries |
 
 **Capabilities:**
@@ -90,6 +93,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:verify-phase`, `/mindforge:agent qa-engineer` |
 | **Tools** | Read, Write, Bash, Grep, Glob, CommandStatus |
 | **Color** | `yellow` |
+| **Trust Tier** | `2` |
 | **Produces** | `UAT.md`, `BUGS.md` |
 
 **Capabilities:**
@@ -109,6 +113,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:security-scan`, `/mindforge:agent security-reviewer` |
 | **Tools** | Read, Write, Bash, Grep, Glob, CommandStatus |
 | **Color** | `red` |
+| **Trust Tier** | `3` |
 | **Produces** | `SECURITY-REVIEW.md` |
 
 **Capabilities:**
@@ -181,6 +186,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:research`, `/mindforge:agent research-agent` |
 | **Tools** | Read, Write, Bash, Grep, Glob, Browser, Context7 |
 | **Color** | `cyan` |
+| **Trust Tier** | `1` |
 | **Produces** | `RESEARCH-NOTES-*.md` |
 
 **Capabilities:**
@@ -199,6 +205,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:plan-phase`, `/mindforge:agent decision-architect` |
 | **Tools** | Read, Write, Bash, Grep, Glob |
 | **Color** | `purple` |
+| **Trust Tier** | `3` |
 | **Produces** | `DECISION-*.md` |
 
 **Capabilities:**
@@ -218,6 +225,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:release`, `/mindforge:agent release-manager` |
 | **Tools** | Read, Write, Bash, Grep, Glob, CommandStatus |
 | **Color** | `blue` |
+| **Trust Tier** | `3` |
 | **Produces** | `CHANGELOG.md`, Git tags, Release Notes |
 
 **Capabilities:**
@@ -236,6 +244,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:ship`, `/mindforge:agent tech-writer` |
 | **Tools** | Read, Write, Bash, Grep, Glob, Context7 |
 | **Color** | `cyan` |
+| **Trust Tier** | `1` |
 | **Produces** | `README.md`, API Reference, Runbooks |
 
 **Capabilities:**
@@ -254,6 +263,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:validate-phase`, `/mindforge:agent coverage-specialist` |
 | **Tools** | Read, Write, Bash, Grep, Glob, CommandStatus |
 | **Color** | `yellow` |
+| **Trust Tier** | `2` |
 | **Produces** | `COVERAGE-AUDIT.md` |
 
 **Capabilities:**
@@ -272,6 +282,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:research`, `/mindforge:agent advisor-researcher` |
 | **Tools** | Read, Write, Bash, Grep, Glob, Browser, Context7 |
 | **Color** | `cyan` |
+| **Trust Tier** | `1` |
 | **Produces** | Comparison tables, Rationale documents |
 
 **Capabilities:**
@@ -290,6 +301,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:init-project`, `/mindforge:agent project-researcher` |
 | **Tools** | Read, Write, Bash, Grep, Glob, Browser, Context7 |
 | **Color** | `purple` |
+| **Trust Tier** | `1` |
 | **Produces** | `SUMMARY.md`, `STACK.md`, `ARCHITECTURE.md` |
 
 **Capabilities:**
@@ -308,6 +320,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:research`, `/mindforge:agent research-synthesizer` |
 | **Tools** | Read, Write, Bash, Grep, Glob |
 | **Color** | `purple` |
+| **Trust Tier** | `1` |
 | **Produces** | Integrated `SUMMARY.md` |
 
 **Capabilities:**
@@ -326,6 +339,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:plan-phase`, `/mindforge:agent ui-researcher` |
 | **Tools** | Read, Write, Bash, Grep, Glob, Browser, Context7 |
 | **Color** | `#E879F9` |
+| **Trust Tier** | `1` |
 | **Produces** | `UI-SPEC.md` |
 
 **Capabilities:**
@@ -344,6 +358,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:plan-phase`, `/mindforge:agent phase-researcher` |
 | **Tools** | Read, Write, Bash, Grep, Glob, Context7 |
 | **Color** | `blue` |
+| **Trust Tier** | `1` |
 | **Produces** | `RESEARCH.md` |
 
 **Capabilities:**
@@ -362,6 +377,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:plan-phase`, `/mindforge:agent planner` |
 | **Tools** | Read, Write, Bash, Grep, Glob |
 | **Color** | `blue` |
+| **Trust Tier** | `1` |
 | **Produces** | `PLAN-*.md` (XML task breakdown)|
 
 **Capabilities:**
@@ -380,6 +396,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:verify-phase`, `/mindforge:agent integration-checker` |
 | **Tools** | Read, Write, Bash, Grep, Glob |
 | **Color** | `blue` |
+| **Trust Tier** | `1` |
 | **Produces** | `INTEGRATION-REPORT.md` |
 
 **Capabilities:**
@@ -398,6 +415,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:validate-phase`, `/mindforge:agent nyquist-auditor` |
 | **Tools** | Read, Write, Bash, Grep, Glob, CmdStatus, ReadTerminal |
 | **Color** | `#8B5CF6` |
+| **Trust Tier** | `2` |
 | **Produces** | `VALIDATION-REPORT.md` |
 
 **Capabilities:**
@@ -416,6 +434,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:plan-phase`, `/mindforge:agent plan-checker` |
 | **Tools** | Read, Write, Bash, Grep, Glob |
 | **Color** | `yellow` |
+| **Trust Tier** | `1` |
 | **Produces** | `PLAN-VERDICT.md` |
 
 **Capabilities:**
@@ -434,6 +453,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:verify-phase`, `/mindforge:agent ui-auditor` |
 | **Tools** | Read, Write, Bash, Grep, Glob |
 | **Color** | `#F472B6` |
+| **Trust Tier** | `1` |
 | **Produces** | `UI-REVIEW.md` |
 
 **Capabilities:**
@@ -452,6 +472,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:plan-phase`, `/mindforge:agent ui-checker` |
 | **Tools** | Read, Write, Bash, Grep, Glob |
 | **Color** | `#22D3EE` |
+| **Trust Tier** | `1` |
 | **Produces** | `UI-SPEC-VERDICT.md` |
 
 **Capabilities:**
@@ -470,6 +491,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:verify-phase`, `/mindforge:agent verifier` |
 | **Tools** | Read, Write, Bash, Grep, Glob |
 | **Color** | `green` |
+| **Trust Tier** | `1` |
 | **Produces** | `VERIFICATION.md` |
 
 **Capabilities:**
@@ -488,6 +510,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:execute-phase`, `/mindforge:agent executor` |
 | **Tools** | Read, Write, Bash, Grep, Glob, CmdStatus, ReadTerminal |
 | **Color** | `yellow` |
+| **Trust Tier** | `3` |
 | **Produces** | Atomic commits, Execution summaries |
 
 **Capabilities:**
@@ -498,6 +521,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 ---
 
 ### mindforge-debugger (The RCA Scientist)
+**Trust Tier:** `1`
 
 **Role:** Specialist in systematic root cause analysis and complex defect resolution.
 
@@ -516,6 +540,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 ---
 
 ### mindforge-assumptions-analyzer-extend (The Reality Checker)
+**Trust Tier:** `1`
 
 **Role:** Reality checker for identifying hidden codebase constraints and risks.
 
@@ -542,6 +567,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:map-codebase`, `/mindforge:agent codebase-mapper` |
 | **Tools** | Read, Write, Bash, Grep, Glob |
 | **Color** | `cyan` |
+| **Trust Tier** | `1` |
 | **Produces** | `CONVENTIONS.md`, `STRUCTURE.md` |
 
 **Capabilities:**
@@ -560,6 +586,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:map-codebase`, `/mindforge:agent codebase-mapper-extend` |
 | **Tools** | Read, Write, Bash, Grep, Glob |
 | **Color** | `cyan` |
+| **Trust Tier** | `1` |
 | **Produces** | `STACK.md`, `ARCHITECTURE.md`, `CONVENTIONS.md` |
 
 **Capabilities:**
@@ -596,6 +623,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Spawned by** | `/mindforge:agent user-profiler` |
 | **Tools** | Read, Write, Bash, Grep, Glob |
 | **Color** | `magenta` |
+| **Trust Tier** | `1` |
 | **Produces** | `USER-PROFILE.md` |
 
 **Capabilities:**
@@ -605,36 +633,71 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 
 ---
 
+## Swarm Clusters (The Agentic Mesh) [v4.2]
+
+MindForge V4 introduces the ability to spawn dynamic, task-aware clusters of specialist personas. These swarms work in parallel with shared state to solve complex enterprise challenges.
+
+### Enterprise Swarm Templates
+
+| Swarm | Leader | Members | Focus |
+| :--- | :--- | :--- | :--- |
+| **UISwarm** | ui-auditor | developer, accessibility, whimsy-injector | Visual fidelity, interaction, WCAG 2.2 |
+| **BackendSwarm** | architect | developer, security-reviewer, db-optimizer | Architecture, performance, API versioning |
+| **SecuritySwarm** | security-reviewer | architect, developer, threat-detection | OWASP mitigation, secret detection |
+| **AIEngineeringSwarm** | ai-engineer | prompt-engineer, developer, model-qa | Hallucination mitigation, grounding |
+| **IncidentResponse** | sre-engineer | developer, incident-commander, debugger | RCA, hotfix, post-mortem |
+| **ComplianceSwarm** | compliance-auditor | legal-compliance, architect, security | GDPR/SOC2 alignment, PII masking |
+| **IdentityTrustSwarm** | identity-architect | security-reviewer, architect, blockchain | Zero-Trust, DID-based signing |
+| **DataMeshSwarm** | data-engineer | db-optimizer, analyst, compliance | Lakehouse patterns, ETL integrity |
+
+### Swarm Governance Protocols
+
+- **Trust Tiers**: Swarms are enforced by ZTAI (Zero-Trust Agentic Identity) tiers (0-3).
+- **Decision Gates**: High-risk swarms (e.g., Compliance) use **Human-in-the-Loop (HITL)** gates.
+- **Resource Budgets**: Performance-aware routing based on confidence-to-cost (C2C) ratios.
+- **Mesh Synthesis**: The Swarm Leader synthesizes all specialist outputs into a single, cohesive `SWARM-SUMMARY`.
+
+---
+
 ### MF-Series: Fundamental Framework Identities
 
 The MF-Series represents the "Core Essence" of the MindForge agentic framework. These personas provide a standardized, high-value foundation for delegation and multi-agent interaction.
 
 #### mf-planner (The Strategist)
+**Trust Tier:** `1`
 **Role:** High-level goal decomposition and structured planning.
 - **Triggers:** `plan`, `decompose`, `roadmap`.
 - **Produces:** Structured JSON/Markdown execution plans.
 
 #### mf-executor (The Pilot)
+**Trust Tier:** `3`
 **Role:** Precise implementation and high-fidelity plan execution.
 - **Triggers:** `execute`, `implement`, `fix`.
 - **Produces:** Implementation details and completion status.
 
 #### mf-researcher (The Detective)
+**Trust Tier:** `1`
 **Role:** Knowledge gathering and objective approach comparison.
+
 - **Triggers:** `research`, `explore`, `benchmark`.
 - **Produces:** Tradeoff analysis and strategy recommendations.
 
 #### mf-reviewer (The Auditor)
+**Trust Tier:** `1`
 **Role:** Quality assurance and output validation.
+
 - **Triggers:** `review`, `audit`, `validate`.
 - **Produces:** Feedback, issues, and approval status.
 
 #### mf-memory (The Clerk)
+**Trust Tier:** `1`
 **Role:** Persistence management and knowledge graph maintenance.
+
 - **Triggers:** `remember`, `store`, `learning`.
 - **Produces:** Memory updates and linked patterns.
 
 #### mf-tool (The Operator)
+**Trust Tier:** `2`
 **Role:** Safe external system interaction and tool execution.
 - **Triggers:** `tool`, `git`, `api`, `shell`.
 - **Produces:** Action results and safety logs.

package/docs/architecture/NEXUS-DASHBOARD.md

@@ -0,0 +1,35 @@
+# MindForge Nexus: Observability Dashboard
+
+## Vision
+The Nexus Dashboard provides real-time visibility into the "thought chains" of the agentic mesh. It transforms the linear `AUDIT.jsonl` into a hierarchical, interactive visualization of reasoning and execution waves.
+
+## Core Views
+
+### 1. Mesh Trace View (Gantt/Waterfall)
+- **Trace Visualization:** Displays hierarchical spans (Waves -> Clusters -> Tasks).
+- **Critical Path Highlighting:** Identifies bottlenecks in parallel wave execution.
+- **Span Metadata:** Hovering over a span reveals the agent persona, trust tier, and execution time.
+
+### 2. Reasoning Heatmap (ART)
+- **Density Maps:** Visualizes where the agents are performing the most "Thinking" (debate cycles).
+- **ADS Breakdown:** Highlights Adversarial Decision Synthesis debates between specialists (e.g., Security vs Dev).
+- **Thought Stream:** Real-time feed of `reasoning_trace` events.
+
+### 3. ZTAI Trust Heatmap
+- **Security Posture:** Real-time visibility into which tasks are running in which Trust Tier (0-3).
+- **Policy Violations:** Instant alerts when an agent attempts to bypass a HITL decision gate.
+
+## Technical Stack
+- **Engine:** Next.js (React) + D3.js for complex tree visualizations.
+- **Data Source:** Tail-following parser for `.planning/AUDIT.jsonl`.
+- **State Management:** Zustand for real-time trace aggregation.
+
+## API Hooks
+```javascript
+// Example Dashboard Feed Hook
+const useNexusFeed = () => {
+  // Listen for new AUDIT.jsonl entries
+  // Reconstruct span hierarchy on the fly
+  // Return nodes and edges for D3 renderer
+};
+```

package/docs/architecture/V4-SWARM-MESH.md

@@ -0,0 +1,77 @@
+# Architecture: V4 Swarm Mesh Paradigm
+
+## 1. Overview
+
+MindForge V4 introduces the **Swarm Mesh**, a decentralized multi-agent orchestration model. Unlike the sequential subagent model of previous versions, the Mesh enables **Dynamic Task-Aware Clusters** that execute in parallel with shared state and unified governance.
+
+---
+
+## 2. Core Components
+
+### I. SwarmController
+The central engine logic that handles:
+- **Complexity Analysis**: Deciding if a task requires a single agent or a specialist cluster.
+
+- **Cluster Spawning**: Selecting the optimal swarm template based on tech stack and task category.
+
+- **Identity Governance**: Validating **ZTAI (Zero-Trust Agentic Identity)** trust tiers and verifying cryptographic signatures for specialized results.
+
+### II. PersonaFactory (Micro-Personas)
+Dynamically creates specialized "Micro-Personas" on-the-fly by:
+- Patching base personas (e.g., `developer`) with **Context7** library insights.
+- Injecting task-specific imperative rules and role specializations.
+
+### III. Mesh Parallelism (WaveExecutor)
+The `WaveExecutor` has been refactored to support:
+- **Parallel Swarm Spawning**: Multiple specialists (e.g., UI Auditor + Accessibility Specialist) working on the same branch simultaneously.
+
+- **Shared State (`SWARM-STATE.json`)**: Real-time coordination and conflict avoidance between swarm members.
+
+- **Consolidation Protocol**: The Swarm Leader synthesizes all findings into a unified `SWARM-SUMMARY.md`.
+
+### IV. MindForge Nexus: ART (Agentic Reasoning Tracing)
+The definitive observability layer for the mesh:
+- **Reasoning Spans**: Hierarchical tracking of every "thought" and decision point.
+- **Trace Propagation**: Context-aware trace IDs that link waves, tasks, and clusters.
+- **Audit Integration**: Direct link to `.planning/AUDIT.jsonl` via `trace_id` and `span_id`.
+
+### V. Global Intelligence Mesh (The Hub)
+The foundation for cross-repository organizational memory:
+- **Semantic Hub**: Syncs local knowledge pieces with the global organizational store (`~/.mindforge/`).
+- **Ghost Pattern Detection**: Proactive risk matching that prevents repeating known organizational failures at the planning stage.
+- **Repository Graph**: Every repo in the mesh contributes to a shared understanding of architectural success and failure.
+
+### VI. Autonomous FinOps Hub (Economics)
+MindForge integrates an **Autonomous FinOps Hub** that treats compute as a first-class resource. The `ModelBroker` utilizes a **Confidence-to-Cost (C2C)** engine to dynamically route tasks based on complexity and trust tier, ensuring maximum ROI without compromising safety.
+
+### VII. Proactive Equilibrium (Reliability)
+The system achieves **Proactive Equilibrium** through a `WaveFeedbackLoop`. If execution divergence exceeds 20%, the system triggers **Temporal Hindsight**—an automated RCA process that rewrites the phase plan to stay within project guardrails.
+
+---
+
+## 3. Swarm Governance (v4.2)
+
+Every swarm cluster operates under strict enterprise governance rules:
+
+- **Decision Gates**: Use of "Human-in-the-Loop" (HITL) for high-risk Tier 3 actions.
+
+- **Resource Budgets**: FinOps-aware routing to optimal models based on the cluster's defined confidence-to-cost (C2C) ratio.
+
+- **Audit Trails**: Non-repudiable logs signed by each agent's unique **Decentralized Identifier (DID)**.
+
+- **Identity Hardening (Beast Mode)**: High-tier agents (T3) use asymmetric keys anchored in a simulated **Secure Enclave (HSM)**.
+- **Integrity Proofs**: All audit blocks are finalized with **Merkle-root payloads** signed by the archiver to prevent tampering.
+
+---
+
+## 4. Swarm Lifecycle
+
+1. **Detection**: `SwarmController` detects target files and estimates task difficulty.
+2. **Cluster Assembly**: `PersonaFactory` assembles the micro-persona specialist group.
+3. **Execution**: Parallel execution waves with shared JSON state synchronization.
+4. **Consolidation**: Leader-led summary and plan update.
+5. **Verification**: Adversarial audit by the `mf-reviewer` or assigned swarm auditor.
+
+---
+
+*This document defines the architectural standard for MindForge V4 Swarm Orchestration.*

package/docs/feature-dashboard.md

@@ -1,4 +1,4 @@
-# Feature: Real-time Dashboard (v2)
+# Feature: Real-time Dashboard (v4.1.0)
 
 The MindForge Real-time Dashboard provides a high-fidelity, web-based control center for your agentic workflows. It leverages **Server-Sent Events (SSE)** to push live updates from your codebase directly to your browser with zero performance overhead.
 
@@ -33,6 +33,11 @@ Default access: `http://localhost:7339` (Strictly bound to `127.0.0.1` for secur
 - **Persona Context**: See which agent personas are currently active.
 - **Steerage Feed**: View steering instructions as they are applied.
 
+### 5. MindForge Nexus (v4.1+)
+- **ART Trace Explorer**: Drill down into hierarchical reasoning spans and thought chains.
+- **Mesh Topology**: Visual graph of the active agentic mesh and specialist clusters.
+- **Reasoning Heatmaps**: Identifying areas of adversarial disagreement and drift in real-time.
+
 ## 🛡 Hardened Security
 - **Localhost Binding**: The server refuses connections from external IPs.
 - **CORS Lock-down**: Only allows requests from the local control plane.

package/docs/governance-guide.md

@@ -1,23 +1,32 @@
-# MindForge Governance Guide
+# MindForge Governance Guide (v4.2.5)
 
 ## Goal
-Explain how change classification, approvals, compliance gates, and milestone
- governance work in Day 4.
+Explain how change classification, approvals, compliance gates, and trust-based identity enforcement work in the MindForge ecosystem.
 
-## Governance flow
-1. Classify the change before plan execution
-2. Apply Tier 3 signals first
-3. Request approval when required
-4. Enforce compliance gates before completion or release
-5. Log decisions and approvals to AUDIT
+## Trust Tier Architecture (ZTAI)
+MindForge enforces a 4-tier trust model to govern agentic actions and code modifications.
 
-## Key guarantees
-- Tier 3 can be triggered by code content, not just file paths
-- GDPR/PII gate runs independently of skill loading
-- emergency override requires explicit `--emergency` and listed approver identity
-- approval expiry is session-detected and config-driven
+| Tier | Name | Role | Verification Requirement |
+| :--- | :--- | :--- | :--- |
+| **0** | Informational | Research/Query agents. | No signing required. |
+| **1** | Verified | Standard implementation agents. | DID-signed audit entries. |
+| **2** | Specialized | Security, UI, and Data specialists. | Multi-agent peer review + DID signing. |
+| **3** | Principal | Architects and Core Engine agents. | **Secure Enclave (HSM) Signing** + Principal Approval. |
 
-## Team operation
-- multi-developer sessions coordinate via shared `HANDOFF.json`
-- stale active developers expire after 4 hours
-- shared state merges happen through git conflict resolution, not silent overwrite
+## Governance Flow
+1. **Classify**: Automated classification of intent before planning.
+2. **Tier Mapping**: Assigning a Trust Tier based on persona and scope.
+3. **Cryptographic Signing**:
+    - T1/T2: Standard Ed25519 signing via ZTAIManager.
+    - T3: Hardware-enclave (simulated) signing for critical engine/security paths.
+4. **Compliance Gates**: Enforce non-bypassable gates (Secrets, SQLi, PII) before release.
+5. **Non-Repudiation**: Finalize audit blocks with Merkle-root manifests for integrity verification.
+
+## Key Guarantees
+- **Identity Integrity**: Agents cannot spoof identities; every block in `AUDIT.jsonl` is cryptographically tied to a DID.
+- **Ghost Pattern Mitigation**: Planning is gated by the Global Intelligence Mesh to prevent repeating organizational anti-patterns.
+- **Emergency Override**: Requires explicit `--emergency` flag and authorized DID signing.
+
+## Team Operation
+- **Handoff Continuity**: Multi-developer sessions coordinate via `HANDOFF.json`.
+- **Global Mesh Sync**: Project memory is automatically bubbled up to the organizational `~/.mindforge` store for cross-repo awareness.

package/docs/references/audit-events.md

@@ -14,6 +14,9 @@ Each line is a JSON object with a required `event` type and a `session_id`.
 - `agent` (string)
 - `phase` (number or null)
 - `session_id` (string)
+- `trace_id` (string, v4.1+) - UUID linking multiple related spans.
+- `span_id` (string, v4.1+) - ID for the current execution unit.
+- `parent_span_id` (string, v4.1+) - Link to the calling span.
 
 ## Common event types
 ### `project_initialised`
@@ -46,6 +49,9 @@ Fields: `plugin_name`, `version`, `permissions`
 ### `plugin_uninstalled`
 Fields: `plugin_name`
 
+### `reasoning_trace` (v4.1+)
+Fields: `trace_id`, `span_id`, `persona`, `thought_chain`, `decision_point`, `adversarial_critique` (optional)
+
 ## Rotation
 Rotate when file exceeds 10,000 lines. Archive into `.planning/audit-archive/`.
 

package/docs/security/SECURITY.md

@@ -29,14 +29,25 @@
 - Crediting researchers in the security advisory (with their permission)
 - Maintaining confidentiality until a fix is released
 
+## ZTAI Identity Model (v4.2)
+
+MindForge enforces **Zero-Trust Agentic Identity (ZTAI)** for all actions. Every agent is assigned a cryptographically unique asymmetric key pair (Ed25519) in the format `did:mf:<key-fingerprint>`.
+
+- **Asymmetric Signing**: All high-tier (T1-T3) agent actions are cryptographically signed.
+- **Secure Enclave (HSM)**: Tier 3 principal agents utilize simulated hardware-secured enclave signing.
+- **Audit Non-Repudiation**: The `AUDIT.jsonl` log is finalized with **Merkle-root integrity manifests** to prevent tampering.
+- **See also:** [ZTAI Overview](file:///Users/sairamugge/Desktop/MindForge/docs/security/ZTAI-OVERVIEW.md)
+
 ## Known security model limitations
 
 See `docs/security/threat-model.md` for the full threat model.
 
 Key acknowledged limitations:
-1. Plugin permission model is advisory (not OS-enforced) — see TA7 in threat model
-2. The SSE event stream is localhost-only but any local process can connect — see TA6
-3. Approver identity uses `git config user.email` which is user-controlled — see TA5
-4. Agent instruction injection via SKILL.md requires review beyond pattern matching — see TA1
+1. Plugin permission model is advisory (not OS-enforced) — see TA7 in threat model.
+2. The SSE event stream is localhost-only but any local process can connect — see TA6.
+3. Cryptographic identity is local-first; remote anchor validation is a planned v4.5 feature.
+4. Agent instruction injection via SKILL.md requires review beyond pattern matching — see TA1.
+
+*Note: The previous limitation on approver identity (TA5) has been mitigated by the ZTAI DID-based signing model in v4.2.*
 
 These are known trade-offs, not bugs. They are documented in ADR-020.