@jeffober/thatch 0.1.6 → 0.1.9

package/bin/release

@@ -22,9 +22,30 @@ echo "  bump:    $v"
 echo "  next:    $next"
 echo
 
-echo "▸ running tests..."
-bun test
-echo "  ✓ tests passed"
+# Pre-flight: verify the current version is published on npm before allowing a
+# new release. A tagged-but-unpublished version means the prior publish failed;
+# stacking another release on top hides the gap and complicates recovery.
+if git rev-parse -q --verify "refs/tags/v$curr" >/dev/null 2>&1; then
+  pub_status=$(npm view "@jeffober/thatch@$curr" version 2>&1 || true)
+  if ! echo "$pub_status" | grep -q "^$curr$"; then
+    if echo "$pub_status" | grep -q "E404"; then
+      echo "ERROR: v$curr is tagged but not published to npm."
+      echo "  The previous release failed. Check: gh run view --workflow=publish.yml"
+      echo "  Fix the workflow, delete and re-tag v$curr, push, then re-run this release."
+      echo "  To re-tag: git tag -d v$curr && git tag v$curr <commit> && git push origin :refs/tags/v$curr && git push origin v$curr"
+      exit 1
+    else
+      echo "WARN: npm registry check failed (not a 404 — may be a network issue or npm outage):"
+      echo "  $pub_status"
+      echo "  Proceeding anyway. Verify v$curr is published before relying on this."
+      echo
+    fi
+  fi
+fi
+
+echo "▸ running checks (typecheck + tests + markdown lint)..."
+mise run check
+echo "  ✓ checks passed"
 echo
 
 echo "▸ bumping version..."

package/docs/dev/README.md

@@ -70,9 +70,10 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | Hook | What it does |
 |------|-------------|
 | `experimental.chat.system.transform` | Appends the thatch system prompt (store names, usage rules). |
-| `experimental.session.compacting` | Appends re-familiarization context so a compacted session still knows thatch exists. |
+| `experimental.session.compacting` | Marks the session as compacting and appends re-familiarization context so a compacted session still knows thatch exists. |
+| `experimental.compaction.autocontinue` | Clears the compacting flag so `chat.message` nudges resume. Without this, nudges that instruct tool calls would fire during summary generation where tools are blocked. |
 | `tool.execute.after` | Buffers every non-`thatch_*` tool call into the session's extraction buffer. This is a plugin hook, NOT a bus event — do not move it into the `event` handler; the event bus has no such event and it will silently never fire. |
-| `chat.message` | Two priority tiers: (a) if extraction buffer has interactions, flushes them as a synthetic text part carrying the extraction nudge + JSON payload; (b) otherwise, embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). |
+| `chat.message` | Two priority tiers: (a) if extraction buffer has interactions, flushes them as a synthetic text part carrying the extraction nudge + JSON payload; (b) otherwise, embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). Skipped entirely while the session is compacting (tool calls are blocked during summary generation). |
 | `event` (`session.created`) | Sends the session-start reminder via `client.session.prompt`, carrying the hygiene heartbeat (pending dedup pairs, stale count, orphaned branch memories) when any signal is non-zero. The session id is at `event.properties.info.id`. |
 | `dispose` | Closes the DB. |
 

package/docs/dev/setup-and-hooks.md

@@ -17,9 +17,10 @@ The plugin entry (`src/index.ts`) registers these hooks in code:
 | Hook | Input | Output | Behavior |
 |------|-------|--------|----------|
 | `experimental.chat.system.transform` | `{}` | `{ system: string[] }` | Pushes the system prompt (store names, usage rules). |
-| `experimental.session.compacting` | `{}` | `{ context: string[] }` | Pushes re-familiarization context. |
+| `experimental.session.compacting` | `{ sessionID }` | `{ context: string[] }` | Marks the session as compacting, pushes re-familiarization context. |
+| `experimental.compaction.autocontinue` | `{ sessionID }` | `{ enabled: boolean }` | Clears the compacting flag so `chat.message` nudges resume post-compaction. |
 | `tool.execute.after` | `{ tool, sessionID, callID, args }` | `{ title, output, metadata }` | Buffers non-`thatch_` tool calls into the in-memory extraction ring buffer (max 20). |
-| `chat.message` | `{ sessionID, messageID }` | `{ message, parts }` | Two tiers: extraction nudge if pending, else prompt-aware recall nudge. |
+| `chat.message` | `{ sessionID, messageID }` | `{ message, parts }` | Two tiers: extraction nudge if pending, else prompt-aware recall nudge. Skipped while the session is compacting. |
 | `event` (`session.created`) | `{ event: { type, properties: { info: { id } } } }` | — | Calls `client.session.prompt` with the reminder + hygiene heartbeat. |
 | `dispose` | — | — | Closes the DB. |
 

package/docs/dev/skills.md

@@ -21,9 +21,9 @@ description: Extract durable project facts ... Use when ...
 - `description` drives when the agent loads the skill (both opencode and
   Cursor auto-discover skills and use the description for relevance).
 
-## The 11 skills
+## The 12 skills
 
-**Shared (10)** — installed everywhere; no sub-agents required:
+**Shared (11)** — installed everywhere; no sub-agents required:
 
 | Skill | Role |
 |-------|------|
@@ -36,13 +36,14 @@ description: Extract durable project facts ... Use when ...
 | `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth-wall breaks, em dashes, filler. |
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of behavior? |
 | `thatch-review-synthesizer` | Verify specialist findings against code, dedupe, classify, calibrate severity. |
+| `thatch-review-context` | Gather project/feature context (PR descriptions, git archaeology, ticket references, memory) before fan-out. Prevents false positives about intentionally deferred work. |
 | `thatch-session-reflection` | End-of-session memory recording (project, user, tools, self). |
 
 **opencode-only (1)** — the coordinator needs sub-agent support:
 
 | Skill | Role |
 |-------|------|
-| `thatch-code-review` | Resolve review target, estimate complexity, partition, dispatch the 5 specialists in parallel, synthesize. |
+| `thatch-code-review` | Resolve review target, gather context, estimate complexity, partition, dispatch the 5 specialists in parallel, synthesize. |
 
 ## REVIEW_COMMON
 
@@ -57,6 +58,12 @@ The five review specialists share a framework interpolated via `${REVIEW_COMMON}
   trigger; "the code allows this" is not enough.
 - **Intent verification** — trace callers, check git history, and `thatch_memory_recall`
   for design rationale before flagging a behavior as a bug.
+- **Project context awareness** — if a context brief is provided (from the
+  coordinator or from loading `thatch-review-context`), use it to avoid false
+  positives about intentionally deferred work.
+- **TODO ($ticket) markers** — recognize `TODO ($TICKET-ID): ...` as legitimate
+  breadcrumbs for deferred work, not stale artifacts. Flag only if the referenced
+  ticket is closed or merged.
 - **Output format** — `[SEVERITY] [CATEGORY] file:line` with finding, evidence
   (quoted), trigger, reachability, source of truth, producer chain, provenance.
 
@@ -66,7 +73,7 @@ The synthesizer reuses the same verification rigor but has its own structure
 ## The two arrays
 
 ```ts
-const SHARED_SKILLS: SkillDef[] = [ /* 10 skills above */ ];
+const SHARED_SKILLS: SkillDef[] = [ /* 11 skills above */ ];
 const OPENCODE_ONLY_SKILLS: SkillDef[] = [ /* code-review coordinator */ ];
 ```
 
@@ -100,8 +107,8 @@ and `--cursor` pass only the shared set.
 ## Memory review skills in practice
 
 - **Quick single lens**: load any specialist directly and point it at a branch.
-- **Full review on opencode**: load `thatch-code-review` — it dispatches all 5
-  specialists in parallel, then synthesizes.
+- **Full review on opencode**: load `thatch-code-review` — it gathers project context, dispatches all 5
+  specialists in parallel (with context injected into each briefing), then synthesizes.
 - **Full review on Claude Code/Cursor**: run each specialist in sequence, then
   run `thatch-review-synthesizer` to verify and aggregate.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.6",
+  "version": "0.1.9",
   "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/index.ts

@@ -41,6 +41,14 @@ export const server: Plugin = async ({ client, worktree }) => {
   const model = new BgeEmbeddingModel(modelName);
   const extraction = new ExtractionPipeline();
 
+  // Sessions currently being compacted. chat.message nudges are skipped while
+  // a session is in this set — the agent can't call tools during summary
+  // generation, so a recall or extraction nudge would cause a blocked-tool
+  // error. Cleared by experimental.compaction.autocontinue. If compaction
+  // fails, the entry leaks (graceful degradation: nudges stay off for that
+  // session, but no crash).
+  const compacting = new Set<string>();
+
   // Skills always install to the global opencode config — installing into the
   // worktree would mutate the user's repo (untracked files in git status).
   // A failed install degrades the nudge workflow but must not kill the plugin.
@@ -64,11 +72,20 @@ export const server: Plugin = async ({ client, worktree }) => {
       output.system.push(sys);
     },
 
-    // 2. Compaction context — re-familiarizes after compaction.
-    "experimental.session.compacting": async (_input, output) => {
+    // 2. Compaction context — re-familiarizes after compaction. The flag
+    //    suppresses chat.message nudges during summary generation (tool
+    //    calls are blocked there).
+    "experimental.session.compacting": async (input, output) => {
+      compacting.add(input.sessionID);
       output.context.push(compact);
     },
 
+    // 2b. Clear the compacting flag after compaction succeeds so chat.message
+    //     nudges resume for the synthetic auto-continue turn and beyond.
+    "experimental.compaction.autocontinue": async (input) => {
+      compacting.delete(input.sessionID);
+    },
+
     // 3. Tool buffering — feeds the extraction nudge. Thatch's own tools are
     // excluded: extracting facts from memory operations would just echo the
     // store back into itself.
@@ -89,7 +106,12 @@ export const server: Plugin = async ({ client, worktree }) => {
     //   b. Recall nudge: the user's prompt semantically matches existing
     //      memories — surface that prior knowledge exists before the agent
     //      responds. Uses the in-process warm model (no sideband needed).
+    //
+    // Skipped during compaction: the agent can't call tools while generating
+    // a summary, so a nudge that says "use thatch_memory_recall" triggers a
+    // blocked-tool error.
     "chat.message": async (input, output) => {
+      if (compacting.has(input.sessionID)) return;
       if (extraction.pending(input.sessionID)) {
         const batch = extraction.flush(input.sessionID);
         const payload = extraction.buildPayload(batch, repo);

package/src/prompts.ts

@@ -64,9 +64,9 @@ CLAUDE.md or OPENCODE.md, speculative conclusions.
 
 export function compactionContext(repo: string): string {
   return `Thatch persistent memory is active with stores "${repo}" and "global".
-Use thatch_memory_recall to retrieve prior knowledge, thatch_memory_remember
-to persist important decisions, patterns, and conventions encountered so far.
-Include context about what's been learned and decided when summarizing.`;
+When summarizing, preserve context about what's been learned and decided
+this session — conventions, architectural decisions, and prior knowledge
+retrieved from memory. This ensures continuity after compaction.`;
 }
 
 export function sessionStartReminder(repo: string, hygiene?: string | null): string {

package/src/skills.ts

@@ -72,6 +72,8 @@ Identify the application's runtime model early: Is it a CLI tool (process exits
 ## Reachability gate
 For every potential finding, you MUST describe a concrete scenario where a real user triggers the problem through normal usage. "The code allows this" is not sufficient — show how a user actually encounters it given the application's runtime model. If the only trigger requires conditions that cannot occur in actual usage, it is not a finding.
 
+Before claiming a value can hold a problematic state (NULL, orphaned, out-of-range, wrong-type), read the artifact that governs that state: the column definition, type declaration, FK/NOT NULL constraint, validation, or guard. Quote it in your finding. If a schema constraint, type, or guard makes the state unreachable, it is not a finding. "The join could drop rows" requires proving a droppable row can exist — cite the constraint that permits it.
+
 ## Intent verification
 Before flagging behavior as a bug, verify intent:
 1. **Trace callers.** Read every caller of the cited code. The behavior may be intentional given how the feature is actually used.
@@ -80,6 +82,18 @@ Before flagging behavior as a bug, verify intent:
 
 If any of these reveals the behavior is intentional, it is not a finding. If you cannot determine intent after all three steps, you may report it — but note that you could not confirm whether the behavior is intentional.
 
+## Project context awareness
+If your briefing includes a project context brief (from the coordinator or from loading thatch-review-context), use it to calibrate your findings:
+- **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.
+
+## TODO ($ticket) markers
+Code may contain \`TODO ($TICKET-ID): description\` comments that mark intentionally deferred work: temporary code, placeholders for future tickets, or planned cleanups. These are legitimate breadcrumbs, not stale artifacts.
+- Do NOT flag a TODO ($ticket) marker as a stale artifact if the ticket it references is still open or future work.
+- DO flag it if you can verify the referenced ticket is closed or merged (the TODO is now stale).
+- If your briefing includes a context brief that lists the deferred work, use it to determine whether the ticket is still pending.
+
 ## Output format
 Produce findings as markdown. For each finding:
 
@@ -453,11 +467,13 @@ For each, walk through actual function calls, tracking data shape at each step.
 
 ### 4. Prove the producer chain
 For every finding about invalid state, missing data, shape mismatches, or cross-module behavior, trace the full causal chain:
-- Who produces the state or value?
+- Who produces the state or value? Cite the file:line that writes the problematic value.
 - Which functions transform it?
 - Which consumer or branch fails?
 - Which real entrypoint/workflow exercises that chain?
 
+The producer must be a specific file:line in current code that writes the problematic value. "Source deletion could orphan this" is not a producer; the file:line where a row is written with a dangling reference is. If no such write site exists in the codebase, the state is unreachable — do not report it.
+
 If you cannot identify a real producer in current code, or the only way to trigger the issue is by manually fabricating invalid state/data, do not report it as a real finding.
 
 ### 5. Identify the implicit FSM
@@ -490,6 +506,10 @@ For each new module or significant change:
 - **DEAD_PATH**: Code path exists but cannot be reached given current callers/preconditions
 
 For each finding, cite both sides of any contract (file:line for caller and callee).
+
+## Worked non-finding (negative example)
+
+Example non-finding: "INNER JOIN on source_id silently drops rows whose source was deleted." Before reporting, read the FK: if source_id is NOT NULL with a foreign key and deletion cascades to children, an orphaned row cannot exist and the drop is unreachable. Reporting it anyway is the canonical reachability failure. The fix is not to switch to LEFT JOIN (which would add dead code for an impossible case) but to verify the constraint that governs the state.
 `;
 
 const REVIEW_NO_SLOP = `---
@@ -660,6 +680,8 @@ For each finding from the specialists:
    - Identify the real entrypoint/workflow that exercises this chain.
    If the only way to trigger the issue is by manually fabricating invalid data/state or bypassing the real producers/guards, reject the finding. If the citation is real but you cannot prove the producer chain, classify as UNVERIFIABLE rather than CONFIRMED.
 
+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.
+
 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.
@@ -673,9 +695,9 @@ For each finding from the specialists:
    Runtime reachability, producer chains, and intent verification do not apply. A mechanical finding is not a "bug" and does not need a "trigger scenario."
 
 7. **Classify:**
-   - **CONFIRMED**: For behavioral findings: the cited code matches, the claim is accurate, the bug is reachable through realistic usage, you proved the workflow/producer chain where applicable, and the behavior is not intentional. For mechanical findings: the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy.
-   - **REJECTED**: For behavioral findings: the citation is wrong, the claim is inaccurate, the bug cannot manifest in the actual runtime context, or the behavior is an intentional design decision (explain why briefly). Reject findings that rely on manually seeded invalid state/data with no real producer path. For mechanical findings: the cited text does not exist, does not violate the stated guideline, is unchanged legacy outside the touched scope, or the finding duplicates another confirmed finding.
-   - **UNVERIFIABLE**: The citation is correct but you cannot confirm the claim without deeper tracing. This is the default for plausible behavioral claims that lack a proven trigger path, producer chain, or authoritative source of truth. Mechanical findings should rarely be UNVERIFIABLE — if the text exists and violates the guideline, it is CONFIRMED.
+   - **CONFIRMED**: For behavioral findings: the cited code matches, the claim is accurate, the bug is reachable through realistic usage, you proved the workflow/producer chain where applicable, the behavior is not intentional, and for data-shape findings you read and cited the governing constraint confirming the claimed state is reachable. For mechanical findings: the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy.
+   - **REJECTED**: For behavioral findings: the citation is wrong, the claim is inaccurate, the bug cannot manifest in the actual runtime context, the behavior is an intentional design decision (explain why briefly), or a governing constraint (NOT NULL, FK, type, guard) forecloses the claimed state. Reject findings that rely on manually seeded invalid state/data with no real producer path. For mechanical findings: the cited text does not exist, does not violate the stated guideline, is unchanged legacy outside the touched scope, or the finding duplicates another confirmed finding.
+   - **UNVERIFIABLE**: The citation is correct but you cannot confirm the claim without deeper tracing. This is the default for plausible behavioral claims that lack a proven trigger path, producer chain, or authoritative source of truth. A data-shape finding that lacks the governing-constraint citation is UNVERIFIABLE, not CONFIRMED. Mechanical findings should rarely be UNVERIFIABLE — if the text exists and violates the guideline, it is CONFIRMED.
 
 ## Deduplication
 
@@ -691,6 +713,8 @@ Assign final severity based on YOUR verification:
 - **MEDIUM**: Edge cases, UX friction, or issues where the citation is correct but the impact is limited or requires unusual conditions.
 - **LOW**: Mechanical issues (stale docs, guideline violations, naming) that don't affect correctness.
 
+A data-shape or reachability finding that lacks the governing-constraint citation (the schema, type, or guard definition you read to confirm the state is reachable) is capped at UNVERIFIABLE. It cannot be classified CONFIRMED or assigned a severity. This removes the path where a plausible-but-unchecked claim lands at MEDIUM.
+
 ## Report format
 
 You MUST produce the full report structure below. Do not simplify or omit sections. Every confirmed finding must include all numbered fields. If a section has no entries, write "None" — do not skip the section.
@@ -721,6 +745,122 @@ Findings you verified as real but pre-existing, with a one-line note on the issu
 Note which files or areas were NOT covered by any specialist.
 `;
 
+// ---------------------------------------------------------------------------
+// Review context builder — gathers project/feature context before fan-out
+// ---------------------------------------------------------------------------
+
+const REVIEW_CONTEXT = `---
+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.
+---
+
+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.
+
+## Why this matters
+
+A specialist reviewer without project context will flag missing pieces of a feature as bugs or inconsistencies. If the PR is one ticket in a multi-ticket effort, the "missing" piece may be scheduled for the next ticket. Context prevents these false positives.
+
+## Sources to investigate
+
+Work through these sources in order. Not every source will yield information for every change. Skip sources that produce nothing rather than forcing a narrative.
+
+### 1. PR description
+If reviewing a PR, read the description:
+- \`gh pr view N --json title,body,labels,milestone\` (or the local branch's PR if detected)
+- Extract: stated scope, what is intentionally excluded, ticket references, linked PRs
+
+### 2. Branch name
+Branch names often contain ticket identifiers. Look for patterns:
+- \`user/ticket-123\`, \`user/plat-122\`, \`feature/PROJ-456\`
+- Extract the ticket ID and use it to search other sources
+
+### 3. Git archaeology
+- \`git log --oneline merge-base..HEAD\` — commit messages may reference tickets, describe scope, or mention future work
+- \`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
+
+### 4. TODO ($ticket) markers in the diff
+Scan the diff for TODO markers that reference ticket identifiers:
+- Pattern: \`TODO ($TICKET-ID): description\`
+- Example: \`// TODO (PLAT-123): replace this temporary flag with the real config loader\`
+- Example: \`// TODO (PLAT-124): this fallback will be removed when the new API lands\`
+- These mark intentionally deferred work: cleanups, temporary code, or pieces to be introduced later
+- Each marker tells a reviewer "this is known and scheduled, not missing"
+- Extract the ticket IDs and note what is deferred
+
+### 5. Thatch memories (RAG)
+Call \`thatch_memory_recall\` with queries like:
+- The feature or project name (if known from the PR or branch)
+- The ticket identifier
+- "feature status" or "milestone" or "roadmap"
+- Any architectural decisions or design docs related to the changed area
+
+### 6. Project documentation
+- README, docs/, design docs, ADRs
+- CONTRIBUTING.md or equivalent for conventions
+- Any roadmap, milestone, or project plan documents
+
+### 7. Issue tracker (if accessible)
+If ticket IDs were found:
+- \`gh issue list --search "TICKET-ID"\` or \`gh issue view N\`
+- Look for milestone assignments, dependencies, and blocking relationships
+- Check for epic or parent issues that describe the overall feature
+
+## Context brief format
+
+Produce a structured brief:
+
+### Project context
+- What larger initiative or feature this change is part of
+- The ticket or milestone this PR implements
+
+### This change's scope
+- What this PR is scoped to deliver (from PR description, commit messages, diff analysis)
+- What is explicitly excluded or deferred
+
+### Deferred work
+List each deferred piece:
+- What is deferred
+- Which ticket will deliver it (if known)
+- Any TODO ($ticket) markers in the code that annotate it
+
+### Dependencies
+- 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)
+
+### Relevant constraints
+- Design decisions or architectural constraints from memories or docs
+- Conventions that reviewers should be aware of
+
+## If context is sparse
+
+Not every PR will have rich context. If you find minimal context:
+- State what you looked for and what you found
+- Note that the change appears to be standalone (no multi-ticket dependencies detected)
+- Flag any TODO ($ticket) markers in the diff even if you could not resolve the ticket
+
+## The TODO ($ticket) convention
+
+When code is intentionally temporary or incomplete because work is split across tickets, mark it with a TODO that references the ticket that will resolve it:
+
+\`\`\`
+// TODO ($TICKET-ID): description of what will be done or removed here
+\`\`\`
+
+Examples:
+- \`// TODO (PLAT-123): replace this temporary flag with the real config loader\`
+- \`// TODO (PLAT-124): this fallback will be removed when the new API lands\`
+- \`# TODO (INFRA-456): delete this compatibility shim once all callers migrate\`
+
+These markers serve as breadcrumbs for reviewers (human and LLM) who lack project context:
+- They signal "this is known and scheduled, not a bug or oversight"
+- They link the code to the ticket that will resolve it
+- They should NOT be flagged as stale artifacts (the work is not yet completed)
+- They SHOULD be flagged if the referenced ticket is closed or merged (the TODO is now stale)
+`;
+
 // ---------------------------------------------------------------------------
 // Session reflection — end-of-session memory recording guidance
 // ---------------------------------------------------------------------------
@@ -821,7 +961,22 @@ Fetch any refs not locally reachable so branches and PRs that were never checked
 
 Run git diff --stat on the resolved range and git log --oneline to understand the change.
 
-## Step 2: Estimate complexity
+## Step 2: Gather project context
+
+Load the thatch-review-context skill and follow its methodology to build a context brief for this change. Investigate:
+- PR description (if a PR was specified or detected via the branch)
+- Branch name for ticket identifiers
+- Git log for commit messages referencing tickets or describing scope
+- TODO ($ticket) markers in the diff
+- 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
+
+Produce the context brief in the format the skill prescribes (project context, this change's scope, deferred work, dependencies, relevant constraints).
+
+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.
+
+## Step 3: Estimate complexity
 
 Estimate the review effort in scrum points (1-13 scale):
 - **1**: Trivial — typo fix, config tweak, single-line change.
@@ -835,7 +990,7 @@ Points reflect *review complexity*, not implementation effort.
 
 Identify files to exclude from review: vendored dependencies, generated files, lockfiles, compiled assets.
 
-## Step 3: Partition (if > 3 points)
+## Step 4: Partition (if > 3 points)
 
 For changes estimated at more than 3 points, partition into review units of approximately 3 points each:
 - Group files by logical component or feature, not by directory.
@@ -845,7 +1000,7 @@ For changes estimated at more than 3 points, partition into review units of appr
 
 For changes estimated at 3 points or fewer, skip partitioning — dispatch one set of specialists covering the full scope. A single 3-point unit is not large enough to warrant decomposition.
 
-## Step 4: Dispatch specialist sub-agents
+## Step 5: 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 five specialists are:
 
@@ -864,7 +1019,7 @@ For the integration review unit (5+ points), dispatch a sub-agent focused on:
 - Boundary correctness — race conditions, ordering dependencies, shared state issues at boundaries.
 - Top-level coherence — does the overall change make sense as a unit?
 
-## Step 5: Synthesize
+## Step 6: Synthesize
 
 After all sub-agents complete, load the thatch-review-synthesizer skill to verify findings, deduplicate across specialists, classify (CONFIRMED/REJECTED/UNVERIFIABLE), and produce the final severity-grouped report.
 
@@ -885,10 +1040,12 @@ When dispatching each sub-agent, include in the prompt:
 - The specific files in this unit's scope
 - The specialist focus (from the five 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.
 - 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
-- Instruction to apply the reachability gate and intent verification before reporting
+- Instruction to apply the reachability gate (including reading and citing governing constraints for data-state claims) and intent verification before reporting
+- Instruction to respect the project context brief: do not flag deferred work as bugs or inconsistencies, and recognize TODO ($ticket) markers as intentional breadcrumbs
 `;
 
 // ---------------------------------------------------------------------------
@@ -906,6 +1063,7 @@ const SHARED_SKILLS: SkillDef[] = [
   { name: "thatch-review-no-slop", content: REVIEW_NO_SLOP },
   { name: "thatch-review-breadcrumbs", content: REVIEW_BREADCRUMBS },
   { name: "thatch-review-synthesizer", content: REVIEW_SYNTHESIZER },
+  { name: "thatch-review-context", content: REVIEW_CONTEXT },
   { name: "thatch-session-reflection", content: SESSION_REFLECTION },
 ];