@jeffober/thatch 0.1.16 → 0.1.18

package/docs/dev/mcp-parity.md

@@ -18,11 +18,11 @@ This document maps the feature parity and documents the remaining gaps.
 
 | Feature | OpenCode plugin | Claude Code MCP + hooks | Cursor MCP + hooks | Parity |
 |---------|----------------|------------------------|---------------------|--------|
-| **Tools** (8, single source of truth) | Plugin tool registration, `thatch_` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix | **Full** |
+| **Tools** (9, single source of truth) | Plugin tool registration, `thatch_` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix | **Full** |
 | **System prompt** (store names, usage rules) | `experimental.chat.system.transform` — dynamic, repo baked in at runtime | CLAUDE.md static text appended by `thatch setup`; repo auto-detected by the MCP server at startup | AGENTS.md static text appended by `thatch setup`; repo auto-detected at startup | **Approximate** — static text persists through compaction, so the agent retains the usage instructions, but the dynamic per-turn refresh is lost |
 | **Session-start reminder** (recall nudge + hygiene heartbeat) | `session.created` event → `client.session.prompt` injects a synthetic message | `SessionStart` hook → `thatch reminder`; stdout becomes context | `sessionStart` hook → `thatch reminder --json`; output is `additional_context` JSON | **Full** |
 | **Compaction context** (re-familiarize after compaction) | `experimental.session.compacting` hook appends context to the compaction output | `PostCompact` hook — side-effects only, **cannot inject context** | No equivalent hook | **Gapped** — see below |
-| **Extraction nudge** (buffer tool calls, inject JSON payload) | `tool.execute.after` buffers non-thatch tool calls in-process; `chat.message` flushes the buffer as a synthetic text part | `PostToolBatch` → `thatch buffer-batch` (file-backed JSONL queue); `UserPromptSubmit` → `thatch flush-tools` drains the queue and prints the nudge | `postToolUse` → `thatch buffer-tool` (single-tool, file-backed queue); `beforeSubmitPrompt` → `thatch flush-tools --json` | **Full** (file-backed) — timing differs: the nudge arrives at the **start** of the next turn in Claude Code/Cursor, not at the end of the current one like opencode's `chat.message` |
+| **Extraction nudge** (buffer tool calls, inject JSON payload) | `tool.execute.after` buffers non-thatch, non-skill, non-task tool calls in-process; `chat.message` peeks the buffer (does not drain it) and injects a synthetic text part | `PostToolBatch` → `thatch buffer-batch` (file-backed JSONL queue); `UserPromptSubmit` → `thatch flush-tools` peeks the queue and prints the nudge (does not drain — the queue persists until a memory write or `extraction_done`) | `postToolUse` → `thatch buffer-tool` (single-tool, file-backed queue); `beforeSubmitPrompt` → `thatch flush-tools --json` | **Full** (file-backed) — timing differs: the nudge arrives at the **start** of the next turn in Claude Code/Cursor, not at the end of the current one like opencode's `chat.message` |
 | **Prompt-aware recall nudge** | `chat.message` hook embeds the prompt with the in-process warm model, searches `db.search()`, pushes a nudge part if matches ≥ threshold | `UserPromptSubmit` hook → `thatch flush-tools` connects to the MCP server's sideband socket; the warm server embeds + searches; hook prints the nudge or falls back to the write nudge | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — sideband socket gives cold hook processes access to the warm MCP server's model |
 | **Skills** | Installed to `$XDG_CONFIG_HOME/opencode/skills` at plugin init (shared **+** opencode-only) | Installed to `$CLAUDE_CONFIG_DIR/skills/` by `thatch setup` (shared only) | Installed to `~/.cursor/skills/` by `thatch setup` (shared only) | **Full** — same SKILL.md format; the code-review coordinator is opencode-only (needs sub-agents) |
 | **Store detection** (repo identity from git remote) | `worktree` parameter from the opencode plugin | `CLAUDE_PROJECT_DIR` env (set by Claude Code for stdio MCP servers) | `CURSOR_PROJECT_DIR` then `CLAUDE_PROJECT_DIR` then cwd | **Full** |
@@ -64,13 +64,17 @@ explicit "re-familiarization" nudge for hosts without a compaction hook.
 
 OpenCode's extraction pipeline works by:
 
-1. `tool.execute.after` buffers every non-thatch tool call into a per-session
-   in-memory array (max 20 interactions).
-2. On the next `chat.message`, the buffer is flushed and a synthetic text part
-   carrying the JSON payload is injected into the conversation (end of the
-   current turn).
+1. `tool.execute.after` buffers every non-thatch, non-skill, non-task tool
+   call into a per-session in-memory array (max 20 interactions).
+2. On the next `chat.message`, the buffer is **peeked** (not drained) and a
+   synthetic text part carrying the JSON payload is injected into the
+   conversation. The buffer persists until the agent writes a memory or calls
+   `thatch_extraction_done`, so ignored nudges repeat and escalate (polite →
+   insistent → ALL-CAPS) via the `missedNudges` counter.
 3. The agent sees the nudge, loads the `thatch-fact-extractor` skill, and saves
-   durable facts via `thatch_memory_remember`.
+   durable facts via `thatch_memory_remember`. A memory write in the session
+   (or a child sub-agent via the `childToParent` Map) or `thatch_extraction_done`
+   drains the buffer and resets the missed-nudge counter.
 
 Claude Code and Cursor use a **file-backed** queue (`src/extract-queue.ts`)
 because hooks fire one-shot with no cross-call state:
@@ -80,7 +84,10 @@ because hooks fire one-shot with no cross-call state:
    (max 20, oldest dropped). These commands are silent — no stdout — so the
    agent loop is not delayed.
 2. `UserPromptSubmit` / `beforeSubmitPrompt` runs `thatch flush-tools`, which
-   drains the queue and prints the JSON payload. This arrives at the **start**
+   peeks the queue (does not drain it) and prints the JSON payload. The queue
+   persists until the agent writes a memory or calls `thatch_extraction_done`,
+   so ignored nudges accumulate and escalate (polite → insistent → ALL-CAPS)
+   via the file-backed missed-nudge counter. This arrives at the **start**
    of the next turn (before the model processes the prompt), not at the end of
    the current one.
 
@@ -106,7 +113,7 @@ Claude Code / Cursor session
 │   ├── stdio JSON-RPC (tool calls)
 │   └── Unix socket sideband (embed + search for hooks)
 ├── UserPromptSubmit / beforeSubmitPrompt hook → thatch flush-tools [--json]
-│   ├── drains the file-backed extraction queue (existing)
+│   ├── peeks the file-backed extraction queue (does not drain)
 │   ├── connects to sideband socket
 │   ├── sends prompt text
 │   ├── receives match labels + scores

package/docs/dev/setup-and-hooks.md

@@ -19,7 +19,7 @@ The plugin entry (`src/index.ts`) registers these hooks in code:
 | `experimental.chat.system.transform` | `{}` | `{ system: string[] }` | Pushes the system prompt (store names, usage rules). |
 | `experimental.session.compacting` | `{ sessionID }` | `{ context: string[] }` | Marks the session as compacting, pushes re-familiarization context. |
 | `experimental.compaction.autocontinue` | `{ sessionID }` | `{ enabled: boolean }` | Clears the compacting flag so `chat.message` nudges resume post-compaction. |
-| `tool.execute.after` | `{ tool, sessionID, callID, args }` | `{ title, output, metadata }` | Buffers non-`thatch_` tool calls into the in-memory extraction ring buffer (max 20). |
+| `tool.execute.after` | `{ tool, sessionID, callID, args }` | `{ title, output, metadata }` | Buffers non-`thatch_`, non-`skill`, non-`task` tool calls into the in-memory extraction ring buffer (max 20). |
 | `chat.message` | `{ sessionID, messageID }` | `{ message, parts }` | Two tiers: extraction nudge if pending, else prompt-aware recall nudge. Skipped while the session is compacting. |
 | `event` (`session.created`) | `{ event: { type, properties: { info: { id } } } }` | — | Calls `client.session.prompt` with the reminder + hygiene heartbeat. |
 | `dispose` | — | — | Closes the DB. |
@@ -60,10 +60,10 @@ in the repo; only skills are user-scoped.
 |-------|---------|--------|------|
 | `SessionStart` | `thatch reminder` | plain text to stdout (becomes context) | Recall instructions + hygiene heartbeat |
 | `PostToolBatch` | `thatch buffer-batch` | **silent** (no stdout) | Appends a batch of tool calls to the file-backed JSONL queue |
-| `UserPromptSubmit` | `thatch flush-tools` | nudge text to stdout | Drains queue (extraction nudge), else recall nudge via sideband, else write nudge |
+| `UserPromptSubmit` | `thatch flush-tools` | nudge text to stdout | Peeks queue (extraction nudge), else recall nudge via sideband, else write nudge |
 
 `PostToolBatch` is silent so the agent loop is not delayed; the buffered
-content is invisible until `UserPromptSubmit` flushes it.
+content is invisible until `UserPromptSubmit` peeks it.
 
 ## Cursor (MCP server + hooks)
 
@@ -100,7 +100,7 @@ is honored for symmetry and forward-compatibility. Cursor has no equivalent of
 |-------|---------|--------|------|
 | `sessionStart` | `thatch reminder --json` | `{ additional_context: "..." }` | Recall + heartbeat, JSON-wrapped for Cursor |
 | `postToolUse` | `thatch buffer-tool` | **silent** | Appends a **single** tool call to the file-backed queue |
-| `beforeSubmitPrompt` | `thatch flush-tools --json` | JSON `additional_context` | Drains queue, else recall via sideband, else write nudge |
+| `beforeSubmitPrompt` | `thatch flush-tools --json` | JSON `additional_context` | Peeks queue, else recall via sideband, else write nudge |
 
 Differences from Claude Code:
 

package/docs/dev/skills.md

@@ -21,9 +21,9 @@ description: Extract durable project facts ... Use when ...
 - `description` drives when the agent loads the skill (both opencode and
   Cursor auto-discover skills and use the description for relevance).
 
-## The 16 skills
+## The 19 skills
 
-**Shared (15)** — installed everywhere; no sub-agents required:
+**Shared (18)** — installed everywhere; no sub-agents required:
 
 | Skill | Role |
 |-------|------|
@@ -42,6 +42,9 @@ description: Extract durable project facts ... Use when ...
 | `thatch-change-walkthrough` | Explain a change to the user as a teaching walkthrough: resolve the delta, research each affected workflow at the merge-base, teach current behavior, then overlay the modifications with file:line citations and analogies. |
 | `thatch-code-walkthrough` | Explain a feature, module, or workflow to the user as a teaching walkthrough: identify the code area (optionally from a branch or PR), research how it works, teach it with file:line citations and analogies, list the key files. |
 | `thatch-session-reflection` | End-of-session memory recording (project, user, tools, self). |
+| `pr-description` | Draft PR descriptions with instructional-design scaffolding (SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES) and bold+italic emphasis for scanning. |
+| `ticket-description` | Draft ticket/issue descriptions with instructional-design scaffolding (SYNOPSIS / PROBLEM / BACKGROUND / PROPOSED APPROACH / ACCEPTANCE CRITERIA / RELEASE PLAN / VALIDATION / DEPENDENCIES / NOTES). |
+| `split-overlarge-pr` | Split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main. |
 
 **opencode-only (1)** — the coordinator needs sub-agent support:
 
@@ -81,7 +84,7 @@ The synthesizer reuses the same verification rigor but has its own structure
 ## The two arrays
 
 ```ts
-const SHARED_SKILLS: SkillDef[] = [ /* 15 skills above */ ];
+const SHARED_SKILLS: SkillDef[] = [ /* 18 skills above */ ];
 const OPENCODE_ONLY_SKILLS: SkillDef[] = [ /* code-review coordinator */ ];
 ```
 

package/docs/qa/README.md

@@ -91,7 +91,7 @@ correctness on `README.md` and `docs/` excluding `docs/plans/`; see
 
 ### `tests/plugin.test.ts`
 
-- `server` export shape: all eight tools, every hook present, tools carry
+- `server` export shape: all nine tools, every hook present, tools carry
   description/args/execute
 - System transform and compaction hooks append their text
 - `tool.execute.after` → `chat.message` extraction round-trip: nudge carries

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

@@ -14,7 +14,7 @@ file/IPC/CLI contracts ready to graduate into `bun:test` integration tests.
 | [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 drain |
+| [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 |
@@ -22,11 +22,13 @@ file/IPC/CLI contracts ready to graduate into `bun:test` integration tests.
 | [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: 10 shared vs 11 opencode; drift overwritten on re-setup |
+| [UC-014](UC-014-skill-install-drift.md) | Skill install: 18 shared vs 19 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` drain |
 
 ## Template
 

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

@@ -1,11 +1,14 @@
 # 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 tool activity.
+   any non-`thatch_*`, non-`skill`, non-`task` tool activity.
 2. Send your next message (anything).
 
 **Expected**
@@ -14,8 +17,18 @@
   truncated args/output).
 - The agent loads `thatch-fact-extractor` and saves durable facts via
   `thatch_memory_remember` — or saves nothing if the activity was routine.
-- The buffer is flushed: the following message carries no repeat nudge unless
-  new tool activity happened.
+- The buffer is **not** drained on nudge delivery — it persists until the agent
+  writes a memory or calls `thatch_extraction_done`. 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
+  `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).
+  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-005-setup-install.md

@@ -17,12 +17,12 @@
   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
-  **12 shared skills** (no code-review coordinator) to `$CLAUDE_CONFIG_DIR/skills/` — user-scoped
+  **18 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 12 shared skills to `~/.cursor/skills/`.
+  `thatch flush-tools --json`; and installs 18 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

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

@@ -17,9 +17,10 @@
 **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` drains the queue first (extraction tier): prints the JSON payload wrapped for
-  Cursor as `additional_context`, and **deletes the queue file** so the next call carries no
-  repeat payload unless new tool activity happened.
+- `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.

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

@@ -16,7 +16,9 @@
 
 **Expected**
 - Tiers fire in strict priority — **extraction > recall > write** — at most one nudge per call:
-  - extraction: queue non-empty -> JSON payload, queue file deleted.
+  - 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

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

@@ -13,16 +13,16 @@
 5. Check whether the `thatch-code-review` coordinator skill is present.
 
 **Expected**
-- Claude Code and Cursor install exactly **12 shared skills** to the skills
+- Claude Code and Cursor install exactly **18 shared skills** to the skills
   dir — the coordinator (`thatch-code-review`) is **absent** (it needs
   sub-agents, which those hosts lack).
-- opencode installs **13** — the 12 shared plus the coordinator.
+- opencode installs **19** — the 18 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 (12 vs 13), content-diff-overwrite, and
+_Automatable: yes — file presence, count (18 vs 19), 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-016-concurrent-session-isolation.md

@@ -24,9 +24,10 @@
   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 drains only A's queue file and deletes it; a second
-  flush for A is empty. Session B's queue file is untouched and drains on its own
-  flush.
+- `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.

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

@@ -0,0 +1,36 @@
+# 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.

package/docs/qa/use-cases/UC-020-extraction-escalation.md

@@ -0,0 +1,38 @@
+# UC-020: Extraction nudge escalation and acknowledgment
+
+_Automatable: missedNudges counter + escalation tiers + extraction_done drain
+are testable with the mock client and a synthetic tool call sequence._
+
+**Preconditions**
+- thatch active in an opencode, Claude Code, or Cursor session
+- For the child-sub-agent path: opencode with
+  `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true`
+
+**Steps**
+1. Do some non-thatch tool work (read files, run commands). Do NOT write any
+   memories.
+2. Send a message. Observe the extraction nudge — polite tone (missedCount=0).
+3. Ignore the nudge. Send another message without writing a memory (missedCount=1).
+4. Repeat step 3 (missedCount=2).
+5. Repeat step 3 again (missedCount=3+).
+6. Acknowledge by calling `thatch_extraction_done` in the session.
+7. Send another message.
+
+**Expected**
+- Step 2: the nudge is polite, referencing the queued tool interactions.
+- Step 4: after 2 consecutive misses (missedCount=2), the nudge is insistent
+  (directive tone).
+- Step 5: after 3+ consecutive misses (missedCount>=3), the nudge is ALL-CAPS.
+- The buffer was NOT drained at any point during steps 2-5 — the buffer
+  persists until a memory is written or `extraction_done` is called. The nudge
+  repeats each turn with escalated tone (and the payload grows if new tool
+  activity adds entries between nudges).
+- Step 6: `thatch_extraction_done` drains the buffer and resets the
+  `missedNudges` counter. The tool returns `"[acknowledged] extraction buffer
+  drained"`.
+- Step 7: no extraction nudge appears (buffer is empty). If the user prompt
+  semantically matches existing memories, a recall nudge may appear instead.
+- Alternative drain path: if a child sub-agent (dispatched via the `task`
+  tool) writes a memory via `thatch_memory_remember`, the parent's buffer is
+  also drained via the `childToParent` Map — the `missedNudges` counter resets
+  for the parent session.

package/docs/user/README.md

@@ -102,6 +102,12 @@ Stores are created automatically — no setup required.
 | `thatch_find_duplicates` | Surface pairs of memories with suspiciously similar content. |
 | `thatch_dedup_mark_checked` | Record the verdict for a reviewed pair so it stops being re-reported. |
 
+### Extraction tools
+
+| Tool | What it does |
+|------|-------------|
+| `thatch_extraction_done` | Acknowledge that the extraction nudge was dispatched to a sub-agent. Drains the buffer so the nudge does not replay. Called after dispatching a background task to run the fact-extractor skill. |
+
 ## Automatic behaviors
 
 Beyond the tools, thatch hooks into opencode itself:
@@ -120,8 +126,11 @@ Beyond the tools, thatch hooks into opencode itself:
   similar entries so it can merge them or record that they're distinct.
 - **Fact-extraction nudges.** Thatch buffers the session's recent tool calls
   (up to 20, per session). On your next message, the agent receives a summary
-  payload and is prompted to save any durable facts it reveals. The agent does
-  the writing — thatch never saves memories on its own.
+  payload and is prompted to save any durable facts it reveals. The nudge
+  repeats and escalates (polite to insistent to ALL-CAPS) each turn it's
+  ignored — the buffer drains only when the agent writes a memory or
+  acknowledges via `thatch_extraction_done`. The agent does the writing —
+  thatch never saves memories on its own.
 - **Compaction context.** When opencode compacts a long session, thatch injects
   a reminder so the summarized session still knows memory tools exist.
 
@@ -155,7 +164,7 @@ With `thatch setup --claude`, skills install to `~/.claude/skills/` (or
 
 ### Code review skills
 
-Five specialist review lenses, each a self-contained static-analysis pass:
+Six specialist review lenses, each a self-contained static-analysis pass:
 
 | Skill | Focus |
 |-------|-------|
@@ -164,9 +173,20 @@ Five specialist review lenses, each a self-contained static-analysis pass:
 | `thatch-review-state-flow` | Data flow and contracts: module boundaries, implicit state machines, error propagation, separation of concerns. |
 | `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth wall breaks, em dashes, hedging, filler. |
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of the code's behavior? |
+| `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
 | `thatch-review-synthesizer` | Verifies and synthesizes findings from multiple specialists into a single deduplicated, severity-grouped report. |
 | `thatch-review-context` | Gathers project context (PR descriptions, git archaeology, ticket references, memory) before a review. Prevents false positives about intentionally deferred work. |
 | `thatch-workflow-research` | Researches code workflows and features affected by a change or planned change. Reads code flows, comments, git history, and produces a guide for reviewers or planners. |
+| `thatch-change-walkthrough` | Explains a change to the user as a teaching walkthrough: researches each affected workflow at the merge-base, teaches current behavior, then overlays the modifications with file:line citations. |
+| `thatch-code-walkthrough` | Explains a feature, module, or workflow to the user as a teaching walkthrough with file:line citations. Also used to draft high-level docs for new or undocumented features. |
+
+### Writing skills
+
+| Skill | Purpose |
+|-------|---------|
+| `pr-description` | Drafts PR descriptions using instructional-design scaffolding (SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES) with bold and italic emphasis for scanning. |
+| `ticket-description` | Drafts ticket or issue descriptions (Linear or Jira) using instructional-design scaffolding with bold and italic emphasis for scanning. |
+| `split-overlarge-pr` | Splits already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main. |
 
 ### opencode-only skills
 
@@ -179,9 +199,11 @@ Five specialist review lenses, each a self-contained static-analysis pass:
 | Skill | opencode | Claude Code | Cursor |
 |-------|----------|-------------|--------|
 | Memory skills (4) | Yes | Yes | Yes |
-| Review specialists (5) | Yes | Yes | Yes |
+| Review specialists (6) | Yes | Yes | Yes |
 | Review synthesizer | Yes | Yes | Yes |
 | Review context + workflow research | Yes | Yes | Yes |
+| Walkthrough skills (2) | Yes | Yes | Yes |
+| Writing skills (3) | Yes | Yes | Yes |
 | Code review coordinator | Yes | No (requires sub-agents) | No (requires sub-agents) |
 
 ### Using review skills
@@ -208,7 +230,7 @@ specialist in sequence, then synthesize:
 ```text
 1. Load thatch-review-pedantic, review branch feature-x, report findings.
 2. Load thatch-review-acceptance, review the same branch.
-3. ... repeat for state-flow, no-slop, breadcrumbs ...
+3. ... repeat for state-flow, no-slop, breadcrumbs, mark-and-sweep ...
 4. Load thatch-review-synthesizer, verify and aggregate all findings.
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config. Works with OpenCode (as a plugin), Claude Code (as an MCP server), and Cursor (as an MCP server).",
   "type": "module",
   "main": "src/index.ts",

package/src/extract-queue.ts

@@ -99,13 +99,6 @@ export function consumeQueue(sessionID: string): void {
   try { unlinkSync(queuePath(sessionID)); } catch { /* not present is fine */ }
 }
 
-/** Read and delete a session's queue. Returns the buffered interactions in order. */
-export function flushQueue(sessionID: string): ToolInteraction[] {
-  const interactions = peekQueue(sessionID);
-  consumeQueue(sessionID);
-  return interactions;
-}
-
 function readQueueFile(path: string): ToolInteraction[] {
   if (!existsSync(path)) return [];
   const text = readFileSync(path, "utf8").trim();

package/src/extraction.ts

@@ -110,11 +110,24 @@ export class ExtractionPipeline {
     this.#buffers.delete(sessionID);
   }
 
-  /** Returns the session's buffered interactions and clears them. */
-  flush(sessionID: string): ToolInteraction[] {
-    const batch = this.peek(sessionID);
-    this.consume(sessionID);
-    return batch;
+  /**
+   * Remove entries that were in the snapshot (by reference identity), keeping
+   * any that arrived after the snapshot was taken. Used by the child-parent
+   * drain: when a sub-agent writes a memory, only the entries present at
+   * dispatch time should be drained — not the entire buffer, which may now
+   * contain interleaved-turn entries the parent accumulated while the
+   * sub-agent was running.
+   */
+  consumeSnapshot(sessionID: string, snapshot: ToolInteraction[]): void {
+    const buf = this.#buffers.get(sessionID);
+    if (!buf) return;
+    const old = new Set(snapshot);
+    const remaining = buf.filter((ix) => !old.has(ix));
+    if (remaining.length === 0) {
+      this.#buffers.delete(sessionID);
+    } else {
+      this.#buffers.set(sessionID, remaining);
+    }
   }
 
   pending(sessionID: string): boolean {

package/src/index.ts

@@ -12,7 +12,7 @@ import {
   extractionNudge,
   type NudgeMatch,
 } from "./prompts";
-import { ExtractionPipeline } from "./extraction";
+import { ExtractionPipeline, type ToolInteraction } from "./extraction";
 import { installSkills, SHARED_SKILLS, OPENCODE_ONLY_SKILLS } from "./skills";
 import { hygieneReport } from "./hygiene";
 
@@ -64,6 +64,14 @@ export const server: Plugin = async ({ client, worktree }) => {
   // Populated from session.created events that carry a parentID.
   const childToParent = new Map<string, string>();
 
+  // Snapshot of the parent's buffer at the moment each child was dispatched.
+  // When the child writes a memory, consumeSnapshot drains only these entries
+  // (by reference identity), preserving interleaved-turn entries that arrived
+  // while the sub-agent was running. Without this, the child's memory_remember
+  // would drain the parent's ENTIRE buffer — silently dropping facts from
+  // any tool calls the parent made concurrenly with the sub-agent.
+  const parentSnapshots = new Map<string, ToolInteraction[]>();
+
   // Skills always install to the global opencode config — installing into the
   // worktree would mutate the user's repo (untracked files in git status).
   // A failed install degrades the nudge workflow but must not kill the plugin.
@@ -112,32 +120,41 @@ export const server: Plugin = async ({ client, worktree }) => {
     //    agent writes a memory, so ignored nudges accumulate and the payload
     //    grows with each missed cycle.
     //
-    //    Fix A: a memory_remember call in a child session (sub-agent) also
-    //    drains the parent's buffer. Without this, dispatching the
-    //    fact-extractor as a background task writes memories in the child
-    //    but never clears the parent's queue — the nudge replays every turn.
+    //    A memory_remember call in a child session (sub-agent) also drains
+    //    the parent's buffer — but only the entries that existed at dispatch
+    //    time (the snapshot). Entries from interleaved turns survive so their
+    //    facts aren't silently dropped. Without this, dispatching the
+    //    fact-extractor as a background task writes memories in the child but
+    //    never clears the parent's queue — the nudge replays every turn.
     //
-    //    Fix C: thatch_extraction_done is an explicit acknowledgment tool the
-    //    model calls in the parent session after dispatching. Belt-and-
-    //    suspenders for fix A: covers the case where the sub-agent errors out
-    //    or the host doesn't expose parent-child session relationships.
+    //    thatch_extraction_done is an explicit acknowledgment tool the model
+    //    calls in the parent session after dispatching. Covers the case where
+    //    the sub-agent errors out or the host doesn't expose parent-child
+    //    session relationships.
     "tool.execute.after": async (input, output) => {
       if (input.tool === "thatch_memory_remember") {
         extraction.consume(input.sessionID);
         missedNudges.delete(input.sessionID);
-        // Fix A: if this is a child session, also drain the parent so the
-        // parent's extraction nudge stops replaying after a sub-agent writes
-        // memories on its behalf.
+        // If this is a child session, drain only the parent's snapshot entries
+        // (those present at dispatch time). Interleaved-turn entries survive.
+        // If no snapshot was recorded (e.g. session.created event never
+        // arrived), fall back to draining the entire parent buffer.
         const parentID = childToParent.get(input.sessionID);
         if (parentID) {
-          extraction.consume(parentID);
+          const snapshot = parentSnapshots.get(input.sessionID);
+          if (snapshot) {
+            extraction.consumeSnapshot(parentID, snapshot);
+            parentSnapshots.delete(input.sessionID);
+          } else {
+            extraction.consume(parentID);
+          }
           missedNudges.delete(parentID);
         }
         return;
       }
-      // Fix C: explicit acknowledgment tool drains the buffer without
-      // requiring a memory write. The model calls this after dispatching
-      // the fact-extractor to a sub-agent.
+      // Explicit acknowledgment tool drains the buffer without requiring a
+      // memory write. The model calls this after dispatching the
+      // fact-extractor to a sub-agent.
       if (input.tool === "thatch_extraction_done") {
         extraction.consume(input.sessionID);
         missedNudges.delete(input.sessionID);
@@ -218,18 +235,23 @@ export const server: Plugin = async ({ client, worktree }) => {
     // 5. Session-start reminder, carrying the hygiene heartbeat. Hygiene is
     // best-effort: a failure there must not cost the reminder itself.
     //
-    // Also tracks parent-child session relationships for fix A (cross-session
-    // buffer drain). session.created with a parentID records the mapping;
-    // session.deleted cleans it up to avoid unbounded growth.
+    // Also tracks parent-child session relationships for cross-session buffer
+    // drain. session.created with a parentID records the mapping AND
+    // snapshots the parent's current buffer — so the child's later
+    // memory_remember drains only those snapshot entries, not the parent's
+    // entire buffer (which may have grown from interleaved turns).
+    // session.deleted cleans both maps to avoid unbounded growth.
     event: async ({ event }) => {
       if (event.type === "session.created") {
         const info = event.properties.info;
         if (info.parentID) {
           childToParent.set(info.id, info.parentID);
+          parentSnapshots.set(info.id, [...extraction.peek(info.parentID)]);
         }
       }
       if (event.type === "session.deleted") {
         childToParent.delete(event.properties.info.id);
+        parentSnapshots.delete(event.properties.info.id);
         return;
       }
 
@@ -248,7 +270,7 @@ export const server: Plugin = async ({ client, worktree }) => {
           path: { id },
           body: {
             noReply: true,
-            parts: [{ type: "text", text: sessionStartReminder(repo, hygiene) }],
+            parts: [{ type: "text", text: sessionStartReminder(repo, hygiene), synthetic: true }],
           },
         });
       } catch (err) {

package/src/mcp.ts

@@ -5,6 +5,7 @@ import { detectRepo } from "./git";
 import { checkSetup } from "./setup";
 import { TOOL_DEFS, type CoreContext, type ToolDef } from "./tool-defs";
 import { SidebandServer, sidebandSocketPath } from "./sideband";
+import pkg from "../package.json";
 
 // ---------------------------------------------------------------------------
 // JSON-RPC 2.0 types
@@ -34,7 +35,7 @@ const INTERNAL_ERROR = -32603;
 // ---------------------------------------------------------------------------
 
 const SERVER_NAME = "thatch";
-const SERVER_VERSION = "0.1.2";
+const SERVER_VERSION = pkg.version;
 
 /**
  * MCP capabilities declared in the initialize response. Thatch is a tools-only