@jeffober/thatch 0.2.4 → 0.2.6

package/README.md

@@ -1,6 +1,13 @@
 # Thatch
 
-[![CI](https://github.com/sysread/thatch/actions/workflows/ci.yml/badge.svg)](https://github.com/sysread/thatch/actions/workflows/ci.yml)
+[![CI](https://github.com/sysread/thatch/actions/workflows/ci.yml/badge.svg)](https://github.com/sysread/thatch/actions/workflows/ci.yml) [![Ask DeepWiki](https://raw.githubusercontent.com/sysread/thatch/main/docs/assets/deepwiki-badge.svg)](https://deepwiki.com/sysread/thatch)
+
+<!-- Experiment (Oct 2026): deepwiki.com/badge.svg 429-challenges non-browser
+     fetchers, so the hotlinked badge rendered broken. The wiki indexed us
+     anyway ("featured in the repository"), so this vendored copy tests
+     whether DeepWiki keeps reindexing without any request to their domain.
+     If freshness holds, the hotlink never mattered; if the wiki goes stale,
+     restore https://deepwiki.com/badge.svg when their challenge lifts. -->
 
 Persistent memory and operational methodology for AI coding agents. Works with
 **OpenCode** (as a plugin), **Claude Code** (as a local MCP server), and
@@ -37,10 +44,11 @@ synchronously (fire-and-forget) instead of asynchronously.
 
 The v2 plugin API is missing a few surfaces the v1 API had. On 2.x:
 
-- **No toasts.** Toasts are dropped on v2 (no publish surface). The
-  model-facing nudges they accompanied - watcher and chat wake nudges -
-  still arrive; the extraction-result and other TUI-only toasts have no
-  replacement.
+- **Toasts ride the session-tab bridge.** Every plugin toast (extraction
+  metrics, alerts, chat registration, blocked wrap-ups) travels the
+  session-tab rpc bridge to the TUI plugin's `ui.toast.show`. A TUI-less
+  environment (headless run, still connecting) shows nothing - toasts are
+  best-effort by design.
 - **Plugin state survives reloads.** Editing the plugin (or `opencode
   plugin update`) reloads it, but extraction buffers, watcher
   registrations, and armed wrap-ups are journaled and restored; a process
@@ -49,14 +57,23 @@ The v2 plugin API is missing a few surfaces the v1 API had. On 2.x:
   such a session re-arms its watches on the first message (expired ones
   are dropped and reported), and a live session in the same project gets a
   one-line notice that a dead session's watch will re-arm if resumed.
-- **Extraction children are visible.** The fact-extractor child sessions are
-  top-level sessions the host cannot delete, so they accumulate in the
-  session picker, and "continue last session" (`-c`) can land in one after
-  any session that triggered extraction.
-- **`/thatch/compact` does not auto-compact.** The checklist and memory
-  flush run, but the compaction itself cannot be triggered from the plugin
-  API - run `/compact` yourself after the wrap-up completes. `/thatch/exit`
-  cannot auto-exit for the same reason.
+- **Extraction children are visible on older 2.x builds.** Upstream exposed
+  `session.remove` on the plugin API (v2.0.22), so the fact-extractor
+  child sessions are deleted when they finish - the session picker stays
+  clean. On an older 2.x build (pre-`session.remove`) the deletion
+  degrades silently: children accumulate in the session picker, and
+  "continue last session" (`-c`) can land in one after any session that
+  triggered extraction.
+- **Wrap-up actions need a new host (compact) or an open tab (exit).** The
+  compaction trigger rides `session.compact` on the plugin API (upstream
+  added it in v2.0.22); on an older 2.x build the checklist and memory
+  flush run but the compaction itself is skipped - run `/compact` yourself
+  there. `/thatch/exit` closes the session's own tab over the session-tab
+  bridge; with no tab open (headless run, tabs off) nothing visible happens,
+  but the session still unregisters from chat and its watches are
+  cancelled - on either host, and reopening or resuming the session does
+  not re-arm them. Re-create watches you still want with
+  `thatch_watch_create`.
 - **No `-c` session listing.** The chat resume listing degrades.
 
 Everything else - tools, memory, nudges, chat, watchers - behaves the
@@ -195,16 +212,24 @@ Thatch gives your agent:
 - **Slash commands** -- `/thatch/defrag` (consolidate duplicate memories),
   `/thatch/extract` (drain the extraction queue now), `/thatch/hygiene`
   (tend stale and orphaned memories), `/thatch/reflect` (persist what
-  the session learned), and `/thatch/refine` (refine a plan under the
-  project type's requirements, classifying the project first) run on
-  demand. The first four mirror the same behaviors the nudges run on
-  their own schedule. Plus the opencode-only wrap-ups: `/thatch/compact` and
+  the session learned), `/thatch/refine` (refine a plan under the
+  project type's requirements, classifying the project first),
+  `/thatch/self-review` (review your own completed work before
+  submitting it, weighted for reputation and simplicity),
+  `/thatch/peer-review` (review another author's change, weighted for
+  org velocity and sharing the project's persistent memory), and
+  `/thatch/whois` (report the session's chat identity) run on demand.
+  The nudge-backed actions (`defrag`, `extract`, `hygiene`, `reflect`)
+  mirror the same behaviors the nudges run on their own schedule; the
+  rest stand alone. Plus the opencode-only wrap-ups: `/thatch/compact` and
   `/thatch/exit` run a pre-flight checklist before a compaction or an exit:
   the agent flushes pending fact extraction, finishes promised memory
   writes, and surfaces todos or follow-ups it never addressed. It ends its
   response with a greenlight token only when the checklist is clean; thatch
-  then triggers the compaction or quits opencode. With items outstanding,
-  the agent lists them and nothing fires -- you decide when to retry.
+  then triggers the compaction or closes the session (its tab on opencode
+  2, the whole app on opencode 1 - either way its watches are cancelled).
+  With items outstanding, the agent lists them and nothing fires -- you
+  decide when to retry.
 - **Notifications + user config** -- the agent can ping you out-of-band when a
   long-running outcome lands: a desktop banner, a spoken voice
   announcement, or both (macOS and Linux). On opencode, thatch also watches
@@ -228,19 +253,24 @@ host.
 
 The memory tools, prediction and behavior engines, conversation search via
 the `thatch session` CLI, cross-session chat (with stop-hook wake), skills,
-and the on-demand actions `/thatch/defrag`, `/thatch/hygiene`, and
-`/thatch/reflect` (synced by `thatch setup --claude`). Not available: the
-wrap-up commands and `/thatch/extract` (they need the opencode plugin's
-session identity and TUI control routes), live recall/prediction nudges
+and the on-demand actions `/thatch/defrag`, `/thatch/hygiene`,
+`/thatch/reflect`, `/thatch/refine`, `/thatch/self-review`, and
+`/thatch/peer-review` (synced by `thatch setup --claude`; the review-mode
+commands run the specialist sequence inline, since the coordinator skill is
+opencode-only). Not available: the
+wrap-up commands (they need the plugin's host action routes),
+`/thatch/extract` and `/thatch/whois` (they need the opencode plugin's
+session identity), live recall/prediction nudges
 beyond the hook-based flow, and toast notifications.
 
 ## What works in Cursor
 
 The same core set as Claude Code (memory, predictions, behaviors, chat with
-stop-hook wake, skills, and the `defrag`/`hygiene`/`reflect` actions). Cursor
+stop-hook wake, skills, and the `defrag`/`hygiene`/`reflect`/`refine`/
+`self-review`/`peer-review` actions). Cursor
 has no file-based slash commands, so the actions surface through MCP prompts
-instead. Not available: the wrap-up commands, `/thatch/extract`, and toast
-notifications.
+instead. Not available: the wrap-up commands, `/thatch/extract`,
+`/thatch/whois`, and toast notifications.
 
 ## Privacy
 

package/artifacts/skills/common.md

@@ -34,6 +34,7 @@ If your briefing includes a project context brief (from the coordinator or from
 - **Deferred work** listed in the brief is intentionally excluded from this PR. Do not flag the absence of deferred pieces as bugs, inconsistencies, or missing functionality.
 - **Dependencies** in the brief tell you whether base-branch behavior is expected to be present or not. Do not assert that base-branch behavior exists without verifying it landed.
 - **Relevant constraints** may explain why code is structured a certain way. Consider them before flagging design choices.
+- **Sibling PR context** in the brief (when related PRs were detected) tells you where the pieces outside this diff live. Before flagging something as "referenced but not implemented anywhere in this change", check the sibling register: a stack member or release-train sibling may deliver it.
 
 ## Workflow context awareness
 If your briefing includes a workflow guide (from the coordinator or from loading thatch-code-archaeology), use it to understand the purpose and evolution of the code you are reviewing:

package/artifacts/skills/thatch-clear-writing.md

@@ -1,6 +1,6 @@
 ---
 name: thatch-clear-writing
-description: Prose rules for every piece of text a human reads that no dedicated skill already covers - PR and ticket comments posted on the user's behalf, documentation, feature plans, reports, write-ups, status updates, and chat replies to the user. Load it before drafting any of those. When a dedicated writing skill is loaded (thatch-pr-description, thatch-ticket-description, thatch-review-response), that skill's rules win.
+description: Prose rules for every piece of text a human reads that no dedicated skill already covers - PR and ticket comments posted on the user's behalf, documentation, feature plans, reports, write-ups, status updates, chat replies, and code and doc comments. Load it before drafting any of those. When a dedicated writing skill is loaded (thatch-pr-description, thatch-ticket-description, thatch-review-response), that skill's rules win.
 ---
 
 # Clear writing
@@ -19,6 +19,7 @@ Every text a human reads:
 
 - **Comments you post for the user** - PR comments, ticket comments (Linear, Jira), replies to reviewers, replies to bot findings.
 - **Written artifacts** - documentation, feature plans, reports, write-ups, design notes, status updates.
+- **Code and doc comments** - comments in source files, doc comments, package READMEs.
 - **Replies to the user in chat** - explanations, summaries, answers.
 
 Same prose rules everywhere. Only the structure differs:
@@ -56,9 +57,12 @@ Hard rules. Not suggestions.
 8. **Show causal links.** If a sentence uses "so", "because", or "prevents", make the middle step visible. Cause and effect that do not obviously touch need the missing step spelled out.
 9. **Clarity wins over compression.** Brevity means fewer claims, not denser claims. Shorten by deleting whole claims. Never rewrite surviving sentences into tighter ones. Keep the connective tissue that makes a sentence parse on first read.
 10. **No invented shorthand.** Do not coin abbreviations, portmanteaus, or labels mid-text. Use the real name, or spell out the behavior. A term the reader cannot find anywhere else is a term they cannot look up.
-11. **No buzzwordy abstractions.** "leverage" -> "use". "utilize" -> "use". If you cannot say what a phrase means in plain English, it does not belong.
-12. **Plain ASCII.** No smart quotes, em dashes, or ellipsis glyphs.
-13. **No process narration.** Never describe the order you assembled things in or narrate your own actions inside the text. State the thing itself.
+11. **No made-up technical phrases.** Do not coin multi-word terms that sound technical but mean nothing: "identity contract", "canonical hash", "semantic alignment layer". Every term must exist somewhere - in the code, the docs, or standard engineering usage. If you cannot point to where it is defined, delete the label and say what the thing does: what runs, what changes, what the reader gets.
+12. **No buzzwordy abstractions.** "leverage" -> "use". "utilize" -> "use". If you cannot say what a phrase means in plain English, it does not belong.
+13. **Plain ASCII.** No smart quotes, em dashes, or ellipsis glyphs.
+14. **No process narration.** Never describe the order you assembled things in or narrate your own actions inside the text. State the thing itself.
+15. **No sycophancy.** Never open by validating the question: phrases like "Great question", "Excellent question", "You're absolutely right", "You're asking the right questions", "I'm excited to help" signal "AI bot managing your emotions" and must never appear. Never hedge a verifiable claim with "I think", "I believe", "In my opinion", "Arguably", or "Just" as a softener. Stating uncertainty on purpose (you are genuinely unsure of a preference or a prediction) is not a hedge. Corrections are not rudeness. They are the point.
+16. **When you don't know, say so.** Say "I don't know" and stop. If you know part of it, state what you know, what you don't, and your confidence. No plausible filler.
 
 ## Length
 
@@ -70,8 +74,102 @@ Match length to complexity: how much new mental model the reader must build.
 
 For chat replies: terse is fine, illegible is not. If a two-line answer only fits by inventing shorthand, spend five lines.
 
+## Session replies
+
+A substantial turn ends with a brief state summary: what was done, what was found, the current state, and what remains. The response comes first; the summary is a short block after it. Keep it to a few lines. Never a large task list the user must scroll past to find the response. When work spans turns, keep pending work visible as a brief outline, not a list that grows until it hides the answer.
+
+A state summary at the end of a turn is not process narration. Rule 14 bans narrating how you assembled the text; this section requires reporting where the work stands.
+
+## Code comments
+
+Comments are human-facing text. The same prose rules apply, plus these. The
+reader is the same future coder from "The reader" above: they know the stack
+and general engineering vocabulary, and they have never touched this area.
+
+- **No metaphor standing in for a mechanism.** If a word labels behavior the
+  comment never states, replace the word with the behavior: "re-enqueued
+  rows get a fresh timestamp so they don't starve the rest", not "a
+  quarantine". A metaphor verb attached to the stated mechanism is fine
+  ("the sweep heals the dropped ids"). A metaphor noun doing the
+  mechanism's job is not.
+- **Euphemisms die; call the thing what it is.** "later UPDATEs of the same
+  row leave it unchanged", not "enqueued_at is not bumped by re-touches"
+  ("bumped by re-touches" is a terrible phrase for "UPDATEs"). A pinned
+  term of art survives.
+- **Full sentences, always.** "A failed cycle waits out the backoff delay,
+  an idle cycle waits the short idle cadence, and a productive cycle waits
+  zero because the queue still has work", not "failures wait out the
+  backoff delay, idle cycles the short idle cadence, productive cycles
+  nothing". The missing causal clause is usually the point.
+- **If/then with the named cause, not a label-colon chain.** "If the
+  recompute returns no row for a claimed id, that id was deleted or
+  soft-deleted after it was enqueued; the worker then deletes any cache row
+  it still has", not "A claimed id with no recompute row was deleted or
+  soft-deleted mid-drain: its cache row is deleted". No passives
+  in the consequence half.
+- **Subject first.** "DrainLoop is a background goroutine that repeatedly
+  claims", not "A background goroutine (DrainLoop) repeatedly claims".
+  Names never hide inside parentheticals.
+- **Behavior before implementation structure.** "takes up to limit rows
+  off the queue, oldest first, and returns them; deleting the row is the
+  claim", not "a CTE selects the stalest ids ... and the outer DELETE
+  removes exactly those rows". State the invariant the design buys ("a
+  trigger enqueue for the same row never waits on this transaction"),
+  not the failure mechanics behind it.
+- **Parentheticals only when they add a distinct fact.** Keep "(or has
+  been killed on)". Cut "(the worker runs when the flag is unset)" after
+  "It defaults to enabled".
+- **Enumerate the parts once, then the collective noun.** "stops the
+  worker" after the drain loop and the sweep are established. Never
+  re-enumerate, and never enumerate what the thing does not control.
+- **State what is impossible, plainly, in first person.** "This should not
+  be possible: the apply statements are a plain INSERT ... SELECT and
+  DELETE whose only inputs are ids that exist in the queue. If we screwed
+  up (a projection drift, a constraint we did not anticipate), the same
+  batch would fail again on retry, so re-enqueueing would only churn. Log
+  it with the ids and drop it; the daily sweep heals the dropped ids."
+  Invariant, failure conditions, decision, recovery. No hedging.
+- **Rescope every label when behavior splits.** If re-enqueue now only
+  happens for lock-blocked batches, "failed batch" is wrong everywhere it
+  appears: comments, log messages, test names.
+- **Doc comments own the mechanism; package READMEs stay high-level
+  guides.** A README is not "the code but in english". Implementation
+  detail belongs to the doc comment next to the code.
+- **Do not document de facto conventions.** If the framework or the
+  migrations make something the default rule, the comment does not say so.
+  Point at the artifact that owns the contract or say nothing.
+- **No ticket refs or plan-doc coordinates in place of behavior.** "the
+  backfill worker", not "the TICKET-123 backfill worker". The reader never
+  opens the ticket tracker to understand the code.
+- **A term of art is defined once; plain behavior everywhere else.** "(the
+  tombstone correction)" in the place it is defined; "a second pass
+  removing cache rows whose source row no longer exists" everywhere else.
+- **Keep load-bearing precision.** Translate jargon ("mid-drain" becomes
+  "after it was enqueued"), but keep the contract when the code depends on
+  it: Postgres error classes 40 and 55, genuine lists, cross-references
+  that carry the why.
+
+The comment shape for a named thing (a metric, a function, a constant):
+
+1. What it does or reports, in behavior terms.
+2. What a reading means: "Sustained growth means the drain loop cannot
+   keep up with (or has been killed on) the enqueue rate".
+3. The operational caveat, when needed: "Sampled by the drain loop, so it
+   freezes while the kill switch is off".
+
+The wart shape, for code that looks wrong but is correct:
+
+1. Name the sensible implementation the reader expects: "Why not
+   min(base * 3^(n-1), max)?"
+2. State the crux: the multiply wraps the int64 before min clamps.
+3. Why, in the fewest words: "30s * 3^19 overflows the Duration, an int64,
+   and min would clamp the overflowed value, not the intended product."
+
+Simple and good beats complex and great. Cut whole claims to shorten;
+never compress the survivors.
+
 ## Clarity pass
 
 Before you post, save, or send: reread the draft as a reader with zero context. Fix what they would stumble on. Do not announce the pass; just return clean prose.
 
-Check: Does every sentence parse on first read? Does every term carry its plain-English meaning before or with the label? Would a reader who has never seen this codebase, ticket, or conversation understand it? If the draft runs long, cut a claim; never tighten the grammar.
+Check: Does every sentence parse on first read? Does every term carry its plain-English meaning before or with the label? Is every technical phrase real - could you find it in the code, the docs, or common usage? If not, say what the thing does instead of naming it. Would a reader who has never seen this codebase, ticket, or conversation understand it? If the draft runs long, cut a claim; never tighten the grammar.

package/artifacts/skills/thatch-code-archaeology.md

@@ -198,6 +198,15 @@ For each feature or workflow you investigated, teach the user what it is and how
 
 Include sub-agent findings as their own per-feature sections, integrated into the same report.
 
+### Cross-PR context (when a sibling register is supplied)
+
+When the review coordinator dispatches you, your input may include the project context brief with a sibling register: related PRs detected as stack members or release-train siblings. Fold the register into the guide where it changes what a reviewer would flag:
+
+- A comment or doc referencing work delivered by a sibling PR is intentional cross-referencing, not a dangling reference. Note it as a design decision, with the sibling PR number.
+- A contract consumed from a sibling (an API, type, schema, or flag) is part of the workflow's data flow. Map it, and note the dependency direction.
+- An ordering assumption across the stack or train (this change assumes a sibling lands first) is a workflow constraint. Note it with the claimed order from the register.
+- Do not investigate a sibling's code beyond what the register and its consistency verdicts already established. The register is context, not a mandate to review the sibling.
+
 ### Recommendations
 Tailor this section to the user's original ask:
 - **Research or investigation**: summarize what you found and what remains unknown

package/artifacts/skills/thatch-code-review.md

@@ -18,11 +18,11 @@ Identify what to review:
 - If a git range was specified (A..B form), use it directly.
 - If no target was specified, review the current branch against its base, resolving the base from `origin/main` (or the appropriate remote tracking ref) after fetching.
 
-Also detect whether the current branch has a **connected PR/MR** even when none was specified — this is what enables follow-up-round detection in Step 2. Inspect `git remote -v` to recognize the VCS host (github.com → GitHub/`gh`; gitlab.* → GitLab/`glab`; bitbucket.org → Bitbucket Cloud; dev.azure.com → Azure DevOps). Then probe for an open PR/MR on the current branch using the matching CLI or REST API:
-- GitHub: `gh pr view --head <branch> --json number,headRefOid,baseRefOid`
+Also detect whether the current branch has a **connected PR/MR** even when none was specified — this is what enables follow-up-round detection and related-PR discovery in Step 2. Inspect `git remote -v` to recognize the VCS host (github.com → GitHub/`gh`; gitlab.* → GitLab/`glab`; bitbucket.org → Bitbucket Cloud; dev.azure.com → Azure DevOps). Then probe for an open PR/MR on the current branch using the matching CLI or REST API:
+- GitHub: `gh pr view <branch> --json number,headRefOid,baseRefOid`
 - GitLab: `glab mr list --source-branch <branch>`
 - Other providers: equivalent detection via their CLI or REST API.
-- If you cannot detect or cannot interact with the VCS (no CLI, no REST access), treat the change as a **local-branch review** and proceed with the existing procedure. A local-branch review is not a defect — it just means there is no prior-comments register to build.
+- If you cannot detect or cannot interact with the VCS (no CLI, no REST access), treat the change as a **local-branch review** and proceed with the existing procedure. A local-branch review is not a defect — it means there is no prior-comments register to build and no connected PR to chain stack discovery from (release trains remain discoverable through tracker relations and linked PRs).
 
 Also fetch any refs not locally reachable so branches and PRs that were never checked out can be reviewed (e.g. `git fetch origin <branch>` for a PR head).
 
@@ -43,8 +43,9 @@ Load the thatch-review-context skill and follow its methodology to build a conte
 - **Links in the change** — docs, designs, tickets, and related PRs linked from the PR description, commit messages, or the changed files themselves; follow them for scope and design context (see source #8 in the review-context skill)
 - **Staleness check** — whether main has moved past the merge-base touching the same paths (see source #3 in the review-context skill); when it has, record the commits in the brief
 - **Prior review comments** — if Step 1 detected a connected PR/MR, fetch ALL prior review comments on it (see source #9 in the review-context skill) and build the prior-comments register with a preliminary addressed-check status per comment. This is what distinguishes a **follow-up round** (register non-empty) from the **first round** (register empty or PR has no prior reviews). If Step 1 found no connected PR/MR, the brief explicitly states `Local-branch review — no prior-comment fetch`.
+- **Related PRs (stacks and release trains)** — discover the coordinated set this change belongs to (see source #11 in the review-context skill): stack members chained through base branches, and release-train siblings ordered by tracker relations or ticket DEPENDENCIES sections (the ticket section that names the change's blocking links). Build the sibling register with targeted consistency verdicts; source #11's early-out governs when to skip (a connected PR/MR is required to chain a stack, but a release train is discoverable from ticket references and linked PRs alone). When reading the siblings' descriptions and targeted diffs would crowd the orchestrator's context (a deep stack or a large train), dispatch one sub-agent instructed to follow source #11's methodology in the review-context skill, then fold its output into the brief.
 
-Produce the context brief in the format the skill prescribes (project context, this change's scope, deferred work, dependencies, relevant constraints, and the prior review comments section when present).
+Produce the context brief in the format the skill prescribes (project context, this change's scope, deferred work, dependencies, relevant constraints, the prior review comments section when present, and the sibling PR context section when related PRs were detected).
 
 If context is sparse (no PR description, no ticket references, no relevant memories), note that the change appears standalone. Even a sparse brief is valuable: it tells specialists you looked and found nothing, so they do not need to repeat the search.
 
@@ -57,7 +58,9 @@ Dispatch a sub-agent using the Task tool to research the code workflows affected
 
 The sub-agent produces a code guide with one section per affected workflow or feature. Wait for it to complete and collect the guide.
 
-This guide gives specialists the code-level context (purpose, data flow, evolutions, constraints) they need to avoid false positives about intentional behavior and long-standing design decisions, and reduces duplicate code-tracing across the eight specialist lenses.
+This guide gives specialists the code-level context (purpose, data flow, evolutions, constraints) they need to avoid false positives about intentional behavior and long-standing design decisions, and reduces duplicate code-tracing across the nine specialist lenses.
+
+If the context brief includes a sibling register (from Step 2's related-PR discovery), fold it into the guide per the `Cross-PR context` section of the thatch-code-archaeology skill — whether you dispatch a sub-agent or do this research inline. The traps the guide exists to catch are comments referencing sibling work, contracts consumed from a sibling, and ordering assumptions across the stack or train.
 
 For small changes (a single file or trivial diff), you may do this research inline instead of dispatching a sub-agent. Use your judgment: if the workflow research would require reading more than 3-4 files, dispatch a sub-agent to preserve your context for orchestration.
 
@@ -129,6 +132,7 @@ Pass the synthesizer:
 - The workflow guide from Step 3.
 - The specialist findings.
 - The prior-comments register when present.
+- The sibling register from Step 2 when present.
 - The staleness signal from the brief (commits on main after the merge-base touching this change's paths), when present.
 
 The final user-facing report MUST begin with a concise explanation of the workflow(s) this PR changes before listing findings. Use one `### Workflow changes` section, with one subheading per affected workflow when there are multiple. Use the before/now walkthrough shape from the thatch-pr-description skill: numbered step = existing behavior; `NOW` sub-bullet = what the PR changes; `N/A` for new stages. This gives the user a map of the change before the findings. Keep it short: 3-6 steps per workflow.
@@ -141,15 +145,18 @@ Technique notes (from the technique specialist) appear in a `### Technique notes
 
 **Follow-up round cross-reference** — if Step 2 built a prior-comments register, the synthesizer must cross-reference every confirmed and rejected finding against it (see the synthesizer skill's "Cross-reference against prior review comments" section). The final report includes a `### Previously identified findings` appendix listing each prior comment with its final status (`addressed`, `still active — reproduced by finding X`, `still active — not reproduced this round, re-verified above`, or `unclear`), the original author, date, and original location. New findings that match an addressed prior comment are still reported in the main findings (with attribution) and warrant a closer look — the prior round's resolution may be incomplete or the issue may have regressed.
 
+**Cross-PR consistency** — if Step 2 built a sibling register, the synthesizer must cross-reference findings against it (see the synthesizer skill's "Cross-reference against the sibling PR register" section). A finding claiming something is missing is rejected or downgraded to a stack note when a sibling delivers it. An inconsistency between this change and a sibling becomes a finding of THIS review only when it affects this change's safety or correctness, or when flagging it now heads off a bug the author will hit in imminent follow-up work in the same project; otherwise it lands in the `### Cross-PR notes` appendix, for the sibling's own review (the synthesizer skill's section carries the rule).
+
 Alternatively, perform the synthesis yourself:
 1. Read each finding's cited location to verify evidence accuracy.
 2. Deduplicate findings flagged by multiple specialists.
 3. Group findings by root cause where multiple findings stem from the same issue.
 4. Classify each as CONFIRMED, REJECTED, or UNVERIFIABLE. For behavioral findings, apply citation verification, reachability, and intent verification. For mechanical findings, verify the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy. For highlights, verify the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence. For technique notes, verify the cited alternative exists at the cited location and achieves the same behavior; if the code as written is actually a defect, hand the finding to the defect track instead. When the brief reports staleness (main moved past the merge-base touching this change's paths), re-verify each behavioral finding against current main first — a finding true only at the merge-base is a rebase note for the author, not a defect in this PR.
 5. Cross-reference against the prior-comments register if one was built in Step 2: tag matching findings `Provenance: previously identified by @author, PR #N, DATE` and produce the `### Previously identified findings` appendix per the synthesizer skill.
-6. Calibrate severity (BLOCKING > HIGH > MEDIUM > LOW) based on your verification.
-7. Produce a final report with a workflow-change preface, highlights (if any), technique notes (if any), findings grouped by severity, coverage gaps, and human-verifiable unknowns noted. Include every confirmed LOW finding.
-8. Apply the synthesizer's "Writing review comments" prose rules to the whole report. Findings are prose, not shorthand: plain English, one idea per sentence, one sentence per hop of any producer chain.
+6. Cross-reference against the sibling register if one was built in Step 2: reject or downgrade to a stack note any finding whose "missing piece" a sibling delivers; confirm findings where this change consumes a contract a sibling does not provide; route sibling-side problems to the Cross-PR notes appendix unless they affect this change's safety or correctness or head off a bug the author will hit in imminent follow-up work in the same project; produce the `### Cross-PR notes` appendix per the synthesizer skill.
+7. Calibrate severity (BLOCKING > HIGH > MEDIUM > LOW) based on your verification.
+8. Produce a final report with a workflow-change preface, highlights (if any), technique notes (if any), findings grouped by severity, coverage gaps, and human-verifiable unknowns noted. Include every confirmed LOW finding.
+9. Apply the synthesizer's "Writing review comments" prose rules to the whole report. Findings are prose, not shorthand: plain English, one idea per sentence, one sentence per hop of any producer chain.
 
 ## Specialist briefing template
 
@@ -162,6 +169,7 @@ When dispatching each sub-agent, include in the prompt:
 - **The project context brief** from Step 2, filtered to what is relevant to this unit's scope. Explicitly list any deferred work that falls within this unit's files, and call out TODO ($ticket) markers the specialists should recognize as intentional.
 - **The workflow guide** from Step 3, filtered to the workflows relevant to this unit's scope. Use it to understand the purpose and evolution of the code before flagging issues. It provides the code-level context (flows, contracts, history, constraints) that prevents false positives about intentional behavior and long-standing design decisions.
 - **The prior review comments register** from Step 2 when present — the list of issues other reviewers already raised, with each comment's current-HEAD location and preliminary status. This is a **hint list, not a finding list**: it saves specialists the work of treating an already-identified issue as newly discovered. Specialists still produce their own findings normally. For any finding that matches a prior comment, set `Provenance` to `previously identified by @author, PR #N, DATE` in addition to the branch-introduced / pre-existing classification — the synthesizer does the final cross-reference and dedup.
+- **The sibling register** from Step 2 when present — the related PRs (stack members and release-train siblings), what each implements, and the targeted consistency verdicts. Before flagging anything as "referenced but missing" or "not implemented anywhere in this change", check the register: a sibling may deliver the missing piece.
 - Any design context or specific concerns
 - Explicit scope boundaries ("your scope is X; do NOT review Y")
 - Instruction to produce markdown findings with: severity, category, file:line, finding, evidence, trigger scenario, reachability, source of truth, producer chain, provenance

package/artifacts/skills/thatch-coordination.md

@@ -0,0 +1,69 @@
+---
+name: thatch-coordination
+description: Coordinate subordinate LLM sessions as a supervisor. Dispatch work with thatch_session_tab (opencode v2 only), track each subordinate in your task list, supervise over cross-session chat, verify before declaring done. Use when orchestrating multi-session work - parallel tasks, delegated implementation, or any flow where you manage work happening in OTHER sessions.
+---
+
+You are the coordinating LLM. Work happens in subordinate sessions you spawn
+and supervise. Your hands are the dispatch tool and the chat; the hands-on
+work belongs to the subordinates.
+
+## Dispatch discipline
+
+One task list entry per subordinate, created BEFORE the dispatch. The entry
+records the top-level task, the subordinate's chat name (from the
+`thatch_session_tab` response), its session id, and its status. Your task
+list is the stateful map of the fleet — if it is not in the list, you are
+not supervising it.
+
+Dispatch with `thatch_session_tab`:
+
+- `title` — short task label (~50 characters).
+- `prompt` — what the subordinate cannot infer: the goal, the relevant paths,
+  the acceptance criteria, and any coordination ground rules. The tool
+  prepends your coordinator identity and authority framing; you supply the
+  substance.
+- `worktree` for work in this repository (the subordinate gets an isolated
+  checkout; its tab opens beside yours), `directory` for anything else.
+- Dispatch one subordinate per independent task. Two tasks that touch the
+  same files are one task, or a sequenced pair — not two tabs.
+
+## Supervision loop
+
+Reconcile your task list against reality every turn:
+
+- `chat_read` drains mail from subordinates; answer questions, send
+  corrections, and record status changes in the task list.
+- A subordinate that goes quiet is not necessarily dead — but the watcher
+  machinery sends death notices when a subordinate's session disappears
+  (`watcherDeathNotice` names the dead session's chat name). On a death
+  notice: mark the task failed, salvage what the subordinate reported, and
+  re-dispatch if the work still matters.
+- Do not block on one subordinate while others run. Answer mail in priority
+  order; keep your own turns short.
+
+## Verification before completion
+
+A subordinate reporting "done" is a claim, not a fact. Before you mark a
+task complete or report to the user:
+
+1. Review the subordinate's actual output — the diff, the test results, the
+   files it claims to have changed.
+2. Re-run the acceptance criteria yourself where cheap (run the tests, read
+   the file).
+3. Only then mark the task done and say so.
+
+## Authority and escalation
+
+The user outranks everything. Your instructions carry accepted priority with
+subordinates, but a direct user instruction to a subordinate supersedes you,
+and a direct user instruction to you supersedes your plan. When a
+subordinate surfaces a conflict, resolve it toward the user's expressed
+wishes and record the decision in the task list.
+
+## Cleanup
+
+A finished subordinate's tab closes with `thatch_session_tab_close` (pass
+the subordinate's chat name) once its work is verified — tab-level only:
+the session survives and the user can reopen it. If a subordinate strands
+an empty or stuck session, tell the user which session id to delete — you
+cannot delete sessions yourself.

package/artifacts/skills/thatch-plan-refinement.md

@@ -1,6 +1,6 @@
 ---
 name: thatch-plan-refinement
-description: Refine a plan for a code change by dispatching a fresh-context reviewer subagent to hunt for gaps, unverified premises, and unexpected side effects, then revising and re-reviewing until consensus. Use when a plan is about to be implemented, when the user asks to refine, stress-test, or double-check a plan, or after a plan revision that incorporated prior findings. This is the generic core loop; when the project type should shape the refinement bar, load thatch-refine instead and it will apply a type delta on top of this loop. Quick mode is one fresh reviewer per round; deep mode adds a specialist lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology).
+description: Refine a plan for a code change by dispatching a fresh-context reviewer subagent to hunt for gaps, unverified premises, and unexpected side effects, then revising and re-reviewing until consensus. Use when a plan is about to be implemented, when the user asks to refine, stress-test, or double-check a plan, or after a plan revision that incorporated prior findings. This is the generic core loop; when the project type should shape the refinement bar, load thatch-refine instead and it will apply a type delta on top of this loop. Quick mode is one fresh reviewer per round; deep mode adds a specialist lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology). Deep-mode triggers are binding; when one is met the fan-out runs, and project-type deltas relax round counts, never mode selection.
 ---
 
 You are refining a plan before code exists. A plan written by the same context that researched the problem inherits that context's blind spots. A reviewer with no stake in the plan and no memory of writing it finds what the author cannot. Refinement is the loop: draft, review, revise, repeat until consensus. Each pass tightens the plan; a round with no findings means the plan is done, not that the loop failed.
@@ -17,6 +17,16 @@ Pick the mode before starting, and say which you picked.
 
 **Deep mode** — adds a one-time specialist lens fan-out (see below) before the consensus rounds. Use when the plan: touches shared or persistent state (database tables, files, config) that other consumers read; spans many files or multiple hosts/processes; introduces a new abstraction, table, or contract; or when the user asks for depth. Deep mode runs the lenses ONCE, in the first round; the remaining rounds are quick-mode consensus on the revised plan.
 
+**These triggers are binding.** If any trigger is met, deep mode's lens fan-out runs for that plan; quick mode is not an option for it. Project-type deltas (`thatch-refine-personal` and its siblings) relax round counts and skip thresholds. They never relax mode selection. The triggers were met verbatim in a 26-round field refinement (October 2026) and quick mode ran anyway, which is why this paragraph is a rule and not advice.
+
+## Plan format requirements
+
+Two plan shapes earn their own plan section. Add them at draft time; retrofitting them mid-loop costs rounds, because every round after the retrofit re-reviews prose the section would have settled.
+
+**State and transition matrix.** Any plan that adds or changes UI or session state (modes, statuses, retention, flags, caches) must carry a state-and-transition matrix as a plan section: every state, every transition between states, and the precedence rule that decides which transition wins when two compete. The first reviewer round verifies every user journey in the plan against the matrix, not against the prose. UX rules written as prose accrete; a matrix makes the unspecified combination impossible to miss. In a 26-round field refinement (October 2026), the state rules of a chat-and-UI plan lived as prose for 16 rounds, and reviewers kept finding combinations no one had written down; a matrix forced at round one would have collapsed most of those findings into the first two rounds.
+
+**Deltas-from-template ledger.** When the plan ports or clones a template or twin feature, it must carry a table of deltas from that template. Each row names one divergence and what the twin actually does at that point, verified against the template's source, not remembered. Reviewers check template-behavior claims against the ledger instead of re-deriving the twin's behavior from scratch. In the same field refinement, a template fact flipped across three rounds because each fresh reviewer re-derived it and got a different answer; the ledger is the fix for that class.
+
 ## The loop
 
 1. **Draft the plan.** Every factual premise carries a `file:line` citation you personally verified. A premise you did not check is a guess wearing a citation; verify it or mark it unverified.
@@ -26,9 +36,26 @@ Pick the mode before starting, and say which you picked.
    - Hunt for gaps by severity (blocker / should-fix / nice-to-have), unexpected side effects, blast radius, and the question "how does this fail in production?" — concurrency, stale state, multi-host interactions, test flakiness, and behavior changes for existing callers.
    - Say explicitly when it cannot verify something, rather than guessing.
 3. **Revise the plan** from the findings. Fix what is wrong, adjust what needs adjusting, and record what you rejected and why.
-4. **Dispatch a NEW reviewer with fresh context** on the revised plan. Never continue the prior reviewer's session, and never tell it what previous reviewers said — prior findings anchor the next reviewer, and it will inherit the earlier reviewer's blind spots instead of finding its own. Present the revised plan as if it were the original.
-5. **Consensus** is a round where the reviewer reports no blockers, no unaddressed should-fixes, and the plan's premises all verify. Two consecutive quiet rounds is strong consensus; one is enough to build.
-6. **Cap at three review rounds.** If the plan has not converged by then, stop looping and put the remaining disagreements in front of the user — continued revision usually means the design problem, not the plan, is unresolved.
+4. **Run the revision self-check.** Before dispatching the next reviewer, re-read the revision diff against the plan it edits, in the same context, and check three things: does the fix contradict anything else in the plan, does it open a new unspecified corner, and is it consistent with findings already folded in. This is a contradiction check on the diff, not a fresh review, and it is cheap because it reuses context you already have. Skipping it hands the next fresh reviewer your own unfinished edges one round late. In the 26-round field refinement cited above, revision churn dominated rounds 8 through 19 because each fix opened corners no one checked until the next round caught them.
+5. **Dispatch a NEW reviewer with fresh context** on the revised plan. Never continue the prior reviewer's session, and never tell it what previous reviewers said — prior findings anchor the next reviewer, and it will inherit the earlier reviewer's blind spots instead of finding its own. Present the revised plan as if it were the original.
+6. **Consensus** is a round where the reviewer reports no blockers, no unaddressed should-fixes, and the plan's premises all verify. Two consecutive quiet rounds is strong consensus; one is enough to build. For a run extended past the cap, the stopping rule changes; see Extended runs below.
+7. **Cap at three review rounds.** If the plan has not converged by then, stop looping and put the remaining disagreements in front of the user — continued revision usually means the design problem, not the plan, is unresolved. If the user explicitly extends the run past the cap, follow Extended runs below instead of stopping.
+
+## Extended runs (past the cap)
+
+The cap is a default, not a law. When the user explicitly extends the run ("keep going while it is useful"), do not stop, and do not repeat the general reviewer prompt either. In the 26-round field refinement cited above, the user overrode the cap, the extended rounds kept earning their keep, and the repeated prompt re-trod ground earlier rounds had already covered. Two mechanics govern the extension.
+
+**Rotate the reviewer lens.** Each extended round's reviewer prompt carries one lens from a fixed schedule, instead of the general prompt:
+
+1. Schema and data model: the tables, columns, constraints, and migrations the plan touches.
+2. Cross-module contracts: the callers, imports, and API surfaces the plan changes.
+3. Lifecycle and edge cases: creation, teardown, concurrency, and failure paths.
+4. Prompt and UI surfaces: user-visible text, states, and flows.
+5. General: the standard reviewer prompt, then restart the schedule.
+
+This rotation applies only past the cap. The standard loop keeps the general prompt for all three of its rounds.
+
+**Stop on a build-clean round.** For an extended run, consensus is a round with no build-changing findings, where build-changing means the finding would change what gets built, not how a sentence reads. Wording and editorial findings batch into one final editorial pass after the last round; they do not start new rounds. The quiet-round definition in the loop stays in force for standard runs.
 
 ## Deep mode: the lenses
 
@@ -68,6 +95,8 @@ Do not argue, and do not silently drop the findings. Reduce the risk of building
 - Demand `file:line` evidence for every claim, and explicit "unverified" where it cannot check.
 - Ask it to state whether the plan's own list of affected surfaces is complete or over-broad. Plan authors over-scope and under-scope in equal measure.
 - Tell it the repo is read-only for this task.
+- If the plan carries a state-and-transition matrix, tell the reviewer to verify each user journey against the matrix. This is the first round's job in particular.
+- If the plan carries a deltas-from-template ledger, tell the reviewer to check template-behavior claims against the ledger and not re-derive the twin's behavior from its source. Each ledger row already records what the twin does, verified; independent re-derivation is how contradictory facts about the template flip-flop across rounds.
 
 ## Cost control