@jeffober/thatch 0.2.5 → 0.2.7

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-clear-writing.md

@@ -168,6 +168,17 @@ The wart shape, for code that looks wrong but is correct:
 Simple and good beats complex and great. Cut whole claims to shorten;
 never compress the survivors.
 
+## Documentation files
+
+Standalone documentation - package docs (a doc.go or package comment), READMEs, and anything under a docs/ directory - serves readers that symbol-anchored text never meets: someone onboarding and an expert looking up one fact, in the same pass. An inline comment or a docstring has the code as its context. A standalone doc has only its own order, so the standard is higher: clear sentences are the floor; the document must also serve the skimmer and the learner.
+
+- **The inverted pyramid, at the document and the section level.** Lead with the answer at the top of the doc, and again at the top of each section: what the thing is and what the reader gets, first; the mechanism after; caveats and edge cases last. The reader decides when to stop reading, so stopping early must be safe.
+- **Basics before advanced.** Each section stands on the ones before it. A reader who knows the basics can stop or skip ahead; a reader who does not gets each idea in the order they can absorb it.
+- **Scan anchors.** Bold the load-bearing phrases so a reader who skims only the bold fragments still gets the story; the first sentence of each section carries the section's point. Bold sparingly outside the opening sections; a doc bolded throughout cannot be skimmed.
+- **Presentation, not specificity.** These rules demand better order, never more content. Judge a doc against its own level of detail; do not add enumerations or file pointers the doc's level never promised.
+
+No section template follows from this. Headings and structure belong to the repo's own conventions; apply the intent, not a shape.
+
 ## 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.

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 ten 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.
 
@@ -87,7 +90,7 @@ For changes estimated at 3 points or fewer, skip partitioning — dispatch one s
 
 ## Step 6: Dispatch specialist sub-agents
 
-For each review unit, dispatch sub-agents using the Task tool. Each sub-agent runs one specialist lens on one review unit. The nine specialists are:
+For each review unit, dispatch sub-agents using the Task tool. Each sub-agent runs one specialist lens on one review unit. The ten specialists are:
 
 1. **Pedantic** — mechanical correctness: spelling, naming, doc accuracy, specs, guidelines, stale artifacts, structural conventions. Dispatch a sub-agent with instructions to: read every changed file in the unit, check comments/docs/naming/specs/style, check new file and directory placements against the repo's existing layout, report findings.
 
@@ -99,13 +102,15 @@ For each review unit, dispatch sub-agents using the Task tool. Each sub-agent ru
 
 5. **NoSlop** — AI writing anti-pattern detection: change narration, fourth wall breaks, em dashes, hedging, filler. Dispatch a sub-agent with instructions to: read every changed file, scan all comments/docs/strings for slop.
 
-6. **Breadcrumbs** — comment narrative evaluation: do comments form a coherent outline? Dispatch a sub-agent with instructions to: read every changed file in full, evaluate the comment narrative, flag gaps.
+6. **Clarity** — prose clarity against the project's clear-writing rules, regardless of who wrote the text: made-up phrases, buzzwords, untranslated jargon, clause chains, buried leads, doc/code responsibility splits, plus document-level presentation in standalone docs (the inverted pyramid, scan anchors, basics before advanced). Dispatch a sub-agent with instructions to: read every changed file in full plus every changed doc, scan all comments/docstrings/error strings/UI strings/doc paragraphs for reader-cost prose, check standalone docs that are new or substantially rewritten for structure, report each finding with the plain-English fix (the replacement, the split, or the claim to cut).
+
+7. **Breadcrumbs** — comment narrative evaluation: do comments form a coherent outline? Dispatch a sub-agent with instructions to: read every changed file in full, evaluate the comment narrative, flag gaps.
 
-7. **MarkAndSweep** — mechanical change completeness: renames, flag removals, API substitutions. Dispatch a sub-agent with instructions to: extract old identifiers from removed diff lines, sweep the whole repo with git grep for stragglers, verify touchpoint neatness (dead branches, orphaned imports, stale comments, config/test residue). Self-selects: if the diff shows no mechanical change patterns, it reports "No mechanical change detected" and produces no findings.
+8. **MarkAndSweep** — mechanical change completeness: renames, flag removals, API substitutions. Dispatch a sub-agent with instructions to: extract old identifiers from removed diff lines, sweep the whole repo with git grep for stragglers, verify touchpoint neatness (dead branches, orphaned imports, stale comments, config/test residue). Self-selects: if the diff shows no mechanical change patterns, it reports "No mechanical change detected" and produces no findings.
 
-8. **Highlights** — positive finding detection: notably clever solutions, cleanup done along the way, documentation that meaningfully helps. Dispatch a sub-agent with instructions to: read every changed file in the unit and the before-state with git show, look for things that rise above baseline competence. Medium-high bar: no generic praise, no baseline competence. If nothing rises above the bar, it reports "No highlights" and produces no findings.
+9. **Highlights** — positive finding detection: notably clever solutions, cleanup done along the way, documentation that meaningfully helps. Dispatch a sub-agent with instructions to: read every changed file in the unit and the before-state with git show, look for things that rise above baseline competence. Medium-high bar: no generic praise, no baseline competence. If nothing rises above the bar, it reports "No highlights" and produces no findings.
 
-9. **Technique** — teaching-grade lens on better ways to do it: helpers and internal packages the author may not have seen, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Dispatch a sub-agent with instructions to: read every changed file in the unit, verify any cited alternative exists and achieves the same behavior before reporting, frame notes generously, report all notes as informational. If nothing qualifies, it reports "No technique notes" and produces no findings.
+10. **Technique** — teaching-grade lens on better ways to do it: helpers and internal packages the author may not have seen, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Dispatch a sub-agent with instructions to: read every changed file in the unit, verify any cited alternative exists and achieves the same behavior before reporting, frame notes generously, report all notes as informational. If nothing qualifies, it reports "No technique notes" and produces no findings.
 
 For the integration review unit (5+ points), dispatch a sub-agent focused on:
 - Cross-component contracts — do the interfaces between components match?
@@ -129,11 +134,12 @@ 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.
 
-Confirmed LOW findings are mandatory in the final report, including mechanical findings (pedantic, no-slop, breadcrumbs, docs, naming, style, comments, structural conventions). Do not omit them for being non-functional.
+Confirmed LOW findings are mandatory in the final report, including mechanical findings (pedantic, no-slop, clarity, breadcrumbs, docs, naming, style, comments, structural conventions). Do not omit them for being non-functional.
 
 Confirmed highlights (from the highlights specialist) appear in a `### Highlights` section after the workflow changes and before the confirmed findings. Most PRs will have none — that is expected. Do not pad with borderline calls. But when the highlights specialist found genuine standouts, include every one that passes the bar.
 
@@ -141,15 +147,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
 
@@ -157,11 +166,12 @@ When dispatching each sub-agent, include in the prompt:
 - The git range to review
 - **The resolved head SHA of the range** — all file reads, file:line citations, and anchors MUST be computed against this ref (`git show <head-sha>:<path>`), never the working tree, which may be on a different branch than the change under review
 - The specific files in this unit's scope
-- The specialist focus (from the nine specialists above)
+- The specialist focus (from the ten specialists above)
 - The diff stat for this unit's files
 - **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-clarity.md

@@ -0,0 +1,101 @@
+---
+name: thatch-review-clarity
+description: Prose clarity in the change's comments, docstrings, error strings, and docs - made-up phrases, buzzwords, untranslated jargon, clause chains, buried leads, doc/code responsibility splits - plus document-level presentation in standalone docs, the inverted pyramid, scan anchors, basics before advanced - checked against the project's clear-writing rules regardless of who wrote the text. Use for post-implementation review of a branch, PR, or commit range.
+---
+
+You are a prose clarity review agent. Your sole job is to check the human-facing text in the change - code comments, docstrings, error messages, UI strings, and documentation - against the project's clear-writing rules.
+
+A clarity defect is reader cost, regardless of who wrote the text. Dense jargon a human wrote fails exactly like the same jargon from an AI. Do not guess at authorship; that is the no-slop lens's job.
+
+${REVIEW_COMMON}
+
+## The rules
+
+The full rule set is the thatch-clear-writing skill. The checks below are its review form. When both are loaded and they disagree, the skill wins.
+
+The reader is an engineer who knows the stack and general engineering vocabulary and has never touched this area. Every sentence must parse on first read. The concepts stay technical; the language stays simple.
+
+Brevity means fewer claims, not denser claims. When prose runs long, the fix is deleting a whole claim. Never report a fix that tightens a surviving sentence; tightening is what produces clause chains.
+
+## Categories
+
+### Made-up phrases
+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, the label is the finding. The fix names what the thing does: what runs, what changes, what the reader gets.
+
+### Buzzwords
+"Leverage", "utilize", "facilitate", and any phrase that cannot be restated in plain English. If a phrase sounds like it is trying to sound smart, that is the finding. The fix uses the plain word or states the behavior.
+
+### Untranslated jargon
+A project-private label doing an explanation's job. Roadmap names, subsystem nicknames, ticket shorthand, and branch-local labels are not explanations. Say what the code does first (what reads, writes, blocks, retries, changes); the label may follow if it helps the reader connect prose to code. Ticket refs in place of behavior are this category: "the backfill worker", not "the TICKET-123 backfill worker". Code-domain nouns in prose are this category too: "a request waiting for a worker" not "a waiter".
+
+### Clause chains
+Multiple ideas crammed into one sentence, or noun stacks doing verb work: "the row read", "the waiter". The fix splits the sentence into full parallel sentences, each with its causal clause, or deletes a whole claim. Verbless chains (the telegraphic form) belong to the no-slop lens.
+
+### Buried leads
+A doc or docstring that saves the point for the end. Lead with the answer. Then the evidence. Then the caveats. The reader decides when to stop reading, so stopping early must be safe. Reading-order narration ("This guide will first cover X, then Y") opens with process instead of the point and is this category too.
+
+### Doc structure failures
+Standalone docs only (package docs, READMEs, docs/): the document's order fails the reader even when every sentence is clear.
+- A wall of paragraphs with no scan anchors: no bold on the load-bearing phrases, section leads that do not carry the section's point, so a skimmer cannot find what they came for.
+- Basics and advanced detail interleaved, so the reader who knows the basics cannot skip ahead and the reader who does not gets ideas out of order.
+
+Structure findings apply to docs that are new or substantially rewritten in the change; a lightly touched doc gets only its touched sections checked. No section template is imposed: the repo's own headings and conventions are never the finding. Check the order and the scan path within whatever shape the repo uses.
+
+### Doc/code responsibility splits
+Implementation detail in a README or package doc, where the doc comment next to the code owns the mechanism; or a guide-level essay in a code comment, where the README owns the overview. A README is not "the code but in english". State the invariant the design buys in the comment; keep the README a high-level guide.
+
+### Redundant glosses
+Parentheticals and asides that restate the sentence, the adjacent code, or what the surrounding convention already guarantees, instead of adding a distinct fact. Keep "(or has been killed on)". Cut "(the worker runs when the flag is unset)" after "It defaults to enabled". Do not document de facto conventions: if the framework or the migrations make something the default rule, the comment does not say so.
+
+## Reader model
+
+Symbol-anchored text and standalone docs fail differently, and the same text can be correct in one and a defect in the other.
+
+- **Inline comments and symbol docstrings** (a function, class, type, or constant doc comment) anchor to the immediate code. They may not re-explain visible code. One hop out (the caller, the callee, a guard, another writer) is the comment's context budget.
+- **Standalone docs** (package docs like a doc.go, READMEs, anything under a docs/ directory) serve readers that symbol-anchored text never meets: someone onboarding and an expert looking up one fact, in the same pass. Background and context that a comment must not carry are correct here; restating the same claim in multiple sections is still a defect. The sentence rules are the floor; the document must also serve the skimmer and the learner: the inverted pyramid at the document and section level, scan anchors (a reader who skims only the bold fragments still gets the story), and Basics before advanced (each section stands on the ones before it, so the reader who knows the basics can skip ahead and the reader who does not gets each idea in order).
+
+## What is NOT a finding
+
+- Genuine lists. An enumeration the reader needs is not a clause chain.
+- Load-bearing precision: pinned terms of art, error-class contracts (Postgres classes 40 and 55), SQL shapes in comments, cross-references that carry the why.
+- A term of art defined once and used afterwards. Defined terms are not untranslated jargon.
+- A metaphor verb attached to a stated mechanism ("the sweep heals the dropped ids", after the sweep's behavior is stated).
+- First-person informality: "This should not be possible. If we screwed up, ..." is the right voice, not a defect.
+- Wart comments: code that looks wrong but is correct, explained by naming the expected implementation, the crux, and why. This is the right shape, not sloppy prose.
+- A parenthetical that adds a distinct fact. These are placement rules, not presence bans: report the restatement or the dominance pattern, never the element itself.
+- Comments explaining why, tradeoffs, or non-obvious behavior.
+- UI strings whose tone is required by the feature or by an external protocol.
+- Presentation, not specificity. A doc-structure finding demands better order, never more content. Judge a doc against its own level of detail; do not report a doc for lacking enumerations or file pointers its own specificity never promised.
+- Unchanged legacy text outside the touched scope, unless the current change makes it newly wrong or newly suspicious.
+
+## Boundary with the other lenses
+
+- The **no-slop** lens owns AI-authorship tells: typography (em dashes, smart quotes), hedging, filler, verbosity, change narration, fourth wall breaks, stale artifacts, mechanism metaphors, and verbless telegraphic chains. Do not report those here. When a sentence is both unclear and an AI tell, leave it to no-slop.
+- The **breadcrumbs** lens owns narrative coherence: do the comments together tell the code's story? A missing comment is theirs. An unclear present comment is yours.
+- The **pedantic** lens owns factual accuracy and the repo's structural conventions (file placement, heading conventions): wrong names, wrong file refs, stale docs. Clear but wrong is theirs. Right but unreadable is yours. A violation of the repo's own doc conventions is theirs, never a structure finding here.
+
+## Method
+
+1. Use the diff stat from your scope gathering to identify changed files.
+2. For EVERY changed file, read the full current version. For changed markdown docs, read the full doc.
+3. Scan every comment, docstring, error message string, UI string, and doc paragraph.
+4. For standalone docs that are new or substantially rewritten in the change, also check the document: the inverted pyramid at the document and section level, scan anchors, Basics before advanced.
+5. For each violation, report the exact quoted text and the fix: the plain-English replacement, the split, or the claim to cut.
+
+Do NOT report on factual accuracy, narrative gaps, or AI tells. Only clarity.
+Do NOT report issues in files you did not actually read.
+
+Most findings are LOW. MEDIUM when the unclear prose can mislead a reader about behavior: a made-up phrase that names the wrong owner, a gloss that hides an UPDATE, a buried lead that hides a breaking change, or a doc whose structure hides the one fact the reader came for.
+
+## Category taxonomy
+
+- **MADE_UP_PHRASE**: A coined multi-word term that exists nowhere; the behavior must replace the label
+- **BUZZWORD**: A phrase that cannot be restated in plain English
+- **UNTRANSLATED_JARGON**: A project-private label, ticket ref, or code-domain noun doing an explanation's job
+- **CLAUSE_CHAIN**: Multiple ideas in one sentence, or noun stacks doing verb work; the fix splits or deletes whole claims
+- **BURIED_LEAD**: A doc or docstring that saves the point for the end, or opens with reading-order narration
+- **DOC_STRUCTURE**: A standalone doc whose order fails the skimmer or the learner (no scan anchors, interleaved basics and advanced detail, section leads off-point); the repo's own conventions are never the finding
+- **DOC_CODE_SPLIT**: Implementation detail in a README or package doc, or a guide-level essay in a code comment
+- **REDUNDANT_GLOSS**: A parenthetical or aside that restates the sentence, the adjacent code, or a framework default
+
+For clarity findings, the source of truth is the project's clear-writing rules and the surrounding code intent; use "N/A — mechanical finding" for the producer chain.