@jeffober/thatch 0.1.22 → 0.1.25

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 19 skills
+## The 20 skills
 
-**Shared (18)** — installed everywhere; no sub-agents required:
+**Shared (19)** — installed everywhere; no sub-agents required:
 
 | Skill | Role |
 |-------|------|
@@ -36,6 +36,7 @@ description: Extract durable project facts ... Use when ...
 | `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth-wall breaks, em dashes, filler. |
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of behavior? |
 | `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
+| `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar against generic praise. |
 | `thatch-review-synthesizer` | Verify specialist findings against code, dedupe, classify, calibrate severity. Starts the final report with a workflow-change preface, then cross-references findings against prior review comments when a follow-up round register is provided. |
 | `thatch-review-context` | Gather project/feature context (PR descriptions, git archaeology, ticket references, memory) before fan-out. Prevents false positives about intentionally deferred work. Also fetches prior review comments on a connected PR/MR for follow-up-round detection and builds a register with preliminary addressed-check status per comment. |
 | `thatch-workflow-research` | Research code workflows/features affected by a change or planned change. Reads code flows, comments, git history, memories, docs. Produces a guide to the code for reviewers or planners. |
@@ -50,11 +51,11 @@ description: Extract durable project facts ... Use when ...
 
 | Skill | Role |
 |-------|------|
-| `thatch-code-review` | Resolve review target (incl. VCS detection and connected PR/MR lookup for follow-up round detection), gather project context, research affected workflows, estimate complexity, partition, dispatch the 6 specialists in parallel, synthesize with a workflow-change preface and prior-comment cross-reference. |
+| `thatch-code-review` | Resolve review target (incl. VCS detection and connected PR/MR lookup for follow-up round detection), gather project context, research affected workflows, estimate complexity, partition, dispatch the 7 specialists in parallel, synthesize with a workflow-change preface and prior-comment cross-reference. |
 
 ## REVIEW_COMMON
 
-The six review specialists share a framework interpolated via `${REVIEW_COMMON}`:
+The six problem-finding review specialists share a framework interpolated via `${REVIEW_COMMON}` (the seventh specialist, highlights, finds positive things and uses its own structure):
 
 - **Static analysis only** — no running tests/linters/compilers.
 - **Scope gathering** — resolve the git range, `git diff --stat`, read changed
@@ -84,7 +85,7 @@ The synthesizer reuses the same verification rigor but has its own structure
 ## The two arrays
 
 ```ts
-const SHARED_SKILLS: SkillDef[] = [ /* 18 skills above */ ];
+const SHARED_SKILLS: SkillDef[] = [ /* 19 skills above */ ];
 const OPENCODE_ONLY_SKILLS: SkillDef[] = [ /* code-review coordinator */ ];
 ```
 
@@ -107,7 +108,7 @@ and `--cursor` pass only the shared set.
 
 ## Adding a skill
 
-1. Write `artifacts/skills/thatch-<name>.md` with YAML frontmatter. If it's a review specialist, include `${REVIEW_COMMON}` (interpolated from `artifacts/skills/common.md`).
+1. Write `artifacts/skills/thatch-<name>.md` with YAML frontmatter. If it's a problem-finding review specialist, include `${REVIEW_COMMON}` (interpolated from `artifacts/skills/common.md`). The highlights specialist does not use REVIEW_COMMON — it finds positive things, not problems, so the problem-finding framework does not apply.
 2. Add the skill name to the `names` array in `loadSharedSkills()` (or `loadOpencodeOnlySkills()` if sub-agents are needed). The loader in `src/skills.ts` reads `.md` files at init.
 3. If the skill name appears in a tool's workflow (e.g. `thatch-fact-extractor`), update `src/prompts.ts`.
 4. Run `mise run check` — tests verify counts; `installSkills` picks up new files on next init.
@@ -115,7 +116,7 @@ and `--cursor` pass only the shared set.
 ## Memory review skills in practice
 
 - **Quick single lens**: load any specialist directly and point it at a branch.
-- **Full review on opencode**: load `thatch-code-review` — it gathers project context, researches affected workflows, dispatches all 6 specialists in parallel (with both the context brief and workflow guide injected into each briefing), then synthesizes a report that starts with the workflow changes before findings.
+- **Full review on opencode**: load `thatch-code-review` — it gathers project context, researches affected workflows, dispatches all 7 specialists in parallel (with both the context brief and workflow guide injected into each briefing), then synthesizes a report that starts with the workflow changes before findings.
 - **Full review on Claude Code/Cursor**: run each specialist in sequence, then
   run `thatch-review-synthesizer` to verify and aggregate.
 

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

@@ -22,7 +22,7 @@ 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: 18 shared vs 19 opencode; drift overwritten on re-setup |
+| [UC-014](UC-014-skill-install-drift.md) | Skill install: 19 shared vs 20 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`) |

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

@@ -9,26 +9,46 @@ client and a synthetic tool call sequence._
 **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. Send your next message (anything).
+2. The agent's turn ends and the session goes idle.
 
-**Expected**
-- The agent's context for that message includes a `[thatch]` nudge carrying a
-  JSON payload summarizing the buffered tool interactions (tool name, title,
-  truncated args/output).
-- The agent loads `thatch-fact-extractor` and saves durable facts via
+**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.
-- 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:
+- 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
+- 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

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
-  **18 shared skills** (no code-review coordinator) to `$CLAUDE_CONFIG_DIR/skills/` — user-scoped
+  **19 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 18 shared skills to `~/.cursor/skills/`.
+  `thatch flush-tools --json`; and installs 19 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-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 **18 shared skills** to the skills
+- Claude Code and Cursor install exactly **19 shared skills** to the skills
   dir — the coordinator (`thatch-code-review`) is **absent** (it needs
   sub-agents, which those hosts lack).
-- opencode installs **19** — the 18 shared plus the coordinator.
+- opencode installs **20** — the 19 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 (18 vs 19), content-diff-overwrite, and
+_Automatable: yes — file presence, count (19 vs 20), 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-020-extraction-escalation.md

@@ -34,7 +34,19 @@ are testable with the mock client and a synthetic tool call sequence._
   or is deleted first, the entries requeue and the nudge replays.
 - Step 7: no extraction nudge appears (buffer is accepted). 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.
+- Alternative drain path (opencode direct extraction): when the parent session
+  goes idle with pending tool interactions, the plugin calls
+  `triggerExtraction` — creates a child session via the SDK client and prompts
+  it directly. The `extracting` set suppresses the nudge in `chat.message`
+  while the child runs. The child writes memories via
+  `thatch_memory_remember`, which drains the parent's snapshot entries via
+  `consumeSnapshot`. When the child goes idle, the snapshot is drained
+  (covering no-save runs), the child session is deleted, and a toast fires
+  with the metrics. This path bypasses the nudge-and-acknowledge cycle
+  entirely — no `missedNudges` counter, no escalation. The nudge path is
+  fallback only (when `triggerExtraction` throws).
+- Alternative drain path (agent-initiated): if a child sub-agent (dispatched
+  via the `task` tool in the fallback nudge path) 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

@@ -20,16 +20,15 @@ Publish to npm and add thatch to your opencode config:
 
 OpenCode installs the plugin and its dependencies automatically on next start.
 
-Set this environment variable so the extraction nudge can dispatch the
-fact-extractor as a **background** sub-agent instead of blocking your turn:
+For async extraction (child sessions run in the background):
 
 ```bash
 export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
 ```
 
-Without it, opencode hides the task tool's `background` parameter and the
-extraction nudge runs synchronously. Put it in your shell rc, `mise.toml`
-`[env]`, or `.envrc`.
+Without this env var, extraction still works — the child session runs
+fire-and-forget instead of asynchronously. Put it in your shell rc,
+`mise.toml` `[env]`, or `.envrc`.
 
 For local development before publishing, use a file path:
 
@@ -106,7 +105,7 @@ Stores are created automatically — no setup required.
 
 | 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. |
+| `thatch_extraction_done` | Acknowledge extraction buffer work. In the nudge fallback path, quiets the nudge while holding entries until the extractor completes. In a child extractor session, marks entries complete. Called by the model after dispatching the fact-extractor skill. |
 
 ### Prediction tools
 
@@ -133,13 +132,21 @@ Beyond the tools, thatch hooks into opencode itself:
 - **Write-time similarity warning.** Saving a memory that closely resembles an
   existing one succeeds, but the response warns the agent and lists the
   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 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.
+- **Fact extraction.** Thatch buffers the session's recent tool calls (up
+  to 20, per session). When the session goes idle, the plugin creates a
+  child session and prompts it to run the fact-extractor skill directly —
+  no nudge text in your conversation. The child writes memories via
+  `thatch_memory_remember` and is cleaned up when it finishes. A toast
+  notification shows the results (`[thatch] new: 2, updated: 1`). If the
+  direct path fails, a nudge is injected into the next message as a
+  fallback. On Claude Code and Cursor, the nudge-and-acknowledge path is
+  the only mechanism (no SDK client to create child sessions). The agent
+  does the writing — thatch never saves memories on its own.
+- **Recall and prediction toasts.** When your prompt matches stored
+  memories or learned decision patterns, thatch injects a synthetic nudge
+  (invisible to you, visible to the agent) and fires a toast notification
+  (`[thatch] recalled 3 memories` or `[thatch] 2 predictions surfaced`).
+  The toast is ephemeral — it fades after a few seconds.
 - **Compaction context.** When opencode compacts a long session, thatch injects
   a reminder so the summarized session still knows memory tools exist.
 - **Prediction auto-fire.** When a prompt matches learned contexts, thatch
@@ -179,7 +186,7 @@ With `thatch setup --claude`, skills install to `~/.claude/skills/` (or
 
 ### Code review skills
 
-Six specialist review lenses, each a self-contained static-analysis pass:
+Seven specialist review lenses, each a self-contained static-analysis pass:
 
 | Skill | Focus |
 |-------|-------|
@@ -189,7 +196,8 @@ Six specialist review lenses, each a self-contained static-analysis pass:
 | `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 report that starts with workflow changes, then deduplicated severity-grouped findings. |
+| `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar against generic praise. |
+| `thatch-review-synthesizer` | Verifies and synthesizes findings from multiple specialists into a report that starts with workflow changes, then highlights, then deduplicated severity-grouped findings. |
 | `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. |
@@ -214,7 +222,7 @@ Six specialist review lenses, each a self-contained static-analysis pass:
 | Skill | opencode | Claude Code | Cursor |
 |-------|----------|-------------|--------|
 | Memory skills (4) | Yes | Yes | Yes |
-| Review specialists (6) | Yes | Yes | Yes |
+| Review specialists (7) | Yes | Yes | Yes |
 | Review synthesizer | Yes | Yes | Yes |
 | Review context + workflow research | Yes | Yes | Yes |
 | Walkthrough skills (2) | Yes | Yes | Yes |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.22",
+  "version": "0.1.25",
   "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",