musememory 1.10.0 → 2.0.0

package/.agents/standards/system-design.md

@@ -0,0 +1,67 @@
+# 📐 System, Domain & Resilience Design Standards
+
+> Synthesized from: Eric Evans' *Domain-Driven Design*, Michael Nygard's *Release It!*, and High-Reliability Distributed Systems Engineering.
+
+---
+
+## 1. Domain-Driven Design Principles (Eric Evans)
+
+### Ubiquitous Language & Bounded Contexts
+- **Ubiquitous Language**: Code entities, method names, and test descriptions must use the exact business terminology of the domain expert within that bounded context.
+- **Explicit Context Boundaries**: A domain model is valid only inside its own bounded context. Never create a company-wide "god" model. Translate across context boundaries using explicit Anti-Corruption Layers (ACL) or Published Languages.
+- **Core Domain Distillation**: Focus rich modeling on the core strategic domain; keep supporting and generic subdomains lightweight.
+
+### Building Blocks
+- **Entities**: Objects with persistent identity over time. Entities must protect their own valid state transitions (no public setters for arbitrary mutations).
+- **Value Objects**: Immutable objects defined strictly by their attributes. Construction must guarantee validity; equality is determined by value.
+- **Aggregates & Consistency Boundaries**: Aggregates are strict consistency boundaries. Keep them as small as possible. All modifications must route through the aggregate root; reference other aggregates by identity only.
+- **Repositories**: Repositories exist for aggregate roots, not individual database tables. Return domain objects, not raw database rows or ORM records.
+- **Domain Services**: Use domain services only for business logic that naturally spans multiple entities or value objects.
+
+---
+
+## 2. Production Stability & Resilience (Michael Nygard)
+
+### Stability Mindset
+Assume production is hostile and fragile: every dependency can be slow, every queue can fill, every cache can miss or stampede.
+
+### Dependency Protection
+- **Mandatory Timeouts**: Every outbound network call, database query, or inter-service request MUST have an explicit, intentional timeout. Infinite waits are strictly forbidden.
+- **Disciplined Retries**: Retry only idempotent operations. Always apply exponential backoff with random jitter to prevent retry storms. Never retry permanent 4xx or validation failures.
+- **Circuit Breakers**: Protect unstable downstreams by tripping to fast-fail mode when error rates spike.
+- **Bulkheads & Isolation**: Isolate slow or failure-prone dependencies in dedicated resource pools so one failing third-party does not exhaust the entire system's thread or connection pool.
+
+### Overload & Capacity Control
+- **Back Pressure**: Implement explicit back pressure when producers outpace consumers.
+- **Load Shedding**: Gracefully reject low-priority requests under extreme load to preserve core system availability.
+- **Dead-Letter Queues**: Every asynchronous queue must define poison-message handling and a dead-letter queue.
+
+---
+
+## 3. Explicit Persistence & Data Mapping Boundaries
+
+- **Named Mapping Methods**: Persistence-layer ↔ domain-model conversions (Payload CMS, Neon, Supabase, SQLite, ORMs) MUST use explicit named methods (e.g., `fromRecord()`, `toRecord()`, `toDTO()`).
+- **Prohibited**: Implicit casting, unchecked `as unknown as Type`, or field-by-field object spreading (`{ ...dbRow }`) across architectural boundaries.
+- **Data Protection**: Prevent internal database columns, metadata, or sensitive properties from leaking to client components or public API responses.
+
+---
+
+## 4. Database Safety & Migration Rehearsal Protocol
+
+- **Rehearsal Before Proposal**: Before proposing or applying database migrations (Drizzle, Prisma, SQL), rehearse the full migration history against a fresh throwaway database (`npx create-db@latest --json` or local isolated container) and verify test passes.
+- **Destructive Operation Gate**: Never run destructive operations (`DROP TABLE`, `TRUNCATE`, `db push --accept-data-loss`, `migrate reset`) on staging or production without explicit authorization.
+- **Zero Inlined Credentials**: Store connection strings strictly in `.env.local` or environment secrets. Never commit connection URIs to version control.
+
+---
+
+## 5. Mathematical & Algorithmic Exactness
+
+- **Concrete Scoring Formulas**: Algorithms for ranking, cache invalidation, or relevance must use explicit mathematical weights and decay constants ($Score = \sum W_i \cdot S_i \times e^{-\lambda \Delta t}$).
+- **Determinism & Fallback Parity**: Accelerators (e.g., SQLite FTS5 or vector indices) must maintain output parity with zero-dependency fallbacks.
+
+---
+
+## 6. API & Library Fidelity (Zero Hallucinated Options)
+
+- **Exact Constructor Signatures**: Verify configuration keys against installed `.d.ts` definitions or local package documentation before use.
+- **Dual-Layer Specifications**: Pair human-readable YAML/JSON examples with formal machine-checkable schemas (Zod, JSON Schema, Pydantic) validated via automated tests.

package/.agents/standards/tech-stacks.md

@@ -0,0 +1,52 @@
+# 🚀 Agency Tech Stack Directions & Architectural Standards
+
+All digital products and client builds follow one of three designated architectural directions. All tooling is kept at the latest stable version.
+
+---
+
+## 🧭 Direction 1: Modern Web & High-Performance Astro
+
+> **Best For**: High-speed marketing platforms, content ecosystems, portals, and interactive agency web applications.
+
+### Core Toolchain & Stack
+- **Framework**: **Astro v7.2.x** (Server-first, content collections, hybrid rendering)
+- **Styling**: **UnoCSS v66.x** + Custom Semantic BEM CSS tokens
+- **Animations**: **Motion.dev** (Framer Motion engine for high-end web interactions)
+- **UI & Accessibility**: **Aria Builder `@latest`** (WCAG 2.2 AA compliant accessible components)
+- **Testing**: **Vitest** (Unit, component, and utility tests)
+- **Runtime & Deployment**: **`@astrojs/cloudflare`** on **Cloudflare Free Tier** or **GitHub Pages**
+- **Persistence & Analytics**: SQLite DB (when local storage/edge persistence is needed) + Cloudflare Web Analytics
+
+---
+
+## ⚡ Direction 2: Instatic (Pure HTML / Brochure & Static Sites)
+
+> **Best For**: Pure HTML brochure sites, lightweight marketing landing pages, and zero-JS static client deliverables.
+
+### Core Toolchain & Stack
+- **Engine**: **[Instatic](https://github.com/corebunch/instatic)** — Pure HTML-based static site generator
+- **Delivery**: Semantic HTML5, CSS3, minimal vanilla JS
+- **Hosting**: Cloudflare Pages / GitHub Pages (Zero compute overhead, sub-millisecond TTFB)
+- **Principle**: Zero runtime dependencies, 100/100 Lighthouse performance score by default.
+
+---
+
+## 🛍️ Direction 3: Headless E-Commerce & Dynamic CMS
+
+> **Best For**: Direct-to-Consumer (D2C) e-commerce brands, high-scale digital stores, and content-managed portals.
+
+### Core Toolchain & Stack
+- **CMS & Backend**: **Payload CMS** with official E-Commerce Module
+- **Frontend Framework**: **Next.js** (App Router, Server Components by default)
+- **Styling & Motion**: **UnoCSS** + **Motion.dev**
+- **Type Safety & Validation**: **Zod** (strict schema validation at all API boundaries)
+- **Testing**: **Vitest** (Unit, integration, and API tests)
+- **Database**: **Neon** (Serverless PostgreSQL) or **Supabase**
+- **Hosting & Infrastructure**: **Cloudflare Free / Low-Cost Tier** + edge caching for zero-to-low operational cost
+
+---
+
+## 🔒 Tech Stack Invariants
+1. **No Speculative Dependencies**: Do not introduce unlisted frameworks or heavy third-party runtime libraries without explicit human authorization.
+2. **Edge-First Hosting**: Default to Cloudflare edge deployment across all three directions to maintain zero-to-low infrastructure costs.
+3. **Accessibility Baseline**: WCAG 2.2 AA compliance is mandatory across all user-facing components.

package/.agents/standards/workflows.md

@@ -0,0 +1,54 @@
+# 🔄 Agent Development Workflows & Phase Gates
+
+> **Lifecycle Doctrine**: Every engineering task moves through deterministic phases scaled to its classification tier. Bypassing quality gates is strictly prohibited.
+
+---
+
+## 1. Scaled Task Classification Tiers
+
+To balance velocity with rigor, overhead is strictly proportional to task risk:
+
+| Classification | Scope & Criteria | Required Phases & Gates |
+| :--- | :--- | :--- |
+| **`tiny-fix`** | < 3 files, typo, CSS token tweak, no semantic/logic change | Direct edit + 1-line verification check. Skips heavy planning. |
+| **`quick-win`** | < 1 module, localized bug fix, small feature enhancement | Scoping → Implement → Targeted Test & Review. |
+| **`feature`** | Multi-file additions, new endpoints, stateful UI flows | Full 5-Phase Pipeline (Scoping → Plan → Implement → Review → Ship). |
+| **`architecture-change`** | Core schemas, database migrations, auth, global router/build refactors | Full 5-Phase Pipeline + Architecture Decision Record (ADR) + Nexus Gate. |
+
+---
+
+## 2. The 5-Phase Execution Pipeline
+
+```
+[ 📋 1. Scoping & Intake ] ──► [ 📐 2. Plan ] ──► [ ⚡ 3. Implement ] ──► [ 🛡️ 4. Review & Hardening ] ──► [ 🚢 5. Ship & Archive ]
+```
+
+### Phase 1: 📋 Scoping & Intake (Muse)
+- **Decomposition Gate**: For multi-feature requests, decompose the input into a structured Feature Inventory before writing individual specifications.
+- **Classification Freeze**: Lock task classification (`tiny-fix`, `quick-win`, `feature`, `architecture-change`). Silent scope expansion mid-implementation is prohibited. If scope grows, pause and notify the user.
+- Identify the target tech direction (Astro / Instatic / Payload + Next.js).
+- Load active constraints from `./.agents/context/` and `./.memory`.
+
+### Phase 2: 📐 Plan & Design
+- For `feature` and `architecture-change` tasks, generate an implementation plan inside `.agents/artifacts/`.
+- Satisfy the **Task Start Gate**:
+  1. **Goal**: What exact outcome is required?
+  2. **Mechanism**: What is the root cause / structural design?
+  3. **Proof**: What exact automated or visual observation proves success?
+
+### Phase 3: ⚡ Implement (Sol / Jasper)
+- Apply **The Confidence Gate** (<80% Stop, 80-90% State Assumption, >90% Proceed).
+- Apply **Read-Before-Write**: Inspect target files, imported types, and callers before modifying code.
+- Apply **Preparatory Refactoring**: Restructure cleanly before introducing functional changes.
+- Respect code limits (pure UI components < 200 lines, custom hooks `use<Feature><Action>`).
+
+### Phase 4: 🛡️ Review & Hardening (Nexus Quality Gate)
+- Run targeted automated tests (`bun test` / `vitest`).
+- Run the Vibeguard SecretScan (`bun ~/.config/LIFEOS/runtime/TOOLS/SecretScan.ts .`).
+- Verify WCAG 2.2 AA accessibility and responsive mobile breakpoints.
+
+### Phase 5: 🚢 Ship & Archive (Crew)
+- Create structured Conventional Commits following the Git standard.
+- **Archive Work Artifacts**: Move completed plans or temporary scratchpads into `.agents/archive/` using the timestamped format `[title]-[YYYYMMDD-HHMMSS].md`.
+- **DOX Pass**: Update `./.agents/context/current.md` and the nearest owning `AGENTS.md`.
+- **Memory Update**: Persist newly confirmed invariants or architectural decisions into `./.memory`.

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-319%20Passed-brightgreen?style=for-the-badge&logo=checkmarx)
+![CI Tests](https://img.shields.io/badge/Tests-480%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,8 +24,23 @@
 
 ---
 
+## 🚀 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.
+
+---
+
 ## 📑 Table of Contents
 
+- [🚀 What's New in v2.0.0](#-whats-new-in-v200-autonomous-cognitive-engine-major-overhaul)
 - [💡 What is Muse Memory? (TL;DR)](#-what-is-muse-memory-tldr)
 - [✨ Key Feature Highlights](#-key-feature-highlights)
 - [⚡ Quick Start & Installation](#-quick-start--installation)
@@ -368,13 +383,28 @@ Navigate to `http://localhost:2222` to access:
 ## 📖 Deep Technical References & Documentation
 
 <details>
-<summary><b>🔌 Complete MCP Tool Reference (29 Tools)</b> — <i>Click to expand</i></summary>
+<summary><b>🔌 Complete MCP Tool Reference (61 Tools across 6 Profiles)</b> — <i>Click to expand</i></summary>
 
-When registered as an MCP server, `musememory` exposes the following native tools:
+When registered as an MCP server, `musememory` exposes the following native tools (filtered dynamically into role-tailored profiles to eliminate tool bloat):
 
 | MCP Tool | Execution Phase | Description |
 | :--- | :--- | :--- |
-| `get_context` | **Session Start** | Fetches Top-$K$ ranked memories, `USER.md` profile, and active `CURRENT.md` constraints. |
+| `muse_context` | **Flagship Fusion** | Single-call fused orchestrator combining search, active file, symbol, error messages, and task intent under strict knapsack token budgets. |
+| `muse_health` | **Quality Gate** | 5-Pillar Project Health Gate: audits store integrity, code anchors, doc/code alignment, anti-pattern sentry, and technical debt with A-F grading and pass/fail status. |
+| `muse_why` | **Cognition / "Why"** | Explains *why* code was designed the way it is by reconstructing past ADRs, bug fixes, trade-offs, and timeless rules. |
+| `muse_bug_clusters` | **Fragility Hotspots** | Categorizes recurring bugs into 5 root causes with subsystem fragility scoring. |
+| `muse_tech_debt` | **Technical Debt** | Scans code and memory for TODO/FIXME markers, unsafe `as any` casts, and drifted anchors. |
+| `muse_memory_for_code`| **Code-to-Memory** | Queries all memories, ADRs, constraints, and bugs associated with a code file and symbol. |
+| `muse_code_for_memory`| **Memory-to-Code** | Resolves all native code anchors and affected source files for a given memory entry. |
+| `memory_adr_record` / `list` | **Architecture Decisions** | Records and queries first-class Architecture Decision Records with native code anchors and options considered. |
+| `memory_drift_audit` | **Drift Engine** | Audits bi-directional documentation $\longleftrightarrow$ code drift across 6 alignment states (`DOCUMENTED`, `IMPLEMENTED`, `PARTIAL`, `CONFLICTING`, `STALE`, `MISSING`). |
+| `memory_capture_negative` | **Negative Sentry** | Records failed approaches, anti-patterns, and reproduction commands to prevent repeating mistakes. |
+| `memory_promote_scope` | **Scoped Promotion** | Promotes memory along 3-tier ladder (`local` $\rightarrow$ `project` $\rightarrow$ `global`) with 5× repeated success policy and universal generalization. |
+| `memory_archive` / `rehydrate` | **Archival Lifecycle** | Evaluates and manages `active` $\rightarrow$ `cold` $\rightarrow$ `dormant` $\rightarrow$ `archived` lifecycle with query rehydration. |
+| `memory_lifecycle_stats` / `sweep` | **Lifecycle Sweeper** | Reports store-wide lifecycle statistics and executes sweep transitions for aging memories. |
+| `anchor_create` / `verify` / `audit` | **Code Identity** | Creates, verifies, and audits line-independent structural code anchors. |
+| `profile_list` / `profile_switch` | **Tool Management** | Lists and switches task-focused MCP profiles (`core`, `coding`, `debugging`, `review`, `architecture`, `maintenance`). |
+| `get_context` | **Session Start** | Fetches Top-$K$ ranked memories, `USER.md` profile, active `CURRENT.md` constraints, and supports `--tier 0|1|2`. |
 | `search` | **Investigation** | Searches memory units with query, token budget, project, type, and verification filters. |
 | `memory_current` | **Constraints** | Reads or appends active project working constraints (`CURRENT.md`). |
 | `memory_get_user_profile` | **Context Loading** | Reads active `USER.md` persona and communication preferences. |
@@ -386,6 +416,13 @@ When registered as an MCP server, `musememory` exposes the following native tool
 | `memory_mark_stale` | **Deprecation** | Flags decaying knowledge with deprecation rationale. |
 | `memory_reject` | **Hypothesis Refutation** | Marks invalidated hypotheses as rejected. |
 | `memory_delete` | **Purge** | Permanently deletes an entry and records audit ledger log. |
+| `memory_source_add` / `list` | **Provenance** | Records external docs/RFCs/URLs into `.memory/sources.json` and queries sources. |
+| `memory_claim_record` / `list` | **Claim Ledger** | Records evidence-backed claims tagged with `[RAW]`, `[FETCH]`, `[SEARCH]`, `[INFER]`. |
+| `memory_freeze_run` / `list` | **Execution Snapshots** | Freezes immutable task snapshots with file inventory and SHA-256 memory hashes. |
+| `memory_prompt_list` / `get` / `run` | **Prompt Templates** | Manages and executes native structured prompt templates with live context injection. |
+| `memory_rollup` | **Temporal Compounding** | Aggregates atomic memories into weekly, monthly, and quarterly rollups and updates `HOT.md`. |
+| `memory_loop_record` / `status` | **Gauntlet Loops** | Multi-agent iteration ledger and plateau/regression detector (`.memory/iterations.jsonl`). |
+| `memory_verify_strict` | **Integrity Gate** | Zero-tolerance audit verifying secrets, referential links, wikilinks, claims, and candidates. |
 | `memory_tree_search` | **Tree Retrieval** | Hierarchical reasoning search across partitioned memory shards. |
 | `memory_wiki_compile` | **Wiki Compiler** | Compiles confirmed memories into Obsidian-compatible Markdown pages. |
 | `memory_wiki_search` / `get` | **Wiki Reading** | Searches and reads compiled concept and entity wiki pages. |
@@ -410,7 +447,7 @@ When registered as an MCP server, `musememory` exposes the following native tool
 </details>
 
 <details>
-<summary><b>💻 Full CLI Command Matrix (35 Commands)</b> — <i>Click to expand</i></summary>
+<summary><b>💻 Full CLI Command Matrix (42 Commands)</b> — <i>Click to expand</i></summary>
 
 ```bash
 memory <command> [arguments] [flags]  # alias: musememory
@@ -418,6 +455,7 @@ memory <command> [arguments] [flags]  # alias: musememory
 
 | Command | Arguments / Flags | Description |
 | :--- | :--- | :--- |
+| `health` | `[--json] [--global]` | **Unified 5-Pillar Project Health Gate**: audits Store Integrity, Code Anchors, Drift, Sentry, and Tech Debt with A-F grading and pass/fail gate. |
 | `install` | `[path] [--global]` | **One-line complete setup**: initializes `.memory/`, `USER.md`, and auto-wires coding agents. |
 | `doctor` | `[path] [--global]` | **System diagnostic**: checks SQLite primary, schemas, secrets, and MCP connections. |
 | `uninstall` | `[agent] [--purge] [--dry-run]` | **Clean uninstaller**: unwires MCP configs (and optionally purges `.memory/`). |
@@ -428,7 +466,7 @@ memory <command> [arguments] [flags]  # alias: musememory
 | `detect` | *(none)* | Scan workstation and local workspace for 29 external memory systems. |
 | `migrate` | `[--provider P] [--all] [--dry-run] [--overwrite]` | Migrate memories into Muse Memory preserving active/archived state. |
 | `ui` | `[--port N] [--global]` | Launch 6-view Cognitive Studio dashboard (default port: `2222`). |
-| `context` | `[query] [--token-budget N] [--limit N]` | Retrieve Top-$K$ ranked active context for prompt injection. |
+| `context` | `[query] [--token-budget N] [--limit N] [--tier 0\|1\|2]` | Retrieve Top-$K$ ranked active context for prompt injection. |
 | `search` | `<query> [--limit N] [--token-budget N] [--type T]` | Ranked multi-factor token search with score breakdown. |
 | `search-transcript` | `<query> [file.jsonl] [--window N]` | Full-text search past transcripts with dialogue context windows. |
 | `learn` / `sync-chats` | `[--confirm] [--force] [--max N]` | **Universal auto-learner**: auto-discovers and distills memories from all agent chats across host machine. |
@@ -441,6 +479,13 @@ memory <command> [arguments] [flags]  # alias: musememory
 | `mark-stale` | `<id> [--reason <text>]` | Mark an entry stale with deprecation rationale. |
 | `reject` | `<id> [--global]` | Mark an entry rejected. |
 | `delete` | `<id> [--reason <text>]` | Permanently delete a memory entry and record audit event. |
+| `source` | `add\|list\|show <url> [--title T] [--type T]` | Manage external documentation and URLs in provenance Source Ledger (`.memory/sources.json`). |
+| `claim` | `record\|list\|show <text> [--confidence RAW\|FETCH\|SEARCH\|INFER]` | Record and query verifiable claims connected to sources (`.memory/claims.json`). |
+| `freeze` | `--task <task.md\|text> [--run-id R]` | Capture immutable execution snapshot with file inventory and SHA-256 memory hashes. |
+| `prompt` | `list\|show\|run <name> [--args k=v,...]` | Manage and run structured prompt templates with live context injection. |
+| `rollup` | `--period week\|month\|quarter [--date YYYY-MM-DD]` | Multi-scale temporal compounding and `.memory/HOT.md` working memory cache compiler. |
+| `loop` | `record\|status\|clear` | Multi-agent Gauntlet iteration ledger and plateau/regression detector. |
+| `verify` | `<id> [--timeout S] [--strict]` | Execute a fix entry's test command or run full strict integrity gate. |
 | `audit` | `[--operation OP] [--entry-id ID] [--limit N]` | Query append-only operational audit trail (`.memory/audit.jsonl`). |
 | `link` | `<id> --related <id1,id2>` | Synchronize bidirectional relation links between entries. |
 | `export` / `import` | `[--out <file.json>]` / `<file.json>` | Export and import portable JSON memory snapshots. |
@@ -505,7 +550,7 @@ memory user set "- Prefers TypeScript, Bun, and ultra terse responses"
 
 ```bash
 bun install
-bun test          # 319 passed across 57 test files (1294 assertions)
+bun test          # 322 passed across 58 test files (1305 assertions)
 bun run typecheck # 0 static type errors
 bun run build     # Clean bundled distribution build (dist/index.js)
 ```
@@ -517,13 +562,18 @@ bun run build     # Clean bundled distribution build (dist/index.js)
 <details>
 <summary><b>🔮 Sprint & Roadmap Lifecycle (Requested ➔ Planned ➔ In Progress ➔ Done)</b> — <i>Click to expand</i></summary>
 
-Muse Memory features are developed in structured sprints moving across 4 deterministic lifecycle phases. Every sprint is delivered via PR from `dev` to `main` with associated GitHub milestones. Live tracking: [GitHub Issues & Milestones](https://github.com/harshsinghmp/musememory/issues).
+Muse Memory features are developed in structured sprints moving across 4 deterministic lifecycle phases following strict `vX.Y.Z` semantic versioning. Every sprint is delivered via PR from `dev` to `main` with associated GitHub milestones. Live tracking: [GitHub Issues & Milestones](https://github.com/harshsinghmp/musememory/issues).
 
 ```
 [ 📋 Requested ] ──► [ 📅 Planned ] ──► [ ⚡ In Progress ] ──► [ ✅ Done ]
  (Issues / PRs)     (Sprint Backlog)    (Active PR / Milestone)  (Shipped to Main)
 ```
 
+### 🏷️ Semantic Versioning Protocol (`vX.Y.Z`)
+- **`X` (Major)**: Breaking architectural changes, core schema shifts, or protocol overhauls (`vX.0.0`).
+- **`Y` (Feature)**: Substantive new agent capabilities, MCP tools, or CLI subcommands (`vX.Y.0`).
+- **`Z` (Minor / Hotfix / Critical Fix)**: Bug remediations, security patches, performance, and urgent hotfixes (`vX.Y.Z`).
+
 ### 📋 Phase 1: Requested (Backlog)
 *Incoming community proposals, agent adapters, and feature requests pending sprint triage:*
 - [ ] Multi-Agent Consensus Verification Protocol (cross-agent memory agreement)
@@ -532,9 +582,13 @@ Muse Memory features are developed in structured sprints moving across 4 determi
 
 ### 📅 Phase 2: Planned
 *Confirmed high-leverage features scheduled for upcoming sprints:*
-- [ ] Multi-Agent Consensus Verification Protocol (cross-agent memory agreement)
-- [ ] Continuous Background Memory Compaction & Pruning Cron
-- [ ] Export to Local Vector GGUF Embedding Index
+- [ ] **Tiered Retrieval Engine**: Deterministic Tier 0 (manifest), Tier 1 (invariants), Tier 2 (bounded bodies) knapsack retrieval
+- [ ] **Provenance & Claim Ledgers**: Direct memory citations with `[RAW]`, `[FETCH]`, `[SEARCH]`, and `[INFER]` confidence tagging
+- [ ] **Frozen Context Snapshots**: Immutable SHA-256 state tracking for reproducible agent execution
+- [ ] **Native Prompt Registry**: Declarative prompt library & runner (`.memory/prompts/*.md`, `memory prompt run`)
+- [ ] **Temporal Compounding**: Multi-scale Day $\to$ Week $\to$ Quarter wiki rollups & `.memory/HOT.md` cache
+- [ ] **Gauntlet Iteration Ledger**: Multi-turn improvement loop tracking and plateau detection
+- [ ] **Strict Health Gate**: Comprehensive `memory verify --strict` referential, link, and secret validator
 
 ### ⚡ Phase 3: In Progress (Active Sprint / PR)
 *Currently under active development on dedicated feature branches:*