mindforge-cc 2.3.5 → 3.0.0

package/.agent/workflows/mindforge:executor.md

@@ -0,0 +1,18 @@
+---
+description: Invoke the Implementation Pilot persona (mf-executor)
+---
+# 🛠️ /mindforge:executor
+
+## Objective
+Adopt the **Implementation Pilot** persona for high-fidelity plan execution and atomic commit discipline.
+
+---
+
+## Execution
+// turbo
+1. Execute the MindForge CLI to spawn the executor essence:
+   ```bash
+   node bin/mindforge-cli.js spawn mf-executor
+   ```
+
+2. The AI will adopt the **Self-Correction & Polish** pattern and await your execution tasks.

package/.agent/workflows/mindforge:identity.md

@@ -0,0 +1,18 @@
+---
+description: Invoke a specialized agent identity from the /agents/ workspace
+---
+# 🆔 /mindforge:identity
+
+## Objective
+Directly load a specialized research identity (e.g., Planner, Executor) from the `/agents/` workspace.
+
+---
+
+## Execution
+// turbo
+1. Execute the MindForge CLI to load the specialized identity:
+   ```bash
+   node bin/mindforge-cli.js identity [role]
+   ```
+
+2. The AI will adopt the deep, research-backed cognitive model defined in `agents/[role]/IDENTITY.md`.

package/.agent/workflows/mindforge:memory.md

@@ -0,0 +1,18 @@
+---
+description: Invoke the Semantic Clerk persona (mf-memory)
+---
+# 📓 /mindforge:memory
+
+## Objective
+Adopt the **Semantic Clerk** persona to manage long-term project memory and knowledge graph maintenance.
+
+---
+
+## Execution
+// turbo
+1. Execute the MindForge CLI to spawn the memory essence:
+   ```bash
+   node bin/mindforge-cli.js spawn mf-memory
+   ```
+
+2. The AI will adopt the **Memory Indexing & Pattern Recall** pattern and await your persistence tasks.

package/.agent/workflows/mindforge:planner.md

@@ -0,0 +1,18 @@
+---
+description: Invoke the Strategic Planner persona (mf-planner)
+---
+# 🧠 /mindforge:planner
+
+## Objective
+Adopt the **Strategic Planner** persona to decompose high-level goals into structured, executable plans.
+
+---
+
+## Execution
+// turbo
+1. Execute the MindForge CLI to spawn the planner essence:
+   ```bash
+   node bin/mindforge-cli.js spawn mf-planner
+   ```
+
+2. The AI will adopt the **Goal-Backward Decomposition** pattern and await your objective.

package/.agent/workflows/mindforge:researcher.md

@@ -0,0 +1,18 @@
+---
+description: Invoke the Knowledge Detective persona (mf-researcher)
+---
+# 🔍 /mindforge:researcher
+
+## Objective
+Adopt the **Knowledge Detective** persona for grounded research and recursive browsing.
+
+---
+
+## Execution
+// turbo
+1. Execute the MindForge CLI to spawn the researcher essence:
+   ```bash
+   node bin/mindforge-cli.js spawn mf-researcher
+   ```
+
+2. The AI will adopt the **Deep Context Synthesis** pattern and await your research objective.

package/.agent/workflows/mindforge:reviewer.md

@@ -0,0 +1,18 @@
+---
+description: Invoke the Quality Auditor persona (mf-reviewer)
+---
+# 🛡️ /mindforge:reviewer
+
+## Objective
+Adopt the **Quality Auditor** persona for adversarial review and 6-pillar logic auditing.
+
+---
+
+## Execution
+// turbo
+1. Execute the MindForge CLI to spawn the reviewer essence:
+   ```bash
+   node bin/mindforge-cli.js spawn mf-reviewer
+   ```
+
+2. The AI will adopt the **Adversarial Logic Verification** pattern and await your review target.

package/.agent/workflows/mindforge:tdd.md

@@ -0,0 +1,41 @@
+---
+description: Strict TDD workflow (Red-Green-Refactor).
+---
+# 🧪 /mindforge:tdd
+
+<instruction>
+Execute a strict Test-Driven Development (TDD) loop using the Red-Green-Refactor pattern with an emphasis on "Tracer Bullets" (vertical slices).
+</instruction>
+
+<context>
+Follow the specialized MindForge TDD standards defined in [.agent/skills/mindforge-tdd/SKILL.md](.agent/skills/mindforge-tdd/SKILL.md).
+</context>
+
+<rules>
+- **No Implementation without Test**: Do not write production code unless it is to make a failing test pass.
+- **Minimalist Green**: Write the absolute minimum code required to satisfy the test.
+- **Refactor Ruthlessly**: Clean up after every green state while keeping tests passing.
+- **Vertical Slicing**: Prioritize end-to-end functionality over horizontal layers.
+</rules>
+
+<process>
+1.  **RED**: Define a single behavioral requirement and write a failing test.
+2.  **GREEN**: Implement the simplest code to fix the failure.
+3.  **REFACTOR**: Optimize the code and tests for readability and maintainability.
+4.  **VERIFY**: Ensure all tests in the suite pass before proceeding.
+</process>
+
+<supporting_documents>
+- [Deep Modules](.agent/skills/mindforge-tdd/deep-modules.md)
+- [Interface Design](.agent/skills/mindforge-tdd/interface-design.md)
+- [Mocking Strategies](.agent/skills/mindforge-tdd/mocking.md)
+- [Refactoring Guide](.agent/skills/mindforge-tdd/refactoring.md)
+- [Test Infrastructure](.agent/skills/mindforge-tdd/tests.md)
+</supporting_documents>
+
+<output_format>
+Summarize each TDD cycle with:
+- `[RED]`: The test added.
+- `[GREEN]`: The minimal change made.
+- `[REFACTOR]`: Specific improvements made.
+</output_format>

package/.agent/workflows/mindforge:tool.md

@@ -0,0 +1,18 @@
+---
+description: Invoke the System Operator persona (mf-tool)
+---
+# 🔌 /mindforge:tool
+
+## Objective
+Adopt the **System Operator** persona for safe external system interaction and tool execution logic.
+
+---
+
+## Execution
+// turbo
+1. Execute the MindForge CLI to spawn the tool essence:
+   ```bash
+   node bin/mindforge-cli.js spawn mf-tool
+   ```
+
+2. The AI will adopt the **Least-Privilege Gating** pattern and await your tool-use requests.

package/.mindforge/engine/ads-protocol.md

@@ -0,0 +1,54 @@
+# MindForge Engine — Adversarial Decision Synthesis (ADS) Protocol
+
+## Purpose
+Evolve the standard single-agent planning model into a high-fidelity Red-Team/Blue-Team architectural synthesis. This protocol ensures all major decisions are stress-tested for maintainability, security, and scalability before execution begins.
+
+## Core Roles
+
+### 1. The Architect (Blue Team — Performance & Complexity)
+- **Persona**: `mindforge-architect` or `mf-planner`
+- **Objective**: Propose the most technically superior, performant, and feature-complete solution.
+- **Bias**: "We should build for scale and future-proof the system."
+
+### 2. The Auditor (Red Team — Simplicity & Maintainability)
+- **Persona**: `mindforge-qa-engineer` or `mindforge-security-reviewer`
+- **Objective**: Find logic gaps, security flaws, and architectural "over-engineering".
+- **Bias**: "Do we really need this complexity? How will this break tomorrow?"
+
+### 3. The Synthesizer (Gold Team — Decision Merge)
+- **Persona**: `mindforge-decision-architect`
+- **Objective**: Mediate the debate, score proposals using `SOUL.md` metrics, and merge into a final `PLAN.md`.
+- **Bias**: "Objective leverage. Minimal risk. Maximum impact."
+
+## Synthesis Loop — Execution Order
+
+### Step 1: Blue Proposal (Propose)
+The **Architect** generates a detailed implementation plan (`PLAN-[P]-BLUE.md`).
+- Focus on: Data flow, performance, and API design.
+
+### Step 2: Red Critique (Challenge)
+The **Auditor** reviews the Blue plan and generates a critique (`PLAN-[P]-RED-CRITIQUE.md`).
+- **Pressure Rule**: Red *must* identify at least 3 potential failure modes or "Complexity Traps."
+- Red proposes a "Simpler Alternative" if the Blue plan is deemed over-engineered.
+
+### Step 3: Gold Verdict (Synthesize)
+The **Synthesizer** ingest both plans and the critique. 
+1. Calculates the **SOUL_SCORE** for each approach:
+   `Score = (Impact × Leverage × Reversibility) / (Effort × Risk × Cost)`
+2. Generates the final `PLAN.md` by adopting the best parts of both.
+3. Produces a `DECISION_ADS.md` (ADR) justifying the synthesis.
+
+## Synthesis Tossing (Iterative Loop)
+If the **SOUL_SCORE** difference between approaches is < 0.2, the Synthesizer can trigger one round of "Tossing":
+- Both teams are given the other's feedback and asked to refine their proposal.
+- Total iterations capped at 2 to avoid scope-paralysis.
+
+## Output Structure
+The final result must always move to the standard `.planning/` directory:
+- `.planning/PLAN.md` (Validated & Hardened)
+- `.planning/decisions/ADS-[UUID].md` (The Proof of Synthesis)
+
+## Trigger Conditions
+- Any phase marked "Architectural" in `ROADMAP.md`
+- Manual trigger via `/mindforge:plan-phase --ads`
+- When a `security-reviewer` flags a high-risk change

package/.mindforge/engine/compaction-protocol.md

@@ -63,55 +63,40 @@ workarounds discovered, gotchas found, things that seemed like they would
 work but did not]
 ```
 
-### Step 4 — Write HANDOFF.json
-Overwrite `.planning/HANDOFF.json` with complete current state:
+### Step 4 — Write HANDOFF.json (Hot Context)
+Overwrite `.planning/HANDOFF.json` with the current **Hot** state. This file should only contain high-SRD items required for immediate task resumption.
 
 ```json
 {
-  "schema_version": "1.0.0",
-  "project": "[project name from PROJECT.md]",
+  "schema_version": "2.1.0",
+  "project": "[project name]",
   "phase": [N],
   "plan": [M],
-  "plan_step": "[exact step description — be precise enough to restart from here]",
-  "last_completed_task": {
-    "description": "[task description]",
-    "commit_sha": "[git sha or 'wip-checkpoint']",
-    "verified": true/false
-  },
-  "next_task": "[exact instruction for the next session to execute]",
-  "in_progress": {
-    "file": "[file being modified]",
-    "intent": "[what the modification is trying to achieve]",
-    "completed_steps": ["step 1", "step 2"],
-    "remaining_steps": ["step 3", "step 4"]
+  "plan_step": "[exact step description]",
+  "next_task": "[exact instruction for next session]",
+  "hot_context": {
+    "active_decisions": [],
+    "recent_discoveries": [],
+    "file_offsets": {}
   },
   "blockers": [],
-  "decisions_needed": [],
   "context_refs": [
-    ".planning/PROJECT.md",
     ".planning/STATE.md",
-    ".planning/REQUIREMENTS.md",
-    ".planning/ARCHITECTURE.md",
-    ".planning/phases/[N]/PLAN-[N]-[M].md",
-    "[any other files critical for the next session]"
-  ],
-  "recent_commits": [
-    "[sha1]: [message]",
-    "[sha2]: [message]"
+    ".planning/HANDOFF.json",
+    ".planning/memories/WARM-SHARD-LATEST.jsonl"
   ],
-  "recent_files": [
-    "[most recently touched file 1]",
-    "[most recently touched file 2]",
-    "[most recently touched file 3]",
-    "[most recently touched file 4]",
-    "[most recently touched file 5]"
-  ],
-  "agent_notes": "[anything the agent knows that isn't captured elsewhere]",
-  "_warning": "Never store secrets, tokens, or passwords in this file. It is tracked in git.",
-  "updated_at": "[ISO-8601 timestamp]"
+  "shard_ref": ".planning/memories/WARM-SHARD-N.jsonl",
+  "updated_at": "[ISO-8601]"
 }
 ```
 
+### Step 4.5 — Semantic Sharding (Warm/Cold Context)
+Invoke the [Shard Controller](shard-controller.md) to offload lower-SRD items:
+1. Identify items with SRD < 0.8 (Decisions from earlier in the phase, transient research).
+2. Append these to `.planning/memories/WARM-SHARD-N.jsonl`.
+3. If any item has matured into a Project-wide pattern (SRD > 0.9 + repeated usage), move it to `.mindforge/memory/`.
+4. Ensure `HANDOFF.json` remains under 10KB.
+
 ### Step 5 — Write compaction AUDIT entry
 ```json
 {

package/.mindforge/engine/context-injector.md

@@ -38,6 +38,25 @@ You are a MindForge agent executing a specific task. Read these instructions com
 [Contents of any ADR files referenced in the plan's <context> field]
 [Only the referenced ones]
 
+## Auto-Shadow Context (RAG 2.0)
+[Generated by bin/memory/auto-shadow.js — DO NOT populate manually]
+
+Before building the context package, the injector MUST:
+1. Read the <task> description from the current PLAN file.
+2. Call `auto-shadow.generateShadowContext({ taskDescription, excludeIds })`.
+3. Inject the returned `formatted` string here (if non-empty).
+4. The auto-shadow output is budget-capped at 2KB (~8000 chars).
+5. If the output is empty, omit this section entirely.
+6. Never include entries that are already in the "Relevant decisions" section above.
+
+The Auto-Shadow engine queries:
+- **Embedding similarity**: TF-IDF cosine similarity against the full knowledge base
+- **Graph traversal**: 1-hop and 2-hop neighbors of top embedding matches
+- **Hybrid scoring**: 60% embedding score + 40% graph proximity
+
+Security: The engine automatically filters out entries containing secrets,
+credentials, API keys, or PEM blocks. Deprecated entries are excluded.
+
 ## Active skills
 [Contents of any SKILL.md files listed in the plan's <context> field]
 [Only the listed ones]
@@ -108,6 +127,13 @@ Before injecting context to a subagent:
    c. If still > 30,000 after summarisation: warn the user and ask to proceed
 3. Never silently inject oversized context — the budget exists for a reason.
 
+## Semantic Warm Retrieval (New)
+To maximize subagent fidelity without bloat, perform proactive retrieval from shards:
+1. **Query**: The `next_task` description.
+2. **Search**: Scan `.planning/memories/WARM-SHARD-N.jsonl` for semantic keywords (e.g., "auth", "database", "Kafka").
+3. **Inject**: Top 3 most relevant items into a new section: `## Sharded Context (Warm)`.
+4. **Scoring**: Use `bin/shard-helper.js --retrieve "[query]"` for automated matching.
+
 ## Subagent completion protocol
 
 After the subagent completes, the orchestrator must receive:

package/.mindforge/engine/knowledge-graph-protocol.md

@@ -0,0 +1,125 @@
+# MindForge Engine — Knowledge Graph Protocol (RAG 2.0)
+
+## Purpose
+
+Govern the Local-First Knowledge Graph's integrity, security, and performance.
+This protocol defines the rules for graph operations, auto-shadowing, and
+life-cycle management of nodes and edges.
+
+## Graph Integrity Rules
+
+### Node Rules
+
+- Every node MUST have a valid `id`, `type`, `topic`, and `content`.
+- Deprecated nodes are excluded from all queries and traversals.
+- Orphan nodes (no edges) are flagged in `graphStats()` but NOT auto-pruned.
+- Orphan pruning only runs on `/mindforge:complete-milestone`.
+
+### Edge Rules
+
+- Every edge MUST have a valid `sourceId`, `targetId`, and `type`.
+- Self-referencing edges (sourceId === targetId) are rejected.
+- Duplicate edges (same source, target, type) are prevented at creation time.
+- All edge records include a SHA-256 integrity checksum.
+- Edge writes are append-only — never mutate-in-place.
+
+### Cycle Prevention
+
+- `CAUSED_BY` and `SUPERSEDES` edges form DAGs (Directed Acyclic Graphs).
+- Cycle detection runs via DFS before any `CAUSED_BY` or `SUPERSEDES` edge creation.
+- If a cycle is detected: the edge creation is rejected and logged.
+- `RELATED_TO` and `INFORMS` edges are allowed to be cyclical (they are undirected semantics).
+
+## Edge Type Semantics
+
+| Type | Direction | Meaning | Auto-Created |
+|:---|:---|:---|:---|
+| `RELATED_TO` | Bidirectional | Semantic similarity ≥ 0.65 | Yes |
+| `CAUSED_BY` | Source → Target | Bug pattern caused by root cause | Yes (capture) |
+| `SUPERSEDES` | New → Old | New decision replaces old decision | Manual only |
+| `DEPENDS_ON` | Dependent → Dependency | Pattern requires another pattern | Manual only |
+| `INFORMS` | Decision → Knowledge | Decision informed by domain knowledge | Yes (capture) |
+| `CONTRADICTS` | Bidirectional | Conflicting knowledge entries | Manual only |
+
+## Auto-Shadow Protocol
+
+### Trigger Conditions
+
+Auto-Shadow MUST be invoked:
+
+1. Before every subagent spawn (via context-injector)
+2. At session boot (via session-memory-loader, after hot context load)
+3. On explicit `/mindforge:remember --shadow` calls
+
+### Budget Constraints
+
+- Maximum shadow section size: **2KB** (~8000 characters)
+- Maximum shadow items: **5 entries**
+- Minimum combined score: **0.35** (below this, entry is excluded)
+- Entries already in Hot/Warm context are excluded (no duplication)
+
+### Security Guards
+
+Auto-Shadow MUST NEVER include:
+
+- Entries containing passwords, API keys, or credentials
+- Entries matching patterns: `/[a-z0-9]{32,}/`, `/-----BEGIN/`, `/sk_[a-z]+_/`
+- Entries with `type: 'secret'` or tags including `secret` or `credential`
+- Deprecated entries
+
+### Contradiction Handling
+
+- If two shadow items have a `CONTRADICTS` edge between them:
+  - Both items are included but flagged with ⚠️ prefix
+  - The higher-confidence entry is displayed first
+  - The agent is instructed: "These entries may conflict — verify with user"
+
+## Edge Weight Lifecycle
+
+### Reinforcement
+
+- Traversal: +0.1 weight (capped at 2.0)
+- Each reinforcement updates `last_traversed` and increments `traversal_count`
+- When a node is reinforced (knowledge-store), its top 3 edges are also reinforced
+
+### Decay
+
+- Edges not traversed in 30 days lose 10% weight per decay cycle
+- Edges that decay to weight ≤ 0.1 are automatically deprecated
+- Decay runs on `/mindforge:complete-milestone` or explicit `/mindforge:remember --gc`
+
+### Pruning
+
+- Deprecated edges are retained in the JSONL for audit trail
+- Graph compaction (removing deprecated entries from the file) runs only on explicit request
+- Orphan nodes are reported but never auto-deleted
+
+## Embedding Cache
+
+- Cache path: `.mindforge/memory/embeddings.json`
+- Cache is rebuilt when knowledge-base.jsonl changes (detected by entry count mismatch)
+- Cache format includes `schema_version` for forward compatibility
+- Corrupted cache is silently rebuilt — never crash on cache errors
+
+## Performance Guarantees
+
+| Operation | Target | Measured at |
+|:---|:---|:---|
+| Full embedding rebuild | < 200ms | 1K entries |
+| Single cosine similarity | < 1ms | Any |
+| Auto-edge inference | < 100ms | 1K entries |
+| Graph traversal (2-hop) | < 50ms | 500 edges |
+| Auto-shadow generation | < 500ms | 1K entries + 500 edges |
+
+## AUDIT Integration
+
+All graph operations emit AUDIT entries:
+
+```json
+{
+  "event": "knowledge_graph_operation",
+  "operation": "add_edge | deprecate_edge | auto_shadow | decay | cycle_detected",
+  "details": { ... },
+  "timestamp": "<ISO-8601>"
+}
+```

package/.mindforge/engine/shard-controller.md

@@ -0,0 +1,53 @@
+# MindForge Engine — Semantic Shard Controller
+
+## Purpose
+Manage the tiered storage of session context items to maintain high reasoning performance while minimizing token waste.
+
+## 1. The Tri-Tier Memory Model
+
+| Tier | Storage Location | Retention Scope | Content Type |
+| :--- | :--- | :--- | :--- |
+| **Hot** | `HANDOFF.json` | 1-2 Sessions | Active tasks, current file offsets, uncommitted intent. |
+| **Warm** | `.planning/memories/WARM-SHARD-N.jsonl` | Phase/Milestone | Decisions with rationale, discoveries, implicit quirks. |
+| **Cold** | `.mindforge/memory/*.jsonl` | Project Life | Architecture patterns, global team preferences, recurring bugs. |
+
+## 2. Semantic Relevance Density (SRD) Scoring
+
+Every context item (Decision, Discovery, Task Result) is scored before compaction using the following formula:
+
+**SRD = (D * 0.6) + (F * 0.1) + (I * 0.3)**
+
+- **D (Decisiveness)**: 1.0 for terminal decisions (ADRs), 0.5 for transient discoveries.
+- **F (Frequency)**: Count of references in the last 10 tool calls (normalized 0-1).
+- **I (Impact)**: 1.0 for security/core-logic, 0.5 for UI/Docs, 0.1 for housekeeping.
+
+### Tier Routing Gates
+- **SRD > 0.8**: Tier 1 (Hot) -> Retain in `HANDOFF.json`.
+- **0.4 <= SRD <= 0.8**: Tier 2 (Warm) -> Move to `WARM-SHARD-N.jsonl`.
+- **SRD < 0.4**: Tier 3 (Cold/Drop) -> Archive to `.mindforge/memory` or drop if redundant.
+
+## 3. Shard Management Logic
+
+### On Compaction Trigger (70% Context)
+1. Invoke `bin/shard-helper.js --analyse` to generate SRD scores.
+2. Filter items by SRD.
+3. Append Warm items to `.planning/memories/WARM-SHARD-N.jsonl`.
+4. Update `HANDOFF.json` with only the Hot items.
+5. Record `sharding_completed` in `AUDIT.jsonl`.
+
+### On Session Restart
+1. Load `HANDOFF.json`.
+2. Locate `WARM-SHARD-N.jsonl` for the current phase.
+3. Perform **Semantic Retrieval**: Load top 5 most relevant Warm items based on the `next_task` description.
+4. Load top 3 most relevant Cold items from the Knowledge Graph.
+
+## 4. Governance & Constraints
+- **Security First**: Never shard secrets or credentials (enforced by Gate 3).
+- **Deduplication**: Before appending to a shard, check for identical `topic` or `id` to avoid context cycles.
+- **Pruning**: Warm shards are archived to Cold storage upon Phase Completion.
+
+## 5. Beast Mode — Enterprise Hardening
+- **Temporal Integrity**: Every shard entry must contain a `sha256` checksum. `bin/shard-helper.js --verify` ensures zero corruption.
+- **Semantic Indexing**: Shards are tagged automatically during compaction for O(1) keyword retrieval.
+- **Hindsight Injection**: If a "Warm" decision is corrected in a later session, the shard is updated with a `superseded_by` pointer.
+- **Atomic Writes**: Shard appends are followed by a `fsync` to ensure durability.

package/.mindforge/engine/temporal-protocol.md

@@ -0,0 +1,40 @@
+# Temporal Vision & Hindsight Protocol (v3.0.0)
+
+## Overview
+Temporal Vision enables high-fidelity "Time-Travel Debugging" by snapshotting the `.planning/` directory at every significant audit point. Hindsight Injection allows agents to learn from past failures by rolling back state and re-executing waves with injected corrections.
+
+## Snapshot Rules
+1. **Triggering**: Snapshots MUST be triggered on any `state-changing` audit event:
+   - `auto_mode_started`
+   - `phase_planned`
+   - `task_completed`
+   - `hindsight_injected`
+2. **Persistence**: Snapshots are stored in `.planning/history/[audit_id]/`.
+3. **Retention**: The system retains snapshots for the current milestone. Completed milestones should be archived or purged using `/mindforge:temporal --cleanup`.
+
+## Hindsight Injection Protocol
+Hindsight Injection is a powerful tool and must be used according to these safety rules:
+
+### 1. Identify the Failure Coordinate ($T_n$)
+- Use the Dashboard Temporal Slider to find the exact audit entry where the "architectural drift" or "logic failure" occurred.
+
+### 2. Inject the Correction
+- The correction must be a concise "Steering Instruction" (e.g., "The database schema should use UUID instead of INT").
+- The system will:
+  - Rollback `.planning/` to $T_n$.
+  - Append the `hindsight_injected` event.
+  - Set state to `awaiting_regeneration`.
+
+### 3. Verification
+- After injection, the `AutoRunner` will re-trigger the wave. 
+- The agent must verify that the new execution path resolves the original failure.
+
+## Security Controls
+- **Integrity**: Each snapshot includes a `SNAPSHOT-META.json` with a timestamp and file list.
+- **Local-Only**: Rollback APIs are restricted to 127.0.0.1 ( localhost) to prevent remote state manipulation.
+- **Atomic Operations**: History restoration uses synchronous file copies to prevent partial state corruption.
+
+## Common Operations
+- `GET /api/temporal/history`: View the timeline.
+- `POST /api/temporal/inject`: Perform hindsight repair.
+- `/mindforge:temporal --status`: Check history size and snapshot count.

package/.mindforge/personas/mf-executor.md

@@ -0,0 +1,40 @@
+---
+name: mf-executor
+description: Implementation specialist focused on high-fidelity execution of provided plans and code completion.
+tools: Read, Write, Bash, multi_replace_file_content
+color: orange
+---
+
+<role>
+You are the **MF-Executor**. You implement assigned tasks with precision, following the orchestrator's Source of Truth.
+</role>
+
+<responsibilities>
+- Implement code changes accurately based on the planner's source
+- Follow provided architectural patterns and constraints
+- Provide detailed implementation notes and status reports
+- Ensure all changes are verified and functional
+</responsibilities>
+
+<process>
+1. **Task Loading**: Internalize the specifics of the current plan.
+2. **Context Retrieval**: Read all relevant files and documentation.
+3. **High-Fidelity Implementation**: Apply changes exactly as planned.
+</process>
+
+<rules>
+- Do not deviate from the plan without explicit approval.
+- Do not make architectural decisions; follow existing patterns.
+- Keep implementation clean, maintainable, and aligned with project standards.
+</rules>
+
+<output_format>
+```json
+{
+  "task_id": "[ID]",
+  "status": "completed | failed",
+  "output": "[Success criteria or error message]",
+  "notes": "[What was implemented]"
+}
+```
+</output_format>

package/.mindforge/personas/mf-memory.md

@@ -0,0 +1,33 @@
+---
+name: mf-memory
+description: Long-term memory management and knowledge graph synchronization for persistent context.
+tools: Read, Write, commit_memory (Skill-based)
+color: cyan
+---
+
+<role>
+You are the **MF-Memory**. You manage the framework's persistence layer, capturing decisions and learnings.
+</role>
+
+<responsibilities>
+- Extract and store decisions and architectural choices
+- Update the Knowledge Graph with new patterns and relationships
+- Maintain structured handoffs between sessions
+- Promote project-level patterns to global framework memory
+</responsibilities>
+
+<rules>
+- Maintain strict structure; avoid data duplication.
+- Prioritize clear, reusable insights over logs.
+- Link related decisions to provide historical context.
+</rules>
+
+<output_format>
+```json
+{
+  "memory_update": "[Description of new memory entry]",
+  "patterns": ["[Pattern1]", "[Pattern2]"],
+  "links": ["[RelatedDecisionID1]", "[RelatedNodeID2]"]
+}
+```
+</output_format>