mindforge-cc 3.0.0 → 5.0.0

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/{references → 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/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/PAR-ZTS-SURVEY.md

@@ -0,0 +1,43 @@
+# PAR & ZTS Architectural Survey — MindForge v5
+
+## Pillar III: Predictive Agentic Reliability (PAR)
+
+Predictive Agentic Reliability (PAR) addresses the "Reasoning Decay" problem in long-running autonomous sessions. It implements proactive monitoring and self-healing at the reasoning layer.
+
+### 1. Stuck Detection (S03 & S04)
+The `StuckMonitor` has been extended to detect advanced reasoning loop patterns:
+- **S03 (Semantic Mirroring)**: Detects when the agent paraphrases its own previous thoughts without taking new actions.
+- **S04 (Infinite Decomposition)**: Detects when the agent breaks sub-tasks into smaller and smaller pieces indefinitely without resolving the parent task.
+
+### 2. Context Refactoring
+The `ContextRefactorer` monitors "Context Density" (the ratio of implementation actions to reasoning thoughts).
+- When density falls below 30%, it triggers a proactive **Refactor Event**.
+- This encourages the agent to summarize its progress and reset its active context window, preventing bloat.
+
+### 3. C2C Arbitrage
+Confidence-to-Cost (C2C) arbitrage ensures that the agent only continues execution when the expected value (confidence) exceeds the operational cost (tokens/compute).
+
+---
+
+## Pillar IV: Supply Chain Trust (ZTS)
+
+Supply Chain Trust (ZTS) ensures that every asset (skill, model, tool) used by MindForge is authenticated and verified against enterprise standards.
+
+### 1. Agentic SBOM (Software Bill of Materials)
+MindForge now generates a real-time `MANIFEST.sbom.json` during every autonomous run.
+- **Model Tracking**: Logs the exact model version used for every reasoning span.
+- **Skill Telemetry**: Tracks which skills were invoked and their specific versions.
+- **Timestamping**: Captures full start/end telemetry for supply chain auditing.
+
+### 2. 7-Dimension Certification (7D)
+Skills are now evaluated across 7 weighted dimensions:
+1. **Schema Compliance (15%)**
+2. **Trigger Density (15%)**
+3. **Mandatory Coverage (20%)**
+4. **Security Sanitization (20%)**
+5. **Doc Clarity (10%)**
+6. **Edge Case Handling (10%)**
+7. **Example Fidelity (10%)**
+
+> [!IMPORTANT]
+> In `--enterprise` mode, skills must achieve a minimum score of **7.0/10.0** to be loaded.

package/docs/architecture/README.md

@@ -1,17 +1,21 @@
 # MindForge Architecture Overview
 
-MindForge v2.1.1 is built on a unified "Agentic OS" architecture, designed to provide a consistent execution environment across all major AI IDEs and CLI tools.
+MindForge v5.0.0 is built on a distributed "Agentic OS" architecture, designed for enterprise-scale intelligence sharing and absolute governance.
 
 ---
 
-## 1. Core Architectural Pillars
+## 1. Core Architectural Pillars (v5.0.0)
 
-The framework is organized into four logical pillars that map directly to the development lifecycle:
+The framework is focused on six major pillars, with V5 introducing the **Distributed Intelligence** and **Policy Governance** layers:
 
-1. **PLAN**: Multi-agent task decomposition using the `PLANNER_MODEL`. Resulting in atomic `.planning/` artifacts.
-2. **EXECUTE**: Parallel, wave-based implementation using the `EXECUTOR_MODEL`.
-3. **VERIFY**: Multi-stage validation (Automated Tests + UAT + Integrity Checks) using the `VERIFIER_MODEL`.
-4. **SHIP**: Release orchestration, PR generation, and audit finalization.
+1. **Federated Intelligence Mesh (FIM)**: Distributed knowledge sharing with delta-sync and cryptographic provenance. [V5-ENTERPRISE.md](./V5-ENTERPRISE.md)
+2. **Agentic Policy Orchestrator (APO)**: Non-bypassable policy-as-code governance that intercepts autonomous intents.
+3. **Predictive Agentic Reliability (PAR)**: Self-healing reasoning loops and context refactoring. [PAR-ZTS-SURVEY.md](./PAR-ZTS-SURVEY.md)
+4. **Supply Chain Trust (ZTS)**: Agentic SBOM and 7-dimension skill certification. [PAR-ZTS-SURVEY.md](./PAR-ZTS-SURVEY.md)
+5. **Zero-Trust Agentic Identity (ZTAI)**: DID-based cryptographic signing for all agentic actions and tiered trust enforcement.
+6. **Adversarial Decision Synthesis (ADS)**: 3-model synthesis loop ensuring architectural integrity.
+7. **Semantic Context Sharding**: Tri-tier memory (Hot/Warm/Cold) for high-fidelity context management.
+8. **Autonomous Execution Engine**: Self-healing wave execution with stuck-detection and repair hierarchies.
 
 ---
 
@@ -21,8 +25,9 @@ MindForge uses a "Tiered Configuration" model allowing for global, organizationa
 
 | Directory | Scope | Purpose |
 | :--- | :--- | :--- |
+| **EIS / Mesh** | `bin/memory` | Core FIM implementation (eis-client, federated-sync). |
+| **Governance** | `bin/governance` | Core APO implementation (policy-engine, rbac-manager). |
 | `.mindforge/` | System/Global | Core personas, core skills, and engine protocols. |
-| `.mindforge/org/` | Organizational | Shared company standards and private skill registries. |
 | `.agent/` | Project/Local | Project-specific configuration, hooks, and local skill overrides. |
 | `.planning/` | Session/State | Ephemeral state, task blocks, and session handoffs. |
 
@@ -34,78 +39,40 @@ The `file-manifest.json` file in `.agent/` is the single source of truth for the
 
 ---
 
-## 4. Runtime Execution Flow
+## 4. Runtime Execution Flow (V5 Hardened)
 
-1.  **Context Loading**: Load `MINDFORGE.md` and `file-manifest.json` to configure the environment.
-2.  **Skill Discovery**: Match task intent against the 3-tier skill registry (Core → Org → Project).
-3.  **Persona Spawning**: Instantiate the required persona from the 32-persona ecosystem.
-4.  **Action Loop**: Execute the 4-pillar workflow, persisting state to `.planning/STATE.md` at every step.
-5.  **Audit Persistence**: All non-trivial actions are appended to the encrypted `.planning/AUDIT.jsonl`.
+1.  **Context Loading**: Load `MINDFORGE.md` and `file-manifest.json`.
+2.  **Identity Verification**: Resolve the agent's ZTAI identity and trust tier.
+3.  **Policy Interception**: The `APO` evaluates the task intent. If not **PERMIT**, the session is halted.
+4.  **Skill Discovery**: Match task intent against the 3-tier skill registry.
+5.  **Execution Wave**: Parallel task execution with continuous FIM synchronization.
+6.  **Audit Pulse**: All actions are cryptographically signed and appended to `.planning/AUDIT.jsonl`.
 
 ---
 
-## 5. Stability & Extension
+## 5. Decision Records & Stability
 
-MindForge provides stable interfaces for extension:
+MindForge provides stable interfaces for extension while documenting every major design shift via ADRs.
 
-- **Skills**: Domain expertise via `SKILL.md`.
-- **Workflows**: Sequence automation via `WORKFLOW.md`.
-- **Hooks**: Lifecycle interception via `.agent/hooks/`.
-- **SDK**: Programmatic access via `@mindforge/sdk`.
-
-See [ADR-041](../adr/ADR-041-runtime-interfaces.md) for the stabilization contract.
+- **ADR Index**: See [decision-records-index.md](./decision-records-index.md).
+- **V3 Core**: See [V3-CORE.md](./V3-CORE.md).
+- **V4 Mesh**: See [V4-SWARM-MESH.md](./V4-SWARM-MESH.md).
+- **V5 Enterprise**: See [V5-ENTERPRISE.md](./V5-ENTERPRISE.md).
 
 ---
 
-## 6. Semantic Memory Tiering (V3)
-
-MindForge v2.4.0 introduces **Semantic Context Sharding**, a Tri-Tier memory architecture that optimizes context window usage for long-running engineering sessions.
+## 6. Semantic Memory Tiering (V3/V4)
 
 | Tier | Storage | Purpose | Retrieval |
 | :--- | :--- | :--- | :--- |
 | **HOT** | `HANDOFF.json` | Immediate task state and core ADRs (SRD > 0.8). | Loaded every session. |
-| **WARM** | `.planning/memories/` | Phase-specific shards and active project context (SRD 0.5-0.8). | Proactive retrieval via keyword matching. |
-| **COLD** | `.mindforge/memory/` | Historical logs and legacy architectural decisions (SRD < 0.5). | On-demand search via `/mindforge:remember`. |
-
-### SRD Scoring Engine
-
-Semantic Relevance Density (SRD) is calculated using a weighted formula:
-`SRD = (Decisiveness * 0.6) + (Frequency * 0.1) + (Impact * 0.3)`
-
-### Integrity & Hardening
-
-All shards are hardened with **SHA-256 Checksums** and **Semantic Tags** to prevent state drift and enable O(1) keyword-based context injection.
-
----
-
+| **WARM** | `.planning/memories/` | Phase-specific shards and active project context (SRD 0.5-0.8). | Proactive retrieval. |
+| **COLD** | `.mindforge/memory` | Global knowledge base and historical logs (SRD < 0.5). | Federated search (FIM). |
 
 ---
 
-## 7. Adversarial Decision Synthesis (ADS) (V3)
+## 7. Adversarial Decision Synthesis (ADS)
 
-MindForge v3.0.0 introduces **Adversarial Decision Synthesis (ADS)**, a 3-model synthesis loop that ensures every architectural decision is battle-tested.
-
-### The 3-Model Loop
-
-1.  **Blue Team (Architect)**: Proposes the initial high-performance plan.
-2.  **Red Team (Auditor)**: Hardened via "Jailbreak" protocol to identify at least 3 critical flaws (Maintainability, Complexity, Security).
-3.  **Gold Team (Synthesizer)**: Consolidates findings using the **SOUL.md** scoring algorithm.
-
-### SOUL Decision Scoring
-
-| Metric | Factor | Description |
-| :--- | :--- | :--- |
-| **I** | Impact | Overall system-wide importance of the change. |
-| **L** | Leverage | How much this change unblocks future high-value work. |
-| **R** | Reversibility | How easy it is to undo this change if it fails. |
-| **E** | Effort | Total engineering complexity and time required. |
-| **Ri** | Risk | Probability of breakage or system regression. |
-| **C** | Cost | Token/Compute usage and infrastructure weight. |
-
-**Formula**: `Score = (I * L * R) / (E * Ri * C)`
-
-Decisions with a SOUL Score > 1.0 are considered architecturally sound.
+MindForge v3.0.0 introduces **Adversarial Decision Synthesis (ADS)**, a 3-model synthesis loop that ensures every architectural decision is battle-tested using the **SOUL.md** scoring algorithm.
 
 ---
-
-## 8. Stability & Extension

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.*