mindforge-cc 8.1.1 → 8.2.0

package/.mindforge/mirrors/mirror-sre-776a1cf9/.mindforge/engine/autonomous/stuck-detector.md

@@ -0,0 +1,89 @@
+# MindForge v2 — Stuck Detection Engine
+
+## Purpose
+Identify iterative loops where the agent is making no progress but still
+consuming tokens. This engine monitors the AUDIT.jsonl stream and triggers
+ESCALATE when specific failure patterns (S01-S05) are detected.
+
+---
+
+## Stuck patterns (Signatures)
+
+### S01 — The Lint Loop (The "Infinite Fixer")
+**Signature:** Multi-replace calls on the same file 3+ times with identical
+or near-identical (Levenshtein distance < 10) `Instruction` and `TargetContent`.
+**Verdict:** Agent is stuck in a "fix lint -> new lint -> fix lint" cycle
+without resolving the underlying pattern.
+**Action:** ESCALATE. "Stuck in lint loop on [file]."
+
+### S02 — The Command Loop (The "Dead Command")
+**Signature:** `run_command` called with identical `CommandLine` 3+ times
+within 5 minutes, where each command returns status `done` but with
+non-zero exit code or "command not found" stderr.
+**Verdict:** Agent expects a command to exist and is retrying it blindly.
+**Action:** ESCALATE. "Stuck retrying missing or failing command: [command]."
+
+### S03 — The Dependency Loop (The "Circular Wait")
+**Signature:** Two plans (A and B) both mark the other as a dependency in
+the PLAN-N-MM.md files, causing the wave engine to never start either.
+**Verdict:** Broken wave DAG.
+**Action:** ESCALATE. "Circular dependency detected between [A] and [B]."
+
+### S04 — The Verification Loop (The "Proofless Progress")
+**Signature:** Path: EXECUTE → VERIFY (fails) → EXECUTE → VERIFY (fails)
+where the `ReplacementContent` in EXECUTE is identical to the previous attempt.
+**Verdict:** Agent is trying the same fix multiple times expecting a different result.
+**Action:** RETRY (once with forced error injection) → DECOMPOSE.
+If decomposition also fails this loop signature: ESCALATE.
+
+### S05 — The Multi-Agent Collision
+**Signature:** Two subagents in the same wave attempting to `multi_replace`
+the same file simultaneously (Gate 1 violation detected multiple times).
+**Verdict:** Wave planning is too aggressive or files are poorly isolated.
+**Action:** RE-PLAN current wave. Move one of the colliding plans to the next wave.
+
+---
+
+## Stuck detection logic (Monitor)
+
+The stuck monitor runs as a sidecar process in `/mindforge:auto`.
+It reads `.planning/AUDIT.jsonl` in real time.
+
+```javascript
+// bin/autonomous/stuck-monitor.js logic
+const fs = require('fs');
+
+function monitorAuditStream(auditPath) {
+  let lastPos = 0;
+  setInterval(() => {
+    const stats = fs.statSync(auditPath);
+    if (stats.size > lastPos) {
+      const newLines = readLines(auditPath, lastPos, stats.size);
+      newLines.forEach(line => {
+        const event = JSON.parse(line);
+        checkS01(event);
+        checkS02(event);
+        checkS04(event);
+      });
+      lastPos = stats.size;
+    }
+  }, 5000); // Check every 5 seconds
+}
+```
+
+---
+
+## Recovery protocols
+
+When a pattern is matched:
+
+1. **Stop the subagent** immediately if still running.
+2. **Identify the pattern** in the progress stream.
+3. **Execute recovery** based on pattern type:
+   - S01/S02/S03: ESCALATE (requires human to fix command/context).
+   - S04: Invoke NODE_REPAIR with `DECOMPOSE` mandatory.
+   - S05: Invoke AUTO_PLAN --adjust-waves to resolve parallelism issues.
+4. **Write to AUDIT**:
+   ```json
+   { "event": "stuck_pattern_detected", "pattern": "S01", "file": "src/api.js" }
+   ```

package/.mindforge/mirrors/mirror-sre-776a1cf9/.mindforge/engine/compaction-protocol.md

@@ -0,0 +1,167 @@
+# MindForge Engine — Context Compaction Protocol
+
+## Purpose
+Preserve agent session state when the context window approaches its limit,
+enabling seamless continuation in a fresh context with full awareness of
+prior work.
+
+## Trigger conditions
+Initiate compaction when ANY of the following are true:
+- Context window usage reaches 70% of capacity
+- User explicitly requests: "compact context" or "save state and continue"
+- A task that would significantly expand context is about to begin
+- The agent detects it cannot recall details from early in the session
+
+DO NOT wait for 90%+ context before compacting. By then, the agent may have
+already lost critical early context. 70% is the safe threshold.
+
+## Compaction procedure — execute in strict order
+
+### Step 1 — Capture current task state
+Before writing anything, record exactly where work currently stands:
+- Which PLAN file is active
+- Which step within the plan is in progress
+- Which files have been modified since the last commit
+- Any uncommitted changes and their intent
+- Any decisions made that haven't been documented yet
+
+### Step 2 — Commit any uncommitted work-in-progress
+If there are uncommitted changes:
+```bash
+git add -A
+git commit --no-verify -m "wip(phase-[N]-plan-[M]): compaction checkpoint — [brief description]"
+```
+This ensures no work is lost. WIP commits are acceptable at compaction points.
+Document in STATE.md that hooks were bypassed for this WIP commit.
+
+### Step 3 — Update STATE.md
+Append to the current STATE.md (do not overwrite — append):
+
+```markdown
+---
+## Compaction checkpoint — [ISO-8601 timestamp]
+
+### Session summary
+[2-4 sentences summarising what was accomplished in this session]
+
+### Decisions made this session
+- [Decision 1]: [rationale]
+- [Decision 2]: [rationale]
+
+### Current position
+- Phase: [N]
+- Plan: [M]
+- Step within plan: [description of where execution stopped]
+
+### Files modified this session
+- [file 1]: [what changed]
+- [file 2]: [what changed]
+
+### What the next session must know
+[Any critical context that doesn't live in a file — implicit knowledge,
+workarounds discovered, gotchas found, things that seemed like they would
+work but did not]
+```
+
+### 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": "2.1.0",
+  "project": "[project name]",
+  "phase": [N],
+  "plan": [M],
+  "plan_step": "[exact step description]",
+  "next_task": "[exact instruction for next session]",
+  "hot_context": {
+    "active_decisions": [],
+    "recent_discoveries": [],
+    "file_offsets": {}
+  },
+  "blockers": [],
+  "context_refs": [
+    ".planning/STATE.md",
+    ".planning/HANDOFF.json",
+    ".planning/memories/WARM-SHARD-LATEST.jsonl"
+  ],
+  "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
+{
+  "id": "[uuid-v4]",
+  "timestamp": "[ISO-8601]",
+  "event": "context_compaction",
+  "phase": [N],
+  "plan": [M],
+  "context_usage_pct": [70-85],
+  "session_summary": "[1 sentence]",
+  "handoff_written": true,
+  "agent": "mindforge-orchestrator"
+}
+```
+
+### Step 6 — Compact and continue
+After all state is written:
+1. Inform the user: "Context compacted and state saved. Continuing with fresh context."
+2. Discard the accumulated tool call history from working context
+3. Reload only: ORG.md + PROJECT.md + STATE.md + HANDOFF.json + current PLAN file
+4. Continue from the exact step documented in `plan_step` field of HANDOFF.json
+
+## Session restart from HANDOFF.json
+
+When a new session begins and HANDOFF.json exists:
+
+1. Read HANDOFF.json completely
+2. Check `updated_at`:
+   - If older than 48 hours: warn the user and offer a fresh state detection
+3. Read every file in `context_refs` list
+4. Run `git log --oneline -10` to verify recent history matches `recent_commits`
+   - If git shows commits not in HANDOFF: list them and ask how to proceed
+5. Report to user: "Resuming from: [next_task field]"
+6. Ask: "Shall I continue from where we left off? (yes/no)"
+7. If yes: begin from the `plan_step` position
+8. If no: ask what the user wants to do instead
+
+## What NOT to compact
+Never compact:
+- Uncommitted work (commit it first as WIP)
+- The contents of PLAN files (they are files — they survive context resets)
+- The SUMMARY files (already written to disk)
+- Any information that is already in a file on disk
+
+Compaction is about capturing IMPLICIT knowledge — the things in the agent's
+working context that haven't been written to disk yet.
+
+## Edge case handling
+
+### Compaction during active wave execution
+If compaction is triggered while a wave is executing (subagents are running):
+1. Do not interrupt running subagents. Let them complete their current task.
+2. When the running subagent writes its SUMMARY file: trigger compaction
+   immediately after, before starting the next task or wave.
+3. Never compact mid-task. Always compact at task boundaries.
+
+### Multiple session risk
+HANDOFF.json is a shared file. If two agents read or write it concurrently,
+the last writer wins. In team environments, each engineer should use their
+own feature branch to avoid collisions.
+
+### Compaction when near 85%+ context
+If compaction was not triggered at 70% and context is now at 85%+:
+1. This is an error condition — the 70% trigger was missed.
+2. Emergency compact immediately: skip the "summarise last 20 tool calls" step.
+3. Write HANDOFF.json from whatever state is available.
+4. Restart immediately with the minimum viable context.
+5. Add an AUDIT entry with `"event":"compaction_late"` to flag this for review.

package/.mindforge/mirrors/mirror-sre-776a1cf9/.mindforge/engine/context-injector.md

@@ -0,0 +1,154 @@
+# MindForge Engine — Context Injector
+
+## Purpose
+Define exactly what context each subagent receives when spawned during
+wave execution. The context injector enforces the principle of minimum
+necessary context — giving subagents only what they need, nothing more.
+
+## Why minimum context matters
+Each subagent has 200K tokens. Wasting tokens on irrelevant files means less
+capacity for actual reasoning about the task. A subagent that receives only
+its PLAN, its persona, and relevant conventions will produce better output than
+one buried under the entire project's context.
+
+## Context injection template
+
+When spawning a subagent for PLAN-[N]-[M].md, construct this system message:
+
+```
+You are a MindForge agent executing a specific task. Read these instructions completely.
+
+## Your identity
+[Full contents of the persona file specified in <persona> field]
+
+## Your conventions
+[Full contents of CONVENTIONS.md]
+
+## Your security requirements  
+[Full contents of SECURITY.md]
+
+## Your task
+[Full contents of PLAN-[N]-[M].md]
+
+## Architecture context
+[Contents of ARCHITECTURE.md sections relevant to the files in <files> field]
+[Only include sections, not the entire file]
+
+## Relevant decisions
+[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]
+
+## Execution rules (mandatory)
+1. Implement ONLY what is specified in your <task> block. Nothing more.
+2. Touch ONLY the files listed in <files>. Nothing else.
+3. Run the <verify> step. Report its exact output.
+4. If the verify step fails: describe what failed and why. Do not mark done.
+5. Write your SUMMARY after completion (template below).
+6. Commit with: type(scope): [task name from <n>]
+
+## SUMMARY template
+File: .planning/phases/[N]/SUMMARY-[N]-[M].md
+[Use the standard SUMMARY template from execute-phase.md]
+
+## Important constraints
+- You are one task in a larger wave. Other tasks are running in parallel.
+- You do not know what the other tasks are doing. That is intentional.
+- Do not read files outside your <files> list. You may read them to
+  understand existing code context, but your writes are scoped to <files>.
+- If you encounter something unexpected that requires scope expansion:
+  stop, describe what you found, and wait for orchestrator input.
+```
+
+## Security guards (run before building any context package)
+
+### Path traversal guard
+Before reading any file referenced in a plan's `<context>` field:
+1. Resolve the file path to an absolute path.
+2. Verify the absolute path starts with the project root directory.
+3. If it does not: STOP and report a possible path traversal attempt.
+4. Never read files outside the project root, regardless of the reference.
+
+### SECURITY.md placeholder detection
+Before injecting SECURITY.md into a subagent context:
+1. Check for placeholders: `[ORG NAME]`, `[specify]`, `[your-org]`, `TODO`, `[placeholder]`
+2. If found: warn the user that SECURITY.md is incomplete and may misguide subagents.
+3. Allow the user to proceed or update SECURITY.md first.
+4. Log an AUDIT entry:
+   `{"event":"security_config_warning","detail":"SECURITY.md has placeholder text"}`
+
+## Context size budget
+
+Before injecting, estimate the total context size:
+- Persona file: ~1-3K tokens
+- CONVENTIONS.md: ~2-5K tokens  
+- SECURITY.md: ~2-4K tokens
+- PLAN file: ~500-2K tokens
+- ARCHITECTURE sections: ~2-10K tokens
+- ADR files: ~1-3K tokens each
+- SKILL files: ~2-5K tokens each
+
+Target: under 30K tokens for context injection.
+This leaves 170K tokens for actual implementation work.
+
+If the context package would exceed 30K tokens:
+1. Summarise ARCHITECTURE.md to only the directly relevant sections
+2. Reference ADRs by title rather than full content if not critical
+3. Never compress the PLAN file or security/conventions files
+
+## Context size enforcement
+Before injecting context to a subagent:
+1. Estimate total token count (rough estimate: characters / 4)
+2. If estimated tokens > 30,000:
+   a. Log which files are contributing most
+   b. Summarise ARCHITECTURE.md to relevant sections only
+   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:
+1. Status: completed ✅ / failed ❌ / blocked 🚫
+2. The verify step output (exact text)
+3. The git commit SHA
+4. The path to SUMMARY-[N]-[M].md
+5. Any decisions made that deviated from the plan (for escalation)
+
+### Completion signal
+Completion is confirmed ONLY when the SUMMARY file exists AND contains a
+status line:
+- `Status: Completed ✅`
+- `Status: Failed ❌`
+- `Status: Blocked 🚫`
+
+If status is failed or blocked: the orchestrator stops the wave and
+reports to the user before taking any further action.

package/.mindforge/mirrors/mirror-sre-776a1cf9/.mindforge/engine/dependency-parser.md

@@ -0,0 +1,113 @@
+# MindForge Engine — Dependency Parser
+
+## Purpose
+Parse all PLAN files for a given phase and build a directed acyclic graph (DAG)
+of task dependencies. This graph is the input to the wave grouping algorithm.
+
+## Input
+All files matching: `.planning/phases/[N]/PLAN-[N]-*.md`
+
+## Parsing protocol
+
+### Step 1 — Read all plan files
+For each PLAN file in the phase directory:
+1. Read the full file content
+2. Extract the `<task>` XML block
+3. Parse these fields:
+   - `<n>` → task name (string)
+   - `<plan>` → plan ID (e.g., "01", "02")
+   - `<dependencies>` → comma-separated list of plan IDs, or "none"
+   - `<files>` → newline-separated list of file paths
+
+### Step 2 — Build the dependency graph
+Represent the graph as an adjacency list:
+
+```
+Graph = {
+  "01": { name: "...", dependsOn: [],         blockedBy: [] },
+  "02": { name: "...", dependsOn: [],         blockedBy: [] },
+  "03": { name: "...", dependsOn: ["01"],     blockedBy: [] },
+  "04": { name: "...", dependsOn: ["01","02"],blockedBy: [] },
+  "05": { name: "...", dependsOn: ["03","04"],blockedBy: [] },
+}
+```
+
+### Step 3 — Validate the graph
+Before proceeding, validate:
+
+**Circular dependency check:**
+Perform a depth-first traversal. If any node is visited twice in the same
+traversal path, a cycle exists. Stop and report:
+"Circular dependency detected: [plan A] → [plan B] → [plan A]"
+A cycle makes execution impossible. The user must fix the PLAN files.
+
+**Missing dependency check:**
+For every plan ID in any `<dependencies>` list, verify that a corresponding
+PLAN file exists. If not:
+"Plan [N]-[M] declares dependency on [X] but PLAN-[N]-[X].md does not exist."
+
+**File conflict check:**
+If two plans in the same potential wave touch the same file, they CANNOT
+run in parallel — they must be in different waves. Flag any such conflicts:
+"Plans [A] and [B] both modify [file]. Placing [B] in a later wave."
+Automatically adjust wave assignment to resolve file conflicts.
+
+### Additional validation cases
+
+**Self-referencing plan:**
+If any plan lists its own ID in `<dependencies>` (e.g., Plan 03 depends on 03):
+```
+Error: Plan [N]-[M] declares a dependency on itself.
+This is impossible to satisfy. Remove [M] from its own <dependencies> list.
+```
+
+**Empty plan directory:**
+If the phase directory contains zero PLAN files:
+```
+Error: No PLAN files found in .planning/phases/[N]/.
+Run /mindforge:plan-phase [N] to create plans before executing.
+```
+Do not return an empty graph — return this error explicitly.
+
+**Dependency on a completed phase's plans:**
+If a PLAN in Phase 3 declares a dependency on a PLAN in Phase 2:
+This is valid only if Phase 2 is complete (all SUMMARY files exist and passing).
+If Phase 2 is not complete: flag as a warning, not an error.
+Allow execution to proceed but note the cross-phase dependency.
+
+**All plans in the same wave touch the same file:**
+If all plans in a computed wave touch at least one common file, the wave
+cannot run in parallel without conflicts. In this case:
+Sort the plans into sequential execution order within the wave.
+Notify: "Wave [W]: file conflicts detected — executing plans sequentially."
+This is suboptimal but safe. The user should redesign plans to avoid this.
+
+### Step 4 — Output the dependency report
+Write to `.planning/phases/[N]/DEPENDENCY-GRAPH-[N].md`:
+
+```markdown
+# Dependency Graph — Phase [N]
+
+## Tasks
+| Plan | Name                  | Depends On    | Wave | File Conflicts |
+|------|-----------------------|---------------|------|----------------|
+| 01   | Create user model     | none          | 1    | none           |
+| 02   | Create product model  | none          | 1    | none           |
+| 03   | User API endpoints    | 01            | 2    | none           |
+| 04   | Product API endpoints | 02            | 2    | none           |
+| 05   | Checkout UI           | 03, 04        | 3    | none           |
+
+## Validation
+- Circular dependencies: None ✅
+- Missing dependencies: None ✅
+- File conflicts resolved: [list any that were adjusted]
+
+## Execution order
+Wave 1 → Wave 2 → Wave 3
+(see wave-executor.md for wave grouping)
+
+## Wave assignments
+- Wave 1: 01, 02
+- Wave 2: 03, 04
+- Wave 3: 05
+```

package/.mindforge/mirrors/mirror-sre-776a1cf9/.mindforge/engine/integrity.json

@@ -0,0 +1,12 @@
+{
+  "version": "8.1.1",
+  "manifest_date": "2026-03-29T17:15:03Z",
+  "signature_type": "lattice-based",
+  "integrity_status": "MANIFESTED",
+  "signed_assets": [
+    "bin/governance/quantum-crypto.js",
+    "bin/governance/policy-engine.js",
+    "bin/autonomous/intent-harvester.js",
+    "bin/autonomous/mesh-self-healer.js"
+  ]
+}

package/.mindforge/mirrors/mirror-sre-776a1cf9/.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/mirrors/mirror-sre-776a1cf9/.mindforge/engine/nexus-tracer.js

@@ -0,0 +1,11 @@
+/**
+ * MindForge Nexus — Legacy Shim (v5.9.0)
+ * 
+ * This file acts as a compatibility layer for the v4.1.0-alpha.nexus ART protocol.
+ * ALL core tracing logic has been migrated to /bin/engine/nexus-tracer.js for 
+ * production-grade performance and security hardening.
+ */
+
+'use strict';
+
+module.exports = require('../../bin/engine/nexus-tracer');