mindforge-cc 1.0.5 → 2.0.0-alpha.6

package/bin/review/cross-review-engine.js

@@ -0,0 +1,81 @@
+/**
+ * MindForge v2 — Cross-Review Engine
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const ModelClient = require('../models/model-client');
+const { synthesizeFindings, extractVerdict } = require('./finding-synthesizer');
+const { write: writeReport } = require('./review-report-writer');
+
+const PRIMARY_PROMPT = `You are a senior codebase architect performing a code review.
+Focus on: architectural alignment, logic correctness, maintainability, and complexity.
+Format every finding as: **[SEVERITY]** \`file:line\` — description
+Severities: LOW, MEDIUM, HIGH, CRITICAL.
+Finish with "### Verdict: APPROVE" or "### Verdict: REQUEST_CHANGES".`;
+
+const ADVERSARIAL_PROMPT = `You are a paranoid security auditor reviewing code written by a competitor.
+Your goal is to find bugs, security holes, and edge cases they missed. 
+Be critical. Trust nothing. 
+Format every finding as: **[SEVERITY]** \`file:line\` — description
+Severities: LOW, MEDIUM, HIGH, CRITICAL.
+Finish with "### Verdict: APPROVE" or "### Verdict: REQUEST_CHANGES".`;
+
+async function runCrossReview(params) {
+  const {
+    phaseNum,
+    diff,
+    context = '',
+    models = ['claude-3-5-sonnet-20240620', 'gpt-4o'],
+    sessionId = 'unknown'
+  } = params;
+
+  process.stdout.write(`⚡ Starting cross-model review for Phase ${phaseNum}...\n`);
+
+  const reviews = [];
+  
+  // Round 1: Primary
+  process.stdout.write(`  Round 1 (${models[0]}): `);
+  const r1 = await ModelClient.complete({
+    model: models[0],
+    systemPrompt: PRIMARY_PROMPT,
+    userMessage: `Context:\n${context}\n\nDiff:\n${diff}`,
+    taskName: `review-primary-phase-${phaseNum}`,
+    sessionId,
+    phaseNum
+  });
+  reviews.push({ model: models[0], content: r1.content, role: 'primary', cost_usd: r1.cost_usd });
+  process.stdout.write(`done ($${r1.cost_usd.toFixed(4)})\n`);
+
+  // Round 2: Adversarial
+  process.stdout.write(`  Round 2 (${models[1]}): `);
+  const r2 = await ModelClient.complete({
+    model: models[1],
+    systemPrompt: ADVERSARIAL_PROMPT,
+    userMessage: `Context:\n${context}\n\nDiff:\n${diff}`,
+    taskName: `review-adversarial-phase-${phaseNum}`,
+    sessionId,
+    phaseNum
+  });
+  reviews.push({ model: models[1], content: r2.content, role: 'adversarial', cost_usd: r2.cost_usd });
+  process.stdout.write(`done ($${r2.cost_usd.toFixed(4)})\n`);
+
+  // Synthesis
+  const synthesis = synthesizeFindings(reviews);
+  
+  const result = {
+    phase: phaseNum,
+    reviews,
+    synthesis,
+    total_cost_usd: reviews.reduce((sum, r) => sum + r.cost_usd, 0),
+    timestamp: new Date().toISOString()
+  };
+
+  const reportPath = writeReport(phaseNum, result);
+  process.stdout.write(`✅ Cross-review complete. Saved to ${reportPath}\n`);
+  
+  return result;
+}
+
+module.exports = { runCrossReview, parseFindings: synthesizeFindings.parseFindings, extractVerdict };

package/bin/review/finding-synthesizer.js

@@ -0,0 +1,116 @@
+/**
+ * MindForge v2 — Finding Synthesizer
+ * Identifies consensus, model-specific issues, and contradictions.
+ */
+'use strict';
+
+const SEVERITY_ORDER = ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'];
+
+function synthesizeFindings(reviews) {
+  const allFindings = [];
+  const modelSpecific = {};
+
+  for (const review of reviews) {
+    const findings = parseFindings(review.content);
+    modelSpecific[review.model] = findings;
+    for (const f of findings) {
+      allFindings.push({ ...f, model: review.model });
+    }
+  }
+
+  // Detect consensus
+  const consensus = [];
+  const processed = new Set();
+
+  for (let i = 0; i < allFindings.length; i++) {
+    if (processed.has(i)) continue;
+    const f1 = allFindings[i];
+    const group = [f1];
+    processed.add(i);
+
+    for (let j = i + 1; j < allFindings.length; j++) {
+      if (processed.has(j)) continue;
+      const f2 = allFindings[j];
+      
+      if (isSameFinding(f1, f2)) {
+        group.push(f2);
+        processed.add(j);
+      }
+    }
+
+    if (group.length >= 2) {
+      consensus.push({
+        location: f1.location,
+        description: f1.description,
+        severity: getHighestSeverity(group.map(f => f.severity)),
+        models: group.map(f => f.model),
+      });
+    }
+  }
+
+  // Detect contradictions (large severity gap on same finding)
+  const contradictions = [];
+  // (In a real implementation, we'd more deeply analyze conflicting logic)
+
+  return {
+    consensus,
+    model_specific: modelSpecific,
+    contradictions,
+    total_findings: allFindings.length,
+    critical_count: allFindings.filter(f => f.severity === 'CRITICAL').length,
+    overall_verdict: getOverallVerdict(reviews.map(r => extractVerdict(r.content)))
+  };
+}
+
+function parseFindings(text) {
+  const findings = [];
+  // Simple regex-based parser for the [SEVERITY] location - description format
+  const regex = /\*\*\[(LOW|MEDIUM|HIGH|CRITICAL)\]\*\* `([^`]+)` — ([^\n]+)/g;
+  let match;
+  while ((match = regex.exec(text)) !== null) {
+    findings.push({
+      severity: match[1],
+      location: match[2],
+      description: match[3].trim()
+    });
+  }
+  return findings;
+}
+
+function isSameFinding(f1, f2) {
+  const loc1 = normalizeLocation(f1.location);
+  const loc2 = normalizeLocation(f2.location);
+  return loc1 === loc2;
+}
+
+function normalizeLocation(loc) {
+  if (!loc) return '';
+  // Fuzzy match on line numbers using 20-line band
+  return loc.toLowerCase().replace(/:(\d+)$/, (_, n) => {
+    const band = Math.round(parseInt(n, 10) / 20) * 20;
+    return `:${band}`;
+  });
+}
+
+function getHighestSeverity(severities) {
+  let highest = 0;
+  for (const s of severities) {
+    const idx = SEVERITY_ORDER.indexOf(s);
+    if (idx > highest) highest = idx;
+  }
+  return SEVERITY_ORDER[highest];
+}
+
+function extractVerdict(text) {
+  if (text.includes('### Verdict: APPROVE')) return 'APPROVE';
+  if (text.includes('### Verdict: REQUEST_CHANGES')) return 'REQUEST_CHANGES';
+  return 'COMMENT';
+}
+
+function getOverallVerdict(verdicts) {
+  if (verdicts.includes('REQUEST_CHANGES')) return 'REQUEST_CHANGES';
+  if (verdicts.every(v => v === 'APPROVE')) return 'APPROVE';
+  return 'COMMENT';
+}
+
+module.exports = { synthesizeFindings, parseFindings, extractVerdict };

package/bin/review/review-report-writer.js

@@ -0,0 +1,49 @@
+/**
+ * MindForge v2 — Review Report Writer
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function write(phaseNum, result) {
+  const dir = path.join(process.cwd(), '.planning', 'phases', String(phaseNum));
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const reportPath = path.join(dir, `CROSS-REVIEW-${phaseNum}.md`);
+
+  let content = [
+    `# Cross-Model Code Review — Phase ${phaseNum}`,
+    `**Verdict:** ${result.synthesis.overall_verdict === 'APPROVE' ? '✅ APPROVE' : '❌ REQUEST_CHANGES'}`,
+    `**Total Cost:** $${result.total_cost_usd.toFixed(4)}`,
+    `**Models:** ${result.reviews.map(r => r.model).join(', ')}`,
+    `**Date:** ${new Date(result.timestamp).toLocaleString()}`,
+    '',
+    '## Consensus Findings (High Confidence)',
+    result.synthesis.consensus.length > 0
+      ? result.synthesis.consensus.map(f => `- **[${f.severity}]** \`${f.location}\` — ${f.description} (Models: ${f.models.join(', ')})`).join('\n')
+      : '_No consensus issues found._',
+    '',
+    '## Model-Specific Findings',
+  ].join('\n');
+
+  for (const model in result.synthesis.model_specific) {
+    const findings = result.synthesis.model_specific[model];
+    content += `\n### ${model}\n`;
+    if (findings.length === 0) {
+      content += '_No specific issues found._\n';
+    } else {
+      content += findings.map(f => `- **[${f.severity}]** \`${f.location}\` — ${f.description}`).join('\n') + '\n';
+    }
+  }
+
+  content += '\n## Full Model Outputs\n';
+  for (const review of result.reviews) {
+    content += `\n### ${review.model} (${review.role})\n\n${review.content}\n\n---\n`;
+  }
+
+  fs.writeFileSync(reportPath, content);
+  return reportPath;
+}
+
+module.exports = { write };

package/bin/updater/self-update.js

@@ -76,13 +76,13 @@ async function checkAndUpdate(options = {}) {
 
   console.log(`\n${bold('⚡  MindForge Update Check')}\n`);
   console.log(`  Current : v${CURRENT_VERSION}`);
-  process.stdout.write(`  Latest  : checking npm registry... `);
+  process.stdout.write('  Latest  : checking npm registry... ');
 
   const latestVersion = await fetchLatestVersion();
   if (!latestVersion) {
     console.log(`${warn('unavailable')}`);
     console.log(`\n  ${warn('⚠️')}  Cannot reach npm registry. Check your internet connection.`);
-    console.log(`  Manual check: npm info mindforge-cc version\n`);
+    console.log('  Manual check: npm info mindforge-cc version\n');
     return { status: 'check-failed' };
   }
 
@@ -99,30 +99,30 @@ async function checkAndUpdate(options = {}) {
   // Major version safety gate
   if (type === 'major' && !force) {
     console.log(`\n  ${warn('⚠️  MAJOR UPDATE')} — may contain breaking changes.`);
-    console.log(`  Review the changelog before applying.`);
-    console.log(`  To apply anyway: /mindforge:update --apply --force\n`);
+    console.log('  Review the changelog before applying.');
+    console.log('  To apply anyway: /mindforge:update --apply --force\n');
   }
 
   // Fetch and display changelog
   if (!skipChangelog) {
-    process.stdout.write(`\n  Fetching changelog... `);
+    process.stdout.write('\n  Fetching changelog... ');
     const changelog = await fetchChangelog(CURRENT_VERSION, latestVersion);
     if (changelog) {
-      console.log(`done\n`);
+      console.log('done\n');
       console.log('─'.repeat(62));
       console.log(changelog.slice(0, 3000));  // Max 3000 chars to avoid flooding terminal
-      if (changelog.length > 3000) console.log(`\n  [changelog truncated — see CHANGELOG.md for full details]`);
+      if (changelog.length > 3000) console.log('\n  [changelog truncated — see CHANGELOG.md for full details]');
       console.log('─'.repeat(62));
     } else {
-      console.log(`unavailable\n`);
+      console.log('unavailable\n');
     }
   }
 
   if (!apply) {
     if (isCI) {
-      console.log(`\n  CI mode: check-only (no apply without --apply)`);
+      console.log('\n  CI mode: check-only (no apply without --apply)');
     }
-    console.log(`\n  To apply: /mindforge:update --apply`);
+    console.log('\n  To apply: /mindforge:update --apply');
     console.log(`  Or directly: npx mindforge-cc@${latestVersion} --update\n`);
     return { status: 'update-available', current: CURRENT_VERSION, latest: latestVersion, type };
   }
@@ -136,7 +136,7 @@ async function checkAndUpdate(options = {}) {
   // Detect original install scope to preserve it
   const { scope, runtime } = detectInstallScope();
   console.log(`  Install scope : ${runtime} / ${scope}`);
-  console.log(`\n  Applying update...`);
+  console.log('\n  Applying update...');
 
   try {
     execSync(
@@ -158,11 +158,11 @@ async function checkAndUpdate(options = {}) {
     }
   } catch (migErr) {
     console.warn(`  ${warn('⚠️')}  Schema migration had an issue: ${migErr.message}`);
-    console.warn(`      Run /mindforge:migrate manually if state files look wrong.`);
+    console.warn('      Run /mindforge:migrate manually if state files look wrong.');
   }
 
   console.log(`\n  ${ok('✅')}  MindForge updated to v${latestVersion}\n`);
-  console.log(`  Run /mindforge:health to verify the update.\n`);
+  console.log('  Run /mindforge:health to verify the update.\n');
   return { status: 'updated', from: CURRENT_VERSION, to: latestVersion };
 }
 

package/bin/wizard/setup-wizard.js

@@ -246,4 +246,8 @@ async function main() {
   }
 }
 
-main();
+module.exports = { main };
+
+if (require.main === module) {
+  main();
+}

package/docs/adr/ADR-024-browser-localhost-only.md

@@ -0,0 +1,17 @@
+# ADR-024: Browser Daemon Localhost Binding
+
+## Status
+Accepted
+
+## Context
+The MindForge v2 Browser Runtime exposes an HTTP API for controlling a Chromium instance. This API allows for powerful actions like navigation, interaction, and data extraction, which could be exploited if exposed to the network.
+
+## Decision
+We will strictly bind the Browser Daemon to `127.0.0.1` (localhost) only.
+
+1. The HTTP server will only listen on `127.0.0.1`.
+2. The server will perform a secondary check on `req.socket.remoteAddress` to reject any requests not originating from `127.0.0.1`, `::1`, or `::ffff:127.0.0.1`.
+
+## Consequences
+- The daemon cannot be controlled remotely by default, significantly reducing the attack surface.
+- Developers needing remote control must use an explicit SSH tunnel or reverse proxy with authentication.

package/docs/adr/ADR-025-visual-verify-failure-treatment.md

@@ -0,0 +1,19 @@
+# ADR-025: <verify-visual> Failure Treatment
+
+## Status
+Accepted
+
+## Context
+Visual verification is a critical part of the UI development lifecycle in MindForge v2. Failures in visual verification often indicate broken layouts or missing components that standard unit/integration tests might miss.
+
+## Decision
+Failures within a `<verify-visual>` block in a PLAN file will be treated as fatal errors, equivalent to a `<verify>` (shell command) failure.
+
+1. The wave executor will stop immediately if a visual verification fails.
+2. The user will be notified of the specific failure (e.g., "Element not visible").
+3. Subsequent waves or phase-level verification will not proceed until the failure is resolved.
+
+## Consequences
+- High confidence in UI integrity.
+- Prevents "broken" UI states from being committed to the codebase.
+- May slightly increase development time if visual selectors are brittle.

package/docs/adr/ADR-026-session-persistence-security.md

@@ -0,0 +1,20 @@
+# ADR-026: Browser Session Persistence and Security
+
+## Status
+Accepted
+
+## Context
+MindForge v2 persists browser sessions (cookies, localStorage) to allow for seamless multi-phase development without re-authentication.
+
+## Decision
+1. Session files will be stored in `.mindforge/browser/sessions/`.
+2. All files in this directory will be explicitly ignored by Git to prevent leaking sensitive credentials (auth tokens).
+3. Session files are JSON-formatted and map directly to Playwright's state format.
+
+## Implementation
+- Update `.gitignore` to include `.mindforge/browser/sessions/`.
+- `session-manager.js` will handle the logic for atomic file writes and reads.
+
+## Consequences
+- Security: Credentials are kept local to the developer's machine.
+- Dev Experience: Sessions persist across restarts of the tool or the daemon.

package/docs/architecture/README.md

@@ -8,13 +8,16 @@ Markdown protocols and JSON schemas, with a small Node.js CLI runtime.
 1. **Command layer** — Markdown commands in `.claude/commands/mindforge/`
 2. **Engine layer** — Execution protocols under `.mindforge/engine/`
 3. **Governance layer** — Approvals, audit, compliance gates in `.mindforge/governance/`
-4. **Intelligence layer** — Health, difficulty, anti-patterns in `.mindforge/intelligence/`
-5. **Distribution layer** — Installer, registry, CI, SDK, plugins
+4. **Intelligence Layer** — Health, difficulty, anti-patterns in `.mindforge/intelligence/`
+5. **Knowledge Layer** — Long-term memory, capture, and sync in `.mindforge/memory/`
+6. **Distribution Layer** — Installer, registry, CI, SDK, plugins
+7. **Observability Layer (v2)** — Real-time dashboard, SSE bridge, metrics aggregator
 
 ## Key data artifacts
 - `.planning/PROJECT.md` — project brief
 - `.planning/STATE.md` — current execution state
 - `.planning/HANDOFF.json` — machine-readable session handoff
+- `.mindforge/memory/knowledge-base.jsonl` — local project memory
 - `.planning/AUDIT.jsonl` — append-only audit log
 
 ## Runtime flow (high level)
@@ -22,6 +25,7 @@ Markdown protocols and JSON schemas, with a small Node.js CLI runtime.
 2. `/mindforge:execute-phase` runs plans in waves
 3. `/mindforge:verify-phase` runs automated + human gates
 4. `/mindforge:ship` generates release artifacts and PR metadata
+5. `/mindforge:dashboard` provides real-time observability and governance
 
 ## Installation targets
 - Claude Code: `~/.claude/` or `.claude/`

package/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 "Beast" 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/docs/commands-reference.md

@@ -8,4 +8,5 @@
 | `/mindforge:execute-phase [N]`  | Execute plans with wave-based parallelism     |
 | `/mindforge:verify-phase [N]`   | Human acceptance testing + automated checks  |
 | `/mindforge:ship [N]`           | Generate changelog, run quality gates, create PR |
+| `/mindforge:dashboard`           | Manage the real-time web observability dashboard |
 

package/docs/feature-dashboard.md

@@ -0,0 +1,52 @@
+# Feature: Real-time Dashboard (v2)
+
+The MindForge Real-time Dashboard provides a high-fidelity, web-based control center for your agentic workflows. It leverages **Server-Sent Events (SSE)** to push live updates from your codebase directly to your browser with zero performance overhead.
+
+## 🚀 Getting Started
+
+To launch the dashboard:
+```bash
+/mindforge:dashboard --start --open
+```
+
+Default access: `http://localhost:7339` (Strictly bound to `127.0.0.1` for security).
+
+## 🛠 Key Features
+
+### 1. Live Audit Stream
+- Real-time rolling feed of all `AUDIT.jsonl` events.
+- Color-coded status indicators (Success, Failure, Security Warning).
+- Detailed JSON inspection for every action.
+
+### 2. Performance Metrics
+- **Token Costs**: Cumulative and session-based cost tracking across all providers.
+- **Quality Score**: Real-time graphing of verify-pass-rates.
+- **Compaction Health**: Monitoring of context management efficiency.
+
+### 3. Web-based Governance
+- **Tier 2/3 Approvals**: Review pending architectural or security changes.
+- **Tier 3 Confirmation**: Mandatory plan ID typing for high-risk approvals is enforced in the UI.
+- **Decision History**: Interactive timeline of past approvals and rejections.
+
+### 4. Team & Agent Activity
+- **Wave Progress**: Track multiple agents executing parallel waves.
+- **Persona Context**: See which agent personas are currently active.
+- **Steerage Feed**: View steering instructions as they are applied.
+
+## 🛡 Hardened Security
+- **Localhost Binding**: The server refuses connections from external IPs.
+- **CORS Lock-down**: Only allows requests from the local control plane.
+- **Integrity First**: Audit logs are written by the backend *before* changes are committed, ensuring a bulletproof trail.
+
+## 📟 Command Reference
+
+| Flag | Action |
+| :--- | :--- |
+| `--start` | Launch the dashboard server process. |
+| `--stop` | Gracefully shut down the server. |
+| `--status` | Check if the dashboard is running and get PID. |
+| `--open` | Open the UI in your default browser. |
+| `--port [N]` | Change the default port (7339). |
+
+---
+*For technical implementation details, see `.mindforge/dashboard/dashboard-spec.md`.*

package/docs/publishing-guide.md

@@ -0,0 +1,43 @@
+# MindForge Publishing Guide
+
+This guide outlines the standard procedure for publishing a new version of `mindforge-cc` and its associated SDK to npm. Following this process ensures stability, correct versioning, and structural integrity.
+
+## Prerequisites
+
+1. **NPM Permissions**: You must have publish access to the `mindforge-cc` and `@mindforge/sdk` packages.
+2. **Clean State**: Ensure all changes are committed and your working directory is clean.
+3. **Authentication**: Run `npm whoami` to verify you are logged into the correct account.
+
+## Step-by-Step Workflow
+
+### 1. Pre-Flight Verification & Adversarial Review
+Before any release, ensure the following is completed:
+
+- **Structural Integrity**: Run `npm test` to verify layout and command mirroring.
+- **Security Check**: Run `/mindforge:security-scan` to ensure no keys or CVEs are present.
+- **Mult-Model Review**: Run `/mindforge:cross-review` to have multiple models (Claude, GPT, Gemini) audit the new features for edge cases.
+
+### 2. Versioning Strategy
+MindForge follows SemVer. Update `package.json` and `CHANGELOG.md` first.
+
+### 3. Automated Release Workflow
+MindForge provides a built-in workflow to handle the heavy lifting:
+
+1. Run the slash command: `/publish-release`
+2. Follow the interactive prompts to execute tests and dry runs.
+
+### 4. Manual Publishing (Fallback)
+If the workflow is unavailable:
+
+```bash
+npm publish --tag alpha --access public
+```
+
+### 5. Git Tagging & Origin Sync
+```bash
+git tag v[version]
+git push origin --tags
+```
+
+---
+*Last Updated: 2026-03-22*