@jeffober/thatch 0.1.28 → 0.1.29

package/docs/dev/features/setup.md

@@ -0,0 +1,199 @@
+# Setup System
+
+Installs thatch into Claude Code and Cursor. opencode does not need setup --- it
+auto-installs skills and injects the system prompt at plugin init. All setup
+operations are idempotent: re-running updates drifted content without clobbering
+unrelated config.
+
+For the concrete artifact paths and hook event tables each host writes, see
+[../setup-and-hooks.md](../setup-and-hooks.md). This doc covers the architecture:
+how setup commands, the marker system, detection, auto-refresh, and binary
+resolution fit together.
+
+## What it does
+
+- `thatch setup --claude` --- installs MCP config, CLAUDE.md instructions,
+  hooks, and skills for Claude Code
+- `thatch setup --cursor` --- installs MCP config, AGENTS.md instructions,
+  hooks, and skills for Cursor
+- `--global` flag --- installs to user-scoped config dirs instead of
+  project-local
+- **Marker system** --- idempotent replacement of the thatch instruction block
+  in `CLAUDE.md` or `AGENTS.md` via start/end markers
+- **`checkSetup`** --- detects installed, not-installed, or markers-broken at
+  MCP server startup
+- **Auto-refresh** --- MCP server re-runs setup on startup if installed,
+  updating drifted content
+- **Setup warning surfacing** --- first `tools/call` response prepends a
+  warning if setup was not run
+- **Binary resolution** --- uses bare `thatch` if on PATH (survives updates),
+  else the absolute path to the running script
+
+## How it works
+
+### Setup commands
+
+At least one of `--claude` or `--cursor` is required. Both can be passed
+together. `--global` applies to whichever host or hosts are selected.
+
+### Claude Code setup (`setupClaudeCode` in `src/setup.ts`)
+
+Four artifacts, all idempotent:
+
+1. **MCP config** --- project-local writes `.mcp.json` with a stdio thatch
+   MCP server entry. Global prints a `claude mcp add --scope user thatch --
+   <bin> mcp` command for the user to run (does not write a file, because
+   `~/.claude.json` is too complex to write directly).
+2. **Instructions** --- appends `claudeInstructions()` to `CLAUDE.md` between
+   start and end markers (`THATCH_MARKER` / `THATCH_END_MARKER`). Project-local:
+   `<projectDir>/CLAUDE.md`. Global: `$CLAUDE_CONFIG_DIR/CLAUDE.md`.
+3. **Hooks** --- writes to `.claude/settings.json` (project) or
+   `$CLAUDE_CONFIG_DIR/settings.json` (global). Three hooks: `SessionStart`
+   → `thatch reminder`, `PostToolBatch` → `thatch buffer-batch`,
+   `UserPromptSubmit` → `thatch flush-tools`. Nested format:
+   `{hooks:{Event:{hooks:[{type,command}]}}}`.
+4. **Skills** --- installs to `$CLAUDE_CONFIG_DIR/skills/` (always
+   user-scoped, even for project-local setup). `SHARED_SKILLS` only --- the
+   code-review coordinator requires sub-agent dispatch, which Claude Code
+   does not support.
+
+### Cursor setup (`setupCursor` in `src/setup.ts`)
+
+Four artifacts, same idempotent pattern:
+
+1. **MCP config** --- writes `.cursor/mcp.json` (project) or
+   `$CURSOR_CONFIG_DIR/mcp.json` (global). Same JSON shape as Claude Code.
+   No `claude mcp add` equivalent needed --- Cursor reads the config file
+   directly.
+2. **Instructions** --- appends `cursorInstructions()` to `AGENTS.md` between
+   markers (`CURSOR_MARKER` / `CURSOR_END_MARKER`). Project-local:
+   `<projectDir>/AGENTS.md`. Global: `$CURSOR_CONFIG_DIR/AGENTS.md`.
+3. **Hooks** --- writes to `.cursor/hooks.json` (project) or
+   `$CURSOR_CONFIG_DIR/hooks.json` (global). Flat format:
+   `{version:1, hooks:{event:[{command}]}}`. Three hooks: `sessionStart`
+   → `thatch reminder --json`, `postToolUse` → `thatch buffer-tool`,
+   `beforeSubmitPrompt` → `thatch flush-tools --json`.
+4. **Skills** --- installs to `$CURSOR_CONFIG_DIR/skills/` (shared only).
+
+### Marker system (`appendBlock`)
+
+`appendBlock(path, instructions, startMarker, endMarker)` handles three cases:
+
+1. **Both markers found** --- replace content between them. Preserve text
+   before the start marker and after the end marker. This is the normal
+   update path: re-running setup replaces the thatch block without touching
+   user-written content elsewhere in the file.
+2. **Start marker found but end missing** --- leave the file alone. This is a
+   corrupted state --- someone edited the file and accidentally removed the
+   end marker. Writing would risk clobbering content that follows the start
+   marker. `checkSetup` reports this as `markers-broken`.
+3. **No markers** --- append instructions to the end of the file (with a
+   separator). Create the file if it does not exist.
+
+Start markers differ by host (the text says "Claude Code" or "Cursor"). The end
+marker is shared.
+
+### `checkSetup` (`src/setup.ts`)
+
+Detects the host from environment variables set by the host process:
+
+- `CURSOR_PROJECT_DIR` set → Cursor
+- `CLAUDE_PROJECT_DIR` set (and Cursor not) → Claude Code
+- Neither set → returns `null` (manual `thatch mcp` invocation, no check)
+
+Cursor takes priority because Cursor also sets `CLAUDE_PROJECT_DIR` as an
+alias. Without the priority check, Cursor sessions would be misidentified as
+Claude Code.
+
+`checkSetup` looks for start and end markers in the host's instructions file
+--- `CLAUDE.md` for Claude Code, `AGENTS.md` for Cursor. It checks local first,
+then global. Local takes priority.
+
+| Outcome | Condition | Action |
+|---------|-----------|--------|
+| **installed** | Both markers found (local or global) | No warning |
+| **not-installed** | No instructions file with markers | Warning surfaced on first `tools/call` |
+| **markers-broken** | Start marker found, end marker missing | Warning with file path and fix instructions |
+
+### Auto-refresh at MCP startup
+
+If `checkSetup` returns `installed`, the MCP server re-runs `setupClaudeCode`
+or `setupCursor` with the same scope. This updates skills, instructions, and
+hooks that drifted since the last `thatch setup`. All operations are
+idempotent --- they only write when content differs. Failure is best-effort
+and logged to stderr.
+
+This is how installations stay current without the user manually re-running
+setup after upgrading thatch. The next MCP session picks up new skill content,
+updated instructions, and any hook changes automatically.
+
+### Setup warning surfacing
+
+On the first `tools/call` response, if a setup warning exists, the server
+prepends `[thatch] {warning}` to the tool's text output. The agent sees it
+and can tell the user to run `thatch setup`. The warning is cleared after one
+surfacing so it does not repeat on every tool call.
+
+### Binary resolution
+
+Setup resolves the thatch binary via `Bun.which("thatch")`. If `thatch` is on
+`PATH` (npm global install, opencode plugin install), it uses the bare name.
+This survives updates --- the resolved path points to whatever `thatch` is
+current at hook execution time, not a stale absolute path.
+
+If `thatch` is not on `PATH`, setup falls back to the absolute path of the
+running script. This handles one-off invocations (e.g., `bun run bin/thatch
+setup --claude`).
+
+The resolved binary is baked into every installed hook command. Hooks are
+short-lived processes spawned by the host after the setup session ends, so
+they cannot rely on the original process's environment. The baked-in path
+ensures hooks keep working across sessions.
+
+### Hook replacement
+
+`replaceThatchHooks` / `replaceCursorThatchHooks` filter out any existing hook
+group whose `command` contains the string `thatch`, then add the current
+ones. Non-thatch hooks are preserved. This handles legacy hooks --- for
+example, an older `thatch echo` hook is replaced with the current
+`flush-tools` hook without touching hooks from other tools.
+
+## Interactions with other features
+
+- [Multi-host](multi-host.md) --- setup is the installation mechanism for
+  Claude Code and Cursor. opencode auto-installs at plugin init.
+- [Skills](../skills.md) --- setup installs skills as part of the install.
+  Skill content is plugin-owned and overwritten on drift.
+- [Nudge pipeline](nudge-pipeline.md) --- setup installs the hooks that drive
+  the nudge pipeline for MCP hosts.
+- [Extraction](extraction.md) --- setup installs the `buffer-batch` /
+  `buffer-tool` hooks that feed the file-backed extraction queue.
+- [Sideband](sideband.md) --- setup installs `flush-tools`, which connects to
+  the sideband socket for warm-model access during nudge evaluation.
+
+## Source files
+
+| File | Role |
+|------|------|
+| `src/setup.ts` | `setupClaudeCode`, `setupCursor`, `checkSetup`, `appendBlock`, marker definitions, hook replacement |
+| `bin/thatch` | `setup` subcommand --- parses flags, dispatches to `setupClaudeCode` / `setupCursor` |
+| `src/prompts.ts` | `claudeInstructions`, `cursorInstructions` --- the instruction text appended to `CLAUDE.md` / `AGENTS.md` |
+
+## Key invariants
+
+1. **All operations are idempotent.** Re-running setup updates drifted content
+   without clobbering. Instructions use markers, hooks filter by `thatch`
+   string, MCP config preserves existing servers, skills diff before writing.
+2. **Skills are always user-scoped**, even in project-local setup. Claude Code
+   and Cursor load skills from the user config dir, not the project.
+3. **`appendBlock` leaves content alone if markers do not parse.** A start
+   marker without an end marker means the file was edited externally. Writing
+   would risk clobbering content after the start marker.
+4. **Binary path is baked into hook commands.** Hooks are short-lived
+   processes that outlive the setup session. The resolved path ensures they
+   keep working.
+5. **Non-thatch hooks are preserved during hook replacement.** Only hooks
+   whose `command` contains `thatch` are filtered out.
+6. **Auto-refresh keeps installations current.** The MCP server re-runs
+   setup on startup if markers are present, picking up new skills and
+   updated instructions without manual intervention.

package/docs/dev/features/sideband.md

@@ -0,0 +1,104 @@
+# Sideband IPC (MCP Hosts)
+
+A Unix domain socket server that lets one-shot hook processes borrow the MCP server's warm embedding model. Without this, each hook invocation would load the ~34 MB model from scratch, adding 300-700 ms to every prompt.
+
+## What it does
+
+- Unix domain socket at a deterministic path derived from the DB path
+- Three request methods: match (recall), predictions, behaviors
+- One embedding round-trip per request (all three methods share the model)
+- 2-second timeout, null on failure (callers skip the nudge gracefully)
+- Stale socket cleanup on connection error
+
+## How it works
+
+### The problem it solves
+
+Claude Code and Cursor spawn a fresh process for each hook invocation (`thatch flush-tools`, `thatch reminder`). These processes need the embedding model to embed the user's prompt for the recall/prediction/behavior nudges. Loading the ~34 MB model on every prompt would add unacceptable latency.
+
+The MCP server is long-lived (kept alive by the host's stdio connection) and has the model warm in memory. The sideband socket lets hook processes ask the warm server to do the embedding work.
+
+### Socket path
+
+The path is derived from a SHA-256 hash of the DB path (first 16 hex chars), under os.tmpdir():
+
+```text
+$TMPDIR/thatch-<sha256(dbPath)[0:16]>.sock
+```
+
+Both the MCP server and hook processes compute the same path independently (from `THATCH_DB_PATH` or the default under `XDG_CONFIG_HOME`). No out-of-band coordination needed.
+
+Changing `THATCH_DB_PATH` moves the socket. A stale socket from a crash is cleaned up on ECONNREFUSED/ENOENT.
+
+### Protocol
+
+Newline-delimited JSON. One request per connection, one response.
+
+Request:
+
+```json
+{"method":"match|predictions|behaviors","text":"...","stores":[...],"threshold":N,"limit":N}
+```
+
+Response (success):
+
+```json
+{"ok":true,"matches":[...]}
+```
+
+```json
+{"ok":true,"predictions":[...]}
+```
+
+```json
+{"ok":true,"behaviors":[...]}
+```
+
+Response (failure):
+
+```json
+{"ok":false,"error":"..."}
+```
+
+### Three methods
+
+1. **match** -- embeds text, runs `db.search` across stores, returns matches with score >= threshold as `{label, score, store}`
+2. **predictions** -- embeds text, calls `db.scorePredictionNudge`, returns scored prediction nudge items
+3. **behaviors** -- embeds text, calls `db.scoreBehaviorNudge`, returns scored behavior nudge items
+
+### Client helpers
+
+- `sidebandMatch(text, stores, threshold, limit)` -- returns matches or null on failure
+- `sidebandPredictions(text, stores, threshold, limit)` -- returns predictions or null
+- `sidebandBehaviors(text, stores, threshold, limit)` -- returns behaviors or null
+
+All three return null on any failure (server not running, stale socket, timeout, parse error). Callers must treat null as "skip the nudge, fall back gracefully."
+
+### Graceful degradation
+
+If the socket isn't available (MCP server not running, old version, stale socket, >2s timeout), `sidebandMatch` returns null and `flush-tools` falls back to the static write nudge. The recall/prediction/behavior nudge is best-effort -- its absence never blocks the agent's workflow.
+
+### Server lifecycle
+
+- Opened at MCP server startup (`src/mcp.ts`). Failure is non-fatal (only the prompt-aware recall/prediction/behavior nudge degrades).
+- Closed + socket file removed on shutdown (stdin close).
+
+## Interactions with other features
+
+- Nudge pipeline ([nudge-pipeline.md](nudge-pipeline.md)): MCP hosts use the sideband socket for all three nudge tiers (recall, prediction, behavior)
+- Multi-host ([multi-host.md](multi-host.md)): only MCP hosts (Claude Code, Cursor) use the sideband; opencode has the model in-process
+- Prediction engine ([prediction-engine.md](prediction-engine.md)): predictions method
+- Behavior engine ([behavior-engine.md](behavior-engine.md)): behaviors method
+- Memory store ([memory-store.md](memory-store.md)): match method uses `db.search`
+
+## Source files
+
+- `src/sideband.ts` -- SidebandServer (server side) + sidebandMatch/sidebandPredictions/sidebandBehaviors (client helpers)
+
+## Key invariants
+
+- Socket path = SHA-256 of DB path. Both sides compute it independently.
+- Sideband failure never blocks. All client helpers return null on failure.
+- One embedding per request (all three methods share the model).
+- 2-second timeout default.
+- Stale socket cleanup on ECONNREFUSED/ENOENT.

package/docs/dev/gotchas.md

@@ -41,7 +41,7 @@ here first. These are the things that have already cost time.
   a memory, write it with `archived: true`; to unarchive, `archived: false`.
 - **Updating an archived memory requires explicit `archived` param.** If the
   entry is already archived and a `remember` call omits the `archived` param,
-  the tool returns an error (`db.ts:211`). Pass `archived: true` to keep it
+  the tool returns an error (`db.ts:395`). Pass `archived: true` to keep it
   archived or `archived: false` to unarchive. This guard prevents accidental
   unarchival via an unrelated content update.
 
@@ -61,7 +61,7 @@ here first. These are the things that have already cost time.
 - **`chat.message` has two priority tiers**: extraction nudge first (returns
   early), then the prompt-aware recall nudge. Don't run both in one turn.
 - **The extraction nudge peeks, never flushes.** The buffer is NOT drained
-  on nudge delivery (`index.ts:169` — `peek()` call). It persists until the
+  on nudge delivery (`index.ts:366` — `peek()` call). It persists until the
   agent writes a memory or calls `thatch_extraction_done`. Ignored nudges
   accumulate; the `missedNudges` counter escalates the tone (polite at 0-1
   misses, insistent at 2, ALL-CAPS at 3+). The counter resets when the
@@ -71,7 +71,7 @@ here first. These are the things that have already cost time.
   is active. The peek-not-drain semantics still hold for the fallback nudge
   path (MCP hosts and any `triggerExtraction` failure).
 - **A child sub-agent's `thatch_memory_remember` drains the parent's buffer**
-  via the `childToParent` Map (`index.ts:65` declaration, `index.ts:131`
+  via the `childToParent` Map (`index.ts:79` declaration, `index.ts:272`
   lookup). Two paths reach this machinery: (a) the **plugin-initiated child
   session** — `triggerExtraction` calls `client.session.create` with a
   `parentID`, the primary opencode path; (b) the **agent-initiated background

package/docs/dev/mcp-parity.md

@@ -18,7 +18,7 @@ This document maps the feature parity and documents the remaining gaps.
 
 | Feature | OpenCode plugin | Claude Code MCP + hooks | Cursor MCP + hooks | Parity |
 |---------|----------------|------------------------|---------------------|--------|
-| **Tools** (13, 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** (18, 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 |
@@ -26,6 +26,7 @@ This document maps the feature parity and documents the remaining gaps.
 | **Extraction feedback** (toast notifications) | `client.tui.showToast` fires when the extraction child goes idle — shows `[thatch] new: N, updated: M, deleted: K` (success) or `extraction complete — nothing to save` (info); best-effort, silently ignored in headless mode | No TUI connection — MCP hosts have no equivalent | No TUI connection | **Gapped** — MCP hosts cannot show toast notifications |
 | **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 |
 | **Prediction auto-fire** (user decision model) | `chat.message` hook scores the prompt embedding against prediction matchers; injects a `[thatch] User decision model` nudge alongside the recall nudge (separate synthetic part, same embedding call) | `UserPromptSubmit` hook → `thatch flush-tools` fires prediction query via the sideband socket's `predictions` method in parallel with the recall nudge | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — same `scorePredictionNudge` entry point in both paths |
+| **Behavior auto-fire** (self-discipline rules) | `chat.message` hook scores the prompt embedding against behavior matchers; injects a `[thatch] Situational behaviors` nudge (separate synthetic part, same embedding call) | `UserPromptSubmit` hook → `thatch flush-tools` fires behavior query via the sideband socket's `behaviors` method in parallel with recall and predictions | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — same `scoreBehaviorNudge` entry point in both paths |
 | **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** |
 | **Setup detection at startup** | n/a — plugin auto-installs at init | `checkSetup` in MCP server: detects missing or broken instructions in CLAUDE.md | Same as Claude Code (checks AGENTS.md) | **Full** — warns the agent to tell the user to run `thatch setup` |
@@ -151,9 +152,10 @@ same socket path without out-of-band coordination. The path lives under
 `os.tmpdir()`.
 
 The protocol is newline-delimited JSON: one request per connection, one
-response. Requests are `{"method":"match","text":"...","stores":[...],
-"threshold":N,"limit":N}`. Responses are `{"ok":true,"matches":[...]}` or
-`{"ok":false,"error":"..."}`.
+response. Requests are `{"method":"match|predictions|behaviors",
+"text":"...","stores":[...],"threshold":N,"limit":N}`. Responses are
+`{"ok":true,"matches":[...]}` / `{"ok":true,"predictions":[...]}` /
+`{"ok":true,"behaviors":[...]}` or `{"ok":false,"error":"..."}`.
 
 Graceful degradation: if the socket isn't available (MCP server not running,
 old version, stale socket from a crash, or a >2 s timeout), `sidebandMatch`

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

@@ -35,8 +35,8 @@ threw an error (the `extracting` set is cleared on failure).
 
 `client.tui.showToast` is called from the `event` hook (on child idle, with
 extraction metrics: new/updated/deleted counts) and from `chat.message` (on
-recall and prediction matches). Best-effort — silently ignored if the TUI is
-not connected (headless mode).
+recall, prediction, and behavior matches). Best-effort — silently ignored if
+the TUI is not connected (headless mode).
 
 ## Claude Code (MCP server + hooks)
 
@@ -71,7 +71,7 @@ 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 | Peeks queue (extraction nudge), else recall nudge via sideband, else write nudge |
+| `UserPromptSubmit` | `thatch flush-tools` | nudge text to stdout | Peeks queue (extraction nudge), else fires recall, prediction, and behavior nudges via sideband in parallel, else write nudge |
 
 `PostToolBatch` is silent so the agent loop is not delayed; the buffered
 content is invisible until `UserPromptSubmit` peeks it.
@@ -111,7 +111,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` | Peeks queue, else recall via sideband, else write nudge |
+| `beforeSubmitPrompt` | `thatch flush-tools --json` | JSON `additional_context` | Peeks queue, else recall, prediction, and behavior via sideband, else write nudge |
 
 Differences from Claude Code:
 

package/docs/dev/skills.md

@@ -25,12 +25,13 @@ description: Extract durable project facts ... Use when ...
 ```
 
 - `name` must match the directory name (`<skillsDir>/<name>/SKILL.md`).
-- `description` drives when the agent loads the skill (both opencode and
-  Cursor auto-discover skills and use the description for relevance).
+- `description` drives when the agent loads the skill (opencode, Claude
+  Code, and Cursor all auto-discover skills and use the description for
+  relevance).
 
-## The 23 skills
+## The 24 skills
 
-**Shared (22)** — installed everywhere; no sub-agents required:
+**Shared (23)** — installed everywhere; no sub-agents required:
 
 | Skill | Role |
 |-------|------|
@@ -40,6 +41,7 @@ description: Extract durable project facts ... Use when ...
 | `thatch-review-pedantic` | Mechanical correctness: spelling, naming, doc accuracy, specs, stale artifacts. |
 | `thatch-review-acceptance` | Behavioral/product review: UX, behavioral delta, integration effects. |
 | `thatch-review-state-flow` | Data flow and contracts: module boundaries, implicit FSMs, error propagation. |
+| `thatch-review-economy` | Design simplicity and maintainability: is the complexity earned? Evaluates both the overall change design (forest) and individual touch points (trees) for unnecessary complexity, redundancy, and simpler available alternatives. |
 | `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. |
@@ -61,11 +63,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 7 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 8 specialists in parallel, synthesize with a workflow-change preface and prior-comment cross-reference. |
 
 ## 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):
+The seven problem-finding review specialists share a framework interpolated via `${REVIEW_COMMON}` (the eighth 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
@@ -95,7 +97,7 @@ The synthesizer reuses the same verification rigor but has its own structure
 ## The two arrays
 
 ```ts
-const SHARED_SKILLS: SkillDef[] = [ /* 21 skills above */ ];
+const SHARED_SKILLS: SkillDef[] = [ /* 23 skills above */ ];
 const OPENCODE_ONLY_SKILLS: SkillDef[] = [ /* code-review coordinator */ ];
 ```
 
@@ -132,7 +134,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 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 opencode**: load `thatch-code-review` — it gathers project context, researches affected workflows, dispatches all 8 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.
 - **Follow-up round (re-review)**: load `thatch-review-followup` when the author

package/docs/plans/README.md

@@ -1,6 +1,6 @@
 # Plans
 
-Numbered plan documents capture design decisions that span multiple sessions.
+Plan documents capture design decisions that span multiple sessions.
 Each plan is a snapshot of the reasoning at the time — subsequent plans may
 supersede earlier ones as the project evolves.
 
@@ -9,7 +9,7 @@ Plans are temporary. When a plan is fully implemented, it **graduates**:
 1. The plan file is removed from this folder.
 2. The final architecture is documented in `docs/dev/` — either updated into
    existing dev docs or captured in a new one.
-3. End-to-end use-case scenarios are added to `docs/qa/use-cases/`.
+3. End-to-end use-case scenarios are added to `tests/qa/`.
 
 Once graduated, the dev docs and use-case docs are the permanent record. The
 plan file is no longer needed — git history preserves it if someone needs the