mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/073-plugin-auto-install.rispec.md

@@ -0,0 +1,115 @@
+# RISE-073: Plugin Auto-Install
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/073-plugin-auto-install.rispec.md
+
+## Creative Intent
+
+Plugin adoption becomes frictionless — a developer adds a plugin name to their config and mia-code handles the rest. No manual `npm install`, no version hunting, no PATH wrangling. The gap between "I want this plugin" and "the plugin is running" collapses to a single config line and one startup cycle.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code has no plugin system, so no installation mechanism exists
+- Users manually install npm packages for any external dependency
+- No lock file tracks what was installed or at what version
+- No auto-resolution of missing packages — failures are opaque ("MODULE_NOT_FOUND")
+- Different package managers (npm, pnpm, bun) are in use across projects with no detection
+- No offline fallback — network failures during install block startup entirely
+
+**Desired State:**
+- Config references a plugin by name; mia-code resolves, installs, and loads it automatically
+- Version pinning via semver ranges (`"my-plugin@^2.0.0"`) gives control without manual management
+- Installation uses the detected package manager or falls back to npm
+- A lock file (`.mia-code/plugin-lock.json`) records exact installed versions for reproducibility
+- Offline mode gracefully degrades — uses cached installations, skips missing plugins
+- User sees clear feedback: "Installing plugin my-plugin@2.1.0..." with progress
+
+## Desired Outcome Definition
+
+A developer adds `"plugin": ["mia-code-plugin-terraform@^1.0.0"]` to their `mia-code.json`. On next startup, mia-code checks `~/.mia-code/plugins/node_modules/` for the package. Not found — mia-code runs `npm install mia-code-plugin-terraform@^1.0.0` into that directory, displays progress, records the resolved version in the lock file, and loads the plugin. Next startup: package found in cache, version satisfies range, skip install, load directly.
+
+## Natural Language Functional Description
+
+### Resolution Process
+
+For each entry in the `plugin` config array:
+
+1. **Classify** — determine if the entry is a local path (starts with `./` or `/`), a built-in name, or an NPM package reference.
+2. **Local paths** — resolve relative to project root. No installation needed. Skip to load.
+3. **Built-in names** — resolve to internal module. No installation needed. Skip to load.
+4. **NPM packages** — proceed to installation check.
+
+### Installation Check
+
+For NPM package references:
+
+1. **Parse** — extract package name and optional version range from the entry (e.g., `"my-plugin@^2.0.0"` → name: `my-plugin`, range: `^2.0.0`).
+2. **Check lock file** — read `.mia-code/plugin-lock.json`. If package exists with a version satisfying the range, check filesystem.
+3. **Check filesystem** — look for the package in `~/.mia-code/plugins/node_modules/{name}/`. Verify `package.json` version matches lock file.
+4. **If found and valid** — skip installation, proceed to load.
+5. **If not found or outdated** — proceed to installation.
+
+### Installation
+
+1. **Detect package manager** — check for `bun.lockb` (bun), `pnpm-lock.yaml` (pnpm), or default to npm.
+2. **Execute install** — run `{pm} install {name}@{version}` with `cwd` set to `~/.mia-code/plugins/`.
+3. **Timeout** — 30-second limit. If exceeded, log warning and skip plugin.
+4. **Retry** — on network failure, retry up to 3 times with exponential backoff (1s, 2s, 4s).
+5. **Update lock file** — record `{name: version}` in `.mia-code/plugin-lock.json`.
+6. **Notify user** — print "✓ Installed plugin my-plugin@2.1.0" on success.
+
+### Lock File Format
+
+```json
+{
+  "version": 1,
+  "plugins": {
+    "mia-code-plugin-terraform": {
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/mia-code-plugin-terraform/-/...",
+      "installedAt": "2025-02-17T12:00:00Z"
+    }
+  }
+}
+```
+
+### Install Location
+
+Plugins install into `~/.mia-code/plugins/node_modules/` — a global location shared across projects. This avoids polluting project `node_modules/` and allows plugin reuse. A `package.json` is auto-created in `~/.mia-code/plugins/` if not present.
+
+### Offline Mode
+
+When `--offline` flag is set or network is unavailable:
+- Skip all auto-install attempts
+- Use only plugins already present in cache
+- Log which plugins were skipped: "Plugin my-plugin not cached, skipping (offline mode)"
+- Never fail startup due to missing optional plugins
+
+### Version Updates
+
+When config specifies a range and a newer version exists:
+- Auto-update is **not** performed by default — stability over freshness
+- `mia-code plugin update` command explicitly checks and updates all plugins
+- Lock file prevents accidental upgrades between runs
+
+## Supporting Structures
+
+- **Plugin Architecture (RISE-071)** defines the plugin interface that installed packages must conform to
+- **Multi-Level Config (RISE-064)** provides the `plugin` array from merged configuration
+- **Managed Config Directory (RISE-070)** manages `~/.mia-code/` where plugins are installed
+- **Structured Logging (RISE-007)** records installation attempts, successes, and failures
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Zero-Friction Adoption:**
+A developer reads about `mia-code-plugin-eslint` in a blog post. They add one line to their config. Next time they run mia-code, the plugin auto-installs in 3 seconds and the agent gains ESLint integration. No terminal commands, no README hunting.
+
+**Scenario 2 — Team-Wide Plugin Standardization:**
+A team commits `.mia-code.json` with `"plugin": ["mia-code-plugin-jira@^1.0.0", "mia-code-plugin-datadog@^2.0.0"]`. Every developer who clones the repo gets the same plugins auto-installed on first run. The lock file ensures version consistency.
+
+**Scenario 3 — Offline Development:**
+A developer works on an airplane. mia-code starts with `--offline`. Plugins installed from previous sessions load normally from cache. A newly added plugin in config is skipped with a clear message. The developer continues working with reduced but functional capabilities.
+
+**Scenario 4 — Install Failure Recovery:**
+NPM registry is temporarily down. mia-code attempts to install a new plugin, times out after 30 seconds, retries twice, then logs: "Failed to install my-plugin: network timeout. Plugin disabled for this session." The agent starts normally with all other plugins active. Next session, auto-install succeeds.

package/rispecs/borrowed_from_opencode/074-permission-system.rispec.md

@@ -0,0 +1,133 @@
+# RISE-074: Permission System
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/074-permission-system.rispec.md
+
+## Creative Intent
+
+Every agent action passes through a permission gate that balances autonomy with safety. Developers define granular rules — allow file reads everywhere, deny writes to lock files, ask before running shell commands — creating a trust boundary that lets the agent work freely within defined limits while requiring human approval at the edges.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code has no formal permission system — the agent can read, write, and execute anything
+- Users must trust the agent entirely or not use it at all — no middle ground
+- No way to restrict the agent from modifying sensitive files (`.env`, `package-lock.json`, production configs)
+- Shell command execution has no guardrails — the agent can run destructive commands
+- Different projects have different security requirements but share the same unrestricted agent
+- Session-level permission grants ("always allow" / "never allow") are not tracked
+
+**Desired State:**
+- A rules-based permission model evaluates every agent action before execution
+- Rules specify permission (tool/action), optional file pattern (glob), and action (allow/deny/ask)
+- Rules are evaluated in order — first match wins, no match defaults to "ask"
+- Permissions layer across sources: built-in defaults → global config → project config → session overrides
+- Developers can lock down sensitive paths while leaving routine operations unrestricted
+- Session-scoped overrides accumulate as users respond to "ask" prompts with "always" or "never"
+
+## Desired Outcome Definition
+
+A project's `.mia-code.json` contains permission rules that allow all file reads, deny writes to `*.lock` files, and ask before any bash execution. The agent reads files freely, is blocked from modifying lock files with a clear message, and prompts the user before running shell commands. The user responds "always allow" to bash — this override persists for the session.
+
+## Natural Language Functional Description
+
+### Permission Rule Model
+
+Each rule is an object with three fields:
+
+```typescript
+interface PermissionRule {
+  permission: string;   // tool or action identifier, or "*" for all
+  pattern?: string;     // glob pattern for file paths (optional)
+  action: "allow" | "deny" | "ask";
+}
+```
+
+### Covered Permissions
+
+The system recognizes these permission identifiers:
+
+- `read` — file reading operations
+- `write` — file creation or full overwrite
+- `edit` — file modification (partial edits)
+- `bash` — shell command execution
+- `question` — asking the user a question
+- `external_directory` — accessing files outside the project root
+- `plan_enter` — entering plan mode
+- `plan_exit` — exiting plan mode
+- `todo_create`, `todo_update`, `todo_delete` — todo operations
+- Any tool ID (e.g., `grep`, `glob`, `web_fetch`) — tool-specific permissions
+
+### Rule Evaluation
+
+When the agent attempts an action:
+
+1. Determine the permission identifier (e.g., `write` for file creation).
+2. Determine the target path if applicable (e.g., `src/auth.ts`).
+3. Iterate through the merged rules array in order.
+4. For each rule: if `permission` matches (exact or wildcard) AND `pattern` matches the path (or no pattern specified), return the rule's `action`.
+5. If no rule matches, default to `"ask"`.
+
+### Configuration
+
+Rules are defined in `mia-code.json` at any config level:
+
+```json
+{
+  "permissions": [
+    {"permission": "read", "action": "allow"},
+    {"permission": "write", "pattern": "*.lock", "action": "deny"},
+    {"permission": "write", "pattern": "*.env*", "action": "deny"},
+    {"permission": "bash", "action": "ask"},
+    {"permission": "external_directory", "action": "deny"}
+  ]
+}
+```
+
+### Layered Resolution
+
+Permissions merge across configuration layers with later layers taking precedence:
+
+1. **Built-in defaults** — sensible base: allow reads, ask for writes and bash
+2. **Global config** (`~/.mia-code.json`) — user-wide preferences
+3. **Project config** (`.mia-code.json` in project root) — project-specific restrictions
+4. **Agent-specific** — agents can have tailored permissions (e.g., a review agent gets read-only)
+5. **Session overrides** — accumulated from "always"/"never" responses during the session
+
+### Session-Scoped Overrides
+
+When the user responds to an "ask" prompt:
+- **"yes"** — allow this specific invocation only
+- **"always"** — add a session-scoped `allow` rule for this permission+pattern
+- **"no"** — deny this specific invocation only
+- **"never"** — add a session-scoped `deny` rule for this permission+pattern
+
+Session overrides are prepended to the rules array (checked first) and discarded when the session ends.
+
+### Deny Behavior
+
+When a permission is denied:
+- The tool execution is skipped
+- A clear message is returned to the agent: "Permission denied: cannot write to package-lock.json (matched rule: deny writes to *.lock)"
+- The agent can acknowledge and proceed with alternative approaches
+
+## Supporting Structures
+
+- **Plugin Hooks (RISE-072)** exposes `permission.ask` hook for plugins to participate in permission decisions
+- **Multi-Level Config (RISE-064)** provides the layered configuration that permissions merge across
+- **Agent Definition (RISE-010)** allows per-agent permission profiles
+- **Permission Prompts (RISE-060)** handles the TUI rendering of ask/allow/deny prompts
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Read-Only Review Agent:**
+A code review agent is configured with `{"permission": "*", "action": "deny"}` followed by `{"permission": "read", "action": "allow"}` and `{"permission": "grep", "action": "allow"}`. The agent can explore the codebase but cannot modify anything. Perfect for automated review workflows where the agent should only observe and report.
+
+**Scenario 2 — Locked Production Configs:**
+A project's `.mia-code.json` denies writes to `*.env*`, `docker-compose.yml`, and `terraform/*.tf`. The agent freely refactors application code but cannot touch infrastructure or secrets. A developer working on Terraform explicitly overrides with "always allow" when needed.
+
+**Scenario 3 — Progressive Trust Building:**
+A new user starts with default permissions (ask for everything). Over several sessions, they respond "always" to file reads, writes to `src/`, and test execution. Their comfort grows. Eventually they configure explicit allow rules in their global config, keeping "ask" only for bash commands and external directory access.
+
+**Scenario 4 — Team Security Policy:**
+A team commits strict permissions in their project `.mia-code.json`: no bash commands allowed, no external directory access, writes only to `src/` and `tests/`. Individual developers can add session overrides for their workflows, but the base policy ensures the agent stays within safe boundaries for everyone.

package/rispecs/borrowed_from_opencode/075-git-worktree-management.rispec.md

@@ -0,0 +1,126 @@
+# RISE-075: Git Worktree Management
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/075-git-worktree-management.rispec.md
+
+## Creative Intent
+
+Agents gain the ability to work in isolated sandboxes without touching the developer's working tree. By leveraging git worktrees, mia-code creates parallel workspaces where experimental changes live on their own branches — enabling fearless exploration, parallel investigations, and clean rollback without ever disrupting the main branch or the developer's uncommitted work.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code operates directly on the developer's working directory — all changes are immediately visible and risky
+- The agent's experimental modifications mix with the developer's in-progress work
+- No mechanism exists to isolate speculative changes (e.g., "try refactoring this two different ways")
+- Reverting agent changes requires manual `git checkout` or `git stash`, which may conflict with developer's own changes
+- Parallel investigations are impossible — the agent can only work in one directory state at a time
+- Git awareness is basic — mia-code uses CLI git commands but has no worktree management layer
+
+**Desired State:**
+- Agents can create git worktrees for isolated experimentation with a single operation
+- Each worktree gets a uniquely named branch (`mia-code/adjective-noun`) for easy identification
+- Multiple worktrees can coexist, enabling parallel approaches to the same problem
+- Worktree cleanup is complete — removing a worktree also deletes its branch
+- Submodules and project initialization (npm install, etc.) are handled automatically
+- The developer's main working tree is never modified by worktree operations
+
+## Desired Outcome Definition
+
+The agent receives a task to "try two different approaches to optimizing the database queries." It creates two worktrees: `mia-code/swift-falcon` and `mia-code/calm-brook`. In each, it applies a different optimization strategy. The developer reviews both, picks the better one, and merges that branch. The other worktree is removed cleanly — branch deleted, directory gone, no traces.
+
+## Natural Language Functional Description
+
+### Worktree Operations
+
+The worktree module exposes four operations:
+
+**Create** — `worktree.create(name?: string)`
+1. Generate a branch name: `mia-code/{adjective}-{noun}` (or use provided name).
+2. Verify no existing branch or directory conflicts.
+3. Run `git worktree add .mia-code/worktrees/{name} -b mia-code/{name}` from the repository root.
+4. If the project has submodules, run `git submodule update --init --recursive` in the new worktree.
+5. If start scripts are configured (e.g., `npm install`), execute them in the new worktree.
+6. Return the worktree path and branch name.
+
+**Remove** — `worktree.remove(name: string)`
+1. Run `git worktree remove .mia-code/worktrees/{name} --force`.
+2. Delete the branch: `git branch -D mia-code/{name}`.
+3. Run `git worktree prune` to clean stale references.
+
+**Reset** — `worktree.reset(name: string)`
+1. In the worktree, run `git checkout -- .` and `git clean -fd`.
+2. Reset to the default branch state: `git reset --hard origin/main` (or detected default branch).
+
+**List** — `worktree.list()`
+1. Run `git worktree list --porcelain`.
+2. Parse output into structured data: `{name, path, branch, head}[]`.
+3. Filter to only mia-code-managed worktrees (branch prefix `mia-code/`).
+
+### Worktree Directory Structure
+
+```
+project-root/
+├── .mia-code/
+│   └── worktrees/
+│       ├── swift-falcon/    ← full working copy
+│       │   ├── src/
+│       │   ├── package.json
+│       │   └── ...
+│       └── calm-brook/      ← another full working copy
+│           ├── src/
+│           ├── package.json
+│           └── ...
+├── src/                      ← developer's main working tree (untouched)
+└── ...
+```
+
+### Naming Convention
+
+Branch names follow the pattern `mia-code/{adjective}-{noun}`:
+- Adjective pool: ~50 positive, memorable adjectives (swift, bright, calm, clear, crisp, deep, fair, keen, kind, lean, mild, neat, pure, rich, sage, warm, wise...)
+- Noun pool: ~50 nature/animal nouns (brook, cedar, crane, dawn, eagle, flame, grove, hawk, jade, lake, maple, oak, peak, ridge, tide, vale, wave, wolf...)
+- Selection: random pairing from each pool
+- Collision handling: if the combination exists (branch or directory), try another random pair up to 10 times, then append a numeric counter
+
+### Start Scripts
+
+After worktree creation, mia-code can run initialization commands:
+
+```json
+{
+  "worktree": {
+    "startScripts": ["npm install", "npm run build"]
+  }
+}
+```
+
+These run in the worktree directory, ensuring dependencies are installed and the project is buildable in the new workspace.
+
+### Conflict Avoidance
+
+Before creating a worktree:
+- Check `git branch --list mia-code/{name}` — fail if branch exists
+- Check filesystem for `.mia-code/worktrees/{name}/` — fail if directory exists
+- Check `git worktree list` — fail if worktree already registered
+
+## Supporting Structures
+
+- **Branch Naming (RISE-079)** defines the adjective-noun naming convention in detail
+- **Snapshot System (RISE-076)** can capture state within worktrees for undo support
+- **Permission System (RISE-074)** governs whether the agent is allowed to create worktrees
+- **Structured Logging (RISE-007)** records worktree lifecycle events
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Parallel Refactoring Strategies:**
+The agent creates two worktrees to try different approaches to a performance issue. In `swift-falcon`, it rewrites the hot path with caching. In `calm-brook`, it parallelizes the computation. Both build and pass tests. The developer compares benchmarks and merges the winner.
+
+**Scenario 2 — Safe Experimentation:**
+A developer asks "can you try upgrading React to v19?" The agent creates a worktree, performs the upgrade, fixes breaking changes, and runs tests — all without touching the developer's working tree. If tests fail, the worktree is removed and the developer's code is untouched.
+
+**Scenario 3 — Code Review Isolation:**
+The agent creates a worktree to apply suggested changes from a PR review. The reviewer can inspect the worktree to verify the changes look correct before the PR author applies them to their branch.
+
+**Scenario 4 — Cleanup After Exploration:**
+A developer has three old worktrees from previous sessions. They run `worktree.list()` and see `swift-falcon` (3 days old), `calm-brook` (1 week old), `deep-ridge` (2 weeks old). They remove the stale ones — branches are deleted, directories cleaned, git refs pruned.

package/rispecs/borrowed_from_opencode/076-snapshot-system.rispec.md

@@ -0,0 +1,124 @@
+# RISE-076: Snapshot System
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/076-snapshot-system.rispec.md
+
+## Creative Intent
+
+Every file-modifying action the agent takes is preceded by an invisible checkpoint. These git-based snapshots create a complete timeline of the workspace state throughout a session — enabling undo, diff, audit, and revert without relying on the project's own git history. The developer gains the confidence to let the agent work freely, knowing any change can be precisely unwound.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code has no formal snapshot system — file modifications are permanent once written
+- Undoing agent changes requires manual `git checkout` or `git stash`, mixing agent and developer changes
+- No record exists of what the workspace looked like before a specific tool call
+- The project's git history is the only recovery mechanism, but uncommitted changes are invisible to it
+- Multi-step agent operations have no intermediate save points — failure mid-sequence leaves partial changes
+- No audit trail captures the exact sequence of file modifications within a session
+
+**Desired State:**
+- Before every file-modifying operation, a snapshot captures the current state of all tracked files
+- Snapshots are stored in a hidden git repository separate from the project's git, avoiding history pollution
+- Each snapshot records the tree hash, affected files, timestamp, and associated message/tool IDs
+- Snapshots enable undo (revert last change), diff (compare states), and session revert (go back to start)
+- Binary and large files are handled gracefully — detected and excluded from snapshots
+- Old snapshots are pruned automatically to prevent unbounded storage growth
+
+## Desired Outcome Definition
+
+The agent edits three files during a session. Before each edit, a snapshot is silently captured. The developer says "undo that last change." mia-code restores the files to the snapshot taken before the third edit. The developer says "show me what changed since the session started." mia-code diffs snapshot #0 (session start) against the current state and displays a unified diff of all three files.
+
+## Natural Language Functional Description
+
+### Snapshot Capture
+
+Before any file-modifying operation (write, edit, bash that may modify files), the snapshot system:
+
+1. **Stage tracked files** — run `git add -A` in the snapshot repository to capture current state.
+2. **Write tree** — run `git write-tree` to create a tree object representing the complete directory state.
+3. **Store metadata** — record the tree hash with associated context:
+
+```typescript
+interface Snapshot {
+  hash: string;          // git tree hash
+  files: string[];       // list of files in the tree
+  timestamp: number;     // Unix timestamp
+  messageId: string;     // associated session message
+  toolCallId: string;    // specific tool invocation that triggered this
+}
+```
+
+4. **Index** — append snapshot metadata to the session's snapshot index for fast lookup.
+
+### Snapshot Repository
+
+Snapshots use a hidden git repository at `.mia-code/snapshots/`:
+
+```
+.mia-code/
+└── snapshots/
+    ├── .git/           ← bare-ish git repo for object storage
+    └── index.json      ← snapshot metadata index
+```
+
+This repository is separate from the project's git. It uses git's object storage for efficient deduplication (unchanged files share objects across snapshots) without affecting the project's history, branches, or remote.
+
+### Automatic Snapshot Triggers
+
+Snapshots are captured automatically before:
+- `file_write` — creating or overwriting a file
+- `file_edit` — modifying part of a file
+- `bash` — executing shell commands (which may modify files unpredictably)
+- `file_delete` — removing a file
+
+The snapshot captures the state **before** the operation, so restoring it undoes that specific change.
+
+### Binary File Handling
+
+Before including a file in a snapshot:
+- Check the first 8KB for null bytes — if found, treat as binary
+- Files matching common binary patterns (`*.png`, `*.jpg`, `*.wasm`, `*.bin`) are excluded
+- Excluded files are noted in the snapshot metadata but not stored
+
+### Large File Handling
+
+- Files exceeding 1MB are flagged but still included (git handles large files efficiently)
+- Extended path support handles deeply nested directories (git's default 4096-char limit)
+- Symlinks are stored as symlinks, not dereferenced
+
+### Snapshot Cleanup
+
+To prevent unbounded growth:
+- Keep the last 100 snapshots per session
+- On session end, prune unreferenced git objects: `git prune` and `git gc`
+- Snapshots older than 30 days are eligible for removal
+- The session-start snapshot is always preserved (never pruned)
+
+### Session Integration
+
+Each session tracks its snapshots:
+- Session start triggers an initial snapshot (baseline state)
+- The snapshot index maps message IDs to snapshot hashes for efficient lookup
+- Session metadata includes snapshot count and total storage size
+
+## Supporting Structures
+
+- **Snapshot Diff (RISE-077)** compares snapshots to generate human-readable diffs
+- **Snapshot Restore (RISE-078)** uses snapshots to revert files to previous states
+- **Session Persistence (RISE-018)** stores snapshot references alongside session data
+- **Structured Logging (RISE-007)** records snapshot capture events for debugging
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Undo Last Edit:**
+The agent modifies `src/auth.ts` but introduces a bug. The developer says "undo." mia-code identifies the most recent snapshot (taken before the edit), restores `src/auth.ts` to its previous state, and confirms: "Restored src/auth.ts to state before file_edit."
+
+**Scenario 2 — Session Impact Review:**
+After a long session with 20+ tool calls, the developer asks "what did you change?" mia-code diffs the session-start snapshot against the current state, producing a complete summary: 5 files modified, 2 created, 120 lines added, 45 deleted.
+
+**Scenario 3 — Mid-Session Recovery:**
+The agent runs a bash command that unexpectedly modifies several config files. The developer notices and says "revert to before that bash command." mia-code finds the snapshot taken before the bash execution and restores all affected files.
+
+**Scenario 4 — Audit Trail:**
+A developer reviews what happened during an overnight agent session. The snapshot index shows 15 snapshots with timestamps and associated tool calls. They can step through the timeline, diffing adjacent snapshots to see exactly what changed at each step.

package/rispecs/borrowed_from_opencode/077-snapshot-diff.rispec.md

@@ -0,0 +1,117 @@
+# RISE-077: Snapshot Diff
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/077-snapshot-diff.rispec.md
+
+## Creative Intent
+
+Any two snapshots become comparable — revealing exactly what changed between two points in time. Developers see precise, syntax-highlighted diffs that answer "what did the agent do?" at any granularity: between individual tool calls, across message groups, or over an entire session. The workspace timeline becomes fully transparent.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code has no snapshot system, so no diff between workspace states is possible
+- The only diff available is `git diff` against the project's last commit, which includes developer changes too
+- No way to isolate "what the agent changed" from "what the developer changed"
+- No per-tool-call change tracking — understanding the impact of a specific operation requires manual inspection
+- Session summaries are narrative (LLM-generated text), not precise (actual file diffs)
+- No statistics on agent impact — lines added, files modified, scope of changes
+
+**Desired State:**
+- Any two snapshot hashes can be compared to produce a structured diff
+- Diffs include file-level status (added, deleted, modified), line-level changes (additions, deletions), and statistics
+- Display formatting includes syntax highlighting, color-coded additions/deletions, and clear file headers
+- Session-level diffs (start → current) give a complete picture of agent impact
+- Tool-call-level diffs (before → after) show exactly what one operation changed
+- Diffs can be exported as patches for application elsewhere
+
+## Desired Outcome Definition
+
+The developer asks "what changed in the last tool call?" mia-code compares the snapshot before the tool call with the snapshot after, producing a colored diff showing 2 files modified: `src/api.ts` (+15 lines, -3 lines) and `tests/api.test.ts` (+22 lines). The developer asks "show me everything since session start" — mia-code diffs snapshot #0 against current state, showing 5 files changed with aggregate statistics.
+
+## Natural Language Functional Description
+
+### Diff Operations
+
+Two primary diff operations:
+
+**Text Diff** — `diff(hashA: string, hashB: string): string`
+- Uses `git diff-tree` to compare two tree hashes from the snapshot repository
+- Returns unified diff format text with context lines
+- Suitable for display in terminal or piping to tools
+
+**Structured Diff** — `diffFull(hashA: string, hashB: string): FileDiff[]`
+- Parses the raw diff into structured objects per file
+- Each object contains before/after content, change counts, and status
+
+### FileDiff Model
+
+```typescript
+interface FileDiff {
+  file: string;                                    // relative file path
+  before: string;                                  // full file content before
+  after: string;                                   // full file content after
+  additions: number;                               // lines added
+  deletions: number;                               // lines deleted
+  status: "added" | "deleted" | "modified";        // file-level change type
+  hunks: Hunk[];                                   // grouped changes
+}
+
+interface Hunk {
+  startBefore: number;   // starting line in before-version
+  startAfter: number;    // starting line in after-version
+  lines: DiffLine[];     // individual line changes
+}
+
+interface DiffLine {
+  type: "add" | "delete" | "context";
+  content: string;
+  lineNumber: number;
+}
+```
+
+### Display Formatting
+
+Diffs are rendered with terminal formatting:
+- File headers in bold with status badge: `■ src/api.ts [modified]`
+- Added lines in green with `+` prefix
+- Deleted lines in red with `-` prefix
+- Context lines in dim gray
+- Hunk headers showing line ranges: `@@ -10,5 +10,8 @@`
+- Syntax highlighting applied to diff content based on file extension
+- Statistics summary at the bottom: "3 files changed, 45 insertions(+), 12 deletions(-)"
+
+### Common Diff Scenarios
+
+- **Tool call diff:** compare snapshot before and after a specific tool execution
+- **Session diff:** compare session-start snapshot with current state for complete session impact
+- **Message diff:** compare state before a message's first tool call with state after its last tool call
+
+### Patch Generation
+
+`toPatch(diffs: FileDiff[]): string` generates standard unified diff format applicable with `git apply` or `patch -p1` — useful for sharing agent changes as portable patches.
+
+### Statistics
+
+Aggregate `DiffStats` computed from `FileDiff[]`: `filesChanged`, `filesAdded`, `filesDeleted`, `filesModified`, `totalAdditions`, `totalDeletions`, and `estimatedLOCImpact` (additions minus deletions).
+
+## Supporting Structures
+
+- **Snapshot System (RISE-076)** provides the tree hashes that diff operations compare
+- **Snapshot Restore (RISE-078)** uses diff display to show what a restore operation will change
+- **Syntax Highlighting (RISE-062)** applies language-aware coloring to diff content
+- **Streaming Display (RISE-059)** renders large diffs incrementally in the TUI
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Tool Call Inspection:**
+The agent ran `bash npm run build` and the developer suspects it modified generated files. They ask "what did that bash command change?" mia-code diffs the pre-bash snapshot against post-bash state, revealing that `dist/bundle.js` was regenerated (+500 lines changed) — expected behavior, no concern.
+
+**Scenario 2 — Session Summary Report:**
+At session end, the developer asks for a summary. mia-code generates a session diff: 8 files modified across `src/` and `tests/`, 234 lines added, 67 deleted. The developer reviews the complete diff to verify all changes before committing.
+
+**Scenario 3 — Selective Understanding:**
+The agent made 12 tool calls across 5 messages. The developer wants to understand what message #3 did specifically. mia-code diffs the snapshots bracketing message #3's tool calls, showing only the 2 files that message touched.
+
+**Scenario 4 — Patch Export for Review:**
+The developer asks the agent to generate a patch of all session changes. mia-code produces a unified diff file that the developer attaches to a PR or sends to a colleague for review — portable, standard format, applicable with `git apply`.