NOTE-2I: Batch parent metadata cache for note regeneration

## Background
extract_note_document() fetches parent entity metadata per note. During initial backfill of ~8K notes, this creates N+1 amplification — 50 notes on same MR = 50 identical parent lookups. Performance optimization for batch regeneration only.

## Approach
1. Add ParentMetadataCache struct in src/documents/extractor.rs:
   HashMap<(String, i64), ParentMetadata> keyed by (noteable_type, parent_local_id)
   ParentMetadata: iid, title, web_url, labels, project_path
   get_or_fetch(conn, noteable_type, parent_id) — HashMap entry API, fetch from DB on miss

2. Add extract_note_document_cached(conn, note_id, cache) variant that uses cache instead of inline queries. Uncached version remains for single-note use.

3. Update batch regeneration loop in src/documents/regenerator.rs:
   let mut parent_cache = ParentMetadataCache::new();
   For SourceType::Note, use extract_note_document_cached with &mut parent_cache.
   Cache created fresh per batch, no cross-batch persistence.

## Files
- MODIFY: src/documents/extractor.rs (ParentMetadataCache + cached variant)
- MODIFY: src/documents/regenerator.rs (use cache in batch loop)

## TDD Anchor
RED: test_note_regeneration_batch_uses_cache — 10 notes on same issue, regenerate all, assert correct documents.
Tests: test_note_regeneration_cache_consistent_with_direct_extraction, test_note_regeneration_cache_invalidates_across_parents

## Acceptance Criteria
- [ ] ParentMetadataCache reduces DB queries during batch regeneration
- [ ] Cached extraction produces identical output to uncached
- [ ] Cache keyed per (noteable_type, parent_id) — no cross-parent leakage
- [ ] Cache scoped to single batch — no persistence or invalidation complexity
- [ ] All 3 tests pass

## Dependency Context
- Depends on NOTE-2C: extract_note_document function must exist to create cached variant


Create lore-tui crate scaffold

## Background
The TUI is implemented as a separate binary crate (crates/lore-tui/) that uses nightly Rust for FrankenTUI. It is EXCLUDED from the root workspace to keep nightly-only deps isolated. The lore CLI spawns lore-tui at runtime via binary delegation — zero compile-time dependency.

## Approach
Create the crate directory structure:
- crates/lore-tui/Cargo.toml with FrankenTUI deps (ftui-core, ftui-runtime, ftui-render, ftui-style, ftui), clap, anyhow, chrono, dirs, rusqlite (bundled), crossterm
- crates/lore-tui/rust-toolchain.toml pinning nightly-2026-02-08
- crates/lore-tui/src/main.rs — binary entry point with TuiCli struct (clap Parser) supporting --config, --sync, --fresh, --render-mode, --ascii, --no-alt-screen
- crates/lore-tui/src/lib.rs — public API: launch_tui(), launch_sync_tui(), LaunchOptions struct, module declarations
- Root Cargo.toml: verify lore-tui is NOT in [workspace] members

The lore-tui crate depends on `lore` (the main crate) as a library dependency for Config, db, LoreError types. The main crate has NO dependency on lore-tui.

## Acceptance Criteria
- [ ] crates/lore-tui/Cargo.toml exists with all required dependencies
- [ ] crates/lore-tui/rust-toolchain.toml pins nightly-2026-02-08
- [ ] crates/lore-tui/src/main.rs compiles with clap CLI args
- [ ] crates/lore-tui/src/lib.rs declares all module stubs and exports LaunchOptions, launch_tui, launch_sync_tui
- [ ] cargo +stable check --workspace --all-targets passes (lore-tui excluded)
- [ ] cargo +nightly check --manifest-path crates/lore-tui/Cargo.toml --all-targets passes
- [ ] Root Cargo.toml does NOT include lore-tui in workspace members

## Files
- CREATE: crates/lore-tui/Cargo.toml
- CREATE: crates/lore-tui/rust-toolchain.toml
- CREATE: crates/lore-tui/src/main.rs
- CREATE: crates/lore-tui/src/lib.rs
- VERIFY: Cargo.toml (root — confirm lore-tui excluded)

## TDD Anchor
RED: Write test in crates/lore-tui/src/lib.rs that asserts LaunchOptions can be constructed with default values.
GREEN: Implement LaunchOptions struct.
VERIFY: cargo test --manifest-path crates/lore-tui/Cargo.toml

## Edge Cases
- Nightly toolchain may not be installed on CI — document rustup install step
- FrankenTUI version pins may need updating if crate publishes breaking changes
- The lore dependency path must use relative path (path = "../../") since lore-tui is not in the workspace


Orchestrator: status enrichment phase with transactional writes

## Background
The orchestrator controls the sync pipeline. Status enrichment is a new Phase 1.5 that runs after issue ingestion but before discussion sync. It must be non-fatal — errors skip enrichment but don't crash the sync.

## Approach
Add enrichment phase to ingest_project_issues_with_progress. Use client.graphql_client() factory. Look up project path from DB via .optional()? for non-fatal failure. Transactional writes via enrich_issue_statuses_txn() with two phases: clear stale, then apply new.

## Files
- src/ingestion/orchestrator.rs (enrichment phase + txn helper + IngestProjectResult fields + ProgressEvent variants)
- src/cli/commands/ingest.rs (add match arms for new ProgressEvent variants)

## Implementation

IngestProjectResult new fields:
  statuses_enriched: usize, statuses_cleared: usize, statuses_seen: usize,
  statuses_without_widget: usize, partial_error_count: usize,
  first_partial_error: Option<String>, status_enrichment_error: Option<String>,
  status_enrichment_mode: String, status_unsupported_reason: Option<String>
  Default: all 0/None/"" as appropriate

ProgressEvent new variants:
  StatusEnrichmentComplete { enriched: usize, cleared: usize }
  StatusEnrichmentSkipped

Phase 1.5 logic (after ingest_issues, before discussion sync):
  1. Check config.sync.fetch_work_item_status && !signal.is_cancelled()
  2. If false: set mode="skipped", emit StatusEnrichmentSkipped
  3. Look up project path: conn.query_row("SELECT path_with_namespace FROM projects WHERE id = ?1", [project_id], |r| r.get(0)).optional()?
  4. If None: warn, set status_enrichment_error="project_path_missing", emit StatusEnrichmentComplete{0,0}
  5. Create graphql_client via client.graphql_client()
  6. Call fetch_issue_statuses(&graphql_client, &project_path).await
  7. On Ok: map unsupported_reason to mode/reason, call enrich_issue_statuses_txn(), set counters
  8. On Err: warn, set status_enrichment_error, mode="fetched"
  9. Emit StatusEnrichmentComplete

enrich_issue_statuses_txn(conn, project_id, statuses, all_fetched_iids, now_ms) -> Result<(usize, usize)>:
  Uses conn.unchecked_transaction() (conn is &Connection not &mut)
  Phase 1 (clear): UPDATE issues SET status_*=NULL, status_synced_at=now_ms WHERE project_id=? AND iid=? AND status_name IS NOT NULL — for IIDs in all_fetched_iids but NOT in statuses
  Phase 2 (apply): UPDATE issues SET status_name=?, status_category=?, status_color=?, status_icon_name=?, status_synced_at=now_ms WHERE project_id=? AND iid=?
  tx.commit(), return (enriched, cleared)

In src/cli/commands/ingest.rs progress callback, add arms:
  ProgressEvent::StatusEnrichmentComplete { enriched, cleared } => { ... }
  ProgressEvent::StatusEnrichmentSkipped => { ... }

## Acceptance Criteria
- [ ] Enrichment runs after ingest_issues, before discussion sync
- [ ] Gated by config.sync.fetch_work_item_status
- [ ] Project path missing -> skipped with error="project_path_missing", sync continues
- [ ] enrich_issue_statuses_txn correctly UPDATEs status columns + status_synced_at
- [ ] Stale status cleared: issue in all_fetched_iids but not statuses -> NULL + synced_at set
- [ ] Transaction rollback on failure: no partial updates
- [ ] Idempotent: running twice with same data produces same result
- [ ] GraphQL error: logged, enrichment_error captured, sync continues
- [ ] ingest.rs compiles with new ProgressEvent arms
- [ ] cargo check --all-targets passes

## TDD Loop
RED: test_enrich_issue_statuses_txn, test_enrich_skips_unknown_iids, test_enrich_clears_removed_status, test_enrich_transaction_rolls_back_on_failure, test_enrich_idempotent_across_two_runs, test_enrich_sets_synced_at_on_clear, test_enrichment_error_captured_in_result, test_project_path_missing_skips_enrichment
  Tests use in-memory DB with migration 021 applied
GREEN: Implement enrichment phase + txn helper + result fields + progress arms
VERIFY: cargo test enrich && cargo test orchestrator

## Edge Cases
- unchecked_transaction() needed because conn is &Connection not &mut Connection
- .optional()? requires use rusqlite::OptionalExtension
- status_synced_at is set on BOTH clear and apply operations (not NULL on clear)
- Clear SQL has WHERE status_name IS NOT NULL to avoid counting already-cleared rows
- Progress callback match must be updated in SAME batch as enum change (compile error otherwise)
- status_enrichment_mode must be set in ALL code paths (fetched/unsupported/skipped)

Implemented by agent swarm — all quality gates pass (595 tests, 0 failures)


Implement Issue List (state + action + view)

## Background
The Issue List is the primary browse interface for issues. It uses keyset pagination (not OFFSET) for deterministic cross-page traversal under concurrent sync writes. A browse snapshot fence preserves stable ordering until explicit refresh.

## Approach
State (state/issue_list.rs):
- IssueListState: window (Vec<IssueListRow>), total_count, selected_index, scroll_offset, next_cursor (Option<IssueCursor>), prev_cursor (Option<IssueCursor>), prefetch_in_flight (bool), filter (IssueFilter), filter_input (TextInput), filter_focused (bool), sort_field (SortField), sort_order (SortOrder)
- IssueCursor: updated_at (i64), iid (i64) — boundary values for keyset pagination
- IssueFilter: state (Option<String>), author (Option<String>), assignee (Option<String>), label (Option<String>), milestone (Option<String>), status (Option<String>), free_text (Option<String>), project_id (Option<i64>)
- IssueListRow: project_path, iid, title, state, author, assignee, labels, updated_at, status_name, status_icon
- handle_key(): j/k scroll, J/K page, Enter select, / focus filter, Tab sort, g+g top, G bottom, r refresh
- scroll_to_top(), apply_filter(), set_sort()

Action (action.rs):
- fetch_issues(conn, filter, cursor, page_size, clock) -> Result<IssueListPage, LoreError>: keyset pagination query with WHERE (updated_at, iid) < (cursor.updated_at, cursor.iid) ORDER BY updated_at DESC, iid DESC LIMIT page_size+1 (extra row detects has_next). Uses idx_issues_list_default index.
- IssueListPage: rows, next_cursor, prev_cursor, total_count

View (view/issue_list.rs):
- render_issue_list(frame, state, area, theme): FilterBar at top, EntityTable below, status bar at bottom
- Columns: IID, Title (flex), State, Author, Labels, Updated, Status
- Quick Peek: Enter on row opens issue detail, Esc returns with state preserved

## Acceptance Criteria
- [ ] Keyset pagination fetches pages without OFFSET
- [ ] Next/prev page navigation preserves deterministic ordering
- [ ] Browse snapshot fence prevents rows from shifting during concurrent sync
- [ ] Filter bar accepts DSL tokens and triggers re-query via ScreenIntent::RequeryNeeded
- [ ] j/k scrolls within current page, J/K loads next/prev page
- [ ] Enter navigates to IssueDetail(EntityKey), Esc returns to list with cursor preserved
- [ ] Tab cycles sort column, sort indicator shown
- [ ] Total count displayed in status area

## Files
- MODIFY: crates/lore-tui/src/state/issue_list.rs (expand from stub)
- MODIFY: crates/lore-tui/src/action.rs (add fetch_issues)
- CREATE: crates/lore-tui/src/view/issue_list.rs

## TDD Anchor
RED: Write test_keyset_pagination in action.rs that inserts 30 issues, fetches page 1 (size 10), then fetches page 2 using returned cursor, asserts no overlap between pages.
GREEN: Implement keyset pagination query.
VERIFY: cargo test --manifest-path crates/lore-tui/Cargo.toml test_keyset_pagination

## Edge Cases
- Multi-project datasets: cursor must include project_id scope from global ScopeContext
- Issues with identical updated_at: keyset tiebreaker on iid ensures deterministic ordering
- Empty result set: show "No issues match your filter" message, not empty table
- Filter changes must reset cursor to first page (not continue from mid-pagination)

## Dependency Context
Uses EntityTable and FilterBar from "Implement entity table + filter bar widgets" task.
Uses AppState, IssueListState, ScreenIntent from "Implement AppState composition" task.
Uses TaskSupervisor for load management from "Implement TaskSupervisor" task.
Uses DbManager from "Implement DbManager" task.


Implement property tests for navigation invariants

## Background
Property-based tests verify navigation invariants hold for all possible sequences of push/pop/forward/jump/reset operations. Uses proptest or quickcheck for automated input generation.

## Approach
- Property: stack depth always >= 1 (Dashboard is always reachable)
- Property: after push(X), current() == X
- Property: after push(X) then pop(), current() returns to previous
- Property: forward_stack cleared after any push (browser semantics)
- Property: jump_list only contains detail/entity screens
- Property: reset_to(X) clears all history, current() == X
- Property: breadcrumbs length == back_stack.len() + 1
- Arbitrary sequence of operations should never panic

## Acceptance Criteria
- [ ] All 7 navigation properties hold for 10000 generated test cases
- [ ] No panic for any sequence of operations
- [ ] Proptest shrinking finds minimal counterexamples on failure

## Files
- CREATE: crates/lore-tui/tests/nav_property_tests.rs

## TDD Anchor
RED: Write proptest that generates random sequences of push/pop/forward/reset, asserts stack depth >= 1 after every operation.
GREEN: Ensure NavigationStack maintains invariant (pop returns None at root).
VERIFY: cargo test --manifest-path crates/lore-tui/Cargo.toml nav_property

## Dependency Context
Uses NavigationStack from "Implement NavigationStack" task.
Uses Screen enum from "Implement core types" task.


OBSERV Epic: Phase 3 - Performance Metrics Collection

StageTiming struct, custom MetricsLayer tracing subscriber layer, span-to-metrics extraction, robot JSON enrichment with meta.stages, human-readable timing summary.

Depends on: Phase 2 (spans must exist to extract timing from)
Unblocks: Phase 4 (sync history needs Vec<StageTiming> to store)

Files: src/core/metrics.rs (new), src/cli/commands/sync.rs, src/cli/commands/ingest.rs, src/main.rs

Acceptance criteria (PRD Section 6.3):
- lore --robot sync includes meta.run_id and meta.stages array
- Each stage has name, elapsed_ms, items_processed
- Top-level stages have sub_stages arrays
- Interactive sync prints timing summary table
- Zero-value fields omitted from JSON

All Phase 3 tasks complete: StageTiming struct, MetricsLayer, span field recording, robot JSON enrichment with stages, and human-readable timing summary


Implement hybrid search with adaptive recall

## Background
Hybrid search is the top-level search orchestrator that combines FTS5 lexical results with sqlite-vec semantic results via RRF ranking. It supports three modes (Lexical, Semantic, Hybrid) and implements adaptive recall (wider initial fetch when filters are applied) and graceful degradation (falls back to FTS when Ollama is unavailable). All modes use RRF for consistent --explain output.

## Approach
Create `src/search/hybrid.rs` per PRD Section 5.3.

**Key types:**
```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SearchMode {
    Hybrid,    // Vector + FTS with RRF
    Lexical,   // FTS only
    Semantic,  // Vector only
}

impl SearchMode {
    pub fn from_str(s: &str) -> Option<Self> {
        match s.to_lowercase().as_str() {
            "hybrid" => Some(Self::Hybrid),
            "lexical" | "fts" => Some(Self::Lexical),
            "semantic" | "vector" => Some(Self::Semantic),
            _ => None,
        }
    }

    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Hybrid => "hybrid",
            Self::Lexical => "lexical",
            Self::Semantic => "semantic",
        }
    }
}

pub struct HybridResult {
    pub document_id: i64,
    pub score: f64,          // Normalized RRF score (0-1)
    pub vector_rank: Option<usize>,
    pub fts_rank: Option<usize>,
    pub rrf_score: f64,      // Raw RRF score
}
```

**Core function (ASYNC, PRD-exact signature):**
```rust
pub async fn search_hybrid(
    conn: &Connection,
    client: Option<&OllamaClient>,      // None if Ollama unavailable
    ollama_base_url: Option<&str>,       // For actionable error messages
    query: &str,
    mode: SearchMode,
    filters: &SearchFilters,
    fts_mode: FtsQueryMode,
) -> Result<(Vec<HybridResult>, Vec<String>)>
```

**IMPORTANT — client is `Option<&OllamaClient>`:** This enables graceful degradation. When Ollama is unavailable, the caller passes `None` and hybrid mode falls back to FTS-only with a warning. The `ollama_base_url` is separate so error messages can include it even when client is None.

**Adaptive recall constants (PRD Section 5.3):**
```rust
const BASE_RECALL_MIN: usize = 50;
const FILTERED_RECALL_MIN: usize = 200;
const RECALL_CAP: usize = 1500;
```

**Recall formula:**
```rust
let requested = filters.clamp_limit();
let top_k = if filters.has_any_filter() {
    (requested * 50).max(FILTERED_RECALL_MIN).min(RECALL_CAP)
} else {
    (requested * 10).max(BASE_RECALL_MIN).min(RECALL_CAP)
};
```

**Mode behavior:**
- **Lexical:** FTS only -> rank_rrf with empty vector list (single-list RRF)
- **Semantic:** Vector only -> requires client (error if None) -> rank_rrf with empty FTS list
- **Hybrid:** Both FTS + vector -> rank_rrf with both lists
- **Hybrid with client=None:** Graceful degradation to Lexical with warning, NOT error

**Graceful degradation logic:**
```rust
SearchMode::Hybrid => {
    let fts_results = search_fts(conn, query, top_k, fts_mode)?;
    let fts_tuples: Vec<_> = fts_results.iter().map(|r| (r.document_id, r.rank)).collect();

    match client {
        Some(client) => {
            let query_embedding = client.embed_batch(vec\![query.to_string()]).await?;
            let embedding = query_embedding.into_iter().next().unwrap();
            let vec_results = search_vector(conn, &embedding, top_k)?;
            let vec_tuples: Vec<_> = vec_results.iter().map(|r| (r.document_id, r.distance)).collect();
            let ranked = rank_rrf(&vec_tuples, &fts_tuples);
            // ... map to HybridResult
            Ok((results, warnings))
        }
        None => {
            warnings.push("Ollama unavailable, falling back to lexical search".into());
            let ranked = rank_rrf(&[], &fts_tuples);
            // ... map to HybridResult
            Ok((results, warnings))
        }
    }
}
```

## Acceptance Criteria
- [ ] Function is `async` (per PRD — Ollama client methods are async)
- [ ] Signature takes `client: Option<&OllamaClient>` (not required)
- [ ] Signature takes `ollama_base_url: Option<&str>` for actionable error messages
- [ ] Returns `(Vec<HybridResult>, Vec<String>)` — results + warnings
- [ ] Lexical mode: FTS-only results ranked via RRF (single list)
- [ ] Semantic mode: vector-only results ranked via RRF; error if client is None
- [ ] Hybrid mode: both FTS + vector results merged via RRF
- [ ] Graceful degradation: client=None in Hybrid falls back to FTS with warning (not error)
- [ ] Adaptive recall: unfiltered max(50, limit*10), filtered max(200, limit*50), capped 1500
- [ ] All modes produce consistent --explain output (vector_rank, fts_rank, rrf_score)
- [ ] SearchMode::from_str accepts aliases: "fts" for Lexical, "vector" for Semantic
- [ ] `cargo build` succeeds

## Files
- `src/search/hybrid.rs` — new file
- `src/search/mod.rs` — add `pub use hybrid::{search_hybrid, HybridResult, SearchMode};`

## TDD Loop
RED: Tests (some integration, some unit):
- `test_lexical_mode` — FTS results only
- `test_semantic_mode` — vector results only
- `test_hybrid_mode` — both lists merged
- `test_graceful_degradation` — None client falls back to FTS with warning in warnings vec
- `test_adaptive_recall_unfiltered` — recall = max(50, limit*10)
- `test_adaptive_recall_filtered` — recall = max(200, limit*50)
- `test_recall_cap` — never exceeds 1500
- `test_search_mode_from_str` — "hybrid", "lexical", "fts", "semantic", "vector", invalid
GREEN: Implement search_hybrid
VERIFY: `cargo test hybrid`

## Edge Cases
- Both FTS and vector return zero results: empty output (not error)
- FTS returns results but vector returns empty: RRF still works (single-list)
- Very high limit (100) with filters: recall = min(5000, 1500) = 1500
- Semantic mode with client=None: error (OllamaUnavailable), not degradation
- Semantic mode with 0% coverage: return LoreError::EmbeddingsNotBuilt

Implemented hybrid search with 3 modes (lexical/semantic/hybrid), graceful degradation when Ollama unavailable, adaptive recall (50-1500), RRF fusion. 6 tests pass.


Implement RRF ranking

## Background
Reciprocal Rank Fusion (RRF) combines results from multiple retrieval systems (FTS5 lexical + sqlite-vec semantic) into a single ranked list without requiring score normalization. Documents appearing in both lists rank higher than single-list documents. This is the core ranking algorithm for hybrid search in Gate B.

## Approach
Create \`src/search/rrf.rs\` per PRD Section 5.2.

```rust
use std::collections::HashMap;

const RRF_K: f64 = 60.0;

pub struct RrfResult {
    pub document_id: i64,
    pub rrf_score: f64,           // Raw RRF score
    pub normalized_score: f64,    // Normalized to 0-1 (rrf_score / max)
    pub vector_rank: Option<usize>,  // 1-indexed rank in vector list
    pub fts_rank: Option<usize>,     // 1-indexed rank in FTS list
}

/// Input: tuples of (document_id, score/distance) — already sorted by retriever.
/// Ranks are 1-indexed (first result = rank 1).
/// Score = sum of 1/(k + rank) for each list containing the document.
pub fn rank_rrf(
    vector_results: &[(i64, f64)],  // (doc_id, distance)
    fts_results: &[(i64, f64)],     // (doc_id, bm25_score)
) -> Vec<RrfResult>
```

**Algorithm (per PRD):**
1. Build HashMap<doc_id, (rrf_score, vector_rank, fts_rank)>
2. For each vector result at position i: score += 1/(K + (i+1)), record vector_rank = i+1 (**1-indexed**)
3. For each FTS result at position i: score += 1/(K + (i+1)), record fts_rank = i+1 (**1-indexed**)
4. Sort descending by rrf_score
5. Normalize: each result.normalized_score = result.rrf_score / max_score (best = 1.0)

**Key PRD details:**
- Ranks are **1-indexed** (rank 1 = best, not rank 0)
- Input is \`&[(i64, f64)]\` tuples, NOT custom structs
- Output has both \`rrf_score\` (raw) and \`normalized_score\` (0-1)

## Acceptance Criteria
- [ ] Documents in both lists score higher than single-list documents
- [ ] Single-list documents are included (not dropped)
- [ ] Ranks are 1-indexed (first element = rank 1)
- [ ] Raw RRF score available in rrf_score field
- [ ] Normalized score: best = 1.0, all in [0, 1]
- [ ] Results sorted descending by rrf_score
- [ ] vector_rank and fts_rank tracked per result for --explain
- [ ] Empty input lists handled (return empty)
- [ ] One empty list + one non-empty returns results from non-empty list

## Files
- \`src/search/rrf.rs\` — new file
- \`src/search/mod.rs\` — add \`mod rrf; pub use rrf::{rank_rrf, RrfResult};\`

## TDD Loop
RED: Tests in \`#[cfg(test)] mod tests\`:
- \`test_dual_list_ranks_higher\` — doc in both lists scores > doc in one list
- \`test_single_list_included\` — FTS-only and vector-only docs appear
- \`test_normalization\` — best score is 1.0, all in [0, 1]
- \`test_empty_inputs\` — empty returns empty
- \`test_ranks_are_1_indexed\` — verify vector_rank/fts_rank start at 1
- \`test_raw_and_normalized_scores\` — both fields populated correctly
GREEN: Implement rank_rrf()
VERIFY: \`cargo test rrf\`

## Edge Cases
- Duplicate document_id within same list: shouldn't happen, use first occurrence
- Single result in one list, zero in other: normalized_score = 1.0
- Very large input lists: HashMap handles efficiently

Completed: RRF ranking with 1-indexed ranks, raw+normalized scores, vector_rank/fts_rank provenance, 7 tests pass


Implement stale response + SQLITE_BUSY + cancel race tests

## Background
These tests verify the TUI handles async race conditions correctly: stale responses from superseded tasks are dropped, SQLITE_BUSY errors trigger retry with backoff, and query cancellation doesn't bleed across tasks or leave stuck loading states.

## Approach
Stale response tests:
- Submit task A (generation 1), then submit task B (generation 2) with same key
- Deliver task A's result: assert it's dropped (generation mismatch)
- Deliver task B's result: assert it's applied

SQLITE_BUSY retry tests:
- Lock DB with a writer, attempt read query, assert retry with exponential backoff
- Verify TUI shows "Database busy" toast, not a crash

Cancel race tests:
- Submit task, cancel via CancelToken, immediately submit new task with same key
- Assert old task's CancelToken is set, new task proceeds normally
- Rapid cancel-then-resubmit: no stuck LoadingInitial state after sequence
- Cross-task bleed: interrupt handle only cancels the owning task's connection

## Acceptance Criteria
- [ ] Stale response with old generation silently dropped
- [ ] SQLITE_BUSY shows user-friendly error, retries automatically
- [ ] Cancel-then-resubmit: no stuck loading state
- [ ] InterruptHandle only cancels its owning task's query
- [ ] Rapid sequence (5 cancel+submit in 100ms): final state is correct

## Files
- CREATE: crates/lore-tui/tests/race_condition_tests.rs

## TDD Anchor
RED: Write test_stale_response_dropped that submits two tasks, delivers first result, asserts state unchanged.
GREEN: Ensure is_current() check in update() guards all *Loaded handlers.
VERIFY: cargo test --manifest-path crates/lore-tui/Cargo.toml test_stale_response

## Edge Cases
- SQLITE_BUSY timeout must be configurable (default 5000ms)
- Rapid navigation can create >10 pending tasks — all but latest should be cancelled
- CancelToken check must be in hot loops, not just at task entry

## Dependency Context
Uses TaskSupervisor from "Implement TaskSupervisor" task.
Uses DbManager from "Implement DbManager" task.
Uses LoreApp update() stale-result guards from "Implement LoreApp Model" task.


Implement session persistence + instance lock + text width

## Background
Session state persistence allows the TUI to resume where the user left off (current screen, filter state, scroll position). Instance locking prevents data corruption from accidental double-launch. Text width handling ensures correct rendering of CJK, emoji, and combining marks.

## Approach
Session (session.rs):
- SessionState: versioned struct with current_screen, nav_history, per-screen filter/scroll state, global_scope
- save(path): atomic write (tmp->fsync->rename) + CRC32 checksum + max-size guard (1MB)
- load(path) -> Result<SessionState>: validate CRC32, reject corrupted (quarantine bad file), handle version migration
- corruption quarantine: move bad files to .quarantine/ subdir

Instance Lock (instance_lock.rs):
- InstanceLock: advisory lock file (~/.local/share/lore/tui.lock) with PID written
- acquire() -> Result<InstanceLock>: try lock, check for stale lock (PID no longer running), clear stale, create new
- Drop impl: remove lock file
- On collision: clear error message with running PID

Text Width (text_width.rs):
- measure_display_width(s: &str) -> usize: terminal display width using unicode-width + unicode-segmentation
- truncate_display_width(s: &str, max_width: usize) -> String: truncate at grapheme boundary, append ellipsis
- pad_display_width(s: &str, width: usize) -> String: pad with spaces to target display width
- Handles: CJK (2-cell), emoji ZWJ sequences, skin tone modifiers, flag sequences, combining marks

## Acceptance Criteria
- [ ] Session state saved on quit, restored on launch
- [ ] Atomic write prevents partial session files
- [ ] CRC32 checksum detects corruption
- [ ] Corrupted sessions quarantined (not deleted)
- [ ] Max 1MB session file size enforced
- [ ] Instance lock prevents double-launch with clear error
- [ ] Stale lock (dead PID) automatically recovered
- [ ] Lock released on normal exit and on panic (Drop impl)
- [ ] CJK characters measured as 2 cells wide
- [ ] Emoji ZWJ sequences treated as single grapheme cluster
- [ ] Truncation never splits a grapheme cluster

## Files
- CREATE: crates/lore-tui/src/session.rs
- CREATE: crates/lore-tui/src/instance_lock.rs
- CREATE: crates/lore-tui/src/text_width.rs

## TDD Anchor
RED: Write test_measure_cjk_width that asserts measure_display_width("Hello") == 5 and measure_display_width("日本語") == 6.
GREEN: Implement measure_display_width using unicode-width.
VERIFY: cargo test --manifest-path crates/lore-tui/Cargo.toml test_measure

Additional tests:
- test_session_roundtrip: save and load, assert equal
- test_session_corruption_detected: modify saved file, assert load returns error
- test_instance_lock_stale_recovery: create lock with dead PID, assert acquire succeeds
- test_truncate_emoji: truncate string with emoji, assert no split grapheme

## Edge Cases
- Lock file dir doesn't exist: create it
- PID reuse: rare but possible — stale lock detection uses PID existence check only
- Session version migration: old version file should be handled gracefully (reset to defaults)
- text_width: some terminals render emoji incorrectly — we use standard wcwidth semantics


Quality gates: cargo check, clippy, fmt, test

## Background
Final verification that all implementation beads integrate cleanly. Must pass all quality gates before the feature is considered complete.

## Approach
Run all 4 quality gate commands. Fix any issues discovered.

## Commands (in order)
1. cargo check --all-targets (zero errors)
2. cargo clippy --all-targets -- -D warnings (pedantic + nursery clean)
3. cargo fmt --check (formatted)
4. cargo test (all green, including all 42 new tests)

## Acceptance Criteria
- [ ] cargo check --all-targets: exit 0
- [ ] cargo clippy --all-targets -- -D warnings: exit 0
- [ ] cargo fmt --check: exit 0
- [ ] cargo test: all pass (0 failures)
- [ ] All 42 new tests from the plan are present and green

## Known Gotchas from Plan's Trial Run
- clippy::items_after_test_module: ansi256_from_rgb must be BEFORE #[cfg(test)]
- clippy::collapsible_if: use let-chain syntax (if x && let ...)
- clippy::manual_range_contains: use (16..=231).contains(&blue)
- r##"..."## needed for test JSON with hex colors


[CP1] Test fixtures for mocked GitLab responses

Create mock response files for integration tests using wiremock.

## Fixtures to Create

### tests/fixtures/gitlab_issue.json
Single issue with labels:
- id, iid, project_id, title, description, state
- author object
- labels array (string names)
- timestamps
- web_url

### tests/fixtures/gitlab_issues_page.json
Array of issues simulating paginated response:
- 3-5 issues with varying states
- Mix of labels

### tests/fixtures/gitlab_discussion.json
Single discussion:
- id (string)
- individual_note: false
- notes array with 2+ notes
- Include one system note

### tests/fixtures/gitlab_discussions_page.json
Array of discussions:
- Mix of individual_note true/false
- Include resolvable/resolved examples

## Edge Cases to Cover
- Issue with no labels (empty array)
- Issue with labels_details (ignored in CP1)
- Discussion with individual_note=true (single note)
- System notes with system=true
- Resolvable notes

Files: tests/fixtures/gitlab_issue.json, gitlab_issues_page.json, gitlab_discussion.json, gitlab_discussions_page.json
Done when: wiremock handlers can use fixtures for deterministic tests


Fetch closes_issues API and populate entity_references

## Background
GET /projects/:id/merge_requests/:iid/closes_issues returns issues that will close when MR merges. This is the most reliable source for MR→issue relationships. Uses the generic dependent fetch queue (job_type = 'mr_closes_issues').

## Approach

**1. Add API endpoint to GitLab client (src/gitlab/client.rs):**
```rust
/// Fetch issues that will be closed when this MR merges.
pub async fn fetch_mr_closes_issues(
    &self,
    project_id: i64,
    iid: i64
) -> Result<Vec<GitLabIssueRef>>
```

New type in src/gitlab/types.rs:
```rust
#[derive(Debug, Clone, Deserialize)]
pub struct GitLabIssueRef {
    pub id: i64,
    pub iid: i64,
    pub project_id: i64,
    pub title: String,
    pub state: String,
    pub web_url: String,
}
```

URL: `GET /api/v4/projects/{project_id}/merge_requests/{iid}/closes_issues?per_page=100`

**2. Enqueue jobs during MR ingestion:**
In orchestrator.rs, after MR upsert:
```rust
enqueue_job(conn, project_id, "merge_request", iid, local_id, "mr_closes_issues", None)?;
```

This is always enqueued (not gated by a config flag) because cross-reference data is fundamental to all temporal queries.

**3. Process jobs in drain step:**
In the drain dispatcher (from bd-1ep), handle "mr_closes_issues" job_type:
```rust
let closes_issues = client.fetch_mr_closes_issues(gitlab_project_id, job.entity_iid).await?;
for issue_ref in &closes_issues {
    let target_id = resolve_issue_local_id(conn, project_id, issue_ref.iid);
    insert_entity_reference(conn, EntityReference {
        source_entity_type: "merge_request",
        source_entity_id: job.entity_local_id,
        target_entity_type: "issue",
        target_entity_id: target_id,            // Some(id) or None for cross-project
        target_project_path: if target_id.is_none() { Some(resolve_project_path(issue_ref.project_id)) } else { None },
        target_entity_iid: if target_id.is_none() { Some(issue_ref.iid) } else { None },
        reference_type: "closes",
        source_method: "api_closes_issues",
        created_at: None,
    })?;
}
```

**4. Insert helper for entity_references:**
Add to src/core/references.rs:
```rust
pub fn insert_entity_reference(conn: &Connection, ref_: &EntityReference) -> Result<bool>
// INSERT OR IGNORE, returns true if inserted
```

## Acceptance Criteria
- [ ] closes_issues API called for all MRs during sync
- [ ] Entity references created with reference_type='closes', source_method='api_closes_issues'
- [ ] Source = MR, target = issue (correct directionality)
- [ ] Cross-project issues stored as unresolved (target_entity_id=NULL, target_project_path set)
- [ ] Idempotent: re-sync doesn't create duplicate references
- [ ] 404 on deleted MR handled gracefully (fail_job)

## Files
- src/gitlab/client.rs (add fetch_mr_closes_issues)
- src/gitlab/types.rs (add GitLabIssueRef)
- src/core/references.rs (add insert_entity_reference helper)
- src/ingestion/orchestrator.rs (enqueue mr_closes_issues jobs)
- src/core/drain.rs or sync.rs (handle mr_closes_issues in drain dispatcher)

## TDD Loop
RED: tests/references_tests.rs:
- `test_closes_issues_creates_references` - mock closes_issues response, verify entity_references rows
- `test_closes_issues_cross_project_unresolved` - issue from different project stored as unresolved
- `test_closes_issues_idempotent` - process same job twice, verify no duplicates

tests/gitlab_types_tests.rs:
- `test_deserialize_issue_ref` - verify GitLabIssueRef deserialization

GREEN: Implement API endpoint, enqueue hook, drain handler, insert helper

VERIFY: `cargo test references -- --nocapture && cargo test gitlab_types -- --nocapture`

## Edge Cases
- closes_issues API returns issues from OTHER projects (cross-project closing) — must check if issue is in local DB
- Empty response (MR doesn't close any issues) — no refs created, job still completed
- MR may close the same issue via description ("Closes #123") and via commits — API deduplicates, but our INSERT OR IGNORE handles it too
- The closes_issues API may return stale data for draft MRs (issues that *would* close but haven't yet)


NOTE-1B: CLI arguments and command wiring for lore notes

## Background
Wire the notes query layer into the CLI. Add NotesArgs clap struct, Notes variant to Commands enum, and handler in main.rs.

## Approach
1. Add NotesArgs to src/cli/mod.rs (after MrsArgs ~line 472) with full clap derive:
   --limit/-n (default 50), --fields, --format (table/json/jsonl/csv), --author/-a, --note-type, --contains, --note-id, --gitlab-note-id, --discussion-id, --include-system, --for-issue (conflicts_with for_mr), --for-mr, --project/-p, --since, --until, --path, --resolution, --sort, --asc
   NOTE: --for-issue/--for-mr do NOT use clap requires="project" (defaultProject handles it)

2. Add Notes(NotesArgs) to Commands enum (~line 113)

3. Add "notes" minimal preset to expand_fields_preset() in src/cli/robot.rs (~line 42):
   "notes" => ["id", "author_username", "body", "created_at_iso"]

4. Add handle_notes() in src/main.rs following handle_issues/handle_mrs pattern. Dispatch format: robot/json, jsonl, csv, table.

5. Re-export in src/cli/commands/mod.rs

## Files
- MODIFY: src/cli/mod.rs (NotesArgs struct + Commands::Notes variant)
- MODIFY: src/cli/robot.rs (notes minimal preset)
- MODIFY: src/main.rs (handle_notes + dispatch)
- MODIFY: src/cli/commands/mod.rs (re-export)

## TDD Anchor
RED: test_expand_fields_preset_notes — assert minimal preset returns ["id", "author_username", "body", "created_at_iso"]

## Acceptance Criteria
- [ ] lore notes command exists and dispatches to handle_notes
- [ ] All 19 CLI flags parsed correctly by clap
- [ ] --for-issue and --for-mr are mutually exclusive
- [ ] --format supports table, json, jsonl, csv
- [ ] Robot mode auto-selects JSON output
- [ ] --fields minimal preset works for notes
- [ ] Test passes

## Dependency Context
- Depends on NOTE-1A: uses NoteListFilters, run_list_notes, print functions


Add database migration 006_merge_requests.sql

## Background
Foundation for all CP2 MR features. This migration defines the schema that all other MR components depend on. Must complete BEFORE any other CP2 work can proceed.

## Approach
Create migration file that adds:
1. `merge_requests` table with all CP2 fields
2. `mr_labels`, `mr_assignees`, `mr_reviewers` junction tables
3. Indexes on discussions for MR queries
4. DiffNote position columns on notes table

## Files
- `migrations/006_merge_requests.sql` - New migration file
- `src/core/db.rs` - Update MIGRATIONS const to include version 6

## Acceptance Criteria
- [ ] Migration file exists at `migrations/006_merge_requests.sql`
- [ ] `merge_requests` table has columns: id, gitlab_id, project_id, iid, title, description, state, draft, author_username, source_branch, target_branch, head_sha, references_short, references_full, detailed_merge_status, merge_user_username, created_at, updated_at, merged_at, closed_at, last_seen_at, discussions_synced_for_updated_at, discussions_sync_last_attempt_at, discussions_sync_attempts, discussions_sync_last_error, web_url, raw_payload_id
- [ ] `mr_labels` junction table exists with (merge_request_id, label_id) PK
- [ ] `mr_assignees` junction table exists with (merge_request_id, username) PK
- [ ] `mr_reviewers` junction table exists with (merge_request_id, username) PK
- [ ] `idx_discussions_mr_id` and `idx_discussions_mr_resolved` indexes exist
- [ ] `notes` table has new columns: position_type, position_line_range_start, position_line_range_end, position_base_sha, position_start_sha, position_head_sha
- [ ] `gi doctor` runs without migration errors
- [ ] `cargo test` passes

## TDD Loop
RED: Cannot open DB with version 6 schema
GREEN: Add migration file with full SQL
VERIFY: `cargo run -- doctor` shows healthy DB

## SQL Reference (from PRD)
```sql
-- Merge requests table
CREATE TABLE merge_requests (
  id INTEGER PRIMARY KEY,
  gitlab_id INTEGER UNIQUE NOT NULL,
  project_id INTEGER NOT NULL REFERENCES projects(id),
  iid INTEGER NOT NULL,
  title TEXT,
  description TEXT,
  state TEXT,                         -- opened | merged | closed | locked
  draft INTEGER NOT NULL DEFAULT 0,   -- SQLite boolean
  author_username TEXT,
  source_branch TEXT,
  target_branch TEXT,
  head_sha TEXT,
  references_short TEXT,
  references_full TEXT,
  detailed_merge_status TEXT,
  merge_user_username TEXT,
  created_at INTEGER,                 -- ms epoch UTC
  updated_at INTEGER,
  merged_at INTEGER,
  closed_at INTEGER,
  last_seen_at INTEGER NOT NULL,
  discussions_synced_for_updated_at INTEGER,
  discussions_sync_last_attempt_at INTEGER,
  discussions_sync_attempts INTEGER DEFAULT 0,
  discussions_sync_last_error TEXT,
  web_url TEXT,
  raw_payload_id INTEGER REFERENCES raw_payloads(id)
);
CREATE INDEX idx_mrs_project_updated ON merge_requests(project_id, updated_at);
CREATE UNIQUE INDEX uq_mrs_project_iid ON merge_requests(project_id, iid);
-- ... (see PRD for full index list)

-- Junction tables
CREATE TABLE mr_labels (
  merge_request_id INTEGER REFERENCES merge_requests(id) ON DELETE CASCADE,
  label_id INTEGER REFERENCES labels(id) ON DELETE CASCADE,
  PRIMARY KEY(merge_request_id, label_id)
);

CREATE TABLE mr_assignees (
  merge_request_id INTEGER REFERENCES merge_requests(id) ON DELETE CASCADE,
  username TEXT NOT NULL,
  PRIMARY KEY(merge_request_id, username)
);

CREATE TABLE mr_reviewers (
  merge_request_id INTEGER REFERENCES merge_requests(id) ON DELETE CASCADE,
  username TEXT NOT NULL,
  PRIMARY KEY(merge_request_id, username)
);

-- DiffNote position columns (ALTER TABLE)
ALTER TABLE notes ADD COLUMN position_type TEXT;
ALTER TABLE notes ADD COLUMN position_line_range_start INTEGER;
ALTER TABLE notes ADD COLUMN position_line_range_end INTEGER;
ALTER TABLE notes ADD COLUMN position_base_sha TEXT;
ALTER TABLE notes ADD COLUMN position_start_sha TEXT;
ALTER TABLE notes ADD COLUMN position_head_sha TEXT;

INSERT INTO schema_version (version, applied_at, description)
VALUES (6, strftime('%s', 'now') * 1000, 'Merge requests, MR labels, assignees, reviewers');
```

## Edge Cases
- SQLite does not support ADD CONSTRAINT - FK defined as nullable in CP1
- `locked` state is transitional (merge-in-progress) - store as first-class
- discussions_synced_for_updated_at prevents redundant discussion refetch

Migration 006_merge_requests.sql created and verified. Schema v6 applied successfully with all tables, indexes, and position columns.


Implement terminal safety module (sanitize + URL policy + redact)

## Background
GitLab content (issue titles, descriptions, comments) can contain ANSI escape sequences, OSC codes, bidirectional text overrides, and other terminal control characters that could corrupt display or enable terminal injection attacks. All untrusted text must be sanitized before rendering. URLs must be classified for safe opening. Crash reports must have credentials redacted.

## Approach
Create crates/lore-tui/src/safety.rs:
- sanitize_for_terminal(input: &str) -> String: strips ANSI escape sequences (CSI \x1b[...m etc), OSC sequences (\x1b]...\x07), C1 control codes (0x80-0x9F), bidirectional overrides (U+202A-U+202E, U+2066-U+2069), device control sequences, keeping only safe printable text and whitespace
- UrlPolicy enum: Open, Warn, Block
- classify_safe_url(url: &str) -> UrlPolicy: Open for http/https with common domains, Warn for unknown https, Block for non-http schemes (file://, javascript:, data:)

Create crates/lore-tui/src/redact.rs:
- redact_sensitive(input: &str) -> String: replaces patterns matching PRIVATE-TOKEN, Authorization: Bearer, GITLAB_TOKEN=, and common credential patterns with [REDACTED]

## Acceptance Criteria
- [ ] sanitize_for_terminal strips all ANSI CSI sequences
- [ ] sanitize_for_terminal strips OSC sequences
- [ ] sanitize_for_terminal strips C1 control codes (0x80-0x9F)
- [ ] sanitize_for_terminal strips bidi overrides
- [ ] sanitize_for_terminal preserves normal printable text including Unicode
- [ ] classify_safe_url returns Open for https://gitlab.com/...
- [ ] classify_safe_url returns Block for javascript: and data: URLs
- [ ] redact_sensitive removes PRIVATE-TOKEN values from crash reports
- [ ] redact_sensitive removes Authorization: Bearer tokens
- [ ] redact_sensitive removes GITLAB_TOKEN=... patterns

## Files
- CREATE: crates/lore-tui/src/safety.rs
- CREATE: crates/lore-tui/src/redact.rs

## TDD Anchor
RED: Write test_sanitize_strips_ansi that asserts sanitize_for_terminal("\x1b[31mred\x1b[0m") == "red".
GREEN: Implement ANSI stripping regex/parser.
VERIFY: cargo test --manifest-path crates/lore-tui/Cargo.toml test_sanitize

Additional tests:
- test_sanitize_preserves_unicode: CJK, emoji, combining marks pass through
- test_sanitize_strips_osc: OSC title-set sequences removed
- test_sanitize_strips_bidi: bidirectional overrides removed
- test_url_policy_blocks_javascript: javascript: URLs blocked
- test_redact_removes_tokens: PRIVATE-TOKEN header values replaced

## Edge Cases
- Multi-byte UTF-8 sequences must not be corrupted by stripping — work at char boundaries
- Some terminal emulators use C1 codes (0x80-0x9F) legitimately for 8-bit mode — strip them anyway for safety
- URL classification should be case-insensitive for scheme matching
- Redaction patterns must handle both header-style (PRIVATE-TOKEN: xxx) and env-style (GITLAB_TOKEN=xxx)


Add transform_mr_discussion and transform_notes_with_diff_position

## Background
Extends discussion transformer for MR context. MR discussions can contain DiffNotes with file position metadata. This is critical for code review context in CP3 document generation.

## Approach
Add two new functions to existing `src/gitlab/transformers/discussion.rs`:
1. `transform_mr_discussion()` - Transform discussion with MR reference
2. `transform_notes_with_diff_position()` - Extract DiffNote position metadata

CP1 already has the polymorphic `NormalizedDiscussion` with `NoteableRef` enum - reuse that pattern.

## Files
- `src/gitlab/transformers/discussion.rs` - Add new functions
- `tests/diffnote_tests.rs` - DiffNote position extraction tests
- `tests/mr_discussion_tests.rs` - MR discussion transform tests

## Acceptance Criteria
- [ ] `transform_mr_discussion()` returns `NormalizedDiscussion` with `merge_request_id: Some(local_mr_id)`
- [ ] `transform_notes_with_diff_position()` returns `Result<Vec<NormalizedNote>, String>`
- [ ] DiffNote position fields extracted: `position_old_path`, `position_new_path`, `position_old_line`, `position_new_line`
- [ ] Extended position fields extracted: `position_type`, `position_line_range_start`, `position_line_range_end`
- [ ] SHA triplet extracted: `position_base_sha`, `position_start_sha`, `position_head_sha`
- [ ] Strict timestamp parsing - returns `Err` on invalid timestamps (no `unwrap_or(0)`)
- [ ] `cargo test diffnote` passes
- [ ] `cargo test mr_discussion` passes

## TDD Loop
RED: `cargo test diffnote_position` -> test fails
GREEN: Add position extraction logic
VERIFY: `cargo test diffnote`

## Function Signatures
```rust
/// Transform GitLab discussion for MR context.
/// Reuses existing transform_discussion logic, just with MR reference.
pub fn transform_mr_discussion(
    gitlab_discussion: &GitLabDiscussion,
    local_project_id: i64,
    local_mr_id: i64,
) -> NormalizedDiscussion {
    // Use existing transform_discussion with NoteableRef::MergeRequest(local_mr_id)
    transform_discussion(
        gitlab_discussion,
        local_project_id,
        NoteableRef::MergeRequest(local_mr_id),
    )
}

/// Transform notes with DiffNote position extraction.
/// Returns Result to enforce strict timestamp parsing.
pub fn transform_notes_with_diff_position(
    gitlab_discussion: &GitLabDiscussion,
    local_project_id: i64,
) -> Result<Vec<NormalizedNote>, String>
```

## DiffNote Position Extraction
```rust
// Extract position metadata if present
let (old_path, new_path, old_line, new_line, position_type, lr_start, lr_end, base_sha, start_sha, head_sha) = note
    .position
    .as_ref()
    .map(|pos| (
        pos.old_path.clone(),
        pos.new_path.clone(),
        pos.old_line,
        pos.new_line,
        pos.position_type.clone(),                    // "text" | "image" | "file"
        pos.line_range.as_ref().map(|r| r.start_line),
        pos.line_range.as_ref().map(|r| r.end_line),
        pos.base_sha.clone(),
        pos.start_sha.clone(),
        pos.head_sha.clone(),
    ))
    .unwrap_or((None, None, None, None, None, None, None, None, None, None));
```

## Strict Timestamp Parsing
```rust
// CRITICAL: Return error on invalid timestamps, never zero
let created_at = iso_to_ms(&note.created_at)
    .ok_or_else(|| format\!(
        "Invalid note.created_at for note {}: {}",
        note.id, note.created_at
    ))?;
```

## NormalizedNote Fields for DiffNotes
```rust
NormalizedNote {
    // ... existing fields ...
    // DiffNote position metadata
    position_old_path: old_path,
    position_new_path: new_path,
    position_old_line: old_line,
    position_new_line: new_line,
    // Extended position
    position_type,
    position_line_range_start: lr_start,
    position_line_range_end: lr_end,
    // SHA triplet
    position_base_sha: base_sha,
    position_start_sha: start_sha,
    position_head_sha: head_sha,
}
```

## Edge Cases
- Notes without position should have all position fields as None
- Invalid timestamp should fail the entire discussion (no partial results)
- File renames: `old_path \!= new_path` indicates a renamed file
- Multi-line comments: `line_range` present means comment spans lines 45-48

Implemented transform_mr_discussion() and transform_notes_with_diff_position() with full DiffNote position extraction:
- Extended NormalizedNote with 10 DiffNote position fields (path, line, type, line_range, SHA triplet)
- Added strict timestamp parsing that returns Err on invalid timestamps
- Created 13 diffnote_position_tests covering all extraction paths and error cases
- Created 6 mr_discussion_tests verifying MR reference handling
- All 161 tests passing


Implement MR CLI commands (list, show, count)

## Background
CLI commands for viewing and filtering merge requests. Includes list, show, and count commands with MR-specific filters.

## Approach
Update existing CLI command files:
1. `list.rs` - Add MR listing with filters
2. `show.rs` - Add MR detail view with discussions
3. `count.rs` - Add MR counting with state breakdown

## Files
- `src/cli/commands/list.rs` - Add MR subcommand
- `src/cli/commands/show.rs` - Add MR detail view
- `src/cli/commands/count.rs` - Add MR counting

## Acceptance Criteria
- [ ] `gi list mrs` shows MR table with iid, title, state, author, branches
- [ ] `gi list mrs --state=merged` filters by state
- [ ] `gi list mrs --state=locked` filters locally (not server-side)
- [ ] `gi list mrs --draft` shows only draft MRs
- [ ] `gi list mrs --no-draft` excludes draft MRs
- [ ] `gi list mrs --reviewer=username` filters by reviewer
- [ ] `gi list mrs --target-branch=main` filters by target branch
- [ ] `gi list mrs --source-branch=feature/x` filters by source branch
- [ ] Draft MRs show `[DRAFT]` prefix in title
- [ ] `gi show mr <iid>` displays full detail including discussions
- [ ] DiffNote shows file context: `[src/file.ts:45]`
- [ ] Multi-line DiffNote shows: `[src/file.ts:45-48]`
- [ ] `gi show mr` shows `detailed_merge_status`
- [ ] `gi count mrs` shows total with state breakdown
- [ ] `gi sync-status` shows MR cursor positions
- [ ] `cargo test cli_commands` passes

## TDD Loop
RED: `cargo test list_mrs` -> command not found
GREEN: Add MR subcommand
VERIFY: `gi list mrs --help`

## gi list mrs Output
```
Merge Requests (showing 20 of 1,234)

  !847  Refactor auth to use JWT tokens           merged   @johndoe   main <- feature/jwt   3 days ago
  !846  Fix memory leak in websocket handler      opened   @janedoe   main <- fix/websocket 5 days ago
  !845  [DRAFT] Add dark mode CSS variables       opened   @bobsmith  main <- ui/dark-mode  1 week ago
```

## SQL for MR Listing
```sql
SELECT
    m.iid, m.title, m.state, m.draft, m.author_username,
    m.target_branch, m.source_branch, m.updated_at
FROM merge_requests m
WHERE m.project_id = ?
  AND (? IS NULL OR m.state = ?)           -- state filter
  AND (? IS NULL OR m.draft = ?)           -- draft filter
  AND (? IS NULL OR m.author_username = ?) -- author filter
  AND (? IS NULL OR m.target_branch = ?)   -- target-branch filter
  AND (? IS NULL OR m.source_branch = ?)   -- source-branch filter
  AND (? IS NULL OR EXISTS (               -- reviewer filter
    SELECT 1 FROM mr_reviewers r
    WHERE r.merge_request_id = m.id AND r.username = ?
  ))
ORDER BY m.updated_at DESC
LIMIT ?
```

## gi show mr Output
```
Merge Request !847: Refactor auth to use JWT tokens
================================================================================

Project:        group/project-one
State:          merged
Draft:          No
Author:         @johndoe
Assignees:      @janedoe, @bobsmith
Reviewers:      @alice, @charlie
Source:         feature/jwt
Target:         main
Merge Status:   mergeable
Merged By:      @alice
Merged At:      2024-03-20 14:30:00
Labels:         enhancement, auth, reviewed

Description:
  Moving away from session cookies to JWT-based authentication...

Discussions (8):

  @janedoe (2024-03-16) [src/auth/jwt.ts:45]:
    Should we use a separate signing key for refresh tokens?

    @johndoe (2024-03-16):
      Good point. I'll add a separate key with rotation support.

  @alice (2024-03-18) [RESOLVED]:
    Looks good! Just one nit about the token expiry constant.
```

## DiffNote File Context Display
```rust
// Build file context string
let file_context = match (note.position_new_path, note.position_new_line, note.position_line_range_end) {
    (Some(path), Some(line), Some(end_line)) if line != end_line => {
        format!("[{}:{}-{}]", path, line, end_line)
    }
    (Some(path), Some(line), _) => {
        format!("[{}:{}]", path, line)
    }
    _ => String::new(),
};
```

## gi count mrs Output
```
Merge Requests: 1,234
  opened: 89
  merged: 1,045
  closed: 100
```

## Filter Arguments (clap)
```rust
#[derive(Parser)]
struct ListMrsArgs {
    #[arg(long)]
    state: Option<String>,  // opened|merged|closed|locked|all
    #[arg(long)]
    draft: bool,
    #[arg(long)]
    no_draft: bool,
    #[arg(long)]
    author: Option<String>,
    #[arg(long)]
    assignee: Option<String>,
    #[arg(long)]
    reviewer: Option<String>,
    #[arg(long)]
    target_branch: Option<String>,
    #[arg(long)]
    source_branch: Option<String>,
    #[arg(long)]
    label: Vec<String>,
    #[arg(long)]
    project: Option<String>,
    #[arg(long, default_value = "20")]
    limit: u32,
}
```

## Edge Cases
- `--state=locked` must filter locally (GitLab API doesn't support it)
- Ambiguous MR iid across projects: prompt for `--project`
- Empty discussions: show "No discussions" message
- Multi-line DiffNotes: show line range in context


[CP0] gi version, backup, reset, sync-status commands

## Background

These are the remaining utility commands for CP0. version is trivial. backup creates safety copies before destructive operations. reset provides clean-slate capability. sync-status is a stub for CP0 that will be implemented in CP1.

Reference: docs/prd/checkpoint-0.md sections "gi version", "gi backup", "gi reset", "gi sync-status"

## Approach

**src/cli/commands/version.ts:**
```typescript
import { Command } from 'commander';
import { version } from '../../../package.json' with { type: 'json' };

export const versionCommand = new Command('version')
  .description('Show version information')
  .action(() => {
    console.log(\`gi version \${version}\`);
  });
```

**src/cli/commands/backup.ts:**
```typescript
import { Command } from 'commander';
import { copyFileSync, mkdirSync } from 'node:fs';
import { loadConfig } from '../../core/config';
import { getDbPath, getBackupDir } from '../../core/paths';

export const backupCommand = new Command('backup')
  .description('Create timestamped database backup')
  .action(async (options, command) => {
    const globalOpts = command.optsWithGlobals();
    const config = loadConfig(globalOpts.config);

    const dbPath = getDbPath(config.storage?.dbPath);
    const backupDir = getBackupDir(config.storage?.backupDir);

    mkdirSync(backupDir, { recursive: true });

    // Format: data-2026-01-24T10-30-00.db (colons replaced for Windows compat)
    const timestamp = new Date().toISOString().replace(/:/g, '-').replace(/\\..*/, '');
    const backupPath = \`\${backupDir}/data-\${timestamp}.db\`;

    copyFileSync(dbPath, backupPath);
    console.log(\`Created backup: \${backupPath}\`);
  });
```

**src/cli/commands/reset.ts:**
```typescript
import { Command } from 'commander';
import { unlinkSync, existsSync } from 'node:fs';
import { createInterface } from 'node:readline';
import { loadConfig } from '../../core/config';
import { getDbPath } from '../../core/paths';

export const resetCommand = new Command('reset')
  .description('Delete database and reset all state')
  .option('--confirm', 'Skip confirmation prompt')
  .action(async (options, command) => {
    const globalOpts = command.optsWithGlobals();
    const config = loadConfig(globalOpts.config);
    const dbPath = getDbPath(config.storage?.dbPath);

    if (!existsSync(dbPath)) {
      console.log('No database to reset.');
      return;
    }

    if (!options.confirm) {
      console.log(\`This will delete:\n  - Database: \${dbPath}\n  - All sync cursors\n  - All cached data\n\`);
      // Prompt for 'yes' confirmation
      // If not 'yes', exit 2
    }

    unlinkSync(dbPath);
    // Also delete WAL and SHM files if they exist
    if (existsSync(\`\${dbPath}-wal\`)) unlinkSync(\`\${dbPath}-wal\`);
    if (existsSync(\`\${dbPath}-shm\`)) unlinkSync(\`\${dbPath}-shm\`);

    console.log("Database reset. Run 'gi sync' to repopulate.");
  });
```

**src/cli/commands/sync-status.ts:**
```typescript
// CP0 stub - full implementation in CP1
export const syncStatusCommand = new Command('sync-status')
  .description('Show sync state')
  .action(() => {
    console.log("No sync runs yet. Run 'gi sync' to start.");
  });
```

## Acceptance Criteria

- [ ] `gi version` outputs "gi version X.Y.Z"
- [ ] `gi backup` creates timestamped copy of database
- [ ] Backup filename is Windows-compatible (no colons)
- [ ] Backup directory created if missing
- [ ] `gi reset` prompts for 'yes' confirmation
- [ ] `gi reset --confirm` skips prompt
- [ ] Reset deletes .db, .db-wal, and .db-shm files
- [ ] Reset exits 2 if user doesn't type 'yes'
- [ ] `gi sync-status` outputs stub message

## Files

CREATE:
- src/cli/commands/version.ts
- src/cli/commands/backup.ts
- src/cli/commands/reset.ts
- src/cli/commands/sync-status.ts

## TDD Loop

N/A - simple commands, verify manually:

```bash
gi version
gi backup
ls ~/.local/share/gi/backups/
gi reset  # type 'no'
gi reset --confirm
ls ~/.local/share/gi/data.db  # should not exist
gi sync-status
```

## Edge Cases

- Backup when database doesn't exist - show clear error
- Reset when database doesn't exist - show "No database to reset"
- WAL/SHM files may not exist - check before unlinking
- Timestamp with milliseconds could cause very long filename
- readline prompt in non-interactive terminal - handle SIGINT


Rename GiError to LoreError across codebase

## Background
The codebase currently uses `GiError` as the primary error enum name (legacy from when the project was called "gi"). Checkpoint 3 introduces new modules (documents, search, embedding) that import error types. Renaming before Gate A work begins prevents every subsequent bead from needing to reference the old name and avoids merge conflicts across parallel work streams.

## Approach
Mechanical find-and-replace using `ast-grep` or `sed`:
1. Rename the enum declaration in `src/core/error.rs`: `pub enum GiError` -> `pub enum LoreError`
2. Update the type alias: `pub type Result<T> = std::result::Result<T, LoreError>;`
3. Update re-exports in `src/core/mod.rs` and `src/lib.rs`
4. Update all `use` statements across ~16 files that import `GiError`
5. Update any `GiError::` variant construction sites
6. Run `cargo build` to verify no references remain

**Do NOT change:**
- Error variant names (ConfigNotFound, etc.) — only the enum name
- ErrorCode enum — it's already named correctly
- RobotError — already named correctly

## Acceptance Criteria
- [ ] `cargo build` succeeds with zero warnings about GiError
- [ ] `rg GiError src/` returns zero results
- [ ] `rg LoreError src/core/error.rs` shows the enum declaration
- [ ] `src/core/mod.rs` re-exports `LoreError` (not `GiError`)
- [ ] `src/lib.rs` re-exports `LoreError`
- [ ] All `use crate::core::error::LoreError` imports compile

## Files
- `src/core/error.rs` — enum rename + type alias
- `src/core/mod.rs` — re-export update
- `src/lib.rs` — re-export update
- All files matching `rg 'GiError' src/` (~16 files: ingestion/*.rs, cli/commands/*.rs, gitlab/*.rs, main.rs)

## TDD Loop
RED: `cargo build` fails after renaming enum but before fixing imports
GREEN: Fix all imports; `cargo build` succeeds
VERIFY: `cargo build && rg GiError src/ && echo "FAIL: GiError references remain" || echo "PASS: clean"`

## Edge Cases
- Some files may use `GiError` in string literals (error messages) — do NOT rename those, only type references
- `impl From<X> for GiError` blocks must become `impl From<X> for LoreError`
- The `thiserror` derive macro on the enum does not reference the name, so no macro changes needed

Completed: renamed GiError to LoreError across all 16 files, cargo build + 164 tests pass


Implement TaskSupervisor (dedup + cancellation + generation IDs)

## Background
Background tasks (DB queries, sync, search) are managed by a centralized TaskSupervisor that prevents redundant work, enables cooperative cancellation, and uses generation IDs for stale-result detection. This is the ONLY allowed path for background work — state handlers return ScreenIntent, not Cmd::task directly.

## Approach
Create crates/lore-tui/src/task_supervisor.rs:
- TaskKey enum: LoadScreen(Screen), Search, SyncStream, FilterRequery(Screen) — dedup keys, NOT generation-bearing
- TaskPriority enum: Input(0), Navigation(1), Background(2)
- CancelToken: AtomicBool wrapper with cancel(), is_cancelled()
- TaskHandle struct: key (TaskKey), generation (u64), cancel (Arc<CancelToken>), interrupt (Option<InterruptHandle>)
- TaskSupervisor struct: active (HashMap<TaskKey, TaskHandle>), generation (AtomicU64)
- submit(key: TaskKey) -> TaskHandle: cancels existing task with same key (via CancelToken), increments generation, stores new handle, returns TaskHandle
- is_current(key: &TaskKey, generation: u64) -> bool: checks if generation matches active handle
- complete(key: &TaskKey, generation: u64): removes handle if generation matches
- cancel_all(): cancels all active tasks (used on quit)

## Acceptance Criteria
- [ ] submit() with existing key cancels previous task's CancelToken
- [ ] submit() returns handle with monotonically increasing generation
- [ ] is_current() returns true only for the latest generation
- [ ] complete() removes handle only if generation matches (prevents removing newer task)
- [ ] CancelToken is Arc-wrapped and thread-safe (Send+Sync)
- [ ] TaskHandle includes optional InterruptHandle for SQLite cancellation
- [ ] Generation counter never wraps during reasonable use (AtomicU64)

## Files
- CREATE: crates/lore-tui/src/task_supervisor.rs

## TDD Anchor
RED: Write test_submit_cancels_previous that submits two tasks with same key, asserts first task's CancelToken is cancelled.
GREEN: Implement submit() with cancel-on-supersede logic.
VERIFY: cargo test --manifest-path crates/lore-tui/Cargo.toml test_submit_cancels

Additional tests:
- test_is_current_after_supersede: old generation returns false, new returns true
- test_complete_removes_handle: after complete, key is absent from active map
- test_complete_ignores_stale: completing with old generation doesn't remove newer task
- test_generation_monotonic: submit() always returns increasing generation values

## Edge Cases
- CancelToken uses Relaxed ordering — sufficient for cooperative cancellation polling
- Generation u64 overflow is theoretical but worth noting (would require 2^64 submissions)
- submit() must cancel old task BEFORE storing new handle to prevent race conditions
- InterruptHandle is rusqlite-specific — only set for tasks that lease a reader connection


Implement lore search CLI command (lexical mode)

## Background
The search CLI command is the user-facing entry point for Gate A lexical search. It orchestrates the search pipeline: query parsing -> FTS5 search -> filter application -> result hydration (single round-trip) -> display. Gate B extends this same command with --mode=hybrid and --mode=semantic. The hydration query is critical for performance — it fetches all display fields + labels + paths in one SQL query using json_each() + json_group_array().

## Approach
Create `src/cli/commands/search.rs` per PRD Section 3.4.

**Key types:**
- `SearchResultDisplay` — display-ready result with all fields (dates as ISO via `ms_to_iso`)
- `ExplainData` — ranking explanation for --explain flag (vector_rank, fts_rank, rrf_score)
- `SearchResponse` — wrapper with query, mode, total_results, results, warnings

**Core function:**
```rust
pub fn run_search(
    config: &Config,
    query: &str,
    mode: SearchMode,
    filters: SearchFilters,
    explain: bool,
) -> Result<SearchResponse>
```

**Pipeline:**
1. Parse query + filters
2. Execute search based on mode -> ranked doc_ids (+ explain ranks)
3. Apply post-retrieval filters via apply_filters() preserving ranking order
4. Hydrate results in single DB round-trip using json_each + json_group_array
5. Attach snippets: prefer FTS snippet, fallback to `generate_fallback_snippet()` for semantic-only
6. Convert timestamps via `ms_to_iso()` from `crate::core::time`
7. Build SearchResponse

**Hydration query (critical — single round-trip, replaces 60 queries with 1):**
```sql
SELECT d.id, d.source_type, d.title, d.url, d.author_username,
       d.created_at, d.updated_at, d.content_text,
       p.path_with_namespace AS project_path,
       (SELECT json_group_array(dl.label_name)
        FROM document_labels dl WHERE dl.document_id = d.id) AS labels,
       (SELECT json_group_array(dp.path)
        FROM document_paths dp WHERE dp.document_id = d.id) AS paths
FROM json_each(?) AS j
JOIN documents d ON d.id = j.value
JOIN projects p ON p.id = d.project_id
ORDER BY j.key
```

**Human output uses `console::style` for terminal formatting:**
```rust
use console::style;
// Type prefix in cyan
println!("[{}] {} - {} ({})", i+1, style(type_prefix).cyan(), title, score);
// URL in dim
println!("    {}", style(url).dim());
```

**JSON robot mode includes elapsed_ms in meta (PRD Section 3.4):**
```rust
pub fn print_search_results_json(response: &SearchResponse, elapsed_ms: u64) {
    let output = serde_json::json!({
        "ok": true,
        "data": response,
        "meta": { "elapsed_ms": elapsed_ms }
    });
    println!("{}", serde_json::to_string_pretty(&output).unwrap());
}
```

**CLI args in `src/cli/mod.rs` (PRD Section 3.4):**
```rust
#[derive(Args)]
pub struct SearchArgs {
    query: String,
    #[arg(long, default_value = "hybrid")]
    mode: String,
    #[arg(long, value_name = "TYPE")]
    r#type: Option<String>,
    #[arg(long)]
    author: Option<String>,
    #[arg(long)]
    project: Option<String>,
    #[arg(long, action = clap::ArgAction::Append)]
    label: Vec<String>,
    #[arg(long)]
    path: Option<String>,
    #[arg(long)]
    after: Option<String>,
    #[arg(long)]
    updated_after: Option<String>,
    #[arg(long, default_value = "20")]
    limit: usize,
    #[arg(long)]
    explain: bool,
    #[arg(long, default_value = "safe")]
    fts_mode: String,
}
```

**IMPORTANT: default_value = "hybrid"** — When Ollama is unavailable, hybrid mode gracefully degrades to FTS-only with a warning (not an error). `lore search` works without Ollama.

## Acceptance Criteria
- [ ] Default mode is "hybrid" (not "lexical") per PRD
- [ ] Hybrid mode degrades gracefully to FTS-only when Ollama unavailable (warning, not error)
- [ ] All filters work (type, author, project, label, path, after, updated_after, limit)
- [ ] Label filter uses `clap::ArgAction::Append` for repeatable --label flags
- [ ] Hydration in single query (not N+1) — uses json_each + json_group_array
- [ ] Timestamps converted via `ms_to_iso()` for display (ISO format)
- [ ] Human output uses `console::style` for colored type prefix (cyan) and dim URLs
- [ ] JSON robot mode includes `elapsed_ms` in `meta` field
- [ ] Semantic-only results get fallback snippets via `generate_fallback_snippet()`
- [ ] Empty results show friendly message: "No results found for 'query'"
- [ ] "No data indexed" message if documents table empty
- [ ] --explain shows vector_rank, fts_rank, rrf_score per result
- [ ] --fts-mode=safe preserves prefix `*` while escaping special chars
- [ ] --fts-mode=raw passes FTS5 MATCH syntax through unchanged
- [ ] --mode=semantic with 0% embedding coverage returns LoreError::EmbeddingsNotBuilt (not OllamaUnavailable)
- [ ] SearchArgs registered in cli/mod.rs with Clap derive
- [ ] `cargo build` succeeds

## Files
- `src/cli/commands/search.rs` — new file
- `src/cli/commands/mod.rs` — add `pub mod search;`
- `src/cli/mod.rs` — add SearchArgs struct, wire up search subcommand
- `src/main.rs` — add search command handler

## TDD Loop
RED: Integration test requiring DB with documents
- `test_lexical_search_returns_results` — FTS search returns hits
- `test_hydration_single_query` — verify no N+1 (mock/inspect query count)
- `test_json_output_includes_elapsed` — robot mode JSON has meta.elapsed_ms
- `test_empty_results_message` — zero results shows friendly message
- `test_fallback_snippet` — semantic-only result uses truncated content
GREEN: Implement run_search + hydrate_results + print functions
VERIFY: `cargo build && cargo test search`

## Edge Cases
- Zero results: display friendly empty message, JSON returns empty array
- --mode=semantic with 0% embedding coverage: return LoreError::EmbeddingsNotBuilt
- json_group_array returns "[]" for documents with no labels — parse as empty array
- Very long snippets: truncated at display time
- Hybrid default works without Ollama: degrades to FTS-only with warning
- ms_to_iso with epoch 0: return valid ISO string (not crash)

Implemented search CLI with FTS5 + RRF ranking, single-query hydration (json_each + json_group_array), adaptive recall, all filters, --explain, human + JSON output. Builds clean.


WHO: Robot JSON output for all 5 modes

## Background

Robot-mode JSON output following the standard lore envelope: `{"ok":true,"data":{...},"meta":{"elapsed_ms":N}}`. Includes both raw CLI args (input) and computed values (resolved_input) for agent reproducibility.

## Approach

### Envelope structs:
```rust
#[derive(Serialize)]
struct WhoJsonEnvelope { ok: bool, data: WhoJsonData, meta: RobotMeta }

#[derive(Serialize)]
struct WhoJsonData {
    mode: String,
    input: serde_json::Value,
    resolved_input: serde_json::Value,
    #[serde(flatten)]
    result: serde_json::Value,
}
```

### print_who_json(run, args, elapsed_ms):
- `input`: raw CLI args `{ target, path, project, since, limit }`
- `resolved_input`: `{ mode, project_id, project_path, since_ms, since_iso, since_mode, limit }`
- `result`: mode-specific JSON via *_to_json() functions using serde_json::json\!() macro

### Mode-specific JSON fields:
- **Expert**: path_query, path_match, truncated, experts[] with ISO last_seen_at
- **Workload**: username, 4 entity arrays with ref/project_path/ISO timestamps, summary{} counts, truncation{} per-section bools
- **Reviews**: username, total_diffnotes, categorized_count, mrs_reviewed, categories[] with rounded percentages
- **Active**: total_unresolved_in_window, truncated, discussions[] with discussion_id + participants + participants_total + participants_truncated
- **Overlap**: path_query, path_match, truncated, users[] with role + touch counts + mr_refs + mr_refs_total + mr_refs_truncated

### Key implementation detail — #[serde(flatten)] on result field:
The `result` field uses `#[serde(flatten)]` so mode-specific keys are merged into the top-level data object rather than nested. This means `data.experts` (not `data.result.experts`).

### Timestamps: all use ms_to_iso() for ISO 8601 format in JSON output

### Percentage rounding: Reviews categories use `(percentage * 10.0).round() / 10.0` for single decimal precision

## Files

- `src/cli/commands/who.rs`

## TDD Loop

No unit tests for JSON serialization — the serde_json::json\!() macro produces correct JSON by construction. Verification via manual robot mode invocation.
VERIFY: `cargo check && cargo run --release -- -J who src/features/global-search/ | python3 -m json.tool`

## Acceptance Criteria

- [ ] cargo check passes
- [ ] JSON output validates (valid JSON, no trailing content)
- [ ] input echoes raw CLI args
- [ ] resolved_input includes since_mode tri-state (default/explicit/none)
- [ ] All timestamps in ISO 8601 format
- [ ] Bounded metadata present (participants_total, mr_refs_total, truncation object)
- [ ] #[serde(flatten)] correctly merges result keys into data object

## Edge Cases

- `#[serde(flatten)]` on the result Value means mode-specific keys must not collide with mode/input/resolved_input — verified by convention (expert uses "experts", workload uses "username", etc.)
- serde_json::json\!() panics are impossible for valid Rust expressions, but verify that all row.get() values in *_to_json() handle None fields correctly (author_username in WorkloadMr is Option<String> — json\!() serializes None as null, which is correct)
- ms_to_iso() must handle 0 and very old timestamps gracefully — produces "1970-01-01T00:00:00Z" for epoch 0, which is valid
- Reviews percentage rounding: categories summing to >100% due to rounding is acceptable (display artifact) — agent consumers should not assert sum == 100
- println\!() for JSON output (not eprintln\!) — errors go to stderr, data to stdout, matching all other robot-mode commands
- If a mode returns empty results, the JSON should still be valid (empty arrays, zero counts) — serde handles this correctly

Implemented by agent team: migration 017, CLI skeleton, all 5 query modes, human+robot output, 20 tests. All quality gates pass.


[CP1] gi list issues command

List issues from the database.

Flags:
- --limit=N (default: 20)
- --project=PATH (filter by project)
- --state=opened|closed|all (default: all)

Output: Table with iid, title, state, author, relative time

Files: src/cli/commands/list.ts
Done when: List displays issues with proper filtering and formatting


[CP1] gi list issues command

## Background

The `gi list issues` command displays a paginated list of issues from the local database. It supports filtering by project and state, with configurable limit. This provides quick access to synced issues without opening GitLab.

## Approach

### Module: src/cli/commands/list.rs

### Clap Definition

```rust
#[derive(Args)]
pub struct ListArgs {
    /// Entity type to list
    #[arg(value_parser = ["issues", "mrs"])]
    pub entity: String,

    /// Maximum results
    #[arg(long, default_value = "20")]
    pub limit: usize,

    /// Filter by project path
    #[arg(long)]
    pub project: Option<String>,

    /// Filter by state
    #[arg(long, value_parser = ["opened", "closed", "all"])]
    pub state: Option<String>,
}
```

### Handler Function

```rust
pub async fn handle_list(args: ListArgs, conn: &Connection) -> Result<()>
```

### Query (for issues)

```sql
SELECT i.iid, i.title, i.state, i.author_username, i.updated_at, p.path
FROM issues i
JOIN projects p ON i.project_id = p.id
WHERE (p.path = ? OR ? IS NULL)
  AND (i.state = ? OR ? IS NULL OR ? = 'all')
ORDER BY i.updated_at DESC
LIMIT ?
```

### Output Format (matches PRD)

```
Issues (showing 20 of 3,801)

  #1234  Authentication redesign                       opened   @johndoe   3 days ago
  #1233  Fix memory leak in cache                      closed   @janedoe   5 days ago
  #1232  Add dark mode support                         opened   @bobsmith  1 week ago
  ...
```

### Column Layout

| Column | Width | Alignment |
|--------|-------|-----------|
| IID | 6 | right |
| Title | 45 | left (truncate) |
| State | 8 | left |
| Author | 12 | left |
| Updated | 12 | right (relative) |

### Relative Time Formatting

```rust
fn format_relative_time(ms_epoch: i64) -> String {
    let now = now_ms();
    let diff = now - ms_epoch;
    match diff {
        d if d < 60_000 => "just now".to_string(),
        d if d < 3_600_000 => format!("{} min ago", d / 60_000),
        d if d < 86_400_000 => format!("{} hours ago", d / 3_600_000),
        d if d < 604_800_000 => format!("{} days ago", d / 86_400_000),
        d if d < 2_592_000_000 => format!("{} weeks ago", d / 604_800_000),
        _ => format!("{} months ago", diff / 2_592_000_000),
    }
}
```

## Acceptance Criteria

- [ ] Lists issues ordered by updated_at DESC
- [ ] Shows "showing X of Y" with total count
- [ ] Respects --limit parameter
- [ ] --project filters to single project
- [ ] --state filters to opened/closed/all
- [ ] Title truncated if longer than column width
- [ ] Updated time shown as relative ("3 days ago")

## Files

- src/cli/commands/mod.rs (add `pub mod list;`)
- src/cli/commands/list.rs (create)
- src/cli/mod.rs (add List variant to Commands enum)

## TDD Loop

RED:
```rust
#[tokio::test] async fn list_issues_shows_correct_columns()
#[tokio::test] async fn list_issues_respects_limit()
#[tokio::test] async fn list_issues_filters_by_project()
#[tokio::test] async fn list_issues_filters_by_state()
```

GREEN: Implement handler with query and formatting

VERIFY: `cargo test list_issues`

## Edge Cases

- No issues match filters - show "No issues found"
- Title exactly 45 chars - no truncation
- Title 46+ chars - truncate with "..."
- --state=all shows both opened and closed
- Default state filter is all (not just opened)


[CP1] Issue transformer with label extraction

## Background

The issue transformer converts GitLab API responses into our local schema format. It extracts core fields and, critically, the array of label names from each issue. This transformer is pure logic with no I/O, making it easy to test.

## Approach

Create a transformer module with a function that:
1. Takes a `GitLabIssue` and returns an `IssueRow` struct
2. Extracts the `labels: Vec<String>` directly from the issue (GitLab returns label names as strings)

### Structs

```rust
// src/gitlab/transformers/issue.rs

pub struct IssueRow {
    pub gitlab_id: i64,
    pub iid: i64,
    pub project_id: i64,
    pub title: String,
    pub description: Option<String>,
    pub state: String,
    pub author_username: String,
    pub created_at: i64,      // ms epoch UTC
    pub updated_at: i64,      // ms epoch UTC
    pub web_url: String,
}

pub struct IssueWithLabels {
    pub issue: IssueRow,
    pub label_names: Vec<String>,
}
```

### Function

```rust
pub fn transform_issue(issue: GitLabIssue) -> Result<IssueWithLabels, TransformError> {
    // Parse ISO 8601 timestamps to ms epoch
    // Extract author.username
    // Return IssueWithLabels with label_names from issue.labels
}
```

## Acceptance Criteria

- [ ] `IssueRow` struct exists with all fields from schema
- [ ] `IssueWithLabels` struct bundles issue + label names
- [ ] `transform_issue` parses ISO 8601 to ms epoch correctly
- [ ] `transform_issue` handles missing description (None)
- [ ] Label names are preserved exactly as received from GitLab
- [ ] Unit tests cover all edge cases

## Files

- src/gitlab/transformers/mod.rs (create, add `pub mod issue;`)
- src/gitlab/transformers/issue.rs (create)

## TDD Loop

RED:
```rust
// tests/unit/issue_transformer_test.rs
#[test] fn transforms_issue_with_all_fields()
#[test] fn handles_missing_description()
#[test] fn extracts_label_names()
#[test] fn parses_timestamps_to_ms_epoch()
```

GREEN: Implement transform_issue function

VERIFY: `cargo test issue_transformer`

## Edge Cases

- GitLab timestamps are ISO 8601 with timezone - use chrono::DateTime::parse_from_rfc3339
- Description can be null in GitLab API - map to Option<String>
- Empty labels array is valid - return empty Vec
- Do NOT parse labels_details - it varies across GitLab versions

Implemented IssueRow, IssueWithLabels, transform_issue with 6 passing unit tests covering all edge cases


[CP0] Database setup with migrations and app lock

## Background

The database is the backbone of gitlab-inbox. SQLite with WAL mode for performance, foreign keys for integrity, and proper pragmas for reliability. Migrations allow schema evolution. App lock prevents concurrent sync corruption.

Reference: docs/prd/checkpoint-0.md sections "Database Schema", "SQLite Runtime Pragmas", "App Lock Mechanism"

## Approach

**src/core/db.ts:**
```typescript
import Database from 'better-sqlite3';
import { join, dirname } from 'node:path';
import { mkdirSync, readdirSync, readFileSync } from 'node:fs';
import { getDbPath } from './paths';
import { dbLogger } from './logger';

export function createConnection(dbPath: string): Database.Database {
  mkdirSync(dirname(dbPath), { recursive: true });
  const db = new Database(dbPath);

  // Production-grade pragmas
  db.pragma('journal_mode = WAL');
  db.pragma('synchronous = NORMAL');
  db.pragma('foreign_keys = ON');
  db.pragma('busy_timeout = 5000');
  db.pragma('temp_store = MEMORY');

  return db;
}

export function runMigrations(db: Database.Database, migrationsDir: string): void {
  // Create schema_version table if not exists
  // Read migration files sorted by version
  // Apply migrations not yet applied
  // Track in schema_version table
}
```

**migrations/001_initial.sql:**
Full schema with tables: schema_version, projects, sync_runs, app_locks, sync_cursors, raw_payloads

**src/core/lock.ts:**
AppLock class with:
- acquire(force?): acquires lock or throws DatabaseLockError
- release(): releases lock and stops heartbeat
- Heartbeat timer that updates heartbeat_at every N seconds
- Stale lock detection (heartbeat_at > staleLockMinutes ago)

## Acceptance Criteria

- [ ] createConnection() creates parent directories if missing
- [ ] WAL mode verified: `db.pragma('journal_mode')` returns 'wal'
- [ ] Foreign keys verified: `db.pragma('foreign_keys')` returns 1
- [ ] busy_timeout verified: `db.pragma('busy_timeout')` returns 5000
- [ ] 001_initial.sql creates all 6 tables
- [ ] schema_version shows version 1 after migration
- [ ] AppLock.acquire() succeeds for first caller
- [ ] AppLock.acquire() throws DatabaseLockError for second concurrent caller
- [ ] Stale lock (heartbeat > 10 min old) can be taken over
- [ ] tests/unit/db.test.ts passes (8 tests)
- [ ] tests/integration/app-lock.test.ts passes (6 tests)

## Files

CREATE:
- src/core/db.ts
- src/core/lock.ts
- migrations/001_initial.sql
- tests/unit/db.test.ts
- tests/integration/app-lock.test.ts

## TDD Loop

RED:
```typescript
// tests/unit/db.test.ts
describe('Database', () => {
  it('creates database file if not exists')
  it('applies migrations in order')
  it('sets WAL journal mode')
  it('enables foreign keys')
  it('sets busy_timeout=5000')
  it('sets synchronous=NORMAL')
  it('sets temp_store=MEMORY')
  it('tracks schema version')
})

// tests/integration/app-lock.test.ts
describe('App Lock', () => {
  it('acquires lock successfully')
  it('updates heartbeat during operation')
  it('detects stale lock and recovers')
  it('refuses concurrent acquisition')
  it('allows force override')
  it('releases lock on completion')
})
```

GREEN: Implement db.ts, lock.ts, 001_initial.sql

VERIFY:
```bash
npm run test -- tests/unit/db.test.ts
npm run test -- tests/integration/app-lock.test.ts
```

## Edge Cases

- Migration file with syntax error should rollback and throw MigrationError
- Lock heartbeat timer must be unref()'d to not block process exit
- Database file permissions - fail clearly if not writable
- Concurrent lock tests need separate database files


NOTE-2E: Generate-docs full rebuild support for notes

## Background
lore generate-docs --full seeds all issues, MRs, and discussions into the dirty queue. Notes must be seeded too.

## Approach
Find the function that seeds dirty_sources for --full mode. Add:
INSERT INTO dirty_sources (source_type, source_id, queued_at)
SELECT 'note', n.id, ?1 FROM notes n WHERE n.is_system = 0
ON CONFLICT(source_type, source_id) DO UPDATE SET queued_at = excluded.queued_at, attempt_count = 0, last_attempt_at = NULL, last_error = NULL, next_attempt_at = NULL

## Files
- MODIFY: wherever generate-docs --full seeds the dirty queue

## TDD Anchor
RED: test_full_seed_includes_notes — setup 3 non-system + 1 system note, seed, assert 3 dirty entries.
Tests: test_note_document_count_stable_after_second_generate_docs_full

## Acceptance Criteria
- [ ] generate-docs --full seeds non-system notes into dirty queue
- [ ] System notes excluded from seeding
- [ ] Second full rebuild is idempotent (same document count)
- [ ] Both tests pass

## Dependency Context
- Depends on NOTE-2D: regenerator must handle SourceType::Note


OBSERV Epic: Phase 5 - Rate Limit + Retry Instrumentation

Enhanced logging in GitLab HTTP client for rate limits and retries. Structured fields on retry/rate-limit events. StageTiming gets rate_limit_hits and retries counters.

Depends on: Phase 2 (spans for context)
Parallel with: Phase 3

Files: src/gitlab/client.rs, src/core/metrics.rs

Acceptance criteria (PRD Section 6.5):
- 429 events log at INFO with path, attempt, retry_after_secs, status_code
- Retry events log with path, attempt, error
- StageTiming includes rate_limit_hits and retries (omitted when zero)
- lore -v sync shows retry activity on stderr
- Rate limit counts included in metrics_json

All Phase 5 tasks complete: structured rate-limit logging (bd-12ae) and rate_limit_hits/retries counters in StageTiming (bd-3vqk)


Add required TUI indexes via migration

## Background
The TUI requires covering indexes for keyset pagination and efficient entity lookups. These must be added via the migration system in the main lore crate before TUI GA. Without them, list screens will full-scan on M-tier datasets.

## Approach
Add a new migration to src/core/db.rs MIGRATIONS array:
- idx_issues_list_default ON issues(project_id, state, updated_at DESC, iid DESC)
- idx_mrs_list_default ON merge_requests(project_id, state, updated_at DESC, iid DESC)
- idx_discussions_entity ON discussions(project_id, entity_type, entity_iid, created_at DESC)
- idx_notes_discussion ON notes(discussion_id, created_at ASC)
- Filter-path indexes: issues(author_id, state), issues(assignee_id, state), merge_requests(author_id, state), merge_requests(reviewer_id, state), merge_requests(target_branch, state)

Add EXPLAIN QUERY PLAN CI test that verifies index usage for top 10 TUI queries.

## Acceptance Criteria
- [ ] Migration adds all 9+ indexes
- [ ] Existing data is not affected (indexes are additive)
- [ ] EXPLAIN QUERY PLAN shows index usage for issue list default query
- [ ] EXPLAIN QUERY PLAN shows index usage for MR list default query
- [ ] EXPLAIN QUERY PLAN shows index usage for discussion list query
- [ ] No full table scan on primary entity tables under default filters
- [ ] Migration passes on empty DB and on DB with existing data

## Files
- MODIFY: src/core/db.rs (add migration to MIGRATIONS array, increment LATEST_SCHEMA_VERSION)
- CREATE: tests/tui_index_verification.rs (EXPLAIN QUERY PLAN tests)

## TDD Anchor
RED: Write test_tui_indexes_exist that runs migrations, queries sqlite_master for each expected index name, asserts all present.
GREEN: Add migration with CREATE INDEX IF NOT EXISTS statements.
VERIFY: cargo test test_tui_indexes

## Edge Cases
- CREATE INDEX IF NOT EXISTS: safe for re-runs
- Indexes on large tables may take significant time during first migration — add progress logging
- Migration version must be bumped correctly (LATEST_SCHEMA_VERSION = MIGRATIONS.len() as i32)

## Dependency Context
This modifies the main lore crate, not lore-tui.
Required by all TUI list screens for performance SLOs.


Epic: TUI Phase 2.5 — Vertical Slice Gate

## Background
Phase 2.5 validates that the core screens work together end-to-end: Dashboard -> Issue List -> Issue Detail -> Sync flows correctly, performance SLOs are met, and there are no stuck-input bugs or cancel latency issues. This is a quality gate before investing in power features.

## Acceptance Criteria
- [ ] Dashboard + IssueList + IssueDetail + Sync screens integrated and navigable
- [ ] p95 nav latency < 75ms on M-tier fixtures
- [ ] Zero stuck-input-mode bugs across full flow
- [ ] Cancel latency p95 < 2s
- [ ] Bootstrap screen handles empty/incompatible databases gracefully


OBSERV Epic: Phase 4 - Sync History Enrichment

Wire up sync_runs INSERT/UPDATE lifecycle (table exists but nothing writes to it), schema migration 014, enhanced sync-status with recent runs and metrics.

Depends on: Phase 3 (needs Vec<StageTiming> to store in metrics_json)
Unblocks: nothing (terminal phase)

Files: migrations/014_sync_runs_enrichment.sql (new), src/core/sync_run.rs (new), src/cli/commands/sync.rs, src/cli/commands/ingest.rs, src/cli/commands/sync_status.rs

Acceptance criteria (PRD Section 6.4):
- lore sync creates sync_runs row with status=running, updated to succeeded/failed
- sync_runs.run_id matches log files and robot JSON
- metrics_json contains serialized Vec<StageTiming>
- lore sync-status shows last 10 runs with metrics
- Failed syncs record error and partial metrics
- Migration 014 applies cleanly

Phase 4 complete: migration 014, SyncRunRecorder, wiring, sync-status enhancement


Implement search filters module

## Background
Search filters are applied post-retrieval to narrow results by source type, author, project, date, labels, and file paths. The filter module must preserve ranking order from the search pipeline (FTS/RRF scores). It uses SQLite's JSON1 extension (json_each) to pass ranked document IDs efficiently and maintain their original order.

## Approach
Create `src/search/filters.rs` per PRD Section 3.3. The full implementation is specified in the PRD including the SQL query.

**Key types:**
- `SearchFilters` struct with all filter fields + `has_any_filter()` + `clamp_limit()`
- `PathFilter` enum: `Prefix(String)` (trailing `/`) or `Exact(String)`

**Core function:**
```rust
pub fn apply_filters(
    conn: &Connection,
    document_ids: &[i64],
    filters: &SearchFilters,
) -> Result<Vec<i64>>
```

**SQL pattern (JSON1 for ordered ID passing):**
```sql
SELECT d.id
FROM json_each(?) AS j
JOIN documents d ON d.id = j.value
WHERE 1=1
  AND d.source_type = ?      -- if source_type filter set
  AND d.author_username = ?  -- if author filter set
  -- ... dynamic WHERE clauses
ORDER BY j.key               -- preserves ranking order
LIMIT ?
```

**Filter logic:**
- Labels: AND logic via `EXISTS (SELECT 1 FROM document_labels dl WHERE dl.document_id = d.id AND dl.label_name = ?)`
- Path prefix: `LIKE ? ESCAPE '\\'` with escaped wildcards
- Path exact: `= ?`
- Limit: clamped to [1, 100], default 20

## Acceptance Criteria
- [ ] source_type filter works (issue, merge_request, discussion)
- [ ] author filter: exact username match
- [ ] project_id filter: restricts to single project
- [ ] after filter: created_at >= value
- [ ] updated_after filter: updated_at >= value
- [ ] labels filter: AND logic (all specified labels must be present)
- [ ] path exact filter: matches exact path string
- [ ] path prefix filter: trailing `/` triggers LIKE with escaped wildcards
- [ ] Ranking order preserved (ORDER BY j.key from json_each)
- [ ] Limit clamped: 0 -> 20 (default), 200 -> 100 (max)
- [ ] Empty document_ids returns empty Vec
- [ ] Multiple filters compose correctly (all applied via AND)
- [ ] `cargo test filters` passes

## Files
- `src/search/filters.rs` — new file
- `src/search/mod.rs` — add `pub use filters::{SearchFilters, PathFilter, apply_filters};`

## TDD Loop
RED: Tests in `filters.rs` `#[cfg(test)] mod tests`:
- `test_no_filters` — all docs returned up to limit
- `test_source_type_filter` — only issues returned
- `test_author_filter` — exact match
- `test_labels_and_logic` — must have ALL specified labels
- `test_path_exact` — matches exact path
- `test_path_prefix` — trailing slash matches prefix
- `test_limit_clamping` — 0 -> 20, 200 -> 100
- `test_ranking_preserved` — output order matches input order
- `test_has_any_filter` — true when any filter set, false when default
GREEN: Implement apply_filters with dynamic SQL
VERIFY: `cargo test filters`

## Edge Cases
- Path containing SQL LIKE wildcards (`%`, `_`): must be escaped before LIKE
- Empty labels list: no label filter applied (not "must have zero labels")
- `has_any_filter()` returns false for default SearchFilters (no filters set)
- Large document_ids array (1000+): JSON1 handles efficiently

Completed: SearchFilters with has_any_filter/clamp_limit, PathFilter enum, apply_filters with dynamic SQL + json_each ordering, escape_like, 8 tests pass


[CP1] Final validation - tests, smoke tests, integrity checks

Run all tests and perform data integrity checks.

Validation steps:
1. Run all unit tests (vitest)
2. Run all integration tests
3. Run ESLint
4. Run TypeScript strict check
5. Manual smoke tests per PRD table
6. Data integrity SQL checks:
   - Issue count matches GitLab
   - Every issue has raw_payload
   - Labels in junction exist in labels table
   - sync_cursors has entry per project
   - Re-run fetches 0 new items
   - Discussion count > 0
   - Every discussion has >= 1 note
   - individual_note=true has exactly 1 note

Files: All CP1 files
Done when: All gate criteria from Definition of Done pass


Rewrite who --path to use mr_file_changes for authorship signal

## Problem

who --path currently only queries DiffNote records (notes.position_new_path), so it only finds people who left inline review comments on that exact file. This is highly misleading -- it reports 'no experts' for files that have been actively authored and reviewed, just without inline comments on that specific path.

## Solution

Rewrite query_expert() to incorporate mr_file_changes as a primary signal source:

1. MR authorship signal: JOIN mr_file_changes to find MR authors who touched the file (strongest signal)
2. MR reviewer signal: JOIN mr_file_changes + merge_request_reviewers to find reviewers of MRs that touched the file (even without DiffNotes on that file)
3. DiffNote signal: Keep existing DiffNote query as a supplementary signal (inline comments show deep familiarity)

### Scoring weights (to tune):
- MR author who touched the file: 15 points per MR
- MR reviewer of MR touching the file: 10 points per MR
- DiffNote reviewer on that file: 20 points per MR + 1 per note (existing)
- DiffNote MR author: 12 points per MR (existing)

### Path matching:
- Reuse build_path_query() but extend DB probes to also check mr_file_changes.new_path
- For prefix matching, LIKE on mr_file_changes.new_path

### Also fix:
- build_path_query() probes should check mr_file_changes in addition to notes, so path resolution works even when no DiffNotes exist

## Acceptance Criteria
- who --path returns results for files touched in MRs even without DiffNotes
- Existing DiffNote-based scoring still contributes
- build_path_query probes mr_file_changes for path existence
- Tests cover: MR-only authorship, DiffNote-only, combined scoring
- Robot mode JSON output unchanged (same schema)

Rewrote query_expert() and query_overlap() in who.rs to incorporate mr_file_changes + mr_reviewers as signal sources alongside existing DiffNote data. Uses 4-branch UNION ALL with COUNT(DISTINCT CASE) for proper deduplication across signal types. 8 new tests, all 397 pass.


Implement lore generate-docs CLI command

## Background
The generate-docs CLI command is the user-facing wrapper around the document regeneration pipeline. It has two modes: incremental (default, processes dirty_sources queue only) and full (seeds dirty_sources with ALL entities, then drains). Both modes use the same regenerator codepath to avoid logic divergence. Full mode uses keyset pagination (WHERE id > last_id) for seeding to avoid O(n^2) OFFSET degradation on large tables.

## Approach
Create `src/cli/commands/generate_docs.rs` per PRD Section 2.4.

**Core function:**
```rust
pub fn run_generate_docs(
    config: &Config,
    full: bool,
    project_filter: Option<&str>,
) -> Result<GenerateDocsResult>
```

**Full mode seeding (keyset pagination):**
```rust
const FULL_MODE_CHUNK_SIZE: usize = 2000;

// For each source type (issues, MRs, discussions):
let mut last_id: i64 = 0;
loop {
    let tx = conn.transaction()?;
    let inserted = tx.execute(
        "INSERT INTO dirty_sources (source_type, source_id, queued_at, ...)
         SELECT 'issue', id, ?, 0, NULL, NULL, NULL
         FROM issues WHERE id > ? ORDER BY id LIMIT ?
         ON CONFLICT(source_type, source_id) DO NOTHING",
        params![now_ms(), last_id, FULL_MODE_CHUNK_SIZE],
    )?;
    if inserted == 0 { tx.commit()?; break; }
    // Advance keyset cursor...
    tx.commit()?;
}
```

**After draining (full mode only):**
```sql
INSERT INTO documents_fts(documents_fts) VALUES('optimize')
```

**CLI args:**
```rust
#[derive(Args)]
pub struct GenerateDocsArgs {
    #[arg(long)]
    full: bool,
    #[arg(long)]
    project: Option<String>,
}
```

**Output:** Human-readable table + JSON robot mode.

## Acceptance Criteria
- [ ] Default mode (no --full): processes only existing dirty_sources entries
- [ ] --full mode: seeds dirty_sources with ALL issues, MRs, and discussions
- [ ] Full mode uses keyset pagination (WHERE id > last_id, not OFFSET)
- [ ] Full mode chunk size is 2000
- [ ] Full mode does FTS optimize after completion
- [ ] Both modes use regenerate_dirty_documents() (same codepath)
- [ ] Progress bar shown in human mode (via indicatif)
- [ ] JSON output in robot mode with GenerateDocsResult
- [ ] GenerateDocsResult has issues/mrs/discussions/total/truncated/skipped counts
- [ ] `cargo build` succeeds

## Files
- `src/cli/commands/generate_docs.rs` — new file
- `src/cli/commands/mod.rs` — add `pub mod generate_docs;`
- `src/cli/mod.rs` — add GenerateDocsArgs, wire up generate-docs subcommand
- `src/main.rs` — add generate-docs command handler

## TDD Loop
RED: Integration test with seeded DB
GREEN: Implement run_generate_docs with seeding + drain
VERIFY: `cargo build && cargo test generate_docs`

## Edge Cases
- Empty database (no issues/MRs/discussions): full mode seeds nothing, returns all-zero counts
- --project filter in full mode: only seed dirty_sources for entities in that project
- Interrupted full mode: dirty_sources entries persist (ON CONFLICT DO NOTHING), resume by re-running
- FTS optimize on empty FTS table: no-op (safe)

Implemented generate-docs command with incremental + full mode, keyset pagination seeding, FTS optimize, project filter, human + JSON output. Builds clean.