@jeffober/thatch 0.1.33 → 0.1.35

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

@@ -26,6 +26,8 @@ Also detect whether the current branch has a **connected PR/MR** even when none
 
 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).
 
+**Anchor discipline**: the working tree may be checked out on any branch — main, another feature, a detached HEAD — and is not guaranteed to match the change under review. Resolve the head SHA of the review range (`git rev-parse <head-ref>`), and compute every file:line citation and review-comment anchor against that ref with `git show <head-sha>:<path>` — never from the working tree, and never from the base. When the working tree happens to be the PR branch this is equivalent, so apply the rule unconditionally rather than branching on it. Pass the head SHA to sub-agents (see the briefing template).
+
 Run git diff --stat on the resolved range and git log --oneline to understand the change.
 
 ## Step 2: Gather project context
@@ -38,7 +40,9 @@ Load the thatch-review-context skill and follow its methodology to build a conte
 - thatch_memory_recall for feature/project status, design decisions, ticket dependencies
 - Project docs, READMEs, design docs
 - Issue tracker (gh issue/view) if ticket IDs are found
-- **Prior review comments** — if Step 1 detected a connected PR/MR, fetch ALL prior review comments on it (see source #8 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`.
+- **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`.
 
 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).
 
@@ -123,6 +127,7 @@ Pass the synthesizer:
 - The workflow guide from Step 3.
 - The specialist findings.
 - The prior-comments register 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.
 
@@ -136,7 +141,7 @@ 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.
+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. 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), findings grouped by severity, coverage gaps, and human-verifiable unknowns noted. Include every confirmed LOW finding.
@@ -145,6 +150,7 @@ Alternatively, perform the synthesis yourself:
 
 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 eight specialists above)
 - The diff stat for this unit's files

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, 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, 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.
 ---
 
 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.
@@ -28,6 +28,7 @@ Branch names often contain ticket identifiers. Look for patterns:
 - `git log --all --oneline --grep="TICKET-ID"` — find related commits on other branches
 - `git log -S "TODO (TICKET"` — find TODO markers that reference this or related tickets
 - `git branch -a` — other branches may show planned or in-progress related work
+- **Staleness check**: `git log --oneline <merge-base>..origin/main -- <changed paths>` — commits that landed on main AFTER this branch's merge-base, touching the same files. If any exist, the branch is stale relative to main and findings true at the merge-base may already be moot. List these commits in the brief under Dependencies so the synthesizer re-verifies findings against current main.
 
 ### 4. TODO ($ticket) markers in the diff
 Scan the diff for TODO markers that reference ticket identifiers:
@@ -56,7 +57,17 @@ If ticket IDs were found:
 - Look for milestone assignments, dependencies, and blocking relationships
 - Check for epic or parent issues that describe the overall feature
 
-### 8. Prior review comments (follow-up round detection)
+### 8. Links in the change (follow the references)
+
+Collect links to material outside the diff that a reviewer would need for context, then follow them:
+- PR description links: docs, design docs, RFCs, tickets, related PRs
+- Commit message links and ticket references
+- Links inside the changed files themselves: READMEs, doc comments, config comments referencing designs or runbooks
+- Ticket bodies from source 7, which often link parent epics, blocking issues, or design docs
+
+Follow each link one hop and read it for review-relevant context: scope, design decisions, constraints, deferred work, sibling changes. If a linked document references another artifact that is directly about this change (a parent epic, a design doc for the same feature), follow that too. Stop at depth 2, and stop following a path once the linked material stops changing what a reviewer would flag. Record anything that changes review context in the brief. A link that 404s or requires access you do not have is not a finding — note it as `link unreachable` and move on.
+
+### 9. Prior review comments (follow-up round detection)
 
 If the change under review has a connected PR/MR on the upstream remote, fetch all prior review comments so this review does not duplicate already-identified issues. Any prior review activity on the PR/MR means **this is a follow-up round**, not the first review. If no PR/MR is connected, this is a **local-branch review** — skip this source entirely; the existing review procedure applies.
 
@@ -113,7 +124,7 @@ For each comment, attempt to determine whether it has been addressed in the **cu
 
 The register produced here is a **preliminary** classification. The synthesizer produces the final cross-reference, including any prelim-status overrides when new findings from the specialist round reproduce or refute a prior comment.
 
-### 9. Repo structure conventions (implicit)
+### 10. Repo structure conventions (implicit)
 Directory structure conventions are often undocumented. They live in the repo's layout itself, not in a CONTRIBUTING.md. Look at the directory tree to identify how the repo organizes code:
 - `git ls-files | head -50` or `ls` at the top level to see the organizational pattern
 - For multi-app repos, identify whether shared packages live inside app directories or at the repo root
@@ -143,6 +154,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)
+- **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
 - Design decisions or architectural constraints from memories or docs

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

@@ -31,11 +31,9 @@ For each finding from the specialists:
 
 5a. **Verify governing constraints for data-shape findings.** For findings claiming a field can be NULL/missing/orphaned/malformed, locate and read the field's definition (schema migration, model, type declaration). If a NOT NULL, FK, enum, or type constraint forecloses the claimed state, REJECT and cite the constraint. Do not classify such a finding CONFIRMED without having read the governing definition.
 
+5b. **Re-verify against post-branch-point main (behavioral findings, only when the context brief flags staleness).** If the brief reports commits on main after this branch's merge-base touching this change's paths, the branch may be stale and a finding can be true at the merge-base but already moot on main. For each behavioral finding, read the equivalent code on current main (`git show origin/main:<path>`). A finding that main has already fixed or mooted is a **rebase note**, not a defect in this PR: keep it out of the confirmed findings and list it in the report's rebase-notes appendix instead.
+
 6. **Verify intent (behavioral findings only).** If the specialist flagged behavior as a bug but the code appears to work as designed, check whether the behavior is intentional:
-   - Read the callers of the cited code to see if the pattern makes sense in context.
-   - Check git log or git blame on the cited file for commit messages explaining the decision.
-   - Use thatch_memory_recall to search for documented rationale.
-   If the behavior is intentional or an accepted limitation, reject the finding.
 
 4m. **Mechanical verification (pedantic, no-slop, breadcrumbs, docs, naming, style, comments, structural conventions).** For mechanical findings, verification means:
     - The cited text exists at the cited location (already confirmed in step 2). For PLACEMENT findings, the cited evidence is the file path and the existing directory structure, not quoted code. Verify the file exists at the claimed path and that the existing structure shows the convention the specialist cited.
@@ -71,7 +69,7 @@ Multiple findings may stem from the same underlying issue (e.g., a contract mism
 
 ## Cross-reference against prior review comments
 
-If your input includes a **prior-comments register** (built by the coordinator via `thatch-review-context` source #8 — prior review comments retrieved from the PR/MR's review history), cross-reference every confirmed and rejected finding against it so the final report does not present already-identified issues as fresh discoveries.
+If your input includes a **prior-comments register** (built by the coordinator via `thatch-review-context` source #9 — prior review comments retrieved from the PR/MR's review history), cross-reference every confirmed and rejected finding against it so the final report does not present already-identified issues as fresh discoveries.
 
 For each new finding:
 1. **Search for a matching prior comment** by location and semantic claim. Match if both hold:
@@ -255,6 +253,10 @@ Findings you rejected and a one-line reason why. Include the specialist and loca
 
 Findings you verified as real but pre-existing, with a one-line note on the issue and its potential impact.
 
+### Rebase notes (appendix, brief — only when the context brief flags staleness)
+
+Findings that were true at the merge-base but are already fixed or mooted by later commits on main. One line each: the finding, and the main commit that moots it. Omit this section entirely when the brief reports no staleness.
+
 ### Previously identified findings (appendix — only when a prior-comments register was provided)
 
 List every entry from the prior-comments register here. For each entry, produce a one-block record:

package/docs/dev/skills.md

@@ -47,7 +47,7 @@ description: Extract durable project facts ... Use when ...
 | `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
 | `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar against generic praise. |
 | `thatch-review-synthesizer` | Verify specialist findings against code, dedupe, classify, calibrate severity. Starts the final report with a workflow-change preface, then cross-references findings against prior review comments when a follow-up round register is provided. |
-| `thatch-review-context` | Gather project/feature context (PR descriptions, git archaeology, ticket references, memory) before fan-out. Prevents false positives about intentionally deferred work. Also fetches prior review comments on a connected PR/MR for follow-up-round detection and builds a register with preliminary addressed-check status per comment. |
+| `thatch-review-context` | Gather project/feature context (PR descriptions, git archaeology, ticket references, linked docs/tickets followed from the change, memory) before fan-out. Prevents false positives about intentionally deferred work, and checks whether main moved past the merge-base touching the same paths (staleness signal for the synthesizer). Also fetches prior review comments on a connected PR/MR for follow-up-round detection and builds a register with preliminary addressed-check status per comment. |
 | `thatch-code-archaeology` | Investigate an existing feature, debug an unfamiliar area, or begin a new ticket. Explores the code base from multiple angles (data model, state flow, git history, sibling features, skeletons) before proposing changes. The research skill; pair with `thatch-coding-workflow`. |
 | `thatch-review-followup` | Alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review round adequately addressed your prior findings, offers to reply on resolved items, then optionally re-runs the full structured review. |
 | `thatch-change-walkthrough` | Explain a change to the user as a teaching walkthrough: resolve the delta, research each affected workflow at the merge-base, teach current behavior, then overlay the modifications with file:line citations and analogies. |

package/docs/user/README.md

@@ -237,7 +237,7 @@ response, walkthrough, and workflow skills that support the review pipeline:
 | `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
 | `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar against generic praise. |
 | `thatch-review-synthesizer` | Verifies and synthesizes findings from multiple specialists into a report that starts with workflow changes, then highlights, then deduplicated severity-grouped findings. |
-| `thatch-review-context` | Gathers project context (PR descriptions, git archaeology, ticket references, memory) before a review. Prevents false positives about intentionally deferred work. |
+| `thatch-review-context` | Gathers project context (PR descriptions, git archaeology, ticket references, linked docs/tickets, memory) before a review. Prevents false positives about intentionally deferred work. |
 | `thatch-code-archaeology` | Investigates an existing feature, debugs an unfamiliar area, or begins a new ticket. Explores the code base from multiple angles (data model, state flow, git history, sibling features, skeletons) before proposing changes. Pairs with `thatch-coding-workflow`. |
 | `thatch-review-followup` | Alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review adequately addressed your prior findings, offers to reply on resolved items, then optionally re-runs the full structured review. |
 | `thatch-review-response` | Author-side review response: triage findings on your own PR, fix bugs one by one, reply on each thread, post a top-level summary comment. |

package/docs/user/code-review.md

@@ -10,9 +10,15 @@ The coordinator skill (`thatch-code-review`, opencode-only) orchestrates
 the review:
 
 1. **Resolve the target**: fetch origin, compute merge-base against
-   `origin/main`, support branch/PR/explicit range.
+   `origin/main`, support branch/PR/explicit range. All file reads and
+   comment anchors are computed against the PR head ref, not the
+   working tree, which may be checked out on a different branch.
 2. **Gather project context**: PR descriptions, git archaeology,
-   ticket references, TODO markers, prior reviews, project memory.
+   ticket references, links to docs/designs/tickets found in the
+   change (followed one hop for scope and design context), TODO
+   markers, prior reviews, project memory. Also checks whether main
+   has moved past the merge-base touching the same paths — a stale
+   branch can make findings true only at the merge-base.
 3. **Research affected workflows**: load `thatch-code-archaeology`,
    trace the code paths the change touches.
 4. **Estimate complexity**: partition the diff into review units.
@@ -21,7 +27,9 @@ the review:
 6. **Synthesize**: the synthesizer reads all specialist output,
    verifies each finding (cited text exists, claim is accurate,
    severity is justified), deduplicates by root cause, and produces
-   the final report.
+   the final report. When the branch is stale relative to main, it
+   re-verifies behavioral findings against current main and reports
+   merge-base-only findings as rebase notes rather than defects.
 
 ## The eight specialists
 

package/docs/user/skills.md

@@ -46,7 +46,7 @@ becomes part of the agent's context.
 | `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
 | `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar. |
 | `thatch-review-synthesizer` | Verifies and synthesizes findings from multiple specialists into a deduplicated, severity-grouped report. |
-| `thatch-review-context` | Gathers project context (PRs, tickets, TODOs, deferred work) before a review. Prevents false positives about intentionally deferred work. |
+| `thatch-review-context` | Gathers project context (PRs, tickets, linked docs/designs followed from the change, TODOs, deferred work) before a review. Prevents false positives about intentionally deferred work. |
 | `thatch-code-archaeology` | Investigates an existing feature, debugs an unfamiliar area, or begins a new ticket. The research skill; pair with `thatch-coding-workflow`. |
 | `thatch-review-followup` | Verifies whether the author's responses and code changes since your last review adequately addressed your prior findings. |
 | `thatch-review-response` | Author-side review response: triage findings on your own PR, fix bugs one by one, reply on each thread, post a top-level summary comment. |

package/package.json

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

package/src/prompts.ts

@@ -523,7 +523,7 @@ function extractionNudgeOpencode(
   sessionID: string,
 ): string {
   const plural = count === 1 ? "" : "s";
-  const dispatch = "Dispatch a task with background: true";
+  const dispatch = 'Dispatch a task with background: true and subagent_type: "general" (required for thatch tool access)';
   const drainTool = "thatch_extraction_done";
   const fetchTool = "thatch_get_extraction_payload";
   return buildExtractionNudge(count, missedCount, plural, dispatch, drainTool, fetchTool, sessionID);