mindforge-cc 3.0.0-rc1 → 4.3.0

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.

package/docs/security/ZTAI-OVERVIEW.md

@@ -0,0 +1,37 @@
+# Zero-Trust Agentic Identity (ZTAI) Overview
+
+MindForge v4.2 introduces **ZTAI Beast Mode**, an enterprise-grade identity layer that ensures every agent action is cryptographically signed and non-repudiable.
+
+## 1. Asymmetric Identity Model
+Every MindForge persona in the 32+ agent library is assigned a unique asymmetric key pair (Ed25519) upon project initialization or agent spawning.
+
+- **Private Key**: Stored securely in the local `.mindforge/identity` vault (never exposed).
+- **Public Key / DID**: Represented as a **Decentralized Identifier (DID)** in the format `did:mf:<key-fingerprint>`.
+
+## 2. Trust Tiers & Signing Requirements
+MindForge enforces tiered signing based on the risk level of the persona's actions.
+
+| Tier | Persona Examples | Signing Tech | Integrity Proof |
+| :--- | :--- | :--- | :--- |
+| **T0** | `mf-researcher`, `mf-query` | None | Audit log entry only. |
+| **T1** | `mf-executor`, `mf-coder` | Ed25519 (Software) | Signed JSON payload. |
+| **T2** | `security-auditor`, `ui-specialist` | Ed25519 (Software) | Signed Block + Peer Review. |
+| **T3** | `mf-planner`, `system-architect` | **Secure Enclave (HSM)** | Enclave-attested signature. |
+
+*Note: T3 agents utilize a simulated hardware-secured enclave (HSM) to ensure principal-level accountability.*
+
+## 3. Non-Repudiable Audit Manifests
+The `ZTAIArchiver` generates high-fidelity integrity proofs for the session history.
+
+- **Merkle-Root Chain**: Every 50 audit entries trigger the generation of a Merkle-root.
+- **Manifest Finalization**: The cumulative root of all audit entries is signed by the **Principal Agent (T3)**.
+- **Tamper Detection**: Any modification to the `AUDIT.jsonl` file will invalidate the Merkle-proof, triggering an immediate security alert.
+
+## 4. Key Provider Abstraction
+The `ZTAIManager` uses a pluggable `KeyProvider` architecture:
+- `FileSystemProvider`: Standard key storage for T1/T2 agents.
+- `SecureEnclaveProvider`: Simulates hardware-backed signing for T3 agents.
+- `KMSProvider` (Future): Integration with AWS/GCP/Azure Key Management Services.
+
+## 5. Governance Integration
+ZTAI identities are verified during the `/mindforge:verify-phase` and `/mindforge:ship` processes. High-tier changes will be BLOCKED if the cryptographic signatures are missing or invalid.

package/docs/usp-features.md

@@ -1,6 +1,6 @@
-# MindForge v3.0.0 — Unique Selling Points, Features, and Best Practices (v3.0.0)
+# MindForge v4.2.5 — Unique Selling Points, Features, and Best Practices (v4.2.5)
 
-This document summarizes what makes MindForge v2.0.0 distinct, what features
+This document summarizes what makes MindForge v4.1.0 distinct, what features
 are included in the official release, and how to use them effectively.
 
 ---
@@ -58,6 +58,18 @@ are included in the official release, and how to use them effectively.
 16. **Temporal Vision (v3)**
     - Full-fidelity history navigation, hindsight injection, and automated state repair across the execution wave.
 
+17. **Dynamic Swarm Orchestration (v4)**
+    - Parallel "Agentic Mesh" with shared state (`SWARM-STATE.json`) and leader-led synthesis of specialist outcomes.
+
+18. **Zero-Trust Agentic Identity "Beast Mode" (v4.2)**
+    - Non-repudiable audit trails signed by unique Decentralized Identifiers (DIDs) for every swarm action. Tier 3 agents use simulated **Secure Enclave (HSM)** signing.
+
+19. **MindForge Nexus: Agentic Reasoning Tracing (v4.1)**
+    - High-fidelity **ART** spans embedded in the execution engine, providing deep visibility into agentic "thought chains" and parallel mesh reasoning.
+
+20. **Global Intelligence Mesh (v4.2)**
+    - Cross-repository knowledge sharing via the **Semantic Hub**. Proactive **Ghost Pattern Detection** identifies and prevents repeating past organizational failures.
+
 ---
 
 ## Feature Set (v2.0.0)
@@ -247,6 +259,67 @@ preserving scope (local vs global).
 
 ---
 
+### 21. Dynamic Swarm Mesh (v4)
+**What it does:** Orchestrates parallel specialist clusters (e.g., Security, UI, Data) with automated state coordination.
+
+**How to use:**
+```bash
+/mindforge:swarm spawn --template [NAME]
+/mindforge:swarm status --mesh
+```
+
+---
+
+### 22. ZTAI Governance & Beast Mode (v4.2)
+**What it does:** Enforces cryptographic signing and trust-tier validation for all autonomous agent actions. Tier 3 agents utilize simulated Secure Enclaves for principal-level non-repudiation.
+
+**How to use:**
+```bash
+/mindforge:identity verify [AGENT_ID]
+/mindforge:identity sign --did
+/mindforge:identity audit --manifest # Generates Merkle-root integrity proof
+```
+
+---
+
+### 23. Global Intelligence Mesh (v4.2)
+**What it does:** Synchronizes local repo memory with a global organizational store. Includes Ghost Pattern Detection to flag architectural anti-patterns from past failures.
+
+**How to use:**
+```bash
+/mindforge:memory sync --global
+/mindforge:memory status --mesh
+/mindforge:plan-phase --detect-ghosts # Automated during planning
+```
+---
+
+### 24. Autonomous FinOps Hub (v4.3)
+**What it does:** Enterprise-grade economics engine 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.
+
+**How to use:**
+```bash
+/mindforge:finops status # View consumption and budget profile
+/mindforge:costs --roi # Detailed Agentic ROI analysis
+/mindforge:finops budget 500 # Set project-level budget ($500)
+```
+
+---
+
+### 25. Proactive Equilibrium (Self-Healing) (v4.3)
+**What it does:** Achieves autonomous reliability via a `WaveFeedbackLoop`. If execution divergence exceeds 20%, the system performs **Temporal Hindsight** analysis and automatically rewrites the plan to recover.
+
+**How to use:**
+- Automated: Triggers during `/mindforge:execute-phase` when divergence is detected.
+- Manual: `/mindforge:temporal analyze` to run RCA on the last wave.
+**What it does:** High-fidelity Agentic Reasoning Tracing (ART) for the agentic mesh. Logs spans, parent-trace IDs, and granular reasoning traces.
+
+**How to use:**
+- Automated: Every wave/task execution triggers Nexus Tracer spans.
+- Manual: Query `.planning/AUDIT.jsonl` for `trace_id` and `span_id` chains.
+- Dashboard: Real-time visualization of mesh traces and reasoning heatmaps.
+
+---
+
 ### 15. SDK (TypeScript)
 **What it does:** Programmatic access to health, audit log, event stream, and commands.
 
@@ -304,6 +377,4 @@ const report = await client.health();
 ---
 
 ## Summary
-MindForge v2.0.0 combines governance, observability, and autonomous execution rigor into a
-single workflow engine that works across 6 major AI runtimes. Its core
-value is consistent, repeatable quality in long‑running AI development sessions.
+MindForge v4.3.0 combines governance, observability, and autonomous execution rigor with **enterprise-grade economics (FinOps)** and **self-healing reliability**. Its core value is providing a non-repudiable, cost-optimized, and resilient AI development engine for the most demanding software projects.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindforge-cc",
-  "version": "3.0.0-rc1",
+  "version": "4.3.0",
   "description": "MindForge - Enterprise Agentic Framework for Claude Code and Antigravity",
   "bin": {
     "mindforge-cc": "bin/install.js"