@gi4nks/ph 1.5.0 → 1.7.0

package/docs/specs/SPEC-013-importers.md

@@ -0,0 +1,109 @@
+# SPEC-013: Importers (Claude / Gemini / OpenCode / Codex)
+
+- **ID**: SPEC-013
+- **Cluster**: Import
+- **Status**: Implemented
+- **Date**: 2026-08-08
+- **Source**: reverse-engineered from code (files listed in §8)
+
+## 1. Purpose
+Bootstrap history from existing AI CLI session stores: Claude Code (JSONL),
+Gemini CLI (JSONL), OpenCode (SQLite at `~/.local/share/opencode/opencode.db`),
+and Codex CLI rollout JSONL files under `~/.codex/sessions/`.
+All imports route through the filter pipeline (SPEC-004) and can trigger inline
+LLM analysis (`--analyze`).
+
+## 2. Scope
+- **In scope**: four importer modules, import command flow, dedup, dry-run,
+  filter/analyze flags.
+- **Out of scope**: real-time capture (SPEC-003), remote import.
+- **Entry points**: `ph import gemini|claude|opencode|codex [--dry-run] [--analyze] [--filter]`; Codex also accepts `--file <transcript>`.
+
+## 3. Data Model
+- `ImportResult` (src/types.ts:70-77): filesScanned, promptsFound,
+  promptsImported, skipped, filtered, errors.
+- Sources: Claude JSONL sessions; Gemini session JSON; OpenCode `opencode.db`
+  (`session`/`message`/`part` tables; assistant→user link via `parentID` in
+  `message.data`); Codex rollout JSONL.
+
+## 4. Flows
+
+### 4.1 Claude/Gemini (src/importer/claude.ts, gemini.ts)
+1. Locate session stores in `~/.claude` / `~/.gemini` (JSONL).
+2. Parse pairs (prompt + response); apply filter pipeline; dedup vs existing
+   (by prompt hash or content).
+3. Normalize and insert via `createCaptureRecord` in PhDB; `--analyze` runs
+   inline analysis per imported prompt.
+
+### 4.2 OpenCode (src/importer/opencode.ts)
+1. Read `~/.local/share/opencode/opencode.db` (better-sqlite3).
+2. Pair user messages with assistant responses (parentID join).
+3. Dedup (existing prompt check), insert, optional analyze.
+   Reference run: 186 pairs found → 151 imported (AGENTS.md).
+
+### 4.3 Command flow (src/commands/import.ts)
+`cmdImport(db, cfg, args)` dispatches by source; `--dry-run` reports counts
+without inserting; `--filter` enables the pipeline; `--analyze` runs LLM
+analysis inline.
+
+### 4.4 Codex (src/importer/codex.ts)
+1. Recursively scan `~/.codex/sessions/` for `rollout-*.jsonl`, or use the
+   transcript passed with `--file` by the Codex Stop hook.
+2. Read `session_meta` for session ID and working directory; pair legacy
+   `event_msg.user_message` records or modern `response_item` messages with
+   `role=user` with the following assistant response. Prefer assistant messages
+   with `phase=final_answer` over commentary when that phase is present.
+3. Insert through the normalized capture record and content dedup filter.
+
+## 5. Invariants & Business rules
+- Imports never duplicate existing prompts (content-based dedup).
+- `--dry-run` performs no writes.
+- OpenCode source DB is opened read-only (never modified).
+- Imported prompts carry the source tool name (`claude`/`gemini`/`opencode`/`codex`).
+- Importers share the capture record shape and retain source-specific metadata.
+
+## 6. UI / UX surface
+CLI summary: `Files scanned / prompts found / imported / skipped / filtered`.
+
+## 7. Acceptance criteria (Given/When/Then)
+- **G1**: Given a Claude JSONL with one session, When `importer/claude` runs,
+  Then a prompt+response pair is produced (src/importer/claude.ts).
+- **G2**: Given an already-imported prompt, When the importer runs again, Then
+  it is skipped (not duplicated) (src/importer/claude.ts dedup path).
+- **G3**: Given `--dry-run`, When `cmdImport` runs, Then no rows are inserted
+  and counts are reported (src/commands/import.ts).
+- **G4**: Given `--analyze`, When an import runs, Then analysis runs inline for
+  each imported prompt (SPEC-006).
+- **G5**: Given `--filter`, When an import runs, Then FilterPipeline rejects
+  noise before insert (SPEC-004).
+- **G6**: Given a Codex rollout with user and agent events, When the Codex
+  importer runs, Then it stores paired text with the session working directory
+  and does not duplicate the turn on a subsequent import.
+
+## 8. Key implementation map
+| Concern | File(s) |
+|---|---|
+| Claude importer | src/importer/claude.ts |
+| Gemini importer | src/importer/gemini.ts |
+| OpenCode importer | src/importer/opencode.ts |
+| Codex importer | src/importer/codex.ts |
+| Command dispatch | src/commands/import.ts |
+| Normalized insertion | src/capture/index.ts |
+
+## 9. Open questions / discrepancies
+- Claude JSONL, Gemini session JSON, OpenCode SQLite, and Codex rollout fixtures verify
+  prompt/response pairing and imported workdir against a temporary `PhDB`.
+- Claude/Gemini store discovery paths are version-specific — a CLI update can
+  break pairing silently (returns empty).
+- OpenCode parentID pairing relies on `message.data` JSON shape; schema drift in
+  opencode.db breaks imports.
+- Codex transcript paths and rollout formats are not stable hook interfaces;
+  unknown or malformed JSONL records are ignored. The importer supports both
+  `event_msg` user/agent messages and `response_item` user/assistant messages.
+- Shared content dedup hashes prompt text across tools; repeated user prompts
+  from different tools collapse under this policy.
+
+## 10. Related
+- SPEC-002 (insert), SPEC-004 (filter), SPEC-006 (analyze). Source-format
+  importer tests still need fixtures (SPEC-ISSUES-007); normalized record
+  behavior is covered in `src/capture/__tests__/record.test.ts`.

package/docs/specs/SPEC-014-analytics-commands.md

@@ -0,0 +1,109 @@
+# SPEC-014: Analytics Commands (Sessions / Stats / Cluster / Timeline / Context)
+
+- **ID**: SPEC-014
+- **Cluster**: Analytics
+- **Status**: Implemented (baseline)
+- **Date**: 2026-08-08
+- **Source**: reverse-engineered from code (files listed in §8)
+
+## 1. Purpose
+Higher-level views over the history: work-session grouping (time gaps +
+semantic cohesion), statistics, K-means clustering of prompts by embedding,
+per-project timelines, and RAG context output.
+
+## 2. Scope
+- **In scope**: `ph sessions`, `ph stats`, `ph cluster`, `ph timeline`,
+  `ph context`, `ph chat` (context injection).
+- **Out of scope**: search (SPEC-005), embeddings (SPEC-008), memories
+  (SPEC-007).
+- **Entry points**: the five commands above.
+
+## 3. Data Model
+- `WorkSession` (src/sessions/index.ts:4): id, project, start/end, prompts,
+  cohesion score.
+- `Stats` (src/stats/index.ts:4): totals, per-tool, per-role, per-project,
+  averages.
+- Cluster: `{ centroid, entryIds }` (src/cluster/index.ts:20-21).
+
+## 4. Flows
+
+### 4.1 Sessions (src/sessions/index.ts:16-63)
+`groupIntoSessions(entries, gapHours)` splits on idle gaps (default 2h);
+`computeSessionCohesion` (:65) uses embedding similarity. CLI `ph sessions`
+with `--gap-hours`, `--min-size`, `--no-cohesion`, `--export <n>` (markdown).
+
+### 4.2 Stats (src/stats/index.ts:16)
+`getStats(db)` computes totals + breakdowns; `ph stats` prints a table.
+
+### 4.3 Cluster (src/cluster/index.ts)
+K-means (maxIterations, convergence at cosine ≥ 0.9999) over embeddings;
+`ph cluster -k N` prints the top prompts per cluster.
+
+### 4.4 Timeline (src/commands/timeline.ts)
+`ph timeline <project>` interleaves prompts + memories chronologically
+(`getAllPromptsByProject` :740, `getAllMemoriesByProject` :774).
+
+### 4.5 Context & chat
+`getProjectContext` in `src/context/index.ts` retrieves the accumulated project
+summary, recent memories, and recent prompts for CLI, chat, and MCP consumers.
+An optional semantic query uses a configured embedder and project-scoped KNN.
+`formatProjectContext` renders shared Markdown, with optional prompt text for
+`ph context --verbose`. CLI flags can exclude prompt or memory sources.
+`ph chat <tool> <prompt>` injects the same project context into a tool run.
+
+## 5. Invariants & Business rules
+- Sessions split purely on time gaps (2h default) unless cohesion overrides.
+- Cluster requires embeddings — without them the command errors/warns.
+- Context output is markdown text (pipe-ready); memory section comes from
+  `memories` + `project_summaries`.
+- CLI, chat, and MCP project context use the shared retrieval and Markdown
+  formatting boundary; evidence remains structured until rendering.
+- Semantic retrieval with a project scope applies the project filter before
+  returning the requested number of results (SPEC-005).
+- Timeline is ascending chronological (oldest → newest).
+
+## 6. UI / UX surface
+CLI tables/markdown; TUI chat mode (C key, SPEC-012) launches the tool with
+context injected.
+
+## 7. Acceptance criteria (Given/When/Then)
+- **G1**: Given prompts 3h apart, When `groupIntoSessions(entries, 2)` runs,
+  Then two sessions are produced (src/sessions/index.ts:16-63).
+- **G2**: Given prompts 1h apart, When `groupIntoSessions(entries, 2)` runs,
+  Then one session is produced (src/sessions/index.ts:16-63).
+- **G3**: Given `getStats(db)`, When run, Then the returned Stats match the DB
+  contents (src/stats/index.ts:16).
+- **G4**: Given identical embedding vectors, When k-means runs with k=1, Then a
+  single cluster contains all entries (src/cluster/index.ts:28-75).
+- **G5**: Given `ph timeline ph`, When run, Then prompts and memories are
+  interleaved in ascending order (src/commands/timeline.ts,
+  db/index.ts:740-780).
+- **G6**: Given a project with a summary, memories, and prompts, When
+  `getProjectContext` runs, Then it returns each evidence source for consumers
+  to render (src/context/index.ts).
+- **G7**: Given excluded sources or no stored evidence, When shared context is
+  retrieved and rendered, Then excluded sources are omitted and empty context
+  is reported (src/context/index.ts).
+
+## 8. Key implementation map
+| Concern | File(s) |
+|---|---|
+| Sessions + cohesion | src/sessions/index.ts:16-80 |
+| Stats | src/stats/index.ts:16-60 |
+| K-means cluster | src/cluster/index.ts:1-78 |
+| Timeline | src/commands/timeline.ts |
+| Context retrieval and formatting | src/context/index.ts |
+| Context consumers | src/commands/context.ts, src/commands/chat.ts, src/mcp/server.ts |
+
+## 9. Open questions / discrepancies
+- Cohesion scoring cost is O(n²) embeddings comparisons; large histories make
+  `ph sessions` slow (no cache).
+- Cluster convergence threshold (0.9999) with 768-dim floats can oscillate —
+  maxIterations is the real bound.
+- Project-scoped semantic lookup evaluates all vectors before filtering. See
+  SPEC-005 for the current cost and possible indexed alternatives.
+
+## 10. Related
+- SPEC-005/008 (inputs), SPEC-007 (memory inputs), SPEC-012 (TUI chat),
+  SPEC-011 (MCP). Context retrieval GWT coverage is in
+  `src/context/__tests__/context.test.ts`.

package/docs/specs/SPEC-015-config-env.md

@@ -0,0 +1,85 @@
+# SPEC-015: Config & Env Overrides
+
+- **ID**: SPEC-015
+- **Cluster**: Config
+- **Status**: Implemented (baseline)
+- **Date**: 2026-08-08
+- **Source**: reverse-engineered from code (files listed in §8)
+
+## 1. Purpose
+Central configuration for ph: `~/.ph_config.json` with typed keys, `ph config
+get/set`, and environment overrides (`PH_DB`, `PH_REMOTE_URL`, `GEMINI_API_KEY`).
+
+## 2. Scope
+- **In scope**: PhConfig shape, load/save, `ph config` command, env precedence.
+- **Out of scope**: per-command flags (each command parses its own).
+- **Entry points**: `ph config get|set <key> <value>`, env vars.
+
+## 3. Data Model
+- `PhConfig` (src/config/index.ts:5-22): geminiApiKey, dbPath, analyzeProvider,
+  ollamaUrl, ollamaModel, ollamaEmbedModel, filterMinLength, filterMinRelevance,
+  backgroundAnalysis, remoteUrl, remoteApiKey, remoteLastPush, remoteLastPull,
+  retentionDays, retentionMinStarred, retentionMinAnalyzed, retentionMinRelevance.
+- Env: `PH_DB` (dbPath, cli.ts:157), `PH_REMOTE_URL` (remote.ts:6-8),
+  `GEMINI_API_KEY` (cli.ts:153-155).
+- `load()` (src/config/index.ts:27-35): reads the file, defaults `{}` on
+  missing/corrupt. `save(cfg)` (:38-40) writes JSON.
+
+## 4. Flows
+
+### 4.1 Command (src/commands/config.ts)
+`ph config set <key> <value>` — validates key exists in PhConfig, coerces
+value (boolean/number), loads → updates → saves. `ph config get <key>` prints
+the value; no key prints the whole config.
+
+### 4.2 Precedence
+1. Env beats config: PH_DB > cfg.dbPath > defaultPath; PH_REMOTE_URL >
+   cfg.remoteUrl.
+2. geminiApiKey in config is exported to `process.env.GEMINI_API_KEY` before
+   dispatch (cli.ts:153-155).
+3. `analyzeProvider` ('ollama' | 'gemini') picks the LLM provider
+   (SPEC-006 factory).
+
+## 5. Invariants & Business rules
+- Unknown keys in `ph config set` are rejected (validated against PhConfig).
+- load() never throws — corrupt config degrades to defaults.
+- Save is full-file write (no partial merge).
+
+## 6. UI / UX surface
+`ph config` CLI + Settings panel in the TUI (`o`, SPEC-012) which edits the same
+file.
+
+## 7. Acceptance criteria (Given/When/Then)
+- **G1**: Given `ph config set background-analysis true`, When run, Then the
+  config file contains `"backgroundAnalysis": true`
+  (src/commands/config.ts, config/index.ts:38-40).
+- **G2**: Given a missing config file, When `load()` runs, Then `{}` is returned
+  without throwing (src/config/index.ts:27-35).
+- **G3**: Given `ph config set bogus-key 1`, When run, Then the key is rejected
+  (src/commands/config.ts validation).
+- **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 a config with `geminiApiKey`, When main() runs, Then
+  `process.env.GEMINI_API_KEY` is set (src/cli.ts:153-155).
+
+## 8. Key implementation map
+| Concern | File(s) |
+|---|---|
+| PhConfig + load/save | src/config/index.ts:5-40 |
+| get/set command | src/commands/config.ts |
+| Env precedence | src/cli.ts:157, src/commands/remote.ts:6-8 |
+| TUI settings panel | src/ui/BrowseApp.tsx (SettingsView) |
+
+## 9. Open questions / discrepancies
+- `remoteLastPush` was missing from PhConfig (FIXED 2026-08-08, SPEC-ISSUES-003).
+- `save()` writes the whole object — concurrent `ph` processes (e.g. a hook
+  logging while the user sets config) can clobber each other's writes (no
+  locking).
+- Config comments in AGENTS.md describe defaults that live in code
+  (load-time defaults in cli.ts/commands) — the doc is authoritative for intent,
+  code for truth.
+
+## 10. Related
+- SPEC-001 (load at startup), SPEC-004/006/009 (filter/analysis/retention keys),
+  SPEC-010 (remote keys). No tests (SPEC-ISSUES-007) — G1/G2/G4 are vitest
+  targets with a temp HOME.

package/docs/specs/SPEC-INDEX.md

@@ -0,0 +1,35 @@
+# SPEC INDEX — ph
+
+Spec-driven baseline for **ph** (Prompt History & Analysis — transparent
+observability layer for AI CLI tools). Reverse-engineered from code on
+2026-08-08 with `path:line` evidence. Published as `@gi4nks/ph` (npm,
+semantic-release + OIDC provenance).
+
+Cluster map: Core (CLI/architecture) · Capture (wrapper/hooks/log) · DB (PhDB)
+· Search (FTS/semantic) · AI (analysis/embeddings) · Memory (memories/summaries)
+· Sync (server/remote) · MCP · TUI · Import · Analytics · Config.
+
+## Registry
+
+| ID | Feature | Cluster | Status | Tests |
+|----|---------|---------|--------|-------|
+| SPEC-001 | Architecture & CLI dispatch | Core | **Implemented (baseline)** | — |
+| SPEC-002 | Database layer (PhDB) | DB | **Implemented (baseline)** | — |
+| SPEC-003 | Capture modes (pty/inline/hooks/log) | Capture | **Implemented (baseline)** | — |
+| SPEC-004 | Filter pipeline & metadata | Core | **Implemented (baseline)** | — |
+| SPEC-005 | Search (FTS + filters + semantic) | Search | **Implemented (baseline)** | — |
+| SPEC-006 | Analysis pipeline (LLM) | AI | **Implemented (baseline)** | — |
+| SPEC-007 | Memory & project summaries | Memory | **Implemented (baseline)** | — |
+| SPEC-008 | Embeddings (sqlite-vec) | AI | **Implemented (baseline)** | — |
+| SPEC-009 | Retention & archive | DB | **Implemented (baseline)** | — |
+| SPEC-010 | Remote sync (server + push/pull) | Sync | **Implemented (baseline)** | — |
+| SPEC-011 | MCP server | MCP | **Implemented (baseline)** | — |
+| SPEC-012 | TUI browser | TUI | **Implemented (baseline)** | — |
+| SPEC-013 | Importers (claude/gemini/opencode/codex) | Import | **Implemented** | import fixtures |
+| SPEC-014 | Analytics commands (sessions/stats/cluster/timeline) | Analytics | **Implemented (baseline)** | — |
+| SPEC-015 | Config & env overrides | Config | **Implemented (baseline)** | — |
+
+## Cross-cutting findings (SPEC-ISSUES.md)
+
+See SPEC-ISSUES.md for code-vs-doc discrepancies and open questions collected
+while reverse-engineering the baseline.

package/docs/specs/SPEC-ISSUES.md

@@ -0,0 +1,122 @@
+# SPEC-ISSUES — ph cross-cutting findings
+
+Discrepancies, dead code, and open questions found while reverse-engineering
+the ph baseline (2026-08-08). Each entry cites `path:line` evidence.
+Status: Open → assigned SPEC / fixed.
+
+## Database
+
+- **ISSUE-001 — `response` column created by ALTER, not CREATE TABLE** — the
+  `prompts` CREATE TABLE (src/db/index.ts:55-66) omits `response`; the column is
+  added later by a migration `ALTER TABLE prompts ADD COLUMN response`
+  (src/db/index.ts:143-146) that runs on every open. Works, but a fresh DB goes
+  through two steps and the schema is documented with `response` in CREATE
+  (AGENTS.md). → cleanup candidate.
+- **ISSUE-002 — Private `db` accessed from server/remote (FIXED 2026-08-08)** —
+  `server/index.ts` used `db.db.prepare(...)` in 6 places and `remote.ts` in 1
+  (health, sync push/pull, stats, status). Fixed by adding public PhDB methods
+  (`getPromptCountSince`, `getStats`, `dbPath`) and reusing existing ones
+  (`getPromptBySyncHash`, `getPromptsSince`, `getAllPrompts`). Fixed.
+- **ISSUE-003 — `remoteLastPush` undeclared in PhConfig (FIXED 2026-08-08)** —
+  `remote.ts` read/wrote `cfg.remoteLastPush` (push + status) while
+  `PhConfig` (src/config/index.ts:5-22) declared only `remoteLastPull`; the
+  field silently worked at runtime but was invisible to the type system. Fixed.
+
+## Types / build
+
+- **ISSUE-004 — node-pty typings blocked by package exports (FIXED 2026-08-08)** —
+  `@lydell/node-pty` ships `node-pty.d.ts` but its package.json `exports` field
+  breaks resolution under `moduleResolution: Bundler` → TS7016. Fixed with a
+  minimal local declaration (src/pty/node-pty.d.ts) covering the used API. Fixed.
+- **ISSUE-005 — TS6/@types-node-25 type breakage (FIXED 2026-08-08)** — the
+  TS 5.9→6.0 upgrade broke 12 sites (Float32Array<ArrayBufferLike>, readSync
+  4-arg, insert() response, private db, node-pty). All fixed; tsc green. Fixed.
+- **ISSUE-006 — eslint 10 unusable with eslint-plugin-react 7.37.5** — peer range
+  excludes eslint 10 (ERESOLVE). Resolved by pinning eslint back to ^9.39.4 and
+  adding the missing `@eslint/js` devDep (eslint.config.js imported it but it was
+  never in package.json → lint was completely broken). Fixed (downgrade).
+- **ISSUE-007 — ZERO test files (FIXED 2026-10-09)** — baseline had no test
+  files. Tests now cover database, search, memory, archive, sync, config,
+  analysis, sessions, context, capture, TUI filter transitions, importer formats,
+  PTY response cleanup, HTTP endpoints, and MCP tool calls over an in-memory
+  protocol transport. The Ink browser also has a PTY smoke test that opens its
+  filter panel and exits cleanly; a nested PTY test verifies wrapped prompt and
+  ANSI-clean response persistence. Broader screen flows remain covered by
+  component/module tests rather than end-to-end navigation.
+- **ISSUE-016 — NON_PRINTABLE pattern matched plain words (FIXED 2026-08-08)** —
+  the filter's non-printable regex `^[\x00-\x1f\x7f\x1b\[\]()#;\d;A-Za-z]*$`
+  matched ANY all-alphanumeric string (e.g. "yes") because of `[A-Za-z\d]` in
+  the class, classifying normal prompts as PTY noise. Fixed with a control-char
+  lookahead (src/filter/index.ts:32-35). Found by the SPEC-004 GWT suite. Fixed.
+- **ISSUE-017 — trivial filler list missed an Italian thank-you phrase (FIXED 2026-08-08)** —
+  the Italian filler set lacked a common thank-you phrase;
+  added (src/filter/index.ts:25). Found by the SPEC-004 GWT suite. Fixed.
+- **ISSUE-018 — semantic project filter ran after global KNN limit (FIXED 2026-10-09)** —
+  Context consumers fetched global nearest neighbors and filtered metadata
+  afterward, which could omit relevant entries from the requested project.
+  `PhDB.searchSemantic(query, limit, project)` now scopes results before the
+  final limit; project-scoped searches inspect all stored vectors because
+  sqlite-vec applies its KNN candidate limit before ordinary SQL filters.
+  Fixed; performance trade-off documented in SPEC-005.
+
+## Docs
+
+- **ISSUE-008 — AGENTS.md stack table stale** — AGENTS.md says ink 6.8 / TS 5.9
+  / eslint 9; package.json has ink 7.0.5 / TS 6.0.3 / eslint 9 (after revert).
+  → docs update.
+- **ISSUE-009 — `standard-version` still a devDep** — replaced by
+  semantic-release (AGENTS.md) but still listed in package.json devDependencies.
+  → chore cleanup.
+
+## Design smells
+
+- **ISSUE-010 — cli.ts TUI bootstrap duplicated 3× (FIXED 2026-08-08)** —
+  extracted `openBrowser(db, props)` and `runRerun()` in `src/cli.ts`; default,
+  `search -i`, and `browse` now share the alt-screen cleanup path. Fixed.
+- **ISSUE-011 — BrowseApp remains a large module** — detail, edit, rerun,
+  provider selection, settings, and app state remain in `src/ui/BrowseApp.tsx`.
+  Filter policy/count generation now lives in `src/ui/filtering.ts` and keyboard
+  rendering in `src/ui/FilterPanel.tsx`; filter transitions are directly tested
+  and the keyboard path to open/close the rendered filter panel has a PTY smoke
+  test. Detail/edit/rerun and other screen interactions remain in BrowseApp.
+- **ISSUE-012 — sync_hash excludes args/workdir (FIXED 2026-08-08)** — dedup
+  hash was `sha256(tool|prompt|response)` duplicated inline in server
+  (src/server/index.ts:104) and remote (remote.ts:116) — drift risk. Now a
+  shared `syncHash` helper (src/utils/syncHash.ts) that includes `args` ONLY
+  when present — backward compatible: entries without args keep the legacy
+  hash (no mass re-push), entries with different args no longer collapse. Fixed.
+- **ISSUE-013 — server auth is declared but never enforced (FIXED 2026-08-08)** —
+  `remoteApiKey` was sent by the client but the HTTP server never checked it.
+  Now `createRequestHandler` (exported for tests) gates every endpoint except
+  `/health` with `Authorization: Bearer <key>` (timingSafeEqual) when
+  `remoteApiKey` is configured (src/server/index.ts:30-60). Fixed.
+- **ISSUE-014 — memories prompt_ids unused after summaries** — `prompt_ids` in
+  `memories` (src/db/index.ts:109) is written but the summary merge path
+  (project_summaries) tracks prompt_count instead; the timeline joins via
+  project name. → verify whether prompt_ids is still load-bearing.
+- **ISSUE-015 — `printResults`/`printEntry` display layer** — src/display/print.ts
+  duplicates formatting logic that the TUI ListEntry also renders; two code paths
+  for entry display can drift (e.g. badges, truncation rules).
+
+## Issue-to-spec map
+
+| Issue | Spec (fix target) | Status |
+|---|---|---|
+| 001 | SPEC-002 | Open (cleanup) |
+| 002 | SPEC-002/010 | Fixed 2026-08-08 |
+| 003 | SPEC-015 | Fixed 2026-08-08 |
+| 004 | SPEC-003 | Fixed 2026-08-08 |
+| 005 | SPEC-002 | Fixed 2026-08-08 |
+| 006 | — (tooling) | Fixed 2026-08-08 (eslint 9 + @eslint/js) |
+| 007 | SPEC-002/003/005/009/010/011/012/013/014 | Fixed 2026-10-09 (core terminal and TUI paths covered; other screen flows remain module-tested) |
+| 008 | — (docs) | Open |
+| 009 | — (chore) | Open |
+| 010 | SPEC-001 | Fixed 2026-08-08 |
+| 011 | SPEC-012 | Open |
+| 012 | SPEC-010 | Fixed 2026-08-08 (shared syncHash, args-aware, backward compatible) |
+| 013 | SPEC-010 | Fixed 2026-08-08 (auth gate on createRequestHandler) |
+| 014 | SPEC-007 | Open |
+| 015 | SPEC-012 | Open |
+| 016 | SPEC-004 | Fixed 2026-08-08 |
+| 017 | SPEC-004 | Fixed 2026-08-08 |
+| 018 | SPEC-005/014 | Fixed 2026-10-09 |

package/docs/specs/_TEMPLATE.md

@@ -0,0 +1,65 @@
+# SPEC Template — use for every ph spec
+
+> Copy this file to `docs/specs/SPEC-XXX-<slug>.md` and fill in. Keep it in **English**.
+> Reverse-engineering rule: every claim must be traceable to code. When writing specs,
+> cite `path:line` evidence. If behavior is ambiguous in code, record it in
+> section 9 as an open question — never invent behavior.
+
+```markdown
+# SPEC-XXX: <Feature Name>
+
+- **ID**: SPEC-XXX
+- **Cluster**: Core | Capture | DB | AI | Search | Memory | Sync | MCP | TUI | Import | Analytics | Config
+- **Status**: Draft | In Review | Accepted | Implemented
+- **Date**: 2026-08-08
+- **Source**: reverse-engineered from code (files listed in §8)
+
+## 1. Purpose
+Why this feature exists, the problem it solves.
+
+## 2. Scope
+- **In scope**: …
+- **Out of scope**: …
+- **Entry points**: (ph commands, hooks, MCP tools, HTTP endpoints)
+
+## 3. Data Model
+Entities and fields the feature reads/writes.
+
+## 4. Flows
+
+### 4.1 Happy path
+Numbered, concrete steps.
+
+### 4.2 Edge cases & error handling
+Known branches, validation failures, provider errors, concurrency notes.
+
+## 5. Invariants & Business rules
+- Rules that MUST never be violated.
+
+## 6. UI / UX surface
+TUI components, CLI output, keybindings.
+
+## 7. Acceptance criteria (Given/When/Then)
+- **G1**: Given … When … Then …
+- **G2**: …
+- **G3**: …
+
+## 8. Key implementation map
+| Concern | File(s) |
+|---|---|
+
+## 9. Open questions / discrepancies
+- Any spec-vs-code mismatch, dead code, or undocumented behavior discovered.
+
+## 10. Related
+- Other SPEC ids, AGENTS.md notes, tests that exercise this feature.
+```
+
+## Rules of the road
+1. Each MUST have ≥3 GWT acceptance criteria (they become vitest wiring later).
+2. IDs are assigned in SPEC-INDEX.md — do NOT create new IDs.
+3. One feature per file; files go to `docs/specs/SPEC-XXX-<slug>.md`.
+4. Do not modify code. Read-only probe + `write_file` for the spec only.
+5. Baseline specs (SPEC-001…) describe ph **as it is today** (regression targets).
+   ph is an application: integration targets (harness-style) are not planned —
+   keep specs baseline-only unless a target spec is explicitly requested.