@gi4nks/ph 1.6.0 → 1.8.0

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

@@ -19,6 +19,7 @@ get/set`, and environment overrides (`PH_DB`, `PH_REMOTE_URL`, `GEMINI_API_KEY`)
 - `PhConfig` (src/config/index.ts:5-22): geminiApiKey, dbPath, analyzeProvider,
   ollamaUrl, ollamaModel, ollamaEmbedModel, filterMinLength, filterMinRelevance,
   backgroundAnalysis, remoteUrl, remoteApiKey, remoteLastPush, remoteLastPull,
+  remotePushCursor {target, databaseId, id}, remotePullCursor {target, databaseId, id},
   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).
@@ -75,6 +76,9 @@ file.
 - `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).
+- `remoteLastPush` and `remoteLastPull` are global timestamps rather than
+  target-scoped values, so status can display another remote's last success.
+  Cursor identity also omits the remote database generation (SPEC-ISSUES-025).
 - 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.

package/docs/specs/SPEC-016-operational-memory.md

@@ -0,0 +1,48 @@
+# SPEC-016 — Operational memory workflow
+
+**Status:** Implemented (2026-10-10)
+
+## Purpose
+
+Support a deliberate `prepare → work → close → promote` loop. Task retrieval is shared by CLI context, chat, and MCP knowledge checks. General context without a task remains non-semantic. Captured work only becomes curated knowledge after explicit user approval, and promoted memories keep verifiable prompt sources.
+
+## Behavior
+
+### `ph prepare`
+
+- Accepts a task description and a project inferred from CWD or specified with `--project`.
+- Uses shared `getProjectContext` retrieval with the task as a semantic query.
+- If embeddings fail, labels the failure and falls back to recent project context.
+- Renders source IDs and bounds the retrieved content using `--budget`; source references are preserved even if they exceed that target.
+- Does not generate text or write to the database.
+
+### `ph close`
+
+- Requires exactly one explicit selection: `--since <duration>` or inclusive `--from <id> --to <id>`; selects only prompts tagged with the chosen project.
+- Prints source prompt/response excerpts before generating proposals. `--dry-run` performs no generation and no database writes.
+- Uses the configured analysis provider to propose zero or more knowledge entries. Every proposal must cite one or more selected prompt IDs.
+- Requires an interactive TTY to approve or edit proposals. Proposals are staged until the user completes the review; quitting or interrupting before completion writes nothing.
+- Checks for an interactive TTY before calling the analysis provider.
+- On completed review, approved proposals append memories with cited `prompt_ids` and update `project_summaries` in one SQLite transaction. A failed write rolls back the whole approved batch.
+
+### MCP
+
+- `check_project_knowledge` uses the shared retrieval and formatter; embedding failure is labeled and falls back to recent context.
+- `save_decision` accepts optional `promptIds`, validates existence and project ownership before writing, and stores them on the memory.
+
+## GWT Acceptance
+
+1. **Given** a task in a project with semantic embeddings, **when** `ph prepare` runs, **then** it returns scoped evidence and source IDs without changing prompt, memory, or summary data.
+2. **Given** unavailable Ollama embeddings, **when** `ph prepare` runs, **then** it labels the fallback and renders recent context for the selected project.
+3. **Given** selected prompt history, **when** `ph close --dry-run` runs, **then** it displays the selected excerpts without calling a model or writing memory/summary data.
+4. **Given** generated proposals, **when** a cited ID is not in the selected prompt set, **then** the response is rejected before review or persistence.
+5. **Given** a user approves proposals and finishes review, **when** review commits, **then** each approved memory stores the proposal's cited prompt IDs and updates the matching project summary.
+6. **Given** `save_decision` receives a missing or other-project prompt ID, **when** called through MCP, **then** it returns an error and creates no memory.
+7. **Given** MCP or CLI task retrieval for a project, **when** embeddings fail, **then** shared recent-context fallback is used and the degradation is visible.
+8. **Given** a batch contains an invalid memory write, **when** promotion fails, **then** none of the batch's memories or summary updates persist.
+9. **Given** `ph close` runs without an interactive TTY, **when** it is not a dry run, **then** it exits before calling the analysis provider.
+
+## Verification
+
+- Deterministic golden retrieval contract spans at least 12 judged queries across five projects; fixed-vector ranking test reports Recall@2/MRR without generation calls.
+- Full local verification on 2026-10-10: 93 Vitest tests, ESLint, TypeScript, and tsup build passed.

package/docs/specs/SPEC-017-architecture-consolidation.md

@@ -0,0 +1,63 @@
+# SPEC-017 — Internal architecture consolidation
+
+- **ID**: SPEC-017
+- **Cluster**: Core, DB, MCP
+- **Status**: Implemented
+- **Date**: 2026-10-22
+
+## Purpose
+
+Reduce internal coupling and constrain product-surface growth without changing
+the public behavior of existing PH commands, MCP tools, or the SQLite schema.
+
+**Spec impact: none.** This is an internal-only change. Existing CLI syntax,
+MCP tool names and payloads, database schema, persisted data, and retrieval
+results remain compatible.
+
+## Decisions
+
+1. Do not add, remove, rename, or deprecate user-facing commands in this work.
+   Clarify the existing jobs of `context`, `prepare`, agent-facing MCP, and
+   `chat`; hold new feature proposals until the operational workflow is used on
+   three real tasks across different projects.
+2. Keep `src/mcp/server.ts` as the protocol composition root. Move tool
+   declarations, domain handlers, and response formatting into cohesive
+   modules. It remains responsible for MCP SDK registration and error/content
+   envelope translation.
+3. Keep `PhDB` as the public facade and keep its constructor, method names, and
+   return values stable. Keep prompt CRUD, FTS, schema, and migrations in the
+   prompt core. Move memory/summary operations and archive operations behind
+   internal repositories sharing the same SQLite connection. Semantic vectors
+   remain in the existing `SemanticIndex`. Preserve the single connection and
+   transaction boundary.
+4. Reuse shared project-context and memory-promotion operations from CLI and
+   MCP. Adapters must not own business validation or multi-write consistency.
+
+## Acceptance
+
+- Existing commands and all registered MCP tools retain their current names,
+  schemas, behavior, and text response contracts.
+- Existing databases open without migration or data rewrite.
+- `PhDB` remains source-compatible for current callers.
+- MCP server composition contains no per-tool business logic or response
+  formatting.
+- Memory/summary and archive SQL operations are owned by cohesive internal
+  persistence modules; prompt CRUD and FTS remain together in the prompt core.
+  Transaction behavior stays on the shared connection.
+- New user-facing capabilities are not introduced in this change.
+- Existing test suite, lint, TypeScript check, and build pass.
+
+## Verification
+
+- `npm test`: 17 files, 94 tests passed.
+- `npm run lint`: passed.
+- `npx tsc --noEmit`: passed.
+- `npm run build`: passed.
+
+## Non-goals
+
+- Removing or renaming existing commands or MCP tools.
+- Reworking retrieval ranking, metadata storage, or the SQLite schema.
+- Splitting files solely to reduce line counts.
+- Adding agent feedback, automatic memory promotion, or project-state
+  fingerprinting.

package/docs/specs/SPEC-018-interaction-inspection-and-recall-integrity.md

@@ -0,0 +1,164 @@
+# SPEC-018 — Interaction inspection and recall integrity
+
+- **ID**: SPEC-018
+- **Cluster**: Core, Capture, Search, Memory, MCP
+- **Status**: Implemented
+- **Date**: 2026-10-24
+- **Source**: Implemented interaction retrieval in `src/commands/search.ts`, `src/commands/show.ts`, and `src/interaction/detail.ts`, with behavior covered in `src/commands/__tests__/`.
+
+## Purpose
+
+Make the stored unit of PH useful and verifiable: a person can find one
+interaction, inspect its complete prompt, response, capture metadata, and
+derived analysis, and tell whether capture enrichment or configured remote
+delivery succeeded. Keep the daily workflow small while making retrieval and
+durable project knowledge consistent across adapters.
+
+## Scope
+
+- Add one CLI detail operation and make export formats preserve the complete
+  interaction record.
+- Make full-text search cover analyzed summary/insight text as well as the raw
+  prompt and response.
+- Make task-aware context retrieval share one project-scoped policy across CLI,
+  chat, and MCP knowledge checks.
+- Keep per-interaction analysis in prompt metadata. Only explicit `close` and
+  MCP `save_decision` promotion write active project memories and summaries.
+- Persist bounded lifecycle outcomes for optional background analysis and
+  configured per-capture remote push; expose recent capture state through an
+  advanced CLI diagnostic.
+- Keep everyday help focused on setup, search, detail, and optional context.
+  Existing maintenance and integration commands stay available through
+  `ph help --all`.
+
+## Decisions
+
+1. `ph show <id>` is the canonical single-interaction view. It prints complete
+   stored prompt and response, source/capture fields, all supported analysis
+   metadata, and an explicit analysis state. Missing response and missing
+   analysis are rendered as such, not silently omitted. `--json` emits the
+   complete record and decoded metadata. `--archive` resolves an archived row
+   using the ID printed by archived search.
+2. `ph search` remains a compact discovery list and prints an actionable
+   `ph show <id>` hint. `--full` means full prompt and response. Text queries
+   also match analyzed summary, key insights, and technical decisions. Search
+   ranking and current project/global scope rules remain stable.
+3. `ph export <id>` formats all preserve prompt and response. Markdown and JSON
+   also preserve complete capture and analysis metadata; plain text includes
+   clear Prompt and Response headings. `--archive` exports an archived row.
+4. `analyzeAll` and background analysis update only per-interaction metadata;
+   they do not write `memories` or `project_summaries`. Existing saved memories
+   are retained. Only `promoteProjectKnowledge`, reached through CLI `close`
+   and MCP `save_decision`, creates active curated project knowledge.
+5. `retrieveTaskContext` owns task embedding, project scope, shared sources, and
+   explicit recent-context fallback. CLI task `context`, `chat`, and MCP
+   `check_project_knowledge` use this policy. `chat` embeds the user's actual
+   task prompt. General project-context retrieval without a task remains a
+   separate non-semantic operation.
+6. Capture records use backward-compatible optional metadata fields for
+   analysis and remote-push lifecycle states. States are bounded enums and
+   failure text is a safe category, never raw provider output or credentials.
+   `ph status` shows the latest captures and their available state; it does not
+   claim that a configured hook delivered an interaction that is absent.
+7. SPEC-018 supersedes SPEC-017's “no new user-facing capability” acceptance
+   only for `ph show`, complete `ph export`/`--full`, and advanced `ph status`.
+   It does not remove or rename existing commands, MCP tools, or configuration.
+   The only new table column is rebuildable search text derived from existing
+   metadata; the migration must preserve all prompt/response records and be
+   idempotent.
+
+## Data contract
+
+`PromptMetadata` may contain:
+
+- `analysis_status`: `pending`, `complete`, or `failed` when analysis was
+  requested; absent on legacy records is inferred as `complete` when analysis
+  fields exist and otherwise `not requested`.
+- `analysis_error`: one safe category (`worker_launch_failed`,
+  `provider_unavailable`, `analysis_failed`, or `analysis_persistence_failed`).
+- `remote_sync_status`: `pending`, `complete`, or `failed` for configured
+  per-capture pushes; absent on old records is `unknown` when a remote is
+  configured and `not configured` otherwise.
+- `remote_sync_error`: `push_failed` only; raw response bodies are not stored.
+- `technical_decisions`: per-interaction analyzed decisions, alongside
+  `summary`, `key_insights`, `quality`, and `relevance`.
+
+The FTS index receives a derived text field built from analysis summary, key
+insights, and technical decisions. The existing prompt, response, and tool
+fields remain indexed/scoped as before. Rebuilding FTS from existing rows must
+be safe and idempotent.
+
+## Acceptance criteria
+
+- **G1 — Full detail**: Given a stored interaction with prompt, response,
+  metadata, and analysis fields, when `ph show <id>` runs, then all are printed
+  without truncation. Given missing response or analysis, then the output names
+  the missing state and returns successfully.
+- **G1a — Archived detail**: Given an archived search result ID, when
+  `ph show <id> --archive` or `ph export <id> --archive` runs, then the original
+  prompt, response, and metadata are shown without changing the archive.
+- **G2 — Complete export**: Given a stored interaction, when each supported
+  export format runs, then prompt and response are present; JSON includes the
+  full entry and decoded metadata. Unknown IDs and formats fail with a useful
+  message.
+- **G3 — Search to detail**: Given a matching result, when `ph search` prints
+  it, then the ID and `ph show <id>` instruction are visible. `--full` prints
+  complete prompt and response. Search still honors current-project default,
+  `--all`, explicit project, filters, and the requested result limit.
+- **G4 — Search derived analysis**: Given only a summary, insight, or technical
+  decision contains a query term, when search runs, then the source interaction
+  is returned. Existing prompt/response matches and BM25 ordering continue to
+  work. Updating metadata updates indexed analysis text; rebuilding old DBs
+  indexes existing metadata without losing prompt history.
+- **G5 — One active knowledge writer**: Given manual or background analysis,
+  when it succeeds, then the interaction metadata is updated and no active
+  memory or project summary is created. Given `close` approval or MCP
+  `save_decision`, then the existing provenance validation and transactional
+  promotion write the curated memory and summary. Existing memories remain
+  readable.
+- **G6 — Shared task retrieval**: Given a task prompt in a project, when CLI
+  `context`, `chat`, or MCP `check_project_knowledge` retrieves context, then
+  they use the same task embedding prefix, project scope, sources, and labeled
+  fallback behavior. `chat` includes the user's task in the semantic query.
+  Retrieval remains read-only.
+- **G7 — Lifecycle status**: Given background analysis is requested, when a
+  capture is stored, then its state becomes pending and transitions to complete
+  or a safe failed category. Spawn failure, missing provider, empty analysis,
+  provider error, and persistence error are observable. Given configured remote
+  push, then its state transitions from pending to complete/failed. State writes
+  do not overwrite unrelated metadata.
+- **G8 — Diagnostic**: Given captured records exist, when `ph status` runs, then
+  it shows a bounded recent list with timestamp, tool, project, response
+  presence, analysis state, and remote state. It does not print prompt or
+  response content. `status` is listed in advanced help, not the short default
+  guide.
+- **G9 — Small product surface**: The short guide documents setup, search,
+  inspecting a result with `show`, and optional task context. Existing advanced
+  commands remain available behind `ph help --all`.
+- **G10 — Compatibility**: Existing DB files open without destructive rewrite;
+  existing IDs, prompt/response text, config, commands, and MCP tool names stay
+  intact. Analysis-derived FTS data is rebuilt transactionally or through an
+  idempotent migration.
+
+## Implementation map
+
+| Concern | Files |
+|---|---|
+| Detail command, compact search, export/help | `src/cli.ts`, `src/commands/{show,search,export,status}.ts`, `src/display/print.ts` |
+| Record and search index | `src/types.ts`, `src/db/index.ts`, `src/db/__tests__/phdb.test.ts` |
+| Analysis lifecycle and trust | `src/analyzer/index.ts`, `src/commands/{analyze,background-analyze,log}.ts`, `src/background/analyzer.ts` |
+| Task retrieval | `src/knowledge/task-context.ts`, `src/commands/{context,chat}.ts`, `src/mcp/tools/projects.ts` |
+| MCP detail projection | `src/mcp/tools/prompts.ts`, `src/mcp/tools/format.ts` |
+| Contracts and user docs | `docs/specs/SPEC-001-architecture-cli.md`, `SPEC-003-capture-modes.md`, `SPEC-005-search.md`, `SPEC-016-operational-memory.md`, `docs/ph-manual.md`, `README.md` |
+
+## Verification
+
+Focused GWT tests cover detail/export fidelity, FTS metadata indexing and
+migration, memory ownership, retrieval parity/fallback, lifecycle transitions,
+and status output. Completion requires `npm test`, `npm run lint`,
+`npx tsc --noEmit`, and `npm run build`.
+
+## Related
+
+SPEC-001, SPEC-002, SPEC-003, SPEC-005, SPEC-006, SPEC-007, SPEC-011,
+SPEC-016, and SPEC-017.

package/docs/specs/SPEC-019-network-capture-and-ranking-integrity.md

@@ -0,0 +1,36 @@
+# SPEC-019 — Network, capture, and retrieval integrity
+
+- **ID**: SPEC-019
+- **Cluster**: Capture, Sync, Search, CLI
+- **Status**: Implemented
+- **Date**: 2026-10-24
+- **Source**: Implemented network, sync, capture, and ranking contracts in `src/server/`, `src/sync/`, `src/capture/lifecycle.ts`, and related tests.
+
+## Purpose
+
+Close the remaining correctness and exposure gaps at PH's network and live-capture seams. The everyday local workflow stays simple; optional HTTP and sync paths must fail safely and preserve every acknowledged interaction.
+
+## Scope and decisions
+
+1. **HTTP exposure**: `ph server` listens on loopback by default and requires a configured API key before opening the listener. Every endpoint except `/health` requires that key. Health never returns the database path. Request bodies have a documented byte limit; malformed/oversized requests return bounded client errors without leaking internal exception text. A non-loopback deployment still requires explicit `--host` and the same authentication; cross-machine deployments require a trusted network or TLS termination.
+2. **Push pagination**: local prompts are selected by monotonically increasing local row ID, not timestamp. The remote push cursor is scoped to both the normalized target URL and the persistent source database ID. Pages are split into HTTP bodies no larger than the server byte limit; the outer cursor advances only after every subpage and record is acknowledged or deduplicated. A failed subpage leaves the outer page retryable. Retrying is safe because `sync_hash` is idempotent.
+3. **Pull pagination**: the server returns prompts in ascending remote row-ID order, a continuation cursor, and `hasMore`. The client persists an opaque target-and-local-database-scoped ID cursor only after a page is fully inserted or deduplicated. Switching either target or local database starts at row zero. Missing cursor fields are a compatibility error, not permission to silently fall back to a capped timestamp pull. Legacy timestamp cursors trigger a full idempotent scan from row zero.
+4. **Capture completion**: hooks/direct `ph log`, inline wrapper, and interactive PTY wrapper share lifecycle initialization and configured analysis/remote-push effects. Invalid remote URLs mark the optional push failed without blocking local persistence or tool execution. Wrapper records identify a live capture owner; bulk sync stops before a live record so it cannot publish a partial response or advance past it. Markers from exited processes are cleared and the locally captured partial record remains eligible. Inline wrapper stdout is forwarded unchanged and persisted as the response; exit code is preserved. Live pushes have a five-second timeout. Empty responses are still captured and lifecycle work is dispatched.
+5. **Search ranking**: raw prompt/response FTS and derived-metadata FTS retain separate indexes. Results use Reciprocal Rank Fusion (RRF, fixed `k=60`) across the two ranked lists, then timestamp descending and ID descending for deterministic ties. The raw-only relative BM25 order remains unchanged. Project-scoped CLI semantic search loads project embeddings through one metadata join instead of issuing one prompt query per embedding.
+6. **Everyday help and docs**: short help lists optional `ph context "task"`; SPEC-010, SPEC-003, SPEC-005, SPEC-018, SPEC-ISSUES, README, manual, and AGENTS describe the implemented security, cursor, lifecycle, and ranking contracts.
+
+## Acceptance criteria
+
+- **G1 — Fail-closed HTTP**: Without `remoteApiKey`, `ph server` fails before listening. Default host is loopback. With a key, health returns status only; all data endpoints require the Bearer key. Invalid JSON returns 400, an oversized body returns 413, and internal errors do not expose exception details.
+- **G2 — Lossless push**: Given more than one row-ID page, same-timestamp rows, late-imported lower-timestamp rows, bodies that exceed the byte limit, and a server response with per-record errors, every local row remains eligible until acknowledged. Live captures are held until completion; completed subpages checkpoint only after all subrequests are acknowledged. A database switch resets its cursor to zero. Retries do not duplicate acknowledged records.
+- **G3 — Lossless pull**: Given over 10,000 remote rows, pagination imports all rows. Equal timestamps do not skip records. Legacy timestamp-only or database-unscoped config starts an idempotent full scan. A target or local database change starts at row zero. A server without continuation support fails clearly.
+- **G4 — Shared live capture effects**: Given configured analysis and remote sync, direct log, inline wrapper, and PTY wrapper mark pending and dispatch the same effects. A malformed optional remote URL does not block local persistence or launching the wrapped CLI. A concurrent bulk push stops before active captures and resumes after completion; abandoned owner markers are reclaimed. Inline stdout is both displayed and stored as response. Exit status is preserved. Empty output is explicitly stored and still gets lifecycle completion.
+- **G5 — Search ranking**: Raw-only queries preserve BM25 order; analysis-only queries find the correct source record; mixed-source queries follow RRF with deterministic tie breaks. Updating analysis metadata keeps the derived index fresh.
+- **G6 — Product help**: Default help documents setup, search, show, and optional task context; status and maintenance remain advanced.
+- **G7 — Migration and compatibility**: Existing prompt/response rows and sync dedup hashes remain intact. Legacy sync config replays idempotently instead of advancing a lossy timestamp cursor. HTTP/API clients receive an actionable upgrade error when pagination support is missing.
+- **G8 — Bounded startup work**: Given a database whose search-text migration is complete, When another `PhDB` instance opens, Then it does not scan and parse all rows with empty derived metadata again. The database identity remains stable across reopen and differs across database files.
+- **G9 — Scoped semantic loading**: Given embeddings across multiple projects, When CLI semantic search selects one project, Then only that project's vectors are loaded by a joined query and no per-vector `getById` lookup is issued.
+
+## Verification
+
+Verification completed: `npm test`, `npm run lint`, `npx tsc --noEmit`, and `npm run build` pass. Focused tests cover server startup/auth/body bounds, pull pagination over 10,000 records, partial push retry and late old-timestamp records, database-scoped push/pull cursors, active-capture deferral and stale-marker recovery, byte-sized push subpages, invalid-URL local capture and real inline child execution, legacy metadata backfill with blank rows and no repeated scan, project-scoped embedding loads, inline response/exit forwarding, and mixed-index ranking. HTML link validation and `git diff --check` pass.

package/docs/specs/SPEC-INDEX.md

@@ -7,27 +7,32 @@ 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.
+· Sync (server/remote) · MCP · Import · Analytics · Config. The history TUI was
+retired on 2026-10-22; SPEC-012 is retained as a decision record.
 
 ## 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-001 | Architecture & CLI dispatch | Core | **Implemented (plain-text daily workflow)** | `src/commands/__tests__/operational-memory.test.ts` |
+| SPEC-002 | Database layer (PhDB) | DB | **Implemented; stable DB identity and one-time metadata migration (SPEC-019)** | `src/db/__tests__/phdb.test.ts` |
+| SPEC-003 | Capture modes (pty/inline/hooks/log) | Capture | **Implemented; shared live lifecycle (SPEC-019)** | `src/runner/inline.test.ts`, `src/capture/lifecycle.ts` |
 | SPEC-004 | Filter pipeline & metadata | Core | **Implemented (baseline)** | — |
-| SPEC-005 | Search (FTS + filters + semantic) | Search | **Implemented (baseline)** | — |
+| SPEC-005 | Search (FTS + filters + semantic) | Search | **Implemented; cross-index RRF and scoped CLI vector loading (SPEC-019)** | `src/db/__tests__/phdb.test.ts`, `src/commands/__tests__/search.test.ts` |
 | 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-010 | Remote sync (server + push/pull) | Sync | **Implemented; database-scoped cursors, active-capture barrier, byte-bounded pages (SPEC-019)** | `src/server/__tests__/server.test.ts`, `src/commands/__tests__/remote.test.ts`, `src/sync/__tests__/client.test.ts` |
 | SPEC-011 | MCP server | MCP | **Implemented (baseline)** | — |
-| SPEC-012 | TUI browser | TUI | **Implemented (baseline)** | — |
+| SPEC-012 | Interactive history browser | Retired UI | **Retired 2026-10-22** | — |
 | 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)** | — |
+| SPEC-016 | Operational memory workflow (context/close/MCP provenance) | Memory, CLI, MCP | **Implemented** | `src/commands/__tests__/operational-memory.test.ts`, `src/mcp/__tests__/server.test.ts` |
+| SPEC-017 | Internal architecture consolidation (CLI surface gate, MCP modules, DB repositories) | Core, DB, MCP | **Implemented** | `src/knowledge/`, `src/mcp/tools/`, `src/db/{memory,archive}-repository.ts` |
+| SPEC-018 | Interaction inspection and recall integrity | Core, Capture, Search, Memory, MCP | **Implemented** | `src/commands/__tests__/`, `src/db/__tests__/phdb.test.ts`, `src/context/__tests__/context.test.ts`, `src/mcp/__tests__/server.test.ts` |
+| SPEC-019 | Network, capture, and retrieval integrity | Capture, Sync, Search, CLI | **Implemented; follow-up edge cases closed** | `src/server/__tests__/server.test.ts`, `src/capture/__tests__/lifecycle.test.ts`, `src/commands/__tests__/remote.test.ts`, `src/sync/__tests__/client.test.ts`, `src/commands/__tests__/search.test.ts`, `src/db/__tests__/phdb.test.ts` |
 
 ## Cross-cutting findings (SPEC-ISSUES.md)
 

package/docs/specs/SPEC-ISSUES.md

@@ -37,12 +37,10 @@ Status: Open → assigned SPEC / fixed.
   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.
+  analysis, sessions, context, capture, importer formats, PTY response cleanup,
+  HTTP endpoints, and MCP tool calls over an in-memory protocol transport. The
+  retired Ink browser coverage is historical; current product tests target the
+  plain-text CLI, capture adapters, and command modules.
 - **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
@@ -73,23 +71,21 @@ Status: Open → assigned SPEC / fixed.
 - **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-011 — BrowseApp remains a large module (RETIRED 2026-10-22)** — the
+  history TUI and its Ink/React screens were removed when PH moved to the
+  plain-text daily workflow. This finding no longer applies to the product.
 - **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)** —
+- **ISSUE-013 — server auth was conditional and fail-open (FIXED 2026-10-24)** —
   `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.
+  `/health` with `Authorization: Bearer <key>` (timingSafeEqual). Since
+  SPEC-019, startup refuses to run without a key; default bind is loopback and
+  `/health` returns status only (src/server/index.ts). 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
@@ -98,6 +94,87 @@ Status: Open → assigned SPEC / fixed.
   duplicates formatting logic that the TUI ListEntry also renders; two code paths
   for entry display can drift (e.g. badges, truncation rules).
 
+## Follow-up findings (2026-10-24)
+
+- **ISSUE-019 — sync cursors were shared across local databases (FIXED 2026-10-24)** —
+  global configuration stored push/pull cursors keyed only by remote target, so
+  switching `PH_DB` or `db-path` could skip records. Each SQLite file now has a
+  persistent UUID included in both cursor comparisons; older cursor shapes replay
+  idempotently from row zero (`src/db/index.ts:69-79,129`,
+  `src/commands/remote.ts:44-49,118-126`). Regression coverage:
+  `src/commands/__tests__/remote.test.ts` switches local database files and
+  verifies both push and pull restart at row zero.
+- **ISSUE-020 — invalid optional remote URL interrupted local capture (FIXED 2026-10-24)** —
+  `syncTarget()` could throw before the local row was inserted or the wrapped
+  CLI started. Remote URLs are validated when configured; environment overrides
+  are handled as a failed remote effect while local capture continues
+  (`src/sync/protocol.ts:25-40`, `src/capture/lifecycle.ts:24-40,63-68`,
+  `src/commands/config.ts:174-175`). Regression coverage:
+  `src/config/__tests__/config.test.ts`, `src/capture/__tests__/lifecycle.test.ts`,
+  and `src/runner/inline.test.ts` verify validation, local persistence, and that
+  the wrapped child still runs and its response is saved.
+- **ISSUE-021 — bulk sync could publish a live partial response (FIXED 2026-10-24)** —
+  wrappers persist prompts before their response is complete. Captures now carry
+  a local owner PID; bulk push stops before a live capture and clears markers
+  left by exited owners, preventing the partial and final versions from being
+  imported as separate interactions (`src/commands/wrap.ts:53-63`,
+  `src/runner/inline.ts:50-58`, `src/capture/lifecycle.ts:24-40,49-55`,
+  `src/commands/remote.ts:68-104,205-212`). Regression coverage:
+  `src/commands/__tests__/remote.test.ts` verifies a live partial response is
+  withheld and only the completed response is pushed.
+- **ISSUE-022 — fixed record-count pages could exceed the request-body cap (FIXED 2026-10-24)** —
+  a 500-row request could exceed the server's 32 MiB limit and repeat unchanged.
+  The client now splits outer pages by serialized byte size before sending and
+  aggregates acknowledgements; an individually oversized record gets an
+  explicit ID and size error (`src/sync/client.ts:9-29,32-50`,
+  `src/sync/protocol.ts:4-5`). Regression coverage in
+  `src/sync/__tests__/client.test.ts` verifies byte limits, record order,
+  acknowledgement aggregation, and a clear error for a single oversized row.
+- **ISSUE-023 — search metadata backfill scanned the prompt table on every open (FIXED 2026-10-24)** —
+  rows with legitimately empty derived text were selected and parsed on each
+  command. The backfill now runs once under an immediate transaction and records
+  its completion in `ph_meta` (`src/db/index.ts:185-205`).
+  `src/db/__tests__/phdb.test.ts` upgrades a legacy database with analyzed and
+  blank rows, verifies searchable derived text, and ensures a later open does
+  not query the blank rows again.
+- **ISSUE-024 — project semantic search issued one query per vector (FIXED 2026-10-24)** —
+  CLI search loaded all legacy embeddings and called `getById` for each vector
+  to filter the current project. `SemanticIndex.loadProject()` now filters via
+  one join, and the CLI loads only scoped vectors (`src/db/semantic-index.ts:43-50`,
+  `src/db/index.ts:518-524`, `src/commands/search.ts:107-110`). Regression
+  coverage in `src/db/__tests__/phdb.test.ts` checks project membership through
+  the joined query; `src/commands/__tests__/search.test.ts` verifies the CLI
+  chooses the scoped loader and never loads all vectors for a project search.
+- **ISSUE-025 — remote database replacement is invisible to sync cursors (OPEN 2026-10-24)** —
+  Push/pull cursors are keyed by normalized URL and local database UUID, but
+  `/api/sync/pull` returns only row IDs and continuation state. If the remote
+  SQLite database is replaced behind the same URL, a stored high cursor treats
+  its new low IDs as already read; push likewise does not replay old local rows.
+  Config also stores only one push and one pull cursor, so switching A→B→A
+  replays A from row zero (idempotently, but with a full network scan).
+  The global `remoteLastPush` and `remoteLastPull` fields can also report another
+  target's time (`src/commands/remote.ts:111-119, 127-170, 183-199`,
+  `src/server/index.ts:161-170`, `src/config/index.ts:23-26`). Add remote
+  database identity to the protocol and scope all checkpoint/status state to it.
+- **ISSUE-026 — semantic retrieval paths can disagree and vectors lack provenance (OPEN 2026-10-24)** —
+  The CLI loads the legacy BLOB table, computes cosine similarity, and applies
+  a fixed `0.3` cutoff, while context, HTTP, and MCP use `sqlite-vec`. The same
+  query can return a different set and order by consumer. Stored vectors do not
+  identify the configured embedding model; changing `ollama-embed-model` changes
+  query vectors, and `ph embed-all` leaves existing vectors untouched
+  (`src/commands/search.ts:95-120`, `src/db/semantic-index.ts:8-50`,
+  `src/commands/embed-all.ts:6-32`, `src/config/index.ts:20`). Unify the search
+  contract and make vector profile changes explicit.
+- **ISSUE-027 — database migration work scales with history (OPEN 2026-10-24)** —
+  Every `PhDB` constructor calls `migrate()`. Routine opens still select prompts
+  missing `$schema_version` by parsing the JSON field and retry legacy column
+  migrations. On the first open after the derived-search migration, the marker
+  prevents repeats, but every blank `search_metadata` row is loaded and updated
+  individually inside one immediate transaction. Large databases can pay O(n)
+  startup work and hold a write lock during that first backfill
+  (`src/db/index.ts:72-80, 164-205, 209-217`). Version and bound the migration
+  steps, and avoid rewriting rows with no searchable analysis text.
+
 ## Issue-to-spec map
 
 | Issue | Spec (fix target) | Status |
@@ -108,15 +185,24 @@ Status: Open → assigned SPEC / fixed.
 | 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) |
+| 007 | SPEC-002/003/005/009/010/011/012/013/014 | Fixed 2026-10-09; test scope updated after TUI retirement |
 | 008 | — (docs) | Open |
 | 009 | — (chore) | Open |
 | 010 | SPEC-001 | Fixed 2026-08-08 |
-| 011 | SPEC-012 | Open |
+| 011 | SPEC-012 | Retired 2026-10-22 |
 | 012 | SPEC-010 | Fixed 2026-08-08 (shared syncHash, args-aware, backward compatible) |
-| 013 | SPEC-010 | Fixed 2026-08-08 (auth gate on createRequestHandler) |
+| 013 | SPEC-010/019 | Fixed 2026-10-24 (mandatory key, loopback default, health redaction) |
 | 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 |
+| 019 | SPEC-010/019 | Fixed 2026-10-24 (persistent local database UUID scopes push/pull cursors) |
+| 020 | SPEC-003/019 | Fixed 2026-10-24 (invalid optional remote URL cannot block local capture) |
+| 021 | SPEC-003/010/019 | Fixed 2026-10-24 (active and abandoned capture markers handled before bulk push) |
+| 022 | SPEC-010/019 | Fixed 2026-10-24 (push subpages bounded by serialized request bytes) |
+| 023 | SPEC-002/019 | Fixed 2026-10-24 (one-time transactional search metadata backfill) |
+| 024 | SPEC-005/019 | Fixed 2026-10-24 (project embedding load uses one metadata join) |
+| 025 | SPEC-010/019 | Open (remote database replacement is not detected; timestamps are global) |
+| 026 | SPEC-005/008 | Open (semantic search engines diverge; vectors lack model profile) |
+| 027 | SPEC-002 | Open (routine database initialization repeats history scans) |

package/hooks/claude/README.md

@@ -25,7 +25,7 @@ Add (or update) the `hooks` section in your `~/.claude/settings.json` file:
         "hooks": [
           {
             "type": "command",
-            "command": "/Users/gianluca/.claude/ph-hook.sh",
+            "command": "$HOME/.claude/ph-hook.sh",
             "async": true
           }
         ]

package/hooks/codex/README.md

@@ -1,6 +1,6 @@
 # Codex CLI hook for ph
 
-The hook imports the active Codex rollout after each completed turn. Codex supplies the transcript path to the `Stop` hook; `ph` pairs user messages with the assistant response and deduplicates turns already captured.
+The hook imports the active Codex rollout after each completed turn. Codex supplies the transcript path to the `Stop` hook; `ph` pairs user messages with the assistant response and deduplicates turns already captured. The hook supplies the active CLI working directory to the importer so captures are associated with the project where Codex was launched, even when the transcript records a synthetic directory.
 
 ## Install
 

package/hooks/codex/ph-hook.sh

@@ -4,11 +4,12 @@ set -u
 
 INPUT=$(cat)
 TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | node -e 'let s="";process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{try{process.stdout.write(JSON.parse(s).transcript_path||"")}catch{}})' 2>/dev/null)
+WORKDIR="$PWD"
 if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
   printf '{}\n'
   exit 0
 fi
 
-ph import codex --file "$TRANSCRIPT_PATH" >/dev/null 2>&1 || true
+ph import codex --file "$TRANSCRIPT_PATH" --workdir "$WORKDIR" >/dev/null 2>&1 || true
 printf '{}\n'
 exit 0

package/hooks/gemini/README.md

@@ -24,7 +24,7 @@ Add (or update) the `hooks` section in your `~/.gemini/settings.json` file:
         "hooks": [
           {
             "type": "command",
-            "command": "/Users/gianluca/.gemini/ph-hook.sh"
+            "command": "$HOME/.gemini/ph-hook.sh"
           }
         ]
       }

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@gi4nks/ph",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Transparent CLI wrapper that captures and indexes AI prompts",
   "type": "module",
   "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
   "bin": {
     "ph": "dist/cli.js"
   },
@@ -55,12 +58,11 @@
     "eval:retrieval": "tsx scripts/eval-context-retrieval.ts"
   },
   "dependencies": {
-    "@gi4nks/ink": "^1.5.0",
+    "@gi4nks/wise": "^2.1.0",
     "@lydell/node-pty": "^1.2.0-beta.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "ai": "^7.0.136",
     "better-sqlite3": "^12.8.0",
-    "ink": "^7.0.5",
-    "react": "^19.2.7",
     "sqlite-vec": "^0.1.9",
     "zod": "^4.3.6"
   },
@@ -72,12 +74,9 @@
     "@semantic-release/npm": "^13.1.5",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^25.9.3",
-    "@types/react": "^19.2.7",
     "@typescript-eslint/eslint-plugin": "^8.58.2",
     "@typescript-eslint/parser": "^8.58.2",
     "eslint": "^9.39.5",
-    "eslint-plugin-react": "^7.37.5",
-    "eslint-plugin-react-hooks": "^7.0.1",
     "semantic-release": "^25.0.3",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",