mindforge-cc 2.3.5 → 3.0.0

package/bin/review/ads-engine.js

@@ -0,0 +1,126 @@
+/**
+ * MindForge v3 — ADS Engine
+ * Orchestrates the Red-Team/Blue-Team synthesis loop.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const ModelClient = require('../models/model-client');
+const { calculateSoulScore, parseMetrics, synthesizeADSPlan } = require('./ads-synthesizer');
+const { v4: uuidv4 } = require('uuid');
+
+async function runADSSynthesis(params) {
+  const {
+    phaseNum,
+    goal,
+    context = '',
+    sessionId = 'unknown'
+  } = params;
+
+  process.stdout.write(`🛡️ Starting Adversarial Decision Synthesis (ADS) for Phase ${phaseNum}...\n`);
+
+  // Step 1: Blue Proposal (Architect)
+  process.stdout.write(`  Step 1: Architect (Blue Team) Proposal... `);
+  const blueResponse = await ModelClient.complete({
+    persona: 'architect',
+    tier: 2,
+    systemPrompt: `You are the Blue Team Architect. Your goal is to propose a high-performance, scalable solution.
+Include a [ADS_METRICS] block with impact, leverage, reversibility, effort, risk, cost (1-10).
+Format: [ADS_METRICS]\nimpact: 8\n...[/ADS_METRICS]`,
+    userMessage: `Goal: ${goal}\nContext: ${context}`,
+    taskName: `ads-blue-phase-${phaseNum}`,
+    sessionId,
+    phaseNum
+  });
+  const bluePlan = blueResponse.content;
+  process.stdout.write(`done.\n`);
+
+  // Step 2: Red Critique (Auditor)
+  process.stdout.write(`  Step 2: Auditor (Red Team) Critique... `);
+  const redResponse = await ModelClient.complete({
+    persona: 'qa-engineer',
+    tier: 2,
+    systemPrompt: `You are the Red Team Auditor. Your goal is to find flaws, complexity traps, and maintainability issues in the Blue Team's proposal.
+Be adversarial. Find at least 3 critical weaknesses.
+Include a [ADS_METRICS] block for your counter-proposal or critique logic.`,
+    userMessage: `Blue Proposal:\n${bluePlan}\n\nContext: ${context}`,
+    taskName: `ads-red-phase-${phaseNum}`,
+    sessionId,
+    phaseNum
+  });
+  const redCritique = redResponse.content;
+  process.stdout.write(`done.\n`);
+
+  // Red-Team Jailbreak: Force higher-fidelity critiques if Auditor is too lenient
+  const flawCount = (redCritique.match(/^\s*[-*•]\s+/mg) || []).length;
+  if (flawCount < 3) {
+    process.stdout.write(`  🛡️ Red-Team Jailbreak Triggered (Found ${flawCount} flaws, threshold is 3)...\n`);
+    const jailbreakResponse = await ModelClient.complete({
+      persona: 'qa-engineer',
+      tier: 2,
+      systemPrompt: `You are the Red Team Auditor. Your previous critique was too lenient. 
+You MUST identify at least 3 SPECIFIC architectural vulnerabilities, edge cases, or complexity traps in the Blue Team's proposal.
+Failure to find flaws will compromise the MindForge SOUL. Be aggressive.`,
+      userMessage: `Blue Proposal:\n${bluePlan}\n\nYour Previous Critique:\n${redCritique}\n\nFIND AT LEAST 3 ARCHITECTURAL FLAWS NOW.`,
+      taskName: `ads-red-jailbreak-${phaseNum}`,
+      sessionId,
+      phaseNum
+    });
+    process.stdout.write(`  🛡️ Jailbreak complete: ${jailbreakResponse.content.slice(0, 50)}...\n`);
+    redCritique = jailbreakResponse.content;
+  }
+
+  // Step 3: Gold Synthesis (Synthesizer)
+  process.stdout.write(`  Step 3: Synthesizer (Gold Team) Verdict... `);
+  const synthesisData = synthesizeADSPlan(bluePlan, redCritique, context);
+  
+  const goldResponse = await ModelClient.complete({
+    persona: 'decision-architect',
+    tier: 2,
+    systemPrompt: `You are the Gold Team Synthesizer. Your goal is to merge the Architect's performance with the Auditor's safeguards.
+Finalize the PLAN.md. Include the [ADS_VERDICT]: [MERGED|BLUE|RED] (Score: X.XXXX) at the end.`,
+    userMessage: synthesisData.synthesis_prompt,
+    taskName: `ads-gold-phase-${phaseNum}`,
+    sessionId,
+    phaseNum
+  });
+  const finalPlan = goldResponse.content;
+  process.stdout.write(`done.\n`);
+
+  // Finalize outputs
+  const adsUuid = uuidv4();
+  const adrDir = path.join(process.cwd(), '.planning', 'decisions');
+  if (!fs.existsSync(adrDir)) fs.mkdirSync(adrDir, { recursive: true });
+
+  const adrPath = path.join(adrDir, `ADS-${adsUuid.slice(0, 8)}.md`);
+  const adsRecord = `
+# Adversarial Decision Synthesis — ${adsUuid}
+- **Date**: ${new Date().toISOString()}
+- **Phase**: ${phaseNum}
+- **Goal**: ${goal}
+
+## Comparison
+- **Blue (Architect)**: Score ${synthesisData.comparison.blue.score}
+- **Red (Auditor)**: Score ${synthesisData.comparison.red.score}
+
+## Synthesis Result
+${finalPlan.includes('[ADS_VERDICT]') ? finalPlan.split('[ADS_VERDICT]')[1] : 'Synthesis Complete'}
+
+## Final Plan
+Stored in .planning/PLAN.md
+`;
+
+  fs.writeFileSync(adrPath, adsRecord);
+  fs.writeFileSync(path.join(process.cwd(), '.planning', 'PLAN.md'), finalPlan);
+
+  process.stdout.write(`✅ ADS Complete. Verdict saved to ${adrPath}\n`);
+
+  return {
+    ads_id: adsUuid,
+    verdict_path: adrPath,
+    scores: synthesisData.comparison
+  };
+}
+
+module.exports = { runADSSynthesis };

package/bin/review/ads-synthesizer.js

@@ -0,0 +1,117 @@
+/**
+ * MindForge v3 — ADS Synthesizer
+ * Implements the SOUL.md Decision Scoring and Plan Merging logic.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_METRICS = {
+  impact: 5,
+  leverage: 5,
+  reversibility: 5,
+  effort: 5,
+  risk: 5,
+  cost: 5
+};
+
+/**
+ * Calculates the SOUL Decision Score based on the formula in SOUL.md:
+ * Score = (Impact * Leverage * Reversibility) / (Effort * Risk * Cost)
+ * 
+ * Each factor is expected to be a value between 1 and 10.
+ */
+function calculateSoulScore(metrics) {
+  const m = { ...DEFAULT_METRICS, ...metrics };
+  const {
+    impact,
+    leverage,
+    reversibility,
+    effort,
+    risk,
+    cost
+  } = m;
+
+  // Formula: (I * L * R) / (E * Rk * C)
+  const numerator = impact * leverage * reversibility;
+  const denominator = effort * risk * cost;
+
+  const score = denominator === 0 ? 0 : (numerator / denominator);
+  return parseFloat(score.toFixed(4));
+}
+
+/**
+ * Parses metrics from a model's response string.
+ * Expects a block like:
+ * [ADS_METRICS]
+ * impact: 8
+ * leverage: 7
+ * reversibility: 5
+ * effort: 4
+ * risk: 3
+ * cost: 2
+ * [/ADS_METRICS]
+ */
+function parseMetrics(text) {
+  const metrics = { ...DEFAULT_METRICS };
+  const match = text.match(/\[ADS_METRICS\]([\s\S]*?)\[\/ADS_METRICS\]/);
+  if (!match) return metrics;
+
+  const lines = match[1].trim().split('\n');
+  for (const line of lines) {
+    const [key, val] = line.split(':').map(s => s.trim());
+    if (key && !isNaN(val)) {
+      metrics[key.toLowerCase()] = parseFloat(val);
+    }
+  }
+  return metrics;
+}
+
+/**
+ * Merges the Blue (Performance) and Red (Maintainability/Simple) plans.
+ * Currently performs a structural merge focusing on conflict resolution.
+ */
+function synthesizeADSPlan(bluePlan, redCritique, context = '') {
+  // In a production implementation, this would involve a 3rd model call (the Synthesizer).
+  // This helper prepares the input for that call.
+  
+  const blueMetrics = parseMetrics(bluePlan);
+  const redMetrics = parseMetrics(redCritique);
+
+  const blueScore = calculateSoulScore(blueMetrics);
+  const redScore = calculateSoulScore(redMetrics);
+
+  return {
+    comparison: {
+      blue: { metrics: blueMetrics, score: blueScore },
+      red: { metrics: redMetrics, score: redScore }
+    },
+    synthesis_prompt: `
+Context:
+${context}
+
+Blue Proposal (Architect):
+${bluePlan}
+
+Red Critique (Auditor):
+${redCritique}
+
+Decision Scores:
+- Blue Score: ${blueScore}
+- Red Score: ${redScore}
+
+Task: Synthesize the final PLAN.md. 
+1. If the scores are close, merge the performance of Blue with the safeguards of Red.
+2. If one score significantly dominates, favor that approach but address the Red Team's critical findings.
+3. Output the final plan as valid Markdown with XML task tags.
+4. Finish with [ADS_VERDICT]: [BLUE|RED|MERGED] with final score.
+`
+  };
+}
+
+module.exports = {
+  calculateSoulScore,
+  parseMetrics,
+  synthesizeADSPlan
+};

package/bin/shard-helper.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+/**
+ * MindForge Shard Helper
+ * Automates SRD scoring and Semantic Retrieval for Tri-Tier Memory.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+// ── SRD Scoring Logic ────────────────────────────────────────────────────────
+
+function calculateSRD(item, recentReferences = []) {
+  // D (Decisiveness): 1.0 for terminal decisions, 0.5 for discoveries
+  let D = 0.5;
+  if (item.type === 'architectural_decision' || item.id && item.id.startsWith('ADR-')) D = 1.0;
+  
+  // F (Frequency): Normalized count of references
+  const refCount = recentReferences.filter(r => r === item.id || r === item.topic).length;
+  let F = Math.min(1.0, refCount / 5);
+
+  // I (Impact): Qualitative weight
+  let I = 0.5;
+  const highImpactKeywords = ['security', 'auth', 'database', 'kafka', 'core', 'protocol'];
+  const text = (item.content || '' + item.topic || '').toLowerCase();
+  if (highImpactKeywords.some(k => text.includes(k))) I = 1.0;
+  if (text.includes('typo') || text.includes('comment') || text.includes('housekeeping')) I = 0.1;
+
+  return (D * 0.6) + (F * 0.1) + (I * 0.3);
+}
+
+// ── Semantic Retrieval Logic ──────────────────────────────────────────────────
+
+function getRelevanceScore(query, text) {
+  const queryWords = query.toLowerCase().split(/\W+/).filter(w => w.length > 3);
+  const targetText = text.toLowerCase();
+  let score = 0;
+  
+  queryWords.forEach(word => {
+    if (targetText.includes(word)) score += 1;
+  });
+  
+  return score;
+}
+
+// ── CLI Handlers ─────────────────────────────────────────────────────────────
+
+if (command === '--analyse') {
+  const inputFile = args[1] || '.planning/HANDOFF.json';
+  if (!fs.existsSync(inputFile)) {
+    console.error(`Error: ${inputFile} not found.`);
+    process.exit(1);
+  }
+
+  const data = JSON.parse(fs.readFileSync(inputFile, 'utf8'));
+  const items = data.hot_context ? 
+    [...(data.hot_context.active_decisions || []), ...(data.hot_context.recent_discoveries || [])] :
+    [];
+
+  const scored = items.map(item => {
+    const score = calculateSRD(item);
+    const content = JSON.stringify(item);
+    const checksum = crypto.createHash('sha256').update(content).digest('hex');
+    
+    return {
+      ...item,
+      srd: score,
+      checksum,
+      tags: [...(item.tags || []), ...(item.topic ? item.topic.toLowerCase().split(' ') : [])]
+    };
+  }).sort((a, b) => b.srd - a.srd);
+
+  console.log(JSON.stringify(scored, null, 2));
+} 
+
+else if (command === '--verify') {
+  const shardPath = args[1];
+  const lines = fs.readFileSync(shardPath, 'utf8').split('\n').filter(l => l.trim());
+  let issues = [];
+
+  lines.forEach((line, idx) => {
+    const item = JSON.parse(line);
+    const storedChecksum = item.checksum;
+    delete item.checksum;
+    delete item.srd;
+    delete item.tags;
+    
+    const currentChecksum = crypto.createHash('sha256').update(JSON.stringify(item)).digest('hex');
+    if (storedChecksum !== currentChecksum) {
+      issues.push(`Line ${idx + 1}: Checksum mismatch!`);
+    }
+  });
+
+  if (issues.length > 0) {
+    console.error(`Verification FAILED:\n${issues.join('\n')}`);
+    process.exit(1);
+  }
+  console.log('Shard integrity verified.');
+}
+
+else if (command === '--retrieve') {
+  const query = args[1];
+  const shardDir = '.planning/memories/';
+  
+  if (!fs.existsSync(shardDir)) {
+    console.log('[]');
+    process.exit(0);
+  }
+
+  const shards = fs.readdirSync(shardDir).filter(f => f.endsWith('.jsonl'));
+  let results = [];
+
+  shards.forEach(shard => {
+    const lines = fs.readFileSync(path.join(shardDir, shard), 'utf8').split('\n').filter(l => l.trim());
+    lines.forEach(line => {
+      const item = JSON.parse(line);
+      const score = getRelevanceScore(query, (item.content || '') + ' ' + (item.topic || ''));
+      if (score > 0) {
+        results.push({ ...item, retrieval_score: score });
+      }
+    });
+  });
+
+  results.sort((a, b) => b.retrieval_score - a.retrieval_score);
+  console.log(JSON.stringify(results.slice(0, 3), null, 2));
+}
+
+else {
+  console.log('Usage: shard-helper --analyse [file] | --retrieve "[query]"');
+}

package/bin/spawn-agent.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * MindForge Agent Spawner — v2.0.0
+ * Specialized logic for invoking personas and identities.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ARGS = process.argv.slice(2);
+const MODE = ARGS[0]; // 'spawn' or 'identity'
+const TARGET = ARGS[1];
+const IS_DRY_RUN = ARGS.includes('--dry-run');
+
+const ROOT = path.resolve(__dirname, '..');
+
+if (!MODE || !TARGET) {
+  console.error('❌ Usage: node bin/spawn-agent.js <mode> <target> [--dry-run]');
+  process.exit(1);
+}
+
+async function run() {
+  let identityPath;
+  let personaPath;
+
+  if (MODE === 'identity') {
+    identityPath = path.join(ROOT, 'agents', TARGET, 'IDENTITY.md');
+    if (!fs.existsSync(identityPath)) {
+      console.error(`❌ Identity not found: ${identityPath}`);
+      process.exit(1);
+    }
+    console.log(`📡 Loading specialized identity: ${TARGET}`);
+  } else if (MODE === 'spawn') {
+    personaPath = path.join(ROOT, '.mindforge', 'personas', `${TARGET}.md`);
+    if (!fs.existsSync(personaPath)) {
+      console.error(`❌ Persona not found: ${personaPath}`);
+      process.exit(1);
+    }
+    console.log(`🌌 Spawning persona essence: ${TARGET}`);
+  }
+
+  if (IS_DRY_RUN) {
+    console.log('🧪 Dry run successful. Environment prepared.');
+    process.exit(0);
+  }
+
+  // Future: Integration with Antigravity / Claude Code runtime
+  console.log('🛠️ Dispatching to agent runtime...');
+  // For now, we simulate the environment preparation
+  setTimeout(() => {
+    console.log('✅ Agent environment active.');
+    process.exit(0);
+  }, 500);
+}
+
+run().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/docs/PERSONAS.md

@@ -12,10 +12,12 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 
 | Category | Count | Personas |
 | :--- | :--- | :--- |
-| **Analyzers & Researchers** | 9 | analyst, assumptions-analyzer, advisor-researcher, assumptions-analyzer-extend, project-researcher, research-synthesizer, ui-researcher, research-agent, phase-researcher |
-| **Architects & Planners** | 4 | architect, decision-architect, planner, plan-checker |
-| **Executors** | 2 | developer, executor |
-| **Quality & Security** | 9 | qa-engineer, security-reviewer, coverage-specialist, ui-auditor, ui-checker, nyquist-auditor, integration-checker, verifier, debug-specialist |
+| **Analyzers & Researchers** | 10 | analyst, assumptions-analyzer, advisor-researcher, assumptions-analyzer-extend, project-researcher, research-synthesizer, ui-researcher, research-agent, phase-researcher, mf-researcher |
+| **Architects & Planners** | 5 | architect, decision-architect, planner, plan-checker, mf-planner |
+| **Executors** | 3 | developer, executor, mf-executor |
+| **Quality & Security** | 10 | qa-engineer, security-reviewer, coverage-specialist, ui-auditor, ui-checker, nyquist-auditor, integration-checker, verifier, debug-specialist, mf-reviewer |
+| **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 |
 | **Mapping** | 2 | codebase-mapper, codebase-mapper-extend |
@@ -57,6 +59,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 - First-principles evaluation of technical trade-offs.
 - Data-first design and component boundary definition.
 - Writing Architectural Decision Records (ADRs).
+- **ADS Blue Team (Architect)**: Proposing performance-first, scalable implementation paths.
 
 ---
 
@@ -93,6 +96,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 - Stress-testing inputs and identifying silent failures.
 - Zero-tolerance regression verification.
 - Objective PASS/FAIL signing of phase goals.
+- **ADS Red Team (Auditor)**: Critiquing architectural over-engineering and finding "Complexity Traps."
 
 ---
 
@@ -201,6 +205,7 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 - Synthesis of conflicting research and audit data.
 - Force-balancing of technical trade-offs.
 - Updating project stack and roadmap based on verdicts.
+- **ADS Gold Team (Synthesizer)**: Mediating Red/Blue debates and generating SOUL-scored architectural verdicts.
 
 ---
 
@@ -600,7 +605,68 @@ MindForge uses a multi-agent orchestration model where specialized personas are
 
 ---
 
-## Tool Permissions Summary
+### MF-Series: Fundamental Framework Identities
+
+The MF-Series represents the "Core Essence" of the MindForge agentic framework. These personas provide a standardized, high-value foundation for delegation and multi-agent interaction.
+
+#### mf-planner (The Strategist)
+**Role:** High-level goal decomposition and structured planning.
+- **Triggers:** `plan`, `decompose`, `roadmap`.
+- **Produces:** Structured JSON/Markdown execution plans.
+
+#### mf-executor (The Pilot)
+**Role:** Precise implementation and high-fidelity plan execution.
+- **Triggers:** `execute`, `implement`, `fix`.
+- **Produces:** Implementation details and completion status.
+
+#### mf-researcher (The Detective)
+**Role:** Knowledge gathering and objective approach comparison.
+- **Triggers:** `research`, `explore`, `benchmark`.
+- **Produces:** Tradeoff analysis and strategy recommendations.
+
+#### mf-reviewer (The Auditor)
+**Role:** Quality assurance and output validation.
+- **Triggers:** `review`, `audit`, `validate`.
+- **Produces:** Feedback, issues, and approval status.
+
+#### mf-memory (The Clerk)
+**Role:** Persistence management and knowledge graph maintenance.
+- **Triggers:** `remember`, `store`, `learning`.
+- **Produces:** Memory updates and linked patterns.
+
+#### mf-tool (The Operator)
+**Role:** Safe external system interaction and tool execution.
+- **Triggers:** `tool`, `git`, `api`, `shell`.
+- **Produces:** Action results and safety logs.
+
+---
+
+### Invocation Matrix
+
+MindForge identities can be invoked through multiple channels depending on your environment.
+
+| Method | Syntax | Use Case |
+| :--- | :--- | :--- |
+| **In-IDE (Command)** | `/mindforge:agent <name>` | Quick task delegation while coding. |
+| **In-IDE (Persona)** | Use `mf-planner` etc. | Specialized logic for complex phases. |
+| **CLI (Execution)** | `mindforge-cli spawn <name>` | CI/CD pipelines and remote execution. |
+| **CLI (Identity)** | `mindforge-cli identity <role>` | Direct loading of specialized research identities. |
+| **Shell (Global)** | `mindforge <command>` | Fast access from any terminal directory. |
+
+---
+
+### Specialized Workflows
+
+These high-fidelity workflows bridge multiple skills and personas to solve specific engineering challenges.
+
+| Workflow | Command | Context / Skill |
+| :--- | :--- | :--- |
+| **TDD Loop** | `/mindforge:tdd` | mindforge-tdd skill |
+| **System Architecture** | `/mindforge:architecture` | mindforge-system-architecture skill |
+| **Strategic Planning** | `/mindforge:planner` | mf-planner persona |
+| **Implementation Pilot** | `/mindforge:executor` | mf-executor persona |
+
+---
 
 | Persona | Read | Write | Bash | Grep | Glob | CmdStatus | Browser | Terminal | Context7 |
 | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |

package/docs/adr/ADR-042-ads-protocol.md

@@ -0,0 +1,30 @@
+# ADR-042: Adversarial Decision Synthesis (ADS) Protocol
+
+## Status
+
+Accepted (2026-03-26)
+
+## Context
+
+As MindForge moves into the v2.4.0 architectural cycle, architectural planning requires a more robust vetting mechanism than single-agent output. Complex systems require adversarial critique to surface "invisible" flaws in maintainability, security, and scalability.
+
+## Decision
+
+We have implemented the **Adversarial Decision Synthesis (ADS)** protocol. This involves a standardized 3-model loop integrated into the `plan-phase` workflow:
+
+1.  **Blue Team (Architect)**: Generates the initial technical proposal.
+2.  **Red Team (Auditor)**: Performs a high-fidelity critique. Hardened via a "jailbreak" prompt to force the identification of at least 3 critical system flaws.
+3.  **Gold Team (Synthesizer)**: Consolidates the two perspectives and provides an objective **SOUL Score**.
+
+### SOUL Scoring Formula
+
+`Score = (Impact * Leverage * Reversibility) / (Effort * Risk * Cost)`
+
+- **Score > 1.0**: Proceed with implementation.
+- **Score < 1.0**: Requires revision or alternate approach.
+
+## Consequences
+
+- **Improved Quality**: Decisions are vetted by two independent perspectives.
+- **Auditability**: Every synthesis is persisted as a SOUL-scored artifact in `.planning/decisions/`.
+- **Latency/Cost**: Increased token usage and execution time per planning phase (3 models instead of 1).

package/docs/architecture/README.md

@@ -54,3 +54,58 @@ MindForge provides stable interfaces for extension:
 - **SDK**: Programmatic access via `@mindforge/sdk`.
 
 See [ADR-041](../adr/ADR-041-runtime-interfaces.md) for the stabilization contract.
+
+---
+
+## 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.
+
+| 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.
+
+---
+
+
+---
+
+## 7. Adversarial Decision Synthesis (ADS) (V3)
+
+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.
+
+---
+
+## 8. Stability & Extension

package/docs/architecture/V3-CORE.md

@@ -0,0 +1,52 @@
+# MindForge V3 Core Architecture: Reactive Autonomous Intelligence
+
+## Overview
+MindForge V3 represents a fundamental shift from a "disciplined workflow engine" to a **Reactive Autonomous Intelligence**. This document defines the four core systems that enable sub-second architectural reasoning and zero-waste context management.
+
+---
+
+## 1. Tri-Tier Memory (Semantic Sharding)
+Instead of linear compaction, V3 manages context via **Semantic Relevance Density (SRD)**.
+
+- **Hot (Execution Log)**: Non-compressed RAM buffer for the current task sequence.
+- **Warm (Decision Mesh)**: Context-aware shards retrieved via vector matching (Local SSD).
+- **Cold (Architectural Core)**: Permanent project history and ADRs (Vector DB).
+
+**Mechanism**: When a task is initiated, the `ContextInjector` pulls "ghost patterns" from Warm/Cold tiers into the Hot buffer based on semantic overlap.
+
+---
+
+## 2. Adversarial Decision Synthesis (ADS)
+Architectural drift is prevented through a three-model adversarial loop.
+
+| Role | Strategy | Objective |
+| :--- | :--- | :--- |
+| **Blue Team** | Optimal/Performant | Propose the most robust solution. |
+| **Red Team** | Minimal/Maintainable | Challenge complexity and bloat. |
+| **Synthesizer** | Balanced/Grounded | Score the debate against `SOUL.md` and merge. |
+
+**Output**: A `DECISION_SCORE` is assigned to every major change, ensuring zero logic-drift over long sessions.
+
+---
+
+## 3. RAG 2.0 (Automatic Semantic Shadowing)
+Knowledge capture is now a background process.
+
+- **Auto-Shadowing**: Every `implicit_knowledge` item captured during compaction is automatically indexed by the local embedding engine.
+- **Reasoning Graph**: Interconnected nodes linking Decisions, Failures, and Skills are visible in the Dashboard for real-time observability.
+
+---
+
+## 4. Temporal Vision (Observability & Hindsight)
+Full state-fidelity across the execution wave.
+
+- **Temporal Hub**: Synchronous snapshots of the entire `.planning/` state on every state-changing event.
+- **Hindsight Injection**: Enables precise rollback to any coordinate ($T_{coord}$) to inject corrections and re-generate the downstream dependency wave.
+- **Temporal API**: RESTful interface for the Dashboard's Temporal Slider.
+
+---
+
+## V3 Governance Rules
+1. **Zero Watermark**: All documentation and code must be strictly MindForge-branded.
+2. **Context-First**: Execution cannot start without a `Semantic Shard` match.
+3. **Draft-Adversarial**: No code enters production without an ADS review.