@jeffober/thatch 0.1.27 → 0.1.29

package/docs/dev/README.md

@@ -24,9 +24,14 @@ Shared core
   ├── embeddings.ts   → embedding model via transformers.js
   ├── git.ts          → detect repo identity (store name)
   ├── hygiene.ts      → hygiene report (pending dedups, stale, orphaned branches)
-  ├── prompts.ts      → system prompt, compaction, reminders, recall nudge, CLAUDE.md instructions
+  ├── prompts.ts      → system prompt, compaction, reminders, recall/prediction/behavior nudges, CLAUDE.md instructions
   ├── sideband.ts     → Unix socket server + client: warm-model semantic match for hook processes
-  └── skills.ts       → SKILL.md content + installer (shared + opencode-only arrays)
+  ├── skills.ts       → SKILL.md content + installer (shared + opencode-only arrays)
+  ├── scoring-engine.ts → generic four-table scoring base (shared by prediction + behavior engines)
+  ├── prediction.ts   → prediction engine wrapper (thin layer over ScoringEngine)
+  ├── behavior.ts     → behavior engine wrapper (thin layer over ScoringEngine)
+  ├── seed-behaviors.ts → default behavior seeding on first run
+  └── vector-math.ts  → blobToVector + cosineSimilarity helpers
 
 OpenCode plugin path
   ├── index.ts        → plugin entry: wires DB/model/extraction, registers tools + hooks
@@ -44,7 +49,7 @@ MCP server path
                         CLAUDE.md / AGENTS.md, settings/hooks JSON, installs skills
 
 bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygiene|
-                        prime|buffer-batch|buffer-tool|flush-tools|setup
+                        prime|buffer-batch|buffer-tool|flush-tools|flush-predictions|setup
 ```
 
 ## Module responsibilities
@@ -55,16 +60,21 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `tools.ts` | Thin opencode wrappers. Imports tool-defs, wraps each in opencode's `tool()` with a `thatch_` prefix. |
 | `mcp.ts` | Stdio JSON-RPC 2.0 server. Compiles zod schemas to JSON Schema via `z.toJSONSchema()` for `tools/list`. Validates args via `z.object().parse()` in `tools/call`. All logging to stderr (stdout is the transport). |
 | `index.ts` | OpenCode plugin entry. Wires DB, model, extraction; registers tools and hooks; installs skills. Internal state beyond the extraction pipeline: `extracting` set (parent IDs with an active direct-extraction child), `childMetrics` map (new/updated/deleted counts per child session), and `triggerExtraction(parentID)` (creates a child session via the SDK client and prompts it with the extraction payload). |
-| `setup.ts` | `thatch setup --claude` installer. Writes .mcp.json, appends to CLAUDE.md (idempotent), installs hooks in settings.json, installs skills. |
+| `setup.ts` | `thatch setup --claude` / `--cursor` installer. Writes MCP config (`.mcp.json` / `.cursor/mcp.json`), appends to CLAUDE.md / AGENTS.md (idempotent), installs hooks in settings.json / hooks.json, installs skills. |
 | `hygiene.ts` | Hygiene report: pending dedup pairs, stale count, orphaned branch memories. Shared by the plugin's session-start hook and the CLI's `thatch reminder` command. |
 | `git.ts` | Parse `owner/repo` from git remote. Worktree-safe fallback chain. |
-| `db.ts` | SQLite schema, CRUD for entries/stores, brute-force cosine search (`search` = pure scoring, `recall` = search + telemetry stamping), dedup-pair verdict tracking. Prediction tables: matchers, predictions, edges, provenance. `scorePredictionNudge` is the shared auto-fire entry point for both host paths. |
+| `db.ts` | SQLite schema, CRUD for entries/stores, brute-force cosine search (`search` = pure scoring, `recall` = search + telemetry stamping), dedup-pair verdict tracking. Prediction tables: matchers, predictions, edges, provenance. `scorePredictionNudge` is the shared auto-fire entry point for both host paths. Behavior tables: same four-table shape (matchers, behaviors, edges, provenance) with `scoreBehaviorNudge` as the shared entry point. |
 | `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 extraction nudge carries. The in-memory pipeline is opencode-only, but the payload builders (`buildExtractionPayload`, `deriveTitle`) are shared by both paths — `extract-queue.ts` imports `deriveTitle`, `bin/thatch` imports `buildExtractionPayload`. `summarizeArgs` is used internally by `buildExtractionPayload`. |
+| `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`. |
-| `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 two methods: `match` (recall nudge) and `predictions` (prediction 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`), 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` (22 skills: fact-extractor, dedup-classifier, project-primer, 7 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 — work on both opencode and Claude Code) and `OPENCODE_ONLY_SKILLS` (1 skill: code-review coordinator — requires sub-agent support, not installed for Claude Code). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
+| `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` (23 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 — 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]`. |
+| `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. |
+| `seed-behaviors.ts` | Default behavior seeding on first run. Populates starter self-discipline rules. |
+| `vector-math.ts` | `blobToVector` and `cosineSimilarity` helpers used across the codebase. |
 
 ## Plugin hooks
 
@@ -76,7 +86,7 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `experimental.session.compacting` | Marks the session as compacting and appends re-familiarization context so a compacted session still knows thatch exists. |
 | `experimental.compaction.autocontinue` | Clears the compacting flag so `chat.message` nudges resume. Without this, nudges that instruct tool calls would fire during summary generation where tools are blocked. The `chat.message` hook also clears the flag if it fires for a session still in the compacting set but the incoming message has no compaction-type part — this handles compaction failure, where the session would otherwise be stuck with nudges off forever. |
 | `tool.execute.after` | Buffers every non-`thatch_*`, non-`skill`, non-`task` tool call into the session's extraction buffer. (Skill/task are excluded — buffering them creates a feedback loop where the nudge triggers a skill load, which gets buffered, which triggers another nudge.) Memory writes (`thatch_memory_remember`) and `thatch_extraction_done` drain the buffer and reset the missed-nudge counter. For child sessions (`childToParent.has(sessionID)`), also tracks metrics: `remember` with `overwrite:false` → new++, `overwrite:true` → updated++, `forget` → deleted++. This is a plugin hook, NOT a bus event — do not move it into the `event` handler; the event bus has no such event and it will silently never fire. |
-| `chat.message` | Two priority tiers: (a) if extraction buffer has interactions and the session is NOT in the `extracting` set (direct extraction in progress), **peeks** the buffer (does NOT drain it) and injects a synthetic text part carrying the extraction nudge + JSON payload — the buffer persists until the agent writes a memory or calls `thatch_extraction_done`, so ignored nudges repeat and escalate (polite → insistent → ALL-CAPS) via the `missedNudges` counter; (b) otherwise, embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). The same embedding also feeds the prediction auto-fire: `db.scorePredictionNudge` scores the prompt against prediction matchers and injects a separate `[thatch] User decision model` nudge if any matchers clear the 0.45 threshold. Recall and prediction nudges fire independently (separate try/catch blocks, separate synthetic parts). Skipped entirely while the session is compacting (tool calls are blocked during summary generation). |
+| `chat.message` | Two priority tiers: (a) if extraction buffer has interactions and the session is NOT in the `extracting` set (direct extraction in progress), **peeks** the buffer (does NOT drain it) and injects a synthetic text part carrying the extraction nudge with the session ID and fetch tool name (not the full payload) — the sub-agent calls `thatch_get_extraction_payload` to retrieve the interactions as a tool response, keeping the full payload out of the main session's context window. The buffer persists until the agent writes a memory or calls `thatch_extraction_done`, so ignored nudges repeat and escalate (polite → insistent → ALL-CAPS) via the `missedNudges` counter; (b) otherwise, embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). The same embedding also feeds the prediction auto-fire (`db.scorePredictionNudge`, injects `[thatch] User decision model`) and the behavior auto-fire (`db.scoreBehaviorNudge`, injects `[thatch] Situational behaviors`). All three nudges (recall, prediction, behavior) fire independently in separate try/catch blocks with separate synthetic parts. Skipped entirely while the session is compacting (tool calls are blocked during summary generation). |
 | `event` | Subscribes to all session bus events. `session.created`: records `childToParent` + `parentSnapshots` (shallow copy of the parent's buffer for snapshot-aware drain), then sends the session-start reminder via `client.session.prompt` carrying the hygiene heartbeat (pending dedup pairs, stale count, orphaned branch memories) when any signal is non-zero. `session.status` (idle): if the session is a child, drains its snapshot, fires a toast with `childMetrics`, and deletes the child session; if the session is a parent with pending tool interactions and not already extracting, calls `triggerExtraction` to create a direct-extraction child. `session.error`: requeues the parent's buffer (child died without draining). `session.deleted`: cleans up `childToParent`, `parentSnapshots`, `childMetrics`, and `extracting`. `session.compacted`: clears the compacting flag so `chat.message` nudges resume. |
 | `dispose` | Closes the DB. |
 
@@ -100,12 +110,14 @@ Two of these hooks were dead for weeks because failures were invisible.
 5. **Store creation is implicit.** First `remember` to a new store creates it.
 6. **Default recall scope is repo + global.** The tool layer hardcodes this.
 7. **Skills are plugin-owned files.** Installed to
-   `$XDG_CONFIG_HOME/opencode/skills` (opencode) or `~/.claude/skills/`
-   (Claude Code) — never into the worktree; drifted content is overwritten
-   on plugin init or re-running `thatch setup`. Skills are split into
-   `SHARED_SKILLS` (work on both hosts) and `OPENCODE_ONLY_SKILLS` (require
-   sub-agent support, not installed for Claude Code). The opencode plugin
-   installs both arrays; `thatch setup --claude` installs only shared.
+   `$XDG_CONFIG_HOME/opencode/skills` (opencode), `~/.claude/skills/`
+   (Claude Code), or `~/.cursor/skills/` (Cursor) — never into the
+   worktree; drifted content is overwritten on plugin init or re-running
+   `thatch setup`. Skills are split into `SHARED_SKILLS` (work on all
+   three hosts) and `OPENCODE_ONLY_SKILLS` (require sub-agent support,
+   not installed for Claude Code or Cursor). The opencode plugin
+   installs both arrays; `thatch setup --claude` and `--cursor` install
+   only shared.
 8. **Tool definitions are the single source of truth.** `tool-defs.ts` defines
    each tool once (name, zod schema, execute function). The opencode plugin
    wraps them in `tool()` with a `thatch_` prefix; the MCP server wraps them
@@ -138,6 +150,18 @@ Two of these hooks were dead for weeks because failures were invisible.
     relevance-gated (being tested moves it, not being ignored). See the
     prediction DB tables, auto-fire in `chat.message`, and the sideband
     `predictions` method for the MCP path.
+12. **Behavior engine mirrors the prediction engine but is self-graded.** Same
+    four-table data model, same Bayesian confidence, same auto-fire pipeline.
+    The difference: predictions model what the USER wants (graded by user
+    feedback); behaviors model what the LLM should do (graded by the LLM's own
+    ham/spam relevance judgment via `behavior_feedback`). The firewall
+    principle from predictions (the model that uses predictions cannot grade
+    them) does not apply: the LLM grading its own behavioral rules is the
+    point, not a violation. The ham/spam is a relevance judgment ("does this
+    rule apply here?"), not a value judgment ("is this a good rule?"). An
+    anti-laziness guard in the prompt prevents the agent from codifying
+    shortcuts. See the behavior DB tables, auto-fire in `chat.message`, and
+    the sideband `behaviors` method for the MCP path.
 
 ## Data flow
 
@@ -186,12 +210,13 @@ extraction cycle
   → nudge path (fallback): if triggerExtraction throws (create or prompt
     fails), the `extracting` set clears and the next chat.message sees
     pending entries with no extracting flag → peeks the buffer and injects
-    a nudge part with JSON payload; missed nudges escalate (polite →
+    a nudge part with session ID and fetch tool name; missed nudges escalate (polite →
     insistent → ALL-CAPS) via the missedNudges counter
     → drain: thatch_memory_remember (or thatch_extraction_done) clears the
       buffer and resets the missed-nudge counter
-    → agent loads thatch-fact-extractor skill, saves facts via
-      thatch_memory_remember
+    → agent dispatches a sub-agent that calls thatch_get_extraction_payload
+      to fetch the queued interactions, loads thatch-fact-extractor skill,
+      saves facts via thatch_memory_remember
   → MCP path (Claude Code/Cursor): unchanged — no SDK client, no child
     sessions; extract-queue.ts + flush-tools drives the nudge via hooks
 
@@ -206,7 +231,9 @@ toast notifications (opencode-only, TUI-rendered)
   → recall matches: `[thatch] recalled N memories` (info variant, 3s) —
     fires when chat.message matches stored memories
   → prediction matches: `[thatch] N predictions surfaced` (info variant,
-    3s) — fires when chat.message matches decision-model patterns
+     3s) — fires when chat.message matches decision-model patterns
+  → behavior matches: `[thatch] N behaviors surfaced` (info variant,
+     3s) — fires when chat.message matches codified behavior matchers
 
 prompt-aware recall nudge (both paths)
   → opencode: chat.message hook embeds prompt text with warm in-process model,
@@ -236,7 +263,7 @@ prediction cycle (agent-driven, statistical model)
     confidence is relevance-gated (being tested moves it, not being ignored).
   → auto-fire (opencode): chat.message reuses the prompt embedding already
     computed for the recall nudge. db.scorePredictionNudge([repo, global],
-    embedding, 0.45) finds matchers above threshold, follows edges to
+     embedding, 0.60) finds matchers above threshold, follows edges to
     predictions, scores by cosine * weight * confidence, dedups by
     prediction_id, and returns top 5. Injects a separate synthetic part
     with a [thatch] User decision model block. 0-evidence predictions use
@@ -251,6 +278,29 @@ prediction cycle (agent-driven, statistical model)
     thatch_prediction_list inspects the model with provenance;
     thatch_prediction_delete removes bad predictions (cascade clears edges
     and provenance).
+
+behavior cycle (agent-driven, self-graded)
+  → formation: agent calls thatch_behavior_codify(situation, behavior, rationale)
+    when it recognizes a situation it should react to in a specific, repeatable
+    way. The tool embeds the situation text, finds or creates a behavior matcher
+    (0.85 dedup), finds or creates a behavior (0.85 store-wide dedup), links
+    them via an edge. Confidence starts at p0 (0.5) with 0 evidence.
+  → auto-fire (opencode): chat.message reuses the prompt embedding. db.
+     scoreBehaviorNudge([repo, global], embedding, 0.60) finds behavior matchers
+    above threshold, follows edges to behaviors, scores by cosine * weight *
+    confidence, dedups by behavior_id, returns top 5. Injects a separate
+    synthetic part with a [thatch] Situational behaviors block. 0-evidence
+    behaviors use "consider"; behaviors with evidence use "do".
+  → auto-fire (Claude Code/Cursor): flush-tools fires the behavior query via
+    the sideband socket's `behaviors` method in parallel with recall and
+    predictions. Same scoreBehaviorNudge entry point prevents scoring drift.
+  → consumption: agent evaluates each surfaced behavior against the current
+    situation. If relevant (ham), follows it and calls behavior_feedback with
+    relevant: true (confirm). If not relevant (spam), calls behavior_feedback
+    with relevant: false (disconfirm). The feedback adjusts the Bayesian
+    confidence the same way prediction signals do. thatch_behavior_list
+    inspects with provenance; thatch_behavior_delete removes bad rules
+    (cascade clears edges and provenance).
 ```
 
 ## Database
@@ -265,7 +315,11 @@ prediction cycle (agent-driven, statistical model)
   `prediction_matchers(id PK, store, description, embedding BLOB, model, created_at, updated_at)`,
   `predictions(id PK, store, statement, rationale, embedding BLOB, model, confidence REAL, confirm_count REAL, disconfirm_count REAL, created_at, updated_at)`,
   `prediction_edges(matcher_id, prediction_id, weight REAL, PK(matcher_id, prediction_id), FK CASCADE)`,
-  `prediction_provenance(id PK, prediction_id, signal, detail, created_at, FK CASCADE)`.
+  `prediction_provenance(id PK, prediction_id, signal, detail, created_at, FK CASCADE)`,
+  `behavior_matchers(id PK, store, description, embedding BLOB, model, created_at, updated_at)`,
+  `behaviors(id PK, store, statement, rationale, embedding BLOB, model, confidence REAL, confirm_count REAL, disconfirm_count REAL, created_at, updated_at)`,
+  `behavior_edges(matcher_id, behavior_id, weight REAL, PK(matcher_id, behavior_id), FK CASCADE)`,
+  `behavior_provenance(id PK, behavior_id, signal, detail, created_at, FK CASCADE)`.
 - `recall_count`, `last_recalled_at`, and `archived` are added to pre-existing
   databases by an idempotent column migration at init (`PRAGMA table_info` +
   `ALTER TABLE`). The `archived` column is `INTEGER NOT NULL DEFAULT 0` (0 =

package/docs/dev/features/README.md

@@ -0,0 +1,33 @@
+# Feature Architecture
+
+Per-feature architecture docs for thatch. Each doc covers what the feature
+does, how it works, how it interacts with other features, and the source
+files that implement it.
+
+For the monolithic architecture overview, see
+[../README.md](../README.md). For hook configuration and concrete artifact
+paths, see [../setup-and-hooks.md](../setup-and-hooks.md). For feature
+parity across hosts, see [../mcp-parity.md](../mcp-parity.md). For the skill
+system, see [../skills.md](../skills.md). For non-obvious invariants, see
+[../gotchas.md](../gotchas.md).
+
+## Docs
+
+| Doc | Feature |
+|-----|---------|
+| [memory-store.md](memory-store.md) | Persistent memory store (CRUD, search, embeddings, stores, branches) |
+| [multi-host.md](multi-host.md) | Three-host architecture (opencode, Claude Code, Cursor) |
+| [extraction.md](extraction.md) | Extraction pipeline (buffering, child sessions, nudge escalation, file-backed queue) |
+| [nudge-pipeline.md](nudge-pipeline.md) | Per-message nudge pipeline (extraction, recall, prediction, behavior tiers) |
+| [prediction-engine.md](prediction-engine.md) | Prediction engine (user decision model, Bayesian confidence, auto-fire) |
+| [behavior-engine.md](behavior-engine.md) | Behavior engine (LLM self-discipline rules, ham/spam, auto-fire) |
+| [hygiene.md](hygiene.md) | Hygiene system (duplicate, stale, orphaned branch signals) |
+| [deduplication.md](deduplication.md) | Deduplication system (find pairs, verdict lifecycle) |
+| [sideband.md](sideband.md) | Sideband IPC (Unix socket for MCP host hook processes) |
+| [compaction-recovery.md](compaction-recovery.md) | Compaction recovery (opencode compaction hooks) |
+| [session-lifecycle.md](session-lifecycle.md) | Session lifecycle management (opencode events, child tracking) |
+| [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) |
+| [cicd.md](cicd.md) | CI/CD (CI pipeline, OIDC publishing, release helper) |

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

@@ -0,0 +1,271 @@
+# Behavior Engine (LLM Self-Discipline Rules)
+
+A statistical model of the LLM's own operational discipline. Captures "when
+situation X arises, I should do Y." Mirrors the
+[prediction engine](prediction-engine.md) architecture but serves a different
+purpose: predictions model what the *user* wants; behaviors model what the
+*LLM* should do.
+
+## What it does
+
+- Four tools: `behavior_codify`, `behavior_feedback`, `behavior_list`,
+  `behavior_delete`. All defined in `src/tool-defs.ts`.
+- Auto-fires at every user message: embeds the prompt, cosine-matches against
+  behavior matchers, injects scored behaviors as a synthetic nudge part.
+- Ham/spam feedback (ham = relevant, spam = not relevant) adjusts Bayesian
+  confidence, training the classifier over time.
+- Anti-laziness guard in prompt instructions: prevents codifying rules that
+  make the agent less thorough. Rules should encode discipline, not shortcuts.
+- Default behavior seeding at startup: seeds several default behaviors into
+  the global store (session wrap-up, work finalization, research discipline,
+  day-turnover checks, dead-end capture, git archaeology). Idempotent across
+  releases via version stamps.
+
+## How it works
+
+### Data model: matchers, behaviors, edges, provenance
+
+Four tables in SQLite — same shape as the prediction engine:
+
+- **Behavior matchers** — situation descriptions (when to apply the rule).
+  Embedded, cosine-matched at `chat.message`. Capture "when."
+- **Behaviors** — self-discipline rule statements (what to do). Capture
+  "what." Each carries a rationale explaining why the rule is worth
+  persisting.
+- **Edges** — weighted matcher-to-behavior links. Many-to-many. The same
+  matcher can link to multiple behaviors; the same behavior can be reached
+  by multiple matchers.
+- **Provenance** — audit trail of every signal applied to a behavior
+  (`codify`, `confirm` / ham, `disconfirm` / spam) with detail and timestamp.
+
+### Confidence model (Bayesian posterior)
+
+Same formula and constants as the prediction engine — the constants live in
+`src/scoring-engine.ts` and are shared by both engines:
+
+```text
+confidence = (confirm_count + K * P0) / (confirm_count + disconfirm_count + K)
+```
+
+- K = 5 (shrinkage parameter)
+- P0 = 0.5 (prior)
+- Ham feedback = confirm signal. Spam feedback = disconfirm signal.
+- Same shrinkage and relevance-gated properties as predictions: a single ham
+  is plausible, not reliable. Untested behaviors stay at P0.
+
+### How it differs from the prediction engine
+
+| Aspect | Prediction engine | Behavior engine |
+|--------|-------------------|-----------------|
+| Models | What the USER wants | What the LLM should do |
+| Graded by | User feedback (confirm/disconfirm/soft) | LLM's own ham/spam relevance judgment |
+| Firewall principle | Applies — the model that uses predictions cannot grade them | Does NOT apply — the LLM grading its own behaviors IS the point |
+| Signal types | confirm, disconfirm, soft, create | confirm (ham), disconfirm (spam), codify |
+| Default seeding | No | Yes (multiple default behaviors at startup) |
+
+The firewall principle from predictions does not apply here. The LLM grading
+its own behavioral rules is the point, not a violation. Ham/spam is a
+relevance judgment ("does this rule apply here?"), not a value judgment ("is
+this a good rule?"). The agent evaluates each surfaced behavior against the
+current situation and records whether it was relevant.
+
+### Codify (`behavior_codify` tool)
+
+Parameters: `situation` (triggering context), `behavior` (the rule),
+`rationale` (why worth persisting).
+
+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.
+3. **New behavior** — creates behavior + edge + provenance entry tagged
+   `codify`.
+4. Returns `[codified]` for a new behavior or `[linked]` for an existing one
+   (with confidence and counts).
+
+Confidence starts at P0 (0.5) with 0 evidence.
+
+### Feedback (`behavior_feedback` tool)
+
+Parameters: `behavior` (statement, semantic match at cosine >= 0.85),
+`relevant` (boolean), `context` (situation description for provenance).
+
+- `relevant: true` = ham = confirm signal.
+- `relevant: false` = spam = disconfirm signal.
+- Adjusts confidence and records provenance tagged `ham:` or `spam:`.
+- Returns updated confidence and confirm/disconfirm counts.
+- Returns a "not found" message if no behavior matches.
+
+### Auto-fire (opencode: `chat.message` hook)
+
+- Reuses the prompt embedding already computed for the recall nudge — same
+  embedding serves recall (tier 2), prediction (tier 3), and behavior (tier
+  4). One embed, three lookups.
+- Calls `db.scoreBehaviorNudge([repo, "global"], embedding,
+  BEHAVIOR_THRESHOLD)`.
+- Threshold: 0.60 (env: `THATCH_BEHAVIOR_THRESHOLD`). Same as prediction —
+  surfacing a discipline rule is as disruptive as surfacing a preference.
+- Injects `behaviorNudge(items)` as a separate synthetic text part with a
+  `[thatch] Situational behaviors` header.
+- 0-evidence behaviors use "consider"; behaviors with evidence use "do".
+- Independent try/catch — a behavior failure does not block recall or
+  prediction.
+- Toast: `[thatch] N behaviors surfaced`.
+
+### Auto-fire (MCP: sideband)
+
+- `flush-tools` fires the behavior query via the sideband socket's
+  `behaviors` method, in parallel with recall and predictions.
+- The same `scoreBehaviorNudge` entry point prevents scoring drift between
+  host paths.
+- Sideband failure returns `null`; the caller skips the behavior nudge
+  gracefully.
+
+### Default behavior seeding (`src/seed-behaviors.ts`)
+
+Runs at startup in both the opencode plugin (`src/index.ts`) and the MCP
+server (`src/mcp.ts`), after DB and model initialization.
+
+Seeds multiple default behaviors into the global store — session wrap-up
+(check for uncommitted changes, untracked files, stale artifacts), work
+finalization (check before commits/merges), research discipline (investigate
+before proposing changes), day-turnover checks (rebase staleness, new review
+comments), dead-end capture (save red herrings as memories), and git
+archaeology (understand history before debugging or planning).
+
+Idempotent across releases via version stamps:
+
+1. For each default behavior, embeds the situation and behavior text.
+2. Checks whether a behavior matcher with cosine >= 0.85 already exists.
+3. If found, checks the linked behavior's rationale for a version stamp
+   (`seed-version:X.Y.Z`).
+4. If the stamp matches the current package version, skips — already seeded.
+5. If the stamp differs (older release seeded it) or is absent (manually
+   codified), deletes the old behavior and re-creates it with the current
+   version stamp. The matcher and edge cascade-delete with the behavior.
+6. Creates: behavior matcher (situation embedding), behavior (statement +
+   rationale embedding, with version stamp), edge (weight 1.0), provenance
+   entry tagged `codify`.
+
+### Anti-laziness guard
+
+Prompt instructions in all host variants explicitly prevent the agent from
+codifying rules that make it less thorough. The guard text — "Do not codify
+rules that make you lazier or less thorough. Rules should encode discipline,
+not shortcuts." — appears in `src/prompts.ts` in each host's system prompt.
+
+### Consumption
+
+When surfaced behaviors appear in the nudge, the agent evaluates each against
+the current situation:
+
+- If relevant (ham): follows the rule and calls `behavior_feedback` with
+  `relevant: true` (confirm).
+- If not relevant (spam): calls `behavior_feedback` with `relevant: false`
+  (disconfirm).
+
+This trains the classifier so future nudges are more accurate. Behaviors
+that consistently score as spam will drop in confidence and eventually fall
+below the auto-fire threshold.
+
+## Interactions with other features
+
+- **Nudge pipeline** ([nudge-pipeline.md](nudge-pipeline.md)): behavior
+  auto-fire is tier 4. Shares the prompt embedding with recall (tier 2) and
+  prediction (tier 3).
+- **Prediction engine** ([prediction-engine.md](prediction-engine.md)): same
+  four-table data model, same Bayesian confidence, same scoring engine.
+  Different semantics and different grading — user feedback vs. self
+  feedback.
+- **Scoring engine**: `src/scoring-engine.ts` provides the generic
+  four-table scoring base. `BehaviorEngine` (`src/behavior.ts`) is a thin
+  wrapper with behavior-specific table names.
+- **Memory store** ([memory-store.md](memory-store.md)): same embedding
+  model (BGE-small-en-v1.5), same SQLite DB, different tables.
+- **Sideband IPC** ([sideband.md](sideband.md)): MCP hosts query behaviors
+  via the sideband socket's `behaviors` method.
+
+## Source files
+
+| File | Role |
+|------|------|
+| `src/behavior.ts` | Thin wrapper around `ScoringEngine` with behavior-specific table names |
+| `src/scoring-engine.ts` | Generic four-table scoring engine with Bayesian confidence (shared base for prediction and behavior) |
+| `src/seed-behaviors.ts` | Default behavior seeding at startup — version-stamped, idempotent across releases |
+| `src/db.ts` | Behavior tables, `scoreBehaviorNudge` delegation |
+| `src/tool-defs.ts` | Four behavior tools (`codify`, `feedback`, `list`, `delete`) |
+| `src/prompts.ts` | `behaviorNudge` formatting, verb selection ("consider" vs "do"), anti-laziness guard |
+| `src/sideband.ts` | `behaviors` method for the MCP path |
+
+## Database tables
+
+```sql
+behavior_matchers(
+    id          TEXT PRIMARY KEY,
+    store       TEXT NOT NULL REFERENCES stores(name),
+    description TEXT NOT NULL,
+    embedding   BLOB,
+    model       TEXT,
+    created_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now')),
+    updated_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now'))
+)
+
+behaviors(
+    id               TEXT PRIMARY KEY,
+    store            TEXT NOT NULL REFERENCES stores(name),
+    statement        TEXT NOT NULL,
+    rationale        TEXT,
+    embedding        BLOB,
+    model            TEXT,
+    confidence       REAL NOT NULL DEFAULT 0.5,
+    confirm_count    REAL NOT NULL DEFAULT 0,
+    disconfirm_count REAL NOT NULL DEFAULT 0,
+    created_at       TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now')),
+    updated_at       TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now'))
+)
+
+behavior_edges(
+    matcher_id  TEXT NOT NULL,
+    behavior_id TEXT NOT NULL,
+    weight      REAL NOT NULL DEFAULT 1.0,
+    created_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now')),
+    PRIMARY KEY (matcher_id, behavior_id),
+    FOREIGN KEY (matcher_id)  REFERENCES behavior_matchers(id) ON DELETE CASCADE,
+    FOREIGN KEY (behavior_id) REFERENCES behaviors(id)         ON DELETE CASCADE
+)
+
+behavior_provenance(
+    id          TEXT PRIMARY KEY,
+    behavior_id TEXT NOT NULL,
+    signal      TEXT NOT NULL,
+    detail      TEXT,
+    created_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now')),
+    FOREIGN KEY (behavior_id) REFERENCES behaviors(id) ON DELETE CASCADE
+)
+```
+
+## Key invariants
+
+1. **The firewall principle does NOT apply.** The LLM grading its own
+   behaviors is the point. Ham/spam is a relevance judgment, not a value
+   judgment.
+
+2. **Anti-laziness guard prevents codifying shortcuts.** Rules must encode
+   discipline, not shortcuts. The guard text is in the system prompt for all
+   host variants.
+
+3. **Same `scoreBehaviorNudge` entry point** in both host paths (opencode
+   `chat.message` hook and MCP sideband) prevents scoring drift.
+
+4. **Default behavior seeding is idempotent.** Version stamps in the
+   rationale text allow re-seeding when content changes across releases
+   without duplicating rows.
+
+5. **One embedding computation serves recall, prediction, and behavior.**
+   The prompt is embedded once at `chat.message`; three separate cosine
+   scans run against different tables.
+
+6. **Dedup at creation.** Cosine >= 0.85 for both matchers and behaviors.

package/docs/dev/features/cicd.md

@@ -0,0 +1,89 @@
+# CI/CD
+
+Thatch uses GitHub Actions for CI and publishing, plus a local release helper script. The quality gate is `mise run check` (typecheck + tests + markdownlint).
+
+## CI pipeline (.github/workflows/ci.yml)
+
+Runs on every push/PR to main. Three jobs:
+1. **Typecheck** — `bunx tsc -p tsconfig.check.json` (includes test files that the build's `tsconfig.json` excludes)
+2. **Tests** — `bun test` (bun:test framework, no network, `:memory:` DB or temp dirs)
+3. **Markdownlint** — `bunx markdownlint-cli2` on `README.md` and `docs/**/*.md` (excluding `docs/plans/**`)
+
+The CI gate is the never-merge-broken guard before a release. All three must pass.
+
+## Publish pipeline (.github/workflows/publish.yml)
+
+Triggered by pushing a `v*` tag. Publishes to npm via OIDC trusted publishing — no stored npm token.
+
+Key details:
+- `id-token: write` permission lets npm authenticate through GitHub's OIDC exchange
+- Prerequisite: a Trusted Publisher configured on npmjs.com for `@jeffober/thatch` pointing at the `sysread/thatch` repo
+- npm >= 11.5.1 required (OIDC exchange needs it). The workflow installs setup-node@v4 (node 24) and `npm install -g npm@11`
+- npm 12 shipped a sigstore bug that broke OIDC publishing; the pin prevents it
+- The workflow deliberately sets NO `registry-url`, which would write a token-expecting `.npmrc` that preempts the OIDC exchange
+
+## Release helper (bin/release)
+
+A bash script (`set -euo pipefail`) that bumps, checks, commits, tags, and pushes.
+
+Args: exactly one required: `patch | minor | major`. Anything else prints an error and exits 1.
+
+Steps:
+1. Read current version from `package.json` via `node -p`
+2. Compute next version (major resets minor/patch to 0; minor resets patch to 0)
+3. Print current/bump/next
+4. Pre-flight: if git tag `v$curr` exists, check npm registry for `@jeffober/thatch@$curr`. If npm returns E404 (tagged but not published = prior release failed), error with recovery instructions and exit 1. If npm check fails for non-404 reason, warn and proceed.
+5. Run `mise run check` (typecheck + tests + markdownlint)
+6. Bump `package.json` via `npm version $v --no-git-tag-version`
+7. Prompt `commit, tag, and push v$next? [y/N]`. On no: revert `package.json` and exit 0. On yes: git add, commit -m "v$next", tag `v$next`, push, push --tags.
+8. Print `done - CI will publish v$next to npm`
+
+## mise tasks
+
+| Task | Purpose |
+|------|---------|
+| `test` | Run the test suite (`bun test`) |
+| `test-watch` | Run tests in watch mode |
+| `coverage` | Run tests with coverage report |
+| `typecheck` | Typecheck src + tests (`bunx tsc -p tsconfig.check.json`) |
+| `lint-md` | Lint markdown docs (`bunx markdownlint-cli2`) |
+| `check` | The CI gate: typecheck + tests + markdownlint |
+| `release` | Bump version, commit, tag, push (args: `patch\|minor\|major`) |
+| `qa` | Run QA use cases (auto first, then live) |
+| `qa-dry-run` | List QA use cases without spawning opencode sessions |
+| `qa-auto` | Run only automatable QA use cases (no LLM, fast) |
+| `qa-live` | Run only live-session QA use cases (spawns opencode, costs model tokens) |
+| `cli` | Run the thatch CLI (list, show, search, forget) |
+
+`mise.toml` pins Bun 1.3.14 and sets `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true`.
+
+## Development tooling
+
+- **Bun 1.3.14** (pinned via mise)
+- **TypeScript** with `tsconfig.check.json` for typecheck (includes test files; build's `tsconfig.json` excludes them)
+- **bun:test** framework (no network, `:memory:` DB or temp dirs, mock embeddings)
+- **markdownlint-cli2** with custom config (`.markdownlint-cli2.jsonc`): disables MD013 (line length), MD032 (blanks around lists), MD036 (emphasis as heading), MD060 (table alignment). Keeps MD040 (code-block language), MD047 (trailing newline), heading hierarchy.
+- **Zod** for tool schema validation and JSON Schema generation (`src/tool-defs.ts`)
+
+## Interactions with other features
+
+- QA system ([qa-system.md](qa-system.md)): `mise run qa` runs the QA use cases
+- All features: `mise run check` is the gate that validates everything before release
+
+## Source files
+
+- `.github/workflows/ci.yml` — CI pipeline
+- `.github/workflows/publish.yml` — publish pipeline (OIDC)
+- `bin/release` — release helper script
+- `mise.toml` — task definitions, tool pins, env vars
+- `.markdownlint-cli2.jsonc` — markdownlint config
+- `tsconfig.check.json` — typecheck config (includes tests)
+
+## Key invariants
+
+- `mise run check` (typecheck + tests + markdownlint) must pass before any release. The release helper enforces this in step 5.
+- OIDC publishing uses no stored npm token. The workflow sets NO `registry-url` because it would write a token-expecting `.npmrc` that preempts the OIDC exchange.
+- npm is pinned to 11.x. npm 12 shipped a sigstore bug that broke OIDC publishing.
+- The release helper checks for tagged-but-not-published state (tag exists, npm returns E404) and refuses to proceed with recovery instructions.
+- CI runs on push/PR to main. Publish runs only on `v*` tags. The release helper bridges them: tag + push triggers publish.
+- `tsconfig.check.json` includes test files for typecheck. The build's `tsconfig.json` excludes them.