@jeffober/thatch 0.1.20 → 0.1.22

package/README.md

@@ -67,7 +67,7 @@ Include thatch's instructions in your agent's system prompt manually; see
 - **Prediction engine**: a statistical model of user decision-making
   preferences. When a prompt matches learned contexts, predictions fire
   alongside the recall nudge.
-- **Skills**: 20 skills for memory workflows, structured multi-specialist
+- **Skills**: 19 skills for memory workflows, structured multi-specialist
   code review, change walkthroughs, and writing tasks (PR descriptions,
   tickets, PR splitting).
 

package/artifacts/skills/pr-description.md

@@ -39,7 +39,7 @@ Sections, in order: SYNOPSIS, PURPOSE, DESCRIPTION, WALK-THROUGH (conditional),
 
 **SYNOPSIS, PURPOSE, and DESCRIPTION are mandatory** - even for a one-line, single-concern change. A tiny PR gets short sections, not fewer sections. WALK-THROUGH and NOTES appear only when warranted; omit them when empty. robots.txt appears only after an automated reviewer has produced a false positive worth heading off (see its section); it is always the final section.
 
-**Scale the body to the diff's conceptual size**, not its structure's capacity. A 2-file, single-concern change (add a flag, guard a branch, rename a symbol, bump a constant) is a few lines per section. SYNOPSIS one line, PURPOSE one to three, DESCRIPTION one short paragraph, NOTES if needed. The layered DESCRIPTION machinery below is for changes with real before/after mechanics to teach; when the diff is self-evident once you know the intent, collapse it. If your draft for a small change runs past ~15 lines of body, you are padding. Cut until each remaining line earns its place. Most of this skill's guidance exists to tame large PRs; applying it wholesale to a small one produces exactly the bloat the skill warns against.
+**Scale the body to the PR's complexity, not its size in files or lines.** Estimate complexity by how much new mental model the reviewer must build (see the point-based budgets in Length and style). A 1-point mechanical change gets short sections, not fewer sections. The layered DESCRIPTION machinery below is for changes with real before/after mechanics to teach; when the diff is self-evident once you know the intent, collapse it. Most of this skill's guidance exists to tame large PRs; applying it wholesale to a small one produces exactly the bloat the skill warns against.
 
 ### SYNOPSIS
 
@@ -77,7 +77,7 @@ When a ticket description is available, use its problem statement as the seed fo
 
 ### DESCRIPTION
 
-How much structure DESCRIPTION needs depends on the change's conceptual size.
+How much structure DESCRIPTION needs depends on the PR's complexity.
 
 **Small, self-evident change** (add a flag, guard a branch, rename a symbol, bump a constant): collapse to a sentence or two stating what the PR adds/changes. Do not manufacture a "how the code behaves today" paragraph for a change whose intent already makes the diff obvious. That is padding, not scaffolding.
 
@@ -240,13 +240,20 @@ These are hard rules, not suggestions.
 
 Target for most PRs: the reader can take in the whole description in under 60 seconds. Err on the shorter side.
 
-Scale the body to the diff's conceptual size:
-- Trivial 2-file change: ~15-line ceiling. SYNOPSIS one line, PURPOSE one to three, DESCRIPTION one short paragraph, NOTES if needed.
-- Moderate refactor: one tight paragraph or bullet set per section.
-- Large change with WALK-THROUGH: as long as the flow needs, but no longer. Aim for 3-6 steps; more means you are over-decomposing. Each step earns its place.
-- Enormous PR: accept that the reader may need more than 60 seconds. Keep the same rules, but spend the extra words on context, concrete behavior, and reviewer safety. Do not chase a tiny body by compressing meaning.
+Estimate the PR's **complexity** (how much new mental model the reviewer must build), not its size in files or lines. Complexity drives the word budget the way scrum points drive effort estimates:
 
-If your draft for a small change runs past ~15 lines of body, you are padding. Cut until each remaining line earns its place.
+- **1 point** (mechanical: rename, flag, guard, bump): the reviewer needs to know what changed, not why or how. ~50-100 words. SYNOPSIS one line, PURPOSE 1-2 sentences, DESCRIPTION 1-2 sentences.
+- **2-3 points** (new behavior, non-obvious mechanics): the reviewer needs to understand a before/after they cannot infer from the diff. ~100-250 words. SYNOPSIS 1-2 lines, PURPOSE 2-4 sentences, DESCRIPTION one tight paragraph or short three-layer.
+- **5 points** (new primitive, multi-workflow): the reviewer needs a mental model they do not have yet. ~250-400 words. Full sections as needed, WALK-THROUGH if there is a lifecycle.
+- **8 points** (architectural shift): the reviewer needs to re-orient their understanding of a subsystem. ~400-600 words. Accept the length, spend on context and reviewer safety.
+
+Estimate by: how many new concepts, how many decision points, whether the before/after is non-obvious, whether multiple workflows are affected. Not by files changed or lines added. A 200-line mechanical rename is 1 point. A 50-line new primitive with non-obvious semantics is 3-5 points.
+
+**When a section is too long, step up the abstraction ladder.** Do not compress terminology or cut connective tissue to hit a word count. Instead, replace a sequence of mechanism details with the principle that subsumes them. If you are explaining three mechanisms in sequence, find the one principle that makes all three obvious to someone who already knows the stack. The mechanism details belong in DESCRIPTION or the diff, not in PURPOSE or every section.
+
+Example: instead of six claims about how a connection pool reuses connections, how session locks are session-scoped, how a lock taken by one statement does not guard the next, and how nothing reports the mismatch, write: "Some Postgres features attach to the connection, not the statement. The pool freely reuses connections between statements, so state set by one statement may not be there for the next, and nothing reports the mismatch." Same understanding, fewer words, no compression.
+
+Brevity means fewer ideas, not compressed claims. If the section is still too long after stepping up, cut the lowest-value claim entirely. Do not cut the connective tissue that makes the remaining claims parse on first read.
 
 Inside sections, telegraphic bullet style is fine: lowercase start, abbreviations (`w/`, `1x`, `~`), parenthetical shorthand. Full sentences only when required for clarity. The section headers are the only formal structure.
 
@@ -401,7 +408,7 @@ That reading alone conveys the shape and scope of both changes. The prose is for
 11. **Verify links**: check ticket/PR links, repo file links, and external docs where tooling allows. Do not claim an unverified link was verified.
 12. **Verify prose style and core principle**: check each rule in Prose style. Cut design-narration, authoring-sequence, and buzzwordy abstractions. Verify plain ASCII. Verify first-use definitions for subsystem jargon. Verify project-private labels are translated before use. Verify plain English nouns (no code-domain nouns in prose). Verify conclusion-first in PURPOSE. Verify NOTES bullets are either short pointers or self-contained. Verify one-paragraph-one-physical-line for GitHub rendering. The robots.txt section is exempt from these prose rules below its human-warning line.
 13. **Clarity pass**: read the draft as a cold reviewer skimming the PR. Rewrite before returning it; do not tell the user you performed this pass. Check: does every project-specific term get plain-English meaning before or with the label? Are ambiguous terms qualified or replaced with concrete behavior? Did you replace code/comment shorthand with reader-facing behavior when the shorthand is less clear? Does every process word name object/action/effect? Does every contrast name old and new behavior? Does every causal sentence show the middle step? Did you preserve connective tissue instead of compressing meaning into noun stacks? If the draft got longer, cut a lower-value claim instead of compressing a high-value one.
-14. **Verify length**: if the body exceeds the ceiling for its conceptual size, cut until each line earns its place. For enormous PRs, accept extra length only when it buys context, concrete behavior, or reviewer safety.
+14. **Verify length**: estimate the PR's complexity (see the point-based budgets in Length and style). If the body exceeds the budget, step up the abstraction ladder first (replace mechanism sequences with the principle that subsumes them). If still over, cut the lowest-value claim entirely. Do not compress terminology or cut connective tissue to hit a word count.
 15. **Submit** via `gh pr create --body "$(cat <<'EOF' ... EOF)"` to preserve formatting.
 
 ## Anti-patterns

package/artifacts/skills/thatch-fact-extractor.md

@@ -15,7 +15,10 @@ You will be given a JSON payload with:
 1. Call thatch_memory_recall to check for existing memories related to the interactions.
 2. For each new fact, call thatch_memory_remember with the appropriate store.
 3. Do not save session-specific state, ephemeral debugging details, or info already in CLAUDE.md.
-4. Write for a future session with zero current context. No "we", "our session", "just now".
+4. Apply the durability test before saving: will this still be true and useful in a future session that knows nothing about this branch, commit, or session? If not, skip it. Do not store point-in-time values (migration indices, line numbers, file counts), commit hashes or branch history narratives (git is the source of truth), or anything re-derivable from the codebase faster than recalling it.
+5. Write for a future session with zero current context. No "we", "our session", "just now".
+6. Call thatch_extraction_done to mark the run complete. Do this even when nothing was worth saving: the parent session holds the buffered interactions until a completion signal arrives, and a memory write is not one on a no-save run.
+7. Your final message must be exactly: "Extraction complete." — do not list or summarize what you saved. The memories are in the store; the parent session does not need a report.
 
 ## What to extract
 

package/artifacts/skills/ticket-description.md

@@ -44,7 +44,7 @@ Sections, in order: SYNOPSIS, PROBLEM, BACKGROUND (conditional), PROPOSED APPROA
 
 **SYNOPSIS, PROBLEM, PROPOSED APPROACH, and ACCEPTANCE CRITERIA are mandatory.** A small ticket gets short sections, not fewer sections. Conditional sections appear only when warranted; omit them when empty. Never emit an empty header.
 
-**Scale the body to the work's conceptual size.** A one-line fix gets a one-line PROBLEM, a one-line PROPOSED APPROACH, and one or two acceptance criteria. A multi-PR feature gets full sections with real depth. The implementer should be able to start work after reading the ticket, but they should not have to read a novel to fix a guard clause.
+**Scale the body to the work's complexity, not its size in files or lines.** Estimate complexity by how much new mental model the implementer must build (see the point-based budgets in Length and style). A one-line fix gets a one-line PROBLEM, a one-line PROPOSED APPROACH, and one or two acceptance criteria. A multi-PR feature gets full sections with real depth. The implementer should be able to start work after reading the ticket, but they should not have to read a novel to fix a guard clause. Most of this skill's guidance exists to tame large tickets; applying it wholesale to a small one produces exactly the bloat the skill warns against.
 
 ### SYNOPSIS
 
@@ -66,11 +66,13 @@ The reader should know what the problem is before they read why it happens.
 
 No solution yet. The reader should finish this section agreeing there is something to address, even with zero code knowledge.
 
-Cover three things, each in its own paragraph:
+Cover three things, each in its own paragraph when the ticket has the complexity to warrant it:
 1. **What is wrong**, concretely. Name the component, the behavior, and the failure mode.
 2. **Why it matters.** Incident history, risk rating, customer impact, or "preventive: blocks a class of bug we keep almost-hitting."
 3. **Hazard rating and motivation.** How likely is the bad outcome, and under what conditions? Then answer "why now?": if the risk is low, what motivates this ticket? A prior PR identified it as a follow-up, the API still permits a failure shape, or the next planned change would make it worse. The lead's question is "should I prioritize this?" - give them the answer. _PLAT-135's ticket did this well: it named the cross-wait, then said "why it never fired" and rated the window as once-per-process cold load._
 
+A small ticket covers all three in a single paragraph; split into one paragraph per topic only when the content earns it.
+
 If the problem is preventive (no current defect), say so plainly. Then say why it is worth fixing despite the low risk.
 
 ### BACKGROUND (conditional)
@@ -89,6 +91,8 @@ Omit when the problem is self-contained. A one-line "follow-up from #6838" can l
 
 The design concept. Not a full implementation plan. Enough that the implementer knows the direction: "load key material outside the mutex" not "restructure ActiveKey to use cachedKey/publish helpers with a publish function that zeroizes the loser's DEK." The implementer writes the implementation plan; the ticket sets the compass heading.
 
+Present each mechanism in one short paragraph: what it does, plus the constraint that justifies its existence. Keep a justification when it answers an objection the reader will have (a lock that looks redundant, a retry that looks pointless). Compress failure-mode sagas to their consequence: "a leaked lock blocks every later attempt" carries what a paragraph of driver internals would. Reasons of the form "why not X" (no metric, no kill switch, no singleflight) go in NOTES as declined alternatives.
+
 For investigative tickets, this is "investigate X and propose a solution" rather than a concrete approach. Say so explicitly so the implementer knows the ticket expects analysis before implementation.
 
 This is where the ticket diverges most from a PR description. A PR description describes a change that already happened. A ticket proposes one that hasn't. The prose is prescriptive ("the fix should...") rather than descriptive ("this PR moves...").
@@ -105,7 +109,9 @@ Bad criteria are vague:
 - "improve the locking situation" (untestable)
 - "restructure ActiveKey" (implementation detail, not a behavior)
 
-If the criterion has a test shape, name it: "SetMaxOpenConns(1) with the connection held by a tx that also resolves the key." This gives the implementer the test design without dictating the implementation.
+If a criterion's test design is non-obvious, name the test shape: "SetMaxOpenConns(1) with the connection held by a tx that also resolves the key." This gives the implementer the test design without dictating the implementation. "Tested explicitly" is not a test shape.
+
+Keep the list coarse: three to seven criteria cover most tickets. This section defines "done"; it is not a test inventory. Merge parallel checks that verify the same behavior under different triggers. Drop criteria that restate PROPOSED APPROACH as a checklist - the criterion must add an observable gate, not echo the design.
 
 ### RELEASE PLAN (conditional)
 
@@ -115,7 +121,7 @@ Rollout strategy for tickets that change production behavior. Only when the chan
 - Deploy sequence (which services, in what order).
 - Rollback path (what to do if it goes wrong).
 
-A pure internal refactor with no operator-visible behavior change does not need this section. A migration that gates on a backfill completing does.
+A pure internal refactor with no operator-visible behavior change does not need this section. Neither does a change whose rollout is a normal deploy: if the only available bullets say "nothing special happens," omit the section - its absence is the nothing-special signal. A migration that gates on a backfill completing, or a revert that is not free, does need it.
 
 ### VALIDATION (conditional)
 
@@ -129,10 +135,12 @@ Only when prod verification is non-trivial. A pure refactor with good tests does
 
 ### DEPENDENCIES (conditional)
 
-Blocking relationships and ordering constraints. "Blocked by PLAT-126" is the tracker field; the _why_ belongs here: "PLAT-125 partitions by location_fingerprint, so it can only run after backfill completes (count == 0), not merely after PLAT-124 merges." That kind of nuance is what prevents a well-intentioned lead from reordering the queue.
+The tracker's blocker links carry the what; this section carries only what links cannot. Write a bullet when there is a _why_ the link cannot express: "PLAT-125 partitions by location_fingerprint, so it can only run after backfill completes (count == 0), not merely after PLAT-124 merges." That kind of nuance is what prevents a well-intentioned lead from reordering the queue. "Blocked by PLAT-126" with nothing to add is the tracker field - set the link there and omit the bullet.
 
 Distinguish hard data dependencies (cannot run until X completes) from soft dependencies (should run after X for cleanliness, but technically works independently). Say which kind it is.
 
+If every bullet would restate a tracker link, omit the section and set the links.
+
 ### NOTES
 
 Always a `## NOTES` markdown header. Never a bare `Notes:` line ending a section.
@@ -195,12 +203,24 @@ These are hard rules, not suggestions.
 
 ## Length and style
 
-Target: the implementer can start work after one read. The lead can prioritize after reading SYNOPSIS and PROBLEM.
+Target: the implementer can start work after one read. The lead can prioritize after reading SYNOPSIS and PROBLEM. Err on the shorter side.
+
+Estimate the ticket's **complexity** (how much new mental model the implementer must build), not its size in files or lines. Complexity drives the word budget the way scrum points drive effort estimates:
+
+- **1 point** (one guard, one flag, one constant): the implementer needs to know what to change, not a lesson in the subsystem. ~100-200 words. SYNOPSIS one line, PROBLEM 2-4 sentences (still rate the hazard, even if it is "no current defect"), PROPOSED APPROACH 1-2 sentences, one to three acceptance criteria.
+- **2-3 points** (new function, restructured flow, multi-file refactor): the implementer needs a before/after they cannot infer from the code alone. ~200-400 words. Full mandatory sections; BACKGROUND only when prior work or project context earns it.
+- **5 points** (new feature, migration sequence): the implementer needs a mental model they do not have yet. ~400-600 words. RELEASE PLAN, VALIDATION, and DEPENDENCIES when prod coordination warrants.
+- **8 points** (multi-PR effort, subsystem redesign, constraint-dense work): ~800-1100 words. Complex tickets legitimately need more text; spend it on context and starting state, not on repetition. If PROPOSED APPROACH is longer than the rest of the ticket combined, the ticket is probably a design doc wearing a ticket costume; split it.
 
-Scale the body to the work's conceptual size:
-- Small fix (one guard, one flag, one constant): one paragraph per mandatory section, one to three acceptance criteria. ~20-line ceiling.
-- Moderate change (new function, restructured flow, multi-file refactor): full sections with real depth. No hard ceiling, but each paragraph earns its place.
-- Large change (new feature, multi-PR effort, migration sequence): full sections plus RELEASE PLAN and VALIDATION. May run a full page. If PROPOSED APPROACH is longer than the rest of the ticket combined, the ticket is probably a design doc wearing a ticket costume; split it.
+Estimate by: how many new concepts the implementer must learn, whether the problem and approach have non-obvious mechanics, whether the work spans multiple workflows or systems. Not by files the change will touch or sections present. A mechanical multi-file rename is 1 point. A one-line fix with subtle semantics is 2-3.
+
+**When a ticket runs long, take the section-level levers first.** Omit RELEASE PLAN, VALIDATION, DEPENDENCIES, or NOTES when they carry nothing a normal deploy or the tracker links already say. Coarsen ACCEPTANCE CRITERIA. Compress PROPOSED APPROACH failure sagas to their consequences. These levers remove duplication, not knowledge.
+
+**Then step up the abstraction ladder.** Do not compress terminology or cut connective tissue to hit a word count. Instead, replace a sequence of mechanism details with the principle that subsumes them.
+
+Example: instead of six claims about how a connection pool reuses connections, how session locks are session-scoped, how a lock taken by one statement does not guard the next, and how nothing reports the mismatch, write: "Some Postgres features attach to the connection, not the statement. The pool freely reuses connections between statements, so state set by one statement may not be there for the next, and nothing reports the mismatch." Same understanding, fewer words, no compression. The mechanism details belong in the linked design doc or the code itself, not in the ticket.
+
+Brevity means fewer ideas, not compressed claims. If the ticket is still too long after the levers and the ladder, cut the lowest-value claim entirely. Do not cut the connective tissue that makes the remaining claims parse on first read. The knowledge build-up - each section introducing what the next one needs - survives every trim; what goes is redundancy.
 
 Inside sections, telegraphic bullet style is fine for criteria and plans: lowercase start, abbreviations (`w/`, `1x`, `~`), parenthetical shorthand. Full sentences for PROBLEM and BACKGROUND prose.
 
@@ -231,6 +251,8 @@ Read project context when the request, existing ticket, code comments, branch na
 
 Use available source material: linked tickets, linked PRs, nearby docs, code comments, commit messages, and project memory. Build a private term map: term -> plain behavior -> source. Do not dump the map into the ticket. Use it to write the shortest useful BACKGROUND.
 
+When rewriting an existing ticket, mine the old text for facts - harm statements, platform behaviors, traps already discovered - but draft the new description from the sources, not from the old text. Editing the old ticket inherits its phrasing and its habits; the rewrite should stand on the plan docs, the code, and the mined facts.
+
 If a term or dependency controls the work and you cannot resolve it from available context, stop and ask the user. Do not guess. Do not write around the missing definition with vaguer words.
 
 Put project context in BACKGROUND only when it helps the implementer start work or helps a lead schedule it correctly. Omit generic backstory.
@@ -389,14 +411,14 @@ That reading alone conveys the shape, scope, and gates of all three tickets.
 1. **Gather**: read the code the ticket references. Check `git log` for recent changes to the same files. Identify the problem, the prior work, and the proposed direction.
 2. **Search before create**: search Linear/Jira for likely duplicate tickets. If one exists, surface it before drafting or filing.
 3. **Codebase comparison**: verify the problem still exists in the current code. If it was already fixed, tell the user. If it was partially mitigated, note the mitigation.
-4. **Read project context for planned work**: if the ticket is part of a larger project, depends on prior work, uses unexplained project terms, or has scheduling dependencies, read the linked tickets, PRs, docs, comments, and memory before drafting. Build a private term map. If a term or dependency controls the work and you cannot resolve it, ask the user.
+4. **Read project context for planned work**: if the ticket is part of a larger project, depends on prior work, uses unexplained project terms, or has scheduling dependencies, read the linked tickets, PRs, docs, comments, and memory before drafting. Build a private term map. If a term or dependency controls the work and you cannot resolve it, ask the user. When rewriting an existing ticket, mine the old text for facts but draft fresh.
 5. **Draft PROBLEM first**, in one breath, without looking at code. If you cannot state the harm in three sentences, you do not understand the problem yet. Go back and read.
 6. **Write BACKGROUND** (if needed): what prior work led here, what was done, what was left behind, and what project context an engineer new to this area needs to start.
-7. **Write PROPOSED APPROACH**: the compass heading, not the map. Prescriptive voice.
-8. **Write ACCEPTANCE CRITERIA**: observable, testable bullets. Name the test shape where relevant.
-9. **Write RELEASE PLAN** (if needed): flags, ordering, rollback.
+7. **Write PROPOSED APPROACH**: the compass heading, not the map. Prescriptive voice. One short paragraph per mechanism, each with the constraint that justifies it; compress failure sagas to their consequence; move "why not X" reasoning to NOTES.
+8. **Write ACCEPTANCE CRITERIA**: observable, testable bullets. Coarse: three to seven, merging parallel checks and dropping restatements of the approach. Name the test shape only where the test design is non-obvious.
+9. **Write RELEASE PLAN** (if needed): flags, ordering, rollback. Omit when the rollout is a normal deploy.
 10. **Write VALIDATION** (if needed): monitoring, signals, smoke tests.
-11. **Write DEPENDENCIES** (if needed): what blocks this, what this blocks, and why.
+11. **Write DEPENDENCIES** (if needed): only the why that tracker blocker links cannot express. Omit when the links carry it; set the links instead.
 12. **Write SYNOPSIS last** - it is a compression of PROBLEM + the core approach.
 13. **Bold and italicize the save points** in the allowed locations. Bold phrases that name the work (components, mechanisms, behaviors). Italicize phrases that orient to significance (conclusions, payoffs), at most one per paragraph. Apply the scan check.
 14. **Add NOTES** for non-goals, declined alternatives, and scope limits. Use `## NOTES` header. Omit if empty.
@@ -404,7 +426,7 @@ That reading alone conveys the shape, scope, and gates of all three tickets.
 16. **Verify links**: check repo file links, external docs, tickets, PRs, and design artifacts where tooling allows. Do not claim an unverified link was verified.
 17. **Verify prose style and core principle**: check each rule in Prose style. Cut design-narration, authoring-sequence, and buzzwordy abstractions. Verify plain ASCII. Verify prescriptive voice (not descriptive). Verify first-use definitions for subsystem jargon in BACKGROUND or PROBLEM. Verify plain English nouns (no code-domain nouns in prose). Verify conclusion-first in PROBLEM. Verify NOTES bullets are either short pointers or self-contained.
 18. **Clarity pass**: read the draft as a cold lead skimming a backlog, then as an implementer picking up the work cold. Rewrite before returning it; do not tell the user you performed this pass. Check: does every project-specific term get plain-English meaning before or with the label? Are ambiguous terms qualified or replaced with specific behavior? Does every process word name object/action/effect? Does every contrast name current and proposed behavior? Does every causal sentence show the middle step? Did you preserve connective tissue instead of compressing meaning into noun stacks? If the draft got longer, cut a lower-value claim instead of compressing a high-value one.
-19. **Verify length**: if the body exceeds what the work's conceptual size warrants, cut until each line earns its place. If PROPOSED APPROACH dominates, consider splitting into a design doc plus ticket.
+19. **Verify length**: estimate the ticket's complexity (see the point-based budgets in Length and style). If the body exceeds the budget, take the section-level levers first (omit conditional sections that duplicate the tracker or a normal deploy, coarsen acceptance criteria, compress approach sagas), then step up the abstraction ladder (replace mechanism sequences with the principle that subsumes them). If still over, cut the lowest-value claim entirely. Do not compress terminology or cut connective tissue to hit a word count. If PROPOSED APPROACH dominates, consider splitting into a design doc plus ticket.
 
 ## Anti-patterns
 
@@ -427,3 +449,7 @@ That reading alone conveys the shape, scope, and gates of all three tickets.
 - **Conclusion buried at the end.** PROBLEM that builds to its point in the last sentence forces the reader to absorb the explanation before knowing what is being explained. Lead with the problem, then explain why.
 - **Hazard rating without motivation.** "No incident has hit this shape" answers "how bad?" but not "why prioritize this?" Answer "why now?" so the lead can decide whether to schedule it.
 - **NOTES bullets that are both wordy and terse.** A bullet that compresses a paragraph of rationale into one dense sentence reads as a private note. Either flag the thing and point to the full explanation, or write a self-contained sentence or two. Not the middle thing.
+- **RELEASE PLAN that argues the release is boring.** If every bullet says the rollout is routine, omit the section. Its absence is the nothing-special signal.
+- **DEPENDENCIES that restate tracker links.** "Blocked by PLAT-126" with nothing to add is the tracker field. Set the link; keep the section only for the why a link cannot express.
+- **Test inventory as acceptance criteria.** A dozen bullets covering every code path is a test plan, not a definition of done. Keep three to seven observable gates; merge parallel checks.
+- **Failure sagas in PROPOSED APPROACH.** Paragraphs of driver internals, pool lifecycle, or library quirks. Compress to the consequence; the implementer discovers the saga at the keyboard.

package/docs/dev/README.md

@@ -58,11 +58,11 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `setup.ts` | `thatch setup --claude` installer. Writes .mcp.json, appends to CLAUDE.md (idempotent), installs hooks in settings.json, installs skills. |
 | `hygiene.ts` | Hygiene report: pending dedup pairs, stale count, orphaned branch memories. Shared by the plugin's session-start hook and the CLI's `thatch reminder` command. |
 | `git.ts` | Parse `owner/repo` from git remote. Worktree-safe fallback chain. |
-| `db.ts` | SQLite schema, CRUD for entries/stores, brute-force cosine search (`search` = pure scoring, `recall` = search + telemetry stamping), dedup-pair verdict tracking. |
+| `db.ts` | SQLite schema, CRUD for entries/stores, brute-force cosine search (`search` = pure scoring, `recall` = search + telemetry stamping), dedup-pair verdict tracking. Prediction tables: matchers, predictions, edges, provenance. `scorePredictionNudge` is the shared auto-fire entry point for both host paths. |
 | `embeddings.ts` | Lazy-load the embedding model. Expose `queryEmbed`/`passageEmbed` and the model `name` (stored as an informational tag). `MockEmbeddingModel` for tests. |
 | `extraction.ts` | Per-session in-memory ring buffer (cap 20) that buffers non-thatch tool interactions and serializes them into the JSON payload the extraction nudge carries. The in-memory pipeline is opencode-only, but the payload builders (`buildExtractionPayload`, `deriveTitle`) are shared by both paths — `extract-queue.ts` imports `deriveTitle`, `bin/thatch` imports `buildExtractionPayload`. `summarizeArgs` is used internally by `buildExtractionPayload`. |
 | `extract-queue.ts` | File-backed per-session JSONL queue (caps 20, oldest dropped). Shared by the Claude Code and Cursor hook paths, which fire one-shot per event with no cross-call state. This is the MCP-side equivalent of `extraction.ts`. |
-| `sideband.ts` | Unix domain socket server + client. The MCP server (long-lived, warm model) runs `SidebandServer` so one-shot hook processes can ask it to embed a prompt and search for matches without loading the model themselves. Socket path is a hash of the DB path — both processes compute it independently. |
+| `sideband.ts` | Unix domain socket server + client. The MCP server (long-lived, warm model) runs `SidebandServer` so one-shot hook processes can ask it to embed a prompt and search for matches without loading the model themselves. Handles two methods: `match` (recall nudge) and `predictions` (prediction auto-fire). Socket path is a hash of the DB path — both processes compute it independently. |
 | `prompts.ts` | Text constants: opencode system prompt, compaction context, session-start reminder, prompt-aware recall nudge (`recallNudge` / `claudeRecallNudge`), Claude Code CLAUDE.md instructions, Cursor AGENTS.md instructions, Claude Code hook text. |
 | `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (18 skills: fact-extractor, dedup-classifier, project-primer, 6 review specialists, review synthesizer, review context, workflow research, change walkthrough, code walkthrough, session reflection, pr-description, ticket-description, split-overlarge-pr — work on both opencode and Claude Code) and `OPENCODE_ONLY_SKILLS` (1 skill: code-review coordinator — requires sub-agent support, not installed for Claude Code). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
 
@@ -74,9 +74,9 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 |------|-------------|
 | `experimental.chat.system.transform` | Appends the thatch system prompt (store names, usage rules). |
 | `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. |
+| `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. The `chat.message` hook also clears the flag if it fires for a session still in the compacting set but the incoming message has no compaction-type part — this handles compaction failure, where the session would otherwise be stuck with nudges off forever. |
 | `tool.execute.after` | Buffers every non-`thatch_*`, non-`skill`, non-`task` tool call into the session's extraction buffer. (Skill/task are excluded — buffering them creates a feedback loop where the nudge triggers a skill load, which gets buffered, which triggers another nudge.) Memory writes (`thatch_memory_remember`) and `thatch_extraction_done` drain the buffer and reset the missed-nudge counter. 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, **peeks** the buffer (does NOT drain it) and injects a synthetic text part carrying the extraction nudge + JSON payload — the buffer persists until the agent writes a memory or calls `thatch_extraction_done`, so ignored nudges repeat and escalate (polite → insistent → ALL-CAPS) via the `missedNudges` counter; (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). |
+| `chat.message` | Two priority tiers: (a) if extraction buffer has interactions, **peeks** the buffer (does NOT drain it) and injects a synthetic text part carrying the extraction nudge + JSON payload — the buffer persists until the agent writes a memory or calls `thatch_extraction_done`, so ignored nudges repeat and escalate (polite → insistent → ALL-CAPS) via the `missedNudges` counter; (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). The same embedding also feeds the prediction auto-fire: `db.scorePredictionNudge` scores the prompt against prediction matchers and injects a separate `[thatch] User decision model` nudge if any matchers clear the 0.45 threshold. Recall and prediction nudges fire independently (separate try/catch blocks, separate synthetic parts). 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. |
 
@@ -121,6 +121,23 @@ Two of these hooks were dead for weeks because failures were invisible.
    case (agent forgot to save, next user turn arrives with buffer still
    pending). This is an experiment — model reliability on meta-instructions
    is uncertain.
+10. **Background completion narration is suppressed, not prevented.** When a
+    background sub-agent completes, opencode injects a `<task_result>` block
+    into the parent session and triggers a full model generation. Thatch
+    cannot cancel this turn (no pre-response hook). Two mitigations: the
+    fact-extractor skill's return value is constrained to the literal
+    "Extraction complete." so the injected block has no narratable content,
+    and the system prompt's "Background Task Completions" section instructs
+    the model not to narrate completions or treat them as approval to act.
+11. **Prediction engine is a statistical model, not an LLM call.** The query
+    (embed prompt, cosine-match against matchers, score linked predictions)
+    is mechanical — same shape as `thatch_memory_recall` but against different
+    tables. The agent drives formation and evaluation via tools
+    (`thatch_prediction_update` with confirm/disconfirm/soft/create signals)
+    guided by system prompt instructions. No wall-clock decay; confidence is
+    relevance-gated (being tested moves it, not being ignored). See the
+    prediction DB tables, auto-fire in `chat.message`, and the sideband
+    `predictions` method for the MCP path.
 
 ## Data flow
 
@@ -178,6 +195,33 @@ hygiene heartbeat (session start)
     longer exist (skipped when worktree isn't a git repo)
   → non-zero signals appended to the session-start reminder; the agent tends
     the store when convenient — the plugin never deletes memories itself
+
+prediction cycle (agent-driven, statistical model)
+  → formation: agent calls thatch_prediction_update(matcher, prediction, signal)
+    with signal = create|confirm|disconfirm|soft. The tool embeds the matcher
+    text (raw, no header prepend — unlike memory_remember), finds or creates
+    a matcher (0.85 dedup), finds or creates a prediction (0.85 store-wide
+    dedup), links them via an edge, and adjusts confidence via a Bayesian
+    posterior: (confirm + K*P0) / (confirm + disconfirm + K), K=5, P0=0.5.
+    Soft signals count as 0.25 of a full signal. No wall-clock decay;
+    confidence is relevance-gated (being tested moves it, not being ignored).
+  → auto-fire (opencode): chat.message reuses the prompt embedding already
+    computed for the recall nudge. db.scorePredictionNudge([repo, global],
+    embedding, 0.45) finds matchers above threshold, follows edges to
+    predictions, scores by cosine * weight * confidence, dedups by
+    prediction_id, and returns top 5. Injects a separate synthetic part
+    with a [thatch] User decision model block. 0-evidence predictions use
+    "you may prefer"; predictions with evidence use "you tend to".
+  → auto-fire (Claude Code/Cursor): flush-tools fires the prediction query
+    via the sideband socket's `predictions` method in parallel with the
+    recall nudge. Same scorePredictionNudge entry point prevents scoring
+    drift between host paths.
+  → consumption: agent follows strong predictions silently, surfaces
+    ambiguous/competing predictions to the user, and calls
+    thatch_prediction_update to reinforce or weaken after the user responds.
+    thatch_prediction_list inspects the model with provenance;
+    thatch_prediction_delete removes bad predictions (cascade clears edges
+    and provenance).
 ```
 
 ## Database
@@ -188,7 +232,11 @@ hygiene heartbeat (session start)
   `entries(slug, store, label, content, embedding BLOB, model, branch,
   confidence, archived, created_at, updated_at, recall_count,
   last_recalled_at, PK(slug, store))`,
-  `dedup_pairs(store, slug_a, slug_b, status, checked_at, PK(store, slug_a, slug_b))`.
+  `dedup_pairs(store, slug_a, slug_b, status, checked_at, PK(store, slug_a, slug_b))`,
+  `prediction_matchers(id PK, store, description, embedding BLOB, model, created_at, updated_at)`,
+  `predictions(id PK, store, statement, rationale, embedding BLOB, model, confidence REAL, confirm_count REAL, disconfirm_count REAL, created_at, updated_at)`,
+  `prediction_edges(matcher_id, prediction_id, weight REAL, PK(matcher_id, prediction_id), FK CASCADE)`,
+  `prediction_provenance(id PK, prediction_id, signal, detail, created_at, FK CASCADE)`.
 - `recall_count`, `last_recalled_at`, and `archived` are added to pre-existing
   databases by an idempotent column migration at init (`PRAGMA table_info` +
   `ALTER TABLE`). The `archived` column is `INTEGER NOT NULL DEFAULT 0` (0 =

package/docs/dev/mcp-parity.md

@@ -18,12 +18,13 @@ This document maps the feature parity and documents the remaining gaps.
 
 | Feature | OpenCode plugin | Claude Code MCP + hooks | Cursor MCP + hooks | Parity |
 |---------|----------------|------------------------|---------------------|--------|
-| **Tools** (9, single source of truth) | Plugin tool registration, `thatch_` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix | **Full** |
+| **Tools** (13, single source of truth) | Plugin tool registration, `thatch_` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix | **Full** |
 | **System prompt** (store names, usage rules) | `experimental.chat.system.transform` — dynamic, repo baked in at runtime | CLAUDE.md static text appended by `thatch setup`; repo auto-detected by the MCP server at startup | AGENTS.md static text appended by `thatch setup`; repo auto-detected at startup | **Approximate** — static text persists through compaction, so the agent retains the usage instructions, but the dynamic per-turn refresh is lost |
 | **Session-start reminder** (recall nudge + hygiene heartbeat) | `session.created` event → `client.session.prompt` injects a synthetic message | `SessionStart` hook → `thatch reminder`; stdout becomes context | `sessionStart` hook → `thatch reminder --json`; output is `additional_context` JSON | **Full** |
 | **Compaction context** (re-familiarize after compaction) | `experimental.session.compacting` hook appends context to the compaction output | `PostCompact` hook — side-effects only, **cannot inject context** | No equivalent hook | **Gapped** — see below |
 | **Extraction nudge** (buffer tool calls, inject JSON payload) | `tool.execute.after` buffers non-thatch, non-skill, non-task tool calls in-process; `chat.message` peeks the buffer (does not drain it) and injects a synthetic text part | `PostToolBatch` → `thatch buffer-batch` (file-backed JSONL queue); `UserPromptSubmit` → `thatch flush-tools` peeks the queue and prints the nudge (does not drain — the queue persists until a memory write or `extraction_done`) | `postToolUse` → `thatch buffer-tool` (single-tool, file-backed queue); `beforeSubmitPrompt` → `thatch flush-tools --json` | **Full** (file-backed) — timing differs: the nudge arrives at the **start** of the next turn in Claude Code/Cursor, not at the end of the current one like opencode's `chat.message` |
 | **Prompt-aware recall nudge** | `chat.message` hook embeds the prompt with the in-process warm model, searches `db.search()`, pushes a nudge part if matches ≥ threshold | `UserPromptSubmit` hook → `thatch flush-tools` connects to the MCP server's sideband socket; the warm server embeds + searches; hook prints the nudge or falls back to the write nudge | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — sideband socket gives cold hook processes access to the warm MCP server's model |
+| **Prediction auto-fire** (user decision model) | `chat.message` hook scores the prompt embedding against prediction matchers; injects a `[thatch] User decision model` nudge alongside the recall nudge (separate synthetic part, same embedding call) | `UserPromptSubmit` hook → `thatch flush-tools` fires prediction query via the sideband socket's `predictions` method in parallel with the recall nudge | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — same `scorePredictionNudge` entry point in both paths |
 | **Skills** | Installed to `$XDG_CONFIG_HOME/opencode/skills` at plugin init (shared **+** opencode-only) | Installed to `$CLAUDE_CONFIG_DIR/skills/` by `thatch setup` (shared only) | Installed to `~/.cursor/skills/` by `thatch setup` (shared only) | **Full** — same SKILL.md format; the code-review coordinator is opencode-only (needs sub-agents) |
 | **Store detection** (repo identity from git remote) | `worktree` parameter from the opencode plugin | `CLAUDE_PROJECT_DIR` env (set by Claude Code for stdio MCP servers) | `CURSOR_PROJECT_DIR` then `CLAUDE_PROJECT_DIR` then cwd | **Full** |
 | **Setup detection at startup** | n/a — plugin auto-installs at init | `checkSetup` in MCP server: detects missing or broken instructions in CLAUDE.md | Same as Claude Code (checks AGENTS.md) | **Full** — warns the agent to tell the user to run `thatch setup` |

package/docs/qa/use-cases/README.md

@@ -28,7 +28,7 @@ file/IPC/CLI contracts ready to graduate into `bun:test` integration tests.
 | [UC-017](UC-017-buffer-tool-vs-buffer-batch.md) | `buffer-batch` (Claude, `tool_calls[]`+`session_id`) vs `buffer-tool` (Cursor, single+`conversation_id`) |
 | [UC-018](UC-018-mcp-startup-setup-detection.md) | MCP startup detects missing/broken setup instructions and warns the agent |
 | [UC-019](UC-019-archived-memory-lifecycle.md) | Archive, search exclusion, update guard, unarchive |
-| [UC-020](UC-020-extraction-escalation.md) | Nudge escalation (polite → insistent → ALL-CAPS), buffer persistence, `extraction_done` drain |
+| [UC-020](UC-020-extraction-escalation.md) | Nudge escalation (polite → insistent → ALL-CAPS), buffer persistence, `extraction_done` accept/complete |
 | [UC-021](UC-021-prediction-autofire.md) | Prediction auto-fire: matcher scores prompt, prediction nudge injected alongside recall |
 | [UC-022](UC-022-prediction-dedup.md) | Prediction create-on-existing: dedup finds match, links edge without disconfirming |
 | [UC-023](UC-023-prediction-confidence-model.md) | Bayesian confidence math: create, confirm, soft (weak disconfirm), disconfirm signals |

package/docs/qa/use-cases/UC-003-extraction-nudge.md

@@ -18,13 +18,15 @@ client and a synthetic tool call sequence._
 - The agent loads `thatch-fact-extractor` and saves durable facts via
   `thatch_memory_remember` — or saves nothing if the activity was routine.
 - The buffer is **not** drained on nudge delivery — it persists until the agent
-  writes a memory or calls `thatch_extraction_done`. If the nudge is ignored,
+  writes a memory or accepts it by calling `thatch_extraction_done`. Accepting
+  quiets the nudge while holding the entries until the extractor completes; a
+  child extractor that errors or is deleted requeues them. If the nudge is ignored,
   the next message carries a repeat nudge, escalating in urgency:
   - 1st-2nd miss: polite tone
   - 3rd consecutive miss (missedCount=2): insistent (directive) tone
   - 4th+ consecutive miss (missedCount>=3): ALL-CAPS tone
-  The counter resets when the buffer drains (memory write or
-  `thatch_extraction_done`).
+  The counter resets when the buffer drains (memory write) or is accepted
+  (`thatch_extraction_done`).
 - A `thatch_memory_remember` call in a child sub-agent session also drains the
   parent's buffer (via the `childToParent` Map), so dispatching the
   fact-extractor as a background task clears the parent's queue.

package/docs/qa/use-cases/UC-020-extraction-escalation.md

@@ -1,6 +1,6 @@
 # UC-020: Extraction nudge escalation and acknowledgment
 
-_Automatable: missedNudges counter + escalation tiers + extraction_done drain
+_Automatable: missedNudges counter + escalation tiers + extraction_done accept
 are testable with the mock client and a synthetic tool call sequence._
 
 **Preconditions**
@@ -27,10 +27,12 @@ are testable with the mock client and a synthetic tool call sequence._
   persists until a memory is written or `extraction_done` is called. The nudge
   repeats each turn with escalated tone (and the payload grows if new tool
   activity adds entries between nudges).
-- Step 6: `thatch_extraction_done` drains the buffer and resets the
-  `missedNudges` counter. The tool returns `"[acknowledged] extraction buffer
-  drained"`.
-- Step 7: no extraction nudge appears (buffer is empty). If the user prompt
+- Step 6: `thatch_extraction_done` in the parent accepts the buffer (moves it
+  to a holding area) and resets the `missedNudges` counter. The tool returns
+  `"[acknowledged]"`. Held entries drop when the extractor completes (child
+  memory write, child `extraction_done`, or child idle); if the child errors
+  or is deleted first, the entries requeue and the nudge replays.
+- Step 7: no extraction nudge appears (buffer is accepted). If the user prompt
   semantically matches existing memories, a recall nudge may appear instead.
 - Alternative drain path: if a child sub-agent (dispatched via the `task`
   tool) writes a memory via `thatch_memory_remember`, the parent's buffer is

package/docs/user/README.md

@@ -108,6 +108,15 @@ Stores are created automatically — no setup required.
 |------|-------------|
 | `thatch_extraction_done` | Acknowledge that the extraction nudge was dispatched to a sub-agent. Drains the buffer so the nudge does not replay. Called after dispatching a background task to run the fact-extractor skill. |
 
+### Prediction tools
+
+| Tool | What it does |
+|------|-------------|
+| `thatch_prediction_query` | Query the user decision model for scored predictions matching a context. Returns predictions with confidence and evidence count. |
+| `thatch_prediction_update` | Create, reinforce, or weaken a prediction. Takes a matcher (context description), a prediction (preference statement), and a signal (confirm/disconfirm/soft/create). |
+| `thatch_prediction_list` | List all predictions in a store with matchers, confidence, and provenance. |
+| `thatch_prediction_delete` | Delete a prediction by semantic match. Edges and provenance are cascade-deleted. |
+
 ## Automatic behaviors
 
 Beyond the tools, thatch hooks into opencode itself:
@@ -133,6 +142,12 @@ Beyond the tools, thatch hooks into opencode itself:
   thatch never saves memories on its own.
 - **Compaction context.** When opencode compacts a long session, thatch injects
   a reminder so the summarized session still knows memory tools exist.
+- **Prediction auto-fire.** When a prompt matches learned contexts, thatch
+  injects a `User decision model` block alongside the recall nudge. The block
+  lists scored predictions (confidence, evidence count) that the agent can
+  follow silently (strong prediction), surface to the user (ambiguous), or
+  use to update the model after the user responds. No extra model call —
+  the prediction search reuses the same prompt embedding as the recall nudge.
 
 ### Setup detection (Claude Code and Cursor)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "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/extraction.ts

@@ -91,6 +91,7 @@ export function buildExtractionPayload(
  */
 export class ExtractionPipeline {
   #buffers = new Map<string, ToolInteraction[]>();
+  #accepted = new Map<string, ToolInteraction[]>();
   #maxBuffer = 20;
 
   /** Record a tool execution for later extraction. */
@@ -110,6 +111,46 @@ export class ExtractionPipeline {
     this.#buffers.delete(sessionID);
   }
 
+  /**
+   * Accept the session's buffer: move it to a holding area so the nudge
+   * stops replaying while a dispatched extractor works. AMQP-style accept —
+   * the entries are not dropped until a completion signal arrives (the
+   * extractor writes a memory, calls extraction_done, or goes idle). If the
+   * extractor dies first, requeueAccepted puts them back.
+   */
+  accept(sessionID: string): void {
+    const buf = this.#buffers.get(sessionID) ?? [];
+    if (buf.length === 0) return;
+    this.#buffers.delete(sessionID);
+    const existing = this.#accepted.get(sessionID) ?? [];
+    this.#accepted.set(sessionID, [...existing, ...buf]);
+  }
+
+  /** Drop accepted entries: the extractor finished (save or no-save). */
+  completeAccepted(sessionID: string): void {
+    this.#accepted.delete(sessionID);
+  }
+
+  /**
+   * Move accepted entries back to pending: the extractor errored or its
+   * session was deleted before completing, so the facts were never
+   * processed. Prepended so they replay in original order. Not capped at
+   * maxBuffer — a silent drop here would defeat the point of requeueing;
+   * the next push trims back to the cap.
+   */
+  requeueAccepted(sessionID: string): void {
+    const accepted = this.#accepted.get(sessionID);
+    if (!accepted || accepted.length === 0) return;
+    this.#accepted.delete(sessionID);
+    const buf = this.#buffers.get(sessionID) ?? [];
+    this.#buffers.set(sessionID, [...accepted, ...buf]);
+  }
+
+  /** Returns the session's accepted (held) interactions. Test/introspection. */
+  peekAccepted(sessionID: string): ToolInteraction[] {
+    return this.#accepted.get(sessionID) ?? [];
+  }
+
   /**
    * Remove entries that were in the snapshot (by reference identity), keeping
    * any that arrived after the snapshot was taken. Used by the child-parent

package/src/index.ts

@@ -51,9 +51,12 @@ export const server: Plugin = async ({ client, worktree }) => {
   // 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).
+  // error. Cleared by experimental.compaction.autocontinue (success), the
+  // session.compacted event (redundant belt-and-suspenders), or chat.message
+  // itself when a non-compaction message arrives (compaction failure fallback
+  // — autocontinue never fired, so the next real user message clears the
+  // stale flag). If all three somehow miss, the flag leaks (graceful
+  // degradation: nudges stay off for that session, but no crash).
   const compacting = new Set<string>();
 
   // Per-session count of consecutive extraction nudges delivered without any
@@ -126,27 +129,34 @@ export const server: Plugin = async ({ client, worktree }) => {
     //    agent writes a memory, so ignored nudges accumulate and the payload
     //    grows with each missed cycle.
     //
-    //    A memory_remember call in a child session (sub-agent) also drains
-    //    the parent's buffer — but only the entries that existed at dispatch
-    //    time (the snapshot). Entries from interleaved turns survive so their
-    //    facts aren't silently dropped. Without this, dispatching the
-    //    fact-extractor as a background task writes memories in the child but
-    //    never clears the parent's queue — the nudge replays every turn.
+    //    Buffer lifecycle is AMQP-style accept/complete, so a failed
+    //    extractor does not silently drop unprocessed interactions:
+    //    - thatch_extraction_done in the parent ACCEPTS the buffer: it moves
+    //      to a holding area and the nudge quiets, but entries are not
+    //      dropped yet.
+    //    - COMPLETE drops the held entries. Signals: a memory_remember or
+    //      extraction_done call in a child session of that parent (the
+    //      extractor confirming it processed them), or the child going idle
+    //      (a no-save run that never acks still counts as processed).
+    //    - REQUEUE returns the held entries to pending. Signals: the child
+    //      session errors or is deleted before completing.
     //
-    //    thatch_extraction_done is an explicit acknowledgment tool the model
-    //    calls in the parent session after dispatching. Covers the case where
-    //    the sub-agent errors out or the host doesn't expose parent-child
-    //    session relationships.
+    //    A memory_remember call in a child session (sub-agent) also drains
+    //    the parent's pending buffer — but only the entries that existed at
+    //    dispatch time (the snapshot). Entries from interleaved turns survive
+    //    so their facts aren't silently dropped.
     "tool.execute.after": async (input, output) => {
       if (input.tool === "thatch_memory_remember") {
         extraction.consume(input.sessionID);
         missedNudges.delete(input.sessionID);
-        // If this is a child session, drain only the parent's snapshot entries
-        // (those present at dispatch time). Interleaved-turn entries survive.
-        // If no snapshot was recorded (e.g. session.created event never
-        // arrived), fall back to draining the entire parent buffer.
+        // If this is a child session, complete the parent's accepted entries
+        // (the extractor confirmed it is alive and saving) and drain the
+        // parent's snapshot entries from the pending buffer. If no snapshot
+        // was recorded (e.g. session.created event never arrived), fall back
+        // to draining the entire parent buffer.
         const parentID = childToParent.get(input.sessionID);
         if (parentID) {
+          extraction.completeAccepted(parentID);
           const snapshot = parentSnapshots.get(input.sessionID);
           if (snapshot) {
             extraction.consumeSnapshot(parentID, snapshot);
@@ -158,11 +168,21 @@ export const server: Plugin = async ({ client, worktree }) => {
         }
         return;
       }
-      // Explicit acknowledgment tool drains the buffer without requiring a
-      // memory write. The model calls this after dispatching the
-      // fact-extractor to a sub-agent.
+      // thatch_extraction_done has two roles depending on the session:
+      // - parent, after dispatching the fact-extractor: ACCEPT the buffer
+      //   (quiet the nudge, hold the entries for completion).
+      // - child extractor, at the end of its run: COMPLETE the parent's
+      //   accepted entries, including no-save runs that write no memory,
+      //   and drop the child's own buffer (its work is done).
       if (input.tool === "thatch_extraction_done") {
-        extraction.consume(input.sessionID);
+        const parentID = childToParent.get(input.sessionID);
+        if (parentID) {
+          extraction.completeAccepted(parentID);
+          missedNudges.delete(parentID);
+          extraction.consume(input.sessionID);
+        } else {
+          extraction.accept(input.sessionID);
+        }
         missedNudges.delete(input.sessionID);
         return;
       }
@@ -192,7 +212,18 @@ export const server: Plugin = async ({ client, worktree }) => {
     // 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 (compacting.has(input.sessionID)) {
+        // The session is marked as compacting. If this message is the
+        // compaction summary generation itself (has a compaction-type part),
+        // suppress nudges — tools are blocked during summary generation and a
+        // nudge would cause a blocked-tool error. If it is NOT a compaction
+        // message, compaction has already failed (autocontinue never fired)
+        // and the user is sending a new message. Clear the stale flag and
+        // proceed normally — tools are available again.
+        const isCompactionMsg = (output.parts as any[]).some((p) => p.type === "compaction");
+        if (isCompactionMsg) return;
+        compacting.delete(input.sessionID);
+      }
       if (extraction.pending(input.sessionID)) {
         const batch = extraction.peek(input.sessionID);
         const payload = extraction.buildPayload(batch, repo);
@@ -276,7 +307,13 @@ export const server: Plugin = async ({ client, worktree }) => {
     // snapshots the parent's current buffer — so the child's later
     // memory_remember drains only those snapshot entries, not the parent's
     // entire buffer (which may have grown from interleaved turns).
-    // session.deleted cleans both maps to avoid unbounded growth.
+    //
+    // The accepted-buffer lifecycle completes or requeues on child lifecycle
+    // events: idle means the extractor finished (a no-save run writes no
+    // memory but still processed the payload); error or deletion before
+    // completion means the facts were never extracted, so the entries go
+    // back to pending. session.deleted also cleans both maps to avoid
+    // unbounded growth.
     event: async ({ event }) => {
       if (event.type === "session.created") {
         const info = event.properties.info;
@@ -285,9 +322,39 @@ export const server: Plugin = async ({ client, worktree }) => {
           parentSnapshots.set(info.id, [...extraction.peek(info.parentID)]);
         }
       }
+      if (event.type === "session.error") {
+        const childID = event.properties.sessionID;
+        const parentID = childID ? childToParent.get(childID) : undefined;
+        if (parentID) extraction.requeueAccepted(parentID);
+        return;
+      }
+      if (event.type === "session.status" && event.properties.status?.type === "idle") {
+        const childID = event.properties.sessionID;
+        const parentID = childID ? childToParent.get(childID) : undefined;
+        if (parentID) {
+          extraction.completeAccepted(parentID);
+          missedNudges.delete(parentID);
+        }
+        return;
+      }
       if (event.type === "session.deleted") {
-        childToParent.delete(event.properties.info.id);
-        parentSnapshots.delete(event.properties.info.id);
+        const id = event.properties.info.id;
+        // A child deleted before completing never processed its payload.
+        const parentID = childToParent.get(id);
+        if (parentID) extraction.requeueAccepted(parentID);
+        childToParent.delete(id);
+        parentSnapshots.delete(id);
+        // A deleted parent takes its accepted entries with it.
+        extraction.completeAccepted(id);
+        return;
+      }
+
+      // session.compacted fires on successful compaction. Redundant with
+      // experimental.compaction.autocontinue, but belt-and-suspenders: if
+      // autocontinue didn't fire or wasn't installed, the event still clears
+      // the compacting flag so nudges resume.
+      if (event.type === "session.compacted") {
+        compacting.delete(event.properties.sessionID);
         return;
       }
 

package/src/prompts.ts

@@ -54,7 +54,9 @@ workflows. The host auto-discovers them, but reach for them proactively:
 
 **One signal is enough.** Do not wait for confirmation.
 Save immediately on: feedback, preferences, corrections, emotional signals,
-new project knowledge, conventions, architectural decisions, investigation results.
+new project knowledge, conventions, architectural decisions, investigation
+results that produced durable knowledge (not point-in-time facts about the
+current state of the code).
 
 ## Before Responding
 
@@ -64,6 +66,16 @@ whether you've discovered knowledge worth persisting. Use thatch_memory_recall
 to check for duplicates, then thatch_memory_remember for new findings. Then
 deliver your response.
 
+## Background Task Completions
+
+When a background task completes and its result is injected into the session,
+the completion is informational — it is not user input and not approval to
+proceed with anything you were discussing. Do not narrate what the task did or
+summarize its output. If you were mid-conversation with the user, continue
+that thread. If the user's last message has been fully addressed, stop and
+wait. Do not treat the completion as a trigger to advance work the user has
+not greenlit.
+
 ## User Decision Model
 
 A statistical model of the user's decision-making preferences is maintained by
@@ -100,8 +112,9 @@ reinforce or adjust it when possible.
   component relationships, conventions, operational playbooks
 - **Branch-scoped**: branch purpose, feature design decisions, PR status,
   temporary workarounds
-- **Insights**: ALWAYS save non-obvious gotchas, patterns, and architectural
-  lessons discovered during implementation. Never prompt the user; just do it.
+- **Insights**: Save non-obvious gotchas, patterns, and architectural
+  lessons discovered during implementation, but only if they remain true
+  across sessions. Never prompt the user; just do it.
 
 ## How to Write
 
@@ -116,6 +129,16 @@ reinforce or adjust it when possible.
 Session-specific context, incomplete/unverified info, anything already in
 CLAUDE.md or OPENCODE.md, speculative conclusions.
 
+Apply the durability test: will this still be true and useful in a future
+session that knows nothing about this branch, commit, or session? If not,
+do not save it. Do not store:
+- Point-in-time values (migration indices, line numbers, file counts) that
+  will be stale by next session
+- Commit hashes and branch-specific history narratives. Git is the source
+  of truth for this; do not duplicate it in memory
+- Anything re-derivable from the codebase faster than recalling it (current
+  file locations, type signatures, function names)
+
 ## Archived Memories
 
 Memories can be marked \`archived\` — a flag for stable, long-term historical
@@ -228,7 +251,9 @@ workflows. The host auto-discovers them, but reach for them proactively:
 
 **One signal is enough.** Do not wait for confirmation.
 Save immediately on: feedback, preferences, corrections, emotional signals,
-new project knowledge, conventions, architectural decisions, investigation results.
+new project knowledge, conventions, architectural decisions, investigation
+results that produced durable knowledge (not point-in-time facts about the
+current state of the code).
 
 ## Before Responding
 
@@ -274,8 +299,9 @@ reinforce or adjust it when possible.
   component relationships, conventions, operational playbooks
 - **Branch-scoped**: branch purpose, feature design decisions, PR status,
   temporary workarounds
-- **Insights**: ALWAYS save non-obvious gotchas, patterns, and architectural
-  lessons discovered during implementation. Never prompt the user; just do it.
+- **Insights**: Save non-obvious gotchas, patterns, and architectural
+  lessons discovered during implementation, but only if they remain true
+  across sessions. Never prompt the user; just do it.
 
 ## How to Write
 
@@ -290,6 +316,16 @@ reinforce or adjust it when possible.
 Session-specific context, incomplete/unverified info, anything already in
 CLAUDE.md, speculative conclusions.
 
+Apply the durability test: will this still be true and useful in a future
+session that knows nothing about this branch, commit, or session? If not,
+do not save it. Do not store:
+- Point-in-time values (migration indices, line numbers, file counts) that
+  will be stale by next session
+- Commit hashes and branch-specific history narratives. Git is the source
+  of truth for this; do not duplicate it in memory
+- Anything re-derivable from the codebase faster than recalling it (current
+  file locations, type signatures, function names)
+
 ## Archived Memories
 
 Memories can be marked \`archived\` — a flag for stable, long-term historical
@@ -390,7 +426,9 @@ export function extractionNudge(
   return `[thatch] ${dispatch} to run the thatch-fact-extractor skill ` +
     `on ${count} queued tool interaction${plural}. ` +
     `${acknowledge} ` +
-    `Then answer the user. ` +
+    `This is a system nudge, not user input. After dispatching and acknowledging, ` +
+    `stop: do not advance pending work on this nudge's account. If you are ` +
+    `waiting for the user to respond, continue waiting. ` +
     `Use ${toolName} to save durable facts from this payload:\n${payload}`;
 }
 
@@ -464,7 +502,9 @@ workflows. The host auto-discovers them, but reach for them proactively:
 
 **One signal is enough.** Do not wait for confirmation.
 Save immediately on: feedback, preferences, corrections, emotional signals,
-new project knowledge, conventions, architectural decisions, investigation results.
+new project knowledge, conventions, architectural decisions, investigation
+results that produced durable knowledge (not point-in-time facts about the
+current state of the code).
 
 ## Before Responding
 
@@ -510,8 +550,9 @@ reinforce or adjust it when possible.
   component relationships, conventions, operational playbooks
 - **Branch-scoped**: branch purpose, feature design decisions, PR status,
   temporary workarounds
-- **Insights**: ALWAYS save non-obvious gotchas, patterns, and architectural
-  lessons discovered during implementation. Never prompt the user; just do it.
+- **Insights**: Save non-obvious gotchas, patterns, and architectural
+  lessons discovered during implementation, but only if they remain true
+  across sessions. Never prompt the user; just do it.
 
 ## How to Write
 
@@ -526,6 +567,16 @@ reinforce or adjust it when possible.
 Session-specific context, incomplete/unverified info, anything already in
 AGENTS.md, speculative conclusions.
 
+Apply the durability test: will this still be true and useful in a future
+session that knows nothing about this branch, commit, or session? If not,
+do not save it. Do not store:
+- Point-in-time values (migration indices, line numbers, file counts) that
+  will be stale by next session
+- Commit hashes and branch-specific history narratives. Git is the source
+  of truth for this; do not duplicate it in memory
+- Anything re-derivable from the codebase faster than recalling it (current
+  file locations, type signatures, function names)
+
 ## Archived Memories
 
 Memories can be marked \`archived\` — a flag for stable, long-term historical

package/src/tool-defs.ts

@@ -352,29 +352,35 @@ const markCheckedDef: ToolDef = {
 };
 
 /**
- * Acknowledge that the extraction nudge has been handled. Drains the
- * extraction buffer so the nudge does not replay on the next turn.
+ * Extraction-buffer acknowledgment, with AMQP-style accept/complete roles.
  *
- * The actual draining happens in the host's post-tool hook
+ * Called in a PARENT session after dispatching the fact-extractor, it accepts
+ * the buffer: entries move to a holding area and the nudge quiets, but they
+ * are not dropped until the extractor completes. Called in a CHILD extractor
+ * at the end of its run, it completes the parent's accepted entries —
+ * including no-save runs that write no memory. If the child errors or is
+ * deleted before either signal, the host requeues the entries so the facts
+ * are not lost.
+ *
+ * The actual state changes happen in the host's post-tool hook
  * (tool.execute.after for opencode, PostToolBatch/appendBatch for MCP) —
  * this tool's execute function is a no-op confirmation. The tool exists so
- * the model can call it in the parent session after dispatching the
- * fact-extractor to a sub-agent, giving the hook a recognizable tool name
- * to key on. Without it, the buffer only drains when a memory_remember
- * call lands in the same session (or a tracked child session), which fails
- * if the sub-agent errors out or the host doesn't expose parent-child
- * session relationships.
+ * the model has a recognizable tool name to key on. In the MCP path the
+ * file-backed queue is consumed on this call (or on any memory_remember),
+ * which is durable across interruption because the queue persists on disk
+ * until then.
  */
 const extractionDoneDef: ToolDef = {
   name: "extraction_done",
   description:
-    "Acknowledge that the extraction nudge has been dispatched to a sub-agent. " +
-    "Drains the extraction buffer so the nudge does not replay. " +
-    "Call this in the parent session after dispatching a background task " +
-    "to run the thatch-fact-extractor skill.",
+    "Acknowledge extraction-buffer work. In a parent session, call after " +
+    "dispatching the fact-extractor to a sub-agent: accepts the buffer " +
+    "(quiets the nudge) while keeping entries until the extractor completes. " +
+    "In the fact-extractor sub-agent, call at the end of the run to mark the " +
+    "entries complete, even when nothing was worth saving.",
   args: {},
   async execute() {
-    return "[acknowledged] extraction buffer drained";
+    return "[acknowledged]";
   },
 };