@jeffober/thatch 0.1.26 → 0.1.27

package/docs/qa/use-cases/README.md

@@ -1,51 +0,0 @@
-# Use Cases
-
-Manual end-to-end QA scenarios for thatch. Each use case has preconditions,
-steps, and expected results. These cover behavior the automated suite can't:
-real opencode sessions, the real embedding model, and the CLI.
-
-Newer use cases carry an _Automatable_ note flagging which are pure
-file/IPC/CLI contracts ready to graduate into `bun:test` integration tests.
-
-| Use case | Covers |
-|----------|--------|
-| [UC-001](UC-001-memory-roundtrip.md) | Remember/recall across sessions, store naming, duplicate rejection |
-| [UC-002](UC-002-dedup-cycle.md) | Full dedup review cycle: find, classify, resolve, mark checked |
-| [UC-003](UC-003-extraction-nudge.md) | Tool buffering → extraction nudge → agent-driven fact saving |
-| [UC-004](UC-004-cli-inspection.md) | CLI commands, arg validation, env overrides |
-| [UC-005](UC-005-setup-install.md) | `thatch setup --claude`/`--cursor`, project-local + `--global`, idempotent re-run, legacy hook migration |
-| [UC-006](UC-006-cursor-hook-lifecycle.md) | Cursor hook lifecycle: `buffer-tool` (`conversation_id`), `flush-tools --json`, queue peek |
-| [UC-007](UC-007-recall-nudge.md) | Prompt-aware recall nudge — opencode in-process + Claude/Cursor sideband paths; no telemetry |
-| [UC-008](UC-008-hygiene-heartbeat.md) | Hygiene heartbeat: stale 90d, orphaned branches, pending dedup; advisory, agent-driven |
-| [UC-009](UC-009-flush-tools-tiers.md) | `flush-tools` three-tier priority (extraction > recall > write) + sideband degradation |
-| [UC-010](UC-010-prime.md) | `thatch prime` CLI dispatch chain (opencode/Cursor/claude), child exit code |
-| [UC-011](UC-011-write-time-similarity-warning.md) | Write-time warning never blocks; merge or mark-distinct reconciliation |
-| [UC-012](UC-012-model-migration.md) | `THATCH_MODEL` change: old memories skipped (not corrupted) until re-saved |
-| [UC-013](UC-013-compaction-context.md) | Compaction context re-familiarization (opencode-only) |
-| [UC-014](UC-014-skill-install-drift.md) | Skill install: 20 shared vs 21 opencode; drift overwritten on re-setup |
-| [UC-015](UC-015-env-override-matrix.md) | `THATCH_DB_PATH`, `XDG_CONFIG_HOME`, `CLAUDE_CONFIG_DIR`, `THATCH_QUEUE_DIR`, `THATCH_RECALL_THRESHOLD`, `THATCH_MODEL` |
-| [UC-016](UC-016-concurrent-session-isolation.md) | Per-session extraction isolation (in-memory + file queue); shared stateless sideband |
-| [UC-017](UC-017-buffer-tool-vs-buffer-batch.md) | `buffer-batch` (Claude, `tool_calls[]`+`session_id`) vs `buffer-tool` (Cursor, single+`conversation_id`) |
-| [UC-018](UC-018-mcp-startup-setup-detection.md) | MCP startup detects missing/broken setup instructions and warns the agent |
-| [UC-019](UC-019-archived-memory-lifecycle.md) | Archive, search exclusion, update guard, unarchive |
-| [UC-020](UC-020-extraction-escalation.md) | Nudge escalation (polite → insistent → ALL-CAPS), buffer persistence, `extraction_done` accept/complete |
-| [UC-021](UC-021-prediction-autofire.md) | Prediction auto-fire: matcher scores prompt, prediction nudge injected alongside recall |
-| [UC-022](UC-022-prediction-dedup.md) | Prediction create-on-existing: dedup finds match, links edge without disconfirming |
-| [UC-023](UC-023-prediction-confidence-model.md) | Bayesian confidence math: create, confirm, soft (weak disconfirm), disconfirm signals |
-| [UC-024](UC-024-prediction-delete.md) | Prediction delete with cascade, provenance inspection, not-found handling |
-
-## Template
-
-```markdown
-# UC-NNN: Title
-
-**Preconditions**
-- State of the system before the test
-
-**Steps**
-1. Action
-2. Action
-
-**Expected**
-- Observable outcome
-```

package/docs/qa/use-cases/UC-001-memory-roundtrip.md

@@ -1,20 +0,0 @@
-# UC-001: Remember and recall across sessions
-
-**Preconditions**
-- thatch configured as a plugin in opencode (npm or local path)
-- Working directory is a git repo with an `origin` remote
-
-**Steps**
-1. In an opencode session, ask the agent to remember a distinctive fact, e.g.
-   "remember that our staging DB lives at staging-db.internal:5432".
-2. Confirm the agent calls `thatch_memory_remember` and reports `[saved]`.
-3. End the session. Start a fresh session in the same repo.
-4. Ask a related question: "where does staging data live?"
-
-**Expected**
-- The agent calls `thatch_memory_recall` and surfaces the saved fact with a
-  similarity score.
-- `thatch list` (CLI) shows the memory in the repo's store (named
-  `owner/repo` from the git remote), not in `global`.
-- Saving the same label again without `overwrite: true` is rejected with an
-  error naming the label and store.

package/docs/qa/use-cases/UC-002-dedup-cycle.md

@@ -1,23 +0,0 @@
-# UC-002: Deduplication review cycle
-
-**Preconditions**
-- A store containing at least two memories with near-identical content
-  (e.g. save "the API rate limit is 100 req/min" twice under different labels)
-
-**Steps**
-1. Ask the agent to check for duplicate memories.
-2. Agent calls `thatch_find_duplicates`; the similar pair is reported with a
-   score above the 0.85 default threshold.
-3. Agent loads the `thatch-dedup-classifier` skill and classifies the pair.
-4. For a true duplicate: agent merges content via
-   `thatch_memory_remember(overwrite: true)` on the better label and deletes
-   the other via `thatch_memory_forget`.
-5. For a false positive (unrelated/supplement/contradiction kept as-is):
-   agent records the verdict via `thatch_dedup_mark_checked`.
-6. Ask the agent to check for duplicates again.
-
-**Expected**
-- After step 4 or 5, `thatch_find_duplicates` no longer reports the pair.
-- Overwriting either memory of a checked pair afterwards clears the verdict:
-  the pair becomes eligible for re-reporting.
-- Forgetting a memory clears all verdicts involving it.

package/docs/qa/use-cases/UC-003-extraction-nudge.md

@@ -1,56 +0,0 @@
-# UC-003: Fact extraction from tool activity
-
-_Automatable: buffer/peek/escalation contract could be tested with the mock
-client and a synthetic tool call sequence._
-
-**Preconditions**
-- thatch plugin active in an opencode session
-
-**Steps**
-1. Do some real work: have the agent read files, run commands, edit code —
-   any non-`thatch_*`, non-`skill`, non-`task` tool activity.
-2. The agent's turn ends and the session goes idle.
-
-**Expected (opencode — direct extraction, primary path)**
-- The plugin's `event` hook catches `session.status` idle with pending tool
-  interactions and calls `triggerExtraction`: creates a child session via
-  `client.session.create({ parentID })` and prompts it via
-  `client.session.promptAsync` (or `client.session.prompt` fire-and-forget
-  if the env var is unset).
-- The `extracting` set suppresses the nudge in `chat.message` while the
-  child runs — no nudge text appears in the user's conversation.
-- The child loads `thatch-fact-extractor` and saves durable facts via
-  `thatch_memory_remember` — or saves nothing if the activity was routine.
-- A `thatch_memory_remember` call in the child drains the parent's snapshot
-  entries from the buffer (via `consumeSnapshot` with `parentSnapshots`).
-- When the child goes idle, the parent's snapshot entries are drained
-  (covering no-save runs where no memory was written), the child session is
-  deleted, and a toast notification fires with the extraction metrics
-  (`[thatch] new: N, updated: M, deleted: K`, or
-  `[thatch] extraction complete — nothing to save`).
-- If `triggerExtraction` throws, the `extracting` set is cleared and the
-  nudge fires as a fallback on the next `chat.message` (see below).
-
-**Expected (fallback nudge path — opencode when direct extraction fails,
-and all MCP hosts)**
-- The agent's context for the next message includes a `[thatch]` nudge
-  carrying a JSON payload summarizing the buffered tool interactions (tool
-  name, title, truncated args/output).
-- The buffer is **not** drained on nudge delivery — it persists until the
-  agent writes a memory or accepts it by calling `thatch_extraction_done`.
-  Accepting quiets the nudge while holding the entries until the extractor
-  completes; a child extractor that errors or is deleted requeues them. If
-  the nudge is ignored, the next message carries a repeat nudge, escalating
-  in urgency:
-  - 1st-2nd miss: polite tone
-  - 3rd consecutive miss (missedCount=2): insistent (directive) tone
-  - 4th+ consecutive miss (missedCount>=3): ALL-CAPS tone
-  The counter resets when the buffer drains (memory write) or is accepted
-  (`thatch_extraction_done`).
-- A `thatch_memory_remember` call in a child sub-agent session also drains
-  the parent's buffer (via the `childToParent` Map), so dispatching the
-  fact-extractor as a background task clears the parent's queue.
-- Two concurrent sessions never see each other's interactions in a nudge.
-- The agent's own `thatch_*` tool calls never appear in a payload (no
-  feedback loop). `skill` and `task` tool calls are also excluded (buffering
-  them would create a nudge → skill load → buffer → nudge loop).

package/docs/qa/use-cases/UC-004-cli-inspection.md

@@ -1,22 +0,0 @@
-# UC-004: Inspecting stores from the shell
-
-**Preconditions**
-- Bun on PATH; thatch installed (`npm i -g @jeffober/thatch` or a checkout)
-- At least one memory saved via opencode
-
-**Steps**
-1. `thatch stores` — list all stores.
-2. `cd` into the project's repo, then `thatch list` — labels default to the
-   repo's store.
-3. `thatch show <label>` — full content.
-4. `thatch search "some topic"` — semantic search (downloads/loads the real
-   embedding model on first use; prints a loading notice to stderr).
-5. `thatch search some topic` (unquoted, multi-word).
-6. `thatch search "query" bogus-store`.
-
-**Expected**
-- Steps 1–4 behave as described; search results are ranked with scores.
-- Step 5 exits non-zero with an error telling you to quote the query —
-  it must NOT silently search a store named "topic".
-- Step 6 exits non-zero listing the stores that do exist.
-- All commands respect `THATCH_DB_PATH` and `$XDG_CONFIG_HOME`.

package/docs/qa/use-cases/UC-005-setup-install.md

@@ -1,34 +0,0 @@
-# UC-005: Setup install (Claude Code and Cursor)
-
-**Preconditions**
-- Thatch installed and `bun` on PATH
-- Target config dirs writable (`$XDG_CONFIG_HOME`, `$CLAUDE_CONFIG_DIR`, `~/.cursor`)
-
-**Steps**
-1. From a project root: `thatch setup --claude`
-2. From the same project root: `thatch setup --cursor`
-3. Repeat both commands (re-run idempotence and drift recovery)
-4. Add a non-thatch hook to `.claude/settings.json` and `.cursor/hooks.json`,
-   then re-run setup
-5. From elsewhere: `thatch setup --cursor --global`, then `thatch setup --claude --global`
-
-**Expected**
-- `--claude` project-local writes `.mcp.json` (`mcpServers.thatch`, stdio + `["mcp"]`),
-  appends a thatch block to `CLAUDE.md` bracketed by start/end markers (replaced, not
-  duplicated, on re-run), writes `.claude/settings.json` hooks (`SessionStart` -> `thatch reminder`,
-  `PostToolBatch` -> `thatch buffer-batch`, `UserPromptSubmit` -> `thatch flush-tools`), and installs
-  **20 shared skills** (no code-review coordinator) to `$CLAUDE_CONFIG_DIR/skills/` — user-scoped
-  even in project-local mode.
-- `--cursor` project-local writes `.cursor/mcp.json`, appends to `AGENTS.md`, writes
-  `.cursor/hooks.json` in the **flat format** (`{version:1, hooks:{...}}`): `sessionStart` ->
-  `thatch reminder --json`, `postToolUse` -> `thatch buffer-tool`, `beforeSubmitPrompt` ->
-  `thatch flush-tools --json`; and installs 20 shared skills to `~/.cursor/skills/`.
-- Re-run is idempotent: instructions are not duplicated, thatch hooks are replaced (not appended),
-  and non-thatch hooks are preserved. A legacy `thatch echo` hook is replaced with `flush-tools`.
-- `--global` (Claude) writes `~/.claude/CLAUDE.md` + `~/.claude/settings.json` but **no project
-  `.mcp.json`** — it prints a `claude mcp add --scope user` command instead. `--global` (Cursor)
-  writes `~/.cursor/mcp.json`, `~/.cursor/AGENTS.md`, `~/.cursor/hooks.json`, `~/.cursor/skills/`.
-
-_Automatable: yes — file presence and shape assertions on `.mcp.json`, `hooks.json`,
-`CLAUDE.md`/`AGENTS.md` blocks, and the skills directory. `setup.test.ts` already covers the
-unit contract; this is the end-to-end runbook version._

package/docs/qa/use-cases/UC-006-cursor-hook-lifecycle.md

@@ -1,32 +0,0 @@
-# UC-006: Cursor hook lifecycle
-
-**Preconditions**
-- `thatch setup --cursor` has run; `.cursor/mcp.json` registers the thatch MCP server
-- A store with at least one memory (for the recall tier)
-
-**Steps**
-1. Start a Cursor agent session; the MCP server boots and opens its sideband socket.
-2. Have the agent run a non-thatch tool (e.g. read a file). The `postToolUse` hook runs
-   `thatch buffer-tool`, reading Cursor's stdin (`conversation_id`), and appends one
-   interaction to the session's queue file. Stdout is empty.
-3. Have the agent run a thatch tool (`mcp__thatch__memory_list`). The hook fires but filters
-   it out — nothing is appended.
-4. Submit a prompt. The `beforeSubmitPrompt` hook runs `thatch flush-tools --json`.
-5. Submit the next prompt with no fresh tool activity since step 4.
-
-**Expected**
-- `buffer-tool` normalizes `conversation_id` to a safe session file name and appends exactly one
-  interaction per call; thatch's own `mcp__thatch__*` tools never enter the queue (no self-echo).
-- `flush-tools` peeks the queue first (extraction tier): prints the JSON payload wrapped for
-  Cursor as `additional_context`. The queue is **not** deleted — it persists until the agent
-  writes a memory or calls `thatch_extraction_done`, so ignored nudges repeat and escalate
-  (polite to insistent to ALL-CAPS) on subsequent calls.
-- With the queue empty and the sideband socket live, a semantically matching prompt yields a
-  recall nudge using the bare `memory_recall` tool name; below `THATCH_RECALL_THRESHOLD`
-  (default 0.55), no nudge.
-- `buffer-tool` and `flush-tools --json` output is the shape Cursor's `additional_context`
-  field consumes.
-
-_Automatable: partial — the `buffer-tool` and `flush-tools --json` CLI contracts are fully
-automatable; the live Cursor agent loop (booting the MCP server, the agent acting on a nudge)
-is manual._

package/docs/qa/use-cases/UC-007-recall-nudge.md

@@ -1,31 +0,0 @@
-# UC-007: Prompt-aware recall nudge
-
-**Preconditions**
-- A store with a memorable fact, e.g. "staging DB at staging-db.internal:5432"
-- An opencode session AND (separately) a Claude Code / Cursor session with the MCP server
-  running and the sideband socket live
-
-**Steps**
-
-**opencode path**
-1. Send a prompt matching the memory, e.g. "where does staging data live?"
-2. Send an unrelated prompt.
-3. Send a prompt shorter than 10 characters.
-
-**Claude Code / Cursor path**
-4. With the MCP server running and the sideband socket live, send a matching prompt (queue empty).
-5. Stop the MCP server; send a matching prompt.
-
-**Expected**
-- opencode: the `chat.message` hook embeds the prompt text (skipped when shorter than 10 chars),
-  searches `db.search([repo, global])`; a match at or above 0.55 pushes a synthetic nudge part
-  with labels and scores (singular wording for one match; up to two labels plus "etc." for more).
-- No match above threshold produces no nudge.
-- The nudge uses `db.search`, not `db.recall`, so **no recall telemetry is stamped** — usage
-  tracking fires only on explicit `thatch_memory_recall` / CLI `search`, not on nudges.
-- Claude Code / Cursor: `flush-tools` asks the warm MCP server via the sideband socket; the
-  returned labels become a nudge using the bare `memory_recall` name. With the MCP server down,
-  the recall nudge is absent (UC-009 covers the write-nudge fallback).
-
-_Automatable: partial — the sideband embed + search round-trip and threshold logic are
-unit-tested in `sideband.test.ts`; a live agent observing and acting on the nudge is manual._

package/docs/qa/use-cases/UC-008-hygiene-heartbeat.md

@@ -1,26 +0,0 @@
-# UC-008: Hygiene heartbeat
-
-**Preconditions**
-- A store with: one memory not updated or recalled in 90+ days; one memory scoped to a git
-  branch that no longer exists; two near-duplicate memories (similarity > 0.85)
-- A second, clean store for the negative case
-
-**Steps**
-1. `thatch hygiene` (from the repo)
-2. `thatch reminder` (Claude Code hook shape) and `thatch reminder --json` (Cursor)
-3. Start an opencode session and a Claude Code / Cursor session (the session-start path)
-4. Run the same commands from a directory that is **not** a git repo
-
-**Expected**
-- The report names three signals — pending duplicate pairs, stale-memory count, orphaned-branch
-  memory count — and **only the non-zero ones**. A fully healthy store prints "Store is healthy."
-  (or `null`) and the reminder omits the hygiene block entirely.
-- Both `reminder` shapes fold the hygiene block into the session-start text only when it is non-null.
-- Outside a git repo, the orphaned-branch check is **skipped** — a missing branch list would
-  otherwise make everything look orphaned; stale and dup signals still report.
-- Signals are advisory: thatch never deletes or merges memories itself. The agent acts on the
-  nudge to fix the store, by the same `memory_forget` / `dedup_mark_checked` tools as UC-002.
-
-_Automatable: yes — `thatch hygiene` and `hygieneReport()` are pure functions over the DB and
-git state (`hygiene.test.ts` covers the unit contract); the live session-injection path is
-manual._

package/docs/qa/use-cases/UC-009-flush-tools-tiers.md

@@ -1,33 +0,0 @@
-# UC-009: flush-tools tier priority and sideband degradation
-
-**Preconditions**
-- A Claude Code / Cursor session; `.mcp.json` and hooks installed
-- At least one memory for the recall tier to match
-- For the failure modes: a way to stop the MCP server and to leave a stale socket file
-
-**Steps**
-1. Put buffered non-thatch tool interactions in the queue (via `buffer-tool` / `buffer-batch`),
-   then run `thatch flush-tools --json`.
-2. With the queue empty and the MCP server running, send a prompt matching a memory (recall tier),
-   then a prompt below threshold.
-3. Stop the MCP server; run `flush-tools` with an empty queue.
-4. Leave a stale socket file from a crashed MCP server; run `flush-tools`.
-5. Make the sideband server hang (> 2 s); run `flush-tools`.
-
-**Expected**
-- Tiers fire in strict priority — **extraction > recall > write** — at most one nudge per call:
-  - extraction: queue non-empty -> JSON payload. The queue is peeked, not
-    deleted; it persists until a memory write or `extraction_done` (drains via
-    `consumeQueue` in `appendBatch`).
-  - recall: queue empty, socket live, match at or above `THATCH_RECALL_THRESHOLD` (default 0.55)
-    -> nudge with match labels; below threshold -> no nudge.
-  - write: socket unavailable, no matches, or socket error -> static
-    "did you learn anything worth persisting?" nudge.
-- Sideband failure **never blocks** the agent: server down, a stale socket file, and a > 2 s
-  timeout all degrade to the write nudge. A stale socket file left by a crash is cleaned up on
-  connection error.
-- `--json` wraps whichever nudge fires for Cursor's `additional_context`; plain stdout for Claude Code.
-
-_Automatable: yes — `flush-tools` is a deterministic CLI contract and sideband failure modes
-(server down, stale socket, timeout) plus tier ordering are filesystem/IPC only, with no LLM in
-the loop._

package/docs/qa/use-cases/UC-010-prime.md

@@ -1,25 +0,0 @@
-# UC-010: thatch prime
-
-**Preconditions**
-- Thatch installed and `bun` on PATH
-- At least one of: opencode (for `opencode run`), Cursor (`agent` CLI), or Claude Code
-  (`claude`) on PATH
-
-**Steps**
-1. From a project root, run `thatch prime`
-2. Let the selected child CLI run the `thatch-project-primer` skill to completion
-3. After it finishes, inspect the project store (`thatch list`)
-
-**Expected**
-- `prime` resolves the first available CLI in order — `opencode run`, then
-  `agent -p --approve-mcps` (Cursor), then `claude` — and spawns it with the project-primer
-  prompt.
-- The primer skill recalls existing memories first, investigates the codebase from multiple
-  angles, and writes foundational memories via `thatch_memory_remember` (project vs global
-  assignment per its own rules), then runs dedup afterward.
-- `prime` exits with the **child process's exit code** (0 on success).
-- If no supported CLI is on PATH, `prime` fails fast with a clear error rather than spawning
-  nothing.
-
-_Automatable: partial — the CLI dispatch selection (which child, which flags, exit-code
-pass-through) is automatable; the LLM's real investigation and memory writing are manual._

package/docs/qa/use-cases/UC-011-write-time-similarity-warning.md

@@ -1,24 +0,0 @@
-# UC-011: Write-time similarity warning
-
-**Preconditions**
-- A store with a memory, e.g. `API rate limit` -> "the API rate limit is 100 req/min"
-- A second, similar memory not yet saved
-
-**Steps**
-1. Save the second memory under a different label with similar content, without
-   `overwrite: true`.
-2. Read the tool's response.
-
-**Expected**
-- The save **succeeds** (`[saved] ...`) — the warning never blocks. The response
-  also carries a warning listing the existing memory with a similarity score and
-  instructions to reconcile.
-- Two reconciliation paths both work:
-  - Merge: `memory_remember` the merged content with `overwrite: true` on the
-    better label, then `memory_forget` the other. The survivor has the combined
-    content; the deleted label is gone.
-  - Mark distinct: `dedup_mark_checked` the pair as `unrelated`. A subsequent
-    `find_duplicates` no longer reports the pair.
-
-_Automatable: yes — the "save proceeds + warning lists similar entries" contract
-and both reconciliation paths are pure tool/DB calls with no LLM in the loop._

package/docs/qa/use-cases/UC-012-model-migration.md

@@ -1,28 +0,0 @@
-# UC-012: THATCH_MODEL migration (mixed embedding dimensions)
-
-**Preconditions**
-- A store with memories embedded by a model of dimension A (e.g. the default
-  384-dim `bge-small-en-v1.5`)
-- A second model available whose vectors have a **different** dimension
-
-**Steps**
-1. `export THATCH_MODEL=<other-model>` (different vector dimension).
-2. Start a fresh session. `memory_list` and `memory_show` an old memory by label.
-3. `memory_recall` for a topic that matches an old memory.
-4. Save a new memory with the new model; `memory_recall` for it.
-5. `memory_show` an old memory and inspect its `model` tag.
-
-**Expected**
-- `list` and `show` still return the old memories — the data is intact, **not
-  corrupted and not deleted**.
-- `recall` returns **no matches** for the old memories: entries whose vector
-  dimension differs from the query are skipped, not scored. This is a silent
-  skip, not an error.
-- The new memory embeds at the new dimension and is recallable.
-- `show` reveals the old memories carry the old model tag while new ones carry
-  the new tag. There is **no automatic re-embedding** — old memories stay
-  invisible to search until re-saved.
-
-_Automatable: yes — dimension-skip and data-intact assertions are pure DB calls;
-use two `MockEmbeddingModel` instances with different dimensions (no network, no
-real model download)._

package/docs/qa/use-cases/UC-013-compaction-context.md

@@ -1,25 +0,0 @@
-# UC-013: Compaction context (opencode-only)
-
-**Preconditions**
-- An opencode session that grows long enough to trigger context compaction
-- Several memories already stored in the repo's store
-
-**Steps**
-1. Work in the session until opencode compacts the context window.
-2. Inspect the compaction output.
-3. After compaction, ask the agent something that should use a memory tool.
-
-**Expected**
-- The compaction output includes the thatch re-familiarization context block
-  pushed by `experimental.session.compacting` — it reminds the agent that
-  `thatch_memory_recall` exists and that memories persist.
-- After compaction, the agent still knows the memory tools exist and uses them
-  (it does not "forget" thatch just because the window was summarized).
-- This behavior is **opencode-only**. Claude Code's `PostCompact` hook is
-  side-effects only and cannot inject context; Cursor has no equivalent hook.
-  See `docs/dev/mcp-parity.md` for the gap and its mitigation (CLAUDE.md /
-  AGENTS.md persists through compaction; the `SessionStart` recall reminder
-  runs again after compaction in Claude Code).
-
-_Automatable: no — requires a live opencode compaction event. The hook's string
-content is unit-tested, but actual compaction injection is manual._

package/docs/qa/use-cases/UC-014-skill-install-drift.md

@@ -1,28 +0,0 @@
-# UC-014: Skill install and drift recovery
-
-**Preconditions**
-- Thatch installed; the host's skills directory empty
-- `bun` on PATH
-
-**Steps**
-1. `thatch setup --claude` (and/or start an opencode session, and/or
-   `thatch setup --cursor`).
-2. List the skills directory.
-3. Edit one `SKILL.md` file locally to introduce drift.
-4. Re-run `setup` (or restart opencode).
-5. Check whether the `thatch-code-review` coordinator skill is present.
-
-**Expected**
-- Claude Code and Cursor install exactly **20 shared skills** to the skills
-  dir — the coordinator (`thatch-code-review`) is **absent** (it needs
-  sub-agents, which those hosts lack).
-- opencode installs **21** — the 20 shared plus the coordinator.
-- The locally edited `SKILL.md` is **overwritten** with the canonical content
-  on the next `setup`/init (drift detection: a file is only rewritten when its
-  content differs from the definition). Unrelated skill files are untouched.
-- Skills never land in the worktree — always under the user-scoped config dir
-  (`~/.claude/skills`, `~/.cursor/skills`, `$XDG_CONFIG_HOME/opencode/skills`).
-
-_Automatable: yes — file presence, count (20 vs 21), content-diff-overwrite, and
-coordinator host-gating are all file assertions (`setup.test.ts` already covers
-the unit contract)._

package/docs/qa/use-cases/UC-015-env-override-matrix.md

@@ -1,28 +0,0 @@
-# UC-015: Environment variable override matrix
-
-**Preconditions**
-- Writable temp directories; `bun` on PATH
-
-**Steps**
-Set each variable and confirm the effect at the documented resolution point.
-
-| Variable | Set to | Expected effect |
-|----------|--------|------------------|
-| `THATCH_DB_PATH` | a temp file path | the SQLite DB is created there (CLI + plugin + MCP) |
-| `XDG_CONFIG_HOME` | a temp dir | the default DB (`$XDG_CONFIG_HOME/thatch/thatch.db`) and opencode skill dir move there; the real `~/.config` is untouched |
-| `CLAUDE_CONFIG_DIR` | a temp dir | `thatch setup --claude --global` writes CLAUDE.md, settings.json, and skills under that dir; project-local keeps project paths but skills under the custom dir |
-| `THATCH_QUEUE_DIR` | a temp dir | extraction-queue JSONL files land there instead of `$XDG_CACHE_HOME/thatch/queue` |
-| `THATCH_RECALL_THRESHOLD` | a low value (e.g. `0.2`) | the prompt-aware recall nudge fires for weaker matches (a prompt that matched nothing at 0.55 now surfaces results) |
-| `THATCH_MODEL` | a different model name | new memories carry the new model tag and vector dimension; old memories become invisible to search (see UC-012) |
-
-**Expected**
-- Each override takes effect at the point the docs describe (see
-  `docs/dev/setup-and-hooks.md` and the dev README config section). None require
-  a restart beyond the process that reads them.
-- `THATCH_DB_PATH` and `XDG_CONFIG_HOME` change the **same** sideband socket
-  path (it is a hash of the resolved DB path) — so a hook process and the MCP
-  server must both resolve the same DB path or they miss each other.
-
-_Automatable: yes — env resolution is deterministic and side-effect-free;
-`setup.test.ts` already covers `CLAUDE_CONFIG_DIR`; the rest follow the same
-shape._

package/docs/qa/use-cases/UC-016-concurrent-session-isolation.md

@@ -1,37 +0,0 @@
-# UC-016: Concurrent session isolation
-
-**Preconditions**
-- Two opencode sessions in the same repo (A and B)
-- (Separately) two Claude Code / Cursor hook processes with different session IDs
-
-**Steps**
-
-**opencode (in-memory buffer)**
-1. In session A, run a non-thatch tool (the extraction ring buffer records it).
-2. In session B, send a message — `chat.message` runs.
-3. In session A, send a message — `chat.message` runs.
-
-**Claude Code / Cursor (file-backed queue)**
-4. Hook process for session A calls `buffer-tool`/`buffer-batch`.
-5. Hook process for session B calls `buffer-tool`/`buffer-batch`.
-6. `flush-tools` is invoked for session A, then for session B.
-
-**Sideband (shared warm model)**
-7. Both sessions' `flush-tools` connect to the same sideband socket.
-
-**Expected**
-- **No cross-session bleed** in either path: session B's `chat.message` produces
-  no nudge from session A's buffered interaction; session B's message only sees
-  its own buffer. The in-memory `ExtractionPipeline` and the file-backed queue are
-  both keyed by session ID.
-- `flush-tools` for session A peeks only A's queue file (does not delete it); a
-  second flush for A returns the same content with an escalated missed-nudge
-  counter (the queue persists until a memory write or `extraction_done`). Session
-  B's queue file is untouched and is peeked on its own flush.
-- The sideband socket is **shared** (one warm MCP server) but **stateless per
-  query**: each request embeds a fresh prompt and returns its own matches. Two
-  concurrent match requests do not interfere.
-
-_Automatable: yes — `extraction.test.ts` (in-memory per-session) and
-`extract-queue.test.ts` (file-backed per-session) already cover isolation; the
-sideband is a stateless request/response so concurrency is trivially safe._

package/docs/qa/use-cases/UC-017-buffer-tool-vs-buffer-batch.md

@@ -1,27 +0,0 @@
-# UC-017: buffer-tool vs buffer-batch contract
-
-**Preconditions**
-- A Claude Code setup (`PostToolBatch` -> `buffer-batch`) and a Cursor setup
-  (`postToolUse` -> `buffer-tool`)
-
-**Steps**
-1. **Claude Code**: a `PostToolBatch` fires with a `tool_calls` array (several
-   tools, one a `mcp__thatch__*` call) and a `session_id`.
-2. **Cursor**: a `postToolUse` fires for a single tool with a `conversation_id`.
-3. Run `flush-tools` for both.
-
-**Expected**
-- `buffer-batch` (Claude Code) reads the `tool_calls` array and `session_id`,
-  appends all interactions to the session's JSONL queue, filters out
-  `mcp__thatch__*` calls, and caps at 20 (oldest dropped). It is **silent**.
-- `buffer-tool` (Cursor) reads **one** tool call, normalizes `conversation_id`
-  to a safe filename (unsafe chars -> underscore), appends that single
-  interaction, filters `mcp__thatch__*`, same 20 cap. Also silent.
-- Both write the same `ToolInteraction` shape to the same JSONL format, so
-  `flush-tools` drains them identically and `buildExtractionPayload` produces an
-  identical contract for the fact-extractor skill.
-- Thatch's own tools never appear in either queue (no self-echo feedback loop).
-
-_Automatable: yes — `extract-queue.test.ts` covers both shapes (batch with
-`tool_calls` and single-tool), the `mcp__thatch__*` filter, the 20 cap, and
-back-compat with `buildExtractionPayload`._

package/docs/qa/use-cases/UC-018-mcp-startup-setup-detection.md

@@ -1,38 +0,0 @@
-# UC-018: MCP startup setup detection
-
-**Preconditions**
-- Thatch installed and `bun` on PATH
-- MCP server launched by Claude Code (`thatch mcp` with `CLAUDE_PROJECT_DIR` set)
-  or Cursor (`thatch mcp` with `CURSOR_PROJECT_DIR` set)
-
-**Steps**
-1. Start a Claude Code session in a project where `thatch setup --claude` was
-   never run (no `CLAUDE.md` with thatch markers, neither local nor global).
-2. Call any thatch tool (e.g. `mcp__thatch__store_list`).
-3. Repeat in a project where setup was run but `CLAUDE.md` was edited externally
-   and the thatch block's end marker was deleted.
-4. Repeat in a project where setup was run correctly.
-5. Repeat all steps for Cursor (substituting `--cursor`, `AGENTS.md`,
-   `CURSOR_PROJECT_DIR`).
-
-**Expected**
-- **Not-installed**: The first `tools/call` response is prepended with a
-  warning: "[thatch] Thatch is running as an MCP server but has not been set
-  up for Claude Code. ... Tell the user to run: thatch setup --claude". The
-  warning also appears on stderr. Subsequent tool responses are clean (warning
-  is one-shot).
-- **Markers-broken**: The first `tools/call` response is prepended with a
-  warning naming the corrupted file and instructing the user to run
-  `thatch setup` (or manually remove the corrupted block and re-run).
-- **Installed**: No warning. Tool responses are clean from the first call.
-- **Cursor**: Same behavior, with "Cursor" substituted for "Claude Code" and
-  `thatch setup --cursor` in the message. When both `CURSOR_PROJECT_DIR` and
-  `CLAUDE_PROJECT_DIR` are set, Cursor detection takes priority.
-- **No env var**: When neither `CURSOR_PROJECT_DIR` nor `CLAUDE_PROJECT_DIR` is
-  set (manual `thatch mcp` invocation), `checkSetup` returns `null` and no
-  warning is emitted.
-
-_Automatable: yes — `setup.test.ts` already covers the unit contract (10 tests
-in the `checkSetup` describe block: null, local, global, not-installed,
-markers-broken, local priority, Cursor variants, Cursor priority). This is the
-end-to-end runbook version._

package/docs/qa/use-cases/UC-019-archived-memory-lifecycle.md

@@ -1,36 +0,0 @@
-# UC-019: Archived memory lifecycle
-
-_Automatable: archive guard + search/dedup/staleness exclusion are pure DB
-contract testable with a temp DB._
-
-**Preconditions**
-- thatch plugin active in an opencode session (or CLI with a test store)
-
-**Steps**
-1. Save a memory scoped to a feature branch:
-   `thatch_memory_remember` with `branch: "feature-x"`, `label: "Feature X design decisions"`, `content: "..."`.
-2. Merge or delete the branch. Save a consolidated archived memory:
-   `thatch_memory_remember` with `overwrite: true`, `archived: true`,
-   `branch: "feature-x"`, same label, consolidated content.
-3. Search for content related to the archived memory:
-   `thatch_memory_recall` with a relevant query (no `includeArchived`).
-4. Search again with `includeArchived: true`.
-5. Attempt to update the archived memory's content without passing the
-   `archived` param.
-6. Unarchive the memory: `thatch_memory_remember` with `overwrite: true`,
-   `archived: false`.
-
-**Expected**
-- Step 2: the memory is saved with `archived: true`. The `archived` column is
-  set to 1 in the database.
-- Step 3: the archived memory does NOT appear in search results — `search`
-  filters `WHERE archived = 0`.
-- Step 4: the archived memory DOES appear when `includeArchived: true` is
-  passed.
-- Step 5: the tool returns an error: `"Feature X design decisions" is
-  archived. Pass archived: true to keep it archived, or archived: false to
-  unarchive it.` The content is NOT updated.
-- Step 6: the memory is unarchived (`archived` column set to 0). It reappears
-  in normal search results.
-- `find_duplicates` does not surface archived memories as candidates.
-- `staleEntryCount` (hygiene) does not count archived memories as stale.