mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/015-subagent-task-delegation.rispec.md

@@ -0,0 +1,146 @@
+# RISE-015: Subagent Task Delegation
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/015-subagent-task-delegation.rispec.md
+
+## Creative Intent
+
+mia-code enables agents to delegate specialized subtasks to other agents, creating a collaborative multi-agent workflow within a single session. When a primary agent encounters a task better suited to a specialist — complex multi-file search, background code analysis, focused review — it spawns a subagent to handle it. The subagent works within its own permission boundary, returns results, and the parent agent synthesizes. This mirrors how effective teams work: leaders delegate, specialists execute, results converge. The `@mention` syntax makes delegation feel natural — like addressing a colleague in a conversation.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code processes every request with a single agent — there is no delegation or task splitting
+- Complex multi-step tasks (e.g., "find all auth patterns and then refactor them") are handled sequentially by one agent, which may lose focus or context across steps
+- The engine (Gemini/Claude) has a single context window — large codebase searches consume tokens that could be used for reasoning
+- There is no way to run a focused search in parallel with an ongoing conversation
+- The unifier interprets all output through one lens, regardless of whether the output came from exploration, analysis, or execution
+
+**Desired State:**
+- Primary agents can spawn subagents via `@mention` syntax in user messages or programmatic delegation
+- Subagents run in their own context with their own permissions but share the session's file system state
+- Subagent results flow back to the parent agent, which synthesizes and presents them to the user
+- Delegation is explicit and observable — the user sees when a subtask is delegated and when it completes
+- Subagents have limited tool access compared to primary agents (configurable per agent definition)
+- The parent agent decides when to delegate versus handle directly, based on task complexity and agent availability
+
+## Desired Outcome Definition
+
+A user types `@explore find all files importing the Database class` in their message. The active primary agent recognizes the `@explore` mention, extracts the task, and delegates to the explore subagent. The explore agent searches the codebase, returns results, and the primary agent presents the synthesized findings to the user.
+
+## Natural Language Functional Description
+
+### Delegation Syntax
+
+Users trigger delegation by prefixing a task with `@agentname`:
+
+```
+@explore find all uses of the createSession function
+@general analyze the dependency graph of the auth module
+@reviewer check the last 3 file changes for security issues
+```
+
+The `@mention` is parsed from the user's message. Everything after the agent name is treated as the delegated task prompt.
+
+### Delegation Flow
+
+1. **Parse**: The system detects `@agentname` in the user's message and extracts the agent name and task
+2. **Validate**: The named agent must exist and have mode "subagent" or "all" — primary-only agents cannot be invoked as subagents
+3. **Context Assembly**: The subagent receives: the task prompt, relevant session context (recent messages, current file state), and its own system prompt
+4. **Execute**: The subagent processes the task within its permission boundary, using its configured model
+5. **Return**: The subagent's response is returned to the parent agent as a structured result
+6. **Synthesize**: The parent agent incorporates the subagent's results into its response to the user
+7. **Display**: The UI shows the delegation as a nested thread — the user sees the subagent's work and the parent's synthesis
+
+### Subagent Context
+
+Subagents receive a focused context, not the full conversation history:
+
+- **Task prompt**: The text following the `@mention`
+- **Recent context**: The last N messages from the session (configurable, default 5) for conversational continuity
+- **File state**: Full access to the session's file system (subject to the subagent's permissions)
+- **Project metadata**: Project name, root directory, detected language/framework
+
+Subagents do not receive:
+- The full message history (to keep their context window focused)
+- The parent agent's system prompt (they use their own)
+- Other subagents' results (unless explicitly included in the task prompt)
+
+### Parent Agent Synthesis
+
+When a subagent returns results, the parent agent:
+1. Receives the subagent's response as a structured message with metadata (agent name, execution time, tool calls made)
+2. Evaluates the results in the context of the ongoing conversation
+3. May use the results directly, summarize them, or combine them with its own analysis
+4. Presents a unified response to the user that credits the subagent's contribution
+
+### UI Representation
+
+Delegation appears in the terminal UI as a nested thread:
+
+```
+You: @explore find all files that use the EventBus
+
+  ┌─ explore agent ──────────────────────────────┐
+  │ Searching codebase...                         │
+  │ Found 12 files importing EventBus:            │
+  │   src/session/manager.ts:3                    │
+  │   src/engine/gemini.ts:7                      │
+  │   src/engine/claude.ts:5                      │
+  │   ... (9 more)                                │
+  │ ⏱ completed in 1.2s                           │
+  └───────────────────────────────────────────────┘
+
+🤖 Build agent: Found 12 files using EventBus. The heaviest usage 
+   is in the session management layer (4 files) and engine 
+   adapters (3 files). Want me to refactor any of these?
+```
+
+### Programmatic Delegation
+
+Beyond user-initiated `@mention`, the primary agent can decide to delegate programmatically. When the agent's reasoning determines that a subtask would benefit from delegation, it emits a delegation request:
+
+- The agent recognizes a complex search task → delegates to `@explore`
+- The agent needs a focused code review → delegates to `@reviewer`
+- The agent needs multi-step analysis → delegates to `@general`
+
+Programmatic delegation uses the same flow as user-initiated delegation but is triggered by the agent's own reasoning rather than an explicit `@mention`.
+
+### Delegation Limits
+
+To prevent runaway delegation chains:
+- Maximum delegation depth: 2 (a subagent can delegate to another subagent, but no further)
+- Maximum concurrent subagents: 3 (additional delegations queue)
+- Subagent timeout: 60 seconds default (configurable) — if a subagent exceeds the timeout, its partial results are returned
+- Subagents cannot delegate to primary-mode-only agents
+- A subagent cannot invoke its parent agent (no circular delegation)
+
+### Error Handling
+
+When delegation fails:
+- **Agent not found**: The parent agent is informed and can handle the task itself or suggest alternatives
+- **Permission denied**: The subagent's permission ruleset prevented the requested operation — the parent agent is informed with the specific denial reason
+- **Timeout**: Partial results are returned with a timeout indicator — the parent agent decides whether to retry, delegate to a different agent, or handle manually
+- **Subagent error**: Errors are propagated to the parent agent as structured error objects (see RISE-006)
+
+## Supporting Structures
+
+- **Multi-Agent System (RISE-009)** defines the agent architecture and mode system that delegation relies on
+- **Agent Permission Rulesets (RISE-011)** enforces permission boundaries for subagents independently
+- **Agent Prompt Templates (RISE-012)** provides subagent-specific system prompts optimized for focused tasks
+- **Agent Model Selection (RISE-016)** enables subagents to use cost-appropriate models for their tasks
+- **Event Bus (RISE-002)** broadcasts delegation events (start, complete, error) to the UI
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Large Codebase Exploration:**
+A developer working in a monorepo asks the build agent to refactor the authentication module. The build agent delegates `@explore find all files importing AuthService and map their dependency relationships` to the explore agent. The explore agent uses a fast model to scan thousands of files in seconds, returns a dependency map. The build agent uses this map to plan a safe refactoring order, then executes the changes file by file.
+
+**Scenario 2 — Review Before Commit:**
+After making several changes in build mode, the developer types `@reviewer check all files I modified this session for bugs or security issues`. The reviewer subagent reads the modified files, analyzes the changes, and returns a focused review. The build agent presents the review and asks whether to proceed with committing or address the findings first.
+
+**Scenario 3 — Parallel Research:**
+The developer asks: "Refactor the database layer to use connection pooling. @explore find how connections are currently managed. @general research best practices for connection pooling in Node.js." Both subagents execute concurrently. The explore agent maps the current implementation while the general agent provides architectural guidance. The build agent synthesizes both results into a refactoring plan.
+
+**Scenario 4 — Cascading Delegation:**
+The developer asks the build agent to migrate a module from JavaScript to TypeScript. The build agent delegates `@explore find all .js files in src/auth/` to map the migration scope. The explore agent returns the file list. The build agent then processes each file, converting it to TypeScript. For complex type inference, it delegates `@general analyze the runtime types used in src/auth/middleware.js` to get detailed type information before converting.

package/rispecs/borrowed_from_opencode/016-agent-model-selection.rispec.md

@@ -0,0 +1,151 @@
+# RISE-016: Agent Model Selection
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/016-agent-model-selection.rispec.md
+
+## Creative Intent
+
+mia-code enables developers to assign different LLM models to different agents, optimizing for cost, speed, and capability across the agent roster. A fast, cheap model powers rapid codebase exploration. A powerful, expensive model handles complex code generation. A balanced model manages code review. Each agent uses the right tool for its job — the explore agent does not need Opus-level reasoning for `grep` and `glob`, and the build agent should not be constrained to a Flash-tier model for complex refactoring. Model selection turns the agent system into a cost-efficient ensemble.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code selects between two engines: Gemini CLI and Claude CLI — this is a binary choice, not a model selection
+- The engine choice applies globally to the entire session — there is no per-task or per-agent model variation
+- Both engines use their default models (Gemini 2.5 Pro, Claude Sonnet) — there is no mechanism to specify a model variant
+- Cost optimization is impossible — every interaction uses the same model regardless of task complexity
+- Simple tasks (file listing, content search) consume the same expensive tokens as complex tasks (architecture design, code generation)
+- The `engineChoice` field in session state stores "gemini" or "claude" but not a specific model identifier
+
+**Desired State:**
+- Each agent definition includes an optional `model` field specifying `{providerID, modelID}`
+- When no model is specified, the agent uses the session's global default
+- Agents use their assigned model for all interactions, regardless of the session default
+- Model selection is independent of agent permissions and prompt — a model change does not affect what the agent can do
+- Users can change an agent's model mid-session via config update
+- The system tracks token usage and cost per agent for visibility
+
+## Desired Outcome Definition
+
+Each agent in mia-code uses its configured model for all LLM interactions. The explore agent defaults to a fast model, the build agent to a powerful one, and users can override any agent's model via configuration. Model selection is transparent, cost-aware, and independent of other agent properties.
+
+## Natural Language Functional Description
+
+### Model Reference Format
+
+A model reference is a two-field object:
+
+```typescript
+interface ModelReference {
+  providerID: string;  // API provider identifier
+  modelID: string;     // specific model within the provider
+}
+```
+
+Provider IDs map to configured API endpoints:
+- `"anthropic"` → Anthropic API (Claude models)
+- `"google"` → Google AI API (Gemini models)
+- `"openai"` → OpenAI API (GPT models)
+- `"local"` → Local model server (Ollama, LM Studio, etc.)
+
+Model IDs are provider-specific strings:
+- `"claude-sonnet-4-20250514"`, `"claude-opus-4-20250514"`, `"claude-haiku-3-5-20241022"`
+- `"gemini-2.5-pro"`, `"gemini-2.5-flash"`, `"gemini-2.0-flash"`
+- `"gpt-4.1"`, `"o3"`, `"gpt-4.1-mini"`
+
+### Default Model Assignments
+
+Built-in agents have these default model preferences:
+
+| Agent | Default Model Strategy | Rationale |
+|-------|----------------------|-----------|
+| build | Session default (most capable) | Complex code generation needs top-tier reasoning |
+| plan | Session default | Analysis benefits from strong reasoning |
+| explore | Fast/cheap variant | Search tasks need speed, not deep reasoning |
+| general | Session default | Subagent tasks may be complex |
+
+The "fast/cheap variant" is resolved at runtime based on the session's provider:
+- If session uses Anthropic → explore defaults to `claude-haiku-3-5-20241022`
+- If session uses Google → explore defaults to `gemini-2.5-flash`
+- If session uses OpenAI → explore defaults to `gpt-4.1-mini`
+
+### Configuration
+
+Users set agent models in `mia-code.json`:
+
+```json
+{
+  "agent": {
+    "build": {
+      "model": {
+        "providerID": "anthropic",
+        "modelID": "claude-sonnet-4-20250514"
+      }
+    },
+    "explore": {
+      "model": {
+        "providerID": "google",
+        "modelID": "gemini-2.5-flash"
+      }
+    },
+    "reviewer": {
+      "model": {
+        "providerID": "anthropic",
+        "modelID": "claude-opus-4-20250514"
+      }
+    }
+  }
+}
+```
+
+Agents can use models from different providers within the same session. The build agent might use Claude while the explore agent uses Gemini Flash — each agent talks to its configured API endpoint independently.
+
+### Model Resolution Order
+
+When an agent needs to make an LLM call, the model is resolved in this order:
+
+1. **Agent config override**: The `model` field in the agent's definition (highest priority)
+2. **Session default**: The model selected when the session started or changed via `/model` command
+3. **Global default**: The default model from `~/.config/mia-code/config.json`
+4. **Engine fallback**: The default model of the configured engine (gemini/claude)
+
+### Runtime Model Switching
+
+An agent's model can be changed mid-session:
+- Via command: `/model build anthropic/claude-opus-4` changes the build agent's model
+- Via config edit: Modifying `mia-code.json` and reloading
+- The change takes effect on the next message — in-flight operations complete with the previous model
+
+### Cost Tracking
+
+The system tracks token usage per agent per session (input tokens, output tokens, estimated cost). Cost data is logged and optionally displayed via `/cost` command, enabling users to see the cost impact of their model choices and optimize accordingly.
+
+### Integration with mia-code Engine System
+
+The current mia-code engine system (`gemini` vs `claude` CLI selection) maps to the model reference format: `engineChoice: "gemini"` → `{providerID: "google", modelID: "gemini-2.5-pro"}`, `engineChoice: "claude"` → `{providerID: "anthropic", modelID: "claude-sonnet-4"}`. The model selection system is a superset — the engine choice becomes the session default, and per-agent overrides layer on top, preserving backward compatibility.
+
+### Provider Configuration
+
+Each provider requires API credentials and endpoint configuration in a `providers` config section. Environment variable references (prefixed with `$`) are resolved at runtime. Provider configuration is global — not per-agent. Agents reference providers by ID; the system resolves credentials from the provider config.
+
+## Supporting Structures
+
+- **Multi-Agent System (RISE-009)** defines the agents that model selection applies to
+- **Agent Definition Config (RISE-010)** provides the configuration format for model overrides
+- **Structured Logging (RISE-007)** records token usage and cost data
+- **Compaction Agent (RISE-017)** benefits from model selection — compaction uses a cheap model to summarize
+- **Instance State (RISE-003)** stores per-session cost tracking data
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Cost-Optimized Development:**
+A solo developer on a budget configures: build agent → Claude Sonnet (balanced cost/quality), explore agent → Gemini Flash (nearly free for search), plan agent → Claude Haiku (cheap analysis). Their daily cost drops from $5 to $1.50 without noticeable quality loss in exploration and planning tasks. Build tasks retain full quality where it matters most.
+
+**Scenario 2 — Cross-Provider Ensemble:**
+A team uses Claude Opus for the build agent (best code generation), Gemini Pro for the plan agent (strong analysis at lower cost), and GPT-4.1-mini for the explore agent (fast and cheap). Each model plays to its strengths. The agents don't know or care which provider powers them — the abstraction is complete.
+
+**Scenario 3 — Local Model for Sensitive Code:**
+A defense contractor configures the explore agent to use a local Ollama model — no data leaves the network for search operations. The build agent uses Claude via API for complex generation, but only for non-classified code paths. Model selection enables hybrid local/cloud architectures.
+
+**Scenario 4 — Mid-Session Upgrade:**
+A developer starts with Sonnet for the build agent. Midway through a complex refactoring, they realize they need stronger reasoning. They run `/model build anthropic/claude-opus-4` and the next message uses Opus. The session context is preserved — only the model changes. When the hard part is done, they switch back to Sonnet to save costs.

package/rispecs/borrowed_from_opencode/017-compaction-agent.rispec.md

@@ -0,0 +1,150 @@
+# RISE-017: Compaction Agent
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/017-compaction-agent.rispec.md
+
+## Creative Intent
+
+mia-code enables long-running development sessions without context window exhaustion by employing a specialized compaction agent that summarizes older conversation history into a condensed, high-signal representation. As sessions grow, the compaction agent distills verbose tool outputs, intermediate reasoning, and redundant exchanges into a compact summary that preserves key decisions, file modifications, error resolutions, and current task state. The developer's working context remains sharp and focused no matter how long the session runs — the agent remembers what matters and forgets what doesn't.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code sessions accumulate messages without limit — long sessions consume ever-growing context windows
+- The underlying engines (Gemini/Claude CLI) have finite context limits — exceeding them causes truncation or errors
+- Verbose tool outputs (full file contents, large command outputs, search results) inflate context rapidly
+- There is no mechanism to summarize or compress older messages — every historical message occupies context tokens
+- Long sessions degrade in quality as the model loses access to early decisions obscured by later noise
+- Session persistence (`~/.mia-code-sessions.json`) stores full message history, growing storage over time
+- The unifier's dual perspective adds interpretive text to every exchange, further inflating context
+
+**Desired State:**
+- A compaction agent monitors session message count and automatically compresses older messages when a threshold is exceeded
+- Compacted summaries replace detailed history — recent messages remain verbatim
+- The summary preserves: file modification records, key decisions, error resolutions, current task state, and important code snippets
+- The summary discards: verbose tool outputs, intermediate reasoning chains, redundant exchanges, large file contents, and raw search results
+- Compaction runs in the background without interrupting the developer's workflow
+- Multiple compaction rounds can occur in a long session — each round compresses the oldest uncompacted messages
+- The compacted context is smaller but semantically equivalent for ongoing work
+
+## Desired Outcome Definition
+
+When a mia-code session exceeds a message threshold (default: 50 messages), the compaction agent automatically summarizes older messages into a condensed context block. Recent messages (default: last 20) remain verbatim. The session continues seamlessly with the compacted history, maintaining coherence while reducing token consumption.
+
+## Natural Language Functional Description
+
+### Compaction Trigger
+
+Compaction is triggered when:
+- The session message count exceeds the configured threshold (default: 50)
+- The estimated token count of the conversation exceeds 80% of the model's context window
+- The user explicitly requests compaction via `/compact` command
+
+The system checks for compaction need after every agent response. When triggered, compaction runs asynchronously — the developer can continue working while compression happens in the background.
+
+### Compaction Agent Definition
+
+The compaction agent is a specialized internal agent:
+
+```json
+{
+  "name": "Compaction Agent",
+  "mode": "subagent",
+  "hidden": true,
+  "model": {
+    "providerID": "auto",
+    "modelID": "cheapest-available"
+  },
+  "permissions": [
+    {"permission": "read", "action": "allow"},
+    {"permission": "*", "action": "deny"}
+  ]
+}
+```
+
+Key properties:
+- **Hidden**: Does not appear in agent list or Tab switcher
+- **Read-only**: Can only read — cannot edit files, run commands, or modify state
+- **Cheap model**: Uses the most cost-effective model available (e.g., Gemini Flash, Haiku) since summarization does not require top-tier reasoning
+- **Subagent mode**: Only invocable internally by the system, never by the user directly
+
+### Compaction Algorithm
+
+**Step 1 — Segment Selection:**
+Divide the conversation into two segments:
+- **Compactable segment**: Messages from the start of the session (or last compaction) up to the retention boundary
+- **Retained segment**: The most recent N messages (default: 20) that remain verbatim
+
+**Step 2 — Information Extraction:**
+The compaction agent analyzes the compactable segment and extracts:
+- **File modifications**: Every file created, edited, or deleted, with a summary of changes
+- **Key decisions**: Choices made by the developer or agent that affect the project direction
+- **Error resolutions**: Problems encountered and how they were resolved
+- **Current task state**: What the developer is working on and where they left off
+- **Important code patterns**: Architectural patterns, conventions, or constraints discovered
+- **Tool results summary**: Condensed versions of search results, build outputs, and test results
+
+**Step 3 — Summary Generation:**
+The compaction agent generates a structured markdown summary with sections for: File Modifications (files created/edited/deleted with change summaries), Key Decisions (choices affecting project direction), Error Resolutions (problems and fixes), Current Task State (active work and next steps), and Context Notes (project conventions and preferences).
+
+**Step 4 — History Replacement:**
+The compacted summary replaces the compactable segment in the session's message history. The conversation now contains:
+1. The compaction summary (as a system message)
+2. The retained segment (verbatim recent messages)
+
+### Multiple Compaction Rounds
+
+In very long sessions, compaction can occur multiple times. Each round:
+- Takes the current summary + the next batch of compactable messages
+- Generates an updated summary that incorporates the new information
+- The summary grows incrementally, but much slower than the raw message history
+
+A session with 200 messages might compact at messages 50, 100, and 150 — each time updating the summary and retaining the latest 20 messages.
+
+### Preserved vs. Discarded Information
+
+**Always preserved:**
+- File paths and modification summaries (what changed, not the full diff)
+- Decision rationale (why a particular approach was chosen)
+- Error messages and their resolutions
+- Current task context and next steps
+- Project conventions discovered during the session
+- Configuration changes made
+
+**Always discarded:**
+- Full file contents shown during read operations (preserved as "read file X, N lines")
+- Raw bash command output exceeding 10 lines (preserved as "ran command X, output summary")
+- Intermediate reasoning chains that led to dead ends
+- Duplicate questions or re-explanations
+- Verbose tool parameter listings
+- The unifier's 🧠/🌸 commentary on compacted messages (only recent commentary retained)
+
+### User Control
+
+Users configure compaction in `mia-code.json` with: `enabled` (default: true), `messageThreshold` (default: 50), `retainCount` (default: 20), `autoCompact` (default: true). The `/compact` command triggers immediate compaction regardless of message count — useful when early conversation is no longer relevant or the session approaches context limits.
+
+### Integration with Session Persistence
+
+The full pre-compaction history is archived in a separate file for forensic recovery. The active session file contains only the summary + retained messages, enabling faster loading. The archive is never consulted during normal operation — it exists only for post-session review.
+
+## Supporting Structures
+
+- **Multi-Agent System (RISE-009)** provides the subagent architecture the compaction agent uses
+- **Agent Model Selection (RISE-016)** enables the compaction agent to use a cost-effective model
+- **Agent Permission Rulesets (RISE-011)** ensures the compaction agent is read-only
+- **Structured Logging (RISE-007)** records compaction events (when, what was compacted, compression ratio)
+- **Instance State (RISE-003)** tracks compaction state per session
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Marathon Refactoring Session:**
+A developer spends 4 hours refactoring a large module — 150 messages deep. Without compaction, the agent would have lost early context about why certain design decisions were made. With compaction, the session summary carries forward: "Chose strategy pattern over switch-case for handler dispatch (message #12), extracted shared types to avoid circular imports (message #34)." At message 150, the agent still references these early decisions accurately.
+
+**Scenario 2 — Multi-Day Session:**
+A developer works on a feature across three days, each time resuming the same session. Compaction runs at the end of each day's work, producing a summary of that day's progress. On day 3, the session contains: Day 1 summary + Day 2 summary + today's verbatim messages. The agent has clear continuity without drowning in three days of raw history.
+
+**Scenario 3 — Cost-Conscious Development:**
+A developer on a pay-per-token plan enables aggressive compaction (threshold: 30, retain: 10). The compaction agent uses Gemini Flash at near-zero cost. Each compaction round reduces the active context by ~60%, significantly lowering the token cost of subsequent messages. The developer maintains session coherence while keeping costs predictable.
+
+**Scenario 4 — Forensic Recovery:**
+After a complex debugging session, the developer wants to review the full uncompacted history to understand how they arrived at the solution. They access the archived pre-compaction messages via `/history --full`, which loads the complete raw conversation. The archive exists for exactly this purpose — learning from the full journey, not just the destination.

package/rispecs/borrowed_from_opencode/018-session-persistence.rispec.md

@@ -0,0 +1,125 @@
+# RISE-018: Session Persistence with SQLite
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/018-session-persistence.rispec.md
+
+## Creative Intent
+
+mia-code replaces its fragile flat-file session storage with a proper SQLite database. Developers gain transactional integrity, concurrent access safety, and queryable session history — the foundation upon which every other session feature is built. A crash mid-write no longer corrupts the entire session store. The database becomes the single source of truth for all session, message, and part data.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Sessions are stored in `~/.mia-code-sessions.json` as a flat JSON file
+- Each session contains only basic metadata: id, startedAt, model, projectRoot, initialized
+- Every write rewrites the entire file — a crash during write can corrupt all sessions
+- No concurrent access protection: two mia-code instances editing the same file race each other
+- No query capability: finding sessions by project or date requires loading and scanning the full file
+- Message history is not persisted — conversation context is lost between restarts
+- No schema enforcement: any malformed JSON entry silently corrupts the store
+
+**Desired State:**
+- A SQLite database at `~/.mia-code/data.db` stores all session data
+- Three normalized tables (sessions, messages, parts) with proper foreign keys
+- Writes are transactional — partial writes never corrupt existing data
+- Multiple mia-code instances can read/write concurrently via SQLite's WAL mode
+- Sessions are queryable by project, date range, status, or any column
+- Full conversation history (messages and their parts) persists across restarts
+- Schema is enforced by the database engine, with migrations for future changes
+
+## Desired Outcome Definition
+
+When mia-code starts, it opens (or creates) `~/.mia-code/data.db`. All session CRUD operations go through a typed data access layer backed by SQLite. Existing `~/.mia-code-sessions.json` data is auto-migrated on first run. The JSON file is renamed to `.mia-code-sessions.json.migrated` after successful migration.
+
+## Natural Language Functional Description
+
+### Database Schema
+
+The database contains three core tables:
+
+**sessions** — one row per conversation session:
+- `id` TEXT PRIMARY KEY — UUID v4
+- `slug` TEXT — human-readable short identifier (e.g. "fix-auth-bug-3")
+- `project_id` TEXT — identifier for the project (derived from directory path hash)
+- `directory` TEXT — absolute path to the project root
+- `parent_id` TEXT nullable — references sessions.id for forked/child sessions
+- `title` TEXT — human-readable session title
+- `version` TEXT — mia-code version that created the session
+- `created_at` INTEGER — Unix timestamp in milliseconds
+- `updated_at` INTEGER — Unix timestamp, updated on every mutation
+- `archived_at` INTEGER nullable — set when session is archived, null when active
+
+**messages** — one row per conversation turn:
+- `id` TEXT PRIMARY KEY — UUID v4
+- `session_id` TEXT FOREIGN KEY references sessions.id
+- `role` TEXT — "user", "assistant", or "system"
+- `metadata` JSON — model name, token counts, cost, timing, etc.
+- `created_at` INTEGER — Unix timestamp in milliseconds
+
+**parts** — one row per content unit within a message:
+- `id` TEXT PRIMARY KEY — UUID v4
+- `message_id` TEXT FOREIGN KEY references messages.id
+- `type` TEXT — one of: text, tool_call, tool_result, error, image, file
+- `content` JSON — type-specific payload (see RISE-026)
+- `index` INTEGER — ordering within the parent message
+- `created_at` INTEGER — Unix timestamp in milliseconds
+
+### Data Access Layer
+
+A `SessionDB` class wraps all database operations:
+
+- `open()` — opens the database, runs migrations, enables WAL mode
+- `createSession(opts)` — inserts a session row, returns typed Session object
+- `getSession(id)` — retrieves session with metadata
+- `listSessions(filter?)` — queries sessions with optional project/date/status filters
+- `updateSession(id, patch)` — partial update with automatic `updated_at`
+- `archiveSession(id)` — sets `archived_at` timestamp
+- `addMessage(sessionId, message)` — inserts message and its parts in a transaction
+- `getMessages(sessionId, opts?)` — retrieves messages with parts, supports pagination
+- `deleteSession(id)` — hard delete with cascading part/message removal
+
+### Migration System
+
+On first open, the database runs a migration check:
+1. Read `user_version` pragma from SQLite
+2. If version < current, apply sequential migration scripts
+3. Migration 0→1: create sessions, messages, parts tables with indices
+4. Future migrations increment the version number
+
+### JSON Migration Path
+
+When `~/.mia-code-sessions.json` exists and the database is empty:
+1. Read all sessions from JSON
+2. Insert each as a session row (mapping startedAt→created_at, projectRoot→directory)
+3. Verify row count matches
+4. Rename JSON file to `.mia-code-sessions.json.migrated`
+5. Log migration summary to structured log
+
+### Performance Indices
+
+- `idx_sessions_project` on sessions(project_id)
+- `idx_sessions_directory` on sessions(directory)
+- `idx_sessions_created` on sessions(created_at)
+- `idx_messages_session` on messages(session_id, created_at)
+- `idx_parts_message` on parts(message_id, index)
+
+## Supporting Structures
+
+- **Instance State (RISE-003)** scopes database connections per project context
+- **Structured Logging (RISE-007)** traces all database operations for debugging
+- **Zod Schema Validation (RISE-005)** validates data before insertion
+- **Named Error System (RISE-006)** provides typed errors for database failures (MigrationError, CorruptionError, ConcurrencyError)
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Seamless Migration:**
+A developer upgrades mia-code. On first launch, the migration detects 47 sessions in the JSON file. All 47 are imported into SQLite in under a second. The JSON file is renamed. The developer notices nothing except a log line: "Migrated 47 sessions from JSON to SQLite."
+
+**Scenario 2 — Concurrent Access:**
+Two terminal tabs run mia-code in the same project. Both create sessions and add messages simultaneously. SQLite's WAL mode handles concurrent writes without corruption. Neither instance blocks the other.
+
+**Scenario 3 — Query Power:**
+A developer runs `/sessions --project myapp --since 2025-01-01`. The query hits the `idx_sessions_project` and `idx_sessions_created` indices, returning 12 sessions in milliseconds without loading the entire dataset.
+
+**Scenario 4 — Crash Recovery:**
+The process is killed mid-message-write. On restart, the database is intact — the incomplete transaction was rolled back by SQLite. No data corruption, no manual repair needed.