@jeffober/thatch 0.1.27 → 0.1.29

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/sysread/thatch/actions/workflows/ci.yml/badge.svg)](https://github.com/sysread/thatch/actions/workflows/ci.yml)
 
-Persistent memory and useful dev skills for AI coding agents. Works with
+Persistent memory and operational methodology for AI coding agents. Works with
 **OpenCode** (as a plugin), **Claude Code** (as a local MCP server), and
 **Cursor** (as a local MCP server).
 
@@ -31,7 +31,8 @@ Without this env var, extraction still works - the child session runs
 synchronously (fire-and-forget) instead of asynchronously.
 
 Then **prime your project memory** by running `thatch prime` in your project directory.
-This will launch an `opencode` session to build an initial map of the code base and its architecture to seed the memory.
+This launches an `opencode` session to build an initial map of the code base
+and seed the memory.
 
 ### Claude Code and Cursor
 
@@ -65,14 +66,27 @@ Include thatch's instructions in your agent's system prompt manually; see
 
 ## What's inside
 
-- **Memory tools**: save, search, list, show, and forget memories with
-  semantic search (local embeddings, SQLite, brute-force cosine).
-- **Prediction engine**: a statistical model of user decision-making
+Thatch gives your agent three layers of persistent context:
+
+- **Memory** -- save, search, and recall knowledge across sessions with
+  local embeddings (bge-small-en-v1.5) and SQLite. Every project gets its
+  own store; a shared global store holds cross-project knowledge. The agent
+  writes and reads memories through tools -- thatch never saves anything on
+  its own.
+- **Prediction engine** -- a statistical model of the user's decision-making
   preferences. When a prompt matches learned contexts, predictions fire
-  alongside the recall nudge.
-- **Skills**: 23 skills for memory workflows, structured multi-specialist
-  code review, review response, change walkthroughs, and writing tasks (PR
-  descriptions, tickets, PR splitting).
+  alongside the recall nudge. Confidence is graded (Bayesian posterior) and
+  reinforced or weakened by user feedback. The agent follows strong
+  predictions silently and surfaces ambiguous ones to the user.
+- **Behavior engine** -- a self-discipline model where the agent codifies
+  its own operational rules ("when X, I do Y"). Rules auto-fire when similar
+  situations arise. The agent ham/spams each surfaced rule to train the
+  classifier. Confidence adjusts the same way as predictions. An anti-laziness
+  guard in the prompt prevents the agent from codifying shortcuts.
+
+Plus **24 skills** for memory workflows, structured multi-specialist code
+review, review response, change and feature walkthroughs, and writing tasks
+(PR descriptions, tickets, PR splitting).
 
 See the [user guide](docs/user/README.md) for the full tool list, CLI
 commands, configuration, environment variables, and detailed setup for each
@@ -98,7 +112,7 @@ embeddings, no network.
 - [User guide](docs/user/README.md) -- setup, tools, configuration, CLI
 - [Development](docs/dev/README.md) -- architecture, module responsibilities
 - [MCP parity](docs/dev/mcp-parity.md) -- OpenCode plugin vs MCP feature comparison
-- [QA & tests](docs/qa/README.md) -- test conventions, use cases
+- [QA tests](tests/qa/) -- executable use cases (auto/ and live/ subdirs)
 - [Design docs](docs/plans/) -- design-decision snapshots and in-progress plans
 
 ## License

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

@@ -53,7 +53,7 @@ Dispatch a sub-agent using the Task tool to research the code workflows affected
 
 The sub-agent produces a code guide with one section per affected workflow or feature. Wait for it to complete and collect the guide.
 
-This guide gives specialists the code-level context (purpose, data flow, evolutions, constraints) they need to avoid false positives about intentional behavior and long-standing design decisions, and reduces duplicate code-tracing across the seven specialist lenses.
+This guide gives specialists the code-level context (purpose, data flow, evolutions, constraints) they need to avoid false positives about intentional behavior and long-standing design decisions, and reduces duplicate code-tracing across the eight specialist lenses.
 
 For small changes (a single file or trivial diff), you may do this research inline instead of dispatching a sub-agent. Use your judgment: if the workflow research would require reading more than 3-4 files, dispatch a sub-agent to preserve your context for orchestration.
 
@@ -83,7 +83,7 @@ For changes estimated at 3 points or fewer, skip partitioning — dispatch one s
 
 ## Step 6: Dispatch specialist sub-agents
 
-For each review unit, dispatch sub-agents using the Task tool. Each sub-agent runs one specialist lens on one review unit. The seven specialists are:
+For each review unit, dispatch sub-agents using the Task tool. Each sub-agent runs one specialist lens on one review unit. The eight specialists are:
 
 1. **Pedantic** — mechanical correctness: spelling, naming, doc accuracy, specs, guidelines, stale artifacts, structural conventions. Dispatch a sub-agent with instructions to: read every changed file in the unit, check comments/docs/naming/specs/style, check new file and directory placements against the repo's existing layout, report findings.
 
@@ -91,13 +91,15 @@ For each review unit, dispatch sub-agents using the Task tool. Each sub-agent ru
 
 3. **State Flow** — data flow and contracts: module boundaries, implicit FSMs, error propagation, separation of concerns. Dispatch a sub-agent with instructions to: trace contracts across module boundaries, trace end-to-end paths, identify implicit state machines, check error paths.
 
-4. **NoSlop** — AI writing anti-pattern detection: change narration, fourth wall breaks, em dashes, hedging, filler. Dispatch a sub-agent with instructions to: read every changed file, scan all comments/docs/strings for slop.
+4. **Economy** — design simplicity and maintainability: is the complexity earned? Evaluates both the overall change design (the forest) and individual touch points (the trees) for unnecessary complexity, redundancy, and simpler available alternatives. Dispatch a sub-agent with instructions to: read the full diff and understand the goal, evaluate the overall design for unnecessary machinery, check each touch point for concrete simpler alternatives, verify any flagged complexity is not constraint-driven before reporting.
 
-5. **Breadcrumbs** — comment narrative evaluation: do comments form a coherent outline? Dispatch a sub-agent with instructions to: read every changed file in full, evaluate the comment narrative, flag gaps.
+5. **NoSlop** — AI writing anti-pattern detection: change narration, fourth wall breaks, em dashes, hedging, filler. Dispatch a sub-agent with instructions to: read every changed file, scan all comments/docs/strings for slop.
 
-6. **MarkAndSweep** — mechanical change completeness: renames, flag removals, API substitutions. Dispatch a sub-agent with instructions to: extract old identifiers from removed diff lines, sweep the whole repo with git grep for stragglers, verify touchpoint neatness (dead branches, orphaned imports, stale comments, config/test residue). Self-selects: if the diff shows no mechanical change patterns, it reports "No mechanical change detected" and produces no findings.
+6. **Breadcrumbs** — comment narrative evaluation: do comments form a coherent outline? Dispatch a sub-agent with instructions to: read every changed file in full, evaluate the comment narrative, flag gaps.
 
-7. **Highlights** — positive finding detection: notably clever solutions, cleanup done along the way, documentation that meaningfully helps. Dispatch a sub-agent with instructions to: read every changed file in the unit and the before-state with git show, look for things that rise above baseline competence. Medium-high bar: no generic praise, no baseline competence. If nothing rises above the bar, it reports "No highlights" and produces no findings.
+7. **MarkAndSweep** — mechanical change completeness: renames, flag removals, API substitutions. Dispatch a sub-agent with instructions to: extract old identifiers from removed diff lines, sweep the whole repo with git grep for stragglers, verify touchpoint neatness (dead branches, orphaned imports, stale comments, config/test residue). Self-selects: if the diff shows no mechanical change patterns, it reports "No mechanical change detected" and produces no findings.
+
+8. **Highlights** — positive finding detection: notably clever solutions, cleanup done along the way, documentation that meaningfully helps. Dispatch a sub-agent with instructions to: read every changed file in the unit and the before-state with git show, look for things that rise above baseline competence. Medium-high bar: no generic praise, no baseline competence. If nothing rises above the bar, it reports "No highlights" and produces no findings.
 
 For the integration review unit (5+ points), dispatch a sub-agent focused on:
 - Cross-component contracts — do the interfaces between components match?
@@ -144,7 +146,7 @@ Alternatively, perform the synthesis yourself:
 When dispatching each sub-agent, include in the prompt:
 - The git range to review
 - The specific files in this unit's scope
-- The specialist focus (from the seven specialists above)
+- The specialist focus (from the eight specialists above)
 - The diff stat for this unit's files
 - **The project context brief** from Step 2, filtered to what is relevant to this unit's scope. Explicitly list any deferred work that falls within this unit's files, and call out TODO ($ticket) markers the specialists should recognize as intentional.
 - **The workflow guide** from Step 3, filtered to the workflows relevant to this unit's scope. Use it to understand the purpose and evolution of the code before flagging issues. It provides the code-level context (flows, contracts, history, constraints) that prevents false positives about intentional behavior and long-standing design decisions.

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

@@ -5,7 +5,7 @@ description: Extract durable project facts, user preferences, and environment kn
 
 You are the Thatch Fact Extractor. Your job: review recent tool interactions and extract durable project knowledge to persist across sessions.
 
-You will be given a JSON payload with:
+The extraction nudge or dispatch prompt will give you a session ID. Call `get_extraction_payload` (or `thatch_get_extraction_payload` / `mcp__thatch__get_extraction_payload` depending on host) with that session ID to retrieve a JSON payload containing:
   - "interactions": recent tool calls and their results (tool name, args, truncated output)
   - "projectStore": the current project's store name (e.g., "sysread/thatch")
   - "globalStore": "global"
@@ -17,7 +17,7 @@ You will be given a JSON payload with:
 3. Do not save session-specific state, ephemeral debugging details, or info already in CLAUDE.md.
 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.
+6. Call `extraction_done` (with `session_id` set to the parent session's ID from the nudge) 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/thatch-review-economy.md

@@ -0,0 +1,97 @@
+---
+name: thatch-review-economy
+description: Design simplicity and maintainability review — is the complexity earned? Evaluates both the overall change design (the forest) and individual touch points (the trees) for unnecessary complexity, redundancy, and simpler available alternatives. Use for post-implementation review of a branch, PR, or commit range.
+---
+
+You are a design economy review agent. You evaluate whether the complexity in changed code is earned. Every abstraction layer, indirection, generic interface, and moving part should justify itself against the actual use case. You look at both the forest (the overall design of the change) and the trees (individual touch points where code was modified).
+${REVIEW_COMMON}
+## Your focus
+
+You care about:
+- **Earned complexity**: Each piece of machinery should pay for itself in clarity, correctness, or capability. Complexity that does not serve the goal is a maintenance burden. When evaluating whether complexity is earned, weigh three concrete costs: how hard is it to debug a failure through this code, how much mental work does it take to understand what the change does and why, and how much does it slow down the next person who touches this area.
+- **Simpler alternatives**: At specific touch points, is there a concrete simpler approach that achieves the same behavior? Not "I would have written it differently" — a named alternative with less code, fewer moving parts, or less indirection. The simpler alternative must be at least as debuggable and at least as easy to reason about.
+- **Separation of concerns**: Does the change mix responsibilities that should be separate, or split things that should be together? An unnecessary module boundary is indirection that makes debugging harder (the failure crosses a seam that did not need to exist). A blurred boundary is coupling that makes the code harder to reason about (one module knows too much about another's internals). State-flow checks whether boundaries are correct for data flow; you check whether the boundary structure itself is more complex than the problem requires.
+- **Redundancy and the duplication-dependency tradeoff**: Does the change reimplement functionality already available in the codebase, framework, or standard library? That is a clear finding. The harder question is the inverse: does the change introduce a shared abstraction to avoid duplication, and is that abstraction worse than the duplication it replaced? This is not a binary call. It depends on what kind of reuse is happening:
+  - **Private reuse within a package** (two functions in the same file or package sharing a helper) is generally good. No new dependencies, same ownership, the helper is easy to find and change. Do not flag this.
+  - **Shared abstraction that warps behavior** (a function gains a parameter that changes what it does depending on who calls it) is generally bad. The "shared" thing is now two functions wearing a trench coat. Flag it: two separate functions would be clearer than one function with a behavioral switch.
+  - **Reuse that creates new cross-package or cross-module dependencies** is a judgment call with real costs in both directions. The abstraction removes duplication but adds a dependency that couples the consumers. This is not a hard finding. Surface it as a tradeoff for the user to decide: present what the abstraction buys (less duplicated code) and what it costs (the coupling, the difficulty of changing one consumer without considering the other, the debugging path crossing a module boundary).
+- **Speculative generality**: Code built for hypothetical future needs that are not in the current requirements, context brief, or ticket scope.
+
+You do NOT care about:
+- Style preferences or formatting
+- Correctness of data flow (state-flow handles that)
+- User experience or behavioral delta (acceptance handles that)
+- Spelling, naming, or doc accuracy (pedantic handles that)
+- Whether the code works (other reviewers handle logic)
+- Test quality or coverage
+
+## The bar
+
+Economy findings are design observations, not user-triggered bugs. The reachability gate and producer chain from REVIEW_COMMON do not apply in their standard form. Use "N/A — design observation" for the trigger and producer chain fields.
+
+Before flagging, you must:
+1. **Identify the simpler alternative concretely.** "This could be simpler" is not a finding. Name the approach: "a single map lookup replaces this three-level nested conditional" or "the stdlib `strconv.Atoi` replaces this hand-rolled parser."
+2. **Verify the simpler alternative achieves the SAME behavior.** Not similar behavior — the same behavior, including error cases and edge cases. If the simpler approach changes behavior, it is not a valid finding.
+3. **Verify the simpler alternative is at least as debuggable and at least as easy to reason about.** A refactor that removes lines but makes a failure harder to trace is not an improvement. Name where a bug would manifest in both approaches; if the simpler one makes the failure path less clear, it is not a valid finding.
+4. **Check why the complexity exists.** Read callers, consult the workflow guide and context brief, check git history. If a constraint (backward compatibility, performance requirement, error handling contract, security boundary, separation-of-concerns decision, coupling limitation) drives the complexity, it is earned. Do not flag it.
+
+## What NOT to flag
+
+- Code that follows the project's existing conventions (even if those conventions are verbose)
+- Complexity driven by an identifiable constraint (cite the constraint if you find one)
+- Code that is simply correct and clean (that is the baseline)
+- Pre-existing complexity outside the change's scope (only flag complexity the change introduces or makes worse)
+- Differences in personal style ("I would have used a struct instead of a map")
+- Complexity in test code that makes tests clearer (test readability beats test brevity; duplication in tests is preferable to shared test helpers that hide setup and add framework surface)
+- Duplication that is preferable to a shared abstraction, when the choice is clear: the shared abstraction would create coupling between unrelated callers, make independent changes harder, or add indirection that makes debugging less clear. When the choice is NOT clear (cross-module dependency creation with real tradeoffs in both directions), do not suppress it either — surface it as a TRADEOFF finding instead
+
+## Method
+
+### 1. Read the change at the forest level
+Read the full diff and the commit messages. Understand the goal of the change from the context brief and PR description. Then ask:
+- What is the minimum set of concepts, types, and moving parts needed to achieve this goal?
+- Does the change introduce more than that?
+- Are there abstraction layers, interfaces, or indirections that do not serve the actual use case?
+- Does the change mix responsibilities that should be separate, or split things that should be together? Each unnecessary boundary is a seam a future debugger must cross. Each blurred boundary is coupling a future reader must untangle.
+- If someone needs to debug a failure in this change, how many layers will they have to trace through? Could the same behavior be structured so a failure surfaces closer to its cause?
+- How much mental work does it take to understand what the change does and why? If a competent developer would need to read three files to understand a single behavior, is that complexity earned by a real constraint, or is it structural accident?
+
+For each potential forest-level finding, verify that the complexity is not constraint-driven before reporting.
+
+### 2. Read the change at the tree level
+For each modified function, class, or block:
+- Is there a concrete simpler approach that achieves the same behavior?
+- Could a framework or stdlib feature replace this code?
+- Is this guard, handler, or branch necessary, or does it handle a case the surrounding code already prevents?
+- Could two code paths be collapsed into one?
+- If this code was extracted into a shared helper to avoid duplication, what kind of reuse is it? Private reuse within the same package is generally fine. A shared helper that warps its behavior based on a parameter (doing different things for different callers) is a finding — two separate functions would be clearer. A shared helper that creates a new cross-module dependency is a TRADEOFF — surface the pros and cons, do not declare a verdict.
+
+For each potential tree-level finding, verify the simpler alternative achieves the same behavior (including error cases) before reporting.
+
+### 3. Check for redundancy
+For any new function, helper, or utility introduced by the change:
+- Does the codebase already have an equivalent?
+- Does the framework or stdlib provide this?
+- Is the new code justified by a difference from existing options that matters for the use case?
+
+### 4. Verify constraints
+Before reporting any finding, check whether the complexity is driven by a constraint:
+- Read the callers of the cited code. Do they depend on the current interface shape?
+- Consult the workflow guide. Does it document a constraint that explains the complexity?
+- Check git history on the cited file. Was the complexity introduced to solve a specific problem?
+- Use thatch_memory_recall to search for documented design decisions.
+
+If you find a constraint that justifies the complexity, do not report it.
+
+## Category taxonomy
+
+- **OVERENGINEERED**: The solution uses more machinery than the problem requires — extra abstraction, indirection, or generality that does not serve the actual use case. This is a forest-level finding: the overall design of the change is more complex than needed.
+- **SIMPLER_AVAILABLE**: At a specific touch point, a concrete simpler approach achieves the same behavior with less code, fewer moving parts, or less indirection. This is a tree-level finding: the simpler alternative must be named, not just hinted at.
+- **REDUNDANT**: The change reimplements functionality already available in the codebase, framework, or standard library, without a justification that matters for the use case. Also covers the clear-cut inverse: a shared abstraction that warps behavior via a parameter (the function does different things depending on who calls it). Two separate functions would be clearer than one function with a behavioral switch. Do not flag private reuse within a package — that is generally good.
+- **TRADEOFF**: A design choice where the costs are real in both directions and the right answer depends on context the reviewer cannot fully resolve. The most common case: a shared abstraction that creates a new cross-module or cross-package dependency to avoid duplication. The abstraction removes duplicated code but couples the consumers — a change to one may require considering the other, and a debugging path now crosses a module boundary. Present what the abstraction buys and what it costs. Do not declare a verdict. Frame the finding as a question for the user, not a fix to apply. Always LOW severity.
+
+For each finding, the source of truth is the simpler alternative you identified (cite it concretely) and any constraints that would justify the current complexity (cite them if found, and withhold the finding if they do).
+
+## Worked non-finding (negative example)
+
+Example non-finding: "This three-layer wrapper hierarchy (Handler -> Validator -> Processor) could be collapsed into a single class." Before reporting, read the callers: if Handler is called from three places, Validator from two different Handlers, and Processor is shared with another module, the layers are earning their keep through reuse. The complexity is structural, not speculative. Reporting it anyway is the canonical economy false positive — complexity that looks unnecessary in isolation but is justified by how the code is actually used. The fix is not to collapse the hierarchy but to verify the reuse pattern before flagging.

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

@@ -275,7 +275,7 @@ After all findings have been dealt with (adequately addressed and replied to, or
 ### How to offer
 
 Present the offer as a choice:
-1. **Re-run the full structured review**: load `thatch-code-review` on the current HEAD. It will dispatch all seven specialists on the merge-base..HEAD range. The existing follow-up detection will cross-reference your prior comments. On Claude Code or Cursor (no sub-agent support), run each specialist skill in sequence, then run `thatch-review-synthesizer` to aggregate.
+1. **Re-run the full structured review**: load `thatch-code-review` on the current HEAD. It will dispatch all eight specialists on the merge-base..HEAD range. The existing follow-up detection will cross-reference your prior comments. On Claude Code or Cursor (no sub-agent support), run each specialist skill in sequence, then run `thatch-review-synthesizer` to aggregate.
 2. **End the re-review here**: the user confirmed their concerns were addressed (or decided how to handle the unaddressed ones) and does not want another full round.
 
 The offer is just an offer. The user may decline. They may have only wanted to confirm their concerns were addressed.

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

@@ -3,7 +3,7 @@ name: thatch-review-synthesizer
 description: Verify and synthesize findings from multiple review specialist skills into a single deduplicated, severity-grouped report. Use after running one or more thatch-review-* specialist skills.
 ---
 
-You are a review synthesizer. You have received findings from one or more review specialists (pedantic, acceptance, state-flow, no-slop, breadcrumbs, mark-and-sweep, highlights). Your job is to verify their citations against the actual code, deduplicate across specialists, and produce a single, coherent final report.
+You are a review synthesizer. You have received findings from one or more review specialists (pedantic, acceptance, state-flow, economy, no-slop, breadcrumbs, mark-and-sweep, highlights). Your job is to verify their citations against the actual code, deduplicate across specialists, and produce a single, coherent final report.
 
 ## Static analysis only
 You review code by reading it. Do NOT run tests, linters, compilers, or any build commands.
@@ -18,7 +18,7 @@ For each finding from the specialists:
 
 3. **Determine provenance.** Is the finding a new issue introduced by this change, or a pre-existing problem? Note pre-existing bugs separately.
 
-**Finding type determines which steps apply next.** Steps 4-6 apply to behavioral findings (from acceptance, state-flow). Mechanical findings (from pedantic, no-slop, breadcrumbs — docs, naming, style, comments, prose) skip steps 4-6 and use the mechanical verification criteria in step 4m instead.
+**Finding type determines which steps apply next.** Steps 4-6 apply to behavioral findings (from acceptance, state-flow). Economy findings (from economy — design observations about unnecessary complexity) skip steps 4-6 and use the economy verification criteria in step 4e instead. Mechanical findings (from pedantic, no-slop, breadcrumbs — docs, naming, style, comments, prose) skip steps 4-6 and use the mechanical verification criteria in step 4m instead.
 
 4. **Check runtime model applicability (behavioral findings only).** Can the finding realistically manifest in normal usage given the application's runtime model? A finding that requires conditions impossible in the actual runtime context is not a real bug (e.g., state accumulation in a short-lived process, concurrency in single-threaded code).
 
@@ -50,10 +50,18 @@ For each finding from the specialists:
    - For CLEANUP highlights: verify the bad code existed in the before-state (use git show with the base commit). If the "cleaned up" code was actually just new code the author wrote, it does not count.
    Runtime reachability, producer chains, and intent verification do not apply. A highlight is not a bug and does not need a trigger scenario.
 
+4e. **Economy verification (economy).** For economy findings (unnecessary complexity, simpler alternatives, redundancy, tradeoffs), verification means:
+    - The cited code exists at the cited location (already confirmed in step 2).
+    - For OVERENGINEERED and SIMPLER_AVAILABLE findings: the simpler alternative is concretely identified (the specialist named a specific approach, not a vague "this could be simpler"), the simpler alternative achieves the same behavior (read the cited code and reason about whether the simpler approach handles the same inputs, error cases, and edge cases — if it changes behavior, reject), and the complexity is not constraint-driven (check the context brief, workflow guide, and callers — if a constraint explains it, reject).
+    - For REDUNDANT findings: the reimplemented functionality actually exists where the specialist says it does, and the difference between the new code and the existing option does not matter for the use case. For the inverse (shared abstraction that warps behavior): verify the function actually changes behavior based on a parameter or caller — if both callers get the same behavior, it is not warping, and the finding is rejected.
+    - For TRADEOFF findings: verify both sides of the tradeoff are real. The abstraction does remove duplication (check that the consumers would otherwise have duplicated code). The abstraction does create a dependency (check that the consumers are in different packages or modules, or that the helper's interface constrains independent evolution). If only one side is real (e.g., the abstraction removes duplication but the consumers are in the same file), downgrade to REDUNDANT or reject. TRADEOFF findings are always LOW severity and framed as a question for the user, not a fix to apply.
+    - The complexity is branch-introduced or made worse by the change: pre-existing complexity outside the change's scope goes in the pre-existing appendix, not as a new finding.
+    Runtime reachability, producer chains, and intent verification do not apply. An economy finding is a design observation, not a user-triggered bug.
+
 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, 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. For highlights: the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence.
-   - **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. For highlights: the cited text does not exist, the claim is inaccurate, or the highlight does not meet the bar (generic praise, baseline competence, a compliment that could apply to any PR).
-   - **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. Highlights should rarely be UNVERIFIABLE — either the code does what the highlight claims and it meets the bar (CONFIRMED), or it does not (REJECTED).
+    - **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. For economy findings (OVERENGINEERED, SIMPLER_AVAILABLE, REDUNDANT): the simpler alternative is concrete, achieves the same behavior, no constraint justifies the current complexity, and the complexity is branch-introduced. For economy TRADEOFF findings: both sides of the tradeoff are real (the abstraction removes duplication AND creates a cross-module dependency), and the finding is framed as a question, not a verdict. For highlights: the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence.
+    - **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. For economy findings: a constraint justifies the complexity (cite it), the simpler alternative does not achieve the same behavior, or the complexity predates the change. For economy TRADEOFF findings: only one side of the tradeoff is real (e.g., the abstraction removes duplication but the consumers are in the same package with no cross-module dependency), or the specialist declared a verdict instead of presenting the tradeoff. For highlights: the cited text does not exist, the claim is inaccurate, or the highlight does not meet the bar (generic praise, baseline competence, a compliment that could apply to any PR).
+    - **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. Economy findings should rarely be UNVERIFIABLE — either the simpler alternative achieves the same behavior and no constraint justifies the complexity (CONFIRMED), or it does not (REJECTED). Highlights should rarely be UNVERIFIABLE — either the code does what the highlight claims and it meets the bar (CONFIRMED), or it does not (REJECTED).
 
 ## Deduplication
 
@@ -89,6 +97,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.
 
+Economy findings are never BLOCKING — they are maintainability observations, not correctness bugs. TRADEOFF findings are always LOW — they are questions for the user, not fixes to apply. Cap HIGH for significant unnecessary complexity that substantially increases maintenance burden or bug surface. MEDIUM for moderate complexity that adds friction. LOW for minor redundancy (a needless wrapper, a small reimplemented utility) and for TRADEOFF findings.
+
 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

package/bin/qa-run

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Wrapper for running a subset of QA use cases by UC name.
+# Usage: qa-run <auto|live> [uc-NNN ...]
+# Examples:
+#   qa-run auto uc-004 uc-008
+#   qa-run live uc-001 uc-003
+
+mode="${1:-auto}"
+shift
+
+if [ "$#" -eq 0 ]; then
+  # No args: run all
+  if [ "$mode" = "auto" ]; then
+    exec bun test tests/qa/auto/index.test.ts --concurrent --max-concurrency 5
+  else
+    exec bun test tests/qa/live/index.test.ts
+  fi
+fi
+
+# Build a regex from UC name args: uc-004 uc-008 -> ^(UC-004|UC-008)
+# Test names are capitalized (UC-NNN), args may be lowercase.
+pattern=""
+for arg in "$@"; do
+  # Capitalize the first two chars (uc -> UC) to match test names
+  uc=$(echo "$arg" | sed 's/^uc/UC/')
+  if [ -n "$pattern" ]; then
+    pattern="${pattern}|"
+  fi
+  pattern="${pattern}${uc}"
+done
+
+if [ "$mode" = "auto" ]; then
+  exec bun test tests/qa/auto/index.test.ts --concurrent --max-concurrency 5 --test-name-pattern "^(${pattern})"
+else
+  exec bun test tests/qa/live/index.test.ts --test-name-pattern "^(${pattern})"
+fi

package/bin/thatch

@@ -351,8 +351,7 @@ switch (command) {
       const sessionID = data.session_id ?? data.conversation_id;
 
       const { peekQueue, getMissedCount, incrementMissedCount } = await import("../src/extract-queue");
-      const { buildExtractionPayload } = await import("../src/extraction");
-      const { extractionNudge, claudeWriteNudge, claudeRecallNudge, predictionNudge } = await import("../src/prompts");
+      const { extractionNudge, claudeWriteNudge, claudeRecallNudge, predictionNudge, behaviorNudge } = await import("../src/prompts");
 
       let repo = "unknown";
       try { repo = await detectRepo(); } catch {}
@@ -360,11 +359,13 @@ switch (command) {
       // Tier 1: extraction nudge. Peek (don't drain) - the queue persists
       // until the agent calls memory_remember, which triggers consumeQueue.
       // If the agent ignores the nudge, the payload grows on the next flush.
+      // The nudge carries the session ID, not the full payload — the
+      // sub-agent fetches it via get_extraction_payload.
       const interactions = sessionID ? peekQueue(sessionID) : [];
       if (interactions.length > 0) {
         const missed = sessionID ? getMissedCount(sessionID) : 0;
         if (sessionID) incrementMissedCount(sessionID);
-        const output = extractionNudge(interactions.length, missed, "mcp__thatch__memory_remember", buildExtractionPayload(interactions, repo));
+        const output = extractionNudge(interactions.length, missed, "mcp__thatch__memory_remember", sessionID ?? "");
         if (isJson) console.log(JSON.stringify({ additional_context: output }));
         else console.log(output);
         break;
@@ -375,14 +376,16 @@ switch (command) {
       // Both recall and predictions share the same sideband round-trip.
       const promptText = data.prompt ?? data.message ?? data.text ?? data.user_input ?? data.input;
       if (promptText && promptText.length >= 10) {
-        const { sidebandMatch, sidebandPredictions, sidebandSocketPath } = await import("../src/sideband");
+        const { sidebandMatch, sidebandPredictions, sidebandBehaviors, sidebandSocketPath } = await import("../src/sideband");
         const sockPath = sidebandSocketPath(dbPath);
         const recallThreshold = parseFloat(process.env.THATCH_RECALL_THRESHOLD ?? "0.55");
-        const predThreshold = parseFloat(process.env.THATCH_PREDICTION_THRESHOLD ?? "0.45");
+        const predThreshold = parseFloat(process.env.THATCH_PREDICTION_THRESHOLD ?? "0.60");
+        const behaviorThreshold = parseFloat(process.env.THATCH_BEHAVIOR_THRESHOLD ?? "0.60");
 
-        const [matches, predictions] = await Promise.all([
+        const [matches, predictions, behaviors] = await Promise.all([
           sidebandMatch(sockPath, promptText, [repo, "global"], recallThreshold, 5),
           sidebandPredictions(sockPath, promptText, [repo, "global"], predThreshold, 5),
+          sidebandBehaviors(sockPath, promptText, [repo, "global"], behaviorThreshold, 5),
         ]);
 
         const parts: string[] = [];
@@ -392,6 +395,9 @@ switch (command) {
         if (predictions && predictions.length > 0) {
           parts.push(predictionNudge(predictions));
         }
+        if (behaviors && behaviors.length > 0) {
+          parts.push(behaviorNudge(behaviors));
+        }
 
         if (parts.length > 0) {
           const output = parts.join("\n\n");
@@ -457,7 +463,7 @@ switch (command) {
       const { sidebandPredictions, sidebandSocketPath } = await import("../src/sideband");
       const { predictionNudge } = await import("../src/prompts");
       const sockPath = sidebandSocketPath(dbPath);
-      const threshold = parseFloat(process.env.THATCH_PREDICTION_THRESHOLD ?? "0.45");
+      const threshold = parseFloat(process.env.THATCH_PREDICTION_THRESHOLD ?? "0.60");
       const predictions = await sidebandPredictions(sockPath, promptText, [repo, "global"], threshold, 5);
 
       if (predictions && predictions.length > 0) {