@gi4nks/ph 1.7.0 → 1.8.0

package/docs/specs/SPEC-005-search.md

@@ -7,7 +7,7 @@
 - **Source**: reverse-engineered from code (files listed in §8)
 
 ## 1. Purpose
-Find prompts by full-text (FTS5 over prompt+response), by metadata filters
+Find prompts by full-text (FTS5 over prompt+response+derived analysis metadata), by metadata filters
 (tool/project/language/role/tag/starred/quality/relevance/date range), or by
 semantic similarity (sqlite-vec, SPEC-008). Backs `ph search`, the TUI text
 filter, the MCP `search_prompts*` tools and the HTTP `/api/prompts/search`.
@@ -30,8 +30,9 @@ filter, the MCP `search_prompts*` tools and the HTTP `/api/prompts/search`.
 1. Build identical filters for two paths: FTS (JOIN with alias `p.`) and scan
    (direct `prompts`). Filters use `json_extract` on metadata for
    project/language/role/tag/starred/quality/relevance (db/index.ts:252-297).
-2. With a text query → FTS path: `prompts_fts JOIN prompts p` via MATCH, filters
-   prefixed `p.` (db/index.ts:300-320).
+2. With a text query → FTS path: `prompts_fts` plus the derived-analysis FTS index are matched and deduplicated by interaction, filters
+   prefixed `p.` and ordered by FTS5 BM25 relevance, then recency for ties
+   (db/index.ts:300-320).
 3. Without text → scan path: `SELECT * FROM prompts WHERE … ORDER BY timestamp
    DESC LIMIT ?` (db/index.ts:322-330).
 4. Date range: `since`/`until` become timestamp comparisons.
@@ -43,21 +44,37 @@ that project before the final result limit. Requires embeddings (SPEC-008).
 Because sqlite-vec applies `k` before ordinary metadata predicates, scoped
 queries currently examine all stored vectors before filtering and limiting.
 
+The CLI cosine-similarity path uses the legacy embedding table. When scoped, it
+loads only vectors joined to prompts whose valid metadata names the selected
+project. It does not load all vectors and issue one `getById` query per vector.
+
 ### 4.3 CLI (src/commands/search.ts)
-`ph search` prints via `printResults` (src/display/print.ts:33); `-i` opens the
-TUI (SPEC-001); `--archive` queries `prompts_archive` (SPEC-009).
+`ph search` defaults to five results and scopes to the detected current project.
+`--all` searches every project; `--project` selects another project. If no
+project is detected, it labels and searches all saved work. `-i` is a text-only
+compatibility flag (SPEC-001); `--archive` queries `prompts_archive` (SPEC-009).
 
 ## 5. Invariants & Business rules
 - FTS path is used ONLY when a text query exists; otherwise full scan + filters.
 - `tag` filter is a JSON-array LIKE `%"tag"%` — substring match on the serialized
   array, not a JSON array membership check (db/index.ts:276-282).
-- `limit` defaults to 50 in the CLI; results ordered timestamp DESC.
+- CLI `limit` defaults to five and must be between 1 and 1000.
+- Raw prompts/responses and derived analysis remain in separate FTS5 indexes.
+  Text search ranks each source list by BM25, then combines their ordinal ranks
+  with Reciprocal Rank Fusion (`1 / (60 + rank)`). Results order by fused score,
+  then timestamp DESC and ID DESC for deterministic ties. Raw-only query order
+  retains its BM25 ordering; an interaction found in both sources receives
+  evidence from both ranked lists.
+- The user-facing search defaults to the current detected project; `--all`
+  explicitly broadens the search. The archive path remains global.
 - Project-scoped semantic search returns the nearest matching prompts within
   that project, even when closer prompts from other projects exist.
+- Project-scoped CLI semantic search loads its vectors with one project join;
+  malformed metadata is ignored without aborting the search.
 
 ## 6. UI / UX surface
 `ph search` output: `#id tool date [tags] [exit:N]` + truncated prompt
-(printResults); `--full` shows the complete text.
+(printResults); `--full` shows complete prompt and response and prints a `ph show <id>` hint. Search text also matches derived summary, insights, and technical decisions; a separate FTS index preserves raw prompt/response BM25 ranking.
 
 ## 7. Acceptance criteria (Given/When/Then)
 - **G1**: Given prompts with text "goroutines" and "react", When `search({query:
@@ -77,6 +94,16 @@ TUI (SPEC-001); `--archive` queries `prompts_archive` (SPEC-009).
 - **G6**: Given an unrelated project has the nearest vector, When
   `searchSemantic(query, 1, "go-play")` runs, Then it returns the nearest
   vector belonging to `go-play` (src/db/index.ts, project scope before limit).
+- **G7**: Given the CLI runs inside a detected project, When `ph search <query>`
+  runs, Then it returns at most five matches from that project by default.
+- **G8**: Given `ph search --all <query>`, When the command runs, Then results
+  may include every project and the output labels the global scope.
+- **G9**: Given matching prompts with different FTS5 scores, When the text
+  search runs, Then matches from raw text and analysis are fused by RRF and
+  tied results resolve by timestamp and ID (SPEC-019).
+- **G10**: Given embeddings across projects, When CLI semantic search targets
+  one project, Then the database returns only that project's vectors in one
+  joined query and the command does not call `getById` for each vector.
 
 ## 8. Key implementation map
 | Concern | File(s) |
@@ -84,6 +111,7 @@ TUI (SPEC-001); `--archive` queries `prompts_archive` (SPEC-009).
 | Dual-path search | src/db/index.ts:243-330 |
 | Semantic KNN | src/db/index.ts (`searchSemantic`) |
 | CLI output | src/commands/search.ts, src/display/print.ts:33-60 |
+| Search scope and defaults | src/commands/search.ts |
 | SearchOptions | src/types.ts:54-68 |
 
 ## 9. Open questions / discrepancies
@@ -91,10 +119,17 @@ TUI (SPEC-001); `--archive` queries `prompts_archive` (SPEC-009).
   `auth` (substring). JSON array membership would be stricter.
 - FTS path columns need the `p.` prefix; a new filter added to only one path
   silently breaks the other (dual maintenance).
-- Project-scoped semantic search currently evaluates the full vector set
-  before metadata filtering because sqlite-vec's KNN limit precedes the join
-  predicate. A project-aware vector index or auxiliary metadata column may
-  reduce this cost if vector counts make it material.
+- Project-scoped semantic search on the sqlite-vec KNN path still evaluates the
+  full vector set before metadata filtering because sqlite-vec's KNN limit
+  precedes the join predicate. The CLI cosine path is project-filtered at load
+  time. A project-aware vector index may reduce KNN cost if vector counts make
+  it material.
+- Semantic search has two implementations: CLI `--semantic` loads the legacy
+  BLOB table and computes cosine similarity in TypeScript; task context, HTTP,
+  and MCP use `sqlite-vec`. Embeddings do not record their producing model, and
+  `ph embed-all` fills missing rows without rebuilding vectors after a model
+  change. Consolidate the search contract and add explicit vector profile and
+  rebuild behavior (ISSUE-026).
 
 ## 10. Related
 - SPEC-002 (primitives), SPEC-008 (embeddings), SPEC-009 (archive),

package/docs/specs/SPEC-006-analysis-pipeline.md

@@ -8,8 +8,9 @@
 
 ## 1. Purpose
 Turns raw prompts into structured knowledge: role/tags/relevance/quality plus
-summary/key_insights/technical_decisions via an LLM. Results feed metadata
-(SPEC-002), memories and project summaries (SPEC-007).
+summary/key_insights/technical_decisions via an LLM. Results enrich interaction
+metadata (SPEC-002) and derived full-text search. They do not create active
+memories or project summaries; explicit approval promotes durable knowledge.
 
 ## 2. Scope
 - **In scope**: ANALYSIS_PROMPT, parseAnalysisResponse, analyzePrompt, mergeMetadata,
@@ -41,8 +42,8 @@ contract; input truncated to 2000 chars (:49). No markdown fences allowed.
 metadata unless `force=true` (:136-183).
 
 ### 4.4 Batch (src/analyzer/index.ts:205)
-`analyzeAll(db, provider, opts)` iterates unanalyzed prompts, updates metadata,
-writes memories (SPEC-007). CLI `ph analyze` with `--limit/--force/--prune/
+`analyzeAll(db, provider, opts)` iterates unanalyzed prompts and updates only
+per-interaction metadata, including lifecycle outcome fields. CLI `ph analyze` with `--limit/--force/--prune/
 --dry-run`.
 
 ### 4.5 Background (src/background/analyzer.ts:7)
@@ -60,8 +61,9 @@ deletes low-score ones (SPEC-009 cross-ref).
 - Input truncated to 2000 chars before the LLM.
 
 ## 6. UI / UX surface
-`ph analyze` progress output; TUI shows `●` (analyzed) vs `○` (pending) in
-ListEntry (SPEC-012).
+`ph analyze` progress output; `ph show` displays full analysis and state;
+`ph status` lists bounded recent background/remote lifecycle outcomes without
+printing prompt or response content.
 
 ## 7. Acceptance criteria (Given/When/Then)
 - **G1**: Given an LLM response with fenced JSON, When `parseAnalysisResponse`

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

@@ -7,11 +7,10 @@
 - **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).
+Project-level knowledge explicitly promoted from reviewed proposals or MCP
+decisions: an append-only `memories` table plus one merged, deduplicated
+`project_summaries` row per project. Current automatic analysis enriches prompt
+metadata only and does not write to these active stores.
 
 ## 2. Scope
 - **In scope**: memories CRUD, upsertProjectMemory (append-only),
@@ -19,7 +18,7 @@ knowledge base" core of the evolution plan (docs/superpowers/specs/
   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`,
+- **Entry points**: `ph close`, MCP `save_decision`, `ph memory-migrate`, `ph context`,
   `ph timeline`, MCP tools, `save_decision`.
 
 ## 3. Data Model
@@ -33,13 +32,13 @@ knowledge base" core of the evolution plan (docs/superpowers/specs/
 
 ## 4. Flows
 
-### 4.1 Append-only memory (src/db/index.ts:535-640)
+### 4.1 Append-only memory (src/db/memory-repository.ts)
 `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;
+technical_decisions, git_context_snapshot})` inserts a new row for an explicitly
+approved or saved decision; automatic per-prompt analysis does not call it. `searchMemories(project, limit)` returns latest N;
 `getAllMemoriesByProject` (774) ascending for timelines.
 
-### 4.2 Curated summary (src/db/index.ts:643-699)
+### 4.2 Curated summary (src/db/memory-repository.ts)
 `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).
@@ -52,7 +51,8 @@ first/last_analyzed. `getProjectSummary(project)` (690).
 `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.
+- memories = append-only timeline of promoted knowledge; project_summaries = 1 row per project.
+- Automatic analysis writes source interaction metadata only; explicit promotion owns active knowledge.
 - 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).
@@ -63,15 +63,15 @@ 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).
+  (src/db/memory-repository.ts).
 - **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).
+  (src/db/memory-repository.ts).
 - **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).
+  (src/db/memory-repository.ts).
 - **G4**: Given `recordMemoryAccess(id)`, When run, Then access_count
-  increments and last_accessed updates (src/db/index.ts:701-706).
+  increments and last_accessed updates (src/db/memory-repository.ts).
 - **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).
@@ -79,9 +79,9 @@ PreviewPane memory tab (SPEC-012); `ph context` markdown output; `ph timeline`.
 ## 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 |
+| Memories CRUD + upsert | src/db/memory-repository.ts |
+| Summary upsert/merge + read | src/db/memory-repository.ts |
+| Access tracking | src/db/memory-repository.ts |
 | Migrate command | src/commands/memory-migrate.ts |
 | Evolution design | docs/superpowers/specs/2026-06-12-ph-evolution-design.md |
 
@@ -92,5 +92,5 @@ PreviewPane memory tab (SPEC-012); `ph context` markdown output; `ph timeline`.
   but their use beyond storage is undocumented.
 
 ## 10. Related
-- SPEC-006 (analysis feeds memories), SPEC-011 (MCP tools), SPEC-014 (context/
+- SPEC-006 (interaction analysis metadata), 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

@@ -82,8 +82,14 @@ unreachable.
 ## 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.
+- Project-scoped `searchSemantic` requests all vectors as the KNN candidate set
+  and applies the project predicate in SQL afterward; large databases may pay
+  full-index KNN cost first (`src/db/semantic-index.ts:17-35`).
+- CLI semantic search uses the legacy BLOB vectors and a TypeScript cosine
+  ranking path, while context, HTTP, and MCP use `sqlite-vec`. Vector rows do
+  not retain their producing model, and `ph embed-all` fills missing vectors
+  rather than rebuilding after a model change. The same query can therefore
+  return different results or compare incompatible vector spaces (ISSUE-026).
 
 ## 10. Related
 - SPEC-005 (semantic search), SPEC-014 (cluster/cohesion use embeddings),

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

@@ -75,8 +75,8 @@ TUI header shows `N prompts (M archived)` (Header.tsx archiveCount prop);
 | 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 |
+| Archive move (transaction) | src/db/archive-repository.ts |
+| Archive search + purge + stats | src/db/archive-repository.ts |
 | Config keys | src/config/index.ts:18-21 |
 | TUI archive count | src/ui/Header.tsx, BrowseApp.tsx:793 |
 

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

@@ -1,106 +1,80 @@
-# SPEC-010: Remote Sync (HTTP Server + Push/Pull)
+# SPEC-010 — Remote sync and HTTP server
 
 - **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.
+- **Status**: Implemented; lossless protocol defined by SPEC-019
+- **Date**: 2026-10-24
+- **Source**: `src/server/`, `src/commands/remote.ts`, `src/sync/`
+
+## Purpose and scope
+
+Share local PH history across trusted machines while each local SQLite database
+remains usable offline. This spec covers server access, authentication, stable
+pagination, deduplication, cursor persistence, and the status command.
+
+## Server contract
+
+- The default listener is `127.0.0.1`; a non-loopback host must be explicit.
+- The server refuses to start without a non-empty `remote-api-key`.
+- `/health` is public and returns `{ "status": "ok" }`. All data routes require
+  `Authorization: Bearer <remote-api-key>` and compare credentials safely.
+- Request bodies are limited to 32 MiB. Oversized and malformed requests return
+  413 and 400 respectively. Internal errors are returned without exception
+  details.
+- `/api/sync/push` accepts up to 500 entries. It reports imported, duplicate,
+  and rejected records separately; the client advances only after complete
+  acknowledgement of the page.
+- `/api/sync/pull` accepts `afterId` and `limit` (1–500), and returns entries in
+  ascending database row-ID order with `hasMore` and `nextCursor`.
+
+## Client contract
+
+- Push selects local rows after a cursor scoped to the normalized target and
+  persistent source database UUID. New imports receive higher IDs even when
+  their timestamps are old, so the next page sees them. Active wrapper captures
+  are not sent until completion; exited-owner markers are reclaimed. Byte-limited
+  HTTP subpages may split one 500-row outer page, and the outer cursor advances
+  only after every subpage is acknowledged.
+- Pull reads remote row-ID pages, inserts or deduplicates every entry, then
+  persists the cursor. Replaying a page is safe through `sync_hash`.
+- Switching the normalized server target or local database starts from row
+  zero. Legacy timestamp or database-unscoped cursors are ignored and trigger an
+  idempotent full scan. A server without cursor response fields produces an
+  actionable upgrade error.
+- `PH_REMOTE_URL` overrides `remoteUrl`. Credentials are never included in the
+  stored target identity.
+- `ph remote status` reports counts after the current target's push cursor and
+  the last successful push/pull times.
+
+## Open reassessment finding
+
+- **ISSUE-025**: cursor identity currently includes the normalized URL and local
+  database UUID, but not the remote database generation. Replacing the remote
+  SQLite file behind the same URL can make a high stored cursor skip the new
+  database's lower row IDs. Config holds only one cursor per direction, so
+  switching local databases and switching back triggers an idempotent full
+  replay. Last-success timestamps are global config fields rather than
+  target-scoped values. Add a remote identity handshake and persist state per
+  complete source/target identity before treating cursors as durable across
+  server restores.
+
+## Acceptance criteria
+
+- **G1**: Server startup requires an API key and defaults to loopback; health
+  discloses no database path; data endpoints reject missing/incorrect keys.
+- **G2**: Equal timestamps, old-timestamp late imports, and multiple pages do
+  not skip rows.
+- **G3**: A failed record prevents that page's cursor from advancing; retrying
+  the page does not duplicate acknowledged records.
+- **G4**: Pull pages are ordered and cursor-based; legacy timestamp configuration
+  replays from the beginning; an old server fails clearly.
+- **G5**: Malformed and oversized bodies return bounded client errors and do not
+  expose internal exceptions.
+- **G6**: `PH_REMOTE_URL` takes precedence and target changes restart sync from
+  row zero.
+- **G7**: Changing local database files restarts push and pull at row zero;
+  byte-limited subpages all remain within the server request cap; live records
+  are not bulk-pushed before response completion.
+
+Focused server and protocol tests live under `src/server/__tests__/` and
+`src/sync/`. SPEC-019 defines cross-cutting capture and ranking requirements.

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

@@ -2,7 +2,7 @@
 
 - **ID**: SPEC-011
 - **Cluster**: MCP
-- **Status**: Implemented (baseline)
+- **Status**: Implemented; adapter decomposition in SPEC-017
 - **Date**: 2026-08-08
 - **Source**: reverse-engineered from code (files listed in §8)
 
@@ -74,9 +74,12 @@ MCP config.
 ## 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 |
+| Server composition + transport | src/mcp/server.ts |
+| Tool definitions | src/mcp/tools/definitions.ts |
+| Prompt and project handlers | src/mcp/tools/prompts.ts, src/mcp/tools/projects.ts |
+| Timeline handler | src/mcp/tools/timeline.ts |
+| Response formatting | src/mcp/tools/format.ts |
+| Memory/summary backends | src/db/memory-repository.ts |
 
 ## 9. Open questions / discrepancies
 - Protocol smoke coverage uses the official SDK client with paired in-memory

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

@@ -1,98 +1,32 @@
-# SPEC-012: TUI Browser
+# SPEC-012: Interactive History Browser (Retired)
 
 - **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.
+- **Cluster**: Retired UI
+- **Status**: Retired on 2026-10-22
+- **Implementation**: Removed from `src/ui/`; Ink/React runtime dependencies removed
+- **Replacement**: `ph search`, `ph last`, and `ph context` print terminal text
+
+## Decision
+
+PH no longer ships the interactive history browser. The former browser combined
+history filtering, details, metadata editing, starring, deletion, reruns,
+provider selection, settings, and context launch in a keyboard-driven Ink/React
+application. This breadth made PH feel like a second terminal application and
+kept the user from the smaller jobs the product needs to do well.
+
+The default command now prints a short guide. `ph search` is the primary way to
+find past interactions; `ph last` and the legacy `ph browse` command print recent
+interactions. `ph search -i` is accepted for compatibility and prints normal
+search results. No search or memory data is changed by this UI retirement.
+
+## Historical Context
+
+The retired implementation supported list/detail panes, filters, settings,
+star/edit/delete, rerun, context-aware chat, keyboard navigation, and an
+alternate-screen terminal mode. Those interactions were removed with the UI
+components and their PTY/filter tests. Equivalent history and knowledge remain
+available through the CLI, MCP, and existing storage APIs where applicable.
+
+The old keybindings, source locations, and interaction criteria are deliberately
+not maintained as current requirements. Use `SPEC-001` for the current CLI
+contract.