mindforge-cc 8.1.0 → 8.2.0

package/.planning/archive/v8-cleanup/implementation-roadmap/v2.0.0/ci-actions/github-workflows-v2.md

@@ -0,0 +1,421 @@
+# 🧠 MindForge Day 10 — Enterprise GitHub Actions System (Control + Execution Plane Architecture)
+
+## Context
+
+You are building **MindForge v2.0.0**, an enterprise-grade agentic framework with:
+
+* Command-driven architecture (`/mindforge:*`)
+* Autonomous execution (`/mindforge:auto`)
+* Multi-model intelligence (Claude, GPT-4o, Gemini)
+* Governance system (Tier 1/2/3 approvals, compliance gates)
+* State persistence (`.planning/HANDOFF.json`)
+* Audit system (`.planning/AUDIT.jsonl`)
+* CI mode + SDK integration
+
+Your task is to design and implement a **production-grade GitHub Actions system** that aligns with:
+
+* Enterprise CI/CD standards (Amazon / Stripe level)
+* Agentic workflow execution (NOT traditional CI)
+* Governance-first enforcement
+* Observability + failure-first design
+* Modular, scalable architecture
+
+---
+
+# 🎯 Objective
+
+Build a **5-layer GitHub Actions architecture**:
+
+1. **Control Plane** → orchestrates CI + governance
+2. **Execution Plane** → runs MindForge agents
+3. **AI Intelligence Layer** → multi-model review
+4. **Release Plane** → packaging + deployment
+5. **Observability Plane** → metrics + audit analysis
+
+---
+
+# 🏗️ Required Workflows
+
+Create the following inside `.github/workflows/`:
+
+---
+
+## 1. control-plane.yml (🔥 Orchestrator — REQUIRED ENTRY POINT)
+
+### Purpose
+
+Acts as the **brain of CI/CD**:
+
+* Classifies changes
+* Enforces governance
+* Routes execution
+
+### Triggers
+
+* `pull_request`
+* `push` to `main`, `develop`
+
+---
+
+### Jobs
+
+#### Job 1 — Setup
+
+* Checkout repo
+* Setup Node.js (>=18)
+* Cache dependencies (npm)
+
+---
+
+#### Job 2 — Change Classification (CRITICAL)
+
+Implement logic inspired by `change-classifier.md`:
+
+Detect:
+
+* File paths (`auth/`, `payment/`, `security/`)
+* Code patterns (`jwt`, `bcrypt`, `stripe`, PII usage)
+* Sensitive modules
+
+Output:
+
+* `tier=1|2|3`
+
+---
+
+#### Job 3 — Governance Enforcement (NON-BYPASSABLE)
+
+Rules:
+
+* ❗ Tier 3 → FAIL unless approved
+* ❗ Secrets detected → FAIL
+* ❗ GDPR violations → FAIL
+* ❗ CRITICAL security findings → FAIL
+
+Run:
+
+```bash
+mindforge-cc security-scan
+mindforge-cc health --repair
+```
+
+---
+
+#### Job 4 — Pipeline Routing
+
+Conditionally trigger:
+
+* execution-plane.yml
+* ai-intelligence.yml
+
+Use:
+
+```yaml
+uses: ./.github/workflows/execution-plane.yml
+```
+
+---
+
+#### Job 5 — Step Summary
+
+Generate:
+
+* Tier classification
+* Gate results
+* Next actions
+
+Use GitHub Step Summary
+
+---
+
+## 2. execution-plane.yml (⚡ Agent Runtime Layer)
+
+### Purpose
+
+Executes MindForge workflows in CI (headless mode)
+
+---
+
+### Trigger
+
+* `workflow_call`
+
+---
+
+### Jobs
+
+#### Job 1 — Environment Setup
+
+* Node setup
+* Install MindForge CLI
+* Validate config (`MINDFORGE.md`)
+
+---
+
+#### Job 2 — Health Check
+
+```bash
+mindforge-cc health --verbose
+```
+
+---
+
+#### Job 3 — Execute Agent Workflow
+
+Run:
+
+```bash
+mindforge-cc headless \
+  --phase $PHASE \
+  --timeout 3600 \
+  --output json
+```
+
+---
+
+#### Job 4 — Verification Pipeline
+
+* Run tests
+* Run lint
+* Run type check
+
+---
+
+#### Job 5 — Artifact Upload (CRITICAL)
+
+Upload:
+
+* `.planning/HANDOFF.json`
+* `.planning/AUDIT.jsonl`
+* `AUTONOMOUS-REPORT.md`
+
+---
+
+#### Job 6 — Failure Handling
+
+Rules:
+
+* Exit 0 → timeout (resume later)
+* Exit 1 → real failure
+* Retry transient failures (max 3)
+
+---
+
+## 3. ai-intelligence.yml (🤖 Multi-Model Layer)
+
+### Purpose
+
+Implements cross-model validation
+
+---
+
+### Trigger
+
+* Pull Requests
+
+---
+
+### Jobs
+
+#### Job 1 — Standard Review
+
+```bash
+mindforge-cc pr-review
+```
+
+---
+
+#### Job 2 — Cross-Model Review
+
+```bash
+mindforge-cc cross-review \
+  --models claude,gpt4o \
+  --focus security,architecture
+```
+
+---
+
+#### Job 3 — Result Publishing
+
+* Comment on PR
+* Add GitHub annotations
+* Upload reports
+
+---
+
+#### Constraints
+
+* Respect token limits
+* Cache per commit SHA
+
+---
+
+## 4. release-plane.yml (🚀 Production Deployment)
+
+### Trigger
+
+* Tag push (`v*`)
+
+---
+
+### Jobs
+
+#### Job 1 — Validation
+
+* Version consistency
+* Full CI run
+
+---
+
+#### Job 2 — Build
+
+* npm build
+* package verification
+
+---
+
+#### Job 3 — Publish
+
+* npm publish
+* GitHub release creation
+
+---
+
+#### Job 4 — Notifications
+
+* Slack (if configured)
+* Release summary
+
+---
+
+## 5. observability-plane.yml (📊 Competitive Advantage)
+
+### Purpose
+
+Analyze and learn from executions
+
+---
+
+### Trigger
+
+* `workflow_run` (after control-plane)
+
+---
+
+### Jobs
+
+#### Job 1 — Collect Data
+
+* AUDIT.jsonl
+* HANDOFF.json
+* metrics files
+
+---
+
+#### Job 2 — Analysis
+
+Compute:
+
+* Failure rate
+* Node repairs
+* Token usage
+* Execution time
+
+---
+
+#### Job 3 — Output
+
+* Upload artifacts
+* Generate summary report
+
+---
+
+# ⚙️ Advanced Engineering Requirements
+
+---
+
+## 1. Architecture
+
+* Modular workflows (no monolith)
+* Use `workflow_call`
+* Parallel execution with `needs:`
+
+---
+
+## 2. Security
+
+* Secrets only via GitHub Secrets
+* Mask sensitive logs
+* No credentials in outputs
+
+---
+
+## 3. Performance
+
+* Cache:
+
+  * node_modules
+  * AI results
+* Use matrix builds (Node versions)
+
+---
+
+## 4. Observability
+
+* Step Summary (MANDATORY)
+* Structured logs (JSON)
+* Artifact versioning
+
+---
+
+## 5. Failure Strategy
+
+* Fail fast on critical errors
+* Retry transient failures
+* Resume from HANDOFF.json
+
+---
+
+# 🧠 Integration Requirements
+
+Workflows MUST integrate with:
+
+* `.planning/HANDOFF.json` (state)
+* `.planning/AUDIT.jsonl` (audit log)
+* `/mindforge:auto`
+* `/mindforge:security-scan`
+* `/mindforge:review`
+
+---
+
+# 🧪 Testing Scenarios
+
+Simulate:
+
+1. PR with secret → must FAIL
+2. Tier 3 change → must block
+3. Autonomous execution → must resume
+4. AI review → must comment on PR
+
+---
+
+# 📦 Deliverables
+
+* All `.github/workflows/*.yml`
+* Reusable composite actions (optional)
+* Documentation: `docs/ci-cd.md`
+* Architecture diagram
+
+---
+
+# 🔥 Final Goal
+
+This CI/CD system should:
+
+* Enable **autonomous software development**
+* Enforce **enterprise governance**
+* Support **multi-model validation**
+* Provide **deep observability**
+* Be **scalable, modular, and secure**
+
+---

package/.planning/archive/v8-cleanup/implementation-roadmap/v2.0.0/ci-actions/v2-ci-actions.md

@@ -0,0 +1,292 @@
+# 🧠 MindForge Day 10 — GitHub Actions + Workflow System (Enterprise Grade)
+
+## Context
+
+You are working on **MindForge v2.0.0**, an enterprise-grade agentic framework with:
+
+* Autonomous execution engine (`/mindforge:auto`)
+* Multi-model intelligence layer (Claude, GPT-4o, Gemini)
+* CI/CD integration with governance gates
+* Skills system, audit logs, and compliance enforcement
+
+Your task is to design and implement a **production-grade GitHub Actions system** that aligns with:
+
+* Enterprise CI/CD standards
+* Agentic workflow orchestration
+* Security-first pipelines
+* Observability + failure-first design
+
+---
+
+## 🎯 Objective
+
+Design a **modular, scalable GitHub Actions architecture** that supports:
+
+1. Continuous Integration (CI)
+2. Autonomous Agent Execution (Headless Mode)
+3. Cross-Model Code Review
+4. Security + Compliance Gates (non-bypassable)
+5. Release + Distribution pipeline (npm + GitHub Releases)
+6. Observability + Debuggability
+
+---
+
+## 🏗️ Required Workflows (MANDATORY)
+
+Create the following workflows inside `.github/workflows/`:
+
+---
+
+### 1. `mindforge-ci.yml` (Core CI Pipeline)
+
+Trigger:
+
+* `push` to `main`, `develop`
+* `pull_request`
+
+Jobs:
+
+#### Job 1 — Setup & Cache
+
+* Node.js setup (v18+)
+* Cache npm dependencies
+* Install dependencies
+
+#### Job 2 — Health Check
+
+* Run: `/mindforge:health --repair`
+* Validate:
+
+  * HANDOFF.json schema
+  * MINDFORGE.md config
+  * Required directories exist
+
+#### Job 3 — Code Quality
+
+* TypeScript compile (`tsc`)
+* ESLint
+* Prettier check
+* Fail on any issue
+
+#### Job 4 — Testing
+
+* Unit tests
+* Integration tests
+* Coverage enforcement (>= MIN_TEST_COVERAGE_PCT)
+
+#### Job 5 — Security Scan (NON-BYPASSABLE)
+
+* Secret detection
+* Dependency audit (`npm audit`)
+* OWASP checks via `/mindforge:security-scan`
+* ❗ If CRITICAL → FAIL pipeline immediately
+
+#### Job 6 — Governance Gate
+
+* Run compliance gates:
+
+  * No secrets
+  * No CRITICAL vulnerabilities
+  * GDPR checks (PII detection)
+* ❗ Tier 3 changes MUST fail without approval
+
+---
+
+### 2. `mindforge-ai-review.yml` (Cross-Model Review)
+
+Trigger:
+
+* Pull Requests only
+
+Jobs:
+
+#### AI Review Job
+
+* Run `/mindforge:pr-review`
+* Run `/mindforge:cross-review --models claude,gpt4o`
+* Generate:
+
+  * CODE-REVIEW.md
+  * CROSS-REVIEW.md
+
+Post results as:
+
+* PR comment
+* GitHub annotations
+
+Constraints:
+
+* Respect daily token limits
+* Cache results per commit SHA
+
+---
+
+### 3. `mindforge-autonomous.yml` (Headless Execution)
+
+Trigger:
+
+* Manual (`workflow_dispatch`)
+* Scheduled (cron)
+
+Inputs:
+
+* phase number
+* timeout
+* dry-run flag
+
+Steps:
+
+* Run:
+
+```bash
+mindforge-cc headless --phase $PHASE --timeout $TIMEOUT --output json
+```
+
+Outputs:
+
+* Structured JSON result
+* Upload artifacts:
+
+  * HANDOFF.json
+  * AUDIT.jsonl
+  * AUTONOMOUS-REPORT.md
+
+Failure Handling:
+
+* If partial → mark as warning
+* If critical failure → fail job
+
+---
+
+### 4. `mindforge-release.yml` (Release Pipeline)
+
+Trigger:
+
+* Tag push (`v*`)
+
+Steps:
+
+1. Validate version consistency
+2. Run full CI pipeline
+3. Generate CHANGELOG
+4. Build package
+5. Publish to npm
+6. Create GitHub Release
+7. Attach artifacts
+8. Notify Slack (if configured)
+
+---
+
+### 5. `mindforge-observability.yml` (Advanced)
+
+Trigger:
+
+* Always-on (post CI)
+
+Responsibilities:
+
+* Upload metrics:
+
+  * session-quality.jsonl
+  * token-usage.jsonl
+* Generate summary:
+
+  * success rate
+  * failure patterns
+* Store as artifacts
+
+---
+
+## ⚙️ Advanced Design Requirements
+
+### 1. Pipeline Architecture
+
+* Use **job dependencies (needs:)**
+* Parallelize where possible
+* Fail fast on critical stages
+
+### 2. Security First
+
+* Secrets via GitHub Secrets ONLY
+* No credentials in logs
+* Mask all sensitive output
+
+### 3. Caching Strategy
+
+* Node modules cache
+* AI review cache (commit SHA)
+* Skill registry cache
+
+### 4. Observability
+
+* Use GitHub Step Summary
+* Upload logs as artifacts
+* Structured JSON outputs
+
+### 5. Failure Handling
+
+* Exit code 0 for timeout (resume later)
+* Exit code 1 for real failures
+* Retry transient failures (3 attempts)
+
+---
+
+## 🧠 Integration with MindForge Core
+
+Ensure workflows integrate with:
+
+* `.planning/HANDOFF.json`
+* `.planning/AUDIT.jsonl`
+* `/mindforge:auto`
+* `/mindforge:review`
+* `/mindforge:security-scan`
+
+---
+
+## 📦 Deliverables
+
+1. Full `.github/workflows/*.yml` files
+2. Reusable composite GitHub Actions (if needed)
+3. CI configuration in `MINDFORGE.md`
+4. Documentation:
+
+   * docs/ci-cd.md
+   * pipeline architecture diagram
+
+---
+
+## 🚀 Bonus (HIGH PRIORITY)
+
+* Add **matrix builds** (Node versions)
+* Add **self-healing retry logic**
+* Add **artifact versioning**
+* Add **PR status checks integration**
+* Add **branch protection compatibility**
+
+---
+
+## 🧪 Testing
+
+* Simulate:
+
+  * PR with security issue
+  * PR with Tier 3 change
+  * Autonomous execution
+* Ensure:
+
+  * Correct failures
+  * Proper logs
+  * No silent errors
+
+---
+
+## 🔥 Final Goal
+
+This pipeline should:
+
+* Match or exceed enterprise CI/CD systems (Amazon / Stripe level)
+* Fully support agentic workflows
+* Be scalable, observable, and secure
+* Enable autonomous development safely
+
+---