chore: add drift to autocorrect command registry

Add quick_start section with glab equivalents, lore-exclusive features,
and read/write split guidance. Add example_output to issues, mrs, search,
and who commands. Update strip_schemas to also strip example_output in
brief mode. Update beads tracking state.

Closes: bd-91j1

.beads/last-touched

@@ -1 +1 @@
-bd-3pz
+bd-xsgw

.claude/hooks/on-file-write.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# Ultimate Bug Scanner - Claude Code Hook
+# Runs on every file save for UBS-supported languages (JS/TS, Python, C/C++, Rust, Go, Java, Ruby)
+# Claude Code hooks receive context as JSON on stdin.
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty')
+
+if [[ "$FILE_PATH" =~ \.(js|jsx|ts|tsx|mjs|cjs|py|pyw|pyi|c|cc|cpp|cxx|h|hh|hpp|hxx|rs|go|java|rb)$ ]]; then
+  echo "🔬 Running bug scanner..."
+  if ! command -v ubs >/dev/null 2>&1; then
+    echo "⚠️  'ubs' not found in PATH; install it before using this hook." >&2
+    exit 0
+  fi
+  ubs "$FILE_PATH" --ci 2>&1 | head -50
+fi

.claude/skills/release/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: release
+description: Bump version, tag, and prepare for next development cycle
+version: 1.0.0
+author: Taylor Eernisse
+category: automation
+tags: ["release", "versioning", "semver", "git"]
+---
+# Release
+
+Automate SemVer version bumps for the `lore` CLI.
+
+## Invocation
+
+```
+/release <type>
+```
+
+Where `<type>` is one of:
+- **major** — breaking changes (0.5.0 -> 1.0.0)
+- **minor** — new features (0.5.0 -> 0.6.0)
+- **patch** / **hotfix** — bug fixes (0.5.0 -> 0.5.1)
+
+If no type is provided, ask the user.
+
+## Procedure
+
+Follow these steps exactly. Do NOT skip any step.
+
+### 1. Determine bump type
+
+Parse the argument. Accept these aliases:
+- `major`, `breaking` -> MAJOR
+- `minor`, `feature`, `feat` -> MINOR
+- `patch`, `hotfix`, `fix` -> PATCH
+
+If the argument doesn't match, ask the user to clarify.
+
+### 2. Read current version
+
+Read `Cargo.toml` and extract the `version = "X.Y.Z"` line. Parse into major, minor, patch integers.
+
+### 3. Compute new version
+
+- MAJOR: `(major+1).0.0`
+- MINOR: `major.(minor+1).0`
+- PATCH: `major.minor.(patch+1)`
+
+### 4. Check preconditions
+
+Run `git status` and `git log --oneline -5`. Show the user:
+- Current version: X.Y.Z
+- New version: A.B.C
+- Bump type: major/minor/patch
+- Working tree status (clean or dirty)
+- Last 5 commits (so they can confirm scope)
+
+If the working tree is dirty, warn: "You have uncommitted changes. They will NOT be included in the release tag. Continue?"
+
+Ask the user to confirm before proceeding.
+
+### 5. Update Cargo.toml
+
+Edit the `version = "..."` line in Cargo.toml to the new version.
+
+### 6. Update Cargo.lock
+
+Run `cargo check` to update Cargo.lock with the new version. This also verifies the project compiles.
+
+### 7. Commit the version bump
+
+```bash
+git add Cargo.toml Cargo.lock
+git commit -m "release: v{NEW_VERSION}"
+```
+
+### 8. Tag the release
+
+```bash
+git tag v{NEW_VERSION}
+```
+
+### 9. Report
+
+Print a summary:
+```
+Release v{NEW_VERSION} created.
+
+  Previous: v{OLD_VERSION}
+  Bump:     {type}
+  Tag:      v{NEW_VERSION}
+  Commit:   {short hash}
+
+  To push:  git push && git push --tags
+```
+
+Do NOT push automatically. The user decides when to push.
+
+## Examples
+
+```
+/release minor       -> 0.5.0 -> 0.6.0
+/release hotfix      -> 0.5.0 -> 0.5.1
+/release patch       -> 0.5.0 -> 0.5.1
+/release major       -> 0.5.0 -> 1.0.0
+```

.cline/rules

@@ -0,0 +1,50 @@
+
+````markdown
+## UBS Quick Reference for AI Agents
+
+UBS stands for "Ultimate Bug Scanner": **The AI Coding Agent's Secret Weapon: Flagging Likely Bugs for Fixing Early On**
+
+**Install:** `curl -sSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh | bash`
+
+**Golden Rule:** `ubs <changed-files>` before every commit. Exit 0 = safe. Exit >0 = fix & re-run.
+
+**Commands:**
+```bash
+ubs file.ts file2.py                    # Specific files (< 1s) — USE THIS
+ubs $(git diff --name-only --cached)    # Staged files — before commit
+ubs --only=js,python src/               # Language filter (3-5x faster)
+ubs --ci --fail-on-warning .            # CI mode — before PR
+ubs --help                              # Full command reference
+ubs sessions --entries 1                # Tail the latest install session log
+ubs .                                   # Whole project (ignores things like .venv and node_modules automatically)
+```
+
+**Output Format:**
+```
+⚠️  Category (N errors)
+    file.ts:42:5 – Issue description
+    💡 Suggested fix
+Exit code: 1
+```
+Parse: `file:line:col` → location | 💡 → how to fix | Exit 0/1 → pass/fail
+
+**Fix Workflow:**
+1. Read finding → category + fix suggestion
+2. Navigate `file:line:col` → view context
+3. Verify real issue (not false positive)
+4. Fix root cause (not symptom)
+5. Re-run `ubs <file>` → exit 0
+6. Commit
+
+**Speed Critical:** Scope to changed files. `ubs src/file.ts` (< 1s) vs `ubs .` (30s). Never full scan for small edits.
+
+**Bug Severity:**
+- **Critical** (always fix): Null safety, XSS/injection, async/await, memory leaks
+- **Important** (production): Type narrowing, division-by-zero, resource leaks
+- **Contextual** (judgment): TODO/FIXME, console logs
+
+**Anti-Patterns:**
+- ❌ Ignore findings → ✅ Investigate each
+- ❌ Full scan per edit → ✅ Scope to file
+- ❌ Fix symptom (`if (x) { x.y }`) → ✅ Root cause (`x?.y`)
+````

.codex/rules/ubs.md

@@ -0,0 +1,50 @@
+
+````markdown
+## UBS Quick Reference for AI Agents
+
+UBS stands for "Ultimate Bug Scanner": **The AI Coding Agent's Secret Weapon: Flagging Likely Bugs for Fixing Early On**
+
+**Install:** `curl -sSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh | bash`
+
+**Golden Rule:** `ubs <changed-files>` before every commit. Exit 0 = safe. Exit >0 = fix & re-run.
+
+**Commands:**
+```bash
+ubs file.ts file2.py                    # Specific files (< 1s) — USE THIS
+ubs $(git diff --name-only --cached)    # Staged files — before commit
+ubs --only=js,python src/               # Language filter (3-5x faster)
+ubs --ci --fail-on-warning .            # CI mode — before PR
+ubs --help                              # Full command reference
+ubs sessions --entries 1                # Tail the latest install session log
+ubs .                                   # Whole project (ignores things like .venv and node_modules automatically)
+```
+
+**Output Format:**
+```
+⚠️  Category (N errors)
+    file.ts:42:5 – Issue description
+    💡 Suggested fix
+Exit code: 1
+```
+Parse: `file:line:col` → location | 💡 → how to fix | Exit 0/1 → pass/fail
+
+**Fix Workflow:**
+1. Read finding → category + fix suggestion
+2. Navigate `file:line:col` → view context
+3. Verify real issue (not false positive)
+4. Fix root cause (not symptom)
+5. Re-run `ubs <file>` → exit 0
+6. Commit
+
+**Speed Critical:** Scope to changed files. `ubs src/file.ts` (< 1s) vs `ubs .` (30s). Never full scan for small edits.
+
+**Bug Severity:**
+- **Critical** (always fix): Null safety, XSS/injection, async/await, memory leaks
+- **Important** (production): Type narrowing, division-by-zero, resource leaks
+- **Contextual** (judgment): TODO/FIXME, console logs
+
+**Anti-Patterns:**
+- ❌ Ignore findings → ✅ Investigate each
+- ❌ Full scan per edit → ✅ Scope to file
+- ❌ Fix symptom (`if (x) { x.y }`) → ✅ Root cause (`x?.y`)
+````

.continue/config.json

@@ -0,0 +1,16 @@
+{
+  "customCommands": [
+    {
+      "name": "scan-bugs",
+      "description": "Run Ultimate Bug Scanner on current project",
+      "prompt": "Run 'ubs --fail-on-warning .' and fix any critical issues found before proceeding"
+    }
+  ],
+  "slashCommands": [
+    {
+      "name": "quality",
+      "description": "Check code quality with UBS",
+      "run": "ubs ."
+    }
+  ]
+}

.cursor/rules

@@ -0,0 +1,50 @@
+
+````markdown
+## UBS Quick Reference for AI Agents
+
+UBS stands for "Ultimate Bug Scanner": **The AI Coding Agent's Secret Weapon: Flagging Likely Bugs for Fixing Early On**
+
+**Install:** `curl -sSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh | bash`
+
+**Golden Rule:** `ubs <changed-files>` before every commit. Exit 0 = safe. Exit >0 = fix & re-run.
+
+**Commands:**
+```bash
+ubs file.ts file2.py                    # Specific files (< 1s) — USE THIS
+ubs $(git diff --name-only --cached)    # Staged files — before commit
+ubs --only=js,python src/               # Language filter (3-5x faster)
+ubs --ci --fail-on-warning .            # CI mode — before PR
+ubs --help                              # Full command reference
+ubs sessions --entries 1                # Tail the latest install session log
+ubs .                                   # Whole project (ignores things like .venv and node_modules automatically)
+```
+
+**Output Format:**
+```
+⚠️  Category (N errors)
+    file.ts:42:5 – Issue description
+    💡 Suggested fix
+Exit code: 1
+```
+Parse: `file:line:col` → location | 💡 → how to fix | Exit 0/1 → pass/fail
+
+**Fix Workflow:**
+1. Read finding → category + fix suggestion
+2. Navigate `file:line:col` → view context
+3. Verify real issue (not false positive)
+4. Fix root cause (not symptom)
+5. Re-run `ubs <file>` → exit 0
+6. Commit
+
+**Speed Critical:** Scope to changed files. `ubs src/file.ts` (< 1s) vs `ubs .` (30s). Never full scan for small edits.
+
+**Bug Severity:**
+- **Critical** (always fix): Null safety, XSS/injection, async/await, memory leaks
+- **Important** (production): Type narrowing, division-by-zero, resource leaks
+- **Contextual** (judgment): TODO/FIXME, console logs
+
+**Anti-Patterns:**
+- ❌ Ignore findings → ✅ Investigate each
+- ❌ Full scan per edit → ✅ Scope to file
+- ❌ Fix symptom (`if (x) { x.y }`) → ✅ Root cause (`x?.y`)
+````

.gemini/rules

@@ -0,0 +1,50 @@
+
+````markdown
+## UBS Quick Reference for AI Agents
+
+UBS stands for "Ultimate Bug Scanner": **The AI Coding Agent's Secret Weapon: Flagging Likely Bugs for Fixing Early On**
+
+**Install:** `curl -sSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh | bash`
+
+**Golden Rule:** `ubs <changed-files>` before every commit. Exit 0 = safe. Exit >0 = fix & re-run.
+
+**Commands:**
+```bash
+ubs file.ts file2.py                    # Specific files (< 1s) — USE THIS
+ubs $(git diff --name-only --cached)    # Staged files — before commit
+ubs --only=js,python src/               # Language filter (3-5x faster)
+ubs --ci --fail-on-warning .            # CI mode — before PR
+ubs --help                              # Full command reference
+ubs sessions --entries 1                # Tail the latest install session log
+ubs .                                   # Whole project (ignores things like .venv and node_modules automatically)
+```
+
+**Output Format:**
+```
+⚠️  Category (N errors)
+    file.ts:42:5 – Issue description
+    💡 Suggested fix
+Exit code: 1
+```
+Parse: `file:line:col` → location | 💡 → how to fix | Exit 0/1 → pass/fail
+
+**Fix Workflow:**
+1. Read finding → category + fix suggestion
+2. Navigate `file:line:col` → view context
+3. Verify real issue (not false positive)
+4. Fix root cause (not symptom)
+5. Re-run `ubs <file>` → exit 0
+6. Commit
+
+**Speed Critical:** Scope to changed files. `ubs src/file.ts` (< 1s) vs `ubs .` (30s). Never full scan for small edits.
+
+**Bug Severity:**
+- **Critical** (always fix): Null safety, XSS/injection, async/await, memory leaks
+- **Important** (production): Type narrowing, division-by-zero, resource leaks
+- **Contextual** (judgment): TODO/FIXME, console logs
+
+**Anti-Patterns:**
+- ❌ Ignore findings → ✅ Investigate each
+- ❌ Full scan per edit → ✅ Scope to file
+- ❌ Fix symptom (`if (x) { x.y }`) → ✅ Root cause (`x?.y`)
+````

.opencode/rules

@@ -0,0 +1,50 @@
+
+````markdown
+## UBS Quick Reference for AI Agents
+
+UBS stands for "Ultimate Bug Scanner": **The AI Coding Agent's Secret Weapon: Flagging Likely Bugs for Fixing Early On**
+
+**Install:** `curl -sSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh | bash`
+
+**Golden Rule:** `ubs <changed-files>` before every commit. Exit 0 = safe. Exit >0 = fix & re-run.
+
+**Commands:**
+```bash
+ubs file.ts file2.py                    # Specific files (< 1s) — USE THIS
+ubs $(git diff --name-only --cached)    # Staged files — before commit
+ubs --only=js,python src/               # Language filter (3-5x faster)
+ubs --ci --fail-on-warning .            # CI mode — before PR
+ubs --help                              # Full command reference
+ubs sessions --entries 1                # Tail the latest install session log
+ubs .                                   # Whole project (ignores things like .venv and node_modules automatically)
+```
+
+**Output Format:**
+```
+⚠️  Category (N errors)
+    file.ts:42:5 – Issue description
+    💡 Suggested fix
+Exit code: 1
+```
+Parse: `file:line:col` → location | 💡 → how to fix | Exit 0/1 → pass/fail
+
+**Fix Workflow:**
+1. Read finding → category + fix suggestion
+2. Navigate `file:line:col` → view context
+3. Verify real issue (not false positive)
+4. Fix root cause (not symptom)
+5. Re-run `ubs <file>` → exit 0
+6. Commit
+
+**Speed Critical:** Scope to changed files. `ubs src/file.ts` (< 1s) vs `ubs .` (30s). Never full scan for small edits.
+
+**Bug Severity:**
+- **Critical** (always fix): Null safety, XSS/injection, async/await, memory leaks
+- **Important** (production): Type narrowing, division-by-zero, resource leaks
+- **Contextual** (judgment): TODO/FIXME, console logs
+
+**Anti-Patterns:**
+- ❌ Ignore findings → ✅ Investigate each
+- ❌ Full scan per edit → ✅ Scope to file
+- ❌ Fix symptom (`if (x) { x.y }`) → ✅ Root cause (`x?.y`)
+````

AGENTS.md

@@ -14,6 +14,47 @@ If I tell you to do something, even if it goes against what follows below, YOU M
 
 ---
 
+## Version Control: jj-First (CRITICAL)
+
+**ALWAYS prefer jj (Jujutsu) over git for VCS mutations** (commit, describe, rebase, push, bookmark, undo). This is a colocated repo with both `.jj/` and `.git/`. Only fall back to raw `git` for things jj cannot do (hooks, LFS, submodules, `gh` CLI interop).
+
+**Exception — read-only inspection:** Use `git status`, `git diff`, `git log` instead of their jj equivalents. In a colocated repo these see accurate data, and unlike jj, they don't create operations that cause divergences when multiple agents run concurrently. See "Parallel Agent VCS Protocol" below.
+
+See `~/.claude/rules/jj-vcs/` for the full command reference, translation table, revsets, patterns, and recovery recipes.
+
+### Parallel Agent VCS Protocol (CRITICAL)
+
+Multiple agents often run concurrently in separate terminal panes, sharing the same repo directory. This requires care because jj's auto-snapshot creates operations on EVERY command — even read-only ones like `jj status`. Concurrent jj commands fork from the same parent operation and create **divergent changes**.
+
+**The rule: use git for reads, jj for writes.**
+
+In a colocated repo, git reads see accurate data because jj keeps `.git/` in sync.
+
+| Operation | Use | Why |
+|-----------|-----|-----|
+| Check status | `git status` | No jj operation created |
+| View diff | `git diff` | No jj operation created |
+| Browse history | `git log` | No jj operation created |
+| Commit work | `jj commit -m "msg"` | jj mutation (better UX) |
+| Update description | `jj describe -m "msg"` | jj mutation |
+| Rebase | `jj rebase -d trunk()` | jj mutation |
+| Push | `jj git push -b <name>` | jj mutation |
+| Manage bookmarks | `jj bookmark set ...` | jj mutation |
+| Undo a mistake | `jj undo` | jj mutation |
+
+**NEVER run `jj status`, `jj diff`, `jj log`, or `jj show` when other agents may be active** — these trigger snapshots that cause divergences.
+
+**If using Claude Code's built-in agent teams:** Only the team lead runs ANY VCS commands (git or jj). Workers only edit files via Edit/Write tools and do NOT run "Landing the Plane".
+
+**Resolving divergences if they occur:**
+
+```bash
+jj log -r 'divergent()'              # Find divergent changes
+jj abandon <unwanted-commit-id>      # Keep the version you want
+```
+
+---
+
 ## Irreversible Git & Filesystem Actions — DO NOT EVER BREAK GLASS
 
 > **Note:** Treat destructive commands as break-glass. If there's any doubt, stop and ask.
@@ -35,6 +76,8 @@ We only use **Cargo** in this project, NEVER any other package manager.
 - **Configuration:** Cargo.toml only
 - **Unsafe code:** Forbidden (`#![forbid(unsafe_code)]`)
 
+When writing Rust code, reference RUST_CLI_TOOLS_BEST_PRACTICES.md
+
 ### Release Profile
 
 Use the release profile defined in `Cargo.toml`. If you need to change it, justify the
@@ -314,7 +357,7 @@ bv --robot-insights | jq '.Cycles'                         # Circular deps (must
 
 ```bash
 ubs file.rs file2.rs                    # Specific files (< 1s) — USE THIS
-ubs $(git diff --name-only --cached)    # Staged files — before commit
+ubs $(jj diff --name-only)              # Changed files — before commit
 ubs --only=rust,toml src/               # Language filter (3-5x faster)
 ubs --ci --fail-on-warning .            # CI mode — before PR
 ubs .                                   # Whole project (ignores target/, Cargo.lock)
@@ -426,9 +469,9 @@ Returns structured results with file paths, line ranges, and extracted code snip
 
 ## Beads Workflow Integration
 
-This project uses [beads_viewer](https://github.com/Dicklesworthstone/beads_viewer) for issue tracking. Issues are stored in `.beads/` and tracked in git.
+This project uses [beads_viewer](https://github.com/Dicklesworthstone/beads_viewer) for issue tracking. Issues are stored in `.beads/` and tracked in version control.
 
-**Note:** `br` is non-invasive—it never executes git commands directly. You must run git commands manually after `br sync --flush-only`.
+**Note:** `br` is non-invasive—it never executes VCS commands directly. You must commit manually after `br sync --flush-only`.
 
 ### Essential Commands
 
@@ -444,7 +487,7 @@ br create --title="..." --type=task --priority=2
 br update <id> --status=in_progress
 br close <id> --reason="Completed"
 br close <id1> <id2>  # Close multiple issues at once
-br sync --flush-only  # Export to JSONL (then manually: git add .beads/ && git commit)
+br sync --flush-only  # Export to JSONL (then: jj commit -m "Update beads")
 ```
 
 ### Workflow Pattern
@@ -464,15 +507,14 @@ br sync --flush-only  # Export to JSONL (then manually: git add .beads/ && git c
 
 ### Session Protocol
 
-**Before ending any session, run this checklist:**
+**Before ending any session, run this checklist (solo/lead only — workers skip VCS):**
 
 ```bash
-git status              # Check what changed
-git add <files>         # Stage code changes
-br sync --flush-only    # Export beads to JSONL
-git add .beads/         # Stage beads changes
-git commit -m "..."     # Commit code and beads
-git push                # Push to remote
+jj status                        # Check what changed
+br sync --flush-only             # Export beads to JSONL
+jj commit -m "..."               # Commit code and beads (jj auto-tracks all changes)
+jj bookmark set <name> -r @-     # Point bookmark at committed work
+jj git push -b <name>            # Push to remote
 ```
 
 ### Best Practices
@@ -481,13 +523,15 @@ git push                # Push to remote
 - Update status as you work (in_progress → closed)
 - Create new issues with `br create` when you discover tasks
 - Use descriptive titles and set appropriate priority/type
-- Always run `br sync --flush-only` then commit .beads/ before ending session
+- Always run `br sync --flush-only` then commit before ending session (jj auto-tracks .beads/)
 
 <!-- end-bv-agent-instructions -->
 
 ## Landing the Plane (Session Completion)
 
-**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until push succeeds.
+
+**WHO RUNS THIS:** Solo agents run it themselves. In multi-agent sessions, ONLY the team lead runs this. Workers skip VCS entirely.
 
 **MANDATORY WORKFLOW:**
 
@@ -496,19 +540,20 @@ git push                # Push to remote
 3. **Update issue status** - Close finished work, update in-progress items
 4. **PUSH TO REMOTE** - This is MANDATORY:
    ```bash
-   git pull --rebase
-   br sync --flush-only
-   git add .beads/
-   git commit -m "Update beads"
-   git push
-   git status  # MUST show "up to date with origin"
+   jj git fetch                       # Get latest remote state
+   jj rebase -d trunk()               # Rebase onto latest trunk if needed
+   br sync --flush-only               # Export beads to JSONL
+   jj commit -m "Update beads"        # Commit (jj auto-tracks .beads/ changes)
+   jj bookmark set <name> -r @-       # Point bookmark at committed work
+   jj git push -b <name>              # Push to remote
+   jj log -r '<name>'                 # Verify bookmark position
    ```
-5. **Clean up** - Clear stashes, prune remote branches
+5. **Clean up** - Abandon empty orphan changes if any (`jj abandon <rev>`)
 6. **Verify** - All changes committed AND pushed
 7. **Hand off** - Provide context for next session
 
 **CRITICAL RULES:**
-- Work is NOT complete until `git push` succeeds
+- Work is NOT complete until `jj git push` succeeds
 - NEVER stop before pushing - that leaves work stranded locally
 - NEVER say "ready to push when you are" - YOU must push
 - If push fails, resolve and retry until it succeeds
@@ -591,7 +636,7 @@ If you aren't 100% sure how to use a third-party library, **SEARCH ONLINE** to f
 
 ## Gitlore Robot Mode
 
-The `lore` CLI has a robot mode optimized for AI agent consumption with structured JSON output, meaningful exit codes, and TTY auto-detection.
+The `lore` CLI has a robot mode optimized for AI agent consumption with compact JSON output, structured errors with machine-actionable recovery steps, meaningful exit codes, response timing metadata, field selection for token efficiency, and TTY auto-detection.
 
 ### Activation
 
@@ -616,6 +661,13 @@ LORE_ROBOT=1 lore issues
 lore --robot issues -n 10
 lore --robot mrs -s opened
 
+# Filter issues by work item status (case-insensitive)
+lore --robot issues --status "In progress"
+
+# List with field selection (reduces token usage ~60%)
+lore --robot issues --fields minimal
+lore --robot mrs --fields iid,title,state,draft
+
 # Show detailed entity info
 lore --robot issues 123
 lore --robot mrs 456 -p group/repo
@@ -633,6 +685,9 @@ lore --robot status
 # Run full sync pipeline
 lore --robot sync
 
+# Run sync without resource events
+lore --robot sync --no-events
+
 # Run ingestion only
 lore --robot ingest issues
 
@@ -642,7 +697,7 @@ lore --robot doctor
 # Document and index statistics
 lore --robot stats
 
-# Quick health pre-flight check (exit 0 = healthy, 1 = unhealthy)
+# Quick health pre-flight check (exit 0 = healthy, 19 = unhealthy)
 lore --robot health
 
 # Generate searchable documents from ingested data
@@ -651,7 +706,7 @@ lore --robot generate-docs
 # Generate vector embeddings via Ollama
 lore --robot embed
 
-# Agent self-discovery manifest (all commands, flags, exit codes)
+# Agent self-discovery manifest (all commands, flags, exit codes, response schemas)
 lore robot-docs
 
 # Version information
@@ -660,16 +715,27 @@ lore --robot version
 
 ### Response Format
 
-All commands return consistent JSON:
+All commands return compact JSON with a uniform envelope and timing metadata:
 
 ```json
-{"ok":true,"data":{...},"meta":{...}}
+{"ok":true,"data":{...},"meta":{"elapsed_ms":42}}
 ```
 
-Errors return structured JSON to stderr:
+Errors return structured JSON to stderr with machine-actionable recovery steps:
 
 ```json
-{"error":{"code":"CONFIG_NOT_FOUND","message":"...","suggestion":"Run 'lore init'"}}
+{"error":{"code":"CONFIG_NOT_FOUND","message":"...","suggestion":"Run 'lore init'","actions":["lore init"]}}
+```
+
+The `actions` array contains executable shell commands for automated recovery. It is omitted when empty.
+
+### Field Selection
+
+The `--fields` flag on `issues` and `mrs` list commands controls which fields appear in the JSON response:
+
+```bash
+lore -J issues --fields minimal                    # Preset: iid, title, state, updated_at_iso
+lore -J mrs --fields iid,title,state,draft,labels  # Custom field list
 ```
 
 ### Exit Codes
@@ -677,7 +743,7 @@ Errors return structured JSON to stderr:
 | Code | Meaning |
 |------|---------|
 | 0 | Success |
-| 1 | Internal error / health check failed / not implemented |
+| 1 | Internal error / not implemented |
 | 2 | Usage error (invalid flags or arguments) |
 | 3 | Config invalid |
 | 4 | Token not set |
@@ -695,6 +761,7 @@ Errors return structured JSON to stderr:
 | 16 | Embedding failed |
 | 17 | Not found (entity does not exist) |
 | 18 | Ambiguous match (use `-p` to specify project) |
+| 19 | Health check failed |
 | 20 | Config not found |
 
 ### Configuration Precedence
@@ -708,10 +775,79 @@ Errors return structured JSON to stderr:
 
 - Use `lore --robot` or `lore -J` for all agent interactions
 - Check exit codes for error handling
-- Parse JSON errors from stderr
+- Parse JSON errors from stderr; use `actions` array for automated recovery
+- Use `--fields minimal` to reduce token usage (~60% fewer tokens)
 - Use `-n` / `--limit` to control response size
 - Use `-q` / `--quiet` to suppress progress bars and non-essential output
 - Use `--color never` in non-TTY automation for ANSI-free output
+- Use `-v` / `-vv` / `-vvv` for increasing verbosity (debug/trace logging)
+- Use `--log-format json` for machine-readable log output to stderr
 - TTY detection handles piped commands automatically
 - Use `lore --robot health` as a fast pre-flight check before queries
+- Use `lore robot-docs` for response schema discovery
 - The `-p` flag supports fuzzy project matching (suffix and substring)
+
+---
+
+## Read/Write Split: lore vs glab
+
+| Operation | Tool | Why |
+|-----------|------|-----|
+| List issues/MRs | lore | Richer: includes status, discussions, closing MRs |
+| View issue/MR detail | lore | Pre-joined discussions, work-item status |
+| Search across entities | lore | FTS5 + vector hybrid search |
+| Expert/workload analysis | lore | who command — no glab equivalent |
+| Timeline reconstruction | lore | Chronological narrative — no glab equivalent |
+| Create/update/close | glab | Write operations |
+| Approve/merge MR | glab | Write operations |
+| CI/CD pipelines | glab | Not in lore scope |
+
+````markdown
+## UBS Quick Reference for AI Agents
+
+UBS stands for "Ultimate Bug Scanner": **The AI Coding Agent's Secret Weapon: Flagging Likely Bugs for Fixing Early On**
+
+**Install:** `curl -sSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh | bash`
+
+**Golden Rule:** `ubs <changed-files>` before every commit. Exit 0 = safe. Exit >0 = fix & re-run.
+
+**Commands:**
+```bash
+ubs file.ts file2.py                    # Specific files (< 1s) — USE THIS
+ubs $(git diff --name-only --cached)    # Staged files — before commit
+ubs --only=js,python src/               # Language filter (3-5x faster)
+ubs --ci --fail-on-warning .            # CI mode — before PR
+ubs --help                              # Full command reference
+ubs sessions --entries 1                # Tail the latest install session log
+ubs .                                   # Whole project (ignores things like .venv and node_modules automatically)
+```
+
+**Output Format:**
+```
+⚠️  Category (N errors)
+    file.ts:42:5 – Issue description
+    💡 Suggested fix
+Exit code: 1
+```
+Parse: `file:line:col` → location | 💡 → how to fix | Exit 0/1 → pass/fail
+
+**Fix Workflow:**
+1. Read finding → category + fix suggestion
+2. Navigate `file:line:col` → view context
+3. Verify real issue (not false positive)
+4. Fix root cause (not symptom)
+5. Re-run `ubs <file>` → exit 0
+6. Commit
+
+**Speed Critical:** Scope to changed files. `ubs src/file.ts` (< 1s) vs `ubs .` (30s). Never full scan for small edits.
+
+**Bug Severity:**
+- **Critical** (always fix): Null safety, XSS/injection, async/await, memory leaks
+- **Important** (production): Type narrowing, division-by-zero, resource leaks
+- **Contextual** (judgment): TODO/FIXME, console logs
+
+**Anti-Patterns:**
+- ❌ Ignore findings → ✅ Investigate each
+- ❌ Full scan per edit → ✅ Scope to file
+- ❌ Fix symptom (`if (x) { x.y }`) → ✅ Root cause (`x?.y`)
+````

AGENTS.md.backup

@@ -0,0 +1,742 @@
+# AGENTS.md
+
+## RULE 0 - THE FUNDAMENTAL OVERRIDE PEROGATIVE
+
+If I tell you to do something, even if it goes against what follows below, YOU MUST LISTEN TO ME. I AM IN CHARGE, NOT YOU.
+
+---
+
+## RULE NUMBER 1: NO FILE DELETION
+
+**YOU ARE NEVER ALLOWED TO DELETE A FILE WITHOUT EXPRESS PERMISSION.** Even a new file that you yourself created, such as a test code file. You have a horrible track record of deleting critically important files or otherwise throwing away tons of expensive work. As a result, you have permanently lost any and all rights to determine that a file or folder should be deleted.
+
+**YOU MUST ALWAYS ASK AND RECEIVE CLEAR, WRITTEN PERMISSION BEFORE EVER DELETING A FILE OR FOLDER OF ANY KIND.**
+
+---
+
+## Irreversible Git & Filesystem Actions — DO NOT EVER BREAK GLASS
+
+> **Note:** Treat destructive commands as break-glass. If there's any doubt, stop and ask.
+
+1. **Absolutely forbidden commands:** `git reset --hard`, `git clean -fd`, `rm -rf`, or any command that can delete or overwrite code/data must never be run unless the user explicitly provides the exact command and states, in the same message, that they understand and want the irreversible consequences.
+2. **No guessing:** If there is any uncertainty about what a command might delete or overwrite, stop immediately and ask the user for specific approval. "I think it's safe" is never acceptable.
+3. **Safer alternatives first:** When cleanup or rollbacks are needed, request permission to use non-destructive options (`git status`, `git diff`, `git stash`, copying to backups) before ever considering a destructive command.
+4. **Mandatory explicit plan:** Even after explicit user authorization, restate the command verbatim, list exactly what will be affected, and wait for a confirmation that your understanding is correct. Only then may you execute it—if anything remains ambiguous, refuse and escalate.
+5. **Document the confirmation:** When running any approved destructive command, record (in the session notes / final response) the exact user text that authorized it, the command actually run, and the execution time. If that record is absent, the operation did not happen.
+
+---
+
+## Toolchain: Rust & Cargo
+
+We only use **Cargo** in this project, NEVER any other package manager.
+
+- **Edition/toolchain:** Follow `rust-toolchain.toml` (if present). Do not assume stable vs nightly.
+- **Dependencies:** Explicit versions for stability; keep the set minimal.
+- **Configuration:** Cargo.toml only
+- **Unsafe code:** Forbidden (`#![forbid(unsafe_code)]`)
+
+When writing Rust code, reference RUST_CLI_TOOLS_BEST_PRACTICES.md
+
+### Release Profile
+
+Use the release profile defined in `Cargo.toml`. If you need to change it, justify the
+performance/size tradeoff and how it impacts determinism and cancellation behavior.
+
+---
+
+## Code Editing Discipline
+
+### No Script-Based Changes
+
+**NEVER** run a script that processes/changes code files in this repo. Brittle regex-based transformations create far more problems than they solve.
+
+- **Always make code changes manually**, even when there are many instances
+- For many simple changes: use parallel subagents
+- For subtle/complex changes: do them methodically yourself
+
+### No File Proliferation
+
+If you want to change something or add a feature, **revise existing code files in place**.
+
+**NEVER** create variations like:
+- `mainV2.rs`
+- `main_improved.rs`
+- `main_enhanced.rs`
+
+New files are reserved for **genuinely new functionality** that makes zero sense to include in any existing file. The bar for creating new files is **incredibly high**.
+
+---
+
+## Backwards Compatibility
+
+We do not care about backwards compatibility—we're in early development with no users. We want to do things the **RIGHT** way with **NO TECH DEBT**.
+
+- Never create "compatibility shims"
+- Never create wrapper functions for deprecated APIs
+- Just fix the code directly
+
+---
+
+## Compiler Checks (CRITICAL)
+
+**After any substantive code changes, you MUST verify no errors were introduced:**
+
+```bash
+# Check for compiler errors and warnings
+cargo check --all-targets
+
+# Check for clippy lints (pedantic + nursery are enabled)
+cargo clippy --all-targets -- -D warnings
+
+# Verify formatting
+cargo fmt --check
+```
+
+If you see errors, **carefully understand and resolve each issue**. Read sufficient context to fix them the RIGHT way.
+
+---
+
+## Testing
+
+### Unit & Property Tests
+
+```bash
+# Run all tests
+cargo test
+
+# Run with output
+cargo test -- --nocapture
+```
+
+When adding or changing primitives, add tests that assert the core invariants:
+
+- no task leaks
+- no obligation leaks
+- losers are drained after races
+- region close implies quiescence
+
+Prefer deterministic lab-runtime tests for concurrency-sensitive behavior.
+
+---
+
+## MCP Agent Mail — Multi-Agent Coordination
+
+A mail-like layer that lets coding agents coordinate asynchronously via MCP tools and resources. Provides identities, inbox/outbox, searchable threads, and advisory file reservations with human-auditable artifacts in Git.
+
+### Why It's Useful
+
+- **Prevents conflicts:** Explicit file reservations (leases) for files/globs
+- **Token-efficient:** Messages stored in per-project archive, not in context
+- **Quick reads:** `resource://inbox/...`, `resource://thread/...`
+
+### Same Repository Workflow
+
+1. **Register identity:**
+   ```
+   ensure_project(project_key=<abs-path>)
+   register_agent(project_key, program, model)
+   ```
+
+2. **Reserve files before editing:**
+   ```
+   file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true)
+   ```
+
+3. **Communicate with threads:**
+   ```
+   send_message(..., thread_id="FEAT-123")
+   fetch_inbox(project_key, agent_name)
+   acknowledge_message(project_key, agent_name, message_id)
+   ```
+
+4. **Quick reads:**
+   ```
+   resource://inbox/{Agent}?project=<abs-path>&limit=20
+   resource://thread/{id}?project=<abs-path>&include_bodies=true
+   ```
+
+### Macros vs Granular Tools
+
+- **Prefer macros for speed:** `macro_start_session`, `macro_prepare_thread`, `macro_file_reservation_cycle`, `macro_contact_handshake`
+- **Use granular tools for control:** `register_agent`, `file_reservation_paths`, `send_message`, `fetch_inbox`, `acknowledge_message`
+
+### Common Pitfalls
+
+- `"from_agent not registered"`: Always `register_agent` in the correct `project_key` first
+- `"FILE_RESERVATION_CONFLICT"`: Adjust patterns, wait for expiry, or use non-exclusive reservation
+- **Auth errors:** If JWT+JWKS enabled, include bearer token with matching `kid`
+
+---
+
+## Beads (br) — Dependency-Aware Issue Tracking
+
+Beads provides a lightweight, dependency-aware issue database and CLI (`br` / beads_rust) for selecting "ready work," setting priorities, and tracking status. It complements MCP Agent Mail's messaging and file reservations.
+
+**Note:** `br` is non-invasive—it never executes git commands directly. You must run git commands manually after `br sync --flush-only`.
+
+### Conventions
+
+- **Single source of truth:** Beads for task status/priority/dependencies; Agent Mail for conversation and audit
+- **Shared identifiers:** Use Beads issue ID (e.g., `br-123`) as Mail `thread_id` and prefix subjects with `[br-123]`
+- **Reservations:** When starting a task, call `file_reservation_paths()` with the issue ID in `reason`
+
+### Typical Agent Flow
+
+1. **Pick ready work (Beads):**
+   ```bash
+   br ready --json  # Choose highest priority, no blockers
+   ```
+
+2. **Reserve edit surface (Mail):**
+   ```
+   file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true, reason="br-123")
+   ```
+
+3. **Announce start (Mail):**
+   ```
+   send_message(..., thread_id="br-123", subject="[br-123] Start: <title>", ack_required=true)
+   ```
+
+4. **Work and update:** Reply in-thread with progress
+
+5. **Complete and release:**
+   ```bash
+   br close br-123 --reason "Completed"
+   ```
+   ```
+   release_file_reservations(project_key, agent_name, paths=["src/**"])
+   ```
+   Final Mail reply: `[br-123] Completed` with summary
+
+### Mapping Cheat Sheet
+
+| Concept | Value |
+|---------|-------|
+| Mail `thread_id` | `br-###` |
+| Mail subject | `[br-###] ...` |
+| File reservation `reason` | `br-###` |
+| Commit messages | Include `br-###` for traceability |
+
+---
+
+## bv — Graph-Aware Triage Engine
+
+bv is a graph-aware triage engine for Beads projects (`.beads/beads.jsonl`). It computes PageRank, betweenness, critical path, cycles, HITS, eigenvector, and k-core metrics deterministically.
+
+**Scope boundary:** bv handles *what to work on* (triage, priority, planning). For agent-to-agent coordination (messaging, work claiming, file reservations), use MCP Agent Mail.
+
+**CRITICAL: Use ONLY `--robot-*` flags. Bare `bv` launches an interactive TUI that blocks your session.**
+
+### The Workflow: Start With Triage
+
+**`bv --robot-triage` is your single entry point.** It returns:
+- `quick_ref`: at-a-glance counts + top 3 picks
+- `recommendations`: ranked actionable items with scores, reasons, unblock info
+- `quick_wins`: low-effort high-impact items
+- `blockers_to_clear`: items that unblock the most downstream work
+- `project_health`: status/type/priority distributions, graph metrics
+- `commands`: copy-paste shell commands for next steps
+
+```bash
+bv --robot-triage        # THE MEGA-COMMAND: start here
+bv --robot-next          # Minimal: just the single top pick + claim command
+```
+
+### Command Reference
+
+**Planning:**
+| Command | Returns |
+|---------|---------|
+| `--robot-plan` | Parallel execution tracks with `unblocks` lists |
+| `--robot-priority` | Priority misalignment detection with confidence |
+
+**Graph Analysis:**
+| Command | Returns |
+|---------|---------|
+| `--robot-insights` | Full metrics: PageRank, betweenness, HITS, eigenvector, critical path, cycles, k-core, articulation points, slack |
+| `--robot-label-health` | Per-label health: `health_level`, `velocity_score`, `staleness`, `blocked_count` |
+| `--robot-label-flow` | Cross-label dependency: `flow_matrix`, `dependencies`, `bottleneck_labels` |
+| `--robot-label-attention [--attention-limit=N]` | Attention-ranked labels |
+
+**History & Change Tracking:**
+| Command | Returns |
+|---------|---------|
+| `--robot-history` | Bead-to-commit correlations |
+| `--robot-diff --diff-since <ref>` | Changes since ref: new/closed/modified issues, cycles |
+
+**Other:**
+| Command | Returns |
+|---------|---------|
+| `--robot-burndown <sprint>` | Sprint burndown, scope changes, at-risk items |
+| `--robot-forecast <id\|all>` | ETA predictions with dependency-aware scheduling |
+| `--robot-alerts` | Stale issues, blocking cascades, priority mismatches |
+| `--robot-suggest` | Hygiene: duplicates, missing deps, label suggestions |
+| `--robot-graph [--graph-format=json\|dot\|mermaid]` | Dependency graph export |
+| `--export-graph <file.html>` | Interactive HTML visualization |
+
+### Scoping & Filtering
+
+```bash
+bv --robot-plan --label backend              # Scope to label's subgraph
+bv --robot-insights --as-of HEAD~30          # Historical point-in-time
+bv --recipe actionable --robot-plan          # Pre-filter: ready to work
+bv --recipe high-impact --robot-triage       # Pre-filter: top PageRank
+bv --robot-triage --robot-triage-by-track    # Group by parallel work streams
+bv --robot-triage --robot-triage-by-label    # Group by domain
+```
+
+### Understanding Robot Output
+
+**All robot JSON includes:**
+- `data_hash` — Fingerprint of source beads.jsonl
+- `status` — Per-metric state: `computed|approx|timeout|skipped` + elapsed ms
+- `as_of` / `as_of_commit` — Present when using `--as-of`
+
+**Two-phase analysis:**
+- **Phase 1 (instant):** degree, topo sort, density
+- **Phase 2 (async, 500ms timeout):** PageRank, betweenness, HITS, eigenvector, cycles
+
+### jq Quick Reference
+
+```bash
+bv --robot-triage | jq '.quick_ref'                        # At-a-glance summary
+bv --robot-triage | jq '.recommendations[0]'               # Top recommendation
+bv --robot-plan | jq '.plan.summary.highest_impact'        # Best unblock target
+bv --robot-insights | jq '.status'                         # Check metric readiness
+bv --robot-insights | jq '.Cycles'                         # Circular deps (must fix!)
+```
+
+---
+
+## UBS — Ultimate Bug Scanner
+
+**Golden Rule:** `ubs <changed-files>` before every commit. Exit 0 = safe. Exit >0 = fix & re-run.
+
+### Commands
+
+```bash
+ubs file.rs file2.rs                    # Specific files (< 1s) — USE THIS
+ubs $(git diff --name-only --cached)    # Staged files — before commit
+ubs --only=rust,toml src/               # Language filter (3-5x faster)
+ubs --ci --fail-on-warning .            # CI mode — before PR
+ubs .                                   # Whole project (ignores target/, Cargo.lock)
+```
+
+### Output Format
+
+```
+⚠️  Category (N errors)
+    file.rs:42:5 – Issue description
+    💡 Suggested fix
+Exit code: 1
+```
+
+Parse: `file:line:col` → location | 💡 → how to fix | Exit 0/1 → pass/fail
+
+### Fix Workflow
+
+1. Read finding → category + fix suggestion
+2. Navigate `file:line:col` → view context
+3. Verify real issue (not false positive)
+4. Fix root cause (not symptom)
+5. Re-run `ubs <file>` → exit 0
+6. Commit
+
+### Bug Severity
+
+- **Critical (always fix):** Memory safety, use-after-free, data races, SQL injection
+- **Important (production):** Unwrap panics, resource leaks, overflow checks
+- **Contextual (judgment):** TODO/FIXME, println! debugging
+
+---
+
+## ast-grep vs ripgrep
+
+**Use `ast-grep` when structure matters.** It parses code and matches AST nodes, ignoring comments/strings, and can **safely rewrite** code.
+
+- Refactors/codemods: rename APIs, change import forms
+- Policy checks: enforce patterns across a repo
+- Editor/automation: LSP mode, `--json` output
+
+**Use `ripgrep` when text is enough.** Fastest way to grep literals/regex.
+
+- Recon: find strings, TODOs, log lines, config values
+- Pre-filter: narrow candidate files before ast-grep
+
+### Rule of Thumb
+
+- Need correctness or **applying changes** → `ast-grep`
+- Need raw speed or **hunting text** → `rg`
+- Often combine: `rg` to shortlist files, then `ast-grep` to match/modify
+
+### Rust Examples
+
+```bash
+# Find structured code (ignores comments)
+ast-grep run -l Rust -p 'fn $NAME($$$ARGS) -> $RET { $$$BODY }'
+
+# Find all unwrap() calls
+ast-grep run -l Rust -p '$EXPR.unwrap()'
+
+# Quick textual hunt
+rg -n 'println!' -t rust
+
+# Combine speed + precision
+rg -l -t rust 'unwrap\(' | xargs ast-grep run -l Rust -p '$X.unwrap()' --json
+```
+
+---
+
+## Morph Warp Grep — AI-Powered Code Search
+
+**Use `mcp__morph-mcp__warp_grep` for exploratory "how does X work?" questions.** An AI agent expands your query, greps the codebase, reads relevant files, and returns precise line ranges with full context.
+
+**Use `ripgrep` for targeted searches.** When you know exactly what you're looking for.
+
+**Use `ast-grep` for structural patterns.** When you need AST precision for matching/rewriting.
+
+### When to Use What
+
+| Scenario | Tool | Why |
+|----------|------|-----|
+| "How is pattern matching implemented?" | `warp_grep` | Exploratory; don't know where to start |
+| "Where is the quick reject filter?" | `warp_grep` | Need to understand architecture |
+| "Find all uses of `Regex::new`" | `ripgrep` | Targeted literal search |
+| "Find files with `println!`" | `ripgrep` | Simple pattern |
+| "Replace all `unwrap()` with `expect()`" | `ast-grep` | Structural refactor |
+
+### warp_grep Usage
+
+```
+mcp__morph-mcp__warp_grep(
+  repoPath: "/path/to/dcg",
+  query: "How does the safe pattern whitelist work?"
+)
+```
+
+Returns structured results with file paths, line ranges, and extracted code snippets.
+
+### Anti-Patterns
+
+- **Don't** use `warp_grep` to find a specific function name → use `ripgrep`
+- **Don't** use `ripgrep` to understand "how does X work" → wastes time with manual reads
+- **Don't** use `ripgrep` for codemods → risks collateral edits
+
+<!-- bv-agent-instructions-v1 -->
+
+---
+
+## Beads Workflow Integration
+
+This project uses [beads_viewer](https://github.com/Dicklesworthstone/beads_viewer) for issue tracking. Issues are stored in `.beads/` and tracked in git.
+
+**Note:** `br` is non-invasive—it never executes git commands directly. You must run git commands manually after `br sync --flush-only`.
+
+### Essential Commands
+
+```bash
+# View issues (launches TUI - avoid in automated sessions)
+bv
+
+# CLI commands for agents (use these instead)
+br ready              # Show issues ready to work (no blockers)
+br list --status=open # All open issues
+br show <id>          # Full issue details with dependencies
+br create --title="..." --type=task --priority=2
+br update <id> --status=in_progress
+br close <id> --reason="Completed"
+br close <id1> <id2>  # Close multiple issues at once
+br sync --flush-only  # Export to JSONL (then manually: git add .beads/ && git commit)
+```
+
+### Workflow Pattern
+
+1. **Start**: Run `br ready` to find actionable work
+2. **Claim**: Use `br update <id> --status=in_progress`
+3. **Work**: Implement the task
+4. **Complete**: Use `br close <id>`
+5. **Sync**: Run `br sync --flush-only`, then `git add .beads/ && git commit -m "Update beads"`
+
+### Key Concepts
+
+- **Dependencies**: Issues can block other issues. `br ready` shows only unblocked work.
+- **Priority**: P0=critical, P1=high, P2=medium, P3=low, P4=backlog (use numbers, not words)
+- **Types**: task, bug, feature, epic, question, docs
+- **Blocking**: `br dep add <issue> <depends-on>` to add dependencies
+
+### Session Protocol
+
+**Before ending any session, run this checklist:**
+
+```bash
+git status              # Check what changed
+git add <files>         # Stage code changes
+br sync --flush-only    # Export beads to JSONL
+git add .beads/         # Stage beads changes
+git commit -m "..."     # Commit code and beads
+git push                # Push to remote
+```
+
+### Best Practices
+
+- Check `br ready` at session start to find available work
+- Update status as you work (in_progress → closed)
+- Create new issues with `br create` when you discover tasks
+- Use descriptive titles and set appropriate priority/type
+- Always run `br sync --flush-only` then commit .beads/ before ending session
+
+<!-- end-bv-agent-instructions -->
+
+## Landing the Plane (Session Completion)
+
+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
+
+**MANDATORY WORKFLOW:**
+
+1. **File issues for remaining work** - Create issues for anything that needs follow-up
+2. **Run quality gates** (if code changed) - Tests, linters, builds
+3. **Update issue status** - Close finished work, update in-progress items
+4. **PUSH TO REMOTE** - This is MANDATORY:
+   ```bash
+   git pull --rebase
+   br sync --flush-only
+   git add .beads/
+   git commit -m "Update beads"
+   git push
+   git status  # MUST show "up to date with origin"
+   ```
+5. **Clean up** - Clear stashes, prune remote branches
+6. **Verify** - All changes committed AND pushed
+7. **Hand off** - Provide context for next session
+
+**CRITICAL RULES:**
+- Work is NOT complete until `git push` succeeds
+- NEVER stop before pushing - that leaves work stranded locally
+- NEVER say "ready to push when you are" - YOU must push
+- If push fails, resolve and retry until it succeeds
+
+---
+
+## cass — Cross-Agent Session Search
+
+`cass` indexes prior agent conversations (Claude Code, Codex, Cursor, Gemini, ChatGPT, etc.) so we can reuse solved problems.
+
+**Rules:** Never run bare `cass` (TUI). Always use `--robot` or `--json`.
+
+### Examples
+
+```bash
+cass health
+cass search "async runtime" --robot --limit 5
+cass view /path/to/session.jsonl -n 42 --json
+cass expand /path/to/session.jsonl -n 42 -C 3 --json
+cass capabilities --json
+cass robot-docs guide
+```
+
+### Tips
+
+- Use `--fields minimal` for lean output
+- Filter by agent with `--agent`
+- Use `--days N` to limit to recent history
+
+stdout is data-only, stderr is diagnostics; exit code 0 means success.
+
+Treat cass as a way to avoid re-solving problems other agents already handled.
+
+---
+
+## Note for Codex/GPT-5.2
+
+You constantly bother me and stop working with concerned questions that look similar to this:
+
+```
+Unexpected changes (need guidance)
+
+- Working tree still shows edits I did not make in Cargo.toml, Cargo.lock, src/runtime.rs, src/scope.rs. Please advise whether to keep/commit/revert these before any further work. I did not touch them.
+
+Next steps (pick one)
+
+1. Decide how to handle the unrelated modified files above so we can resume cleanly.
+```
+
+NEVER EVER DO THAT AGAIN. The answer is literally ALWAYS the same: those are changes created by the potentially dozen of other agents working on the project at the same time. This is not only a common occurence, it happens multiple times PER MINUTE. The way to deal with it is simple: you NEVER, under ANY CIRCUMSTANCE, stash, revert, overwrite, or otherwise disturb in ANY way the work of other agents. Just treat those changes identically to changes that you yourself made. Just fool yourself into thinking YOU made the changes and simply don't recall it for some reason.
+
+---
+
+## Note on Built-in TODO Functionality
+
+Also, if I ask you to explicitly use your built-in TODO functionality, don't complain about this and say you need to use beads. You can use built-in TODOs if I tell you specifically to do so. Always comply with such orders.
+
+## TDD Requirements
+
+Test-first development is mandatory:
+1. **RED** - Write failing test first
+2. **GREEN** - Minimal implementation to pass
+3. **REFACTOR** - Clean up while green
+
+## Key Patterns
+
+Find the simplest solution that meets all acceptance criteria.
+Use third party libraries whenever there's a well-maintained, active, and widely adopted solution (for example, date-fns for TS date math)
+Build extensible pieces of logic that can easily be integrated with other pieces.
+DRY principles should be loosely held.
+Architecture MUST be clear and well thought-out. Ask the user for clarification whenever ambiguity is discovered around architecture, or you think a better approach than planned exists.
+
+---
+
+## Third-Party Library Usage
+
+If you aren't 100% sure how to use a third-party library, **SEARCH ONLINE** to find the latest documentation and mid-2025 best practices.
+
+---
+
+## Gitlore Robot Mode
+
+The `lore` CLI has a robot mode optimized for AI agent consumption with compact JSON output, structured errors with machine-actionable recovery steps, meaningful exit codes, response timing metadata, field selection for token efficiency, and TTY auto-detection.
+
+### Activation
+
+```bash
+# Explicit flag
+lore --robot issues -n 10
+
+# JSON shorthand (-J)
+lore -J issues -n 10
+
+# Auto-detection (when stdout is not a TTY)
+lore issues | jq .
+
+# Environment variable
+LORE_ROBOT=1 lore issues
+```
+
+### Robot Mode Commands
+
+```bash
+# List issues/MRs with JSON output
+lore --robot issues -n 10
+lore --robot mrs -s opened
+
+# List with field selection (reduces token usage ~60%)
+lore --robot issues --fields minimal
+lore --robot mrs --fields iid,title,state,draft
+
+# Show detailed entity info
+lore --robot issues 123
+lore --robot mrs 456 -p group/repo
+
+# Count entities
+lore --robot count issues
+lore --robot count discussions --for mr
+
+# Search indexed documents
+lore --robot search "authentication bug"
+
+# Check sync status
+lore --robot status
+
+# Run full sync pipeline
+lore --robot sync
+
+# Run sync without resource events
+lore --robot sync --no-events
+
+# Run ingestion only
+lore --robot ingest issues
+
+# Check environment health
+lore --robot doctor
+
+# Document and index statistics
+lore --robot stats
+
+# Quick health pre-flight check (exit 0 = healthy, 19 = unhealthy)
+lore --robot health
+
+# Generate searchable documents from ingested data
+lore --robot generate-docs
+
+# Generate vector embeddings via Ollama
+lore --robot embed
+
+# Agent self-discovery manifest (all commands, flags, exit codes, response schemas)
+lore robot-docs
+
+# Version information
+lore --robot version
+```
+
+### Response Format
+
+All commands return compact JSON with a uniform envelope and timing metadata:
+
+```json
+{"ok":true,"data":{...},"meta":{"elapsed_ms":42}}
+```
+
+Errors return structured JSON to stderr with machine-actionable recovery steps:
+
+```json
+{"error":{"code":"CONFIG_NOT_FOUND","message":"...","suggestion":"Run 'lore init'","actions":["lore init"]}}
+```
+
+The `actions` array contains executable shell commands for automated recovery. It is omitted when empty.
+
+### Field Selection
+
+The `--fields` flag on `issues` and `mrs` list commands controls which fields appear in the JSON response:
+
+```bash
+lore -J issues --fields minimal                    # Preset: iid, title, state, updated_at_iso
+lore -J mrs --fields iid,title,state,draft,labels  # Custom field list
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Internal error / not implemented |
+| 2 | Usage error (invalid flags or arguments) |
+| 3 | Config invalid |
+| 4 | Token not set |
+| 5 | GitLab auth failed |
+| 6 | Resource not found |
+| 7 | Rate limited |
+| 8 | Network error |
+| 9 | Database locked |
+| 10 | Database error |
+| 11 | Migration failed |
+| 12 | I/O error |
+| 13 | Transform error |
+| 14 | Ollama unavailable |
+| 15 | Ollama model not found |
+| 16 | Embedding failed |
+| 17 | Not found (entity does not exist) |
+| 18 | Ambiguous match (use `-p` to specify project) |
+| 19 | Health check failed |
+| 20 | Config not found |
+
+### Configuration Precedence
+
+1. CLI flags (highest priority)
+2. Environment variables (`LORE_ROBOT`, `GITLAB_TOKEN`, `LORE_CONFIG_PATH`)
+3. Config file (`~/.config/lore/config.json`)
+4. Built-in defaults (lowest priority)
+
+### Best Practices
+
+- Use `lore --robot` or `lore -J` for all agent interactions
+- Check exit codes for error handling
+- Parse JSON errors from stderr; use `actions` array for automated recovery
+- Use `--fields minimal` to reduce token usage (~60% fewer tokens)
+- Use `-n` / `--limit` to control response size
+- Use `-q` / `--quiet` to suppress progress bars and non-essential output
+- Use `--color never` in non-TTY automation for ANSI-free output
+- Use `-v` / `-vv` / `-vvv` for increasing verbosity (debug/trace logging)
+- Use `--log-format json` for machine-readable log output to stderr
+- TTY detection handles piped commands automatically
+- Use `lore --robot health` as a fast pre-flight check before queries
+- Use `lore robot-docs` for response schema discovery
+- The `-p` flag supports fuzzy project matching (suffix and substring)

Cargo.lock

@@ -1106,7 +1106,7 @@ checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
 [[package]]
 name = "lore"
-version = "0.1.0"
+version = "0.6.2"
 dependencies = [
  "async-stream",
  "chrono",
@@ -1118,16 +1118,19 @@ dependencies = [
  "dirs",
  "flate2",
  "futures",
+ "httpdate",
  "indicatif",
  "libc",
  "open",
  "rand",
+ "regex",
  "reqwest",
  "rusqlite",
  "serde",
  "serde_json",
  "sha2",
  "sqlite-vec",
+ "strsim",
  "tempfile",
  "thiserror",
  "tokio",
@@ -1754,6 +1757,15 @@ version = "1.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
 
+[[package]]
+name = "signal-hook-registry"
+version = "1.4.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9203b8055f63a2a00e2f593bb0510367fe707d7ff1e5c872de2f537b339e5410"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "simd-adler32"
 version = "0.3.8"
@@ -1966,6 +1978,7 @@ dependencies = [
  "libc",
  "mio",
  "pin-project-lite",
+ "signal-hook-registry",
  "socket2",
  "tokio-macros",
  "windows-sys 0.61.2",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "lore"
-version = "0.1.0"
+version = "0.6.2"
 edition = "2024"
 description = "Gitlore - Local GitLab data management with semantic search"
 authors = ["Taylor Eernisse"]
@@ -30,7 +30,7 @@ open = "5"
 
 # HTTP
 reqwest = { version = "0.12", features = ["json"] }
-tokio = { version = "1", features = ["rt-multi-thread", "macros", "time"] }
+tokio = { version = "1", features = ["rt-multi-thread", "macros", "time", "signal"] }
 
 # Async streaming for pagination
 async-stream = "0.3"
@@ -45,7 +45,10 @@ rand = "0.8"
 sha2 = "0.10"
 flate2 = "1"
 chrono = { version = "0.4", features = ["serde"] }
+httpdate = "1"
 uuid = { version = "1", features = ["v4"] }
+regex = "1"
+strsim = "0.11"
 
 [target.'cfg(unix)'.dependencies]
 libc = "0.2"

PERFORMANCE_AUDIT.md

@@ -0,0 +1,467 @@
+# Gitlore Performance Audit Report
+
+**Date**: 2026-02-05
+**Auditor**: Claude Code (Opus 4.5)
+**Scope**: Core system performance - ingestion, embedding, search, and document regeneration
+
+## Executive Summary
+
+This audit identifies 12 high-impact optimization opportunities across the Gitlore codebase. The most significant findings center on:
+
+1. **SQL query patterns** with N+1 issues and inefficient correlated subqueries
+2. **Memory allocation patterns** in hot paths (embedding, chunking, ingestion)
+3. **Change detection queries** using triple-EXISTS patterns instead of JOINs
+
+**Estimated overall improvement potential**: 30-50% reduction in latency for filtered searches, 2-5x improvement in ingestion throughput for issues/MRs with many labels.
+
+---
+
+## Methodology
+
+- **Codebase analysis**: Full read of all modules in `src/`
+- **SQL pattern analysis**: All queries checked for N+1, missing indexes, unbounded results
+- **Memory allocation analysis**: Clone patterns, unnecessary collections, missing capacity hints
+- **Test baseline**: All tests pass (`cargo test --release`)
+
+Note: Without access to a live GitLab instance or populated database, profiling is code-analysis based rather than runtime measured.
+
+---
+
+## Opportunity Matrix
+
+| ID | Issue | Location | Impact | Confidence | Effort | ICE Score | Status |
+|----|-------|----------|--------|------------|--------|-----------|--------|
+| 1 | Triple-EXISTS change detection | `change_detector.rs:19-46` | HIGH | 95% | LOW | **9.5** | **DONE** |
+| 2 | N+1 label/assignee inserts | `issues.rs:270-285`, `merge_requests.rs:242-272` | HIGH | 95% | MEDIUM | **9.0** | Pending |
+| 3 | Clone in embedding batch loop | `pipeline.rs:165` | HIGH | 90% | LOW | **9.0** | Pending |
+| 4 | Correlated GROUP_CONCAT in list | `list.rs:341-348` | HIGH | 90% | MEDIUM | **8.5** | Pending |
+| 5 | Multiple EXISTS per label filter | `filters.rs:100-107` | HIGH | 85% | MEDIUM | **8.0** | **DONE** |
+| 6 | String allocation in chunking | `chunking.rs:7-49` | MEDIUM | 95% | MEDIUM | **7.5** | Pending |
+| 7 | Multiple COUNT queries | `count.rs:44-56` | MEDIUM | 95% | LOW | **7.0** | **DONE** |
+| 8 | Collect-then-concat pattern | `truncation.rs:60-61` | MEDIUM | 90% | LOW | **7.0** | **DONE** |
+| 9 | Box<dyn ToSql> allocations | `filters.rs:67-135` | MEDIUM | 80% | HIGH | **6.0** | Pending |
+| 10 | Missing Vec::with_capacity | `pipeline.rs:106`, multiple | LOW | 95% | LOW | **5.5** | **DONE** |
+| 11 | FTS token collect-join | `fts.rs:26-41` | LOW | 90% | LOW | **5.0** | **DONE** |
+| 12 | Transformer string clones | `merge_request.rs:51-77` | MEDIUM | 85% | HIGH | **5.0** | Pending |
+
+ICE Score = (Impact x Confidence) / Effort, scaled 1-10
+
+---
+
+## Detailed Findings
+
+### 1. Triple-EXISTS Change Detection Query (ICE: 9.5)
+
+**Location**: `src/embedding/change_detector.rs:19-46`
+
+**Current Code**:
+```sql
+SELECT d.id, d.content_text, d.content_hash
+FROM documents d
+WHERE d.id > ?1
+  AND (
+    NOT EXISTS (SELECT 1 FROM embedding_metadata em WHERE em.document_id = d.id AND em.chunk_index = 0)
+    OR EXISTS (SELECT 1 FROM embedding_metadata em WHERE em.document_id = d.id AND em.chunk_index = 0 AND em.document_hash != d.content_hash)
+    OR EXISTS (SELECT 1 FROM embedding_metadata em WHERE em.document_id = d.id AND em.chunk_index = 0 AND (...))
+  )
+ORDER BY d.id
+LIMIT ?2
+```
+
+**Problem**: Three separate EXISTS subqueries, each scanning `embedding_metadata`. SQLite cannot short-circuit across OR'd EXISTS efficiently.
+
+**Proposed Fix**:
+```sql
+SELECT d.id, d.content_text, d.content_hash
+FROM documents d
+LEFT JOIN embedding_metadata em
+  ON em.document_id = d.id AND em.chunk_index = 0
+WHERE d.id > ?1
+  AND (
+    em.document_id IS NULL                      -- no embedding
+    OR em.document_hash != d.content_hash       -- hash mismatch
+    OR em.chunk_max_bytes IS NULL
+    OR em.chunk_max_bytes != ?3
+    OR em.model != ?4
+    OR em.dims != ?5
+  )
+ORDER BY d.id
+LIMIT ?2
+```
+
+**Isomorphism Proof**: Both queries return documents needing embedding when:
+- No embedding exists for chunk_index=0 (NULL check)
+- Hash changed (direct comparison)
+- Config mismatch (model/dims/chunk_max_bytes)
+
+The LEFT JOIN + NULL check is semantically identical to NOT EXISTS. The OR conditions inside WHERE match the EXISTS predicates exactly.
+
+**Expected Impact**: 2-3x faster for large document sets. Single scan of embedding_metadata instead of three.
+
+---
+
+### 2. N+1 Label/Assignee Inserts (ICE: 9.0)
+
+**Location**:
+- `src/ingestion/issues.rs:270-285`
+- `src/ingestion/merge_requests.rs:242-272`
+
+**Current Code**:
+```rust
+for label_name in label_names {
+    let label_id = upsert_label_tx(tx, project_id, label_name, &mut labels_created)?;
+    link_issue_label_tx(tx, local_issue_id, label_id)?;
+}
+```
+
+**Problem**: Each label triggers 2+ SQL statements. With 20 labels × 100 issues = 4000+ queries per batch.
+
+**Proposed Fix**: Batch insert using prepared statements with multi-row VALUES:
+
+```rust
+// Build batch: INSERT INTO issue_labels VALUES (?, ?), (?, ?), ...
+let mut values = String::new();
+let mut params: Vec<Box<dyn ToSql>> = Vec::with_capacity(label_ids.len() * 2);
+for (i, label_id) in label_ids.iter().enumerate() {
+    if i > 0 { values.push_str(","); }
+    values.push_str("(?,?)");
+    params.push(Box::new(local_issue_id));
+    params.push(Box::new(*label_id));
+}
+let sql = format!("INSERT OR IGNORE INTO issue_labels (issue_id, label_id) VALUES {}", values);
+```
+
+Or use `prepare_cached()` pattern from `events_db.rs`.
+
+**Isomorphism Proof**: Both approaches insert identical rows. OR IGNORE handles duplicates identically.
+
+**Expected Impact**: 5-10x faster ingestion for issues/MRs with many labels.
+
+---
+
+### 3. Clone in Embedding Batch Loop (ICE: 9.0)
+
+**Location**: `src/embedding/pipeline.rs:165`
+
+**Current Code**:
+```rust
+let texts: Vec<String> = batch.iter().map(|c| c.text.clone()).collect();
+```
+
+**Problem**: Every batch iteration clones all chunk texts. With BATCH_SIZE=32 and thousands of chunks, this doubles memory allocation in the hot path.
+
+**Proposed Fix**: Transfer ownership instead of cloning:
+
+```rust
+// Option A: Drain chunks from all_chunks instead of iterating
+let texts: Vec<String> = batch.into_iter().map(|c| c.text).collect();
+
+// Option B: Store references in ChunkWork, clone only at API boundary
+struct ChunkWork<'a> {
+    text: &'a str,
+    // ...
+}
+```
+
+**Isomorphism Proof**: Same texts sent to Ollama, same embeddings returned. Order and content identical.
+
+**Expected Impact**: 30-50% reduction in embedding pipeline memory allocation.
+
+---
+
+### 4. Correlated GROUP_CONCAT in List Queries (ICE: 8.5)
+
+**Location**: `src/cli/commands/list.rs:341-348`
+
+**Current Code**:
+```sql
+SELECT i.*,
+       (SELECT GROUP_CONCAT(l.name, X'1F') FROM issue_labels il JOIN labels l ... WHERE il.issue_id = i.id) AS labels_csv,
+       (SELECT COUNT(*) FROM discussions WHERE issue_id = i.id) as discussion_count
+FROM issues i
+```
+
+**Problem**: Each correlated subquery executes per row. With LIMIT 50, that's 100+ subquery executions.
+
+**Proposed Fix**: Use window functions or pre-aggregated CTEs:
+
+```sql
+WITH label_agg AS (
+    SELECT il.issue_id, GROUP_CONCAT(l.name, X'1F') AS labels_csv
+    FROM issue_labels il JOIN labels l ON il.label_id = l.id
+    GROUP BY il.issue_id
+),
+discussion_agg AS (
+    SELECT issue_id, COUNT(*) AS cnt
+    FROM discussions WHERE issue_id IS NOT NULL
+    GROUP BY issue_id
+)
+SELECT i.*, la.labels_csv, da.cnt
+FROM issues i
+LEFT JOIN label_agg la ON la.issue_id = i.id
+LEFT JOIN discussion_agg da ON da.issue_id = i.id
+WHERE ...
+LIMIT 50
+```
+
+**Isomorphism Proof**: Same data returned - labels concatenated, discussion counts accurate. JOIN preserves NULL when no labels/discussions exist.
+
+**Expected Impact**: 3-5x faster list queries with discussion/label data.
+
+---
+
+### 5. Multiple EXISTS Per Label Filter (ICE: 8.0)
+
+**Location**: `src/search/filters.rs:100-107`
+
+**Current Code**:
+```sql
+WHERE EXISTS (SELECT 1 ... AND label_name = ?)
+  AND EXISTS (SELECT 1 ... AND label_name = ?)
+  AND EXISTS (SELECT 1 ... AND label_name = ?)
+```
+
+**Problem**: Filtering by 3 labels generates 3 EXISTS subqueries. Each scans document_labels.
+
+**Proposed Fix**: Single EXISTS with GROUP BY/HAVING:
+
+```sql
+WHERE EXISTS (
+    SELECT 1 FROM document_labels dl
+    WHERE dl.document_id = d.id
+      AND dl.label_name IN (?, ?, ?)
+    GROUP BY dl.document_id
+    HAVING COUNT(DISTINCT dl.label_name) = 3
+)
+```
+
+**Isomorphism Proof**: Both return documents with ALL specified labels. AND of EXISTS = document has label1 AND label2 AND label3. GROUP BY + HAVING COUNT(DISTINCT) = 3 is mathematically equivalent.
+
+**Expected Impact**: 2-4x faster filtered search with multiple labels.
+
+---
+
+### 6. String Allocation in Chunking (ICE: 7.5)
+
+**Location**: `src/embedding/chunking.rs:7-49`
+
+**Current Code**:
+```rust
+chunks.push((chunk_index, remaining.to_string()));
+```
+
+**Problem**: Converts `&str` slices to owned `String` for every chunk. The input is already a `&str`.
+
+**Proposed Fix**: Return borrowed slices or use `Cow`:
+
+```rust
+pub fn split_into_chunks(content: &str) -> Vec<(usize, &str)> {
+    // Return slices into original content
+}
+```
+
+Or if ownership is needed later:
+```rust
+pub fn split_into_chunks(content: &str) -> Vec<(usize, Cow<'_, str>)>
+```
+
+**Isomorphism Proof**: Same chunk boundaries, same text content. Only allocation behavior changes.
+
+**Expected Impact**: Reduces allocations by ~50% in chunking hot path.
+
+---
+
+### 7. Multiple COUNT Queries (ICE: 7.0)
+
+**Location**: `src/cli/commands/count.rs:44-56`
+
+**Current Code**:
+```rust
+let count = conn.query_row("SELECT COUNT(*) FROM issues", ...)?;
+let opened = conn.query_row("SELECT COUNT(*) FROM issues WHERE state = 'opened'", ...)?;
+let closed = conn.query_row("SELECT COUNT(*) FROM issues WHERE state = 'closed'", ...)?;
+```
+
+**Problem**: 5 separate queries for MR state breakdown, 3 for issues.
+
+**Proposed Fix**: Single query with CASE aggregation:
+
+```sql
+SELECT
+    COUNT(*) AS total,
+    SUM(CASE WHEN state = 'opened' THEN 1 ELSE 0 END) AS opened,
+    SUM(CASE WHEN state = 'closed' THEN 1 ELSE 0 END) AS closed
+FROM issues
+```
+
+**Isomorphism Proof**: Identical counts returned. CASE WHEN with SUM is standard SQL for conditional counting.
+
+**Expected Impact**: 3-5x fewer round trips for count command.
+
+---
+
+### 8. Collect-then-Concat Pattern (ICE: 7.0)
+
+**Location**: `src/documents/truncation.rs:60-61`
+
+**Current Code**:
+```rust
+let formatted: Vec<String> = notes.iter().map(format_note).collect();
+let total: String = formatted.concat();
+```
+
+**Problem**: Allocates intermediate Vec<String>, then allocates again for concat.
+
+**Proposed Fix**: Use fold or format directly:
+
+```rust
+let total = notes.iter().fold(String::new(), |mut acc, note| {
+    acc.push_str(&format_note(note));
+    acc
+});
+```
+
+Or with capacity hint:
+```rust
+let total_len: usize = notes.iter().map(|n| estimate_note_len(n)).sum();
+let mut total = String::with_capacity(total_len);
+for note in notes {
+    total.push_str(&format_note(note));
+}
+```
+
+**Isomorphism Proof**: Same concatenated string output. Order preserved.
+
+**Expected Impact**: 50% reduction in allocations for document regeneration.
+
+---
+
+### 9. Box<dyn ToSql> Allocations (ICE: 6.0)
+
+**Location**: `src/search/filters.rs:67-135`
+
+**Current Code**:
+```rust
+let mut params: Vec<Box<dyn rusqlite::types::ToSql>> = vec![Box::new(ids_json)];
+// ... more Box::new() calls
+let param_refs: Vec<&dyn rusqlite::types::ToSql> = params.iter().map(|p| p.as_ref()).collect();
+```
+
+**Problem**: Boxing each parameter, then collecting references. Two allocations per parameter.
+
+**Proposed Fix**: Use rusqlite's params! macro or typed parameter arrays:
+
+```rust
+// For known parameter counts, use arrays
+let params: [&dyn ToSql; 4] = [&ids_json, &author, &state, &limit];
+
+// Or build SQL with named parameters and use params! directly
+```
+
+**Expected Impact**: Eliminates ~15 allocations per filtered search.
+
+---
+
+### 10. Missing Vec::with_capacity (ICE: 5.5)
+
+**Locations**:
+- `src/embedding/pipeline.rs:106`
+- `src/embedding/pipeline.rs:162`
+- Multiple other locations
+
+**Current Code**:
+```rust
+let mut all_chunks: Vec<ChunkWork> = Vec::new();
+```
+
+**Proposed Fix**:
+```rust
+// Estimate: average 3 chunks per document
+let mut all_chunks = Vec::with_capacity(pending.len() * 3);
+```
+
+**Expected Impact**: Eliminates reallocation overhead during vector growth.
+
+---
+
+### 11. FTS Token Collect-Join (ICE: 5.0)
+
+**Location**: `src/search/fts.rs:26-41`
+
+**Current Code**:
+```rust
+let tokens: Vec<String> = trimmed.split_whitespace().map(...).collect();
+tokens.join(" ")
+```
+
+**Proposed Fix**: Use itertools or avoid intermediate vec:
+
+```rust
+use itertools::Itertools;
+trimmed.split_whitespace().map(...).join(" ")
+```
+
+**Expected Impact**: Minor - search queries are typically short.
+
+---
+
+### 12. Transformer String Clones (ICE: 5.0)
+
+**Location**: `src/gitlab/transformers/merge_request.rs:51-77`
+
+**Problem**: Multiple `.clone()` calls on String fields during transformation.
+
+**Proposed Fix**: Use `std::mem::take()` where possible, or restructure to avoid cloning.
+
+**Expected Impact**: Moderate - depends on MR volume.
+
+---
+
+## Regression Guardrails
+
+For any optimization implemented:
+
+1. **Test Coverage**: All existing tests must pass
+2. **Output Equivalence**: For SQL changes, verify identical result sets with test data
+3. **Benchmark Suite**: Add benchmarks for affected paths before/after
+
+Suggested benchmark targets:
+```rust
+#[bench] fn bench_change_detection_1k_docs(b: &mut Bencher) { ... }
+#[bench] fn bench_label_insert_50_labels(b: &mut Bencher) { ... }
+#[bench] fn bench_hybrid_search_filtered(b: &mut Bencher) { ... }
+```
+
+---
+
+## Implementation Priority
+
+**Phase 1 (Quick Wins)** - COMPLETE:
+1. ~~Change detection query rewrite (#1)~~ **DONE**
+2. ~~Multiple COUNT consolidation (#7)~~ **DONE**
+3. ~~Collect-concat pattern (#8)~~ **DONE**
+4. ~~Vec::with_capacity hints (#10)~~ **DONE**
+5. ~~FTS token collect-join (#11)~~ **DONE**
+6. ~~Multiple EXISTS per label (#5)~~ **DONE**
+
+**Phase 2 (Medium Effort)**:
+5. Embedding batch clone removal (#3)
+6. Label filter EXISTS consolidation (#5)
+7. Chunking string allocation (#6)
+
+**Phase 3 (Higher Effort)**:
+8. N+1 batch inserts (#2)
+9. List query CTEs (#4)
+10. Parameter boxing (#9)
+
+---
+
+## Appendix: Test Baseline
+
+```
+cargo test --release
+running 127 tests
+test result: ok. 127 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
+```
+
+All tests pass. Any optimization must maintain this baseline.

README.md

@@ -1,6 +1,6 @@
 # Gitlore
 
-Local GitLab data management with semantic search. Syncs issues, MRs, discussions, and notes from GitLab to a local SQLite database for fast, offline-capable querying, filtering, and hybrid search.
+Local GitLab data management with semantic search, people intelligence, and temporal analysis. Syncs issues, MRs, discussions, notes, and work item statuses from GitLab to a local SQLite database for fast, offline-capable querying, filtering, hybrid search, chronological event reconstruction, and expert discovery.
 
 ## Features
 
@@ -8,11 +8,19 @@ Local GitLab data management with semantic search. Syncs issues, MRs, discussion
 - **Incremental sync**: Cursor-based sync only fetches changes since last sync
 - **Full re-sync**: Reset cursors and fetch all data from scratch when needed
 - **Multi-project**: Track issues and MRs across multiple GitLab projects
-- **Rich filtering**: Filter by state, author, assignee, labels, milestone, due date, draft status, reviewer, branches
+- **Rich filtering**: Filter by state, author, assignee, labels, milestone, due date, draft status, reviewer, branches, work item status
 - **Hybrid search**: Combines FTS5 lexical search with Ollama-powered vector embeddings via Reciprocal Rank Fusion
+- **People intelligence**: Expert discovery, workload analysis, review patterns, active discussions, and code ownership overlap
+- **Timeline pipeline**: Reconstructs chronological event histories by combining search, graph traversal, and event aggregation across related entities
+- **Git history linking**: Tracks merge and squash commit SHAs to connect MRs with git history
+- **File change tracking**: Records which files each MR touches, enabling file-level history queries
 - **Raw payload storage**: Preserves original GitLab API responses for debugging
 - **Discussion threading**: Full support for issue and MR discussions including inline code review comments
-- **Robot mode**: Machine-readable JSON output with structured errors and meaningful exit codes
+- **Cross-reference tracking**: Automatic extraction of "closes", "mentioned" relationships between MRs and issues
+- **Work item status enrichment**: Fetches issue statuses (e.g., "To do", "In progress", "Done") from GitLab's GraphQL API with adaptive page sizing, color-coded display, and case-insensitive filtering
+- **Resource event history**: Tracks state changes, label events, and milestone events for issues and MRs
+- **Robot mode**: Machine-readable JSON output with structured errors, meaningful exit codes, and actionable recovery steps
+- **Observability**: Verbosity controls, JSON log format, structured metrics, and stage timing
 
 ## Installation
 
@@ -54,6 +62,15 @@ lore mrs 456
 # Search across all indexed data
 lore search "authentication bug"
 
+# Who knows about this code area?
+lore who src/features/auth/
+
+# What is @asmith working on?
+lore who @asmith
+
+# Timeline of events related to deployments
+lore timeline "deployment"
+
 # Robot mode (machine-readable JSON)
 lore -J issues -n 5 | jq .
 ```
@@ -74,13 +91,15 @@ Configuration is stored in `~/.config/lore/config.json` (or `$XDG_CONFIG_HOME/lo
     { "path": "group/project" },
     { "path": "other-group/other-project" }
   ],
+  "defaultProject": "group/project",
   "sync": {
     "backfillDays": 14,
     "staleLockMinutes": 10,
     "heartbeatIntervalSeconds": 30,
     "cursorRewindSeconds": 2,
     "primaryConcurrency": 4,
-    "dependentConcurrency": 2
+    "dependentConcurrency": 2,
+    "fetchWorkItemStatus": true
   },
   "storage": {
     "compressRawPayloads": true
@@ -101,12 +120,14 @@ Configuration is stored in `~/.config/lore/config.json` (or `$XDG_CONFIG_HOME/lo
 | `gitlab` | `baseUrl` | -- | GitLab instance URL (required) |
 | `gitlab` | `tokenEnvVar` | `GITLAB_TOKEN` | Environment variable containing API token |
 | `projects` | `path` | -- | Project path (e.g., `group/project`) |
+| *(top-level)* | `defaultProject` | none | Fallback project path used when `-p` is omitted. Must match a configured project path (exact or suffix). CLI `-p` always overrides. |
 | `sync` | `backfillDays` | `14` | Days to backfill on initial sync |
 | `sync` | `staleLockMinutes` | `10` | Minutes before sync lock considered stale |
 | `sync` | `heartbeatIntervalSeconds` | `30` | Frequency of lock heartbeat updates |
 | `sync` | `cursorRewindSeconds` | `2` | Seconds to rewind cursor for overlap safety |
 | `sync` | `primaryConcurrency` | `4` | Concurrent GitLab requests for primary resources |
 | `sync` | `dependentConcurrency` | `2` | Concurrent requests for dependent resources |
+| `sync` | `fetchWorkItemStatus` | `true` | Enrich issues with work item status via GraphQL (requires GitLab Premium/Ultimate) |
 | `storage` | `dbPath` | `~/.local/share/lore/lore.db` | Database file path |
 | `storage` | `backupDir` | `~/.local/share/lore/backups` | Backup directory |
 | `storage` | `compressRawPayloads` | `true` | Compress stored API responses with gzip |
@@ -168,18 +189,24 @@ lore issues --since 1m               # Updated in last month
 lore issues --since 2024-01-01       # Updated since date
 lore issues --due-before 2024-12-31  # Due before date
 lore issues --has-due                 # Only issues with due dates
+lore issues --status "In progress"   # By work item status (case-insensitive)
+lore issues --status "To do" --status "In progress"  # Multiple statuses (OR)
 lore issues -p group/repo            # Filter by project
 lore issues --sort created --asc     # Sort by created date, ascending
 lore issues -o                        # Open first result in browser
+
+# Field selection (robot mode)
+lore -J issues --fields minimal       # Compact: iid, title, state, updated_at_iso
+lore -J issues --fields iid,title,labels,state  # Custom fields
 ```
 
-When listing, output includes: IID, title, state, author, assignee, labels, and update time.
+When listing, output includes: IID, title, state, status (when any issue has one), assignee, labels, and update time. Status values display with their configured color. In robot mode, the `--fields` flag controls which fields appear in the JSON response.
 
-When showing a single issue (e.g., `lore issues 123`), output includes: title, description, state, author, assignees, labels, milestone, due date, web URL, and threaded discussions.
+When showing a single issue (e.g., `lore issues 123`), output includes: title, description, state, work item status (with color and category), author, assignees, labels, milestone, due date, web URL, and threaded discussions.
 
 #### Project Resolution
 
-The `-p` / `--project` flag uses cascading match logic across all commands:
+When `-p` / `--project` is omitted, the `defaultProject` from config is used as a fallback. If neither is set, results span all configured projects. When a project is specified (via `-p` or config default), it uses cascading match logic across all commands:
 
 1. **Exact match**: `group/project`
 2. **Case-insensitive**: `Group/Project`
@@ -214,6 +241,10 @@ lore mrs --since 7d                  # Updated in last 7 days
 lore mrs -p group/repo               # Filter by project
 lore mrs --sort created --asc        # Sort by created date, ascending
 lore mrs -o                           # Open first result in browser
+
+# Field selection (robot mode)
+lore -J mrs --fields minimal          # Compact: iid, title, state, updated_at_iso
+lore -J mrs --fields iid,title,draft,target_branch  # Custom fields
 ```
 
 When listing, output includes: IID, title (with [DRAFT] prefix if applicable), state, author, assignee, labels, and update time.
@@ -242,11 +273,138 @@ lore search "deploy" --explain               # Show ranking explanation per resu
 lore search "deploy" --fts-mode raw          # Raw FTS5 query syntax (advanced)
 ```
 
+The `--fts-mode` flag defaults to `safe`, which sanitizes user input into valid FTS5 queries with automatic fallback. Use `raw` for advanced FTS5 query syntax (AND, OR, NOT, phrase matching, prefix queries).
+
 Requires `lore generate-docs` (or `lore sync`) to have been run at least once. Semantic and hybrid modes require `lore embed` (or `lore sync`) to have generated vector embeddings via Ollama.
 
+### `lore who`
+
+People intelligence: discover experts, analyze workloads, review patterns, active discussions, and code overlap.
+
+#### Expert Mode
+
+Find who has expertise in a code area based on authoring and reviewing history (DiffNote analysis).
+
+```bash
+lore who src/features/auth/           # Who knows about this directory?
+lore who src/features/auth/login.ts   # Who knows about this file?
+lore who --path README.md             # Root files need --path flag
+lore who --path Makefile              # Dotless root files too
+lore who src/ --since 3m              # Limit to recent 3 months
+lore who src/ -p group/repo           # Scope to project
+```
+
+The target is auto-detected as a path when it contains `/`. For root files without `/` (e.g., `README.md`), use the `--path` flag. Default time window: 6 months.
+
+#### Workload Mode
+
+See what someone is currently working on.
+
+```bash
+lore who @asmith                      # Full workload summary
+lore who @asmith -p group/repo       # Scoped to one project
+```
+
+Shows: assigned open issues, authored MRs, MRs under review, and unresolved discussions.
+
+#### Reviews Mode
+
+Analyze someone's code review patterns by area.
+
+```bash
+lore who @asmith --reviews            # Review activity breakdown
+lore who @asmith --reviews --since 3m # Recent review patterns
+```
+
+Shows: total DiffNotes, categorized by code area with percentage breakdown.
+
+#### Active Mode
+
+Surface unresolved discussions needing attention.
+
+```bash
+lore who --active                     # Unresolved discussions (last 7 days)
+lore who --active --since 30d        # Wider time window
+lore who --active -p group/repo      # Scoped to project
+```
+
+Shows: discussion threads with participants and last activity timestamps.
+
+#### Overlap Mode
+
+Find who else is touching a file or directory.
+
+```bash
+lore who --overlap src/features/auth/ # Who else works here?
+lore who --overlap src/lib.rs        # Single file overlap
+```
+
+Shows: users with touch counts (author vs. review), linked MR references. Default time window: 6 months.
+
+#### Common Flags
+
+| Flag | Description |
+|------|-------------|
+| `-p` / `--project` | Scope to a project (fuzzy match) |
+| `--since` | Time window (7d, 2w, 6m, YYYY-MM-DD). Default varies by mode. |
+| `-n` / `--limit` | Max results per section (1-500, default 20) |
+
+### `lore timeline`
+
+Reconstruct a chronological timeline of events matching a keyword query. The pipeline discovers related entities through cross-reference graph traversal and assembles a unified, time-ordered event stream.
+
+```bash
+lore timeline "deployment"                    # Events related to deployments
+lore timeline "auth" -p group/repo           # Scoped to a project
+lore timeline "auth" --since 30d             # Only recent events
+lore timeline "migration" --depth 2          # Deeper cross-reference expansion
+lore timeline "migration" --expand-mentions  # Follow 'mentioned' edges (high fan-out)
+lore timeline "deploy" -n 50                 # Limit event count
+lore timeline "auth" --max-seeds 5           # Fewer seed entities
+```
+
+#### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `-p` / `--project` | all | Scope to a specific project (fuzzy match) |
+| `--since` | none | Only events after this date (7d, 2w, 6m, YYYY-MM-DD) |
+| `--depth` | `1` | Cross-reference expansion depth (0 = seeds only) |
+| `--expand-mentions` | off | Also follow "mentioned" edges during expansion |
+| `-n` / `--limit` | `100` | Maximum events to display |
+| `--max-seeds` | `10` | Maximum seed entities from search |
+| `--max-entities` | `50` | Maximum entities discovered via cross-references |
+| `--max-evidence` | `10` | Maximum evidence notes included |
+
+#### Pipeline Stages
+
+1. **SEED** -- Full-text search identifies the most relevant issues and MRs matching the query. Documents are ranked by BM25 relevance.
+2. **HYDRATE** -- Evidence notes are extracted: the top FTS-matched discussion notes with 200-character snippets explaining *why* each entity was surfaced.
+3. **EXPAND** -- Breadth-first traversal over the `entity_references` graph discovers related entities via "closes", "related", and optionally "mentioned" references up to the configured depth.
+4. **COLLECT** -- Events are gathered for all discovered entities. Event types include: creation, state changes, label adds/removes, milestone assignments, merge events, and evidence notes. Events are sorted chronologically with stable tiebreaking.
+5. **RENDER** -- Events are formatted as human-readable text or structured JSON (robot mode).
+
+#### Event Types
+
+| Event | Description |
+|-------|-------------|
+| `Created` | Entity creation |
+| `StateChanged` | State transitions (opened, closed, reopened) |
+| `LabelAdded` | Label applied to entity |
+| `LabelRemoved` | Label removed from entity |
+| `MilestoneSet` | Milestone assigned |
+| `MilestoneRemoved` | Milestone removed |
+| `Merged` | MR merged (deduplicated against state events) |
+| `NoteEvidence` | Discussion note matched by FTS, with snippet |
+| `CrossReferenced` | Reference to another entity |
+
+#### Unresolved References
+
+When graph expansion encounters cross-project references to entities not yet synced locally, these are collected as unresolved references in the output. This enables discovery of external dependencies and can inform future sync targets.
+
 ### `lore sync`
 
-Run the full sync pipeline: ingest from GitLab, generate searchable documents, and compute embeddings.
+Run the full sync pipeline: ingest from GitLab (including work item status enrichment via GraphQL), generate searchable documents, and compute embeddings.
 
 ```bash
 lore sync                    # Full pipeline
@@ -254,19 +412,24 @@ lore sync --full             # Reset cursors, fetch everything
 lore sync --force            # Override stale lock
 lore sync --no-embed         # Skip embedding step
 lore sync --no-docs          # Skip document regeneration
+lore sync --no-events        # Skip resource event fetching
+lore sync --dry-run          # Preview what would be synced
 ```
 
+The sync command displays animated progress bars for each stage and outputs timing metrics on completion. In robot mode (`-J`), detailed stage timing is included in the JSON response.
+
 ### `lore ingest`
 
-Sync data from GitLab to local database. Runs only the ingestion step (no doc generation or embeddings).
+Sync data from GitLab to local database. Runs only the ingestion step (no doc generation or embeddings). For issue ingestion, this includes a status enrichment phase that fetches work item statuses via the GitLab GraphQL API.
 
 ```bash
 lore ingest                                    # Ingest everything (issues + MRs)
-lore ingest issues                             # Issues only
+lore ingest issues                             # Issues only (includes status enrichment)
 lore ingest mrs                                # MRs only
 lore ingest issues -p group/repo              # Single project
 lore ingest --force                            # Override stale lock
 lore ingest --full                             # Full re-sync (reset cursors)
+lore ingest --dry-run                          # Preview what would change
 ```
 
 The `--full` flag resets sync cursors and discussion watermarks, then fetches all data from scratch. Useful when:
@@ -274,6 +437,8 @@ The `--full` flag resets sync cursors and discussion watermarks, then fetches al
 - You want to ensure complete data after schema changes
 - Troubleshooting sync issues
 
+Status enrichment uses adaptive page sizing (100 → 50 → 25 → 10) to handle GitLab GraphQL complexity limits. It gracefully handles instances without GraphQL support or Premium/Ultimate licensing. Disable via `sync.fetchWorkItemStatus: false` in config.
+
 ### `lore generate-docs`
 
 Extract searchable documents from ingested issues, MRs, and discussions for the FTS5 index.
@@ -290,6 +455,7 @@ Generate vector embeddings for documents via Ollama. Requires Ollama running wit
 
 ```bash
 lore embed                    # Embed new/changed documents
+lore embed --full             # Re-embed all documents (clears existing)
 lore embed --retry-failed     # Retry previously failed embeddings
 ```
 
@@ -305,6 +471,9 @@ lore count discussions --for issue   # Issue discussions only
 lore count discussions --for mr      # MR discussions only
 lore count notes                      # Total notes (system vs user breakdown)
 lore count notes --for issue         # Issue notes only
+lore count events                     # Total resource events
+lore count events --for issue        # Issue events only
+lore count events --for mr           # MR events only
 ```
 
 ### `lore stats`
@@ -315,6 +484,7 @@ Show document and index statistics, with optional integrity checks.
 lore stats                    # Document and index statistics
 lore stats --check            # Run integrity checks
 lore stats --check --repair   # Repair integrity issues
+lore stats --dry-run          # Preview repairs without saving
 ```
 
 ### `lore status`
@@ -340,6 +510,17 @@ lore init --force            # Overwrite existing config
 lore init --non-interactive  # Fail if prompts needed
 ```
 
+When multiple projects are configured, `init` prompts whether to set a default project (used when `-p` is omitted). This can also be set via the `--default-project` flag.
+
+In robot mode, `init` supports non-interactive setup via flags:
+
+```bash
+lore -J init --gitlab-url https://gitlab.com \
+  --token-env-var GITLAB_TOKEN \
+  --projects "group/project,other/project" \
+  --default-project group/project
+```
+
 ### `lore auth`
 
 Verify GitLab authentication is working.
@@ -375,7 +556,7 @@ lore migrate
 
 ### `lore health`
 
-Quick pre-flight check for config, database, and schema version. Exits 0 if healthy, 1 if unhealthy.
+Quick pre-flight check for config, database, and schema version. Exits 0 if healthy, 19 if unhealthy.
 
 ```bash
 lore health
@@ -403,7 +584,7 @@ lore version
 
 ## Robot Mode
 
-Machine-readable JSON output for scripting and AI agent consumption.
+Machine-readable JSON output for scripting and AI agent consumption. All responses use compact (single-line) JSON with a uniform envelope and timing metadata.
 
 ### Activation
 
@@ -423,18 +604,51 @@ lore issues -n 5 | jq .
 
 ### Response Format
 
-All commands return consistent JSON:
+All commands return a consistent JSON envelope to stdout:
 
 ```json
-{"ok": true, "data": {...}, "meta": {...}}
+{"ok":true,"data":{...},"meta":{"elapsed_ms":42}}
 ```
 
-Errors return structured JSON to stderr:
+Every response includes `meta.elapsed_ms` (wall-clock milliseconds for the command).
+
+Errors return structured JSON to stderr with machine-actionable recovery steps:
 
 ```json
-{"error": {"code": "CONFIG_NOT_FOUND", "message": "...", "suggestion": "Run 'lore init'"}}
+{"error":{"code":"CONFIG_NOT_FOUND","message":"...","suggestion":"Run 'lore init'","actions":["lore init"]}}
 ```
 
+The `actions` array contains executable shell commands an agent can run to recover from the error. It is omitted when empty (e.g., for generic I/O errors).
+
+### Field Selection
+
+The `--fields` flag on `issues` and `mrs` list commands controls which fields appear in the JSON response, reducing token usage for AI agent workflows:
+
+```bash
+# Minimal preset (~60% fewer tokens)
+lore -J issues --fields minimal
+
+# Custom field list
+lore -J issues --fields iid,title,state,labels,updated_at_iso
+
+# Available presets
+#   minimal: iid, title, state, updated_at_iso
+```
+
+Valid fields for issues: `iid`, `title`, `state`, `author_username`, `labels`, `assignees`, `discussion_count`, `unresolved_count`, `created_at_iso`, `updated_at_iso`, `web_url`, `project_path`, `status_name`, `status_category`, `status_color`, `status_icon_name`, `status_synced_at_iso`
+
+Valid fields for MRs: `iid`, `title`, `state`, `author_username`, `labels`, `draft`, `target_branch`, `source_branch`, `discussion_count`, `unresolved_count`, `created_at_iso`, `updated_at_iso`, `web_url`, `project_path`, `reviewers`
+
+### Agent Self-Discovery
+
+The `robot-docs` command provides a complete machine-readable manifest including response schemas for every command:
+
+```bash
+lore robot-docs | jq '.data.commands.issues.response_schema'
+```
+
+Each command entry includes `response_schema` describing the shape of its JSON response, `fields_presets` for commands supporting `--fields`, and copy-paste `example` invocations.
+
 ### Exit Codes
 
 | Code | Meaning |
@@ -458,6 +672,7 @@ Errors return structured JSON to stderr:
 | 16 | Embedding failed |
 | 17 | Not found (entity does not exist) |
 | 18 | Ambiguous match (use `-p` to specify project) |
+| 19 | Health check failed |
 | 20 | Config not found |
 
 ## Configuration Precedence
@@ -478,6 +693,10 @@ lore -J <command>                         # JSON shorthand
 lore --color never <command>              # Disable color output
 lore --color always <command>             # Force color output
 lore -q <command>                         # Suppress non-essential output
+lore -v <command>                         # Debug logging
+lore -vv <command>                        # More verbose debug logging
+lore -vvv <command>                       # Trace-level logging
+lore --log-format json <command>          # JSON-formatted log output to stderr
 ```
 
 Color output respects `NO_COLOR` and `CLICOLOR` environment variables in `auto` mode (the default).
@@ -507,8 +726,8 @@ Data is stored in SQLite with WAL mode and foreign keys enabled. Main tables:
 | Table | Purpose |
 |-------|---------|
 | `projects` | Tracked GitLab projects with metadata |
-| `issues` | Issue metadata (title, state, author, due date, milestone) |
-| `merge_requests` | MR metadata (title, state, draft, branches, merge status) |
+| `issues` | Issue metadata (title, state, author, due date, milestone, work item status) |
+| `merge_requests` | MR metadata (title, state, draft, branches, merge status, commit SHAs) |
 | `milestones` | Project milestones with state and due dates |
 | `labels` | Project labels with colors |
 | `issue_labels` | Many-to-many issue-label relationships |
@@ -516,8 +735,13 @@ Data is stored in SQLite with WAL mode and foreign keys enabled. Main tables:
 | `mr_labels` | Many-to-many MR-label relationships |
 | `mr_assignees` | Many-to-many MR-assignee relationships |
 | `mr_reviewers` | Many-to-many MR-reviewer relationships |
+| `mr_file_changes` | Files touched by each MR (path, change type, renames) |
 | `discussions` | Issue/MR discussion threads |
 | `notes` | Individual notes within discussions (with system note flag and DiffNote position data) |
+| `resource_state_events` | Issue/MR state change history (opened, closed, merged, reopened) |
+| `resource_label_events` | Label add/remove events with actor and timestamp |
+| `resource_milestone_events` | Milestone add/remove events with actor and timestamp |
+| `entity_references` | Cross-references between entities (MR closes issue, mentioned in, etc.) |
 | `documents` | Extracted searchable text for FTS and embedding |
 | `documents_fts` | FTS5 full-text search index |
 | `embeddings` | Vector embeddings for semantic search |

build.rs

@@ -5,6 +5,17 @@ fn main() {
         .ok()
         .and_then(|o| String::from_utf8(o.stdout).ok())
         .unwrap_or_default();
-    println!("cargo:rustc-env=GIT_HASH={}", hash.trim());
+    let hash = hash.trim();
+    println!("cargo:rustc-env=GIT_HASH={hash}");
+
+    // Combined version string for clap --version flag
+    let pkg_version = std::env::var("CARGO_PKG_VERSION").unwrap_or_default();
+    if hash.is_empty() {
+        println!("cargo:rustc-env=LORE_VERSION={pkg_version}");
+    } else {
+        println!("cargo:rustc-env=LORE_VERSION={pkg_version} ({hash})");
+    }
+
     println!("cargo:rerun-if-changed=.git/HEAD");
+    println!("cargo:rerun-if-changed=.git/refs/heads");
 }

docs/api-efficiency-findings.md

@@ -1,3 +1,15 @@
+---
+plan: true
+title: "api-efficiency-findings"
+status: drafting
+iteration: 0
+target_iterations: 8
+beads_revision: 0
+related_plans: []
+created: 2026-02-07
+updated: 2026-02-07
+---
+
 # API Efficiency & Observability Findings
 
 > **Status:** Draft - working through items

docs/diagrams/01-human-flow-map.excalidraw

@@ -0,0 +1,245 @@
+{
+  "type": "excalidraw",
+  "version": 2,
+  "source": "https://excalidraw.com",
+  "elements": [
+    { "type": "text", "id": "title", "x": 300, "y": 15, "text": "Human User Flow Map", "fontSize": 28 },
+    { "type": "text", "id": "subtitle", "x": 220, "y": 53, "text": "15 human workflows mapped to lore commands. Arrows show data dependency.", "fontSize": 14, "strokeColor": "#868e96" },
+
+    { "type": "text", "id": "col-trigger", "x": 60, "y": 80, "text": "TRIGGER (Problem)", "fontSize": 16, "strokeColor": "#495057" },
+    { "type": "text", "id": "col-flow", "x": 400, "y": 80, "text": "COMMAND FLOW", "fontSize": 16, "strokeColor": "#495057" },
+    { "type": "text", "id": "col-gap", "x": 880, "y": 80, "text": "GAP", "fontSize": 16, "strokeColor": "#ef4444" },
+
+    { "type": "rectangle", "id": "zone-daily", "x": 20, "y": 110, "width": 960, "height": 190,
+      "backgroundColor": "#dbe4ff", "fillStyle": "solid", "roundness": { "type": 3 },
+      "strokeColor": "#4a9eed", "strokeWidth": 1, "opacity": 20 },
+    { "type": "text", "id": "zone-daily-label", "x": 30, "y": 115, "text": "Daily Operations", "fontSize": 14, "strokeColor": "#1971c2" },
+
+    { "type": "rectangle", "id": "h1-trigger", "x": 30, "y": 140, "width": 200, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
+      "label": { "text": "H1: Standup prep\n\"What moved overnight?\"", "fontSize": 14 } },
+    { "type": "arrow", "id": "h1-a1", "x": 230, "y": 165, "width": 50, "height": 0,
+      "points": [[0,0],[50,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h1-cmd1", "x": 280, "y": 145, "width": 90, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "sync -q", "fontSize": 14 } },
+    { "type": "arrow", "id": "h1-a2", "x": 370, "y": 165, "width": 30, "height": 0,
+      "points": [[0,0],[30,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h1-cmd2", "x": 400, "y": 145, "width": 140, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "issues --since 1d", "fontSize": 14 } },
+    { "type": "arrow", "id": "h1-a3", "x": 540, "y": 165, "width": 30, "height": 0,
+      "points": [[0,0],[30,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h1-cmd3", "x": 570, "y": 145, "width": 130, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "mrs --since 1d", "fontSize": 14 } },
+    { "type": "arrow", "id": "h1-a4", "x": 700, "y": 165, "width": 30, "height": 0,
+      "points": [[0,0],[30,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h1-cmd4", "x": 730, "y": 145, "width": 100, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "who @me", "fontSize": 14 } },
+    { "type": "arrow", "id": "h1-a5", "x": 830, "y": 165, "width": 40, "height": 0,
+      "points": [[0,0],[40,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h1-gap", "x": 870, "y": 140, "width": 100, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444",
+      "label": { "text": "No @me\nNo feed", "fontSize": 14 } },
+
+    { "type": "rectangle", "id": "h3-trigger", "x": 30, "y": 210, "width": 200, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
+      "label": { "text": "H3: Incident\n\"Deploy broke prod\"", "fontSize": 14 } },
+    { "type": "arrow", "id": "h3-a1", "x": 230, "y": 235, "width": 50, "height": 0,
+      "points": [[0,0],[50,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h3-cmd1", "x": 280, "y": 215, "width": 130, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "timeline deploy", "fontSize": 14 } },
+    { "type": "arrow", "id": "h3-a2", "x": 410, "y": 235, "width": 30, "height": 0,
+      "points": [[0,0],[30,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h3-cmd2", "x": 440, "y": 215, "width": 160, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "search deploy --mr", "fontSize": 14 } },
+    { "type": "arrow", "id": "h3-a3", "x": 600, "y": 235, "width": 30, "height": 0,
+      "points": [[0,0],[30,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h3-cmd3", "x": 630, "y": 215, "width": 110, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "mrs <iid>", "fontSize": 14 } },
+    { "type": "arrow", "id": "h3-a4", "x": 740, "y": 235, "width": 30, "height": 0,
+      "points": [[0,0],[30,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h3-cmd4", "x": 770, "y": 215, "width": 100, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "who --overlap", "fontSize": 14 } },
+
+    { "type": "rectangle", "id": "zone-planning", "x": 20, "y": 310, "width": 960, "height": 190,
+      "backgroundColor": "#d3f9d8", "fillStyle": "solid", "roundness": { "type": 3 },
+      "strokeColor": "#22c55e", "strokeWidth": 1, "opacity": 20 },
+    { "type": "text", "id": "zone-planning-label", "x": 30, "y": 315, "text": "Planning & Assignment", "fontSize": 14, "strokeColor": "#15803d" },
+
+    { "type": "rectangle", "id": "h2-trigger", "x": 30, "y": 340, "width": 200, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
+      "label": { "text": "H2: Sprint plan\n\"What's ready to pick?\"", "fontSize": 14 } },
+    { "type": "arrow", "id": "h2-a1", "x": 230, "y": 365, "width": 50, "height": 0,
+      "points": [[0,0],[50,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h2-cmd1", "x": 280, "y": 345, "width": 170, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "issues -s opened -l ready", "fontSize": 13 } },
+    { "type": "arrow", "id": "h2-a2", "x": 450, "y": 365, "width": 30, "height": 0,
+      "points": [[0,0],[30,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h2-cmd2", "x": 480, "y": 345, "width": 150, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "issues --has-due", "fontSize": 14 } },
+    { "type": "arrow", "id": "h2-a3", "x": 630, "y": 365, "width": 230, "height": 0,
+      "points": [[0,0],[230,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h2-gap", "x": 860, "y": 340, "width": 110, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444",
+      "label": { "text": "No\n--no-assignee", "fontSize": 14 } },
+
+    { "type": "rectangle", "id": "h8-trigger", "x": 30, "y": 410, "width": 200, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
+      "label": { "text": "H8: Assign work\n\"Who has bandwidth?\"", "fontSize": 14 } },
+    { "type": "arrow", "id": "h8-a1", "x": 230, "y": 435, "width": 50, "height": 0,
+      "points": [[0,0],[50,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h8-cmd1", "x": 280, "y": 415, "width": 120, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffd8a8", "fillStyle": "solid",
+      "label": { "text": "who @alice", "fontSize": 14 } },
+    { "type": "arrow", "id": "h8-a2", "x": 400, "y": 435, "width": 30, "height": 0,
+      "points": [[0,0],[30,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h8-cmd2", "x": 430, "y": 415, "width": 110, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffd8a8", "fillStyle": "solid",
+      "label": { "text": "who @bob", "fontSize": 14 } },
+    { "type": "arrow", "id": "h8-a3", "x": 540, "y": 435, "width": 30, "height": 0,
+      "points": [[0,0],[30,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h8-cmd3", "x": 570, "y": 415, "width": 120, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffd8a8", "fillStyle": "solid",
+      "label": { "text": "who @carol...", "fontSize": 14 } },
+    { "type": "arrow", "id": "h8-a4", "x": 690, "y": 435, "width": 170, "height": 0,
+      "points": [[0,0],[170,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h8-gap", "x": 860, "y": 410, "width": 110, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444",
+      "label": { "text": "No team\nworkload view", "fontSize": 14 } },
+
+    { "type": "rectangle", "id": "zone-investigation", "x": 20, "y": 510, "width": 960, "height": 260,
+      "backgroundColor": "#fff3bf", "fillStyle": "solid", "roundness": { "type": 3 },
+      "strokeColor": "#f59e0b", "strokeWidth": 1, "opacity": 20 },
+    { "type": "text", "id": "zone-invest-label", "x": 30, "y": 515, "text": "Investigation & Understanding", "fontSize": 14, "strokeColor": "#b45309" },
+
+    { "type": "rectangle", "id": "h7-trigger", "x": 30, "y": 540, "width": 200, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
+      "label": { "text": "H7: Why this way?\n\"Understand a decision\"", "fontSize": 14 } },
+    { "type": "arrow", "id": "h7-a1", "x": 230, "y": 565, "width": 50, "height": 0,
+      "points": [[0,0],[50,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h7-cmd1", "x": 280, "y": 545, "width": 160, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "search \"rationale\"", "fontSize": 14 } },
+    { "type": "arrow", "id": "h7-a2", "x": 440, "y": 565, "width": 30, "height": 0,
+      "points": [[0,0],[30,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h7-cmd2", "x": 470, "y": 545, "width": 140, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "timeline --depth 2", "fontSize": 14 } },
+    { "type": "arrow", "id": "h7-a3", "x": 610, "y": 565, "width": 30, "height": 0,
+      "points": [[0,0],[30,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h7-cmd3", "x": 640, "y": 545, "width": 100, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "issues 234", "fontSize": 14 } },
+    { "type": "arrow", "id": "h7-a4", "x": 740, "y": 565, "width": 120, "height": 0,
+      "points": [[0,0],[120,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h7-gap", "x": 860, "y": 540, "width": 110, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444",
+      "label": { "text": "No per-note\nsearch", "fontSize": 14 } },
+
+    { "type": "rectangle", "id": "h11-trigger", "x": 30, "y": 610, "width": 200, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
+      "label": { "text": "H11: Bug lifecycle\n\"Why does #321 reopen?\"", "fontSize": 14 } },
+    { "type": "arrow", "id": "h11-a1", "x": 230, "y": 635, "width": 50, "height": 0,
+      "points": [[0,0],[50,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h11-cmd1", "x": 280, "y": 615, "width": 120, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "issues 321", "fontSize": 14 } },
+    { "type": "arrow", "id": "h11-a2", "x": 400, "y": 635, "width": 30, "height": 0,
+      "points": [[0,0],[30,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h11-cmd2", "x": 430, "y": 615, "width": 130, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffd8a8", "fillStyle": "solid",
+      "label": { "text": "timeline ???", "fontSize": 14 } },
+    { "type": "arrow", "id": "h11-a3", "x": 560, "y": 635, "width": 300, "height": 0,
+      "points": [[0,0],[300,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h11-gap", "x": 860, "y": 610, "width": 110, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444",
+      "label": { "text": "No entity\ntimeline", "fontSize": 14 } },
+
+    { "type": "rectangle", "id": "h14-trigger", "x": 30, "y": 680, "width": 200, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
+      "label": { "text": "H14: Prior art?\n\"Was this tried before?\"", "fontSize": 14 } },
+    { "type": "arrow", "id": "h14-a1", "x": 230, "y": 705, "width": 50, "height": 0,
+      "points": [[0,0],[50,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h14-cmd1", "x": 280, "y": 685, "width": 170, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "search \"memory leak\"", "fontSize": 14 } },
+    { "type": "arrow", "id": "h14-a2", "x": 450, "y": 705, "width": 30, "height": 0,
+      "points": [[0,0],[30,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h14-cmd2", "x": 480, "y": 685, "width": 120, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffd8a8", "fillStyle": "solid",
+      "label": { "text": "mrs --closed?", "fontSize": 14 } },
+    { "type": "arrow", "id": "h14-a3", "x": 600, "y": 705, "width": 260, "height": 0,
+      "points": [[0,0],[260,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h14-gap", "x": 860, "y": 680, "width": 110, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444",
+      "label": { "text": "No --state\non search", "fontSize": 14 } },
+
+    { "type": "rectangle", "id": "zone-people", "x": 20, "y": 780, "width": 960, "height": 190,
+      "backgroundColor": "#e5dbff", "fillStyle": "solid", "roundness": { "type": 3 },
+      "strokeColor": "#8b5cf6", "strokeWidth": 1, "opacity": 20 },
+    { "type": "text", "id": "zone-people-label", "x": 30, "y": 785, "text": "People & Expertise", "fontSize": 14, "strokeColor": "#7048e8" },
+
+    { "type": "rectangle", "id": "h4-trigger", "x": 30, "y": 810, "width": 200, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
+      "label": { "text": "H4: Review prep\n\"Context for MR !789\"", "fontSize": 14 } },
+    { "type": "arrow", "id": "h4-a1", "x": 230, "y": 835, "width": 50, "height": 0,
+      "points": [[0,0],[50,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h4-cmd1", "x": 280, "y": 815, "width": 100, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "mrs 789", "fontSize": 14 } },
+    { "type": "arrow", "id": "h4-a2", "x": 380, "y": 835, "width": 30, "height": 0,
+      "points": [[0,0],[30,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h4-cmd2", "x": 410, "y": 815, "width": 120, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "who src/auth/", "fontSize": 14 } },
+    { "type": "arrow", "id": "h4-a3", "x": 530, "y": 835, "width": 30, "height": 0,
+      "points": [[0,0],[30,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h4-cmd3", "x": 560, "y": 815, "width": 130, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "search \"auth\"", "fontSize": 14 } },
+    { "type": "arrow", "id": "h4-a4", "x": 690, "y": 835, "width": 170, "height": 0,
+      "points": [[0,0],[170,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h4-gap", "x": 860, "y": 810, "width": 110, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444",
+      "label": { "text": "No MR file\nlist output", "fontSize": 14 } },
+
+    { "type": "rectangle", "id": "h6-trigger", "x": 30, "y": 880, "width": 200, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
+      "label": { "text": "H6: Find reviewer\n\"Who should review?\"", "fontSize": 14 } },
+    { "type": "arrow", "id": "h6-a1", "x": 230, "y": 905, "width": 50, "height": 0,
+      "points": [[0,0],[50,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h6-cmd1", "x": 280, "y": 885, "width": 130, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffd8a8", "fillStyle": "solid",
+      "label": { "text": "who src/auth/", "fontSize": 14 } },
+    { "type": "arrow", "id": "h6-a2", "x": 410, "y": 905, "width": 30, "height": 0,
+      "points": [[0,0],[30,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h6-cmd2", "x": 440, "y": 885, "width": 140, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffd8a8", "fillStyle": "solid",
+      "label": { "text": "who src/pay/", "fontSize": 14 } },
+    { "type": "arrow", "id": "h6-a3", "x": 580, "y": 905, "width": 30, "height": 0,
+      "points": [[0,0],[30,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h6-cmd3", "x": 610, "y": 885, "width": 140, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffd8a8", "fillStyle": "solid",
+      "label": { "text": "who @candidate", "fontSize": 14 } },
+    { "type": "arrow", "id": "h6-a4", "x": 750, "y": 905, "width": 110, "height": 0,
+      "points": [[0,0],[110,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "h6-gap", "x": 860, "y": 880, "width": 110, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444",
+      "label": { "text": "No multi-\npath query", "fontSize": 14 } },
+
+    { "type": "text", "id": "callout-1", "x": 30, "y": 990, "text": "Pattern: Most human flows require 3-5 serial commands. Average gap rate: 73% of flows have at least one.", "fontSize": 14, "strokeColor": "#495057" },
+    { "type": "text", "id": "callout-2", "x": 30, "y": 1015, "text": "Top optimization: Composite commands (activity feed, team workload) would reduce multi-command flows by ~40%.", "fontSize": 14, "strokeColor": "#15803d" },
+    { "type": "text", "id": "callout-3", "x": 30, "y": 1040, "text": "Top missing data: MR file changes and entity references are stored but invisible to CLI users.", "fontSize": 14, "strokeColor": "#ef4444" }
+  ],
+  "appState": { "viewBackgroundColor": "#ffffff", "gridSize": null },
+  "files": {}
+}

docs/diagrams/02-agent-flow-map.excalidraw

@@ -0,0 +1,204 @@
+{
+  "type": "excalidraw",
+  "version": 2,
+  "source": "https://excalidraw.com",
+  "elements": [
+    { "type": "text", "id": "title", "x": 320, "y": 15, "text": "AI Agent Flow Map", "fontSize": 28 },
+    { "type": "text", "id": "subtitle", "x": 180, "y": 53, "text": "15 agent automation workflows. Agents need structured JSON (-J), exit codes, and field selection.", "fontSize": 14, "strokeColor": "#868e96" },
+
+    { "type": "text", "id": "col-trigger", "x": 60, "y": 80, "text": "TRIGGER (Agent Goal)", "fontSize": 16, "strokeColor": "#495057" },
+    { "type": "text", "id": "col-flow", "x": 400, "y": 80, "text": "COMMAND PIPELINE", "fontSize": 16, "strokeColor": "#495057" },
+    { "type": "text", "id": "col-gap", "x": 880, "y": 80, "text": "BLOCKED BY", "fontSize": 16, "strokeColor": "#ef4444" },
+
+    { "type": "rectangle", "id": "zone-context", "x": 20, "y": 110, "width": 960, "height": 200,
+      "backgroundColor": "#e5dbff", "fillStyle": "solid", "roundness": { "type": 3 },
+      "strokeColor": "#8b5cf6", "strokeWidth": 1, "opacity": 20 },
+    { "type": "text", "id": "zone-context-label", "x": 30, "y": 115, "text": "Context Gathering (pre-action)", "fontSize": 14, "strokeColor": "#7048e8" },
+
+    { "type": "rectangle", "id": "a1-trigger", "x": 30, "y": 140, "width": 200, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#d0bfff", "fillStyle": "solid",
+      "label": { "text": "A1: Pre-edit context\nAbout to modify files", "fontSize": 14 } },
+    { "type": "arrow", "id": "a1-a1", "x": 230, "y": 165, "width": 50, "height": 0,
+      "points": [[0,0],[50,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "a1-cmd1", "x": 280, "y": 145, "width": 80, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "-J health", "fontSize": 14 } },
+    { "type": "arrow", "id": "a1-a2", "x": 360, "y": 165, "width": 20, "height": 0,
+      "points": [[0,0],[20,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "a1-cmd2", "x": 380, "y": 145, "width": 140, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "-J who src/auth/", "fontSize": 14 } },
+    { "type": "arrow", "id": "a1-a3", "x": 520, "y": 165, "width": 20, "height": 0,
+      "points": [[0,0],[20,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "a1-cmd3", "x": 540, "y": 145, "width": 170, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "-J search \"auth\" -n 10", "fontSize": 14 } },
+    { "type": "arrow", "id": "a1-a4", "x": 710, "y": 165, "width": 20, "height": 0,
+      "points": [[0,0],[20,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "a1-cmd4", "x": 730, "y": 145, "width": 130, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "-J who --overlap", "fontSize": 14 } },
+
+    { "type": "rectangle", "id": "a6-trigger", "x": 30, "y": 210, "width": 200, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#d0bfff", "fillStyle": "solid",
+      "label": { "text": "A6: Auto-assign reviewers\nBased on file expertise", "fontSize": 14 } },
+    { "type": "arrow", "id": "a6-a1", "x": 230, "y": 235, "width": 50, "height": 0,
+      "points": [[0,0],[50,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "a6-cmd1", "x": 280, "y": 215, "width": 100, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffd8a8", "fillStyle": "solid",
+      "label": { "text": "-J mrs 456", "fontSize": 14 } },
+    { "type": "text", "id": "a6-block", "x": 390, "y": 218, "text": "file list not\nin response!", "fontSize": 12, "strokeColor": "#ef4444" },
+    { "type": "arrow", "id": "a6-a2", "x": 380, "y": 245, "width": 480, "height": -10,
+      "points": [[0,0],[480,-10]], "endArrowhead": "arrow", "strokeColor": "#ef4444", "strokeStyle": "dashed" },
+    { "type": "rectangle", "id": "a6-gap", "x": 860, "y": 210, "width": 110, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444",
+      "label": { "text": "MR files\nnot exposed", "fontSize": 14 } },
+
+    { "type": "rectangle", "id": "zone-report", "x": 20, "y": 320, "width": 960, "height": 200,
+      "backgroundColor": "#d3f9d8", "fillStyle": "solid", "roundness": { "type": 3 },
+      "strokeColor": "#22c55e", "strokeWidth": 1, "opacity": 20 },
+    { "type": "text", "id": "zone-report-label", "x": 30, "y": 325, "text": "Reporting & Synthesis", "fontSize": 14, "strokeColor": "#15803d" },
+
+    { "type": "rectangle", "id": "a3-trigger", "x": 30, "y": 350, "width": 200, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#d0bfff", "fillStyle": "solid",
+      "label": { "text": "A3: Sprint status report\n7 queries for 1 report", "fontSize": 14 } },
+    { "type": "arrow", "id": "a3-a1", "x": 230, "y": 375, "width": 50, "height": 0,
+      "points": [[0,0],[50,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "a3-cmd1", "x": 280, "y": 352, "width": 100, "height": 36,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "issues -s closed", "fontSize": 12 } },
+    { "type": "rectangle", "id": "a3-cmd2", "x": 390, "y": 352, "width": 100, "height": 36,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "issues --status", "fontSize": 12 } },
+    { "type": "rectangle", "id": "a3-cmd3", "x": 500, "y": 352, "width": 100, "height": 36,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "mrs -s merged", "fontSize": 12 } },
+    { "type": "rectangle", "id": "a3-cmd4", "x": 610, "y": 352, "width": 80, "height": 36,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "mrs -s open", "fontSize": 12 } },
+    { "type": "rectangle", "id": "a3-cmd5", "x": 700, "y": 352, "width": 80, "height": 36,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "count x2", "fontSize": 12 } },
+    { "type": "rectangle", "id": "a3-cmd6", "x": 790, "y": 352, "width": 60, "height": 36,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "who", "fontSize": 12 } },
+    { "type": "arrow", "id": "a3-agap", "x": 850, "y": 370, "width": 20, "height": 0,
+      "points": [[0,0],[20,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "a3-gap", "x": 860, "y": 350, "width": 110, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444",
+      "label": { "text": "No summary\ncommand", "fontSize": 14 } },
+    { "type": "text", "id": "a3-note", "x": 280, "y": 395, "text": "7 sequential API calls for one report. A `lore summary` could reduce to 1.", "fontSize": 12, "strokeColor": "#868e96" },
+
+    { "type": "rectangle", "id": "a7-trigger", "x": 30, "y": 430, "width": 200, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#d0bfff", "fillStyle": "solid",
+      "label": { "text": "A7: Incident timeline\nPostmortem reconstruction", "fontSize": 14 } },
+    { "type": "arrow", "id": "a7-a1", "x": 230, "y": 455, "width": 50, "height": 0,
+      "points": [[0,0],[50,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "a7-cmd1", "x": 280, "y": 435, "width": 190, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "-J timeline --depth 2", "fontSize": 14 } },
+    { "type": "arrow", "id": "a7-a2", "x": 470, "y": 455, "width": 20, "height": 0,
+      "points": [[0,0],[20,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "a7-cmd2", "x": 490, "y": 435, "width": 170, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "-J search --since 3d", "fontSize": 14 } },
+    { "type": "arrow", "id": "a7-a3", "x": 660, "y": 455, "width": 20, "height": 0,
+      "points": [[0,0],[20,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "a7-cmd3", "x": 680, "y": 435, "width": 170, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "-J mrs -s merged", "fontSize": 14 } },
+
+    { "type": "rectangle", "id": "zone-discover", "x": 20, "y": 530, "width": 960, "height": 200,
+      "backgroundColor": "#fff3bf", "fillStyle": "solid", "roundness": { "type": 3 },
+      "strokeColor": "#f59e0b", "strokeWidth": 1, "opacity": 20 },
+    { "type": "text", "id": "zone-discover-label", "x": 30, "y": 535, "text": "Discovery & Correlation", "fontSize": 14, "strokeColor": "#b45309" },
+
+    { "type": "rectangle", "id": "a5-trigger", "x": 30, "y": 560, "width": 200, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#d0bfff", "fillStyle": "solid",
+      "label": { "text": "A5: PR description\nFind related issues to link", "fontSize": 14 } },
+    { "type": "arrow", "id": "a5-a1", "x": 230, "y": 585, "width": 50, "height": 0,
+      "points": [[0,0],[50,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "a5-cmd1", "x": 280, "y": 565, "width": 170, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "-J search keywords", "fontSize": 14 } },
+    { "type": "arrow", "id": "a5-a2", "x": 450, "y": 585, "width": 20, "height": 0,
+      "points": [[0,0],[20,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "a5-cmd2", "x": 470, "y": 565, "width": 180, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "-J issues --fields iid,url", "fontSize": 14 } },
+    { "type": "arrow", "id": "a5-a3", "x": 650, "y": 585, "width": 210, "height": 0,
+      "points": [[0,0],[210,0]], "endArrowhead": "arrow", "strokeColor": "#ef4444", "strokeStyle": "dashed" },
+    { "type": "rectangle", "id": "a5-gap", "x": 860, "y": 560, "width": 110, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444",
+      "label": { "text": "No refs\nquery", "fontSize": 14 } },
+    { "type": "text", "id": "a5-note", "x": 280, "y": 612, "text": "Agent can't ask \"which issues does MR !456 close?\" -- entity_references data exists but isn't queryable.", "fontSize": 12, "strokeColor": "#868e96" },
+
+    { "type": "rectangle", "id": "a11-trigger", "x": 30, "y": 640, "width": 200, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#d0bfff", "fillStyle": "solid",
+      "label": { "text": "A11: Knowledge graph\nMap entity relationships", "fontSize": 14 } },
+    { "type": "arrow", "id": "a11-a1", "x": 230, "y": 665, "width": 50, "height": 0,
+      "points": [[0,0],[50,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "a11-cmd1", "x": 280, "y": 645, "width": 140, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "-J search -n 30", "fontSize": 14 } },
+    { "type": "arrow", "id": "a11-a2", "x": 420, "y": 665, "width": 20, "height": 0,
+      "points": [[0,0],[20,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "a11-cmd2", "x": 440, "y": 645, "width": 190, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "-J timeline --depth 2", "fontSize": 14 } },
+    { "type": "arrow", "id": "a11-a3", "x": 630, "y": 665, "width": 230, "height": 0,
+      "points": [[0,0],[230,0]], "endArrowhead": "arrow", "strokeColor": "#ef4444", "strokeStyle": "dashed" },
+    { "type": "rectangle", "id": "a11-gap", "x": 860, "y": 640, "width": 110, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444",
+      "label": { "text": "No refs\nquery", "fontSize": 14 } },
+
+    { "type": "rectangle", "id": "zone-maint", "x": 20, "y": 740, "width": 960, "height": 140,
+      "backgroundColor": "#dbe4ff", "fillStyle": "solid", "roundness": { "type": 3 },
+      "strokeColor": "#4a9eed", "strokeWidth": 1, "opacity": 20 },
+    { "type": "text", "id": "zone-maint-label", "x": 30, "y": 745, "text": "Maintenance & Cleanup", "fontSize": 14, "strokeColor": "#1971c2" },
+
+    { "type": "rectangle", "id": "a9-trigger", "x": 30, "y": 770, "width": 200, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#d0bfff", "fillStyle": "solid",
+      "label": { "text": "A9: Stale issue cleanup\nWeekly backlog hygiene", "fontSize": 14 } },
+    { "type": "arrow", "id": "a9-a1", "x": 230, "y": 795, "width": 50, "height": 0,
+      "points": [[0,0],[50,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "a9-cmd1", "x": 280, "y": 775, "width": 200, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "-J issues --sort updated --asc", "fontSize": 12 } },
+    { "type": "arrow", "id": "a9-a2", "x": 480, "y": 795, "width": 20, "height": 0,
+      "points": [[0,0],[20,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "a9-cmd2", "x": 500, "y": 775, "width": 120, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffd8a8", "fillStyle": "solid",
+      "label": { "text": "filter client-side", "fontSize": 14 } },
+    { "type": "arrow", "id": "a9-a3", "x": 620, "y": 795, "width": 240, "height": 0,
+      "points": [[0,0],[240,0]], "endArrowhead": "arrow", "strokeColor": "#ef4444", "strokeStyle": "dashed" },
+    { "type": "rectangle", "id": "a9-gap", "x": 860, "y": 770, "width": 110, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444",
+      "label": { "text": "No --before\nNo offset", "fontSize": 14 } },
+
+    { "type": "rectangle", "id": "a15-trigger", "x": 30, "y": 840, "width": 200, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#d0bfff", "fillStyle": "solid",
+      "label": { "text": "A15: Conflict detect\n\"Safe to start work?\"", "fontSize": 14 } },
+    { "type": "arrow", "id": "a15-a1", "x": 230, "y": 865, "width": 50, "height": 0,
+      "points": [[0,0],[50,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "a15-cmd1", "x": 280, "y": 845, "width": 110, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "-J issues 123", "fontSize": 14 } },
+    { "type": "arrow", "id": "a15-a2", "x": 390, "y": 865, "width": 20, "height": 0,
+      "points": [[0,0],[20,0]], "endArrowhead": "arrow" },
+    { "type": "rectangle", "id": "a15-cmd2", "x": 410, "y": 845, "width": 130, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "-J who --overlap", "fontSize": 14 } },
+    { "type": "arrow", "id": "a15-a3", "x": 540, "y": 865, "width": 320, "height": 0,
+      "points": [[0,0],[320,0]], "endArrowhead": "arrow", "strokeColor": "#ef4444", "strokeStyle": "dashed" },
+    { "type": "rectangle", "id": "a15-gap", "x": 860, "y": 840, "width": 110, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444",
+      "label": { "text": "No refs +\n--state", "fontSize": 14 } },
+
+    { "type": "text", "id": "callout-1", "x": 30, "y": 910, "text": "Agent-specific pain: Agents always use -J and --fields minimal for token efficiency. Every extra query burns tokens.", "fontSize": 14, "strokeColor": "#495057" },
+    { "type": "text", "id": "callout-2", "x": 30, "y": 935, "text": "Biggest ROI: `lore refs` command would unblock A5, A11, A12, A15 instantly. Data already exists in entity_references table.", "fontSize": 14, "strokeColor": "#15803d" },
+    { "type": "text", "id": "callout-3", "x": 30, "y": 960, "text": "Token waste: Sprint report (A3) requires 7 calls. A composite `lore summary` could save ~85% of tokens.", "fontSize": 14, "strokeColor": "#ef4444" }
+  ],
+  "appState": { "viewBackgroundColor": "#ffffff", "gridSize": null },
+  "files": {}
+}

docs/diagrams/03-command-coverage.excalidraw

@@ -0,0 +1,203 @@
+{
+  "type": "excalidraw",
+  "version": 2,
+  "source": "https://excalidraw.com",
+  "elements": [
+    { "type": "text", "id": "title", "x": 280, "y": 15, "text": "Command Coverage Heatmap", "fontSize": 28 },
+    { "type": "text", "id": "subtitle", "x": 220, "y": 53, "text": "Which commands serve which workflows? Darker = more essential to that flow.", "fontSize": 14, "strokeColor": "#868e96" },
+
+    { "type": "text", "id": "col-issues", "x": 260, "y": 85, "text": "issues", "fontSize": 14, "strokeColor": "#1971c2" },
+    { "type": "text", "id": "col-mrs", "x": 330, "y": 85, "text": "mrs", "fontSize": 14, "strokeColor": "#1971c2" },
+    { "type": "text", "id": "col-search", "x": 390, "y": 85, "text": "search", "fontSize": 14, "strokeColor": "#1971c2" },
+    { "type": "text", "id": "col-who", "x": 465, "y": 85, "text": "who", "fontSize": 14, "strokeColor": "#1971c2" },
+    { "type": "text", "id": "col-timeline", "x": 520, "y": 85, "text": "timeline", "fontSize": 14, "strokeColor": "#1971c2" },
+    { "type": "text", "id": "col-sync", "x": 600, "y": 85, "text": "sync", "fontSize": 14, "strokeColor": "#1971c2" },
+    { "type": "text", "id": "col-count", "x": 660, "y": 85, "text": "count", "fontSize": 14, "strokeColor": "#1971c2" },
+    { "type": "text", "id": "col-status", "x": 720, "y": 85, "text": "status", "fontSize": 14, "strokeColor": "#1971c2" },
+    { "type": "text", "id": "col-missing", "x": 790, "y": 85, "text": "MISSING?", "fontSize": 14, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "grp-human", "x": 15, "y": 108, "text": "HUMAN FLOWS", "fontSize": 14, "strokeColor": "#15803d" },
+
+    { "type": "text", "id": "h1-label", "x": 15, "y": 135, "text": "H1  Standup prep", "fontSize": 14 },
+    { "type": "rectangle", "id": "h1-issues", "x": 255, "y": 130, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h1-mrs", "x": 325, "y": 130, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h1-who", "x": 460, "y": 130, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h1-sync", "x": 595, "y": 130, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "text", "id": "h1-gap", "x": 780, "y": 135, "text": "activity feed", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "h2-label", "x": 15, "y": 170, "text": "H2  Sprint planning", "fontSize": 14 },
+    { "type": "rectangle", "id": "h2-issues", "x": 255, "y": 165, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h2-count", "x": 655, "y": 165, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "text", "id": "h2-gap", "x": 780, "y": 170, "text": "--no-assignee", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "h3-label", "x": 15, "y": 205, "text": "H3  Incident response", "fontSize": 14 },
+    { "type": "rectangle", "id": "h3-mrs", "x": 325, "y": 200, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h3-search", "x": 390, "y": 200, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h3-who", "x": 460, "y": 200, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h3-timeline", "x": 525, "y": 200, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h3-sync", "x": 595, "y": 200, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+
+    { "type": "text", "id": "h4-label", "x": 15, "y": 240, "text": "H4  Code review prep", "fontSize": 14 },
+    { "type": "rectangle", "id": "h4-mrs", "x": 325, "y": 235, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h4-search", "x": 390, "y": 235, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h4-who", "x": 460, "y": 235, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h4-timeline", "x": 525, "y": 235, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "text", "id": "h4-gap", "x": 780, "y": 240, "text": "MR file list", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "h5-label", "x": 15, "y": 275, "text": "H5  Onboarding", "fontSize": 14 },
+    { "type": "rectangle", "id": "h5-issues", "x": 255, "y": 270, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h5-mrs", "x": 325, "y": 270, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h5-search", "x": 390, "y": 270, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h5-who", "x": 460, "y": 270, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h5-timeline", "x": 525, "y": 270, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+
+    { "type": "text", "id": "h6-label", "x": 15, "y": 310, "text": "H6  Find reviewer", "fontSize": 14 },
+    { "type": "rectangle", "id": "h6-who", "x": 460, "y": 305, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "text", "id": "h6-gap", "x": 780, "y": 310, "text": "multi-path who", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "h7-label", "x": 15, "y": 345, "text": "H7  Why was this built?", "fontSize": 14 },
+    { "type": "rectangle", "id": "h7-issues", "x": 255, "y": 340, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h7-mrs", "x": 325, "y": 340, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h7-search", "x": 390, "y": 340, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h7-timeline", "x": 525, "y": 340, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "text", "id": "h7-gap", "x": 780, "y": 345, "text": "per-note search", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "h8-label", "x": 15, "y": 380, "text": "H8  Team workload", "fontSize": 14 },
+    { "type": "rectangle", "id": "h8-who", "x": 460, "y": 375, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "text", "id": "h8-gap", "x": 780, "y": 380, "text": "team view", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "h9-label", "x": 15, "y": 415, "text": "H9  Release notes", "fontSize": 14 },
+    { "type": "rectangle", "id": "h9-issues", "x": 255, "y": 410, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h9-mrs", "x": 325, "y": 410, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "text", "id": "h9-gap", "x": 780, "y": 415, "text": "mrs --milestone", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "h10-label", "x": 15, "y": 450, "text": "H10 Stale issues", "fontSize": 14 },
+    { "type": "rectangle", "id": "h10-issues", "x": 255, "y": 445, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "text", "id": "h10-gap", "x": 780, "y": 450, "text": "--updated-before", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "h11-label", "x": 15, "y": 485, "text": "H11 Bug lifecycle", "fontSize": 14 },
+    { "type": "rectangle", "id": "h11-issues", "x": 255, "y": 480, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h11-timeline", "x": 525, "y": 480, "width": 50, "height": 28, "backgroundColor": "#ffd8a8", "fillStyle": "solid" },
+    { "type": "text", "id": "h11-gap", "x": 780, "y": 485, "text": "entity timeline", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "h12-label", "x": 15, "y": 520, "text": "H12 Who broke tests?", "fontSize": 14 },
+    { "type": "rectangle", "id": "h12-search", "x": 390, "y": 515, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h12-who", "x": 460, "y": 515, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+
+    { "type": "text", "id": "h13-label", "x": 15, "y": 555, "text": "H13 Feature tracking", "fontSize": 14 },
+    { "type": "rectangle", "id": "h13-issues", "x": 255, "y": 550, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h13-mrs", "x": 325, "y": 550, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h13-timeline", "x": 525, "y": 550, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+
+    { "type": "text", "id": "h14-label", "x": 15, "y": 590, "text": "H14 Prior art check", "fontSize": 14 },
+    { "type": "rectangle", "id": "h14-search", "x": 390, "y": 585, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "h14-timeline", "x": 525, "y": 585, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "text", "id": "h14-gap", "x": 780, "y": 590, "text": "--state on search", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "h15-label", "x": 15, "y": 625, "text": "H15 My discussions", "fontSize": 14 },
+    { "type": "rectangle", "id": "h15-who", "x": 460, "y": 620, "width": 50, "height": 28, "backgroundColor": "#ffd8a8", "fillStyle": "solid" },
+    { "type": "text", "id": "h15-gap", "x": 780, "y": 625, "text": "participant filter", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "rectangle", "id": "divider", "x": 10, "y": 655, "width": 910, "height": 2, "backgroundColor": "#dee2e6", "fillStyle": "solid" },
+
+    { "type": "text", "id": "grp-agent", "x": 15, "y": 668, "text": "AI AGENT FLOWS", "fontSize": 14, "strokeColor": "#7048e8" },
+
+    { "type": "text", "id": "a1-label", "x": 15, "y": 695, "text": "A1  Pre-edit context", "fontSize": 14 },
+    { "type": "rectangle", "id": "a1-mrs", "x": 325, "y": 690, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a1-search", "x": 390, "y": 690, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a1-who", "x": 460, "y": 690, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+
+    { "type": "text", "id": "a2-label", "x": 15, "y": 730, "text": "A2  Auto-triage", "fontSize": 14 },
+    { "type": "rectangle", "id": "a2-issues", "x": 255, "y": 725, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a2-search", "x": 390, "y": 725, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a2-who", "x": 460, "y": 725, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "text", "id": "a2-gap", "x": 780, "y": 730, "text": "detail --fields", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "a3-label", "x": 15, "y": 765, "text": "A3  Sprint report", "fontSize": 14 },
+    { "type": "rectangle", "id": "a3-issues", "x": 255, "y": 760, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a3-mrs", "x": 325, "y": 760, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a3-who", "x": 460, "y": 760, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a3-count", "x": 655, "y": 760, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "text", "id": "a3-gap", "x": 780, "y": 765, "text": "summary cmd", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "a4-label", "x": 15, "y": 800, "text": "A4  Prior art", "fontSize": 14 },
+    { "type": "rectangle", "id": "a4-search", "x": 390, "y": 795, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a4-timeline", "x": 525, "y": 795, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "text", "id": "a4-gap", "x": 780, "y": 800, "text": "per-note search", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "a5-label", "x": 15, "y": 835, "text": "A5  PR description", "fontSize": 14 },
+    { "type": "rectangle", "id": "a5-issues", "x": 255, "y": 830, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a5-search", "x": 390, "y": 830, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "text", "id": "a5-gap", "x": 780, "y": 835, "text": "entity refs query", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "a6-label", "x": 15, "y": 870, "text": "A6  Reviewer assign", "fontSize": 14 },
+    { "type": "rectangle", "id": "a6-mrs", "x": 325, "y": 865, "width": 50, "height": 28, "backgroundColor": "#ffd8a8", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a6-who", "x": 460, "y": 865, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "text", "id": "a6-gap", "x": 780, "y": 870, "text": "MR file list", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "a7-label", "x": 15, "y": 905, "text": "A7  Incident timeline", "fontSize": 14 },
+    { "type": "rectangle", "id": "a7-mrs", "x": 325, "y": 900, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a7-search", "x": 390, "y": 900, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a7-timeline", "x": 525, "y": 900, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+
+    { "type": "text", "id": "a8-label", "x": 15, "y": 940, "text": "A8  Cross-project", "fontSize": 14 },
+    { "type": "rectangle", "id": "a8-search", "x": 390, "y": 935, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a8-timeline", "x": 525, "y": 935, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "text", "id": "a8-gap", "x": 780, "y": 940, "text": "group by project", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "a9-label", "x": 15, "y": 975, "text": "A9  Stale cleanup", "fontSize": 14 },
+    { "type": "rectangle", "id": "a9-issues", "x": 255, "y": 970, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a9-search", "x": 390, "y": 970, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "text", "id": "a9-gap", "x": 780, "y": 975, "text": "--updated-before", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "a10-label", "x": 15, "y": 1010, "text": "A10 Review context", "fontSize": 14 },
+    { "type": "rectangle", "id": "a10-mrs", "x": 325, "y": 1005, "width": 50, "height": 28, "backgroundColor": "#ffd8a8", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a10-who", "x": 460, "y": 1005, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "text", "id": "a10-gap", "x": 780, "y": 1010, "text": "MR file list", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "a11-label", "x": 15, "y": 1045, "text": "A11 Knowledge graph", "fontSize": 14 },
+    { "type": "rectangle", "id": "a11-search", "x": 390, "y": 1040, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a11-timeline", "x": 525, "y": 1040, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "text", "id": "a11-gap", "x": 780, "y": 1045, "text": "entity refs query", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "a12-label", "x": 15, "y": 1080, "text": "A12 Release check", "fontSize": 14 },
+    { "type": "rectangle", "id": "a12-issues", "x": 255, "y": 1075, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a12-mrs", "x": 325, "y": 1075, "width": 50, "height": 28, "backgroundColor": "#ffd8a8", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a12-who", "x": 460, "y": 1075, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "text", "id": "a12-gap", "x": 780, "y": 1080, "text": "mrs --milestone", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "a13-label", "x": 15, "y": 1115, "text": "A13 What changed?", "fontSize": 14 },
+    { "type": "rectangle", "id": "a13-issues", "x": 255, "y": 1110, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a13-mrs", "x": 325, "y": 1110, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "text", "id": "a13-gap", "x": 780, "y": 1115, "text": "state-change filter", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "a14-label", "x": 15, "y": 1150, "text": "A14 Meeting prep", "fontSize": 14 },
+    { "type": "rectangle", "id": "a14-issues", "x": 255, "y": 1145, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a14-mrs", "x": 325, "y": 1145, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a14-who", "x": 460, "y": 1145, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a14-count", "x": 655, "y": 1145, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "text", "id": "a14-gap", "x": 780, "y": 1150, "text": "summary cmd", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "a15-label", "x": 15, "y": 1185, "text": "A15 Conflict detect", "fontSize": 14 },
+    { "type": "rectangle", "id": "a15-issues", "x": 255, "y": 1180, "width": 50, "height": 28, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a15-mrs", "x": 325, "y": 1180, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "rectangle", "id": "a15-who", "x": 460, "y": 1180, "width": 50, "height": 28, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "text", "id": "a15-gap", "x": 780, "y": 1185, "text": "entity refs, --state", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "legend-title", "x": 15, "y": 1230, "text": "Legend:", "fontSize": 14 },
+    { "type": "rectangle", "id": "leg-essential", "x": 80, "y": 1228, "width": 20, "height": 20, "backgroundColor": "#22c55e", "fillStyle": "solid" },
+    { "type": "text", "id": "leg-essential-t", "x": 105, "y": 1230, "text": "Essential", "fontSize": 14 },
+    { "type": "rectangle", "id": "leg-supporting", "x": 190, "y": 1228, "width": 20, "height": 20, "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "text", "id": "leg-supporting-t", "x": 215, "y": 1230, "text": "Supporting", "fontSize": 14 },
+    { "type": "rectangle", "id": "leg-partial", "x": 310, "y": 1228, "width": 20, "height": 20, "backgroundColor": "#ffd8a8", "fillStyle": "solid" },
+    { "type": "text", "id": "leg-partial-t", "x": 335, "y": 1230, "text": "Partially blocked", "fontSize": 14 },
+    { "type": "text", "id": "leg-gap-t", "x": 470, "y": 1230, "text": "Red text = gap", "fontSize": 14, "strokeColor": "#ef4444" },
+
+    { "type": "text", "id": "insight-1", "x": 15, "y": 1270, "text": "Key insight: `issues` and `search` are the workhorses (used in 20+ flows).", "fontSize": 14, "strokeColor": "#495057" },
+    { "type": "text", "id": "insight-2", "x": 15, "y": 1295, "text": "`who` is critical for people questions but siloed from file-change data.", "fontSize": 14, "strokeColor": "#495057" },
+    { "type": "text", "id": "insight-3", "x": 15, "y": 1320, "text": "`timeline` is powerful but keyword-only seeding limits entity-specific queries.", "fontSize": 14, "strokeColor": "#495057" },
+    { "type": "text", "id": "insight-4", "x": 15, "y": 1345, "text": "22/30 flows have at least one gap. Most gaps are filter additions, not new commands.", "fontSize": 14, "strokeColor": "#ef4444" }
+  ],
+  "appState": { "viewBackgroundColor": "#ffffff", "gridSize": null },
+  "files": {}
+}

docs/diagrams/04-gap-priority-matrix.excalidraw

@@ -0,0 +1,110 @@
+{
+  "type": "excalidraw",
+  "version": 2,
+  "source": "https://excalidraw.com",
+  "elements": [
+    { "type": "text", "id": "title", "x": 300, "y": 20, "text": "Lore CLI Gap Priority Matrix", "fontSize": 28 },
+    { "type": "text", "id": "subtitle", "x": 310, "y": 58, "text": "20 identified gaps plotted by impact vs effort", "fontSize": 16, "strokeColor": "#868e96" },
+
+    { "type": "rectangle", "id": "q1-zone", "x": 100, "y": 120, "width": 500, "height": 380,
+      "backgroundColor": "#d3f9d8", "fillStyle": "solid", "roundness": { "type": 3 },
+      "strokeColor": "#22c55e", "strokeWidth": 1, "opacity": 25 },
+    { "type": "text", "id": "q1-label", "x": 110, "y": 126, "text": "QUICK WINS", "fontSize": 18, "strokeColor": "#15803d" },
+
+    { "type": "rectangle", "id": "q2-zone", "x": 620, "y": 120, "width": 500, "height": 380,
+      "backgroundColor": "#fff3bf", "fillStyle": "solid", "roundness": { "type": 3 },
+      "strokeColor": "#f59e0b", "strokeWidth": 1, "opacity": 25 },
+    { "type": "text", "id": "q2-label", "x": 630, "y": 126, "text": "STRATEGIC", "fontSize": 18, "strokeColor": "#b45309" },
+
+    { "type": "rectangle", "id": "q3-zone", "x": 100, "y": 520, "width": 500, "height": 300,
+      "backgroundColor": "#dbe4ff", "fillStyle": "solid", "roundness": { "type": 3 },
+      "strokeColor": "#4a9eed", "strokeWidth": 1, "opacity": 25 },
+    { "type": "text", "id": "q3-label", "x": 110, "y": 526, "text": "FILL-IN", "fontSize": 18, "strokeColor": "#1971c2" },
+
+    { "type": "rectangle", "id": "q4-zone", "x": 620, "y": 520, "width": 500, "height": 300,
+      "backgroundColor": "#ffc9c9", "fillStyle": "solid", "roundness": { "type": 3 },
+      "strokeColor": "#ef4444", "strokeWidth": 1, "opacity": 25 },
+    { "type": "text", "id": "q4-label", "x": 630, "y": 526, "text": "DEPRIORITIZE", "fontSize": 18, "strokeColor": "#c92a2a" },
+
+    { "type": "text", "id": "y-axis-hi", "x": 30, "y": 130, "text": "HIGH\nIMPACT", "fontSize": 16, "strokeColor": "#495057", "textAlign": "center" },
+    { "type": "text", "id": "y-axis-lo", "x": 30, "y": 550, "text": "LOW\nIMPACT", "fontSize": 16, "strokeColor": "#495057", "textAlign": "center" },
+    { "type": "text", "id": "x-axis-lo", "x": 280, "y": 840, "text": "LOW EFFORT", "fontSize": 16, "strokeColor": "#495057" },
+    { "type": "text", "id": "x-axis-hi", "x": 800, "y": 840, "text": "HIGH EFFORT", "fontSize": 16, "strokeColor": "#495057" },
+
+    { "type": "arrow", "id": "y-arrow", "x": 85, "y": 810, "width": 0, "height": -680,
+      "points": [[0,0],[0,-680]], "endArrowhead": "arrow", "strokeColor": "#495057", "strokeWidth": 1 },
+    { "type": "arrow", "id": "x-arrow", "x": 85, "y": 810, "width": 1050, "height": 0,
+      "points": [[0,0],[1050,0]], "endArrowhead": "arrow", "strokeColor": "#495057", "strokeWidth": 1 },
+
+    { "type": "rectangle", "id": "g5", "x": 120, "y": 160, "width": 210, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "#5 @me alias", "fontSize": 16 } },
+    { "type": "rectangle", "id": "g8", "x": 120, "y": 225, "width": 210, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "#8 --state on search", "fontSize": 16 } },
+    { "type": "rectangle", "id": "g9", "x": 120, "y": 290, "width": 210, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "#9 mrs --milestone", "fontSize": 16 } },
+    { "type": "rectangle", "id": "g10", "x": 120, "y": 355, "width": 210, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "#10 --no-assignee", "fontSize": 16 } },
+    { "type": "rectangle", "id": "g11", "x": 350, "y": 160, "width": 230, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "#11 --updated-before", "fontSize": 16 } },
+    { "type": "rectangle", "id": "g14", "x": 350, "y": 225, "width": 230, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "#14 detail --fields", "fontSize": 16 } },
+    { "type": "rectangle", "id": "g18", "x": 350, "y": 290, "width": 230, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "#18 1y/12m duration", "fontSize": 16 } },
+    { "type": "rectangle", "id": "g20", "x": 350, "y": 355, "width": 230, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "#20 sort by due date", "fontSize": 16 } },
+
+    { "type": "rectangle", "id": "g1", "x": 640, "y": 160, "width": 220, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffd8a8", "fillStyle": "solid",
+      "label": { "text": "#1 MR file changes", "fontSize": 16 } },
+    { "type": "rectangle", "id": "g2", "x": 640, "y": 225, "width": 220, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffd8a8", "fillStyle": "solid",
+      "label": { "text": "#2 entity refs query", "fontSize": 16 } },
+    { "type": "rectangle", "id": "g3", "x": 640, "y": 290, "width": 220, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffd8a8", "fillStyle": "solid",
+      "label": { "text": "#3 per-note search", "fontSize": 16 } },
+    { "type": "rectangle", "id": "g4", "x": 880, "y": 160, "width": 220, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffd8a8", "fillStyle": "solid",
+      "label": { "text": "#4 entity timeline", "fontSize": 16 } },
+    { "type": "rectangle", "id": "g6", "x": 880, "y": 225, "width": 220, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffd8a8", "fillStyle": "solid",
+      "label": { "text": "#6 activity feed", "fontSize": 16 } },
+    { "type": "rectangle", "id": "g12", "x": 880, "y": 290, "width": 220, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffd8a8", "fillStyle": "solid",
+      "label": { "text": "#12 team workload", "fontSize": 16 } },
+
+    { "type": "rectangle", "id": "g13", "x": 120, "y": 570, "width": 210, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
+      "label": { "text": "#13 pagination/offset", "fontSize": 16 } },
+    { "type": "rectangle", "id": "g15", "x": 120, "y": 635, "width": 210, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
+      "label": { "text": "#15 group by project", "fontSize": 16 } },
+    { "type": "rectangle", "id": "g19", "x": 120, "y": 700, "width": 210, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
+      "label": { "text": "#19 participant filter", "fontSize": 16 } },
+
+    { "type": "rectangle", "id": "g7", "x": 640, "y": 570, "width": 220, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid",
+      "label": { "text": "#7 multi-path who", "fontSize": 16 } },
+    { "type": "rectangle", "id": "g16", "x": 640, "y": 635, "width": 220, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid",
+      "label": { "text": "#16 trend metrics", "fontSize": 16 } },
+    { "type": "rectangle", "id": "g17", "x": 640, "y": 700, "width": 220, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid",
+      "label": { "text": "#17 --for-issue on mrs", "fontSize": 16 } },
+
+    { "type": "text", "id": "q1-count", "x": 180, "y": 430, "text": "8 gaps - lowest hanging fruit", "fontSize": 14, "strokeColor": "#15803d" },
+    { "type": "text", "id": "q2-count", "x": 710, "y": 370, "text": "6 gaps - build deliberately", "fontSize": 14, "strokeColor": "#b45309" },
+    { "type": "text", "id": "q3-count", "x": 160, "y": 770, "text": "3 gaps - fill as needed", "fontSize": 14, "strokeColor": "#1971c2" },
+    { "type": "text", "id": "q4-count", "x": 680, "y": 770, "text": "3 gaps - defer or rethink", "fontSize": 14, "strokeColor": "#c92a2a" }
+  ],
+  "appState": { "viewBackgroundColor": "#ffffff", "gridSize": null },
+  "files": {}
+}

docs/diagrams/05-data-flow-architecture.excalidraw

@@ -0,0 +1,184 @@
+{
+  "type": "excalidraw",
+  "version": 2,
+  "source": "https://excalidraw.com",
+  "elements": [
+    { "type": "text", "id": "title", "x": 350, "y": 15, "text": "Lore Data Flow Architecture", "fontSize": 28 },
+    { "type": "text", "id": "subtitle", "x": 280, "y": 53, "text": "Green = queryable via CLI  |  Red = stored but hidden  |  Gray = internal", "fontSize": 14, "strokeColor": "#868e96" },
+
+    { "type": "rectangle", "id": "zone-gitlab", "x": 30, "y": 90, "width": 200, "height": 300,
+      "backgroundColor": "#e5dbff", "fillStyle": "solid", "roundness": { "type": 3 },
+      "strokeColor": "#8b5cf6", "strokeWidth": 1, "opacity": 30 },
+    { "type": "text", "id": "zone-gitlab-label", "x": 55, "y": 96, "text": "GitLab APIs", "fontSize": 16, "strokeColor": "#7048e8" },
+
+    { "type": "rectangle", "id": "rest-api", "x": 50, "y": 130, "width": 160, "height": 60,
+      "roundness": { "type": 3 }, "backgroundColor": "#d0bfff", "fillStyle": "solid",
+      "label": { "text": "REST API\n(paginated)", "fontSize": 16 } },
+    { "type": "rectangle", "id": "graphql-api", "x": 50, "y": 210, "width": 160, "height": 60,
+      "roundness": { "type": 3 }, "backgroundColor": "#d0bfff", "fillStyle": "solid",
+      "label": { "text": "GraphQL API\n(adaptive pages)", "fontSize": 16 } },
+    { "type": "rectangle", "id": "ollama-api", "x": 50, "y": 310, "width": 160, "height": 60,
+      "roundness": { "type": 3 }, "backgroundColor": "#d0bfff", "fillStyle": "solid",
+      "label": { "text": "Ollama\n(embeddings)", "fontSize": 16 } },
+
+    { "type": "rectangle", "id": "zone-ingest", "x": 270, "y": 90, "width": 180, "height": 300,
+      "backgroundColor": "#dbe4ff", "fillStyle": "solid", "roundness": { "type": 3 },
+      "strokeColor": "#4a9eed", "strokeWidth": 1, "opacity": 30 },
+    { "type": "text", "id": "zone-ingest-label", "x": 300, "y": 96, "text": "Ingestion", "fontSize": 16, "strokeColor": "#1971c2" },
+
+    { "type": "rectangle", "id": "ingest-issues", "x": 285, "y": 130, "width": 150, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
+      "label": { "text": "Issue Sync", "fontSize": 16 } },
+    { "type": "rectangle", "id": "ingest-mrs", "x": 285, "y": 195, "width": 150, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
+      "label": { "text": "MR Sync", "fontSize": 16 } },
+    { "type": "rectangle", "id": "ingest-disc", "x": 285, "y": 260, "width": 150, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
+      "label": { "text": "Discussion Sync", "fontSize": 16 } },
+    { "type": "rectangle", "id": "ingest-events", "x": 285, "y": 325, "width": 150, "height": 50,
+      "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
+      "label": { "text": "Event Sync", "fontSize": 16 } },
+
+    { "type": "arrow", "id": "a-rest-issues", "x": 210, "y": 155, "width": 75, "height": 0,
+      "points": [[0,0],[75,0]], "endArrowhead": "arrow", "strokeColor": "#495057" },
+    { "type": "arrow", "id": "a-rest-mrs", "x": 210, "y": 165, "width": 75, "height": 50,
+      "points": [[0,0],[75,50]], "endArrowhead": "arrow", "strokeColor": "#495057" },
+    { "type": "arrow", "id": "a-graphql-issues", "x": 210, "y": 240, "width": 75, "height": -80,
+      "points": [[0,0],[75,-80]], "endArrowhead": "arrow", "strokeColor": "#495057" },
+
+    { "type": "rectangle", "id": "zone-sqlite", "x": 490, "y": 90, "width": 400, "height": 650,
+      "backgroundColor": "#d3f9d8", "fillStyle": "solid", "roundness": { "type": 3 },
+      "strokeColor": "#22c55e", "strokeWidth": 1, "opacity": 20 },
+    { "type": "text", "id": "zone-sqlite-label", "x": 570, "y": 96, "text": "SQLite (WAL mode)", "fontSize": 16, "strokeColor": "#15803d" },
+
+    { "type": "text", "id": "grp-queryable", "x": 500, "y": 120, "text": "Queryable Tables", "fontSize": 14, "strokeColor": "#15803d" },
+
+    { "type": "rectangle", "id": "t-projects", "x": 500, "y": 145, "width": 170, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "projects", "fontSize": 14 } },
+    { "type": "rectangle", "id": "t-issues", "x": 500, "y": 195, "width": 170, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "issues + assignees", "fontSize": 14 } },
+    { "type": "rectangle", "id": "t-mrs", "x": 500, "y": 245, "width": 170, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "merge_requests", "fontSize": 14 } },
+    { "type": "rectangle", "id": "t-discussions", "x": 500, "y": 295, "width": 170, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "discussions + notes", "fontSize": 14 } },
+    { "type": "rectangle", "id": "t-events", "x": 500, "y": 345, "width": 170, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "resource_*_events", "fontSize": 14 } },
+    { "type": "rectangle", "id": "t-docs", "x": 500, "y": 395, "width": 170, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "documents + FTS5", "fontSize": 14 } },
+    { "type": "rectangle", "id": "t-embed", "x": 500, "y": 445, "width": 170, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
+      "label": { "text": "embeddings (vec)", "fontSize": 14 } },
+
+    { "type": "text", "id": "grp-hidden", "x": 700, "y": 120, "text": "Hidden Tables", "fontSize": 14, "strokeColor": "#c92a2a" },
+
+    { "type": "rectangle", "id": "t-file-changes", "x": 695, "y": 145, "width": 180, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444",
+      "label": { "text": "mr_file_changes", "fontSize": 14 } },
+    { "type": "rectangle", "id": "t-entity-refs", "x": 695, "y": 195, "width": 180, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444",
+      "label": { "text": "entity_references", "fontSize": 14 } },
+    { "type": "rectangle", "id": "t-raw", "x": 695, "y": 245, "width": 180, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444",
+      "label": { "text": "raw_payloads", "fontSize": 14 } },
+
+    { "type": "text", "id": "grp-internal", "x": 700, "y": 310, "text": "Internal Only", "fontSize": 14, "strokeColor": "#868e96" },
+
+    { "type": "rectangle", "id": "t-sync", "x": 695, "y": 340, "width": 180, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#dee2e6", "fillStyle": "solid", "strokeColor": "#868e96",
+      "label": { "text": "sync_runs + cursors", "fontSize": 14 } },
+    { "type": "rectangle", "id": "t-dirty", "x": 695, "y": 390, "width": 180, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#dee2e6", "fillStyle": "solid", "strokeColor": "#868e96",
+      "label": { "text": "dirty_sources", "fontSize": 14 } },
+    { "type": "rectangle", "id": "t-locks", "x": 695, "y": 440, "width": 180, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#dee2e6", "fillStyle": "solid", "strokeColor": "#868e96",
+      "label": { "text": "app_locks", "fontSize": 14 } },
+
+    { "type": "arrow", "id": "a-ingest-tables", "x": 435, "y": 200, "width": 55, "height": 0,
+      "points": [[0,0],[55,0]], "endArrowhead": "arrow", "strokeColor": "#495057" },
+
+    { "type": "rectangle", "id": "zone-cli", "x": 930, "y": 90, "width": 250, "height": 650,
+      "backgroundColor": "#fff3bf", "fillStyle": "solid", "roundness": { "type": 3 },
+      "strokeColor": "#f59e0b", "strokeWidth": 1, "opacity": 25 },
+    { "type": "text", "id": "zone-cli-label", "x": 990, "y": 96, "text": "CLI Commands", "fontSize": 16, "strokeColor": "#b45309" },
+
+    { "type": "rectangle", "id": "cmd-issues", "x": 950, "y": 130, "width": 210, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#fff3bf", "fillStyle": "solid",
+      "label": { "text": "lore issues", "fontSize": 16 } },
+    { "type": "rectangle", "id": "cmd-mrs", "x": 950, "y": 185, "width": 210, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#fff3bf", "fillStyle": "solid",
+      "label": { "text": "lore mrs", "fontSize": 16 } },
+    { "type": "rectangle", "id": "cmd-search", "x": 950, "y": 240, "width": 210, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#fff3bf", "fillStyle": "solid",
+      "label": { "text": "lore search", "fontSize": 16 } },
+    { "type": "rectangle", "id": "cmd-who", "x": 950, "y": 295, "width": 210, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#fff3bf", "fillStyle": "solid",
+      "label": { "text": "lore who", "fontSize": 16 } },
+    { "type": "rectangle", "id": "cmd-timeline", "x": 950, "y": 350, "width": 210, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#fff3bf", "fillStyle": "solid",
+      "label": { "text": "lore timeline", "fontSize": 16 } },
+    { "type": "rectangle", "id": "cmd-count", "x": 950, "y": 405, "width": 210, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#fff3bf", "fillStyle": "solid",
+      "label": { "text": "lore count", "fontSize": 16 } },
+    { "type": "rectangle", "id": "cmd-sync", "x": 950, "y": 460, "width": 210, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#fff3bf", "fillStyle": "solid",
+      "label": { "text": "lore sync", "fontSize": 16 } },
+    { "type": "rectangle", "id": "cmd-status", "x": 950, "y": 515, "width": 210, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#fff3bf", "fillStyle": "solid",
+      "label": { "text": "lore status", "fontSize": 16 } },
+
+    { "type": "arrow", "id": "a-issues-cmd", "x": 670, "y": 215, "width": 270, "height": -65,
+      "points": [[0,0],[270,-65]], "endArrowhead": "arrow", "strokeColor": "#22c55e", "strokeWidth": 2 },
+    { "type": "arrow", "id": "a-mrs-cmd", "x": 670, "y": 265, "width": 270, "height": -60,
+      "points": [[0,0],[270,-60]], "endArrowhead": "arrow", "strokeColor": "#22c55e", "strokeWidth": 2 },
+    { "type": "arrow", "id": "a-docs-cmd", "x": 670, "y": 415, "width": 270, "height": -155,
+      "points": [[0,0],[270,-155]], "endArrowhead": "arrow", "strokeColor": "#22c55e", "strokeWidth": 2 },
+    { "type": "arrow", "id": "a-embed-cmd", "x": 670, "y": 465, "width": 270, "height": -200,
+      "points": [[0,0],[270,-200]], "endArrowhead": "arrow", "strokeColor": "#22c55e", "strokeWidth": 2 },
+    { "type": "arrow", "id": "a-events-cmd", "x": 670, "y": 365, "width": 270, "height": 5,
+      "points": [[0,0],[270,5]], "endArrowhead": "arrow", "strokeColor": "#22c55e", "strokeWidth": 2 },
+
+    { "type": "text", "id": "hidden-note-1", "x": 695, "y": 498, "text": "mr_file_changes: populated by\nMR sync but NOT queryable.\nBlocks H4, A6, A10 flows.", "fontSize": 14, "strokeColor": "#ef4444" },
+    { "type": "text", "id": "hidden-note-2", "x": 695, "y": 568, "text": "entity_references: used by\ntimeline internally but NOT\nqueryable. Blocks A5, A11.", "fontSize": 14, "strokeColor": "#ef4444" },
+
+    { "type": "arrow", "id": "a-hidden-who", "x": 875, "y": 165, "width": 65, "height": 148,
+      "points": [[0,0],[65,148]], "endArrowhead": "arrow", "strokeColor": "#ef4444", "strokeWidth": 2,
+      "strokeStyle": "dashed" },
+    { "type": "text", "id": "hidden-who-label", "x": 880, "y": 240, "text": "who uses\nDiffNotes,\nnot file\nchanges", "fontSize": 12, "strokeColor": "#ef4444" },
+
+    { "type": "arrow", "id": "a-hidden-timeline", "x": 875, "y": 215, "width": 65, "height": 155,
+      "points": [[0,0],[65,155]], "endArrowhead": "arrow", "strokeColor": "#ef4444", "strokeWidth": 2,
+      "strokeStyle": "dashed" },
+
+    { "type": "rectangle", "id": "cmd-missing-refs", "x": 950, "y": 580, "width": 210, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444", "strokeStyle": "dashed",
+      "label": { "text": "lore refs (missing)", "fontSize": 16 } },
+    { "type": "rectangle", "id": "cmd-missing-files", "x": 950, "y": 635, "width": 210, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444", "strokeStyle": "dashed",
+      "label": { "text": "lore files (missing)", "fontSize": 16 } },
+    { "type": "rectangle", "id": "cmd-missing-activity", "x": 950, "y": 690, "width": 210, "height": 40,
+      "roundness": { "type": 3 }, "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444", "strokeStyle": "dashed",
+      "label": { "text": "lore activity (missing)", "fontSize": 16 } },
+
+    { "type": "text", "id": "legend-title", "x": 30, "y": 430, "text": "Legend", "fontSize": 16 },
+    { "type": "rectangle", "id": "leg-green", "x": 30, "y": 460, "width": 20, "height": 20,
+      "backgroundColor": "#b2f2bb", "fillStyle": "solid" },
+    { "type": "text", "id": "leg-green-t", "x": 60, "y": 462, "text": "Queryable via CLI", "fontSize": 14 },
+    { "type": "rectangle", "id": "leg-red", "x": 30, "y": 490, "width": 20, "height": 20,
+      "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444" },
+    { "type": "text", "id": "leg-red-t", "x": 60, "y": 492, "text": "Stored but hidden", "fontSize": 14 },
+    { "type": "rectangle", "id": "leg-gray", "x": 30, "y": 520, "width": 20, "height": 20,
+      "backgroundColor": "#dee2e6", "fillStyle": "solid", "strokeColor": "#868e96" },
+    { "type": "text", "id": "leg-gray-t", "x": 60, "y": 522, "text": "Internal bookkeeping", "fontSize": 14 },
+    { "type": "rectangle", "id": "leg-dashed", "x": 30, "y": 550, "width": 20, "height": 20,
+      "backgroundColor": "#ffc9c9", "fillStyle": "solid", "strokeColor": "#ef4444", "strokeStyle": "dashed" },
+    { "type": "text", "id": "leg-dashed-t", "x": 60, "y": 552, "text": "Missing command", "fontSize": 14 }
+  ],
+  "appState": { "viewBackgroundColor": "#ffffff", "gridSize": null },
+  "files": {}
+}

docs/ideas/README.md

@@ -0,0 +1,66 @@
+# Gitlore Feature Ideas
+
+Central registry of potential features. Each idea leverages data already ingested
+into the local SQLite database (issues, MRs, discussions, notes, resource events,
+entity references, embeddings, file changes).
+
+## Priority Tiers
+
+**Tier 1 — High confidence, low effort, immediate value:**
+
+| # | Idea | File | Confidence |
+|---|------|------|------------|
+| 9 | Similar Issues Finder | [similar-issues.md](similar-issues.md) | 95% |
+| 17 | "What Changed?" Digest | [digest.md](digest.md) | 93% |
+| 5 | Who Knows About X? | [experts.md](experts.md) | 92% |
+| -- | Multi-Project Ergonomics | [project-ergonomics.md](project-ergonomics.md) | 90% |
+| 27 | Weekly Digest Generator | [weekly-digest.md](weekly-digest.md) | 90% |
+| 4 | Stale Discussion Finder | [stale-discussions.md](stale-discussions.md) | 90% |
+
+**Tier 2 — Strong ideas, moderate effort:**
+
+| # | Idea | File | Confidence |
+|---|------|------|------------|
+| 19 | MR-to-Issue Closure Gap | [closure-gaps.md](closure-gaps.md) | 88% |
+| 1 | Contributor Heatmap | [contributors.md](contributors.md) | 88% |
+| 21 | Knowledge Silo Detection | [silos.md](silos.md) | 87% |
+| 2 | Review Bottleneck Detector | [bottlenecks.md](bottlenecks.md) | 85% |
+| 14 | File Hotspot Report | [hotspots.md](hotspots.md) | 85% |
+| 26 | Unlinked MR Finder | [unlinked.md](unlinked.md) | 83% |
+| 6 | Decision Archaeology | [decisions.md](decisions.md) | 82% |
+| 18 | Label Hygiene Audit | [label-audit.md](label-audit.md) | 82% |
+
+**Tier 3 — Promising, needs more design work:**
+
+| # | Idea | File | Confidence |
+|---|------|------|------------|
+| 29 | Entity Relationship Explorer | [graph.md](graph.md) | 80% |
+| 12 | Milestone Risk Report | [milestone-risk.md](milestone-risk.md) | 78% |
+| 3 | Label Velocity | [label-flow.md](label-flow.md) | 78% |
+| 24 | Recurring Bug Patterns | [recurring-patterns.md](recurring-patterns.md) | 76% |
+| 7 | Cross-Project Impact Graph | [impact-graph.md](impact-graph.md) | 75% |
+| 16 | Idle Work Detector | [idle.md](idle.md) | 73% |
+| 8 | MR Churn Analysis | [churn.md](churn.md) | 72% |
+| 15 | Author Collaboration Network | [collaboration.md](collaboration.md) | 70% |
+| 28 | DiffNote Coverage Map | [review-coverage.md](review-coverage.md) | 75% |
+| 25 | MR Pipeline Efficiency | [mr-pipeline.md](mr-pipeline.md) | 78% |
+
+## Rejected Ideas (with reasons)
+
+| # | Idea | Reason |
+|---|------|--------|
+| 10 | Sprint Burndown from Labels | Too opinionated about label semantics |
+| 11 | Code Review Quality Score | Subjective "quality" scoring creates perverse incentives |
+| 13 | Discussion Sentiment Drift | Unreliable heuristic sentiment on technical text |
+| 20 | Response Time Leaderboard | Toxic "leaderboard" framing; metric folded into #2 |
+| 22 | Timeline Diff | Niche use case; timeline already interleaves events |
+| 23 | Discussion Thread Summarizer | Requires LLM inference; out of scope for local-first tool |
+| 30 | NL Query Interface | Over-engineered; existing filters cover this |
+
+## How to use this list
+
+1. Pick an idea from Tier 1 or Tier 2
+2. Read its detail file for implementation plan and SQL sketches
+3. Create a bead (`br create`) referencing the idea file
+4. Implement following TDD (test first, then minimal impl)
+5. Update the idea file with `status: implemented` when done

docs/ideas/SYSTEM-PROPOSAL.md

@@ -0,0 +1,555 @@
+# Project Manager System — Design Proposal
+
+## The Problem
+
+We have a growing backlog of ideas and issues in markdown files. Agents can ship
+features in under an hour. The constraint isn't execution speed — it's knowing
+WHAT to execute NEXT, in what ORDER, and detecting when the plan needs to change.
+
+We need a system that:
+1. Automatically scores and sequences work items
+2. Detects when scope changes during spec generation
+3. Tracks the full lifecycle: idea → spec → beads → shipped
+4. Re-triages instantly when the dependency graph changes
+5. Runs in seconds, not minutes
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    docs/ideas/*.md                           │
+│                    docs/issues/*.md                          │
+│                    (YAML frontmatter)                        │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   IDEA TRIAGE SKILL                          │
+│                                                              │
+│  Phase 1: INGEST    — parse all frontmatter                  │
+│  Phase 2: VALIDATE  — check refs, detect staleness           │
+│  Phase 3: EVALUATE  — detect scope changes since last run    │
+│  Phase 4: SCORE     — compute priority with unlock graph     │
+│  Phase 5: SEQUENCE  — topological sort by dependency + score │
+│  Phase 6: RECOMMEND — top 3 + unlock advisories + warnings   │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    HUMAN DECIDES                             │
+│            (picks from top 3, takes seconds)                 │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│               SPEC GENERATION (Claude/GPT)                   │
+│  Takes the idea doc, generates detailed implementation spec  │
+│  ALSO: re-evaluates frontmatter fields based on deeper       │
+│  understanding. Updates effort, blocked-by, components.      │
+│  This is the SCOPE CHANGE DETECTION point.                   │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│               PLAN-TO-BEADS (existing skill)                 │
+│  Spec → granular beads with dependencies via br CLI          │
+│  Links bead IDs back into the idea frontmatter               │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│               AGENT IMPLEMENTATION                           │
+│  Works beads via br/bv workflow                              │
+│  bv --robot-triage handles execution-phase prioritization    │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│               COMPLETION & RE-TRIAGE                         │
+│  Beads close → idea status updates to implemented            │
+│  Skill re-runs → newly unblocked ideas surface               │
+│  Loop back to top                                            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## The Two Systems and Their Boundary
+
+| Concern | Ideas System (new) | Beads System (existing) |
+|---------|-------------------|------------------------|
+| Phase | Pre-commitment (what to build) | Execution (how to build) |
+| Data | docs/ideas/*.md, docs/issues/*.md | .beads/issues.jsonl |
+| Triage | Idea triage skill | bv --robot-triage |
+| Tracking | YAML frontmatter | JSONL records |
+| Granularity | Feature-level | Task-level |
+| Lifecycle | proposed → specced → promoted | open → in_progress → closed |
+
+**The handoff point is promotion.** An idea becomes one or more beads. After that,
+the ideas system only tracks the idea's status (promoted/implemented). Beads owns
+execution.
+
+An idea file is NEVER deleted. It's a permanent design record. Even after
+implementation, it documents WHY the feature was built and what tradeoffs were made.
+
+---
+
+## Data Model
+
+### Frontmatter Schema
+
+```yaml
+---
+# ── Identity ──
+id: idea-009                    # stable unique identifier
+title: Similar Issues Finder
+type: idea                      # idea | issue
+status: proposed                # see lifecycle below
+
+# ── Timestamps ──
+created: 2026-02-09
+updated: 2026-02-09
+eval-hash: null                 # SHA of scoring fields at last triage run
+
+# ── Scoring Inputs ──
+impact: high                    # high | medium | low
+effort: small                   # small | medium | large | xlarge
+severity: null                  # critical | high | medium | low (issues only)
+autonomy: full                  # full | needs-design | needs-human
+
+# ── Dependency Graph ──
+blocked-by: []                  # IDs of ideas/issues that must complete first
+unlocks:                        # IDs that become possible/better after this ships
+  - idea-recurring-patterns
+requires: []                    # external prerequisites (gate names)
+related:                        # soft links, not blocking
+  - issue-001
+
+# ── Implementation Context ──
+components:                     # source code paths this will touch
+  - src/search/
+  - src/embedding/
+command: lore similar           # proposed CLI command (null for issues)
+has-spec: false                 # detailed spec has been generated
+spec-path: null                 # path to spec doc if it exists
+beads: []                       # bead IDs after promotion
+
+# ── Classification ──
+tags:
+  - embeddings
+  - search
+---
+```
+
+### Status Lifecycle
+
+```
+IDEA lifecycle:
+  proposed ──→ accepted ──→ specced ──→ promoted ──→ implemented
+      │                        │
+      └──→ rejected            └──→ (scope changed, back to accepted)
+
+ISSUE lifecycle:
+  open ──→ accepted ──→ specced ──→ promoted ──→ resolved
+      │
+      └──→ wontfix
+```
+
+Transitions:
+- `proposed → accepted`: Human confirms this is worth building
+- `accepted → specced`: Detailed implementation spec has been generated
+- `specced → promoted`: Beads created from the spec
+- `promoted → implemented`: All beads closed
+- Any → `rejected`/`wontfix`: Decided not to build (with reason in body)
+- `specced → accepted`: Scope changed during spec, needs re-evaluation
+
+### Effort Calibration (Agent-Executed)
+
+| Level | Wall Clock | Autonomy | Example |
+|-------|-----------|----------|---------|
+| small | ~30 min | Agent ships end-to-end | stale-discussions, closure-gaps |
+| medium | ~1 hour | Agent ships end-to-end | similar-issues, digest |
+| large | 1-2 hours | May need one design decision | recurring-patterns, experts |
+| xlarge | 2+ hours | Needs human architecture input | project groups |
+
+### Gates Registry (docs/gates.yaml)
+
+```yaml
+gates:
+  gate-1:
+    title: Resource Events Ingestion
+    status: complete
+    completed: 2025-12-15
+
+  gate-2:
+    title: Cross-References & Entity Graph
+    status: complete
+    completed: 2026-01-10
+
+  gate-3:
+    title: Timeline Pipeline
+    status: complete
+    completed: 2026-01-25
+
+  gate-4:
+    title: MR File Changes Ingestion
+    status: partial
+    notes: Schema ready (migration 016), ingestion code exists but untested
+    tracks: mr_file_changes table population
+
+  gate-5:
+    title: Code Trace (file:line → commit → MR → issue)
+    status: not-started
+    blocked-by: gate-4
+    notes: Requires git log parsing + commit SHA matching
+```
+
+The skill reads this file to determine which `requires` entries are satisfied.
+
+---
+
+## Scoring Algorithm
+
+### Priority Score
+
+```
+For ideas:
+  base       = impact_weight                    # high=3, medium=2, low=1
+  unlock     = 1 + (0.5 × count_of_unlocks)    # items this directly enables
+  readiness  = 0 if blocked, 1 if ready
+  priority   = base × unlock × readiness
+
+For issues:
+  base       = severity_weight × 1.5           # critical=6, high=4.5, medium=3, low=1.5
+  unlock     = 1 + (0.5 × count_of_unlocks)    # (bugs rarely unlock, but can)
+  readiness  = 0 if blocked, 1 if ready
+  priority   = base × unlock × readiness
+
+Tiebreak (among equal priority):
+  1. Prefer smaller effort (ships faster, starts next cycle sooner)
+  2. Prefer autonomy:full over needs-design over needs-human
+  3. Prefer older items (FIFO within same score)
+```
+
+### Why This Works
+
+- High-impact items that unlock other items float to the top
+- Blocked items score 0 regardless of impact (can't be worked)
+- Effort is a tiebreaker, not a primary factor (since execution is fast)
+- Issues with severity get a 1.5× multiplier (bugs degrade existing value)
+- Unlock multiplier captures the "do Gate 4 first" insight automatically
+
+### Example Rankings
+
+| Item | Impact | Unlocks | Readiness | Score |
+|------|--------|---------|-----------|-------|
+| project-ergonomics | high(3) | 10 | ready(1) | 3 × 6.0 = 18.0 |
+| gate-4-completion | med(2) | 5 | ready(1) | 2 × 3.5 = 7.0 |
+| similar-issues | high(3) | 1 | ready(1) | 3 × 1.5 = 4.5 |
+| stale-discussions | high(3) | 0 | ready(1) | 3 × 1.0 = 3.0 |
+| hotspots | high(3) | 1 | blocked(0) | 0.0 |
+
+Project-ergonomics dominates because it unlocks 10 downstream items. This is the
+correct recommendation — it's the highest-leverage work even though "stale-discussions"
+is simpler.
+
+---
+
+## Scope Change Detection
+
+This is the hardest problem. An idea's scope can change in three ways:
+
+### 1. During Spec Generation (Primary Detection Point)
+
+When Claude/GPT generates a detailed implementation spec from an idea doc, it
+understands the idea more deeply than the original sketch. The spec process should
+be instructed to:
+
+- Re-evaluate effort (now that implementation is understood in detail)
+- Discover new dependencies (need to change schema first, need a new config option)
+- Identify component changes (touches more modules than originally thought)
+- Assess impact more accurately (this is actually higher/lower value than estimated)
+
+**Mechanism:** The spec generation prompt includes an explicit "re-evaluate frontmatter"
+step. The spec output includes an updated frontmatter block. If scoring-relevant
+fields changed, the skill flags it:
+
+```
+SCOPE CHANGE DETECTED:
+  idea-009 (Similar Issues Finder)
+  - effort: small → medium (needs embedding aggregation strategy)
+  - blocked-by: [] → [gate-embeddings-populated]
+  - components: +src/cli/commands/similar.rs (new file)
+  Previous score: 4.5 → New score: 3.0
+  Recommendation: Still top-3, but sequencing may change.
+```
+
+### 2. During Implementation (Discovered Complexity)
+
+An agent working on beads may discover the spec was wrong:
+- "This requires a database migration I didn't anticipate"
+- "This module doesn't expose the API I need"
+
+**Mechanism:** When a bead is blocked or takes significantly longer than estimated,
+the agent should update the idea's frontmatter. The skill detects the change on
+next triage run via eval-hash comparison.
+
+### 3. External Changes (Gate Completion, New Ideas)
+
+When a gate completes or a new idea is added that changes the dependency graph:
+- Gate 4 completes → 5 ideas become unblocked
+- New idea added that's higher priority than current top-3
+- Two ideas discovered to be duplicates
+
+**Mechanism:** The skill detects these automatically by re-computing the full graph
+on every run. The eval-hash tracks what the scoring fields looked like last time;
+if they haven't changed but the SCORE changed (because a dependency was resolved),
+the skill flags it as "newly unblocked."
+
+### The eval-hash Field
+
+```yaml
+eval-hash: "a1b2c3d4"  # SHA-256 of: impact + effort + blocked-by + unlocks + requires
+```
+
+Computed by hashing the concatenation of all scoring-relevant fields. When the skill
+runs, it compares:
+- If eval-hash matches AND score is same → no change, skip
+- If eval-hash matches BUT score changed → external change (dependency resolved)
+- If eval-hash differs → item was modified, re-evaluate
+
+This avoids re-announcing unchanged items on every run.
+
+---
+
+## Skill Design
+
+### Location
+
+`.claude/skills/idea-triage/SKILL.md` (project-local)
+
+### Trigger Phrases
+
+- "triage ideas" / "what should I build next?"
+- "idea triage" / "prioritize ideas"
+- "what's the highest value work?"
+- `/idea-triage`
+
+### Workflow Phases
+
+**Phase 1: INGEST**
+- Glob docs/ideas/*.md and docs/issues/*.md
+- Parse YAML frontmatter from each file
+- Read docs/gates.yaml for capability status
+- Collect: id, title, type, status, impact, effort, severity, autonomy,
+  blocked-by, unlocks, requires, has-spec, beads, eval-hash
+
+**Phase 2: VALIDATE**
+- Required fields present (id, title, type, status, impact, effort)
+- All blocked-by IDs reference existing files
+- All unlocks IDs reference existing files
+- All requires entries exist in gates.yaml
+- No dependency cycles (blocked-by graph is a DAG)
+- Status transitions are valid (no "proposed" with beads linked)
+- Output: list of validation errors/warnings
+
+**Phase 3: EVALUATE (Scope Change Detection)**
+- For each item, compute current eval-hash from scoring fields
+- Compare against stored eval-hash in frontmatter
+- If different: flag as SCOPE_CHANGED with field-level diff
+- If same but score changed (due to external dep resolution): flag as NEWLY_UNBLOCKED
+- If status is specced but has-spec is false: flag as INCONSISTENT
+
+**Phase 4: SCORE**
+- Resolve requires against gates.yaml (is the gate complete?)
+- Resolve blocked-by against other items (is the blocker done?)
+- Compute readiness: 0 if any hard blocker is unresolved, 1 otherwise
+- Compute unlock count: count items whose blocked-by includes this ID
+- Apply scoring formula:
+  - Ideas: impact_weight × (1 + 0.5 × unlock_count) × readiness
+  - Issues: severity_weight × 1.5 × (1 + 0.5 × unlock_count) × readiness
+- Apply tiebreak: effort_weight, autonomy, created date
+
+**Phase 5: SEQUENCE**
+- Separate into: actionable (score > 0) vs blocked (score = 0)
+- Among actionable: sort by score descending with tiebreak
+- Among blocked: sort by "what-if score" (score if blockers were resolved)
+- Compute unlock advisories: "completing X unblocks Y items worth Z total score"
+
+**Phase 6: RECOMMEND**
+Output structured report:
+
+```
+== IDEA TRIAGE ==
+Run: 2026-02-09T14:30:00Z
+Items: 22 (18 proposed, 2 accepted, 1 specced, 1 implemented)
+
+RECOMMENDED SEQUENCE:
+1. [idea-project-ergonomics]  Multi-Project Ergonomics
+   impact:high  effort:medium  autonomy:full  score:18.0
+   WHY FIRST: Unlocks 10 downstream ideas. Highest leverage.
+   COMPONENTS: src/core/config.rs, src/core/project.rs, src/cli/
+
+2. [idea-009]  Similar Issues Finder
+   impact:high  effort:small  autonomy:full  score:4.5
+   WHY NEXT: Highest standalone impact. Ships in ~30 min.
+   UNLOCKS: idea-recurring-patterns
+
+3. [idea-004]  Stale Discussion Finder
+   impact:high  effort:small  autonomy:full  score:3.0
+   WHY NEXT: Quick win, no dependencies, immediate user value.
+
+BLOCKED (would rank high if unblocked):
+  idea-014  File Hotspots        score-if-unblocked:4.5  BLOCKED BY: gate-4
+  idea-021  Knowledge Silos      score-if-unblocked:3.0  BLOCKED BY: gate-4
+  UNLOCK ADVISORY: Completing gate-4 unblocks 5 items (combined: 15.0)
+
+SCOPE CHANGES DETECTED:
+  idea-009: effort changed small→medium (eval-hash mismatch)
+  idea-017: now has spec (has-spec flipped to true)
+
+NEWLY UNBLOCKED:
+  (none this run)
+
+WARNINGS:
+  idea-016: status=proposed, unchanged for 30+ days
+  idea-008: blocked-by references "idea-gate4" which doesn't exist (typo?)
+
+HEALTH:
+  Proposed: 18 | Accepted: 2 | Specced: 1 | Promoted: 0 | Implemented: 1
+  Blocked: 6 | Actionable: 16
+  Backlog runway at ~5/day: ~3 days
+```
+
+### What the Skill Does NOT Do
+
+- **Never modifies files.** Read-only triage. The agent or human updates frontmatter.
+  Exception: the skill CAN update eval-hash after a triage run (opt-in).
+- **Never creates beads.** That's plan-to-beads skill territory.
+- **Never replaces bv.** Once work is in beads, bv --robot-triage handles execution
+  prioritization. This skill owns pre-commitment only.
+- **Never generates specs.** That's a separate step with Claude/GPT.
+
+---
+
+## Integration Points
+
+### With Spec Generation
+
+The spec generation prompt (separate from this skill) should include:
+
+```
+After generating the implementation spec, re-evaluate the idea's frontmatter:
+1. Is the effort estimate still accurate? (small/medium/large/xlarge)
+2. Did you discover new dependencies? (add to blocked-by)
+3. Are there components not listed? (add to components)
+4. Has the impact assessment changed?
+5. Can an agent ship this autonomously? (autonomy: full/needs-design/needs-human)
+
+Output an UPDATED frontmatter block at the end of the spec.
+If any scoring field changed, explain what changed and why.
+```
+
+### With plan-to-beads
+
+When promoting an idea to beads:
+1. Run plan-to-beads on the spec
+2. Capture the created bead IDs
+3. Update the idea's frontmatter: status → promoted, beads → [bd-xxx, bd-yyy]
+4. Run br sync --flush-only && git add .beads/
+
+### With bv --robot-triage
+
+These systems don't talk to each other directly. The boundary is:
+- Idea triage skill → "build idea-009 next"
+- Human/agent generates spec → plan-to-beads → beads created
+- bv --robot-triage → "work on bd-xxx next"
+- Beads close → human/agent updates idea frontmatter → idea triage re-runs
+
+### With New Item Ingestion
+
+When someone adds a new file to docs/ideas/ or docs/issues/:
+- If it has valid frontmatter: picked up automatically on next triage run
+- If it has no/invalid frontmatter: flagged in WARNINGS section
+- Skill can suggest default frontmatter based on content analysis
+
+---
+
+## Failure Modes and Mitigations
+
+### 1. Frontmatter Rot
+**Risk:** Fields don't get updated. Status says "proposed" but it's actually shipped.
+**Mitigation:** Cross-reference with beads. If an idea has beads and all beads are
+closed, flag that the idea should be "implemented" even if frontmatter says otherwise.
+The skill detects this inconsistency.
+
+### 2. Score Gaming
+**Risk:** Someone inflates impact or unlocks count to make their idea rank higher.
+**Mitigation:** Unlocks are verified — the skill checks that the referenced items
+actually have this idea in their blocked-by. Impact is subjective but reviewed during
+spec generation (second opinion from a different model/session).
+
+### 3. Stale Gates Registry
+**Risk:** gate-4 is actually complete but gates.yaml wasn't updated.
+**Mitigation:** Skill warns when a gate has been "partial" for a long time. Could
+also probe the codebase (check if mr_file_changes ingestion code exists and has tests).
+
+### 4. Circular Dependencies
+**Risk:** A blocks B blocks A.
+**Mitigation:** Phase 2 validation explicitly checks for cycles in the blocked-by
+graph and reports them as errors.
+
+### 5. Unlock Count Inflation
+**Risk:** An item claims to unlock 20 things, making it score astronomically.
+**Mitigation:** Unlock count is VERIFIED by checking reverse blocked-by references.
+If idea-X says it unlocks idea-Y, but idea-Y's blocked-by doesn't include idea-X,
+the claim is discounted. Both explicit unlocks and reverse blocked-by contribute to
+the count, but unverified claims are flagged.
+
+### 6. Scope Creep During Spec
+**Risk:** Spec generation reveals the idea is actually 5× harder than estimated.
+The score drops, but the human has already mentally committed.
+**Mitigation:** The scope change detection makes this VISIBLE. The triage output
+explicitly shows "effort changed small→xlarge, score dropped from 4.5 to 0.75."
+Human can then decide: proceed anyway, or switch to a different top-3 pick.
+
+### 7. Orphaned Ideas
+**Risk:** Ideas get promoted to beads, beads get implemented, but the idea file
+never gets updated. It sits in "promoted" forever.
+**Mitigation:** Skill checks: for each idea with status=promoted, look up the
+linked beads. If all beads are closed, flag: "idea-009 appears complete, update
+status to implemented."
+
+---
+
+## Implementation Plan
+
+### Step 1: Create the Frontmatter Schema (this doc → applied to all files)
+- Define the exact YAML schema (above)
+- Create docs/gates.yaml
+- Apply frontmatter to all 22 existing files in docs/ideas/ and docs/issues/
+
+### Step 2: Build the Skill
+- Create .claude/skills/idea-triage/SKILL.md
+- Implement all 6 phases in the skill prompt
+- The skill uses Glob, Read, and text processing — no external scripts needed
+  (25 files is small enough for Claude to process directly)
+
+### Step 3: Test the System
+- Run the skill against current files
+- Verify scoring matches manual expectations
+- Check that project-ergonomics ranks #1 (it should, due to unlock count)
+- Verify blocked items score 0
+- Check validation catches intentional errors
+
+### Step 4: Run One Full Cycle
+- Pick the top recommendation
+- Generate a spec (separate session)
+- Verify scope change detection works (spec should update frontmatter)
+- Promote to beads via plan-to-beads
+- Implement
+- Verify completion detection works
+
+### Step 5: Iterate
+- Run triage again after implementation
+- Verify newly unblocked items surface
+- Adjust scoring weights if rankings feel wrong
+- Add new ideas as they emerge

docs/ideas/bottlenecks.md

@@ -0,0 +1,88 @@
+# Review Bottleneck Detector
+
+- **Command:** `lore bottlenecks [--since <date>]`
+- **Confidence:** 85%
+- **Tier:** 2
+- **Status:** proposed
+- **Effort:** medium — join MRs with first review note, compute percentiles
+
+## What
+
+For MRs in a given time window, compute:
+1. **Time to first review** — created_at to first non-author DiffNote
+2. **Review cycles** — count of discussion resolution rounds
+3. **Time to merge** — created_at to merged_at
+
+Flag MRs above P90 thresholds as bottlenecks.
+
+## Why
+
+Review bottlenecks are the #1 developer productivity killer. Making them visible
+and measurable is the first step to fixing them. This provides data for process
+retrospectives.
+
+## Data Required
+
+All exists today:
+- `merge_requests` (created_at, merged_at, author_username)
+- `notes` (note_type='DiffNote', author_username, created_at)
+- `discussions` (resolved, resolvable)
+
+## Implementation Sketch
+
+```sql
+-- Time to first review per MR
+SELECT
+    mr.id,
+    mr.iid,
+    mr.title,
+    mr.author_username,
+    mr.created_at,
+    mr.merged_at,
+    p.path_with_namespace,
+    MIN(n.created_at) as first_review_at,
+    (MIN(n.created_at) - mr.created_at) / 3600000.0 as hours_to_first_review,
+    (mr.merged_at - mr.created_at) / 3600000.0 as hours_to_merge
+FROM merge_requests mr
+JOIN projects p ON mr.project_id = p.id
+LEFT JOIN discussions d ON d.merge_request_id = mr.id
+LEFT JOIN notes n ON n.discussion_id = d.id
+    AND n.note_type = 'DiffNote'
+    AND n.is_system = 0
+    AND n.author_username != mr.author_username
+WHERE mr.created_at >= ?1
+  AND mr.state IN ('merged', 'opened')
+GROUP BY mr.id
+ORDER BY hours_to_first_review DESC NULLS FIRST;
+```
+
+## Human Output
+
+```
+Review Bottlenecks (last 30 days)
+
+  P50 time to first review: 4.2h
+  P90 time to first review: 28.1h
+  P50 time to merge: 2.1d
+  P90 time to merge: 8.3d
+
+  Slowest to review:
+    !234  Refactor auth       72h to first review  (alice, still open)
+    !228  Database migration   48h to first review  (bob, merged in 5d)
+
+  Most review cycles:
+    !234  Refactor auth       8 discussion threads, 4 resolved
+    !225  API versioning      6 discussion threads, 6 resolved
+```
+
+## Downsides
+
+- Doesn't capture review done outside GitLab (Slack, in-person)
+- DiffNote timestamp != when reviewer started reading
+- Large MRs naturally take longer; no size normalization
+
+## Extensions
+
+- `lore bottlenecks --reviewer alice` — how fast does alice review?
+- Per-project comparison: which project has the fastest review cycle?
+- Trend line: is review speed improving or degrading over time?

docs/ideas/churn.md

@@ -0,0 +1,77 @@
+# MR Churn Analysis
+
+- **Command:** `lore churn [--since <date>]`
+- **Confidence:** 72%
+- **Tier:** 3
+- **Status:** proposed
+- **Effort:** medium — multi-table aggregation with composite scoring
+
+## What
+
+For merged MRs, compute a "contentiousness score" based on: number of review
+discussions, number of DiffNotes, resolution cycles, file count. Flag high-churn
+MRs as candidates for architectural review.
+
+## Why
+
+High-churn MRs often indicate architectural disagreements, unclear requirements,
+or code that's hard to review. Surfacing them post-merge enables retrospectives
+and identifies areas that need better design upfront.
+
+## Data Required
+
+All exists today:
+- `merge_requests` (state='merged')
+- `discussions` (merge_request_id, resolved, resolvable)
+- `notes` (note_type='DiffNote', discussion_id)
+- `mr_file_changes` (file count per MR)
+
+## Implementation Sketch
+
+```sql
+SELECT
+    mr.iid,
+    mr.title,
+    mr.author_username,
+    p.path_with_namespace,
+    COUNT(DISTINCT d.id) as discussion_count,
+    COUNT(DISTINCT CASE WHEN n.note_type = 'DiffNote' THEN n.id END) as diffnote_count,
+    COUNT(DISTINCT CASE WHEN d.resolvable = 1 AND d.resolved = 1 THEN d.id END) as resolved_threads,
+    COUNT(DISTINCT mfc.id) as files_changed,
+    -- Composite score: normalize each metric and weight
+    (COUNT(DISTINCT d.id) * 2 + COUNT(DISTINCT n.id) + COUNT(DISTINCT mfc.id)) as churn_score
+FROM merge_requests mr
+JOIN projects p ON mr.project_id = p.id
+LEFT JOIN discussions d ON d.merge_request_id = mr.id AND d.noteable_type = 'MergeRequest'
+LEFT JOIN notes n ON n.discussion_id = d.id AND n.is_system = 0
+LEFT JOIN mr_file_changes mfc ON mfc.merge_request_id = mr.id
+WHERE mr.state = 'merged'
+  AND mr.merged_at >= ?1
+GROUP BY mr.id
+ORDER BY churn_score DESC
+LIMIT ?2;
+```
+
+## Human Output
+
+```
+High-Churn MRs (last 90 days)
+
+  MR       Discussions  DiffNotes  Files  Score  Title
+  !234          12          28       8     60    Refactor auth middleware
+  !225           8          19       5     39    API versioning v2
+  !218           6          15      12     39    Database schema migration
+  !210           5           8       3     21    Update logging framework
+```
+
+## Downsides
+
+- High discussion count could mean thorough review, not contention
+- Composite scoring weights are arbitrary; needs calibration per team
+- Large MRs naturally score higher regardless of contention
+
+## Extensions
+
+- Normalize by file count (discussions per file changed)
+- Compare against team averages (flag outliers, not absolute values)
+- `lore churn --author alice` — which of alice's MRs generate the most discussion?

docs/ideas/closure-gaps.md

@@ -0,0 +1,73 @@
+# MR-to-Issue Closure Gap
+
+- **Command:** `lore closure-gaps`
+- **Confidence:** 88%
+- **Tier:** 2
+- **Status:** proposed
+- **Effort:** low — single join query
+
+## What
+
+Find entity_references where reference_type='closes' AND the target issue is still
+open AND the source MR is merged. These represent broken auto-close links where a
+merge should have closed an issue but didn't.
+
+## Why
+
+Simple, definitive, actionable. If a merged MR says "closes #42" but #42 is still
+open, something is wrong. Either auto-close failed (wrong target branch), the
+reference was incorrect, or the issue needs manual attention.
+
+## Data Required
+
+All exists today:
+- `entity_references` (reference_type='closes')
+- `merge_requests` (state='merged')
+- `issues` (state='opened')
+
+## Implementation Sketch
+
+```sql
+SELECT
+    mr.iid as mr_iid,
+    mr.title as mr_title,
+    mr.merged_at,
+    mr.target_branch,
+    i.iid as issue_iid,
+    i.title as issue_title,
+    i.state as issue_state,
+    p.path_with_namespace
+FROM entity_references er
+JOIN merge_requests mr ON er.source_entity_type = 'merge_request'
+    AND er.source_entity_id = mr.id
+JOIN issues i ON er.target_entity_type = 'issue'
+    AND er.target_entity_id = i.id
+JOIN projects p ON er.project_id = p.id
+WHERE er.reference_type = 'closes'
+  AND mr.state = 'merged'
+  AND i.state = 'opened';
+```
+
+## Human Output
+
+```
+Closure Gaps — merged MRs that didn't close their referenced issues
+
+group/backend !234 merged 3d ago → #42 still OPEN
+  "Refactor auth middleware" should have closed "Login timeout bug"
+  Target branch: develop (default: main) — possible branch mismatch
+
+group/frontend !45 merged 1w ago → #38 still OPEN
+  "Update dashboard" should have closed "Dashboard layout broken"
+```
+
+## Downsides
+
+- Could be intentional (MR merged to wrong branch, issue tracked across branches)
+- Cross-project references may not be resolvable if target project not synced
+- GitLab auto-close only works when merging to default branch
+
+## Extensions
+
+- Flag likely cause: branch mismatch (target_branch != project.default_branch)
+- `lore closure-gaps --auto-close` — actually close the issues via API (dangerous, needs confirmation)

docs/ideas/collaboration.md

@@ -0,0 +1,101 @@
+# Author Collaboration Network
+
+- **Command:** `lore collaboration [--since <date>]`
+- **Confidence:** 70%
+- **Tier:** 3
+- **Status:** proposed
+- **Effort:** medium — self-join on notes, graph construction
+
+## What
+
+Build a weighted graph of author pairs: (author_A, author_B, weight) where weight =
+number of times A reviewed B's MR + B reviewed A's MR + they both commented on the
+same entity.
+
+## Why
+
+Reveals team structure empirically. Shows who collaborates across team boundaries
+and where knowledge transfer happens. Useful for re-orgs, onboarding planning,
+and identifying isolated team members.
+
+## Data Required
+
+All exists today:
+- `merge_requests` (author_username)
+- `notes` (author_username, note_type='DiffNote')
+- `discussions` (for co-participation)
+
+## Implementation Sketch
+
+```sql
+-- Review relationships: who reviews whose MRs
+SELECT
+    mr.author_username as author,
+    n.author_username as reviewer,
+    COUNT(*) as review_count
+FROM merge_requests mr
+JOIN discussions d ON d.merge_request_id = mr.id
+JOIN notes n ON n.discussion_id = d.id
+WHERE n.note_type = 'DiffNote'
+  AND n.is_system = 0
+  AND n.author_username != mr.author_username
+  AND mr.created_at >= ?1
+GROUP BY mr.author_username, n.author_username;
+
+-- Co-participation: who comments on the same entities
+WITH entity_participants AS (
+    SELECT
+        COALESCE(d.issue_id, d.merge_request_id) as entity_id,
+        d.noteable_type,
+        n.author_username
+    FROM discussions d
+    JOIN notes n ON n.discussion_id = d.id
+    WHERE n.is_system = 0
+      AND n.created_at >= ?1
+)
+SELECT
+    a.author_username as person_a,
+    b.author_username as person_b,
+    COUNT(DISTINCT a.entity_id) as shared_entities
+FROM entity_participants a
+JOIN entity_participants b
+    ON a.entity_id = b.entity_id
+    AND a.noteable_type = b.noteable_type
+    AND a.author_username < b.author_username  -- avoid duplicates
+GROUP BY a.author_username, b.author_username;
+```
+
+## Output Formats
+
+### JSON (for further analysis)
+```json
+{
+  "nodes": ["alice", "bob", "charlie"],
+  "edges": [
+    { "source": "alice", "target": "bob", "reviews": 15, "co_participated": 8 },
+    { "source": "bob", "target": "charlie", "reviews": 3, "co_participated": 12 }
+  ]
+}
+```
+
+### Human
+```
+Collaboration Network (last 90 days)
+
+  alice <-> bob         15 reviews, 8 shared discussions    [strong]
+  bob <-> charlie        3 reviews, 12 shared discussions   [moderate]
+  alice <-> charlie      1 review, 2 shared discussions     [weak]
+  dave <-> (none)        0 reviews, 0 shared discussions    [isolated]
+```
+
+## Downsides
+
+- Interpretation requires context; high collaboration might mean dependency
+- Doesn't capture collaboration outside GitLab
+- Self-join can be slow with many notes
+
+## Extensions
+
+- `lore collaboration --format dot` — GraphViz network diagram
+- `lore collaboration --isolated` — find team members with no collaboration edges
+- Team boundary detection via graph clustering algorithms

docs/ideas/contributors.md

@@ -0,0 +1,86 @@
+# Contributor Heatmap
+
+- **Command:** `lore contributors [--since <date>]`
+- **Confidence:** 88%
+- **Tier:** 2
+- **Status:** proposed
+- **Effort:** medium — multiple aggregation queries
+
+## What
+
+Rank team members by activity across configurable time windows (7d, 30d, 90d). Shows
+issues authored, MRs authored, MRs merged, review comments made, discussions
+participated in.
+
+## Why
+
+Team leads constantly ask "who's been active?" or "who's contributing to reviews?"
+This answers it from local data without GitLab Premium analytics. Also useful for
+identifying team members who may be overloaded or disengaged.
+
+## Data Required
+
+All exists today:
+- `issues` (author_username, created_at)
+- `merge_requests` (author_username, created_at, merged_at)
+- `notes` (author_username, created_at, note_type, is_system)
+- `discussions` (for participation counting)
+
+## Implementation Sketch
+
+```sql
+-- Combined activity per author
+WITH activity AS (
+    SELECT author_username, 'issue_authored' as activity_type, created_at
+    FROM issues WHERE created_at >= ?1
+    UNION ALL
+    SELECT author_username, 'mr_authored', created_at
+    FROM merge_requests WHERE created_at >= ?1
+    UNION ALL
+    SELECT author_username, 'mr_merged', merged_at
+    FROM merge_requests WHERE merged_at >= ?1 AND state = 'merged'
+    UNION ALL
+    SELECT author_username, 'review_comment', created_at
+    FROM notes WHERE created_at >= ?1 AND note_type = 'DiffNote' AND is_system = 0
+    UNION ALL
+    SELECT author_username, 'discussion_comment', created_at
+    FROM notes WHERE created_at >= ?1 AND note_type != 'DiffNote' AND is_system = 0
+)
+SELECT
+    author_username,
+    COUNT(*) FILTER (WHERE activity_type = 'issue_authored') as issues,
+    COUNT(*) FILTER (WHERE activity_type = 'mr_authored') as mrs_authored,
+    COUNT(*) FILTER (WHERE activity_type = 'mr_merged') as mrs_merged,
+    COUNT(*) FILTER (WHERE activity_type = 'review_comment') as reviews,
+    COUNT(*) FILTER (WHERE activity_type = 'discussion_comment') as comments,
+    COUNT(*) as total
+FROM activity
+GROUP BY author_username
+ORDER BY total DESC;
+```
+
+Note: SQLite doesn't support FILTER — use SUM(CASE WHEN ... THEN 1 ELSE 0 END).
+
+## Human Output
+
+```
+Contributors (last 30 days)
+
+  Username    Issues  MRs  Merged  Reviews  Comments  Total
+  alice          3     8      7      23        12       53
+  bob            1     5      4      31         8       49
+  charlie        5     3      2       4        15       29
+  dave           0     1      0       2         3        6
+```
+
+## Downsides
+
+- Could be used for surveillance; frame as team health, not individual tracking
+- Activity volume != productivity (one thoughtful review > ten "LGTM"s)
+- Doesn't capture work done outside GitLab
+
+## Extensions
+
+- `lore contributors --project group/backend` — scoped to project
+- `lore contributors --type reviews` — focus on review activity only
+- Trend comparison: `--compare 30d,90d` shows velocity changes

docs/ideas/decisions.md

@@ -0,0 +1,94 @@
+# Decision Archaeology
+
+- **Command:** `lore decisions <query>`
+- **Confidence:** 82%
+- **Tier:** 2
+- **Status:** proposed
+- **Effort:** medium — search pipeline + regex pattern matching on notes
+
+## What
+
+Search for discussion notes that contain decision-making language. Use the existing
+search pipeline but boost notes containing patterns like "decided", "agreed",
+"will go with", "tradeoff", "because we", "rationale", "the approach is", "we chose".
+Return the surrounding discussion context.
+
+## Why
+
+This is gitlore's unique value proposition — "why was this decision made?" is the
+question that no other tool answers well. Architecture Decision Records are rarely
+maintained; the real decisions live in discussion threads. This mines them.
+
+## Data Required
+
+All exists today:
+- `documents` + search pipeline (for finding relevant entities)
+- `notes` (body text for pattern matching)
+- `discussions` (for thread context)
+
+## Implementation Sketch
+
+```
+1. Run existing hybrid search to find entities matching the query topic
+2. For each result entity, query all discussion notes
+3. Score each note against decision-language patterns:
+   - Strong signals (weight 3): "decided to", "agreed on", "the decision is",
+     "we will go with", "approved approach"
+   - Medium signals (weight 2): "tradeoff", "because", "rationale", "chosen",
+     "opted for", "rejected", "alternative"
+   - Weak signals (weight 1): "should we", "proposal", "option A", "option B",
+     "pros and cons"
+4. Return notes scoring above threshold, with surrounding context (previous and
+   next note in discussion thread)
+5. Sort by: search relevance * decision score
+```
+
+### Decision Patterns (regex)
+
+```rust
+const STRONG_PATTERNS: &[&str] = &[
+    r"(?i)\b(decided|agreed|approved)\s+(to|on|that)\b",
+    r"(?i)\bthe\s+(decision|approach|plan)\s+is\b",
+    r"(?i)\bwe('ll| will| are going to)\s+(go with|use|implement)\b",
+    r"(?i)\blet'?s\s+(go with|use|do)\b",
+];
+
+const MEDIUM_PATTERNS: &[&str] = &[
+    r"(?i)\b(tradeoff|trade-off|rationale|because we|opted for)\b",
+    r"(?i)\b(rejected|ruled out|won't work|not viable)\b",
+    r"(?i)\b(chosen|selected|picked)\b.{0,20}\b(over|instead of)\b",
+];
+```
+
+## Human Output
+
+```
+Decisions related to "authentication"
+
+group/backend !234 — "Refactor auth middleware"
+  Discussion #a1b2c3 (alice, 3w ago):
+    "We decided to use JWT with short-lived tokens instead of session cookies.
+     The tradeoff is more complexity in the refresh flow, but we get stateless
+     auth which scales better."
+    Decision confidence: HIGH (3 strong pattern matches)
+
+group/backend #42 — "Auth architecture review"
+  Discussion #d4e5f6 (bob, 2mo ago):
+    "After discussing with the security team, we'll go with bcrypt for password
+     hashing. Argon2 is theoretically better but bcrypt has wider library support."
+    Decision confidence: HIGH (2 strong pattern matches)
+```
+
+## Downsides
+
+- Pattern matching is imperfect; may miss decisions phrased differently
+- May surface "discussion about deciding" rather than actual decisions
+- Non-English discussions won't match
+- Requires good search results as input (garbage in, garbage out)
+
+## Extensions
+
+- `lore decisions --recent` — decisions made in last 30 days
+- `lore decisions --author alice` — decisions made by specific person
+- Export as ADR (Architecture Decision Record) format
+- Combine with timeline for chronological decision history

docs/ideas/digest.md

@@ -0,0 +1,131 @@
+# "What Changed?" Digest
+
+- **Command:** `lore digest --since <date>`
+- **Confidence:** 93%
+- **Tier:** 1
+- **Status:** proposed
+- **Effort:** medium — multiple queries across event tables, formatting logic
+
+## What
+
+Generate a structured summary of all activity since a given date: issues
+opened/closed, MRs merged, labels changed, milestones updated, key discussions.
+Group by project and sort by significance (state changes > merges > label changes >
+new comments).
+
+Default `--since` is 1 day (last 24 hours). Supports `7d`, `2w`, `YYYY-MM-DD`.
+
+## Why
+
+"What happened while I was on PTO?" is the most universal developer question. This
+is a killer feature that leverages ALL the event data gitlore has ingested. No other
+local tool provides this.
+
+## Data Required
+
+All exists today:
+- `resource_state_events` (opened/closed/merged/reopened)
+- `resource_label_events` (label add/remove)
+- `resource_milestone_events` (milestone add/remove)
+- `merge_requests` (merged_at for merge events)
+- `issues` (created_at for new issues)
+- `discussions` (last_note_at for active discussions)
+
+## Implementation Sketch
+
+```
+1. Parse --since into ms epoch timestamp
+2. Query each event table WHERE created_at >= since
+3. Query new issues WHERE created_at >= since
+4. Query merged MRs WHERE merged_at >= since
+5. Query active discussions WHERE last_note_at >= since
+6. Group all events by project
+7. Within each project, sort by: state changes first, then merges, then labels
+8. Format as human-readable sections or robot JSON
+```
+
+### SQL Queries
+
+```sql
+-- State changes in window
+SELECT rse.*, i.iid as issue_iid, mr.iid as mr_iid,
+       COALESCE(i.title, mr.title) as title,
+       p.path_with_namespace
+FROM resource_state_events rse
+LEFT JOIN issues i ON rse.issue_id = i.id
+LEFT JOIN merge_requests mr ON rse.merge_request_id = mr.id
+JOIN projects p ON rse.project_id = p.id
+WHERE rse.created_at >= ?1
+ORDER BY rse.created_at DESC;
+
+-- Newly merged MRs
+SELECT mr.iid, mr.title, mr.author_username, mr.merged_at,
+       p.path_with_namespace
+FROM merge_requests mr
+JOIN projects p ON mr.project_id = p.id
+WHERE mr.merged_at >= ?1
+ORDER BY mr.merged_at DESC;
+
+-- New issues
+SELECT i.iid, i.title, i.author_username, i.created_at,
+       p.path_with_namespace
+FROM issues i
+JOIN projects p ON i.project_id = p.id
+WHERE i.created_at >= ?1
+ORDER BY i.created_at DESC;
+```
+
+## Human Output Format
+
+```
+=== What Changed (last 7 days) ===
+
+group/backend (12 events)
+  Merged:
+    !234  Refactor auth middleware          (alice, 2d ago)
+    !231  Fix connection pool leak          (bob, 5d ago)
+  Closed:
+    #89   Login timeout on slow networks    (closed by alice, 3d ago)
+  Opened:
+    #95   Rate limiting returns 500         (charlie, 1d ago)
+  Labels:
+    #90   +priority::high                   (dave, 4d ago)
+
+group/frontend (3 events)
+  Merged:
+    !45   Update dashboard layout           (eve, 6d ago)
+```
+
+## Robot Mode Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "since": "2025-01-20T00:00:00Z",
+    "projects": [
+      {
+        "path": "group/backend",
+        "merged": [ { "iid": 234, "title": "...", "author": "alice" } ],
+        "closed": [ { "iid": 89, "title": "...", "actor": "alice" } ],
+        "opened": [ { "iid": 95, "title": "...", "author": "charlie" } ],
+        "label_changes": [ { "iid": 90, "label": "priority::high", "action": "add" } ]
+      }
+    ],
+    "summary": { "total_events": 15, "projects_active": 2 }
+  }
+}
+```
+
+## Downsides
+
+- Can be overwhelming for very active repos; needs `--limit` per category
+- Doesn't capture nuance (a 200-comment MR merge is more significant than a typo fix)
+- Only shows what gitlore has synced; stale data = stale digest
+
+## Extensions
+
+- `lore digest --author alice` — personal activity digest
+- `lore digest --project group/backend` — single project scope
+- `lore digest --format markdown` — paste-ready for Slack/email
+- Combine with weekly-digest for scheduled summaries

docs/ideas/experts.md

@@ -0,0 +1,120 @@
+# Who Knows About X?
+
+- **Command:** `lore experts <path-or-topic>`
+- **Confidence:** 92%
+- **Tier:** 1
+- **Status:** proposed
+- **Effort:** medium — two query paths (file-based, topic-based)
+
+## What
+
+Given a file path, find people who have authored MRs touching that file, left
+DiffNotes on that file, or discussed issues referencing that file. Given a topic
+string, use search to find relevant entities then extract the active participants.
+
+## Why
+
+"Who should I ask about the auth module?" is one of the most common questions in
+large teams. This answers it empirically from actual contribution and review data.
+No guessing, no out-of-date wiki pages.
+
+## Data Required
+
+All exists today:
+- `mr_file_changes` (new_path, merge_request_id) — who changed the file
+- `notes` (position_new_path, author_username) — who reviewed the file
+- `merge_requests` (author_username) — MR authorship
+- `documents` + search pipeline — for topic-based queries
+- `discussions` + `notes` — for participant extraction
+
+## Implementation Sketch
+
+### Path Mode: `lore experts src/auth/`
+
+```
+1. Query mr_file_changes WHERE new_path LIKE 'src/auth/%'
+2. Join merge_requests to get author_username for each MR
+3. Query notes WHERE position_new_path LIKE 'src/auth/%'
+4. Collect all usernames with activity counts
+5. Rank by: MR authorship (weight 3) + DiffNote authorship (weight 2) + discussion participation (weight 1)
+6. Apply recency decay (recent activity weighted higher)
+```
+
+### Topic Mode: `lore experts "authentication timeout"`
+
+```
+1. Run existing hybrid search for the topic
+2. Collect top N document results
+3. For each document, extract author_username
+4. For each document's entity, query discussions and collect note authors
+5. Rank by frequency and recency
+```
+
+### SQL (Path Mode)
+
+```sql
+-- Authors who changed files matching pattern
+SELECT mr.author_username, COUNT(*) as changes, MAX(mr.merged_at) as last_active
+FROM mr_file_changes mfc
+JOIN merge_requests mr ON mfc.merge_request_id = mr.id
+WHERE mfc.new_path LIKE ?1
+  AND mr.state = 'merged'
+GROUP BY mr.author_username
+ORDER BY changes DESC;
+
+-- Reviewers who commented on files matching pattern
+SELECT n.author_username, COUNT(*) as reviews, MAX(n.created_at) as last_active
+FROM notes n
+WHERE n.position_new_path LIKE ?1
+  AND n.note_type = 'DiffNote'
+  AND n.is_system = 0
+GROUP BY n.author_username
+ORDER BY reviews DESC;
+```
+
+## Human Output Format
+
+```
+Experts for: src/auth/
+
+  alice     12 changes, 8 reviews   (last active 3d ago)   [top contributor]
+  bob        3 changes, 15 reviews  (last active 1d ago)   [top reviewer]
+  charlie    5 changes, 2 reviews   (last active 2w ago)
+  dave       1 change,  0 reviews   (last active 3mo ago)  [stale]
+```
+
+## Robot Mode Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "query": "src/auth/",
+    "query_type": "path",
+    "experts": [
+      {
+        "username": "alice",
+        "changes": 12,
+        "reviews": 8,
+        "discussions": 3,
+        "score": 62,
+        "last_active": "2025-01-25T10:00:00Z",
+        "role": "top_contributor"
+      }
+    ]
+  }
+}
+```
+
+## Downsides
+
+- Historical data may be stale (people leave teams, change roles)
+- Path mode requires `mr_file_changes` to be populated (Gate 4 ingestion)
+- Topic mode quality depends on search quality
+- Doesn't account for org chart / actual ownership
+
+## Extensions
+
+- `lore experts --since 90d` — recency filter
+- `lore experts --min-activity 3` — noise filter
+- Combine with `lore silos` to highlight when an expert is the ONLY expert

docs/ideas/graph.md

@@ -0,0 +1,75 @@
+# Entity Relationship Explorer
+
+- **Command:** `lore graph <entity-type> <iid>`
+- **Confidence:** 80%
+- **Tier:** 3
+- **Status:** proposed
+- **Effort:** medium — BFS traversal (similar to timeline expand), output formatting
+
+## What
+
+Given an issue or MR, traverse `entity_references` and display all connected
+entities with relationship types and depths. Output as tree, JSON, or Mermaid diagram.
+
+## Why
+
+The entity_references graph is already built (Gate 2) but has no dedicated
+exploration command. Timeline shows events over time; this shows the relationship
+structure. "What's connected to this issue?" is a different question from "what
+happened to this issue?"
+
+## Data Required
+
+All exists today:
+- `entity_references` (source/target entity, reference_type)
+- `issues` / `merge_requests` (for entity context)
+- Timeline expand stage already implements BFS over this graph
+
+## Implementation Sketch
+
+```
+1. Resolve entity type + iid to local ID
+2. BFS over entity_references:
+   - Follow source→target AND target→source (bidirectional)
+   - Track depth (--depth flag, default 2)
+   - Track reference_type for edge labels
+3. Hydrate each discovered entity with title, state, URL
+4. Format as tree / JSON / Mermaid
+```
+
+## Human Output (Tree)
+
+```
+#42 Login timeout bug (CLOSED)
+  ├── closes ── !234 Refactor auth middleware (MERGED)
+  │   ├── mentioned ── #38 Connection timeout in auth flow (CLOSED)
+  │   └── mentioned ── #51 Token refresh improvements (OPEN)
+  ├── related ── #45 Auth module documentation (OPEN)
+  └── mentioned ── !228 Database migration (MERGED)
+      └── closes ── #35 Schema version drift (CLOSED)
+```
+
+## Mermaid Output
+
+```mermaid
+graph LR
+    I42["#42 Login timeout"] -->|closes| MR234["!234 Refactor auth"]
+    MR234 -->|mentioned| I38["#38 Connection timeout"]
+    MR234 -->|mentioned| I51["#51 Token refresh"]
+    I42 -->|related| I45["#45 Auth docs"]
+    I42 -->|mentioned| MR228["!228 DB migration"]
+    MR228 -->|closes| I35["#35 Schema drift"]
+```
+
+## Downsides
+
+- Overlaps somewhat with timeline (but different focus: structure vs chronology)
+- High fan-out for popular entities (need depth + limit controls)
+- Unresolved cross-project references appear as dead ends
+
+## Extensions
+
+- `lore graph --format dot` — GraphViz DOT output
+- `lore graph --format mermaid` — Mermaid diagram
+- `lore graph --include-discussions` — show discussion threads as nodes
+- Interactive HTML visualization (future web UI)

docs/ideas/hotspots.md

@@ -0,0 +1,70 @@
+# File Hotspot Report
+
+- **Command:** `lore hotspots [--since <date>]`
+- **Confidence:** 85%
+- **Tier:** 2
+- **Status:** proposed
+- **Effort:** low — single query on mr_file_changes (requires Gate 4 population)
+
+## What
+
+Rank files by frequency of appearance in merged MRs over a time window. Show
+change_type breakdown (modified vs added vs deleted). Optionally filter by project.
+
+## Why
+
+Hot files are where bugs live. This is a proven engineering metric (see "Your Code
+as a Crime Scene" by Adam Tornhill). High-churn files deserve extra test coverage,
+better documentation, and architectural review.
+
+## Data Required
+
+- `mr_file_changes` (new_path, change_type, merge_request_id) — needs Gate 4 population
+- `merge_requests` (merged_at, state='merged')
+
+## Implementation Sketch
+
+```sql
+SELECT
+    mfc.new_path,
+    p.path_with_namespace,
+    COUNT(*) as total_changes,
+    SUM(CASE WHEN mfc.change_type = 'modified' THEN 1 ELSE 0 END) as modifications,
+    SUM(CASE WHEN mfc.change_type = 'added' THEN 1 ELSE 0 END) as additions,
+    SUM(CASE WHEN mfc.change_type = 'deleted' THEN 1 ELSE 0 END) as deletions,
+    SUM(CASE WHEN mfc.change_type = 'renamed' THEN 1 ELSE 0 END) as renames,
+    COUNT(DISTINCT mr.author_username) as unique_authors
+FROM mr_file_changes mfc
+JOIN merge_requests mr ON mfc.merge_request_id = mr.id
+JOIN projects p ON mfc.project_id = p.id
+WHERE mr.state = 'merged'
+  AND mr.merged_at >= ?1
+GROUP BY mfc.new_path, p.path_with_namespace
+ORDER BY total_changes DESC
+LIMIT ?2;
+```
+
+## Human Output
+
+```
+File Hotspots (last 90 days, top 20)
+
+  File                              Changes  Authors  Type Breakdown
+  src/auth/middleware.rs                 18        4  14 mod, 3 add, 1 del
+  src/api/routes.rs                     15        3  12 mod, 2 add, 1 rename
+  src/db/migrations.rs                  12        2  8 mod, 4 add
+  tests/integration/auth_test.rs        11        3  9 mod, 2 add
+```
+
+## Downsides
+
+- Requires `mr_file_changes` to be populated (Gate 4 ingestion)
+- Doesn't distinguish meaningful changes from trivial ones (formatting, imports)
+- Configuration files (CI, Cargo.toml) will rank high but aren't risky
+
+## Extensions
+
+- `lore hotspots --exclude "*.toml,*.yml"` — filter out config files
+- `lore hotspots --dir src/auth/` — scope to directory
+- Combine with `lore silos` for risk scoring: high churn + bus factor 1 = critical
+- Complexity trend: correlate with discussion count (churn + many discussions = problematic)

docs/ideas/idle.md

@@ -0,0 +1,69 @@
+# Idle Work Detector
+
+- **Command:** `lore idle [--days <N>] [--labels <pattern>]`
+- **Confidence:** 73%
+- **Tier:** 3
+- **Status:** proposed
+- **Effort:** medium — label event querying with configurable patterns
+
+## What
+
+Find entities that received an "in progress" or similar label but have had no
+discussion activity for N days. Cross-reference with assignee to show who might
+have forgotten about something.
+
+## Why
+
+Forgotten WIP is invisible waste. Developers start work, get pulled to something
+urgent, and the original task sits idle. This makes it visible before it becomes
+a problem.
+
+## Data Required
+
+All exists today:
+- `resource_label_events` (label_name, action='add', created_at)
+- `discussions` (last_note_at for entity activity)
+- `issues` / `merge_requests` (state, assignees)
+- `issue_assignees` / `mr_assignees`
+
+## Implementation Sketch
+
+```
+1. Query resource_label_events for labels matching "in progress" patterns
+   Default patterns: "in-progress", "in_progress", "doing", "wip",
+   "workflow::in-progress", "status::in-progress"
+   Configurable via --labels flag
+2. For each entity with an "in progress" label still applied:
+   a. Check if the label was subsequently removed (if so, skip)
+   b. Get last_note_at from discussions for that entity
+   c. Flag if last_note_at is older than threshold
+3. Join with assignees for attribution
+```
+
+## Human Output
+
+```
+Idle Work (labeled "in progress" but no activity for 14+ days)
+
+group/backend
+  #90  Rate limiting design       assigned to: charlie    idle 18 days
+       Last activity: label +priority::high by dave
+  #85  Cache invalidation fix     assigned to: alice      idle 21 days
+       Last activity: discussion comment by bob
+
+group/frontend
+  !230 Dashboard redesign         assigned to: eve        idle 14 days
+       Last activity: DiffNote by dave
+```
+
+## Downsides
+
+- Requires label naming conventions; no universal standard
+- Work may be happening outside GitLab (local branch, design doc)
+- "Idle" threshold is subjective; 14 days may be normal for large features
+
+## Extensions
+
+- `lore idle --assignee alice` — personal idle work check
+- `lore idle --notify` — generate message templates for nudging owners
+- Configurable label patterns in config.json for team-specific workflows

docs/ideas/impact-graph.md

@@ -0,0 +1,92 @@
+# Cross-Project Impact Graph
+
+- **Command:** `lore impact-graph [--format json|dot|mermaid]`
+- **Confidence:** 75%
+- **Tier:** 3
+- **Status:** proposed
+- **Effort:** medium — aggregation over entity_references, graph output formatting
+
+## What
+
+Aggregate `entity_references` by project pair to produce a weighted adjacency matrix
+showing how projects reference each other. Output as JSON, DOT, or Mermaid for
+visualization.
+
+## Why
+
+Makes invisible architectural coupling visible. "Backend and frontend repos have
+47 cross-references this quarter" tells you about tight coupling that may need
+architectural attention.
+
+## Data Required
+
+All exists today:
+- `entity_references` (source/target entity IDs)
+- `issues` / `merge_requests` (project_id for source/target)
+- `projects` (path_with_namespace)
+
+## Implementation Sketch
+
+```sql
+-- Project-to-project reference counts
+WITH ref_projects AS (
+    SELECT
+        CASE er.source_entity_type
+            WHEN 'issue' THEN i_src.project_id
+            WHEN 'merge_request' THEN mr_src.project_id
+        END as source_project_id,
+        CASE er.target_entity_type
+            WHEN 'issue' THEN i_tgt.project_id
+            WHEN 'merge_request' THEN mr_tgt.project_id
+        END as target_project_id,
+        er.reference_type
+    FROM entity_references er
+    LEFT JOIN issues i_src ON er.source_entity_type = 'issue' AND er.source_entity_id = i_src.id
+    LEFT JOIN merge_requests mr_src ON er.source_entity_type = 'merge_request' AND er.source_entity_id = mr_src.id
+    LEFT JOIN issues i_tgt ON er.target_entity_type = 'issue' AND er.target_entity_id = i_tgt.id
+    LEFT JOIN merge_requests mr_tgt ON er.target_entity_type = 'merge_request' AND er.target_entity_id = mr_tgt.id
+    WHERE er.target_entity_id IS NOT NULL  -- resolved references only
+)
+SELECT
+    p_src.path_with_namespace as source_project,
+    p_tgt.path_with_namespace as target_project,
+    er.reference_type,
+    COUNT(*) as weight
+FROM ref_projects rp
+JOIN projects p_src ON rp.source_project_id = p_src.id
+JOIN projects p_tgt ON rp.target_project_id = p_tgt.id
+WHERE rp.source_project_id != rp.target_project_id  -- cross-project only
+GROUP BY p_src.path_with_namespace, p_tgt.path_with_namespace, er.reference_type
+ORDER BY weight DESC;
+```
+
+## Output Formats
+
+### Mermaid
+```mermaid
+graph LR
+    Backend -->|closes 23| Frontend
+    Backend -->|mentioned 47| Infrastructure
+    Frontend -->|mentioned 12| Backend
+```
+
+### DOT
+```dot
+digraph impact {
+    "group/backend" -> "group/frontend" [label="closes: 23"];
+    "group/backend" -> "group/infra" [label="mentioned: 47"];
+}
+```
+
+## Downsides
+
+- Requires multiple projects synced; limited value for single-project users
+- "Mentioned" references are noisy (high volume, low signal)
+- Doesn't capture coupling through shared libraries or APIs (code-level coupling)
+
+## Extensions
+
+- `lore impact-graph --since 90d` — time-scoped coupling analysis
+- `lore impact-graph --type closes` — only meaningful reference types
+- Include unresolved references to show dependencies on un-synced projects
+- Coupling trend: is cross-project coupling increasing over time?

docs/ideas/label-audit.md

@@ -0,0 +1,97 @@
+# Label Hygiene Audit
+
+- **Command:** `lore label-audit`
+- **Confidence:** 82%
+- **Tier:** 2
+- **Status:** proposed
+- **Effort:** low — straightforward aggregation queries
+
+## What
+
+Report on label health:
+- Labels used only once (may be typos or abandoned experiments)
+- Labels applied and removed within 1 hour (likely mistakes)
+- Labels with no active issues/MRs (orphaned)
+- Label name collisions across projects (same name, different meaning)
+- Labels never used at all (defined but not applied)
+
+## Why
+
+Label sprawl is real and makes filtering useless over time. Teams create labels
+ad-hoc and never clean them up. This simple audit surfaces maintenance tasks.
+
+## Data Required
+
+All exists today:
+- `labels` (name, project_id)
+- `issue_labels` / `mr_labels` (usage counts)
+- `resource_label_events` (add/remove pairs for mistake detection)
+- `issues` / `merge_requests` (state for "active" filtering)
+
+## Implementation Sketch
+
+```sql
+-- Labels used only once
+SELECT l.name, p.path_with_namespace, COUNT(*) as usage
+FROM labels l
+JOIN projects p ON l.project_id = p.id
+LEFT JOIN issue_labels il ON il.label_id = l.id
+LEFT JOIN mr_labels ml ON ml.label_id = l.id
+GROUP BY l.id
+HAVING COUNT(il.issue_id) + COUNT(ml.merge_request_id) = 1;
+
+-- Flash labels (applied and removed within 1 hour)
+SELECT
+    rle1.label_name,
+    rle1.created_at as added_at,
+    rle2.created_at as removed_at,
+    (rle2.created_at - rle1.created_at) / 60000 as minutes_active
+FROM resource_label_events rle1
+JOIN resource_label_events rle2
+    ON rle1.issue_id = rle2.issue_id
+    AND rle1.label_name = rle2.label_name
+    AND rle1.action = 'add'
+    AND rle2.action = 'remove'
+    AND rle2.created_at > rle1.created_at
+    AND (rle2.created_at - rle1.created_at) < 3600000;
+
+-- Unused labels (defined but never applied)
+SELECT l.name, p.path_with_namespace
+FROM labels l
+JOIN projects p ON l.project_id = p.id
+LEFT JOIN issue_labels il ON il.label_id = l.id
+LEFT JOIN mr_labels ml ON ml.label_id = l.id
+WHERE il.issue_id IS NULL AND ml.merge_request_id IS NULL;
+```
+
+## Human Output
+
+```
+Label Audit
+
+Unused Labels (4):
+  group/backend:  deprecated-v1, needs-triage, wontfix-maybe
+  group/frontend: old-design
+
+Single-Use Labels (3):
+  group/backend:  perf-regression (1 issue)
+  group/frontend: ux-debt (1 MR), mobile-only (1 issue)
+
+Flash Labels (applied < 1hr, 2):
+  group/backend #90: +priority::critical then -priority::critical (12 min)
+  group/backend #85: +blocked then -blocked (5 min)
+
+Cross-Project Collisions (1):
+  "needs-review" used in group/backend (32 uses) AND group/frontend (8 uses)
+```
+
+## Downsides
+
+- Low glamour; this is janitorial work
+- Single-use labels may be legitimate (one-off categorization)
+- Cross-project collisions may be intentional (shared vocabulary)
+
+## Extensions
+
+- `lore label-audit --fix` — suggest deletions for unused labels
+- Trend: label count over time (is sprawl increasing?)

docs/ideas/label-flow.md

@@ -0,0 +1,74 @@
+# Label Velocity
+
+- **Command:** `lore label-flow <from-label> <to-label>`
+- **Confidence:** 78%
+- **Tier:** 3
+- **Status:** proposed
+- **Effort:** medium — self-join on resource_label_events, percentile computation
+
+## What
+
+For a given label pair (e.g., "needs-review" to "approved"), compute median and P90
+transition times using `resource_label_events`. Shows how fast work moves through
+your process labels.
+
+Also supports: single label dwell time (how long does "in-progress" stay applied?).
+
+## Why
+
+Process bottlenecks become quantifiable. "Our code review takes a median of 3 days"
+is actionable data for retrospectives and process improvement.
+
+## Data Required
+
+All exists today:
+- `resource_label_events` (label_name, action, created_at, issue_id, merge_request_id)
+
+## Implementation Sketch
+
+```sql
+-- Label A → Label B transition time
+WITH add_a AS (
+    SELECT issue_id, merge_request_id, MIN(created_at) as added_at
+    FROM resource_label_events
+    WHERE label_name = ?1 AND action = 'add'
+    GROUP BY issue_id, merge_request_id
+),
+add_b AS (
+    SELECT issue_id, merge_request_id, MIN(created_at) as added_at
+    FROM resource_label_events
+    WHERE label_name = ?2 AND action = 'add'
+    GROUP BY issue_id, merge_request_id
+)
+SELECT
+    (b.added_at - a.added_at) / 3600000.0 as hours_transition
+FROM add_a a
+JOIN add_b b ON a.issue_id = b.issue_id OR a.merge_request_id = b.merge_request_id
+WHERE b.added_at > a.added_at;
+```
+
+Then compute percentiles in Rust (median, P75, P90).
+
+## Human Output
+
+```
+Label Flow: "needs-review" → "approved"
+
+  Transitions:  42 issues/MRs in last 90 days
+  Median:       18.5 hours
+  P75:          36.2 hours
+  P90:          72.8 hours
+  Slowest:      !234 Refactor auth (168 hours)
+```
+
+## Downsides
+
+- Only works if teams use label-based workflows consistently
+- Labels may be applied out of order or skipped
+- Self-join performance could be slow with many events
+
+## Extensions
+
+- `lore label-flow --dwell "in-progress"` — how long does a label stay?
+- `lore label-flow --all` — auto-discover common transitions from event data
+- Visualization: label state machine with median transition times on edges

docs/ideas/milestone-risk.md

@@ -0,0 +1,81 @@
+# Milestone Risk Report
+
+- **Command:** `lore milestone-risk [title]`
+- **Confidence:** 78%
+- **Tier:** 3
+- **Status:** proposed
+- **Effort:** medium — milestone + issue aggregation with scope change detection
+
+## What
+
+For each active milestone (or a specific one): show total issues, % closed, issues
+added after milestone creation (scope creep), issues with no assignee, issues with
+overdue due_date. Flag milestones where completion rate is below expected trajectory.
+
+## Why
+
+Milestone health is usually assessed by gut feel. This provides objective signals
+from data already ingested. Project managers can spot risks early.
+
+## Data Required
+
+All exists today:
+- `milestones` (title, state, due_date)
+- `issues` (milestone_id, state, created_at, due_date, assignee)
+- `issue_assignees` (for unassigned detection)
+
+## Implementation Sketch
+
+```sql
+SELECT
+    m.title,
+    m.state,
+    m.due_date,
+    COUNT(*) as total_issues,
+    SUM(CASE WHEN i.state = 'closed' THEN 1 ELSE 0 END) as closed,
+    SUM(CASE WHEN i.state = 'opened' THEN 1 ELSE 0 END) as open,
+    SUM(CASE WHEN i.created_at > m.created_at THEN 1 ELSE 0 END) as scope_creep,
+    SUM(CASE WHEN ia.username IS NULL AND i.state = 'opened' THEN 1 ELSE 0 END) as unassigned,
+    SUM(CASE WHEN i.due_date < DATE('now') AND i.state = 'opened' THEN 1 ELSE 0 END) as overdue
+FROM milestones m
+JOIN issues i ON i.milestone_id = m.id
+LEFT JOIN issue_assignees ia ON ia.issue_id = i.id
+WHERE m.state = 'active'
+GROUP BY m.id;
+```
+
+Note: `created_at` comparison for scope creep is approximate — GitLab doesn't
+expose when an issue was added to a milestone via its milestone_events.
+
+Actually we DO have `resource_milestone_events` — use those for precise scope change
+detection.
+
+## Human Output
+
+```
+Milestone Risk Report
+
+v2.0 (due Feb 15, 2025)
+  Progress:  14/20 closed (70%)
+  Scope:     +3 issues added after milestone start
+  Risks:     2 issues overdue, 1 issue unassigned
+  Status:    ON TRACK (70% complete, 60% time elapsed)
+
+v2.1 (due Mar 30, 2025)
+  Progress:  2/15 closed (13%)
+  Scope:     +8 issues added after milestone start
+  Risks:     5 issues unassigned
+  Status:    AT RISK (13% complete, scope still growing)
+```
+
+## Downsides
+
+- Milestone semantics vary wildly between teams
+- "Scope creep" detection is noisy if teams batch-add issues to milestones
+- due_date comparison assumes consistent timezone handling
+
+## Extensions
+
+- `lore milestone-risk --history` — show scope changes over time
+- Velocity estimation: at current closure rate, will the milestone finish on time?
+- Combine with label-flow for "how fast are milestone issues moving through workflow"

docs/ideas/mr-pipeline.md

@@ -0,0 +1,67 @@
+# MR Pipeline Efficiency
+
+- **Command:** `lore mr-pipeline [--since <date>]`
+- **Confidence:** 78%
+- **Tier:** 3
+- **Status:** proposed
+- **Effort:** medium — builds on bottleneck detector with more stages
+
+## What
+
+Track the full MR lifecycle: creation, first review, all reviews complete (threads
+resolved), approval, merge. Compute time spent in each stage across all MRs.
+Identify which stage is the bottleneck.
+
+## Why
+
+"Our merge process is slow" is vague. This breaks it into stages so teams can target
+the actual bottleneck. Maybe creation-to-review is fast but review-to-merge is slow
+(merge queue issues). Maybe first review is fast but resolution takes forever
+(contentious code).
+
+## Data Required
+
+All exists today:
+- `merge_requests` (created_at, merged_at)
+- `notes` (note_type='DiffNote', created_at, author_username)
+- `discussions` (resolved, resolvable, merge_request_id)
+- `resource_state_events` (state changes with timestamps)
+
+## Implementation Sketch
+
+For each merged MR, compute:
+1. **Created → First Review**: MIN(DiffNote.created_at) - mr.created_at
+2. **First Review → All Resolved**: MAX(discussion.resolved_at) - MIN(DiffNote.created_at)
+3. **All Resolved → Merged**: mr.merged_at - MAX(discussion.resolved_at)
+
+Note: "resolved_at" isn't directly stored but can be approximated from the last
+note in resolved discussions, or from state events.
+
+## Human Output
+
+```
+MR Pipeline (last 30 days, 24 merged MRs)
+
+  Stage                    Median    P75      P90
+  Created → First Review   4.2h     12.1h    28.3h
+  First Review → Resolved  8.1h     24.5h    72.0h    <-- BOTTLENECK
+  Resolved → Merged        0.5h      1.2h     3.1h
+
+  Total (Created → Merged) 18.4h    48.2h    96.1h
+
+  Biggest bottleneck: Review resolution (median 8.1h)
+  Suggestion: Consider breaking large MRs into smaller reviewable chunks
+```
+
+## Downsides
+
+- "Resolved" timestamp approximation may be inaccurate
+- Pipeline assumes linear flow; real MRs have back-and-forth cycles
+- Draft MRs skew metrics (created early, reviewed late intentionally)
+
+## Extensions
+
+- `lore mr-pipeline --exclude-drafts` — cleaner metrics
+- Per-project comparison: which project has the fastest pipeline?
+- Trend line: weekly pipeline speed over time
+- Break down by MR size (files changed) to normalize

docs/ideas/project-ergonomics.md

@@ -0,0 +1,265 @@
+# Multi-Project Ergonomics
+
+- **Confidence:** 90%
+- **Tier:** 1
+- **Status:** proposed
+- **Effort:** medium (multiple small improvements that compound)
+
+## The Problem
+
+Every command that touches project-scoped data requires `-p group/subgroup/project`
+to disambiguate. For users with 5+ projects synced, this is:
+
+- Repetitive: typing `-p infra/platform/auth-service` on every query
+- Error-prone: mistyping long paths
+- Discoverable only by failure: you don't know you need `-p` until you hit an
+  ambiguous error
+
+The fuzzy matching in `resolve_project` is already good (suffix, substring,
+case-insensitive) but it only kicks in on the `-p` value itself. There's no way to
+set a default, group projects, or scope a whole session.
+
+## Proposed Improvements
+
+### 1. Project Aliases in Config
+
+Let users define short aliases for long project paths.
+
+```json
+{
+  "projects": [
+    { "path": "infra/platform/auth-service", "alias": "auth" },
+    { "path": "infra/platform/billing-service", "alias": "billing" },
+    { "path": "frontend/customer-portal", "alias": "portal" },
+    { "path": "frontend/admin-dashboard", "alias": "admin" }
+  ]
+}
+```
+
+Then: `lore issues -p auth` resolves via alias before falling through to fuzzy match.
+
+**Implementation:** Add optional `alias` field to `ProjectConfig`. In
+`resolve_project`, check aliases before the existing exact/suffix/substring cascade.
+
+```rust
+#[derive(Debug, Clone, Deserialize)]
+pub struct ProjectConfig {
+    pub path: String,
+    #[serde(default)]
+    pub alias: Option<String>,
+}
+```
+
+Resolution order becomes:
+1. Exact alias match (new)
+2. Exact path match
+3. Case-insensitive path match
+4. Suffix match
+5. Substring match
+
+### 2. Default Project (`LORE_PROJECT` env var)
+
+Set a default project for your shell session so you don't need `-p` at all.
+
+```bash
+export LORE_PROJECT=auth
+lore issues                   # scoped to auth-service
+lore mrs --state opened       # scoped to auth-service
+lore search "timeout bug"     # scoped to auth-service
+lore issues -p billing        # explicit -p overrides the env var
+```
+
+**Implementation:** In every command that accepts `-p`, fall back to
+`std::env::var("LORE_PROJECT")` when the flag is absent. The `-p` flag always wins.
+
+Could also support a config-level default:
+
+```json
+{
+  "defaultProject": "auth"
+}
+```
+
+Precedence: CLI flag > env var > config default > (no filter).
+
+### 3. `lore use <project>` — Session Context Switcher
+
+A command that sets `LORE_PROJECT` for the current shell by writing to a dotfile.
+
+```bash
+lore use auth
+# writes ~/.local/state/lore/current-project containing "auth"
+
+lore issues        # reads current-project file, scopes to auth
+lore use --clear   # removes the file, back to all-project mode
+lore use           # shows current project context
+```
+
+This is similar to `kubectl config use-context`, `nvm use`, or `tfenv use`.
+
+**Implementation:** Write a one-line file at a known state path. Each command reads
+it as the lowest-priority default (below env var and CLI flag).
+
+Precedence: CLI flag > env var > `lore use` state file > config default > (no filter).
+
+### 4. `lore projects` — Project Listing and Discovery
+
+A dedicated command to see what's synced, with aliases and activity stats.
+
+```bash
+$ lore projects
+
+  Alias    Path                              Issues   MRs   Last Sync
+  auth     infra/platform/auth-service          142    87   2h ago
+  billing  infra/platform/billing-service        56    34   2h ago
+  portal   frontend/customer-portal             203   112   2h ago
+  admin    frontend/admin-dashboard              28    15   3d ago
+  -        data/ml-pipeline                      89    45   2h ago
+```
+
+Robot mode returns the same as JSON with alias, path, counts, and last sync time.
+
+**Implementation:** Query `projects` joined with `COUNT(issues)`, `COUNT(mrs)`,
+and `MAX(sync_runs.finished_at)`. Overlay aliases from config.
+
+### 5. Project Groups in Config
+
+Let users define named groups of projects for batch scoping.
+
+```json
+{
+  "projectGroups": {
+    "backend": ["auth", "billing", "data/ml-pipeline"],
+    "frontend": ["portal", "admin"],
+    "all-infra": ["auth", "billing"]
+  }
+}
+```
+
+Then: `lore issues -p @backend` (or `--group backend`) queries across all projects
+in the group.
+
+**Implementation:** When `-p` value starts with `@`, look up the group and resolve
+each member project. Pass as a `Vec<i64>` of project IDs to the query layer.
+
+This is especially powerful for:
+- `lore search "auth bug" -p @backend` — search across related repos
+- `lore digest --since 7d -p @frontend` — team-scoped activity digest
+- `lore timeline "deployment" -p @all-infra` — cross-repo timeline
+
+### 6. Git-Aware Project Detection
+
+When running `lore` from inside a git repo that matches a synced project, auto-scope
+to that project without any flags.
+
+```bash
+cd ~/code/auth-service
+lore issues                   # auto-detects this is infra/platform/auth-service
+```
+
+**Implementation:** Read `.git/config` for the remote URL, extract the project path,
+check if it matches a synced project. Only activate when exactly one project matches.
+
+Detection logic:
+```
+1. Check if cwd is inside a git repo (find .git)
+2. Parse git remote origin URL
+3. Extract path component (e.g., "infra/platform/auth-service.git" → "infra/platform/auth-service")
+4. Match against synced projects
+5. If exactly one match, use as implicit -p
+6. If ambiguous or no match, do nothing (fall through to normal behavior)
+```
+
+Precedence: CLI flag > env var > `lore use` > config default > git detection > (no filter).
+
+This is similar to how `gh` (GitHub CLI) auto-detects the repo you're in.
+
+### 7. Prompt Integration / Shell Function
+
+Provide a shell function that shows the current project context in the prompt.
+
+```bash
+# In .bashrc / .zshrc
+eval "$(lore completions zsh)"
+PROMPT='$(lore-prompt)%~ %# '
+```
+
+Output: `[lore:auth] ~/code/auth-service %`
+
+Shows which project `lore` commands will scope to, using the same precedence chain.
+Helps users understand what context they're in before running a query.
+
+### 8. Short Project References in Output
+
+Once aliases exist, use them everywhere in output for brevity:
+
+**Before:**
+```
+infra/platform/auth-service#42  Login timeout bug
+infra/platform/auth-service!234 Refactor auth middleware
+```
+
+**After:**
+```
+auth#42   Login timeout bug
+auth!234  Refactor auth middleware
+```
+
+With `--full-paths` flag to get the verbose form when needed.
+
+## Combined UX Flow
+
+With all improvements, a typical session looks like:
+
+```bash
+# One-time config
+lore init   # sets up aliases during interactive setup
+
+# Daily use
+lore use auth                              # set context
+lore issues --state opened                 # no -p needed
+lore search "timeout"                      # scoped to auth
+lore timeline "login flow"                 # scoped to auth
+lore issues -p @backend                    # cross-repo query via group
+lore mrs -p billing                        # quick alias switch
+lore use --clear                           # back to global
+```
+
+Or for the power user who never wants to type `lore use`:
+
+```bash
+cd ~/code/auth-service
+lore issues                                # git-aware auto-detection
+```
+
+Or for the scripter:
+
+```bash
+LORE_PROJECT=auth lore --robot issues -n 50  # env var for automation
+```
+
+## Priority Order
+
+Implement in this order for maximum incremental value:
+
+1. **Project aliases** — smallest change, biggest daily friction reduction
+2. **`LORE_PROJECT` env var** — trivial to implement, enables scripting
+3. **`lore projects` command** — discoverability, completes the alias story
+4. **`lore use` context** — nice-to-have for heavy users
+5. **Project groups** — high value for multi-repo teams
+6. **Git-aware detection** — polish, "it just works" feel
+7. **Short refs in output** — ties into timeline issue #001
+8. **Prompt integration** — extra polish
+
+## Relationship to Issue #001
+
+The timeline entity-ref ambiguity (issue #001) is solved naturally by items 7 and 8
+here. Once aliases exist, `format_entity_ref` can use the alias as the short project
+identifier in multi-project output:
+
+```
+auth#42    instead of    infra/platform/auth-service#42
+```
+
+And in single-project timelines (detected via `lore use` or git-aware), the project
+prefix is omitted entirely — matching the current behavior but now intentionally.

docs/ideas/recurring-patterns.md

@@ -0,0 +1,81 @@
+# Recurring Bug Pattern Detector
+
+- **Command:** `lore recurring-patterns [--min-cluster <N>]`
+- **Confidence:** 76%
+- **Tier:** 3
+- **Status:** proposed
+- **Effort:** high — vector clustering, threshold tuning
+
+## What
+
+Cluster closed issues by embedding similarity. Identify clusters of 3+ issues that
+are semantically similar — these represent recurring problems that need a systemic
+fix rather than one-off patches.
+
+## Why
+
+Finding the same bug filed 5 different ways is one of the most impactful things you
+can surface. This is a sophisticated use of the embedding pipeline that no competing
+tool offers. It turns "we keep having auth issues" from a gut feeling into data.
+
+## Data Required
+
+All exists today:
+- `documents` (source_type='issue', content_text)
+- `embeddings` (768-dim vectors)
+- `issues` (state='closed' for filtering)
+
+## Implementation Sketch
+
+```
+1. Collect all embeddings for closed issue documents
+2. For each issue, find K nearest neighbors (K=10)
+3. Build adjacency graph: edge exists if similarity > threshold (e.g., 0.80)
+4. Find connected components (simple DFS/BFS)
+5. Filter to components with >= min-cluster members (default 3)
+6. For each cluster:
+   a. Extract common terms (TF-IDF or simple word frequency)
+   b. Sort by recency (most recent issue first)
+   c. Report cluster with: theme, member issues, time span
+```
+
+### Similarity Threshold Tuning
+
+This is the critical parameter. Too low = noise, too high = misses.
+- Start at 0.80 cosine similarity
+- Expose as `--threshold` flag for user tuning
+- Report cluster cohesion score for transparency
+
+## Human Output
+
+```
+Recurring Patterns (3+ similar closed issues)
+
+Cluster 1: "Authentication timeout errors" (5 issues, spanning 6 months)
+  #89  Login timeout on slow networks           (closed 3d ago)
+  #72  Auth flow hangs on cellular               (closed 2mo ago)
+  #58  Token refresh timeout                     (closed 3mo ago)
+  #45  SSO login timeout for remote users        (closed 5mo ago)
+  #31  Connection timeout in auth middleware      (closed 6mo ago)
+  Avg similarity: 0.87 | Suggested: systemic fix for auth timeout handling
+
+Cluster 2: "Cache invalidation issues" (3 issues, spanning 2 months)
+  #85  Stale cache after deploy                  (closed 2w ago)
+  #77  Cache headers not updated                 (closed 1mo ago)
+  #69  Dashboard shows old data after settings change (closed 2mo ago)
+  Avg similarity: 0.82 | Suggested: review cache invalidation strategy
+```
+
+## Downsides
+
+- Clustering quality depends on embedding quality and threshold tuning
+- May produce false clusters (issues that mention similar terms but are different problems)
+- Computationally expensive for large issue counts (N^2 comparisons)
+- Need to handle multi-chunk documents (aggregate embeddings)
+
+## Extensions
+
+- `lore recurring-patterns --open` — find clusters in open issues (duplicates to merge)
+- `lore recurring-patterns --cross-project` — patterns across repos
+- Trend detection: are cluster sizes growing? (escalating problem)
+- Export as report for engineering retrospectives

docs/ideas/review-coverage.md

@@ -0,0 +1,78 @@
+# DiffNote Coverage Map
+
+- **Command:** `lore review-coverage <mr-iid>`
+- **Confidence:** 75%
+- **Tier:** 3
+- **Status:** proposed
+- **Effort:** medium — join DiffNote positions with mr_file_changes
+
+## What
+
+For a specific MR, show which files received review comments (DiffNotes) vs. which
+files were changed but received no review attention. Highlights blind spots in code
+review.
+
+## Why
+
+Large MRs often have files that get reviewed thoroughly and files that slip through
+with no comments. This makes the review coverage visible so teams can decide if
+un-reviewed files need a second look.
+
+## Data Required
+
+All exists today:
+- `mr_file_changes` (new_path per MR)
+- `notes` (position_new_path, note_type='DiffNote', discussion_id)
+- `discussions` (merge_request_id)
+
+## Implementation Sketch
+
+```sql
+SELECT
+    mfc.new_path,
+    mfc.change_type,
+    COUNT(DISTINCT n.id) as review_comments,
+    COUNT(DISTINCT d.id) as review_threads,
+    CASE WHEN COUNT(n.id) = 0 THEN 'NOT REVIEWED' ELSE 'REVIEWED' END as status
+FROM mr_file_changes mfc
+LEFT JOIN notes n ON n.position_new_path = mfc.new_path
+    AND n.note_type = 'DiffNote'
+    AND n.is_system = 0
+LEFT JOIN discussions d ON n.discussion_id = d.id
+    AND d.merge_request_id = mfc.merge_request_id
+WHERE mfc.merge_request_id = ?1
+GROUP BY mfc.new_path
+ORDER BY review_comments DESC;
+```
+
+## Human Output
+
+```
+Review Coverage for !234 — Refactor auth middleware
+
+  REVIEWED (5 files, 23 comments)
+    src/auth/middleware.rs        12 comments, 4 threads
+    src/auth/jwt.rs               6 comments, 2 threads
+    src/auth/session.rs           3 comments, 1 thread
+    tests/auth/middleware_test.rs  1 comment, 1 thread
+    src/auth/mod.rs               1 comment, 1 thread
+
+  NOT REVIEWED (3 files)
+    src/auth/types.rs             modified    [no review comments]
+    src/api/routes.rs             modified    [no review comments]
+    Cargo.toml                    modified    [no review comments]
+
+  Coverage: 5/8 files (62.5%)
+```
+
+## Downsides
+
+- Reviewers may have reviewed a file without leaving comments (approval by silence)
+- position_new_path matching may not cover all DiffNote position formats
+- Config files (Cargo.toml) not being reviewed is usually fine
+
+## Extensions
+
+- `lore review-coverage --all --since 30d` — aggregate coverage across all MRs
+- Per-reviewer breakdown: which reviewers cover which files?
+- Coverage heatmap: files that consistently escape review across multiple MRs

docs/ideas/silos.md

@@ -0,0 +1,90 @@
+# Knowledge Silo Detection
+
+- **Command:** `lore silos [--min-changes <N>]`
+- **Confidence:** 87%
+- **Tier:** 2
+- **Status:** proposed
+- **Effort:** medium — requires mr_file_changes population (Gate 4)
+
+## What
+
+For each file path (or directory), count unique MR authors. Flag paths where only
+1 person has ever authored changes (bus factor = 1). Aggregate by directory to show
+silo areas.
+
+## Why
+
+Bus factor analysis is critical for team resilience. If only one person has ever
+touched the auth module, that's a risk. This uses data already ingested to surface
+knowledge concentration that's otherwise invisible.
+
+## Data Required
+
+- `mr_file_changes` (new_path, merge_request_id) — needs Gate 4 ingestion
+- `merge_requests` (author_username, state='merged')
+- `projects` (path_with_namespace)
+
+## Implementation Sketch
+
+```sql
+-- Find directories with bus factor = 1
+WITH file_authors AS (
+    SELECT
+        mfc.new_path,
+        mr.author_username,
+        p.path_with_namespace,
+        mfc.project_id
+    FROM mr_file_changes mfc
+    JOIN merge_requests mr ON mfc.merge_request_id = mr.id
+    JOIN projects p ON mfc.project_id = p.id
+    WHERE mr.state = 'merged'
+),
+directory_authors AS (
+    SELECT
+        project_id,
+        path_with_namespace,
+        -- Extract directory: everything before last '/'
+        CASE
+            WHEN INSTR(new_path, '/') > 0
+            THEN SUBSTR(new_path, 1, LENGTH(new_path) - LENGTH(REPLACE(RTRIM(new_path, REPLACE(new_path, '/', '')), '', '')))
+            ELSE '.'
+        END as directory,
+        COUNT(DISTINCT author_username) as unique_authors,
+        COUNT(*) as total_changes,
+        GROUP_CONCAT(DISTINCT author_username) as authors
+    FROM file_authors
+    GROUP BY project_id, directory
+)
+SELECT * FROM directory_authors
+WHERE unique_authors = 1
+  AND total_changes >= ?1  -- min-changes threshold
+ORDER BY total_changes DESC;
+```
+
+## Human Output
+
+```
+Knowledge Silos (bus factor = 1, min 3 changes)
+
+group/backend
+  src/auth/         alice (8 changes)    HIGH RISK
+  src/billing/      bob (5 changes)      HIGH RISK
+  src/utils/cache/  charlie (3 changes)  MODERATE RISK
+
+group/frontend
+  src/admin/        dave (12 changes)    HIGH RISK
+```
+
+## Downsides
+
+- Historical authors may have left the team; needs recency weighting
+- Requires `mr_file_changes` to be populated (Gate 4)
+- Single-author directories may be intentional (ownership model)
+- Directory aggregation heuristic is imperfect for deep nesting
+
+## Extensions
+
+- `lore silos --since 180d` — only count recent activity
+- `lore silos --depth 2` — aggregate at directory depth N
+- Combine with `lore experts` to show both silos and experts in one view
+- Risk scoring: weight by directory size, change frequency, recency

docs/ideas/similar-issues.md

@@ -0,0 +1,95 @@
+# Similar Issues Finder
+
+- **Command:** `lore similar <iid>`
+- **Confidence:** 95%
+- **Tier:** 1
+- **Status:** proposed
+- **Effort:** low — infrastructure exists, needs one new query path
+
+## What
+
+Given an issue IID, find the N most semantically similar issues using the existing
+vector embeddings. Show similarity score and overlapping keywords.
+
+Can also work with MRs: `lore similar --mr <iid>`.
+
+## Why
+
+Duplicate detection is a constant problem on active projects. "Is this bug already
+filed?" becomes a one-liner. This is the most natural use of the embedding pipeline
+and the feature people expect when they hear "semantic search."
+
+## Data Required
+
+All exists today:
+- `documents` table (source_type, source_id, content_text)
+- `embeddings` virtual table (768-dim vectors via sqlite-vec)
+- `embedding_metadata` (document_hash for staleness check)
+
+## Implementation Sketch
+
+```
+1. Resolve IID → issue.id → document.id (via source_type='issue', source_id)
+2. Look up embedding vector(s) for that document
+3. Query sqlite-vec for K nearest neighbors (K = limit * 2 for headroom)
+4. Filter to source_type='issue' (or 'merge_request' if --include-mrs)
+5. Exclude self
+6. Rank by cosine similarity
+7. Return top N with: iid, title, project, similarity_score, url
+```
+
+### SQL Core
+
+```sql
+-- Get the embedding for target document (chunk 0 = representative)
+SELECT embedding FROM embeddings WHERE rowid = ?1 * 1000;
+
+-- Find nearest neighbors
+SELECT
+    rowid,
+    distance
+FROM embeddings
+WHERE embedding MATCH ?1
+    AND k = ?2
+ORDER BY distance;
+
+-- Resolve back to entities
+SELECT d.source_type, d.source_id, d.title, d.url, i.iid, i.state
+FROM documents d
+JOIN issues i ON d.source_id = i.id AND d.source_type = 'issue'
+WHERE d.id = ?;
+```
+
+## Robot Mode Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "query_issue": { "iid": 42, "title": "Login timeout on slow networks" },
+    "similar": [
+      {
+        "iid": 38,
+        "title": "Connection timeout in auth flow",
+        "project": "group/backend",
+        "similarity": 0.87,
+        "state": "closed",
+        "url": "https://gitlab.com/group/backend/-/issues/38"
+      }
+    ]
+  },
+  "meta": { "elapsed_ms": 45, "candidates_scanned": 200 }
+}
+```
+
+## Downsides
+
+- Embedding quality depends on description quality; short issues may not match well
+- Multi-chunk documents need aggregation strategy (use chunk 0 or average?)
+- Requires embeddings to be generated first (`lore embed`)
+
+## Extensions
+
+- `lore similar --open-only` to filter to unresolved issues (duplicate triage)
+- `lore similar --text "free text query"` to find issues similar to arbitrary text
+- Batch mode: find all potential duplicate clusters across the entire database

docs/ideas/stale-discussions.md

@@ -0,0 +1,100 @@
+# Stale Discussion Finder
+
+- **Command:** `lore stale-discussions [--days <N>]`
+- **Confidence:** 90%
+- **Tier:** 1
+- **Status:** proposed
+- **Effort:** low — single query, minimal formatting
+
+## What
+
+List unresolved, resolvable discussions where `last_note_at` is older than a
+threshold (default 14 days), grouped by parent entity. Prioritize by discussion
+count per entity (more stale threads = more urgent).
+
+## Why
+
+Unresolved discussions are silent blockers. They prevent MR merges, stall
+decision-making, and represent forgotten conversations. This surfaces them so teams
+can take action: resolve, respond, or explicitly mark as won't-fix.
+
+## Data Required
+
+All exists today:
+- `discussions` (resolved, resolvable, last_note_at)
+- `issues` / `merge_requests` (for parent entity context)
+
+## Implementation Sketch
+
+```sql
+SELECT
+    d.id,
+    d.noteable_type,
+    CASE WHEN d.issue_id IS NOT NULL THEN i.iid ELSE mr.iid END as entity_iid,
+    CASE WHEN d.issue_id IS NOT NULL THEN i.title ELSE mr.title END as entity_title,
+    p.path_with_namespace,
+    d.last_note_at,
+    ((?1 - d.last_note_at) / 86400000) as days_stale,
+    COUNT(*) OVER (PARTITION BY COALESCE(d.issue_id, d.merge_request_id), d.noteable_type) as stale_count_for_entity
+FROM discussions d
+JOIN projects p ON d.project_id = p.id
+LEFT JOIN issues i ON d.issue_id = i.id
+LEFT JOIN merge_requests mr ON d.merge_request_id = mr.id
+WHERE d.resolved = 0
+  AND d.resolvable = 1
+  AND d.last_note_at < ?1
+ORDER BY days_stale DESC;
+```
+
+## Human Output Format
+
+```
+Stale Discussions (14+ days without activity)
+
+group/backend !234 — Refactor auth middleware (3 stale threads)
+  Discussion #a1b2c3  (28d stale)  "Should we use JWT or session tokens?"
+  Discussion #d4e5f6  (21d stale)  "Error handling for expired tokens"
+  Discussion #g7h8i9  (14d stale)  "Performance implications of per-request validation"
+
+group/backend #90 — Rate limiting design (1 stale thread)
+  Discussion #j0k1l2  (18d stale)  "Redis vs in-memory rate counter"
+```
+
+## Robot Mode Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "threshold_days": 14,
+    "total_stale": 4,
+    "entities": [
+      {
+        "type": "merge_request",
+        "iid": 234,
+        "title": "Refactor auth middleware",
+        "project": "group/backend",
+        "stale_discussions": [
+          {
+            "discussion_id": "a1b2c3",
+            "days_stale": 28,
+            "first_note_preview": "Should we use JWT or session tokens?"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Downsides
+
+- Some discussions are intentionally left open (design docs, long-running threads)
+- Could produce noise in repos with loose discussion hygiene
+- Doesn't distinguish "stale and blocking" from "stale and irrelevant"
+
+## Extensions
+
+- `lore stale-discussions --mr-only` — focus on MR review threads (most actionable)
+- `lore stale-discussions --author alice` — "threads I started that went quiet"
+- `lore stale-discussions --assignee bob` — "threads on my MRs that need attention"

docs/ideas/unlinked.md

@@ -0,0 +1,82 @@
+# Unlinked MR Finder
+
+- **Command:** `lore unlinked [--since <date>]`
+- **Confidence:** 83%
+- **Tier:** 2
+- **Status:** proposed
+- **Effort:** low — LEFT JOIN queries
+
+## What
+
+Two reports:
+1. Merged MRs with no entity_references at all (no "closes", no "mentioned",
+   no "related") — orphan MRs with no issue traceability
+2. Closed issues with no MR reference — issues closed manually without code change
+
+## Why
+
+Process compliance metric. Unlinked MRs mean lost traceability — you can't trace
+a code change back to a requirement. Manually closed issues might mean work was done
+outside the tracked process, or issues were closed prematurely.
+
+## Data Required
+
+All exists today:
+- `merge_requests` (state, merged_at)
+- `issues` (state, closed/updated_at)
+- `entity_references` (for join/anti-join)
+
+## Implementation Sketch
+
+```sql
+-- Orphan merged MRs (no references at all)
+SELECT mr.iid, mr.title, mr.author_username, mr.merged_at,
+       p.path_with_namespace
+FROM merge_requests mr
+JOIN projects p ON mr.project_id = p.id
+LEFT JOIN entity_references er
+    ON er.source_entity_type = 'merge_request' AND er.source_entity_id = mr.id
+WHERE mr.state = 'merged'
+  AND mr.merged_at >= ?1
+  AND er.id IS NULL
+ORDER BY mr.merged_at DESC;
+
+-- Closed issues with no MR reference
+SELECT i.iid, i.title, i.author_username, i.updated_at,
+       p.path_with_namespace
+FROM issues i
+JOIN projects p ON i.project_id = p.id
+LEFT JOIN entity_references er
+    ON er.target_entity_type = 'issue' AND er.target_entity_id = i.id
+    AND er.source_entity_type = 'merge_request'
+WHERE i.state = 'closed'
+  AND i.updated_at >= ?1
+  AND er.id IS NULL
+ORDER BY i.updated_at DESC;
+```
+
+## Human Output
+
+```
+Unlinked MRs (merged with no issue reference, last 30 days)
+
+  !245  Fix typo in README              (alice, merged 2d ago)
+  !239  Update CI pipeline              (bob, merged 1w ago)
+  !236  Bump dependency versions         (charlie, merged 2w ago)
+
+Orphan Closed Issues (closed without any MR, last 30 days)
+
+  #92   Update documentation for v2      (closed by dave, 3d ago)
+  #88   Investigate memory usage          (closed by eve, 2w ago)
+```
+
+## Downsides
+
+- Some MRs legitimately don't reference issues (chores, CI fixes, dependency bumps)
+- Some issues are legitimately closed without code (questions, duplicates, won't-fix)
+- Noise level depends on team discipline
+
+## Extensions
+
+- `lore unlinked --ignore-labels "chore,ci"` — filter out expected orphans
+- Compliance score: % of MRs with issue links over time (trend metric)

docs/ideas/weekly-digest.md

@@ -0,0 +1,102 @@
+# Weekly Digest Generator
+
+- **Command:** `lore weekly [--since <date>]`
+- **Confidence:** 90%
+- **Tier:** 1
+- **Status:** proposed
+- **Effort:** medium — builds on digest infrastructure, adds markdown formatting
+
+## What
+
+Auto-generate a markdown document summarizing the week: MRs merged (grouped by
+project), issues closed, new issues opened, ongoing discussions, milestone progress.
+Formatted for pasting into Slack, email, or team standup notes.
+
+Default window is 7 days. `--since` overrides.
+
+## Why
+
+Every team lead writes a weekly status update. This writes itself from the data.
+Leverages everything gitlore has ingested. Saves 30-60 minutes of manual summarization
+per week.
+
+## Data Required
+
+Same as digest (all exists today):
+- `resource_state_events`, `merge_requests`, `issues`, `discussions`
+- `milestones` for progress tracking
+
+## Implementation Sketch
+
+This is essentially `lore digest --since 7d --format markdown` with:
+1. Section headers for each category
+2. Milestone progress bars (X/Y issues closed)
+3. "Highlights" section with the most-discussed items
+4. "Risks" section with overdue issues and stale MRs
+
+### Markdown Template
+
+```markdown
+# Weekly Summary — Jan 20-27, 2025
+
+## Highlights
+- **!234** Refactor auth middleware merged (12 discussions, 4 reviewers)
+- **#95** New critical bug: Rate limiting returns 500
+
+## Merged (3)
+| MR | Title | Author | Reviewers |
+|----|-------|--------|-----------|
+| !234 | Refactor auth middleware | alice | bob, charlie |
+| !231 | Fix connection pool leak | bob | alice |
+| !45 | Update dashboard layout | eve | dave |
+
+## Closed Issues (2)
+- **#89** Login timeout on slow networks (closed by alice)
+- **#87** Stale cache headers (closed by bob)
+
+## New Issues (3)
+- **#95** Rate limiting returns 500 (priority::high, assigned to charlie)
+- **#94** Add rate limit documentation (priority::low)
+- **#93** Flaky test in CI pipeline (assigned to dave)
+
+## Milestone Progress
+- **v2.0** — 14/20 issues closed (70%) — due Feb 15
+- **v1.9-hotfix** — 3/3 issues closed (100%) — COMPLETE
+
+## Active Discussions
+- **#90** 8 new comments this week (needs-review)
+- **!230** 5 review threads unresolved
+```
+
+## Robot Mode Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "period": { "from": "2025-01-20", "to": "2025-01-27" },
+    "merged_count": 3,
+    "closed_count": 2,
+    "opened_count": 3,
+    "highlights": [...],
+    "merged": [...],
+    "closed": [...],
+    "opened": [...],
+    "milestones": [...],
+    "active_discussions": [...]
+  }
+}
+```
+
+## Downsides
+
+- Formatting preferences vary by team; hard to please everyone
+- "Highlights" ranking is heuristic (discussion count as proxy for importance)
+- Doesn't capture work done outside GitLab
+
+## Extensions
+
+- `lore weekly --project group/backend` — single project scope
+- `lore weekly --author alice` — personal weekly summary
+- `lore weekly --output weekly.md` — write to file
+- Scheduled generation via cron + robot mode

docs/issues/001-timeline-missing-project-in-entity-ref.md

@@ -0,0 +1,140 @@
+# 001: Timeline human output omits project path from entity references
+
+- **Severity:** medium
+- **Component:** `src/cli/commands/timeline.rs`
+- **Status:** open
+
+## Problem
+
+The `lore timeline` human-readable output renders entity references as bare `#42` or
+`!234` without the project path. When multiple projects are synced, this makes the
+output ambiguous — issue `#42` in `group/backend` and `#42` in `group/frontend` are
+indistinguishable.
+
+### Affected code
+
+`format_entity_ref` at `src/cli/commands/timeline.rs:201-207`:
+
+```rust
+fn format_entity_ref(entity_type: &str, iid: i64) -> String {
+    match entity_type {
+        "issue" => format!("#{iid}"),
+        "merge_request" => format!("!{iid}"),
+        _ => format!("{entity_type}:{iid}"),
+    }
+}
+```
+
+This function is called in three places:
+
+1. **Event lines** (`print_timeline_event`, line 130) — each event row shows `#42`
+   with no project context
+2. **Footer seed list** (`print_timeline_footer`, line 161) — seed entities listed as
+   `#42, !234` with no project disambiguation
+3. **Collect stage summaries** (`timeline_collect.rs:107`) — the `summary` field itself
+   bakes in `"Issue #42 created: ..."` without project
+
+### Current output (ambiguous)
+
+```
+2025-01-20  CREATED       #42      Issue #42 created: Login timeout bug        @alice
+2025-01-21  LABEL+        #42      Label added: priority::high                 @dave
+2025-01-22  CREATED       !234     MR !234 created: Refactor auth middleware   @alice
+2025-01-25  MERGED        !234     MR !234 merged                              @bob
+
+  Seed entities: #42, !234
+```
+
+When multiple projects are synced, a reader cannot tell which project `#42` belongs to.
+
+## Robot mode is partially affected
+
+The robot JSON output (`EventJson`, line 387-416) DOES include a `project` field per
+event, so programmatic consumers can disambiguate. However, the `summary` string field
+still bakes in bare `#42` without project context, which is misleading if an agent uses
+the summary for display.
+
+## Proposed fix
+
+### 1. Add project to `format_entity_ref`
+
+Pass `project_path` into `format_entity_ref` and use GitLab's full reference format:
+
+```rust
+fn format_entity_ref(entity_type: &str, iid: i64, project_path: &str) -> String {
+    match entity_type {
+        "issue" => format!("{project_path}#{iid}"),
+        "merge_request" => format!("{project_path}!{iid}"),
+        _ => format!("{project_path}/{entity_type}:{iid}"),
+    }
+}
+```
+
+### 2. Smart elision for single-project timelines
+
+When all events belong to the same project, the full path is visual noise. Detect
+this and fall back to bare `#42` / `!234`:
+
+```rust
+fn should_show_project(events: &[TimelineEvent]) -> bool {
+    let mut projects = events.iter().map(|e| &e.project_path).collect::<HashSet<_>>();
+    projects.len() > 1
+}
+```
+
+Then conditionally format:
+
+```rust
+let entity_ref = if show_project {
+    format_entity_ref(&event.entity_type, event.entity_iid, &event.project_path)
+} else {
+    format_entity_ref_short(&event.entity_type, event.entity_iid)
+};
+```
+
+### 3. Fix summary strings in collect stage
+
+`timeline_collect.rs:107` bakes the summary as `"Issue #42 created: title"`. This
+should include the project when multi-project:
+
+```rust
+let prefix = if multi_project {
+    format!("{type_label} {project_path}#{iid}")
+} else {
+    format!("{type_label} #{iid}")
+};
+summary = format!("{prefix} created: {title_str}");
+```
+
+Same pattern for the merge summary at lines 317 and 347.
+
+### 4. Update footer seed list
+
+`print_timeline_footer` (line 155-164) should also use the project-aware format:
+
+```rust
+result.seed_entities.iter()
+    .map(|e| format_entity_ref(&e.entity_type, e.entity_iid, &e.project_path))
+```
+
+## Expected output after fix
+
+### Single project (no change)
+
+```
+2025-01-20  CREATED       #42      Issue #42 created: Login timeout bug        @alice
+```
+
+### Multi-project (project path added)
+
+```
+2025-01-20  CREATED   group/backend#42   Issue group/backend#42 created: Login timeout  @alice
+2025-01-22  CREATED   group/frontend#42  Issue group/frontend#42 created: Broken layout @eve
+```
+
+## Impact
+
+- Human output: ambiguous for multi-project users (the primary use case for gitlore)
+- Robot output: summary field misleading, but `project` field provides workaround
+- Timeline footer: seed entity list ambiguous
+- Collect-stage summaries: baked-in bare references propagate to both renderers

docs/performance-audit-2026-02-12.md

@@ -0,0 +1,179 @@
+# Deep Performance Audit Report
+
+**Date:** 2026-02-12
+**Branch:** `perf-audit` (e9bacc94)
+**Parent:** `039ab1c2` (master, v0.6.1)
+
+---
+
+## Methodology
+
+1. **Baseline** — measured p50/p95 latency for all major commands with warm cache
+2. **Profile** — used macOS `sample` profiler and `EXPLAIN QUERY PLAN` to identify hotspots
+3. **Golden output** — captured exact numeric outputs before changes as equivalence oracle
+4. **One lever per change** — each optimization isolated and independently benchmarked
+5. **Revert threshold** — any optimization <1.1x speedup reverted per audit rules
+
+---
+
+## Baseline Measurements (warm cache, release build)
+
+| Command | Latency | Notes |
+|---------|---------|-------|
+| `who --path src/core/db.rs` (expert) | 2200ms | **Hotspot** |
+| `who --active` | 83-93ms | Acceptable |
+| `who workload` | 22ms | Fast |
+| `stats` | 107-112ms | **Hotspot** |
+| `search "authentication"` | 1030ms | **Hotspot** (library-level) |
+| `list issues -n 50` | ~40ms | Fast |
+
+---
+
+## Optimization 1: INDEXED BY for DiffNote Queries
+
+**Target:** `src/cli/commands/who.rs` — expert and reviews query paths
+
+**Problem:** SQLite query planner chose `idx_notes_system` (38% selectivity, 106K rows) over `idx_notes_diffnote_path_created` (9.3% selectivity, 26K rows) for path-filtered DiffNote queries. The partial index `WHERE noteable_type = 'MergeRequest' AND type = 'DiffNote'` is far more selective but the planner's cost model didn't pick it.
+
+**Change:** Added `INDEXED BY idx_notes_diffnote_path_created` to all 8 SQL queries across `query_expert`, `query_expert_details`, `query_reviews`, `build_path_query` (probes 1 & 2), and `suffix_probe`.
+
+**Results:**
+
+| Query | Before | After | Speedup |
+|-------|--------|-------|---------|
+| expert (specific path) | 2200ms | 56-58ms | **38x** |
+| expert (broad path) | 2200ms | 83ms | **26x** |
+| reviews | 1800ms | 24ms | **75x** |
+
+**Isomorphism proof:** `INDEXED BY` only changes which index the planner uses, not the query semantics. Same rows matched, same ordering, same output. Verified by golden output comparison across 5+ runs.
+
+---
+
+## Optimization 2: Conditional Aggregates in Stats
+
+**Target:** `src/cli/commands/stats.rs`
+
+**Problem:** 12+ sequential `COUNT(*)` queries each requiring a full table scan of `documents` (61K rows). Each scan touched the same pages but couldn't share work.
+
+**Changes:**
+- Documents: 5 sequential COUNTs -> 1 query with `SUM(CASE WHEN ... THEN 1 END)`
+- FTS count: `SELECT COUNT(*) FROM documents_fts` (virtual table, slow) -> `SELECT COUNT(*) FROM documents_fts_docsize` (shadow B-tree table, 19x faster)
+- Embeddings: 2 queries -> 1 with `COUNT(DISTINCT document_id), COUNT(*)`
+- Dirty sources: 2 queries -> 1 with conditional aggregates
+- Pending fetches: 2 queries -> 1 each (discussions, dependents)
+
+**Results:**
+
+| Metric | Before | After | Speedup |
+|--------|--------|-------|---------|
+| Warm median | 112ms | 66ms | **1.70x** |
+| Cold | 1220ms | ~700ms | ~1.7x |
+
+**Golden output verified:**
+
+```
+total:61652, issues:8241, mrs:10018, discussions:43393, truncated:63
+fts:61652, embedded:61652, chunks:88161
+```
+
+All values match exactly across before/after runs.
+
+**Isomorphism proof:** `SUM(CASE WHEN x THEN 1 END)` is algebraically identical to `COUNT(*) WHERE x`. The FTS5 shadow table `documents_fts_docsize` has exactly one row per FTS document by SQLite specification, so `COUNT(*)` on it equals the virtual table count.
+
+---
+
+## Investigation: Two-Phase FTS Search (REVERTED)
+
+**Target:** `src/search/fts.rs`, `src/cli/commands/search.rs`
+
+**Hypothesis:** FTS5 `snippet()` generation is expensive. Splitting search into Phase 1 (score-only MATCH+bm25) and Phase 2 (snippet for filtered results only) should reduce work.
+
+**Implementation:** Created `fetch_fts_snippets()` that retrieves snippets only for post-filter document IDs via `json_each()` join.
+
+**Results:**
+
+| Metric | Before | After | Improvement |
+|--------|--------|-------|-------------|
+| search (limit 20) | 1030ms | 995ms | 3.5% |
+
+**Decision:** Reverted. Per audit rules, <1.1x speedup does not justify added code complexity.
+
+**Root cause:** The bottleneck is not snippet generation but `MATCH` + `bm25()` scoring itself. Profiling showed `strspn` (FTS5 tokenizer) and `memmove` as the top CPU consumers. The same query runs in 30ms on system sqlite3 but 1030ms in rusqlite's bundled SQLite — a ~125x gap despite both being SQLite 3.51.x compiled at -O3.
+
+---
+
+## Library-Level Finding: Bundled SQLite FTS5 Performance
+
+**Observation:** FTS5 MATCH+bm25 queries are ~125x slower in rusqlite's bundled SQLite vs system sqlite3.
+
+| Environment | Query Time | Notes |
+|-------------|-----------|-------|
+| System sqlite3 (macOS) | 30ms (with snippet), 8ms (without) | Same .db file |
+| rusqlite bundled | 1030ms | `features = ["bundled"]`, OPT_LEVEL=3 |
+
+**Profiler data (macOS `sample`):**
+- Top hotspot: `strspn` in FTS5 tokenizer
+- Secondary: `memmove` in FTS5 internals
+- Scaling: ~5ms per result (limit 5 = 497ms, limit 20 = 995ms)
+
+**Possible causes:**
+- Bundled SQLite compiled without platform-specific optimizations (SIMD, etc.)
+- Different memory allocator behavior
+- Missing compile-time tuning flags
+
+**Recommendation for future:** Investigate switching from `features = ["bundled"]` to system SQLite linkage, or audit the bundled compile flags in the `libsqlite3-sys` build script.
+
+---
+
+## Exploration Agent Findings (Informational)
+
+Four parallel exploration agents surveyed the entire codebase. Key findings beyond what was already addressed:
+
+### Ingestion Pipeline
+- Serial DB writes in async context (acceptable — rusqlite is synchronous)
+- Label ingestion uses individual inserts (potential batch optimization, low priority)
+
+### CLI / GitLab Client
+- GraphQL client recreated per call (`client.rs:98-100`) — caches connection pool, minor
+- Double JSON deserialization in GraphQL responses — medium priority
+- N+1 subqueries in `list` command (`list.rs:408-423`) — 4 correlated subqueries per row
+
+### Search / Embedding
+- No N+1 patterns, no O(n^2) algorithms
+- Chunking is O(n) single-pass with proper UTF-8 safety
+- Ollama concurrency model is sound (parallel HTTP, serial DB writes)
+
+### Database / Documents
+- O(n^2) prefix sum in `truncation.rs` — low traffic path
+- String allocation patterns in extractors — micro-optimization territory
+
+---
+
+## Opportunity Matrix
+
+| Candidate | Impact | Confidence | Effort | Score | Status |
+|-----------|--------|------------|--------|-------|--------|
+| INDEXED BY for DiffNote | Very High | High | Low | **9.0** | Shipped |
+| Stats conditional aggregates | Medium | High | Low | **7.0** | Shipped |
+| Bundled SQLite FTS5 | Very High | Medium | High | 5.0 | Documented |
+| List N+1 subqueries | Medium | Medium | Medium | 4.0 | Backlog |
+| GraphQL double deser | Low | Medium | Low | 3.5 | Backlog |
+| Truncation O(n^2) | Low | High | Low | 3.0 | Backlog |
+
+---
+
+## Files Modified
+
+| File | Change |
+|------|--------|
+| `src/cli/commands/who.rs` | INDEXED BY hints on 8 SQL queries |
+| `src/cli/commands/stats.rs` | Conditional aggregates, FTS5 shadow table, merged queries |
+
+---
+
+## Quality Gates
+
+- All 603 tests pass
+- `cargo clippy --all-targets -- -D warnings` clean
+- `cargo fmt --check` clean
+- Golden output verified for both optimizations

docs/phase-b-temporal-intelligence.md

@@ -39,7 +39,7 @@ Five gates, each independently verifiable and shippable:
 - **Opt-in event ingestion.** New config flag `sync.fetchResourceEvents` (default `true`) controls whether the sync pipeline fetches event data. Users who don't need temporal features skip the additional API calls.
 - **Application-level graph traversal.** Cross-reference expansion uses BFS in Rust, not recursive SQL CTEs. Capped at configurable depth (default 1) for predictable performance.
 - **Evolutionary library extraction.** New commands are built with typed return structs from day one. Old commands are not retrofitted until a concrete consumer (MCP server, web UI) requires it.
-- **Phase A fields cherry-picked as needed.** `merge_commit_sha` and `squash_commit_sha` are added in this phase's migration. Remaining Phase A fields are handled in their own migration later.
+- **Phase A fields cherry-picked as needed.** `merge_commit_sha` and `squash_commit_sha` are added in migration 015 and populated during MR ingestion. Remaining Phase A fields are handled in their own migration later.
 
 ### Scope Boundaries
 
@@ -71,9 +71,9 @@ The original approach was to parse system note body text with regex to extract s
 
 System note parsing is still used for events without structured APIs (see Gate 2), but with the explicit understanding that it's best-effort and fragile for non-English instances.
 
-### 1.2 Schema (Migration 010)
+### 1.2 Schema (Migration 011)
 
-**File:** `migrations/010_resource_events.sql`
+**File:** `migrations/011_resource_events.sql`
 
 ```sql
 -- State change events (opened, closed, reopened, merged, locked)
@@ -89,16 +89,16 @@ CREATE TABLE resource_state_events (
   actor_gitlab_id INTEGER,            -- GitLab user ID (stable; usernames can change)
   actor_username TEXT,                -- display/search convenience
   created_at INTEGER NOT NULL,        -- ms epoch UTC
-  -- "closed by MR" link: structured by GitLab, not parsed from text
-  source_merge_request_id INTEGER,    -- GitLab's MR iid that caused this state change
   source_commit TEXT,                 -- commit SHA that caused this state change
-  UNIQUE(gitlab_id, project_id),
+  source_merge_request_iid INTEGER,   -- iid from source_merge_request ref
   CHECK (
     (issue_id IS NOT NULL AND merge_request_id IS NULL)
     OR (issue_id IS NULL AND merge_request_id IS NOT NULL)
   )
 );
 
+CREATE UNIQUE INDEX uq_state_events_gitlab ON resource_state_events(gitlab_id, project_id);
+
 CREATE INDEX idx_state_events_issue ON resource_state_events(issue_id)
   WHERE issue_id IS NOT NULL;
 CREATE INDEX idx_state_events_mr ON resource_state_events(merge_request_id)
@@ -114,24 +114,25 @@ CREATE TABLE resource_label_events (
   project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
   issue_id INTEGER REFERENCES issues(id) ON DELETE CASCADE,
   merge_request_id INTEGER REFERENCES merge_requests(id) ON DELETE CASCADE,
-  label_name TEXT NOT NULL,
   action TEXT NOT NULL CHECK (action IN ('add', 'remove')),
-  actor_gitlab_id INTEGER,            -- GitLab user ID (stable; usernames can change)
-  actor_username TEXT,                -- display/search convenience
+  label_name TEXT,                    -- nullable: GitLab returns null for deleted labels (see §1.2.1)
+  actor_gitlab_id INTEGER,
+  actor_username TEXT,
   created_at INTEGER NOT NULL,        -- ms epoch UTC
-  UNIQUE(gitlab_id, project_id),
   CHECK (
     (issue_id IS NOT NULL AND merge_request_id IS NULL)
     OR (issue_id IS NULL AND merge_request_id IS NOT NULL)
   )
 );
 
+CREATE UNIQUE INDEX uq_label_events_gitlab ON resource_label_events(gitlab_id, project_id);
+
 CREATE INDEX idx_label_events_issue ON resource_label_events(issue_id)
   WHERE issue_id IS NOT NULL;
 CREATE INDEX idx_label_events_mr ON resource_label_events(merge_request_id)
   WHERE merge_request_id IS NOT NULL;
 CREATE INDEX idx_label_events_created ON resource_label_events(created_at);
-CREATE INDEX idx_label_events_label ON resource_label_events(label_name);
+-- Note: idx_label_events_label was added in migration 015 (not in the original 011)
 
 -- Milestone change events (add, remove)
 -- Source: GET /projects/:id/issues/:iid/resource_milestone_events
@@ -142,19 +143,20 @@ CREATE TABLE resource_milestone_events (
   project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
   issue_id INTEGER REFERENCES issues(id) ON DELETE CASCADE,
   merge_request_id INTEGER REFERENCES merge_requests(id) ON DELETE CASCADE,
-  milestone_title TEXT NOT NULL,
-  milestone_id INTEGER,
   action TEXT NOT NULL CHECK (action IN ('add', 'remove')),
-  actor_gitlab_id INTEGER,            -- GitLab user ID (stable; usernames can change)
-  actor_username TEXT,                -- display/search convenience
+  milestone_title TEXT,               -- nullable: GitLab returns null for deleted milestones (see §1.2.1)
+  milestone_id INTEGER,
+  actor_gitlab_id INTEGER,
+  actor_username TEXT,
   created_at INTEGER NOT NULL,        -- ms epoch UTC
-  UNIQUE(gitlab_id, project_id),
   CHECK (
     (issue_id IS NOT NULL AND merge_request_id IS NULL)
     OR (issue_id IS NULL AND merge_request_id IS NOT NULL)
   )
 );
 
+CREATE UNIQUE INDEX uq_milestone_events_gitlab ON resource_milestone_events(gitlab_id, project_id);
+
 CREATE INDEX idx_milestone_events_issue ON resource_milestone_events(issue_id)
   WHERE issue_id IS NOT NULL;
 CREATE INDEX idx_milestone_events_mr ON resource_milestone_events(merge_request_id)
@@ -162,6 +164,27 @@ CREATE INDEX idx_milestone_events_mr ON resource_milestone_events(merge_request_
 CREATE INDEX idx_milestone_events_created ON resource_milestone_events(created_at);
 ```
 
+#### 1.2.1 Nullable Label and Milestone Fields (Migration 012)
+
+GitLab returns `null` for `label` and `milestone` in Resource Events when the referenced label or milestone has been deleted from the project. This was discovered in production after the initial schema deployed with `NOT NULL` constraints.
+
+**Migration 012** recreates `resource_label_events` and `resource_milestone_events` with nullable `label_name` and `milestone_title` columns. The table-swap approach (create new → copy → drop old → rename) is required because SQLite doesn't support `ALTER COLUMN`.
+
+Timeline queries that encounter null labels/milestones display `"[deleted label]"` or `"[deleted milestone]"` in human output and omit the name field in robot JSON.
+
+#### 1.2.2 Resource Event Watermarks (Migration 013)
+
+To avoid re-fetching resource events for every entity on every sync, a watermark column tracks the `updated_at` value at the time of last successful event fetch:
+
+```sql
+ALTER TABLE issues ADD COLUMN resource_events_synced_for_updated_at INTEGER;
+ALTER TABLE merge_requests ADD COLUMN resource_events_synced_for_updated_at INTEGER;
+```
+
+**Incremental behavior:** During sync, only entities where `updated_at > COALESCE(resource_events_synced_for_updated_at, 0)` are enqueued for resource event fetching. On `--full` sync, these watermarks are reset to `NULL`, causing all entities to be re-enqueued.
+
+This mirrors the existing `discussions_synced_for_updated_at` pattern and works in conjunction with the dependent fetch queue.
+
 ### 1.3 Config Extension
 
 **File:** `src/core/config.rs`
@@ -223,7 +246,7 @@ pub struct GitLabLabelEvent {
     pub created_at: String,
     pub resource_type: String,
     pub resource_id: i64,
-    pub label: GitLabLabelRef,
+    pub label: Option<GitLabLabelRef>,  // nullable: deleted labels return null
     pub action: String,              // "add" | "remove"
 }
 
@@ -234,7 +257,7 @@ pub struct GitLabMilestoneEvent {
     pub created_at: String,
     pub resource_type: String,
     pub resource_id: i64,
-    pub milestone: GitLabMilestoneRef,
+    pub milestone: Option<GitLabMilestoneRef>,  // nullable: deleted milestones return null
     pub action: String,              // "add" | "remove"
 }
 ```
@@ -243,7 +266,7 @@ pub struct GitLabMilestoneEvent {
 
 **Architecture:** Generic dependent-fetch queue, generalizing the `pending_discussion_fetches` pattern. A single queue table serves all dependent resource types across Gates 1, 2, and 4, avoiding schema churn as new fetch types are added.
 
-**New queue table (in migration 010):**
+**New queue table (in migration 011):**
 
 ```sql
 -- Generic queue for all dependent resource fetches (events, closes_issues, diffs)
@@ -302,16 +325,32 @@ Acceptable for initial sync. Incremental sync adds negligible overhead.
 
 ### 1.7 Acceptance Criteria
 
-- [ ] Migration 010 creates all three event tables + generic dependent fetch queue
-- [ ] `lore sync` fetches resource events for changed entities when `fetchResourceEvents` is true
-- [ ] `lore sync --no-events` skips event fetching
-- [ ] Event fetch failures are queued for retry with exponential backoff
-- [ ] Stale locks (crashed sync) automatically reclaimed on next run
-- [ ] `lore count events` shows event counts by type
+- [x] Migration 011 creates all three event tables + generic dependent fetch queue
+- [x] `lore sync` fetches resource events for changed entities when `fetchResourceEvents` is true
+- [x] `lore sync --no-events` skips event fetching
+- [x] Event fetch failures are queued for retry with exponential backoff
+- [x] Stale locks (crashed sync) automatically reclaimed on next run
+- [x] `lore count events` shows event counts by type
 - [ ] `lore stats --check` validates event table referential integrity
 - [ ] `lore stats --check` validates dependent job queue health (no stuck locks, retryable jobs visible)
 - [ ] Robot mode JSON for all new commands
 
+### 1.8 Observability Infrastructure (Migration 014)
+
+The sync pipeline includes lightweight observability via `sync_runs` enrichment. Migration 014 adds:
+
+```sql
+ALTER TABLE sync_runs ADD COLUMN run_id TEXT;                  -- correlation ID for log tracing
+ALTER TABLE sync_runs ADD COLUMN total_items_processed INTEGER DEFAULT 0;
+ALTER TABLE sync_runs ADD COLUMN total_errors INTEGER DEFAULT 0;
+
+CREATE INDEX IF NOT EXISTS idx_sync_runs_run_id ON sync_runs(run_id);
+```
+
+**Purpose:** The `run_id` column correlates log entries (via `tracing`) with sync run records. `total_items_processed` and `total_errors` provide aggregate counts for `lore sync-status` and robot mode health checks without requiring log parsing.
+
+This is separate from the event tables but supports the same operational workflow — answering "did the last sync succeed?" and "how many entities were processed?" programmatically.
+
 ---
 
 ## Gate 2: Cross-Reference Extraction
@@ -320,10 +359,10 @@ Acceptable for initial sync. Incremental sync adds negligible overhead.
 
 Temporal queries need to follow links between entities: "MR !567 closed issue #234", "issue #234 mentioned in MR !567", "#299 was opened as a follow-up to !567". These relationships are captured in two places:
 
-1. **Structured API:** `GET /projects/:id/merge_requests/:iid/closes_issues` returns issues that close when the MR merges. Also, `resource_state_events` includes `source_merge_request_id` for "closed by MR" events.
+1. **Structured API:** `GET /projects/:id/merge_requests/:iid/closes_issues` returns issues that close when the MR merges. Also, `resource_state_events` includes `source_merge_request_iid` for "closed by MR" events.
 2. **System notes:** Cross-references like "mentioned in !456" and "closed by !789" appear in system note body text.
 
-### 2.2 Schema (in Migration 010)
+### 2.2 Schema (in Migration 011)
 
 ```sql
 -- Cross-references between entities
@@ -340,33 +379,49 @@ Temporal queries need to follow links between entities: "MR !567 closed issue #2
 -- silently dropping them. Timeline output marks these as "[external]".
 CREATE TABLE entity_references (
   id INTEGER PRIMARY KEY,
+  project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
   source_entity_type TEXT NOT NULL CHECK (source_entity_type IN ('issue', 'merge_request')),
   source_entity_id INTEGER NOT NULL,   -- local DB id
   target_entity_type TEXT NOT NULL CHECK (target_entity_type IN ('issue', 'merge_request')),
   target_entity_id INTEGER,            -- local DB id (NULL when target is unresolved/external)
   target_project_path TEXT,            -- e.g. "group/other-repo" (populated for cross-project refs)
   target_entity_iid INTEGER,           -- GitLab iid (populated when target_entity_id is NULL)
-  reference_type TEXT NOT NULL,        -- 'closes' | 'mentioned' | 'related'
-  source_method TEXT NOT NULL,         -- 'api_closes_issues' | 'api_state_event' | 'system_note_parse'
-  created_at INTEGER,                  -- when the reference was created (if known)
-  UNIQUE(source_entity_type, source_entity_id, target_entity_type,
-         COALESCE(target_entity_id, -1), COALESCE(target_project_path, ''),
-         COALESCE(target_entity_iid, -1), reference_type)
+  reference_type TEXT NOT NULL CHECK (reference_type IN ('closes', 'mentioned', 'related')),
+  source_method TEXT NOT NULL CHECK (source_method IN ('api', 'note_parse', 'description_parse')),
+  created_at INTEGER NOT NULL          -- ms epoch UTC
 );
 
-CREATE INDEX idx_refs_source ON entity_references(source_entity_type, source_entity_id);
-CREATE INDEX idx_refs_target ON entity_references(target_entity_type, target_entity_id)
+-- Unique constraint includes source_method: the same relationship can be discovered by
+-- multiple methods (e.g., closes_issues API and a state event), and we store both for provenance.
+CREATE UNIQUE INDEX uq_entity_refs ON entity_references(
+  project_id, source_entity_type, source_entity_id, target_entity_type,
+  COALESCE(target_entity_id, -1), COALESCE(target_project_path, ''),
+  COALESCE(target_entity_iid, -1), reference_type, source_method
+);
+
+CREATE INDEX idx_entity_refs_source ON entity_references(source_entity_type, source_entity_id);
+CREATE INDEX idx_entity_refs_target ON entity_references(target_entity_id)
   WHERE target_entity_id IS NOT NULL;
-CREATE INDEX idx_refs_unresolved ON entity_references(target_project_path, target_entity_iid)
+CREATE INDEX idx_entity_refs_unresolved ON entity_references(target_project_path, target_entity_iid)
   WHERE target_entity_id IS NULL;
 ```
 
+**`source_method` values:**
+
+| Value | Meaning |
+|-------|---------|
+| `'api'` | Populated from structured GitLab APIs (`closes_issues`, `resource_state_events`) |
+| `'note_parse'` | Extracted from system note body text (best-effort, English only) |
+| `'description_parse'` | Extracted from issue/MR description body text (future) |
+
+The original design used more granular values (`'api_closes_issues'`, `'api_state_event'`, `'system_note_parse'`). In practice, the API-sourced references don't need sub-method distinction — the `reference_type` already captures the semantic relationship — so the implementation simplified to three values.
+
 ### 2.3 Population Strategy
 
 **Tier 1 — Structured APIs (reliable):**
 
-1. **`closes_issues` endpoint:** After MR ingestion, fetch `GET /projects/:id/merge_requests/:iid/closes_issues`. Insert `reference_type = 'closes'`, `source_method = 'api_closes_issues'`. Source = MR, target = issue.
-2. **State events:** When `resource_state_events` contains `source_merge_request_id`, insert `reference_type = 'closes'`, `source_method = 'api_state_event'`. Source = MR (referenced by iid), target = issue (that received the state change).
+1. **`closes_issues` endpoint:** After MR ingestion, fetch `GET /projects/:id/merge_requests/:iid/closes_issues`. Insert `reference_type = 'closes'`, `source_method = 'api'`. Source = MR, target = issue.
+2. **State events:** When `resource_state_events` contains `source_merge_request_iid`, insert `reference_type = 'closes'`, `source_method = 'api'`. Source = MR (referenced by iid), target = issue (that received the state change).
 
 **Tier 2 — System note parsing (best-effort):**
 
@@ -385,14 +440,14 @@ closed by #{iid}
 
 **Cross-project references:** When a system note references `{group}/{project}#{iid}` and the target project is not synced locally, store with `target_entity_id = NULL`, `target_project_path = '{group}/{project}'`, `target_entity_iid = {iid}`. These unresolved references are still valuable for timeline narratives — they indicate external dependencies and decision context even when we can't traverse further.
 
-Insert with `source_method = 'system_note_parse'`. Accept that:
+Insert with `source_method = 'note_parse'`. Accept that:
 - This breaks on non-English GitLab instances
 - Format may vary across GitLab versions
 - Log parse failures at `debug` level for monitoring
 
-**Tier 3 — Description/body parsing (deferred):**
+**Tier 3 — Description/body parsing (`source_method = 'description_parse'`, deferred):**
 
-Issue and MR descriptions often contain `#123` or `!456` references. Parsing these is lower confidence (mentions != relationships) and is deferred to a future iteration.
+Issue and MR descriptions often contain `#123` or `!456` references. Parsing these is lower confidence (mentions != relationships) and is deferred to a future iteration. The `source_method` value `'description_parse'` is reserved in the CHECK constraint for this future work.
 
 ### 2.4 Ingestion Flow
 
@@ -401,6 +456,8 @@ The `closes_issues` fetch uses the generic dependent fetch queue (`job_type = 'm
 - One additional API call per MR: `GET /projects/:id/merge_requests/:iid/closes_issues`
 - Cross-reference parsing from system notes runs as a local post-processing step (no API calls) after all dependent fetches complete
 
+**Watermark pattern (migration 015):** A `closes_issues_synced_for_updated_at` column on `merge_requests` tracks the last `updated_at` value at which closes_issues data was fetched. Only MRs where `updated_at > COALESCE(closes_issues_synced_for_updated_at, 0)` are enqueued for re-fetching. The watermark is updated after successful fetch or after a permanent API error (e.g., 404 for external MRs). On `--full` sync, the watermark is reset to `NULL`.
+
 ### 2.5 Acceptance Criteria
 
 - [ ] `entity_references` table populated from `closes_issues` API for all synced MRs
@@ -562,7 +619,7 @@ Evidence notes (`NOTE` events) show the first ~200 characters of FTS5-matched no
         "via": {
           "from": { "type": "merge_request", "iid": 567, "project": "group/repo" },
           "reference_type": "closes",
-          "source_method": "api_closes_issues"
+          "source_method": "api"
         }
       }
     ],
@@ -639,9 +696,13 @@ Evidence notes (`NOTE` events) show the first ~200 characters of FTS5-matched no
 
 ## Gate 4: File Decision History (`lore file-history`)
 
-### 4.1 Schema (Migration 011)
+### 4.1 Schema
 
-**File:** `migrations/011_file_changes.sql`
+**Commit SHAs (Migration 015 — already applied):**
+
+`merge_commit_sha` and `squash_commit_sha` were added to `merge_requests` in migration 015. These are now populated during MR ingestion and available for Gate 4/5 queries.
+
+**File changes table (future migration — not yet created):**
 
 ```sql
 -- Files changed by each merge request
@@ -660,11 +721,6 @@ CREATE INDEX idx_mr_files_new_path ON mr_file_changes(new_path);
 CREATE INDEX idx_mr_files_old_path ON mr_file_changes(old_path)
   WHERE old_path IS NOT NULL;
 CREATE INDEX idx_mr_files_mr ON mr_file_changes(merge_request_id);
-
--- Add commit SHAs to merge_requests (cherry-picked from Phase A)
--- These link MRs to actual git history
-ALTER TABLE merge_requests ADD COLUMN merge_commit_sha TEXT;
-ALTER TABLE merge_requests ADD COLUMN squash_commit_sha TEXT;
 ```
 
 ### 4.2 Config Extension
@@ -881,14 +937,16 @@ When git integration is added:
 
 ### Migration Numbering
 
-Phase B uses migration numbers starting at 010:
+Phase B uses migration numbers 011–015. The original plan assumed migration 010 was available, but chunk config (`010_chunk_config.sql`) was implemented first, shifting everything by +1.
 
-| Migration | Content | Gate |
-|-----------|---------|------|
-| 010 | Resource event tables, generic dependent fetch queue, entity_references | Gates 1, 2 |
-| 011 | mr_file_changes, merge_commit_sha, squash_commit_sha | Gate 4 |
-
-Phase A's complete field capture migration should use 012+ when implemented, skipping fields already added by 011 (`merge_commit_sha`, `squash_commit_sha`).
+| Migration | File | Content | Gate |
+|-----------|------|---------|------|
+| 011 | `011_resource_events.sql` | Resource event tables (state, label, milestone), entity_references, generic dependent fetch queue | Gates 1, 2 |
+| 012 | `012_nullable_label_milestone.sql` | Make `label_name` and `milestone_title` nullable for deleted labels/milestones | Gate 1 (fix) |
+| 013 | `013_resource_event_watermarks.sql` | Add `resource_events_synced_for_updated_at` to issues and merge_requests | Gate 1 (optimization) |
+| 014 | `014_sync_runs_enrichment.sql` | Observability: `run_id`, `total_items_processed`, `total_errors` on sync_runs | Observability |
+| 015 | `015_commit_shas_and_closes_watermark.sql` | `merge_commit_sha`, `squash_commit_sha`, `closes_issues_synced_for_updated_at` on merge_requests; `idx_label_events_label` index | Gates 2, 4 |
+| TBD | — | `mr_file_changes` table for MR diff data | Gate 4 |
 
 ### Backward Compatibility
 
@@ -909,7 +967,7 @@ Phase A's complete field capture migration should use 012+ when implemented, ski
 | GitLab diffs API returns large payloads | Low | Extract file metadata only, discard diff content |
 | Cross-reference graph traversal unbounded | Medium | BFS depth capped at configurable limit (default 1); `mentioned` edges excluded by default |
 | Cross-project references lost when target not synced | Medium | Unresolved references stored with `target_entity_id = NULL`; still appear in timeline output |
-| Phase A migration numbering conflict | Low | Phase B uses 010-011; Phase A uses 012+ |
+| Phase A migration numbering conflict | Low | Resolved: chunk config took 010; Phase B shifted to 011-015 |
 | Timeline output lacks "why" evidence | Medium | Evidence-bearing notes from FTS5 included as first-class timeline events |
 | Squash commits break blame-to-MR mapping | Medium | Tier 2 (git integration) deferred; Tier 1 uses file-level MR matching |
 

docs/prd-per-note-search.feedback-1.md

@@ -0,0 +1,174 @@
+Highest-impact gaps I see in the current plan:
+
+1. `for-issue` / `for-mr` filtering is ambiguous across projects and can return incorrect rows.
+2. `lore notes` has no pagination contract, so large exports and deterministic resumption are weak.
+3. Migration `022` is high-risk (table rebuild + FTS + junction tables) without explicit integrity gates.
+4. Note-doc freshness is incomplete for upstream note deletions and parent metadata changes (labels/title).
+
+Below are my best revisions, each with rationale and a git-diff-style plan edit.
+
+---
+
+1. **Add gated rollout + rollback controls**
+Rationale: You can still “ship together” while reducing blast radius. This makes recovery fast if note-doc generation causes DB/embedding pressure.
+
+```diff
+@@ ## Design
+-Two phases, shipped together as one feature:
++Two phases, shipped together as one feature, but with runtime gates:
++
++- `feature.notes_cli` (Phase 1 surface)
++- `feature.note_documents` (Phase 2 indexing/extraction path)
++
++Rollout order:
++1) Enable `notes_cli`
++2) Run note-doc backfill in bounded batches
++3) Enable `note_documents` for continuous updates
++
++Rollback:
++- Disabling `feature.note_documents` stops new note-doc generation without affecting issue/MR/discussion docs.
+```
+
+2. **Add keyset pagination + deterministic ordering**
+Rationale: Needed for year-long reviewer analysis and reliable “continue where I left off” behavior under concurrent updates.
+
+```diff
+@@ pub struct NoteListFilters<'a> {
+     pub limit: usize,
++    pub cursor: Option<&'a str>,        // keyset token "<sort_ms>:<id>"
++    pub include_total_count: bool,      // avoid COUNT(*) in hot paths
+@@
+-    pub sort: &'a str,                  // "created" (default) | "updated"
++    pub sort: &'a str,                  // "created" | "updated"
+@@ query_notes SQL
+-ORDER BY {sort_column} {order}
++ORDER BY {sort_column} {order}, n.id {order}
+ LIMIT ?
+```
+
+3. **Make `for-issue` / `for-mr` project-scoped**
+Rationale: IIDs are not globally unique. Requiring project avoids false positives and hard-to-debug cross-project leakage.
+
+```diff
+@@ pub struct NotesArgs {
+-    #[arg(long = "for-issue", help_heading = "Filters", conflicts_with = "for_mr")]
++    #[arg(long = "for-issue", help_heading = "Filters", conflicts_with = "for_mr", requires = "project")]
+     pub for_issue: Option<i64>,
+@@
+-    #[arg(long = "for-mr", help_heading = "Filters", conflicts_with = "for_issue")]
++    #[arg(long = "for-mr", help_heading = "Filters", conflicts_with = "for_issue", requires = "project")]
+     pub for_mr: Option<i64>,
+```
+
+4. **Upgrade path filtering semantics**
+Rationale: Review comments often reference renames/moves. Restricting to `position_new_path` misses relevant notes.
+
+```diff
+@@ pub struct NotesArgs {
+-    /// Filter by file path (trailing / for prefix match)
++    /// Filter by file path
+     #[arg(long, help_heading = "Filters")]
+     pub path: Option<String>,
++    /// Path mode: exact|prefix|glob
++    #[arg(long = "path-mode", value_parser = ["exact","prefix","glob"], default_value = "exact", help_heading = "Filters")]
++    pub path_mode: String,
++    /// Match against old path as well as new path
++    #[arg(long = "match-old-path", help_heading = "Filters")]
++    pub match_old_path: bool,
+@@ query_notes filter mappings
+-- `path` ... n.position_new_path ...
++- `path` applies to `n.position_new_path` and optionally `n.position_old_path`.
++- `glob` mode translates `*`/`?` to SQL LIKE with escaping.
+```
+
+5. **Add explicit performance indexes (new migration)**
+Rationale: `notes` becomes a first-class query surface; without indexes, filters degrade quickly at 10k+ note scale.
+
+```diff
+@@ ## Phase 1: `lore notes` Command
++### Work Chunk 1E: Query Performance Indexes
++**Files:** `migrations/023_notes_query_indexes.sql`, `src/core/db.rs`
++
++Add indexes:
++- `notes(project_id, created_at DESC, id DESC)`
++- `notes(author_username, created_at DESC, id DESC) WHERE is_system = 0`
++- `notes(discussion_id)`
++- `notes(position_new_path)`
++- `notes(position_old_path)`
++- `discussions(issue_id)`
++- `discussions(merge_request_id)`
+```
+
+6. **Harden migration 022 with transactional integrity checks**
+Rationale: This is the riskiest part of the plan. Add hard fail-fast checks so corruption cannot silently pass.
+
+```diff
+@@ ### Work Chunk 2A: Schema Migration (022)
++Migration safety requirements:
++- Execute in a single `BEGIN IMMEDIATE ... COMMIT` transaction.
++- Capture and compare pre/post row counts for `documents`, `document_labels`, `document_paths`, `dirty_sources`.
++- Run `PRAGMA foreign_key_check` and abort on any violation.
++- Run `PRAGMA integrity_check` and abort on non-`ok`.
++- Rebuild FTS and assert `documents_fts` rowcount equals `documents` rowcount.
+```
+
+7. **Add note deletion + parent-change propagation**
+Rationale: Current plan handles create/update ingestion but not all staleness paths. Without this, note documents drift.
+
+```diff
+@@ ## Phase 2: Per-Note Documents
++### Work Chunk 2G: Freshness Propagation
++**Files:** `src/ingestion/discussions.rs`, `src/ingestion/mr_discussions.rs`, `src/documents/regenerator.rs`
++
++Rules:
++- If a previously stored note is missing from upstream payload, delete local note row and enqueue `(note, id)` for document deletion.
++- When parent issue/MR title or labels change, enqueue descendant note docs dirty (notes inherit parent metadata).
++- Keep idempotent behavior for repeated syncs.
+```
+
+8. **Separate FTS coverage from embedding coverage**
+Rationale: Biggest cost/perf risk is embeddings. Index all notes in FTS, but embed selectively with policy knobs.
+
+```diff
+@@ ## Estimated Document Volume Impact
+-FTS5 handles this comfortably. Embedding generation time scales linearly (~4x increase).
++FTS5 handles this comfortably. Embedding generation is policy-controlled:
++- FTS: index all non-system note docs
++- Embeddings default: only notes with body length >= 40 chars (configurable)
++- Add config: `documents.note_embeddings.min_chars`, `documents.note_embeddings.enabled`
++- Prioritize unresolved DiffNotes before other notes during embedding backfill
+```
+
+9. **Bring structured reviewer profiling into scope (not narrative reporting)**
+Rationale: This directly serves the stated use case and makes the feature compelling immediately.
+
+```diff
+@@ ## Non-Goals
+-- Adding a "reviewer profile" report command (that's a downstream use case built on this infrastructure)
++- Generating free-form narrative reviewer reports.
++  A structured profiling command is in scope.
++
++## Phase 3: Structured Reviewer Profiling
++Add `lore notes profile --author <user> --since <window>` returning:
++- top commented paths
++- top parent labels
++- unresolved-comment ratio
++- note-type distribution
++- median comment length
+```
+
+10. **Add operational SLOs + robot-mode status for note pipeline**
+Rationale: Reliability improves when regressions are observable, not inferred from failures.
+
+```diff
+@@ ## Verification Checklist
++Operational checks:
++- `lore -J stats` includes per-`source_type` document counts (including `note`)
++- Add queue lag metrics: oldest dirty note age, retry backlog size
++- Add extraction error breakdown by `source_type`
++- Add smoke assertion: disabling `feature.note_documents` leaves other source regeneration unaffected
+```
+
+---
+
+If you want, I can produce a single consolidated revised PRD draft (fully merged text, not just diffs) as the next step.

docs/prd-per-note-search.feedback-2.md

@@ -0,0 +1,200 @@
+Below are the strongest revisions I’d make, excluding everything in your `## Rejected Recommendations` list.
+
+1. **Add a Phase 0 for stable note identity before any note-doc generation**
+Rationale: your current plan still allows note document churn because Issue discussion ingestion is delete/reinsert-based. That makes local `notes.id` unstable, causing unnecessary dirtying/regeneration and potential stale-doc edge cases. Stabilizing identity first (upsert-by-GitLab-ID + sweep stale) improves correctness and cuts repeated work.
+
+```diff
+@@ ## Design
+-Two phases, shipped together as one feature:
++Three phases, shipped together as one feature:
++- **Phase 0 (Foundation):** Stable note identity in local DB (upsert + sweep, no delete/reinsert churn)
+ - **Phase 1 (Option A):** `lore notes` command — direct SQL query over the `notes` table with rich filtering
+ - **Phase 2 (Option B):** Per-note documents — each non-system note becomes its own searchable document in the FTS/embedding pipeline
+@@
++## Phase 0: Stable Note Identity
++
++### Work Chunk 0A: Upsert/Sweep for Issue Discussion Notes
++**Files:** `src/ingestion/discussions.rs`, `migrations/022_notes_identity_index.sql`, `src/core/db.rs`
++**Implementation:**
++- Add unique index: `UNIQUE(project_id, gitlab_id)` on `notes`
++- Replace delete/reinsert issue-note flow with upsert + `last_seen_at` sweep (same durability model as MR note sweep)
++- Ensure `insert_note/upsert_note` returns the stable local row id for both insert and update paths
+```
+
+2. **Replace `source_type` CHECK constraints with a registry table + FK in migration**
+Rationale: table CHECKs force full table rebuild for every new source type forever. A `source_types` table with FK keeps DB-level integrity and future extensibility without rebuilding `documents`/`dirty_sources` every time. This is a major architecture hardening win.
+
+```diff
+@@ ### Work Chunk 2A: Schema Migration (023)
+-Current migration ... CHECK constraints limiting `source_type` ...
++Current migration ... CHECK constraints limiting `source_type` ...
++Revision: migrate to `source_types` registry table + FK constraints.
+@@
+-1. `dirty_sources` — add `'note'` to source_type CHECK
+-2. `documents` — add `'note'` to source_type CHECK
++1. Create `source_types(name TEXT PRIMARY KEY)` and seed: `issue, merge_request, discussion, note`
++2. Rebuild `dirty_sources` and `documents` to replace CHECK with `REFERENCES source_types(name)`
++3. Future source-type additions become `INSERT INTO source_types(name) VALUES (?)` (no table rebuild)
+@@
++#### Additional integrity tests
++#[test]
++fn test_source_types_registry_contains_note() { ... }
++#[test]
++fn test_documents_source_type_fk_enforced() { ... }
++#[test]
++fn test_dirty_sources_source_type_fk_enforced() { ... }
+```
+
+3. **Mark note documents dirty only when note semantics actually changed**
+Rationale: current loops mark every non-system note dirty every sync. With 8k+ notes this creates avoidable queue pressure and regeneration time. Change-aware dirtying (inserted/changed only) gives major performance and stability improvements.
+
+```diff
+@@ ### Work Chunk 2D: Regenerator & Dirty Tracking Integration
+-for note in notes {
+-    let local_note_id = insert_note(&tx, local_discussion_id, &note, None)?;
+-    if !note.is_system {
+-        dirty_tracker::mark_dirty_tx(&tx, SourceType::Note, local_note_id)?;
+-    }
+-}
++for note in notes {
++    let outcome = upsert_note(&tx, local_discussion_id, &note, None)?;
++    if !note.is_system && outcome.changed_semantics {
++        dirty_tracker::mark_dirty_tx(&tx, SourceType::Note, outcome.local_note_id)?;
++    }
++}
+@@
++// changed_semantics should include: body, note_type, path/line positions, resolvable/resolved/resolved_by, updated_at
+```
+
+4. **Expand filters to support real analysis windows and resolution state**
+Rationale: reviewer profiling usually needs bounded windows and both resolved/unresolved views. Current `unresolved: bool` is too narrow and one-sided. Add `--until` and tri-state resolution filtering for better analytical power.
+
+```diff
+@@ pub struct NoteListFilters<'a> {
+-    pub since: Option<&'a str>,
++    pub since: Option<&'a str>,
++    pub until: Option<&'a str>,
+@@
+-    pub unresolved: bool,
++    pub resolution: &'a str, // "any" (default) | "unresolved" | "resolved"
+@@
+-    pub author: Option<&'a str>,
++    pub author: Option<&'a str>, // case-insensitive match
+@@
+-    // Filter by time (7d, 2w, 1m, or YYYY-MM-DD)
++    // Filter by start time (7d, 2w, 1m, or YYYY-MM-DD)
+     pub since: Option<String>,
++    /// Filter by end time (7d, 2w, 1m, or YYYY-MM-DD)
++    #[arg(long, help_heading = "Filters")]
++    pub until: Option<String>,
+@@
+-    /// Only show unresolved review comments
+-    pub unresolved: bool,
++    /// Resolution filter: any, unresolved, resolved
++    #[arg(long, value_parser = ["any", "unresolved", "resolved"], default_value = "any", help_heading = "Filters")]
++    pub resolution: String,
+```
+
+5. **Broaden index strategy to match actual query shapes, not just author queries**
+Rationale: `idx_notes_user_created` helps one path, but common usage also includes project+time scans and unresolved filters. Add two more partial composites for high-selectivity paths.
+
+```diff
+@@ ### Work Chunk 1E: Composite Query Index
+ CREATE INDEX IF NOT EXISTS idx_notes_user_created
+ ON notes(project_id, author_username, created_at DESC, id DESC)
+ WHERE is_system = 0;
++
++CREATE INDEX IF NOT EXISTS idx_notes_project_created
++ON notes(project_id, created_at DESC, id DESC)
++WHERE is_system = 0;
++
++CREATE INDEX IF NOT EXISTS idx_notes_unresolved_project_created
++ON notes(project_id, created_at DESC, id DESC)
++WHERE is_system = 0 AND resolvable = 1 AND resolved = 0;
+@@
++#[test]
++fn test_notes_query_plan_uses_project_created_index_for_default_listing() { ... }
++#[test]
++fn test_notes_query_plan_uses_unresolved_index_when_resolution_unresolved() { ... }
+```
+
+6. **Improve per-note document payload with structured metadata header + minimal thread context**
+Rationale: isolated single-note docs can lose meaning. A small structured header plus lightweight context (parent + one preceding note excerpt) improves semantic retrieval quality substantially without re-bundling full threads.
+
+```diff
+@@ ### Work Chunk 2C: Note Document Extractor
+-// 6. Format content:
+-//    [[Note]] {note_type or "Comment"} on {parent_type_prefix}: {parent_title}
+-//    Project: {path_with_namespace}
+-//    URL: {url}
+-//    Author: @{author}
+-//    Date: {format_date(created_at)}
+-//    Labels: {labels_json}
+-//    File: {position_new_path}:{position_new_line}  (if DiffNote)
+-//
+-//    --- Body ---
+-//
+-//    {body}
++// 6. Format content with machine-readable header:
++//    [[Note]]
++//    source_type: note
++//    note_gitlab_id: {gitlab_id}
++//    project: {path_with_namespace}
++//    parent_type: {Issue|MergeRequest}
++//    parent_iid: {iid}
++//    note_type: {DiffNote|DiscussionNote|Comment}
++//    author: @{author}
++//    created_at: {iso8601}
++//    resolved: {true|false}
++//    path: {position_new_path}:{position_new_line}
++//    url: {url}
++//
++//    --- Context ---
++//    parent_title: {title}
++//    previous_note_excerpt: {optional, max 200 chars}
++//
++//    --- Body ---
++//    {body}
+```
+
+7. **Add first-class export modes for downstream profiling pipelines**
+Rationale: this makes the feature much more useful immediately (LLM prompts, notebook analysis, external scripts) without adding a profiling command. It stays within your non-goals and increases adoption.
+
+```diff
+@@ pub struct NotesArgs {
++    /// Output format
++    #[arg(long, value_parser = ["table", "json", "jsonl", "csv"], default_value = "table", help_heading = "Output")]
++    pub format: String,
+@@
+-    if robot_mode {
++    if robot_mode || args.format == "json" || args.format == "jsonl" || args.format == "csv" {
+         print_list_notes_json(...)
+     } else {
+         print_list_notes(&result);
+     }
+@@ ### Work Chunk 1C: Human & Robot Output Formatting
++Add `print_list_notes_csv()` and `print_list_notes_jsonl()`:
++- CSV columns mirror `NoteListRowJson` field names
++- JSONL emits one note object per line for streaming pipelines
+```
+
+8. **Strengthen verification with idempotence + migration data-preservation checks**
+Rationale: this feature touches ingestion, migrations, indexing, and regeneration. Add explicit idempotence/perf checks so regressions surface early.
+
+```diff
+@@ ## Verification Checklist
+ cargo test
+ cargo clippy --all-targets -- -D warnings
+ cargo fmt --check
++cargo test test_note_ingestion_idempotent_across_two_syncs
++cargo test test_note_document_count_stable_after_second_generate_docs_full
+@@
++lore sync
++lore generate-docs --full
++lore -J stats > /tmp/stats1.json
++lore generate-docs --full
++lore -J stats > /tmp/stats2.json
++# assert note doc count unchanged and dirty queue drains to zero
+```
+
+If you want, I can turn this into a fully rewritten PRD v2 draft with these changes merged in-place and renumbered work chunks end-to-end.

docs/prd-per-note-search.feedback-3.md

@@ -0,0 +1,162 @@
+These are the highest-impact revisions I’d make. They avoid everything in your `## Rejected Recommendations` list.
+
+1. Add immediate note-document deletion propagation (don’t wait for `generate-docs --full`)
+Why: right now, deleted notes can leave stale `source_type='note'` documents until a full rebuild. That creates incorrect search/reporting results and weakens trust in the dataset.
+```diff
+@@ Phase 0: Stable Note Identity
++### Work Chunk 0B: Immediate Deletion Propagation
++
++When sweep deletes stale notes, propagate deletion to documents in the same transaction.
++Do not rely on eventual cleanup via `generate-docs --full`.
++
++#### Tests to Write First
++#[test]
++fn test_issue_note_sweep_deletes_note_documents_immediately() { ... }
++#[test]
++fn test_mr_note_sweep_deletes_note_documents_immediately() { ... }
++
++#### Implementation
++Use `DELETE ... RETURNING id, is_system` in note sweep functions.
++For returned non-system note ids:
++1) `DELETE FROM documents WHERE source_type='note' AND source_id=?`
++2) `DELETE FROM dirty_sources WHERE source_type='note' AND source_id=?`
+```
+
+2. Add one-time upgrade backfill for existing notes (migration 024)
+Why: existing DBs will otherwise only get note-documents for changed/new notes. Historical notes remain invisible unless users manually run full rebuild.
+```diff
+@@ Phase 2: Per-Note Documents
++### Work Chunk 2H: Backfill Existing Notes After Upgrade (Migration 024)
++
++Create migration `024_note_dirty_backfill.sql`:
++INSERT INTO dirty_sources (source_type, source_id, queued_at)
++SELECT 'note', n.id, unixepoch('now') * 1000
++FROM notes n
++LEFT JOIN documents d
++  ON d.source_type='note' AND d.source_id=n.id
++WHERE n.is_system=0 AND d.id IS NULL
++ON CONFLICT(source_type, source_id) DO NOTHING;
++
++Add migration test asserting idempotence and expected queue size.
+```
+
+3. Fix `--since/--until` semantics and validation
+Why: reusing `parse_since` for `until` creates ambiguous windows and off-by-boundary behavior; your own example `--since 90d --until 180d` is chronologically reversed.
+```diff
+@@ Work Chunk 1A: Data Types & Query Layer
+- since: parse_since(since_str) then n.created_at >= ?
+- until: parse_since(until_str) then n.created_at <= ?
++ since: parse_since_start_bound(since_str) then n.created_at >= ?
++ until: parse_until_end_bound(until_str) then n.created_at <= ?
++ Validate since <= until; otherwise return a clear user error.
++
++#### Tests to Write First
++#[test] fn test_query_notes_invalid_time_window_rejected() { ... }
++#[test] fn test_query_notes_until_date_is_end_of_day_inclusive() { ... }
+```
+
+4. Separate semantic-change detection from housekeeping updates
+Why: current proposed `WHERE` includes `updated_at`, which will cause unnecessary dirty churn. You want `last_seen_at` to always refresh, but regeneration only when searchable semantics changed.
+```diff
+@@ Work Chunk 0A: Upsert/Sweep for Issue Discussion Notes
+- OR notes.updated_at IS NOT excluded.updated_at
++ -- updated_at-only changes should not mark semantic dirty
++
++Perform two-step logic:
++1) Upsert always updates persistence/housekeeping fields (`updated_at`, `last_seen_at`).
++2) `changed_semantics` is computed only from fields used by note documents/search filters
++   (body, note_type, resolved flags, paths, author, parent linkage).
++
++#### Tests to Write First
++#[test]
++fn test_issue_note_upsert_updated_at_only_does_not_mark_semantic_change() { ... }
+```
+
+5. Make indexes align with actual query collation and join strategy
+Why: `author` uses `COLLATE NOCASE`; without collation-aware index, SQLite can skip index use. Also, IID filters via scalar subqueries are harder for planner than direct join predicates.
+```diff
+@@ Work Chunk 1E: Composite Query Index
+-CREATE INDEX ... ON notes(project_id, author_username, created_at DESC, id DESC) WHERE is_system = 0;
++CREATE INDEX ... ON notes(project_id, author_username COLLATE NOCASE, created_at DESC, id DESC) WHERE is_system = 0;
++
++CREATE INDEX IF NOT EXISTS idx_discussions_issue_id ON discussions(issue_id);
++CREATE INDEX IF NOT EXISTS idx_discussions_mr_id ON discussions(merge_request_id);
+```
+
+```diff
+@@ Work Chunk 1A: query_notes()
+- d.issue_id = (SELECT id FROM issues WHERE iid = ? AND project_id = ?)
++ i.iid = ? AND i.project_id = ?
+- d.merge_request_id = (SELECT id FROM merge_requests WHERE iid = ? AND project_id = ?)
++ m.iid = ? AND m.project_id = ?
+```
+
+6. Replace manual CSV escaping with `csv` crate
+Why: manual RFC4180 escaping is fragile (quotes/newlines/multi-byte edge cases). This is exactly where a mature library reduces long-term bug risk.
+```diff
+@@ Work Chunk 1C: Human & Robot Output Formatting
+- Uses a minimal CSV writer (no external dependency — the format is simple enough for manual escaping).
++ Uses `csv::Writer` for RFC4180-compliant escaping and stable output across edge cases.
++
++#### Tests to Write First
++#[test] fn test_csv_output_multiline_and_quotes_roundtrip() { ... }
+```
+
+7. Add `--contains` lexical body filter to `lore notes`
+Why: useful middle ground between metadata filtering and semantic search; great for reviewer-pattern mining without requiring FTS query syntax.
+```diff
+@@ Work Chunk 1B: CLI Arguments & Command Wiring
++/// Filter by case-insensitive substring in note body
++#[arg(long, help_heading = "Filters")]
++pub contains: Option<String>;
+```
+
+```diff
+@@ Work Chunk 1A: NoteListFilters
++ pub contains: Option<&'a str>,
+@@ query_notes dynamic filters
++ if contains.is_some() {
++   where_clauses.push("n.body LIKE ? COLLATE NOCASE");
++   params.push(format!("%{}%", escape_like(contains.unwrap())));
++ }
+```
+
+8. Reduce note-document embedding noise by slimming metadata header
+Why: current verbose key-value header repeats low-signal tokens and consumes embedding budget. Keep context, but bias tokens toward actual review text.
+```diff
+@@ Work Chunk 2C: Note Document Extractor
+- Build content with structured metadata header:
+- [[Note]]
+- source_type: note
+- note_gitlab_id: ...
+- project: ...
+- ...
+- --- Body ---
+- {body}
++ Build content with compact, high-signal layout:
++ [[Note]]
++ @{author} on {Issue#|MR!}{iid} in {project_path}
++ path: {path:line}            (only when available)
++ state: {resolved|unresolved} (only when resolvable)
++
++ {body}
++
++Keep detailed metadata in structured document columns/labels/paths/url,
++not repeated in verbose text.
+```
+
+9. Add explicit performance regression checks for the new hot paths
+Why: this feature increases document volume ~4x; you should pin acceptable query behavior now so future changes don’t silently degrade.
+```diff
+@@ Verification Checklist
++Performance/plan checks:
++1) `EXPLAIN QUERY PLAN` for:
++   - author+since query
++   - project+date query
++   - for-mr / for-issue query
++2) Seed 50k-note synthetic fixture and assert:
++   - `lore notes --author ... --limit 100` stays under agreed local threshold
++   - `lore search --type note ...` remains deterministic and completes successfully
+```
+
+If you want, I can also provide a fully merged “iteration 3” PRD text with these edits applied end-to-end so you can drop it in directly.

docs/prd-per-note-search.feedback-4.md

@@ -0,0 +1,187 @@
+1. **Canonical note identity for documents: use `notes.gitlab_id` as `source_id`**
+Why this is better: the current plan still couples document identity to local row IDs. Even with upsert+sweep, local IDs are a storage artifact and can be reused in edge cases. Using GitLab note IDs as canonical document IDs makes regeneration, backfill, and deletion propagation more stable and portable.
+
+```diff
+--- a/PRD.md
++++ b/PRD.md
+@@ Phase 0: Stable Note Identity
+-Phase 2 depends on `notes.id` as the `source_id` for note documents.
++Phase 2 uses `notes.gitlab_id` as the `source_id` for note documents.
++`notes.id` remains an internal relational key only.
+
+@@ Work Chunk 0A
+ pub struct NoteUpsertOutcome {
+     pub local_note_id: i64,
++    pub document_source_id: i64, // notes.gitlab_id
+     pub changed_semantics: bool,
+ }
+
+@@ Work Chunk 2D
+-if !note.is_system && outcome.changed_semantics {
+-    dirty_tracker::mark_dirty_tx(&tx, SourceType::Note, outcome.local_note_id)?;
++if !note.is_system && outcome.changed_semantics {
++    dirty_tracker::mark_dirty_tx(&tx, SourceType::Note, outcome.document_source_id)?;
+ }
+
+@@ Work Chunk 2E
+-SELECT 'note', n.id, ?1
++SELECT 'note', n.gitlab_id, ?1
+
+@@ Work Chunk 2H
+-ON d.source_type = 'note' AND d.source_id = n.id
++ON d.source_type = 'note' AND d.source_id = n.gitlab_id
+```
+
+2. **Prevent false deletions on partial/incomplete syncs**
+Why this is better: sweep-based deletion is correct only when a discussion’s notes were fully fetched. If a page fails mid-fetch, current logic can incorrectly delete valid notes. Add an explicit “fetch complete” guard before sweep.
+
+```diff
+--- a/PRD.md
++++ b/PRD.md
+@@ Phase 0
++### Work Chunk 0C: Sweep Safety Guard (Partial Fetch Protection)
++
++Only run stale-note sweep when note pagination completed successfully for that discussion.
++If fetch is partial/interrupted, skip sweep and keep prior notes intact.
+
++#### Tests to Write First
++#[test]
++fn test_partial_fetch_does_not_sweep_notes() { /* ... */ }
++
++#[test]
++fn test_complete_fetch_runs_sweep_notes() { /* ... */ }
+
++#### Implementation
++if discussion_fetch_complete {
++    sweep_stale_issue_notes(...)?;
++} else {
++    tracing::warn!("Skipping stale sweep for discussion {} due to partial fetch", discussion_gitlab_id);
++}
+```
+
+3. **Make deletion propagation set-based (not per-note loop)**
+Why this is better: the current per-note DELETE loop is O(N) statements and gets slow on large threads. A temp-table/CTE set-based delete is faster, simpler to reason about, and remains atomic.
+
+```diff
+--- a/PRD.md
++++ b/PRD.md
+@@ Work Chunk 0B Implementation
+-    for note_id in stale_note_ids {
+-        conn.execute("DELETE FROM documents WHERE source_type = 'note' AND source_id = ?", [note_id])?;
+-        conn.execute("DELETE FROM dirty_sources WHERE source_type = 'note' AND source_id = ?", [note_id])?;
+-    }
++    CREATE TEMP TABLE _stale_note_source_ids(source_id INTEGER PRIMARY KEY) WITHOUT ROWID;
++    INSERT INTO _stale_note_source_ids
++    SELECT gitlab_id
++    FROM notes
++    WHERE discussion_id = ? AND last_seen_at < ? AND is_system = 0;
++
++    DELETE FROM notes
++    WHERE discussion_id = ? AND last_seen_at < ?;
++
++    DELETE FROM documents
++    WHERE source_type = 'note'
++      AND source_id IN (SELECT source_id FROM _stale_note_source_ids);
++
++    DELETE FROM dirty_sources
++    WHERE source_type = 'note'
++      AND source_id IN (SELECT source_id FROM _stale_note_source_ids);
++
++    DROP TABLE _stale_note_source_ids;
+```
+
+4. **Fix project-scoping and time-window semantics in `lore notes`**
+Why this is better: the plan currently has a contradiction: clap `requires = "project"` blocks use of `defaultProject`, while query layer says default fallback is allowed. Also, `since/until` parsing should use one shared “now” to avoid subtle drift and inverted windows.
+
+```diff
+--- a/PRD.md
++++ b/PRD.md
+@@ Work Chunk 1B NotesArgs
+-#[arg(long = "for-issue", ..., requires = "project")]
++#[arg(long = "for-issue", ...)]
+ pub for_issue: Option<i64>;
+
+-#[arg(long = "for-mr", ..., requires = "project")]
++#[arg(long = "for-mr", ...)]
+ pub for_mr: Option<i64>;
+
+@@ Work Chunk 1A Query Notes
+-- `since`: `parse_since(since_str)` then `n.created_at >= ?`
+-- `until`: `parse_since(until_str)` then `n.created_at <= ?`
++- Parse `since` and `until` with a single anchored `now_ms` captured once per command.
++- If user supplies `YYYY-MM-DD` for `--until`, interpret as end-of-day (23:59:59.999 UTC).
++- Validate `since <= until` after both parse with same anchor.
+```
+
+5. **Add an analytics mode (not a profile command): `lore notes --aggregate`**
+Why this is better: this directly supports the stated use case (review patterns) without introducing the rejected “profile report” command. It keeps scope narrow and reuses existing filters.
+
+```diff
+--- a/PRD.md
++++ b/PRD.md
+@@ Phase 1
++### Work Chunk 1F: Aggregation Mode for Notes Listing
++
++Add optional aggregation on top of `lore notes`:
++- `--aggregate author|note_type|path|resolution`
++- `--top N` (default 20)
++
++Behavior:
++- Reuses all existing filters (`--since`, `--project`, `--for-mr`, etc.)
++- Returns grouped counts (+ percentage of filtered corpus)
++- Works in table/json/jsonl/csv
++
++Non-goal alignment:
++- This is not a narrative “reviewer profile” command.
++- It is a query primitive for downstream analysis.
+```
+
+6. **Prevent note backfill from starving other document regeneration**
+Why this is better: after migration/backfill, note dirty entries can dominate the queue and delay issue/MR/discussion updates. Add source-type fairness in regenerator scheduling.
+
+```diff
+--- a/PRD.md
++++ b/PRD.md
+@@ Work Chunk 2D
++#### Scheduling Revision
++Process dirty sources with weighted fairness instead of strict FIFO:
++- issue: 3
++- merge_request: 3
++- discussion: 2
++- note: 1
++
++Implementation sketch:
++- fetch next batch by source_type buckets
++- interleave according to weights
++- preserve retry semantics per source
+
++#### Tests to Write First
++#[test]
++fn test_note_backfill_does_not_starve_issue_and_mr_regeneration() { /* ... */ }
+```
+
+7. **Harden migration 023: remove invalid SQL assertions and move integrity checks to tests**
+Why this is better: `RAISE(ABORT, ...)` in standalone `SELECT` is not valid SQLite usage outside triggers/check expressions. Keep migration SQL minimal/portable and enforce invariants in migration tests.
+
+```diff
+--- a/PRD.md
++++ b/PRD.md
+@@ Work Chunk 2A Migration SQL
+--- Step 10: Integrity verification
+-SELECT CASE
+-    WHEN ... THEN RAISE(ABORT, '...')
+-END;
++-- Step 10 removed from SQL migration.
++-- Integrity verification is enforced in migration tests:
++-- 1) pre/post row-count equality
++-- 2) `PRAGMA foreign_key_check` is empty
++-- 3) documents_fts row count matches documents row count after rebuild
+
+@@ Work Chunk 2A Tests
++#[test]
++fn test_migration_023_integrity_checks_pass() {
++    // pre/post counts, foreign_key_check empty, fts parity
++}
+```
+
+These 7 revisions improve correctness under failure, reduce churn risk, improve large-sync performance, and make the feature materially more useful for reviewer-analysis workflows without reintroducing any rejected recommendations.

docs/prd-per-note-search.feedback-5.md

@@ -0,0 +1,190 @@
+Here are the highest-impact revisions I’d make. None of these repeat anything in your `## Rejected Recommendations`.
+
+1. **Add immutable reviewer identity (`author_id`) as a first-class key**
+Why this improves the plan: the PRD’s core use case is year-scale reviewer profiling. Usernames are mutable in GitLab, so username-only filtering will fragment one reviewer into multiple identities over time. Adding `author_id` closes that correctness hole and makes historical analysis reliable.
+
+```diff
+@@ Problem Statement
+-1. **Query individual notes by author** — the `--author` filter on `lore search` only matches the first note's author per discussion thread
++1. **Query individual notes by reviewer identity** — support both mutable username and immutable GitLab `author_id` for stable longitudinal analysis
+
+@@ Phase 0: Stable Note Identity
++### Work Chunk 0D: Immutable Author Identity Capture
++**Files:** `migrations/025_notes_author_id.sql`, `src/ingestion/discussions.rs`, `src/ingestion/mr_discussions.rs`, `src/cli/commands/list.rs`
++
++#### Implementation
++- Add nullable `notes.author_id INTEGER` and backfill from future syncs.
++- Populate `author_id` from GitLab note payload (`note.author.id`) on both issue and MR note ingestion paths.
++- Add `--author-id <int>` filter to `lore notes`.
++- Keep `--author` for ergonomics; when both provided, require both to match.
++
++#### Indexing
++- Add `idx_notes_author_id_created ON notes(project_id, author_id, created_at DESC, id DESC) WHERE is_system = 0;`
++
++#### Tests
++- `test_query_notes_filter_author_id_survives_username_change`
++- `test_query_notes_author_and_author_id_intersection`
+```
+
+2. **Strengthen partial-fetch safety from a boolean to an explicit fetch state contract**
+Why this improves the plan: `fetch_complete: bool` is easy to misuse and fragile under retries/crashes. A run-scoped state model makes sweep correctness auditable and prevents accidental deletions when ingestion aborts midway.
+
+```diff
+@@ Phase 0: Stable Note Identity
+-### Work Chunk 0C: Sweep Safety Guard (Partial Fetch Protection)
++### Work Chunk 0C: Sweep Safety Guard with Run-Scoped Fetch State
+
+@@ Implementation
+-Add a `fetch_complete` parameter to the discussion ingestion functions. Only run the stale-note sweep when the fetch completed successfully:
++Add a run-scoped fetch state:
++- `FetchState::Complete`
++- `FetchState::Partial`
++- `FetchState::Failed`
++
++Only run sweep on `FetchState::Complete`.
++Persist `run_seen_at` once per sync run and pass unchanged through all discussion/note upserts.
++Require `run_seen_at` monotonicity per discussion before sweep (skip and warn otherwise).
+
+@@ Tests to Write First
++#[test]
++fn test_failed_fetch_never_sweeps_even_after_partial_upserts() { ... }
++#[test]
++fn test_non_monotonic_run_seen_at_skips_sweep() { ... }
++#[test]
++fn test_retry_after_failed_fetch_then_complete_sweeps_correctly() { ... }
+```
+
+3. **Add DB-level cleanup triggers for note-document referential integrity**
+Why this improves the plan: Work Chunk 0B handles the sweep path, but not every possible delete path. DB triggers give defense-in-depth so stale note docs cannot survive even if a future code path deletes notes differently.
+
+```diff
+@@ Work Chunk 0B: Immediate Deletion Propagation
+-Update both sweep functions to propagate deletion to documents and dirty_sources using set-based SQL
++Keep set-based SQL in sweep functions, and add DB-level cleanup triggers as a safety net.
+
+@@ Work Chunk 2A: Schema Migration (023)
++-- Cleanup trigger: deleting a non-system note must delete note document + dirty queue row
++CREATE TRIGGER notes_ad_cleanup AFTER DELETE ON notes
++WHEN old.is_system = 0
++BEGIN
++  DELETE FROM documents
++   WHERE source_type = 'note' AND source_id = old.id;
++  DELETE FROM dirty_sources
++   WHERE source_type = 'note' AND source_id = old.id;
++END;
++
++-- Cleanup trigger: if note flips to system, remove its document artifacts
++CREATE TRIGGER notes_au_system_cleanup AFTER UPDATE OF is_system ON notes
++WHEN old.is_system = 0 AND new.is_system = 1
++BEGIN
++  DELETE FROM documents
++   WHERE source_type = 'note' AND source_id = new.id;
++  DELETE FROM dirty_sources
++   WHERE source_type = 'note' AND source_id = new.id;
++END;
+```
+
+4. **Eliminate N+1 extraction cost with parent metadata caching in regeneration**
+Why this improves the plan: backfilling ~8k notes with per-note parent/label lookups creates avoidable query amplification. Batch caching turns repeated joins into one-time lookups per parent entity and materially reduces rebuild time.
+
+```diff
+@@ Phase 2: Per-Note Documents
++### Work Chunk 2I: Batch Parent Metadata Cache for Note Regeneration
++**Files:** `src/documents/regenerator.rs`, `src/documents/extractor.rs`
++
++#### Implementation
++- Add `NoteExtractionContext` cache keyed by `(noteable_type, parent_id)` containing:
++  - parent iid/title/url
++  - parent labels
++  - project path
++- In batch regeneration, prefetch parent metadata for note IDs in the current chunk.
++- Use cached metadata in `extract_note_document()` to avoid repeated parent/label queries.
++
++#### Tests
++- `test_note_regeneration_uses_parent_cache_consistently`
++- `test_note_regeneration_cache_hit_preserves_hash_determinism`
+```
+
+5. **Add embedding dedup cache keyed by semantic text hash**
+Why this improves the plan: note docs will contain repeated short comments (“LGTM”, “nit: …”). Current doc-level hashing includes metadata, so identical semantic comments still re-embed many times. A semantic embedding hash cache cuts cost and speeds full rebuild/backfill without changing search behavior.
+
+```diff
+@@ Phase 2: Per-Note Documents
++### Work Chunk 2J: Semantic Embedding Dedup for Notes
++**Files:** `migrations/026_embedding_cache.sql`, embedding pipeline module(s), `src/documents/extractor.rs`
++
++#### Implementation
++- Compute `embedding_text` for notes as: normalized note body + compact stable context (`parent_type`, `path`, `resolution`), excluding volatile fields.
++- Compute `embedding_hash = sha256(embedding_text)`.
++- Before embedding generation, lookup existing vector by `(model, embedding_hash)`.
++- Reuse cached vector when present; only call embedding model on misses.
++
++#### Tests
++- `test_identical_note_bodies_reuse_embedding_vector`
++- `test_embedding_hash_changes_when_semantic_context_changes`
+```
+
+6. **Add deterministic review-signal tags as derived labels**
+Why this improves the plan: this makes output immediately more useful for reviewer-pattern analysis without adding a profile command (which is explicitly out of scope). It increases practical value of both `lore notes` and `lore search --type note` with low complexity.
+
+```diff
+@@ Non-Goals
+-- Adding a "reviewer profile" report command (that's a downstream use case built on this infrastructure)
++- Adding a "reviewer profile" report command (downstream), while allowing low-level derived signal tags as indexing primitives
+
+@@ Phase 2: Per-Note Documents
++### Work Chunk 2K: Derived Review Signal Labels
++**Files:** `src/documents/extractor.rs`
++
++#### Implementation
++- Derive deterministic labels from note text + metadata:
++  - `signal:nit`
++  - `signal:blocking`
++  - `signal:security`
++  - `signal:performance`
++  - `signal:testing`
++- Attach via existing `document_labels` flow for note documents.
++- No new CLI mode required; existing label filters can consume these labels.
++
++#### Tests
++- `test_note_document_derives_signal_labels_nit`
++- `test_note_document_derives_signal_labels_security`
++- `test_signal_label_derivation_is_deterministic`
+```
+
+7. **Add high-precision note targeting filters (`--note-id`, `--gitlab-note-id`, `--discussion-id`)**
+Why this improves the plan: debugging, incident response, and reproducibility all benefit from exact addressing. This is especially useful when validating sync correctness and cross-checking a specific note/document lifecycle.
+
+```diff
+@@ Work Chunk 1B: CLI Arguments & Command Wiring
+ pub struct NotesArgs {
++    /// Filter by local note row id
++    #[arg(long = "note-id", help_heading = "Filters")]
++    pub note_id: Option<i64>,
++
++    /// Filter by GitLab note id
++    #[arg(long = "gitlab-note-id", help_heading = "Filters")]
++    pub gitlab_note_id: Option<i64>,
++
++    /// Filter by local discussion id
++    #[arg(long = "discussion-id", help_heading = "Filters")]
++    pub discussion_id: Option<i64>,
+ }
+
+@@ Work Chunk 1A: Filter struct
+ pub struct NoteListFilters<'a> {
++    pub note_id: Option<i64>,
++    pub gitlab_note_id: Option<i64>,
++    pub discussion_id: Option<i64>,
+ }
+
+@@ Tests to Write First
++#[test]
++fn test_query_notes_filter_note_id_exact() { ... }
++#[test]
++fn test_query_notes_filter_gitlab_note_id_exact() { ... }
++#[test]
++fn test_query_notes_filter_discussion_id_exact() { ... }
+```
+
+If you want, I can produce a single consolidated “iteration 5” PRD diff that merges these into your exact section ordering and updates the dependency graph/migration numbering end-to-end.

docs/prd-per-note-search.feedback-6.md

@@ -0,0 +1,131 @@
+1. **Make immutable identity usable now (`--author-id`)**
+Why: The plan captures `author_id` but intentionally defers using it, so the core longitudinal-analysis problem is only half-fixed.
+
+```diff
+@@ Phase 1: `lore notes` Command / Work Chunk 1A
+ pub struct NoteListFilters<'a> {
++    pub author_id: Option<i64>,         // immutable identity filter
+@@
+-    pub author: Option<&'a str>,          // case-insensitive match via COLLATE NOCASE
++    pub author: Option<&'a str>,          // display-name filter
++    // If both author and author_id are provided, apply both (AND) for precision.
+ }
+@@
+ Filter mappings:
++ - `author_id`: `n.author_id = ?` (exact immutable identity)
+  - `author`: strip `@` prefix, `n.author_username = ? COLLATE NOCASE`
+@@ Phase 1 / Work Chunk 1B (CLI)
++ /// Filter by immutable author id
++ #[arg(long = "author-id", help_heading = "Filters")]
++ pub author_id: Option<i64>,
+@@ Phase 2 / Work Chunk 2F
++ Add `--author-id` support to `lore search` filtering for note documents.
+@@ Phase 1 / Work Chunk 1E
++ CREATE INDEX IF NOT EXISTS idx_notes_project_author_id_created
++ ON notes(project_id, author_id, created_at DESC, id DESC)
++ WHERE is_system = 0 AND author_id IS NOT NULL;
+```
+
+2. **Fix document staleness on username changes**
+Why: Current plan says username changes are “not semantic,” but note documents include username in content/title, so docs go stale/inconsistent.
+
+```diff
+@@ Work Chunk 0D: Immutable Author Identity Capture
+- Assert: changed_semantics = false (username change is not a semantic change for documents)
++ Assert: changed_semantics = true (username affects note document content/title)
+@@ Work Chunk 0A: semantic-change detection
+- old_body != body || old_note_type != note_type || ...
++ old_body != body || old_note_type != note_type || ...
++ || old_author_username != author_username
+@@ Work Chunk 2C: Note Document Extractor header
+     author: @{author}
++    author_id: {author_id}
+```
+
+3. **Replace `last_seen_at` sweep marker with monotonic `sync_run_id`**
+Why: Timestamp markers are vulnerable to clock skew and concurrent runs; run IDs are deterministic and safer.
+
+```diff
+@@ Phase 0: Stable Note Identity
++ ### Work Chunk 0E: Monotonic Run Marker
++ Add `sync_runs` table and `notes.last_seen_run_id`.
++ Ingest assigns one run_id per sync transaction.
++ Upsert sets `last_seen_run_id = current_run_id`.
++ Sweep condition becomes `last_seen_run_id < current_run_id` (when fetch_complete=true).
+@@ Work Chunk 0C
+- fetch_complete + last_seen_at-based sweep
++ fetch_complete + run_id-based sweep
+```
+
+4. **Materialize stale-note set once during sweep**
+Why: Current set-based SQL still re-runs the stale subquery 3 times; materializing once improves performance and guarantees identical deletion set.
+
+```diff
+@@ Work Chunk 0B: Immediate Deletion Propagation
+- DELETE FROM documents ... IN (SELECT id FROM notes WHERE ...);
+- DELETE FROM dirty_sources ... IN (SELECT id FROM notes WHERE ...);
+- DELETE FROM notes WHERE ...;
++ CREATE TEMP TABLE _stale_note_ids AS
++ SELECT id, is_system FROM notes WHERE discussion_id = ? AND last_seen_run_id < ?;
++ DELETE FROM documents
++  WHERE source_type='note' AND source_id IN (SELECT id FROM _stale_note_ids WHERE is_system=0);
++ DELETE FROM dirty_sources
++  WHERE source_type='note' AND source_id IN (SELECT id FROM _stale_note_ids WHERE is_system=0);
++ DELETE FROM notes WHERE id IN (SELECT id FROM _stale_note_ids);
++ DROP TABLE _stale_note_ids;
+```
+
+5. **Move historical note backfill out of migration into resumable runtime job**
+Why: Data-heavy migration can block startup and is harder to resume/recover on large DBs.
+
+```diff
+@@ Work Chunk 2H
+- Backfill Existing Notes After Upgrade (Migration 024)
++ Backfill Existing Notes After Upgrade (Resumable Runtime Backfill)
+@@
+- Files: `migrations/024_note_dirty_backfill.sql`, `src/core/db.rs`
++ Files: `src/documents/backfill.rs`, `src/cli/commands/generate_docs.rs`
+@@
+- INSERT INTO dirty_sources ... SELECT ... FROM notes ...
++ Introduce batched backfill API:
++ `enqueue_missing_note_documents(batch_size: usize) -> BackfillProgress`
++ invoked from `generate-docs`/`sync` until complete, resumable across runs.
+```
+
+6. **Add streaming path for large `jsonl`/`csv` note exports**
+Why: Current `query_notes` materializes full result set in memory; streaming improves scalability and latency.
+
+```diff
+@@ Work Chunk 1A
++ Add `query_notes_stream(conn, filters, row_handler)` for forward-only row iteration.
+@@ Work Chunk 1C
+- print_list_notes_jsonl(&result)
+- print_list_notes_csv(&result)
++ print_list_notes_jsonl_stream(config, filters)
++ print_list_notes_csv_stream(config, filters)
++ (table/json keep counted buffered path)
+```
+
+7. **Add index for path-centric note queries**
+Why: `--path` + project/date queries are a stated hot path and not fully covered by current proposed indexes.
+
+```diff
+@@ Work Chunk 1E: Composite Query Index
++ CREATE INDEX IF NOT EXISTS idx_notes_project_path_created
++ ON notes(project_id, position_new_path, created_at DESC, id DESC)
++ WHERE is_system = 0 AND position_new_path IS NOT NULL;
+```
+
+8. **Add property/invariant tests (not only examples)**
+Why: This feature touches ingestion identity, sweeping, deletion propagation, and document regeneration; randomized invariants will catch subtle regressions.
+
+```diff
+@@ Verification Checklist
++ Add property tests (proptest):
++ - stable local IDs across randomized re-sync orderings
++ - no orphan `documents(source_type='note')` after randomized deletions/sweeps
++ - partial-fetch runs never reduce note count
++ - repeated full rebuild converges (fixed-point idempotence)
+```
+
+These revisions keep your existing direction, avoid all rejected items, and materially improve correctness, scale behavior, and long-term maintainability.

docs/robot-mode-design.md

@@ -2,19 +2,22 @@
 
 ## Overview
 
-Robot mode optimizes the `lore` CLI for AI agent consumption with structured JSON output, meaningful exit codes, and token-efficient responses.
+Robot mode optimizes the `lore` CLI for AI agent consumption with compact JSON output, structured errors with machine-actionable recovery steps, meaningful exit codes, response timing metadata, field selection for token efficiency, and TTY auto-detection.
 
 ## Activation
 
 ```bash
 # Explicit flag
-lore --robot list issues
+lore --robot issues -n 5
 
-# Auto-detection (when stdout is not a TTY)
-lore list issues | jq .
+# JSON shorthand
+lore -J issues -n 5
 
 # Environment variable
-LORE_ROBOT=true lore list issues
+LORE_ROBOT=1 lore issues
+
+# Auto-detection (when stdout is not a TTY)
+lore issues | jq .
 ```
 
 ## Global Flags
@@ -22,218 +25,160 @@ LORE_ROBOT=true lore list issues
 | Flag | Description |
 |------|-------------|
 | `--robot` | Force JSON output, structured errors |
-| `--quiet` | Suppress progress/spinners (implied by --robot) |
+| `-J` / `--json` | Shorthand for `--robot` |
+| `--quiet` | Suppress progress/spinners (implied by `--robot`) |
+| `--fields <list>` | Select output fields for list commands |
 
-## Exit Codes
+## Response Envelope
 
-| Code | ErrorCode | Meaning |
-|------|-----------|---------|
-| 0 | - | Success |
-| 1 | INTERNAL_ERROR | Unknown/internal error |
-| 2 | CONFIG_NOT_FOUND | Config file missing |
-| 3 | CONFIG_INVALID | Config file malformed |
-| 4 | TOKEN_NOT_SET | GitLab token not configured |
-| 5 | GITLAB_AUTH_FAILED | Authentication failed |
-| 6 | GITLAB_NOT_FOUND | Resource not found |
-| 7 | GITLAB_RATE_LIMITED | Rate limited |
-| 8 | GITLAB_NETWORK_ERROR | Network/connection error |
-| 9 | DB_LOCKED | Database locked by another process |
-| 10 | DB_ERROR | Database error |
-| 11 | MIGRATION_FAILED | Migration failed |
-| 12 | IO_ERROR | File I/O error |
-| 13 | TRANSFORM_ERROR | Data transformation error |
+All commands return a consistent JSON envelope to stdout:
+
+```json
+{"ok":true,"data":{...},"meta":{"elapsed_ms":42}}
+```
+
+Key properties:
+- **Compact JSON**: Single-line output (no pretty-printing) for efficient parsing
+- **Uniform envelope**: Every command wraps its data in `{"ok":true,"data":{...},"meta":{...}}`
+- **Timing metadata**: `meta.elapsed_ms` is present on every response (wall-clock milliseconds)
 
 ## Error Output Format
 
-When `--robot` is active, errors are JSON on stderr:
+Errors are JSON on stderr with structured fields for programmatic handling:
 
 ```json
 {
   "error": {
     "code": "CONFIG_NOT_FOUND",
-    "message": "Config file not found at ~/.config/lore/config.toml",
-    "suggestion": "Run 'lore init' to create configuration"
+    "message": "Config file not found at ~/.config/lore/config.json. Run \"lore init\" first.",
+    "suggestion": "Run 'lore init' to set up your GitLab connection.",
+    "actions": ["lore init"]
   }
 }
 ```
 
-## Success Output Format
+| Field | Type | Description |
+|-------|------|-------------|
+| `code` | string | Machine-readable error code (e.g., `CONFIG_NOT_FOUND`) |
+| `message` | string | Human-readable error description |
+| `suggestion` | string? | Recovery guidance (omitted when not applicable) |
+| `actions` | string[]? | Executable shell commands for recovery (omitted when empty) |
 
-All commands return consistent JSON structure:
+### Error Actions by Code
 
-```json
-{
-  "ok": true,
-  "data": { ... },
-  "meta": {
-    "count": 50,
-    "total": 1234,
-    "elapsed_ms": 45
-  }
-}
+| Error Code | Actions |
+|------------|---------|
+| `CONFIG_NOT_FOUND` | `["lore init"]` |
+| `CONFIG_INVALID` | `["lore init --force"]` |
+| `GITLAB_AUTH_FAILED` | `["export GITLAB_TOKEN=glpat-xxx", "lore auth"]` |
+| `TOKEN_NOT_SET` | `["export GITLAB_TOKEN=glpat-xxx"]` |
+| `OLLAMA_UNAVAILABLE` | `["ollama serve"]` |
+| `OLLAMA_MODEL_NOT_FOUND` | `["ollama pull nomic-embed-text"]` |
+| `DB_LOCKED` | `["lore ingest --force"]` |
+| `EMBEDDING_FAILED` | `["lore embed --retry-failed"]` |
+| `MIGRATION_FAILED` | `["lore migrate"]` |
+| `GITLAB_NETWORK_ERROR` | `["lore doctor"]` |
+
+## Exit Codes
+
+| Code | ErrorCode | Meaning |
+|------|-----------|---------|
+| 0 | -- | Success |
+| 1 | `INTERNAL_ERROR` | Unknown/internal error |
+| 2 | -- | Usage error (invalid flags or arguments) |
+| 3 | `CONFIG_INVALID` | Config file malformed |
+| 4 | `TOKEN_NOT_SET` | GitLab token not configured |
+| 5 | `GITLAB_AUTH_FAILED` | Authentication failed |
+| 6 | `GITLAB_NOT_FOUND` | Resource not found |
+| 7 | `GITLAB_RATE_LIMITED` | Rate limited |
+| 8 | `GITLAB_NETWORK_ERROR` | Network/connection error |
+| 9 | `DB_LOCKED` | Database locked by another process |
+| 10 | `DB_ERROR` | Database error |
+| 11 | `MIGRATION_FAILED` | Migration failed |
+| 12 | `IO_ERROR` | File I/O error |
+| 13 | `TRANSFORM_ERROR` | Data transformation error |
+| 14 | `OLLAMA_UNAVAILABLE` | Ollama not running |
+| 15 | `OLLAMA_MODEL_NOT_FOUND` | Ollama model not installed |
+| 16 | `EMBEDDING_FAILED` | Embedding generation failed |
+| 17 | `NOT_FOUND` | Entity does not exist locally |
+| 18 | `AMBIGUOUS` | Multiple projects match (use `-p`) |
+| 19 | -- | Health check failed |
+| 20 | `CONFIG_NOT_FOUND` | Config file missing |
+
+## Field Selection
+
+The `--fields` flag on `issues` and `mrs` list commands controls which fields appear in each item of the response array:
+
+```bash
+# Preset: ~60% fewer tokens
+lore -J issues --fields minimal
+
+# Custom field list
+lore -J mrs --fields iid,title,state,draft,target_branch
 ```
 
-## Command-Specific Output
+### Presets
 
-### lore list issues --robot
+| Preset | Expands to |
+|--------|------------|
+| `minimal` | `iid`, `title`, `state`, `updated_at_iso` |
 
-```json
-{
-  "ok": true,
-  "data": {
-    "issues": [
-      {
-        "iid": 123,
-        "project": "group/project",
-        "title": "Bug in login",
-        "state": "opened",
-        "author": "username",
-        "assignees": ["user1"],
-        "labels": ["bug", "priority::high"],
-        "discussions": { "total": 5, "unresolved": 2 },
-        "updated_at": "2024-01-15T10:30:00Z",
-        "web_url": "https://..."
-      }
-    ]
-  },
-  "meta": { "showing": 50, "total": 234 }
-}
+### Available Fields
+
+**Issues**: `iid`, `title`, `state`, `author_username`, `labels`, `assignees`, `discussion_count`, `unresolved_count`, `created_at_iso`, `updated_at_iso`, `web_url`, `project_path`, `status_name`, `status_category`, `status_color`, `status_icon_name`, `status_synced_at_iso`
+
+**MRs**: `iid`, `title`, `state`, `author_username`, `labels`, `draft`, `target_branch`, `source_branch`, `discussion_count`, `unresolved_count`, `created_at_iso`, `updated_at_iso`, `web_url`, `project_path`, `reviewers`
+
+Field selection applies only to list output, not to show (single-entity) output which returns full detail.
+
+## Command Response Schemas
+
+Every command in `lore robot-docs` includes a `response_schema` field describing the shape of its JSON response. This enables agents to understand response structures without trial-and-error.
+
+```bash
+# Get schema for a specific command
+lore robot-docs | jq '.data.commands.issues.response_schema'
+
+# Get all schemas
+lore robot-docs | jq '[.data.commands | to_entries[] | select(.value.response_schema) | {(.key): .value.response_schema}] | add'
 ```
 
-### lore show issue 123 --robot
+## Clap Error Handling
+
+Parse errors from the argument parser emit structured JSON to stderr with semantic error codes:
+
+| Code | Meaning |
+|------|---------|
+| `UNKNOWN_COMMAND` | Unrecognized subcommand (includes fuzzy suggestion) |
+| `UNKNOWN_FLAG` | Unrecognized command-line flag |
+| `MISSING_REQUIRED` | Required argument not provided |
+| `INVALID_VALUE` | Invalid value for argument |
+| `TOO_MANY_VALUES` | Too many values provided |
+| `TOO_FEW_VALUES` | Too few values provided |
+| `ARGUMENT_CONFLICT` | Conflicting arguments |
+| `MISSING_COMMAND` | No subcommand provided |
+| `HELP_REQUESTED` | Help or version flag used |
+| `PARSE_ERROR` | General parse error |
+
+Unknown commands include a fuzzy suggestion when a close match exists:
 
 ```json
-{
-  "ok": true,
-  "data": {
-    "issue": {
-      "iid": 123,
-      "project": "group/project",
-      "title": "Bug in login",
-      "description": "Full markdown...",
-      "state": "opened",
-      "author": "username",
-      "created_at": "2024-01-10T08:00:00Z",
-      "updated_at": "2024-01-15T10:30:00Z",
-      "discussions": [
-        {
-          "id": "abc123",
-          "resolved": false,
-          "notes": [
-            {
-              "author": "user1",
-              "body": "Comment text...",
-              "created_at": "2024-01-11T09:00:00Z",
-              "system": false
-            }
-          ]
-        }
-      ]
-    }
-  }
-}
+{"error":{"code":"UNKNOWN_COMMAND","message":"...","suggestion":"Did you mean 'lore issues'? Run 'lore robot-docs' for all commands"}}
 ```
 
-### lore ingest --type issues --robot
+## Agent Self-Discovery
 
-```json
-{
-  "ok": true,
-  "data": {
-    "resource_type": "issues",
-    "projects": [
-      {
-        "path": "group/project",
-        "issues_synced": 45,
-        "discussions_synced": 123
-      }
-    ],
-    "totals": {
-      "issues": 45,
-      "discussions": 123
-    }
-  },
-  "meta": { "elapsed_ms": 3400 }
-}
+`lore robot-docs` provides a complete manifest for agent bootstrapping:
+
+```bash
+lore robot-docs        # Pretty-printed (human-readable)
+lore --robot robot-docs  # Compact (for parsing)
 ```
 
-### lore count issues --robot
-
-```json
-{
-  "ok": true,
-  "data": {
-    "entity": "issues",
-    "count": 1234,
-    "breakdown": {
-      "opened": 456,
-      "closed": 778
-    }
-  }
-}
-```
-
-### lore doctor --robot
-
-```json
-{
-  "ok": true,
-  "data": {
-    "success": true,
-    "checks": {
-      "config": { "status": "ok", "path": "~/.config/lore/config.toml" },
-      "database": { "status": "ok", "version": 6 },
-      "gitlab": { "status": "ok", "user": "username" },
-      "projects": [
-        { "path": "group/project", "status": "ok" }
-      ]
-    }
-  }
-}
-```
-
-### lore sync-status --robot
-
-```json
-{
-  "ok": true,
-  "data": {
-    "last_sync": {
-      "status": "completed",
-      "resource_type": "issues",
-      "started_at": "2024-01-15T10:00:00Z",
-      "completed_at": "2024-01-15T10:00:45Z",
-      "duration_ms": 45000
-    },
-    "cursors": [
-      {
-        "project": "group/project",
-        "resource_type": "issues",
-        "cursor": "2024-01-15T10:00:00Z"
-      }
-    ]
-  }
-}
-```
-
-## Implementation Plan
-
-### Phase 1: Core Infrastructure
-1. Add `--robot` global flag to Cli struct
-2. Create `RobotOutput` trait for consistent JSON serialization
-3. Add exit code mapping from ErrorCode
-4. Implement TTY detection with `atty` crate
-
-### Phase 2: Command Updates
-1. Update all commands to check robot mode
-2. Add JSON output variants for commands missing them (count, ingest, sync-status)
-3. Suppress progress bars in robot mode
-
-### Phase 3: Error Handling
-1. Update main.rs error handler for robot mode
-2. Add suggestion field to GiError variants
-3. Emit structured JSON errors to stderr
-
-### Phase 4: Documentation
-1. Update AGENTS.md with robot mode commands
-2. Add --robot examples to help text
+The manifest includes:
+- All commands with flags, examples, and response schemas
+- Deprecated command aliases (e.g., `list issues` -> `issues`)
+- Exit codes with meanings
+- Clap error codes
+- Suggested workflows (first setup, daily sync, search, pre-flight)
+- Activation methods (flags, env vars, TTY auto-detection)

docs/user-journeys.md

@@ -0,0 +1,541 @@
+# Lore CLI User Journeys
+
+## Purpose
+
+Map realistic workflows for both human users and AI agents to identify gaps in the command surface and optimization opportunities. Each journey starts with a **problem** and traces the commands needed to reach a **resolution**.
+
+---
+
+## Part 1: Human User Flows
+
+### H1. Morning Standup Prep
+
+**Problem:** "What happened since yesterday? I need to know what moved before standup."
+
+**Flow:**
+```
+lore sync -q                              # Refresh data (quiet, no noise)
+lore issues -s opened --since 1d          # Issues that changed overnight
+lore mrs -s opened --since 1d             # MRs that moved
+lore who @me                              # My current workload snapshot
+```
+
+**Gap identified:** No single "activity feed" command. User runs 3 queries to get what should be one view. No `--since 1d` shorthand for "since yesterday." No `@me` alias for the authenticated user.
+
+---
+
+### H2. Sprint Planning: What's Ready to Pick Up?
+
+**Problem:** "We're planning the next sprint. What's open, unassigned, and actionable?"
+
+**Flow:**
+```
+lore issues -s opened -p myproject        # All open issues
+lore issues -s opened -l "ready"          # Issues labeled ready
+lore issues -s opened --has-due           # Issues with deadlines approaching
+lore count issues -p myproject            # How many total?
+```
+
+**Gap identified:** No way to filter by "unassigned" issues (missing `--no-assignee` flag). No way to sort by due date. No way to see priority/weight. Can't combine filters like "opened AND no assignee AND has due date."
+
+---
+
+### H3. Investigating a Production Incident
+
+**Problem:** "Deploy broke prod. I need the full timeline of what changed around the deploy."
+
+**Flow:**
+```
+lore sync -q                              # Get latest
+lore timeline "deploy" --since 7d         # What happened around deploys
+lore search "deploy" --type mr            # MRs mentioning deploy
+lore mrs 456                              # Inspect the suspicious MR
+lore who --overlap src/deploy/            # Who else touches deploy code
+```
+
+**Gap identified:** Timeline is keyword-based, not event-based. Can't filter by "MRs merged in the last 24 hours" directly. No way to see which MRs were merged between two dates (release diff). Would benefit from `lore mrs -s merged --since 1d`.
+
+---
+
+### H4. Preparing to Review Someone's MR
+
+**Problem:** "I was assigned to review MR !789. I need context before diving in."
+
+**Flow:**
+```
+lore mrs 789                              # Read the MR description + discussions
+lore mrs 789 -o                           # Open in browser for the actual diff
+lore who src/features/auth/               # Who are the experts in this area?
+lore search "auth refactor" --type issue  # Related issues for background
+lore timeline "authentication"            # History of auth changes
+```
+
+**Gap identified:** No way to see the file list touched by an MR from the CLI (data is stored in `mr_file_changes` but not surfaced). No way to link an MR back to its closing issue(s) from the MR detail view. The cross-reference data exists in `entity_references` but isn't shown in `mrs <iid>` output.
+
+---
+
+### H5. Onboarding to an Unfamiliar Code Area
+
+**Problem:** "I'm new to the team and need to understand how the billing module works."
+
+**Flow:**
+```
+lore search "billing" -n 20               # What exists about billing?
+lore who src/billing/                      # Who knows billing best?
+lore timeline "billing" --depth 2         # History of billing changes
+lore mrs -s merged -l billing --since 6m  # Recent merged billing work
+lore issues -s opened -l billing          # Outstanding billing issues
+```
+
+**Gap identified:** No way to get a "module overview" in one command. The search spans issues, MRs, and discussions but doesn't summarize by category. No way to see the most-discussed or most-referenced entities (high-signal items for understanding).
+
+---
+
+### H6. Finding the Right Reviewer for My PR
+
+**Problem:** "I'm about to submit a PR touching auth and payments. Who should review?"
+
+**Flow:**
+```
+lore who src/features/auth/               # Auth experts
+lore who src/features/payments/           # Payment experts
+lore who @candidate1                      # Check candidate1's workload
+lore who @candidate2                      # Check candidate2's workload
+```
+
+**Gap identified:** No way to query multiple paths at once (`lore who src/auth/ src/payments/`). No way to find the intersection of expertise. No workload-aware recommendation ("who knows this AND has bandwidth"). Four separate commands for what should be one decision.
+
+---
+
+### H7. Understanding Why a Feature Was Built This Way
+
+**Problem:** "This code is weird. Why was it implemented like this? What was the original discussion?"
+
+**Flow:**
+```
+lore search "feature-name rationale"      # Search for decision context
+lore timeline "feature-name" --depth 2    # Full history with cross-refs
+lore issues 234                           # Read the original issue
+lore mrs 567                              # Read the implementation MR
+```
+
+**Gap identified:** No way to search within a specific issue's or MR's discussion notes. The search covers documents (titles + descriptions) but per-note search isn't available yet (PRD exists). No way to navigate "issue 234 was closed by MR 567" without manually knowing both IDs.
+
+---
+
+### H8. Checking Team Workload Before Assigning Work
+
+**Problem:** "I need to assign this urgent bug. Who has the least on their plate?"
+
+**Flow:**
+```
+lore who @alice                           # Alice's workload
+lore who @bob                             # Bob's workload
+lore who @carol                           # Carol's workload
+lore who @dave                            # Dave's workload
+```
+
+**Gap identified:** No team-level workload view. Must query each person individually. No way to list "all assignees and their open issue counts." No concept of a team roster. Would benefit from `lore who --team` or `lore workload`.
+
+---
+
+### H9. Preparing Release Notes
+
+**Problem:** "We're cutting a release. I need to summarize what's in this version."
+
+**Flow:**
+```
+lore mrs -s merged --since 2w -p myproject   # MRs merged since last release
+lore issues -s closed --since 2w -p myproject # Issues closed since last release
+lore mrs -s merged -l feature --since 2w      # Feature MRs specifically
+lore mrs -s merged -l bugfix --since 2w       # Bugfix MRs
+```
+
+**Gap identified:** No way to filter by milestone (for version-based releases). Wait -- `issues` has `-m` for milestone but `mrs` does not. No changelog generation. No "what closed between tag A and tag B." No grouping by label for release note categories.
+
+---
+
+### H10. Finding and Closing Stale Issues
+
+**Problem:** "Our backlog is bloated. Which issues haven't been touched in months?"
+
+**Flow:**
+```
+lore issues -s opened --sort updated --asc -n 50  # Oldest-updated first
+# Then manually inspect each one...
+lore issues 42                                      # Is this still relevant?
+```
+
+**Gap identified:** No `--before` or `--updated-before` filter (only `--since` exists). Can sort ascending but can't filter "not updated in 90 days." No staleness indicator. No bulk operations concept.
+
+---
+
+### H11. Understanding a Bug's Full History
+
+**Problem:** "Bug #321 keeps getting reopened. I need to understand its entire lifecycle."
+
+**Flow:**
+```
+lore issues 321                           # Read the issue
+lore timeline "bug-keyword" -p myproject  # Try to find timeline events
+# But timeline is keyword-based, not entity-based...
+```
+
+**Gap identified:** No way to get a timeline for a specific entity by IID. `lore timeline` requires a keyword query, not an entity reference. Would benefit from `lore timeline --issue 321` or `lore timeline --mr 456` to get the event history of a specific entity directly.
+
+---
+
+### H12. Identifying Who to Ask About Failing Tests
+
+**Problem:** "CI tests are failing in `src/lib/parser.rs`. Who last touched this?"
+
+**Flow:**
+```
+lore who src/lib/parser.rs                # Expert lookup
+lore who --overlap src/lib/parser.rs      # Who else has touched it
+lore search "parser" --type mr --since 2w # Recent MRs touching parser
+```
+
+**Gap identified:** Expert mode uses DiffNote analysis (code review comments), not actual file change tracking. The `mr_file_changes` table has the real data but `who` doesn't use it for attribution. Could be much more accurate with file-change-based expertise.
+
+---
+
+### H13. Tracking a Feature Across Multiple MRs
+
+**Problem:** "The 'dark mode' feature spans 5 MRs. I need to see them all together."
+
+**Flow:**
+```
+lore mrs -l dark-mode                     # MRs with the label
+lore issues -l dark-mode                  # Related issues
+lore timeline "dark mode" --depth 2       # Cross-referenced events
+```
+
+**Gap identified:** Works reasonably well with labels as the grouping mechanism. But if the team didn't label consistently, there's no way to discover related MRs by content similarity. No "related items" view that combines issues + MRs + discussions for a topic.
+
+---
+
+### H14. Checking if a Similar Fix Was Already Attempted
+
+**Problem:** "Before I implement this fix, was something similar tried before?"
+
+**Flow:**
+```
+lore search "memory leak connection pool" # Semantic search
+lore search "connection pool" --type mr -s all  # Wait, no state filter on search
+lore mrs -s closed -l bugfix              # Closed bugfix MRs (coarse)
+lore timeline "connection pool"           # Historical context
+```
+
+**Gap identified:** Search doesn't have a `--state` filter. Can't search only closed/merged items. The semantic search is powerful but can't be combined with entity state. Would benefit from `--state merged` on search to find past attempts.
+
+---
+
+### H15. Reviewing Discussions That Need My Attention
+
+**Problem:** "Which discussion threads am I involved in that are still unresolved?"
+
+**Flow:**
+```
+lore who --active                         # All active unresolved discussions
+lore who --active --since 30d             # Wider window
+# But can't filter to "discussions I'm in"...
+```
+
+**Gap identified:** `--active` shows all unresolved discussions, not filtered by participant. No way to say "show me discussions where @me participated." No notification/mention tracking. No "my unresolved threads" view.
+
+---
+
+## Part 2: AI Agent Flows
+
+### A1. Context Gathering Before Code Modification
+
+**Problem:** Agent is about to modify `src/features/auth/session.rs` and needs full context.
+
+**Flow:**
+```
+lore -J health                            # Pre-flight check
+lore -J who src/features/auth/            # Who knows this area
+lore -J search "auth session" -n 10       # Related issues/MRs
+lore -J mrs -s merged --since 3m -l auth  # Recent auth changes
+lore -J who --overlap src/features/auth/session.rs  # Concurrent work risk
+```
+
+**Gap identified:** No way to check "are there open MRs touching this file right now?" The overlap mode shows historical touches, not active branches. An agent needs to know about in-flight changes to avoid conflicts.
+
+---
+
+### A2. Auto-Triaging an Incoming Issue
+
+**Problem:** Agent receives a new issue and needs to categorize it, find related work, and suggest assignees.
+
+**Flow:**
+```
+lore -J issues 999                        # Read the new issue
+lore -J search "$(extract_keywords)" --explain  # Find similar past issues
+lore -J who src/affected/path/            # Suggest experts as assignees
+lore -J issues -s opened -l same-label    # Check for duplicates
+```
+
+**Gap identified:** No way to get just the description text for programmatic keyword extraction. `issues <iid>` returns full detail including discussions. Agent must parse the full response to extract the description for a secondary search. Would benefit from `--fields description` on detail view. No duplicate detection built in.
+
+---
+
+### A3. Generating Sprint Status Report
+
+**Problem:** Agent needs to produce a weekly status report for the team.
+
+**Flow:**
+```
+lore -J issues -s closed --since 1w --fields minimal  # Completed work
+lore -J issues -s opened --status "In progress"        # In-flight work
+lore -J mrs -s merged --since 1w --fields minimal      # Merged PRs
+lore -J mrs -s opened -D --fields minimal              # Open non-draft MRs
+lore -J count issues                                    # Totals
+lore -J count mrs                                       # MR totals
+lore -J who --active --since 1w                         # Discussions needing attention
+```
+
+**Gap identified:** Seven separate queries for one report. No `lore summary` or `lore report` command. No way to get "issues transitioned from X to Y this week" (state change history exists in events but isn't queryable). No velocity metric (issues closed per week trend).
+
+---
+
+### A4. Finding Relevant Prior Art Before Implementing
+
+**Problem:** Agent is implementing a caching layer and wants to find if similar patterns exist in the codebase's GitLab history.
+
+**Flow:**
+```
+lore -J search "caching" --mode hybrid -n 20 --explain
+lore -J search "cache invalidation" --mode hybrid -n 10
+lore -J search "redis" --mode lexical --type discussion   # Exact term in discussions
+lore -J timeline "cache" --since 1y                        # Wait, max is 1y? Let's try 12m
+```
+
+**Gap identified:** No way to search discussion notes individually (per-note search). Discussions are aggregated into documents, so individual note-level matches are lost. The `--explain` flag helps but doesn't show which specific note matched. No `--since 1y` or `--since 12m` duration format.
+
+---
+
+### A5. Building Context for PR Description
+
+**Problem:** Agent wrote code and needs to generate a PR description that references relevant issues.
+
+**Flow:**
+```
+lore -J search "feature description keywords" --type issue
+lore -J issues -s opened -l feature-label --fields iid,title,web_url
+# Cross-reference: which issues does this MR close?
+# No command for this -- must manually scan search results
+```
+
+**Gap identified:** No way to query the `entity_references` table directly. Agent can't ask "which issues reference MR !456" or "which issues contain 'closes #123' in their text." The data exists but isn't exposed as a query surface. Would benefit from `lore refs --mr 456` or `lore refs --issue 123`.
+
+---
+
+### A6. Identifying Affected Experts for Review Assignment
+
+**Problem:** Agent needs to automatically assign reviewers based on the files changed in an MR.
+
+**Flow:**
+```
+lore -J mrs 456                           # Get MR details
+# Parse file paths from response... but file changes aren't in the output
+lore -J who src/path/from/mr/             # Query each path
+lore -J who src/another/path/             # One at a time...
+lore -J who @candidate --fields minimal   # Check workload
+```
+
+**Gap identified:** MR detail view (`mrs <iid>`) doesn't include the file change list from `mr_file_changes`. Agent can't programmatically extract which files an MR touches. Must fall back to GitLab API or guess from description. The `who` command doesn't accept multiple paths. No "auto-reviewer" suggestion combining expertise + availability.
+
+---
+
+### A7. Incident Investigation and Timeline Reconstruction
+
+**Problem:** Agent needs to reconstruct what happened during an outage for a postmortem.
+
+**Flow:**
+```
+lore -J timeline "outage" --since 3d --depth 2 --expand-mentions
+lore -J search "error 500" --since 3d
+lore -J mrs -s merged --since 3d -p production-service
+lore -J issues --status "In progress" -p production-service
+```
+
+**Gap identified:** Timeline is keyword-seeded, which means if the outage wasn't described with that exact term, seeds may miss it. No way to seed a timeline from an entity ID (e.g., "start from issue #321 and expand outward"). No severity/priority filter. No way to correlate with merge times.
+
+---
+
+### A8. Cross-Project Impact Assessment
+
+**Problem:** Agent needs to understand how a breaking API change in project A affects projects B and C.
+
+**Flow:**
+```
+lore -J search "api-endpoint-name" -p project-a
+lore -J search "api-endpoint-name" -p project-b
+lore -J search "api-endpoint-name" -p project-c
+# Or without project filter to search everywhere:
+lore -J search "api-endpoint-name" -n 50
+lore -J timeline "api-endpoint-name" --depth 2
+```
+
+**Gap identified:** Cross-project references in entity_references are tracked but the timeline shows unresolved references for entities not synced locally. No way to see a cross-project dependency map. Search works across projects but doesn't group results by project.
+
+---
+
+### A9. Automated Stale Issue Recommendations
+
+**Problem:** Agent runs weekly to identify issues that should be closed or re-prioritized.
+
+**Flow:**
+```
+lore -J issues -s opened --sort updated --asc -n 100  # Oldest first
+# For each issue, check:
+lore -J issues <iid>                                    # Read details
+lore -J search "<issue title keywords>"                 # Any recent activity?
+```
+
+**Gap identified:** No `--updated-before` filter, so agent must fetch all and filter client-side. No way to detect "issue has no assignee AND no activity in 90 days." The 100-issue limit means pagination is needed for large backlogs, but there's no cursor/offset pagination -- only `--limit`. Agent must do N+1 queries to inspect each candidate.
+
+---
+
+### A10. Code Review Preparation (File-Level Context)
+
+**Problem:** Agent is reviewing MR !789 and needs to understand the history of each changed file.
+
+**Flow:**
+```
+lore -J mrs 789                           # Get MR details
+# Can't get file list from output...
+# Fall back to search by MR title keywords
+lore -J search "feature-from-mr" --type mr
+lore -J who src/guessed/path/             # Expertise for each file
+lore -J who --overlap src/guessed/path/   # Concurrent changes
+```
+
+**Gap identified:** Same as A6 -- `mr_file_changes` data isn't exposed. Agent is blind to the actual files in the MR unless it parses the description or uses the GitLab API directly. This is the single biggest gap for automated code review workflows.
+
+---
+
+### A11. Building a Knowledge Graph of Entity Relationships
+
+**Problem:** Agent wants to map how issues, MRs, and discussions are connected for a feature.
+
+**Flow:**
+```
+lore -J search "feature-name" -n 30
+lore -J timeline "feature-name" --depth 2 --max-entities 100
+# Timeline shows expanded entities and cross-refs, but...
+# No way to query entity_references directly
+# No way to get "all entities that reference issue #123"
+```
+
+**Gap identified:** The `entity_references` table (closes, related, mentioned) is used internally by timeline but isn't queryable as a standalone command. Agent can't ask "what closes issue #123?" or "what does MR !456 reference?" No graph export. Would enable powerful dependency mapping.
+
+---
+
+### A12. Release Readiness Assessment
+
+**Problem:** Agent needs to verify all issues in milestone "v2.0" are closed and MRs are merged.
+
+**Flow:**
+```
+lore -J issues -m "v2.0" -s opened       # Any open issues in milestone?
+lore -J issues -m "v2.0" -s closed       # Closed issues
+# MRs don't have milestone filter...
+lore -J mrs -s opened -l "v2.0"          # Try label as proxy
+lore -J who --active -p myproject        # Unresolved discussions
+```
+
+**Gap identified:** MRs don't have a `--milestone` filter (issues do). No way to check "all MRs linked to issues in milestone v2.0" -- would require joining `entity_references` with issue milestone. No release checklist concept. No way to verify "every issue in this milestone has a closing MR."
+
+---
+
+### A13. Answering "What Changed?" Between Two Points
+
+**Problem:** Agent needs to diff project state between two dates for a stakeholder report.
+
+**Flow:**
+```
+lore -J issues -s closed --since 2w --fields minimal    # Recently closed
+lore -J issues -s opened --since 2w --fields minimal    # Recently opened
+lore -J mrs -s merged --since 2w --fields minimal       # Recently merged
+# But no way to get "issues that CHANGED STATE" in a window
+# An issue opened 3 months ago but closed yesterday won't appear in --since 2w for issues -s opened
+```
+
+**Gap identified:** `--since` filters by `updated_at`, not by "state changed at." An issue closed yesterday but created 6 months ago would appear in `issues -s closed --since 1d` (because updated_at changed), but the semantics are subtle. No explicit "state transitions in time window" query. The resource_state_events table has this data but it's not exposed as a filter.
+
+---
+
+### A14. Meeting Prep: Summarize Recent Activity for a Stakeholder
+
+**Problem:** Agent needs to prepare a 2-minute summary for a project sponsor meeting.
+
+**Flow:**
+```
+lore -J count issues -p project           # Current totals
+lore -J count mrs -p project              # MR totals
+lore -J issues -s closed --since 1w -p project --fields minimal
+lore -J mrs -s merged --since 1w -p project --fields minimal
+lore -J issues -s opened --status "In progress" -p project
+lore -J who --active -p project --since 1w
+```
+
+**Gap identified:** Six queries, same as A3. No summary/dashboard command. Agent must synthesize all responses. No trend data (is the open issue count growing or shrinking?). No "highlights" extraction.
+
+---
+
+### A15. Determining If Work Is Safe to Start (Conflict Detection)
+
+**Problem:** Agent is about to start work on an issue and needs to check nobody else is already working on it.
+
+**Flow:**
+```
+lore -J issues 123                        # Read the issue
+# Check assignees from response
+lore -J mrs -s opened -A other-person     # Are they working on related MRs?
+lore -J who --overlap src/target/path/    # Anyone actively touching these files?
+lore -J search "issue-123-keywords" --type mr -s opened  # Wait, search has no --state
+```
+
+**Gap identified:** No way to check "is there an open MR that closes issue #123?" -- the entity_references data exists but isn't queryable. Search doesn't support `--state` filter. No "conflict detection" or "in-flight work" check. Agent must do multiple queries and manually correlate.
+
+---
+
+## Part 3: Gap Summary
+
+### Critical Gaps (high impact, blocks common workflows)
+
+| # | Gap | Affected Flows | Suggested Command/Flag |
+|---|-----|----------------|----------------------|
+| 1 | **MR file changes not surfaced** | H4, A6, A10 | `lore mrs <iid> --files` or include in detail view |
+| 2 | **Entity references not queryable** | H7, A5, A11, A15 | `lore refs --issue 123` / `lore refs --mr 456` |
+| 3 | **Per-note search missing** | H7, A4 | `lore search --granularity note` (PRD exists) |
+| 4 | **No entity-based timeline** | H11, A7 | `lore timeline --issue 321` / `lore timeline --mr 456` |
+| 5 | **No @me / current-user alias** | H1, H15 | Resolve from auth token automatically |
+
+### Important Gaps (significant friction, multiple workarounds needed)
+
+| # | Gap | Affected Flows | Suggested Command/Flag |
+|---|-----|----------------|----------------------|
+| 6 | **No activity feed / summary** | H1, A3, A14 | `lore activity --since 1d` or `lore summary` |
+| 7 | **No multi-path who query** | H6, A6 | `lore who src/path1/ src/path2/` |
+| 8 | **No --state filter on search** | H14, A15 | `lore search --state merged` |
+| 9 | **MRs missing --milestone filter** | H9, A12 | `lore mrs -m "v2.0"` |
+| 10 | **No --no-assignee / --unassigned** | H2 | `lore issues --no-assignee` |
+| 11 | **No --updated-before filter** | H10, A9 | `lore issues --before 90d` or `--stale 90d` |
+| 12 | **No team workload view** | H8 | `lore who --team` or `lore workload` |
+
+### Nice-to-Have Gaps (would improve agent efficiency)
+
+| # | Gap | Affected Flows | Suggested Command/Flag |
+|---|-----|----------------|----------------------|
+| 13 | **No pagination/offset** | A9 | `--offset 100` for large result sets |
+| 14 | **No detail --fields on show** | A2 | `lore issues 999 --fields description` |
+| 15 | **No cross-project grouping** | A8 | `lore search --group-by project` |
+| 16 | **No trend/velocity metrics** | A3, A14 | `lore trends issues --period week` |
+| 17 | **No --for-issue on mrs** | A12, A15 | `lore mrs --closes 123` (query entity_refs) |
+| 18 | **1y/12m duration not supported** | A4 | Support `1y`, `12m`, `365d` in --since |
+| 19 | **No discussion participant filter** | H15 | `lore who --active --participant @me` |
+| 20 | **No sort by due date** | H2 | `lore issues --sort due` |

docs/who-command-design.feedback-1.md

@@ -0,0 +1,434 @@
+Below are the highest-leverage revisions I’d make to this plan. I’m focusing on correctness pitfalls, SQLite gotchas, query performance on 280K notes, and reducing “dynamic SQL + param juggling” complexity—without turning this into a new ingestion project.
+
+Change 1 — Fix a hard SQLite bug in --active (GROUP_CONCAT DISTINCT + separator)
+Why
+
+SQLite does not allow GROUP_CONCAT(DISTINCT x, sep). With DISTINCT, SQLite only permits a single argument (GROUP_CONCAT(DISTINCT x)). Your current query will error at runtime in many SQLite versions.
+
+Revision
+
+Use a subquery that selects distinct participants, then GROUP_CONCAT with your separator.
+
+diff
+Copy code
+diff --git a/Plan.md b/Plan.md
+@@ fn query_active(...)
+-            (SELECT GROUP_CONCAT(DISTINCT n.author_username, X'1F')
+-             FROM notes n
+-             WHERE n.discussion_id = d.id
+-               AND n.is_system = 0
+-               AND n.author_username IS NOT NULL) AS participants
++            (SELECT GROUP_CONCAT(username, X'1F') FROM (
++               SELECT DISTINCT n.author_username AS username
++               FROM notes n
++               WHERE n.discussion_id = d.id
++                 AND n.is_system = 0
++                 AND n.author_username IS NOT NULL
++               ORDER BY username
++            )) AS participants
+
+Change 2 — Replace “contains('.') => exact file match” with segment-aware path classification
+Why
+
+path.contains('.') misclassifies directories like:
+
+.github/workflows/
+
+src/v1.2/auth/
+
+It also fails the “root file” case (README.md) because your mode discriminator only treats paths as paths if they contain /.
+
+Revision
+
+Add explicit --path to force Expert mode (covers root files cleanly).
+
+Classify file-vs-dir by checking last path segment for a dot, and whether the input ends with /.
+
+diff
+Copy code
+diff --git a/Plan.md b/Plan.md
+@@ pub struct WhoArgs {
+-    /// Username or file path (path if contains /)
+-    pub target: Option<String>,
++    /// Username or file path shorthand (ambiguous for root files like README.md)
++    pub target: Option<String>,
++
++    /// Force expert mode for a file/directory path (supports root files like README.md)
++    #[arg(long, help_heading = "Mode", conflicts_with_all = ["active", "overlap", "reviews"])]
++    pub path: Option<String>,
+@@ fn resolve_mode<'a>(args: &'a WhoArgs) -> Result<WhoMode<'a>> {
+-    if let Some(target) = &args.target {
++    if let Some(p) = &args.path {
++        return Ok(WhoMode::Expert { path: p });
++    }
++    if let Some(target) = &args.target {
+         let clean = target.strip_prefix('@').unwrap_or(target);
+         if args.reviews {
+             return Ok(WhoMode::Reviews { username: clean });
+         }
+-        // Disambiguation: if target contains '/', it's a file path.
+-        // GitLab usernames never contain '/'.
+-        if target.contains('/') {
++        // Disambiguation:
++        // - treat as path if it contains '/'
++        // - otherwise treat as username (root files require --path)
++        if target.contains('/') {
+             return Ok(WhoMode::Expert { path: target });
+         }
+         return Ok(WhoMode::Workload { username: clean });
+     }
+
+
+And update the path pattern logic used by Expert/Overlap:
+
+diff
+Copy code
+diff --git a/Plan.md b/Plan.md
+@@ fn query_expert(...)
+-    // Normalize path for LIKE matching: add trailing % if no extension
+-    let path_pattern = if path.contains('.') {
+-        path.to_string() // Exact file match
+-    } else {
+-        let trimmed = path.trim_end_matches('/');
+-        format!("{trimmed}/%")
+-    };
++    // Normalize:
++    // - if ends_with('/') => directory prefix
++    // - else if last segment contains '.' => file exact match
++    // - else => directory prefix
++    let trimmed = path.trim_end_matches('/');
++    let last = trimmed.rsplit('/').next().unwrap_or(trimmed);
++    let is_file = !path.ends_with('/') && last.contains('.');
++    let path_pattern = if is_file { trimmed.to_string() } else { format!("{trimmed}/%") };
+
+Change 3 — Stop building dynamic SQL strings for optional filters; always bind params
+Why
+
+Right now you’re mixing:
+
+dynamic project_clause string fragments
+
+ad-hoc param vectors
+
+placeholder renumbering by branch
+
+That’s brittle and easy to regress (especially when you add more conditions later). SQLite/rusqlite can bind Option<T> to NULL, which enables a simple pattern:
+
+sql
+Copy code
+AND (?3 IS NULL OR n.project_id = ?3)
+
+Revision (representative; apply to all queries)
+diff
+Copy code
+diff --git a/Plan.md b/Plan.md
+@@ fn query_expert(...)
+-    let project_clause = if project_id.is_some() {
+-        "AND n.project_id = ?3"
+-    } else {
+-        ""
+-    };
+-
+-    let sql = format!(
++    let sql = format!(
+         "SELECT username, role, activity_count, last_active_at FROM (
+@@
+             FROM notes n
+             WHERE n.position_new_path LIKE ?1
+               AND n.is_system = 0
+               AND n.author_username IS NOT NULL
+               AND n.created_at >= ?2
+-              {project_clause}
++              AND (?3 IS NULL OR n.project_id = ?3)
+@@
+             WHERE n.position_new_path LIKE ?1
+               AND m.author_username IS NOT NULL
+               AND m.updated_at >= ?2
+-              {project_clause}
++              AND (?3 IS NULL OR n.project_id = ?3)
+             GROUP BY m.author_username
+-        )"
++        ) t"
+     );
+-
+-    let mut params: Vec<Box<dyn rusqlite::ToSql>> = Vec::new();
+-    params.push(Box::new(path_pattern.clone()));
+-    params.push(Box::new(since_ms));
+-    if let Some(pid) = project_id {
+-        params.push(Box::new(pid));
+-    }
+-    let param_refs: Vec<&dyn rusqlite::ToSql> = params.iter().map(|p| p.as_ref()).collect();
++    let param_refs = rusqlite::params![path_pattern, since_ms, project_id];
+
+
+Notes:
+
+Adds required derived-table alias t (some SQLite configurations are stricter).
+
+Eliminates the dynamic param vector and placeholder gymnastics.
+
+Change 4 — Filter “path touch” queries to DiffNotes and escape LIKE properly
+Why
+
+Only DiffNotes reliably have position_new_path; including other note types can skew counts and harm performance.
+
+LIKE treats % and _ as wildcards—rare in file paths, but not impossible (generated files, templates). Escaping is a low-cost robustness win.
+
+Revision
+
+Add note_type='DiffNote' and LIKE ... ESCAPE '\' plus a tiny escape helper.
+
+diff
+Copy code
+diff --git a/Plan.md b/Plan.md
+@@ fn query_expert(...)
+-            FROM notes n
+-            WHERE n.position_new_path LIKE ?1
++            FROM notes n
++            WHERE n.note_type = 'DiffNote'
++              AND n.position_new_path LIKE ?1 ESCAPE '\'
+               AND n.is_system = 0
+@@
+diff --git a/Plan.md b/Plan.md
+@@ Helper Functions
++fn escape_like(input: &str) -> String {
++    input.replace('\\', "\\\\").replace('%', "\\%").replace('_', "\\_")
++}
+
+
+And when building patterns:
+
+diff
+Copy code
+-    let path_pattern = if is_file { trimmed.to_string() } else { format!("{trimmed}/%") };
++    let base = escape_like(trimmed);
++    let path_pattern = if is_file { base } else { format!("{base}/%") };
+
+
+Apply the same changes to query_overlap and any other position_new_path LIKE ....
+
+Change 5 — Use note timestamps for “touch since” semantics (Expert/Overlap author branch)
+Why
+
+In Expert/Overlap “author” branches you filter by m.updated_at >= since. That answers “MR updated recently” rather than “MR touched at this path recently”, which can surface stale ownership.
+
+Revision
+
+Filter by the note creation time (and use it for “last touch” where relevant). You can still compute author activity, but anchor it to note activity.
+
+diff
+Copy code
+diff --git a/Plan.md b/Plan.md
+@@ fn query_overlap(...)
+-            WHERE n.position_new_path LIKE ?1
++            WHERE n.note_type = 'DiffNote'
++              AND n.position_new_path LIKE ?1 ESCAPE '\'
+               AND m.state IN ('opened', 'merged')
+               AND m.author_username IS NOT NULL
+-              AND m.updated_at >= ?2
++              AND n.created_at >= ?2
+               AND (?3 IS NULL OR m.project_id = ?3)
+
+
+Same idea in Expert mode’s “MR authors” branch.
+
+Change 6 — Workload mode: apply --since consistently to unresolved discussions
+Why
+
+Workload’s unresolved discussions ignore since_ms. That makes --since partially misleading and can dump very old threads.
+
+Revision
+
+Filter on d.last_note_at when since_ms is set.
+
+diff
+Copy code
+diff --git a/Plan.md b/Plan.md
+@@ fn query_workload(...)
+-    let disc_sql = format!(
++    let disc_since = if since_ms.is_some() {
++        "AND d.last_note_at >= ?2"
++    } else { "" };
++    let disc_sql = format!(
+         "SELECT d.noteable_type,
+@@
+          WHERE d.resolvable = 1 AND d.resolved = 0
+            AND EXISTS (
+@@
+            )
+            {disc_project_filter}
++           {disc_since}
+          ORDER BY d.last_note_at DESC
+          LIMIT {limit}"
+     );
+@@
+-    // Rebuild params for discussion query (only username + optional project_id)
+-    let mut disc_params: Vec<Box<dyn rusqlite::ToSql>> = Vec::new();
+-    disc_params.push(Box::new(username.to_string()));
+-    if let Some(pid) = project_id {
+-        disc_params.push(Box::new(pid));
+-    }
++    // Params: username, since_ms, project_id (NULLs ok)
++    let disc_param_refs = rusqlite::params![username, since_ms, project_id];
+
+
+(If you adopt Change 3 fully, this becomes very clean.)
+
+Change 7 — Make Overlap results represent “both roles” instead of collapsing to one
+Why
+
+Collapsing to a single role loses valuable info (“they authored and reviewed”). Also your current “prefer author” rule is arbitrary for the “who else is touching this” question.
+
+Revision
+
+Track role counts separately and render as A, R, or A+R.
+
+diff
+Copy code
+diff --git a/Plan.md b/Plan.md
+@@ pub struct OverlapUser {
+     pub username: String,
+-    pub role: String,
+-    pub touch_count: u32,
++    pub author_touch_count: u32,
++    pub review_touch_count: u32,
++    pub touch_count: u32,
+     pub last_touch_at: i64,
+     pub mr_iids: Vec<i64>,
+ }
+@@ fn query_overlap(...)
+-        let entry = user_map.entry(username.clone()).or_insert_with(|| OverlapUser {
++        let entry = user_map.entry(username.clone()).or_insert_with(|| OverlapUser {
+             username: username.clone(),
+-            role: role.clone(),
++            author_touch_count: 0,
++            review_touch_count: 0,
+             touch_count: 0,
+             last_touch_at: 0,
+             mr_iids: Vec::new(),
+         });
+         entry.touch_count += count;
++        if role == "author" { entry.author_touch_count += count; }
++        if role == "reviewer" { entry.review_touch_count += count; }
+@@ human output
+-        println!(
+-            "  {:<16} {:<8} {:>7}  {:<12}  {}",
++        println!(
++            "  {:<16} {:<6} {:>7}  {:<12}  {}",
+             ...
+         );
+@@
+-            user.role,
++            format_roles(user.author_touch_count, user.review_touch_count),
+
+Change 8 — Add an “Index Audit + optional migration” step (big perf win, low blast radius)
+Why
+
+With 280K notes, the path/timestamp queries will degrade quickly without indexes. This isn’t “scope creep”; it’s making the feature usable.
+
+Revision (plan-level)
+
+Add a non-breaking migration that only creates indexes if missing.
+
+Optionally add a runtime check: if EXPLAIN QUERY PLAN indicates full table scan on notes, print a dim warning in human mode.
+
+diff
+Copy code
+diff --git a/Plan.md b/Plan.md
+@@ Implementation Order
+-| Step | What | Files |
++| Step | What | Files |
+ | 1 | CLI skeleton: `WhoArgs` + `Commands::Who` + dispatch + stub | `cli/mod.rs`, `commands/mod.rs`, `main.rs` |
++| 1.5 | Index audit + add `CREATE INDEX IF NOT EXISTS` migration for who hot paths | `migrations/0xx_who_indexes.sql` |
+@@
+
+
+Suggested indexes (tune names to your conventions):
+
+notes(note_type, position_new_path, created_at)
+
+notes(discussion_id, is_system, author_username)
+
+discussions(resolvable, resolved, last_note_at, project_id)
+
+merge_requests(project_id, state, updated_at, author_username)
+
+issue_assignees(username, issue_id)
+
+Even if SQLite can’t perfectly index LIKE, these still help with join and timestamp filters.
+
+Change 9 — Make robot JSON reproducible by echoing the effective query inputs
+Why
+
+Agent workflows benefit from a stable “query record”: what mode ran, what path/user, resolved project, effective since, limit.
+
+Revision
+
+Include an input object in JSON output.
+
+diff
+Copy code
+diff --git a/Plan.md b/Plan.md
+@@ struct WhoJsonData {
+     mode: String,
++    input: serde_json::Value,
+     #[serde(flatten)]
+     result: serde_json::Value,
+ }
+@@ pub fn print_who_json(...)
+-    let output = WhoJsonEnvelope {
++    let input = serde_json::json!({
++        "project": /* resolved or raw args.project */,
++        "since": /* resolved since ISO */,
++        "limit": /* args.limit */,
++    });
++    let output = WhoJsonEnvelope {
+         ok: true,
+         data: WhoJsonData {
+             mode: mode.to_string(),
++            input,
+             result: data,
+         },
+         meta: RobotMeta { elapsed_ms },
+     };
+
+Change 10 — Tighten clap constraints so invalid combinations never reach resolve_mode
+Why
+
+Right now conflicts are enforced manually (or not at all). Clamp the invalid combos at the CLI layer:
+
+--active should conflict with target, --overlap, --reviews, --path
+
+--reviews should require a username (and should conflict with Expert path modes)
+
+diff
+Copy code
+diff --git a/Plan.md b/Plan.md
+@@ pub struct WhoArgs {
+-    pub active: bool,
++    #[arg(long, help_heading = "Mode", conflicts_with_all = ["target", "overlap", "reviews", "path"])]
++    pub active: bool,
+@@
+-    pub overlap: Option<String>,
++    #[arg(long, help_heading = "Mode", conflicts_with_all = ["target", "active", "reviews", "path"])]
++    pub overlap: Option<String>,
+@@
+-    pub reviews: bool,
++    #[arg(long, help_heading = "Mode", requires = "target", conflicts_with_all = ["active", "overlap", "path"])]
++    pub reviews: bool,
+
+Summary of what I’d definitely change
+
+If you do nothing else, do these first:
+
+Fix GROUP_CONCAT(DISTINCT ..., sep) in Active mode (runtime error).
+
+Path classification: add --path, and stop using contains('.') globally.
+
+Remove dynamic SQL + param vectors: always bind project_id as nullable and use (? IS NULL OR ...).
+
+Filter to DiffNotes + LIKE escaping for correctness and fewer rows scanned.
+
+Optional index migration: otherwise this will feel slow/non-deterministically slow depending on local DB state.
+
+If you want, I can also provide a consolidated “v2 plan” as a single unified patch (one diff) rather than per-change snippets.

docs/who-command-design.feedback-2.md

@@ -0,0 +1,303 @@
+Below are the highest-leverage revisions I’d make to iteration 1 to tighten correctness, performance, and “agent usefulness” without blowing up scope. For each change: (1) rationale, (2) a focused unified diff against the plan you pasted.
+
+Change 1 — Make robot “input echo” actually resolved (project_id, project_path, since_ms/iso, mode)
+Why
+
+Your Design Principle #5 says the robot envelope should echo resolved inputs (“effective since, resolved project”), but the current input object echoes only raw CLI strings. Agents can’t reliably reproduce or compare runs (e.g., fuzzy project resolution may map differently over time).
+
+This is also a reliability improvement: “what ran” should be computed once and propagated, not recomputed in output.
+
+Plan diff
+diff
+Copy code
+--- a/who-command-design.md
++++ b/who-command-design.md
+@@
+-5. **Robot-first reproducibility.** Robot JSON output includes an `input` object echoing the resolved query parameters (effective since, resolved project, limit) so agents can trace exactly what ran.
++5. **Robot-first reproducibility.** Robot JSON output includes a `resolved_input` object (mode, since_ms + since_iso, resolved project_id + project_path, limit, db_path) so agents can trace exactly what ran.
+
+@@
+-/// Main entry point. Resolves mode from args and dispatches.
+-pub fn run_who(config: &Config, args: &WhoArgs) -> Result<WhoResult> {
++/// Main entry point. Resolves mode + resolved inputs once, then dispatches.
++pub fn run_who(config: &Config, args: &WhoArgs) -> Result<WhoRun> {
+     let db_path = get_db_path(config.storage.db_path.as_deref());
+     let conn = create_connection(&db_path)?;
+ 
+-    let project_id = args
++    let project_id = args
+         .project
+         .as_deref()
+         .map(|p| resolve_project(&conn, p))
+         .transpose()?;
++    let project_path = project_id
++        .map(|id| lookup_project_path(&conn, id))
++        .transpose()?;
+ 
+     let mode = resolve_mode(args)?;
+ 
+     match mode {
+         WhoMode::Expert { path } => {
+             let since_ms = resolve_since(args.since.as_deref(), "6m")?;
+             let result = query_expert(&conn, path, project_id, since_ms, args.limit)?;
+-            Ok(WhoResult::Expert(result))
++            Ok(WhoRun::new("expert", &db_path, project_id, project_path, since_ms, args.limit, WhoResult::Expert(result)))
+         }
+@@
+     }
+ }
++
++/// Wrapper that carries resolved inputs for reproducible output.
++pub struct WhoRun {
++    pub mode: String,
++    pub resolved_input: WhoResolvedInput,
++    pub result: WhoResult,
++}
++
++pub struct WhoResolvedInput {
++    pub db_path: String,
++    pub project_id: Option<i64>,
++    pub project_path: Option<String>,
++    pub since_ms: i64,
++    pub since_iso: String,
++    pub limit: usize,
++}
+@@
+-pub fn print_who_json(result: &WhoResult, args: &WhoArgs, elapsed_ms: u64) {
+-    let (mode, data) = match result {
++pub fn print_who_json(run: &WhoRun, args: &WhoArgs, elapsed_ms: u64) {
++    let (mode, data) = match &run.result {
+         WhoResult::Expert(r) => ("expert", expert_to_json(r)),
+@@
+-    let input = serde_json::json!({
++    let input = serde_json::json!({
+         "target": args.target,
+         "path": args.path,
+         "project": args.project,
+         "since": args.since,
+         "limit": args.limit,
+     });
++
++    let resolved_input = serde_json::json!({
++        "mode": run.mode,
++        "db_path": run.resolved_input.db_path,
++        "project_id": run.resolved_input.project_id,
++        "project_path": run.resolved_input.project_path,
++        "since_ms": run.resolved_input.since_ms,
++        "since_iso": run.resolved_input.since_iso,
++        "limit": run.resolved_input.limit,
++    });
+@@
+-        data: WhoJsonData {
+-            mode: mode.to_string(),
+-            input,
+-            result: data,
+-        },
++        data: WhoJsonData { mode: mode.to_string(), input, resolved_input, result: data },
+         meta: RobotMeta { elapsed_ms },
+     };
+@@
+ struct WhoJsonData {
+     mode: String,
+     input: serde_json::Value,
++    resolved_input: serde_json::Value,
+     #[serde(flatten)]
+     result: serde_json::Value,
+ }
+
+Change 2 — Remove dynamic SQL format!(..LIMIT {limit}) and parameterize LIMIT everywhere
+Why
+
+You explicitly prefer static SQL ((?N IS NULL OR ...)) to avoid subtle bugs; but Workload/Active use format! for LIMIT. Even though limit is typed, it’s an inconsistency that complicates statement caching and encourages future string assembly creep.
+
+SQLite supports LIMIT ? with bound parameters; rusqlite can bind an i64.
+
+Plan diff
+diff
+Copy code
+--- a/who-command-design.md
++++ b/who-command-design.md
+@@
+-    let issues_sql = format!(
+-        "SELECT ... 
+-         ORDER BY i.updated_at DESC
+-         LIMIT {limit}"
+-    );
+-    let mut stmt = conn.prepare(&issues_sql)?;
++    let issues_sql =
++        "SELECT ...
++         ORDER BY i.updated_at DESC
++         LIMIT ?4";
++    let mut stmt = conn.prepare(issues_sql)?;
+     let assigned_issues: Vec<WorkloadIssue> = stmt
+-        .query_map(rusqlite::params![username, project_id, since_ms], |row| {
++        .query_map(rusqlite::params![username, project_id, since_ms, limit as i64], |row| {
+@@
+-    let authored_sql = format!(
+-        "SELECT ...
+-         ORDER BY m.updated_at DESC
+-         LIMIT {limit}"
+-    );
+-    let mut stmt = conn.prepare(&authored_sql)?;
++    let authored_sql =
++        "SELECT ...
++         ORDER BY m.updated_at DESC
++         LIMIT ?4";
++    let mut stmt = conn.prepare(authored_sql)?;
+@@
+-        .query_map(rusqlite::params![username, project_id, since_ms], |row| {
++        .query_map(rusqlite::params![username, project_id, since_ms, limit as i64], |row| {
+@@
+-    let reviewing_sql = format!(
+-        "SELECT ...
+-         ORDER BY m.updated_at DESC
+-         LIMIT {limit}"
+-    );
+-    let mut stmt = conn.prepare(&reviewing_sql)?;
++    let reviewing_sql =
++        "SELECT ...
++         ORDER BY m.updated_at DESC
++         LIMIT ?4";
++    let mut stmt = conn.prepare(reviewing_sql)?;
+@@
+-        .query_map(rusqlite::params![username, project_id, since_ms], |row| {
++        .query_map(rusqlite::params![username, project_id, since_ms, limit as i64], |row| {
+@@
+-    let disc_sql = format!(
+-        "SELECT ...
+-         ORDER BY d.last_note_at DESC
+-         LIMIT {limit}"
+-    );
+-    let mut stmt = conn.prepare(&disc_sql)?;
++    let disc_sql =
++        "SELECT ...
++         ORDER BY d.last_note_at DESC
++         LIMIT ?4";
++    let mut stmt = conn.prepare(disc_sql)?;
+@@
+-        .query_map(rusqlite::params![username, project_id, since_ms], |row| {
++        .query_map(rusqlite::params![username, project_id, since_ms, limit as i64], |row| {
+@@
+-    let sql = format!(
+-        "SELECT ...
+-         ORDER BY d.last_note_at DESC
+-         LIMIT {limit}"
+-    );
+-    let mut stmt = conn.prepare(&sql)?;
++    let sql =
++        "SELECT ...
++         ORDER BY d.last_note_at DESC
++         LIMIT ?3";
++    let mut stmt = conn.prepare(sql)?;
+@@
+-        .query_map(rusqlite::params![since_ms, project_id], |row| {
++        .query_map(rusqlite::params![since_ms, project_id, limit as i64], |row| {
+
+Change 3 — Fix path matching for dotless files (LICENSE/Makefile) via “exact OR prefix” (no new flags)
+Why
+
+Your improved “dot only in last segment” heuristic still fails on dotless files (LICENSE, Makefile, Dockerfile) which are common, especially at repo root. Right now they’ll be treated as directories (LICENSE/%) and silently return nothing.
+
+Best minimal UX: if user provides a path that’s ambiguous (no trailing slash), match either exact file OR directory prefix.
+
+Plan diff
+diff
+Copy code
+--- a/who-command-design.md
++++ b/who-command-design.md
+@@
+-/// Build a LIKE pattern from a user-supplied path, with proper LIKE escaping.
+-///
+-/// Rules:
+-/// - If the path ends with `/`, it's a directory prefix → `escaped_path%`
+-/// - If the last path segment contains `.`, it's a file → exact match
+-/// - Otherwise, it's a directory prefix → `escaped_path/%`
++/// Build an exact + prefix match from a user-supplied path, with proper LIKE escaping.
++///
++/// Rules:
++/// - If the path ends with `/`, treat as directory-only (prefix match)
++/// - Otherwise, treat as ambiguous: exact match OR directory prefix
++///   (fixes dotless files like LICENSE/Makefile without requiring new flags)
+@@
+-fn build_path_pattern(path: &str) -> String {
++struct PathMatch {
++    exact: String,
++    prefix: String,
++    dir_only: bool,
++}
++
++fn build_path_match(path: &str) -> PathMatch {
+     let trimmed = path.trim_end_matches('/');
+-    let last_segment = trimmed.rsplit('/').next().unwrap_or(trimmed);
+-    let is_file = !path.ends_with('/') && last_segment.contains('.');
+     let escaped = escape_like(trimmed);
+-
+-    if is_file {
+-        escaped
+-    } else {
+-        format!("{escaped}/%")
+-    }
++    PathMatch {
++        exact: escaped.clone(),
++        prefix: format!("{escaped}/%"),
++        dir_only: path.ends_with('/'),
++    }
+ }
+@@
+-    let path_pattern = build_path_pattern(path);
++    let pm = build_path_match(path);
+@@
+-              AND n.position_new_path LIKE ?1 ESCAPE '\\'
++              AND (
++                    (?4 = 1 AND n.position_new_path LIKE ?2 ESCAPE '\\')
++                 OR (?4 = 0 AND (n.position_new_path = ?1 OR n.position_new_path LIKE ?2 ESCAPE '\\'))
++              )
+@@
+-    let rows: Vec<(String, String, u32, i64)> = stmt
+-        .query_map(rusqlite::params![path_pattern, since_ms, project_id], |row| {
++    let rows: Vec<(String, String, u32, i64)> = stmt
++        .query_map(rusqlite::params![pm.exact, pm.prefix, since_ms, i32::from(pm.dir_only), project_id], |row| {
+             Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?))
+         })?
+
+
+(Apply the same pattern to Overlap mode.)
+
+Change 4 — Consistently exclude system notes in all DiffNote-based branches (Expert/Overlap author branches currently don’t)
+Why
+
+You filter n.is_system = 0 for reviewer branches, but not in the author branches of Expert/Overlap. That can skew “author touch” via system-generated diff notes or bot activity.
+
+Consistency here improves correctness and also enables more aggressive partial indexing.
+
+Plan diff
+diff
+Copy code
+--- a/who-command-design.md
++++ b/who-command-design.md
+@@
+-            WHERE n.note_type = 'DiffNote'
++            WHERE n.note_type = 'DiffNote'
+               AND n.position_new_path LIKE ?1 ESCAPE '\\'
++              AND n.is_system = 0
+               AND m.author_username IS NOT NULL
+               AND n.created_at >= ?2
+               AND (?3 IS NULL OR m.project_id = ?3)
+@@
+-            WHERE n.note_type = 'DiffNote'
++            WHERE n.note_type = 'DiffNote'
+               AND n.position_new_path LIKE ?1 ESCAPE '\\'
++              AND n.is_system = 0
+               AND m.state IN ('opened', 'merged')
+               AND m.author_username IS NOT NULL
+               AND n.created_at >= ?2
+               AND (?3 IS NULL OR m.project_id = ?3)
+
+Change 5 — Rework Migration 017 indexes to match real predicates + add one critical notes index for discussion participation
+Why
+
+(a) idx_notes_diffnote_path_created currently leads with note_type even though it’s constant via partial index. You want the leading columns to match your most selective predicates: position_new_path prefix + created_at range, with optional project_id.
+
+(b) Active + Workload discussion participation repeatedly hits notes by (discussion_id, author_username); you only guarantee notes(discussion_id) is indexed. Adding a narrow partial composite index pays off immediately for both “participants” and “EXISTS user participated” checks.
+
+(c) The discussions index should focus on (project_id, last_note_at) with a partial predicate; resolvable/resolved a_

docs/who-command-design.feedback-3.md

@@ -0,0 +1,471 @@
+Below are the revisions I’d make to iteration 2 to improve correctness, determinism, query-plan quality, and multi-project usability without turning this into a bigger product.
+
+I’m treating your plan as the “source of truth” and showing git-diff style patches against the plan text/code blocks you included.
+
+Change 1 — Fix project scoping to hit the right index (DiffNote branches)
+Why
+
+Your hot-path index is:
+
+idx_notes_diffnote_path_created ON notes(position_new_path, created_at, project_id) WHERE note_type='DiffNote' AND is_system=0
+
+But in Expert/Overlap you sometimes scope by m.project_id = ?3 (MR table), not n.project_id = ?3 (notes table). That weakens the optimizer’s ability to use the composite notes index (and can force broader joins before filtering).
+
+Diff
+diff
+Copy code
+--- a/who-command-design.md
++++ b/who-command-design.md
+@@ Query: Expert Mode @@
+-              AND (?3 IS NULL OR m.project_id = ?3)
++              -- IMPORTANT: scope on notes.project_id to maximize use of
++              -- idx_notes_diffnote_path_created (notes is the selective table)
++              AND (?3 IS NULL OR n.project_id = ?3)
+
+@@ Query: Overlap Mode @@
+-              AND (?3 IS NULL OR m.project_id = ?3)
++              AND (?3 IS NULL OR n.project_id = ?3)
+
+@@ Query: Overlap Mode (author branch) @@
+-              AND (?3 IS NULL OR m.project_id = ?3)
++              AND (?3 IS NULL OR n.project_id = ?3)
+
+Change 2 — Introduce a “prefix vs exact” path query to avoid LIKE when you don’t need it
+Why
+
+For exact file paths (e.g. src/auth/login.rs), you currently do:
+
+position_new_path LIKE ?1 ESCAPE '\' where ?1 has no wildcard
+
+That’s logically fine, but it’s a worse signal to the planner than = and can degrade performance depending on collation/case settings.
+
+This doesn’t violate “static SQL” — you can pick between two static query strings.
+
+Diff
+diff
+Copy code
+--- a/who-command-design.md
++++ b/who-command-design.md
+@@ Helper: Path Pattern Construction @@
+-fn build_path_pattern(path: &str) -> String {
++struct PathQuery {
++    /// The parameter value to bind.
++    value: String,
++    /// If true: use LIKE value || '%'. If false: use '='.
++    is_prefix: bool,
++}
++
++fn build_path_query(path: &str) -> PathQuery {
+     let trimmed = path.trim_end_matches('/');
+     let last_segment = trimmed.rsplit('/').next().unwrap_or(trimmed);
+     let is_file = !path.ends_with('/') && last_segment.contains('.');
+     let escaped = escape_like(trimmed);
+ 
+     if is_file {
+-        escaped
++        PathQuery { value: escaped, is_prefix: false }
+     } else {
+-        format!("{escaped}/%")
++        PathQuery { value: format!("{escaped}/%"), is_prefix: true }
+     }
+ }
+
+
+And then (example for DiffNote predicates):
+
+diff
+Copy code
+@@ Query: Expert Mode @@
+-    let path_pattern = build_path_pattern(path);
++    let pq = build_path_query(path);
+
+-    let sql = " ... n.position_new_path LIKE ?1 ESCAPE '\\' ... ";
++    let sql_prefix = " ... n.position_new_path LIKE ?1 ESCAPE '\\' ... ";
++    let sql_exact  = " ... n.position_new_path = ?1 ... ";
+
+-    let mut stmt = conn.prepare(sql)?;
++    let mut stmt = if pq.is_prefix { conn.prepare_cached(sql_prefix)? }
++                   else { conn.prepare_cached(sql_exact)? };
+     let rows = stmt.query_map(params![... pq.value ...], ...);
+
+Change 3 — Push Expert aggregation into SQL (less Rust, fewer rows, SQL-level LIMIT)
+Why
+
+Right now Expert does:
+
+UNION ALL
+
+return per-role rows
+
+HashMap merge
+
+score compute
+
+sort/truncate
+
+You can do all of that in SQL deterministically, then LIMIT ?N actually works.
+
+Diff
+diff
+Copy code
+--- a/who-command-design.md
++++ b/who-command-design.md
+@@ Query: Expert Mode @@
+-    let sql = "SELECT username, role, activity_count, last_active_at FROM (
+-            ...
+-        )";
++    let sql = "
++      WITH activity AS (
++        SELECT
++          n.author_username AS username,
++          'reviewer' AS role,
++          COUNT(*) AS cnt,
++          MAX(n.created_at) AS last_active_at
++        FROM notes n
++        WHERE n.note_type = 'DiffNote'
++          AND n.is_system = 0
++          AND n.author_username IS NOT NULL
++          AND n.created_at >= ?2
++          AND (?3 IS NULL OR n.project_id = ?3)
++          AND (
++            (?4 = 1 AND n.position_new_path LIKE ?1 ESCAPE '\\') OR
++            (?4 = 0 AND n.position_new_path = ?1)
++          )
++        GROUP BY n.author_username
++
++        UNION ALL
++
++        SELECT
++          m.author_username AS username,
++          'author' AS role,
++          COUNT(DISTINCT m.id) AS cnt,
++          MAX(n.created_at) AS last_active_at
++        FROM merge_requests m
++        JOIN discussions d ON d.merge_request_id = m.id
++        JOIN notes n ON n.discussion_id = d.id
++        WHERE n.note_type = 'DiffNote'
++          AND n.is_system = 0
++          AND m.author_username IS NOT NULL
++          AND n.created_at >= ?2
++          AND (?3 IS NULL OR n.project_id = ?3)
++          AND (
++            (?4 = 1 AND n.position_new_path LIKE ?1 ESCAPE '\\') OR
++            (?4 = 0 AND n.position_new_path = ?1)
++          )
++        GROUP BY m.author_username
++      )
++      SELECT
++        username,
++        SUM(CASE WHEN role='reviewer' THEN cnt ELSE 0 END) AS review_count,
++        SUM(CASE WHEN role='author' THEN cnt ELSE 0 END) AS author_count,
++        MAX(last_active_at) AS last_active_at,
++        (SUM(CASE WHEN role='reviewer' THEN cnt ELSE 0 END) * 3.0) +
++        (SUM(CASE WHEN role='author' THEN cnt ELSE 0 END) * 2.0) AS score
++      FROM activity
++      GROUP BY username
++      ORDER BY score DESC, last_active_at DESC, username ASC
++      LIMIT ?5
++    ";
+
+-    // Aggregate by username: combine reviewer + author counts
+-    let mut user_map: HashMap<...> = HashMap::new();
+-    ...
+-    experts.sort_by(...); experts.truncate(limit);
++    // No Rust-side merge/sort needed; SQL already returns final rows.
+
+Change 4 — Overlap output is ambiguous across projects: include stable MR refs (project_path!iid)
+Why
+
+mr_iids: Vec<i64> is ambiguous in a multi-project DB. !123 only means something with a project.
+
+Also: your MR IID dedup is currently Vec.contains() inside a loop (O(n²)). Use a HashSet.
+
+Diff
+diff
+Copy code
+--- a/who-command-design.md
++++ b/who-command-design.md
+@@ OverlapResult @@
+ pub struct OverlapUser {
+     pub username: String,
+@@
+-    pub mr_iids: Vec<i64>,
++    /// Stable MR references like "group/project!123"
++    pub mr_refs: Vec<String>,
+ }
+
+@@ Query: Overlap Mode (SQL) @@
+-                GROUP_CONCAT(DISTINCT m.iid) AS mr_iids
++                GROUP_CONCAT(DISTINCT (p.path_with_namespace || '!' || m.iid)) AS mr_refs
+             FROM notes n
+             JOIN discussions d ON n.discussion_id = d.id
+             JOIN merge_requests m ON d.merge_request_id = m.id
++            JOIN projects p ON m.project_id = p.id
+@@
+-                GROUP_CONCAT(DISTINCT m.iid) AS mr_iids
++                GROUP_CONCAT(DISTINCT (p.path_with_namespace || '!' || m.iid)) AS mr_refs
+             FROM merge_requests m
+             JOIN discussions d ON d.merge_request_id = m.id
+             JOIN notes n ON n.discussion_id = d.id
++            JOIN projects p ON m.project_id = p.id
+
+@@ Query: Overlap Mode (Rust merge) @@
+-    let mr_iids: Vec<i64> = mr_iids_csv ...
++    let mr_refs: Vec<String> = mr_refs_csv
++      .as_deref()
++      .map(|csv| csv.split(',').map(|s| s.trim().to_string()).collect())
++      .unwrap_or_default();
+@@
+-        // Merge MR IIDs, deduplicate
+-        for iid in &mr_iids {
+-            if !entry.mr_iids.contains(iid) {
+-                entry.mr_iids.push(*iid);
+-            }
+-        }
++        // Merge MR refs, deduplicate
++        use std::collections::HashSet;
++        let mut set: HashSet<String> = entry.mr_refs.drain(..).collect();
++        for r in mr_refs { set.insert(r); }
++        entry.mr_refs = set.into_iter().collect();
+
+Change 5 — Active mode: avoid correlated subqueries by preselecting discussions, then aggregating notes once
+Why
+
+Your Active query does two correlated subqueries per discussion row:
+
+note_count
+
+participants
+
+With LIMIT 20 it’s not catastrophic, but it is still unnecessary work and creates “spiky” behavior if the planner chooses poorly.
+
+Pattern to use:
+
+CTE selects the limited set of discussions
+
+Join notes once, aggregate with GROUP BY
+
+Diff
+diff
+Copy code
+--- a/who-command-design.md
++++ b/who-command-design.md
+@@ Query: Active Mode @@
+-    let sql =
+-        "SELECT
+-            d.noteable_type,
+-            ...
+-            (SELECT COUNT(*) FROM notes n
+-             WHERE n.discussion_id = d.id AND n.is_system = 0) AS note_count,
+-            (SELECT GROUP_CONCAT(username, X'1F') FROM (
+-               SELECT DISTINCT n.author_username AS username
+-               FROM notes n
+-               WHERE n.discussion_id = d.id
+-                 AND n.is_system = 0
+-                 AND n.author_username IS NOT NULL
+-               ORDER BY username
+-            )) AS participants
+-         FROM discussions d
+-         ...
+-         LIMIT ?3";
++    let sql = "
++      WITH picked AS (
++        SELECT d.id, d.noteable_type, d.issue_id, d.merge_request_id, d.project_id, d.last_note_at
++        FROM discussions d
++        WHERE d.resolvable = 1 AND d.resolved = 0
++          AND d.last_note_at >= ?1
++          AND (?2 IS NULL OR d.project_id = ?2)
++        ORDER BY d.last_note_at DESC
++        LIMIT ?3
++      ),
++      note_agg AS (
++        SELECT
++          n.discussion_id,
++          COUNT(*) AS note_count,
++          GROUP_CONCAT(n.author_username, X'1F') AS participants
++        FROM (
++          SELECT DISTINCT discussion_id, author_username
++          FROM notes
++          WHERE is_system = 0 AND author_username IS NOT NULL
++        ) n
++        JOIN picked p ON p.id = n.discussion_id
++        GROUP BY n.discussion_id
++      )
++      SELECT
++        p.noteable_type,
++        COALESCE(i.iid, m.iid) AS entity_iid,
++        COALESCE(i.title, m.title) AS entity_title,
++        proj.path_with_namespace,
++        p.last_note_at,
++        COALESCE(na.note_count, 0) AS note_count,
++        COALESCE(na.participants, '') AS participants
++      FROM picked p
++      JOIN projects proj ON p.project_id = proj.id
++      LEFT JOIN issues i ON p.issue_id = i.id
++      LEFT JOIN merge_requests m ON p.merge_request_id = m.id
++      LEFT JOIN note_agg na ON na.discussion_id = p.id
++      ORDER BY p.last_note_at DESC
++    ";
+
+Change 6 — Use prepare_cached() everywhere (cheap perf win, no scope creep)
+Why
+
+You already worked hard to keep SQL static. Taking advantage of sqlite statement caching completes the loop.
+
+Diff
+diff
+Copy code
+--- a/who-command-design.md
++++ b/who-command-design.md
+@@ Query functions @@
+-    let mut stmt = conn.prepare(sql)?;
++    let mut stmt = conn.prepare_cached(sql)?;
+
+
+Apply in all query fns (query_workload, query_reviews, query_active, query_expert, query_overlap, lookup_project_path).
+
+Change 7 — Human output: show project_path where ambiguity exists (Workload + Overlap)
+Why
+
+When not project-scoped, #42 and !100 aren’t unique. You already have project paths in the query results — you’re just not printing them.
+
+Diff
+diff
+Copy code
+--- a/who-command-design.md
++++ b/who-command-design.md
+@@ print_workload_human @@
+-            println!(
+-                "    {} {}  {}",
++            println!(
++                "    {} {}  {}  {}",
+                 style(format!("#{:<5}", item.iid)).cyan(),
+                 truncate_str(&item.title, 45),
+                 style(format_relative_time(item.updated_at)).dim(),
++                style(&item.project_path).dim(),
+             );
+
+@@ print_workload_human (MRs) @@
+-            println!(
+-                "    {} {}{}  {}",
++            println!(
++                "    {} {}{}  {}  {}",
+                 style(format!("!{:<5}", mr.iid)).cyan(),
+                 truncate_str(&mr.title, 40),
+                 style(draft).dim(),
+                 style(format_relative_time(mr.updated_at)).dim(),
++                style(&mr.project_path).dim(),
+             );
+
+@@ print_overlap_human @@
+-        let mr_str = user.mr_iids.iter().take(5).map(|iid| format!("!{iid}")).collect::<Vec<_>>().join(", ");
++        let mr_str = user.mr_refs.iter().take(5).cloned().collect::<Vec<_>>().join(", ");
+
+Change 8 — Robot JSON: add stable IDs + “defaulted” flags for reproducibility
+Why
+
+You already added resolved_input — good. Two more reproducibility gaps remain:
+
+Agents can’t reliably “open” an entity without IDs (discussion_id, mr_id, issue_id).
+
+Agents can’t tell whether since was user-provided vs defaulted (important when replaying intent).
+
+Diff
+diff
+Copy code
+--- a/who-command-design.md
++++ b/who-command-design.md
+@@ WhoResolvedInput @@
+ pub struct WhoResolvedInput {
+@@
+     pub since_ms: Option<i64>,
+     pub since_iso: Option<String>,
++    pub since_was_default: bool,
+     pub limit: usize,
+ }
+
+@@ run_who @@
+-            let since_ms = resolve_since(args.since.as_deref(), "6m")?;
++            let since_was_default = args.since.is_none();
++            let since_ms = resolve_since(args.since.as_deref(), "6m")?;
+             Ok(WhoRun {
+                 resolved_input: WhoResolvedInput {
+@@
+                     since_ms: Some(since_ms),
+                     since_iso: Some(ms_to_iso(since_ms)),
++                    since_was_default,
+                     limit: args.limit,
+                 },
+
+@@ print_who_json resolved_input @@
+     let resolved_input = serde_json::json!({
+@@
+         "since_ms": run.resolved_input.since_ms,
+         "since_iso": run.resolved_input.since_iso,
++        "since_was_default": run.resolved_input.since_was_default,
+         "limit": run.resolved_input.limit,
+     });
+
+
+And for Active/Workload discussion items, add IDs in SQL and JSON:
+
+diff
+Copy code
+@@ ActiveDiscussion @@
+ pub struct ActiveDiscussion {
++    pub discussion_id: i64,
+@@
+ }
+
+@@ query_active SELECT @@
+-      SELECT
+-        p.noteable_type,
++      SELECT
++        p.id AS discussion_id,
++        p.noteable_type,
+
+@@ active_to_json @@
+-        "discussions": r.discussions.iter().map(|d| json!({
++        "discussions": r.discussions.iter().map(|d| json!({
++            "discussion_id": d.discussion_id,
+             ...
+         }))
+
+Change 9 — Make performance verification explicit: require EXPLAIN QUERY PLAN checks for each mode
+Why
+
+You’re adding indexes specifically for these queries. The only way to ensure the planner is doing what you think is to lock in a short perf checklist (especially after schema drift or SQLite version differences).
+
+Diff
+diff
+Copy code
+--- a/who-command-design.md
++++ b/who-command-design.md
+@@ Verification @@
+ # Manual verification against real data
+ cargo run --release -- who src/features/global-search/
+@@
+ cargo run --release -- who src/features/global-search/ -p typescript  # project scoped
++
++# Perf verification (required before merge):
++# Confirm idx_notes_diffnote_path_created is used for Expert/Overlap and
++# idx_discussions_unresolved_recent is used for Active.
++sqlite3 path/to/db.sqlite "
++  EXPLAIN QUERY PLAN
++  SELECT ... -- paste final Expert SQL with representative bindings
++";
+
+
+(Keep it lightweight: one representative query per mode is enough.)
+
+Net effect
+
+Correctness: project scoping hits the notes index; IDs added for agent workflows.
+
+Performance: fewer rows/materialization in Expert; statement caching everywhere; Active avoids correlated subqueries.
+
+UX: human output no longer ambiguous across projects; Overlap MR references become actionable.
+
+Reproducibility: agents can distinguish defaults vs explicit inputs; can dereference entities reliably.
+
+If you want one “highest ROI” subset to implement first: Change 1 + Change 4 + Change 6 + Change 7. That’s where the real operational value lands.

docs/who-command-design.feedback-4.md

@@ -0,0 +1,3 @@
+ChatGPT said:
+Proposing code revisions for performance and determinism
+Answer now

docs/who-command-design.feedback-5.md

@@ -0,0 +1,356 @@
+Below are the highest-leverage revisions I’d make. They’re tightly scoped (no new tables/APIs), but fix a few real correctness issues and make the outputs more actionable.
+
+1) Fix a correctness bug in PathQuery: don’t escape for =, and make --path Makefile actually work
+Why
+
+Bug: build_path_query() currently runs escape_like() even when is_prefix = false (exact match). That will break exact matches for paths containing _, %, or \ because = does not treat those as metacharacters (so the escaped string won’t equal the stored path).
+
+UX mismatch: The plan says --path handles dotless root files (Makefile/LICENSE), but the current logic still treats them as directory prefixes (Makefile/%) → zero results.
+
+Change
+
+Only escape for LIKE.
+
+Treat root paths (no /) passed via --path as exact matches by default (unless they end with /).
+
+diff
+Copy code
+diff --git a/plan.md b/plan.md
+@@
+-/// Build a path query from a user-supplied path.
+-///
+-/// Rules:
+-/// - If the path ends with `/`, it's a directory prefix -> `escaped_path%` (LIKE)
+-/// - If the last path segment contains `.`, it's a file -> exact match (=)
+-/// - Otherwise, it's a directory prefix -> `escaped_path/%` (LIKE)
++/// Build a path query from a user-supplied path.
++///
++/// Rules:
++/// - If the path ends with `/`, it's a directory prefix -> `escaped_path/%` (LIKE)
++/// - If the path is a root path (no `/`) and does NOT end with `/`, treat as exact (=)
++///   (this makes `--path Makefile` and `--path LICENSE` work as intended)
++/// - Else if the last path segment contains `.`, treat as exact (=)
++/// - Otherwise, treat as directory prefix -> `escaped_path/%` (LIKE)
+@@
+-fn build_path_query(path: &str) -> PathQuery {
++fn build_path_query(path: &str) -> PathQuery {
+     let trimmed = path.trim_end_matches('/');
+     let last_segment = trimmed.rsplit('/').next().unwrap_or(trimmed);
+-    let is_file = !path.ends_with('/') && last_segment.contains('.');
+-    let escaped = escape_like(trimmed);
++    let is_root = !trimmed.contains('/');
++    let is_file = !path.ends_with('/') && (is_root || last_segment.contains('.'));
+ 
+     if is_file {
+         PathQuery {
+-            value: escaped,
++            // IMPORTANT: do NOT escape for exact match (=)
++            value: trimmed.to_string(),
+             is_prefix: false,
+         }
+     } else {
++        let escaped = escape_like(trimmed);
+         PathQuery {
+             value: format!("{escaped}/%"),
+             is_prefix: true,
+         }
+     }
+ }
+@@
+-/// **Known limitation:** Dotless root files (LICENSE, Makefile, Dockerfile)
+-/// without a trailing `/` will be treated as directory prefixes. Use `--path`
+-/// for these — the `--path` flag passes through to Expert mode directly,
+-/// and the `build_path_query` output for "LICENSE" is a prefix `LICENSE/%`
+-/// which will simply return zero results (a safe, obvious failure mode that the
+-/// help text addresses).
++/// Note: Root file paths passed via `--path` (including dotless files like Makefile/LICENSE)
++/// are treated as exact matches unless they end with `/`.
+
+
+Also update the --path help text to be explicit:
+
+diff
+Copy code
+diff --git a/plan.md b/plan.md
+@@
+-    /// Force expert mode for a file/directory path (handles root files like
+-    /// README.md, LICENSE, Makefile that lack a / and can't be auto-detected)
++    /// Force expert mode for a file/directory path.
++    /// Root files (README.md, LICENSE, Makefile) are treated as exact matches.
++    /// Use a trailing `/` to force directory-prefix matching.
+
+2) Fix Active mode: your note_count is currently counting participants, and the CTE scans too broadly
+Why
+
+In note_agg, you do SELECT DISTINCT discussion_id, author_username and then COUNT(*) AS note_count. That’s participant count, not note count.
+
+The current note_agg also builds the DISTINCT set from all notes then joins to picked. It’s avoidable work.
+
+Change
+
+Split into two aggregations scoped to picked:
+
+note_counts: counts non-system notes per picked discussion.
+
+participants: distinct usernames per picked discussion, then GROUP_CONCAT.
+
+diff
+Copy code
+diff --git a/plan.md b/plan.md
+@@
+-        note_agg AS (
+-            SELECT
+-                n.discussion_id,
+-                COUNT(*) AS note_count,
+-                GROUP_CONCAT(n.author_username, X'1F') AS participants
+-            FROM (
+-                SELECT DISTINCT discussion_id, author_username
+-                FROM notes
+-                WHERE is_system = 0 AND author_username IS NOT NULL
+-            ) n
+-            JOIN picked p ON p.id = n.discussion_id
+-            GROUP BY n.discussion_id
+-        )
++        note_counts AS (
++            SELECT
++                n.discussion_id,
++                COUNT(*) AS note_count
++            FROM notes n
++            JOIN picked p ON p.id = n.discussion_id
++            WHERE n.is_system = 0
++            GROUP BY n.discussion_id
++        ),
++        participants AS (
++            SELECT
++                x.discussion_id,
++                GROUP_CONCAT(x.author_username, X'1F') AS participants
++            FROM (
++                SELECT DISTINCT n.discussion_id, n.author_username
++                FROM notes n
++                JOIN picked p ON p.id = n.discussion_id
++                WHERE n.is_system = 0 AND n.author_username IS NOT NULL
++            ) x
++            GROUP BY x.discussion_id
++        )
+@@
+-        LEFT JOIN note_agg na ON na.discussion_id = p.id
++        LEFT JOIN note_counts nc ON nc.discussion_id = p.id
++        LEFT JOIN participants pa ON pa.discussion_id = p.id
+@@
+-            COALESCE(na.note_count, 0) AS note_count,
+-            COALESCE(na.participants, '') AS participants
++            COALESCE(nc.note_count, 0) AS note_count,
++            COALESCE(pa.participants, '') AS participants
+
+
+Net effect: correctness fix + more predictable perf.
+
+Add a test that would have failed before:
+
+diff
+Copy code
+diff --git a/plan.md b/plan.md
+@@
+     #[test]
+     fn test_active_query() {
+@@
+-        insert_diffnote(&conn, 1, 1, 1, "reviewer_b", "src/foo.rs", "needs work");
++        insert_diffnote(&conn, 1, 1, 1, "reviewer_b", "src/foo.rs", "needs work");
++        insert_diffnote(&conn, 2, 1, 1, "reviewer_b", "src/foo.rs", "follow-up");
+@@
+-        assert_eq!(result.discussions[0].participants, vec!["reviewer_b"]);
++        assert_eq!(result.discussions[0].participants, vec!["reviewer_b"]);
++        assert_eq!(result.discussions[0].note_count, 2);
+
+3) Index fix: idx_discussions_unresolved_recent won’t help global --active ordering
+Why
+
+Your index is (project_id, last_note_at) with WHERE resolvable=1 AND resolved=0.
+
+When --active is not project-scoped (common default), SQLite can’t use (project_id, last_note_at) to satisfy ORDER BY last_note_at DESC efficiently because project_id isn’t constrained.
+
+This can turn into a scan+sort over potentially large unresolved sets.
+
+Change
+
+Keep the project-scoped index, but add a global ordering index (partial, still small):
+
+diff
+Copy code
+diff --git a/plan.md b/plan.md
+@@
+ CREATE INDEX IF NOT EXISTS idx_discussions_unresolved_recent
+     ON discussions(project_id, last_note_at)
+     WHERE resolvable = 1 AND resolved = 0;
++
++-- Active (global): unresolved discussions by recency (no project scope).
++-- Supports ORDER BY last_note_at DESC LIMIT N when project_id is unconstrained.
++CREATE INDEX IF NOT EXISTS idx_discussions_unresolved_recent_global
++    ON discussions(last_note_at)
++    WHERE resolvable = 1 AND resolved = 0;
+
+4) Make Overlap “touches” coherent: count MRs for reviewers, not DiffNotes
+Why
+
+Overlap’s question is “Who else has MRs touching my files?” but:
+
+reviewer branch uses COUNT(*) (DiffNotes)
+
+author branch uses COUNT(DISTINCT m.id) (MRs)
+
+Those are different units; summing them into touch_count is misleading.
+
+Change
+
+Count distinct MRs on the reviewer branch too:
+
+diff
+Copy code
+diff --git a/plan.md b/plan.md
+@@
+-                COUNT(*) AS touch_count,
++                COUNT(DISTINCT m.id) AS touch_count,
+                 MAX(n.created_at) AS last_touch_at,
+                 GROUP_CONCAT(DISTINCT (p.path_with_namespace || '!' || m.iid)) AS mr_refs
+
+
+Also update human output labeling:
+
+diff
+Copy code
+diff --git a/plan.md b/plan.md
+@@
+-        style("Touches").bold(),
++        style("MRs").bold(),
+
+
+(You still preserve “strength” via mr_refs and last_touch_at.)
+
+5) Make outputs more actionable: add a canonical ref field (group/project!iid, group/project#iid)
+Why
+
+You already do this for Overlap (mr_refs). Doing the same for Workload and Active reduces friction for both humans and agents:
+
+humans can copy/paste a single token
+
+robots don’t need to stitch project_path + iid + prefix
+
+Change (Workload structs + SQL)
+diff
+Copy code
+diff --git a/plan.md b/plan.md
+@@
+ pub struct WorkloadIssue {
+     pub iid: i64,
++    pub ref_: String,
+     pub title: String,
+     pub project_path: String,
+     pub updated_at: i64,
+ }
+@@
+ pub struct WorkloadMr {
+     pub iid: i64,
++    pub ref_: String,
+     pub title: String,
+     pub draft: bool,
+     pub project_path: String,
+@@
+-    let issues_sql =
+-        "SELECT i.iid, i.title, p.path_with_namespace, i.updated_at
++    let issues_sql =
++        "SELECT i.iid,
++                (p.path_with_namespace || '#' || i.iid) AS ref,
++                i.title, p.path_with_namespace, i.updated_at
+@@
+-                iid: row.get(0)?,
+-                title: row.get(1)?,
+-                project_path: row.get(2)?,
+-                updated_at: row.get(3)?,
++                iid: row.get(0)?,
++                ref_: row.get(1)?,
++                title: row.get(2)?,
++                project_path: row.get(3)?,
++                updated_at: row.get(4)?,
+             })
+@@
+-    let authored_sql =
+-        "SELECT m.iid, m.title, m.draft, p.path_with_namespace, m.updated_at
++    let authored_sql =
++        "SELECT m.iid,
++                (p.path_with_namespace || '!' || m.iid) AS ref,
++                m.title, m.draft, p.path_with_namespace, m.updated_at
+@@
+-                iid: row.get(0)?,
+-                title: row.get(1)?,
+-                draft: row.get::<_, i32>(2)? != 0,
+-                project_path: row.get(3)?,
++                iid: row.get(0)?,
++                ref_: row.get(1)?,
++                title: row.get(2)?,
++                draft: row.get::<_, i32>(3)? != 0,
++                project_path: row.get(4)?,
+                 author_username: None,
+-                updated_at: row.get(4)?,
++                updated_at: row.get(5)?,
+             })
+
+
+Then use ref_ in human output + robot JSON.
+
+6) Reviews mode: tolerate leading whitespace before **prefix**
+Why
+
+Many people write " **suggestion**: ...". Current LIKE '**%**%' misses that.
+
+Change
+
+Use ltrim(n.body) consistently:
+
+diff
+Copy code
+diff --git a/plan.md b/plan.md
+@@
+-           AND n.body LIKE '**%**%'
++           AND ltrim(n.body) LIKE '**%**%'
+@@
+-            SUBSTR(n.body, 3, INSTR(SUBSTR(n.body, 3), '**') - 1) AS raw_prefix,
++            SUBSTR(ltrim(n.body), 3, INSTR(SUBSTR(ltrim(n.body), 3), '**') - 1) AS raw_prefix,
+
+7) Add two small tests that catch the above regressions
+Why
+
+These are exactly the kind of issues that slip through without targeted tests.
+
+diff
+Copy code
+diff --git a/plan.md b/plan.md
+@@
+     #[test]
+     fn test_escape_like() {
+@@
+     }
++
++    #[test]
++    fn test_build_path_query_exact_does_not_escape() {
++        // '_' must not be escaped for '='
++        let pq = build_path_query("README_with_underscore.md");
++        assert_eq!(pq.value, "README_with_underscore.md");
++        assert!(!pq.is_prefix);
++    }
++
++    #[test]
++    fn test_path_flag_dotless_root_file_is_exact() {
++        let pq = build_path_query("Makefile");
++        assert_eq!(pq.value, "Makefile");
++        assert!(!pq.is_prefix);
++    }
+
+Summary of net effect
+
+Correctness fixes: exact-path escaping bug; Active.note_count bug.
+
+Perf fixes: global --active index; avoid broad note scans in Active.
+
+Usefulness upgrades: coherent overlap “touch” metric; canonical refs everywhere; reviews prefix more robust.
+
+If you want one extra “stretch” that still isn’t scope creep: add an unscoped warning line in human output when project_id == None (e.g., “Aggregated across projects; use -p to scope”) for Expert/Overlap/Active. That’s pure presentation, but prevents misinterpretation in multi-project DBs.

docs/who-command-design.feedback-6.md

@@ -0,0 +1,471 @@
+Proposed revisions (Iteration 6)
+
+Below are the highest-leverage changes I’d make on top of your current Iteration 5 plan, with rationale and git-diff style edits to the plan text/snippets.
+
+1) Fix a real edge case: dotless non-root files (src/Dockerfile, infra/Makefile, etc.)
+Why
+
+Your current build_path_query() treats dotless last segments as directories (prefix match) unless the path is root. That misclassifies legitimate dotless files inside directories and silently produces path/% (zero hits or wrong hits).
+
+Best minimal fix: keep your static SQL approach, but add a DB existence probe (static SQL) for path queries:
+
+If user didn’t force directory (/), and exact path exists in DiffNotes, treat as exact =.
+
+Otherwise use prefix LIKE 'dir/%'.
+
+This avoids new CLI flags, avoids heuristics lists, and uses your existing partial index (idx_notes_diffnote_path_created) efficiently.
+
+Diff
+diff
+Copy code
+diff --git a/Plan.md b/Plan.md
+@@
+-struct PathQuery {
++struct PathQuery {
+     /// The parameter value to bind.
+     value: String,
+     /// If true: use `LIKE value ESCAPE '\'`. If false: use `= value`.
+     is_prefix: bool,
+ }
+ 
+-/// Build a path query from a user-supplied path.
++/// Build a path query from a user-supplied path, with a DB probe for dotless files.
+@@
+-fn build_path_query(path: &str) -> PathQuery {
++fn build_path_query(conn: &Connection, path: &str) -> Result<PathQuery> {
+     let trimmed = path.trim_end_matches('/');
+     let last_segment = trimmed.rsplit('/').next().unwrap_or(trimmed);
+     let is_root = !trimmed.contains('/');
+-    let is_file = !path.ends_with('/') && (is_root || last_segment.contains('.'));
++    let forced_dir = path.ends_with('/');
++    let looks_like_file = !forced_dir && (is_root || last_segment.contains('.'));
++
++    // If it doesn't "look like a file" but the exact path exists in DiffNotes,
++    // treat as exact (handles src/Dockerfile, infra/Makefile, etc.).
++    let exact_exists = if !looks_like_file && !forced_dir {
++        conn.query_row(
++            "SELECT 1
++             FROM notes
++             WHERE note_type = 'DiffNote'
++               AND is_system = 0
++               AND position_new_path = ?1
++             LIMIT 1",
++            rusqlite::params![trimmed],
++            |_| Ok(()),
++        ).is_ok()
++    } else {
++        false
++    };
++
++    let is_file = looks_like_file || exact_exists;
+ 
+     if is_file {
+         PathQuery {
+             value: trimmed.to_string(),
+             is_prefix: false,
+         }
+     } else {
+         let escaped = escape_like(trimmed);
+         PathQuery {
+             value: format!("{escaped}/%"),
+             is_prefix: true,
+         }
+     }
+ }
+
+
+Also update callers:
+
+diff
+Copy code
+@@
+-    let pq = build_path_query(path);
++    let pq = build_path_query(conn, path)?;
+@@
+-    let pq = build_path_query(path);
++    let pq = build_path_query(conn, path)?;
+
+
+And tests:
+
+diff
+Copy code
+@@
+-    fn test_build_path_query() {
++    fn test_build_path_query() {
+@@
+-        // Dotless root file -> exact match (root path without '/')
++        // Dotless root file -> exact match (root path without '/')
+         let pq = build_path_query("Makefile");
+         assert_eq!(pq.value, "Makefile");
+         assert!(!pq.is_prefix);
++
++        // Dotless file in subdir should become exact if DB contains it (probe)
++        // (set up: insert one DiffNote with position_new_path = "src/Dockerfile")
+
+2) Make “reviewer” semantics correct: exclude MR authors commenting on their own diffs
+Why
+
+Right now, Overlap (and Expert reviewer branch) will count MR authors as “reviewers” if they leave DiffNotes in their own MR (clarifications / replies), inflating A+R and contaminating “who reviewed here” signals.
+
+You already enforce this in --reviews mode (m.author_username != ?1). Apply the same principle consistently:
+
+Reviewer branch: only count notes where n.author_username != m.author_username (when both non-NULL).
+
+Diff (Overlap reviewer branch)
+diff
+Copy code
+@@
+-            WHERE n.note_type = 'DiffNote'
++            WHERE n.note_type = 'DiffNote'
+               AND n.position_new_path LIKE ?1 ESCAPE '\\'
+               AND n.is_system = 0
+               AND n.author_username IS NOT NULL
++              AND (m.author_username IS NULL OR n.author_username != m.author_username)
+               AND n.created_at >= ?2
+               AND (?3 IS NULL OR n.project_id = ?3)
+
+
+Same change for sql_exact.
+
+3) Expert mode scoring: align units + reduce single-MR “comment storms”
+Why
+
+Expert currently mixes units:
+
+reviewer side: DiffNote count
+
+author side: distinct MR count
+
+That makes score noisy and can crown “someone who wrote 30 comments on one MR” as top expert.
+
+Fix: make both sides primarily MR-breadth:
+
+reviewer: COUNT(DISTINCT m.id) as review_mr_count
+
+author: COUNT(DISTINCT m.id) as author_mr_count
+Optionally keep review_note_count as a secondary intensity signal (but not the main driver).
+
+Diff (types + SQL)
+diff
+Copy code
+@@
+ pub struct Expert {
+     pub username: String,
+-    pub score: f64,
+-    pub review_count: u32,
+-    pub author_count: u32,
++    pub score: i64,
++    pub review_mr_count: u32,
++    pub review_note_count: u32,
++    pub author_mr_count: u32,
+     pub last_active_ms: i64,
+ }
+
+
+Reviewer branch now joins to MR so it can count distinct MRs and exclude self-comments:
+
+diff
+Copy code
+@@
+-            SELECT
+-                n.author_username AS username,
+-                'reviewer' AS role,
+-                COUNT(*) AS cnt,
+-                MAX(n.created_at) AS last_active_at
+-            FROM notes n
++            SELECT
++                n.author_username AS username,
++                'reviewer' AS role,
++                COUNT(DISTINCT m.id) AS mr_cnt,
++                COUNT(*) AS note_cnt,
++                MAX(n.created_at) AS last_active_at
++            FROM notes n
++            JOIN discussions d ON n.discussion_id = d.id
++            JOIN merge_requests m ON d.merge_request_id = m.id
+             WHERE n.note_type = 'DiffNote'
+               AND n.is_system = 0
+               AND n.author_username IS NOT NULL
++              AND (m.author_username IS NULL OR n.author_username != m.author_username)
+               AND n.position_new_path LIKE ?1 ESCAPE '\\'
+               AND n.created_at >= ?2
+               AND (?3 IS NULL OR n.project_id = ?3)
+             GROUP BY n.author_username
+
+
+Update author branch payload to match shape:
+
+diff
+Copy code
+@@
+             SELECT
+                 m.author_username AS username,
+                 'author' AS role,
+-                COUNT(DISTINCT m.id) AS cnt,
++                COUNT(DISTINCT m.id) AS mr_cnt,
++                0 AS note_cnt,
+                 MAX(n.created_at) AS last_active_at
+
+
+Aggregate:
+
+diff
+Copy code
+@@
+         SELECT
+             username,
+-            SUM(CASE WHEN role = 'reviewer' THEN cnt ELSE 0 END) AS review_count,
+-            SUM(CASE WHEN role = 'author' THEN cnt ELSE 0 END) AS author_count,
++            SUM(CASE WHEN role = 'reviewer' THEN mr_cnt ELSE 0 END) AS review_mr_count,
++            SUM(CASE WHEN role = 'reviewer' THEN note_cnt ELSE 0 END) AS review_note_count,
++            SUM(CASE WHEN role = 'author' THEN mr_cnt ELSE 0 END) AS author_mr_count,
+             MAX(last_active_at) AS last_active_at,
+-            (SUM(CASE WHEN role = 'reviewer' THEN cnt ELSE 0 END) * 3.0) +
+-            (SUM(CASE WHEN role = 'author' THEN cnt ELSE 0 END) * 2.0) AS score
++            (
++              (SUM(CASE WHEN role = 'reviewer' THEN mr_cnt ELSE 0 END) * 20) +
++              (SUM(CASE WHEN role = 'author' THEN mr_cnt ELSE 0 END) * 12) +
++              (SUM(CASE WHEN role = 'reviewer' THEN note_cnt ELSE 0 END) * 1)
++            ) AS score
+
+
+Human header:
+
+diff
+Copy code
+@@
+-        style("Reviews").bold(),
+-        style("Authored").bold(),
++        style("Reviewed(MRs)").bold(),
++        style("Notes").bold(),
++        style("Authored(MRs)").bold(),
+
+4) Deterministic output: participants + MR refs + tie-breakers
+Why
+
+You’ve correctly focused on reproducibility (resolved_input), but you still have nondeterministic lists:
+
+participants: GROUP_CONCAT order is undefined → vector order changes run-to-run.
+
+mr_refs: you dedup via HashSet then iterate → undefined order.
+
+user sorting in overlap is missing stable tie-breakers.
+
+This is a real “robot mode flake” source.
+
+Diff (Active participants sort)
+diff
+Copy code
+@@
+-            let participants: Vec<String> = participants_csv
++            let mut participants: Vec<String> = participants_csv
+                 .as_deref()
+                 .filter(|s| !s.is_empty())
+                 .map(|csv| csv.split('\x1F').map(String::from).collect())
+                 .unwrap_or_default();
++            participants.sort(); // stable, deterministic
+
+Diff (Overlap MR refs sort + stable user sort)
+diff
+Copy code
+@@
+-    users.sort_by(|a, b| b.touch_count.cmp(&a.touch_count));
++    users.sort_by(|a, b| {
++        b.touch_count.cmp(&a.touch_count)
++            .then_with(|| b.last_touch_at.cmp(&a.last_touch_at))
++            .then_with(|| a.username.cmp(&b.username))
++    });
+@@
+-        entry.mr_refs = set.into_iter().collect();
++        let mut v: Vec<String> = set.into_iter().collect();
++        v.sort();
++        entry.mr_refs = v;
+
+5) Make --limit actionable: surface truncation explicitly (human + robot)
+Why
+
+Agents (and humans) need to know if results were cut off so they can rerun with a bigger -n.
+Right now there’s no signal.
+
+Minimal pattern: query limit + 1, set truncated = true if you got > limit, then truncate.
+
+Diff (result types)
+diff
+Copy code
+@@
+ pub struct ExpertResult {
+     pub path_query: String,
+     pub experts: Vec<Expert>,
++    pub truncated: bool,
+ }
+@@
+ pub struct ActiveResult {
+     pub discussions: Vec<ActiveDiscussion>,
+     pub total_unresolved: u32,
++    pub truncated: bool,
+ }
+@@
+ pub struct OverlapResult {
+     pub path_query: String,
+     pub users: Vec<OverlapUser>,
++    pub truncated: bool,
+ }
+
+Diff (query pattern example)
+diff
+Copy code
+@@
+-    let limit_i64 = limit as i64;
++    let limit_plus_one = (limit + 1) as i64;
+@@
+-        LIMIT ?4
++        LIMIT ?4
+@@
+-            rusqlite::params![pq.value, since_ms, project_id, limit_i64],
++            rusqlite::params![pq.value, since_ms, project_id, limit_plus_one],
+@@
+-    Ok(ExpertResult {
++    let truncated = experts.len() > limit;
++    let experts = experts.into_iter().take(limit).collect();
++    Ok(ExpertResult {
+         path_query: path.to_string(),
+         experts,
++        truncated,
+     })
+
+
+Human output hint:
+
+diff
+Copy code
+@@
+     if r.experts.is_empty() { ... }
++    if r.truncated {
++        println!("  {}", style("(showing first -n; rerun with a higher --limit)").dim());
++    }
+
+
+Robot output field:
+
+diff
+Copy code
+@@
+ fn expert_to_json(r: &ExpertResult) -> serde_json::Value {
+     serde_json::json!({
+         "path_query": r.path_query,
++        "truncated": r.truncated,
+         "experts": ...
+     })
+ }
+
+6) Overlap merge hot loop: avoid repeated HashSet rebuild per row
+Why
+
+This line is expensive in a UNION result with many rows:
+
+rust
+Copy code
+let mut set: HashSet<String> = entry.mr_refs.drain(..).collect();
+
+
+It reallocates and rehashes every time.
+
+Fix: store an accumulator with HashSet during merge, convert once at end.
+
+Diff (internal accumulator)
+diff
+Copy code
+@@
+-    let mut user_map: HashMap<String, OverlapUser> = HashMap::new();
++    struct OverlapAcc {
++        username: String,
++        author_touch_count: u32,
++        review_touch_count: u32,
++        touch_count: u32,
++        last_touch_at: i64,
++        mr_refs: HashSet<String>,
++    }
++    let mut user_map: HashMap<String, OverlapAcc> = HashMap::new();
+@@
+-        let entry = user_map.entry(username.clone()).or_insert_with(|| OverlapUser {
++        let entry = user_map.entry(username.clone()).or_insert_with(|| OverlapAcc {
+             username: username.clone(),
+             author_touch_count: 0,
+             review_touch_count: 0,
+             touch_count: 0,
+             last_touch_at: 0,
+-            mr_refs: Vec::new(),
++            mr_refs: HashSet::new(),
+         });
+@@
+-        let mut set: HashSet<String> = entry.mr_refs.drain(..).collect();
+-        for r in mr_refs { set.insert(r); }
+-        entry.mr_refs = set.into_iter().collect();
++        for r in mr_refs { entry.mr_refs.insert(r); }
+@@
+-    let mut users: Vec<OverlapUser> = user_map.into_values().collect();
++    let mut users: Vec<OverlapUser> = user_map.into_values().map(|a| {
++        let mut mr_refs: Vec<String> = a.mr_refs.into_iter().collect();
++        mr_refs.sort();
++        OverlapUser {
++            username: a.username,
++            author_touch_count: a.author_touch_count,
++            review_touch_count: a.review_touch_count,
++            touch_count: a.touch_count,
++            last_touch_at: a.last_touch_at,
++            mr_refs,
++        }
++    }).collect();
+
+7) Tests to lock these behaviors
+Add tests (high value)
+
+dotless subdir file uses DB probe → exact match
+
+self-review exclusion prevents MR author showing up as reviewer
+
+deterministic ordering for participants and mr_refs (sort)
+
+Diff (test additions outline)
+diff
+Copy code
+@@
+     #[test]
++    fn test_build_path_query_dotless_subdir_file_uses_probe() {
++        let conn = setup_test_db();
++        insert_project(&conn, 1, "team/backend");
++        insert_mr(&conn, 1, 1, 100, "author_a", "opened");
++        insert_discussion(&conn, 1, 1, Some(1), None, true, false);
++        insert_diffnote(&conn, 1, 1, 1, "reviewer_b", "src/Dockerfile", "note");
++
++        let pq = build_path_query(&conn, "src/Dockerfile").unwrap();
++        assert_eq!(pq.value, "src/Dockerfile");
++        assert!(!pq.is_prefix);
++    }
++
++    #[test]
++    fn test_overlap_excludes_self_review_notes() {
++        let conn = setup_test_db();
++        insert_project(&conn, 1, "team/backend");
++        insert_mr(&conn, 1, 1, 100, "author_a", "opened");
++        insert_discussion(&conn, 1, 1, Some(1), None, true, false);
++        // author_a comments on their own MR diff
++        insert_diffnote(&conn, 1, 1, 1, "author_a", "src/auth/login.rs", "clarification");
++
++        let result = query_overlap(&conn, "src/auth/", None, 0, 20).unwrap();
++        let u = result.users.iter().find(|u| u.username == "author_a");
++        // should not be credited as reviewer touch
++        assert!(u.map(|x| x.review_touch_count).unwrap_or(0) == 0);
++    }
+
+Net effect
+
+Correctness: fixes dotless subdir files + self-review pollution.
+
+Signal quality: Expert ranking becomes harder to game by comment volume.
+
+Robot reproducibility: deterministic ordering + explicit truncation.
+
+Performance: avoids rehash loops in overlap merges; path probe uses indexed equality.
+
+If you want one “single best” change: #1 (DB probe exact-match) is the most likely to prevent confusing “why is this empty?” behavior without adding any user-facing complexity.

docs/who-command-design.feedback-7.md

@@ -0,0 +1,353 @@
+Below are the highest-leverage revisions I’d make to iteration 6 to improve correctness (multi-project edge cases), robot-mode reliability (bounded payloads + truncation), and signal quality—without changing the fundamental scope (still pure SQL over existing tables).
+
+1) Make build_path_query project-aware and two-way probe (exact and prefix)
+Why
+
+Your DB probe currently answers: “does this exact file exist anywhere in DiffNotes?” That can misclassify in a project-scoped run:
+
+Path exists as a dotless file in Project A → probe returns true
+
+User runs -p Project B where the path is a directory (or different shape) → you switch to exact, return empty, and miss valid prefix hits.
+
+Also, you still have a minor heuristic fragility for dot directories when the user omits trailing / (e.g., .github/workflows): last segment has a dot → you treat as file unless forced dir.
+
+Revision
+
+Thread project_id into build_path_query(conn, path, project_id)
+
+Probe exact first (scoped), then probe prefix (scoped)
+
+Only fall back to heuristics if both probes fail
+
+This keeps “static SQL, no dynamic assembly,” and costs at most 2 indexed existence queries per invocation.
+
+diff
+Copy code
+diff --git a/who-command-design.md b/who-command-design.md
+@@
+- fn build_path_query(conn: &Connection, path: &str) -> Result<PathQuery> {
++ fn build_path_query(conn: &Connection, path: &str, project_id: Option<i64>) -> Result<PathQuery> {
+     let trimmed = path.trim_end_matches('/');
+     let last_segment = trimmed.rsplit('/').next().unwrap_or(trimmed);
+     let is_root = !trimmed.contains('/');
+     let forced_dir = path.ends_with('/');
+-    let looks_like_file = !forced_dir && (is_root || last_segment.contains('.'));
++    // Heuristic is now only a fallback; probes decide first.
++    let looks_like_file = !forced_dir && (is_root || last_segment.contains('.'));
+ 
+-    let exact_exists = if !looks_like_file && !forced_dir {
+-        conn.query_row(
+-            "SELECT 1 FROM notes
+-             WHERE note_type = 'DiffNote'
+-               AND is_system = 0
+-               AND position_new_path = ?1
+-             LIMIT 1",
+-            rusqlite::params![trimmed],
+-            |_| Ok(()),
+-        )
+-        .is_ok()
+-    } else {
+-        false
+-    };
++    // Probe 1: exact file exists (scoped)
++    let exact_exists = conn.query_row(
++        "SELECT 1 FROM notes
++         WHERE note_type = 'DiffNote'
++           AND is_system = 0
++           AND position_new_path = ?1
++           AND (?2 IS NULL OR project_id = ?2)
++         LIMIT 1",
++        rusqlite::params![trimmed, project_id],
++        |_| Ok(()),
++    ).is_ok();
++
++    // Probe 2: directory prefix exists (scoped)
++    let prefix_exists = if !forced_dir {
++        let escaped = escape_like(trimmed);
++        let pat = format!("{escaped}/%");
++        conn.query_row(
++            "SELECT 1 FROM notes
++             WHERE note_type = 'DiffNote'
++               AND is_system = 0
++               AND position_new_path LIKE ?1 ESCAPE '\\'
++               AND (?2 IS NULL OR project_id = ?2)
++             LIMIT 1",
++            rusqlite::params![pat, project_id],
++            |_| Ok(()),
++        ).is_ok()
++    } else { false };
+ 
+-    let is_file = looks_like_file || exact_exists;
++    // Forced directory always wins; otherwise: exact > prefix > heuristic
++    let is_file = if forced_dir { false }
++                  else if exact_exists { true }
++                  else if prefix_exists { false }
++                  else { looks_like_file };
+ 
+     if is_file {
+         Ok(PathQuery { value: trimmed.to_string(), is_prefix: false })
+     } else {
+         let escaped = escape_like(trimmed);
+         Ok(PathQuery { value: format!("{escaped}/%"), is_prefix: true })
+     }
+ }
+@@
+- let pq = build_path_query(conn, path)?;
++ let pq = build_path_query(conn, path, project_id)?;
+
+
+Add test coverage for the multi-project misclassification case:
+
+diff
+Copy code
+diff --git a/who-command-design.md b/who-command-design.md
+@@
+     #[test]
+     fn test_build_path_query_dotless_subdir_file_uses_db_probe() {
+@@
+-        let pq = build_path_query(&conn, "src/Dockerfile").unwrap();
++        let pq = build_path_query(&conn, "src/Dockerfile", None).unwrap();
+@@
+-        let pq2 = build_path_query(&conn2, "src/Dockerfile").unwrap();
++        let pq2 = build_path_query(&conn2, "src/Dockerfile", None).unwrap();
+     }
++
++    #[test]
++    fn test_build_path_query_probe_is_project_scoped() {
++        // Path exists as a dotless file in project 1; project 2 should not
++        // treat it as an exact file unless it exists there too.
++        let conn = setup_test_db();
++        insert_project(&conn, 1, "team/a");
++        insert_project(&conn, 2, "team/b");
++        insert_mr(&conn, 1, 1, 10, "author_a", "opened");
++        insert_discussion(&conn, 1, 1, Some(1), None, true, false);
++        insert_diffnote(&conn, 1, 1, 1, "rev", "infra/Makefile", "note");
++
++        let pq_scoped = build_path_query(&conn, "infra/Makefile", Some(2)).unwrap();
++        assert!(pq_scoped.is_prefix); // should fall back to prefix in project 2
++    }
+
+2) Bound robot payload sizes for participants and mr_refs (with totals + truncation)
+Why
+
+mr_refs and participants can become unbounded arrays in robot mode, which is a real operational hazard:
+
+huge JSON → slow, noisy diffs, brittle downstream pipelines
+
+potential SQLite group_concat truncation becomes invisible (and you can’t distinguish “no refs” vs “refs truncated”)
+
+Revision
+
+Introduce hard caps and explicit metadata:
+
+participants_total, participants_truncated
+
+mr_refs_total, mr_refs_truncated
+
+This is not scope creep—it’s defensive output hygiene.
+
+diff
+Copy code
+diff --git a/who-command-design.md b/who-command-design.md
+@@
+ pub struct ActiveDiscussion {
+@@
+     pub participants: Vec<String>,
++    pub participants_total: u32,
++    pub participants_truncated: bool,
+ }
+@@
+ pub struct OverlapUser {
+@@
+     pub mr_refs: Vec<String>,
++    pub mr_refs_total: u32,
++    pub mr_refs_truncated: bool,
+ }
+
+
+Implementation sketch (Rust-side, deterministic):
+
+diff
+Copy code
+diff --git a/who-command-design.md b/who-command-design.md
+@@
+ fn query_active(...) -> Result<ActiveResult> {
++    const MAX_PARTICIPANTS: usize = 50;
+@@
+-            participants.sort();
++            participants.sort();
++            let participants_total = participants.len() as u32;
++            let participants_truncated = participants.len() > MAX_PARTICIPANTS;
++            if participants_truncated {
++                participants.truncate(MAX_PARTICIPANTS);
++            }
+@@
+             Ok(ActiveDiscussion {
+@@
+                 participants,
++                participants_total,
++                participants_truncated,
+             })
+@@
+ fn query_overlap(...) -> Result<OverlapResult> {
++    const MAX_MR_REFS_PER_USER: usize = 50;
+@@
+         .map(|a| {
+             let mut mr_refs: Vec<String> = a.mr_refs.into_iter().collect();
+             mr_refs.sort();
++            let mr_refs_total = mr_refs.len() as u32;
++            let mr_refs_truncated = mr_refs.len() > MAX_MR_REFS_PER_USER;
++            if mr_refs_truncated {
++                mr_refs.truncate(MAX_MR_REFS_PER_USER);
++            }
+             OverlapUser {
+@@
+                 mr_refs,
++                mr_refs_total,
++                mr_refs_truncated,
+             }
+         })
+
+
+Update robot JSON accordingly:
+
+diff
+Copy code
+diff --git a/who-command-design.md b/who-command-design.md
+@@
+ fn active_to_json(r: &ActiveResult) -> serde_json::Value {
+@@
+             "participants": d.participants,
++            "participants_total": d.participants_total,
++            "participants_truncated": d.participants_truncated,
+         }))
+@@
+ fn overlap_to_json(r: &OverlapResult) -> serde_json::Value {
+@@
+             "mr_refs": u.mr_refs,
++            "mr_refs_total": u.mr_refs_total,
++            "mr_refs_truncated": u.mr_refs_truncated,
+         }))
+
+
+Also update robot-docs manifest schema snippet for who.active.discussions[] and who.overlap.users[].
+
+3) Add truncation metadata to Workload sections (same LIMIT+1 pattern)
+Why
+
+Workload is the mode most likely to be consumed by agents, and right now it has silent truncation (each section is LIMIT N with no signal). Your plan already treats truncation as a first-class contract elsewhere; Workload should match.
+
+Revision
+
+For each workload query:
+
+request LIMIT + 1
+
+set *_truncated booleans
+
+trim to requested limit
+
+diff
+Copy code
+diff --git a/who-command-design.md b/who-command-design.md
+@@
+ pub struct WorkloadResult {
+     pub username: String,
+     pub assigned_issues: Vec<WorkloadIssue>,
+     pub authored_mrs: Vec<WorkloadMr>,
+     pub reviewing_mrs: Vec<WorkloadMr>,
+     pub unresolved_discussions: Vec<WorkloadDiscussion>,
++    pub assigned_issues_truncated: bool,
++    pub authored_mrs_truncated: bool,
++    pub reviewing_mrs_truncated: bool,
++    pub unresolved_discussions_truncated: bool,
+ }
+
+
+And in JSON include the booleans (plus you already have summary.counts).
+
+This is mechanically repetitive but extremely valuable for automation.
+
+4) Rename “Last Active” → “Last Seen” for Expert/Overlap
+Why
+
+For “author” rows, the timestamp is derived from review activity on their MR (via MAX(n.created_at)), not necessarily that person’s direct action. Calling that “active” is semantically misleading. “Last seen” is accurate across both reviewer+author branches.
+
+diff
+Copy code
+diff --git a/who-command-design.md b/who-command-design.md
+@@
+ pub struct Expert {
+@@
+-    pub last_active_ms: i64,
++    pub last_seen_ms: i64,
+ }
+@@
+ pub struct OverlapUser {
+@@
+-    pub last_touch_at: i64,
++    pub last_seen_at: i64,
+@@
+ fn print_expert_human(...) {
+@@
+-        style("Last Active").bold(),
++        style("Last Seen").bold(),
+@@
+-        style(format_relative_time(expert.last_active_ms)).dim(),
++        style(format_relative_time(expert.last_seen_ms)).dim(),
+
+
+(Keep internal SQL aliases consistent: last_seen_at everywhere.)
+
+5) Make MR state filtering consistent in Expert/Overlap reviewer branches
+Why
+
+You already restrict Overlap author branch to opened|merged, but reviewer branches can include closed/unmerged noise. Consistency improves signal quality and can reduce scan churn.
+
+Low-risk revision: apply the same state filter to reviewer branches (Expert + Overlap). You can keep “closed” excluded by default without adding new flags.
+
+diff
+Copy code
+diff --git a/who-command-design.md b/who-command-design.md
+@@
+ WHERE n.note_type = 'DiffNote'
+   AND n.is_system = 0
+@@
+-  AND n.created_at >= ?2
++  AND m.state IN ('opened','merged')
++  AND n.created_at >= ?2
+
+
+This is a semantic choice; if you later want archaeology across closed/unmerged, that belongs in a separate mode/flag, but I would not add it now.
+
+6) Add a design principle for bounded outputs (aligns with robot-first reproducibility)
+diff
+Copy code
+diff --git a/who-command-design.md b/who-command-design.md
+@@
+ 10. **Truncation transparency.** Result types carry a `truncated: bool` flag...
++11. **Bounded payloads.** Robot JSON must never emit unbounded arrays (participants, refs).
++    Large list fields are capped with `*_total` + `*_truncated` so agents can page/retry.
+
+Consolidated plan metadata bump (Iteration 7)
+diff
+Copy code
+diff --git a/who-command-design.md b/who-command-design.md
+@@
+-iteration: 6
++iteration: 7
+ updated: 2026-02-07
+
+Net effect (what you get)
+
+Correct path classification under -p scoping (no cross-project probe leakage)
+
+Deterministic + bounded robot payloads (no giant JSON surprises)
+
+Uniform truncation contract across all modes (Workload no longer silently truncates)
+
+Clearer semantics (“Last Seen” avoids misinterpretation)
+
+Cleaner signals (reviewer branches ignore closed/unmerged by default)
+
+If you want, I can also produce a second diff that updates the robot-docs schema block and the Verification EXPLAIN expectations to reflect the new probe queries and the state filter.

docs/who-command-design.feedback-8.md

@@ -0,0 +1,552 @@
+Below are the highest-leverage revisions I’d make for iteration 8, staying within your MVP constraints (static SQL, no scope creep into new data sources), but tightening correctness, index utilization predictability, debuggability, and output safety.
+
+1) Fix the semantic bug in since_was_default (Workload mode) by introducing since_mode
+Why this is better
+
+Right now since_was_default = args.since.is_none() is misleading for Workload, because Workload has no default window (it’s “unbounded unless explicitly filtered”). In robot mode, this creates incorrect intent replay and ambiguity.
+
+Replace the boolean with a tri-state:
+
+since_mode: "default" | "explicit" | "none"
+
+Keep since_was_default only if you want backward compatibility, but compute it as since_mode == "default".
+
+Patch
+diff
+Copy code
+diff --git a/who-command-design.md b/who-command-design.md
+--- a/who-command-design.md
++++ b/who-command-design.md
+@@
+-5. **Robot-first reproducibility.** Robot JSON output includes both a raw `input` object (echoing CLI args) and a `resolved_input` object (computed `since_ms`, `since_iso`, `since_was_default`, resolved `project_id` + `project_path`, effective `mode`, `limit`) so agents can trace exactly what ran and reproduce it precisely.
++5. **Robot-first reproducibility.** Robot JSON output includes both a raw `input` object (echoing CLI args) and a `resolved_input` object (computed `since_ms`, `since_iso`, `since_mode`, resolved `project_id` + `project_path`, effective `mode`, `limit`) so agents can trace exactly what ran and reproduce it precisely.
+@@
+ pub struct WhoResolvedInput {
+     pub mode: String,
+     pub project_id: Option<i64>,
+     pub project_path: Option<String>,
+     pub since_ms: Option<i64>,
+     pub since_iso: Option<String>,
+-    pub since_was_default: bool,
++    /// "default" (mode default applied), "explicit" (user provided --since), "none" (no window)
++    pub since_mode: String,
+     pub limit: usize,
+ }
+@@
+-    let since_was_default = args.since.is_none();
++    // since_mode semantics:
++    // - expert/reviews/active/overlap: default window applies if args.since is None
++    // - workload: no default window; args.since None => "none"
++    let since_mode_for_defaulted = if args.since.is_some() { "explicit" } else { "default" };
++    let since_mode_for_workload  = if args.since.is_some() { "explicit" } else { "none" };
+@@
+         WhoMode::Expert { path } => {
+             let since_ms = resolve_since(args.since.as_deref(), "6m")?;
+             let result = query_expert(&conn, path, project_id, since_ms, args.limit)?;
+             Ok(WhoRun {
+                 resolved_input: WhoResolvedInput {
+                     mode: "expert".to_string(),
+                     project_id,
+                     project_path,
+                     since_ms: Some(since_ms),
+                     since_iso: Some(ms_to_iso(since_ms)),
+-                    since_was_default,
++                    since_mode: since_mode_for_defaulted.to_string(),
+                     limit: args.limit,
+                 },
+                 result: WhoResult::Expert(result),
+             })
+         }
+@@
+         WhoMode::Workload { username } => {
+             let since_ms = args
+                 .since
+                 .as_deref()
+                 .map(|s| resolve_since_required(s))
+                 .transpose()?;
+             let result = query_workload(&conn, username, project_id, since_ms, args.limit)?;
+             Ok(WhoRun {
+                 resolved_input: WhoResolvedInput {
+                     mode: "workload".to_string(),
+                     project_id,
+                     project_path,
+                     since_ms,
+                     since_iso: since_ms.map(ms_to_iso),
+-                    since_was_default,
++                    since_mode: since_mode_for_workload.to_string(),
+                     limit: args.limit,
+                 },
+                 result: WhoResult::Workload(result),
+             })
+         }
+@@
+ fn print_who_json(run: &WhoRun, args: &WhoArgs, elapsed_ms: u64) {
+@@
+     let resolved_input = serde_json::json!({
+         "mode": run.resolved_input.mode,
+         "project_id": run.resolved_input.project_id,
+         "project_path": run.resolved_input.project_path,
+         "since_ms": run.resolved_input.since_ms,
+         "since_iso": run.resolved_input.since_iso,
+-        "since_was_default": run.resolved_input.since_was_default,
++        "since_mode": run.resolved_input.since_mode,
+         "limit": run.resolved_input.limit,
+     });
+ }
+
+2) Stop using nullable-OR ((? IS NULL OR col = ?)) where it determines the “right” index (Active is the big one)
+Why this is better
+
+Your global vs project-scoped Active indexes are correct, but the nullable binding pattern undermines them because SQLite’s planner can’t assume whether ?2 is NULL at prepare time. Result: it can pick a “good enough for both” plan, which is often the wrong one for -p.
+
+Fix: keep SQL static, but use two static statements selected at runtime (like you already do for exact vs prefix path matching).
+
+Patch
+diff
+Copy code
+diff --git a/who-command-design.md b/who-command-design.md
+--- a/who-command-design.md
++++ b/who-command-design.md
+@@
+-1. **Lean on existing infrastructure.** Use `(?N IS NULL OR ...)` nullable binding pattern (already used in `timeline_seed.rs`) instead of dynamic SQL string assembly.
++1. **Lean on existing infrastructure.** Prefer `(?N IS NULL OR ...)` nullable binding for optional filters **unless** it materially changes index choice. In those cases, select between **two static SQL strings** at runtime (no `format!()`), e.g. Active mode uses separate global vs project-scoped statements to ensure the intended index is used.
+@@
+ fn query_active(
+     conn: &Connection,
+     project_id: Option<i64>,
+     since_ms: i64,
+     limit: usize,
+ ) -> Result<ActiveResult> {
+     let limit_plus_one = (limit + 1) as i64;
+ 
+-    // Total unresolved count
+-    let total_sql =
+-        "SELECT COUNT(*) FROM discussions d
+-         WHERE d.resolvable = 1 AND d.resolved = 0
+-           AND d.last_note_at >= ?1
+-           AND (?2 IS NULL OR d.project_id = ?2)";
++    // Total unresolved count (two static variants to avoid nullable-OR planner ambiguity)
++    let total_sql_global =
++        "SELECT COUNT(*) FROM discussions d
++         WHERE d.resolvable = 1 AND d.resolved = 0
++           AND d.last_note_at >= ?1";
++    let total_sql_scoped =
++        "SELECT COUNT(*) FROM discussions d
++         WHERE d.resolvable = 1 AND d.resolved = 0
++           AND d.last_note_at >= ?1
++           AND d.project_id = ?2";
+ 
+-    let total_unresolved: u32 =
+-        conn.query_row(total_sql, rusqlite::params![since_ms, project_id], |row| row.get(0))?;
++    let total_unresolved: u32 = match project_id {
++        None => conn.query_row(total_sql_global, rusqlite::params![since_ms], |row| row.get(0))?,
++        Some(pid) => conn.query_row(total_sql_scoped, rusqlite::params![since_ms, pid], |row| row.get(0))?,
++    };
+ 
+-    let sql = "
++    let sql_global = "
+         WITH picked AS (
+             SELECT d.id, d.noteable_type, d.issue_id, d.merge_request_id,
+                    d.project_id, d.last_note_at
+             FROM discussions d
+             WHERE d.resolvable = 1 AND d.resolved = 0
+               AND d.last_note_at >= ?1
+-              AND (?2 IS NULL OR d.project_id = ?2)
+             ORDER BY d.last_note_at DESC
+             LIMIT ?2
+         ),
+@@
+         ORDER BY p.last_note_at DESC
+     ";
+ 
+-    let mut stmt = conn.prepare_cached(sql)?;
+-    let discussions: Vec<ActiveDiscussion> = stmt
+-        .query_map(rusqlite::params![since_ms, project_id, limit_plus_one], |row| {
++    let sql_scoped = "
++        WITH picked AS (
++            SELECT d.id, d.noteable_type, d.issue_id, d.merge_request_id,
++                   d.project_id, d.last_note_at
++            FROM discussions d
++            WHERE d.resolvable = 1 AND d.resolved = 0
++              AND d.last_note_at >= ?1
++              AND d.project_id = ?2
++            ORDER BY d.last_note_at DESC
++            LIMIT ?3
++        ),
++        note_counts AS (
++            SELECT n.discussion_id, COUNT(*) AS note_count
++            FROM notes n
++            JOIN picked p ON p.id = n.discussion_id
++            WHERE n.is_system = 0
++            GROUP BY n.discussion_id
++        ),
++        participants AS (
++            SELECT x.discussion_id, GROUP_CONCAT(x.author_username, X'1F') AS participants
++            FROM (
++                SELECT DISTINCT n.discussion_id, n.author_username
++                FROM notes n
++                JOIN picked p ON p.id = n.discussion_id
++                WHERE n.is_system = 0 AND n.author_username IS NOT NULL
++            ) x
++            GROUP BY x.discussion_id
++        )
++        SELECT
++            p.id AS discussion_id,
++            p.noteable_type,
++            COALESCE(i.iid, m.iid) AS entity_iid,
++            COALESCE(i.title, m.title) AS entity_title,
++            proj.path_with_namespace,
++            p.last_note_at,
++            COALESCE(nc.note_count, 0) AS note_count,
++            COALESCE(pa.participants, '') AS participants
++        FROM picked p
++        JOIN projects proj ON p.project_id = proj.id
++        LEFT JOIN issues i ON p.issue_id = i.id
++        LEFT JOIN merge_requests m ON p.merge_request_id = m.id
++        LEFT JOIN note_counts nc ON nc.discussion_id = p.id
++        LEFT JOIN participants pa ON pa.discussion_id = p.id
++        ORDER BY p.last_note_at DESC
++    ";
++
++    let discussions: Vec<ActiveDiscussion> = match project_id {
++        None => {
++            let mut stmt = conn.prepare_cached(sql_global)?;
++            stmt.query_map(rusqlite::params![since_ms, limit_plus_one], |row| {
++                /* unchanged row mapping */
++            })?.collect::<std::result::Result<Vec<_>, _>>()?
++        }
++        Some(pid) => {
++            let mut stmt = conn.prepare_cached(sql_scoped)?;
++            stmt.query_map(rusqlite::params![since_ms, pid, limit_plus_one], |row| {
++                /* unchanged row mapping */
++            })?.collect::<std::result::Result<Vec<_>, _>>()?
++        }
++    };
+
+
+Also update Verification to explicitly check both variants:
+
+diff
+Copy code
+@@
+ # Performance verification (required before merge):
+@@
+ sqlite3 path/to/db.sqlite "
+   EXPLAIN QUERY PLAN
+   SELECT d.id, d.last_note_at
+   FROM discussions d
+   WHERE d.resolvable = 1 AND d.resolved = 0
+     AND d.last_note_at >= 0
+   ORDER BY d.last_note_at DESC
+   LIMIT 20;
+ "
+ # Expected: SEARCH discussions USING INDEX idx_discussions_unresolved_recent_global
++
++sqlite3 path/to/db.sqlite "
++  EXPLAIN QUERY PLAN
++  SELECT d.id, d.last_note_at
++  FROM discussions d
++  WHERE d.resolvable = 1 AND d.resolved = 0
++    AND d.project_id = 1
++    AND d.last_note_at >= 0
++  ORDER BY d.last_note_at DESC
++  LIMIT 20;
++"
++# Expected: SEARCH discussions USING INDEX idx_discussions_unresolved_recent
+
+3) Add repo-path normalization (eliminate trivial “no results” footguns)
+Why this is better
+
+People paste:
+
+./src/foo/
+
+/src/foo/
+
+src\foo\bar.rs (Windows)
+These currently lead to silent misses.
+
+Normalize only user input (not DB content):
+
+trim whitespace
+
+strip leading ./ and /
+
+convert \ → / when present
+
+collapse repeated //
+
+Patch
+diff
+Copy code
+diff --git a/who-command-design.md b/who-command-design.md
+--- a/who-command-design.md
++++ b/who-command-design.md
+@@
+ fn resolve_mode<'a>(args: &'a WhoArgs) -> Result<WhoMode<'a>> {
+@@
+-    if let Some(p) = &args.path {
+-        return Ok(WhoMode::Expert { path: p });
++    if let Some(p) = &args.path {
++        let norm = normalize_repo_path(p);
++        return Ok(WhoMode::Expert { path: Box::leak(norm.into_boxed_str()) });
+     }
+@@
+-    if let Some(path) = &args.overlap {
+-        return Ok(WhoMode::Overlap { path });
++    if let Some(path) = &args.overlap {
++        let norm = normalize_repo_path(path);
++        return Ok(WhoMode::Overlap { path: Box::leak(norm.into_boxed_str()) });
+     }
+@@
+-        if target.contains('/') {
+-            return Ok(WhoMode::Expert { path: target });
++        if target.contains('/') {
++            let norm = normalize_repo_path(target);
++            return Ok(WhoMode::Expert { path: Box::leak(norm.into_boxed_str()) });
+         }
+@@
+ }
++
++/// Normalize user-supplied repo paths to match stored DiffNote paths.
++/// - trims whitespace
++/// - strips leading "./" and "/" (repo-relative)
++/// - converts '\' to '/' (Windows paste)
++/// - collapses repeated slashes
++fn normalize_repo_path(input: &str) -> String {
++    let mut s = input.trim().to_string();
++    if s.contains('\\') && !s.contains('/') {
++        s = s.replace('\\', "/");
++    }
++    while s.starts_with("./") {
++        s = s.trim_start_matches("./").to_string();
++    }
++    while s.starts_with('/') {
++        s = s.trim_start_matches('/').to_string();
++    }
++    while s.contains("//") {
++        s = s.replace("//", "/");
++    }
++    s
++}
+
+
+(Add a small test block for normalization; even 2–3 asserts catch regressions.)
+
+4) Make path matching observable: include path_match (exact vs prefix) in results/JSON
+Why this is better
+
+You’ve made path classification smarter (heuristics + two-way probe). That’s great, but without visibility you’ll get “why did it treat this as a directory?” confusion. Exposing match metadata is low cost and hugely helps debugging.
+
+Patch
+diff
+Copy code
+diff --git a/who-command-design.md b/who-command-design.md
+--- a/who-command-design.md
++++ b/who-command-design.md
+@@
+-struct PathQuery {
+-    /// The parameter value to bind.
+-    value: String,
+-    /// If true: use `LIKE value ESCAPE '\'`. If false: use `= value`.
+-    is_prefix: bool,
+-}
++struct PathQuery {
++    /// User input after normalization (no trailing slash stripping yet).
++    input: String,
++    /// Trimmed path without trailing '/' used for exact/prefix construction.
++    normalized: String,
++    /// The SQL parameter bound to the statement (`foo/bar` or `foo/bar/%`).
++    sql_value: String,
++    /// If true: use `LIKE sql_value ESCAPE '\'`. If false: use `= normalized`.
++    is_prefix: bool,
++}
+@@
+-    let trimmed = path.trim_end_matches('/');
++    let input = normalize_repo_path(path);
++    let trimmed = input.trim_end_matches('/').to_string();
+@@
+-        Ok(PathQuery {
+-            value: trimmed.to_string(),
+-            is_prefix: false,
+-        })
++        Ok(PathQuery { input, normalized: trimmed.clone(), sql_value: trimmed, is_prefix: false })
+     } else {
+-        Ok(PathQuery {
+-            value: format!("{escaped}/%"),
+-            is_prefix: true,
+-        })
++        Ok(PathQuery { input, normalized: trimmed.clone(), sql_value: format!("{escaped}/%"), is_prefix: true })
+     }
+@@
+ pub struct ExpertResult {
+     pub path_query: String,
++    pub path_match: String, // "exact" or "prefix"
+     pub experts: Vec<Expert>,
+     pub truncated: bool,
+ }
+@@
+ pub struct OverlapResult {
+     pub path_query: String,
++    pub path_match: String, // "exact" or "prefix"
+     pub users: Vec<OverlapUser>,
+     pub truncated: bool,
+ }
+@@
+ fn query_expert(...) -> Result<ExpertResult> {
+     let pq = build_path_query(conn, path, project_id)?;
+@@
+     Ok(ExpertResult {
+         path_query: path.to_string(),
++        path_match: if pq.is_prefix { "prefix".to_string() } else { "exact".to_string() },
+         experts,
+         truncated,
+     })
+ }
+@@
+ fn query_overlap(...) -> Result<OverlapResult> {
+     let pq = build_path_query(conn, path, project_id)?;
+@@
+     Ok(OverlapResult {
+         path_query: path.to_string(),
++        path_match: if pq.is_prefix { "prefix".to_string() } else { "exact".to_string() },
+         users,
+         truncated,
+     })
+ }
+@@
+ fn expert_to_json(r: &ExpertResult) -> serde_json::Value {
+     serde_json::json!({
+         "path_query": r.path_query,
++        "path_match": r.path_match,
+         "truncated": r.truncated,
+         "experts": ...
+     })
+ }
+@@
+ fn overlap_to_json(r: &OverlapResult) -> serde_json::Value {
+     serde_json::json!({
+         "path_query": r.path_query,
++        "path_match": r.path_match,
+         "truncated": r.truncated,
+         "users": ...
+     })
+ }
+
+
+Human output can add a single dim hint line:
+
+(matching exact file) or (matching directory prefix)
+
+5) Put a hard upper bound on --limit at the CLI boundary
+Why this is better
+
+You already bounded nested arrays (participants, mr_refs), but top-level lists are still user-unbounded. A single --limit 50000 can:
+
+generate huge JSON payloads
+
+blow up downstream agent pipelines
+
+create slow queries / memory spikes
+
+Clamp it before execution. A max of 500 is usually plenty; even 200 is fine.
+
+Patch
+diff
+Copy code
+diff --git a/who-command-design.md b/who-command-design.md
+--- a/who-command-design.md
++++ b/who-command-design.md
+@@
+ pub struct WhoArgs {
+@@
+-    /// Maximum results per section
+-    #[arg(short = 'n', long = "limit", default_value = "20", help_heading = "Output")]
++    /// Maximum results per section (bounded for output safety)
++    #[arg(
++        short = 'n',
++        long = "limit",
++        default_value = "20",
++        value_parser = clap::value_parser!(u16).range(1..=500),
++        help_heading = "Output"
++    )]
+     pub limit: usize,
+ }
+@@
+-11. **Bounded payloads.** Robot JSON must never emit unbounded arrays ...
++11. **Bounded payloads.** Robot JSON must never emit unbounded arrays ...
++    Top-level result set size is also bounded via `--limit` (1..=500) to prevent runaway payloads.
+
+6) Clarify Active “unresolved count” semantics (window vs total)
+Why this is better
+
+total_unresolved currently means “unresolved within the time window”. The human header prints “Active Discussions (X unresolved)” which can easily be misread as “total unresolved overall”.
+
+Small rename avoids confusion, no new behavior.
+
+Patch
+diff
+Copy code
+diff --git a/who-command-design.md b/who-command-design.md
+--- a/who-command-design.md
++++ b/who-command-design.md
+@@
+ pub struct ActiveResult {
+     pub discussions: Vec<ActiveDiscussion>,
+-    pub total_unresolved: u32,
++    pub total_unresolved_in_window: u32,
+     pub truncated: bool,
+ }
+@@
+-    println!(
+-        "{}",
+-        style(format!(
+-            "Active Discussions ({} unresolved)",
+-            r.total_unresolved
+-        ))
+-        .bold()
+-    );
++    println!("{}", style(format!(
++        "Active Discussions ({} unresolved in window)",
++        r.total_unresolved_in_window
++    )).bold());
+
+
+(If you later want global total, add a second count query—but I’d keep MVP lean.)
+
+7) Tighten statement cache behavior: avoid preparing both SQL variants when not needed
+Why this is better
+
+You already use prepare_cached(), but as you add more “two static variants” (exact/prefix; scoped/unscoped), it’s easy to accidentally prepare multiple statements per invocation.
+
+Codify: select variant first, then prepare exactly one.
+
+This is mostly a plan hygiene change (helps future you keep perf predictable).
+
+Patch (plan-level emphasis)
+diff
+Copy code
+diff --git a/who-command-design.md b/who-command-design.md
+--- a/who-command-design.md
++++ b/who-command-design.md
+@@
+-1. **Lean on existing infrastructure.** ...
++1. **Lean on existing infrastructure.** ...
++   When multiple static SQL variants exist (exact/prefix; scoped/unscoped), always:
++   (a) resolve which variant applies, then (b) `prepare_cached()` exactly one statement.
+
+Net effect (what you gain)
+
+Correct robot semantics (since_mode) without breaking your static-SQL/agent-first contract.
+
+Guaranteed intended index usage for Active global vs scoped queries (the nullable-OR planner pitfall is real).
+
+Fewer “why no results?” surprises via path normalization.
+
+Better debugging (path match introspection) with essentially no runtime cost.
+
+Output safety even when users/agents misconfigure --limit.
+
+Less ambiguous UX around “unresolved” counts.
+
+If you want a single “most important” change to ship before iteration 8 locks: #2 (Active query variants) and #1 (since semantics) are the two that prevent the most painful, hard-to-diagnose failures.

migrations/015_commit_shas_and_closes_watermark.sql

@@ -0,0 +1,17 @@
+-- Migration 015: Add commit SHAs to merge_requests, closes_issues watermark,
+-- and missing label_name index on resource_label_events.
+
+-- Commit SHAs link MRs to actual git history (needed for Gate 4: file-history, Gate 5: trace)
+ALTER TABLE merge_requests ADD COLUMN merge_commit_sha TEXT;
+ALTER TABLE merge_requests ADD COLUMN squash_commit_sha TEXT;
+
+-- Watermark for closes_issues sync (same pattern as resource_events_synced_for_updated_at)
+-- Prevents re-fetching closes_issues for MRs that haven't changed since last sync
+ALTER TABLE merge_requests ADD COLUMN closes_issues_synced_for_updated_at INTEGER;
+
+-- Missing index from original spec: enables efficient label-name filtering in timeline queries
+CREATE INDEX IF NOT EXISTS idx_label_events_label ON resource_label_events(label_name);
+
+-- Update schema version
+INSERT INTO schema_version (version, applied_at, description)
+VALUES (15, strftime('%s', 'now') * 1000, 'Add commit SHAs, closes_issues watermark, and label event index');

migrations/016_mr_file_changes.sql

@@ -0,0 +1,20 @@
+-- Migration 016: MR file changes table
+-- Powers file-history and trace commands (Gates 4-5)
+
+CREATE TABLE mr_file_changes (
+    id INTEGER PRIMARY KEY,
+    merge_request_id INTEGER NOT NULL REFERENCES merge_requests(id) ON DELETE CASCADE,
+    project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+    old_path TEXT,
+    new_path TEXT NOT NULL,
+    change_type TEXT NOT NULL CHECK (change_type IN ('added', 'modified', 'renamed', 'deleted')),
+    UNIQUE(merge_request_id, new_path)
+);
+
+CREATE INDEX idx_mfc_project_path ON mr_file_changes(project_id, new_path);
+CREATE INDEX idx_mfc_project_old_path ON mr_file_changes(project_id, old_path) WHERE old_path IS NOT NULL;
+CREATE INDEX idx_mfc_mr ON mr_file_changes(merge_request_id);
+CREATE INDEX idx_mfc_renamed ON mr_file_changes(project_id, change_type) WHERE change_type = 'renamed';
+
+INSERT INTO schema_version (version, applied_at, description)
+VALUES (16, strftime('%s', 'now') * 1000, 'MR file changes table');

migrations/017_who_indexes.sql

@@ -0,0 +1,28 @@
+-- Migration 017: Composite indexes for `who` query paths
+
+-- Expert/Overlap: DiffNote path prefix + timestamp filter.
+CREATE INDEX IF NOT EXISTS idx_notes_diffnote_path_created
+    ON notes(position_new_path, created_at, project_id)
+    WHERE note_type = 'DiffNote' AND is_system = 0;
+
+-- Active/Workload: discussion participation lookups.
+CREATE INDEX IF NOT EXISTS idx_notes_discussion_author
+    ON notes(discussion_id, author_username)
+    WHERE is_system = 0;
+
+-- Active (project-scoped): unresolved discussions by recency, scoped by project.
+CREATE INDEX IF NOT EXISTS idx_discussions_unresolved_recent
+    ON discussions(project_id, last_note_at)
+    WHERE resolvable = 1 AND resolved = 0;
+
+-- Active (global): unresolved discussions by recency (no project scope).
+CREATE INDEX IF NOT EXISTS idx_discussions_unresolved_recent_global
+    ON discussions(last_note_at)
+    WHERE resolvable = 1 AND resolved = 0;
+
+-- Workload: issue assignees by username.
+CREATE INDEX IF NOT EXISTS idx_issue_assignees_username
+    ON issue_assignees(username, issue_id);
+
+INSERT INTO schema_version (version, applied_at, description)
+VALUES (17, strftime('%s', 'now') * 1000, 'Composite indexes for who query paths');

migrations/018_fix_assignees_composite_index.sql

@@ -0,0 +1,10 @@
+-- Migration 018: Fix composite index on issue_assignees
+-- Migration 005 created idx_issue_assignees_username(username) as single-column.
+-- Migration 017 attempted to recreate as (username, issue_id) but IF NOT EXISTS
+-- silently skipped it. Drop and recreate with the correct composite columns.
+
+DROP INDEX IF EXISTS idx_issue_assignees_username;
+CREATE INDEX idx_issue_assignees_username ON issue_assignees(username, issue_id);
+
+INSERT INTO schema_version (version, applied_at, description)
+VALUES (18, strftime('%s', 'now') * 1000, 'Fix composite index on issue_assignees');

migrations/019_list_performance.sql

@@ -0,0 +1,16 @@
+-- Standalone updated_at DESC indexes for ORDER BY without temp B-tree sort.
+-- The existing composite indexes (project_id, updated_at) only help when
+-- filtering by project first.
+CREATE INDEX IF NOT EXISTS idx_issues_updated_at_desc
+    ON issues(updated_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_mrs_updated_at_desc
+    ON merge_requests(updated_at DESC);
+
+-- Covering index for correlated subquery: unresolved discussion count per issue.
+-- MRs already have idx_discussions_mr_resolved (migration 006).
+CREATE INDEX IF NOT EXISTS idx_discussions_issue_resolved
+    ON discussions(issue_id, resolvable, resolved);
+
+INSERT INTO schema_version (version, applied_at, description)
+VALUES (19, strftime('%s', 'now') * 1000, 'List performance indexes');

migrations/020_mr_diffs_watermark.sql

@@ -0,0 +1,7 @@
+-- Migration 020: Watermark column for MR diffs sync
+-- Tracks which MRs have had their file changes fetched, same pattern as closes_issues_synced_for_updated_at
+
+ALTER TABLE merge_requests ADD COLUMN diffs_synced_for_updated_at INTEGER;
+
+INSERT INTO schema_version (version, applied_at, description)
+VALUES (20, strftime('%s', 'now') * 1000, 'MR diffs sync watermark');

migrations/021_work_item_status.sql

@@ -0,0 +1,9 @@
+ALTER TABLE issues ADD COLUMN status_name TEXT;
+ALTER TABLE issues ADD COLUMN status_category TEXT;
+ALTER TABLE issues ADD COLUMN status_color TEXT;
+ALTER TABLE issues ADD COLUMN status_icon_name TEXT;
+ALTER TABLE issues ADD COLUMN status_synced_at INTEGER;
+CREATE INDEX IF NOT EXISTS idx_issues_project_status_name ON issues(project_id, status_name);
+
+INSERT INTO schema_version (version, applied_at, description)
+VALUES (21, strftime('%s', 'now') * 1000, 'Work item status columns for issues');

migrations/023_issue_detail_fields.sql

@@ -0,0 +1,5 @@
+ALTER TABLE issues ADD COLUMN closed_at TEXT;
+ALTER TABLE issues ADD COLUMN confidential INTEGER NOT NULL DEFAULT 0;
+
+INSERT INTO schema_version (version, applied_at, description)
+VALUES (23, strftime('%s', 'now') * 1000, 'Add closed_at and confidential to issues');

plans/lore-service.feedback-1.md

@@ -0,0 +1,186 @@
+1. **Isolate scheduled behavior from manual `sync`**
+Reasoning: Your current plan injects backoff into `handle_sync_cmd`, which affects all `lore sync` calls (including manual recovery runs). Scheduled behavior should be isolated so humans aren’t unexpectedly blocked by service backoff.
+
+```diff
+@@ Context
+-`lore sync` runs a 4-stage pipeline (issues, MRs, docs, embeddings) that takes 2-4 minutes.
++`lore sync` remains the manual/operator command.
++`lore service run` (hidden/internal) is the scheduled execution entrypoint.
+
+@@ Commands & User Journeys
++### `lore service run` (hidden/internal)
++**What it does:** Executes one scheduled sync attempt with service-only policy:
++- applies service backoff policy
++- records service run state
++- invokes sync pipeline with configured profile
++- updates retry state on success/failure
++
++**Invocation:** scheduler always runs:
++`lore --robot service run --reason timer`
+
+@@ Backoff Integration into `handle_sync_cmd`
+-Insert **after** config load but **before** the dry_run check:
++Do not add backoff checks to `handle_sync_cmd`.
++Backoff logic lives only in `handle_service_run`.
+```
+
+2. **Use DB as source-of-truth for service state (not a standalone JSON status file)**
+Reasoning: You already have `sync_runs` in SQLite. A separate JSON status file creates split-brain and race/corruption risk. Keep JSON as optional cache/export only.
+
+```diff
+@@ Status File
+-Location: `{get_data_dir()}/sync-status.json`
++Primary state location: SQLite (`service_state` table) + existing `sync_runs`.
++Optional mirror file: `{get_data_dir()}/sync-status.json` (best-effort export only).
+
+@@ File-by-File Implementation Details
+-### `src/core/sync_status.rs` (NEW)
++### `migrations/015_service_state.sql` (NEW)
++CREATE TABLE service_state (
++  id INTEGER PRIMARY KEY CHECK (id = 1),
++  installed INTEGER NOT NULL DEFAULT 0,
++  platform TEXT,
++  interval_seconds INTEGER,
++  profile TEXT NOT NULL DEFAULT 'balanced',
++  consecutive_failures INTEGER NOT NULL DEFAULT 0,
++  next_retry_at_ms INTEGER,
++  last_error_code TEXT,
++  last_error_message TEXT,
++  updated_at_ms INTEGER NOT NULL
++);
++
++### `src/core/service_state.rs` (NEW)
++- read/write state row
++- derive backoff/next_retry
++- join with latest `sync_runs` for status output
+```
+
+3. **Backoff policy should be configurable, jittered, and error-aware**
+Reasoning: Fixed hardcoded backoff (`base=1800`) is wrong when user sets another interval. Also permanent failures (bad token/config) should not burn retries forever; they should enter paused/error state.
+
+```diff
+@@ Backoff Logic
+-// Exponential: base * 2^failures, capped at 4 hours
++// Exponential with jitter: base * 2^(failures-1), capped, ±20% jitter
++// Applies only to transient errors.
++// Permanent errors set `paused_reason` and stop retries until user action.
+
+@@ CLI Definition Changes
++ServiceCommand::Resume,   // clear paused state / failures
++ServiceCommand::Run,      // hidden
+
+@@ Error Types
++ServicePaused,            // scheduler paused due to permanent error
++ServiceCommandFailed,     // OS command failure with stderr context
+```
+
+4. **Add a pipeline-level single-flight lock**
+Reasoning: Current locking is in ingest stages; there’s still overlap risk across full sync pipelines (docs/embed can overlap with another run). Add a top-level lock for scheduled/manual sync pipeline execution.
+
+```diff
+@@ Architecture
++Add `sync_pipeline` lock at top-level sync execution.
++Keep existing ingest lock (`sync`) for ingest internals.
+
+@@ Backoff Integration into `handle_sync_cmd`
++Before starting sync pipeline, acquire `AppLock` with:
++name = "sync_pipeline"
++stale_lock_minutes = config.sync.stale_lock_minutes
++heartbeat_interval_seconds = config.sync.heartbeat_interval_seconds
+```
+
+5. **Don’t embed token in service files by default**
+Reasoning: Embedding PAT into unit/plist is a high-risk secret leak path. Make secure storage explicit and default-safe.
+
+```diff
+@@ `lore service install [--interval 30m]`
++`lore service install [--interval 30m] [--token-source env-file|embedded]`
++Default: `env-file` (0600 perms, user-owned)
++`embedded` allowed only with explicit opt-in and warning
+
+@@ Robot output
+-    "token_embedded": true
++    "token_source": "env_file"
+
+@@ Human output
+-  Note: Your GITLAB_TOKEN is embedded in the service file.
++  Note: Token is stored in a user-private env file (0600).
+```
+
+6. **Introduce a command-runner abstraction with timeout + stderr capture**
+Reasoning: `launchctl/systemctl/schtasks` calls are failure-prone; you need consistent error mapping and deterministic tests.
+
+```diff
+@@ Platform Backends
+-exports free functions that dispatch via `#[cfg(target_os)]`
++exports backend + shared `CommandRunner`:
++- run(cmd, args, timeout)
++- capture stdout/stderr/exit code
++- map failure to `ServiceCommandFailed { cmd, exit_code, stderr }`
+```
+
+7. **Persist install manifest to avoid brittle file parsing**
+Reasoning: Parsing timer/plist for interval/state is fragile and platform-format dependent. Persist a manifest with checksums and expected artifacts.
+
+```diff
+@@ Platform Backends
+-Same pattern for ... `get_interval_seconds()`
++Add manifest: `{data_dir}/service-manifest.json`
++Stores platform, interval, profile, generated files, and command.
++`service status` reads manifest first, then verifies platform state.
+
+@@ Acceptance criteria
++Install is idempotent:
++- if manifest+files already match, report `no_change: true`
++- if drift detected, reconcile and rewrite
+```
+
+8. **Make schedule profile explicit (`fast|balanced|full`)**
+Reasoning: This makes the feature more useful and performance-tunable without requiring users to understand internal flags.
+
+```diff
+@@ `lore service install [--interval 30m]`
++`lore service install [--interval 30m] [--profile fast|balanced|full]`
++
++Profiles:
++- fast: `sync --no-docs --no-embed`
++- balanced (default): `sync --no-embed`
++- full: `sync`
+```
+
+9. **Upgrade `service status` to include scheduler health + recent run summary**
+Reasoning: Single last-sync snapshot is too shallow. Include recent attempts and whether scheduler is paused/backing off/running.
+
+```diff
+@@ `lore service status`
+-What it does: Shows whether the service is installed, its configuration, last sync result, and next scheduled run.
++What it does: Shows install state, scheduler state (running/backoff/paused), recent runs, and next run estimate.
+
+@@ Robot output
+-    "last_sync": { ... },
+-    "backoff": null
++    "scheduler_state": "running|backoff|paused|idle",
++    "last_sync": { ... },
++    "recent_runs": [{"run_id":"...","status":"...","started_at_iso":"..."}],
++    "backoff": null,
++    "paused_reason": null
+```
+
+10. **Strengthen tests around determinism and cross-platform generation**
+Reasoning: Time-based backoff and shell quoting are classic flaky points. Add fake clock + fake command runner for deterministic tests.
+
+```diff
+@@ Testing Strategy
++Add deterministic test seams:
++- `Clock` trait for backoff/now calculations
++- `CommandRunner` trait for backend command execution
++
++Add tests:
++- transient vs permanent error classification
++- backoff schedule with jitter bounds
++- manifest drift reconciliation
++- quoting/escaping for paths with spaces and special chars
++- `service run` does not modify manual `sync` behavior
+```
+
+If you want, I can rewrite your full plan as a single clean revised document with these changes already integrated (instead of patch fragments).

plans/lore-service.feedback-2.md

@@ -0,0 +1,182 @@
+**High-Impact Revisions (ordered by priority)**
+
+1. **Make service identity project-scoped (avoid collisions across repos/users)**
+Analysis: Current fixed names (`com.gitlore.sync`, `LoreSync`, `lore-sync.timer`) will collide when users run multiple gitlore workspaces. This causes silent overwrites and broken uninstall/status behavior.  
+Diff:
+```diff
+--- a/plan.md
++++ b/plan.md
+@@ Commands & User Journeys / install
+- lore service install [--interval 30m] [--profile balanced] [--token-source env-file]
++ lore service install [--interval 30m] [--profile balanced] [--token-source auto] [--name <optional>]
+@@ Install Manifest Schema
++    /// Stable per-install identity (default derived from project root hash)
++    pub service_id: String,
+@@ Platform Backends
+- Label: com.gitlore.sync
++ Label: com.gitlore.sync.{service_id}
+- Task name: LoreSync
++ Task name: LoreSync-{service_id}
+- ~/.config/systemd/user/lore-sync.service
++ ~/.config/systemd/user/lore-sync-{service_id}.service
+```
+
+2. **Replace token model with secure per-OS defaults**
+Analysis: The current “env-file default” is not actually secure on macOS launchd (token still ends up in plist). On Windows, assumptions about inherited environment are fragile. Use OS-native secure stores by default and keep `embedded` as explicit opt-in only.  
+Diff:
+```diff
+--- a/plan.md
++++ b/plan.md
+@@ Token storage strategies
+-| env-file (default) | ...
++| auto (default) | macOS: Keychain, Linux: env-file (0600), Windows: Credential Manager |
++| env-file | Linux/systemd only |
+ | embedded | ... explicit warning ...
+@@ macOS launchd section
+- env-file strategy stores canonical token in service-env but embeds token in plist
++ default strategy is Keychain lookup at runtime; no token persisted in plist
++ env-file is not offered on macOS
+@@ Windows schtasks section
+- token must be in user's system environment
++ default strategy stores token in Windows Credential Manager and injects at runtime
+```
+
+3. **Version and atomically persist manifest/status**
+Analysis: `Option<Self>` on read hides corruption, and non-atomic writes risk truncated JSON on crashes. This will create false “not installed” and scheduler confusion.  
+Diff:
+```diff
+--- a/plan.md
++++ b/plan.md
+@@ Install Manifest Schema
++    pub schema_version: u32, // start at 1
++    pub updated_at_iso: String,
+@@ Status File Schema
++    pub schema_version: u32, // start at 1
++    pub updated_at_iso: String,
+@@ Read/Write
+- read(path) -> Option<Self>
++ read(path) -> Result<Option<Self>, LoreError>
+- write(...) -> std::io::Result<()>
++ write_atomic(...) -> std::io::Result<()> // tmp file + fsync + rename
+```
+
+4. **Persist `next_retry_at_ms` instead of recomputing jitter**
+Analysis: Deterministic jitter from timestamp modulo is predictable and can herd retries. Persisting `next_retry_at_ms` at failure time makes status accurate, stable, and cheap to compute.  
+Diff:
+```diff
+--- a/plan.md
++++ b/plan.md
+@@ SyncStatusFile
+     pub consecutive_failures: u32,
++    pub next_retry_at_ms: Option<i64>,
+@@ Backoff Logic
+- compute backoff from last_run.timestamp_ms and deterministic jitter each read
++ compute backoff once on failure, store next_retry_at_ms, read-only comparison afterward
++ jitter algorithm: full jitter in [0, cap], injectable RNG for tests
+```
+
+5. **Add circuit breaker for repeated transient failures**
+Analysis: Infinite transient retries can run forever on systemic failures (DB corruption, bad network policy). After N transient failures, pause with actionable reason.  
+Diff:
+```diff
+--- a/plan.md
++++ b/plan.md
+@@ Scheduler states
+- backoff — transient failures, waiting to retry
++ backoff — transient failures, waiting to retry
++ paused — permanent error OR circuit breaker tripped after N transient failures
+@@ Service run flow
+- On transient failure: increment failures, compute backoff
++ On transient failure: increment failures, compute backoff, if failures >= max_transient_failures -> pause
+```
+
+6. **Stage-aware outcome policy (core freshness over all-or-nothing)**
+Analysis: Failing embeddings/docs should not block issues/MRs freshness. Split stage outcomes and only treat core stages as hard-fail by default. This improves reliability and practical usefulness.  
+Diff:
+```diff
+--- a/plan.md
++++ b/plan.md
+@@ Context
+- lore sync runs a 4-stage pipeline ... treated as one run result
++ lore service run records per-stage outcomes (issues, mrs, docs, embeddings)
+@@ Status File Schema
++    pub stage_results: Vec<StageResult>,
+@@ service run flow
+- Execute sync pipeline with flags derived from profile
++ Execute stage-by-stage and classify severity:
++   - critical: issues, mrs
++   - optional: docs, embeddings
++ optional stage failures mark run as degraded, not failed
+```
+
+7. **Replace cfg free-function backend with trait-based backend**
+Analysis: Current backend API is hard to test end-to-end without real OS commands. A `SchedulerBackend` trait enables deterministic integration tests and cleaner architecture.  
+Diff:
+```diff
+--- a/plan.md
++++ b/plan.md
+@@ Platform Backends / Architecture
+- exports free functions dispatched via #[cfg]
++ define trait SchedulerBackend { install, uninstall, state, file_paths, next_run }
++ provide LaunchdBackend, SystemdBackend, SchtasksBackend implementations
++ include FakeBackend for integration tests
+```
+
+8. **Harden platform units and detect scheduler prerequisites**
+Analysis: systemd user timers often fail silently without user manager/linger; launchd context can be wrong in headless sessions. Add explicit diagnostics and unit hardening.  
+Diff:
+```diff
+--- a/plan.md
++++ b/plan.md
+@@ Linux systemd unit
+ [Service]
+ Type=oneshot
+ ExecStart=...
++TimeoutStartSec=900
++NoNewPrivileges=true
++PrivateTmp=true
++ProtectSystem=strict
++ProtectHome=read-only
+@@ Linux install/status
++ detect user manager availability and linger state; surface warning/action
+@@ macOS install/status
++ detect non-GUI bootstrap context and return actionable error
+```
+
+9. **Add operational commands: `trigger`, `doctor`, and non-interactive log tail**
+Analysis: `logs` opening an editor is weak for automation and incident response. Operators need a preflight and immediate controlled run.  
+Diff:
+```diff
+--- a/plan.md
++++ b/plan.md
+@@ ServiceCommand
++ Trigger, // run one attempt through service policy now
++ Doctor,  // validate scheduler, token, paths, permissions
+@@ logs
+- opens editor
++ supports --tail <n> and --follow in human mode
++ robot mode can return last_n lines optionally
+```
+
+10. **Fix plan inconsistencies and edge-case correctness**
+Analysis: There are internal mismatches that will cause implementation drift.  
+Diff:
+```diff
+--- a/plan.md
++++ b/plan.md
+@@ Interval Parsing
+- supports 's' suffix
++ remove 's' suffix (acceptance only allows 5m..24h)
+@@ uninstall acceptance
+- removes ALL service files only
++ explicitly also remove service-manifest and service-env (status/logs retained)
+@@ SyncStatusFile schema
+- pub last_run: SyncRunRecord
++ pub last_run: Option<SyncRunRecord> // matches idle/no runs state
+```
+
+---
+
+**Recommended Architecture Upgrade Summary**
+
+The strongest improvement set is: **(1) project-scoped IDs, (2) secure token defaults, (3) atomic/versioned state, (4) persisted retry schedule + circuit breaker, (5) stage-aware outcomes**. That combination materially improves correctness, multi-repo safety, security, operability, and real-world reliability without changing your core manual-vs-scheduled separation principle.

plans/lore-service.feedback-3.md

@@ -0,0 +1,174 @@
+Below are the highest-impact revisions I’d make, ordered by severity/ROI. These focus on correctness first, then security, then operability and UX.
+
+1. **Fix multi-install ambiguity (`service_id` exists, but commands can’t target one explicitly)**
+Analysis: The plan introduces `service-manifest-{service_id}.json`, but `status/uninstall/resume/logs` have no selector. In a multi-workspace or multi-name install scenario, behavior becomes ambiguous and error-prone. Add explicit targeting plus discovery.
+```diff
+@@ ## Commands & User Journeys
++### `lore service list`
++Lists installed services discovered from `{data_dir}/service-manifest-*.json`.
++Robot output includes `service_id`, `platform`, `interval_seconds`, `profile`, `installed_at_iso`.
+
+@@ ### `lore service uninstall`
+-### `lore service uninstall`
++### `lore service uninstall [--service <service_id|name>] [--all]`
+@@
+-2. CLI reads install manifest to find `service_id`
++2. CLI resolves target service via `--service` or current-project-derived default.
++3. If multiple candidates and no selector, return actionable error.
+
+@@ ### `lore service status`
+-### `lore service status`
++### `lore service status [--service <service_id|name>]`
+```
+
+2. **Make status state service-scoped (not global)**
+Analysis: A single `sync-status.json` for all services causes cross-service contamination (pause/backoff/outcome from one profile affecting another). Keep lock global, but state per service.
+```diff
+@@ ## Status File
+-### Location
+-`{get_data_dir()}/sync-status.json`
++### Location
++`{get_data_dir()}/sync-status-{service_id}.json`
+
+@@ ## Paths Module Additions
+-pub fn get_service_status_path() -> PathBuf {
+-    get_data_dir().join("sync-status.json")
++pub fn get_service_status_path(service_id: &str) -> PathBuf {
++    get_data_dir().join(format!("sync-status-{service_id}.json"))
+}
+@@
+-Note: `sync-status.json` is NOT scoped by `service_id`
++Note: status is scoped by `service_id`; lock remains global (`sync_pipeline`) to prevent overlapping writes.
+```
+
+3. **Stop classifying permanence via string matching**
+Analysis: Matching `"401 Unauthorized"` in strings is brittle and will misclassify edge cases. Carry machine codes through stage results and classify by `ErrorCode` only.
+```diff
+@@ pub struct StageResult {
+-    pub error: Option<String>,
++    pub error: Option<String>,
++    pub error_code: Option<String>, // e.g., AUTH_FAILED, NETWORK_ERROR
+}
+@@ Error classification helpers
+-fn is_permanent_error_message(msg: Option<&str>) -> bool { ...string contains... }
++fn is_permanent_error_code(code: Option<&str>) -> bool {
++    matches!(code, Some("TOKEN_NOT_SET" | "AUTH_FAILED" | "CONFIG_NOT_FOUND" | "CONFIG_INVALID" | "MIGRATION_FAILED"))
++}
+```
+
+4. **Install should be transactional (manifest written last)**
+Analysis: Current order writes manifest before scheduler enable. If enable fails, you persist a false “installed” state. Use two-phase install with rollback.
+```diff
+@@ ### `lore service install` User journey
+-9. CLI writes install manifest ...
+-10. CLI runs the platform-specific enable command
++9. CLI runs the platform-specific enable command
++10. On success, CLI writes install manifest atomically
++11. On failure, CLI removes generated files and returns `ServiceCommandFailed`
+```
+
+5. **Fix launchd token security gap (env-file currently still embeds token)**
+Analysis: Current “env-file” on macOS still writes token into plist, defeating the main security goal. Generate a private wrapper script that reads env file at runtime and execs `lore`.
+```diff
+@@ ### macOS: launchd
+-<key>ProgramArguments</key>
+-<array>
+-    <string>{binary_path}</string>
+-    <string>--robot</string>
+-    <string>service</string>
+-    <string>run</string>
+-</array>
++<key>ProgramArguments</key>
++<array>
++    <string>{data_dir}/service-run-{service_id}.sh</string>
++</array>
+@@
+-`env-file`: ... token value must still appear in plist ...
++`env-file`: token never appears in plist; wrapper loads `{data_dir}/service-env-{service_id}` at runtime.
+```
+
+6. **Improve backoff math and add half-open circuit recovery**
+Analysis: Current jitter + min clamp makes first retry deterministic and can over-pause. Also circuit-breaker requires manual resume forever. Add cooldown + half-open probe to self-heal.
+```diff
+@@ Backoff Logic
+-let backoff_secs = ((base_backoff as f64) * jitter_factor) as u64;
+-let backoff_secs = backoff_secs.max(base_interval_seconds);
++let max_backoff = base_backoff;
++let min_backoff = base_interval_seconds;
++let span = max_backoff.saturating_sub(min_backoff);
++let backoff_secs = min_backoff + ((span as f64) * jitter_factor) as u64;
+
+@@ Scheduler states
+-- `paused` — permanent error ... OR circuit breaker tripped ...
++- `paused` — permanent error requiring intervention
++- `half_open` — probe state after circuit cooldown; one trial run allowed
+
+@@ Circuit breaker
+-... transitions to `paused` ... Run: lore service resume
++... transitions to `half_open` after cooldown (default 30m). Successful probe closes breaker automatically; failed probe returns to backoff/paused.
+```
+
+7. **Promote backend trait to v1 (not v2) for deterministic integration tests**
+Analysis: This is a reliability-critical feature spanning OS schedulers. A trait abstraction now gives true behavior tests and safer refactors.
+```diff
+@@ ### Platform Backends
+-> Future architecture note: A `SchedulerBackend` trait ... for v2.
++Adopt `SchedulerBackend` trait in v1 with real backends (`launchd/systemd/schtasks`) and `FakeBackend` for tests.
++This enables deterministic install/uninstall/status/run-path integration tests without touching host scheduler.
+```
+
+8. **Harden `run_cmd` timeout behavior**
+Analysis: If timeout occurs, child process must be killed and reaped. Otherwise you leak processes and can wedge repeated runs.
+```diff
+@@ fn run_cmd(...)
+-// Wait with timeout
+-let output = wait_with_timeout(output, timeout_secs)?;
++// Wait with timeout; on timeout kill child and wait to reap
++let output = wait_with_timeout_kill_and_reap(child, timeout_secs)?;
+```
+
+9. **Add manual control commands (`pause`, `trigger`, `repair`)**
+Analysis: These are high-utility operational controls. `trigger` helps immediate sync without waiting interval. `pause` supports maintenance windows. `repair` avoids manual file deletion for corrupt state.
+```diff
+@@ pub enum ServiceCommand {
++    /// Pause scheduled execution without uninstalling
++    Pause { #[arg(long)] reason: Option<String> },
++    /// Trigger an immediate one-off run using installed profile
++    Trigger { #[arg(long)] ignore_backoff: bool },
++    /// Repair corrupt manifest/status by backing up and reinitializing
++    Repair { #[arg(long)] service: Option<String> },
+}
+```
+
+10. **Make `logs` default non-interactive and add rotation policy**
+Analysis: Opening editor by default is awkward for automation/SSH and slower for normal diagnosis. Defaulting to `tail` is more practical; `--open` can preserve editor behavior.
+```diff
+@@ ### `lore service logs`
+-By default, opens in the user's preferred editor.
++By default, prints last 100 lines to stdout.
++Use `--open` to open editor.
+@@
++Log rotation: rotate `service-stdout.log` / `service-stderr.log` at 10 MB, keep 5 files.
+```
+
+11. **Remove destructive/shell-unsafe suggested action**
+Analysis: `actions(): ["rm {path}", ...]` is unsafe (shell injection + destructive guidance). Replace with safe command path.
+```diff
+@@ LoreError::actions()
+-Self::ServiceCorruptState { path, .. } => vec![&format!("rm {path}"), "lore service install"],
++Self::ServiceCorruptState { .. } => vec!["lore service repair", "lore service install"],
+```
+
+12. **Tighten scheduler units for real-world reliability**
+Analysis: Add explicit working directory and success-exit handling to reduce environment drift and edge failures.
+```diff
+@@ systemd service unit
+ [Service]
+ Type=oneshot
+ ExecStart={binary_path} --robot service run
++WorkingDirectory={data_dir}
++SuccessExitStatus=0
+ TimeoutStartSec=900
+```
+
+If you want, I can produce a single consolidated “v3 plan” markdown with these revisions already merged into your original structure.

plans/lore-service.feedback-4.md

@@ -0,0 +1,190 @@
+No `## Rejected Recommendations` section was present in the plan you shared, so the proposals below are all net-new.
+
+1. **Make scheduled runs explicitly target a single service instance**
+Analysis: right now `service run` has no selector, but the plan supports multiple installed services. That creates ambiguity and incorrect manifest/status selection. This is the most important architectural fix.
+
+```diff
+@@ `lore service install` What it does
+- runs `lore --robot service run` at the specified interval
++ runs `lore --robot service run --service-id <service_id>` at the specified interval
+
+@@ Robot output (`install`)
+- "sync_command": "/usr/local/bin/lore --robot service run",
++ "sync_command": "/usr/local/bin/lore --robot service run --service-id a1b2c3d4",
+
+@@ `ServiceCommand` enum
+- #[command(hide = true)]
+- Run,
++ #[command(hide = true)]
++ Run {
++     /// Internal selector injected by scheduler backend
++     #[arg(long, hide = true)]
++     service_id: String,
++ },
+
+@@ `handle_service_run` signature
+-pub fn handle_service_run(start: std::time::Instant) -> Result<(), Box<dyn std::error::Error>>
++pub fn handle_service_run(service_id: &str, start: std::time::Instant) -> Result<(), Box<dyn std::error::Error>>
+
+@@ run flow step 1
+- Read install manifest
++ Read install manifest for `service_id`
+```
+
+2. **Strengthen `service_id` derivation to avoid cross-workspace collisions**
+Analysis: hashing config path alone can collide when many workspaces share one global config. Identity should represent what is being synced, not only where config lives.
+
+```diff
+@@ Key Design Principles / Project-Scoped Service Identity
+- derive from a stable hash of the config file path
++ derive from a stable fingerprint of:
++ - canonical workspace root
++ - normalized configured GitLab project URLs
++ - canonical config path
++ then take first 12 hex chars of SHA-256
+
+@@ `compute_service_id`
+- Returns first 8 hex chars of SHA-256 of the canonical config path.
++ Returns first 12 hex chars of SHA-256 of a canonical identity tuple
++ (workspace_root + sorted project URLs + config_path).
+```
+
+3. **Introduce a service-state machine with a dedicated admin lock**
+Analysis: install/uninstall/pause/resume/repair/status can race each other. A lock and explicit transition table prevents invalid states and file races.
+
+```diff
+@@ New section: Service State Model
++ All state mutations are serialized by `AppLock("service-admin-{service_id}")`.
++ Legal transitions:
++ - idle -> running -> success|degraded|backoff|paused
++ - backoff -> running|paused
++ - paused -> half_open|running (resume)
++ - half_open -> running|paused
++ Any invalid transition is rejected with `ServiceCorruptState`.
+
+@@ `handle_install`, `handle_uninstall`, `handle_pause`, `handle_resume`, `handle_repair`
++ Acquire `service-admin-{service_id}` before mutating manifest/status/service files.
+```
+
+4. **Unify manual and scheduled sync execution behind one orchestrator**
+Analysis: the plan currently duplicates stage logic and error classification in `service run`, increasing drift risk. A shared orchestrator gives one authoritative pipeline behavior.
+
+```diff
+@@ Key Design Principles
++ #### 6. Single Sync Orchestrator
++ Both `lore sync` and `lore service run` call `SyncOrchestrator`.
++ Service mode adds policy (backoff/circuit-breaker); manual mode bypasses policy.
+
+@@ Service Run Implementation
+- execute_sync_stages(&sync_args)
++ SyncOrchestrator::run(SyncMode::Service { profile, policy })
+
+@@ manual sync
+- separate pipeline path
++ SyncOrchestrator::run(SyncMode::Manual { flags })
+```
+
+5. **Add bounded in-run retries for transient core-stage failures**
+Analysis: single-shot failure handling will over-trigger backoff on temporary network blips. One short retry per core stage significantly improves freshness without much extra runtime.
+
+```diff
+@@ Stage-aware execution
++ Core stages (`issues`, `mrs`) get up to 1 immediate retry on transient errors
++ (jittered 1-5s). Permanent errors are never retried.
++ Optional stages keep best-effort semantics.
+
+@@ Acceptance criteria (`service run`)
++ Retries transient core stage failures once before counting run as failed.
+```
+
+6. **Harden persistence with full crash-safety semantics**
+Analysis: current atomic write description is good but incomplete for power-loss durability. You should fsync parent directory after rename and include lightweight integrity metadata.
+
+```diff
+@@ `write_atomic`
+- tmp file + fsync + rename
++ tmp file + fsync(file) + rename + fsync(parent_dir)
+
+@@ `ServiceManifest` and `SyncStatusFile`
++ pub write_seq: u64,
++ pub content_sha256: String, // optional integrity guard for repair/doctor
+```
+
+7. **Fix token handling to avoid shell/env injection and add secure-store mode**
+Analysis: sourcing env files in shell is brittle if token contains special chars/newlines. Also, secure OS credential stores should be first-class for production reliability/security.
+
+```diff
+@@ Token storage strategies
+-| `env-file` (default) ...
++| `auto` (default) | use secure-store when available, else env-file |
++| `secure-store` | macOS Keychain / libsecret / Windows Credential Manager |
++| `env-file` | explicit fallback |
+
+@@ macOS wrapper script
+-. "{data_dir}/service-env-{service_id}"
+-export {token_env_var}
++TOKEN_VALUE="$(cat "{data_dir}/service-token-{service_id}" )"
++export {token_env_var}="$TOKEN_VALUE"
+
+@@ Acceptance criteria
++ Reject token values containing `\0` or newline for env-file mode.
++ Never eval/source untrusted token content.
+```
+
+8. **Correct platform/runtime implementation hazards**
+Analysis: there are a few correctness risks that should be fixed in-plan now.
+
+```diff
+@@ macOS install steps
+- Get UID via `unsafe { libc::getuid() }`
++ Get UID via safe API (`nix::unistd::Uid::current()` or equivalent safe helper)
+
+@@ Command Runner Helper
+- poll try_wait and read stdout/stderr after exit
++ avoid potential pipe backpressure deadlock:
++ use wait-with-timeout + concurrent stdout/stderr draining
+
+@@ Linux timer
+- OnUnitActiveSec={interval_seconds}s
++ OnUnitInactiveSec={interval_seconds}s
++ AccuracySec=1min
+```
+
+9. **Make logs fully service-scoped**
+Analysis: you already scoped manifest/status by `service_id`; logs are still global in several places. Multi-service installs will overwrite each other’s logs.
+
+```diff
+@@ Paths Module Additions
+-pub fn get_service_log_path() -> PathBuf
++pub fn get_service_log_path(service_id: &str, stream: LogStream) -> PathBuf
+
+@@ log filenames
+- logs/service-stderr.log
+- logs/service-stdout.log
++ logs/service-{service_id}-stderr.log
++ logs/service-{service_id}-stdout.log
+
+@@ `service logs`
+- default path: `{data_dir}/logs/service-stderr.log`
++ default path: `{data_dir}/logs/service-{service_id}-stderr.log`
+```
+
+10. **Resolve internal spec contradictions and rollback gaps**
+Analysis: there are a few contradictory statements and incomplete rollback behavior that will cause implementation churn.
+
+```diff
+@@ `service logs` behavior
+- default (no flags): open in editor (human)
++ default (no flags): print last 100 lines (human and robot metadata mode)
++ `--open` is explicit opt-in
+
+@@ install rollback
+- On failure: removes generated service files
++ On failure: removes generated service files, env file, wrapper script, and temp manifest
+
+@@ `handle_service_run` sample code
+- let manifest_path = get_service_manifest_path();
++ let manifest_path = get_service_manifest_path(service_id);
+```
+
+If you want, I can take these revisions and produce a single consolidated “Iteration 4” replacement plan block with all sections rewritten coherently so it’s ready to hand to an implementer.

plans/lore-service.feedback-5.md

@@ -0,0 +1,196 @@
+I reviewed the full plan and avoided everything already listed in `## Rejected Recommendations`. These are the highest-impact revisions I’d make.
+
+1. **Fix identity model inconsistency and prevent `--name` alias collisions**
+Why this improves the plan: your text says identity includes workspace root, but the current derivation code does not. Also, using `--name` as the actual `service_id` risks accidental cross-project collisions and destructive updates.
+
+```diff
+--- a/plan.md
++++ b/plan.md
+@@ Key Design Principles / 2. Project-Scoped Service Identity
+- Each installed service gets a unique `service_id` derived from a canonical identity tuple: the config file path, sorted GitLab project URLs, and workspace root.
++ Each installed service gets an immutable `identity_hash` derived from a canonical identity tuple:
++ workspace root + canonical config path + sorted normalized project URLs.
++ `service_id` remains the scheduler identifier; `--name` is a human alias only.
++ If `--name` collides with an existing service that has a different `identity_hash`, install fails with an actionable error.
+
+@@ Install Manifest / Schema
++ /// Immutable identity hash for collision-safe matching across reinstalls
++ pub identity_hash: String,
++ /// Optional human-readable alias passed via --name
++ #[serde(skip_serializing_if = "Option::is_none")]
++ pub service_alias: Option<String>,
++ /// Canonical workspace root used in identity derivation
++ pub workspace_root: String,
+
+@@ service_id derivation
+-pub fn compute_service_id(config_path: &Path, project_urls: &[&str]) -> String
++pub fn compute_identity_hash(workspace_root: &Path, config_path: &Path, project_urls: &[&str]) -> String
+```
+
+2. **Add lock protocol to eliminate uninstall/run race conditions**
+Why this improves the plan: today `service run` does not take admin lock, and admin commands do not take pipeline lock. `uninstall` can race with an active run and remove files mid-execution.
+
+```diff
+--- a/plan.md
++++ b/plan.md
+@@ Key Design Principles / 6. Serialized Admin Mutations
+- The `service run` entrypoint does NOT acquire the admin lock — it only acquires the `sync_pipeline` lock
++ The `service run` entrypoint acquires only `sync_pipeline`.
++ Destructive admin operations (`install` overwrite, `uninstall`, `repair --regenerate`) must:
++ 1) acquire `service-admin-{service_id}`
++ 2) disable scheduler backend entrypoint
++ 3) acquire `sync_pipeline` lock with timeout
++ 4) mutate/remove files
++ This lock ordering is mandatory to prevent deadlocks and run/delete races.
+
+@@ lore service uninstall / User journey
+- 4. Runs platform-specific disable command
+- 5. Removes service files from disk
++ 4. Acquires `sync_pipeline` lock (after disabling scheduler) with bounded wait
++ 5. Removes service files from disk only after lock acquisition
+```
+
+3. **Make transient handling `Retry-After` aware**
+Why this improves the plan: rate-limit and 503 responses often carry retry hints. Ignoring them causes useless retries and longer outages.
+
+```diff
+--- a/plan.md
++++ b/plan.md
+@@ Transient vs permanent error classification
+-| Transient | Retry with backoff | Network timeout, rate limited, DB locked, 5xx from GitLab |
++| Transient | Retry with adaptive backoff | Network timeout, DB locked, 5xx from GitLab |
++| Transient (hinted) | Respect server retry hint | Rate limited with Retry-After/X-RateLimit-Reset |
+
+@@ Backoff Logic
++ If an error includes a retry hint (e.g., `Retry-After`), set:
++ `next_retry_at_ms = max(computed_backoff, hinted_retry_at_ms)`.
++ Persist `backoff_reason` for status visibility.
+```
+
+4. **Decouple optional stage cadence from core sync interval**
+Why this improves the plan: running docs/embeddings every 5–30 minutes is expensive and unnecessary. Separate freshness windows reduce cost/latency while keeping core data fresh.
+
+```diff
+--- a/plan.md
++++ b/plan.md
+@@ Sync profiles
+-| `balanced` (default) | `--no-embed` | Issues + MRs + doc generation |
+-| `full` | (none) | Full pipeline including embeddings |
++| `balanced` (default) | core every interval, docs every 60m, no embeddings | Fast + useful docs |
++| `full` | core every interval, docs every interval, embeddings every 6h (default) | Full freshness with bounded cost |
+
+@@ Status File / StageResult
++ /// true when stage intentionally skipped due freshness window
++ #[serde(default)]
++ pub skipped: bool,
+
+@@ lore service run / Stage-aware execution
++ Optional stages may be skipped when their last successful run is within configured freshness windows.
++ Skipped optional stages do not count as failures and are recorded explicitly.
+```
+
+5. **Give Windows parity for secure token handling (env-file + wrapper)**
+Why this improves the plan: current Windows path requires global/system env and has poor UX. A wrapper+env-file model gives platform parity and avoids global token exposure.
+
+```diff
+--- a/plan.md
++++ b/plan.md
+@@ Token storage strategies
+-| On Windows, neither strategy applies — the token must be in the user's system environment
++| On Windows, `env-file` is supported via a generated wrapper script (`service-run-{service_id}.cmd` or `.ps1`)
++| that reads `{data_dir}/service-env-{service_id}` and launches `lore --robot service run ...`.
++| `embedded` remains opt-in and warned as less secure.
+
+@@ Windows: schtasks
+- Token handling on Windows: The env var must be set system-wide via `setx`
++ Token handling on Windows:
++ - `env-file` (default): wrapper script reads token from private file at runtime
++ - `embedded`: token passed via wrapper-set environment variable
++ - `system_env`: still supported as fallback
+```
+
+6. **Add run heartbeat and stale-run detection**
+Why this improves the plan: `running` state can become misleading after crashes or stale locks. Heartbeat metadata makes status accurate and improves incident triage.
+
+```diff
+--- a/plan.md
++++ b/plan.md
+@@ Status File / Schema
++ /// In-flight run metadata for crash/stale detection
++ #[serde(skip_serializing_if = "Option::is_none")]
++ pub current_run: Option<CurrentRunState>,
++
++pub struct CurrentRunState {
++    pub run_id: String,
++    pub started_at_ms: i64,
++    pub last_heartbeat_ms: i64,
++    pub pid: u32,
++}
+
+@@ lore service status
+- - `running` — currently executing (sync_pipeline lock held)
++ - `running` — currently executing with live heartbeat
++ - `running_stale` — in-flight metadata exists but heartbeat exceeded stale threshold
+```
+
+7. **Upgrade drift detection from “loaded/unloaded” to spec-level drift**
+Why this improves the plan: platform state alone misses manual edits to unit/plist/wrapper files. Spec-hash drift gives reliable “what changed?” diagnostics and safe regeneration.
+
+```diff
+--- a/plan.md
++++ b/plan.md
+@@ Install Manifest / Schema
++ /// Hash of generated scheduler artifacts and command spec
++ pub spec_hash: String,
+
+@@ lore service status
+- Detects manifest/platform drift and reports it
++ Detects:
++ - platform drift (loaded/unloaded mismatch)
++ - spec drift (artifact content hash mismatch)
++ - command drift (sync command differs from manifest)
+
+@@ lore service repair
++ Add `--regenerate` to rewrite scheduler artifacts from manifest when spec drift is detected.
++ This is non-destructive and does not delete status/log history.
+```
+
+8. **Add safe operational modes: `install --dry-run` and `doctor --fix`**
+Why this improves the plan: dry-run reduces risk before writing OS scheduler files; fix-mode improves operator ergonomics and lowers support burden.
+
+```diff
+--- a/plan.md
++++ b/plan.md
+@@ lore service install
++ Add `--dry-run`:
++ - validates config/token/prereqs
++ - renders service files and planned commands
++ - writes nothing, executes nothing
+
+@@ lore service doctor
++ Add `--fix` for safe, non-destructive remediations:
++ - create missing dirs
++ - correct file permissions on env/wrapper files
++ - run `systemctl --user daemon-reload` when applicable
++ - report applied fixes in robot output
+```
+
+9. **Define explicit schema migration behavior (not just `schema_version` fields)**
+Why this improves the plan: version fields without migration policy become operational risk during upgrades.
+
+```diff
+--- a/plan.md
++++ b/plan.md
+@@ ServiceManifest Read/Write
+- `ServiceManifest::read(path: &Path) -> Result<Option<Self>, LoreError>`
++ `ServiceManifest::read_and_migrate(path: &Path) -> Result<Option<Self>, LoreError>`
++ - Migrates known older schema versions to current in-memory model
++ - Rewrites migrated file atomically
++ - Fails with actionable `ServiceCorruptState` for unknown future major versions
+
+@@ SyncStatusFile Read/Write
+- `SyncStatusFile::read(path: &Path) -> Result<Option<Self>, LoreError>`
++ `SyncStatusFile::read_and_migrate(path: &Path) -> Result<Option<Self>, LoreError>`
+```
+
+If you want, I can produce a fully rewritten v5 plan text that integrates all nine changes coherently section-by-section.

plans/plan-to-beads-v2-draft.md

@@ -0,0 +1,250 @@
+# plan-to-beads v2 — Draft for Review
+
+This is a draft of the improved skill. Review before applying to `~/.claude/skills/plan-to-beads/SKILL.md`.
+
+---
+
+```markdown
+---
+name: plan-to-beads
+description: Transforms markdown implementation plans into granular, agent-ready beads with dependency graphs. Each bead is fully self-contained — an agent can execute it with zero external context. Triggers on "break down this plan", "create beads from", "convert to beads", "make issues from plan".
+argument-hint: "[path/to/plan.md]"
+---
+
+# Plan to Beads Conversion
+
+## The Prime Directive
+
+**Every bead must be executable by an agent that has ONLY the bead description.** No plan document. No Slack context. No "see the PRD." The bead IS the spec. If an agent can't start coding within 60 seconds of reading the bead, it's not ready.
+
+## Workflow
+
+```
+┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
+│ 1. PARSE │──▶│ 2. MINE  │──▶│ 3. BUILD │──▶│ 4. LINK  │──▶│ 5. AUDIT │
+│ Structure│   │ Context  │   │ Beads    │   │ Deps     │   │ Quality  │
+└──────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────┘
+```
+
+### 1. Parse Structure
+
+Read the plan document. Identify:
+- **Epics**: Major sections / phases / milestones
+- **Tasks**: Implementable units with clear outcomes (1-4 hour scope)
+- **Subtasks**: Granular steps within tasks
+
+### 2. Mine Context
+
+This is the critical step. For EACH identified task, extract everything an implementing agent will need.
+
+#### From the plan document:
+
+| Extract | Where to look | Example |
+|---------|--------------|---------|
+| **Rationale** | Intro paragraphs, "why" sections | "We need this because the current approach causes N+1 queries" |
+| **Approach details** | Implementation notes, code snippets, architecture decisions | "Use a 5-stage pipeline: SEED → HYDRATE → ..." |
+| **Test requirements** | TDD sections, acceptance criteria, "verify by" notes | "Test that empty input returns empty vec" |
+| **Edge cases & risks** | Warnings, gotchas, "watch out for" notes | "Multi-byte UTF-8 chars can cause panics at byte boundaries" |
+| **Data shapes** | Type definitions, struct descriptions, API contracts | "TimelineEvent { kind: EventKind, timestamp: DateTime, ... }" |
+| **File paths** | Explicit mentions or inferable from module structure | "src/core/timeline_seed.rs" |
+| **Dependencies on other tasks** | "requires X", "after Y is done", "uses Z from step N" | "Consumes the TimelineEvent struct from the types task" |
+| **Verification commands** | Test commands, CLI invocations, expected outputs | "cargo test timeline_seed -- --nocapture" |
+
+#### From the codebase:
+
+Search the codebase to supplement what the plan says:
+- Find existing files mentioned or implied by the plan
+- Discover patterns the task should follow (e.g., how existing similar modules are structured)
+- Check test files for naming conventions and test infrastructure in use
+- Confirm exact file paths rather than guessing
+
+Use codebase search tools (WarpGrep, Explore agent, or targeted Grep/Glob) appropriate to the scope of what you need to find.
+
+### 3. Build Beads
+
+Use `br` exclusively.
+
+| Type | Priority | Command |
+|------|----------|---------|
+| Epic | 1 | `br create "Epic: [Title]" -p 1` |
+| Task | 2-3 | `br create "[Verb] [Object]" -p 2` |
+| Subtask | 3-4 | `br q "[Verb] [Object]"` |
+
+**Granularity target**: Each bead completable in 1-4 hours by one agent.
+
+#### Description Templates
+
+Use the **full template** for all task-level beads. Use the **light template** only for trivially small tasks (config change, single-line fix, add a re-export).
+
+##### Full Template (default)
+
+```
+## Background
+[WHY this exists. What problem it solves. How it fits into the larger system.
+Include enough context that an agent unfamiliar with the project understands
+the purpose. Reference architectural patterns in use.]
+
+## Approach
+[HOW to implement. Be specific:
+- Data structures / types to create or use (include field names and types)
+- Algorithms or patterns to follow
+- Code snippets from the plan if available
+- Which existing code to reference for patterns (exact file paths)]
+
+## Acceptance Criteria
+
+### Specified (from plan — implement as-is)
+- [ ] <criteria explicitly stated in the plan>
+- [ ] <criteria explicitly stated in the plan>
+
+### Proposed (inferred — confirm with user before implementing) [?]
+- [ ] [?] <criteria the agent inferred but the plan didn't specify>
+- [ ] [?] <criteria the agent inferred but the plan didn't specify>
+
+**ASSUMPTION RULE**: If proposed criteria exceed ~30% of total, STOP.
+The bead needs human input before it's ready for implementation. Flag it
+in the audit output and ask the user to refine the ACs.
+
+## Files
+[Exact paths to create or modify. Confirmed by searching the codebase.]
+- CREATE: src/foo/bar.rs
+- MODIFY: src/foo/mod.rs (add pub mod bar)
+- MODIFY: tests/foo_tests.rs (add test module)
+
+## TDD Anchor
+[The first test to write. This grounds the agent's work.]
+RED: Write `test_<name>` in `<test_file>` that asserts <specific behavior>.
+GREEN: Implement the minimal code to make it pass.
+VERIFY: <project's test command> <pattern>
+
+[If the plan specifies additional tests, list them all:]
+- test_empty_input_returns_empty_vec
+- test_single_issue_produces_one_event
+- test_handles_missing_fields_gracefully
+
+## Edge Cases
+[Gotchas, risks, things that aren't obvious. Pulled from the plan's warnings,
+known issues, or your analysis of the approach.]
+- <edge case 1>
+- <edge case 2>
+
+## Dependency Context
+[For each dependency, explain WHAT it provides that this bead consumes.
+Not just "depends on bd-xyz" but "uses the `TimelineEvent` struct and
+`SeedConfig` type defined in bd-xyz".]
+```
+
+##### Light Template (trivially small tasks only)
+
+Use this ONLY when the task is a one-liner or pure mechanical change (add a re-export, flip a config flag, rename a constant). If there's any ambiguity about approach, use the full template.
+
+```
+## What
+[One sentence: what to do and where.]
+
+## Acceptance Criteria
+- [ ] <single binary criterion>
+
+## Files
+- MODIFY: <exact path>
+```
+
+### 4. Link Dependencies
+
+```bash
+br dep add [blocker-id] [blocked-id]
+```
+
+Dependency patterns:
+- Types/structs → code that uses them
+- Infrastructure (DB, config) → features that need them
+- Core logic → extensions/enhancements
+- Tests may depend on test helpers
+
+**Critical**: When linking deps, update the "Dependency Context" section in the blocked bead to describe exactly what it receives from the blocker.
+
+### 5. Audit Quality
+
+Before reporting, review EVERY bead against this checklist:
+
+| Check | Pass criteria |
+|-------|--------------|
+| **Self-contained?** | Agent can start coding in 60 seconds with ONLY this description |
+| **TDD anchor?** | First test to write is named and described |
+| **Binary criteria?** | Every acceptance criterion is pass/fail, not subjective |
+| **Exact paths?** | File paths verified against codebase, not guessed |
+| **Edge cases?** | At least 1 non-obvious gotcha identified |
+| **Dep context?** | Each dependency explains WHAT it provides, not just its ID |
+| **Approach specifics?** | Types, field names, patterns — not "implement the thing" |
+| **Assumption budget?** | Proposed [?] criteria are <30% of total ACs |
+
+If a bead fails any check, fix it before moving on. If the assumption budget is exceeded, flag the bead for human review rather than inventing more ACs.
+
+## Assumption & AC Guidance
+
+Agents filling in beads will inevitably encounter gaps in the plan. The rules:
+
+1. **Never silently fill gaps.** If the plan doesn't specify a behavior, don't assume one and bury it in the ACs. Mark it `[?]` so the implementing agent knows to ask.
+
+2. **Specify provenance on every AC.** Specified = from the plan. Proposed = your inference. The implementing agent treats these differently:
+   - **Specified**: implement without question
+   - **Proposed [?]**: pause and confirm with the user before implementing
+
+3. **The 30% rule.** If more than ~30% of ACs on a bead are proposed/inferred, the plan was too vague for this task. Don't create the bead as-is. Instead:
+   - Create it with status noting "needs AC refinement"
+   - List the open questions explicitly
+   - Flag it in the output report under "Beads Needing Human Input"
+
+4. **Prefer smaller scope over more assumptions.** If you're unsure whether a task should handle edge case X, make the bead's scope explicitly exclude it and note it as a potential follow-up. A bead that does less but does it right beats one that guesses wrong.
+
+5. **Implementing agents: honor the markers.** When you encounter `[?]` on an AC, you MUST ask the user before implementing that behavior. Do not silently resolve it in either direction.
+
+## Output Format
+
+After completion, report:
+
+```
+## Beads Created: N total (X epics, Y tasks, Z subtasks)
+
+### Quality Audit
+- Beads scoring 4+: N/N (target: 100%)
+- [list any beads that needed extra attention and why]
+
+### Beads Needing Human Input
+[List any beads where proposed ACs exceeded 30%, or where significant
+ambiguity in the plan made self-contained descriptions impossible.
+Include the specific open questions for each.]
+
+### Critical Path
+[blocker] → [blocked] → [blocked]
+
+### Ready to Start
+- bd-xxx: [Title] — [one-line summary of what agent will do]
+- bd-yyy: [Title] — [one-line summary of what agent will do]
+
+### Dependency Graph
+[Brief visualization or description of the dep structure]
+```
+
+## Risk Tiers
+
+| Operation | Tier | Behavior |
+|-----------|------|----------|
+| `br create` | SAFE | Auto-proceed |
+| `br dep add` | SAFE | Auto-proceed |
+| `br update --description` | CAUTION | Verify content |
+| Bulk creation (>20 beads) | CAUTION | Confirm count first |
+
+## Anti-Patterns
+
+| Anti-Pattern | Why it's bad | Fix |
+|-------------|-------------|-----|
+| "Implement the pipeline stage" | Agent doesn't know WHAT to implement | Name the types, the function signatures, the test |
+| "See plan for details" | Plan isn't available to the agent | Copy the relevant details INTO the bead |
+| "Files: probably src/foo/" | Agent wastes time finding the right file | Search the codebase, confirm exact paths |
+| "Should work correctly" | Not binary, not testable | "test_x passes" or "output matches Y" |
+| No TDD anchor | Agent doesn't know where to start | Always specify the first test to write |
+| "Depends on bd-xyz" (without context) | Agent doesn't know what bd-xyz provides | "Uses FooStruct and bar() function from bd-xyz" |
+| Single-line description | Score 1 bead, agent is stuck | Use the full template, every section |
+| Silently invented ACs | User surprised by implementation choices | Mark inferred ACs with [?], honor the 30% rule |
+```

plans/time-decay-expert-scoring.feedback-1.md

@@ -0,0 +1,114 @@
+Your plan is strong directionally, but I’d revise it in 8 key places to avoid regressions and make it significantly more useful in production.
+
+1. **Split reviewer signals into “participated” vs “assigned-only”**
+Reason: today’s inflation problem is often assignment noise. Treating `mr_reviewers` equal to real review activity still over-ranks passive reviewers.
+
+```diff
+@@ Per-signal contributions
+-| Reviewer (reviewed MR touching path) | 10 | 90 days |
++| ReviewerParticipated (left DiffNote on MR/path) | 10 | 90 days |
++| ReviewerAssignedOnly (in mr_reviewers, no DiffNote by that user on MR/path) | 3 | 45 days |
+```
+
+```diff
+@@ Scoring Formula
+-score = reviewer_mr * reviewer_weight + ...
++score = reviewer_participated * reviewer_weight
++      + reviewer_assigned_only * reviewer_assignment_weight
++      + ...
+```
+
+2. **Cap/saturate note intensity per MR**
+Reason: raw per-note addition can still reward “comment storms.” Use diminishing returns.
+
+```diff
+@@ Rust-Side Aggregation
+-- Notes: Vec<i64> (timestamps) from diffnote_reviewer
++-- Notes grouped per (username, mr_id): note_count + max_ts
++-- Note contribution per MR uses diminishing returns:
++-- note_score_mr = note_bonus * ln(1 + note_count) * decay(now - ts, note_hl)
+```
+
+3. **Use better event timestamps than `m.updated_at` for file-change signals**
+Reason: `updated_at` is noisy (title edits, metadata touches) and creates false recency.
+
+```diff
+@@ SQL Restructure
+- signal 3/4 seen_at = m.updated_at
++ signal 3/4 activity_ts = COALESCE(m.merged_at, m.closed_at, m.created_at, m.updated_at)
+```
+
+4. **Don’t stream raw note rows to Rust; pre-aggregate in SQL**
+Reason: current plan removes SQL grouping and can blow up memory/latency on large repos.
+
+```diff
+@@ SQL Restructure
+-SELECT username, signal, mr_id, note_id, ts FROM signals
++WITH raw_signals AS (...),
++aggregated AS (
++  -- 1 row per (username, signal_class, mr_id) for MR-level signals
++  -- 1 row per (username, mr_id) for note_count + max_ts
++)
++SELECT username, signal_class, mr_id, qty, ts FROM aggregated
+```
+
+5. **Replace fixed `"24m"` with model-driven cutoff**
+Reason: hardcoded 24m is arbitrary and tied to current weights/half-lives only.
+
+```diff
+@@ Default --since Change
+-Expert mode: "6m" -> "24m"
++Expert mode default window derived from scoring.max_age_days (default 1095 days / 36m).
++Formula guidance: choose max_age where max possible single-event contribution < epsilon (e.g. 0.25 points).
++Add `--all-history` to disable cutoff for diagnostics.
+```
+
+6. **Validate scoring config explicitly**
+Reason: silent bad configs (`half_life_days = 0`, negative weights) create undefined behavior.
+
+```diff
+@@ ScoringConfig (config.rs)
+ pub struct ScoringConfig {
+   pub author_weight: i64,
+   pub reviewer_weight: i64,
+   pub note_bonus: i64,
++  pub reviewer_assignment_weight: i64,   // default: 3
+   pub author_half_life_days: u32,
+   pub reviewer_half_life_days: u32,
+   pub note_half_life_days: u32,
++  pub reviewer_assignment_half_life_days: u32, // default: 45
++  pub max_age_days: u32, // default: 1095
+ }
+@@ Config::load_from_path
++validate_scoring(&config.scoring)?; // weights >= 0, half_life_days > 0, max_age_days >= 30
+```
+
+7. **Keep raw float score internally; round only for display**
+Reason: rounding before sort causes avoidable ties/rank instability.
+
+```diff
+@@ Rust-Side Aggregation
+-Round to i64 for Expert.score field
++Compute `raw_score: f64`, sort by raw_score DESC.
++Expose integer `score` for existing UX.
++Optionally expose `score_raw` and `score_components` in robot JSON when `--explain-score`.
+```
+
+8. **Add confidence + data-completeness metadata**
+Reason: rankings are misleading if `mr_file_changes` coverage is poor.
+
+```diff
+@@ ExpertResult / Output
++confidence: "high" | "medium" | "low"
++coverage: { mrs_with_file_changes, total_mrs_in_window, percent }
++warning when coverage < threshold (e.g. 70%)
+```
+
+```diff
+@@ Verification
+ 4. cargo test
++5. ubs src/cli/commands/who.rs src/core/config.rs
++6. Benchmark query_expert on representative DB (latency + rows scanned before/after)
+```
+
+If you want, I can rewrite your full plan document into a clean “v2” version that already incorporates these diffs end-to-end.

plans/time-decay-expert-scoring.feedback-2.md

@@ -0,0 +1,132 @@
+The plan is strong, but I’d revise it in 10 places to improve correctness, scalability, and operator trust.
+
+1. **Add rename/old-path awareness (correctness gap)**
+Analysis: right now both existing code and your plan still center on `position_new_path` / `new_path` matches (`src/cli/commands/who.rs:643`, `src/cli/commands/who.rs:681`). That misses expertise on renamed/deleted paths and under-ranks long-time owners after refactors.
+
+```diff
+@@ ## Context
+-This produces two compounding problems:
++This produces three compounding problems:
+@@
+ 2. **Reviewer inflation**: ...
++3. **Path-history blindness**: Renamed/moved files lose historical expertise because matching relies on current-path fields only.
+
+@@ ### 3. SQL Restructure (who.rs)
+-AND n.position_new_path {path_op}
++AND (n.position_new_path {path_op} OR n.position_old_path {path_op})
+
+-AND fc.new_path {path_op}
++AND (fc.new_path {path_op} OR fc.old_path {path_op})
+```
+
+2. **Follow rename chains for queried paths**
+Analysis: matching `old_path` helps, but true continuity needs alias expansion (A→B→C). Without this, expertise before multi-hop renames is fragmented.
+
+```diff
+@@ ### 3. SQL Restructure (who.rs)
++**Path alias expansion**: Before scoring, resolve a bounded rename alias set (default max depth: 20)
++from `mr_file_changes(change_type='renamed')`. Query signals against all aliases.
++Output includes `path_aliases_used` for transparency.
+```
+
+3. **Use hybrid SQL pre-aggregation instead of fully raw rows**
+Analysis: the “raw row” design is simpler but will degrade on large repos with heavy DiffNote volume. Pre-aggregating to `(user, mr)` for MR signals and `(user, mr, note_count)` for note signals keeps memory/latency predictable.
+
+```diff
+@@ ### 3. SQL Restructure (who.rs)
+-The SQL CTE ... removes the outer GROUP BY aggregation. Instead, it returns raw signal rows:
+-SELECT username, signal, mr_id, note_id, ts FROM signals
++Use hybrid aggregation:
++- SQL returns MR-level rows for author/reviewer signals (1 row per user+MR+signal_class)
++- SQL returns note groups (1 row per user+MR with note_count, max_ts)
++- Rust applies decay + ln(1+count) + final ranking.
+```
+
+4. **Make timestamp policy state-aware (merged vs opened)**
+Analysis: replacing `updated_at` with only `COALESCE(merged_at, created_at)` over-decays long-running open MRs. Open MRs need recency from active lifecycle; merged MRs should anchor to merge time.
+
+```diff
+@@ ### 3. SQL Restructure (who.rs)
+-Replace m.updated_at with COALESCE(m.merged_at, m.created_at)
++Use state-aware timestamp:
++activity_ts =
++  CASE
++    WHEN m.state = 'merged' THEN COALESCE(m.merged_at, m.updated_at, m.created_at, m.last_seen_at)
++    WHEN m.state = 'opened' THEN COALESCE(m.updated_at, m.created_at, m.last_seen_at)
++  END
+```
+
+5. **Replace fixed `24m` with config-driven max age**
+Analysis: `24m` is reasonable now, but brittle after tuning weights/half-lives. Tie cutoff to config so model behavior remains coherent as parameters evolve.
+
+```diff
+@@ ### 1. ScoringConfig (config.rs)
++pub max_age_days: u32,                  // default: 730 (or 1095)
+
+@@ ### 5. Default --since Change
+-Expert mode: "6m" -> "24m"
++Expert mode default window derives from `scoring.max_age_days`
++unless user passes `--since` or `--all-history`.
+```
+
+6. **Add reproducible scoring time via `--as-of`**
+Analysis: decayed ranking is time-sensitive; debugging and tests become flaky without a fixed reference clock. This improves reliability and incident triage.
+
+```diff
+@@ ## Files to Modify
+-2. src/cli/commands/who.rs
++2. src/cli/commands/who.rs
++3. src/cli/mod.rs
++4. src/main.rs
+
+@@ ### 5. Default --since Change
++Add `--as-of <RFC3339|YYYY-MM-DD>` to score at a fixed timestamp.
++`resolved_input` includes `as_of_ms` and `as_of_iso`.
+```
+
+7. **Add explainability output (`--explain-score`)**
+Analysis: decayed multi-signal ranking will be disputed without decomposition. Show components and top evidence MRs to make results actionable and debuggable.
+
+```diff
+@@ ## Rejected Ideas (with rationale)
+-- **`--explain-score` flag with component breakdown**: ... deferred
++**Included in this iteration**: `--explain-score` adds per-user score components
++(`author`, `review_participated`, `review_assigned`, `notes`) plus top evidence MRs.
+```
+
+8. **Add confidence/coverage metadata**
+Analysis: rankings can look precise while data is incomplete (`mr_file_changes` gaps, sparse DiffNotes). Confidence fields prevent false certainty.
+
+```diff
+@@ ### 4. Rust-Side Aggregation (who.rs)
++Compute and emit:
++- `coverage`: {mrs_considered, mrs_with_file_changes, mrs_with_diffnotes, percent}
++- `confidence`: high|medium|low (threshold-based)
+```
+
+9. **Add index migration for new query shapes**
+Analysis: your new `EXISTS/NOT EXISTS` reviewer split and path dual-matching will need better indexes; current `who` indexes are not enough for author+path+time combinations.
+
+```diff
+@@ ## Files to Modify
++3. **`migrations/021_who_decay_indexes.sql`** — indexes for decay query patterns:
++   - notes(diffnote path + author + created_at + discussion_id) partial
++   - notes(old_path variant) partial
++   - mr_file_changes(project_id, new_path, merge_request_id)
++   - mr_file_changes(project_id, old_path, merge_request_id) partial
++   - merge_requests(state, merged_at, updated_at, created_at)
+```
+
+10. **Expand tests to invariants and determinism**
+Analysis: example-based tests are good, but ranking systems need invariant tests to avoid subtle regressions.
+
+```diff
+@@ ### 7. New Tests (TDD)
++**`test_score_monotonicity_by_age`**: same signal, older timestamp never scores higher
++**`test_row_order_independence`**: shuffled SQL row order yields identical ranking
++**`test_as_of_reproducibility`**: same data + same `--as-of` => identical output
++**`test_rename_alias_chain_scoring`**: expertise carries across A->B->C rename chain
++**`test_overlap_participated_vs_assigned_counts`**: overlap reflects split reviewer semantics
+```
+
+If you want, I can produce a full consolidated `v2` plan doc patch (single unified diff against `plans/time-decay-expert-scoring.md`) rather than per-change snippets.

plans/time-decay-expert-scoring.feedback-3.md

@@ -0,0 +1,167 @@
+**Critical Plan Findings First**
+1. The proposed index `idx_notes_mr_path_author ON notes(noteable_id, ...)` will fail: `notes.noteable_id` does not exist in schema (`migrations/002_issues.sql:74`).
+2. Rename awareness is only applied in scoring queries, not in path resolution probes; today `build_path_query()` and `suffix_probe()` only inspect `position_new_path`/`new_path` (`src/cli/commands/who.rs:465`, `src/cli/commands/who.rs:591`), so old-path queries can still miss.
+3. A fixed `"24m"` default window is brittle once half-lives become configurable; it can silently truncate meaningful history for larger half-lives.
+
+Below are the revisions I’d make to your plan.
+
+1. **Fix migration/index architecture (blocking correctness + perf)**
+Rationale: prevents migration failure and aligns indexes to actual query shapes.
+```diff
+diff --git a/plan.md b/plan.md
+@@ ### 6. Index Migration (db.rs)
+- -- Support EXISTS subquery for reviewer participation check
+- CREATE INDEX IF NOT EXISTS idx_notes_mr_path_author
+-   ON notes(noteable_id, position_new_path, author_username)
+-   WHERE note_type = 'DiffNote' AND is_system = 0;
++ -- Support reviewer participation joins (notes -> discussions -> MR)
++ CREATE INDEX IF NOT EXISTS idx_notes_diffnote_discussion_author_created
++   ON notes(discussion_id, author_username, created_at)
++   WHERE note_type = 'DiffNote' AND is_system = 0;
++
++ -- Path-first indexes for global and project-scoped path lookups
++ CREATE INDEX IF NOT EXISTS idx_mfc_new_path_project_mr
++   ON mr_file_changes(new_path, project_id, merge_request_id);
++ CREATE INDEX IF NOT EXISTS idx_mfc_old_path_project_mr
++   ON mr_file_changes(old_path, project_id, merge_request_id)
++   WHERE old_path IS NOT NULL;
+@@
+- -- Support state-aware timestamp selection
+- CREATE INDEX IF NOT EXISTS idx_mr_state_timestamps
+-   ON merge_requests(state, merged_at, closed_at, updated_at, created_at);
++ -- Removed: low-selectivity timestamp composite index; joins are MR-id driven.
+```
+
+2. **Restructure SQL around `matched_mrs` CTE instead of repeating OR path clauses**
+Rationale: better index use, less duplicated logic, cleaner maintenance.
+```diff
+diff --git a/plan.md b/plan.md
+@@ ### 3. SQL Restructure (who.rs)
+- WITH raw AS (
+-   -- 5 UNION ALL subqueries (signals 1, 2, 3, 4a, 4b)
+- ),
++ WITH matched_notes AS (
++   -- DiffNotes matching new_path
++   ...
++   UNION ALL
++   -- DiffNotes matching old_path
++   ...
++ ),
++ matched_file_changes AS (
++   -- file changes matching new_path
++   ...
++   UNION ALL
++   -- file changes matching old_path
++   ...
++ ),
++ matched_mrs AS (
++   SELECT DISTINCT mr_id, project_id FROM matched_notes
++   UNION
++   SELECT DISTINCT mr_id, project_id FROM matched_file_changes
++ ),
++ raw AS (
++   -- signals sourced from matched_mrs + matched_notes
++ ),
+```
+
+3. **Replace correlated `EXISTS/NOT EXISTS` reviewer split with one precomputed participation set**
+Rationale: same semantics, lower query cost, easier reasoning.
+```diff
+diff --git a/plan.md b/plan.md
+@@ Signal 4 splits into two
+- Signal 4a uses an EXISTS subquery ...
+- Signal 4b uses NOT EXISTS ...
++ Build `reviewer_participation(mr_id, username)` once from matched DiffNotes.
++ Then classify `mr_reviewers` rows via LEFT JOIN:
++ - participated: `rp.username IS NOT NULL`
++ - assigned-only: `rp.username IS NULL`
++ This avoids correlated EXISTS scans per reviewer row.
+```
+
+4. **Make default `--since` derived from half-life + decay floor, not hardcoded 24m**
+Rationale: remains mathematically consistent when config changes.
+```diff
+diff --git a/plan.md b/plan.md
+@@ ### 1. ScoringConfig (config.rs)
++ pub decay_floor: f64, // default: 0.05
+@@ ### 5. Default --since Change
+- Expert mode: "6m" -> "24m"
++ Expert mode default window is computed:
++ default_since_days = ceil(max_half_life_days * log2(1.0 / decay_floor))
++ With defaults (max_half_life=180, floor=0.05), this is ~26 months.
++ CLI `--since` still overrides; `--all-history` still disables windowing.
+```
+
+5. **Use `log2(1+count)` for notes instead of `ln(1+count)`**
+Rationale: keeps 1 note ~= 1 unit (with `note_bonus=1`) while preserving diminishing returns.
+```diff
+diff --git a/plan.md b/plan.md
+@@ Scoring Formula
+- note_contribution(mr) = note_bonus * ln(1 + note_count_in_mr) * 2^(-days_elapsed / note_half_life)
++ note_contribution(mr) = note_bonus * log2(1 + note_count_in_mr) * 2^(-days_elapsed / note_half_life)
+```
+
+6. **Guarantee deterministic float aggregation and expose `score_raw`**
+Rationale: avoids hash-order drift and explainability mismatch vs rounded integer score.
+```diff
+diff --git a/plan.md b/plan.md
+@@ ### 4. Rust-Side Aggregation (who.rs)
+- HashMap<i64, ...>
++ BTreeMap<i64, ...> (or sort keys before accumulation) for deterministic summation order
++ Use compensated summation (Kahan/Neumaier) for stable f64 totals
+@@
+- Sort on raw `f64` score ... round only for display
++ Keep `score_raw` internally and expose when `--explain-score` is active.
++ `score` remains integer for backward compatibility.
+```
+
+7. **Extend rename awareness to query resolution (not only scoring)**
+Rationale: fixes user-facing misses for old path input and suffix lookup.
+```diff
+diff --git a/plan.md b/plan.md
+@@ Path rename awareness
+- All signal subqueries match both old and new path columns
++ Also update `build_path_query()` probes and suffix probe:
++ - exact_exists: new_path OR old_path (notes + mr_file_changes)
++ - prefix_exists: new_path LIKE OR old_path LIKE
++ - suffix_probe: union of notes.position_new_path, notes.position_old_path,
++   mr_file_changes.new_path, mr_file_changes.old_path
+```
+
+8. **Tighten CLI/output contracts for new flags**
+Rationale: avoids payload bloat/ambiguity and keeps robot clients stable.
+```diff
+diff --git a/plan.md b/plan.md
+@@ ### 5b. Score Explainability via `--explain-score`
++ `--explain-score` conflicts with `--detail` (mutually exclusive)
++ `resolved_input` includes `as_of_ms`, `as_of_iso`, `scoring_model_version`
++ robot output includes `score_raw` and `components` only when explain is enabled
+```
+
+9. **Add confidence metadata (promote from rejected to accepted)**
+Rationale: makes ranking more actionable and trustworthy with sparse evidence.
+```diff
+diff --git a/plan.md b/plan.md
+@@ Rejected Ideas (with rationale)
+- Confidence/coverage metadata: ... Deferred to avoid scope creep
++ Confidence/coverage metadata: ACCEPTED (minimal v1)
++ Add per-user `confidence: low|medium|high` based on evidence breadth + recency.
++ Keep implementation lightweight (no extra SQL pass).
+```
+
+10. **Upgrade test and verification scope to include query-plan and clock semantics**
+Rationale: catches regressions your current tests won’t.
+```diff
+diff --git a/plan.md b/plan.md
+@@ 8. New Tests (TDD)
++ test_old_path_probe_exact_and_prefix
++ test_suffix_probe_uses_old_path_sources
++ test_since_relative_to_as_of_clock
++ test_explain_and_detail_are_mutually_exclusive
++ test_null_timestamp_fallback_to_created_at
++ test_query_plan_uses_path_indexes (EXPLAIN QUERY PLAN)
+@@ Verification
++ 7. EXPLAIN QUERY PLAN snapshots for expert query (exact + prefix) confirm index usage
+```
+
+If you want, I can produce a single consolidated “revision 3” plan document that fully merges all of the above into your original structure.

plans/time-decay-expert-scoring.feedback-4.md

@@ -0,0 +1,133 @@
+Your plan is already strong. The biggest remaining gaps are temporal correctness, indexability at scale, and ranking reliability under sparse/noisy evidence. These are the revisions I’d make.
+
+1. **Fix temporal correctness for `--as-of` (critical)**
+Analysis: Right now the plan describes `--as-of`, but the SQL only enforces lower bounds (`>= since`). If `as_of` is in the past, “future” events can still enter and get full weight (because elapsed is clamped). This breaks reproducibility.
+```diff
+@@ 3. SQL Restructure
+- AND n.created_at >= ?2
++ AND n.created_at BETWEEN ?2 AND ?4
+@@ Signal 3/4a/4b
+- AND {state_aware_ts} >= ?2
++ AND {state_aware_ts} BETWEEN ?2 AND ?4
+
+@@ 5a. Reproducible Scoring via --as-of
+- All decay computations use as_of_ms instead of SystemTime::now()
++ All event selection and decay computations are bounded by as_of_ms.
++ Query window is [since_ms, as_of_ms], never [since_ms, now_ms].
++ Add test: test_as_of_excludes_future_events.
+```
+
+2. **Resolve `closed`-state inconsistency**
+Analysis: The CASE handles `closed`, but all signal queries filter to `('opened','merged')`, making the `closed_at` branch dead code. Either include closed MRs intentionally or remove that logic. I’d include closed with a reduced multiplier.
+```diff
+@@ ScoringConfig (config.rs)
++ pub closed_mr_multiplier: f64, // default: 0.5
+
+@@ 3. SQL Restructure
+- AND m.state IN ('opened','merged')
++ AND m.state IN ('opened','merged','closed')
+
+@@ 4. Rust-Side Aggregation
++ if state == "closed" { contribution *= closed_mr_multiplier; }
+```
+
+3. **Replace `OR` path predicates with index-friendly `UNION ALL` branches**
+Analysis: `(new_path ... OR old_path ...)` often degrades index usage in SQLite. Split into two indexed branches and dedupe once. This improves planner stability and latency on large datasets.
+```diff
+@@ 3. SQL Restructure
+-WITH matched_notes AS (
+-  ... AND (n.position_new_path {path_op} OR n.position_old_path {path_op})
+-),
++WITH matched_notes AS (
++  SELECT ... FROM notes n WHERE ... AND n.position_new_path {path_op}
++  UNION ALL
++  SELECT ... FROM notes n WHERE ... AND n.position_old_path {path_op}
++),
++matched_notes_dedup AS (
++  SELECT DISTINCT id, discussion_id, author_username, created_at, project_id
++  FROM matched_notes
++),
+@@
+- JOIN matched_notes mn ...
++ JOIN matched_notes_dedup mn ...
+```
+
+4. **Add canonical path identity (rename-chain support)**
+Analysis: Direct `old_path/new_path` matching only handles one-hop rename scenarios. A small alias graph/table built at ingest time gives robust expertise continuity across A→B→C chains and avoids repeated SQL complexity.
+```diff
+@@ Files to Modify
+- 3. src/core/db.rs — Add migration for indexes...
++ 3. src/core/db.rs — Add migration for indexes + path_identity table
++ 4. src/core/ingest/*.rs — populate path_identity on rename events
++ 5. src/cli/commands/who.rs — resolve query path to canonical path_id first
+
+@@ Context
+- The fix has three parts:
++ The fix has four parts:
++ - Introduce canonical path identity so multi-hop renames preserve expertise
+```
+
+5. **Split scoring engine into a versioned core module**
+Analysis: `who.rs` is becoming a mixed CLI/query/math/output surface. Move scoring math and event normalization into `src/core/scoring/` with explicit model versions. This reduces regression risk and enables future model experiments.
+```diff
+@@ Files to Modify
++ 4. src/core/scoring/mod.rs — model interface + shared types
++ 5. src/core/scoring/model_v2_decay.rs — current implementation
++ 6. src/cli/commands/who.rs — orchestration only
+
+@@ 5b. Score Explainability
++ resolved_input includes scoring_model_version and scoring_model_name
+```
+
+6. **Add evidence confidence to reduce sparse-data rank spikes**
+Analysis: One recent MR can outrank broader, steadier expertise. Add a confidence factor derived from number of distinct evidence MRs and expose both `score_raw` and `score_adjusted`.
+```diff
+@@ Scoring Formula
++ confidence(user) = 1 - exp(-evidence_mr_count / 6.0)
++ score_adjusted = score_raw * confidence
+
+@@ 4. Rust-Side Aggregation
++ compute evidence_mr_count from unique MR ids across all signals
++ sort by score_adjusted DESC, then score_raw DESC, then last_seen DESC
+
+@@ 5b. --explain-score
++ include confidence and evidence_mr_count
+```
+
+7. **Add first-class bot/service-account filtering**
+Analysis: Reviewer inflation is not just assignment; bots and automation users can still pollute rankings. Make exclusion explicit and configurable.
+```diff
+@@ ScoringConfig (config.rs)
++ pub excluded_username_patterns: Vec<String>, // defaults include "*bot*", "renovate", "dependabot"
+
+@@ 3. SQL Restructure
++ AND username NOT MATCHES excluded patterns (applied in Rust post-query or SQL where feasible)
+
+@@ CLI
++ --include-bots (override exclusions)
+```
+
+8. **Tighten reviewer “participated” with substantive-note threshold**
+Analysis: A single “LGTM” note shouldn’t classify someone as engaged reviewer equivalent to real inline review. Use a minimum substantive threshold.
+```diff
+@@ ScoringConfig (config.rs)
++ pub reviewer_min_note_chars: u32, // default: 20
+
+@@ reviewer_participation CTE
+- SELECT DISTINCT ... FROM matched_notes
++ SELECT DISTINCT ... FROM matched_notes
++ WHERE LENGTH(TRIM(body)) >= ?reviewer_min_note_chars
+```
+
+9. **Add rollout safety: model compare mode + rank-delta diagnostics**
+Analysis: This is a scoring-model migration. You need safe rollout mechanics, not just tests. Add a compare mode so you can inspect rank deltas before forcing v2.
+```diff
+@@ CLI (who)
++ --scoring-model v1|v2|compare   (default: v2)
++ --max-rank-delta-report N       (compare mode diagnostics)
+
+@@ Robot output
++ include v1_score, v2_score, rank_delta when --scoring-model compare
+```
+
+If you want, I can produce a single consolidated “plan v4” document that applies all nine diffs cleanly into your original markdown.

plans/time-decay-expert-scoring.feedback-5.md

@@ -0,0 +1,128 @@
+**Best Revisions To Strengthen The Plan**
+
+1. **[Critical] Replace one-hop rename matching with canonical path identities**
+Analysis and rationale: Current `old_path OR new_path` fixes direct renames, but it still breaks on rename chains (`a.rs -> b.rs -> c.rs`) and split/move patterns. A canonical `path_identity` graph built from `mr_file_changes(old_path,new_path)` gives stable identity over time, which is the right architectural boundary for expertise history.
+```diff
+@@ ## Context
+-- Match both old and new paths in all signal queries AND path resolution probes so expertise survives file renames
++- Build canonical path identities from rename edges and score by identity, not raw path strings, so expertise survives multi-hop renames and moves
+
+@@ ## Files to Modify
+-2. **`src/cli/commands/who.rs`** — Core changes:
++2. **`src/cli/commands/who.rs`** — Core changes:
+    ...
+-   - Match both `new_path` and `old_path` in all signal queries (rename awareness)
++   - Resolve queried paths to `path_identity_id` and match all aliases in that identity set
++4. **`src/core/path_identity.rs`** — New module:
++   - Build/maintain rename graph from `mr_file_changes`
++   - Resolve path -> identity + aliases for probes/scoring
+```
+
+2. **[Critical] Shift scoring input from runtime CTE joins to a normalized `expertise_events` table**
+Analysis and rationale: Your SQL is correct but complex and expensive at query time. Precomputing normalized events at ingestion gives simpler, faster, and more reliable scoring queries; it also enables model versioning/backfills without touching raw MR/note tables each request.
+```diff
+@@ ## Files to Modify
+-3. **`src/core/db.rs`** — Add migration for indexes supporting the new query shapes
++3. **`src/core/db.rs`** — Add migrations for:
++   - `expertise_events` table (normalized scoring events)
++   - supporting indexes
++4. **`src/core/ingest/expertise_events.rs`** — New:
++   - Incremental upsert of events during sync/ingest
+
+@@ ## SQL Restructure (who.rs)
+-The SQL uses CTE-based dual-path matching and hybrid aggregation...
++Runtime SQL reads precomputed `expertise_events` filtered by path identity + time window.
++Heavy joins/aggregation move to ingest-time normalization.
+```
+
+3. **[High] Upgrade reviewer engagement model beyond char-count threshold**
+Analysis and rationale: `min_note_chars` is a useful guardrail but brittle (easy to game, penalizes concise high-quality comments). Add explicit review-state signals (`approved`, `changes_requested`) and trivial-comment pattern filtering to better capture real reviewer expertise.
+```diff
+@@ ## Scoring Formula
+-| **Reviewer Participated** (left DiffNote on MR/path) | 10 | 90 days |
++| **Reviewer Participated** (substantive DiffNote and/or formal review action) | 10 | 90 days |
++| **Review Decision: changes_requested** | 6 | 120 days |
++| **Review Decision: approved** | 4 | 75 days |
+
+@@ ### 1. ScoringConfig (config.rs)
+     pub reviewer_min_note_chars: u32,
++    pub reviewer_trivial_note_patterns: Vec<String>, // default: ["lgtm","+1","nit","ship it","👍"]
++    pub review_approved_weight: i64,                 // default: 4
++    pub review_changes_requested_weight: i64,        // default: 6
+```
+
+4. **[High] Make temporal semantics explicit and deterministic**
+Analysis and rationale: `--as-of` is good, but day parsing and boundary semantics can still cause subtle reproducibility issues. Define window as `[since_ms, as_of_ms)` and parse `YYYY-MM-DD` as end-of-day UTC (or explicit timezone) so user expectations match outputs.
+```diff
+@@ ### 5a. Reproducible Scoring via `--as-of`
+-- All event selection is bounded by `[since_ms, as_of_ms]`
++- All event selection is bounded by `[since_ms, as_of_ms)` (exclusive upper bound)
++- `YYYY-MM-DD` is interpreted as `23:59:59.999Z` unless `--timezone` is provided
++- Robot output includes `window_start_iso`, `window_end_iso`, `window_end_exclusive: true`
+```
+
+5. **[High] Replace fixed default `--since 24m` with contribution-floor auto cutoff**
+Analysis and rationale: A static window is simple but often over-scans data. Compute a model-derived horizon from a minimum contribution floor (for example `0.01` points) per signal; this keeps results equivalent while reducing query cost.
+```diff
+@@ ### 5. Default --since Change
+-Expert mode: `"6m"` -> `"24m"`
++Expert mode default: `--since auto`
++`auto` computes earliest relevant timestamp from configured weights/half-lives and `min_contribution_floor`
++Add config: `min_contribution_floor` (default: 0.01)
++`--since` still overrides, `--all-history` still bypasses cutoff
+```
+
+6. **[High] Add bot/service-account filtering now (not later)**
+Analysis and rationale: Bot activity can materially distort expertise rankings in real repos. This is low implementation cost with high quality gain and should be in v1 of the scoring revamp, not deferred.
+```diff
+@@ ### 1. ScoringConfig (config.rs)
++    pub excluded_username_patterns: Vec<String>, // default: ["bot","\\[bot\\]","service-account","ci-"]
+@@ ### 2. SQL Restructure (who.rs)
++Apply username exclusion in all signal sources unless `--include-bots` is set
+@@ ### 5b. Score Explainability via `--explain-score`
++Add `filtered_events` counts in robot output metadata
+```
+
+7. **[Medium] Enforce deterministic floating-point accumulation**
+Analysis and rationale: Even with small sets, unordered `HashMap` iteration can cause tiny platform-dependent ranking differences near ties. Sorting contributions and using Neumaier summation removes nondeterminism and stabilizes tests/CI.
+```diff
+@@ ### 4. Rust-Side Aggregation (who.rs)
+-Compute score as `f64`.
++Compute score as `f64` using deterministic contribution ordering:
++1) sort by (username, signal, mr_id, ts)
++2) sum with Neumaier compensation
++Tie-break remains `(raw_score DESC, last_seen DESC, username ASC)`
+```
+
+8. **[Medium] Strengthen explainability with evidence, not just totals**
+Analysis and rationale: Component totals help, but disputes usually need “why this user got this score now.” Add compact top evidence rows per component (`mr_id`, `ts`, `raw_contribution`) behind an optional mode.
+```diff
+@@ ### 5b. Score Explainability via `--explain-score`
+-Component breakdown only (4 floats per user).
++Add `--explain-score=summary|full`:
++`summary`: current 4-component totals
++`full`: adds top N evidence rows per component (default N=3)
++Robot output includes per-evidence `mr_id`, `signal`, `ts`, `contribution`
+```
+
+9. **[Medium] Make query plan strategy explicit: `UNION ALL` default for dual-path scans**
+Analysis and rationale: You currently treat `UNION ALL` as fallback if planner regresses. For SQLite, OR-across-indexed-columns regressions are common enough that defaulting to branch-split queries is often more predictable.
+```diff
+@@ **Index optimization fallback (UNION ALL split)**
+-Start with the simpler `OR` approach and only switch to `UNION ALL` if query plans confirm degradation.
++Use `UNION ALL` + dedup as default for dual-path matching.
++Keep `OR` variant as optional strategy flag for benchmarking/regression checks.
+```
+
+10. **[Medium] Add explicit performance SLO + benchmark gate**
+Analysis and rationale: This plan is query-heavy and ranking-critical; add measurable performance budgets so future edits do not silently degrade UX. Include synthetic fixture benchmarks for exact, prefix, and suffix path modes.
+```diff
+@@ ## Verification
++8. Performance regression gate:
++   - `cargo bench --bench who_expert_scoring`
++   - Dataset tiers: 100k, 1M, 5M notes
++   - SLOs: p95 exact path < 150ms, prefix < 250ms, suffix < 400ms on reference hardware
++   - Fail CI if regression > 20% vs stored baseline
+```
+
+If you want, I can produce a single consolidated “iteration 5” plan document with these changes already merged into your current structure.

plans/time-decay-expert-scoring.feedback-6.md

@@ -0,0 +1,134 @@
+I avoided everything already listed in your `Rejected Ideas` section and focused on net-new upgrades.
+
+1. Centralize MR temporal semantics in one `mr_activity` CTE (architecture + correctness)
+Why this improves the plan: right now the state-aware timestamp logic is repeated across multiple signal branches, while `closed_mr_multiplier` is applied later in Rust by string state checks. That split is brittle. A single `mr_activity` CTE removes drift risk, simplifies query maintenance, and avoids per-row state-string handling in Rust.
+
+```diff
+diff --git a/plan.md b/plan.md
+@@ SQL Restructure
++mr_activity AS (
++  SELECT
++    m.id AS mr_id,
++    m.project_id,
++    m.author_username,
++    m.state,
++    CASE
++      WHEN m.state = 'merged' THEN COALESCE(m.merged_at, m.created_at)
++      WHEN m.state = 'closed' THEN COALESCE(m.closed_at, m.created_at)
++      ELSE COALESCE(m.updated_at, m.created_at)
++    END AS activity_ts,
++    CASE
++      WHEN m.state = 'closed' THEN ?5
++      ELSE 1.0
++    END AS state_mult
++  FROM merge_requests m
++  WHERE m.state IN ('opened','merged','closed')
++),
+@@
+-... {state_aware_ts} AS seen_at, m.state AS mr_state
++... a.activity_ts AS seen_at, a.state_mult
+@@
+-SELECT username, signal, mr_id, qty, ts, mr_state FROM aggregated
++SELECT username, signal, mr_id, qty, ts, state_mult FROM aggregated
+```
+
+2. Parameterize `reviewer_min_note_chars` and tighten config validation (robustness)
+Why this improves the plan: inlining `reviewer_min_note_chars` into SQL text creates statement-cache churn and avoidable SQL-text variability. Also, current validation misses finite-range guards (`NaN`, absurd half-lives). Parameterization + stronger validation reduces weird failure modes.
+
+```diff
+diff --git a/plan.md b/plan.md
+@@ 1. ScoringConfig (config.rs)
+- reviewer_min_note_chars must be >= 0
++ reviewer_min_note_chars must be <= 4096
++ all half-life values must be <= 3650 (10 years safety cap)
++ closed_mr_multiplier must be finite and in (0.0, 1.0]
+@@ SQL Restructure
+-AND LENGTH(TRIM(COALESCE(n_body.body, ''))) >= {reviewer_min_note_chars}
++AND LENGTH(TRIM(COALESCE(n_body.body, ''))) >= ?6
+```
+
+3. Add path canonicalization before probes/scoring (correctness + UX)
+Why this improves the plan: rename-awareness helps only after path resolution succeeds. Inputs like `./src//foo.rs` or inconsistent trailing slashes can still miss. Canonicalizing query paths up front reduces false negatives and ambiguous suffix behavior.
+
+```diff
+diff --git a/plan.md b/plan.md
+@@ 3a. Path Resolution Probes (who.rs)
++Add `normalize_query_path()` before `build_path_query()`:
++- strip leading `./`
++- collapse repeated `/`
++- trim whitespace
++- preserve trailing `/` only for explicit prefix intent
++Expose both `path_input_original` and `path_input_normalized` in `resolved_input`.
+@@ New Tests
++test_path_normalization_handles_dot_and_double_slash
++test_path_normalization_preserves_explicit_prefix_semantics
+```
+
+4. Add epsilon-based tie buckets for stable ranking (determinism)
+Why this improves the plan: even with deterministic summation order, tiny `powf` platform differences can reorder near-equal scores. Tie bucketing keeps ordering stable and user-meaningful.
+
+```diff
+diff --git a/plan.md b/plan.md
+@@ 4. Rust-Side Aggregation (who.rs)
+-Sort on raw `f64` score — `(raw_score DESC, last_seen DESC, username ASC)`.
++Sort using a tie bucket:
++`score_bucket = (raw_score / 1e-9).floor() as i64`
++Order by `(score_bucket DESC, raw_score DESC, last_seen DESC, username ASC)`.
++This preserves precision while preventing meaningless micro-delta reorderings.
+@@ New Tests
++test_near_equal_scores_use_stable_tie_bucket_order
+```
+
+5. Add `--diagnose-score` aggregated diagnostics (operability)
+Why this improves the plan: `--explain-score` tells “why this user scored”, but not “why this query behaved oddly” (path ambiguity, dedup collapse, old_path contribution share, filtered bots, window exclusions). Lightweight aggregate diagnostics are high-value without per-MR drill-down complexity.
+
+```diff
+diff --git a/plan.md b/plan.md
+@@ CLI changes (who.rs)
++Add `--diagnose-score` flag (compatible with `--explain-score`, incompatible with `--detail`).
++When enabled, include:
++- matched_notes_raw_count
++- matched_notes_dedup_count
++- matched_file_changes_raw_count
++- matched_file_changes_dedup_count
++- rows_excluded_by_window_upper_bound
++- users_filtered_by_excluded_usernames
++- query_elapsed_ms
+@@ Robot output
++`diagnostics` object emitted only when `--diagnose-score` is set.
+```
+
+6. Add probe-optimized indexes for path resolution (performance)
+Why this improves the plan: current proposed indexes are optimized for scoring joins, but `build_path_query()` and `suffix_probe()` run existence/path-only probes where `author_username` is not constrained. Dedicated probe indexes will materially reduce latency for path lookup modes.
+
+```diff
+diff --git a/plan.md b/plan.md
+@@ 6. Index Migration (db.rs)
++-- Fast exact/prefix/suffix path probes on notes (no author predicate)
++CREATE INDEX IF NOT EXISTS idx_notes_new_path_project_created
++  ON notes(position_new_path, project_id, created_at)
++  WHERE note_type = 'DiffNote' AND is_system = 0 AND position_new_path IS NOT NULL;
++
++CREATE INDEX IF NOT EXISTS idx_notes_old_path_project_created
++  ON notes(position_old_path, project_id, created_at)
++  WHERE note_type = 'DiffNote' AND is_system = 0 AND position_old_path IS NOT NULL;
+```
+
+7. Add multi-path expert scoring (`--path` repeatable) with dedup across paths (feature + utility)
+Why this improves the plan: current model is single-path centric. Real ownership questions are usually subsystem-level. Repeatable paths/prefixes let users ask “who knows auth stack?” in one call. Dedup by `(username, signal, mr_id)` avoids double-counting same MR touching multiple requested paths.
+
+```diff
+diff --git a/plan.md b/plan.md
+@@ CLI/feature scope
++Add repeatable `--path` in expert mode:
++`lore who --expert --path src/auth/ --path src/session/`
++Optional `--path-file <file>` for large path sets (one per line).
+@@ SQL Restructure
++Add `requested_paths` CTE and match each source against that set.
++Ensure dedup key includes `(username, signal, mr_id)` so one MR contributes once per signal even if multiple paths match.
+@@ New Tests
++test_multi_path_query_unions_results_without_double_counting
++test_multi_path_with_overlap_prefixes_is_idempotent
+```
+
+These 7 revisions keep your current model direction intact, but reduce correctness drift risk, harden edge handling, improve query observability, and make the feature materially more useful for real ownership workflows.

plans/time-decay-expert-scoring.md

@@ -0,0 +1,688 @@
+---
+plan: true
+title: ""
+status: iterating
+iteration: 6
+target_iterations: 8
+beads_revision: 1
+related_plans: []
+created: 2026-02-08
+updated: 2026-02-12
+---
+
+# Time-Decay Expert Scoring Model
+
+## Context
+
+The `lore who --path` command currently uses flat weights to score expertise: each authored MR counts as 25 points, each reviewed MR as 10, each inline note as 1 — regardless of when the activity happened. This produces three compounding problems:
+
+1. **Temporal blindness**: Old activity counts the same as recent activity. Someone who authored a file 2 years ago ranks equivalently to someone who wrote it last week.
+2. **Reviewer inflation**: Senior reviewers (jdefting, zhayes) who rubber-stamp every MR via assignment accumulate inflated scores indistinguishable from reviewers who actually left substantive inline feedback. The `mr_reviewers` table captures assignment, not engagement.
+3. **Path-history blindness**: Renamed or moved files lose historical expertise because signal matching relies on `position_new_path` and `mr_file_changes.new_path` only. A developer who authored the file under its previous name gets zero credit after a rename.
+
+The fix has three parts:
+- Apply **exponential half-life decay** to each signal, grounded in cognitive science research
+- **Split the reviewer signal** into "participated" (left DiffNotes) vs "assigned-only" (in `mr_reviewers` but no inline comments), with different weights and decay rates
+- **Match both old and new paths** in all signal queries AND path resolution probes so expertise survives file renames
+
+## Research Foundation
+
+- **Ebbinghaus Forgetting Curve (1885)**: Memory retention follows exponential decay: `R = 2^(-t/h)` where h is the half-life
+- **Generation Effect (Slamecka & Graf, 1978)**: Producing information (authoring code) creates ~2x more durable memory traces than reading it (reviewing)
+- **Levels of Processing (Craik & Lockhart, 1972)**: Deeper cognitive engagement creates more durable memories — authoring > reviewing > commenting
+- **Half-Life Regression (Settles & Meeder, 2016, Duolingo)**: Exponential decay with per-signal-type half-lives is practical and effective at scale. Chosen over power law for additivity, bounded behavior, and intuitive parameterization
+- **Fritz et al. (2010, ICSE)**: "Degree-of-knowledge" model for code familiarity considers both authoring and interaction events with time-based decay
+
+## Scoring Formula
+
+```
+score(user, path) = Sum_i( weight_i * 2^(-days_elapsed_i / half_life_i) )
+```
+
+For note signals grouped per MR, a diminishing-returns function caps comment storms:
+```
+note_contribution(mr) = note_bonus * log2(1 + note_count_in_mr) * 2^(-days_elapsed / note_half_life)
+```
+
+**Why `log2` instead of `ln`?** With `log2`, a single note contributes exactly `note_bonus * 1.0` (since `log2(2) = 1`), making the `note_bonus` weight directly interpretable as "points per note at count=1." With `ln`, one note contributes `note_bonus * 0.69`, which is unintuitive and means `note_bonus=1` doesn't actually mean "1 point per note." The diminishing-returns curve shape is identical — only the scale factor differs.
+
+Per-signal contributions (each signal is either per-MR or per-note-group):
+
+| Signal Type | Base Weight | Half-Life | Rationale |
+|-------------|-------------|-----------|-----------|
+| **Author** (authored MR touching path) | 25 | 180 days | Deep generative engagement; ~50% retention at 6 months |
+| **Reviewer Participated** (left DiffNote on MR/path) | 10 | 90 days | Active review engagement; ~50% at 3 months |
+| **Reviewer Assigned-Only** (in `mr_reviewers`, no DiffNote on path) | 3 | 45 days | Passive assignment; minimal cognitive engagement, fades fast |
+| **Note** (inline DiffNotes on path, grouped per MR) | 1 | 45 days | `log2(1+count)` per MR; diminishing returns prevent comment storms |
+
+**Why split reviewers?** The `mr_reviewers` table records assignment, not engagement. A reviewer who left 5 inline comments on a file has demonstrably more expertise than one who was merely assigned and clicked "approve." The participated signal inherits the old reviewer weight (10) and decay (90 days); the assigned-only signal gets reduced weight (3) and faster decay (45 days) — enough to register but not enough to inflate past actual contributors.
+
+**Why require substantive notes?** Participation is qualified by a minimum note body length (`reviewer_min_note_chars`, default 20). Without this, a single "LGTM" or "+1" comment would promote a reviewer from the 3-point assigned-only tier to the 10-point participated tier — a 3.3x weight increase for zero substantive engagement. The threshold is configurable to accommodate teams with different review conventions.
+
+**Why cap notes per MR?** Without diminishing returns, a back-and-forth thread of 30 comments on a single MR would score 30 note points — disproportionate to the expertise gained. `log2(1 + 30) ≈ 4.95` vs `log2(1 + 1) = 1.0` preserves the signal that more comments = more engagement while preventing outlier MRs from dominating. The 30-note reviewer gets ~5x the credit of a 1-note reviewer, not 30x.
+
+Author/reviewer signals are deduplicated per MR (one signal per distinct MR). Note signals are grouped per (user, MR) and use `log2(1 + count)` scaling.
+
+**Why include closed MRs?** Closed-without-merge MRs represent real review effort and code familiarity even though the code was abandoned. All signals from closed MRs are multiplied by `closed_mr_multiplier` (default 0.5) to reflect this reduced but non-zero contribution. This applies uniformly to author, reviewer, and note signals on closed MRs.
+
+## Files to Modify
+
+1. **`src/core/config.rs`** — Add half-life fields + assigned-only reviewer config to `ScoringConfig`; add config validation
+2. **`src/cli/commands/who.rs`** — Core changes:
+   - Add `half_life_decay()` pure function
+   - Add `normalize_query_path()` for input canonicalization before path resolution
+   - Restructure `query_expert()`: SQL returns hybrid-aggregated signal rows with timestamps and state multiplier (MR-level for author/reviewer, note-count-per-MR for notes), Rust applies decay + `log2(1+count)` + final ranking
+   - Match both `new_path` and `old_path` in all signal queries (rename awareness)
+   - Extend rename awareness to `build_path_query()` probes and `suffix_probe()` (not just scoring)
+   - Split reviewer signal into participated vs assigned-only
+   - Use state-aware timestamps (`merged_at` for merged MRs, `updated_at` for open MRs)
+   - Change default `--since` from `"6m"` to `"24m"` (2 years captures all meaningful decayed signals)
+   - Add `--as-of` flag for reproducible scoring at a fixed timestamp
+   - Add `--explain-score` flag for per-user score component breakdown
+   - Add `--include-bots` flag to disable bot/service-account filtering
+   - Sort on raw f64 score, round only for display
+   - Update tests
+3. **`src/core/db.rs`** — Add migration for indexes supporting the new query shapes (dual-path matching, reviewer participation CTE, path resolution probes)
+
+## Implementation Details
+
+### 1. ScoringConfig (config.rs)
+
+Add half-life fields and the new assigned-only reviewer signal. All new fields use `#[serde(default)]` for backward compatibility:
+
+```rust
+pub struct ScoringConfig {
+    pub author_weight: i64,                    // default: 25
+    pub reviewer_weight: i64,                  // default: 10  (participated — left DiffNotes)
+    pub reviewer_assignment_weight: i64,       // default: 3   (assigned-only — no DiffNotes on path)
+    pub note_bonus: i64,                       // default: 1
+    pub author_half_life_days: u32,            // default: 180
+    pub reviewer_half_life_days: u32,          // default: 90  (participated)
+    pub reviewer_assignment_half_life_days: u32, // default: 45 (assigned-only)
+    pub note_half_life_days: u32,              // default: 45
+    pub closed_mr_multiplier: f64,             // default: 0.5  (applied to closed-without-merge MRs)
+    pub reviewer_min_note_chars: u32,          // default: 20   (minimum note body length to count as participation)
+    pub excluded_usernames: Vec<String>,       // default: []    (exact-match usernames to exclude, e.g. ["renovate-bot", "gitlab-ci"])
+}
+```
+
+**Config validation**: Add a `validate_scoring()` call in `Config::load_from_path()` after deserialization:
+- All `*_half_life_days` must be > 0 and <= 3650 (prevents division by zero in decay function; rejects absurd 10+ year half-lives that would effectively disable decay)
+- All `*_weight` / `*_bonus` must be >= 0 (negative weights produce nonsensical scores)
+- `closed_mr_multiplier` must be finite (not NaN/Inf) and in `(0.0, 1.0]` (0 would discard closed MRs entirely; >1 would over-weight them; NaN/Inf would propagate through all scores)
+- `reviewer_min_note_chars` must be >= 0 and <= 4096 (0 disables the filter; 4096 is a sane upper bound — no real review comment needs to be longer to qualify; typical useful values: 10-50)
+- `excluded_usernames` entries must be non-empty strings (no blank entries)
+- Return `LoreError::ConfigInvalid` with a clear message on failure
+
+### 2. Decay Function (who.rs)
+
+```rust
+fn half_life_decay(elapsed_ms: i64, half_life_days: u32) -> f64 {
+    let days = (elapsed_ms as f64 / 86_400_000.0).max(0.0);
+    let hl = f64::from(half_life_days);
+    if hl <= 0.0 { return 0.0; }
+    2.0_f64.powf(-days / hl)
+}
+```
+
+### 3. SQL Restructure (who.rs)
+
+The SQL uses **CTE-based dual-path matching**, a **centralized `mr_activity` CTE**, and **hybrid aggregation**. Rather than repeating `OR old_path` in every signal subquery, two foundational CTEs (`matched_notes`, `matched_file_changes`) centralize path matching. A `mr_activity` CTE centralizes the state-aware timestamp and state multiplier in one place, eliminating repetition of the CASE expression across signals 3, 4a, 4b. A fourth CTE (`reviewer_participation`) precomputes which reviewers actually left DiffNotes, avoiding correlated `EXISTS`/`NOT EXISTS` subqueries.
+
+MR-level signals return one row per (username, signal, mr_id) with a timestamp and state multiplier; note signals return one row per (username, mr_id) with `note_count` and `max_ts`. This keeps row counts bounded (dozens to low hundreds per path) while giving Rust the data it needs for decay and `log2(1+count)`.
+
+```sql
+WITH matched_notes_raw AS (
+  -- Branch 1: match on new_path (uses idx_notes_new_path or equivalent)
+  SELECT n.id, n.discussion_id, n.author_username, n.created_at, n.project_id
+  FROM notes n
+  WHERE n.note_type = 'DiffNote'
+    AND n.is_system = 0
+    AND n.author_username IS NOT NULL
+    AND n.created_at >= ?2
+    AND n.created_at < ?4
+    AND (?3 IS NULL OR n.project_id = ?3)
+    AND n.position_new_path {path_op}
+  UNION ALL
+  -- Branch 2: match on old_path (uses idx_notes_old_path_author)
+  SELECT n.id, n.discussion_id, n.author_username, n.created_at, n.project_id
+  FROM notes n
+  WHERE n.note_type = 'DiffNote'
+    AND n.is_system = 0
+    AND n.author_username IS NOT NULL
+    AND n.created_at >= ?2
+    AND n.created_at < ?4
+    AND (?3 IS NULL OR n.project_id = ?3)
+    AND n.position_old_path {path_op}
+),
+matched_notes AS (
+  -- Dedup: prevent double-counting when old_path = new_path (no rename)
+  SELECT DISTINCT id, discussion_id, author_username, created_at, project_id
+  FROM matched_notes_raw
+),
+matched_file_changes_raw AS (
+  -- Branch 1: match on new_path (uses idx_mfc_new_path_project_mr)
+  SELECT fc.merge_request_id, fc.project_id
+  FROM mr_file_changes fc
+  WHERE (?3 IS NULL OR fc.project_id = ?3)
+    AND fc.new_path {path_op}
+  UNION ALL
+  -- Branch 2: match on old_path (uses idx_mfc_old_path_project_mr)
+  SELECT fc.merge_request_id, fc.project_id
+  FROM mr_file_changes fc
+  WHERE (?3 IS NULL OR fc.project_id = ?3)
+    AND fc.old_path {path_op}
+),
+matched_file_changes AS (
+  -- Dedup: prevent double-counting when old_path = new_path (no rename)
+  SELECT DISTINCT merge_request_id, project_id
+  FROM matched_file_changes_raw
+),
+mr_activity AS (
+  -- Centralized state-aware timestamps and state multiplier.
+  -- Defined once, referenced by all file-change-based signals (3, 4a, 4b).
+  -- Scoped to MRs matched by file changes to avoid materializing the full MR table.
+  SELECT DISTINCT
+    m.id AS mr_id,
+    m.author_username,
+    m.state,
+    CASE
+      WHEN m.state = 'merged' THEN COALESCE(m.merged_at, m.created_at)
+      WHEN m.state = 'closed' THEN COALESCE(m.closed_at, m.created_at)
+      ELSE COALESCE(m.updated_at, m.created_at)
+    END AS activity_ts,
+    CASE WHEN m.state = 'closed' THEN ?5 ELSE 1.0 END AS state_mult
+  FROM merge_requests m
+  JOIN matched_file_changes mfc ON mfc.merge_request_id = m.id
+  WHERE m.state IN ('opened','merged','closed')
+),
+reviewer_participation AS (
+  -- Precompute which (mr_id, username) pairs have substantive DiffNote participation.
+  -- Materialized once, then joined against mr_reviewers to classify.
+  -- The LENGTH filter excludes trivial notes ("LGTM", "+1", emoji-only) from qualifying
+  -- a reviewer as "participated." Without this, a single "LGTM" would promote an assigned
+  -- reviewer from 3-point to 10-point weight, defeating the purpose of the split.
+  -- Note: mn.id refers back to notes.id, so we join notes to access the body column
+  -- (not carried in matched_notes to avoid bloating that CTE with body text).
+  -- ?6 is the configured reviewer_min_note_chars value (default 20).
+  SELECT DISTINCT d.merge_request_id AS mr_id, mn.author_username AS username
+  FROM matched_notes mn
+  JOIN discussions d ON mn.discussion_id = d.id
+  JOIN notes n_body ON mn.id = n_body.id
+  WHERE d.merge_request_id IS NOT NULL
+    AND LENGTH(TRIM(COALESCE(n_body.body, ''))) >= ?6
+),
+raw AS (
+  -- Signal 1: DiffNote reviewer (individual notes for note_cnt)
+  -- Computes state_mult inline (not via mr_activity) because this joins through discussions, not file changes.
+  SELECT mn.author_username AS username, 'diffnote_reviewer' AS signal,
+         m.id AS mr_id, mn.id AS note_id, mn.created_at AS seen_at,
+         CASE WHEN m.state = 'closed' THEN ?5 ELSE 1.0 END AS state_mult
+  FROM matched_notes mn
+  JOIN discussions d ON mn.discussion_id = d.id
+  JOIN merge_requests m ON d.merge_request_id = m.id
+  WHERE (m.author_username IS NULL OR mn.author_username != m.author_username)
+    AND m.state IN ('opened','merged','closed')
+
+  UNION ALL
+
+  -- Signal 2: DiffNote MR author
+  -- Computes state_mult inline (same reason as signal 1).
+  SELECT m.author_username AS username, 'diffnote_author' AS signal,
+         m.id AS mr_id, NULL AS note_id, MAX(mn.created_at) AS seen_at,
+         CASE WHEN m.state = 'closed' THEN ?5 ELSE 1.0 END AS state_mult
+  FROM merge_requests m
+  JOIN discussions d ON d.merge_request_id = m.id
+  JOIN matched_notes mn ON mn.discussion_id = d.id
+  WHERE m.author_username IS NOT NULL
+    AND m.state IN ('opened','merged','closed')
+  GROUP BY m.author_username, m.id
+
+  UNION ALL
+
+  -- Signal 3: MR author via file changes (uses mr_activity CTE for timestamp + state_mult)
+  SELECT a.author_username AS username, 'file_author' AS signal,
+         a.mr_id, NULL AS note_id,
+         a.activity_ts AS seen_at, a.state_mult
+  FROM mr_activity a
+  WHERE a.author_username IS NOT NULL
+    AND a.activity_ts >= ?2
+    AND a.activity_ts < ?4
+
+  UNION ALL
+
+  -- Signal 4a: Reviewer participated (in mr_reviewers AND left DiffNotes on path)
+  SELECT r.username AS username, 'file_reviewer_participated' AS signal,
+         a.mr_id, NULL AS note_id,
+         a.activity_ts AS seen_at, a.state_mult
+  FROM mr_activity a
+  JOIN mr_reviewers r ON r.merge_request_id = a.mr_id
+  JOIN reviewer_participation rp ON rp.mr_id = a.mr_id AND rp.username = r.username
+  WHERE r.username IS NOT NULL
+    AND (a.author_username IS NULL OR r.username != a.author_username)
+    AND a.activity_ts >= ?2
+    AND a.activity_ts < ?4
+
+  UNION ALL
+
+  -- Signal 4b: Reviewer assigned-only (in mr_reviewers, NO DiffNotes on path)
+  SELECT r.username AS username, 'file_reviewer_assigned' AS signal,
+         a.mr_id, NULL AS note_id,
+         a.activity_ts AS seen_at, a.state_mult
+  FROM mr_activity a
+  JOIN mr_reviewers r ON r.merge_request_id = a.mr_id
+  LEFT JOIN reviewer_participation rp ON rp.mr_id = a.mr_id AND rp.username = r.username
+  WHERE rp.username IS NULL  -- NOT in participation set
+    AND r.username IS NOT NULL
+    AND (a.author_username IS NULL OR r.username != a.author_username)
+    AND a.activity_ts >= ?2
+    AND a.activity_ts < ?4
+),
+aggregated AS (
+  -- MR-level signals: 1 row per (username, signal_class, mr_id) with MAX(ts)
+  SELECT username, signal, mr_id, 1 AS qty, MAX(seen_at) AS ts, MAX(state_mult) AS state_mult
+  FROM raw WHERE signal != 'diffnote_reviewer'
+  GROUP BY username, signal, mr_id
+  UNION ALL
+  -- Note signals: 1 row per (username, mr_id) with note_count and max_ts
+  SELECT username, 'note_group' AS signal, mr_id, COUNT(*) AS qty, MAX(seen_at) AS ts, MAX(state_mult) AS state_mult
+  FROM raw WHERE signal = 'diffnote_reviewer' AND note_id IS NOT NULL
+  GROUP BY username, mr_id
+)
+SELECT username, signal, mr_id, qty, ts, state_mult FROM aggregated WHERE username IS NOT NULL
+```
+
+Where `{path_op}` is either `= ?1` or `LIKE ?1 ESCAPE '\\'` depending on the path query type, `?2` is `since_ms`, `?3` is the optional project_id, `?4` is the `as_of_ms` exclusive upper bound (defaults to `now_ms` when `--as-of` is not specified), `?5` is the `closed_mr_multiplier` (default 0.5, bound as a parameter), and `?6` is the configured `reviewer_min_note_chars` value (default 20, bound as a parameter). The `>= ?2 AND < ?4` pattern (half-open interval) ensures that when `--as-of` is set to a past date, events at or after that date are excluded — without this, "future" events would leak in with full weight, breaking reproducibility. The exclusive upper bound avoids edge-case ambiguity when events have timestamps exactly equal to the as-of value.
+
+**Rationale for CTE-based dual-path matching**: The previous approach (repeating `OR old_path` in every signal subquery) duplicated the path matching logic 5 times. Factoring it into foundational CTEs (`matched_notes_raw` → `matched_notes`, `matched_file_changes_raw` → `matched_file_changes`) means path matching is defined once, each index branch is explicit, and adding future path resolution logic (e.g., alias chains) only requires changes in one place. The UNION ALL + dedup pattern ensures SQLite uses the optimal index for each path column independently.
+
+**Dual-path matching strategy (UNION ALL split)**: SQLite's query planner commonly struggles with `OR` across two indexed columns, falling back to a full table scan instead of using either index. Rather than starting with `OR` and hoping the planner cooperates, use `UNION ALL` + dedup as the default strategy:
+```sql
+matched_notes AS (
+  SELECT ... FROM notes n WHERE ... AND n.position_new_path {path_op}
+  UNION ALL
+  SELECT ... FROM notes n WHERE ... AND n.position_old_path {path_op}
+),
+matched_notes_dedup AS (
+  SELECT DISTINCT id, discussion_id, author_username, created_at, project_id
+  FROM matched_notes
+),
+```
+This ensures each branch can use its respective index independently. The dedup CTE prevents double-counting when `old_path = new_path` (no rename). The same pattern applies to `matched_file_changes`. The simpler `OR` variant is retained as a comment for benchmarking — if a future SQLite version handles `OR` well, the split can be collapsed.
+
+**Rationale for precomputed participation set**: The previous approach used correlated `EXISTS`/`NOT EXISTS` subqueries to classify reviewers. The `reviewer_participation` CTE materializes the set of `(mr_id, username)` pairs from matched DiffNotes once, then signal 4a JOINs against it (participated) and signal 4b LEFT JOINs with `IS NULL` (assigned-only). This avoids per-reviewer-row correlated scans, is easier to reason about, and produces the same exhaustive split — every `mr_reviewers` row falls into exactly one bucket.
+
+**Rationale for hybrid over fully-raw**: Pre-aggregating note counts in SQL prevents row explosion from heavy DiffNote volume on frequently-discussed paths. MR-level signals are already 1-per-MR by nature (deduped via GROUP BY in each subquery). This keeps memory and latency predictable regardless of review activity density.
+
+**Path rename awareness**: Both `matched_notes` and `matched_file_changes` use UNION ALL + dedup to match against both old and new path columns independently, ensuring each branch uses its respective index:
+
+- Notes: branch 1 matches `position_new_path`, branch 2 matches `position_old_path`, deduped by `notes.id`
+- File changes: branch 1 matches `new_path`, branch 2 matches `old_path`, deduped by `(merge_request_id, project_id)`
+
+Both columns already exist in the schema (`notes.position_old_path` from migration 002, `mr_file_changes.old_path` from migration 016). The UNION ALL approach ensures expertise is credited even when a file was renamed after the work was done. For prefix queries (`--path src/foo/`), the `LIKE` operator applies to both columns identically.
+
+**Signal 4 splits into two**: The current signal 4 (`file_reviewer`) joins `mr_reviewers` but doesn't distinguish participation. In the new plan:
+
+- **Signal 4a** (`file_reviewer_participated`): User is in `mr_reviewers` AND appears in the `reviewer_participation` CTE (left DiffNotes on the path for that MR). Gets `reviewer_weight` (10) and `reviewer_half_life_days` (90).
+- **Signal 4b** (`file_reviewer_assigned`): User is in `mr_reviewers` but NOT in the `reviewer_participation` CTE. Gets `reviewer_assignment_weight` (3) and `reviewer_assignment_half_life_days` (45).
+
+**Rationale for `mr_activity` CTE**: The previous approach repeated the state-aware CASE expression and `m.state` column in signals 3, 4a, and 4b, with the `closed_mr_multiplier` applied later in Rust by string-matching on `mr_state`. This split was brittle — the CASE expression could drift between signal branches, and per-row state-string handling in Rust was unnecessary indirection. The `mr_activity` CTE defines the timestamp and multiplier once, scoped to matched MRs only (via JOIN with `matched_file_changes`) to avoid materializing the full MR table. Signals 3, 4a, 4b now reference `a.activity_ts` and `a.state_mult` directly. Signals 1 and 2 (DiffNote-based) still compute `state_mult` inline because they join through `discussions`, not `matched_file_changes`, and adding them to `mr_activity` would require a second join path that doesn't simplify anything.
+
+**Rationale for parameterized `reviewer_min_note_chars` and `closed_mr_multiplier`**: Previous iterations inlined `reviewer_min_note_chars` as a literal in the SQL string and kept `closed_mr_multiplier` in Rust only. Binding both as SQL parameters (`?5` for `closed_mr_multiplier`, `?6` for `reviewer_min_note_chars`) eliminates statement-cache churn (the SQL text is identical regardless of config values), avoids SQL-text variability that complicates EXPLAIN QUERY PLAN analysis, and centralizes the multiplier application in SQL for file-change signals. The DiffNote signals (1, 2) still compute `state_mult` inline because they don't go through `mr_activity`.
+
+### 3a. Path Canonicalization and Resolution Probes (who.rs)
+
+**Path canonicalization**: Before any path resolution or scoring, normalize the user's input path via `normalize_query_path()`:
+- Strip leading `./` (e.g., `./src/foo.rs` → `src/foo.rs`)
+- Collapse repeated `/` (e.g., `src//foo.rs` → `src/foo.rs`)
+- Trim leading/trailing whitespace
+- Preserve trailing `/` only when present — it signals explicit prefix intent
+
+This is applied once at the top of `run_who()` before `build_path_query()`. The robot JSON `resolved_input` includes both `path_input_original` (raw user input) and `path_input_normalized` (after canonicalization) for debugging transparency. The normalization is purely syntactic — no filesystem lookups, no canonicalization against the database.
+
+**Path resolution probes**: Rename awareness must extend beyond scoring queries to the path resolution layer. Currently `build_path_query()` (line 457) and `suffix_probe()` (line 584) only check `position_new_path` and `new_path`. If a user queries an old path name, these probes return "not found" and the scoring query never runs.
+
+Rename awareness must extend beyond scoring queries to the path resolution layer. Currently `build_path_query()` (line 457) and `suffix_probe()` (line 584) only check `position_new_path` and `new_path`. If a user queries an old path name, these probes return "not found" and the scoring query never runs.
+
+**Changes to `build_path_query()`**:
+
+- **Probe 1 (exact_exists)**: Add `OR position_old_path = ?1` to the notes query and `OR old_path = ?1` to the `mr_file_changes` query. This detects files that existed under the queried name even if they've since been renamed.
+- **Probe 2 (prefix_exists)**: Add `OR position_old_path LIKE ?1 ESCAPE '\\'` and `OR old_path LIKE ?1 ESCAPE '\\'` to the respective queries.
+
+**Changes to `suffix_probe()`**:
+
+The UNION query inside `suffix_probe()` currently only selects `position_new_path` from notes and `new_path` from file changes. Add two additional UNION branches:
+
+```sql
+UNION
+SELECT position_old_path AS full_path FROM notes
+WHERE note_type = 'DiffNote' AND is_system = 0
+  AND position_old_path IS NOT NULL
+  AND (position_old_path LIKE ?1 ESCAPE '\\' OR position_old_path = ?2)
+  AND (?3 IS NULL OR project_id = ?3)
+UNION
+SELECT old_path AS full_path FROM mr_file_changes
+WHERE old_path IS NOT NULL
+  AND (old_path LIKE ?1 ESCAPE '\\' OR old_path = ?2)
+  AND (?3 IS NULL OR project_id = ?3)
+```
+
+This ensures that querying by an old filename (e.g., `login.rs` after it was renamed to `auth.rs`) still resolves to a usable path for scoring. The UNION deduplicates so the same path appearing in both old and new columns doesn't cause false ambiguity.
+
+**State-aware timestamps for file-change signals (signals 3, 4a, 4b)**: Centralized in the `mr_activity` CTE (see section 3). The CASE expression uses `merged_at` for merged MRs, `closed_at` for closed MRs, and `updated_at` for open MRs, with `created_at` as fallback when the preferred timestamp is NULL.
+
+**Rationale**: `updated_at` is noisy for merged MRs — it changes on label edits, title changes, rebases, and metadata touches, creating false recency. `merged_at` is the best indicator of when code expertise was formed (the moment the code entered the branch). But for **open MRs**, `updated_at` is actually the right signal because it reflects ongoing active work. `closed_at` anchors closed-without-merge MRs to their closure time (these represent review effort even if the code was abandoned). Each state gets the timestamp that best represents when expertise was last exercised.
+
+### 4. Rust-Side Aggregation (who.rs)
+
+For each username, accumulate into a struct with:
+- **Author MRs**: `HashMap<i64, (i64, f64)>` (mr_id -> (max timestamp, state_mult)) from `diffnote_author` + `file_author` signals
+- **Reviewer Participated MRs**: `HashMap<i64, (i64, f64)>` from `diffnote_reviewer` + `file_reviewer_participated` signals
+- **Reviewer Assigned-Only MRs**: `HashMap<i64, (i64, f64)>` from `file_reviewer_assigned` signals (excluding any MR already in participated set)
+- **Notes per MR**: `HashMap<i64, (u32, i64, f64)>` (mr_id -> (count, max_ts, state_mult)) from `note_group` rows in the aggregated query (already grouped per user+MR with note_count in `qty`). Used for `log2(1 + count)` diminishing returns.
+- **Last seen**: max of all timestamps
+- **Components** (when `--explain-score`): Track per-component f64 subtotals for `author`, `reviewer_participated`, `reviewer_assigned`, `notes`
+
+The `state_mult` field from each SQL row (already computed in SQL as 1.0 for merged/open or `closed_mr_multiplier` for closed) is stored alongside the timestamp — no string-matching on MR state needed in Rust.
+
+Compute score as `f64` with **deterministic contribution ordering**: within each signal type, sort contributions by `(mr_id ASC)` before summing. This eliminates platform-dependent HashMap iteration order as a source of f64 rounding variance near ties, ensuring CI reproducibility without the complexity of compensated summation (Neumaier/Kahan). Each MR-level contribution is multiplied by its `state_mult` (already computed in SQL):
+```
+raw_score =
+    sum(author_weight * state_mult * decay(now - ts, author_hl) for (mr, ts, state_mult) in author_mrs)
+  + sum(reviewer_weight * state_mult * decay(now - ts, reviewer_hl) for (mr, ts, state_mult) in reviewer_participated)
+  + sum(reviewer_assignment_weight * state_mult * decay(now - ts, reviewer_assignment_hl) for (mr, ts, state_mult) in reviewer_assigned)
+  + sum(note_bonus * state_mult * log2(1 + count) * decay(now - ts, note_hl) for (mr, count, ts, state_mult) in notes_per_mr)
+```
+
+**Why include closed MRs?** A closed-without-merge MR still represents review effort and code familiarity — the reviewer read the diff, left comments, and engaged with the code even though it was ultimately abandoned. Excluding closed MRs entirely (the previous plan's approach) discarded this signal. The `closed_mr_multiplier` (default 0.5) halves the contribution, reflecting that the code never landed but the reviewer's cognitive engagement was real. This also eliminates the dead-code inconsistency where the state-aware CASE expression handled `closed` but the WHERE clause excluded it.
+
+**Sort on raw `f64` score** — `(raw_score DESC, last_seen DESC, username ASC)`. This prevents false ties from premature rounding. Only round to `i64` for the `Expert.score` display field after sorting and truncation. The robot JSON `score` field stays integer for backward compatibility. When `--explain-score` is active, also include `score_raw` (the unrounded f64) alongside `score` so the component totals can be verified without rounding noise.
+
+Compute counts from the accumulated data:
+- `review_mr_count = reviewer_participated.len() + reviewer_assigned.len()`
+- `review_note_count = notes_per_mr.values().map(|(count, _)| count).sum()`
+- `author_mr_count = author_mrs.len()`
+
+**Bot/service-account filtering**: After accumulating all user scores and before sorting, filter out any username that appears in `config.scoring.excluded_usernames` (exact match, case-insensitive). This is applied in Rust post-query (not SQL) to keep the SQL clean and avoid parameter explosion. When `--include-bots` is active, the filter is skipped entirely. The robot JSON `resolved_input` includes `excluded_usernames_applied: true|false` to indicate whether filtering was active.
+
+Truncate to limit after sorting.
+
+### 5. Default --since Change
+
+Expert mode: `"6m"` -> `"24m"` (line 289 in who.rs).
+At 2 years, author decay = 6%, reviewer decay = 0.4%, note decay = 0.006% — negligible, good cutoff.
+
+**Diagnostic escape hatch**: Add `--all-history` flag (conflicts with `--since`) that sets `since_ms = 0`, capturing all data regardless of age. Useful for debugging scoring anomalies and validating the decay model against known experts. The `since_mode` field in robot JSON reports `"all"` when this flag is active.
+
+### 5a. Reproducible Scoring via `--as-of`
+
+Add `--as-of <RFC3339|YYYY-MM-DD>` flag that overrides the `now_ms` reference point used for decay calculations. When set:
+- All event selection is bounded by `[since_ms, as_of_ms)` — exclusive upper bound; events at or after `as_of_ms` are excluded from SQL results entirely (not just decayed). The SQL uses `< ?4` (strict less-than), not `<= ?4`.
+- `YYYY-MM-DD` input (without time component) is interpreted as end-of-day UTC: `T23:59:59.999Z`. This matches user intuition that `--as-of 2025-06-01` means "as of the end of June 1st" rather than "as of midnight at the start of June 1st" which would exclude the entire day's activity.
+- All decay computations use `as_of_ms` instead of `SystemTime::now()`
+- The `--since` window is calculated relative to `as_of_ms` (not wall clock)
+- Robot JSON `resolved_input` includes `as_of_ms`, `as_of_iso`, `window_start_iso`, `window_end_iso`, and `window_end_exclusive: true` fields — making the exact query window unambiguous in output
+
+**Rationale**: Decayed scoring is time-sensitive by nature. Without a fixed reference point, the same query run minutes apart produces different rankings, making debugging and test reproducibility difficult. `--as-of` pins the clock so that results are deterministic for a given dataset. The upper-bound filter in SQL is critical — without it, events after the as-of date would enter with full weight (since `elapsed.max(0.0)` clamps negative elapsed time to zero), breaking the reproducibility guarantee.
+
+Implementation: Parse the flag in `run_who()`, compute `as_of_ms: i64`, and thread it through to `query_expert()` where it replaces `now_ms()` and is bound as `?4` in all SQL queries. When the flag is absent, `?4` defaults to `now_ms()` (wall clock), which makes the upper bound transparent — all events are within the window by definition. The flag is compatible with all modes but primarily useful in expert mode.
+
+### 5b. Score Explainability via `--explain-score`
+
+Add `--explain-score` flag that augments each expert result with a per-user component breakdown:
+
+```json
+{
+  "username": "jsmith",
+  "score": 42,
+  "score_raw": 42.0,
+  "components": {
+    "author": 28.5,
+    "reviewer_participated": 8.2,
+    "reviewer_assigned": 1.8,
+    "notes": 3.5
+  }
+}
+```
+
+**Scope for this iteration**: Component breakdown only (4 floats per user). No top-evidence MRs, no decay curves, no per-MR drill-down. Those are v2 features if scoring disputes arise frequently.
+
+**Flag conflicts**: `--explain-score` is mutually exclusive with `--detail`. Both augment per-user output in different ways; combining them would produce confusing overlapping output. Clap `conflicts_with` enforces this at parse time.
+
+**Human output**: When `--explain-score` is active in human mode, append a parenthetical after each score: `42 (author:28.5 review:10.0 notes:3.5)`.
+
+**Robot output**: Add `score_raw` (unrounded f64) and `components` object to each expert entry. Only present when `--explain-score` is active (no payload bloat by default). The `resolved_input` section also includes `scoring_model_version: 2` to distinguish from the v1 flat-weight model, enabling robot clients to adapt parsing.
+
+**Rationale**: Multi-signal decayed ranking will be disputed without decomposition. Showing which signal drives a user's score makes results actionable and builds trust in the model. Keeping scope minimal avoids the output format complexity that originally motivated deferral.
+
+### 6. Index Migration (db.rs)
+
+Add a new migration to support the restructured query patterns. The dual-path matching CTEs and `reviewer_participation` CTE introduce query shapes that need index coverage:
+
+```sql
+-- Support dual-path matching on DiffNotes (old_path leg of the OR in matched_notes CTE)
+CREATE INDEX IF NOT EXISTS idx_notes_old_path_author
+  ON notes(position_old_path, author_username, created_at)
+  WHERE note_type = 'DiffNote' AND is_system = 0 AND position_old_path IS NOT NULL;
+
+-- Support dual-path matching on file changes (old_path leg of the OR in matched_file_changes CTE)
+CREATE INDEX IF NOT EXISTS idx_mfc_old_path_project_mr
+  ON mr_file_changes(old_path, project_id, merge_request_id)
+  WHERE old_path IS NOT NULL;
+
+-- Support new_path matching on file changes (ensure index parity with old_path)
+-- Existing indexes may not have optimal column order for the CTE pattern.
+CREATE INDEX IF NOT EXISTS idx_mfc_new_path_project_mr
+  ON mr_file_changes(new_path, project_id, merge_request_id);
+
+-- Support reviewer_participation CTE: joining matched_notes -> discussions -> mr_reviewers
+-- notes.discussion_id (NOT noteable_id, which doesn't exist in the schema) is the FK to discussions
+CREATE INDEX IF NOT EXISTS idx_notes_diffnote_discussion_author
+  ON notes(discussion_id, author_username, created_at)
+  WHERE note_type = 'DiffNote' AND is_system = 0;
+
+-- Support path resolution probes on old_path (build_path_query() and suffix_probe())
+-- The existing idx_notes_diffnote_path_created covers new_path probes, but old_path probes
+-- need their own index since probes don't constrain author_username.
+CREATE INDEX IF NOT EXISTS idx_notes_old_path_project_created
+  ON notes(position_old_path, project_id, created_at)
+  WHERE note_type = 'DiffNote' AND is_system = 0 AND position_old_path IS NOT NULL;
+```
+
+**Rationale**: The existing indexes cover `position_new_path` and `new_path` but not their `old_path` counterparts. Without these, the `OR old_path` clauses would force table scans on renamed files. The `reviewer_participation` CTE joins `matched_notes` -> `discussions` -> `merge_requests`, so an index on `(discussion_id, author_username)` speeds up the CTE materialization. The `idx_notes_old_path_project_created` index supports path resolution probes (`build_path_query()` and `suffix_probe()`) which run existence/path-only checks without constraining `author_username` — the scoring-oriented `idx_notes_old_path_author` has `author_username` as the second column, which is suboptimal for these probes.
+
+**Schema note**: The `notes` table uses `discussion_id` as its FK to `discussions`, which in turn has `merge_request_id`. There is no `noteable_id` column on `notes`. The previous plan revision incorrectly referenced `noteable_id` — this is corrected.
+
+**Removed**: The `idx_mr_state_timestamps` composite index on `merge_requests(state, merged_at, closed_at, updated_at, created_at)` was removed. MR lookups in the scoring query are always id-driven (joining from `matched_file_changes` or `discussions`), so the state-aware CASE expression operates on rows already fetched by primary key. A low-selectivity composite index on 5 columns would consume space without improving any query path.
+
+Partial indexes (with `WHERE` clauses) keep the index size minimal — only DiffNote rows and non-null old_path rows are indexed.
+
+### 7. Test Helpers
+
+Add timestamp-aware variants:
+- `insert_mr_at(conn, id, project_id, iid, author, state, updated_at_ms)`
+- `insert_diffnote_at(conn, id, discussion_id, project_id, author, file_path, body, created_at_ms)`
+
+### 8. New Tests (TDD)
+
+#### Example-based tests
+
+**`test_half_life_decay_math`**: Verify the pure function:
+- elapsed=0 -> 1.0
+- elapsed=half_life -> 0.5
+- elapsed=2*half_life -> 0.25
+- half_life_days=0 -> 0.0 (guard against div-by-zero)
+
+**`test_expert_scores_decay_with_time`**: Two authors, one recent (10 days), one old (360 days). Recent author should score ~24, old author ~6.
+
+**`test_expert_reviewer_decays_faster_than_author`**: Same MR, same age (90 days). Author retains ~18 points, reviewer retains ~5 points. Author dominates clearly.
+
+**`test_reviewer_participated_vs_assigned_only`**: Two reviewers on the same MR at the same age. One left DiffNotes (participated), one didn't (assigned-only). Participated reviewer should score ~10 * decay, assigned-only should score ~3 * decay. Verifies the split works end-to-end.
+
+**`test_note_diminishing_returns_per_mr`**: One reviewer with 1 note on MR-A and another with 20 notes on MR-B, both at same age. The 20-note reviewer should score `log2(21)/log2(2) ≈ 4.4x` the 1-note reviewer, NOT 20x. Validates the `log2(1+count)` cap.
+
+**`test_config_validation_rejects_zero_half_life`**: `ScoringConfig` with `author_half_life_days = 0` should return `ConfigInvalid` error.
+
+**`test_file_change_timestamp_uses_merged_at`**: An MR with `merged_at` set and `state = 'merged'` should use `merged_at` timestamp, not `updated_at`. Verify by setting `merged_at` to old date and `updated_at` to recent date — score should reflect the old date.
+
+**`test_open_mr_uses_updated_at`**: An MR with `state = 'opened'` should use `updated_at` (not `created_at`). Verify that an open MR with recent `updated_at` scores higher than one with the same `created_at` but older `updated_at`.
+
+**`test_old_path_match_credits_expertise`**: Insert a DiffNote with `position_old_path = "src/old.rs"` and `position_new_path = "src/new.rs"`. Query `--path src/old.rs` — the author should appear. Query `--path src/new.rs` — same author should also appear. Validates dual-path matching.
+
+**`test_explain_score_components_sum_to_total`**: With `--explain-score`, verify that `components.author + components.reviewer_participated + components.reviewer_assigned + components.notes` equals the reported `score_raw` (within f64 rounding tolerance). Note: the closed_mr_multiplier is already folded into the per-component subtotals, not tracked as a separate component.
+
+**`test_as_of_produces_deterministic_results`**: Insert data at known timestamps. Run `query_expert` twice with the same `--as-of` value — results must be identical. Then run with a later `--as-of` — scores should be lower (more decay).
+
+**`test_old_path_probe_exact_and_prefix`**: Insert a DiffNote with `position_old_path = "src/old/foo.rs"` and `position_new_path = "src/new/foo.rs"`. Call `build_path_query(conn, "src/old/foo.rs")` — should resolve as exact file (not "not found"). Call `build_path_query(conn, "src/old/")` — should resolve as prefix. Validates that the path resolution probes now check old_path columns.
+
+**`test_suffix_probe_uses_old_path_sources`**: Insert a file change with `old_path = "legacy/utils.rs"` and `new_path = "src/utils.rs"`. Call `build_path_query(conn, "legacy/utils.rs")` — should resolve via exact probe on old_path. Call `build_path_query(conn, "utils.rs")` — suffix probe should find both `legacy/utils.rs` and `src/utils.rs` and either resolve uniquely (if deduplicated) or report ambiguity.
+
+**`test_since_relative_to_as_of_clock`**: Insert data at timestamps T1 and T2 (T2 > T1). With `--as-of T2` and `--since 30d`, the window is `[T2 - 30d, T2]`, not `[now - 30d, now]`. Verify that data at T1 is included or excluded based on the as-of-relative window, not the wall clock window.
+
+**`test_explain_and_detail_are_mutually_exclusive`**: Parsing `--explain-score --detail` should fail with a conflict error from clap.
+
+**`test_trivial_note_does_not_count_as_participation`**: A reviewer who left only a short note ("LGTM", 4 chars) on an MR should be classified as assigned-only, not participated, when `reviewer_min_note_chars = 20`. A reviewer who left a substantive note (>= 20 chars) should be classified as participated. Validates the LENGTH threshold in the `reviewer_participation` CTE.
+
+**`test_closed_mr_multiplier`**: Two identical MRs (same author, same age, same path). One is `merged`, one is `closed`. The merged MR should contribute `author_weight * decay(...)`, the closed MR should contribute `author_weight * closed_mr_multiplier * decay(...)`. With default multiplier 0.5, the closed MR contributes half.
+
+**`test_as_of_excludes_future_events`**: Insert events at timestamps T1 (past) and T2 (future relative to as-of). With `--as-of` set between T1 and T2, only T1 events should appear in results. T2 events must be excluded entirely, not just decayed. Validates the exclusive upper-bound (`< ?4`) filtering in SQL.
+
+**`test_as_of_exclusive_upper_bound`**: Insert an event with timestamp exactly equal to the `as_of_ms` value. Verify it is excluded from results (strict less-than, not less-than-or-equal). This validates the half-open interval `[since, as_of)` semantics.
+
+**`test_excluded_usernames_filters_bots`**: Insert signals for a user named "renovate-bot" and a user named "jsmith", both with the same activity. With `excluded_usernames: ["renovate-bot"]` in config, only "jsmith" should appear in results. Validates the Rust-side post-query filtering.
+
+**`test_include_bots_flag_disables_filtering`**: Same setup as above, but with `--include-bots` active. Both "renovate-bot" and "jsmith" should appear in results.
+
+**`test_null_timestamp_fallback_to_created_at`**: Insert a merged MR with `merged_at = NULL` (edge case: old data before the column was populated). The state-aware timestamp should fall back to `created_at`. Verify the score reflects `created_at`, not 0 or a panic.
+
+**`test_path_normalization_handles_dot_and_double_slash`**: Call `normalize_query_path("./src//foo.rs")` — should return `"src/foo.rs"`. Call `normalize_query_path("  src/bar.rs  ")` — should return `"src/bar.rs"`. Call `normalize_query_path("src/foo.rs")` — should return unchanged (already normalized). Call `normalize_query_path("")` — should return `""` (empty input passes through).
+
+**`test_path_normalization_preserves_prefix_semantics`**: Call `normalize_query_path("./src/dir/")` — should return `"src/dir/"` (trailing slash preserved for prefix intent). Call `normalize_query_path("src/dir")` — should return `"src/dir"` (no trailing slash = file, not prefix).
+
+**`test_config_validation_rejects_absurd_half_life`**: `ScoringConfig` with `author_half_life_days = 5000` (>3650 cap) should return `ConfigInvalid` error. Similarly, `reviewer_min_note_chars = 5000` (>4096 cap) should fail.
+
+**`test_config_validation_rejects_nan_multiplier`**: `ScoringConfig` with `closed_mr_multiplier = f64::NAN` should return `ConfigInvalid` error. Same for `f64::INFINITY`.
+
+#### Invariant tests (regression safety for ranking systems)
+
+**`test_score_monotonicity_by_age`**: For any single signal type, an older timestamp must never produce a higher score than a newer timestamp with the same weight and half-life. Generate N random (age, half_life) pairs and assert `decay(older) <= decay(newer)` for all.
+
+**`test_row_order_independence`**: Insert the same set of signals in two different orders (e.g., reversed). Run `query_expert` on both — the resulting rankings (username order + scores) must be identical. Validates that neither SQL ordering nor HashMap iteration order affects final output.
+
+**`test_reviewer_split_is_exhaustive`**: For a reviewer assigned to an MR, they must appear in exactly one of: participated (has substantive DiffNotes meeting `reviewer_min_note_chars`) or assigned-only (no DiffNotes, or only trivial ones below the threshold). Never both, never neither. Test three cases: (1) reviewer with substantive DiffNotes -> participated only, (2) reviewer with no DiffNotes -> assigned-only only, (3) reviewer with only trivial notes ("LGTM") -> assigned-only only.
+
+**`test_deterministic_accumulation_order`**: Insert signals for a user with contributions at many different timestamps (10+ MRs with varied ages). Run `query_expert` 100 times in a loop. All 100 runs must produce the exact same `f64` score (bit-identical). Validates that the sorted contribution ordering eliminates HashMap-iteration-order nondeterminism.
+
+### 9. Existing Test Compatibility
+
+All existing tests insert data with `now_ms()`. With decay, elapsed ~0ms means decay ~1.0, so scores round to the same integers as before. No existing test assertions should break.
+
+The `test_expert_scoring_weights_are_configurable` test needs `..Default::default()` added to fill the new half-life fields, `reviewer_assignment_weight` / `reviewer_assignment_half_life_days`, `closed_mr_multiplier`, `reviewer_min_note_chars`, and `excluded_usernames` fields.
+
+## Verification
+
+1. `cargo check --all-targets` — no compiler errors
+2. `cargo clippy --all-targets -- -D warnings` — no lints
+3. `cargo fmt --check` — formatting clean
+4. `cargo test` — all existing + new tests pass (including invariant tests)
+5. `ubs src/cli/commands/who.rs src/core/config.rs src/core/db.rs` — no bug scanner findings
+6. Manual query plan verification (not automated — SQLite planner varies across versions):
+   - Run `EXPLAIN QUERY PLAN` on the expert query (both exact and prefix modes) against a real database
+   - Confirm that `matched_notes_raw` branch 1 uses the existing new_path index and branch 2 uses `idx_notes_old_path_author` (not a full table scan on either branch)
+   - Confirm that `matched_file_changes_raw` branch 1 uses `idx_mfc_new_path_project_mr` and branch 2 uses `idx_mfc_old_path_project_mr`
+   - Confirm that `reviewer_participation` CTE uses `idx_notes_diffnote_discussion_author`
+   - Confirm that `mr_activity` CTE joins `merge_requests` via primary key from `matched_file_changes`
+   - Confirm that path resolution probes (old_path leg) use `idx_notes_old_path_project_created`
+   - Document the observed plan in a comment near the SQL for future regression reference
+7. Performance baseline (manual, not CI-gated):
+   - Run `time cargo run --release -- who --path <exact-path>` on the real database for exact, prefix, and suffix modes
+   - Target SLOs: p95 exact path < 200ms, prefix < 300ms, suffix < 500ms on development hardware
+   - Record baseline timings as a comment near the SQL for regression reference
+   - If any mode exceeds 2x the baseline after future changes, investigate before merging
+   - Note: These are soft targets for developer awareness, not automated CI gates. Automated benchmarking with synthetic fixtures (100k/1M/5M notes) is a v2 investment if performance becomes a real concern.
+8. Real-world validation:
+   - `cargo run --release -- who --path MeasurementQualityDialog.tsx` — verify jdefting/zhayes old reviews are properly discounted relative to recent authors
+   - `cargo run --release -- who --path MeasurementQualityDialog.tsx --all-history` — compare full history vs 24m window to validate cutoff is reasonable
+   - `cargo run --release -- who --path MeasurementQualityDialog.tsx --explain-score` — verify component breakdown sums to total and authored signal dominates for known authors
+   - Spot-check that assigned-only reviewers (those who never left DiffNotes) rank below participated reviewers on the same MR
+   - Test a known renamed file path — verify expertise from the old name carries forward
+   - `cargo run --release -- who --path MeasurementQualityDialog.tsx --as-of 2025-06-01` — verify deterministic output across repeated runs
+   - Spot-check that reviewers who only left "LGTM"-style notes are classified as assigned-only (not participated)
+   - Verify closed MRs contribute at ~50% of equivalent merged MR scores via `--explain-score`
+   - If the project has known bot accounts (e.g., renovate-bot), add them to `excluded_usernames` config and verify they no longer appear in results. Run again with `--include-bots` to confirm they reappear.
+   - Test path normalization: `who --path ./src//foo.rs` and `who --path src/foo.rs` should produce identical results
+
+## Accepted from External Review
+
+Ideas incorporated from ChatGPT review (feedback-1 through feedback-4) that genuinely improved the plan:
+
+**From feedback-1 and feedback-2:**
+- **Path rename awareness (old_path matching)**: Real correctness gap. Both `position_old_path` and `mr_file_changes.old_path` exist in the schema. Simple `OR` clause addition with high value — expertise now survives file renames.
+- **Hybrid SQL pre-aggregation**: Revised from "fully raw rows" to pre-aggregate note counts per (user, MR) in SQL. MR-level signals were already 1-per-MR; the note rows were the actual scalability risk. Bounded row counts with predictable memory.
+- **State-aware timestamps**: Improved from our overly-simple `COALESCE(merged_at, created_at)` to a state-aware CASE expression. Open MRs genuinely need `updated_at` to reflect ongoing work; merged MRs need `merged_at` to anchor expertise formation.
+- **Index migration**: The dual-path matching and CTE patterns need index support. Added partial indexes to keep size minimal.
+- **Invariant tests**: `test_score_monotonicity_by_age`, `test_row_order_independence`, `test_reviewer_split_is_exhaustive` catch subtle ranking regressions that example-based tests miss.
+- **`--as-of` flag**: Simple clock-pinning for reproducible decay scoring. Essential for debugging and test determinism.
+- **`--explain-score` flag**: Moved from rejected to included with minimal scope (component breakdown only, no per-MR drill-down). Multi-signal scoring needs decomposition to build trust.
+
+**From feedback-3:**
+- **Fix `noteable_id` index bug (critical)**: The `notes` table uses `discussion_id` as FK to `discussions`, not `noteable_id` (which doesn't exist). The proposed `idx_notes_mr_path_author` index would fail at migration time. Fixed to use `(discussion_id, author_username, created_at)`.
+- **CTE-based dual-path matching (`matched_notes`, `matched_file_changes`)**: Rather than repeating `OR old_path` in every signal subquery, centralize path matching in foundational CTEs. Defined once, indexed once, maintained once. Cleaner and more extensible.
+- **Precomputed `reviewer_participation` CTE**: Replaced correlated `EXISTS`/`NOT EXISTS` subqueries with a materialized set of `(mr_id, username)` pairs. Same semantics, lower query cost, simpler reasoning about the reviewer split.
+- **`log2(1+count)` over `ln(1+count)` for notes**: With `log2`, one note contributes exactly 1.0 unit (since `log2(2) = 1`), making `note_bonus=1` directly interpretable. `ln` gives 0.69 per note, which is unintuitive.
+- **Path resolution probe rename awareness**: The plan added `old_path` matching to scoring queries but missed the upstream path resolution layer (`build_path_query()` probes and `suffix_probe()`). Without this, querying an old path name fails at resolution and never reaches scoring. Now both probes check old_path columns.
+- **Removed low-selectivity `idx_mr_state_timestamps`**: MR lookups in scoring are id-driven (from file_changes or discussions), so a 5-column composite on state/timestamps adds no query benefit.
+- **Added `idx_mfc_new_path_project_mr`**: Ensures index parity between old and new path columns on `mr_file_changes`.
+- **`--explain-score` conflicts with `--detail`**: Prevents confusing overlapping output from two per-user augmentation flags.
+- **`scoring_model_version` in resolved_input**: Lets robot clients distinguish v1 (flat weights) from v2 (decayed) output schemas.
+- **`score_raw` in explain mode**: Exposes the unrounded f64 so component totals can be verified without rounding noise.
+- **New tests**: `test_old_path_probe_exact_and_prefix`, `test_suffix_probe_uses_old_path_sources`, `test_since_relative_to_as_of_clock`, `test_explain_and_detail_are_mutually_exclusive`, `test_null_timestamp_fallback_to_created_at` — cover the newly-identified gaps in path resolution, clock semantics, and edge cases.
+- **EXPLAIN QUERY PLAN verification step**: Manual check that the restructured queries use the new indexes (not automated, since SQLite planner varies across versions).
+
+**From feedback-4:**
+- **`--as-of` temporal correctness (critical)**: The plan described `--as-of` but the SQL only enforced a lower bound (`>= ?2`). Events after the as-of date would leak in with full weight (because `elapsed.max(0.0)` clamps negative elapsed time to zero). Added `< ?4` upper bound to all SQL timestamp filters, making the query window `[since_ms, as_of_ms)`. Without this, `--as-of` reproducibility was fundamentally broken. (Refined to exclusive upper bound in feedback-5.)
+- **Closed-state inconsistency resolution**: The state-aware CASE expression handled `closed` state but the WHERE clause filtered to `('opened','merged')` only — dead code. Resolved by including `'closed'` in state filters and adding a `closed_mr_multiplier` (default 0.5) applied in Rust to all signals from closed-without-merge MRs. This credits real review effort on abandoned MRs while appropriately discounting it.
+- **Substantive note threshold for reviewer participation**: A single "LGTM" shouldn't promote a reviewer from 3-point (assigned-only) to 10-point (participated) weight. Added `reviewer_min_note_chars` (default 20) config field and `LENGTH(TRIM(body))` filter in the `reviewer_participation` CTE. This raises the bar for participation classification to actual substantive review comments.
+- **UNION ALL optimization for path predicates**: SQLite's planner can degrade `OR` across two indexed columns to a table scan. Originally documented as a fallback; promoted to default strategy in feedback-5 iteration. The UNION ALL + dedup approach ensures each index branch is used independently.
+- **New tests**: `test_trivial_note_does_not_count_as_participation`, `test_closed_mr_multiplier`, `test_as_of_excludes_future_events` — cover the three new features added from this review round.
+
+**From feedback-5 (ChatGPT review):**
+- **Exclusive upper bound for `--as-of`**: Changed from `[since_ms, as_of_ms]` (inclusive) to `[since_ms, as_of_ms)` (exclusive). Half-open intervals are the standard convention in temporal systems — they eliminate edge-case ambiguity when events have timestamps exactly at the boundary. Also added `YYYY-MM-DD` → end-of-day UTC parsing and window metadata in robot output.
+- **UNION ALL as default for dual-path matching**: Promoted from "fallback if planner regresses" to default strategy. SQLite `OR`-across-indexed-columns degradation is common enough that the predictable UNION ALL + dedup approach is the safer starting point. The simpler `OR` variant is retained as a comment for benchmarking.
+- **Deterministic contribution ordering**: Within each signal type, sort contributions by `mr_id` before summing. This eliminates HashMap iteration order as a source of f64 rounding variance near ties, ensuring CI reproducibility without the overhead of compensated summation (Neumaier/Kahan was rejected as overkill at this scale).
+- **Minimal bot/service-account filtering**: Added `excluded_usernames` (exact match, case-insensitive) to `ScoringConfig` and `--include-bots` CLI flag. Applied as a Rust-side post-filter (not SQL) to keep queries clean. Scope is deliberately minimal — no regex patterns, no heuristic detection. Users configure the list for their team's specific bots.
+- **Performance baseline SLOs**: Added manual performance baseline step to verification — record timings for exact/prefix/suffix modes and flag >2x regressions. Kept lightweight (no CI gating, no synthetic benchmarks) to match the project's current maturity.
+- **New tests**: `test_as_of_exclusive_upper_bound`, `test_excluded_usernames_filters_bots`, `test_include_bots_flag_disables_filtering`, `test_deterministic_accumulation_order` — cover the newly-accepted features.
+
+**From feedback-6 (ChatGPT review):**
+- **Centralized `mr_activity` CTE**: The state-aware timestamp CASE expression and `closed_mr_multiplier` were repeated across signals 3, 4a, 4b with the multiplier applied later in Rust via string-matching on `mr_state`. This was brittle — the CASE could drift between branches and the Rust-side string matching was unnecessary indirection. A single `mr_activity` CTE defines both `activity_ts` and `state_mult` once, scoped to matched MRs only (via JOIN with `matched_file_changes`). Signals 1 and 2 still compute `state_mult` inline because they join through `discussions`, not `matched_file_changes`.
+- **Parameterized `reviewer_min_note_chars` and `closed_mr_multiplier`**: Previously `reviewer_min_note_chars` was inlined as a literal in the SQL string and `closed_mr_multiplier` was applied only in Rust. Binding both as SQL parameters (`?5` for `closed_mr_multiplier`, `?6` for `reviewer_min_note_chars`) eliminates statement-cache churn, ensures identical SQL text regardless of config values, and simplifies EXPLAIN QUERY PLAN analysis.
+- **Tightened config validation**: Added upper bounds — `*_half_life_days <= 3650` (10-year safety cap), `reviewer_min_note_chars <= 4096`, and `closed_mr_multiplier` must be finite (not NaN/Inf). These prevent absurd configurations from silently producing nonsensical results.
+- **Path canonicalization via `normalize_query_path()`**: Inputs like `./src//foo.rs` or whitespace-padded paths could fail path resolution even when the file exists in the database. A simple syntactic normalization (strip `./`, collapse `//`, trim whitespace, preserve trailing `/`) runs before `build_path_query()` to reduce false negatives. No filesystem or database lookups — purely string manipulation.
+- **Probe-optimized `idx_notes_old_path_project_created` index**: The scoring-oriented `idx_notes_old_path_author` index has `author_username` as its second column, which is suboptimal for path resolution probes that don't constrain author. A dedicated probe index on `(position_old_path, project_id, created_at)` ensures `build_path_query()` and `suffix_probe()` old_path lookups are efficient.
+- **New tests**: `test_path_normalization_handles_dot_and_double_slash`, `test_path_normalization_preserves_prefix_semantics`, `test_config_validation_rejects_absurd_half_life`, `test_config_validation_rejects_nan_multiplier` — cover the path canonicalization and tightened validation logic.
+
+## Rejected Ideas (with rationale)
+
+These suggestions were considered during review but explicitly excluded from this iteration:
+
+- **Rename alias chain expansion (A->B->C traversal)** (feedback-2 #2, feedback-4 #4): Over-engineered for v1. The old_path `OR` match covers the 80% case (direct renames). Building a canonical path identity table at ingest time adds schema, ingestion logic, and graph traversal complexity for rare multi-hop renames. If real-world usage shows fragmented expertise on multi-rename files, this becomes a v2 feature.
+- **Config-driven `max_age_days`** (feedback-1 #5, feedback-2 #5): We already have `--since` (explicit window), `--all-history` (no window), and the 24m default (mathematically justified). Adding a config field that derives the default since window creates confusing interaction between config and CLI flags. If half-lives change, updating the default constant is trivial.
+- **Config-driven `decay_floor` for derived `--since` default** (feedback-3 #4): Proposed computing the default since window as `ceil(max_half_life * log2(1/floor))` so it auto-adjusts when half-lives change. Rejected: the formula is non-obvious to users, adds a config param (`decay_floor`) with no intuitive meaning, and the benefit is negligible — half-life changes are rare, and updating a constant is trivial. The 24m default is already mathematically justified and easy to override with `--since` or `--all-history`.
+- **BTreeMap + Kahan/Neumaier compensated summation** (feedback-3 #6): Proposed deterministic iteration order and numerically stable summation. Rejected for this scale: the accumulator processes dozens to low hundreds of entries per user, where HashMap iteration order doesn't measurably affect f64 sums. Compensated summation adds code complexity for zero practical benefit at this magnitude. If we eventually aggregate thousands of signals per user, revisit.
+- **Confidence/coverage metadata** (feedback-1 #8, feedback-2 #8, feedback-3 #9, feedback-4 #6): Repeatedly proposed across reviews with variations (score_adjusted with confidence factor, low/medium/high labels, evidence_mr_count weighting). Still scope creep. The `--explain-score` component breakdown already tells users which signal drives the score. Defining "sparse evidence" thresholds (how many MRs is "low"? what's the right exponential saturation constant?) is domain-specific guesswork without user feedback data. A single recent MR "outranking broader expertise" is the *correct* behavior of time-decay — the model intentionally weights recency. If real-world usage shows this is a problem, confidence becomes a v2 feature informed by actual threshold data.
+- **Automated EXPLAIN QUERY PLAN tests** (feedback-3 #10 partial): SQLite's query planner changes across versions and can use different plans on different data distributions. Automated assertions on plan output are brittle. Instead, we document EXPLAIN QUERY PLAN as a manual verification step during development and include the observed plan as a comment near the SQL.
+- **Per-MR evidence drill-down in `--explain-score`** (feedback-2 #7 promoted this): The v1 `--explain-score` shows component totals only. Listing top-evidence MRs per user would require additional SQL queries and significant output format work. Deferred unless component breakdowns prove insufficient for debugging.
+- **Split scoring engine into core module** (feedback-4 #5): Proposed extracting scoring math from `who.rs` into `src/core/scoring/model_v2_decay.rs`. Premature modularization — `who.rs` is the only consumer and is ~800 lines. Adding module plumbing and indirection for a single call site adds complexity without reducing it. If we add a second scoring consumer (e.g., automated triage), revisit.
+- **Bot/service-account filtering** (feedback-4 #7): Real concern but orthogonal to time-decay scoring. This is a general data quality feature that belongs in its own issue — it affects all `who` modes, not just expert scoring. Adding `excluded_username_patterns` config and `--include-bots` flag is scope expansion that should be designed and tested independently.
+- **Model compare mode / rank-delta diagnostics** (feedback-4 #9): Over-engineered rollout safety for an internal CLI tool with ~3 users. Maintaining two parallel scoring codepaths (v1 flat + v2 decayed) doubles test surface and code complexity. The `--explain-score` + `--as-of` combination already provides debugging capability. If a future model change is risky enough to warrant A/B comparison, build it then.
+- **Canonical path identity graph** (feedback-5 #1, also feedback-2 #2, feedback-4 #4): Third time proposed, third time rejected. Building a rename graph from `mr_file_changes(old_path, new_path)` with identity resolution requires new schema (`path_identities`, `path_aliases` tables), ingestion pipeline changes, graph traversal at query time, and backfill logic for existing data. The UNION ALL dual-path matching already covers the 80%+ case (direct renames). Multi-hop rename chains (A→B→C) are rare in practice and can be addressed in v2 with real usage data showing the gap matters.
+- **Normalized `expertise_events` table** (feedback-5 #2): Proposes shifting from query-time CTE joins to a precomputed `expertise_events` table populated at ingest time. While architecturally appealing for read performance, this doubles the data surface area (raw tables + derived events), requires new ingestion pipelines with incremental upsert logic, backfill tooling for existing databases, and introduces consistency risks when raw data is corrected/re-synced. The CTE approach is correct, maintainable, and performant at our current scale. If query latency becomes a real bottleneck (see performance baseline SLOs), materialized views or derived tables become a v2 optimization.
+- **Reviewer engagement model upgrade** (feedback-5 #3): Proposes adding `approved`/`changes_requested` review-state signals and trivial-comment pattern matching (`["lgtm","+1","nit","ship it"]`). Expands the signal type count from 4 to 6 and adds a fragile pattern-matching layer (what about "don't ship it"? "lgtm but..."?). The `reviewer_min_note_chars` threshold is imperfect but pragmatic — it's a single configurable number with no false-positive risk from substring matching. Review-state signals may be worth adding later as a separate enhancement when we have data on how often they diverge from DiffNote participation.
+- **Contribution-floor auto cutoff for `--since`** (feedback-5 #5): Proposes `--since auto` computing the earliest relevant timestamp from `min_contribution_floor` (e.g., 0.01 points). Adds a non-obvious config parameter for minimal benefit — the 24m default is already mathematically justified from the decay curves (author: 6%, reviewer: 0.4% at 2 years) and easily overridden with `--since` or `--all-history`. The auto-derivation formula (`ceil(max_half_life * log2(1/floor))`) is opaque to users who just want to understand why a certain time range was selected.
+- **Full evidence drill-down in `--explain-score`** (feedback-5 #8): Proposes `--explain-score=summary|full` with per-MR evidence rows. Already rejected in feedback-2 #7. Component totals are sufficient for v1 debugging — they answer "which signal type drives this user's score." Per-MR drill-down requires additional SQL queries and significant output format complexity. Deferred unless component breakdowns prove insufficient.
+- **Neumaier compensated summation** (feedback-5 #7 partial): Accepted the sorting aspect for deterministic ordering, but rejected Neumaier/Kahan compensated summation. At the scale of dozens to low hundreds of contributions per user, the rounding error from naive f64 summation is on the order of 1e-14 — several orders of magnitude below any meaningful score difference. Compensated summation adds code complexity and a maintenance burden for no practical benefit at this scale.
+- **Automated CI benchmark gate** (feedback-5 #10 partial): Accepted manual performance baselines, but rejected automated CI regression gating with synthetic fixtures (100k/1M/5M notes). Building and maintaining benchmark infrastructure is a significant investment that's premature for a CLI tool with ~3 users. Manual timing checks during development are sufficient until performance becomes a real concern.
+- **Epsilon-based tie buckets for ranking** (feedback-6 #4) — rejected because the plan already has deterministic contribution ordering by `mr_id` within each signal type, which eliminates HashMap-iteration nondeterminism. Platform-dependent `powf` differences at the scale of dozens to hundreds of contributions per user are sub-epsilon (order of 1e-15). If two users genuinely score within 1e-9 of each other, the existing tiebreak by `(last_seen DESC, username ASC)` is already meaningful and deterministic. Adding a bucketing layer introduces a magic epsilon constant and floor operation for a problem that doesn't manifest in practice.
+- **`--diagnose-score` aggregated diagnostics flag** (feedback-6 #5) — rejected because this is diagnostic/debugging tooling that adds a new flag, new output format, and new counting logic (matched_notes_raw_count, dedup_count, window exclusions, etc.) across the SQL pipeline. The existing `--explain-score` component breakdown + manual EXPLAIN QUERY PLAN verification already covers the debugging need. The additional SQL instrumentation required (counting rows at each CTE stage) would complicate the query for a feature with unclear demand. A v2 addition if operational debugging becomes a recurring need.
+- **Multi-path expert scoring (`--path` repeatable)** (feedback-6 #7) — rejected because this is a feature expansion, not a plan improvement for the time-decay model. Multi-path requires a `requested_paths` CTE, modified dedup logic keyed on `(username, signal, mr_id)` across paths, CLI parsing changes for repeatable `--path` and `--path-file`, and new test cases for overlap/prefix/dedup semantics. This is a separate bead/feature that should be designed independently — it's orthogonal to time-decay scoring and can be added later without requiring any changes to the decay model.

plans/tui-prd-v2-frankentui.feedback-1.md

@@ -0,0 +1,209 @@
+No `## Rejected Recommendations` section was present, so these are all net-new improvements.
+
+1. Keep core `lore` stable; isolate nightly to a TUI crate  
+Rationale: the current plan says “whole project nightly” but later assumes TUI is feature-gated. Isolating nightly removes unnecessary risk from non-TUI users, CI, and release cadence.
+
+```diff
+@@ 3.2 Nightly Rust Strategy
+-- The entire gitlore project moves to pinned nightly, not just the TUI feature.
++- Keep core `lore` on stable Rust.
++- Add workspace member `lore-tui` pinned to nightly for FrankenTUI.
++- Ship `lore tui` only when `--features tui` (or separate `lore-tui` binary) is enabled.
+
+@@ 10.1 New Files
++- crates/lore-tui/Cargo.toml
++- crates/lore-tui/src/main.rs
+
+@@ 11. Assumptions
+-17. TUI module is feature-gated.
++17. TUI is isolated in a workspace crate and feature-gated in root CLI integration.
+```
+
+2. Add a framework adapter boundary from day 1  
+Rationale: the “3-day ratatui escape hatch” is optimistic without a strict interface. A tiny `UiRuntime` + screen renderer trait makes fallback real, not aspirational.
+
+```diff
+@@ 4. Architecture
++### 4.9 UI Runtime Abstraction
++Introduce `UiRuntime` trait (`run`, `send`, `subscribe`) and `ScreenRenderer` trait.
++FrankenTUI implementation is default; ratatui adapter can be dropped in with no state/action rewrite.
+
+@@ 3.5 Escape Hatch
+-- The migration cost to ratatui is ~3 days
++- Migration cost target is ~3-5 days, validated by one ratatui spike screen in Phase 1.
+```
+
+3. Stop using CLI command modules as the TUI query API  
+Rationale: coupling TUI to CLI output-era structs creates long-term friction and accidental regressions. Create a shared domain query layer used by both CLI and TUI.
+
+```diff
+@@ 10.20 Refactor: Extract Query Functions
+-- extract query_* from cli/commands/*
++- introduce `src/domain/query/*` as the canonical read model API.
++- CLI and TUI both depend on domain query layer.
++- CLI modules retain formatting/output only.
+
+@@ 10.2 Modified Files
++- src/domain/query/mod.rs
++- src/domain/query/issues.rs
++- src/domain/query/mrs.rs
++- src/domain/query/search.rs
++- src/domain/query/who.rs
+```
+
+4. Replace single `Arc<Mutex<Connection>>` with connection manager  
+Rationale: one locked connection serializes everything and hurts responsiveness, especially during sync. Use separate read pool + writer connection with WAL and busy timeout.
+
+```diff
+@@ 4.4 App — Implementing the Model Trait
+- pub db: Arc<Mutex<Connection>>,
++ pub db: Arc<DbManager>, // read pool + single writer coordination
+
+@@ 4.5 Async Action System
+- Each Cmd::task closure locks the mutex, runs the query, and returns a Msg
++ Reads use pooled read-only connections.
++ Sync/write path uses dedicated writer connection.
++ Enforce WAL, busy_timeout, and retry policy for SQLITE_BUSY.
+```
+
+5. Make debouncing/cancellation explicit and correct  
+Rationale: “runtime coalesces rapid keypresses” is not a safe correctness guarantee. Add request IDs and stale-response dropping to prevent flicker and wrong data.
+
+```diff
+@@ 4.3 Core Types (Msg)
++ SearchRequestStarted { request_id: u64, query: String }
+- SearchExecuted(SearchResults),
++ SearchExecuted { request_id: u64, results: SearchResults },
+
+@@ 4.4 maybe_debounced_query()
+- runtime coalesces rapid keypresses
++ use explicit 200ms debounce timer + monotonic request_id
++ ignore results whose request_id != current_search_request_id
+```
+
+6. Implement true streaming sync, not batch-at-end pseudo-streaming  
+Rationale: the plan promises real-time logs/progress but code currently returns one completion message. This gap will disappoint users and complicate cancellation.
+
+```diff
+@@ 4.4 start_sync_task()
+- Pragmatic approach: run sync synchronously, collect all progress events, return summary.
++ Use event channel subscription for `SyncProgress`/`SyncLogLine` streaming.
++ Keep `SyncCompleted` only as terminal event.
++ Add cooperative cancel token mapped to `Esc` while running.
+
+@@ 5.9 Sync
++ Add "Resume from checkpoint" option for interrupted syncs.
+```
+
+7. Fix entity identity ambiguity across projects  
+Rationale: using `iid` alone is unsafe in multi-project datasets. Navigation and cross-refs should key by `(project_id, iid)` or global ID.
+
+```diff
+@@ 4.3 Core Types
+- IssueDetail(i64)
+- MrDetail(i64)
++ IssueDetail(EntityKey)
++ MrDetail(EntityKey)
+
++ pub struct EntityKey { pub project_id: i64, pub iid: i64, pub kind: EntityKind }
+
+@@ 10.12.4 Cross-Reference Widget
+- parse "group/project#123" -> iid only
++ parse into `{project_path, iid, kind}` then resolve to `project_id` before navigation
+```
+
+8. Resolve keybinding conflicts and formalize keymap precedence  
+Rationale: current spec conflicts (`Tab` sort vs focus filter; `gg` vs go-prefix). A deterministic keymap contract prevents UX bugs.
+
+```diff
+@@ 8.2 List Screens
+- Tab | Cycle sort column
+- f   | Focus filter bar
++ Tab | Focus filter bar
++ S   | Cycle sort column
++ /   | Focus filter bar (alias)
+
+@@ 4.4 interpret_key()
++ Add explicit precedence table:
++ 1) modal/palette
++ 2) focused input
++ 3) global
++ 4) screen-local
++ Add configurable go-prefix timeout (default 500ms) with cancel feedback.
+```
+
+9. Add performance SLOs and DB/index plan  
+Rationale: “fast enough” is vague. Add measurable budgets, required indexes, and query-plan gates in CI for predictable performance.
+
+```diff
+@@ 3.1 Risk Matrix
++ Add risk: "Query latency regressions on large datasets"
+
+@@ 9.3 Phase 0 — Toolchain Gate
++7. p95 list query latency < 75ms on 100k issues synthetic fixture
++8. p95 search latency < 200ms on 1M docs (lexical mode)
+
+@@ 11. Assumptions
+-5. SQLite queries are fast enough for interactive use (<50ms for filtered results).
++5. Performance budgets are enforced by benchmark fixtures and query-plan checks.
++6. Required indexes documented and migration-backed before TUI GA.
+```
+
+10. Add reliability/observability model (error classes, retries, tracing)  
+Rationale: one string toast is not enough for production debugging. Add typed errors, retry policy, and an in-TUI diagnostics pane.
+
+```diff
+@@ 4.3 Core Types (Msg)
+- Error(String),
++ Error(AppError),
+
++ pub enum AppError {
++   DbBusy, DbCorruption, NetworkRateLimited, NetworkUnavailable,
++   AuthFailed, ParseError, Internal(String)
++ }
+
+@@ 5.11 Doctor / Stats
++ Add "Diagnostics" tab:
++ - last 100 errors
++ - retry counts
++ - current sync/backoff state
++ - DB contention metrics
+```
+
+11. Add “Saved Views + Watchlist” as high-value product features  
+Rationale: this makes the TUI compelling daily, not just navigable. Users can persist filters and monitor critical slices (e.g., “P1 auth issues updated in last 24h”).
+
+```diff
+@@ 1. Executive Summary
++ - Saved Views (named filters and layouts)
++ - Watchlist panel (tracked queries with delta badges)
+
+@@ 5. Screen Taxonomy
++### 5.12 Saved Views / Watchlist
++Persistent named filters for Issues/MRs/Search.
++Dashboard shows per-watchlist deltas since last session.
+
+@@ 6. User Flows
++### 6.9 Flow: "Run morning watchlist triage"
++Dashboard -> Watchlist -> filtered IssueList/MRList -> detail drilldown
+```
+
+12. Strengthen testing plan with deterministic behavior and chaos cases  
+Rationale: snapshot tests alone won’t catch race/staleness/cancellation issues. Add concurrency, cancellation, and flaky terminal behavior tests.
+
+```diff
+@@ 9.2 Phases
++Phase 5.5 Reliability Test Pack (2d)
++ - stale response drop tests
++ - sync cancel/resume tests
++ - SQLITE_BUSY retry tests
++ - resize storm and rapid key-chord tests
+
+@@ 10.9 Snapshot Test Example
++ Add non-snapshot tests:
++ - property tests for navigation invariants
++ - integration tests for request ordering correctness
++ - benchmark tests for query budgets
+```
+
+If you want, I can produce a consolidated “PRD v2.1 patch” with all of the above merged into one coherent updated document structure.

plans/tui-prd-v2-frankentui.feedback-10.md

@@ -0,0 +1,214 @@
+I found 9 high-impact revisions that materially improve correctness, robustness, and usability without reintroducing anything in `## Rejected Recommendations`.
+
+### 1. Prevent stale async overwrites on **all** screens (not just search)
+Right now, only `SearchExecuted` is generation-guarded. `IssueListLoaded`, `MrListLoaded`, `IssueDetailLoaded`, etc. can still race and overwrite newer state after rapid navigation/filtering. This is the biggest correctness risk in the current design.
+
+```diff
+diff --git a/PRD.md b/PRD.md
+@@ message.rs
+-    IssueListLoaded(Vec<IssueRow>),
++    IssueListLoaded { generation: u64, rows: Vec<IssueRow> },
+@@
+-    MrListLoaded(Vec<MrRow>),
++    MrListLoaded { generation: u64, rows: Vec<MrRow> },
+@@
+-    IssueDetailLoaded { key: EntityKey, detail: IssueDetail },
+-    MrDetailLoaded { key: EntityKey, detail: MrDetail },
++    IssueDetailLoaded { generation: u64, key: EntityKey, detail: IssueDetail },
++    MrDetailLoaded { generation: u64, key: EntityKey, detail: MrDetail },
+
+@@ update()
+-            Msg::IssueListLoaded(result) => {
++            Msg::IssueListLoaded { generation, rows } => {
++                if !self.task_supervisor.is_current(&TaskKey::LoadScreen(Screen::IssueList), generation) {
++                    return Cmd::none();
++                }
+                 self.state.set_loading(false);
+-                self.state.issue_list.set_result(result);
++                self.state.issue_list.set_result(rows);
+                 Cmd::none()
+             }
+```
+
+### 2. Make cancellation safe with task-owned SQLite interrupt handles
+The plan mentions `sqlite3_interrupt()` but uses pooled shared reader connections. Interrupting a shared connection can cancel unrelated work. Use per-task reader leases and store `InterruptHandle` in `TaskHandle`.
+
+```diff
+diff --git a/PRD.md b/PRD.md
+@@ DbManager
+-    readers: Vec<Mutex<Connection>>,
++    readers: Vec<Mutex<Connection>>,
++    // task-scoped interrupt handles prevent cross-task cancellation bleed
++    // each dispatched query receives an owned ReaderLease
+
++pub struct ReaderLease {
++    conn: Connection,
++    interrupt: rusqlite::InterruptHandle,
++}
++
++impl DbManager {
++    pub fn lease_reader(&self) -> Result<ReaderLease, LoreError> { ... }
++}
+
+@@ TaskHandle
+ pub struct TaskHandle {
+     pub key: TaskKey,
+     pub generation: u64,
+     pub cancel: Arc<CancelToken>,
++    pub interrupt: Option<rusqlite::InterruptHandle>,
+ }
+
+@@ cancellation
+-Query interruption: ... fires sqlite3_interrupt() on the connection.
++Query interruption: cancel triggers the task's owned InterruptHandle only.
++No shared-connection interrupt is permitted.
+```
+
+### 3. Harden keyset pagination for multi-project and sort changes
+`updated_at + iid` cursor is not enough when rows share timestamps across projects or sort mode changes. This can duplicate/skip rows.
+
+```diff
+diff --git a/PRD.md b/PRD.md
+@@ issue_list.rs
+-pub struct IssueCursor {
+-    pub updated_at: i64,
+-    pub iid: i64,
+-}
++pub struct IssueCursor {
++    pub sort_field: SortField,
++    pub sort_order: SortOrder,
++    pub updated_at: Option<i64>,
++    pub created_at: Option<i64>,
++    pub iid: i64,
++    pub project_id: i64,   // deterministic tie-breaker
++    pub filter_hash: u64,  // invalidates stale cursors on filter mutation
++}
+
+@@ pagination section
+-Windowed keyset pagination ...
++Windowed keyset pagination uses deterministic tuple ordering:
++`ORDER BY <primary_sort>, project_id, iid`.
++Cursor is rejected if `filter_hash` or sort tuple mismatches current query.
+```
+
+### 4. Replace ad-hoc filter parsing with a small typed DSL
+Current `split_whitespace()` parser is brittle and silently lossy. Add quoted values, negation, and strict parse errors.
+
+```diff
+diff --git a/PRD.md b/PRD.md
+@@ filter_bar.rs
+-    fn parse_tokens(&mut self) {
+-        let text = self.input.value().to_string();
+-        self.tokens = text.split_whitespace().map(|chunk| { ... }).collect();
+-    }
++    fn parse_tokens(&mut self) {
++        // grammar (v1):
++        // term := [ "-" ] (field ":" value | quoted_text | bare_text)
++        // value := quoted | unquoted
++        // examples:
++        //   state:opened label:"P1 blocker" -author:bot since:14d
++        self.tokens = filter_dsl::parse(self.input.value())?;
++    }
+
+@@ section 8 / keybindings-help
++Filter parser surfaces actionable inline diagnostics with cursor position,
++and never silently drops unknown fields.
+```
+
+### 5. Add render caches for markdown/tree shaping
+Markdown and tree shaping are currently recomputed on every frame in several snippets. Cache render artifacts by `(entity, width, theme, content_hash)` to protect frame time.
+
+```diff
+diff --git a/PRD.md b/PRD.md
+@@ module structure
++    render_cache.rs               # Width/theme/content-hash keyed cache for markdown + tree layouts
+
+@@ Assumptions / Performance
++Detail and search preview rendering uses memoized render artifacts.
++Cache invalidation triggers: content hash change, terminal width change, theme change.
+```
+
+### 6. Use one-shot timers for debounce/prefix timeout
+`Every` is periodic; it wakes repeatedly and can produce edge-case repeated firings. One-shot subscriptions are cleaner and cheaper.
+
+```diff
+diff --git a/PRD.md b/PRD.md
+@@ subscriptions()
+-        if self.state.search.debounce_pending() {
+-            subs.push(Box::new(
+-                Every::with_id(3, Duration::from_millis(200), move || {
+-                    Msg::SearchDebounceFired { generation }
+-                })
+-            ));
+-        }
++        if self.state.search.debounce_pending() {
++            subs.push(Box::new(
++                After::with_id(3, Duration::from_millis(200), move || {
++                    Msg::SearchDebounceFired { generation }
++                })
++            ));
++        }
+
+@@ InputMode GoPrefix timeout
+-The tick subscription compares clock instant...
++GoPrefix timeout is a one-shot `After(500ms)` tied to prefix generation.
+```
+
+### 7. New feature: list “Quick Peek” panel (`Space`) for triage speed
+This adds immediate value without v2-level scope. Users can inspect selected issue/MR metadata/snippet without entering detail and coming back.
+
+```diff
+diff --git a/PRD.md b/PRD.md
+@@ 5.2 Issue List
+-Interaction: Enter detail
++Interaction: Enter detail, Space quick-peek (toggle right preview pane)
+
+@@ 5.4 MR List
++Quick Peek mode mirrors Issue List: metadata + first discussion snippet + cross-refs.
+
+@@ 8.2 List Screens
+ | `Enter` | Open selected item |
++| `Space` | Toggle Quick Peek panel for selected row |
+```
+
+### 8. Upgrade compatibility handshake from integer to machine-readable contract
+Single integer compat is too coarse for real drift detection. Keep it simple but structured.
+
+```diff
+diff --git a/PRD.md b/PRD.md
+@@ Nightly Rust Strategy / Compatibility contract
+-  1. Binary compat version (`lore-tui --compat-version`) — integer check ...
++  1. Binary compat contract (`lore-tui --compat-json`) — JSON:
++     `{ "protocol": 1, "compat_version": 2, "min_schema": 14, "max_schema": 16, "build": "..." }`
++     `lore` validates protocol + compat + schema range before spawn.
+
+@@ CLI integration
+-fn validate_tui_compat(...) { ... --compat-version ... }
++fn validate_tui_compat(...) { ... --compat-json ... }
+```
+
+### 9. Fix sync stream bug and formalize progress coalescing
+The current snippet calls `try_send` for progress twice in one callback path and depth math is wrong. Also progress spam should be coalesced by lane.
+
+```diff
+diff --git a/PRD.md b/PRD.md
+@@ start_sync_task()
+-                        let current_depth = 2048 - tx.try_send(Msg::SyncProgress(event.clone()))
+-                            .err().map_or(0, |_| 1);
+-                        max_queue_depth = max_queue_depth.max(current_depth);
+-                        if tx.try_send(Msg::SyncProgress(event.clone())).is_err() {
++                        // coalesce by lane key at <=30Hz; one send attempt per flush
++                        coalescer.update(event.clone());
++                        if let Some(batch) = coalescer.flush_ready() {
++                            if tx.try_send(Msg::SyncProgressBatch(batch)).is_err() {
+                                 dropped_count += 1;
+                                 let _ = tx.try_send(Msg::SyncBackpressureDrop);
++                            } else {
++                                max_queue_depth = max_queue_depth.max(observed_queue_depth());
++                            }
+                         }
+```
+
+---
+
+If you want, I can produce a single consolidated patch-style rewrite of Sections `4.x`, `5.2/5.4`, `8.2`, `9.3`, and `10.x` so you can drop it directly into iteration 10.