@jeffober/thatch 0.1.25 → 0.1.27

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

@@ -1,52 +0,0 @@
-# UC-020: Extraction nudge escalation and acknowledgment
-
-_Automatable: missedNudges counter + escalation tiers + extraction_done accept
-are testable with the mock client and a synthetic tool call sequence._
-
-**Preconditions**
-- thatch active in an opencode, Claude Code, or Cursor session
-- For the child-sub-agent path: opencode with
-  `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true`
-
-**Steps**
-1. Do some non-thatch tool work (read files, run commands). Do NOT write any
-   memories.
-2. Send a message. Observe the extraction nudge — polite tone (missedCount=0).
-3. Ignore the nudge. Send another message without writing a memory (missedCount=1).
-4. Repeat step 3 (missedCount=2).
-5. Repeat step 3 again (missedCount=3+).
-6. Acknowledge by calling `thatch_extraction_done` in the session.
-7. Send another message.
-
-**Expected**
-- Step 2: the nudge is polite, referencing the queued tool interactions.
-- Step 4: after 2 consecutive misses (missedCount=2), the nudge is insistent
-  (directive tone).
-- Step 5: after 3+ consecutive misses (missedCount>=3), the nudge is ALL-CAPS.
-- The buffer was NOT drained at any point during steps 2-5 — the buffer
-  persists until a memory is written or `extraction_done` is called. The nudge
-  repeats each turn with escalated tone (and the payload grows if new tool
-  activity adds entries between nudges).
-- Step 6: `thatch_extraction_done` in the parent accepts the buffer (moves it
-  to a holding area) and resets the `missedNudges` counter. The tool returns
-  `"[acknowledged]"`. Held entries drop when the extractor completes (child
-  memory write, child `extraction_done`, or child idle); if the child errors
-  or is deleted first, the entries requeue and the nudge replays.
-- Step 7: no extraction nudge appears (buffer is accepted). If the user prompt
-  semantically matches existing memories, a recall nudge may appear instead.
-- Alternative drain path (opencode direct extraction): when the parent session
-  goes idle with pending tool interactions, the plugin calls
-  `triggerExtraction` — creates a child session via the SDK client and prompts
-  it directly. The `extracting` set suppresses the nudge in `chat.message`
-  while the child runs. The child writes memories via
-  `thatch_memory_remember`, which drains the parent's snapshot entries via
-  `consumeSnapshot`. When the child goes idle, the snapshot is drained
-  (covering no-save runs), the child session is deleted, and a toast fires
-  with the metrics. This path bypasses the nudge-and-acknowledge cycle
-  entirely — no `missedNudges` counter, no escalation. The nudge path is
-  fallback only (when `triggerExtraction` throws).
-- Alternative drain path (agent-initiated): if a child sub-agent (dispatched
-  via the `task` tool in the fallback nudge path) writes a memory via
-  `thatch_memory_remember`, the parent's buffer is also drained via the
-  `childToParent` Map — the `missedNudges` counter resets for the parent
-  session.

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

@@ -1,21 +0,0 @@
-# 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

@@ -1,19 +0,0 @@
-# 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

@@ -1,23 +0,0 @@
-# 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

@@ -1,20 +0,0 @@
-# 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)._