@jeffober/thatch 0.2.5 → 0.2.6

package/README.md

@@ -44,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
@@ -56,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
@@ -202,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
@@ -235,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-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-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
 

package/artifacts/skills/thatch-refine-personal.md

@@ -32,6 +32,11 @@ below; where they disagree, these win.
 - **Degraded review is fine.** If the host cannot dispatch sub-agents, a
   same-context self-review pass is usually enough. Saying so out loud, as
   the core skill requires, is still worthwhile but the stakes are lower.
+- **Round counts drop, not mode selection.** These deltas relax how many
+  rounds a run needs. If a deep-mode trigger in `thatch-plan-refinement`
+  is met (shared persistent state, many files or hosts, a new
+  abstraction, table, or contract, or the user asks for depth), the lens
+  fan-out still runs.
 
 ## Lens weights
 

package/artifacts/skills/thatch-refine.md

@@ -1,6 +1,6 @@
 ---
 name: thatch-refine
-description: Classify the current project (audience, lifecycle, surface) and refine a plan under that type's requirements. Entry point for the thatch-refine-* family. Use when the user asks to refine a plan, runs /thatch/refine, or when a plan is about to be implemented and the project type should shape the refinement bar. For a bare "refine this plan" request, load this skill rather than thatch-plan-refinement directly - the router picks the type and applies its delta on top of the core loop.
+description: Classify the current project (audience, lifecycle, surface) and refine a plan under that type's requirements. Entry point for the thatch-refine-* family. Use when the user asks to refine a plan, runs /thatch/refine, or when a plan is about to be implemented and the project type should shape the refinement bar. For a bare "refine this plan" request, load this skill rather than thatch-plan-refinement directly - the router picks the type and applies its delta on top of the core loop. Deep-mode triggers in the core skill are binding; a type delta relaxes round counts, never mode selection.
 ---
 
 You are the entry point for project-type-aware plan refinement. The core
@@ -68,6 +68,12 @@ pass.
 4. Load `thatch-plan-refinement` (the core loop) and the type's skill.
 5. Run the core loop with the type skill's deltas applied. Where a delta
    and the core skill disagree, the delta wins; that is its whole job.
+   One exception: mode selection. A delta relaxes round counts, skip
+   thresholds, and plan sections. It never turns off deep mode. When a
+   deep-mode trigger in `thatch-plan-refinement` is met (shared
+   persistent state, many files or hosts, a new abstraction, table, or
+   contract, or the user asks for depth), the lens fan-out runs
+   regardless of type.
 
 If no type fits (the repo serves a niche the table misses), run plain
 `thatch-plan-refinement` and say that the requirements are the generic

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

@@ -1,6 +1,6 @@
 ---
 name: thatch-review-context
-description: Gather project and feature context before a code review. Investigates PR descriptions, git history, ticket references, linked docs/tickets, docs, and memory to build a context brief that prevents false positives about intentionally deferred work. Use before dispatching review specialists or running a solo review.
+description: Gather project and feature context before a code review. Investigates PR descriptions, git history, ticket references, linked docs/tickets, docs, memory, and related PRs (stack members, release trains) to build a context brief that prevents false positives about intentionally deferred work and about pieces delivered by sibling PRs. Use before dispatching review specialists or running a solo review.
 ---
 
 You are a review context builder. Your job is to gather project context that gives reviewers the background they need to avoid false positives about intentionally deferred work, incomplete features, and multi-ticket dependencies.
@@ -85,7 +85,7 @@ If the matching CLI tool (`gh`, `glab`, etc.) is not on PATH and you cannot call
 #### Detect the connected PR/MR
 
 Use the current branch name (without remote or merge-base prefix) to look up an open PR/MR:
-- **GitHub**: `gh pr view --head <branch> --json number,title,state,headRefName,baseRefName,headRefOid,baseRefOid`. Fallback: `gh api repos/{owner}/{repo}/pulls --jq ".[] | select(.head.ref==\"<branch>\")"`.
+- **GitHub**: `gh pr view <branch> --json number,title,state,headRefName,baseRefName,headRefOid,baseRefOid`. Fallback: `gh api repos/{owner}/{repo}/pulls --jq ".[] | select(.head.ref==\"<branch>\")"`.
 - **GitLab**: `glab mr list --source-branch <branch>`.
 - **Bitbucket Cloud**: REST `https://api.bitbucket.org/2.0/repositories/<owner>/<slug>/pullrequests?q=source.branch.name="<branch>"` (no widely-adopted CLI; call via available HTTP tool).
 - **Azure DevOps**: `az repos pr list --source-branch <branch> --org <org-url> -r <project>`.
@@ -132,6 +132,46 @@ Directory structure conventions are often undocumented. They live in the repo's
 
 This gives the pedantic specialist the structural context without having to discover the pattern independently.
 
+### 11. Related PRs: stacks and release trains
+
+A change is often one piece of a coordinated set of PRs. The other pieces are outside this diff, so specialists cannot see them. Two false-positive patterns result: a comment references work that a sibling PR delivers, or the change consumes a contract that a sibling PR defines. Discover the set and record what each piece does.
+
+Two shapes to look for:
+- **Stack**: PRs that merge into each other. This PR's base branch is another PR's head branch.
+- **Release train**: PRs that all target the main branch but must merge or deploy in a specific order. The order lives in tracker relations or ticket DEPENDENCIES sections (the ticket section that names the change's blocking links; the links carry the ordering, the bullets carry only the rationale), not in the branch structure.
+
+#### Discovery
+
+- **Stack chaining**: if the connected PR's base branch is not the main branch, another PR probably owns that branch as its head. Find it (`gh pr view <base-branch>` on GitHub, `glab mr list --source-branch <base-branch>` on GitLab), then repeat from that PR until the chain reaches the main branch. Walk at most 5 links in each direction; record deeper stack members as `unexplored` register entries. Also look downward: `gh pr list --base <this-branch>` (GitHub) or `glab mr list --target-branch <this-branch>` (GitLab) finds PRs stacked on top of this one.
+- **Tracker relations**: tickets surfaced by the earlier sources carry blockedBy/blocks relations, parent epics, and DEPENDENCIES sections that name the ordered set. Stack chaining cannot find a release train, because every PR in a train targets main; this route is the primary way trains surface. Map each ticket in the set to its PR/MR (`gh pr list --search "TICKET-ID"` on GitHub, or the tracker's attached-PR link); a ticket with no open PR stays a dependency recorded in the brief's Dependencies section, not a register entry.
+- **Linked PRs** from sources 1 and 8. Deduplicate against the two methods above.
+
+A sibling that already merged to main is also covered by the staleness check (source 3). Record it in the register anyway, for context.
+
+#### Build the sibling register
+
+For each sibling PR/MR:
+- PR/MR number, title, state (open/merged/closed/draft)
+- Its base branch, and for stacks its position in the chain
+- One line: what it implements, from its description and diff stat
+
+This field list is canonical: the brief section below and the synthesizer's Cross-PR notes appendix render the register as built here. An `unexplored` entry (a stack member beyond the walk cap) carries the number, title, state, base branch, and chain position, but no what-it-implements line and no consistency verdicts; the sibling's description and diff were not read.
+
+#### Targeted consistency verification
+
+Read every sibling's description in full. Open a sibling's diff only to verify the specific contracts, symbols, and references this change consumes or mentions. Never run a full second review of a sibling. Checks:
+
+1. **Contract check**: an API, type, schema, config key, or flag this change consumes from a sibling matches the sibling's actual implementation at its head SHA.
+2. **Reference check**: a comment or doc in this change references a thing X. X exists in this change or in a sibling. If neither delivers X, the reference is dangling.
+3. **Ordering check**: the change or its ticket claims a merge or release order for the set. Verify the claim is stated and consistent with the stack chain or the tracker relations.
+4. **Overlap check**: two PRs in the set implement the same thing differently.
+
+Tag each check that applied: `consistent`, `inconsistent` (with the evidence), or `unclear`.
+
+#### Early-out
+
+If the discovery routes above surfaced no related PR/MR and no coordinated ticket set, state `Standalone change — no sibling register` and skip this source. A coordinated ticket set with no open PRs is not standalone: record it under Dependencies. Most personal projects land here; the source costs one look.
+
 ## Context brief format
 
 Produce a structured brief:
@@ -154,6 +194,7 @@ List each deferred piece:
 - What other tickets or PRs this depends on (must merge first)
 - What tickets or PRs depend on this (are blocked by it)
 - Whether base branches have landed (for stacked PRs)
+- **Release order**: when a ticket or the PR description claims a merge or deploy order for a set of changes, record the claimed order and where it is claimed (which ticket's DEPENDENCIES section, which tracker relation, or which PR description)
 - **Staleness**: whether main has moved past the merge-base since the branch point. When the staleness check (source 3) found commits touching this change's paths, list them here — the synthesizer re-verifies behavioral findings against current main before classifying them
 
 ### Relevant constraints
@@ -175,6 +216,18 @@ If context gathering found a connected PR/MR but no prior reviews by other users
 
 If context gathering found no connected PR/MR (local-branch review), state `Local-branch review — no prior-comment fetch`. This is not a gap; the existing review procedure applies.
 
+### Sibling PR context (only when related PRs were detected)
+
+List the sibling register as built above (one entry per sibling):
+- PR/MR number, title, state, base branch, and for stacks the chain position
+- What it implements (one line)
+- Consistency verdicts from the targeted checks (`consistent` / `inconsistent` with evidence / `unclear`), only for the checks that applied
+- An `unexplored` entry renders its fields only; the missing what-it-implements line and verdicts record the walk cap, not a gap
+
+Whether base branches have landed is recorded under Dependencies above, not here.
+
+If discovery found no related PRs and no coordinated ticket set, state `Standalone change — no sibling register`. This is not a gap; the change is not part of a coordinated set. A coordinated ticket set with no open PRs is not standalone: its claimed order is recorded under Dependencies.
+
 ## If context is sparse
 
 Not every PR will have rich context. If you find minimal context:

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

@@ -30,7 +30,7 @@ Run `git fetch origin` (NOT `git pull`). Inspect `git remote -v` to recognize th
 - `dev.azure.com` → Azure DevOps
 
 Probe for an open PR/MR on the current branch:
-- **GitHub**: `gh pr view --head <branch> --json number,title,headRefOid,baseRefOid`
+- **GitHub**: `gh pr view <branch> --json number,title,headRefOid,baseRefOid,baseRefName`
 - **GitLab**: `glab mr list --source-branch <branch>`
 
 If no PR/MR is found or no VCS CLI is available, you cannot re-check. Report this and stop.
@@ -79,7 +79,7 @@ Compare `LAST_ROUND_SHA` to `CURRENT_SHA`:
 
 **Force-push check**: run `git merge-base --is-ancestor <LAST_ROUND_SHA> <CURRENT_SHA>`. If it fails, the author rewrote history (force-pushed). Line numbers may have drifted. You will need to locate each finding's equivalent location in the new HEAD by matching surrounding context, not by line number.
 
-**Merge-from-main check**: if the author merged main into the branch between rounds, plain `git log <LAST_ROUND_SHA>..<CURRENT_SHA>` and `git diff <LAST_ROUND_SHA> <CURRENT_SHA>` both pull in every main commit, burying the author's actual response commits. To see only the author's commits, run `git log <LAST_ROUND_SHA>..<CURRENT_SHA> --not origin/main` after `git fetch origin`. Then read each remaining commit's diff with `git show <sha>`. Do not assume a large diff stat means the author rewrote the PR. Check for a merge commit first.
+**Merge-from-base check**: if the author merged the default branch into the branch between rounds — or, on a stacked PR, merged or rebased onto the PR's base branch — plain `git log <LAST_ROUND_SHA>..<CURRENT_SHA>` and `git diff <LAST_ROUND_SHA> <CURRENT_SHA>` both pull in every base commit, burying the author's actual response commits. To see only the author's commits, run `git log <LAST_ROUND_SHA>..<CURRENT_SHA> --not origin/<default-branch>` after `git fetch origin` (usually main or master). On a stacked PR (Step 1's probe returned a base branch that is not the default branch — `baseRefName` on GitHub, the MR's target branch on GitLab), also fetch the base branch and exclude it too: `git fetch origin <base-branch>`, then `git log <LAST_ROUND_SHA>..<CURRENT_SHA> --not origin/<default-branch> origin/<base-branch>`. Then read each remaining commit's diff with `git show <sha>`. Do not assume a large diff stat means the author rewrote the PR. Check for a merge commit first.
 
 ### Read author responses
 
@@ -152,7 +152,7 @@ Produce a structured report for the user:
 - PR/MR number, title
 - Last-reviewed SHA, current SHA
 - Whether the author pushed changes, responded to comments, or both
-- Force-push or merge-from-main detected (if applicable)
+- Force-push or merge-from-base detected (if applicable)
 
 ### Finding verification
 
@@ -275,7 +275,7 @@ After all findings have been dealt with (adequately addressed and replied to, or
 ### How to offer
 
 Present the offer as a choice:
-1. **Re-run the full structured review**: load `thatch-code-review` on the current HEAD. It will dispatch all eight specialists on the merge-base..HEAD range. The existing follow-up detection will cross-reference your prior comments. On Claude Code or Cursor (no sub-agent support), run each specialist skill in sequence, then run `thatch-review-synthesizer` to aggregate.
+1. **Re-run the full structured review**: load `thatch-code-review` on the current HEAD. It will dispatch all nine specialists on the merge-base..HEAD range. The existing follow-up detection will cross-reference your prior comments. On Claude Code or Cursor (no sub-agent support), run each specialist skill in sequence, then run `thatch-review-synthesizer` to aggregate.
 2. **End the re-review here**: the user confirmed their concerns were addressed (or decided how to handle the unaddressed ones) and does not want another full round.
 
 The offer is just an offer. The user may decline. They may have only wanted to confirm their concerns were addressed.

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

@@ -80,7 +80,7 @@ Identify the PR and VCS host:
   recognize the VCS host: `github.com` -> GitHub (`gh`), `gitlab.*` ->
   GitLab (`glab`), `bitbucket.org` -> Bitbucket Cloud, `dev.azure.com` ->
   Azure DevOps.
-- Probe for an open PR on the current branch: `gh pr view --head <branch>
+- Probe for an open PR on the current branch: `gh pr view <branch>
   --json number,title,headRefOid` (GitHub) or equivalent.
 
 Fetch ALL review comments:

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

@@ -1,6 +1,6 @@
 ---
 name: thatch-review-synthesizer
-description: Verify and synthesize findings from multiple review specialist skills into a single deduplicated, severity-grouped report. Use after running one or more thatch-review-* specialist skills.
+description: Verify and synthesize findings from multiple review specialist skills into a single deduplicated, severity-grouped report. Cross-references prior review comments and sibling PR registers when provided. Use after running one or more thatch-review-* specialist skills.
 ---
 
 You are a review synthesizer. You have received findings from one or more review specialists (pedantic, acceptance, state-flow, economy, no-slop, breadcrumbs, mark-and-sweep, highlights, technique). Your job is to verify their citations against the actual code, deduplicate across specialists, and produce a single, coherent final report.
@@ -95,6 +95,14 @@ New findings that match a prior comment tagged `addressed` (preliminary) are sti
 
 When the VCS resolve flag (GitLab `resolved`, GitHub `isResolved`) disagrees with the code-state verdict (e.g., thread marked resolved in the UI but the bug persists), trust the code state and call out the disagreement in the appendix entry.
 
+## Cross-reference against the sibling PR register
+
+If your input includes a **sibling register** (built via `thatch-review-context` source #11 — related PRs detected as stack members or release-train siblings), apply it during classification, before finalizing any finding whose claim crosses PR boundaries.
+
+- A finding claiming a referenced thing is **missing** ("comments reference X but nothing implements X", "flagged as unused or undefined") is REJECTED — or moved to the Cross-PR notes appendix as a stack note — when the register shows a sibling PR delivers it. Cite the sibling PR and its register entry as the reason.
+- A finding that this change **consumes a contract a sibling does not actually provide** (shape mismatch, renamed symbol, different semantics at the sibling's head) is CONFIRMED, with the `Provenance` field citing the sibling PR.
+- A problem discovered **in the sibling itself** is not a finding of this review by default. Record it in the Cross-PR notes appendix so it can be raised in the sibling's own review. Escalate it to a finding of THIS review only when the inconsistency 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.
+
 ## Severity calibration
 
 Assign final severity based on YOUR verification:
@@ -323,6 +331,18 @@ List every entry from the prior-comments register here. For each entry, produce
 
 If no prior-comments register was provided (local-branch review or first round on the PR/MR), state `None — no prior review comments to cross-reference` and move on.
 
+### Cross-PR notes (appendix — only when a sibling register was provided)
+
+List every sibling in the register here. For each sibling, produce a one-block record:
+1. **PR/MR number, title, state, base branch**, and for stacks its position in the chain
+2. **What it implements** (one line from the register)
+3. **Consistency verdicts**: `consistent` / `inconsistent` (with the evidence) / `unclear`, per targeted check that applied
+4. **Notes for the sibling's own review**: problems discovered in the sibling that belong in its review, not this one
+
+An `unexplored` entry renders item 1's fields and states `unexplored — not read` for items 2 and 3.
+
+Omit this section entirely when no sibling register was provided (standalone change or local-branch review).
+
 ### Coverage gaps
 
 Note which files or areas were NOT covered by any specialist.