mindforge-cc 4.3.0 → 5.1.0

package/docs/PERSONAS.md

@@ -19,7 +19,8 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 | **Persistence & Memory** | 1 | mf-memory |
 | **Infrastructure & Tools** | 1 | mf-tool |
 | **Strategy & Ops** | 5 | roadmapper, release-manager, tech-writer, roadmapper-extend, user-profiler |
-| **Debuggers** | 1 | debugger |
+| **Neural Protocols** | 6 | brainstormer, swarm-pilot, mesh-orchestrator, workspace-manager, skill-author, tdd-master |
+| **Debuggers** | 2 | debugger, rca-expert |
 | **Mapping** | 2 | codebase-mapper, codebase-mapper-extend |
 
 ---
@@ -505,7 +506,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 
 **Role:** Executes implementation plans with atomic commit discipline.
 
-| Property | Value |
+| **Property** | **Value** |
 | :--- | :--- |
 | **Spawned by** | `/mindforge:execute-phase`, `/mindforge:agent executor` |
 | **Tools** | Read, Write, Bash, Grep, Glob, CmdStatus, ReadTerminal |
@@ -614,6 +615,152 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 
 ---
 
+---
+
+### mindforge-brainstormer (The Ideation Catalyst)
+
+**Role:** Expert in deep requirements discovery and behavioral ideation.
+
+| Property | Value |
+| :--- | :--- |
+| **Spawned by** | `/mindforge:brainstorming` |
+| **Tools** | Read, Write, Bash, Grep |
+| **Color** | `magenta` |
+| **Trust Tier** | `1` |
+
+**Capabilities:**
+- Proactive discovery of edge cases and user intent.
+- Drafting high-fidelity visual companions and behavioral specs.
+- Challenging assumptions through Socratic engineering.
+
+---
+
+### mindforge-swarm-pilot (The Parallel Executor)
+
+**Role:** Orchestrates multiple independent implementation tasks simultaneously.
+
+| Property | Value |
+| :--- | :--- |
+| **Spawned by** | `/mindforge:swarm-execution` |
+| **Tools** | Read, Write, Bash, Grep, CmdStatus |
+| **Color** | `yellow` |
+| **Trust Tier** | `2` |
+
+**Capabilities:**
+- Managing independent "Execution Waves".
+- Merging parallel contributions with zero conflict.
+- Maintaining high-velocity implementation loops.
+
+---
+
+### mindforge-mesh-orchestrator (The Context Guardian)
+
+**Role:** Synchronizes state and context across parallel agent workstreams.
+
+| Property | Value |
+| :--- | :--- |
+| **Spawned by** | `/mindforge:parallel-mesh` |
+| **Tools** | Read, Write, Bash, Grep, Context7 |
+| **Color** | `cyan` |
+| **Trust Tier** | `2` |
+
+**Capabilities:**
+- Maintaining a unified "Shared Reality" for swarms.
+- Preventing context drift in complex multi-agent sessions.
+- Dynamic propagation of architectural decisions.
+
+---
+
+### mindforge-workspace-manager (The Environment Architect)
+
+**Role:** Manages isolated development environments and project sharding.
+
+| Property | Value |
+| :--- | :--- |
+| **Spawned by** | `/mindforge:workspace-isolated` |
+| **Tools** | Read, Write, Bash, Git |
+| **Color** | `blue` |
+| **Trust Tier** | `3` |
+
+**Capabilities:**
+- Provisioning git worktrees for isolated feature branches.
+- Managing workspace cleanup and state protection.
+- Ensuring atomic environment parity across branches.
+
+---
+
+### mindforge-skill-author (The Framework Evolver)
+
+**Role:** Expert in authoring and validating new MindForge skills.
+
+| Property | Value |
+| :--- | :--- |
+| **Spawned by** | `/mindforge:skill-creation` |
+| **Tools** | Read, Write, Bash, Grep |
+| **Color** | `purple` |
+| **Trust Tier** | `3` |
+
+**Capabilities:**
+- Drafting [SKILL.md] instructions and tool-chains.
+- Validating skill quality against the 7-Dimension Registry.
+- Hardening framework protocols for framework-level releases.
+
+---
+
+### mindforge-tdd-master (The Quality Zealot)
+
+**Role:** Enforces strict Test-Driven Development loops with adversarial rigor.
+
+| Property | Value |
+| :--- | :--- |
+| **Spawned by** | `/mindforge:tdd` |
+| **Tools** | Read, Write, Bash, Grep, CmdStatus |
+| **Color** | `red` |
+| **Trust Tier** | `2` |
+
+**Capabilities:**
+- Enforcing Red-Green-Refactor discipline.
+- Automated generation of regression-proof test suites.
+- Validating implementation against pure behavioral specs.
+
+---
+
+### mindforge-rca-expert (The Forensic Scientist)
+
+**Role:** Principal specialist in advanced root cause analysis and forensic debugging.
+
+| Property | Value |
+| :--- | :--- |
+| **Spawned by** | `/mindforge:debug_extended` |
+| **Tools** | Read, Write, Bash, Grep, CmdStatus, ReadTerminal |
+| **Color** | `orange` |
+| **Trust Tier** | `2` |
+
+**Capabilities:**
+- Log-based forensic reconstruction of failures.
+- Identifying systemic architectural flaws.
+- Proving fix validity through falsifiable regression tests.
+
+---
+
+### mindforge-neural-orchestrator (The Framework Pilot)
+
+**Role:** The core identity responsible for activating and managing the protocol mesh.
+
+| Property | Value |
+| :--- | :--- |
+| **Spawned by** | `/mindforge:neural-orchestrator` |
+| **Tools** | All |
+| **Color** | `white` |
+| **Trust Tier** | `3` |
+
+**Capabilities:**
+- Booting the MindForge Session Engine.
+- Dynamically loading required protocols for the task.
+- Enforcing the Master Directive across all sub-agents.
+
+---
+
 ### mindforge-user-profiler (The Relationship Manager)
 
 **Role:** Analyzes session history to personalize agent interactions and technical alignment.
@@ -649,6 +796,7 @@ MindForge V4 introduces the ability to spawn dynamic, task-aware clusters of spe
 | **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 |
+| **NeuralSwarm** | mesh-orchestrator | brainstormer, swarm-pilot, workspace-manager | High-fidelity protocol execution |
 
 ### Swarm Governance Protocols
 

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/V5-ENTERPRISE.md

@@ -0,0 +1,114 @@
+# MindForge v5 Architecture: The Enterprise Beast
+
+MindForge v5.1.0 is built on a distributed "Agentic OS" architecture. This major version introduces distributed intelligence and absolute governance via a zero-trust policy-as-code layer.
+
+## 1. Core Architectural Pillars (v5.1.0)
+
+### Pillar I: Federated Intelligence Mesh (FIM)
+
+The FIM transitions MindForge from local knowledge silos to a shared organizational intelligence mesh.
+
+- **Distributed Sync (LWW)**: Cross-node synchronization using Last-Write-Wins (LWW) conflict resolution with cryptographic versioning.
+- **Delta Pull Protocol**: Intelligent synchronization that only retrieves new insights since the last successful sync, minimizing bandwidth and latency.
+- **Enterprise Resilience & Governance (v5.1.0)**: A high-availability central hub for sharing high-confidence agentic findings across the entire enterprise.
+- **ZTAI-Signed Provenance**: Every piece of knowledge in the mesh is cryptographically tied to the DID of the agent that generated it.
+
+### Pillar II: Agentic Policy Orchestrator (APO)
+
+# MindForge Governance Guide (v5.1.0)
+MindForge v5.1.0 introduces a non-bypassable, intent-level governance layer that evaluates every autonomous wave against organizational security policies.
+
+- **Policy-as-Code (PaC)**: Security rules are defined in declarative JSON/YAML schemas, enabling version-controlled governance.
+- **Real-Time Intent Interception**: The `AutoRunner` intercepts swarm intents (Action, Resource, DID, Tier) before execution.
+- **Dynamic RBAC Mapping**: v5.1.0 automatically maps ZTAI Trust Tiers to project roles based on an agent's **Zero-Trust Agentic Identity (ZTAI)** trust tier.
+- **Fail-Safe Governance**: "Default Deny" posture for sensitive operations (API key access, infra modification, etc.).
+
+### Pillar III: Predictive Agentic Reliability (PAR)
+
+The PAR layer addresses reasoning decay and execution drifting in long-running autonomous sessions.
+
+- **Loop Detection (S03/S04)**: Advanced `StuckMonitor` patterns for Semantic Mirroring and Infinite Decomposition.
+- **Context Density Refactorer**: Proactive context summarization and handoff when reasoning-to-action density falls below 30%.
+- **C2C Arbitrage**: Confidence-to-Cost (C2C) threshold gating to prevent low-value autonomous drifts.
+- **Self-Healing Reasoning**: Automated triggering of "hindsight injection" when stuck patterns are detected.
+
+### Pillar IV: Supply Chain Trust (ZTS)
+
+The ZTS layer ensures the integrity of the agentic supply chain, from the models used to the skills executed.
+
+- **Agentic SBOM**: Automated `MANIFEST.sbom.json` generation tracking every model and skill signature in the reasoning chain.
+- **7-Dimension Certification (7D)**: Weighted scoring system (Schema, Triggers, Security, Clarity, etc.) for skill validation.
+- **Enterprise-Grade Enforcement**: Strict `--enterprise` mode requirement for 7.0/10.0 minimum certification score.
+- **Skill Telemetry**: Real-time auditing of skill performance and reliability metrics.
+
+---
+
+### Pillar V: Multi-Cloud Arbitrage & Hedging
+
+The Multi-Cloud layer ensures absolute availability and cost-efficiency by dynamically load-balancing across multiple AI providers.
+
+- **Dynamic Routing**: Real-time arbitrage across Vertex AI, AWS Bedrock, and Azure based on current latency and cost weights.
+- **Provider Fallback Protocol**: Automated "Hedging" that migrates agent context to a secondary cloud provider (e.g., Anthropic to Google) if 5xx errors or high latencies are detected.
+- **Chaos Mode (Beast Mode)**: Built-in reliability testing that simulates provider dropouts to verify the robustness of the fallback loops.
+
+### Pillar VI: Sovereign Reason Enclaves (SRE)
+
+SRE provides a "Confidential Computing" environment for the agent's internal thought process, protecting sensitive intellectual property.
+
+- **TEE-Simulated Reasoning**: Tier 3 workloads execute reasoning traces in high-isolation simulated enclaves with zero-visibility to the global log.
+- **Thought-Chain Sanitization**: Automatically redacts sensitive patterns (keys, credentials, PII) from the reasoning trace before persistent audit.
+- **Enclave Multi-Tenancy**: Isolated reason-space per project wave, ensuring that cross-stream reasoning cannot leak state or logic.
+
+### Pillar VII: Dynamic Human-Agent Handover (DHH)
+
+DHH creates a seamless bridge between fully autonomous execution and high-precision human steering.
+
+- **Nexus State Bundles**: Automated "Context Freeze" and packaging of memory, diffs, and reasoning traces when agent confidence drops below 60%.
+- **Mid-Wave Steering**: In-flight steering injection into the `AutoRunner` loop, allowing humans to re-orient an active autonomous wave without restarts.
+- **Confidence-to-Human Gating**: Proactive interruption of the autonomous stream for "Human-in-the-Loop" approval on sensitive T3 operations.
+
+---
+
+## Technical Components
+
+### 🧠 Intelligence Mesh
+
+| Component | Path | Description |
+| :--- | :--- | :--- |
+| **EIS Client** | `bin/memory/eis-client.js` | Hardened, ZTAI-signed mesh communicator. |
+| **Fed-Sync** | `bin/memory/federated-sync.js` | Core delta-sync and conflict resolution logic. |
+| **Graph Bridge** | `bin/memory/knowledge-graph.js` | Unified traversal for local and remote nodes. |
+
+### 🛡️ Governance & Cloud Arbitrage
+
+| Component | Path | Description |
+| :--- | :--- | :--- |
+| **Policy Engine** | `bin/governance/policy-engine.js` | Intent-based RBAC/ABAC evaluator. |
+| **RBAC Manager** | `bin/governance/rbac-manager.js` | Tier-to-role binding and DID mapping. |
+| **Cloud Broker** | `bin/models/cloud-broker.js` | Multi-cloud routing and arbitrage engine. |
+| **Fallback Protocol** | `bin/models/model-broker.js` | Provider hedging and context migration logic. |
+
+### ⚡ Reliability & Trust (PAR/ZTS/SRE/DHH)
+
+| Component | Path | Description |
+| :--- | :--- | :--- |
+| **Stuck Monitor** | `bin/autonomous/stuck-monitor.js` | S03/S04 loop detection patterns. |
+| **Refactorer** | `bin/autonomous/context-refactorer.js` | Context density and proactive summarization. |
+| **SRE Manager** | `bin/engine/sre-manager.js` | Trusted execution enclave management. |
+| **Handover Manager** | `bin/engine/handover-manager.js` | Nexus bundle creation and steering logic. |
+| **SBOM Tracer** | `bin/engine/nexus-tracer.js` | SRE-aware audit logging and manifest generation. |
+
+---
+
+## ZTAI & Enclave Security (v5.1.0)
+
+MindForge v5.1.0 enforces **Zero-Trust Agentic Identity (ZTAI)** as the root-of-trust for all enterprise operations.
+
+1.  **Identity Verification**: Agents prove their identity using Ed25519 signatures.
+2.  **Tier Escalation**: Tier 0-1 agents are limited to analytical tasks. Tier 2 agents gain implementation roles. Tier 3 agents (signed by HSM-secured identities) execute in **Sovereign Reason Enclaves**.
+3.  **Policy Binding**: Policies specifically reference `trust_tier` requirements for sensitive namespaces.
+4.  **Handover Thresholds**: Lower trust tiers trigger human-agent handover (DHH) earlier than senior T3 agents.
+
+---
+
+*For implementation details, refer to the [PAR & ZTS Survey](./PAR-ZTS-SURVEY.md) and [Governance Guide](../governance-guide.md).*

package/docs/commands-reference.md

@@ -1,4 +1,4 @@
-# MindForge v2.4.0 — Commands Reference
+# MindForge v5.1.0 — Commands Reference
 
 MindForge commands are organized into functional pillars to support the entire software development lifecycle (SDLC).
 
@@ -35,6 +35,7 @@ MindForge commands are organized into functional pillars to support the entire s
 | `/mindforge:personas --list` | Displays all 32+ specialized engineering personas. |
 | `/mindforge:personas --set ID` | Switches the current agent to a specific persona (e.g., `architect`, `executor`). |
 | `/mindforge:tokens` | Analyzes and profiles token usage for the current session. |
+| `/mindforge:neural-orchestrator` | Activates the advanced protocol layer for the current session. |
 | `shard-helper --verify` | (CLI Internal) Verifies the integrity and SHA-256 checksums of memory shards. |
 
 ---
@@ -62,3 +63,21 @@ MindForge commands are organized into functional pillars to support the entire s
 | `/mindforge:migrate` | Migrates project metadata between framework versions. |
 | `/mindforge:audit --export` | Generates a human-readable PDF report of the session audit log. |
 | `/mindforge:join-discord` | Join the MindForge developer community for support and collaboration. |
+
+---
+
+## 6. Advanced Neural Protocols (Beast Addition)
+
+These protocols represent specialized, high-fidelity engineering behaviors ported and hardened for the MindForge ecosystem.
+
+| Command | Description |
+| :--- | :--- |
+| `/mindforge:brainstorming` | Deep ideation and requirement exploration before planning. |
+| `/mindforge:swarm-execution` | Swarm-based implementation for independent tasks. |
+| `/mindforge:parallel-mesh` | Orchestrates context across multiple parallel agent waves. |
+| `/mindforge:workspace-isolated` | Manages isolated development environments via git worktrees. |
+| `/mindforge:skill-creation` | Expert protocol for authoring new MindForge skills. |
+| `/mindforge:review-request` | Formalizes peer review requests for completed implementation waves. |
+| `/mindforge:tdd` | Enhanced Test-Driven Development protocol with strict verification. |
+| `/mindforge:debug` | Advanced systematic debugging with persistent state tracking. |
+| `/mindforge:verify-work` | Multi-level truth verification (existence, substance, wiring). |

package/docs/governance-guide.md

@@ -1,32 +1,53 @@
-# MindForge Governance Guide (v4.2.5)
+# MindForge Governance Guide (v5.1.0)
+Absolute Control through Policy-as-Code (PaC)
 
-## Goal
-Explain how change classification, approvals, compliance gates, and trust-based identity enforcement work in the MindForge ecosystem.
+## 1. Goal
+MindForge v5.1.0 introduces a non-bypassable, intent-level governance layer. This guide explains how **Agentic Policy Orchestration (APO)** and **Zero-Trust Agentic Identity (ZTAI)** work together to secure the enterprise development lifecycle, now hardened by the **Neural Protocol Mesh**.
 
-## Trust Tier Architecture (ZTAI)
-MindForge enforces a 4-tier trust model to govern agentic actions and code modifications.
+## 2. Agentic Policy Orchestrator (APO)
+The APO is a decentralized governance engine that intercepts every autonomous intent before it is executed.
 
-| Tier | Name | Role | Verification Requirement |
+### A. Intent Interception
+Before the `AutoRunner` begins a new execution wave, it extracts the acting agent's **Intent**:
+- **DID**: The unique identity of the agent.
+- **Action**: The operation being attempted (e.g., `process_phase_wave`, `modify_security_config`).
+- **Resource**: The target of the action (e.g., specific directories, files, or API endpoints).
+- **Tier**: The ZTAI Trust Tier assigned to the agent.
+
+### B. Policy Evaluation
+The `PolicyEngine` evaluates this intent against organizational **Policy-as-Code (PaC)** definitions (typically stored in `bin/governance/policies/`).
+- **Permit**: The action is allowed and execution proceeds.
+- **Deny**: The action is blocked, and the violation is logged to `AUDIT.jsonl`.
+- **Escalate**: The action requires a higher-tier DID signature or explicit HITL (Human-in-the-Loop) approval.
+
+## 3. Trust Tier Architecture (ZTAI Hardened)
+V5.1.0 automatically maps ZTAI Trust Tiers to explicit project roles through the `RBACManager`.
+
+| Tier | Role | Scope | Hardening |
 | :--- | :--- | :--- | :--- |
-| **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. |
-
-## 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.
+| **0** | Informational | Research/Query only. | Read-only access to non-sensitive docs. |
+| **1** | Implementation| Standard feature dev. | Write access to `/src`, `/tests`, `/bin/memory`. |
+| **2** | Specialized | Security/DevOps Specialist. | Access to `/security`, `/infra`, and `/bin/governance`. |
+| **3** | Principal | Lead Architect / Core Engine. | **HSM-Enclave Signing Required** for all engine modifications. |
+
+## 4. Protocol Mesh Governance (v5.1.0 Enhancement)
+The **Beast Addition** integrates protocol-level governance into the APO engine.
+- **Protocol Enforceability**: Every protocol activation (e.g., `/mindforge:tdd`) is logged as a governance event.
+- **Mesh Integrity**: The **Parallel Mesh** synchronizes governance state across multiple agents, preventing "split-brain" policy execution.
+- **Skill Compliance**: New skills created via `/mindforge:skill-creation` are automatically audited for APO compatibility.
+
+## 5. Governance Workflow (V5.1.0)
+1. **ZTAI Handshake**: Agent proves identity using Ed25519 signatures.
+2. **Intent Pulse**: Agentic intent is broadcast to the policy interceptor.
+3. **APO Evaluation**: Policy engine checks the intent against PaC rules.
+4. **Role binding**: `RBACManager` grants or revokes permissions based on the active trust tier.
+5. **Verified Wave**: Execution proceeds only if all policy gates are clear.
+
+## 6. Enterprise Policies
+MindForge v5.1.0 ships with default policies including:
+- **`gate_tier_3_engine`**: Blocks all modifications to `bin/autonomous/` unless signed by a Tier 3 DID.
+- **`protect_security_namespace`**: Limits access to `/security` and `/governance` to Tier 2+ specialists.
+- **`mesh_integrity_lock`**: Ensures only high-confidence agents can push to the **Federated Intelligence Mesh**.
+
+---
+*Status: V5.1.0 "Beast Addition" Governance Implemented & Verified (2026-03-28)*

package/docs/security/SECURITY.md

@@ -4,9 +4,9 @@
 
 | Version | Security support |
 |---|---|
-| 1.x.x | ✅ Active — patches released for all severity levels |
-| 0.6.x | ⚠️  Limited — critical fixes only, 90 days from v1.0.0 release |
-| < 0.6.0 | ❌ No support |
+| 5.x.x | ✅ Active — patches released for all severity levels |
+| 4.x.x | ⚠️  Limited — critical fixes only |
+| < 4.0.0 | ❌ No support |
 
 ## Reporting a vulnerability
 
@@ -29,12 +29,14 @@
 - Crediting researchers in the security advisory (with their permission)
 - Maintaining confidentiality until a fix is released
 
-## ZTAI Identity Model (v4.2)
+## ZTAI & Enclave Security (v5.0.0)
 
-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>`.
+MindForge v5.0.0 enforces **Zero-Trust Agentic Identity (ZTAI)** and **Sovereign Reason Enclaves (SRE)** for all sensitive operations. 
 
-- **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.
+- **Asymmetric Signing**: All high-tier (T1-T3) agent actions are cryptographically signed using Ed25519.
+- **Sovereign Reason Enclaves (SRE)**: Tier 3 principal agents execute reasoning in isolated TEE-simulated enclaves, ensuring that high-value architectural decisions and sensitive IP never leak to the persistent log.
+- **Trace Sanitization**: In-enclave sanitization automatically redacts credentials and PII from reasoning traces before they reach the local filesystem.
+- **Multi-Cloud Resilience**: The **Cloud Broker** provides automated failover and hedging across Vertex AI, Bedrock, and Azure to mitigate provider-side denial-of-service or outages.
 - **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)