@jeffober/thatch 0.1.25 → 0.1.27

package/docs/plans/prediction-consolidation.md

@@ -0,0 +1,361 @@
+# Prediction Consolidation and Compound Predictions
+
+## Synopsis
+
+Post-processing layers for the prediction engine: fire tracking, co-fire-based
+consolidation (dedup), and compound (tier-2) predictions minted from
+co-firing constellations of existing predictions. Uses nudge-driven detection
+and the existing edge model for fire behavior. No cron, no separate backend.
+
+## Background
+
+The prediction engine ships matchers, predictions, edges, and provenance. It
+auto-fires at chat.message and updates via agent tool calls. What it lacks
+relative to nak's samskara system:
+
+- **Fire tracking** -- no record of which predictions fire together on the same
+  turn. This is the prerequisite for both co-fire dedup and compound detection.
+- **Consolidation** -- no corpus-level dedup pass. Write-time dedup
+  (findNearestPrediction at 0.85) catches near-identical statements at creation,
+  but behavioral duplicates (same preference, different wording) accumulate.
+- **Compound predictions** -- no mechanism to mint a higher-order prediction
+  from a constellation of predictions that reliably co-fire. Nak's tier-2
+  samskaras fire at 77% genuine-engagement vs tier-1's 21% because compound
+  claims match broader contexts.
+
+Reference: `docs/dev/samskara.md` in nak (1896 lines), studied July/August 2026.
+The architectural difference between the two systems is load-bearing for this
+plan (see Key Insight below).
+
+## Key Insight: the edge model carries fire behavior
+
+Nak matches on `prediction_embedding` (the claim text). A tier-2 fires because
+its compound claim text cosine-matches the user message. This is why nak needs
+fire tracking, cohort_ids, lift computation, and a separate tier-2 detection
+RPC -- the compound only fires if its own embedding matches.
+
+Thatch matches on `matcher_embedding` (the context description) and follows
+edges. A compound prediction with edges to its children's matchers fires
+automatically whenever any child matcher fires. The compound inherits the fire
+coverage of all its children. This is "firing in tandem" for free, via the
+existing edge model.
+
+The co-fire data is for *deciding what to compound*, not for *making the
+compound fire*. This means:
+
+1. A compound needs no tier column, no special scoring path, no fire-path
+   changes. It is a prediction with multiple matcher edges.
+2. The existing `scorePredictions` already follows all edges and deduplicates by
+   prediction_id. A compound scores through its children's edges.
+3. The existing `prediction_update` tool already finds existing matchers by
+   cosine (0.85 threshold) and creates edges. Calling it multiple times with
+   different matcher texts but the same prediction statement creates a
+   multi-matcher compound naturally.
+
+A v1 could even skip fire tracking and let the agent create compounds based on
+semantic similarity between existing predictions (cosine on prediction
+embeddings). Fire tracking makes detection data-driven instead of
+embedding-driven, but the edge model carries the fire behavior either way.
+
+## Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| No tier column | A compound is a prediction with multiple matcher edges. The edge model already handles multi-matcher predictions. Adding a tier column would special-case scoring and fire paths for no benefit. |
+| Fire tracking as prerequisite | Co-fire data drives both consolidation and compound detection. Without it, detection is limited to semantic similarity. With it, detection is behavioral -- based on what actually fires together. |
+| Nudge-driven, not cron-driven | Thatch has no cron. Detection runs at session start, folded into the existing hygiene nudge. This is the same pattern as `findDuplicates` for memories. |
+| Agent is the minter | Like the existing prediction engine, the agent synthesizes compound statements via `prediction_update`. No separate LLM minter call. The nudge surfaces the candidate constellation; the agent decides whether to compound. |
+| Lift for compound detection, ratio for dedup | Nak proved this: the rarer-member ratio (`cofires / min(fires_A, fires_B)`) catches duplicates (perfectly correlated) but fails for compounds because busy-but-independent pairs still reach ratio ~0.5. Lift (`cofires * cohorts / (fires_A * fires_B)`) separates genuine co-activation from base-rate binding. |
+| Cosine band separates dedup from compound detection | Dedup operates at cosine >= 0.70 (near-duplicates). Compound detection operates at cosine in [0.30, 0.68) (related but distinct). The 0.68 top end stays below dedup's 0.70 floor so the two phases never fight over the same pair. |
+
+## Architecture
+
+### Phase 1: Fire Tracking
+
+**New table: `prediction_fires`**
+
+```sql
+CREATE TABLE IF NOT EXISTS prediction_fires (
+  id            TEXT PRIMARY KEY,
+  prediction_id TEXT NOT NULL,
+  store         TEXT NOT NULL,
+  session_id    TEXT,
+  cohort_id     TEXT NOT NULL,
+  score         REAL NOT NULL,
+  fired_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now')),
+  FOREIGN KEY (prediction_id) REFERENCES predictions(id) ON DELETE CASCADE
+);
+```
+
+`cohort_id` is a UUID generated per auto-fire invocation, shared across all
+predictions that scored above threshold in the same `scorePredictionNudge`
+call. This is the direct analog of nak's `samskara_fires.cohort_id`.
+
+**Write path:** `scorePredictionNudge` currently returns `PredictionNudgeItem[]`
+and is called from two sites (index.ts auto-fire, sideband.ts MCP path). Add a
+`recordFires` method that takes the scored predictions + a generated cohort_id
+and inserts one row per prediction. The callers generate the cohort_id before
+calling `scorePredictionNudge` and pass it through for recording.
+
+Both callers must record fires. The opencode path (index.ts) has the session_id.
+The MCP path (sideband.ts) does not have a session_id in the sideband request --
+pass null or derive from the socket connection.
+
+**New DB methods:**
+- `recordFires(cohortId, sessionId, items, store)` -- batch insert
+- `fireCount(predictionId)` -- total fires for a prediction
+- `cofireCount(predictionIdA, predictionIdB)` -- count shared cohorts
+- `totalCohorts(store)` -- distinct cohort_id count (for lift denominator)
+
+**Schema location:** `#initSchema` in db.ts, alongside existing prediction
+tables. Same conventions (uuid PK, store column, idempotent CREATE TABLE IF
+NOT EXISTS).
+
+### Phase 2: Consolidation (Co-fire Dedup)
+
+**New DB method: `findPredictionDuplicates(store, threshold)`**
+
+Two-pass, mirroring nak's `samskara_collapse_by_cofiring`:
+
+**Primary pass (behavioral):** For each pair of predictions (A, B) in the store
+where both have fire_count > 0:
+
+```
+cofires(A, B) >= 3
+cofires(A, B) / min(fires_A, fires_B) >= 0.5
+cosine(embed_A, embed_B) >= 0.70
+```
+
+The ratio normalization is the key: two predictions that always fire together
+when either fires are duplicates. Two that co-fire but also fire independently
+are adjacent-but-distinct. Cosine is a sanity floor against spurious co-fires.
+
+**Safety cap (cosine-only):** If the prediction count exceeds a target (e.g.,
+100), fall through to pure embedding-cosine greedy merge (cosine >= 0.60)
+regardless of co-fire data. This catches accumulation when the behavioral pass
+finds nothing but the pool is still growing.
+
+**Output:** A list of candidate merge pairs with {predictionA, predictionB,
+cofires, ratio, cosine, firesA, firesB}. Surfaced via the hygiene nudge, not
+auto-merged. The agent reviews and merges via prediction_delete + (optionally)
+prediction_update to fold the loser's matchers into the winner.
+
+The merge itself is agent-driven: the agent sees the candidate pair, reads both
+predictions, deletes the weaker one (or uses a future `prediction_merge` tool
+if one is added). This matches the memory dedup pattern
+(`find_duplicates` + `dedup_mark_checked`).
+
+**Integration point:** `hygiene.ts` -- add a line to `hygieneReport`:
+`N prediction duplicate pairs pending review` when candidates exist.
+
+**Nudge throttling:** Runs at session start only, same as the existing hygiene
+report. The analysis is O(n^2) over the predictions table but n is small
+(tens, not hundreds) so the cost is negligible.
+
+### Phase 3: Compound Prediction Detection
+
+**New DB method: `findCoFireConstellations(store)`**
+
+Returns candidate groups of 3-6 predictions that reliably co-fire but are
+semantically distinct (not dedup candidates).
+
+**Detection formula (lift-based, from nak):**
+
+```
+eligible(A, B) when:
+  cofires(A, B) >= p_min_cofires             -- 10
+  lift(A, B)    >= p_min_lift                 -- 2.0
+  cosine(embed_A, embed_B) >= p_cosine_lo     -- 0.30 (effectively inert)
+  cosine(embed_A, embed_B) <  p_cosine_hi     -- 0.68 (< dedup floor 0.70)
+
+  where lift(A, B) = cofires(A, B) * total_cohorts / (fires_A * fires_B)
+```
+
+Lift is observed co-fires over co-fires expected under independence. Base-rate
+binding (two busy predictions colliding because both fire often) sits at lift
+~1. Genuine co-activation runs several times chance. The `p_min_cofires = 10`
+absolute-mass guard prevents small-sample variance (a pair firing 4x that
+always co-fires scores a huge lift on 4 points).
+
+**Group growth:**
+1. Seed: the strongest-lift eligible edge.
+2. Grow: every node sharing an eligible edge with BOTH seed members (not
+   either -- co-firing with one is adjacent, not part of the constellation).
+   Strongest combined lift first. Capped at 6 members. Reject groups < 3 (a
+   2-member group is a dedup candidate, not a compound).
+3. Coverage skip: if the candidate's Jaccard overlap with any existing
+   compound's child-matchers is >= 0.60, skip to the next-strongest uncovered
+   seed. This prevents one compound on a dense region from masking every other
+   constellation.
+
+**Precondition:** At least 8 predictions with fire_count > 0 before the
+self-join runs. Avoids spending computation on a cold store.
+
+**Output:** A list of candidate constellations, each with {members:
+[{prediction_id, statement, matcher_description, cofire_weight}], lift,
+group_size}. Surfaced via the hygiene nudge.
+
+**Integration point:** `hygiene.ts` -- add: `N co-fire constellations pending
+review` when candidates exist.
+
+### Phase 4: Compound Minting (Agent-Driven)
+
+The nudge surfaces a candidate constellation. The prompt instructions tell the
+agent:
+
+1. Read the member predictions and their matchers.
+2. Synthesize a generalized statement that captures the shared behavior without
+   collapsing to any single child.
+3. Call `prediction_update` once per child matcher, using the child's matcher
+   text and the new compound statement. Each call finds the existing child
+   matcher by cosine (0.85) and creates an edge to the new compound prediction.
+
+The agent calls `prediction_update` with `signal: "create"` for each child
+matcher. The first call creates the compound prediction + an edge from the
+first child's matcher. Subsequent calls find the existing compound by
+`findNearestPrediction` (0.85 store-wide dedup) and add edges from the other
+children's matchers.
+
+This works with the existing tool surface. No new tools needed for minting.
+
+**Prompt instructions addition** (in prompts.ts, all three host variants):
+
+After the existing prediction instructions, add guidance for compounds:
+
+- When the hygiene nudge reports co-fire constellations, consider whether the
+  members share a generalizable behavior.
+- If so, synthesize a compound statement and call `prediction_update` once per
+  child matcher with the compound statement. The tool handles matcher dedup and
+  edge creation.
+- A compound should be strictly more general than any single child. If you
+  cannot generalize, do not compound.
+- The compound inherits the fire coverage of its children's matchers. It will
+  fire whenever any child matcher fires.
+
+### Phase 5: Compound Summary (Optional, Future)
+
+Nak generates a cached prose summary of top samskaras that rides every system
+prompt. Thatch could do the same: a one-paragraph summary of the strongest
+predictions, regenerated when the prediction set changes significantly.
+
+This is lower priority. The per-turn auto-fire nudge already surfaces relevant
+predictions. A compound summary would capture stable bias across every turn,
+not just when a matcher fires. Defer until the compound predictions prove
+useful in practice.
+
+## Data Flow
+
+```
+chat.message (user text)
+  → embed promptText (shared with recall nudge)
+  → scorePredictionNudge([repo, global], embedding, 0.45)
+    → findMatchers (cosine >= 0.45)
+    → scorePredictions (follow edges, dedup by prediction_id)
+    → recordFires (NEW: persist cohort with shared cohort_id)
+    → return PredictionNudgeItem[]
+  → inject prediction nudge (existing)
+
+session.created (top-level)
+  → hygieneReport
+    → findDuplicates (memories, existing)
+    → findPredictionDuplicates (NEW: co-fire dedup candidates)
+    → findCoFireConstellations (NEW: compound candidates)
+    → inject hygiene nudge with all signals
+
+Agent reads hygiene nudge
+  → reviews dedup candidates → prediction_delete / merge
+  → reviews constellation candidates → prediction_update (compound minting)
+```
+
+## Dependencies
+
+No new runtime dependencies. All detection is SQLite queries + JS cosine
+computation, same as existing prediction methods.
+
+**Schema:** One new table (`prediction_fires`), added to `#initSchema` in
+db.ts.
+
+**Code changes by file:**
+- `src/db.ts` -- new table, 4-5 new methods (recordFires, fireCount,
+  cofireCount, totalCohorts, findPredictionDuplicates, findCoFireConstellations)
+- `src/index.ts` -- generate cohort_id, pass to recordFires in auto-fire path
+- `src/sideband.ts` -- same for MCP path
+- `src/hygiene.ts` -- add prediction dedup + constellation counts to report
+- `src/prompts.ts` -- compound minting guidance in all three prompt variants
+- `tests/prediction.test.ts` -- tests for new DB methods
+- `tests/plugin.test.ts` -- test that fire tracking records cohorts
+
+## Implementation Order
+
+1. **Fire tracking** (table + recordFires + caller wiring). Foundation for
+   everything else. Ship and let fire data accumulate.
+2. **Cosine dedup** (findPredictionDuplicates + hygiene integration). Does not
+   need fire tracking. Can ship in parallel with phase 1. Immediate value:
+   catches behavioral duplicates the write-time 0.85 dedup misses.
+3. **Co-fire dedup** (add co-fire ratio + cosine filter to
+  findPredictionDuplicates). Needs fire data to accumulate first. Wait a few
+   weeks after phase 1 ships.
+4. **Compound detection** (findCoFireConstellations + hygiene integration).
+   Needs more fire data than dedup (p_min_cofires = 10). Wait longer.
+5. **Compound minting** (prompt instructions + agent-driven via existing
+  tools). Ships with phase 4 -- the nudge surfaces candidates, the agent
+   compounds.
+
+Phases 1-2 can ship together. Phases 3-5 follow once fire data accumulates.
+
+## Test Plan
+
+- `prediction.test.ts`: test recordFires, fireCount, cofireCount,
+  totalCohorts with synthetic cohorts. Test findPredictionDuplicates with
+  known co-firing pairs. Test findCoFireConstellations with lift thresholds.
+  Use the existing `makeEmbed(seed, dim=384)` helper.
+- `plugin.test.ts`: test that chat.message auto-fire records a cohort.
+  Follow the recall-nudge test pattern (mock.module transformers + server
+  hooks).
+- `hygiene.test.ts` (if exists) or `plugin.test.ts`: test that hygiene report
+  includes prediction dedup/constellation counts when candidates exist.
+
+## Risks and Mitigations
+
+**Risk: O(n^2) co-fire self-join at session start.**
+Mitigation: n is small (tens of predictions per store). The self-join is over
+`prediction_fires` grouped by cohort_id, not over embeddings. Add a
+precondition gate (minimum prediction count, minimum fire count) before running
+the analysis.
+
+**Risk: Compound predictions fire too much, dominating the nudge.**
+Mitigation: The existing `scorePredictionNudge` deduplicates by prediction_id
+and slices to limit=5. A compound competes on equal footing with its children.
+If a compound and a child both fire, the higher-scoring one wins the slot. The
+compound's score is `cosine(matcher) * edge.weight * confidence` -- same
+formula. No special treatment.
+
+**Risk: Agent creates poor compounds (too generic, not useful).**
+Mitigation: The prompt instructions include the "strictly more general" guard
+and the "if you cannot generalize, do not compound" escape hatch. The compound
+starts at confidence 0.5 (p0) and earns confidence through user feedback like
+any prediction. Bad compounds get disconfirmed and stop dominating the nudge.
+
+**Risk: Fire tracking bloats the DB.**
+Mitigation: `prediction_fires` rows are small (id, prediction_id, store,
+session_id, cohort_id, score, fired_at). At ~10 predictions per fire event and
+~100 fire events per session, that is ~1000 rows per session. Add a cleanup
+pass (delete fires older than 90 days with no corresponding prediction) if
+this becomes a concern. Low priority.
+
+## Notes
+
+- The `populationP0` method already exists but is not wired into
+  `createPrediction`. Wiring it would make new predictions (including
+  compounds) start at the store's actual hit rate instead of flat 0.5. This is
+  a separate improvement, not part of this plan, but worth doing alongside
+  phase 1.
+- The existing write-time dedup (`findNearestPrediction` at 0.85) catches
+  near-identical statements at creation. The co-fire dedup in phase 3 catches
+  behavioral duplicates that differ in wording. The two are complementary:
+  write-time catches semantic twins, co-fire catches behavioral twins.
+- Nak's tier-2 decline ledger (`samskara_tier2_declines`, TTL'd 7 days) prevents
+  re-offering a declined constellation every sweep. Thatch's equivalent: a
+  `prediction_constellation_declines` table or a `dedup_pairs`-style
+  checked-pairs set. Defer until the agent is actually declining candidates and
+  the re-offer becomes annoying.

package/docs/qa/README.md

@@ -152,7 +152,24 @@ correctness on `README.md` and `docs/` excluding `docs/plans/`; see
   mocking `fs` to force a write error).
 - `bin/thatch` has no automated tests; it is a thin shell over `db.ts`.
 
-## Use cases
+## QA use-case suite
 
-See `docs/qa/use-cases/` for manual end-to-end scenarios with preconditions,
-steps, and expected results.
+End-to-end QA scenarios live in `tests/qa/` as bun test files, not docs.
+Each use case is a `uc-NNN-*.test.ts` file that defines preconditions,
+steps, and expected results as string constants, then registers itself
+via `registerUseCase` from `tests/qa/runner.ts`.
+
+Most use cases shell out to `opencode run` with an isolated repo copy
+(temp DB, temp config, temp home). Automatable use cases override the
+`run` function with direct CLI/bun assertions. Manual-only use cases
+(compaction, visual TUI) are skipped automatically.
+
+Run the suite:
+
+```bash
+mise run qa          # full run (spawns opencode sessions, costs model tokens)
+mise run qa-dry-run  # list use cases without spawning sessions
+```
+
+The regular test suite (`mise run check`) excludes `tests/qa/` by using
+a flat glob (`bun test tests/*.test.ts`).

package/docs/user/README.md

@@ -199,7 +199,9 @@ Seven specialist review lenses, each a self-contained static-analysis pass:
 | `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar against generic praise. |
 | `thatch-review-synthesizer` | Verifies and synthesizes findings from multiple specialists into a report that starts with workflow changes, then highlights, 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-code-archaeology` | Investigates an existing feature, debugs an unfamiliar area, or begins a new ticket. Explores the code base from multiple angles (data model, state flow, git history, sibling features, skeletons) before proposing changes. Pairs with `thatch-coding-workflow`. |
+| `thatch-review-followup` | Alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review adequately addressed your prior findings, offers to reply on resolved items, then optionally re-runs the full structured review. |
+| `thatch-review-response` | Author-side review response: triage findings on your own PR, fix bugs one by one, reply on each thread, post a top-level summary comment. |
 | `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. |
 | `thatch-code-walkthrough` | Explains a feature, module, or workflow to the user as a teaching walkthrough with file:line citations. Also used to draft high-level docs for new or undocumented features. |
 
@@ -207,9 +209,9 @@ Seven specialist review lenses, each a self-contained static-analysis pass:
 
 | Skill | Purpose |
 |-------|---------|
-| `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. |
+| `thatch-pr-description` | Drafts PR descriptions with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, project-context research, clarity checks, and bold/italic emphasis for scanning. |
+| `thatch-ticket-description` | Drafts ticket or issue descriptions (Linear or Jira) with clear sections, project-context research, clarity checks, and bold/italic emphasis for scanning. |
+| `thatch-split-overlarge-pr` | Splits already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main. |
 
 ### opencode-only skills
 
@@ -224,7 +226,9 @@ Seven specialist review lenses, each a self-contained static-analysis pass:
 | Memory skills (4) | Yes | Yes | Yes |
 | Review specialists (7) | Yes | Yes | Yes |
 | Review synthesizer | Yes | Yes | Yes |
-| Review context + workflow research | Yes | Yes | Yes |
+| Review context + code archaeology | Yes | Yes | Yes |
+| Review followup | Yes | Yes | Yes |
+| Review response (author-side) | Yes | Yes | Yes |
 | Walkthrough skills (2) | Yes | Yes | Yes |
 | Writing skills (3) | Yes | Yes | Yes |
 | Code review coordinator | Yes | No (requires sub-agents) | No (requires sub-agents) |
@@ -258,6 +262,30 @@ specialist in sequence, then synthesize:
 4. Load thatch-review-synthesizer, verify and aggregate all findings.
 ```
 
+For a **follow-up round** (the author responded or pushed changes after your
+review), load the re-check skill:
+
+```text
+Load thatch-review-followup and check whether my prior review comments
+on this PR were adequately addressed.
+```
+
+It verifies whether each finding was resolved (by code change, proof, or
+follow-up ticket with a risk explanation), offers to reply on the resolved
+ones, then optionally hands off to the coordinator for a fresh full review.
+
+For **responding to review on your own PR**, load the author-side skill:
+
+```text
+Load thatch-review-response and help me work through the review comments
+on my PR.
+```
+
+It triages every finding (legitimate, intentional, false positive, unlikely
+edge case), collapses comments sharing a root cause, works through each bug
+with you, drafts replies on each thread, then posts a top-level summary
+comment so reviewers can see what changed without re-reading the full diff.
+
 These files are plugin-owned: local edits are overwritten the next time the
 plugin initializes (this is how skill improvements ship with new versions).
 

package/package.json

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

package/src/db.ts

@@ -344,7 +344,7 @@ export class ThatchDB {
   /**
    * Brute-force cosine similarity search across the given stores.
    * When branch is specified, includes project-wide (branch IS NULL) plus
-   * branch-specific entries. Does NOT stamp recall telemetry — the prompt-aware
+   * branch-specific entries. Does NOT stamp recall telemetry - the prompt-aware
    * nudge uses this to check whether memories relate to a prompt without
    * polluting recall_count/last_recalled_at (the agent hasn't actually read
    * them yet, only the plugin has checked for relevance).
@@ -388,7 +388,7 @@ export class ThatchDB {
 
     // Entries embedded by a different model live in a different vector space;
     // comparing them would produce NaN or nonsense scores, so they're skipped
-    // rather than ranked. Dimension is the discriminator — model tags are
+    // rather than ranked. Dimension is the discriminator - model tags are
     // informational only.
     const scored = rows.flatMap((row) => {
       row.archived = !!row.archived;
@@ -403,7 +403,7 @@ export class ThatchDB {
 
   /**
    * Semantic recall for agent-initiated searches. Delegates to search() for
-   * cosine scoring, then stamps recall telemetry — retrieval is the "used
+   * cosine scoring, then stamps recall telemetry - retrieval is the "used
    * recently" signal hygiene reporting keys on.
    */
   recall(
@@ -427,7 +427,7 @@ export class ThatchDB {
   }
 
   /**
-   * Entries in a store semantically close to the given embedding — the
+   * Entries in a store semantically close to the given embedding - the
    * write-time collision check. Unlike recall(), this records no telemetry:
    * it's the plugin looking, not the agent using.
    */
@@ -931,7 +931,7 @@ export class ThatchDB {
   }
 
   // ---------------------------------------------------------------------------
-  // Hygiene — signals for the session-start heartbeat. Staleness means
+  // Hygiene - signals for the session-start heartbeat. Staleness means
   // neither written nor recalled since the cutoff; recall telemetry keeps
   // actively-used old memories out of the count.
   // ---------------------------------------------------------------------------
@@ -1002,7 +1002,7 @@ function blobToVector(blob: Uint8Array): Float32Array {
 /**
  * Cosine similarity between two Float32Array vectors of equal dimension.
  * Returns a value in [-1, 1]. Normalized embeddings will be close to [0, 1].
- * Throws on dimension mismatch — comparing vectors from different embedding
+ * Throws on dimension mismatch - comparing vectors from different embedding
  * spaces is always a caller bug; callers filter by length first.
  */
 export function cosineSimilarity(a: Float32Array, b: Float32Array): number {

package/src/embeddings.ts

@@ -1,5 +1,5 @@
 // BGE-small-en-v1.5 requires a query prefix for asymmetric search.
-// Passage (memory content) gets no prefix — the model was trained
+// Passage (memory content) gets no prefix - the model was trained
 // to encode passages without instruction.
 const QUERY_PREFIX =
   "Represent this sentence for searching relevant passages: ";
@@ -86,7 +86,7 @@ export class BgeEmbeddingModel implements EmbeddingModel {
 /**
  * Mock embedding model for tests. Returns deterministic vectors derived from
  * a hash of the input text via xorshift, so identical texts embed identically
- * and distinct texts land near-orthogonal — mirroring how unrelated content
+ * and distinct texts land near-orthogonal - mirroring how unrelated content
  * behaves in a real embedding space. Never loads a model or touches the network.
  */
 export class MockEmbeddingModel implements EmbeddingModel {

package/src/extract-queue.ts

@@ -27,7 +27,7 @@ export function queueDir(): string {
   return join(cacheHome, "thatch", "queue");
 }
 
-/** Sanitize a session id for use as a filename — UUIDs are already safe. */
+/** Sanitize a session id for use as a filename - UUIDs are already safe. */
 function safeName(sessionID: string): string {
   return sessionID.replace(/[^a-zA-Z0-9_-]/g, "_");
 }
@@ -38,9 +38,9 @@ function queuePath(sessionID: string): string {
 
 /**
  * Buffer a batch of tool calls for later extraction. Filters out:
- * - thatch's own MCP tools (mcp__thatch__*) to avoid self-echo — extracting
+ * - thatch's own MCP tools (mcp__thatch__*) to avoid self-echo - extracting
  *   facts from memory operations would just write the store back into itself.
- * - skill/task/agent meta-tools — these orchestrate agent behavior (loading
+ * - skill/task/agent meta-tools - these orchestrate agent behavior (loading
  *   skills, dispatching sub-agents) and buffering them creates a feedback
  *   loop where the extraction nudge triggers a skill load, which gets
  *   buffered, which triggers another nudge on the next turn.
@@ -116,7 +116,7 @@ function readQueueFile(path: string): ToolInteraction[] {
 }
 
 // ---------------------------------------------------------------------------
-// Missed-nudge counter — file-backed per-session escalation state. Tracks
+// Missed-nudge counter - file-backed per-session escalation state. Tracks
 // consecutive extraction nudges delivered without any memory_remember call.
 // Reset by appendBatch when the agent writes a memory. Read and incremented
 // by flush-tools when the nudge is delivered.

package/src/extraction.ts

@@ -64,7 +64,7 @@ export function truncate(text: string, maxLen: number): string {
  * thatch-fact-extractor skill expects. Shared by the opencode plugin path
  * (in-memory buffer) and the Claude Code CLI path (file-backed queue) so the
  * extractor sees an identical contract regardless of host. The agent itself
- * does the actual fact extraction — this function only collects and serializes.
+ * does the actual fact extraction - this function only collects and serializes.
  */
 export function buildExtractionPayload(
   interactions: ToolInteraction[],
@@ -113,7 +113,7 @@ export class ExtractionPipeline {
 
   /**
    * Accept the session's buffer: move it to a holding area so the nudge
-   * stops replaying while a dispatched extractor works. AMQP-style accept —
+   * stops replaying while a dispatched extractor works. AMQP-style accept -
    * the entries are not dropped until a completion signal arrives (the
    * extractor writes a memory, calls extraction_done, or goes idle). If the
    * extractor dies first, requeueAccepted puts them back.
@@ -135,7 +135,7 @@ export class ExtractionPipeline {
    * Move accepted entries back to pending: the extractor errored or its
    * session was deleted before completing, so the facts were never
    * processed. Prepended so they replay in original order. Not capped at
-   * maxBuffer — a silent drop here would defeat the point of requeueing;
+   * maxBuffer - a silent drop here would defeat the point of requeueing;
    * the next push trims back to the cap.
    */
   requeueAccepted(sessionID: string): void {
@@ -155,7 +155,7 @@ export class ExtractionPipeline {
    * Remove entries that were in the snapshot (by reference identity), keeping
    * any that arrived after the snapshot was taken. Used by the child-parent
    * drain: when a sub-agent writes a memory, only the entries present at
-   * dispatch time should be drained — not the entire buffer, which may now
+   * dispatch time should be drained - not the entire buffer, which may now
    * contain interleaved-turn entries the parent accumulated while the
    * sub-agent was running.
    */

package/src/git.ts

@@ -84,7 +84,7 @@ export async function detectRepo(cwd?: string): Promise<string> {
 /**
  * Local branch names in the given directory's repository. Used to detect
  * branch-scoped memories whose branch no longer exists. Returns [] outside
- * a git repo — callers must treat that as "unknown", not "no branches",
+ * a git repo - callers must treat that as "unknown", not "no branches",
  * or every branch-scoped memory would look orphaned.
  */
 export async function listBranches(cwd: string): Promise<string[]> {

package/src/hygiene.ts

@@ -27,7 +27,7 @@ export async function hygieneReport(
   }
 
   // listBranches returns [] outside a git repo, which would make every
-  // branch-scoped memory look orphaned — skip the check in that case.
+  // branch-scoped memory look orphaned - skip the check in that case.
   const scoped = db.branchesInStore(repo);
   if (scoped.length > 0) {
     const live = await listBranches(worktree);