@jeffober/thatch 0.2.5 → 0.2.6

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,20 @@ 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 and Stale sections: active sessions' harness is alive; stale
+  ones have missed two heartbeats, about a minute (the opencode process
+  hosting them has probably stopped). Each active row also carries a
+  liveness verdict: `open` means the session has an opencode tab open
+  right now, `recent` means the harness is alive but no tab is open. 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 +53,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 +71,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 +163,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
 

package/docs/user/skills.md

@@ -48,11 +48,11 @@ Skills are split into shared (all hosts) and opencode-only:
 | `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar. |
 | `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 deduplicated, severity-grouped report. |
-| `thatch-review-context` | Gathers project context (PRs, tickets, linked docs/designs followed from the change, TODOs, deferred work) before a review. Prevents false positives about intentionally deferred work. |
+| `thatch-review-context` | Gathers project context (PRs, tickets, linked docs/designs followed from the change, TODOs, deferred work, 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. The research skill; pair with `thatch-coding-workflow`. |
 | `thatch-review-followup` | Verifies whether the author's responses and code changes since your last review adequately addressed your prior findings. |
 | `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-code-review` | Multi-agent review coordinator (opencode-only). Dispatches parallel sub-agents for specialist fan-out and synthesis. |
+| `thatch-code-review` | Multi-agent review coordinator (opencode-only). Dispatches parallel sub-agents for specialist fan-out and synthesis. Also the machinery behind the `/thatch/self-review` and `/thatch/peer-review` mode commands, which couch it with a weighting overlay and run the specialists inline on hosts where the coordinator is not installed. |
 
 ### Walkthrough skills
 
@@ -75,15 +75,15 @@ Skills are split into shared (all hosts) and opencode-only:
 | Skill | Purpose |
 |-------|---------|
 | `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-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. |
 
 ### Plan refinement skills
 
 | Skill | Purpose |
 |-------|---------|
-| `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-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. |
@@ -104,7 +104,9 @@ window.
   re-installs from its canonical source). Edit the canonical source
   in the thatch repo instead.
 - The opencode-only coordinator (`thatch-code-review`) requires
-  sub-agent support. It is not available on Claude Code or Cursor.
+  sub-agent support. It is not available on Claude Code or Cursor; the
+  `/thatch/self-review` and `/thatch/peer-review` commands run the
+  same specialists inline there instead.
 - Skill content is markdown read at runtime, not compiled into the
   binary. If the skill file is missing or corrupted, the skill will
   not load (silent failure).

package/package.json

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

package/src/capabilities.ts

@@ -54,7 +54,13 @@ export interface HostCapabilities {
    * only the title carries over.
    */
   sessionCreate(input: { parentID: string; title: string }): Promise<{ id: string }>;
-  /** Delete a session (child-session cleanup). Degrades to a no-op resolve on v2. */
+  /**
+   * Delete a session (extraction-child cleanup, so the picker stays clean
+   * and `-c` resume does not land in a child). v1: client delete. v2:
+   * session.remove on the promise domain (upstream #52387), runtime-guarded
+   * because the pinned dev types predate the surface - an older host
+   * degrades to a no-op (best-effort by the caller's contract).
+   */
   sessionDelete(id: string): Promise<void>;
   /**
    * Prompt a session with text parts. `sync` mode blocks until the child
@@ -90,15 +96,23 @@ export interface HostCapabilities {
   /**
    * Trigger the host's compaction for a session (the wrap-up compact
    * action). v1 dispatches the TUI's session_compact command (the legacy
-   * alias route; the id is ignored). v2 has no compaction trigger reachable
-   * from the promise context and degrades to a logged no-op.
+   * alias route; the id is ignored). v2 calls session.compact on the
+   * promise domain (upstream #52385), runtime-guarded because the pinned
+   * dev types predate that surface; an older host degrades to a logged
+   * no-op.
    */
   compactSession(sessionID: string): Promise<void>;
   /**
-   * Exit the host application (the wrap-up exit action). v1 publishes the
-   * TUI's app.exit command; v2 has no TUI surface and degrades to a no-op.
+   * End the session's presence on the host (the wrap-up exit action). The
+   * runtime records the session's watcher deaths and unregisters it from
+   * chat BEFORE calling here, so implementations only close out the host
+   * side. v1 publishes the TUI's app.exit command - the id is unused
+   * because the whole app is leaving. v2 emits the session-tab bridge's
+   * exit-tab-closed event, a TUI-only close of the session's OWN tab (the
+   * daemon hosts every tab, so an app-wide exit would take down unrelated
+   * sessions too); a host with no bridge degrades to a logged no-op.
    */
-  exitHost(): Promise<void>;
+  exitHost(sessionID: string): Promise<void>;
 }
 
 /**

package/src/chat.ts

@@ -351,18 +351,28 @@ export function humanAge(iso: string, now = Date.now()): string {
   return `${Math.floor(minutes / (24 * 60))}d ago`;
 }
 
-/** The liveness verdict for one roster row, from heartbeat age alone:
- *  - "fresh"/"stale" for opencode rows (poller-driven heartbeat; stale means *    the hosting harness has missed two beats and is presumed gone)
- *  - "active"/"idle" for MCP rows (turn-driven; idle between prompts is the
- *    NORMAL state, so an idle MCP row is reachable, not dead)
- *  Heartbeat age is the only signal on purpose. A process id cannot serve:
- *  the same session is re-hosted by a new process on every `-s` resume, so
- *  a pid stamped on the row lies as soon as a different harness beats it.
- *  One clock, one rule. */
-export function chatLiveness(row: ChatSessionRow, now = Date.now()): "fresh" | "stale" | "active" | "idle" {
+/** The liveness verdict for one roster row, from heartbeat age plus (for
+ *  opencode rows) the open-tab set:
+ *  - "open" - fresh heartbeat AND a tab is open now (session presence)
+ *  - "recent" - fresh heartbeat, no known tab: an instance that saw this
+ *    session is alive and beating it, but the session itself may or may
+ *    not be wakeable (a closed tab's wake can be swallowed; a daemon-
+ *    resident subordinate runs headless and may still pick up mail)
+ *  - "stale" - the hosting harness has missed two beats and is presumed
+ *    gone
+ *  - "active"/"idle" for MCP rows (turn-driven; idle between prompts is
+ *    the NORMAL state, so an idle MCP row is reachable, not dead)
+ *  Heartbeat age alone decides staleness - a process id cannot serve: the
+ *  same session is re-hosted by a new process on every `-s` resume, so a
+ *  pid stamped on the row lies as soon as a different harness beats it.
+ *  The tab set is a READ-ONLY refinement (src/tab-state.ts) consumed at
+ *  render/broadcast time; omitting it degrades every fresh opencode row
+ *  to "recent" - honest, never a false "open". */
+export function chatLiveness(row: ChatSessionRow, now = Date.now(), openTabs?: ReadonlySet<string>): "open" | "recent" | "stale" | "active" | "idle" {
   const stale = isStale(row, now);
   if (row.host_kind === "mcp") return stale ? "idle" : "active";
-  return stale ? "stale" : "fresh";
+  if (stale) return "stale";
+  return openTabs?.has(row.session_id) ? "open" : "recent";
 }
 
 /** Orders roster rows for display: project first (so a shared-tree reader
@@ -858,10 +868,16 @@ export class ChatStore {
   }
 
   /**
-   * Posts a message to every other registered session at once. Stale
-   * sessions are skipped, not messaged - a host process that has stopped
-   * heartbeat-ing will never read the mail, and a broadcast is for reaching
-   * live agents. Each recipient gets its own inbox row per part, so the
+   * Posts a message to every other registered session at once. Opencode
+   * rows are skipped unless they are OPEN - a fresh heartbeat AND a tab
+   * open right now. Both skip classes are honest: a STALE row's host
+   * process has stopped heartbeat-ing and will never read the mail, and a
+   * RECENT row (fresh heartbeat, no open tab) is not reliably wakeable -
+   * the wake can be swallowed without a tab to receive it, so the fan-out
+   * would spend a model turn on a delivery that likely never runs. MCP
+   * rows always receive (they read mail at their next prompt). Every skip
+   * is listed by name in `skipped` so the caller can see who was left
+   * out and why. Each recipient gets its own inbox row per part, so the
    * existing wake machinery (grouping, gating, rate cap) treats the
    * broadcast as ordinary per-recipient mail. An oversized body is
    * auto-split (splitChatBody) and every recipient gets every part inside
@@ -871,6 +887,7 @@ export class ChatStore {
   broadcast(
     fromSession: string,
     body: string,
+    openTabs?: ReadonlySet<string>,
   ): { ok: true; recipients: string[]; skipped: string[]; deduped: number; parts: number } | { ok: false; error: string } {
     const trimmed = body.trim();
     if (!trimmed) return { ok: false, error: `Message body cannot be empty (attempted ${body.length} characters).` };
@@ -885,6 +902,9 @@ export class ChatStore {
       };
     }
     const parts = splitChatBody(trimmed);
+    // No provider = no tab signal: every fresh opencode row degrades to
+    // RECENT (honest - an unknown tab state never reads as open).
+    const open = openTabs ?? new Set<string>();
     const recipients: string[] = [];
     const skipped: string[] = [];
     let deduped = 0;
@@ -894,10 +914,12 @@ export class ChatStore {
     this.#db.transaction(() => {
       for (const row of this.list()) {
         if (row.session_id === fromSession) continue;
-        // Staleness means "host process gone" only for opencode rows; an
-        // mcp row between turns reads its mail at the next prompt, so it
+        // Two honest skip classes for opencode rows: STALE (host process
+        // gone - never reads the mail) and RECENT (fresh heartbeat, no
+        // open tab - the wake is not guaranteed to run a turn). An mcp
+        // row between turns reads its mail at the next prompt, so it
         // always receives.
-        if (row.host_kind === "opencode" && isStale(row)) {
+        if (row.host_kind === "opencode" && (isStale(row) || !open.has(row.session_id))) {
           skipped.push(row.name);
           continue;
         }

package/src/commands.ts

@@ -1,6 +1,7 @@
 import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import {
+  REVIEW_SPECIALISTS,
   defragCore,
   extractionCore,
   hygieneCore,
@@ -24,12 +25,17 @@ import {
  *
  * Two command families live here:
  *
- * - Actions (/thatch/defrag, extract, hygiene, reflect): user-invoked
- *   wrappers around a behavior that the nudges otherwise only run on their
- *   own schedule. Each action body is a prompt core from src/prompts.ts, so
- *   nudge and command wording cannot drift.
+ * - Actions (/thatch/defrag, extract, hygiene, peer-review, refine,
+ *   reflect, self-review, whois): user-invoked commands. The nudge-backed
+ *   ones (defrag, extract, hygiene, reflect) render prompt cores from
+ *   src/prompts.ts, so nudge and command wording cannot drift. The rest
+ *   (peer-review, refine, self-review, whois) are self-contained here:
+ *   they have no nudge counterpart. peer-review and self-review couch the
+ *   code review pipeline with a mode overlay: the same machinery, with
+ *   findings weighted for whose work is under review.
  * - Wrap-ups (/thatch/compact, exit): greenlight-token commands that need
- *   the opencode plugin's TUI control routes, so they are opencode-only.
+ *   the opencode plugin's host action routes (the compact trigger and the
+ *   session close-out), so they are opencode-only.
  */
 
 /** Greenlight token ending /thatch/compact's assistant response when compaction is safe. */
@@ -39,11 +45,13 @@ export const COMPACT_READY_TOKEN = "THATCH_COMPACT_READY";
 export const EXIT_READY_TOKEN = "THATCH_EXIT_READY";
 
 /**
- * The plugin triggers compaction by running the TUI's compact action. The
- * execute-command route only accepts legacy alias names, and "session_compact"
- * maps to the same session.compact action the built-in /compact command runs.
- * There is no exit alias, so the exit path publishes the TUI keymap command
- * ("app.exit") directly via /tui/publish.
+ * The greenlight token's host action, per host: v1 drives the TUI
+ * (compaction via the "session_compact" legacy alias through
+ * executeCommand, the exit via the "app.exit" keymap command through
+ * /tui/publish). v2 calls session.compact on the plugin's promise domain
+ * and emits the session-tab bridge's TUI-only exit-tab-closed event; the
+ * runtime records the exiting session's watcher deaths before either host
+ * action runs (src/runtime.ts).
  */
 
 const sharedChecklist = `1. Flush pending persistence. Call thatch_get_extraction_payload; if it returns buffered tool interactions, process them now (write any memories worth keeping), then call thatch_extraction_done to mark them complete. Complete any memory writes you promised earlier but have not made.
@@ -55,10 +63,42 @@ $ARGUMENTS
 
 (That section carries the text typed after the command. When it is empty, treat the user message as n/a - the command was run bare.)`;
 
+/**
+ * How the review-mode commands (peer-review, self-review) run the code
+ * review machinery on the host at hand. opencode has the
+ * thatch-code-review coordinator skill and sub-agent dispatch; Claude Code
+ * and Cursor have neither, so the same procedure runs inline through the
+ * shared specialist skills. The mode overlay that differentiates the two
+ * commands lives in each command's own body and applies in both paths:
+ * sub-agent briefings on opencode, specialist passes inline elsewhere.
+ *
+ * Both couchings below are shared consts interpolated into the two bodies
+ * so the commands' procedure and target resolution cannot drift; each body
+ * keeps only its mode rules. The specialist roster and count come from
+ * REVIEW_SPECIALISTS in src/prompts.ts, the same source as the install
+ * list in src/skills.ts.
+ */
+const reviewPipelineCouching = `If the thatch-code-review skill is available, load it and follow its steps, with one addition: apply the mode rules below throughout - to context gathering, every specialist briefing, and the synthesis.
+
+If that skill is not available on this host, run the same procedure yourself, in order:
+- Resolve the review range. Compute the merge-base against the base branch's remote tracking ref (for example origin/main), not the working branch's own upstream, and cite every file:line against the range's head SHA with git show, never the working tree. A PR or MR number resolves through the host's CLI (gh pr view, glab mr view) plus fetching the head ref (git fetch origin refs/pull/N/head on GitHub, refs/merge-requests/N/head on GitLab, or the source branch). A repository with no remote reviews the working tree's recent commits instead.
+- Build the context brief with the thatch-review-context skill.
+- Partition large diffs into review units.
+- Run the ${REVIEW_SPECIALISTS.length} specialist skills (${REVIEW_SPECIALISTS.join(", ")}) on each unit.
+- Synthesize with thatch-review-synthesizer.
+The mode rules below apply in every specialist pass and in the synthesis, on every host. If the specialist skills are not installed on this host, tell the user to run thatch setup for it.`;
+
+/**
+ * How the review-mode commands resolve what to review. Shared so the two
+ * commands accept the same target syntax and default identically.
+ */
+const reviewTargetCouching = `The user message may name the review target: a branch, a PR or MR number, or a git range. On MCP hosts the Focus: line carries that text instead. If no target is given, review the current branch against its base.`;
+
 /**
  * One on-demand action: the command name (minus the thatch/ prefix), the
  * description shown in the command menu, and the instruction body (a prompt
- * core). opencodeOnly marks actions that need a session identity or other
+ * core for the nudge-backed actions, self-contained text for the rest).
+ * opencodeOnly marks actions that need a session identity or other
  * plugin-only capability; those are excluded from Claude Code command files
  * and MCP prompts.
  */
@@ -71,8 +111,11 @@ export interface ActionDef {
 
 /**
  * The on-demand action set, shared by every host that renders actions. The
- * bodies come from prompt cores so a wording change lands in the nudge and
- * the command at once. `tool` renders tool names in the host's spelling.
+ * nudge-backed bodies (defrag, extract, hygiene, reflect) come from prompt
+ * cores in src/prompts.ts so a wording change lands in the nudge and the
+ * command at once; the rest (peer-review, refine, self-review, whois) are
+ * self-contained here because they have no nudge counterpart. `tool`
+ * renders tool names in the host's spelling.
  */
 export function actionDefs(tool: ToolNamer): ActionDef[] {
   return [
@@ -100,6 +143,25 @@ After dispatching, call thatch_extraction_done to acknowledge.`,
       description: "Tend the memory store: stale entries, orphans, pending dedup pairs",
       body: hygieneCore(),
     },
+    {
+      name: "peer-review",
+      description: "Review another author's change (PR, MR, branch, or git range) through the full review pipeline",
+      // Skill-couching action (refine precedent): no nudge counterpart, so
+      // the body lives here. The memory-walk tool name is spelled through
+      // the namer so MCP renderings carry the mcp__thatch__ form.
+      body: `Review a change authored by someone else: a PR, MR, or branch on origin. The review runs the full thatch review pipeline with findings weighted for org velocity.
+
+${reviewTargetCouching}
+
+${reviewPipelineCouching}
+
+## Peer review mode rules
+
+- Weight for org velocity. Findings that speed up or unblock the whole team outrank findings about individual lines. The highest-value findings: a simpler method that achieves the same outcome; an existing function or helper that already does what this change reimplements; documentation that is accurate and extremely clearly written; unintended consequences for callers, sibling features, or contracts the author could not see.
+- Walk the project's memory. The author does not have this project's persistent memory; you do. During context gathering, call ${tool("memory_recall")} with several phrasings about the touched area: past incidents, design constraints, rejected approaches, known footguns. Check each recalled item against the change and report the ones that apply. Frame these findings as sharing knowledge the author could not have had, not as catching mistakes.
+- Do not re-litigate settled designs. When the context brief or memory shows a design decision was agreed (in a ticket discussion, a prior review acceptance, recorded docs, or a memory of the agreement), treat the decision as settled. Findings may address how the change implements that decision. Findings that argue the decision itself was wrong are out of scope for this review.
+- Never report findings of the form "if someone changes this in the future, it will silently break." This review does not solve for engineers who change code without reading it. It solves for engineers and LLMs who WILL read the code. For them, verify the change leaves a breadcrumb trail to wherever this organization records how a feature works (a context module, a feature doc, a README). Flag a missing trail. Do not flag hypothetical future misuse.`,
+    },
     {
       name: "refine",
       description: "Refine a plan under the project type's requirements (classifies the project first)",
@@ -115,6 +177,26 @@ The user message may name a project type (team-app, personal, shared-lib, spike,
       description: "Persist what this session learned as memories",
       body: reflectCore(tool),
     },
+    {
+      name: "self-review",
+      description: "Review the user's own completed work before submitting it",
+      // Skill-couching action (see peer-review). Names no tools, so the
+      // MCP spelling test exempt list covers it.
+      body: `Review the user's own completed work before submitting it: as a PR or MR on a shared project, or as a direct commit on a personal project. The review runs the full thatch review pipeline with findings weighted to protect the user's reputation as a conscientious developer.
+
+The work under review was authored by the user, or by their agent acting in the user's name. Two goals: the work is sound, and it does not read as sloppy. Reviewers and teammates read the comments, docs, and commit messages as the user's own.
+
+${reviewTargetCouching}
+
+${reviewPipelineCouching}
+
+## Self review mode rules
+
+- The reputation lenses weigh heaviest. NoSlop, Technique, and Breadcrumbs findings outrank same-severity findings from the other lenses. AI-writing tells, vague comments, and a missing narrative are exactly what this review exists to catch before anyone else sees them.
+- Overweight simplicity on shared projects. Prefer findings that make the design easier to understand, easier to test, and more reliable: fewer assumptions, less surface area for bugs and side effects.
+- Technique and highlights findings are decisions, not footnotes. Each one that would produce a simpler, clearer, or more reliable design is surfaced for an adopt-or-dismiss decision before submission. Work through them with the user one at a time; do not leave them as informational asides.
+- Iterate rounds. After each round, work the findings with the user: fix each, or explicitly decline it with a reason. Then run another full round on the updated state. A round is meaningful when it produces a MEDIUM or higher finding, or a technique or slop finding worth adopting. A round producing only LOW mechanical findings gets them fixed but does not trigger another round. Stop at the first round with no meaningful findings, and never run more than three rounds.`,
+    },
     {
       name: "whois",
       description: "Report this session's chat identity (handle, topic, project), or look up another session's",
@@ -154,8 +236,18 @@ ${userMessageSection}
 ${action.body}`;
 }
 
+/** The wrap-up command's menu/palette description. Host-neutral on purpose:
+ *  what actually happens after the greenlight differs per host (v1 exits the
+ *  app, v2 closes the session's tab), and the template text the MODEL reads
+ *  is shared verbatim by both hosts. */
+export function wrapUpCommandDescription(kind: "compact" | "exit"): string {
+  return kind === "compact"
+    ? "Flush thatch persistence, check for loose ends, then compact if clear"
+    : "Flush thatch persistence, check for loose ends, then end the session if clear";
+}
+
 const COMPACT_TEMPLATE = `---
-description: ${yamlQuote("Flush thatch persistence, check for loose ends, then compact if clear")}
+description: ${yamlQuote(wrapUpCommandDescription("compact"))}
 ---
 ${userMessageSection}
 
@@ -172,7 +264,7 @@ ${COMPACT_READY_TOKEN}
 If anything is outstanding, list the items concisely so the user can address them, and do NOT include the token. The session will only be compacted when the token is present.`;
 
 const EXIT_TEMPLATE = `---
-description: ${yamlQuote("Flush thatch persistence, check for loose ends, then exit opencode if clear")}
+description: ${yamlQuote(wrapUpCommandDescription("exit"))}
 ---
 ${userMessageSection}
 
@@ -181,13 +273,12 @@ ${userMessageSection}
 Work through this checklist before responding:
 
 ${sharedChecklist}
-3. Leave the chat directory. Call thatch_chat_unregister for this session - the session is exiting, so other sessions must stop addressing mail to it.
 
 Do not start new work beyond this checklist. If every item is handled and nothing needs the user's attention first, end your final response with exactly this token as the very last line, with no formatting around it:
 
 ${EXIT_READY_TOKEN}
 
-If anything is outstanding, list the items concisely so the user can address them, and do NOT include the token. opencode will only exit when the token is present.`;
+If anything is outstanding, list the items concisely so the user can address them, and do NOT include the token. The session will only close when the token is present.`;
 
 /** One command: the command name (minus the thatch/ prefix) and its full markdown file content. */
 export interface CommandDef {
@@ -221,7 +312,7 @@ export function opencodeCommandDefs(): CommandDef[] {
 /**
  * The Claude Code command set: the actions minus the opencode-only ones.
  * The wrap-up commands are excluded too - their greenlight check needs the
- * plugin's command.execute.before arming and TUI control routes.
+ * plugin's command.execute.before arming and host action routes.
  */
 export function claudeCommandDefs(): CommandDef[] {
   return actionDefs(mcpToolName)