@jeffober/thatch 0.2.5 → 0.2.7

package/docs/dev/mcp-parity.md

@@ -22,10 +22,10 @@ This document maps the feature parity and documents the remaining gaps.
 | **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 |
-| **Wrap-up commands** (`/thatch/compact`, `/thatch/exit`) | Command markdown synced to `$XDG_CONFIG_HOME/opencode/command/thatch/` at plugin init; `command.execute.before` arms the session and the next idle resolves the greenlight token into a TUI action (`session.compact` via `executeCommand`, `app.exit` via `publish`) | No equivalent — no plugin host to arm the check or trigger the action | No equivalent | **Gapped** — needs the plugin's SDK client and TUI control routes |
-| **On-demand actions** (`/thatch/defrag`, `extract`, `hygiene`, `reflect`, `refine`) | Command markdown synced at plugin init; bodies rendered from the shared prompt cores with `thatch_` tool spellings; `extract` is opencode-only (needs session identity via `get_session_info` and the plugin's payload provider) | Command markdown synced by `thatch setup --claude` into `<claudeDir>/commands/thatch/`; same cores with `mcp__thatch__` spellings; `extract` excluded | MCP Prompts (`prompts/list` + `prompts/get`) from the same cores; Cursor surfaces them as slash commands; `extract` excluded | **Full** for the shared actions (same cores, per-host tool spellings); `extract` opencode-only |
+| **Wrap-up commands** (`/thatch/compact`, `/thatch/exit`) | Command markdown synced to `$XDG_CONFIG_HOME/opencode/command/thatch/` at plugin init; `command.execute.before` arms the session and the next idle resolves the greenlight token into the host action (compact: the TUI compact command on v1, `session.compact` on v2; exit: `app.exit` on v1, the session's own tab closing on v2) | No equivalent — no plugin host to arm the check or trigger the action | No equivalent | **Gapped** — needs the plugin's SDK client and host action routes |
+| **On-demand actions** (`/thatch/defrag`, `extract`, `hygiene`, `peer-review`, `refine`, `reflect`, `self-review`, `whois`) | Command markdown synced at plugin init; nudge-backed bodies rendered from the shared prompt cores with `thatch_` tool spellings, self-contained bodies (refine, whois, and the review-mode couchings peer-review/self-review) inline in the registry; `extract` and `whois` are opencode-only (they need session identity) | Command markdown synced by `thatch setup --claude` into `<claudeDir>/commands/thatch/`; same bodies with `mcp__thatch__` spellings; `extract` and `whois` excluded | MCP Prompts (`prompts/list` + `prompts/get`) from the same bodies; Cursor surfaces them as slash commands; `extract` and `whois` excluded | **Full** for the shared actions (same bodies, per-host tool spellings); `extract` and `whois` opencode-only |
 | **Extraction** (buffer tool calls, extract durable facts) | `tool.execute.after` buffers non-meta tool calls in-process (`isMetaToolName` in `src/extraction.ts`: thatch_*, skill, task, agent, subagent — execute calls unwrapping only thatch tools are also excluded); **direct extraction** is the primary path — when the parent session goes idle with pending buffer entries, the plugin creates a child session via the SDK (`client.session.create` with `parentID`) and prompts it to call `get_extraction_payload` (nudge suppressed via the `extracting` set); the `chat.message` nudge path is a **fallback** used when direct extraction throws | `PostToolBatch` → `thatch buffer-batch` (file-backed JSONL queue); `UserPromptSubmit` → `thatch flush-tools` peeks the queue and prints the nudge with session ID + fetch tool name (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` | **Partial** — opencode uses direct extraction (parent idle → child session) as the primary path, with the nudge as fallback; MCP hosts are nudge-only. Both paths use `get_extraction_payload` to fetch the queued interactions as a tool response, keeping the full payload out of the main session's context window. Nudge timing differs: the nudge arrives at the **start** of the next turn in Claude Code/Cursor; opencode's direct extraction fires at **end of turn** (session idle), and the nudge fallback fires at the start of the next turn like MCP |
-| **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 |
+| **Extraction feedback** (toast notifications) | `client.tui.showToast` on v1; the session-tab bridge's toast event -> the TUI plugin's `ui.toast.show` on v2 — fires when the extraction child goes idle, but ONLY when memories were actually written (no toast for no-save runs, to avoid notification fatigue): shows `[thatch] new: N, updated: M, deleted: K` (success); 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 |
 | **Automatic alerts** (notify on LLM pause / turn end) | Plugin event hook drives the `alerts.ts` state machine: `question.asked`/`permission.asked` → pause alert; `session.status` idle with a real-work round → done alert; unrecovered errors → needs-attention. Delivered via the shared `notify.ts` dispatcher, channel per event from the `alerts` config section | No event stream — only `thatch_notify_user` when the agent chooses | No event stream — only `thatch_notify_user` when the agent chooses | **Gapped** — MCP hosts have no plugin event hook to watch; Claude Code's `Notification`/`Stop` hooks could feed the same classifier later |
 | **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 |

package/docs/dev/skills.md

@@ -43,22 +43,23 @@ description: Extract durable project facts ... Use when ...
 | `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-clarity` | Prose clarity in comments, docstrings, error strings, and docs: made-up phrases, buzzwords, untranslated jargon, clause chains, buried leads, doc/code responsibility splits, checked against the project's clear-writing rules regardless of who wrote the text. |
 | `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-technique` | Technique lens: teaching-grade notes on unseen helpers/internal packages, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Informational only, verified citations, never blocking. |
-| `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, linked docs/tickets followed from the change, memory) before fan-out. Prevents false positives about intentionally deferred work, and checks whether main moved past the merge-base touching the same paths (staleness signal for the synthesizer). 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-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, and against sibling PR registers when related PRs were detected (cross-PR notes appendix). |
+| `thatch-review-context` | Gather project/feature context (PR descriptions, git archaeology, ticket references, linked docs/tickets followed from the change, memory) before fan-out. Prevents false positives about intentionally deferred work, and checks whether main moved past the merge-base touching the same paths (staleness signal for the synthesizer). 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. Also discovers related PRs (stacks chained through base branches, release trains ordered by tracker relations) and builds a sibling register with targeted consistency verdicts. |
 | `thatch-code-archaeology` | Investigate an existing feature, debug an unfamiliar area, or begin a new ticket. Explores the code base from multiple angles (data model, state flow, git history, sibling features, skeletons) before proposing changes. The research skill; pair with `thatch-coding-workflow`. |
 | `thatch-review-followup` | Alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review round adequately addressed your prior findings, offers to reply on resolved items, then optionally re-runs the full structured review. |
 | `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). |
 | `thatch-coding-workflow` | Plan and execute code changes with a task-list-driven workflow. Use when implementing features, fixing bugs, or making multi-file changes. |
-| `thatch-plan-refinement` | Refine a plan before implementing it: fresh-context reviewer rounds until consensus, with an optional deep-mode lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology). The generic core loop. |
-| `thatch-refine` | Classify the project (audience, lifecycle, surface) and refine a plan under that type's requirements. Entry point for the `thatch-refine-*` family; also the `/thatch/refine` command. |
+| `thatch-plan-refinement` | Refine a plan before implementing it: fresh-context reviewer rounds until consensus, with an optional deep-mode lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology). The generic core loop. Plans with UI or session state carry a state-and-transition matrix; template ports carry a deltas-from-template ledger; a revision self-check runs between revise and re-review; user-extended runs rotate reviewer lenses and stop on a round with no build-changing findings. Deep-mode triggers are binding. |
+| `thatch-refine` | Classify the project (audience, lifecycle, surface) and refine a plan under that type's requirements. Entry point for the `thatch-refine-*` family; also the `/thatch/refine` command. Deep-mode triggers in the core skill are binding; type deltas relax round counts, never mode selection. |
 | `thatch-refine-team-app` | Refinement deltas for multi-developer team codebases: consistency outranks cleverness, intent breadcrumbs are deliverables, pre-mortem and safe-to-modify lenses dominate. |
-| `thatch-refine-personal` | Refinement deltas for solo projects with no downstream consumers: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest. |
+| `thatch-refine-personal` | Refinement deltas for solo projects with no downstream consumers: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest. Relaxes round counts only, never mode selection. |
 | `thatch-refine-shared-lib` | Refinement deltas for changes touching a library's API surface: flexible on input, strict on output, keep special cases out of the API, never foreclose caller options, docs are a deliverable. |
 | `thatch-refine-spike` | Refinement deltas for throwaway prototypes: skip the loop, verify only the premises the experiment's conclusion depends on, state the question and the time box. |
 | `thatch-refine-infra` | Refinement deltas for CI, Terraform, and k8s changes: blast radius across pipelines and environments, rollback plan and staged verification are mandatory, pattern-following is near-absolute. |
@@ -75,11 +76,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 review 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 review specialists in parallel, synthesize with a workflow-change preface, prior-comment cross-reference, and sibling-register cross-reference. Also the machinery behind the `/thatch/self-review` and `/thatch/peer-review` mode commands, which run it with a weighting overlay (inline, without sub-agents, on hosts that lack the coordinator). |
 
 ## REVIEW_COMMON
 
-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):
+The problem-finding review specialists share a framework interpolated via `${REVIEW_COMMON}` (the technique and highlights specialists do not use it: technique reports informational notes and highlights finds positive things, each with its own structure):
 
 - **Static analysis only** — no running tests/linters/compilers.
 - **Scope gathering** — resolve the git range, `git diff --stat`, read changed
@@ -93,6 +94,9 @@ The seven problem-finding review specialists share a framework interpolated via
 - **Project context awareness** — if a context brief is provided (from the
   coordinator or from loading `thatch-review-context`), use it to avoid false
   positives about intentionally deferred work.
+- **Sibling PR context** — when the brief's sibling register is present
+  (related PRs detected), check it before flagging anything as referenced but
+  missing; a stack member or release-train sibling may deliver the piece.
 - **Workflow context awareness** — if a workflow guide is provided (from the
   coordinator or from loading `thatch-code-archaeology`), use it to understand
   the purpose and evolution of the code, distinguishing intentional behavior
@@ -143,7 +147,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 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.
+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 technique and highlights specialists do not use REVIEW_COMMON — technique reports informational notes and highlights finds positive things, so the problem-finding framework does not apply to either.
 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.

package/docs/user/README.md

@@ -202,11 +202,11 @@ requirements.
 | Tool | What it does |
 |------|-------------|
 | `thatch_chat_register` | Join the cross-session chat directory, so other sessions on this machine can message you. Display names are assigned by thatch, never chosen (a pool name plus a never-reused counter), so a name always refers to the same session. Call with no arguments to join, rejoin after unregistering, or check your name. On hosts without session context (Claude Code, Cursor), pass the name your thatch hook printed as `as`. |
-| `thatch_chat_list` | List registered sessions grouped into Active and Stale sections (stale = two missed heartbeats, about a minute; its host process has probably stopped), with how long ago each last checked in, each session's project and checkout kind (project root or linked worktree), its topic, and your unread count. |
+| `thatch_chat_list` | List registered sessions grouped into Active, Recent, and Stale sections (recent = alive but no open tab, so a wake may not be guaranteed; stale = two missed heartbeats, about a minute; its host process has probably stopped), with how long ago each last checked in, each session's project and checkout kind (project root or linked worktree), its topic, and your unread count. |
 | `thatch_chat_send` | Send a message to another registered session, by name or session id. The recipient is nudged when its session is idle. |
 | `thatch_chat_read` | Drain your inbox: all unread messages oldest-first, marked read. Senders identified by display name. |
 | `thatch_chat_unregister` | Leave the chat directory. |
-| `thatch_chat_broadcast` | Send one message to every other live registered session at once. Stale sessions (dead host processes) are skipped and reported. Use sparingly: every live session pays a model turn for a broadcast. |
+| `thatch_chat_broadcast` | Send one message to every other live registered session at once. Opencode sessions without an open tab (stale, or fresh but tab-less) are skipped and reported by name. Use sparingly: every open session pays a model turn for a broadcast. |
 
 See [cross-session-chat.md](cross-session-chat.md) for the full behavior,
 liveness model, and limitations.
@@ -248,16 +248,23 @@ Beyond the tools, thatch hooks into opencode itself:
   flushes pending fact extraction, finishes any promised memory writes, and
   surfaces todos or follow-ups it never addressed. The agent ends its
   response with a greenlight token only when the checklist is clean. Thatch
-  watches for the token and then runs the compaction or exits opencode.
+  watches for the token and then runs the compaction or closes the session
+  (opencode 1 exits the whole app; opencode 2 closes the session's own tab.
+  Either way the session's watches are cancelled, and reopening or resuming
+  the session does not re-arm them - re-create watches you still want with
+  `thatch_watch_create`).
   Without the token nothing fires -- a toast points you at the items the
-  agent listed, and you re-run the command once they're handled. Text typed
+  agent listed in its response, and you re-run the command once they're
+  addressed. Text typed
   after the command reaches the agent first, labeled as a `User Message`
   section ahead of the checklist (say goodbye or hand off context:
   `/thatch/exit Good work - see you tomorrow`). Alongside the wrap-ups,
-  on-demand actions (`/thatch/defrag`, `/thatch/extract`, `/thatch/hygiene`,
-  `/thatch/reflect`, `/thatch/whois`) run the memory-maintenance behaviors
-  whenever you want,
-  not just when a nudge fires -- see [commands.md](commands.md).
+  on-demand actions cover the memory-maintenance behaviors (`/thatch/defrag`,
+  `/thatch/extract`, `/thatch/hygiene`, `/thatch/reflect`) whenever you
+  want, not just when a nudge fires, plus the standalone commands: plan
+  refinement (`/thatch/refine`), the review modes (`/thatch/self-review`,
+  `/thatch/peer-review`), and the chat identity report (`/thatch/whois`)
+  -- see [commands.md](commands.md).
   A greenlit `/thatch/exit` also unregisters the session from the chat
   directory, so other sessions stop sending it mail. The commands
   self-install into `~/.config/opencode/command/thatch/` at plugin startup;
@@ -324,22 +331,23 @@ response, walkthrough, and workflow skills that support the review pipeline:
 | `thatch-review-state-flow` | Data flow and contracts: module boundaries, implicit state machines, error propagation, separation of concerns. |
 | `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, hedging, filler. |
+| `thatch-review-clarity` | Prose clarity in comments, docstrings, error strings, and docs: made-up phrases, buzzwords, untranslated jargon, clause chains, buried leads, doc/code responsibility splits, checked against the project's clear-writing rules regardless of who wrote the text. |
 | `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-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar against generic praise. |
 | `thatch-review-technique` | Technique lens: teaching-grade notes on unseen helpers/internal packages, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Informational only, never blocking. |
 | `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, linked docs/tickets, memory) before a review. Prevents false positives about intentionally deferred work. |
+| `thatch-review-context` | Gathers project context (PR descriptions, git archaeology, ticket references, linked docs/tickets, memory, related PRs) before a review. Prevents false positives about intentionally deferred work and about pieces delivered by sibling PRs in a stack or release train. |
 | `thatch-code-archaeology` | Investigates an existing feature, debugs an unfamiliar area, or begins a new ticket. Explores the code base from multiple angles (data model, state flow, git history, sibling features, skeletons) before proposing changes. Pairs with `thatch-coding-workflow`. |
 | `thatch-review-followup` | Alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review adequately addressed your prior findings, offers to reply on resolved items, then optionally re-runs the full structured review. |
 | `thatch-review-response` | Author-side review response: triage findings on your own PR, fix bugs one by one, reply on each thread, post a top-level summary comment. |
 | `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. |
 | `thatch-coding-workflow` | Plans and executes code changes with a task-list-driven workflow: complexity triage, milestone planning, research before coding, post-coding verification. Pairs with `thatch-code-archaeology` (research first, then plan). |
-| `thatch-plan-refinement` | Refines a plan before it is implemented: a fresh-context reviewer subagent re-checks the plan each round until consensus; deep mode adds specialist lenses (reuse, alternatives, hidden problems, safe-to-modify, intent archaeology). |
-| `thatch-refine` | Classifies the project (audience, lifecycle, surface) and refines a plan under that type's requirements. The entry point for the `thatch-refine-*` family; also the `/thatch/refine` command. |
+| `thatch-plan-refinement` | Refines a plan before it is implemented: a fresh-context reviewer subagent re-checks the plan each round until consensus; deep mode adds specialist lenses (reuse, alternatives, hidden problems, safe-to-modify, intent archaeology). Plans with UI or session state must include a state-and-transition matrix; a revision self-check runs after each revision; extended runs rotate reviewer lenses and stop on a round with no build-changing findings. |
+| `thatch-refine` | Classifies the project (audience, lifecycle, surface) and refines a plan under that type's requirements. The entry point for the `thatch-refine-*` family; also the `/thatch/refine` command. Deep-mode triggers in the core skill are binding; type deltas relax round counts, never mode selection. |
 | `thatch-refine-team-app` | Team codebases: consistency outranks cleverness, intent breadcrumbs are deliverables, pre-mortem and safe-to-modify lenses dominate. |
-| `thatch-refine-personal` | Solo projects: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest. |
+| `thatch-refine-personal` | Solo projects: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest. Relaxes round counts, never mode selection. |
 | `thatch-refine-shared-lib` | Library API surfaces: flexible on input, strict on output, keep special cases out of the API, never foreclose caller options, docs are a deliverable. |
 | `thatch-refine-spike` | Throwaway prototypes: skip the loop, verify only the premises the experiment's conclusion depends on. |
 | `thatch-refine-infra` | CI, Terraform, and k8s changes: blast radius, mandatory rollback plan and staged verification, pattern-following is near-absolute. |
@@ -358,7 +366,7 @@ response, walkthrough, and workflow skills that support the review pipeline:
 
 | Skill | Purpose |
 |-------|---------|
-| `thatch-code-review` | Multi-agent review coordinator. Dispatches parallel sub-agents for triage, decomposition, specialist fan-out, and synthesis with a workflow-change preface. Not available in Claude Code (requires sub-agent support). |
+| `thatch-code-review` | Multi-agent review coordinator. Dispatches parallel sub-agents for triage, decomposition, specialist fan-out, and synthesis with a workflow-change preface. Not available in Claude Code (requires sub-agent support), though the `/thatch/self-review` and `/thatch/peer-review` commands run the same specialists inline there. |
 
 ### Host availability
 
@@ -399,7 +407,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, mark-and-sweep ...
+3. ... repeat for state-flow, no-slop, clarity, breadcrumbs, mark-and-sweep ...
 4. Load thatch-review-synthesizer, verify and aggregate all findings.
 ```
 

package/docs/user/behavior-engine.md

@@ -24,13 +24,19 @@ the agent's context. The block looks like:
 - [0.58 conf, 1 tests] When about to commit changes to the repo:
   do Run mise run check (tsc + bun test + markdownlint) before
   committing. Never commit code that fails the quality gate.
+Snapshot: these labels reflect the behavior store as of this message's
+submission. Behaviors updated after submission (including during this
+turn) do not refresh it; re-check with thatch_behavior_list before
+relying on them.
 ```
 
 The agent evaluates each surfaced rule against the current situation.
 If relevant (ham), it follows the rule and calls `behavior_feedback`
 with `relevant: true`. If not relevant (spam), it calls
 `behavior_feedback` with `relevant: false`. This trains the classifier
-so future nudges are more accurate.
+so future nudges are more accurate. On Claude Code and Cursor the
+footer's tool name appears with its MCP spelling
+(`mcp__thatch__behavior_list`).
 
 ## Default behaviors
 

package/docs/user/cli.md

@@ -4,6 +4,10 @@ Thatch ships with a command-line tool for inspecting memories and
 running maintenance tasks outside the agent. It requires `bun` on your
 PATH.
 
+`thatch --help` (or `-h`) prints the full command list and exits 0.
+The flag works anywhere in the command line: `thatch chat list -h`
+shows help instead of running the command.
+
 ## Memory inspection
 
 ```bash
@@ -45,7 +49,8 @@ Read-only access to the chat directory your opencode sessions share
 (see [cross-session-chat.md](cross-session-chat.md)):
 
 ```bash
-thatch chat list               # who is registered: name, age, project, topic
+thatch chat list               # who is open now: name, age, project, topic
+thatch chat list --recent      # also show alive sessions with no open tab
 thatch chat list --stale all   # also show stale sessions older than a day
 thatch chat tail               # follow sent and read events, live (JSONL)
 thatch chat tail --once        # print the last 20 messages and exit
@@ -55,20 +60,28 @@ thatch chat tail --from al --to bob        # substring match on names
 thatch chat tail --since 2026-09-12 --until "2026-09-13 09:00"   # a window
 ```
 
-`chat list` shows every registered session in two sections, Active and
-Stale, each as aligned columns under a header row: how long since its
-last heartbeat, its status (`fresh` or `stale` for opencode sessions;
-`active` or `idle` for Claude Code and Cursor sessions, which only beat
-when a prompt runs), its project, and its topic (the session's title) -
-the fastest way to answer "which session should I talk to about X?"
-Rows are grouped by project (alphabetical; sessions with no project
-last), most recently seen first within each project. A
-stale session has missed two heartbeats, about a minute: the opencode
-process hosting it has probably stopped. The stale section shows rows
-up to one day old by default; older ones collapse into a hidden-count
-note so long-dead sessions cannot bury the fresh signal. Pass
-`--stale N` (days) to widen the window or `--stale all` to see every
-stale row. Color is added only when the
+`chat list` renders the chat roster in three sections - Active, Recent,
+and Stale - each as aligned columns under a header row: how long since its last heartbeat, its status (`open` - a tab is open now - or
+`recent` - host alive, no open tab - for opencode sessions; `active` or
+`idle` for Claude Code and Cursor sessions, which only beat when a
+prompt runs), its project, and its topic (the session's title) - the
+fastest way to answer "which session should I talk to about X?" Rows
+are grouped by project (alphabetical; sessions with no project last),
+most recently seen first within each project.
+
+The default view shows the sessions you can wake or reach now: open
+sessions plus Claude Code and Cursor rows, which read mail at their
+next prompt. A recent session - its harness is alive but its tab is
+closed, so a wake may not reach it until the tab reopens - collapses
+into a muted hidden-count note pointing at `--recent`, which reveals
+the Recent section. A stale session has missed two heartbeats, about a
+minute: the opencode process hosting it has probably stopped. Its
+section is hidden too, behind `--stale`, but without a count note - the
+default view simply drops stale rows. The stale section
+shows rows up to one day old by default; older ones collapse into a
+hidden-count note so long-dead sessions cannot bury the fresh signal.
+Pass `--stale N` (days) to widen the window or `--stale all` to see
+every stale row. Color is added only when the
 output is a terminal; a pipe prints plain aligned text.
 
 `chat tail` prints the conversation as a JSONL event log: one JSON

package/docs/user/code-review.md

@@ -16,13 +16,16 @@ the review:
 2. **Gather project context**: PR descriptions, git archaeology,
    ticket references, links to docs/designs/tickets found in the
    change (followed one hop for scope and design context), TODO
-   markers, prior reviews, project memory. Also checks whether main
+   markers, prior reviews, project memory. Also discovers related
+   PRs (stacks chained through base branches, release trains
+   ordered by ticket relations) and checks consistency between
+   them and the change. Also checks whether main
    has moved past the merge-base touching the same paths — a stale
    branch can make findings true only at the merge-base.
 3. **Research affected workflows**: load `thatch-code-archaeology`,
    trace the code paths the change touches.
 4. **Estimate complexity**: partition the diff into review units.
-5. **Dispatch specialists**: fan out the nine specialists as
+5. **Dispatch specialists**: fan out the specialists as
    parallel sub-agents, each with the context brief.
 6. **Synthesize**: the synthesizer reads all specialist output,
    verifies each finding (cited text exists, claim is accurate,
@@ -30,8 +33,12 @@ the review:
    the final report. When the branch is stale relative to main, it
    re-verifies behavioral findings against current main and reports
    merge-base-only findings as rebase notes rather than defects.
+   When related PRs were detected, it cross-references findings
+   against the sibling register: a missing piece delivered by a
+   sibling is not a defect, and inconsistencies between connected
+   PRs surface as cross-PR notes.
 
-## The nine specialists
+## The specialists
 
 | Skill | What it checks |
 |-------|-------------|
@@ -40,6 +47,7 @@ the review:
 | `thatch-review-state-flow` | Module boundaries, implicit state machines, error propagation, separation of concerns. |
 | `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, hedging, filler. |
+| `thatch-review-clarity` | Prose clarity in comments, docstrings, error strings, and docs: made-up phrases, buzzwords, untranslated jargon, clause chains, buried leads, doc/code responsibility splits, checked against the project's clear-writing rules regardless of who wrote the text. |
 | `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-highlights` | Positive finding detection: clever solutions, cleanup done along the way, documentation that helps. Medium-high bar. |
@@ -48,6 +56,34 @@ the review:
 Each specialist is a self-contained static-analysis pass. They can run
 individually or as part of the coordinated review.
 
+## Review modes: /thatch/self-review and /thatch/peer-review
+
+Two slash commands run the same pipeline with the findings weighted for
+whose work is under review.
+
+- `/thatch/self-review` reviews your own completed work before you
+  submit it. The slop, clarity, technique, and breadcrumbs lenses weigh
+  heaviest, simplicity is overweighted on shared projects, and
+  technique or highlights findings that would simplify the design are
+  surfaced for an adopt-or-dismiss decision rather than left as
+  footnotes. The review iterates: after each round you fix or decline
+  each finding, and the next round re-reviews the updated state until
+  a round produces no meaningful findings (at most three rounds).
+- `/thatch/peer-review` reviews another author's change. Findings are
+  weighted for org velocity: simpler ways to the same outcome, existing
+  helpers that already do the work, extremely clear documentation, and
+  unintended consequences for callers and siblings. The review walks
+  the project's persistent memory for incidents, constraints, and
+  footguns the author could not have known, and checks them against
+  the change. Settled designs are not re-litigated, and "if someone
+  changes this later it breaks" findings are never reported; instead
+  the review verifies the change leaves a breadcrumb trail to wherever
+  the project records how the feature works.
+
+Both commands work on every host. On opencode they drive the
+coordinator with sub-agents. On Claude Code and Cursor the same
+procedure runs the specialists inline, in sequence.
+
 ## Follow-up rounds
 
 After the author responds or pushes changes, `thatch-review-followup`
@@ -55,6 +91,10 @@ verifies whether prior findings were adequately addressed before
 deciding whether to re-run the full review. The author must either
 fix the code, prove the finding is not a concern with a checkable
 argument, or file a follow-up ticket with a risk explanation.
+Between rounds the author may merge the default branch — or, on a
+stacked PR, merge or rebase onto the base branch — into the branch;
+the followup excludes those commits so only the author's own changes
+are verified.
 
 ## Author-side response
 
@@ -67,7 +107,9 @@ one, reply on each thread, and post a top-level summary comment.
 
 - The coordinator (`thatch-code-review`) is opencode-only. It
   requires sub-agent support to dispatch parallel specialists. On
-  Claude Code or Cursor, run specialists individually instead.
+  Claude Code or Cursor, run specialists individually instead; the
+  `/thatch/self-review` and `/thatch/peer-review` commands package
+  exactly that inline sequence, with a mode overlay on top.
 - The review quality depends on the model. Weak models may
   hallucinate findings or miss subtle issues.
 - The synthesizer verifies cited text exists, but it does not

package/docs/user/commands.md

@@ -1,9 +1,11 @@
 # Slash commands
 
 Thatch ships `/thatch/*` commands you run yourself, on top of the nudges the
-plugin fires on its own schedule. Nudges and commands share the same
-instruction text, so a behavior works the same whether it fires automatically
-or you invoke it.
+plugin fires on its own schedule. The nudge-backed commands (`defrag`,
+`extract`, `hygiene`, `reflect`) share their instruction text with the
+nudges, so a behavior works the same whether it fires automatically or you
+invoke it. The remaining commands (`refine`, `self-review`, `peer-review`,
+`whois`) stand alone.
 
 ## Commands
 
@@ -26,9 +28,24 @@ or you invoke it.
   project type's requirements: the agent classifies the project (team,
   personal, shared library, spike, infrastructure, or open source
   contribution), confirms the pick, and runs the refinement loop with
-  that type's expectations applied. Text after the command can name the
-  type directly (for example, `/thatch/refine shared-lib`) to skip
-  classification.
+  that type's expectations applied. Project type relaxes round counts
+  and documentation bars, never the deep-mode triggers. Text after the
+  command can name the type directly (for example, `/thatch/refine
+  shared-lib`) to skip classification.
+- `/thatch/peer-review` — review another author's change: the full review
+  pipeline with findings weighted for org velocity. Text after the command
+  names the review target (for example, `/thatch/peer-review 1234` for a
+  PR). The review walks the project's persistent memory for
+  incidents, constraints, and footguns the author could not have known,
+  and checks them against the change. Settled designs are not
+  re-litigated, and "if someone changes this later it breaks" findings
+  are never reported. See [code-review.md](code-review.md).
+- `/thatch/self-review` — review your own completed work before
+  submitting it: the full review pipeline weighted for reputation and
+  simplicity. Takes the same target argument as peer-review. Rounds
+  iterate (fix or decline each finding, then re-review the updated
+  state) until a round produces no meaningful findings, at most three.
+  See [code-review.md](code-review.md).
 - `/thatch/compact` and `/thatch/exit` — the wrap-up commands. They run a
   pre-flight checklist (flush extraction, finish promised memory writes,
   surface loose ends) before a compaction or an exit, gated by a greenlight
@@ -45,11 +62,14 @@ or you invoke it.
 | `/thatch/reflect` | yes | yes | yes (as an MCP prompt) |
 | `/thatch/whois` | yes | no | no |
 | `/thatch/refine` | yes | yes | yes (as an MCP prompt) |
+| `/thatch/peer-review` | yes | yes | yes (as an MCP prompt) |
+| `/thatch/self-review` | yes | yes | yes (as an MCP prompt) |
 | `/thatch/compact`, `/thatch/exit` | yes | no | no |
 
 Why the gaps: `/thatch/extract` and `/thatch/whois` need the invoking
 session's ID, which only the opencode plugin can supply. The wrap-up
-commands trigger TUI actions through the plugin. Cursor has no file-based
+commands trigger host actions (the compaction and the session close-out)
+through the plugin. Cursor has no file-based
 commands; its prompts come from the MCP server (`prompts/list` and
 `prompts/get`).
 

package/docs/user/cross-session-chat.md

@@ -25,13 +25,21 @@ explicitly with `thatch_chat_register` (no arguments) - useful after
 `chat_unregister`, or just to check your assigned name. Once registered:
 
 - `thatch_chat_list` shows every registered session on the machine, grouped
-  into Active and Stale sections: active sessions can be woken; stale ones
-  have missed two heartbeats, about a minute (the opencode process hosting
-  them has probably stopped). Each row carries how long ago the session last
+  into Active, Recent, and Stale sections: active sessions either have an
+  opencode tab open right now or are Claude Code and Cursor rows, which
+  read mail at their next prompt; recent ones are alive but have no open
+  tab, so a wake may not reach them until the tab reopens; stale
+  ones have missed two heartbeats, about a minute (the opencode process
+  hosting them has probably stopped). Each
+  row carries how long ago the session last
   checked in, its project, whether it runs in the project root or a linked
   git worktree, its topic, and your unread count
 - `thatch_chat_send` delivers a message to another registered session, by
   name or session id, and states the recipient's liveness at send time.
+  For a recipient with no open tab it says so plainly: the message waits
+  in the inbox, but the wake is not guaranteed to start a turn
+  (daemon-resident sessions like subordinates usually still pick the
+  message up on their next activity).
   An identical resend within a few seconds is treated as a client retry:
   while the first copy is still unread it succeeds but delivers nothing
   new (the tool output says so); once the recipient has read it, the same
@@ -46,13 +54,16 @@ explicitly with `thatch_chat_register` (no arguments) - useful after
   the rest with the `message` and `offset` arguments (each drain line
   carries the message id). Paging never marks anything read
 - `thatch_chat_broadcast` delivers one message to every other live
-  registered session at once (a long body is split per recipient, exactly
-  like a split `chat_send`)
+  registered session that has a tab open, plus every MCP session (a long
+  body is split per recipient, exactly like a split `chat_send`)
 - `thatch_chat_unregister` leaves the directory
 
 When mail arrives for an idle session, thatch wakes it with a notification -
 the agent gets a model turn even with nobody at the keyboard, reads its
-inbox, and decides what to do. The notification names the senders and the
+inbox, and decides what to do. If the session's directory has been deleted
+(a merged branch's worktree, for example), the wake is skipped quietly:
+no error appears, the mail stays queued, and it delivers normally once the
+directory exists again. The notification names the senders and the
 count only; the agent reads the actual messages itself. A split message
 arrives as one grouped notification ("N unread messages from X"), and the
 parts carry their own markers so the reader assembles the whole before
@@ -61,10 +72,14 @@ the last is suffixed "(continued in next message)".
 
 Broadcasts are for announcements and open questions ("which of you is
 working on the payments code?", "main just moved, rebase if you are based
-on it"). Every live session gets the message and spends a model turn on it,
+on it"). Every OPEN session gets the message and spends a model turn on it,
 so broadcast sparingly - for anything with a known audience, `chat_send` is
-the polite tool. Stale sessions are skipped and reported: a dead session
-never reads a broadcast.
+the polite tool. Sessions without an open tab are skipped and reported by
+name: a stale session will never read the mail, and a fresh-but-tab-less
+session (a closed tab, or a headless subordinate) is not reliably wakeable,
+so messaging it would spend a turn on a delivery that likely never runs.
+With opencode tabs disabled, broadcasts reach only MCP sessions - that is
+the honest reading of "no tab signal", never a false fan-out.
 
 ## Watching the conversation
 
@@ -149,21 +164,34 @@ host the sessions run in.
 
 ## Liveness
 
-A session shows as fresh while the opencode process hosting it is
-running: hosted sessions keep beating (idle ones included), so the
-freshness is real. When that process dies, its sessions stop beating and
-show as stale about a minute later (two missed heartbeats), grouped into
-a separate Stale section. A laptop that slept reads the same way until
-its processes catch up.
+Liveness has three levels, and the roster shows which one a row is in.
+
+The base signal is the heartbeat: a session shows as fresh while the
+opencode process hosting it is running - hosted sessions keep beating
+(idle ones included), so the freshness is real. When that process dies,
+its sessions stop beating and show as stale about a minute later (two
+missed heartbeats), grouped into a separate Stale section. A laptop that
+slept reads the same way until its processes catch up.
+
+The second signal, read at roster time, is opencode's own tab state: a
+fresh row whose session has a tab open right now shows as `open`, one
+without shows as `recent`. `recent` covers finished-but-recently-active
+conversations, closed tabs, and daemon-resident sessions that never had a
+window (subordinates) - the harness is alive, but presence is unknown.
+With tabs disabled (or no opencode state on the machine) every fresh row
+shows as `recent`: an unknown tab state never reads as open.
+
 Messages to a stale session wait in its inbox unread - a dead session
-never reads them, and `chat_send` says so at send time. Continuing a
+never reads them, and `chat_send` says so at send time. Messages to a
+`recent` session are delivered, but `chat_send` warns that the wake is
+not guaranteed without an open tab. Continuing a
 session with `opencode -s <id>` reclaims its name and row, and any mail
 that queued while it was down is delivered at startup. Explicitly
 closing a session (deleting it in the TUI) unregisters it immediately,
-and a greenlit `/thatch/exit` unregisters the session too: the wrap-up
-checklist calls `chat_unregister`, and the plugin removes the row itself
-when the exit token passes the greenlight check, so other sessions stop
-addressing mail to a process that is about to vanish.
+and a greenlit `/thatch/exit` unregisters the session too: the plugin
+removes the row itself when the exit token passes the greenlight check,
+so other sessions stop
+addressing mail to a session that is closing out.
 
 ## Turning chat off
 

package/docs/user/prediction-engine.md

@@ -46,10 +46,21 @@ like:
   flag tech debt before reviewing the diff
 - [0.61 conf, 2 tests] When choosing test scope: you may prefer
   integration tests over unit tests
+Snapshot: these labels reflect the prediction store as of this message's
+submission. Predictions updated after submission (including during this
+turn) do not refresh it; re-check with thatch_prediction_query before
+relying on them.
 ```
 
 The agent reads this and decides whether to follow the prediction,
-surface it to you, or ignore it. You never see the nudge directly.
+surface it to you, or ignore it. You never see the nudge directly. The
+snapshot line matters when the agent corrects the model mid-conversation
+(you say "no, that's wrong" and it calls `thatch_prediction_delete`):
+the block it saw at the start of the turn is a submission-time snapshot
+and does not update. The agent should re-query with
+`thatch_prediction_query` instead of trusting the block's labels. On
+Claude Code and Cursor the tool name appears with its MCP spelling
+(`mcp__thatch__prediction_query`).
 
 ## Tools