@gi4nks/ph 1.5.0 → 1.7.0

package/docs/specs/SPEC-007-memory-summaries.md

@@ -0,0 +1,96 @@
+# SPEC-007: Memory & Project Summaries
+
+- **ID**: SPEC-007
+- **Cluster**: Memory
+- **Status**: Implemented (baseline)
+- **Date**: 2026-08-08
+- **Source**: reverse-engineered from code (files listed in §8)
+
+## 1. Purpose
+Project-level knowledge derived from analysis: an append-only `memories` table
+(full timeline per project) PLUS a single curated `project_summaries` row per
+project (merged, deduped by insight/decision content). This is the "curated
+knowledge base" core of the evolution plan (docs/superpowers/specs/
+2026-06-12-ph-evolution-design.md).
+
+## 2. Scope
+- **In scope**: memories CRUD, upsertProjectMemory (append-only),
+  upsertProjectSummary (merge/dedup), getProjectSummary, memory-migrate, access
+  tracking.
+- **Out of scope**: LLM analysis itself (SPEC-006), MCP exposure (SPEC-011),
+  context output (SPEC-014).
+- **Entry points**: analysis pipeline, `ph memory-migrate`, `ph context`,
+  `ph timeline`, MCP tools, `save_decision`.
+
+## 3. Data Model
+- `memories` (src/db/index.ts:106-121): id, project, prompt_ids, summary,
+  key_insights, technical_decisions, git_context_snapshot, created_at,
+  updated_at, access_count, last_accessed.
+- `project_summaries` (PhDB.PROJECT_SUMMARIES_SCHEMA, :123): project (PK),
+  summary, key_insights, technical_decisions, prompt_count, first_analyzed,
+  last_analyzed, git_context_snapshot.
+- `MemoryEntry` / `ProjectSummary` (src/types.ts:29-52).
+
+## 4. Flows
+
+### 4.1 Append-only memory (src/db/index.ts:535-640)
+`upsertProjectMemory({project, prompt_id, summary, key_insights,
+technical_decisions, git_context_snapshot})` INSERTS a new row per analysis —
+full timeline preserved. `searchMemories(project, limit)` returns latest N;
+`getAllMemoriesByProject` (774) ascending for timelines.
+
+### 4.2 Curated summary (src/db/index.ts:643-699)
+`upsertProjectSummary(params)` upserts ONE row per project: merges new insights/
+decisions into existing arrays, deduping by content; updates prompt_count,
+first/last_analyzed. `getProjectSummary(project)` (690).
+
+### 4.3 Migrate (src/commands/memory-migrate.ts)
+`ph memory-migrate` backfills `project_summaries` from existing memories
+(83 projects migrated per AGENTS.md).
+
+### 4.4 Access tracking (src/db/index.ts:701)
+`recordMemoryAccess(id)` bumps access_count + last_accessed (used by MCP reads).
+
+## 5. Invariants & Business rules
+- memories = append-only timeline; project_summaries = 1 row per project.
+- Summary merge dedups by insight/decision CONTENT (not id).
+- `save_decision` writes to summaries too (MCP, SPEC-011).
+- Access stats are write-on-read (recordMemoryAccess on MCP/timeline reads).
+
+## 6. UI / UX surface
+PreviewPane memory tab (SPEC-012); `ph context` markdown output; `ph timeline`.
+
+## 7. Acceptance criteria (Given/When/Then)
+- **G1**: Given two analyses for the same project, When `upsertProjectMemory`
+  runs twice, Then `memories` contains 2 rows (append-only)
+  (src/db/index.ts:612-628).
+- **G2**: Given two summaries with the same insight, When `upsertProjectSummary`
+  runs twice, Then the insight appears once in key_insights and there is 1 row
+  (src/db/index.ts:643-690).
+- **G3**: Given `upsertProjectSummary` with prompt_count 3, When the row is
+  read, Then prompt_count is 3 and first/last_analyzed are set
+  (src/db/index.ts:643-690).
+- **G4**: Given `recordMemoryAccess(id)`, When run, Then access_count
+  increments and last_accessed updates (src/db/index.ts:701-706).
+- **G5**: Given `ph memory-migrate` on a DB with memories but no summaries,
+  When run, Then project_summaries rows are backfilled
+  (src/commands/memory-migrate.ts).
+
+## 8. Key implementation map
+| Concern | File(s) |
+|---|---|
+| Memories CRUD + upsert | src/db/index.ts:535-640 |
+| Summary upsert/merge + read | src/db/index.ts:643-699 |
+| Access tracking | src/db/index.ts:701-706 |
+| Migrate command | src/commands/memory-migrate.ts |
+| Evolution design | docs/superpowers/specs/2026-06-12-ph-evolution-design.md |
+
+## 9. Open questions / discrepancies
+- `memories.prompt_ids` may be load-bearing only for the timeline join; summaries
+  use prompt_count (SPEC-ISSUES-014).
+- Git context snapshots are captured by the analysis pipeline (git-context.ts)
+  but their use beyond storage is undocumented.
+
+## 10. Related
+- SPEC-006 (analysis feeds memories), SPEC-011 (MCP tools), SPEC-014 (context/
+  timeline). No tests (SPEC-ISSUES-007) — G1/G2/G3 are prime vitest targets.

package/docs/specs/SPEC-008-embeddings.md

@@ -0,0 +1,90 @@
+# SPEC-008: Embeddings (sqlite-vec)
+
+- **ID**: SPEC-008
+- **Cluster**: AI
+- **Status**: Implemented (baseline)
+- **Date**: 2026-08-08
+- **Source**: reverse-engineered from code (files listed in §8)
+
+## 1. Purpose
+Semantic search capability: prompt text → vectors (Ollama embed API) → stored
+in a sqlite-vec `vec0` virtual table with 768-dim; `searchSemantic` runs KNN
+against a query vector. Backs `ph search --semantic`, MCP
+`search_prompts_semantic`, HTTP `/api/prompts/semantic`, and cluster/cohesion.
+
+## 2. Scope
+- **In scope**: getEmbeddings (batching), saveEmbedding/getAllEmbeddings,
+  searchSemantic, embed-all command, vec0 migration from legacy BLOB.
+- **Out of scope**: the search UX (SPEC-005), clustering (SPEC-014).
+- **Entry points**: `ph embed-all`, `ph search --semantic`, MCP, HTTP, background analysis.
+
+## 3. Data Model
+- `vec_embeddings` vec0 table: `embedding float[768]` (src/db/index.ts:100-104).
+- Legacy `embeddings (prompt_id, vector BLOB)` (87-91) — migrated on open.
+- Embedding dimension fixed at 768 (matches `nomic-embed-text-v2-moe` default,
+  src/config/index.ts:14).
+
+## 4. Flows
+
+### 4.1 Generation (src/embedding/index.ts:5-34)
+`getEmbeddings(texts, ollamaUrl, model, batchSize=20)` POSTs batches to
+`{ollamaUrl}/api/embed`; throws on non-OK; returns `Float32Array[]`.
+
+### 4.2 Persistence
+`saveEmbedding(id, vector)` (src/db/index.ts:331) writes to vec_embeddings
+(rowid = prompt id); `getAllEmbeddings()` (361) for cluster/cohesion;
+`getPromptsWithoutEmbeddings()` (377) for embed-all.
+
+### 4.3 Search (src/db/index.ts:345-360)
+`searchSemantic(queryVector, limit)` — vec0 KNN: `SELECT … FROM vec_embeddings
+WHERE embedding MATCH ? AND k = ?` joined to prompts.
+
+### 4.4 Migration (src/db/index.ts:148-180)
+If legacy `embeddings` has rows and `vec_embeddings` is empty: copy via
+`vec_f32(?)`; also drops a non-vec0 table named vec_embeddings (95-98).
+
+### 4.5 CLI (src/commands/embed-all.ts)
+`ph embed-all` batches unembedded prompts, generates vectors, saves.
+
+## 5. Invariants & Business rules
+- Dimension is always 768; a mismatched model breaks KNN at runtime.
+- vec_embeddings rowid == prompts.id (identity mapping).
+- Migration runs on every open but is a no-op once done.
+- Embedding failures throw — callers (embed-all, semantic search) surface the
+  error instead of silently degrading.
+
+## 6. UI / UX surface
+`ph search --semantic` requires embeddings; CLI warns/errors when the model is
+unreachable.
+
+## 7. Acceptance criteria (Given/When/Then)
+- **G1**: Given 50 texts with batchSize 20, When `getEmbeddings` runs, Then the
+  Ollama API is called 3 times and 50 vectors are returned
+  (src/embedding/index.ts:13-31).
+- **G2**: Given a prompt with a saved embedding, When `searchSemantic` runs with
+  the same vector, Then the prompt is the top result (src/db/index.ts:345-360).
+- **G3**: Given legacy `embeddings` rows and an empty `vec_embeddings`, When the
+  DB opens, Then the vectors are copied into vec_embeddings
+  (src/db/index.ts:148-180).
+- **G4**: Given `saveEmbedding(id, vec)`, When `getAllEmbeddings` runs, Then the
+  map contains id → vec (src/db/index.ts:331-375).
+- **G5**: Given a non-OK Ollama response, When `getEmbeddings` runs, Then it
+  throws with the HTTP status (src/embedding/index.ts:22-25).
+
+## 8. Key implementation map
+| Concern | File(s) |
+|---|---|
+| Embed API client | src/embedding/index.ts:5-34 |
+| vec0 persistence + KNN | src/db/index.ts:331-360 |
+| Migration | src/db/index.ts:95-104, 148-180 |
+| embed-all | src/commands/embed-all.ts |
+
+## 9. Open questions / discrepancies
+- 768 is hard-coded in the vec0 DDL; a model with a different dim fails at
+  insert time with a vec0 error.
+- `searchSemantic` runs KNN before filtering by project — the server filters in
+  JS afterwards (src/server/index.ts:81-89); large DBs pay KNN cost first.
+
+## 10. Related
+- SPEC-005 (semantic search), SPEC-014 (cluster/cohesion use embeddings),
+  SPEC-010 (HTTP semantic endpoint). No tests (SPEC-ISSUES-007).

package/docs/specs/SPEC-009-retention-archive.md

@@ -0,0 +1,91 @@
+# SPEC-009: Retention & Archive
+
+- **ID**: SPEC-009
+- **Cluster**: DB
+- **Status**: Implemented (baseline)
+- **Date**: 2026-08-08
+- **Source**: reverse-engineered from code (files listed in §8)
+
+## 1. Purpose
+Keeps the DB "shrinking, not growing" (evolution plan): `ph cleanup --retention`
+archives old/unqualified prompts to `prompts_archive` (removing them from the
+live tables) and auto-purges archived entries past 2× retentionDays.
+
+## 2. Scope
+- **In scope**: retention policy (age, starred, analyzed, relevance), archive
+  move (transactional copy+delete incl. embeddings cleanup), archive search,
+  purge, archive stats.
+- **Out of scope**: simple `ph cleanup` (length/score deletion), reusability
+  cleanup (SPEC-006 cross-ref).
+- **Entry points**: `ph cleanup --retention [--dry-run]`, `ph search --archive`,
+  TUI archive count.
+
+## 3. Data Model
+- `prompts_archive` (PhDB.ARCHIVE_SCHEMA, src/db/index.ts:124): full row copy +
+  `archived_at`, `original_id`.
+- Config keys (src/config/index.ts:18-21): retentionDays (90), retentionMinStarred
+  (true), retentionMinAnalyzed (true), retentionMinRelevance (3).
+- Archive stats: total/oldest/newest (src/db/index.ts:511).
+
+## 4. Flows
+
+### 4.1 Selection (src/commands/cleanup.ts:88-133)
+1. cutoff = now − retentionDays.
+2. Priority 1: relevance < threshold AND older than cutoff (cleanup.ts:104-105).
+3. Priority 2: older than cutoff AND not starred AND not analyzed (cleanup.ts:105+).
+4. `--dry-run` lists candidates; otherwise confirm/`--force` then archive.
+
+### 4.2 Archive move (src/db/index.ts:464-493)
+`archivePrompts(ids)` runs a TRANSACTION: copy row → prompts_archive (with
+archived_at/original_id), DELETE from prompts (FTS trigger + embeddings cleanup
+deleteByIds at :439 keep the indexes consistent). Returns moved count.
+
+### 4.3 Purge (src/db/index.ts:506, cleanup.ts:157-162)
+After archiving, entries in prompts_archive older than 2× retentionDays are
+permanently purged.
+
+### 4.4 Archive search (src/db/index.ts:496)
+`searchArchive({since, until, limit})` over prompts_archive; CLI `ph search
+--archive`.
+
+## 5. Invariants & Business rules
+- Archive move is transactional — no partial copies.
+- Starred and analyzed prompts are never archived by default (config flags).
+- Embeddings of archived prompts are deleted (deleteByIds handles vec cleanup).
+- Purge only touches prompts_archive, never live prompts.
+
+## 6. UI / UX surface
+TUI header shows `N prompts (M archived)` (Header.tsx archiveCount prop);
+`ph cleanup --retention` prints policy + per-entry reasons.
+
+## 7. Acceptance criteria (Given/When/Then)
+- **G1**: Given an old, unstarred, unanalyzed prompt, When retention selection
+  runs, Then it is a candidate for archiving (src/commands/cleanup.ts:105+).
+- **G2**: Given `archivePrompts([id])` on an existing prompt, When run, Then the
+  row moves to prompts_archive with archived_at+original_id and disappears from
+  prompts (src/db/index.ts:464-493).
+- **G3**: Given an archived entry older than 2× retentionDays, When
+  `purgeArchive` runs, Then it is deleted (src/db/index.ts:506-510).
+- **G4**: Given `searchArchive({since})`, When run, Then only archived rows in
+  range are returned (src/db/index.ts:496-505).
+- **G5**: Given `getArchiveStats()`, When run, Then total/oldest/newest reflect
+  prompts_archive (src/db/index.ts:511-518).
+
+## 8. Key implementation map
+| Concern | File(s) |
+|---|---|
+| Retention policy + selection | src/commands/cleanup.ts:88-133 |
+| Archive move (transaction) | src/db/index.ts:464-493 |
+| Archive search + purge + stats | src/db/index.ts:496-518 |
+| Config keys | src/config/index.ts:18-21 |
+| TUI archive count | src/ui/Header.tsx, BrowseApp.tsx:793 |
+
+## 9. Open questions / discrepancies
+- "Analyzed" is defined as `meta.summary || meta.role` (cleanup.ts) — verify the
+  exact predicate when wiring tests.
+- `deleteByIds` (439) does the vec cleanup; `archivePrompts` relies on it —
+  archive + vec consistency is only as good as deleteByIds.
+
+## 10. Related
+- SPEC-002 (primitives), SPEC-006 (reusability cleanup), SPEC-012 (TUI count).
+  No tests (SPEC-ISSUES-007) — G2/G3 are prime vitest targets.

package/docs/specs/SPEC-010-remote-sync.md

@@ -0,0 +1,106 @@
+# SPEC-010: Remote Sync (HTTP Server + Push/Pull)
+
+- **ID**: SPEC-010
+- **Cluster**: Sync
+- **Status**: Implemented (baseline)
+- **Date**: 2026-08-08
+- **Source**: reverse-engineered from code (files listed in §8)
+
+## 1. Purpose
+Cross-laptop prompt history sharing: a zero-dependency HTTP server (`ph server`)
+plus `ph remote push|pull|status` with dedup via `sync_hash`
+(sha256(`tool|prompt|response`)) and fire-and-forget background push after
+`ph log`. Offline-first: the local SQLite DB stays the source of truth.
+
+## 2. Scope
+- **In scope**: HTTP endpoints, push/pull/status, dedup, background push,
+  config/env precedence, CORS.
+- **Out of scope**: authentication enforcement (see §9), conflict resolution
+  beyond timestamp+hash, server persistence (uses the same PhDB).
+- **Entry points**: `ph server [--port] [--host]`, `ph remote push|pull|status`,
+  `PH_REMOTE_URL` env, `remoteUrl`/`remoteApiKey`/`remoteLastPush`/`remoteLastPull` config.
+
+## 3. Data Model
+- `sync_hash`: sha256 hex of `${tool}|${prompt}|${response}`, stored in
+  metadata JSON under `$.sync_hash` (src/server/index.ts:104-108).
+- Config: `remoteUrl`, `remoteApiKey`, `remoteLastPush`, `remoteLastPull`
+  (src/config/index.ts:15-18).
+- Env: `PH_REMOTE_URL` (precedence over config, src/commands/remote.ts:6-8).
+
+## 4. Flows
+
+### 4.1 Server (src/server/index.ts:9-164)
+- CORS headers on every response (:15-17); OPTIONS → 204.
+- `/health` → `{ status: 'ok', dbPath }` (:46-48).
+- `POST /api/prompts/search|by-id|semantic` — search delegation (SPEC-005/008).
+- `POST /api/sync/push` (:94-127): per prompt compute hash → skip if
+  `getPromptBySyncHash` finds it → else insert with sync_hash in metadata.
+- `POST /api/sync/pull` (:129-139): prompts since timestamp (or all), capped 10000.
+- `POST /api/memories/search|summary` (:141-154); `GET /api/stats` (:156-161).
+
+### 4.2 Push (src/commands/remote.ts:37-80)
+`push` sends prompts since `remoteLastPush` (≤5000) to `/api/sync/push`;
+on success updates `cfg.remoteLastPush` and saves.
+
+### 4.3 Pull (src/commands/remote.ts:82-146)
+`pull` fetches since `remoteLastPull`; dedups locally via `getPromptBySyncHash`;
+advances `remoteLastPull` to the max timestamp.
+
+### 4.4 Background push (src/commands/log.ts:65-69)
+After each `ph log`, if a remote is configured, `pushToRemote(...).catch(() => {})`
+— fire-and-forget, never blocks or crashes.
+
+### 4.5 Status (src/commands/remote.ts:148+)
+Shows remote URL, local total, last push/pull, pending count
+(`getPromptCountSince(remoteLastPush)`).
+
+## 5. Invariants & Business rules
+- sync_hash is the dedup key on BOTH sides (server skip + client skip).
+- `PH_REMOTE_URL` env wins over config (remote.ts:6-8).
+- Background push swallows errors (`.catch(() => {})`).
+- The server is read/write open — no auth check (SPEC-ISSUES-013).
+
+## 6. UI / UX surface
+CLI progress lines (`Pushing N prompts…`, `Imported: X, Skipped: Y`).
+
+## 7. Acceptance criteria (Given/When/Then)
+- **G1**: Given the same `tool|prompt|response`, When `sha256` runs, Then the
+  same hash is produced both in push and server paths
+  (src/server/index.ts:104, remote.ts:116).
+- **G2**: Given an existing sync_hash in metadata, When `/api/sync/push` receives
+  the entry, Then it is skipped (imported stays 0, skipped 1)
+  (src/server/index.ts:104-106).
+- **G3**: Given `remoteLastPush` set, When `push` runs, Then only prompts newer
+  than the timestamp are sent (src/commands/remote.ts:39-43).
+- **G4**: Given `PH_REMOTE_URL` env and a config remoteUrl, When `remoteUrl()`
+  runs, Then the env value wins (src/commands/remote.ts:6-8).
+- **G5**: Given `remoteLastPush` absent, When `status` runs, Then pending equals
+  the local total (src/commands/remote.ts:151-156).
+- **G6**: Given `POST /api/stats`, When the server handles it, Then
+  total/totalMemories/byTool are returned (src/server/index.ts:156-161).
+
+## 8. Key implementation map
+| Concern | File(s) |
+|---|---|
+| HTTP server + endpoints | src/server/index.ts:9-164 |
+| Push/pull/status | src/commands/remote.ts:37-160 |
+| Background push | src/commands/log.ts:65-85 |
+| Config/env | src/config/index.ts:15-18, remote.ts:6-8 |
+| Dedup primitive | src/db/index.ts:403-407 |
+
+## 9. Open questions / discrepancies
+- ~~sync_hash excludes args/workdir~~ Fixed 2026-08-08: shared `syncHash`
+  helper (src/utils/syncHash.ts) — args included only when present, backward
+  compatible with the legacy `tool|prompt|response` hash.
+- ~~The server NEVER verifies `remoteApiKey`~~ Fixed 2026-08-08: auth gate in
+  `createRequestHandler` (Bearer + timingSafeEqual) on every endpoint except
+  /health when `remoteApiKey` is configured.
+- `remoteLastPush` uses the CLIENT clock; clock skew between laptops breaks
+  incremental sync.
+- No pagination beyond the 10000/5000 caps; a laptop with >5000 unsynced
+  prompts needs repeated pushes.
+
+## 10. Related
+- SPEC-002 (dedup/insert primitives), SPEC-005/008 (search endpoints),
+  SPEC-015 (config). GWT tests target the deterministic parts (hash, dedup,
+  since-window) — no network needed.

package/docs/specs/SPEC-011-mcp-server.md

@@ -0,0 +1,94 @@
+# SPEC-011: MCP Server
+
+- **ID**: SPEC-011
+- **Cluster**: MCP
+- **Status**: Implemented (baseline)
+- **Date**: 2026-08-08
+- **Source**: reverse-engineered from code (files listed in §8)
+
+## 1. Purpose
+Agent-facing interface to ph's knowledge: an MCP stdio server
+(`ph mcp`) exposing prompt history search, project memories/summaries, timelines
+and decision recording. Auto-discovered by MCP clients (Claude Code, OpenCode,
+etc.) — the primary consumer per the evolution plan.
+
+## 2. Scope
+- **In scope**: 11 registered tools, list/call handlers, stdio transport.
+- **Out of scope**: the memory/analysis internals (SPEC-006/007), HTTP server
+  (SPEC-010).
+- **Entry points**: `ph mcp` (stdio); tools auto-listed via ListToolsRequest.
+
+## 3. Data Model
+- MCP `tools` registration (src/mcp/server.ts:30-187):
+  - `list_prompts` (:34)
+  - `save_decision` (:47) — writes to project_summaries
+  - `get_project_diff` (:69)
+  - `search_project_memory` (:82) — keyword + semantic with summary fallback
+  - `get_project_context` (:95)
+  - `get_project_summary` (:107)
+  - `search_prompts` (:118) — FTS
+  - `get_prompt` (:135) — by id
+  - `search_prompts_semantic` (:146)
+  - `get_project_timeline` (:159)
+  - `check_project_knowledge` (:173) — "found" vs "new work"
+- Transport: `McpServer` stdio (src/mcp/server.ts:20).
+
+## 4. Flows
+
+### 4.1 Tool invocation
+1. Client lists tools → `ListToolsRequestSchema` handler returns the 11 tools
+   (src/mcp/server.ts:30-187).
+2. Client calls a tool → `CallToolRequestSchema` handler (src/mcp/server.ts:189)
+   dispatches by name, opens a PhDB per call (or a shared one), returns
+   `{ content: [{ type: 'text', text }] }`.
+3. `check_project_knowledge` (173) is the pre-implementation gate: agents call
+   it before coding a feature; it searches memories + semantic prompt history and
+   recommends "found" (with context) or "new work".
+
+## 5. Invariants & Business rules
+- All tools are read-only EXCEPT `save_decision` (writes summaries).
+- `search_project_memory` falls back to `project_summaries` when semantic search
+  returns nothing (AGENTS.md, Phase 3).
+- Every tool result is a text content block (JSON strings for structured data).
+- The server is stdio-only (no network transport).
+
+## 6. UI / UX surface
+None (protocol). Consumed by agents: `ph mcp` must be registered in the client's
+MCP config.
+
+## 7. Acceptance criteria (Given/When/Then)
+- **G1**: Given a client ListTools request, When the server responds, Then the
+  tool list contains `search_prompts`, `get_prompt`, `search_project_memory`,
+  `get_project_context`, `get_project_summary`, `check_project_knowledge` and
+  `save_decision` (src/mcp/server.ts:30-187).
+- **G2**: Given `get_prompt` with an existing id, When called, Then the prompt
+  text is returned (src/mcp/server.ts:135-145).
+- **G3**: Given `search_prompts` with a query, When called, Then FTS results are
+  returned as text content (src/mcp/server.ts:118-134).
+- **G4**: Given `save_decision` with project/decision, When called, Then the
+  decision is written to project_summaries (src/mcp/server.ts:47-68,
+  SPEC-007).
+- **G5**: Given a project with no knowledge, When `check_project_knowledge` is
+  called, Then the response recommends "new work" (src/mcp/server.ts:173-187).
+
+## 8. Key implementation map
+| Concern | File(s) |
+|---|---|
+| Server + transport | src/mcp/server.ts:1-30 |
+| Tool registry + handlers | src/mcp/server.ts:30-260 |
+| Memory/summary backends | src/db/index.ts:535-699 |
+
+## 9. Open questions / discrepancies
+- Protocol smoke coverage uses the official SDK client with paired in-memory
+  transports and a real temporary `PhDB`; semantic tools still need a separately
+  controlled embedding-provider integration test.
+- A new PhDB is opened per call — connection churn on high-frequency agent use
+  (verify in the handler; a shared instance + close-on-exit would be cheaper).
+- No tool input validation with zod (raw JSON.parse of arguments) — malformed
+  args from a client surface as handler errors.
+- `get_project_diff` reads git state — behavior beyond the name needs
+  verification against git-context.ts.
+
+## 10. Related
+- SPEC-005/007/008 (backends), SPEC-006 (analysis feeding knowledge),
+  evolution plan (MCP as primary interface). No tests (SPEC-ISSUES-007).

package/docs/specs/SPEC-012-tui-browser.md

@@ -0,0 +1,98 @@
+# SPEC-012: TUI Browser
+
+- **ID**: SPEC-012
+- **Cluster**: TUI
+- **Status**: Implemented (baseline)
+- **Date**: 2026-08-08
+- **Source**: reverse-engineered from code (files listed in §8)
+
+## 1. Purpose
+Interactive exploration of the prompt history: list + detail panes, search,
+filter panel, star/edit/rerun/delete, memory tab, settings. Ink + React.
+
+## 2. Scope
+- **In scope**: BrowseApp state machine, ListEntry/PreviewPane/Header/Footer/
+  SearchBar components, keybindings, filter panel, filter policy, themes.
+- **Out of scope**: non-TUI output (src/display/print.ts), command handlers.
+- **Entry points**: `ph` (no args), `ph browse`, `ph search -i`.
+
+## 3. Data Model
+- `Props` (src/ui/BrowseApp.tsx:561-565): db, initialTextFilter, initialFilters,
+  onRerun.
+- State: allEntries, refreshKey, archiveCount, textFilter, activeFilters,
+  showFilterPanel, showSettings, pane/tab state (BrowseApp.tsx:568 onward).
+- `ActiveFilters` — tool/project/language/role/tag/starred/minQuality/
+  minRelevance (populated from `search -i` flags, cli.ts:223-232).
+
+## 4. Flows
+
+### 4.1 Browse loop
+1. `db.search({limit:1000})` seeds the list (BrowseApp.tsx:791).
+2. `/` activates SearchBar → text filter → re-search; `f` opens FilterPanel
+   (flat list with counts, Enter toggle, letter jump).
+3. `Tab` switches pane in wide mode; `1/2/3` switch prompt/response/memory tabs.
+4. `y` copy, `s` star, `e` edit metadata, `x` delete (DB + refresh),
+   `r` rerun (onRerun → cli.ts spawns the tool), `C` chat mode (launch tool with
+   project context), `o` settings.
+5. ListEntry renders role-colored bar, analysis indicator ●/○, star, Q/R badges,
+   summary line (ListEntry.tsx); Header shows counts + archive count
+   (Header.tsx:archiveCount); session separators `╌╌ date ╌╌`.
+
+### 4.2 Filter panel
+Flat scrollable list of all filter options with `[N]` counts; Enter toggles a
+filter; letter jump to category. Pure filtering and option/count generation
+live in `src/ui/filtering.ts`; `FilterPanel.tsx` owns keyboard interaction and
+rendering.
+
+## 5. Invariants & Business rules
+- All mutations go through PhDB and refresh via `refreshKey`.
+- The TUI is launched inside alt-screen (`\x1b[?1049h` … `l`) by cli.ts
+  (SPEC-001) — cleanup in `finally`.
+- Rerun is synchronous spawnSync after the TUI exits (cli.ts:176-181).
+
+## 6. UI / UX surface
+Keybindings (AGENTS.md table): ↑↓/PgUp/PgDn, Tab, 1/2/3, y/s/e/r/x, /, o, f, c,
+q/ESC. Themes in src/ui/themes.ts.
+
+## 7. Acceptance criteria (Given/When/Then)
+- **G1**: Given a DB with entries, When BrowseApp mounts, Then the list shows the
+  entries and Header shows the count (BrowseApp.tsx:791, Header.tsx).
+- **G2**: Given `/` typed and a query, When the search applies, Then the list is
+  filtered via db.search (BrowseApp.tsx SearchBar wiring).
+- **G3**: Given `x` on a selected entry, When pressed, Then the entry is deleted
+  via db.delete and the list refreshes (BrowseApp.tsx delete handler).
+- **G4**: Given `s` on an entry, When pressed, Then `starred` toggles in
+  metadata (BrowseApp.tsx star handler).
+- **G5**: Given an entry with a project, When `C` is pressed, Then chat mode
+  launches with project context injected (BrowseApp chat handler, SPEC-014).
+- **G6**: Given entries and active filters, When `applyFilters` runs, Then only
+  matching metadata and text entries remain (`src/ui/filtering.ts`).
+- **G7**: Given entries with filter metadata, When filter options are built,
+  Then category counts and active state reflect the full entry set
+  (`src/ui/filtering.ts`).
+
+## 8. Key implementation map
+| Concern | File(s) |
+|---|---|
+| Main app + settings | src/ui/BrowseApp.tsx |
+| Filter interaction | src/ui/FilterPanel.tsx |
+| Filter policy and option counts | src/ui/filtering.ts |
+| Entry list / detail | src/ui/ListEntry.tsx, PreviewPane.tsx |
+| Header / footer / search | src/ui/Header.tsx, Footer.tsx, SearchBar.tsx |
+| Themes | src/ui/themes.ts |
+| Alt-screen bootstrap (×3) | src/cli.ts:159-186, 214-248, 373-396 |
+
+## 9. Open questions / discrepancies
+- BrowseApp remains a large module; filter policy now has a tested seam, while
+  detail/edit/rerun/settings interactions remain coupled and need direct UI
+  coverage.
+- `refreshKey` increments trigger full re-search — no pagination past the 1000
+  seed; huge histories truncate silently.
+- React lint issues in BrowseApp/PreviewPane were reported pre-upgrade
+  (AGENTS.md "Known Issues") — status after ink 7 upgrade unverified (lint runs
+  clean now, but the rule set may have changed).
+
+## 10. Related
+- SPEC-001 (bootstrap), SPEC-005 (search backend), SPEC-002 (mutations),
+  SPEC-014 (chat/context). Filter policy/count tests are in
+  `src/ui/__tests__/filtering.test.ts`; full Ink interaction tests remain open.