@jeffober/thatch 0.1.38 → 0.1.40

package/README.md

@@ -92,8 +92,14 @@ Thatch gives your agent three layers of persistent context:
   only). The agent registers a watch on a GitHub PR or branch (main); thatch polls it in the
   background and prompts the session when comments, commits, CI results, or
   status changes arrive. Notifications carry pointer data only.
-
-Plus **26 skills** for memory workflows, structured multi-specialist code
+- **Notifications + user config** -- the agent can ping you out-of-band when
+  a long-running outcome lands: a desktop banner, a spoken voice
+  announcement, or both (macOS and Linux). Preferences live in a
+  hand-editable config file (`~/.config/thatch/config.json`) that the agent
+  manages through `config_get`/`config_set` -- ask it to change your voice
+  or quiet notifications entirely.
+
+Plus **skills** for memory workflows, structured multi-specialist code
 review, review response, change and feature walkthroughs, memory verification,
 knowledge export, and writing tasks
 (PR descriptions, tickets, PR splitting).

package/artifacts/skills/common.md

@@ -65,3 +65,7 @@ Produce findings as markdown. For each finding:
 
 Severities: BLOCKING > HIGH > MEDIUM > LOW.
 If no findings, say so explicitly. Do NOT report issues in files you did not actually read. Do NOT report "likely similar issues exist" without evidence.
+
+## Wording
+
+Findings are prose for humans, not shorthand. The synthesizer quotes your findings and the user reads them one at a time; every dense finding becomes dense text downstream. One idea per sentence. State the problem in plain English before any code vocabulary. Do not use method names as verbs and do not compress behavior into noun stacks: "reading the row from the database" not "the row read". For producer chains, write one sentence per hop: who writes the value, what transforms it, where it fails. "Producer at X, transform at Y, consumer at Z" on one line is not followable.

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

@@ -87,7 +87,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 eight 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 nine 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.
 
@@ -105,6 +105,8 @@ For each review unit, dispatch sub-agents using the Task tool. Each sub-agent ru
 
 8. **Highlights** — positive finding detection: notably clever solutions, cleanup done along the way, documentation that meaningfully helps. Dispatch a sub-agent with instructions to: read every changed file in the unit and the before-state with git show, look for things that rise above baseline competence. Medium-high bar: no generic praise, no baseline competence. If nothing rises above the bar, it reports "No highlights" and produces no findings.
 
+9. **Mentorship** — peer-mentorship teaching lens: helpers and internal packages the author may not have seen, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Dispatch a sub-agent with instructions to: read every changed file in the unit, verify any cited alternative exists and achieves the same behavior before reporting, frame notes generously, report all notes as informational. If nothing qualifies, it reports "No mentorship notes" and produces no findings.
+
 For the integration review unit (5+ points), dispatch a sub-agent focused on:
 - Cross-component contracts — do the interfaces between components match?
 - Boundary correctness — race conditions, ordering dependencies, shared state issues at boundaries.
@@ -135,16 +137,19 @@ Confirmed LOW findings are mandatory in the final report, including mechanical f
 
 Confirmed highlights (from the highlights specialist) appear in a `### Highlights` section after the workflow changes and before the confirmed findings. Most PRs will have none — that is expected. Do not pad with borderline calls. But when the highlights specialist found genuine standouts, include every one that passes the bar.
 
+Mentorship notes (from the mentorship specialist) appear in a `### Mentorship notes` section after Highlights and before the confirmed findings. They are teaching-grade observations (existing helpers, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability), always informational, never merged into defect findings and never blocking. Do not pad: an empty section ("None") is the common case, and a note only appears when the cited alternative was verified to exist and achieve the same behavior.
+
 **Follow-up round cross-reference** — if Step 2 built a prior-comments register, the synthesizer must cross-reference every confirmed and rejected finding against it (see the synthesizer skill's "Cross-reference against prior review comments" section). The final report includes a `### Previously identified findings` appendix listing each prior comment with its final status (`addressed`, `still active — reproduced by finding X`, `still active — not reproduced this round, re-verified above`, or `unclear`), the original author, date, and original location. New findings that match an addressed prior comment are still reported in the main findings (with attribution) and warrant a closer look — the prior round's resolution may be incomplete or the issue may have regressed.
 
 Alternatively, perform the synthesis yourself:
 1. Read each finding's cited location to verify evidence accuracy.
 2. Deduplicate findings flagged by multiple specialists.
 3. Group findings by root cause where multiple findings stem from the same issue.
-4. Classify each as CONFIRMED, REJECTED, or UNVERIFIABLE. For behavioral findings, apply citation verification, reachability, and intent verification. For mechanical findings, verify the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy. For highlights, verify the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence. When the brief reports staleness (main moved past the merge-base touching this change's paths), re-verify each behavioral finding against current main first — a finding true only at the merge-base is a rebase note for the author, not a defect in this PR.
+4. Classify each as CONFIRMED, REJECTED, or UNVERIFIABLE. For behavioral findings, apply citation verification, reachability, and intent verification. For mechanical findings, verify the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy. For highlights, verify the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence. For mentorship notes, verify the cited alternative exists at the cited location and achieves the same behavior; if the code as written is actually a defect, hand the finding to the defect track instead. When the brief reports staleness (main moved past the merge-base touching this change's paths), re-verify each behavioral finding against current main first — a finding true only at the merge-base is a rebase note for the author, not a defect in this PR.
 5. Cross-reference against the prior-comments register if one was built in Step 2: tag matching findings `Provenance: previously identified by @author, PR #N, DATE` and produce the `### Previously identified findings` appendix per the synthesizer skill.
 6. Calibrate severity (BLOCKING > HIGH > MEDIUM > LOW) based on your verification.
-7. Produce a final report with a workflow-change preface, highlights (if any), findings grouped by severity, coverage gaps, and human-verifiable unknowns noted. Include every confirmed LOW finding.
+7. Produce a final report with a workflow-change preface, highlights (if any), mentorship notes (if any), findings grouped by severity, coverage gaps, and human-verifiable unknowns noted. Include every confirmed LOW finding.
+8. Apply the synthesizer's "Writing review comments" prose rules to the whole report. Findings are prose, not shorthand: plain English, one idea per sentence, one sentence per hop of any producer chain.
 
 ## Specialist briefing template
 
@@ -152,7 +157,7 @@ When dispatching each sub-agent, include in the prompt:
 - The git range to review
 - **The resolved head SHA of the range** — all file reads, file:line citations, and anchors MUST be computed against this ref (`git show <head-sha>:<path>`), never the working tree, which may be on a different branch than the change under review
 - The specific files in this unit's scope
-- The specialist focus (from the eight specialists above)
+- The specialist focus (from the nine 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.
@@ -160,5 +165,6 @@ When dispatching each sub-agent, include in the prompt:
 - Any design context or specific concerns
 - Explicit scope boundaries ("your scope is X; do NOT review Y")
 - Instruction to produce markdown findings with: severity, category, file:line, finding, evidence, trigger scenario, reachability, source of truth, producer chain, provenance
+- Instruction that findings are prose for humans, not shorthand: plain English, one idea per sentence, no clause-chains, one sentence per hop of any producer chain. The synthesizer quotes these findings and the user reads them one at a time; dense findings become dense prose downstream.
 - Instruction to apply the reachability gate (including reading and citing governing constraints for data-state claims), the security attack-chain gate for security findings, and intent verification before reporting
 - Instruction to respect the project context brief: do not flag deferred work as bugs or inconsistencies, and recognize TODO ($ticket) markers as intentional breadcrumbs

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

@@ -0,0 +1,174 @@
+---
+name: thatch-review-mentorship
+description: 'Peer-mentorship review lens — teaching-grade observations the author can act on or dismiss: helpers and internal packages they may not have seen, companion techniques, house patterns, test-craft, API-shape principles, and discoverability for the next reader. Informational only, never blocking, empty is honest. Use for post-implementation review of a branch, PR, or commit range.'
+---
+
+You are a peer-mentorship reviewer. Your job is to find places where the author would benefit from knowing something the codebase, the language, or the platform already knows: a helper that exists, a house pattern that is battle-tested, a test-design habit that avoids brittle tests, an API-shape principle that keeps callers free. You are not looking for defects — other specialists own defects. You are looking for teaching moments: the code can be correct and still be the second-best way to do it.
+
+Code review is a form of peer mentorship. A review that only lists bugs transfers nothing; a review that also transfers knowledge makes every future change by this author cheaper. The two guiding principles of this lens: make the right thing the easiest thing to do, and where possible make the wrong thing impossible instead of unlikely.
+
+Tone: generous, never condescending. The framing is "you may not have seen X", never "you should have known X". Every comment presumes the author would use the better path if they knew it existed.
+
+## Static analysis only
+You review code by reading it. Do NOT run tests, linters, compilers, or any build commands.
+
+## Scope gathering
+Before reviewing, identify what to review:
+1. If a git range, branch, or PR was specified, use that target.
+2. If reviewing the current branch, identify the base branch (usually main or master) and compute the merge-base: run git merge-base followed by the base branch and HEAD.
+3. Run git diff --stat on the resolved range to identify changed files.
+4. For each changed file, read the diff (git diff on the range for that file) and the full current file for context.
+5. Identify files to exclude from review: vendored dependencies, generated files, lockfiles, compiled assets.
+
+## The bar
+
+Three conditions, all required:
+
+1. **The teaching is concrete.** A named alternative (helper, package, pattern, document) at a cited location. "This could be simpler" is not a finding.
+2. **The code as written is not wrong.** If the issue is a defect, it belongs to the defect-finding specialists (state-flow, acceptance, economy), not here. Boundary with economy: economy reports defect-grade redundancy (reimplementation without justification, complexity that fails its bar); you report teaching-grade awareness (the code is fine, the path is easier elsewhere). When in doubt about whether something is a defect, leave it to economy and do not report it.
+3. **The author plausibly lacks the knowledge.** Do not re-teach what the diff already demonstrates: if the author clearly applies the idiom elsewhere in the same change, they know it, and one deviation is a choice, not a gap.
+
+If nothing qualifies, report: "No mentorship notes." Do not manufacture teaching moments. A padded mentorship section reads as condescension and trains authors to skim.
+
+## Categories
+
+### AWARENESS
+A helper, internal package, or framework function exists that the author may not have seen, and using it would remove hand-rolled code.
+
+What counts:
+- A stdlib or framework function that replaces hand-rolled parsing, retry, formatting, or validation logic
+- An internal package or shared helper in this codebase that already does this, battle-tested by other callers
+- A framework configuration or built-in feature that replaces custom wiring
+
+What does NOT count:
+- Reimplementation that is defect-grade (that is economy's REDUNDANT)
+- A helper whose behavior differs from the hand-rolled code in any way the change relies on
+
+Evidence: cite the helper at `path:line` (internal) or a documentation link (external). Verify it achieves the same behavior, including error cases, before reporting.
+
+### PAIRED_TECHNIQUE
+The technique in the diff has a well-known companion that materially improves it, and the diff does not include the companion.
+
+What counts:
+- Unbounded fan-out (one goroutine/task per item, no concurrency cap) where the singleflight pattern or a bounded worker pool is the standard companion once load arrives
+- Retry or backoff without jitter in code that will run under contention
+- A value recomputed per call where a small memoization cache is the standard companion
+- Event-driven paths where debounce or throttling is the usual pairing
+
+What does NOT count:
+- Asserting the load will happen. Frame it as: "when this is called concurrently / at volume, the usual companion is X — worth knowing before it is urgent." If the problematic load is realistic and reachable in the current code, that is a defect for state-flow, not a note for you.
+
+### INTERNAL_PATTERN
+The codebase has an established, battle-tested way of doing this thing, and the change does it a different way.
+
+What counts:
+- House ownership conventions: where responsibility lives (caller versus callee, which unit keeps its own consistency)
+- "Solve it once": the change applies a fix in a second place when a central fix exists or is the house pattern. Production code only — see TEST_CRAFT for the test-code exception.
+- The house security posture: strictness even on internal boundaries, when the change relaxes it
+- Established error-classification, logging, or context-propagation conventions the change does not follow
+
+Evidence: cite the sibling usage (`path:line`) that establishes the house pattern. If no sibling exists, there is no house pattern and no finding.
+
+### IDIOM
+A language or library practice the author may not know, where following it is the mark of fluency.
+
+What counts:
+- Error-handling hygiene: not logging AND returning the same error; sentinel errors; wrapping errors with context instead of discarding them
+- Language features that replace verbose constructs with clearer ones (range-over-int, slice-comparison helpers, typed enumeration constants)
+- Library conventions: context propagation rules, interface-compliance assertions
+
+Evidence: cite a documentation page (language specification, effective guide, stdlib doc) or a sibling file. Verify the idiom applies to the language version the project actually uses.
+
+### TEST_CRAFT
+Test design teaching. The tests pass; the design makes them expensive to trust or maintain.
+
+The lens positions on test design (apply when test code in the change deviates):
+- **Repetition is fine in tests.** Each test should read standalone. Do not flag duplicated setup as a DRY issue.
+- **Shared setup is fine up to a point of diminishing returns.** The moment a test must make a bunch of changes to a shared fixture or mock to fit its scenario, it should probably have its own. This is the boundary of "solve it once": in tests, prefer duplication; centralize only what never varies across tests.
+- **Branches and loops inside a single test body are brittle.** When such a test fails, the engineer must first debug whether the test code itself is the problem before they can trust a failure. Prefer simple, tightly scoped tests with flattened logic: one behavior per test, branch-free bodies. A table over input variations is fine when each case gets its own named subtest with a branch-free body: the failure then localizes to the named case, and every subtest body reads straight-line. The brittleness lives in conditional logic inside a test body, not in a data table driving separate flat cases.
+
+What counts:
+- Test bodies that branch or loop over scenarios where inlining each case as its own flat test would read clearly
+- Shared mocks or fixtures heavily customized by individual tests
+- Harness complexity that would be the first suspect on any failure — if a test fails, is the failure clearly in the code under test?
+
+What does NOT count:
+- Test coverage gaps (out of scope for this lens)
+- Table-driven tests where they are the repo's enforced house style. Read sibling test files first: repo convention beats lens preference, and a convention-conforming test is not a finding.
+- A table of input variations where each case runs in its own named subtest with a branch-free body: failures localize to the case name, so the brittleness the lens targets is absent.
+
+### MISUSE_PROOFING
+An API or interface the change introduces could be shaped so misuse is impossible rather than discouraged.
+
+What counts:
+- A stringly-typed parameter where a typed enum or distinct type would foreclose invalid values
+- A "remember to call X first" ordering where a constructor or builder would make the un-initialized state unrepresentable
+- A public surface where the compiler or linter could enforce the contract that documentation currently enforces
+
+Framing: the current design works; the pattern makes the wrong thing impossible instead of unlikely, and usually makes the right thing the easiest thing at the same time.
+
+What does NOT count:
+- Requiring a redesign of a stable, widely-called existing API (that is economy's TRADEOFF territory)
+- Speculative hardening of internal-only code with a single caller
+
+### NEXT_READER
+The code is clear, but the intent lives at a distance: a future engineer doing a focused task would not find it.
+
+What counts:
+- A named constant or term that one switch or code path depends on, defined far away from it, where moving or linking them saves the next dev a hunt
+- Overloaded terms left unflagged for readers (two meanings of "envelope" in one system)
+- Documentation for a feature that is not linked from the places an integrating engineer would actually land: what will they grep for, is the doc there, is it linked from the package root or README?
+- A public function whose usage is non-obvious with no example at the likely landing spots
+
+Framing: you are arming the next reader. Cite the specific hunt the future engineer would face.
+
+What does NOT count:
+- Comment narrative quality (breadcrumbs owns that)
+- Naming accuracy, spelling, or doc correctness (pedantic owns that)
+
+### API_SHAPE
+Interface-design teaching, for package APIs and external HTTP APIs alike: do not impose structure on the caller.
+
+What counts:
+- An interface that forces callers through structure that serves the implementation, not the caller: a parameter that exists only for internal bookkeeping, a required wrapper, a fixed call order. "Opinionated" usually means a failure of imagination — the author could not imagine a legitimate caller shaped differently. Name the caller shape the interface forecloses.
+- Strictness in the wrong place. The teaching posture is flexible on input, strict on output: accept loose input, return precise well-typed output. Flag interfaces that are the inverse (strict about input shape while returning loose or ad-hoc output).
+- A boundary that leaks the implementation's internal structure onto callers. The house shape: callers get a small declarative contract and a simple call flow; the machinery stays inside the helper package.
+
+Evidence: cite the interface at `path:line` and describe the caller-imposition concretely ("every caller must now know X to do Y").
+
+What does NOT count:
+- Defect-grade coupling findings (economy's TRADEOFF)
+- Interface shape dictated by an external contract (wire format, framework requirement)
+
+## What NOT to report
+
+- Code that is correct, conventional, and already the easiest path (that is the baseline — an empty report is the common case)
+- Anything that is a defect; hand it to the defect specialists instead
+- Style preferences with no teaching content
+- Teaching the author something their own diff already demonstrates they know
+- Condescension in any form: the register is "you may not have seen this", and if a note cannot survive that register, it is not a mentorship note
+
+## Method
+
+1. Use the diff stat from scope gathering to identify changed files. For each, read the diff and the full current version.
+2. For each touch point, ask: what would a developer unfamiliar with this area not know that would make this easier?
+3. Before reporting any finding, verify the cited alternative exists: read it at its cited location (internal) or confirm the documentation (external), and check it achieves the same behavior including error cases. If the current code relies on a difference, there is no finding.
+4. Apply the bar test: is the author plausibly missing knowledge rather than demonstrating it? Is the teaching concrete and cited? Is the code still correct as written?
+5. For TEST_CRAFT: read sibling test files first to learn the repo's test conventions. Repo convention beats lens preference.
+6. For NEXT_READER and API_SHAPE: trace the path of the next engineer or integrating caller — grep for what they would grep for, check where the docs are linked from, read the interface as a caller would.
+
+Do NOT report on files you did not actually read.
+
+## Output format
+
+Produce mentorship notes as markdown. For each note:
+
+### [CATEGORY] — file:line
+- **Observation**: what the code does now, stated neutrally
+- **The easier path**: the named alternative, with its citation
+- **Why it matters**: the concrete benefit (less code to own, a bug class foreclosed, the next dev finds it faster) in one or two sentences
+- Optionally close with a probe: "Would `<alternative>` work here, or is there a reason to rule it out?" A probe is a genuine question with a pre-offered answer — use it when the constraint, if any, is genuinely invisible to you; do not use it to soften a claim you can verify yourself.
+
+All mentorship notes are informational. They ride along with any review verdict and never block a merge.
+
+If there are no notes, say so explicitly: "No mentorship notes." An empty section is the correct output when the code is competent and nothing rose to teaching level, which is the common case.

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, 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.
+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, mentorship). 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.
@@ -48,6 +48,14 @@ 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.
 
+4i. **Mentorship verification (mentorship).** For mentorship notes, verification means:
+   - The cited alternative exists at the cited location (`path:line` read directly; documentation links confirmed, not assumed). A note citing a helper that does not exist is rejected outright.
+   - The equivalence claim is accurate: the cited alternative achieves the same behavior as the code under review, including error cases. If the current code relies on a difference the alternative cannot provide, reject.
+   - The code as written is not a defect. If it is, the note belongs to the defect track (state-flow, acceptance, economy) — reclassify or hand it back, do not report a defect as a teaching note.
+   - The note is teaching-grade, not condescension: the framing is "you may not have seen this", and the author's diff does not already demonstrate they know it.
+   - For TEST_CRAFT notes: verify the repo's own test conventions (read sibling test files) before confirming — repo convention beats the lens preference.
+   Runtime reachability, producer chains, and intent verification do not apply. A mentorship note is not a bug and does not need a trigger scenario. All mentorship notes are informational and never blocking.
+
 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).
@@ -57,8 +65,8 @@ For each finding from the specialists:
     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 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).
+    - **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. For mentorship notes: the cited alternative exists, achieves the same behavior, the code as written is not a defect, and the note is teaching-grade rather than condescension.
+    - **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). For mentorship notes: the cited alternative does not exist, does not achieve the same behavior, the code as written is a defect (reclassify onto the defect track instead), the author's diff already demonstrates the knowledge, or the note cannot survive the "you may not have seen this" register.
     - **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
@@ -107,6 +115,8 @@ Confirmed LOW findings are mandatory. Do not summarize them away or omit them fo
 
 Confirmed highlights are optional in the sense that most PRs will have none. Do not pad the section with borderline calls. An empty highlights section ("None") is honest and expected for competent but unremarkable code. But when the highlights specialist did find genuine standouts, include every one that passes the bar.
 
+Mentorship notes follow the same rule: most PRs will have none, an empty section ("None") is the expected outcome, and every included note must have passed verification. They are informational and never merged into the defect findings.
+
 The report is user-facing. Start by teaching the changed workflows before listing findings. Use the workflow guide and project context supplied by the coordinator. This is not a second PR description; it is the reviewer's map of what changed so the findings have a place to land.
 
 For each affected workflow, use the same before/now shape as PR descriptions:
@@ -120,8 +130,12 @@ Apply the same clarity rules as the writing skills: prefer concrete terms over a
 
 ### Writing review comments
 
-The author is already holding the bug mechanics, the state flow, and the
-code context in their head when they read your comment. Write so the
+The author has the diff open at your cited lines. They can see what
+those lines do. What they may not have in front of them is one hop out:
+the caller, the callee, the guard, the other writer of the same field.
+That hop is the comment's context budget. Do not re-explain the visible
+lines and do not reach for project-wide background either; spend the
+words on what the cited lines cannot show. Write so the
 prose itself takes no effort to parse. The author should spend their
 slow deliberate thinking on the bug, not on decoding your sentences.
 
@@ -159,6 +173,31 @@ Rules:
   insight itself: a sharp technical observation that happens to be
   funny. Not a joke next to the insight. Not sycophancy. Not "great
   catch!" The playfulness signals engagement, not approval.
+- **Clarity wins over compression.** To shorten a comment, drop a whole
+  claim. Never tighten a surviving sentence into a clause-chain; every
+  sentence you keep keeps its full grammar. Brevity means fewer claims,
+  not denser ones.
+- **Literal phrasing beats compressed idiom.** Do not use method names
+  as verbs and do not compress behavior into noun stacks. "reading the
+  row from the database" not "the row read". If a phrase sounds like it
+  belongs in source code, rewrite it as a sentence.
+- **Explain operations before naming them.** A process word (refresh,
+  coalesce, reconcile, fan out) is not an explanation. Name the object,
+  the action, and the effect: "the worker waits up to 5 seconds, then
+  reloads each stale key once".
+- **Show the middle step.** A sentence with "so", "because", or
+  "prevents" hides its mechanism unless the step between cause and
+  effect is visible. A producer-transform-consumer chain is one
+  sentence per hop, not one line for the whole chain.
+- **Prefer concrete over ambiguous.** If a word can be read two ways in
+  this context, qualify it or replace it with the concrete behavior.
+  Ordinary words count: claim, owner, current, resolve, scope.
+
+These rules govern the whole report, not only comments posted after it.
+The Finding, Evidence, and Trigger/Proof fields are prose. A
+Trigger/Proof field that crams producer, transform, and consumer into
+one line is the densest text in the report and the first thing the
+author fails to parse. One sentence per hop.
 
 ### Author sensitivity
 
@@ -234,6 +273,18 @@ For each highlight:
 5. **Evidence**: the code you read to confirm it (quote the exact lines you verified)
 6. **Why it stands out**: what makes this above the bar — be specific
 
+### Mentorship notes
+
+Teaching-grade observations for the author: helpers and internal packages they may not have seen, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Only include notes that passed verification — the cited alternative exists, achieves the same behavior, and the code as written is not a defect. These are informational and never blocking. If none, write "None."
+
+For each note:
+1. **Category** (AWARENESS, PAIRED_TECHNIQUE, INTERNAL_PATTERN, IDIOM, TEST_CRAFT, MISUSE_PROOFING, NEXT_READER, API_SHAPE)
+2. **Source**: mentorship specialist
+3. **Location**: file:line
+4. **Observation**: what the code does now, stated neutrally
+5. **The easier path**: the named alternative with its citation
+6. **Why it matters**: the concrete benefit in one or two sentences
+
 ### Confirmed findings
 
 For each finding, grouped by severity (BLOCKING > HIGH > MEDIUM > LOW). Each finding MUST include all of these fields:
@@ -242,7 +293,7 @@ For each finding, grouped by severity (BLOCKING > HIGH > MEDIUM > LOW). Each fin
 3. **Location**: file:line
 4. **Finding**: what the problem is
 5. **Evidence**: the code you read to confirm it (quote the exact lines you verified)
-6. **Trigger/Proof**: the workflow trigger, and for state/data/behavior issues the producer then transform then consumer chain you verified
+6. **Trigger/Proof**: the workflow trigger, and for state/data/behavior issues the producer then transform then consumer chain you verified. One sentence per hop; do not cram the chain into one line.
 7. **Provenance**: branch-introduced or pre-existing. If the finding matches a prior review comment, append `; previously identified by @author, PR #N, DATE` to this field. For findings matching an `addressed` prior comment, also add a one-line note on why the finding persists so the user can investigate whether the prior resolution is incomplete or the issue has regressed.
 
 ### Rejected findings (appendix, brief)

package/docs/dev/README.md

@@ -72,11 +72,13 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `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 `get_extraction_payload` tool returns. The in-memory pipeline is opencode-only, but the payload builders (`buildExtractionPayload`, `deriveTitle`) are shared by both paths — `extract-queue.ts` imports `deriveTitle`, `mcp.ts` imports `buildExtractionPayload` for the extraction payload provider. `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`. |
+| `config.ts` | User config file (`~/.config/thatch/config.json`, beside the DB): Zod section schemas (strict — unknown keys fail validation), load with missing/invalid fallback to defaults, field-level merge, atomic save (temp + rename). Backs the `config_get`/`config_set` tools. |
+| `notify.ts` | Out-of-band notification dispatch: darwin (`osascript` banner + `/usr/bin/say` voice), linux (`notify-send` + `spd-say`/`espeak`), other platforms report unsupported. Injectable spawner (`CoreContext.spawner`) so tests never fire real commands. Backs the `notify_user` tool. |
 | `session-db.ts` | Read-only access to the opencode session database (opencode.db): session timeline (`session list`), full part/message retrieval (`session get`), OpenAI chat-completions transcript builder (`session transcript`), and decoded-content search (`session search`). Backs the `thatch session` CLI subcommands and the opencode-only `session_search`/`session_get` tools. Path resolution honors `OPENCODE_DB`, then the XDG default; the db opens read-only so a thatch bug cannot corrupt host history. |
 | `watchers.ts` | In-memory watcher registry and background poller for event-driven notifications (opencode-only). Watches GitHub PRs and branches via `gh api` (injected `GhRunner`), diffs against last-seen state, queues pointer-only events per session, and delivers them through a plugin-supplied callback when the session is idle. Process-lifetime state by design - no SQLite. |
 | `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 three methods: `match` (recall nudge), `predictions` (prediction auto-fire), and `behaviors` (behavior 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`), prediction nudge (`predictionNudge`), behavior nudge (`behaviorNudge`), prediction verb selection (`predictionVerb`), 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` (25 skills: fact-extractor, dedup-classifier, project-primer, 8 review specialists, review synthesizer, review context, code archaeology, review followup, review response, change walkthrough, code walkthrough, session reflection, coding-workflow, thatch-pr-description, thatch-ticket-description, thatch-split-overlarge-pr, memory-verify, knowledge-export — work on all three hosts) and `OPENCODE_ONLY_SKILLS` (1 skill: code-review coordinator — requires sub-agent support, not installed for Claude Code or Cursor). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
+| `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (fact-extractor, dedup-classifier, project-primer, the review specialists, review synthesizer, review context, code archaeology, review followup, review response, change walkthrough, code walkthrough, session reflection, coding-workflow, thatch-pr-description, thatch-ticket-description, thatch-split-overlarge-pr, memory-verify, knowledge-export — work on all three hosts) and `OPENCODE_ONLY_SKILLS` (code-review coordinator — requires sub-agent support, not installed for Claude Code or Cursor). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
 | `scoring-engine.ts` | Generic four-table scoring engine with Bayesian confidence. Shared base for prediction and behavior engines — each wraps it with table-specific names. |
 | `prediction.ts` | Thin wrapper around `ScoringEngine` with prediction-specific table names. |
 | `behavior.ts` | Thin wrapper around `ScoringEngine` with behavior-specific table names. |

package/docs/dev/features/README.md

@@ -27,8 +27,9 @@ system, see [../skills.md](../skills.md). For non-obvious invariants, see
 | [compaction-recovery.md](compaction-recovery.md) | Compaction recovery (opencode compaction hooks) |
 | [session-lifecycle.md](session-lifecycle.md) | Session lifecycle management (opencode events, child tracking) |
 | [watchers.md](watchers.md) | Event-driven notifications (in-memory registry, background poller, PR watching) |
+| [notifications.md](notifications.md) | Out-of-band notification (banner + voice) and the user config file |
 | [setup.md](setup.md) | Setup system (markers, checkSetup, auto-refresh, binary resolution) |
 | [cli.md](cli.md) | CLI (subcommands, environment variables) |
-| [database.md](database.md) | Database (schema, migrations, WAL, 11 tables) |
-| [qa-system.md](qa-system.md) | QA system (93 use cases, automatable vs live, mise tasks) |
+| [database.md](database.md) | Database (schema, migrations, WAL) |
+| [qa-system.md](qa-system.md) | QA system (automatable vs live, mise tasks) |
 | [cicd.md](cicd.md) | CI/CD (CI pipeline, OIDC publishing, release helper) |

package/docs/dev/features/behavior-engine.md

@@ -78,9 +78,11 @@ Runs in a single DB transaction:
 
 1. **Matcher dedup** — finds an existing behavior matcher above cosine 0.85,
    else creates one.
-2. **Behavior dedup** — store-wide search for a near-identical behavior
-   (cosine >= 0.85). If found, links this matcher to it via an edge rather
-   than creating a duplicate row.
+2. **Behavior dedup** — search across the target store AND global for a
+   near-identical behavior (cosine >= 0.85). If found, links this matcher to
+   it via an edge rather than creating a duplicate row. The auto-fire nudge
+   scans both stores, so the write reinforces the existing row in its home
+   store and the result echoes where it landed.
 3. **New behavior** — creates behavior + edge + provenance entry tagged
    `codify`.
 4. Returns `[codified]` for a new behavior or `[linked]` for an existing one

package/docs/dev/features/database.md

@@ -1,6 +1,6 @@
 # Database
 
-Thatch stores all data in a single SQLite file. The schema has 11 tables organized around three concerns: memory entries, the prediction engine, and the behavior engine.
+Thatch stores all data in a single SQLite file. The schema is organized around three concerns: memory entries, the prediction engine, and the behavior engine.
 
 ## Configuration
 
@@ -10,7 +10,7 @@ Thatch stores all data in a single SQLite file. The schema has 11 tables organiz
 
 ## Schema overview
 
-11 tables in three groups:
+The tables fall into three groups:
 
 | Group | Tables | Purpose |
 |-------|--------|---------|

package/docs/dev/features/memory-store.md

@@ -41,6 +41,19 @@ The "global" store always exists — it is inserted at schema init (`INSERT OR I
 - Output is a `Float32Array`.
 - `MockEmbeddingModel` is available for tests.
 - The model can be overridden via the `THATCH_MODEL` environment variable.
+- Backend: runs on onnxruntime-web's pure-JS/wasm runtime by default. Before
+  transformers initializes, `configureBackend()` pins
+  `globalThis[Symbol.for("onnxruntime")]` to onnxruntime-web, so no
+  onnxruntime-node NAPI wrap finalizers exist to panic Bun at process
+  teardown (oven-sh/bun#34664). `THATCH_EMBEDDING_BACKEND=native` opts back
+  into onnxruntime-node. Wasm runs single-threaded and uses
+  `device: "auto"` with an explicit `wasm` execution provider (the override
+  branch leaves transformers' device allowlist empty, so named devices throw).
+- Native-memory hygiene: each embed copies the vector out of the output
+  tensor, then disposes the tensor; after 10 idle minutes the pipeline's
+  native sessions are released (an embed lazily re-loads). The plugin's
+  `dispose` hook releases them at shutdown. All release paths are
+  best-effort and never throw.
 
 ### Write path (memory_remember)
 

package/docs/dev/features/multi-host.md

@@ -187,7 +187,7 @@ For the full parity matrix, see [../mcp-parity.md](../mcp-parity.md).
 
 ## Interactions with other features
 
-The 18 shared tools are available on all hosts via the single source of truth
+The shared tools are available on all hosts via the single source of truth
 in `src/tool-defs.ts`; opencode-only tools (e.g. `get_session_info`) are
 filtered out by the MCP server. Individual tool behavior is documented in
 [memory-store.md](memory-store.md), [extraction.md](extraction.md),
@@ -227,7 +227,7 @@ the opencode-only skills require sub-agent dispatch or in-process hooks.
 
 ## Key invariants
 
-- All hosts share the tool definitions from `src/tool-defs.ts` (18 shared + opencode-only tools marked `opencodeOnly: true`, which the MCP server filters out). Adding a tool requires updating `TOOL_DEFS` and all three prompt functions; opencode-only tools go in the opencode prompt only.
+- All hosts share the tool definitions from `src/tool-defs.ts` (shared tools plus opencode-only tools marked `opencodeOnly: true`, which the MCP server filters out). Adding a tool requires updating `TOOL_DEFS` and all three prompt functions; opencode-only tools go in the opencode prompt only.
 - The MCP server always exposes bare names. The `mcp__thatch__` prefix is applied by the MCP client, not thatch.
 - The three system prompt variants are independent string constants in `src/prompts.ts` with no shared template. Editing shared prose in one requires mirroring in the other two, or they drift.
 - The tool list line in all three prompts must match `TOOL_DEFS` in `src/tool-defs.ts` (opencode's list includes opencode-only tools; the MCP lists exclude them). The historical failure mode: a tool is added to `TOOL_DEFS` but only two of three prompts are updated.

package/docs/dev/features/notifications.md

@@ -0,0 +1,106 @@
+# Notifications and user config
+
+Out-of-band user notification (desktop banner + spoken voice) backed by a
+hand-editable user config file. Both are plain child processes and file I/O,
+so the feature works identically on every host -- opencode, Claude Code, and
+Cursor -- with no host-specific plumbing and no new npm dependencies.
+
+## Source files
+
+| File | Role |
+|------|------|
+| `src/config.ts` | Zod section schemas, config file load/save/merge, platform defaults. |
+| `src/notify.ts` | Per-platform dispatch for banner + voice, with an injectable spawner. |
+| `src/tool-defs.ts` | `config_get`, `config_set`, `notify_user` tool definitions (shared registry, non-opencodeOnly). |
+
+## Config design
+
+The config is one JSON file at `~/.config/thatch/config.json`, placed next to
+`thatch.db` by deriving the path from `THATCH_DB_PATH` (or the XDG default the
+same way `index.ts` and `mcp.ts` derive the DB path). Tests pass an explicit
+dbPath to keep writes inside a tempdir.
+
+Key decisions:
+
+- **Sections are `z.strictObject`.** Unknown keys fail validation instead of
+  being silently stripped, so a newer-version config round-tripping through an
+  older process cannot lose data. An unparseable file is *ignored* (empty
+  config + warning), never fatal -- a broken hand edit must not take the agent
+  down.
+- **Field-level merge in `config_set`.** `mergeNotificationPrefs` is a shallow
+  spread of current + patch (with `undefined` values stripped first). The
+  tool's description and the system prompt both state the merge semantics, and
+  the setter *echoes the resulting section* so the model can verify the write
+  in the same turn. This is the guardrail against the classic
+  read-modify-write failure where a model reconstructs a document and drops
+  sibling fields.
+- **Atomic writes.** `saveConfig` writes a temp file then renames, so a crash
+  mid-write cannot leave a truncated config and concurrent readers never see a
+  partial document.
+- **No env-var overrides for notification prefs.** The config file is the
+  single source of truth; `THATCH_*` env vars remain reserved for
+  infrastructure (DB path, model, thresholds). Preferences the LLM manages
+  belong in the file the LLM manages.
+
+`notificationDefaults()` supplies the platform fallbacks shown by `config_get`
+and applied by `notify_user`: darwin pins `Zarvox` + `Submarine` (the author's
+preference); other platforms defer to their tools' defaults.
+
+## Notification dispatch
+
+`sendNotification(request, spawner)` composes one or two command steps and
+returns a result string for the tool response:
+
+- **darwin**: banner via `/usr/bin/osascript -e 'display notification ...'`
+  (title defaults to `source`, then `thatch`; sound defaults to `Submarine`),
+  voice via `/usr/bin/say -v <voice>` (absolute path -- `~/bin/say` shadows
+  the system binary on the author's machine).
+- **linux**: banner via `notify-send`; voice via `spd-say -w`, falling back to
+  `espeak` when speech-dispatcher is absent. A voice override goes straight to
+  `espeak -v` because `spd-say` has no voice flag.
+- **other platforms** (win32 included): `[unsupported]` result, nothing runs.
+  Windows support is deliberately not a goal.
+
+Details that matter:
+
+- **The spawner is a `CoreContext` extension field** (`ctx.spawner`), the same
+  pattern as `watchers` and `extractionPayloadProvider`. Tests inject a mock;
+  production falls back to `defaultSpawner` (Bun.spawn). No test ever fires a
+  real banner or speaks.
+- **Failures never throw.** Every step's exit code and stderr are captured;
+  the result string is `[notified]` when anything succeeded, `[failed]` when
+  all requested channels failed, `[skipped]` when configured `mode` is
+  `none`, `[unsupported]` on other platforms.
+- **No delivery claims.** osascript exits 0 whether or not the banner
+  displayed (focus modes silently drop it), so result text reports command
+  success only.
+- **The spoken line prefixes the `source` label** ("PLAT-280: CI is green") so
+  a user with several concurrent agent sessions knows which one spoke. The
+  tool description enforces this on the model side.
+- Speech is awaited (the tool returns when the sentence finishes) so error
+  reporting stays honest. There is no debounce; polling agents notify once at
+  the end.
+
+## Prompt surface
+
+- `systemPrompt()` and `mcpInstructions()` list the three new tools and carry
+  a short "Notifications" section: when to notify, the source-label rule, and
+  the config_get-before-config_set instruction.
+- `notify_user` is not `opencodeOnly`: it needs no host capabilities, so MCP
+  hosts get it too. Nothing was added to `src/tools.ts` or `src/index.ts`.
+
+## Tests
+
+- `tests/config.test.ts` -- path derivation, missing/invalid/strict-schema
+  handling, round-trip, atomic save leaves no temp files, merge keeps
+  siblings, darwin defaults.
+- `tests/notify.test.ts` -- command construction per platform (mock spawner
+  records argv), AppleScript escaping, partial vs total failure, unsupported
+  platform, plus tool-level tests (merge-no-wipe, echo, `mode: none` no-op,
+  configured voice honored) with `THATCH_DB_PATH` pointed at a tempdir.
+- `tests/tool-defs.test.ts` -- registry count and name list (hardcoded literals that fail loudly when the surface changes).
+
+## QA coverage
+
+`tests/qa/auto/uc-059-tool-prefixing.ts` asserts the full bare-name list; the
+three new names are in its `expected` array.