mindforge-cc 8.1.1 → 8.2.0

package/.mindforge/mirrors/mirror-sre-776a1cf9/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 (Enterprise 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/.mindforge/mirrors/mirror-sre-776a1cf9/docs/architecture/V5-ENTERPRISE.md

@@ -0,0 +1,131 @@
+# MindForge v5 Architecture: The Enterprise Standard
+
+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) — CADIA Engine (v6.0.0 Alpha)
+
+# MindForge Governance Guide (v6.0.0)
+MindForge v6.0.0 introduces **Context-Aware Dynamic Impact Analysis (CADIA)**, a non-bypassable, architectural governance layer that evaluates every autonomous wave against organizational security and risk policies.
+
+- **Policy-as-Code (PaC)**: Security rules are defined in declarative JSON schemas, enabling version-controlled governance.
+- **Dynamic Blast Radius Analysis**: Calculates real-time architectural risk based on file influence, session entropy (multi-file modification speed), and goal alignment.
+- **Session Entropy Guardrails**: Risk increases logarithmically as an agent touches more files, preventing "Rogue Wave" mass corruption.
+- **ZTAI-Trust Weighting**: Senior agents (Tier 3) gain "Architectural Credit," while Tier 1-2 agents are kept under strict risk caps.
+- **Reasoning Proof Bypass**: Tier 3 agents can override high-risk blocks by providing a cryptographically signed "Reasoning Proof."
+- **Enterprise Audit Log**: All evaluations are logged to `.planning/RISK-AUDIT.jsonl` for compliance reporting.
+
+### Pillar III: Predictive Agentic Reliability (PAR) (v5.5.0)
+
+The PAR layer addresses reasoning decay and execution drifting in long-running autonomous sessions by monitoring the "logic-space" of the agent.
+
+- **Reasoning Entropy Scoring (RES)**: The `NexusTracer` calculates a semantic similarity score (Jaccard-based) for every reasoning step. A high score indicates thought stagnation or circular logic.
+- **Proactive Loop Detection**: If more than 3 consecutive thoughts fall below the entropy threshold, a `STAGNATION_DETECTED` event is triggered.
+- **Steering Vector Injection**: Upon loop detection, `TemporalHindsight` generates a "Steering Vector" — a high-priority system instruction that forces the agent to pivot its logic or escalate to a human.
+- **Context Density Refactorer**: Proactive context summarization and handoff when reasoning-to-action density falls below 30%.
+
+### Pillar IV: Supply Chain Trust (ZTS) (v5.6.0)
+
+The ZTS layer ensures the absolute integrity of the agentic supply chain, cryptographically locking every skill and model in the reasoning path.
+
+- **Binary Runtime Attestation**: The `SkillValidator` performs Just-In-Time (JIT) attestation. Every `SKILL.md` is hashed and verified against signed signatures before being loaded into the agent's context.
+- **ZTAI-Locked Registry**: Skills are signed using Tier 3 Decentralized Identifiers (DIDs) via HSM-simulated Secure Enclaves. Unauthorized skill modifications result in immediate execution blocking.
+- **7-Dimension Certification (7D)**: Weighted scoring system (Schema, Triggers, Security, Clarity, etc.) for skill validation.
+- **Agentic SBOM**: Automated `MANIFEST.sbom.json` generation tracking every model and skill signature in the reasoning chain.
+
+---
+
+### Pillar V: Multi-Cloud Arbitrage & Hedging (v5.7.0)
+
+The Multi-Cloud layer ensures absolute availability and intelligence-first routing by dynamically mapping task taxonomies to the most performant providers.
+
+- **Task-to-Model Affinity Matrices**: Persistent tracking of success probability per model and task type (refactor, test, audit, etc.) in `performance-stats.json`.
+- **Intelligence-First Routing**: The `CloudBroker` weights routing scoring by success probability (50%), cost (30%), and latency (20%), ensuring the most capable model is selected for the specific task taxonomy.
+- **Automated Feedback Integration**: `WaveFeedbackLoop` automatically records task outcomes back into the performance repository, enabling the system to learn from cross-cloud execution history.
+- **Provider Fallback Protocol**: Automated "Hedging" that migrates agent context to a secondary cloud provider if 5xx errors or high latencies are detected.
+
+### Pillar VI: Sovereign Reason Enclaves (SRE) (v5.8.0)
+
+SRE provides a "Confidential Computing" environment for the agent's internal thought process, protected by cryptographic Zero-Knowledge (ZK) audit trails.
+
+- **ZK-Proof Compliance Certificates**: Simulated zero-knowledge proofs (signed by System DID) generated for every confidential reasoning session in `SREManager`.
+- **Privacy-Preserving Auditing**: `NexusTracer` replaces raw, sensitive thought traces in `AUDIT.jsonl` with verifiable cryptographic certificates, protecting proprietary reasoning logic.
+- **Non-Custodial Verification**: New `verifyZKProof` utility allows auditors to cryptographically verify that an agent followed policy within the enclave without ever seeing the raw thoughts.
+- **Thought-Chain Sanitization**: Automated redaction of sensitive patterns (keys, credentials, PII) from reasoning traces before persistent certificate generation.
+
+### Pillar VII: Interactive Temporal Steering (NEXUS)
+
+NEXUS transforms the `NexusTracer` from a passive observer into an active temporal control plane, enabling sub-second state reconstruction and hindsight injection.
+
+- **Temporal History Slider**: Real-time navigation through the agent's reasoning-space, allowing for high-fidelity state inspection at any point in the execution wave.
+- **Hindsight Injection Protocol**: Allows for the injection of "Steering Vectors" into past reasoning nodes to re-orient the agent's logic without a full session restart.
+- **Rollback-to-State**: Automated state reconstruction that resets the environment and `.planning/` directory to match a specific `auditId` signature.
+- **Dynamic Handover (DHH)**: Integrated confidence-based human escalation when reasoning entropy remains high after steering.
+
+### Pillar VIII: Agentic Revenue Operations (AgRevOps)
+
+AgRevOps treats agentic compute as a first-class financial and governance asset, providing real-time ROI and accountability.
+
+- **ROI Logic Engine**: Maps complex task completions (refactor, test, audit) to developer-hour savings ($100/hr) vs. provider token costs.
+- **Velocity Forecaster**: Predictive analytics that calculate milestone completion ETAs based on historical task-weight throughput and system latency.
+- **Governance Debt Monitoring**: Tracks policy bypasses and high-risk security findings to compute a "Security Health Score" (SHS), ensuring framework liability remains within enterprise bounds.
+
+---
+
+## 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/engine/nexus-tracer.js` | Integrated RES loop detection and entropy scoring. |
+| **Recovery Agent** | `bin/engine/temporal-hindsight.js` | Generates steering vectors for proactive recovery. |
+| **Skill Validator** | `bin/skill-validator.js` | JIT Binary Runtime Attestation and 7D scoring. |
+| **SRE Manager** | `bin/engine/sre-manager.js` | Trusted execution enclave management. |
+| **ROI Engine** | `bin/revops/roi-engine.js` | Financial value synthesis and cost/benefit mapping. |
+| **Velocity Forecaster** | `bin/revops/velocity-forecaster.js` | Predictive milestone ETA and throughput analytics. |
+| **Debt Monitor** | `bin/revops/debt-monitor.js` | Security Health Score (SHS) and governance debt tracking. |
+| **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/.mindforge/mirrors/mirror-sre-776a1cf9/docs/architecture/V6-SOVEREIGN.md

@@ -0,0 +1,43 @@
+# MindForge v6.1.0-alpha: Sovereign Intelligence (Pillars IX & X)
+
+The **Sovereign Intelligence** phase elevates MindForge from reactive autonomous waves to a self-optimizing, self-healing agentic operating system. This is achieved through real-time financial arbitrage and proactive reasoning integrity monitoring.
+
+---
+
+## Pillar IX: Autonomous Resource Harvesting (ARH)
+
+### Goal
+To maximize the economic efficiency of agentic work by dynamically harvesting the lowest-cost, highest-intelligence compute resources in real-time.
+
+### Components
+- **`MarketEvaluator`**: Real-time tracker for token pricing and intelligence benchmarks across model providers (Anthropic, OpenAI, Gemini).
+- **`RouterSteeringV2`**: Advanced task-to-model affinity engine. It calculates the **Min-Intelligence-Requirement (MIR)** and steers tasks accordingly.
+- **ROI Arbitrage Engine**: Automatically calculates and logs the "dollar value" saved by every autonomous wave compared to standard premium-only routing.
+
+### Workflow
+1. **MIR Analysis**: Before a subagent is spawned, the `CloudBroker` analyzes the task taxonomy.
+2. **Arbitrage Selection**: The `MarketEvaluator` selects the optimal model (e.g., routing small fixes to a local model while keeping architectural reasoning on Gemini 1.5 Pro).
+3. **Telemetry**: Savings are logged to `AUDIT.jsonl` under the `roi_arbitrage_event` category.
+
+---
+
+## Pillar X: Neural Drift Remediation (NDR)
+
+### Goal
+To proactively detect and remediate "Reasoning Drift" (logic loops, hallucinations, and semantic decay) before it corrupts the autonomous execution wave.
+
+### Components
+- **`LogicDriftDetector`**: Heuristics-based engine that analyzes the `reasoning_trace` for semantic density, pattern repetition, and logical contradictions.
+- **`RemediationEngine`**: A stateful recovery system that can trigger `REASONING_RESTART`, `GOLDEN_TRACE_INJECTION`, or `AUTONOMY_HALT`.
+- **NexusTracer Hooks**: Deep integration into the core execution loop to intercept every reasoning span.
+
+### Workflow
+1. **Drift Sensing**: At every 10 reasoning nodes, the `NexusTracer` evaluates the current `DriftScore` (0-100).
+2. **Remediation Trigger**: If `DriftScore > Threshold` (Default 75), the `RemediationEngine` is invoked.
+3. **Audit Closure**: Every remediation action is logged as a `drift_remediation_event`, ensuring the "hindsight" is preserved for future sessions.
+
+---
+
+## Architectural interlock (V6.1)
+
+Sovereign Intelligence is the final layer of the MindForge Enterprise roadmap. It leverages the **CADIA** risk engine (v6.0) and the **ZTAI** identity layer (v5.x) to ensure that all self-healing actions are both safe and non-repudiable.

package/.mindforge/mirrors/mirror-sre-776a1cf9/docs/architecture/adr-039-multi-runtime-support.md

@@ -0,0 +1,20 @@
+# ADR-039: Multi-Runtime Platform Support
+
+## Status
+Accepted
+
+## Context
+MindForge v1.0.0 was primarily designed for Claude Code and Antigravity. As the AI agent ecosystem expands, users are increasingly using runtimes like Cursor, GitHub Copilot, and Gemini CLI. To ensure MindForge remains the universal orchestration layer, we need native support for these platforms.
+
+## Decision
+We will implement a multi-runtime adapter system in `installer-core.js`.
+
+1.  **Unified Runtime Map**: A central `RUNTIMES` configuration defining paths, entry files, and capabilities (e.g., `supportsSlash`).
+2.  **Content Adapters**: Dynamic transformation of rules files (e.g., GEMINI.md) to match runtime-specific model names and conventions.
+3.  **Non-Slash Preambles**: For runtimes that do not support slash commands natively (Cursor, Copilot), we will inject a preamble explaining how to reference MindForge commands via file-path patterns.
+4.  **Local/Global Scoping**: Runtime-specific local directory detection (e.g., `.cursor/rules` vs `.agents/workflows`).
+
+## Consequences
+- **Positive**: MindForge becomes the first framework to provide a consistent "autonomous enterprise" experience across all major AI IDEs and CLIs.
+- **Positive**: Simplified onboarding for users of non-Claude runtimes.
+- **Neutral**: Increased complexity in the installer to handle 6+ distinct directory structures.

package/.mindforge/mirrors/mirror-sre-776a1cf9/docs/architecture/adr-040-additive-schema-migration.md

@@ -0,0 +1,21 @@
+# ADR-040: Additive Schema Migration Strategy
+
+## Status
+Accepted
+
+## Context
+MindForge v2.0.0 introduces new fields to `AUDIT.jsonl` and `token-usage.jsonl`. Previous migrations sometimes involve destructive changes or complex transformations. To ensure data integrity for enterprise users, we need a safer, more robust migration path.
+
+## Decision
+We will adopt an **additive-only** migration strategy for v2.0.0.
+
+1.  **Non-Destructive**: Every migration step must strictly append or backfill missing values without overwriting existing data.
+2.  **Smart Skipping**: Migration scripts must detect if a file is already at the target schema level and skip processing (idempotency).
+3.  **Backup-First**: Automatic creation of `.backups/` directories before any file modification.
+4.  **Audit Backfill**: Pre-v2.0.0 audit entries will be backfilled with `runtime: "unknown"` and `agent_id: "migrated-v1"` to preserve historical consistency.
+
+## Consequences
+- **Positive**: Zero risk of data loss during v1-to-v2 upgrades.
+- **Positive**: Simplified testing of migration logic (only new fields need verification).
+- **Positive**: Enterprise-grade reliability for long-running audit logs.
+- **Negative**: Historical entries will contain placeholder values for new fields.

package/.mindforge/mirrors/mirror-sre-776a1cf9/docs/architecture/adr-041-stable-runtime-interface-contract.md

@@ -0,0 +1,20 @@
+# ADR-041: Stable Runtime Interface Contract
+
+## Status
+Accepted
+
+## Context
+To support multi-runtime extensibility, we need a stable interface for the installer to interact with different platforms. Historically, these members were private constants within `installer-core.js`.
+
+## Decision
+We will promote critical runtime members to a public exported contract.
+
+1.  **Exported Members**: `RUNTIMES` map and `generateEntryContent` adapter function are now officially part of the `module.exports`.
+2.  **Stable Registry**: The `RUNTIMES` object must follow a strict schema: `displayName`, `globalDir`, `localDir`, `commandsSubdir`, `entryFile`, and `supportsSlash`.
+3.  **Extensibility**: This allows the `/mindforge:new-runtime` command and community plugins to dynamically inspect or extend MindForge support for new AI platforms without core framework modifications.
+
+## Consequences
+- **Positive**: Enables community-driven support for emerging AI tools.
+- **Positive**: Improved testability of the installer via standard Node.js `require`.
+- **Positive**: Decouples platform-specific logic from core installation routines.
+- **Neutral**: Any changes to these exported members must now be treated as potentially breaking in terms of semver.

package/.mindforge/mirrors/mirror-sre-776a1cf9/docs/architecture/decision-records-index.md

@@ -0,0 +1,29 @@
+# MindForge — Architecture Decision Records Index
+
+All 20 ADRs in chronological order.
+
+| ADR | Title | Status | Day | Key decision |
+|---|---|---|---|---|
+| ADR-001 | HANDOFF.json for cross-session state | Accepted | HANDOFF.json as the primary cross-session state artifact |
+| ADR-002 | Markdown-based commands | Accepted | Slash commands as Markdown files (not code) |
+| ADR-003 | Keyword-trigger model for skill loading | Accepted | Deterministic keyword matching over AI-decided selection |
+| ADR-004 | Wave parallelism over full parallelism | Accepted | Wave-based (dependency-ordered) over unconstrained parallel |
+| ADR-005 | Append-only JSONL for audit log | Accepted | AUDIT.jsonl append-only (never update, never delete) |
+| ADR-006 | Three-tier skills architecture | Accepted | Core → Org → Project tier hierarchy |
+| ADR-007 | Keyword-trigger model (reaffirmed at scale) | Accepted | Confirmed at 10+ skill scale |
+| ADR-008 | Just-in-time skill loading | Accepted | Load at task time, not session start |
+| ADR-009 | Environment-variable-only credential storage | Accepted | Credentials only in env vars, never in config files |
+| ADR-010 | Compliance gates non-bypassable; approvals allow emergency | Accepted | Gates: never bypass. Approvals: emergency override with audit |
+| ADR-011 | Integration failures are non-blocking | Accepted | Jira/Slack/GitHub down ≠ phase blocked |
+| ADR-012 | Intelligence outputs feed back into system behaviour | Accepted | Difficulty → granularity, retro → MINDFORGE.md, quality → behaviour |
+| ADR-013 | MINDFORGE.md as constitution with non-overridable primitives | Accepted | Non-overridable governance primitives cannot be disabled |
+| ADR-014 | Metrics are system signals, not developer performance | Accepted | Quality scores improve the system, not evaluate individuals |
+| ADR-015 | npm as the public skills registry | Accepted | npm ecosystem for skill distribution |
+| ADR-016 | CI timeout exits with code 0 (soft stop) | Accepted | Timeout = save and resume, not failure |
+| ADR-017 | SDK event stream is localhost-only | Accepted | SSE binds to 127.0.0.1 only |
+| ADR-018 | Installer detects and handles self-install | Accepted | Installer running inside its own repo = no-op for framework files |
+| ADR-019 | Self-update preserves original install scope | Accepted | Update local→local, global→global |
+| ADR-020 | v1.0.0 stable interface contract | Accepted | Defines what "stable" means for plugins and SDK consumers |
+| ADR-039 | Multi-runtime platform support | Accepted | Native support for Cursor, Gemini, Copilot, etc. |
+| ADR-040 | Additive schema migration strategy | Accepted | Non-destructive, backup-first backfill logic |
+| ADR-041 | Stable runtime interface contract | Accepted | Exported RUNTIMES and adapters for extensibility |

package/.mindforge/mirrors/mirror-sre-776a1cf9/docs/ci-cd-integration.md

@@ -0,0 +1,30 @@
+# MindForge CI/CD Integration
+
+## Overview
+MindForge supports non-interactive CI mode for GitHub Actions, GitLab CI, and Jenkins.
+CI mode activates when `CI=true` or `MINDFORGE_CI=true`.
+
+## GitHub Actions
+Use `.github/workflows/mindforge-ci.yml` for:
+- Health checks
+- Security scanning
+- Quality gates
+- AI PR review (if `ANTHROPIC_API_KEY` is set)
+
+## GitLab CI
+Use `.gitlab-ci-mindforge.yml` as a template. Ensure CI variables include:
+- `ANTHROPIC_API_KEY`
+- `GITHUB_TOKEN` (optional)
+- `SLACK_BOT_TOKEN` (optional)
+
+## Jenkins
+Use `.mindforge/ci/jenkins-adapter.md` for a Jenkinsfile template.
+
+## Governance in CI
+- Tier 1 auto-approves.
+- Tier 2 auto-approves only if `CI_AUTO_APPROVE_TIER2=true`.
+- Tier 3 always blocks CI and requires human approval.
+
+## Timeouts
+Timeouts are soft stops (exit code 0). MindForge saves state to `HANDOFF.json` and
+prints a summary in the CI step output.

package/.mindforge/mirrors/mirror-sre-776a1cf9/docs/ci-cd.md

@@ -0,0 +1,92 @@
+# 🚀 MindForge 5-Layer Plane Architecture (CI/CD)
+
+MindForge v2.0.0 uses a sophisticated Control + Execution Plane architecture for its GitHub Actions, ensuring enterprise-grade governance and autonomous execution capabilities.
+
+## 🏗️ The 5 Planes
+
+| Plane | Purpose | Trigger |
+| --- | --- | --- |
+| **Control Plane** | Change classification & Routing | `push`, `pull_request` |
+| **Execution Plane** | Headless agent runtime | `workflow_call` |
+| **AI Intelligence** | Multi-model code validation | PRs (reusable) |
+| **Release Plane** | Packaging & Deployment | Tags (`v*`) |
+| **Observability** | Run metrics & Analytics | Post-run |
+
+---
+
+## 🔄 PR Workflow Lifecycle
+
+When you open or update a Pull Request, MindForge triggers the following "Enterprise" sequence:
+
+1. **🔍 Classify**: Analyzes diffs to assign a **Governance Tier (1, 2, or 3)**.
+2. **⚖️ Govern**:
+    - **Tier 3 Enforcement**: Blocks the PR if sensitive changes are detected without an approval file.
+    - **Security Scan**: Automatically validates `MINDFORGE.md` and project configurations.
+3. **⚡ Execute**:
+    - Runs **Headless Agent** to verify autonomous logic.
+    - Executes full **Test Suite** and **Linter**.
+4. **🤖 Review**:
+    - Triggers **AI Intelligence Layer** (Claude + GPT-4o).
+    - Posts architectural/security findings as a **PR Comment**.
+5. **📊 Observe**: Generates a performance and audit trace report.
+
+---
+
+## 🔍 Control Plane & Tiers
+
+Every change is automatically classified into a governance tier:
+
+- **Tier 1 (Trivial)**: Auto-approves and executes basic verification.
+- **Tier 2 (Logic)**: Executes full test suites and AI review.
+- **Tier 3 (Sensitive)**: Blocks the pipeline unless a manual approval is found in `.planning/approvals/`.
+
+---
+
+## 🛠️ MindForge CLI (`bin/mindforge-cli.js`)
+
+All planes interact with MindForge via a centralized CLI router:
+
+- `health`: Validates project integrity.
+- `security-scan`: Scans for secrets and PII.
+- `headless`: Executes agents in non-interactive mode.
+- `pr-review`: Standard code review.
+- `cross-review`: Multi-model architecture validation.
+
+---
+
+## 🛡️ Governance Enforcement
+
+If a PR touches sensitive components (Auth, Payments, Security):
+1. The **Control Plane** identifies it as **Tier 3**.
+2. The **Governance Gate** fails unless a valid `.planning/approvals/*.json` file exists.
+3. Once approved, the **Execution Plane** resumes the workflow.
+
+
+
+---
+
+## 📦 Automated Releases
+
+Releases are triggered by pushing a semver tag:
+
+```bash
+git tag v2.0.0
+git push origin v2.0.0
+```
+
+This will automatically:
+
+- Run the full test suite.
+- Generate a CHANGELOG.
+- Publish to npm.
+- Create a GitHub Release with build artifacts.
+
+---
+
+## 📊 Observability
+
+MindForge tracks every CI execution:
+
+- **Success Rate**: Phase completion status.
+- **Token Usage**: AI cost monitoring.
+- **Audit Trace**: Full execution history in `AUDIT.jsonl`.

package/.mindforge/mirrors/mirror-sre-776a1cf9/docs/ci-quickstart.md

@@ -0,0 +1,78 @@
+# MindForge CI Quickstart (v1.0.0)
+
+This page shows how to run MindForge in real pipelines with non-interactive
+behavior and reliable outputs.
+
+## 1. Basic CI run (GitHub Actions)
+
+```yaml
+name: MindForge CI
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  mindforge:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install MindForge
+        run: npx mindforge-cc@latest --claude --local
+
+      - name: Run MindForge suite
+        run: node tests/install.test.js
+```
+
+## 2. CI mode behavior
+Set `CI=true` to enable non-interactive operation.
+
+MindForge in CI:
+- Skips interactive prompts
+- Emits structured output (if configured)
+- Blocks Tier 3 changes
+- Logs all gate results
+
+## 3. Recommended env settings
+```bash
+CI=true
+MINDFORGE_CI=true
+```
+
+## 4. Add full test battery (v1.0.0)
+```bash
+SUITES=(install wave-engine audit compaction skills-platform \
+        integrations governance intelligence metrics \
+        distribution ci-mode sdk production migration e2e)
+
+for SUITE in "${SUITES[@]}"; do
+  node tests/${SUITE}.test.js
+done
+```
+
+## 5. Reporting
+If you want JSON output in CI, set in `MINDFORGE.md`:
+```
+CI_OUTPUT_FORMAT=json
+```
+
+## 6. Common CI pitfalls
+- Missing Node 18+ → install newer Node
+- CI failing on Tier 3 changes → approvals required
+- Missing `.planning/` in CI → run `/mindforge:init-project` or `map-codebase`
+
+## 7. GitLab CI example
+```yaml
+stages: [test]
+
+mindforge:
+  stage: test
+  image: node:20
+  script:
+    - npx mindforge-cc@latest --claude --local
+    - node tests/install.test.js
+```