musememory 2.1.0 → 2.2.1

package/.agents/context/current.md

@@ -1,7 +1,7 @@
 # 📍 Current Shipped State & Active Invariants
 
-> **Version**: `v2.1.0`  
-> **Status**: Production Release (P2P Sync, Studio, and Monorepo Mesh)
+> **Version**: `v2.2.1`  
+> **Status**: Production Release (Hardened v2.2 with Linus-Style Code Review Bug Fixes)
 
 ---
 
@@ -34,6 +34,11 @@
 25. **Cross-Agent Knowledge Sync & P2P Gossip Protocol (R14)**: Portable sealed `SyncPacket` with SHA-256 integrity, vector clock causal ordering, bidirectional shared pool drop-directory gossip exchange, deduplication, Vibeguard secret scrubbing, and semantic contradiction tagging with mutual `conflict_ids`.
 26. **Full Web Observability Studio & Interactive Visual Dashboard (R15)**: Integrated web studio served over local HTTP (`memory studio`), featuring a 5-pillar health scorecard, overall letter grade, prioritized remediation action checklist, ADR registry with code-to-doc drift inspector, autonomous "Why" reasoner, bug friction clusters heatmap, debt hotspots, and live P2P mesh topology visualizer.
 27. **Multi-Repo & Monorepo Cross-Project Mesh (R16)**: Automatic workspace detection across pnpm, npm, bun, lerna, and multi-repo sibling groups; cross-project memory querying with origin package provenance; cross-package contract and entrypoint export auditing; explicit mesh linking (`mesh_links.json`); and shared invariant propagation across the entire mesh.
+28. **Unified Code & Memory Impact Analysis**: Pre-flight blast radius analysis evaluating AST callers, test suites, governing ADRs, negative warnings, and risk levels (`memory code-impact` / `muse_code_impact`).
+29. **PR & Change Context Generator**: Automatically turns git diffs into rich, memory-grounded GitHub PR descriptions linking touched anchors and active constraints (`memory pr-context` / `muse_pr_context`).
+30. **Interactive Code Anchor Reconciler**: Audits and repairs code anchors across memories, pruning dead references and updating structural hashes (`memory reconcile` / `muse_reconcile_anchors`).
+31. **Latency & Quality Telemetry Suite**: Benchmarks microsecond hot caches, FTS5 BM25 search, knapsack token packing, and ROI in a clean ASCII scoreboard (`memory benchmark`).
+32. **Linus-Style Architectural Hardening (v2.2.1)**: Elimination of shell command injection via `execFileSync`, concurrency-safe `PRAGMA busy_timeout = 5000` on SQLite WAL mode, O(N) stat storm elimination in `list(store)`, structured warnings on YAML dual-write failures, and tightened word-boundary/code-anchor ADR matching.
 
 ---
 

package/.agents/skills/muse-drift/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: muse-drift
+description: Living Architecture Decision Records (ADRs) and bidirectional documentation-to-code drift auditor. Investigates architectural drift, records living decisions, and maintains doc-code harmony.
+---
+
+# 🏛️ Muse Drift (`muse-drift`)
+
+> **When to use**: Execute when introducing architectural changes, making technology choices, refactoring system boundaries, or checking if documentation matches actual implementation.
+
+---
+
+## 🚀 Execution Workflow
+
+### Step 1: Audit Documentation $\longleftrightarrow$ Code Alignment
+Call the `memory_drift_audit` MCP tool (or run `memory drift`):
+
+```json
+{
+  "dir": "."
+}
+```
+
+The auditor classifies documented items across 6 mutually exclusive states:
+- `DOCUMENTED`: Architectural guidelines described in docs/ADRs.
+- `IMPLEMENTED`: Verified clean match between doc and code AST.
+- `PARTIAL`: Incomplete implementation or missing export.
+- `CONFLICTING`: Code directly contradicts documented architecture.
+- `STALE`: Document references removed modules or legacy abstractions.
+- `MISSING`: Code exists with zero architectural documentation.
+
+### Step 2: Record Living Architecture Decision Records (ADRs)
+When establishing or changing an architectural design decision, record a first-class ADR using `memory_adr_record`:
+
+```json
+{
+  "title": "Use SQLite WAL and Microsecond In-Process Memory Cache",
+  "decision": "All memory read/write operations must use in-process SQLite WAL mode with an L0 hot cache. No resident background daemons.",
+  "status": "accepted",
+  "context_and_drivers": [
+    "Zero-daemon constraint",
+    "Sub-millisecond latency requirement for CLI commands"
+  ],
+  "consequences": {
+    "positive": ["Microsecond hot cache lookups", "Concurrent multi-process reads"],
+    "negative": ["Requires file locking management on write"]
+  },
+  "anchors": [
+    { "kind": "file", "file_path": "src/store.ts" },
+    { "kind": "file", "file_path": "src/cache.ts" }
+  ]
+}
+```
+
+### Step 3: Supersede Obsolete Decisions
+When replacing an existing ADR, provide the `supersedes` parameter with the old ADR ID. The engine automatically marks the old decision as `superseded` and records full provenance in the audit ledger.
+
+---
+
+## 💻 CLI Equivalents (Zero-MCP Fallback)
+
+```bash
+# Check repository documentation vs code drift
+memory drift
+
+# List all living Architecture Decision Records
+memory adr list
+
+# Record a new Architecture Decision Record
+memory adr record "Decision Title" --decision "..." --positive "..." --negative "..."
+```

package/.agents/skills/muse-health/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: muse-health
+description: Unified 5-pillar project health gate governor. Audits store integrity, code anchors, doc/code alignment, negative sentry, and technical debt to enforce production hardening gates.
+---
+
+# 🏥 Muse Health (`muse-health`)
+
+> **When to use**: Execute before completing features, opening pull requests, or cutting releases to verify repository hardening and architectural health.
+
+---
+
+## 🚀 Execution Workflow
+
+### Step 1: Run 5-Pillar Health Gate
+Call the `muse_health` MCP tool (or execute `memory health`):
+
+```json
+{
+  "dir": "."
+}
+```
+
+### Step 2: Evaluate 5-Pillar Scorecard
+The engine evaluates 5 distinct hardening dimensions, outputting an overall letter grade (**A–F**) and a gate status (**PASS**, **WARN**, or **FAIL**):
+
+1. **Pillar 1: Store Integrity**:
+   - Validates referential integrity, YAML schema conformances, bidirectional links, and missing target memory IDs.
+2. **Pillar 2: Native Code Anchors**:
+   - Verifies whether files, functions, and symbols referenced by code anchors exist on disk, flagging drifted structural hashes or orphaned anchors.
+3. **Pillar 3: Doc $\longleftrightarrow$ Code Alignment**:
+   - Audits living ADRs and documented invariants against actual code implementations, identifying conflicting, stale, or missing code.
+4. **Pillar 4: Negative Anti-Pattern Sentry**:
+   - Checks if any known `DO_NOT_USE` patterns, regression bug fixes, or failed approaches have resurfaced in the active working tree.
+5. **Pillar 5: Technical Debt & Workaround Sentry**:
+   - Detects unresolved `TODO`/`FIXME`/`HACK` comments, dangerous type casts (`as any`), and drifted architectural commitments.
+
+### Step 3: Execute Actionable Remediation Checklist
+If the gate status is **WARN** or **FAIL**, the engine outputs an ordered remediation checklist. Execute the prioritized items:
+- Prune or re-link orphaned code anchors via `memory reconcile --prune`.
+- Adhere to active ADR decisions.
+- Resolve flagged type assertions or negative pattern recurrences.
+
+---
+
+## 💻 CLI Equivalents (Zero-MCP Fallback)
+
+```bash
+# Full terminal health dashboard
+memory health
+
+# Output raw JSON for CI/CD gating (exits 1 on FAIL)
+memory health --json
+
+# Interactively audit and prune orphaned code anchors
+memory reconcile --prune
+```

package/.agents/skills/muse-mesh/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: muse-mesh
+description: Multi-repo and monorepo cross-project knowledge mesh. Resolves memories across package boundaries, broadcasts shared invariants, and audits cross-package dependency contract integrity.
+---
+
+# 🕸️ Muse Mesh (`muse-mesh`)
+
+> **When to use**: Execute in monorepo environments (pnpm, npm, bun, lerna) or multi-repo projects when code spans multiple package boundaries or microservices.
+
+---
+
+## 🚀 Execution Workflow
+
+### Step 1: Discover Monorepo Topology
+Call the `muse_mesh_status` MCP tool (or run `memory mesh overview`):
+
+```json
+{
+  "dir": "."
+}
+```
+
+Automatically inspects `pnpm-workspace.yaml`, `package.json` workspaces, or `lerna.json`, listing all detected package nodes and explicit mesh links.
+
+### Step 2: Query Knowledge Across Package Boundaries
+Call `muse_mesh_query` to search memories across all connected packages:
+
+```json
+{
+  "query": "authentication session store",
+  "scope": "all"
+}
+```
+
+Results include origin package provenance badges (e.g. `[mesh:@scope/core]`), preventing agents in frontend apps from hallucinating backend contract violations.
+
+### Step 3: Broadcast Shared Invariants to All Packages
+When establishing a monorepo-wide rule (e.g., "All microservices must use JWT v2 tokens"):
+- Use `memory mesh propagate --constraint "Use JWT v2 tokens across all services"`.
+- The invariant is atomically stamped into every package's `.memory/CURRENT.md`.
+
+### Step 4: Audit Cross-Package Contracts
+Call `muse_mesh_audit` (or run `memory mesh check`):
+- Verifies that cross-package imports match valid export entrypoints.
+- Flags drifted cross-repo code anchors.
+
+---
+
+## 💻 CLI Equivalents (Zero-MCP Fallback)
+
+```bash
+# Display monorepo mesh topology and linked packages
+memory mesh overview
+
+# Query memories across all monorepo packages
+memory mesh query "database pool" --scope all
+
+# Audit cross-package contract integrity
+memory mesh check
+
+# Propagate a critical security constraint across all packages
+memory mesh propagate --constraint "Never expose database connection strings"
+
+# Explicitly link an external sibling repository
+memory mesh link ../external-service
+```

package/.agents/skills/muse-sync/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: muse-sync
+description: Cross-agent knowledge sync and P2P gossip mesh protocol. Enables multi-agent swarms and isolated subagent teams to exchange insights, deduplicate knowledge, and resolve contradictions asynchronously.
+---
+
+# 🤝 Muse Sync (`muse-sync`)
+
+> **When to use**: Execute when coordinating multi-agent workflows (e.g., frontend, backend, and test subagents), sharing verified bug fixes between worktrees, or consolidating swarm learnings.
+
+---
+
+## 🚀 Execution Workflow
+
+### Step 1: Check Peer Mesh & Vector Clock Status
+Call the `muse_sync_status` MCP tool (or run `memory sync --status`):
+
+```json
+{
+  "dir": "."
+}
+```
+
+Returns peer agent vector clocks, tracked packet generations, and pending incoming packets.
+
+### Step 2: Broadcast a Sealed Knowledge Packet
+To export recent confirmed memories, bug fixes, and active constraints into a portable packet:
+
+```json
+{
+  "project": "my-project",
+  "export_constraints": true
+}
+```
+
+The engine creates a cryptographically sealed `SyncPacket` with:
+- Whole-packet SHA-256 checksum verification.
+- Vector clock causal sequencing (`sender_id` + logical sequence).
+- Automatic Vibeguard secret inspection prior to packaging.
+
+### Step 3: Synchronize via Zero-Daemon Shared Pool
+Call `muse_sync_pool` (or run `memory sync --pool`):
+- Broadcasts un-synced memories into `.memory/sync_pool/`.
+- Ingests new packets dropped by peer subagents.
+- Eliminates duplicate entries automatically.
+- Flags semantic contradictions with mutual `conflict_ids` and triggers dispute resolution.
+
+---
+
+## 💻 CLI Equivalents (Zero-MCP Fallback)
+
+```bash
+# View peer agent sync status and vector clocks
+memory sync --status
+
+# Broadcast confirmed memories to an exported packet
+memory sync --broadcast --out ./shared_sync.json
+
+# Ingest peer knowledge packet with secret scrubbing
+memory sync --ingest ./shared_sync.json
+
+# Bidirectionally sync with the shared filesystem gossip pool
+memory sync --pool
+```

package/.agents/skills/muse-why/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: muse-why
+description: Historical rationale and code evolution explainer. Synthesizes past ADRs, bug fixes, trade-offs, and invariants to explain why code was written the way it is before refactoring.
+---
+
+# 🤔 Muse Why (`muse-why`)
+
+> **When to use**: Execute before modifying unfamiliar code, refactoring complex logic, or when encountering code patterns that look unusual or overly defensive.
+
+---
+
+## 🚀 Execution Workflow
+
+### Step 1: Query Code Rationale ("Why is this code like this?")
+Call the `muse_why` MCP tool:
+
+```json
+{
+  "target": "src/mcp.ts",
+  "symbol": "createServer",
+  "query": "Why do we filter tools dynamically by profile?"
+}
+```
+
+The "Why" reasoner traces backwards through history and synthesizes:
+1. **Governing Architecture Decisions**: Living ADRs that authorized or mandated this structure.
+2. **Historical Bug Fixes**: Edge cases and production regressions that necessitated defensive checks.
+3. **Accepted Trade-offs**: Documented compromises between performance, complexity, and safety.
+4. **Timeless Constraints**: Core architectural laws that must remain invariant.
+
+### Step 2: Audit Fragility & Bug Friction Clusters
+Call the `muse_bug_clusters` MCP tool:
+
+```json
+{
+  "dir": "."
+}
+```
+
+Clusters recurring issues across 5 core root causes:
+- `concurrency_race`: Race conditions, lock timeouts, async synchronization.
+- `type_mismatch`: Dangerous type bypasses, undefined property access.
+- `state_drift`: Out-of-sync cache entries, missing invalidation.
+- `resource_leak`: Unclosed file descriptors, runaway memory consumption.
+- `edge_case`: Boundary errors, empty array handling, malformed input.
+
+### Step 3: Check Pre-Flight Code & Memory Impact
+Call `muse_code_impact` (or run `memory code-impact <file> --symbol <sym>`) to check direct callers, affected test suites, and composite risk levels before editing.
+
+---
+
+## 💻 CLI Equivalents (Zero-MCP Fallback)
+
+```bash
+# Query unified code & memory impact before editing
+memory code-impact src/mcp.ts --symbol createServer
+
+# View technical debt hotspots
+memory tech-debt
+```

package/README.md

@@ -13,7 +13,7 @@
 ![AST Graph](https://img.shields.io/badge/AST-CodeGraph_%26_Graphify-orange?style=for-the-badge&logo=diagram-project&logoColor=white)
 ![Architecture](https://img.shields.io/badge/Storage-Zero--Daemon_%2F_Local--First-0D9488?style=for-the-badge)
 
-![CI Tests](https://img.shields.io/badge/Tests-480%20Passed-brightgreen?style=for-the-badge&logo=checkmarx)
+![CI Tests](https://img.shields.io/badge/Tests-497%20Passed-brightgreen?style=for-the-badge&logo=checkmarx)
 ![Security](https://img.shields.io/badge/Security-Vibeguard_Zero--Leak-DC2626?style=for-the-badge&logo=shield)
 ![Agent Coverage](https://img.shields.io/badge/Agents-80+_Supported-4F46E5?style=for-the-badge&logo=openai)
 ![License](https://img.shields.io/badge/License-MIT-9333EA?style=for-the-badge)
@@ -24,23 +24,34 @@
 
 ---
 
-## 🚀 What's New in v2.0.0 (Autonomous Cognitive Engine Major Overhaul)
-
-- **🏥 Unified 5-Pillar Project Health Gate (`memory health` / `muse_health`)**: Comprehensive single-call architectural and memory health audit scoring Store Integrity, Code Anchor Validity, Doc $\leftrightarrow$ Code Alignment, Negative Sentry, and Technical Debt with letter grades (A-F), PASS/WARN/FAIL status, and automated remediation checklists.
-- **🧠 Autonomous Engineering Cognition & "Why" Reasoner (`muse_why`)**: Traces code evolution backwards through past bug fixes, ADRs, accepted trade-offs, and invariants to explain *why* code was built the way it is before refactoring.
-- **🏛️ First-Class Architecture Decision Records (`memory_adr_record` / `memory_adr_list`)**: ADRs as queryable, scored, living memory units with options considered, consequences, native code anchors, and supersession lineage.
-- **🔄 Bidirectional Documentation $\leftrightarrow$ Code Drift Engine (`memory_drift_audit`)**: Continuously verifies that documented architectural invariants match live implementation and flags missing, stale, or conflicting code.
-- **🎯 Flagship Unified Context Orchestrator (`muse_context`)**: Single-call fused entry point combining search, active file, symbol, error messages, and task intent under strict knapsack token budgets.
-- **⚙️ Task-Focused MCP Profiles**: Solves agent tool bloat with role-tailored tool filtering profiles (`core`, `coding`, `debugging`, `review`, `architecture`, `maintenance`).
-- **⚓ Native Structural Code Anchors (`src/anchors/`)**: Line-independent structural hashing invariant to comment/spacing edits while strictly sensitive to AST/logic modifications.
-- **🪜 Scoped Promotion & Extended Archival Lifecycle (`src/promotion/`)**: 3-tier promotion ladder (`local` $\rightarrow$ `project` $\rightarrow$ `global`), 5× repeated success policy, universal generalization, and `active` $\rightarrow$ `cold` $\rightarrow$ `dormant` $\rightarrow$ `archived` lifecycle with dynamic query rehydration.
-- **⚡ Hot Query Cache & Multi-Factor Retrieval**: Microsecond caching, SQLite WAL optimization, and 11-dimension retrieval scoring.
+## 🚀 What's New
+
+### v2.2.0
+- **Unified Code & Memory Impact Analysis**: Pre-flight blast radius analysis evaluating AST callers, test suites, governing ADRs, negative warnings, and risk levels (`memory code-impact` / `muse_code_impact`).
+- **PR & Change Context Generator**: Automatically turns git diffs into rich, memory-grounded GitHub PR descriptions linking touched anchors and active constraints (`memory pr-context` / `muse_pr_context`).
+- **Interactive Code Anchor Reconciler**: Audits and repairs code anchors across memories, pruning dead references and updating structural hashes (`memory reconcile` / `muse_reconcile_anchors`).
+- **Latency & Quality Telemetry Suite**: Benchmarks microsecond hot caches, FTS5 BM25 search, knapsack token packing, and ROI in a clean ASCII scoreboard (`memory benchmark`).
+- **Expanded Agent Skills**: Shipped turnkey skills for `muse-health`, `muse-drift`, `muse-why`, `muse-sync`, and `muse-mesh`.
+
+### v2.1.0
+- **Cross-Agent Knowledge Sync & P2P Gossip Protocol**: Sealed portable `SyncPacket` engine with SHA-256 integrity and zero-daemon shared filesystem gossip pool (`memory sync` / `muse_sync_*`).
+- **Web Observability Studio**: Embedded visual dashboard (`memory studio` / `memory ui`) with interactive 5-pillar health, ADR registry, code drift inspector, and sync controls.
+- **Monorepo & Multi-Repo Mesh**: Automatic workspace discovery (pnpm, npm, bun, lerna) with cross-project memory queries and shared constraint propagation (`memory mesh` / `muse_mesh_*`).
+
+### v2.0.0
+- **5-Pillar Project Health Gate**: Architectural health gate evaluating store integrity, code anchors, doc-code alignment, negative sentry, and technical debt (`memory health` / `muse_health`).
+- **Cognitive "Why" Reasoner**: Reconstructs historical code evolution, bug workarounds, and trade-offs before refactoring (`muse_why`).
+- **Living Architecture Decision Records (ADRs)**: Queryable ADRs with options, consequences, native code anchors, and supersession lineage (`memory adr` / `memory_adr_record`).
+- **Doc ⟷ Code Drift Engine**: Continuously audits documentation against AST code implementations across 6 drift states (`memory drift` / `memory_drift_audit`).
+- **Unified Context Orchestrator & MCP Profiles**: Single-call fused context injection with knapsack token packing (`muse_context`) and task-specific tool profiles.
+- **Native Structural Code Anchors**: Line-independent structural SHA-256 hashing for files, symbols, and routes.
+- **Scoped Promotion & Archival Lifecycle**: 3-tier promotion ladder (`local` → `project` → `global`) and cold/dormant/archived storage tiers.
 
 ---
 
 ## 📑 Table of Contents
 
-- [🚀 What's New in v2.0.0](#-whats-new-in-v200-autonomous-cognitive-engine-major-overhaul)
+- [🚀 What's New](#-whats-new)
 - [💡 What is Muse Memory? (TL;DR)](#-what-is-muse-memory-tldr)
 - [✨ Key Feature Highlights](#-key-feature-highlights)
 - [⚡ Quick Start & Installation](#-quick-start--installation)
@@ -62,36 +73,43 @@ Most AI chatbots and coding assistants have **"goldfish memory"**: every time yo
 **Muse Memory gives your AI assistants a persistent, self-organizing cognitive notebook directly on your machine.**
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                    AI Agents & IDE Platforms                │
-│  (Claude Code, Cursor, Antigravity, Windsurf, Codex, CLI)   │
-└──────────────────────────────┬──────────────────────────────┘
-                               │ MCP stdio / Terminal CLI
-┌──────────────────────────────▼──────────────────────────────┐
-│                    Muse Memory Core Engine                  │
-│                                                             │
-│ ┌───────────────────┐ ┌──────────────────┐ ┌──────────────┐ │
-│ │  Retrieval Engine │ │ Vibeguard Secret │ │ Auto-Migrate │ │
-│ │ (Token Knapsack)  │ │ Defense Scanner  │ │  (29 Engines)│ │
-│ └───────────────────┘ └──────────────────┘ └──────────────┘ │
-│ ┌───────────────────┐ ┌──────────────────┐ ┌──────────────┐ │
-│ │ LifeCycle Machine │ │ Knowledge Wiki   │ │ Audit Ledger │ │
-│ │(State Transitions)│ │ (Obsidian/Entities│ │(audit.jsonl) │ │
-│ └───────────────────┘ └──────────────────┘ └──────────────┘ │
-└──────────────────────────────┬──────────────────────────────┘
-                               │ Atomic I/O
-┌──────────────────────────────▼──────────────────────────────┐
-│              Dual-Scope Storage Engine (.memory/)           │
-│                                                             │
-│  .memory/                                                   │
-│  ├── memory.db          # Primary SQLite cognitive database │
-│  ├── CURRENT.md         # Active hard constraints & handoff │
-│  ├── USER.md            # Persona & developer preferences   │
-│  ├── audit.jsonl        # Append-only operational audit trail│
-│  └── memories/          # Dual-persisted YAML export mirror │
-│      ├── m_1700000001000_auth.yaml                          │
-│      └── m_1700000002000_arch.yaml                          │
-└─────────────────────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                 AI Agents, Subagent Pods & Autonomous Swarms                 │
+│        (Claude Code, Cursor, Antigravity, Windsurf, Codex, CLI)             │
+└───────────────────────┬─────────────────────────────────────┬───────────────┘
+                        │ MCP stdio / Terminal CLI            │ Local HTTP
+┌───────────────────────▼─────────────────────────────────────▼───────────────┐
+│                           Muse Memory Core Engine                           │
+│                                                                             │
+│ ┌──────────────────────┐ ┌──────────────────────┐ ┌───────────────────────┐ │
+│ │  Unified Context &   │ │ 5-Pillar Health Gate │ │ Autonomous Cognition  │ │
+│ │  Knapsack Retrieval  │ │  & ADR Drift Sentry  │ │   & "Why" Reasoner    │ │
+│ └──────────────────────┘ └──────────────────────┘ └───────────────────────┘ │
+│ ┌──────────────────────┐ ┌──────────────────────┐ ┌───────────────────────┐ │
+│ │   P2P Gossip Sync    │ │  Monorepo Workspace  │ │   Web Observability   │ │
+│ │  (Vector Clock Mesh) │ │  Cross-Project Mesh  │ │ Studio (memory studio)│ │
+│ └──────────────────────┘ └──────────────────────┘ └───────────────────────┘ │
+│ ┌──────────────────────┐ ┌──────────────────────┐ ┌───────────────────────┐ │
+│ │ Vibeguard Credential │ │ Dynamic Code Anchors │ │ Universal Migrator    │ │
+│ │    Secret Defense    │ │ & Structural Hashes  │ │     (29 Engines)      │ │
+│ └──────────────────────┘ └──────────────────────┘ └───────────────────────┘ │
+└──────────────────────────────────────┬──────────────────────────────────────┘
+                                       │ Atomic SQLite & File I/O
+┌──────────────────────────────────────▼──────────────────────────────────────┐
+│                     Dual-Scope Storage Engine (.memory/)                    │
+│                                                                             │
+│  .memory/                                                                   │
+│  ├── memory.db          # Primary SQLite database (WAL + FTS5 BM25)         │
+│  ├── CURRENT.md         # Real-time working constraints & session handoffs  │
+│  ├── USER.md            # Persona archetypes & working style preferences    │
+│  ├── sync_pool/         # Zero-daemon shared P2P gossip pool drop folder    │
+│  ├── mesh_links.json    # Explicit multi-repo cross-project mesh links      │
+│  ├── sync_peers.json    # Peer agent vector clock causal tracking ledger    │
+│  ├── audit.jsonl        # Append-only operational audit & compliance trail  │
+│  └── memories/          # Dual-persisted human-readable YAML mirror         │
+│      ├── m_1700000001000_auth.yaml                                          │
+│      └── m_1700000002000_mesh.yaml                                          │
+└─────────────────────────────────────────────────────────────────────────────┘
 ```
 
 ---
@@ -169,20 +187,6 @@ memory upgrade
 npx musememory upgrade
 ```
 
-```
-┌──────────────────────────────────────────────────────────────────┐
-│  🧠 MUSE MEMORY · SYSTEM LEVEL-UP & RECOVERY MATRIX              │
-└──────────────────────────────────────────────────────────────────┘
-
-  [████████████████████] 100% ✓ LEVEL 1: Vibeguard Security & Credential Audit [OK]
-  [████████████████████] 100% ✓ LEVEL 2: Package Manager Sync (bun/npm) [OK]
-  [████████████████████] 100% ✓ LEVEL 3: Synaptic Storage & Schema Alignment [OK]
-  [████████████████████] 100% ✓ LEVEL 4: 80+ Agent Platforms & Skills Auto-Wiring [OK]
-  [████████████████████] 100% ✓ LEVEL 5: Cognitive Ascendance Complete [OK]
-
-🏆 [LEVEL-UP COMPLETE] Muse Memory is now fully armed and up to date!
-```
-
 #### What `memory upgrade` automatically handles:
 1. **Package Manager Auto-Detection**: Detects whether your workstation runs `bun`, `npm`, `pnpm`, or `yarn` and pulls the latest published binary.
 2. **Self-Healing Storage Repair**: Recovers missing `.memory/`, `CURRENT.md` constraints, or `USER.md` persona files if corrupted or deleted.
@@ -521,13 +525,18 @@ memory <command> [arguments] [flags]  # alias: musememory
 <details>
 <summary><b>🧠 Shipped Agent Skills (<code>.agents/skills/</code>)</b> — <i>Click to expand</i></summary>
 
-Muse Memory ships with 6 turnkey Agent Skills designed for coding agents (Claude Code, Cursor, Antigravity, OpenCode, Codex, Gemini CLI, etc.) under `.agents/skills/`:
+Muse Memory ships with 11 turnkey Agent Skills designed for coding agents (Claude Code, Cursor, Antigravity, OpenCode, Codex, Gemini CLI, etc.) under `.agents/skills/`:
 
 | Skill | Trigger Phase | Core Agent Responsibility |
 | :--- | :--- | :--- |
 | [`muse-ground`](.agents/skills/muse-ground/SKILL.md) | **Session Start** | Retrieves Top-$K$ relevant memories, active `USER.md` persona profile, and `CURRENT.md` constraints before writing code. |
 | [`muse-capture`](.agents/skills/muse-capture/SKILL.md) | **During Fixes & Refactors** | Captures atomic fix/architecture memories, validates evidence, runs Vibeguard secret scan, and supersedes obsolete knowledge. |
 | [`muse-current`](.agents/skills/muse-current/SKILL.md) | **Invariants & Handoffs** | Synchronizes hard constraints into `.memory/CURRENT.md` and persists structured handoffs across context resets. |
+| [`muse-health`](.agents/skills/muse-health/SKILL.md) | **Hardening Gates & PRs** | Evaluates 5-pillar architectural health (store, anchors, doc/code alignment, negative sentry, debt) and outputs remediation checklists. |
+| [`muse-drift`](.agents/skills/muse-drift/SKILL.md) | **System Architecture & ADRs** | Audits documentation $\longleftrightarrow$ code drift across 6 states, records living ADRs, and supersedes legacy architectural decisions. |
+| [`muse-why`](.agents/skills/muse-why/SKILL.md) | **Refactoring & Historical Context** | Reconstructs historical rationale, synthesizes past bug fixes and accepted trade-offs, and audits recurring bug friction clusters. |
+| [`muse-sync`](.agents/skills/muse-sync/SKILL.md) | **Multi-Agent & Swarm Gossip** | Coordinates cross-agent knowledge sync with whole-packet SHA-256 integrity, vector clocks, and P2P gossip mesh pool. |
+| [`muse-mesh`](.agents/skills/muse-mesh/SKILL.md) | **Monorepo & Multi-Repo Mesh** | Discovers monorepo workspaces, resolves cross-package memories with badges, and propagates shared security constraints. |
 | [`muse-graph`](.agents/skills/muse-graph/SKILL.md) | **AST Code Investigation** | Indexes `.codegraph`/`.graphify` symbols and queries symbol-matching decisions with `+0.2` graph overlap bonus. |
 | [`muse-wiki`](.agents/skills/muse-wiki/SKILL.md) | **Knowledge Compounding** | Compiles confirmed memories into Obsidian-compatible Markdown pages (`[[wikilinks]]`) and entity co-occurrence graphs. |
 | [`muse-brief`](.agents/skills/muse-brief/SKILL.md) | **Daily Hygiene & Loops** | Generates morning briefings, tracks 90/180-day staleness decay, and surfaces unresolved transcript commitments. |
@@ -565,7 +574,7 @@ memory user set "- Prefers TypeScript, Bun, and ultra terse responses"
 
 ```bash
 bun install
-bun test          # 322 passed across 58 test files (1305 assertions)
+bun test          # 497 passed across 84 test files (2190 assertions)
 bun run typecheck # 0 static type errors
 bun run build     # Clean bundled distribution build (dist/index.js)
 ```