@jeffober/thatch 0.1.28 → 0.1.30

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.

package/docs/dev/features/cli.md

@@ -0,0 +1,81 @@
+# CLI (bin/thatch)
+
+The thatch CLI is a Bun script at `bin/thatch`. It provides memory inspection, MCP server startup, hook commands for MCP hosts, and the setup installer.
+
+## Subcommands
+
+15 subcommands:
+
+| Command | Args | Flags | Stdin | Purpose |
+|---------|------|-------|-------|---------|
+| `stores` | none | none | none | List all store names |
+| `list [store]` | optional store | none | none | List memory labels in a store |
+| `show <label> [store]` | label, optional store | none | none | Display one memory by label |
+| `forget <label> [store]` | label, optional store | none | none | Delete one memory by label |
+| `search <query> [store]` | query, optional store | none | none | Semantic cosine search (limit 10; "all" searches project + global) |
+| `mcp` | none | none | none | Start the stdio MCP server (for Claude Code, Cursor) |
+| `reminder [--json]` | none | `--json` | none | Print session-start reminder + hygiene report |
+| `hygiene` | none | none | none | Print the hygiene report standalone |
+| `prime` | none | none | none | Run thatch-project-primer skill via opencode/agent/claude CLI |
+| `buffer-batch` | none | none | JSON | Append PostToolBatch payload to queue (Claude Code hook) |
+| `buffer-tool` | none | none | JSON | Append single postToolUse interaction to queue (Cursor hook) |
+| `flush-tools [--json]` | none | `--json` | JSON | Peek queue + extraction/recall/prediction/behavior/write nudge |
+| `flush-predictions [--json]` | none | `--json` | JSON | Standalone prediction-only nudge |
+| `setup --claude [--cursor] [--global]` | none | `--claude`, `--cursor`, `--global` | none | Install config + instructions + hooks + skills |
+| (unknown) | none | none | none | Print usage, exit 1 |
+
+## Global behavior
+
+- No `--version`, `--help`, `-h`, or short flags. No subcommand aliases.
+- Unknown command or missing required arg calls `usage()` and exits 1.
+- Args are positional, parsed by hand from `process.argv.slice(2)`. No arg-parsing library.
+- DB opened once at startup, closed at end (except `mcp` which closes early).
+- Stores default to git remote detected by `detectRepo()`; "unknown" on failure. "global" is the shared store. "all" (search only) means project + global.
+
+## prime
+
+Runs the thatch-project-primer skill via an external CLI. Searches `PATH` in order: `opencode`, `agent` (Cursor CLI), `claude`. Uses the first found:
+- opencode: `opencode run "<primer prompt>"`
+- agent: `agent -p "<primer prompt>" --approve-mcps`
+- claude: `claude "<primer prompt>"`
+
+Inherits stdio, exits with the child's exit code. Errors and exits 1 if none found.
+
+## Environment variables
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `XDG_CONFIG_HOME` | Config home base | `~/.config` |
+| `THATCH_DB_PATH` | SQLite DB file location | `$XDG_CONFIG_HOME/thatch/thatch.db` |
+| `THATCH_MODEL` | Embedding model override | `Xenova/bge-small-en-v1.5` |
+| `THATCH_RECALL_THRESHOLD` | Cosine cutoff for recall nudge | `0.55` |
+| `THATCH_PREDICTION_THRESHOLD` | Cutoff for prediction auto-fire | `0.60` |
+| `THATCH_BEHAVIOR_THRESHOLD` | Cutoff for behavior auto-fire | `0.60` |
+| `CLAUDE_PROJECT_DIR` | Claude Code project dir | `process.cwd()` |
+| `CURSOR_PROJECT_DIR` | Cursor project dir | falls through |
+| `CLAUDE_CONFIG_DIR` | Claude config dir | `~/.claude` |
+| `CURSOR_CONFIG_DIR` | Cursor config dir | `~/.cursor` |
+| `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS` | Enable async extraction | unset |
+
+## Source files
+
+- `bin/thatch` — the CLI (Bun script, 486 lines)
+- `bin/release` — release helper (bash, separate from the main CLI)
+
+## Interactions with other features
+
+- Memory store ([memory-store.md](memory-store.md)): `stores`, `list`, `show`, `forget`, `search` subcommands
+- Setup ([setup.md](setup.md)): `setup` subcommand
+- Nudge pipeline ([nudge-pipeline.md](nudge-pipeline.md)): `flush-tools`, `flush-predictions`, `reminder` subcommands
+- Extraction ([extraction.md](extraction.md)): `buffer-batch`, `buffer-tool`, `flush-tools` subcommands
+- Hygiene ([hygiene.md](hygiene.md)): `hygiene`, `reminder` subcommands
+- Multi-host ([multi-host.md](multi-host.md)): `mcp` subcommand starts the MCP server for Claude Code and Cursor
+
+## Key invariants
+
+- No arg-parsing library. Args are positional, parsed by hand from `process.argv.slice(2)`.
+- No `--version`, `--help`, `-h`, or short flags. No subcommand aliases.
+- DB opened once at startup, closed at end (except `mcp` which closes early).
+- Store name auto-detected from git remote. "global" is the shared store. "all" (search only) means project + global.
+- Unknown command or missing required arg calls `usage()` and exits 1.
+- `prime` searches PATH in order: `opencode`, `agent`, `claude`. Uses the first found.

package/docs/dev/features/compaction-recovery.md

@@ -0,0 +1,48 @@
+# Compaction Recovery (opencode)
+
+opencode compacts long sessions by generating a summary and replacing the conversation history. Without intervention, a compacted session would lose awareness of thatch -- the agent would stop using memory tools, extraction would stop, and nudges would fire during summary generation where tools are blocked.
+
+## What it does
+
+- Suppresses nudges during compaction (tools are blocked during summary generation)
+- Injects compaction context so the agent retains awareness of thatch after compaction
+- Clears the compacting flag on success (three mechanisms, belt-and-suspenders)
+- Handles compaction failure (clears stale flag if autocontinue never fired)
+
+## How it works
+
+### Four hooks/events
+
+1. **experimental.session.compacting** (hook) -- fires when opencode starts compacting. Adds sessionID to the `compacting` set. Pushes `compactionContext(repo)` into `output.context`. The context tells the agent to preserve what's been learned and decided this session so there's continuity after compaction.
+
+2. **experimental.compaction.autocontinue** (hook) -- fires after compaction succeeds and the auto-continue turn fires. Removes sessionID from the `compacting` set so nudges resume.
+
+3. **session.compacted** (event) -- fires on successful compaction. Clears the `compacting` flag. Belt-and-suspenders: if autocontinue didn't fire or wasn't installed, the event still clears the flag.
+
+4. **Compaction failure fallback** (chat.message hook) -- if a non-compaction chat.message arrives while the session is in the `compacting` set, compaction failed (autocontinue never fired). The hook clears the stale `compacting` flag and proceeds normally. Without this, the session would be stuck with nudges off forever.
+
+### Why nudges are suppressed during compaction
+
+During summary generation, tools are blocked. A nudge that instructs the agent to use `thatch_memory_recall` or `thatch_memory_remember` would cause a blocked-tool error. The `compacting` set is checked at the top of the chat.message hook -- if the session is compacting, all nudges are skipped.
+
+### Compaction context
+
+`compactionContext(repo)` in `src/prompts.ts` generates text that tells the agent: you are using thatch, here's what you've learned and decided this session, preserve this context after compaction. This is pushed into `output.context` (not `output.system`) so it's part of the compaction output, not the permanent system prompt.
+
+## Interactions with other features
+
+- Nudge pipeline ([nudge-pipeline.md](nudge-pipeline.md)): compaction guard is the first check in the chat.message hook; suppresses all 4 tiers
+- Session lifecycle ([session-lifecycle.md](session-lifecycle.md)): `session.compacted` event is handled in the event handler
+- Multi-host ([multi-host.md](multi-host.md)): compaction recovery is opencode-only. Claude Code and Cursor do not have this feature. Mitigation: `CLAUDE.md`/`AGENTS.md` persists through compaction, and SessionStart hooks fire after compaction.
+
+## Source files
+
+- `src/index.ts` -- all four hooks/events (experimental.session.compacting, experimental.compaction.autocontinue, session.compacted event, chat.message compaction guard)
+- `src/prompts.ts` -- compactionContext function
+
+## Key invariants
+
+- The `compacting` set is checked at the top of chat.message. If set, all nudges are skipped.
+- Three mechanisms clear the flag (autocontinue, session.compacted event, chat.message fallback). Belt-and-suspenders.
+- Compaction failure fallback: a non-compaction message during compacting = compaction failed. Clear and proceed.
+- opencode-only feature. MCP hosts rely on static instructions persisting through compaction.