@jeffober/thatch 0.2.4 → 0.2.6

package/docs/plans/prediction-consolidation.md

@@ -1,11 +1,18 @@
-# Prediction Consolidation and Compound Predictions
+# Fire Tracking and Compound Predictions
 
 ## Synopsis
 
-Post-processing layers for the prediction engine: fire tracking, co-fire-based
-consolidation (dedup), and compound (tier-2) predictions minted from
-co-firing constellations of existing predictions. Uses nudge-driven detection
-and the existing edge model for fire behavior. No cron, no separate backend.
+Post-processing layers for the prediction engine: fire tracking and compound
+(tier-2) predictions minted from co-firing constellations of existing
+predictions. Uses nudge-driven detection and the existing edge model for fire
+behavior. No cron, no separate backend.
+
+The consolidation (dedup) half was implemented separately and has graduated —
+the shipped design is documented in
+[../dev/features/prediction-engine.md](../dev/features/prediction-engine.md)
+("Dedup pass"). What remains here is the fire-tracking prerequisite
+and the co-fire refinements (behavioral dedup, compound detection) that
+consume the accumulated data.
 
 ## Background
 
@@ -14,10 +21,10 @@ auto-fires at chat.message and updates via agent tool calls. What it lacks
 relative to nak's samskara system:
 
 - **Fire tracking** -- no record of which predictions fire together on the same
-  turn. This is the prerequisite for both co-fire dedup and compound detection.
-- **Consolidation** -- no corpus-level dedup pass. Write-time dedup
-  (findNearestPrediction at 0.85) catches near-identical statements at creation,
-  but behavioral duplicates (same preference, different wording) accumulate.
+  turn. This is the prerequisite for co-fire dedup and compound detection.
+- **Consolidation** -- implemented and graduated: a cosine-only dedup pass
+  over the prediction corpus, no prerequisites
+  ([../dev/features/prediction-engine.md](../dev/features/prediction-engine.md)).
 - **Compound predictions** -- no mechanism to mint a higher-order prediction
   from a constellation of predictions that reliably co-fire. Nak's tier-2
   samskaras fire at 77% genuine-engagement vs tier-1's 21% because compound
@@ -43,10 +50,13 @@ existing edge model.
 The co-fire data is for *deciding what to compound*, not for *making the
 compound fire*. This means:
 
-1. A compound needs no tier column, no special scoring path, no fire-path
-   changes. It is a prediction with multiple matcher edges.
-2. The existing `scorePredictions` already follows all edges and deduplicates by
-   prediction_id. A compound scores through its children's edges.
+1. A compound needs no tier column and no fire-path changes. It is a
+   prediction with multiple matcher edges. The scoring path does get one
+   addition: dynamic child suppression (see the compound-domination risk).
+2. The existing `scoreNudge`/`scoreItems` already follow all edges and
+   deduplicate by prediction_id. A compound scores through its children's
+   edges. Minting records the compound-to-children relation (Phase 4) so
+   suppression can tell parent from child.
 3. The existing `prediction_update` tool already finds existing matchers by
    cosine (0.85 threshold) and creates edges. Calling it multiple times with
    different matcher texts but the same prediction statement creates a
@@ -111,14 +121,18 @@ pass null or derive from the socket connection.
 tables. Same conventions (uuid PK, store column, idempotent CREATE TABLE IF
 NOT EXISTS).
 
-### Phase 2: Consolidation (Co-fire Dedup)
-
-**New DB method: `findPredictionDuplicates(store, threshold)`**
+### Phase 2: Co-fire refinement of dedup
 
-Two-pass, mirroring nak's `samskara_collapse_by_cofiring`:
+The cosine-only dedup pass (`findPredictionDuplicates`, the
+`prediction_dedup_pairs` table, the hygiene line, the merge flow) is
+IMPLEMENTED and graduated — documented in
+[../dev/features/prediction-engine.md](../dev/features/prediction-engine.md)
+("Dedup pass"). Once
+fire data accumulates, this plan upgrades that same method with behavioral
+evidence, mirroring nak's `samskara_collapse_by_cofiring`:
 
-**Primary pass (behavioral):** For each pair of predictions (A, B) in the store
-where both have fire_count > 0:
+**Behavioral pass (added to `findPredictionDuplicates`):** For each pair of
+predictions (A, B) in the store where both have fire_count > 0:
 
 ```
 cofires(A, B) >= 3
@@ -131,26 +145,11 @@ when either fires are duplicates. Two that co-fire but also fire independently
 are adjacent-but-distinct. Cosine is a sanity floor against spurious co-fires.
 
 **Safety cap (cosine-only):** If the prediction count exceeds a target (e.g.,
-100), fall through to pure embedding-cosine greedy merge (cosine >= 0.60)
-regardless of co-fire data. This catches accumulation when the behavioral pass
-finds nothing but the pool is still growing.
-
-**Output:** A list of candidate merge pairs with {predictionA, predictionB,
-cofires, ratio, cosine, firesA, firesB}. Surfaced via the hygiene nudge, not
-auto-merged. The agent reviews and merges via prediction_delete + (optionally)
-prediction_update to fold the loser's matchers into the winner.
-
-The merge itself is agent-driven: the agent sees the candidate pair, reads both
-predictions, deletes the weaker one (or uses a future `prediction_merge` tool
-if one is added). This matches the memory dedup pattern
-(`find_duplicates` + `dedup_mark_checked`).
-
-**Integration point:** `hygiene.ts` -- add a line to `hygieneReport`:
-`N prediction duplicate pairs pending review` when candidates exist.
+100), the implemented pure cosine pass already covers the pool;
+no behavioral evidence is required to keep dedup moving.
 
-**Nudge throttling:** Runs at session start only, same as the existing hygiene
-report. The analysis is O(n^2) over the predictions table but n is small
-(tens, not hundreds) so the cost is negligible.
+**Output:** the dedup plan's candidate shape extended with {cofires, ratio,
+firesA, firesB} per pair.
 
 ### Phase 3: Compound Prediction Detection
 
@@ -216,7 +215,14 @@ first child's matcher. Subsequent calls find the existing compound by
 `findNearestPrediction` (0.85 store-wide dedup) and add edges from the other
 children's matchers.
 
-This works with the existing tool surface. No new tools needed for minting.
+This works with the existing tool surface. One addition: minting must also
+record WHICH predictions the compound supersedes, because child suppression
+(see the compound-domination risk) needs the parent-to-children relation at
+scoring time -- shared matcher edges are implicit and cannot distinguish a
+compound from a busy multi-matcher prediction. `prediction_update` gains an
+optional `supersedes` arg (array of prediction ids), carried on the first
+mint call, writing one `prediction_compounds(compound_id, child_id)` row per
+child. No tier column; the compound is still an ordinary prediction.
 
 **Prompt instructions addition** (in prompts.ts, all three host variants):
 
@@ -225,8 +231,9 @@ After the existing prediction instructions, add guidance for compounds:
 - When the hygiene nudge reports co-fire constellations, consider whether the
   members share a generalizable behavior.
 - If so, synthesize a compound statement and call `prediction_update` once per
-  child matcher with the compound statement. The tool handles matcher dedup and
-  edge creation.
+  child matcher with the compound statement, passing the child prediction ids
+  as `supersedes` on the first call. The tool handles matcher dedup and edge
+  creation.
 - A compound should be strictly more general than any single child. If you
   cannot generalize, do not compound.
 - The compound inherits the fire coverage of its children's matchers. It will
@@ -258,7 +265,7 @@ chat.message (user text)
 session.created (top-level)
   → hygieneReport
     → findDuplicates (memories, existing)
-    → findPredictionDuplicates (NEW: co-fire dedup candidates)
+    → findPredictionDuplicates (implemented; co-fire-refined here)
     → findCoFireConstellations (NEW: compound candidates)
     → inject hygiene nudge with all signals
 
@@ -276,44 +283,48 @@ computation, same as existing prediction methods.
 db.ts.
 
 **Code changes by file:**
-- `src/db.ts` -- new table, 4-5 new methods (recordFires, fireCount,
-  cofireCount, totalCohorts, findPredictionDuplicates, findCoFireConstellations)
+- `src/db.ts` -- one new table (`prediction_fires`) + 4 new methods
+  (recordFires, fireCount, cofireCount, totalCohorts, findCoFireConstellations);
+  the co-fire refinement extends the implemented `findPredictionDuplicates`
+  method
 - `src/runtime.ts` -- generate cohort_id, pass to recordFires in auto-fire path
 - `src/sideband.ts` -- same for MCP path
-- `src/hygiene.ts` -- add prediction dedup + constellation counts to report
+- `src/hygiene.ts` -- add constellation count to report (the dedup count is
+  already implemented there)
 - `src/prompts.ts` -- compound minting guidance in all three prompt variants
 - `tests/prediction.test.ts` -- tests for new DB methods
 - `tests/plugin.test.ts` -- test that fire tracking records cohorts
 
 ## Implementation Order
 
+0. **Cosine dedup** -- IMPLEMENTED and graduated (Oct 2026):
+   `findPredictionDuplicates` + `prediction_mark_checked`; nothing left to do.
 1. **Fire tracking** (table + recordFires + caller wiring). Foundation for
-   everything else. Ship and let fire data accumulate.
-2. **Cosine dedup** (findPredictionDuplicates + hygiene integration). Does not
-   need fire tracking. Can ship in parallel with phase 1. Immediate value:
-   catches behavioral duplicates the write-time 0.85 dedup misses.
-3. **Co-fire dedup** (add co-fire ratio + cosine filter to
-  findPredictionDuplicates). Needs fire data to accumulate first. Wait a few
-   weeks after phase 1 ships.
-4. **Compound detection** (findCoFireConstellations + hygiene integration).
+   everything else here. Ship and let fire data accumulate.
+2. **Co-fire dedup** (add the behavioral pass to findPredictionDuplicates).
+   Needs fire data only -- the method and pair table already exist. Wait a
+   few weeks after fire tracking ships.
+3. **Compound detection** (findCoFireConstellations + hygiene integration).
    Needs more fire data than dedup (p_min_cofires = 10). Wait longer.
-5. **Compound minting** (prompt instructions + agent-driven via existing
-  tools). Ships with phase 4 -- the nudge surfaces candidates, the agent
-   compounds.
+4. **Compound minting** (prompt instructions + agent-driven via existing
+  tools). Ships with compound detection -- the nudge surfaces candidates,
+   the agent compounds.
 
-Phases 1-2 can ship together. Phases 3-5 follow once fire data accumulates.
+Fire tracking ships immediately; the rest follow once fire data accumulates.
 
 ## Test Plan
 
 - `prediction.test.ts`: test recordFires, fireCount, cofireCount,
-  totalCohorts with synthetic cohorts. Test findPredictionDuplicates with
-  known co-firing pairs. Test findCoFireConstellations with lift thresholds.
+  totalCohorts with synthetic cohorts, the co-fire refinement of
+  findPredictionDuplicates with known co-firing pairs, and
+  findCoFireConstellations with lift thresholds.
   Use the existing `makeEmbed(seed, dim=384)` helper.
 - `plugin.test.ts`: test that chat.message auto-fire records a cohort.
   Follow the recall-nudge test pattern (mock.module transformers + server
   hooks).
 - `hygiene.test.ts` (if exists) or `plugin.test.ts`: test that hygiene report
-  includes prediction dedup/constellation counts when candidates exist.
+  includes the constellation count when candidates exist (the dedup count
+  tests are implemented, riding UC-113).
 
 ## Risks and Mitigations
 
@@ -324,11 +335,18 @@ precondition gate (minimum prediction count, minimum fire count) before running
 the analysis.
 
 **Risk: Compound predictions fire too much, dominating the nudge.**
-Mitigation: The existing `scorePredictionNudge` deduplicates by prediction_id
-and slices to limit=5. A compound competes on equal footing with its children.
-If a compound and a child both fire, the higher-scoring one wins the slot. The
-compound's score is `cosine(matcher) * edge.weight * confidence` -- same
-formula. No special treatment.
+Mitigation (nak-proven): dynamic child suppression, not equal-footing
+competition. When a compound and its child both score in the same round and
+the compound's score is higher, the child is skipped. The rule resolves
+during the scoring pass, per query -- not as a stored flag -- so the
+surviving set adjusts as it searches and freed slots refill from the
+remaining scored list. If the child outscores the compound (it matched a
+matcher the compound did not inherit), both surface. Implementation: the
+per-round dedup filter in `scoreItems` (src/scoring-engine.ts:153-178)
+gains the suppression check, using the compound-to-children relation
+recorded at mint time. Plain prediction_id dedup and the limit=5 slice are
+unchanged. Fire rows record post-suppression survivors only, so co-fire
+data means co-surfaced.
 
 **Risk: Agent creates poor compounds (too generic, not useful).**
 Mitigation: The prompt instructions include the "strictly more general" guard
@@ -351,9 +369,11 @@ this becomes a concern. Low priority.
   a separate improvement, not part of this plan, but worth doing alongside
   phase 1.
 - The existing write-time dedup (`findNearestPrediction` at 0.85) catches
-  near-identical statements at creation. The co-fire dedup in phase 3 catches
-  behavioral duplicates that differ in wording. The two are complementary:
-  write-time catches semantic twins, co-fire catches behavioral twins.
+  near-identical statements at creation. The implemented dedup pass
+  (cosine, with its co-fire refinement here) catches
+  behavioral duplicates that differ in wording. The layers are
+  complementary: write-time catches semantic twins, the dedup passes catch
+  behavioral twins.
 - Nak's tier-2 decline ledger (`samskara_tier2_declines`, TTL'd 7 days) prevents
   re-offering a declined constellation every sweep. Thatch's equivalent: a
   `prediction_constellation_declines` table or a `dedup_pairs`-style

package/docs/user/README.md

@@ -138,6 +138,7 @@ Stores are created automatically. No setup required.
 | `thatch_prediction_update` | Create, reinforce, or weaken a prediction. Takes a matcher (context description), a prediction (preference statement), and a signal (confirm/disconfirm/soft/create). |
 | `thatch_prediction_list` | List all predictions in a store with matchers, confidence, and provenance. |
 | `thatch_prediction_delete` | Delete a prediction by semantic match. Edges and provenance are cascade-deleted. |
+| `thatch_prediction_mark_checked` | Record a verdict (duplicate/distinct) on a pair the hygiene nudge flagged, so it stops resurfacing. |
 
 ### Behavior tools
 
@@ -183,12 +184,19 @@ search` - JSONL output designed for piping to `jq` or `grep`.
 | `thatch_watch_create` | Watch a GitHub PR for events (comments, review comments and replies, thread resolutions, commits, status changes, description edits, CI completions). The plugin polls in the background and prompts the session when a watched event happens. |
 | `thatch_watch_branch_create` | Watch a GitHub branch (typically main) for commit landings, CI check-run completions, and workflow runs, with an optional workflow-name filter. |
 | `thatch_watch_command_create` | Wait on any local condition via a shell command that exits 0 when the wait is over. One-shot: one notification on the first exit 0, then it cancels itself. Accepts a `cd` path to run somewhere other than the project directory. |
-| `thatch_watch_list` | List this session's active watchers. |
+| `thatch_watch_list` | List this session's active watchers, plus events waiting for idle delivery. |
 | `thatch_watch_cancel` | Cancel one of this session's watchers by id. |
 
 See [watchers.md](watchers.md) for the full behavior, lifetime, and
 requirements.
 
+### Session tab tools (opencode v2 only)
+
+| Tool | What it does |
+|------|-------------|
+| `thatch_session_tab` | Spawn a detached subordinate LLM session in a new TUI tab: creates the session, pre-assigns its chat name, delivers your task prompt with your coordinator-identity framing, and opens its tab beside yours (unfocused). Takes `prompt` and `title` (required) plus exactly one of `worktree` (a git worktree of the current repository) or `directory` (any existing directory). Requires opencode v2 and the `thatch-coordination` skill describes the supervisor workflow. |
+| `thatch_session_tab_close` | Close a dispatched subordinate's TUI tab when its task is verified and done. Tab-level only: the session survives and the user can reopen the tab; nothing is deleted. Target: the subordinate's chat name or session id. opencode v2 only. |
+
 ### Chat tools
 
 | Tool | What it does |
@@ -198,7 +206,7 @@ requirements.
 | `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.
@@ -240,15 +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`) 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;
@@ -320,17 +336,17 @@ response, walkthrough, and workflow skills that support the review pipeline:
 | `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. |
@@ -343,13 +359,13 @@ response, walkthrough, and workflow skills that support the review pipeline:
 | `thatch-pr-description` | Drafts PR descriptions with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, project-context research, clarity checks, and bold/italic emphasis for scanning. |
 | `thatch-ticket-description` | Drafts ticket or issue descriptions (Linear or Jira) with clear sections, project-context research, clarity checks, and bold/italic emphasis for scanning. |
 | `thatch-split-overlarge-pr` | Splits already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main. |
-| `thatch-clear-writing` | Prose rules for every human-facing text the dedicated writing skills do not cover: PR and ticket comments, documentation, plans, reports, and chat replies. Clarity over compression. |
+| `thatch-clear-writing` | Prose rules for every human-facing text the dedicated writing skills do not cover: PR and ticket comments, documentation, plans, reports, chat replies, and code comments. Clarity over compression. |
 
 ### opencode-only skills
 
 | 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
 

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

@@ -57,7 +57,8 @@ 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;
+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?"
@@ -163,6 +164,9 @@ thatch setup --claude --skills-only             # refresh just the skill files
 | `THATCH_BEHAVIOR_THRESHOLD` | `0.60` | Cosine threshold for behavior auto-fire |
 | `CLAUDE_PROJECT_DIR` | `process.cwd()` | Claude Code project directory |
 | `CURSOR_PROJECT_DIR` | (falls through) | Cursor project directory |
+| `THATCH_PROJECT_DIR` | (falls through) | Project dir pinned by project-local MCP configs - first in the server's resolution chain |
+| `THATCH_WATCH_DEATH_MINUTES` | `120` | Pending-age threshold before a dead session's watchers are cancelled and announced |
+| `THATCH_PROJECT_DIR` | (falls through) | Project dir pinned by project-local MCP configs - first in the server's resolution chain |
 | `CLAUDE_CONFIG_DIR` | `~/.claude` | Claude Code config directory |
 | `CURSOR_CONFIG_DIR` | `~/.cursor` | Cursor config directory |
 

package/docs/user/code-review.md

@@ -16,7 +16,10 @@ 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`,
@@ -30,6 +33,10 @@ 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
 
@@ -48,6 +55,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, 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 +90,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 +106,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
 
@@ -17,13 +19,33 @@ or you invoke it.
   The agent asks before forgetting anything that may still matter.
 - `/thatch/reflect` — run the session-reflection skill to persist what the
   current session learned.
+- `/thatch/whois` — report the current session's chat identity: its handle,
+  topic, project, and whether it runs in the project root or a worktree.
+  Text after the command looks up another session instead (by handle or
+  session id) — this is how you map a handle from the roster to the tab you
+  see: the topic is the session's live title. opencode only.
 - `/thatch/refine` — refine a plan for a code change under the current
   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
@@ -38,13 +60,18 @@ or you invoke it.
 | `/thatch/extract` | yes | no | no |
 | `/thatch/hygiene` | yes | yes | yes (as an MCP prompt) |
 | `/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` needs 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; its prompts come from
-the MCP server (`prompts/list` and `prompts/get`).
+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 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`).
 
 ## Installation