@jeffober/thatch 0.1.18 → 0.1.20

package/docs/in-progress/prediction-engine.md

@@ -0,0 +1,404 @@
+# Prediction engine (in progress)
+
+> **Status: implementation complete across both host paths.** The
+> schema, tools, auto-fire (opencode), sideband prediction fire (MCP),
+> prompt instructions, and tests are shipped and passing the quality
+> gate. The feature is ready for field testing. This doc is the live
+> ledger; when the work closes, graduate durable parts into a permanent
+> `docs/dev/prediction-engine.md` and retire this file.
+
+## Purpose
+
+A **user decision model** that learns the user's preferences for
+judgment calls the coding agent faces every session: scope (how much to
+do), appropriateness (is this the right thing), methodology (the right
+way). The agent gets a "guess what the user would want in this
+situation" system -- inspired by nak's samskara predictive model, but
+different mechanism and domain.
+
+The delta over flat thatch memory is three things flat memory cannot do:
+
+1. **Graded confidence** -- memory is binary (stored or not).
+   Predictions have a Bayesian posterior that is reinforced or weakened
+   by user feedback. This enables ambiguity-surfacing: when confidence
+   is thin or predictions conflict, the agent asks the user instead of
+   guessing.
+2. **Context-disambiguation** -- matchers separate "when" from "what."
+   The same topic (tech debt in a PR) can produce opposite predictions
+   in different situations (flaky test blocking CI = fix it; unrelated
+   to change = skip it). Flat memory encodes this in prose the LLM must
+   re-reason about every time; the prediction engine encodes it as
+   structure.
+3. **Agent-driven feedback loop** -- the LLM itself decides to
+   strengthen or weaken a prediction based on user feedback, creating a
+   loop that flat memory lacks.
+
+## Design decisions (settled)
+
+These came out of design discussion with Jeff, July 2026. They are
+constraints, not open questions.
+
+1. **Auto-fire at chat.message.** The hook already embeds the user's
+   text for the recall nudge. The prediction fire shares that embedding
+   and does a second cosine search against the matchers table. When
+   matchers clear a relevance floor, scored predictions are injected as
+   a synthetic nudge part. No matchers fire = nothing injected (zero
+   tokens, zero latency). No "if appropriate" hedging -- the block's
+   presence is the appropriateness signal.
+
+2. **Tool-based update, agent-driven.** No local LLM classifier. Prompt
+   instructions tell the agent: when the user corrects you, answers a
+   question, or provides a clear signal, use prediction_update to
+   create/reinforce/weaken a prediction. The LLM decides with
+   appropriately nuanced prompt instructions; the tool is the trusted
+   boundary that handles embedding, dedup, and confidence math.
+
+3. **Statistical model query, not AI.** The query (embed + cosine +
+   weighted edges) is mechanical -- same as thatch_memory_recall but
+   against different tables. No model call. The agent can also call
+   prediction_query explicitly when it wants to check the model before a
+   judgment call.
+
+4. **No local LLM.** Considered and declined. The host LLM is already
+   reading the message and classifying "was this a correction?" as part
+   of understanding it. Adding a second classifier pays twice for the
+   same answer. The cost of not having a classifier is wasted nudge text
+   on turns with no signal -- not wasted model calls.
+
+5. **Descriptive context, not directive.** The injected block reads
+   "[0.72 conf, 4 tests] When X: you tend to Y" -- same shape as
+   samskara's compound summary. The system prompt instructions govern
+   how to act on it (follow strong silently, surface weak/competing,
+   update on user response). No "if appropriate" or "consider" hedging
+   in the injection itself.
+
+6. **Confidence mirrors samskara health.** A Bayesian posterior with
+   population-prior shrinkage: `confidence = (confirm + k*p0) /
+   (confirm + disconfirm + k)`. No wall-clock decay -- relevance-gated,
+   like samskara. Being tested (user gives feedback) is what moves
+   confidence. Untested predictions stay at p0.
+
+7. **LLM is the conflict detector.** The auto-fire returns all
+   predictions from matching matchers, not just the top one. The LLM
+   reads competing predictions and decides whether they conflict. No
+   mechanical conflict heuristic -- the LLM is better at semantic
+   conflict detection than any rule.
+
+## The normative asymmetry (carried from samskara)
+
+Samskara's intents doc identifies a normative asymmetry: the descriptive
+layer (samskara predictions) is ethically free to surface, but the
+normative layer (intents -- "what the model is working toward") carries
+weight because it shapes behavior. The prediction engine is descriptive
+("you tend to prefer X"), not normative ("I'm working toward X with
+you"). It reads user behavior, it does not pursue an agenda. The
+firewall from samskara's efficacy model carries over: the model that
+uses predictions cannot grade its own predictions -- the user's
+feedback is the only signal that moves confidence.
+
+## Data model
+
+Four new tables in the same SQLite DB, same conventions as the existing
+`entries`/`dedup_pairs` tables (idempotent CREATE TABLE IF NOT EXISTS,
+BLOB embeddings, store column, crypto.randomUUID PKs).
+
+### `prediction_matchers`
+
+Context patterns describing situations. The "when."
+
+- `id TEXT PRIMARY KEY` (crypto.randomUUID).
+- `store TEXT NOT NULL`.
+- `description TEXT NOT NULL` -- "reviewing a PR with pre-existing tech
+  debt."
+- `embedding BLOB` -- 384-dim Float32Array, passageEmbed (no query
+  prefix; matchers are passages, not queries).
+- `model TEXT`.
+- `created_at`, `updated_at` -- ISO timestamps.
+
+### `predictions`
+
+User preference statements. The "what."
+
+- `id TEXT PRIMARY KEY`.
+- `store TEXT NOT NULL`.
+- `statement TEXT NOT NULL` -- "skip it unless it's blocking this
+  change."
+- `rationale TEXT` -- why this prediction exists (inspector context).
+- `embedding BLOB` -- for dedup at creation time.
+- `model TEXT`.
+- `confidence REAL NOT NULL DEFAULT 0.5` -- Bayesian posterior [0,1].
+- `confirm_count REAL NOT NULL DEFAULT 0` -- fractional (soft signals
+  are sub-unit).
+- `disconfirm_count REAL NOT NULL DEFAULT 0` -- same.
+- `created_at`, `updated_at`.
+
+### `prediction_edges`
+
+Weighted matcher-to-prediction links. The "context-dependence."
+
+- `matcher_id TEXT NOT NULL` (FK to prediction_matchers, CASCADE).
+- `prediction_id TEXT NOT NULL` (FK to predictions, CASCADE).
+- `weight REAL NOT NULL DEFAULT 1.0`.
+- `created_at`.
+- `PRIMARY KEY (matcher_id, prediction_id)`.
+
+### `prediction_provenance`
+
+Audit trail. Gives the inspector context and the agent "plenty of
+context" for nuance.
+
+- `id TEXT PRIMARY KEY`.
+- `prediction_id TEXT NOT NULL` (FK to predictions, CASCADE).
+- `signal TEXT NOT NULL` -- 'confirm' | 'disconfirm' | 'soft' |
+  'create'.
+- `detail TEXT` -- what the user said or did.
+- `created_at`.
+
+## Confidence model
+
+Mirrors samskara's health posterior with population-prior shrinkage.
+
+```
+confidence = (confirm_count + k * p0) / (confirm_count + disconfirm_count + k)
+
+k      = 5     (prior strength, pseudo-count)
+p0     = 0.5   (population baseline; make population-derived later)
+W_SOFT = 0.25  (soft miss weight, same as samskara)
+```
+
+- `confirm` signal: confirm_count += 1.
+- `disconfirm` signal: disconfirm_count += 1.
+- `soft` signal: disconfirm_count += W_SOFT (0.25).
+- `create` signal: no confidence adjustment, just seeds at p0.
+- No wall-clock decay. Relevance-gated: being tested (user gives
+  feedback) is what moves confidence. Untested = stays at p0.
+- confirm_count / disconfirm_count are REAL (fractional). An integer
+  column would truncate soft signals to 0 (samskara's bug).
+- p0 starts at 0.5 for v1. Later: `populationP0(store)` = sum(confirm) /
+  sum(confirm + disconfirm), with a 0.5 fallback under 20 evidence.
+
+## Scoring at query time
+
+```
+score = cosine(user_text, matcher.embedding) * edge.weight * prediction.confidence
+```
+
+The auto-fire returns all predictions from matching matchers (not just
+the top scoring one), so the LLM can read conflicts. The score is for
+ranking and display, not for a mechanical "follow if above X" gate --
+the LLM decides whether to follow, surface, or ignore, informed by the
+confidence and evidence count shown alongside.
+
+## Ambiguity-surfacing (the killer feature)
+
+- **Strong prediction** (high confidence, sufficient evidence) -> agent
+  follows silently, does not interrupt.
+- **No prediction** -> agent asks the user (same as today).
+- **Ambiguous or competing predictions** -> agent surfaces naturally:
+  "I think you usually prefer X here, but I'm not sure -- what do you
+  want?"
+- **User responds to a surfaced prediction** -> agent calls
+  prediction_update to reinforce or weaken.
+
+Value = fewer interruptions, not more. High-confidence predictions
+suppress questions the agent would otherwise ask.
+
+## Tool surface
+
+Four tools, following the existing ToolDef pattern in tool-defs.ts.
+
+### `prediction_query`
+
+Mechanical search. Returns scored predictions with matcher
+description, confidence, and evidence count.
+
+Args: `context` (string), `store` (optional).
+
+### `prediction_update`
+
+The trusted boundary. The agent says "here's the situation, here's the
+preference, here's what happened." The tool handles: embed matcher,
+find/create by cosine dedup, embed prediction, find/create by cosine
+dedup, adjust confidence, record provenance.
+
+Args: `matcher` (string), `prediction` (string), `signal` (confirm |
+disconfirm | soft | create), `rationale` (string), `store` (optional).
+
+### `prediction_list`
+
+Inspector. Lists all predictions with confidence, evidence, matchers,
+and rationale.
+
+Args: `store` (optional).
+
+## Auto-fire in chat.message hook
+
+Slots into the existing recall-nudge path in index.ts, sharing the
+embedding call. After the recall nudge block, before the catch:
+
+```
+embedding = await model.queryEmbed(promptText)  // already computed
+
+// recall nudge (existing)
+results = db.search([repo, "global"], embedding, { limit: 5 })
+if matches >= RECALL_THRESHOLD -> inject recallNudge
+
+// prediction fire (new)
+predItems = db.scorePredictionNudge([repo, "global"], embedding, PREDICTION_THRESHOLD)
+if predItems.length > 0:
+    output.parts.push(predictionNudge(predItems))  // synthetic: true
+```
+
+One more cosine scan against a separate table. Same brute-force
+pattern, same cost profile. No extra embedding call.
+
+## System prompt instructions
+
+New section in all three prompt variants (systemPrompt,
+claudeInstructions, cursorInstructions), after "Before Responding."
+
+New tools registered in the tool list line:
+`thatch_prediction_query`, `thatch_prediction_update`,
+`thatch_prediction_list` (opencode); bare names for MCP.
+
+The injected block format:
+
+```
+## User decision model
+- [0.72 conf, 4 tests] When reviewing a PR with pre-existing tech debt: you tend to skip it unless it's blocking the change
+- [0.61 conf, 2 tests] When the tech debt is a flaky test: you've preferred fixing it
+```
+
+Prompt instructions:
+- Follow strong predictions silently.
+- Surface weak or competing predictions to the user naturally.
+- When the user responds to a surfaced prediction, use
+  prediction_update to reinforce or weaken.
+- When the user corrects you, answers a question, or provides a clear
+  signal, use prediction_query then prediction_update.
+
+## Constants
+
+```
+PREDICTION_THRESHOLD   = 0.45  // lower than RECALL_THRESHOLD (0.55)
+MATCHER_DEDUP_COSINE   = 0.85  // near-duplicate check at creation
+PREDICTION_DEDUP_COSINE = 0.85
+P0                     = 0.5   // prior (population-derived later)
+K                      = 5     // prior strength
+W_SOFT                 = 0.25  // soft miss weight
+```
+
+## Hook integration
+
+The `tool.execute.after` hook (index.ts) already skips
+`thatch_*`-prefixed tools from the extraction buffer.
+`thatch_prediction_*` is caught by that check -- no special handling
+needed. MCP path same: `mcp__thatch__prediction_*` caught by the
+`mcp__thatch__*` filter in extract-queue.ts.
+
+Prediction calls do NOT drain the extraction buffer -- they are a
+separate system. The agent may do both in the same turn (save a memory
+AND update a prediction).
+
+## Build status
+
+Landed so far:
+
+1. DB schema + methods (db.ts) -- four new tables (prediction_matchers,
+   predictions, prediction_edges, prediction_provenance) in #initSchema,
+   plus findMatchers, scorePredictions, findNearestMatcher,
+   findNearestPrediction, createMatcher, createPrediction, createEdge,
+   adjustConfidence, addProvenance, listPredictions, populationP0,
+   getPrediction, getProvenance, deletePrediction, scorePredictionNudge.
+   Confidence uses Bayesian posterior with k=5, p0=0.5, W_SOFT=0.25.
+2. Tool definitions (tool-defs.ts) -- prediction_query,
+   prediction_update, prediction_list, prediction_delete. Added to
+   TOOL_DEFS array (9 -> 13).
+3. Auto-fire (index.ts) -- prediction fire in chat.message hook,
+   sharing embedding with recall nudge. Prediction blocks injected
+   when matchers clear PREDICTION_THRESHOLD (0.45). predictionNudge
+   formatter in prompts.ts.
+4. System prompt (prompts.ts) -- "User Decision Model" section in all
+   three variants (systemPrompt, claudeInstructions,
+   cursorInstructions). New tools in all three tool lists.
+5. Tools wiring (tools.ts + mcp.ts) -- automatic via TOOL_DEFS
+   iteration. No manual changes needed.
+6. Tests -- tests/prediction.test.ts (schema, confidence math, dedup,
+   scoring, provenance, listPredictions, populationP0). Updated
+   tool-defs.test.ts and plugin.test.ts tool count assertions (9 -> 13).
+7. MCP path (sideband.ts + bin/thatch) -- the sideband server now
+   handles `method: "predictions"` alongside `method: "match"`, so
+   the warm MCP server can query matchers and score predictions for
+   one-shot hook processes. The `flush-tools` CLI subcommand (already
+   wired into UserPromptSubmit hooks for Claude Code and Cursor) now
+   fires predictions alongside the recall nudge in its tier 2 block,
+   sharing one sideband round-trip via `Promise.all`. A standalone
+   `flush-predictions` subcommand is also available for testing.
+   No new hook installation needed -- the existing `flush-tools` hook
+   covers it.
+
+Future enhancements:
+
+1. **p0 population derivation** -- v1 uses flat 0.5. Once enough
+   predictions accumulate, switch to population-derived p0 per store.
+2. **Auto-fire block separation** -- separate synthetic part from the
+   recall nudge, or combined? Starting with separate (simpler).
+3. **Inspector UI** -- `thatch prediction list` CLI subcommand for
+   terminal inspection. No Svelte UI (thatch has no UI).
+4. **Score formula tuning** -- v1 is `cosine * weight * confidence`.
+   If confidence dominates (high confidence on weak cosine swamps low
+   confidence on strong cosine), add samskara's `cosine^1.3` power.
+   Start simple; let data drive.
+5. **Edge weight tuning** -- v1 is flat 1.0 for all edges. The weight
+   encodes context-dependence but we have no signal to set it yet.
+   Could later set it from the matcher's cosine at creation time
+   (stronger match = higher weight) or from co-occurrence statistics.
+
+## Interactions
+
+- **Memory** (existing) -- distinct system. Memory is facts the
+  agent/user committed; predictions are learned preferences with graded
+  confidence. No data flows between them. The agent may write a memory
+  about a preference AND update a prediction about the same preference;
+  the memory is the "what" (durable fact), the prediction is the "how
+  confident" (graded, updated by feedback).
+- **Extraction pipeline** (existing) -- prediction tools are excluded
+  from the extraction buffer by the thatch_* prefix filter. No
+  feedback loop.
+- **Recall nudge** (existing) -- the prediction fire shares the
+  embedding call and runs in the same chat.message hook path (opencode)
+  or the same sideband round-trip (MCP). The two nudges are separate
+  synthetic parts (opencode) or combined in one output block (MCP);
+  either can be absent.
+- **Sideband** (existing, MCP path) -- the sideband server now handles
+  a `predictions` method alongside `match`. The `flush-tools` CLI
+  subcommand queries both in parallel via `Promise.all`.
+- **Compaction guard** (existing) -- the compacting set check at the
+  top of chat.message suppresses ALL nudges, including prediction fire.
+  No change needed.
+
+## Gotchas
+
+- **Matcher embeddings use passageEmbed, not queryEmbed.** Matchers
+  are passages (stored content matched against), not queries. The query
+  prefix applies to the user's text at fire time. Same pattern as
+  remember() which uses passageEmbed for content.
+- **confirm_count / disconfirm_count MUST be REAL.** An integer column
+  truncates soft signals (W_SOFT = 0.25) to 0 and freezes confidence at
+  p0. This is the same bug samskara had.
+- **Cold start is free.** Empty matchers table, findMatchers returns
+  [], nothing injected. The feature is inert until the first
+  prediction_update call. No migration, no config.
+- **Prediction calls do not drain the extraction buffer.** They are a
+  separate system. The agent may do both in the same turn.
+
+## Reference
+
+- nak samskara: `docs/dev/samskara.md` in the nak repo (the predictive
+  model of the user this feature is inspired by).
+- nak intents: `docs/dev/in-progress/intents.md` in the nak repo (the
+  normative layer atop samskara; the C efficacy model and firewall
+  between employment and efficacy informed the confidence model here).
+- thatch memory: this doc's "Interactions" section.
+- thatch extraction pipeline: `docs/dev/README.md` + `docs/dev/mcp-parity.md`.
+- thatch hook surface: `docs/dev/setup-and-hooks.md`, `docs/dev/gotchas.md`.

package/docs/qa/README.md

@@ -91,7 +91,7 @@ correctness on `README.md` and `docs/` excluding `docs/plans/`; see
 
 ### `tests/plugin.test.ts`
 
-- `server` export shape: all nine tools, every hook present, tools carry
+- `server` export shape: all thirteen tools, every hook present, tools carry
   description/args/execute
 - System transform and compaction hooks append their text
 - `tool.execute.after` → `chat.message` extraction round-trip: nudge carries
@@ -101,6 +101,38 @@ correctness on `README.md` and `docs/` excluding `docs/plans/`; see
 - `event` handler: calls `client.session.prompt` on `session.created` with
   correct session ID and nudge text; ignores non-`session.created` events
 - `sessionStartReminder`: includes store name and recall instructions
+- Recall nudge via `chat.message`: surfaces when prompt matches a stored
+  memory, no nudge for unrelated or short prompts, extraction priority
+- Prediction auto-fire via `chat.message`: surfaces when prompt matches a
+  stored matcher, no nudge for unrelated prompts, prediction and recall
+  nudges fire independently as separate synthetic parts
+
+### `tests/tool-defs.test.ts`
+
+- Tool count (13) and name list
+- Zod schema validation for each tool's args
+- Execute functions: `memory_remember` save/duplicate/overwrite/archived,
+  `memory_recall` default/empty/archived, `memory_list`/`show`/`forget`,
+  `store_list`, `find_duplicates` clean store
+- Prediction execute functions: `prediction_update` create/confirm/disconfirm/
+  create-on-existing (dedup links without disconfirming), `prediction_query`
+  matching/unrelated, `prediction_list` with provenance, `prediction_delete`
+  found/not-found
+
+### `tests/prediction.test.ts`
+
+- Schema: tables exist, `populationP0` fallback on empty store
+- Matcher creation and lookup: `findMatchers` ranking, `findNearestMatcher`
+  threshold/dedup
+- Prediction creation: `createPrediction` seeds at p0, `adjustConfidence`
+  confirm/disconfirm/soft/multiple, non-existent ID no-op
+- Edges and scoring: `createEdge` links, `scorePredictions` empty/dedup/
+  weight-preservation, `scorePredictionNudge` threshold filtering + dedup
+- `findNearestPrediction`: store-wide search, threshold, cross-matcher
+- Provenance: `addProvenance` + `getProvenance` read-back, `deletePrediction`
+  cascade to edges and provenance
+- `listPredictions`: sorted by confidence, matchers included
+- `populationP0`: under-20 fallback, population hit rate with sufficient evidence
 
 ### `tests/hygiene.test.ts`
 

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

@@ -29,6 +29,10 @@ file/IPC/CLI contracts ready to graduate into `bun:test` integration tests.
 | [UC-018](UC-018-mcp-startup-setup-detection.md) | MCP startup detects missing/broken setup instructions and warns the agent |
 | [UC-019](UC-019-archived-memory-lifecycle.md) | Archive, search exclusion, update guard, unarchive |
 | [UC-020](UC-020-extraction-escalation.md) | Nudge escalation (polite → insistent → ALL-CAPS), buffer persistence, `extraction_done` drain |
+| [UC-021](UC-021-prediction-autofire.md) | Prediction auto-fire: matcher scores prompt, prediction nudge injected alongside recall |
+| [UC-022](UC-022-prediction-dedup.md) | Prediction create-on-existing: dedup finds match, links edge without disconfirming |
+| [UC-023](UC-023-prediction-confidence-model.md) | Bayesian confidence math: create, confirm, soft (weak disconfirm), disconfirm signals |
+| [UC-024](UC-024-prediction-delete.md) | Prediction delete with cascade, provenance inspection, not-found handling |
 
 ## Template
 

package/docs/qa/use-cases/UC-021-prediction-autofire.md

@@ -0,0 +1,21 @@
+# UC-021: Prediction auto-fire
+
+**Preconditions**
+- An opencode session (or Claude Code / Cursor with the MCP server running and sideband socket live)
+- A clean DB (no existing matchers or predictions)
+
+**Steps**
+
+1. Send a prompt expressing a preference, e.g. "I prefer to handle error cases before happy paths. Record this preference."
+2. Observe the agent calls `prediction_update` with `signal: "create"`.
+3. Start a new session (or send a fresh prompt in the same session).
+4. Send a prompt matching the matcher context, e.g. "Write a function to parse a JSON config file."
+5. Send an unrelated prompt, e.g. "What's the weather like?"
+
+**Expected**
+- Step 2: Agent calls `thatch_prediction_update` with a matcher describing the context ("writing functions", "error handling") and a prediction describing the preference ("handle errors before happy paths"). The tool returns `[created]` and seeds confidence at 0.50 with 0 evidence.
+- Step 4: The `chat.message` hook embeds the prompt, finds matchers above the 0.45 threshold, scores linked predictions, and injects a `[thatch] User decision model` nudge. The 0-evidence prediction uses "you may prefer" (not "you tend to"). The agent may follow the prediction, surface it, or ignore it.
+- Step 5: No prediction nudge (cosine below threshold). No extra synthetic parts.
+- Claude Code / Cursor: The `flush-tools` hook fires predictions alongside the recall nudge via the sideband socket. The `flush-predictions` CLI subcommand provides standalone prediction-only output.
+
+_Automatable: yes — the auto-fire path is tested in `plugin.test.ts` (prediction nudge via chat.message, independent firing, no-match suppression). The end-to-end "agent acts on prediction" flow is manual._

package/docs/qa/use-cases/UC-022-prediction-dedup.md

@@ -0,0 +1,19 @@
+# UC-022: Prediction create-on-existing (dedup + link)
+
+**Preconditions**
+- An opencode session with at least one existing prediction (from UC-021 or seeded directly)
+- The existing prediction's matcher context is semantically similar to a new observation
+
+**Steps**
+
+1. Seed a prediction: `prediction_update(matcher="reviewing a PR", prediction="go through findings one at a time using a todo list", signal="create")`.
+2. In the same or a new session, call `prediction_update(matcher="code review session", prediction="go through findings one at a time using a todo list", signal="create")`.
+3. Call `prediction_update(matcher="code review session", prediction="go through findings one at a time using a todo list", signal="confirm")`.
+4. Call `prediction_list` to inspect the model.
+
+**Expected**
+- Step 2: `findNearestPrediction` finds the existing prediction (cosine > 0.85). The tool returns `[linked]` (not `[created]`). The new matcher is linked via an edge. No duplicate prediction is created. Confidence is unchanged (create is confidence-neutral).
+- Step 3: Same prediction is found. The matcher edge already exists (ON CONFLICT DO NOTHING). Confidence is adjusted upward by the confirm signal. Returns `[confirm]` with updated confidence.
+- Step 4: `prediction_list` shows one prediction with two matchers ("reviewing a PR" and "code review session"), confidence reflecting one confirm, and provenance entries for both the create and confirm signals.
+
+_Automatable: yes — the create-on-existing path is tested in `tool-defs.test.ts` (prediction_update create on existing prediction links without disconfirming). The dedup + edge + confidence behavior is verified with assertions on the return value and prediction_list output._

package/docs/qa/use-cases/UC-023-prediction-confidence-model.md

@@ -0,0 +1,23 @@
+# UC-023: Prediction confidence and signal model
+
+**Preconditions**
+- An opencode or Claude Code / Cursor session with the prediction model seeded
+
+**Steps**
+
+1. `prediction_update(matcher="X", prediction="Y", signal="create")` — seeds at p0 (0.50, 0 evidence).
+2. `prediction_update(matcher="X", prediction="Y", signal="confirm")` — user confirmed.
+3. `prediction_update(matcher="X", prediction="Y", signal="soft")` — user partially disagreed.
+4. `prediction_update(matcher="X", prediction="Y", signal="disconfirm")` — user pushed back.
+5. `prediction_list` to inspect confidence and evidence counts.
+6. `prediction_query(context="X")` to query the model.
+
+**Expected**
+- Step 1: Returns `[created]`, confidence=0.50, counts (0/0).
+- Step 2: Returns `[confirm]`, confidence > 0.50. Formula: (1 + 5*0.5) / (1 + 0 + 5) = 0.583. Counts (1/0).
+- Step 3: Returns `[soft]`, confidence drops slightly. Soft adds 0.25 to disconfirm_count. Formula: (1 + 2.5) / (1 + 0.25 + 5) = 0.571. Counts (1/0.25).
+- Step 4: Returns `[disconfirm]`, confidence drops further. Formula: (1 + 2.5) / (1 + 1.25 + 5) = 0.524. Counts (1/1.25).
+- Step 5: `prediction_list` shows the prediction with accumulated provenance entries (create, confirm, soft, disconfirm) sorted newest-first.
+- Step 6: `prediction_query` returns the prediction with the current confidence and evidence count. Uses "you may prefer" for 0-evidence and "you tend to" for predictions with evidence. Threshold (0.45) filters out matchers below the relevance floor.
+
+_Automatable: yes — the confidence math and signal mapping are tested in `prediction.test.ts` (adjustConfidence confirm/disconfirm/soft/multiple) and `tool-defs.test.ts` (prediction_update confirm applies signal immediately)._

package/docs/qa/use-cases/UC-024-prediction-delete.md

@@ -0,0 +1,20 @@
+# UC-024: Prediction delete and provenance inspection
+
+**Preconditions**
+- An opencode or Claude Code / Cursor session with predictions in the model
+
+**Steps**
+
+1. Seed two predictions in the same store.
+2. `prediction_list` to see both predictions with matchers, confidence, and provenance.
+3. `prediction_delete(statement="first prediction text")` to remove one.
+4. `prediction_list` to verify only one prediction remains.
+5. `prediction_delete(statement="nonexistent prediction")` to test not-found handling.
+
+**Expected**
+- Step 2: Both predictions listed with confidence, evidence count, matchers (with weights), and provenance entries (signal type, detail, date).
+- Step 3: Returns `[deleted]` with the matched prediction's statement. Matching is semantic (cosine >= 0.85), not exact string match. Edges and provenance are cascade-deleted via FK ON DELETE CASCADE.
+- Step 4: Only the remaining prediction is listed. No orphaned edges or provenance entries.
+- Step 5: Returns "No prediction matching ... found" for a statement with no semantic match above threshold.
+
+_Automatable: yes — prediction_delete is tested in `tool-defs.test.ts` (found and not-found cases), and deletePrediction cascade is tested in `prediction.test.ts` (cascade to edges and provenance, non-existent ID)._

package/docs/user/README.md

@@ -174,7 +174,7 @@ Six specialist review lenses, each a self-contained static-analysis pass:
 | `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth wall breaks, em dashes, hedging, filler. |
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of the code's behavior? |
 | `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
-| `thatch-review-synthesizer` | Verifies and synthesizes findings from multiple specialists into a single deduplicated, severity-grouped report. |
+| `thatch-review-synthesizer` | Verifies and synthesizes findings from multiple specialists into a report that starts with workflow changes, then deduplicated severity-grouped findings. |
 | `thatch-review-context` | Gathers project context (PR descriptions, git archaeology, ticket references, memory) before a review. Prevents false positives about intentionally deferred work. |
 | `thatch-workflow-research` | Researches code workflows and features affected by a change or planned change. Reads code flows, comments, git history, and produces a guide for reviewers or planners. |
 | `thatch-change-walkthrough` | Explains a change to the user as a teaching walkthrough: researches each affected workflow at the merge-base, teaches current behavior, then overlays the modifications with file:line citations. |
@@ -184,15 +184,15 @@ Six specialist review lenses, each a self-contained static-analysis pass:
 
 | Skill | Purpose |
 |-------|---------|
-| `pr-description` | Drafts PR descriptions using instructional-design scaffolding (SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES) with bold and italic emphasis for scanning. |
-| `ticket-description` | Drafts ticket or issue descriptions (Linear or Jira) using instructional-design scaffolding with bold and italic emphasis for scanning. |
+| `pr-description` | Drafts PR descriptions with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, project-context research, clarity checks, and bold/italic emphasis for scanning. |
+| `ticket-description` | Drafts ticket or issue descriptions (Linear or Jira) with clear sections, project-context research, clarity checks, and bold/italic emphasis for scanning. |
 | `split-overlarge-pr` | Splits already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main. |
 
 ### opencode-only skills
 
 | Skill | Purpose |
 |-------|---------|
-| `thatch-code-review` | Multi-agent review coordinator. Dispatches parallel sub-agents for triage, decomposition, specialist fan-out, and synthesis. Not available in Claude Code (requires sub-agent support). |
+| `thatch-code-review` | Multi-agent review coordinator. Dispatches parallel sub-agents for triage, decomposition, specialist fan-out, and synthesis with a workflow-change preface. Not available in Claude Code (requires sub-agent support). |
 
 ### Host availability
 
@@ -222,7 +222,8 @@ Load thatch-code-review and review branch feature-x.
 ```
 
 The coordinator will triage the change, dispatch parallel sub-agents (one per
-specialist lens), and synthesize a final report.
+specialist lens), and synthesize a final report. The report starts with the
+workflow-level changes so the findings have context.
 
 For a **full review on Claude Code** (or without the coordinator), run each
 specialist in sequence, then synthesize:

package/package.json

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