@jeffober/thatch 0.1.9 → 0.1.11

package/README.md

@@ -2,18 +2,23 @@
 
 [![CI](https://github.com/sysread/thatch/actions/workflows/ci.yml/badge.svg)](https://github.com/sysread/thatch/actions/workflows/ci.yml)
 
-Persistent memory and operational methodology for AI coding agents — local
-embeddings, SQLite stores, zero config.
+## Synopsis
+
+Persistent memory and useful dev skills for AI coding agents that requires zero
+manual config.
 
 Works with **OpenCode** (as a plugin), **Claude Code** (as an MCP server), and
 **Cursor** (as an MCP server).
+
 Each session inherits the accumulated knowledge of every session before it —
 project architecture, conventions, gotchas, user preferences — so your agent
-starts with context instead of a blank slate. Stores are per-repo with a
-shared `global` store. On top of the memory layer, thatch ships a suite of
-skills that prime, maintain, and reflect on memory, plus a structured
-multi-agent code review framework. No API keys, no cloud services —
-everything runs on your machine.
+starts with context instead of a blank slate. Stores are per-repo with a shared
+`global` store.
+
+On top of the memory layer, thatch ships a suite of skills for managing memories,
+performing in-depth, structured code reviews, and researching your code base.
+
+No API keys, no cloud services; everything runs on your machine.
 
 ## Quick start
 
@@ -118,6 +123,8 @@ agent follows to maintain its own memory and review code systematically.
 | `thatch-review-no-slop` | AI writing anti-pattern detection — change narration, fourth wall breaks, hedging |
 | `thatch-review-breadcrumbs` | Comment narrative — do comments form a coherent outline of the code's behavior? |
 | `thatch-review-synthesizer` | Verify specialist findings against actual code, deduplicate, produce severity-grouped report |
+| `thatch-review-context` | Gather project/feature context (PRs, tickets, TODOs, deferred work) before a review |
+| `thatch-workflow-research` | Research code workflows affected by a change or planned change, before reviewing or planning |
 | `thatch-code-review` | Multi-agent review coordinator — triage, partition, dispatch specialists in parallel (opencode only) |
 
 The five review specialists run independently and can be used standalone. The
@@ -142,7 +149,7 @@ thatch prime                     Prime project memory (runs via opencode or clau
 thatch mcp                       Start the stdio MCP server (for Claude Code)
 thatch reminder                  Print session-start reminder (for hooks)
 thatch hygiene                   Print the hygiene report (standalone)
-thatch setup --claude [--global] Install config + instructions + hooks + skills
+thatch setup --claude [--cursor] [--global] Install config + instructions + hooks + skills
 ```
 
 Stores default to the repo detected from `git remote`. Use `global` for the
@@ -190,17 +197,18 @@ buffer and flush. On Claude Code, `PostToolBatch` and `UserPromptSubmit`
 hooks drive a file-backed queue. Both paths produce the same payload for the
 fact-extractor skill.
 
-## OpenCode vs Claude Code parity
-
-| Feature | OpenCode (plugin) | Claude Code (MCP + hooks) |
-|---------|-------------------|--------------------------|
-| Tools | Plugin tool registration | MCP `tools/list` + `tools/call` |
-| System prompt | Injected at runtime with repo name | Static CLAUDE.md (repo auto-detected by MCP server) |
-| Session-start reminder | `session.created` event | `SessionStart` hook → `thatch reminder` |
-| Compaction context | `experimental.session.compacting` hook | **Gap**: no equivalent (CLAUDE.md persists through compaction) |
-| Extraction nudge | `tool.execute.after` + `chat.message` | `PostToolBatch` + `UserPromptSubmit` (file-backed queue) |
-| Skills | `$XDG_CONFIG_HOME/opencode/skills` | `~/.claude/skills/` |
-| Store detection | `worktree` param from plugin | `CLAUDE_PROJECT_DIR` env var |
+## OpenCode vs Claude Code vs Cursor parity
+
+| Feature | OpenCode (plugin) | Claude Code (MCP + hooks) | Cursor (MCP + hooks) |
+|---------|-------------------|--------------------------|---------------------|
+| Tools | Plugin tool registration | MCP `tools/list` + `tools/call` | MCP `tools/list` + `tools/call` |
+| System prompt | Injected at runtime with repo name | Static CLAUDE.md (repo auto-detected by MCP server) | Static AGENTS.md (repo auto-detected at startup) |
+| Session-start reminder | `session.created` event | `SessionStart` hook → `thatch reminder` | `sessionStart` hook → `thatch reminder --json` |
+| Compaction context | `experimental.session.compacting` hook | **Gap**: no equivalent (CLAUDE.md persists) | **Gap**: no equivalent |
+| Extraction nudge | `tool.execute.after` + `chat.message` | `PostToolBatch` + `UserPromptSubmit` (file-backed queue) | `postToolUse` + `beforeSubmitPrompt` (file-backed queue) |
+| Setup detection at startup | n/a (plugin auto-installs) | `checkSetup` in MCP server: detects missing/broken instructions | Same as Claude Code |
+| Skills | 13 (shared + coordinator) | 12 (shared only) | 12 (shared only) |
+| Store detection | `worktree` param from plugin | `CLAUDE_PROJECT_DIR` env var | `CURSOR_PROJECT_DIR` then `CLAUDE_PROJECT_DIR` |
 
 See [docs/dev/mcp-parity.md](docs/dev/mcp-parity.md) for the full analysis.
 

package/docs/dev/mcp-parity.md

@@ -26,6 +26,7 @@ This document maps the feature parity and documents the remaining gaps.
 | **Prompt-aware recall nudge** | `chat.message` hook embeds the prompt with the in-process warm model, searches `db.search()`, pushes a nudge part if matches ≥ threshold | `UserPromptSubmit` hook → `thatch flush-tools` connects to the MCP server's sideband socket; the warm server embeds + searches; hook prints the nudge or falls back to the write nudge | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — sideband socket gives cold hook processes access to the warm MCP server's model |
 | **Skills** | Installed to `$XDG_CONFIG_HOME/opencode/skills` at plugin init (shared **+** opencode-only) | Installed to `$CLAUDE_CONFIG_DIR/skills/` by `thatch setup` (shared only) | Installed to `~/.cursor/skills/` by `thatch setup` (shared only) | **Full** — same SKILL.md format; the code-review coordinator is opencode-only (needs sub-agents) |
 | **Store detection** (repo identity from git remote) | `worktree` parameter from the opencode plugin | `CLAUDE_PROJECT_DIR` env (set by Claude Code for stdio MCP servers) | `CURSOR_PROJECT_DIR` then `CLAUDE_PROJECT_DIR` then cwd | **Full** |
+| **Setup detection at startup** | n/a — plugin auto-installs at init | `checkSetup` in MCP server: detects missing or broken instructions in CLAUDE.md | Same as Claude Code (checks AGENTS.md) | **Full** — warns the agent to tell the user to run `thatch setup` |
 | **Hook config format** | n/a — plugin registers hooks in code | Nested: `.claude/settings.json` `{hooks:{Event:{hooks:[{type,command}]}}}` | Flat: `.cursor/hooks.json` `{version:1,hooks:{event:[{command}]}}` | n/a |
 
 ## Tool name conventions

package/docs/dev/setup-and-hooks.md

@@ -132,3 +132,39 @@ All setup operations are idempotent:
 `thatch setup` resolves `<bin>` from PATH, falling back to the absolute path of
 the running script. This is baked into every installed hook command, so the
 hooks keep working after the session that ran setup ends.
+
+## Setup detection at MCP startup
+
+When the MCP server starts (`thatch mcp`, spawned by Claude Code or Cursor),
+it calls `checkSetup` (`src/setup.ts`) to verify that `thatch setup` was run
+for the current host. This catches two failure modes that would otherwise leave
+the agent without usage instructions:
+
+### Host detection
+
+The host is determined from env vars set by the host process:
+
+- `CURSOR_PROJECT_DIR` set → Cursor
+- `CLAUDE_PROJECT_DIR` set (and Cursor not) → Claude Code
+- Neither set → returns `null` (no check — manual `thatch mcp` invocation)
+
+Cursor takes priority because Cursor also sets `CLAUDE_PROJECT_DIR` as an alias.
+
+### What it checks
+
+`checkSetup` looks for the instruction markers (start and end) in the host's
+instructions file — `CLAUDE.md` for Claude Code, `AGENTS.md` for Cursor. It
+checks local (in the project directory) first, then global (in the config
+directory). Local takes priority.
+
+### Three outcomes
+
+| Outcome | Condition | Action |
+|---------|-----------|--------|
+| **installed** | Markers found in local or global instructions file | No warning — setup is complete |
+| **not-installed** | No instructions file with markers found anywhere | Warning to stderr + prepended to first `tools/call` response: "Tell the user to run `thatch setup --<host>`" |
+| **markers-broken** | Start marker found but end marker missing (file edited externally) | Warning with the specific file path and fix instructions: run `thatch setup`, or manually remove the corrupted block and re-run |
+
+The warning is cleared after the first `tools/call` response so it surfaces
+once, not on every tool call. The message instructs the LLM to notify the user
+with the specific `thatch setup` command to run.

package/docs/dev/skills.md

@@ -21,9 +21,9 @@ description: Extract durable project facts ... Use when ...
 - `description` drives when the agent loads the skill (both opencode and
   Cursor auto-discover skills and use the description for relevance).
 
-## The 12 skills
+## The 13 skills
 
-**Shared (11)** — installed everywhere; no sub-agents required:
+**Shared (12)** — installed everywhere; no sub-agents required:
 
 | Skill | Role |
 |-------|------|
@@ -37,13 +37,14 @@ description: Extract durable project facts ... Use when ...
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of behavior? |
 | `thatch-review-synthesizer` | Verify specialist findings against code, dedupe, classify, calibrate severity. |
 | `thatch-review-context` | Gather project/feature context (PR descriptions, git archaeology, ticket references, memory) before fan-out. Prevents false positives about intentionally deferred work. |
+| `thatch-workflow-research` | Research code workflows/features affected by a change or planned change. Reads code flows, comments, git history, memories, docs. Produces a guide to the code for reviewers or planners. |
 | `thatch-session-reflection` | End-of-session memory recording (project, user, tools, self). |
 
 **opencode-only (1)** — the coordinator needs sub-agent support:
 
 | Skill | Role |
 |-------|------|
-| `thatch-code-review` | Resolve review target, gather context, estimate complexity, partition, dispatch the 5 specialists in parallel, synthesize. |
+| `thatch-code-review` | Resolve review target, gather project context, research affected workflows, estimate complexity, partition, dispatch the 5 specialists in parallel, synthesize. |
 
 ## REVIEW_COMMON
 
@@ -61,6 +62,10 @@ The five review specialists share a framework interpolated via `${REVIEW_COMMON}
 - **Project context awareness** — if a context brief is provided (from the
   coordinator or from loading `thatch-review-context`), use it to avoid false
   positives about intentionally deferred work.
+- **Workflow context awareness** — if a workflow guide is provided (from the
+  coordinator or from loading `thatch-workflow-research`), use it to understand
+  the purpose and evolution of the code, distinguishing intentional behavior
+  and long-standing design decisions from new issues.
 - **TODO ($ticket) markers** — recognize `TODO ($TICKET-ID): ...` as legitimate
   breadcrumbs for deferred work, not stale artifacts. Flag only if the referenced
   ticket is closed or merged.
@@ -73,7 +78,7 @@ The synthesizer reuses the same verification rigor but has its own structure
 ## The two arrays
 
 ```ts
-const SHARED_SKILLS: SkillDef[] = [ /* 11 skills above */ ];
+const SHARED_SKILLS: SkillDef[] = [ /* 12 skills above */ ];
 const OPENCODE_ONLY_SKILLS: SkillDef[] = [ /* code-review coordinator */ ];
 ```
 
@@ -107,8 +112,7 @@ and `--cursor` pass only the shared set.
 ## Memory review skills in practice
 
 - **Quick single lens**: load any specialist directly and point it at a branch.
-- **Full review on opencode**: load `thatch-code-review` — it gathers project context, dispatches all 5
-  specialists in parallel (with context injected into each briefing), then synthesizes.
+- **Full review on opencode**: load `thatch-code-review` — it gathers project context, researches affected workflows, dispatches all 5 specialists in parallel (with both the context brief and workflow guide injected into each briefing), then synthesizes.
 - **Full review on Claude Code/Cursor**: run each specialist in sequence, then
   run `thatch-review-synthesizer` to verify and aggregate.
 

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

@@ -26,6 +26,7 @@ file/IPC/CLI contracts ready to graduate into `bun:test` integration tests.
 | [UC-015](UC-015-env-override-matrix.md) | `THATCH_DB_PATH`, `XDG_CONFIG_HOME`, `CLAUDE_CONFIG_DIR`, `THATCH_QUEUE_DIR`, `THATCH_RECALL_THRESHOLD`, `THATCH_MODEL` |
 | [UC-016](UC-016-concurrent-session-isolation.md) | Per-session extraction isolation (in-memory + file queue); shared stateless sideband |
 | [UC-017](UC-017-buffer-tool-vs-buffer-batch.md) | `buffer-batch` (Claude, `tool_calls[]`+`session_id`) vs `buffer-tool` (Cursor, single+`conversation_id`) |
+| [UC-018](UC-018-mcp-startup-setup-detection.md) | MCP startup detects missing/broken setup instructions and warns the agent |
 
 ## Template
 

package/docs/qa/use-cases/UC-005-setup-install.md

@@ -17,12 +17,12 @@
   appends a thatch block to `CLAUDE.md` bracketed by start/end markers (replaced, not
   duplicated, on re-run), writes `.claude/settings.json` hooks (`SessionStart` -> `thatch reminder`,
   `PostToolBatch` -> `thatch buffer-batch`, `UserPromptSubmit` -> `thatch flush-tools`), and installs
-  **10 shared skills** (no code-review coordinator) to `$CLAUDE_CONFIG_DIR/skills/` — user-scoped
+  **12 shared skills** (no code-review coordinator) to `$CLAUDE_CONFIG_DIR/skills/` — user-scoped
   even in project-local mode.
 - `--cursor` project-local writes `.cursor/mcp.json`, appends to `AGENTS.md`, writes
   `.cursor/hooks.json` in the **flat format** (`{version:1, hooks:{...}}`): `sessionStart` ->
   `thatch reminder --json`, `postToolUse` -> `thatch buffer-tool`, `beforeSubmitPrompt` ->
-  `thatch flush-tools --json`; and installs 10 shared skills to `~/.cursor/skills/`.
+  `thatch flush-tools --json`; and installs 12 shared skills to `~/.cursor/skills/`.
 - Re-run is idempotent: instructions are not duplicated, thatch hooks are replaced (not appended),
   and non-thatch hooks are preserved. A legacy `thatch echo` hook is replaced with `flush-tools`.
 - `--global` (Claude) writes `~/.claude/CLAUDE.md` + `~/.claude/settings.json` but **no project

package/docs/qa/use-cases/UC-014-skill-install-drift.md

@@ -13,16 +13,16 @@
 5. Check whether the `thatch-code-review` coordinator skill is present.
 
 **Expected**
-- Claude Code and Cursor install exactly **10 shared skills** to the skills
+- Claude Code and Cursor install exactly **12 shared skills** to the skills
   dir — the coordinator (`thatch-code-review`) is **absent** (it needs
   sub-agents, which those hosts lack).
-- opencode installs **11** — the 10 shared plus the coordinator.
+- opencode installs **13** — the 12 shared plus the coordinator.
 - The locally edited `SKILL.md` is **overwritten** with the canonical content
   on the next `setup`/init (drift detection: a file is only rewritten when its
   content differs from the definition). Unrelated skill files are untouched.
 - Skills never land in the worktree — always under the user-scoped config dir
   (`~/.claude/skills`, `~/.cursor/skills`, `$XDG_CONFIG_HOME/opencode/skills`).
 
-_Automatable: yes — file presence, count (10 vs 11), content-diff-overwrite, and
+_Automatable: yes — file presence, count (12 vs 13), content-diff-overwrite, and
 coordinator host-gating are all file assertions (`setup.test.ts` already covers
 the unit contract)._

package/docs/qa/use-cases/UC-018-mcp-startup-setup-detection.md

@@ -0,0 +1,38 @@
+# UC-018: MCP startup setup detection
+
+**Preconditions**
+- Thatch installed and `bun` on PATH
+- MCP server launched by Claude Code (`thatch mcp` with `CLAUDE_PROJECT_DIR` set)
+  or Cursor (`thatch mcp` with `CURSOR_PROJECT_DIR` set)
+
+**Steps**
+1. Start a Claude Code session in a project where `thatch setup --claude` was
+   never run (no `CLAUDE.md` with thatch markers, neither local nor global).
+2. Call any thatch tool (e.g. `mcp__thatch__store_list`).
+3. Repeat in a project where setup was run but `CLAUDE.md` was edited externally
+   and the thatch block's end marker was deleted.
+4. Repeat in a project where setup was run correctly.
+5. Repeat all steps for Cursor (substituting `--cursor`, `AGENTS.md`,
+   `CURSOR_PROJECT_DIR`).
+
+**Expected**
+- **Not-installed**: The first `tools/call` response is prepended with a
+  warning: "[thatch] Thatch is running as an MCP server but has not been set
+  up for Claude Code. ... Tell the user to run: thatch setup --claude". The
+  warning also appears on stderr. Subsequent tool responses are clean (warning
+  is one-shot).
+- **Markers-broken**: The first `tools/call` response is prepended with a
+  warning naming the corrupted file and instructing the user to run
+  `thatch setup` (or manually remove the corrupted block and re-run).
+- **Installed**: No warning. Tool responses are clean from the first call.
+- **Cursor**: Same behavior, with "Cursor" substituted for "Claude Code" and
+  `thatch setup --cursor` in the message. When both `CURSOR_PROJECT_DIR` and
+  `CLAUDE_PROJECT_DIR` are set, Cursor detection takes priority.
+- **No env var**: When neither `CURSOR_PROJECT_DIR` nor `CLAUDE_PROJECT_DIR` is
+  set (manual `thatch mcp` invocation), `checkSetup` returns `null` and no
+  warning is emitted.
+
+_Automatable: yes — `setup.test.ts` already covers the unit contract (10 tests
+in the `checkSetup` describe block: null, local, global, not-installed,
+markers-broken, local priority, Cursor variants, Cursor priority). This is the
+end-to-end runbook version._

package/docs/user/README.md

@@ -114,6 +114,17 @@ Beyond the tools, thatch hooks into opencode itself:
 - **Compaction context.** When opencode compacts a long session, thatch injects
   a reminder so the summarized session still knows memory tools exist.
 
+### Setup detection (Claude Code and Cursor)
+
+When the MCP server starts (Claude Code or Cursor), it checks whether
+`thatch setup` was run for the current host by looking for the instruction
+markers in `CLAUDE.md` (Claude Code) or `AGENTS.md` (Cursor). It checks local
+first (in the project directory), then global (in the config directory). If
+setup was never run, or if the instruction markers are broken (e.g. the file
+was edited externally and the thatch block was partially modified), the server
+emits a warning to stderr and prepends it to the first tool response so the
+agent can tell the user to run `thatch setup`.
+
 ## Skills
 
 On startup thatch installs [skills] into your global opencode config
@@ -143,6 +154,8 @@ Five specialist review lenses, each a self-contained static-analysis pass:
 | `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth wall breaks, em dashes, hedging, filler. |
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of the code's behavior? |
 | `thatch-review-synthesizer` | Verifies and synthesizes findings from multiple specialists into a single deduplicated, severity-grouped report. |
+| `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. |
 
 ### opencode-only skills
 
@@ -152,12 +165,13 @@ Five specialist review lenses, each a self-contained static-analysis pass:
 
 ### Host availability
 
-| Skill | opencode | Claude Code |
-|-------|----------|-------------|
-| Memory skills (4) | Yes | Yes |
-| Review specialists (5) | Yes | Yes |
-| Review synthesizer | Yes | Yes |
-| Code review coordinator | Yes | No (requires sub-agents) |
+| Skill | opencode | Claude Code | Cursor |
+|-------|----------|-------------|--------|
+| Memory skills (4) | Yes | Yes | Yes |
+| Review specialists (5) | Yes | Yes | Yes |
+| Review synthesizer | Yes | Yes | Yes |
+| Review context + workflow research | Yes | Yes | Yes |
+| Code review coordinator | Yes | No (requires sub-agents) | No (requires sub-agents) |
 
 ### Using review skills
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "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

@@ -9,6 +9,7 @@ export interface MemoryRow {
   model: string | null;
   branch: string | null;
   confidence: number | null;
+  archived: boolean;
   created_at: string;
   updated_at: string;
   recall_count: number;
@@ -69,6 +70,7 @@ export class ThatchDB {
         model     TEXT,
         branch    TEXT,
         confidence INTEGER,
+        archived  INTEGER 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')),
         recall_count INTEGER NOT NULL DEFAULT 0,
@@ -102,6 +104,7 @@ export class ThatchDB {
     const wanted: [string, string][] = [
       ["recall_count", "INTEGER NOT NULL DEFAULT 0"],
       ["last_recalled_at", "TEXT"],
+      ["archived", "INTEGER NOT NULL DEFAULT 0"],
     ];
     for (const [col, decl] of wanted) {
       if (!existing.has(col)) {
@@ -170,27 +173,23 @@ export class ThatchDB {
     content: string,
     embedding: Float32Array,
     model: string,
-    opts?: { branch?: string; confidence?: number; overwrite?: boolean },
+    opts?: { branch?: string; confidence?: number; overwrite?: boolean; archived?: boolean },
   ): { ok: true } | { ok: false; error: string } {
     const slug = this.slugify(label);
     this.ensureStore(store);
 
-    // The embedding may be a view into a larger buffer (transformers.js tensor
-    // output); serialize exactly the view's bytes, not the whole backing buffer.
     const blob = new Uint8Array(embedding.buffer, embedding.byteOffset, embedding.byteLength);
     const branch = opts?.branch ?? null;
     const confidence = opts?.confidence ?? null;
+    const archived = opts?.archived === true ? 1 : (opts?.archived === false ? 0 : null);
     const now = new Date().toISOString();
-    const params = [slug, store, label, content, blob, model, branch, confidence, now, now];
 
     if (!opts?.overwrite) {
-      // Plain INSERT so the PK constraint enforces no-clobber atomically —
-      // a check-then-upsert would race against concurrent sessions.
       try {
         this.#db.run(
-          `INSERT INTO entries (slug, store, label, content, embedding, model, branch, confidence, created_at, updated_at)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-          params as any,
+          `INSERT INTO entries (slug, store, label, content, embedding, model, branch, confidence, archived, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+          [slug, store, label, content, blob, model, branch, confidence, archived ?? 0, now, now] as any,
         );
         return { ok: true };
       } catch (err: any) {
@@ -205,10 +204,25 @@ export class ThatchDB {
       }
     }
 
+    const existing = this.#db
+      .query("SELECT archived FROM entries WHERE slug = ? AND store = ?")
+      .get(slug, store) as { archived: number } | null;
+
+    if (existing && existing.archived && opts?.archived === undefined) {
+      return {
+        ok: false,
+        error: `"${label}" is archived. Pass archived: true to keep it archived, or archived: false to unarchive it.`,
+      };
+    }
+
+    // archived column for upsert: the INSERT VALUES always needs a non-null
+    // value (NOT NULL constraint), so use archived ?? 0. To preserve the
+    // existing value when the caller doesn't specify archived, the UPDATE
+    // clause accepts a nullable extra param: NULL means "keep existing."
     this.#db.run(
       `
-      INSERT INTO entries (slug, store, label, content, embedding, model, branch, confidence, created_at, updated_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      INSERT INTO entries (slug, store, label, content, embedding, model, branch, confidence, archived, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(slug, store) DO UPDATE SET
         label = excluded.label,
         content = excluded.content,
@@ -216,13 +230,12 @@ export class ThatchDB {
         model = excluded.model,
         branch = COALESCE(excluded.branch, entries.branch),
         confidence = COALESCE(excluded.confidence, entries.confidence),
+        archived = COALESCE(?, entries.archived),
         updated_at = excluded.updated_at
       `,
-      params as any,
+      [slug, store, label, content, blob, model, branch, confidence, archived ?? 0, now, now, archived] as any,
     );
 
-    // Content changed, so prior dedup verdicts involving this entry are stale;
-    // clear them so findDuplicates can re-flag the pair.
     this.#db.run(
       "DELETE FROM dedup_pairs WHERE store = ? AND (slug_a = ? OR slug_b = ?)",
       [store, slug, slug],
@@ -242,22 +255,25 @@ export class ThatchDB {
   search(
     stores: string[],
     queryEmbedding: Float32Array,
-    opts?: { branch?: string; limit?: number },
+    opts?: { branch?: string; limit?: number; includeArchived?: boolean },
   ): (MemoryRow & { _score: number })[] {
     if (stores.length === 0) return [];
 
     const limit = opts?.limit ?? 10;
     const branch = opts?.branch;
+    const includeArchived = opts?.includeArchived ?? false;
 
     const placeholders = stores.map(() => "?").join(", ");
 
     interface SqlParams { sql: string; params: any[] }
 
     const { sql, params }: SqlParams = (() => {
+      const clauses = ["store IN (" + placeholders + ")", "embedding IS NOT NULL"];
+      if (!includeArchived) clauses.push("archived = 0");
       const base = `
-        SELECT slug, store, label, content, embedding, model, branch, confidence, created_at, updated_at, recall_count, last_recalled_at
+        SELECT slug, store, label, content, embedding, model, branch, confidence, archived, created_at, updated_at, recall_count, last_recalled_at
         FROM entries
-        WHERE store IN (${placeholders}) AND embedding IS NOT NULL
+        WHERE ${clauses.join(" AND ")}
       `;
 
       if (branch) {
@@ -278,6 +294,7 @@ export class ThatchDB {
     // rather than ranked. Dimension is the discriminator — model tags are
     // informational only.
     const scored = rows.flatMap((row) => {
+      row.archived = !!row.archived;
       const emb = blobToVector(row.embedding!);
       if (emb.length !== queryEmbedding.length) return [];
       return [{ ...row, embedding: row.embedding, _score: cosineSimilarity(queryEmbedding, emb) }];
@@ -295,7 +312,7 @@ export class ThatchDB {
   recall(
     stores: string[],
     queryEmbedding: Float32Array,
-    opts?: { branch?: string; limit?: number },
+    opts?: { branch?: string; limit?: number; includeArchived?: boolean },
   ): (MemoryRow & { _score: number })[] {
     const top = this.search(stores, queryEmbedding, opts);
 
@@ -326,7 +343,7 @@ export class ThatchDB {
     const limit = opts?.limit ?? 3;
 
     const rows = this.#db
-      .query("SELECT slug, label, embedding FROM entries WHERE store = ? AND embedding IS NOT NULL")
+      .query("SELECT slug, label, embedding FROM entries WHERE store = ? AND archived = 0 AND embedding IS NOT NULL")
       .all(store) as any[];
 
     const hits: SimilarEntry[] = [];
@@ -345,10 +362,10 @@ export class ThatchDB {
   }
 
   /** Lists all entries in a store, returning metadata without content. */
-  listEntries(store: string): { slug: string; label: string; branch: string | null; confidence: number | null; updated_at: string }[] {
+  listEntries(store: string): { slug: string; label: string; branch: string | null; confidence: number | null; archived: boolean; updated_at: string }[] {
     return this.#db
       .query(
-        "SELECT slug, label, branch, confidence, updated_at FROM entries WHERE store = ? ORDER BY label",
+        "SELECT slug, label, branch, confidence, archived, updated_at FROM entries WHERE store = ? ORDER BY label",
       )
       .all(store)
       .map((r: any) => ({
@@ -356,6 +373,7 @@ export class ThatchDB {
         label: r.label,
         branch: r.branch,
         confidence: r.confidence,
+        archived: !!r.archived,
         updated_at: r.updated_at,
       }));
   }
@@ -363,11 +381,14 @@ export class ThatchDB {
   /** Full content of a single entry by label. */
   showEntry(store: string, label: string): MemoryRow | null {
     const slug = this.slugify(label);
-    return this.#db
+    const row = this.#db
       .query(
-        "SELECT slug, store, label, content, embedding, model, branch, confidence, created_at, updated_at, recall_count, last_recalled_at FROM entries WHERE slug = ? AND store = ?",
+        "SELECT slug, store, label, content, embedding, model, branch, confidence, archived, created_at, updated_at, recall_count, last_recalled_at FROM entries WHERE slug = ? AND store = ?",
       )
-      .get(slug, store) as MemoryRow | null;
+      .get(slug, store) as Record<string, unknown> | null;
+    if (!row) return null;
+    row.archived = !!row.archived;
+    return row as unknown as MemoryRow;
   }
 
   forgetEntry(store: string, label: string): boolean {
@@ -386,7 +407,7 @@ export class ThatchDB {
   findDuplicates(store: string, threshold = 0.85): DedupCandidate[] {
     const rows = this.#db
       .query(
-        "SELECT slug, label, content, embedding FROM entries WHERE store = ? AND embedding IS NOT NULL ORDER BY slug",
+        "SELECT slug, label, content, embedding FROM entries WHERE store = ? AND archived = 0 AND embedding IS NOT NULL ORDER BY slug",
       )
       .all(store) as any[];
 
@@ -446,7 +467,7 @@ export class ThatchDB {
     const row = this.#db
       .query(
         `SELECT COUNT(*) AS n FROM entries
-         WHERE store = ? AND max(updated_at, COALESCE(last_recalled_at, updated_at)) < ?`,
+         WHERE store = ? AND archived = 0 AND max(updated_at, COALESCE(last_recalled_at, updated_at)) < ?`,
       )
       .get(store, cutoffIso) as any;
     return row?.n ?? 0;
@@ -465,7 +486,7 @@ export class ThatchDB {
     if (branches.length === 0) return 0;
     const placeholders = branches.map(() => "?").join(", ");
     const row = this.#db
-      .query(`SELECT COUNT(*) AS n FROM entries WHERE store = ? AND branch IN (${placeholders})`)
+      .query(`SELECT COUNT(*) AS n FROM entries WHERE store = ? AND archived = 0 AND branch IN (${placeholders})`)
       .get(store, ...branches) as any;
     return row?.n ?? 0;
   }

package/src/mcp.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { ThatchDB } from "./db";
 import { BgeEmbeddingModel } from "./embeddings";
 import { detectRepo } from "./git";
+import { checkSetup } from "./setup";
 import { TOOL_DEFS, type CoreContext, type ToolDef } from "./tool-defs";
 import { SidebandServer, sidebandSocketPath } from "./sideband";
 
@@ -99,6 +100,17 @@ export async function runMcpServer(): Promise<void> {
   const ctx: CoreContext = { db, model, defaultStore: repo };
   const tools = compileTools();
 
+  // Check whether `thatch setup` was run for the current host. If not, or if
+  // markers are broken, surface a warning on the first tools/call response so
+  // the agent can tell the user to run setup. Also emit to stderr for
+  // visibility in host debug logs.
+  let setupWarning: string | null = null;
+  const setupStatus = checkSetup(projectDir);
+  if (setupStatus && setupStatus.status !== "installed") {
+    setupWarning = setupStatus.message;
+    console.error(`[thatch] ${setupWarning}`);
+  }
+
   // The sideband socket lets one-shot hook processes (flush-tools) ask the
   // warm MCP server to embed a prompt and search for matches — without
   // loading the ~34 MB model themselves. If the socket can't be opened
@@ -137,6 +149,17 @@ export async function runMcpServer(): Promise<void> {
       const isNotification = req.id === null || req.id === undefined;
       const res = await dispatch(req, tools, ctx);
       if (res === null || isNotification) continue;
+
+      // Surface the setup warning on the first tools/call response so the
+      // agent sees it and can notify the user. Cleared after one surfacing.
+      if (setupWarning && req.method === "tools/call" && !res.error) {
+        const content = res.result?.content;
+        if (Array.isArray(content) && content[0]?.text != null) {
+          content[0].text = `[thatch] ${setupWarning}\n\n${content[0].text}`;
+        }
+        setupWarning = null;
+      }
+
       send(res);
     }
   }

package/src/prompts.ts

@@ -27,6 +27,19 @@ WIP, PR status). Unscoped memories are project-wide and always included in searc
 Before diving into code, thatch_memory_recall with a query relevant to the area
 you're working in. Prior sessions may have already investigated it.
 
+## Skills
+
+Thatch ships skills for code review, project investigation, and memory
+workflows. The host auto-discovers them, but reach for them proactively:
+
+- \`thatch-code-review\` — full multi-agent code review (dispatches 5 specialists + synthesizer). Requires sub-agent support.
+- \`thatch-workflow-research\` — research code workflows affected by a change or planned change, before reviewing or planning.
+- \`thatch-review-context\` — gather project context (PRs, tickets, TODOs, deferred work) before a review.
+- \`thatch-project-primer\` — investigate a new project and write foundational memories.
+- \`thatch-session-reflection\` — record what you learned at end of session.
+- \`thatch-fact-extractor\` — extract durable facts from recent tool interactions (auto-triggered by the extraction pipeline).
+- \`thatch-dedup-classifier\` — resolve duplicate memory pairs from \`thatch_find_duplicates\`.
+
 ## When to Write
 
 **One signal is enough.** Do not wait for confirmation.
@@ -56,6 +69,25 @@ new project knowledge, conventions, architectural decisions, investigation resul
 Session-specific context, incomplete/unverified info, anything already in
 CLAUDE.md or OPENCODE.md, speculative conclusions.
 
+## Archived Memories
+
+Memories can be marked \`archived\` — a flag for stable, long-term historical
+records that should not trigger hygiene nudges (stale, orphaned, duplicate).
+Archived memories are excluded from search/recall results by default; pass
+\`includeArchived: true\` to surface them for archaeological dives.
+
+When a branch is merged or about to be deleted, consolidate its branch-scoped
+memories into a single archived memory scoped to that same branch (preserving
+provenance). Capture intent, design decisions, review back-and-forth, PR
+number, unexpected pivots — the kind of git-archaeology context that explains
+_why_ the code looks the way it does a year from now. Then memory_forget the
+originals. The archived record outlives the branch. Future sessions searching
+with \`includeArchived: true\` can pull it up when investigating ambiguous code.
+
+Updating an archived memory requires passing \`archived\` explicitly — omit it
+and the tool returns an error. Pass \`archived: true\` to keep it archived,
+\`archived: false\` to unarchive.
+
 ## Explicit Requests
 
 "Remember X" — save immediately.
@@ -81,7 +113,7 @@ Use thatch_store_list then thatch_memory_list to see what's available, then that
   return `${base}
 
 [thatch hygiene] ${hygiene}
-When convenient this session (not before addressing the user's request), tend the store: run thatch_find_duplicates and consolidate clusters, review stale memories with thatch_memory_show and update or forget them, and forget memories scoped to deleted branches.`;
+When convenient this session (not before addressing the user's request), tend the store: run thatch_find_duplicates and consolidate clusters, review stale memories with thatch_memory_show and update or forget them, and for memories scoped to deleted branches, consolidate them into an archived historical record before forgetting the originals.`;
 }
 
 /**
@@ -126,6 +158,19 @@ WIP, PR status). Unscoped memories are project-wide and always included in searc
 Before diving into code, \`memory_recall\` with a query relevant to the area
 you're working in. Prior sessions may have already investigated it.
 
+## Skills
+
+Thatch ships skills for code review, project investigation, and memory
+workflows. The host auto-discovers them, but reach for them proactively:
+
+- \`thatch-workflow-research\` — research code workflows affected by a change or planned change, before reviewing or planning.
+- \`thatch-review-context\` — gather project context (PRs, tickets, TODOs, deferred work) before a review.
+- \`thatch-review-pedantic\` / \`-acceptance\` / \`-state-flow\` / \`-no-slop\` / \`-breadcrumbs\` — five specialist review lenses. Run individually, then \`thatch-review-synthesizer\` to verify and aggregate.
+- \`thatch-project-primer\` — investigate a new project and write foundational memories.
+- \`thatch-session-reflection\` — record what you learned at end of session.
+- \`thatch-fact-extractor\` — extract durable facts from recent tool interactions (auto-triggered by the extraction pipeline).
+- \`thatch-dedup-classifier\` — resolve duplicate memory pairs from \`find_duplicates\`.
+
 ## When to Write
 
 **One signal is enough.** Do not wait for confirmation.
@@ -155,6 +200,25 @@ new project knowledge, conventions, architectural decisions, investigation resul
 Session-specific context, incomplete/unverified info, anything already in
 CLAUDE.md, speculative conclusions.
 
+## Archived Memories
+
+Memories can be marked \`archived\` — a flag for stable, long-term historical
+records that should not trigger hygiene nudges (stale, orphaned, duplicate).
+Archived memories are excluded from search/recall results by default; pass
+\`includeArchived: true\` to surface them for archaeological dives.
+
+When a branch is merged or about to be deleted, consolidate its branch-scoped
+memories into a single archived memory scoped to that same branch (preserving
+provenance). Capture intent, design decisions, review back-and-forth, PR
+number, unexpected pivots — the kind of git-archaeology context that explains
+_why_ the code looks the way it does a year from now. Then memory_forget the
+originals. The archived record outlives the branch. Future sessions searching
+with \`includeArchived: true\` can pull it up when investigating ambiguous code.
+
+Updating an archived memory requires passing \`archived\` explicitly — omit it
+and the tool returns an error. Pass \`archived: true\` to keep it archived,
+\`archived: false\` to unarchive.
+
 ## Explicit Requests
 
 "Remember X" — save immediately.
@@ -179,7 +243,7 @@ Use store_list then memory_list to see what's available, then memory_recall as n
   return `${base}
 
 [thatch hygiene] ${hygiene}
-When convenient this session (not before addressing the user's request), tend the store: run find_duplicates and consolidate clusters, review stale memories with memory_show and update or forget them, and forget memories scoped to deleted branches.`;
+When convenient this session (not before addressing the user's request), tend the store: run find_duplicates and consolidate clusters, review stale memories with memory_show and update or forget them, and for memories scoped to deleted branches, consolidate them into an archived historical record before forgetting the originals.`;
 }
 
 /**
@@ -241,6 +305,19 @@ WIP, PR status). Unscoped memories are project-wide and always included in searc
 Before diving into code, \`memory_recall\` with a query relevant to the area
 you're working in. Prior sessions may have already investigated it.
 
+## Skills
+
+Thatch ships skills for code review, project investigation, and memory
+workflows. The host auto-discovers them, but reach for them proactively:
+
+- \`thatch-workflow-research\` — research code workflows affected by a change or planned change, before reviewing or planning.
+- \`thatch-review-context\` — gather project context (PRs, tickets, TODOs, deferred work) before a review.
+- \`thatch-review-pedantic\` / \`-acceptance\` / \`-state-flow\` / \`-no-slop\` / \`-breadcrumbs\` — five specialist review lenses. Run individually, then \`thatch-review-synthesizer\` to verify and aggregate.
+- \`thatch-project-primer\` — investigate a new project and write foundational memories.
+- \`thatch-session-reflection\` — record what you learned at end of session.
+- \`thatch-fact-extractor\` — extract durable facts from recent tool interactions (auto-triggered by the extraction pipeline).
+- \`thatch-dedup-classifier\` — resolve duplicate memory pairs from \`find_duplicates\`.
+
 ## When to Write
 
 **One signal is enough.** Do not wait for confirmation.
@@ -270,6 +347,25 @@ new project knowledge, conventions, architectural decisions, investigation resul
 Session-specific context, incomplete/unverified info, anything already in
 AGENTS.md, speculative conclusions.
 
+## Archived Memories
+
+Memories can be marked \`archived\` — a flag for stable, long-term historical
+records that should not trigger hygiene nudges (stale, orphaned, duplicate).
+Archived memories are excluded from search/recall results by default; pass
+\`includeArchived: true\` to surface them for archaeological dives.
+
+When a branch is merged or about to be deleted, consolidate its branch-scoped
+memories into a single archived memory scoped to that same branch (preserving
+provenance). Capture intent, design decisions, review back-and-forth, PR
+number, unexpected pivots — the kind of git-archaeology context that explains
+_why_ the code looks the way it does a year from now. Then memory_forget the
+originals. The archived record outlives the branch. Future sessions searching
+with \`includeArchived: true\` can pull it up when investigating ambiguous code.
+
+Updating an archived memory requires passing \`archived\` explicitly — omit it
+and the tool returns an error. Pass \`archived: true\` to keep it archived,
+\`archived: false\` to unarchive.
+
 ## Explicit Requests
 
 "Remember X" — save immediately.

package/src/setup.ts

@@ -415,8 +415,120 @@ export function setupCursor(
   return {
     mcpConfig: paths.mcpConfigPath,
     agentsMd: paths.agentsMdPath,
-    hooks: paths.hooksPath,
-    skills,
-    global,
+     hooks: paths.hooksPath,
+     skills,
+     global,
+   };
+}
+
+// ---------------------------------------------------------------------------
+// Setup detection — check whether setup was completed for the current host
+// ---------------------------------------------------------------------------
+
+export type HostKind = "claude" | "cursor";
+
+export type SetupStatus =
+  | { status: "installed"; scope: "local" | "global"; host: HostKind }
+  | { status: "not-installed"; host: HostKind; message: string }
+  | { status: "markers-broken"; host: HostKind; file: string; message: string };
+
+type FileCheck = "installed" | "absent" | "broken";
+
+function checkInstructionsFile(path: string, startMarker: string, endMarker: string): FileCheck {
+  if (!existsSync(path)) return "absent";
+  const content = readFileSync(path, "utf8");
+  const startIdx = content.indexOf(startMarker);
+  if (startIdx === -1) return "absent";
+  const endIdx = content.indexOf(endMarker, startIdx);
+  if (endIdx === -1) return "broken";
+  return "installed";
+}
+
+/**
+ * Detects the host from env vars (CURSOR_PROJECT_DIR for Cursor,
+ * CLAUDE_PROJECT_DIR for Claude Code) and checks whether `thatch setup` was
+ * run for that host. Checks local instructions (in the project dir) first,
+ * then global (in the config dir). Returns null if the host cannot be
+ * determined (neither env var is set — e.g. manual `thatch mcp` invocation).
+ */
+export function checkSetup(projectDir: string, homeDir?: string): SetupStatus | null {
+  const home = homeDir ?? process.env.HOME ?? "/tmp";
+  const isCursor = !!process.env.CURSOR_PROJECT_DIR;
+  const isClaude = !!process.env.CLAUDE_PROJECT_DIR && !isCursor;
+  if (!isCursor && !isClaude) return null;
+
+  const host: HostKind = isCursor ? "cursor" : "claude";
+
+  if (host === "claude") {
+    return checkClaudeSetup(projectDir, home);
+  }
+  return checkCursorSetup(projectDir, home);
+}
+
+function checkClaudeSetup(projectDir: string, home: string): SetupStatus {
+  const configDir = claudeConfigDir(home);
+
+  const localMd = join(projectDir, "CLAUDE.md");
+  const localCheck = checkInstructionsFile(localMd, THATCH_MARKER, THATCH_END_MARKER);
+  if (localCheck === "installed") return { status: "installed", scope: "local", host: "claude" };
+  if (localCheck === "broken") {
+    return {
+      status: "markers-broken",
+      host: "claude",
+      file: localMd,
+      message: `Thatch's instructions in ${localMd} have corrupted markers: the start marker was found but the end marker is missing. This usually happens when the file was edited externally and the thatch block was partially modified. Tell the user to fix this by running: thatch setup --claude. If that doesn't resolve it, they may need to manually remove the corrupted thatch block from ${localMd} and re-run setup.`,
+    };
+  }
+
+  const globalMd = join(configDir, "CLAUDE.md");
+  const globalCheck = checkInstructionsFile(globalMd, THATCH_MARKER, THATCH_END_MARKER);
+  if (globalCheck === "installed") return { status: "installed", scope: "global", host: "claude" };
+  if (globalCheck === "broken") {
+    return {
+      status: "markers-broken",
+      host: "claude",
+      file: globalMd,
+      message: `Thatch's instructions in ${globalMd} have corrupted markers: the start marker was found but the end marker is missing. This usually happens when the file was edited externally and the thatch block was partially modified. Tell the user to fix this by running: thatch setup --claude --global. If that doesn't resolve it, they may need to manually remove the corrupted thatch block from ${globalMd} and re-run setup.`,
+    };
+  }
+
+  return {
+    status: "not-installed",
+    host: "claude",
+    message: "Thatch is running as an MCP server but has not been set up for Claude Code. The instructions that tell you how to use thatch's memory tools are missing from CLAUDE.md. Tell the user to run: thatch setup --claude",
+  };
+}
+
+function checkCursorSetup(projectDir: string, home: string): SetupStatus {
+  const configDir = cursorConfigDir(home);
+
+  const localMd = join(projectDir, "AGENTS.md");
+  const localCheck = checkInstructionsFile(localMd, CURSOR_MARKER, CURSOR_END_MARKER);
+  if (localCheck === "installed") return { status: "installed", scope: "local", host: "cursor" };
+  if (localCheck === "broken") {
+    return {
+      status: "markers-broken",
+      host: "cursor",
+      file: localMd,
+      message: `Thatch's instructions in ${localMd} have corrupted markers: the start marker was found but the end marker is missing. This usually happens when the file was edited externally and the thatch block was partially modified. Tell the user to fix this by running: thatch setup --cursor. If that doesn't resolve it, they may need to manually remove the corrupted thatch block from ${localMd} and re-run setup.`,
+    };
+  }
+
+  const globalMd = join(configDir, "AGENTS.md");
+  const globalCheck = checkInstructionsFile(globalMd, CURSOR_MARKER, CURSOR_END_MARKER);
+  if (globalCheck === "installed") return { status: "installed", scope: "global", host: "cursor" };
+  if (globalCheck === "broken") {
+    return {
+      status: "markers-broken",
+      host: "cursor",
+      file: globalMd,
+      message: `Thatch's instructions in ${globalMd} have corrupted markers: the start marker was found but the end marker is missing. This usually happens when the file was edited externally and the thatch block was partially modified. Tell the user to fix this by running: thatch setup --cursor --global. If that doesn't resolve it, they may need to manually remove the corrupted thatch block from ${globalMd} and re-run setup.`,
+    };
+  }
+
+  return {
+    status: "not-installed",
+    host: "cursor",
+    message: "Thatch is running as an MCP server but has not been set up for Cursor. The instructions that tell you how to use thatch's memory tools are missing from AGENTS.md. Tell the user to run: thatch setup --cursor",
   };
 }

package/src/skills.ts

@@ -88,6 +88,13 @@ If your briefing includes a project context brief (from the coordinator or from
 - **Dependencies** in the brief tell you whether base-branch behavior is expected to be present or not. Do not assert that base-branch behavior exists without verifying it landed.
 - **Relevant constraints** may explain why code is structured a certain way. Consider them before flagging design choices.
 
+## Workflow context awareness
+If your briefing includes a workflow guide (from the coordinator or from loading thatch-workflow-research), use it to understand the purpose and evolution of the code you are reviewing:
+- **Purpose** sections explain why the workflow exists, which helps distinguish intentional behavior from bugs.
+- **Major evolutions** sections explain how the code reached its current state, which helps distinguish recent changes from long-standing design decisions.
+- **Constraints and design decisions** sections explain tradeoffs and intentional choices, which prevents flagging known design decisions as issues.
+- **Current state** sections list known limitations and incomplete work, which prevents flagging known gaps as new bugs.
+
 ## TODO ($ticket) markers
 Code may contain \`TODO ($TICKET-ID): description\` comments that mark intentionally deferred work: temporary code, placeholders for future tickets, or planned cleanups. These are legitimate breadcrumbs, not stale artifacts.
 - Do NOT flag a TODO ($ticket) marker as a stale artifact if the ticket it references is still open or future work.
@@ -861,6 +868,103 @@ These markers serve as breadcrumbs for reviewers (human and LLM) who lack projec
 - They SHOULD be flagged if the referenced ticket is closed or merged (the TODO is now stale)
 `;
 
+// ---------------------------------------------------------------------------
+// Workflow research — code archaeology for review or planning
+// ---------------------------------------------------------------------------
+
+const WORKFLOW_RESEARCH = `---
+name: thatch-workflow-research
+description: Research the code workflows and features affected by a change or planned change. Identifies affected workflows, reads code flows and comments, traces git history, recalls memories, and produces a guide to the code. Use before reviewing a change or planning new work in an unfamiliar area.
+---
+
+You are a code workflow researcher. Your job is to identify the features and logical workflows affected by a change (or a planned change), do deep code archaeology on them, and produce a guide that gives other agents the context they need to review or plan effectively.
+
+## Why this matters
+
+A specialist reviewer without code-level context will misidentify intentional behavior as bugs, miss known design constraints, and duplicate the same code-tracing work across every specialist lens. A planner without code-level context will propose changes that conflict with existing flows. This skill produces the code guide that prevents both.
+
+## Relationship to thatch-review-context
+
+These two skills are complementary, not overlapping:
+- **thatch-review-context** gathers project metadata: tickets, PRs, TODO markers, deferred work, issue-tracker context. It answers "what is this change trying to do and what is intentionally left out?"
+- **thatch-workflow-research** (this skill) gathers code-level context: actual code flows, comments, git history, evolutions. It answers "how does the code being changed actually work, and how did it get that way?"
+
+Use both before a review. The coordinator runs thatch-review-context in Step 2 and this skill in Step 3.
+
+## Two modes
+
+### Review mode (existing change)
+Given a git range, branch, or PR:
+1. Run \`git diff --stat\` on the resolved range to identify changed files.
+2. For each changed file, read the diff to understand what is being modified.
+3. From the changes, identify which features and business-logic workflows are touched. A single file may participate in multiple workflows; a single workflow may span multiple files.
+
+### Planning mode (new change)
+Given a description of work to be done:
+1. Identify which areas of the codebase the planned change would affect.
+2. Use grep/glob to find the files and modules that implement the relevant features.
+3. From those files, identify which existing workflows the change will interact with or modify.
+
+## Research process
+
+For each identified workflow or feature, work through these steps. Not every step will yield information for every workflow. Skip steps that produce nothing rather than forcing a narrative.
+
+### 1. Retrieve memories
+Call \`thatch_memory_recall\` with queries like:
+- The workflow or feature name
+- The primary files or modules involved
+- "architecture" or "design" or "convention" for the area
+- Any gotchas or known issues in the area
+
+### 2. Read documentation
+- README, docs/, design docs, ADRs related to the workflow
+- CLAUDE.md, AGENTS.md, CONTRIBUTING.md for conventions
+- Any inline documentation at the module level
+
+### 3. Read the code flow
+Trace each workflow through the codebase. Do not just read the changed lines; read the full flow:
+- Identify the entry point(s) for the workflow
+- Follow the data path through the functions and modules involved
+- Read the comments in the flow. Comments encode intention, rationale, and design decisions that are invisible from the code alone.
+- Note key contracts: what does each function or module assume about its inputs? What does it guarantee about its outputs?
+- Note implicit state machines: what states can the workflow be in? What transitions are guarded?
+
+### 4. Read git history
+Trace the evolution of the workflow through git:
+- \`git log --oneline -- <key files>\` for the commit history of the files involved
+- \`git log -S "<function name>"\` to find when key functions were introduced or changed
+- \`git blame\` on critical sections to find when and why they were written
+- \`git log --all --oneline --grep="<feature name>"\` to find related work on other branches
+- Look for commit messages that explain design decisions, refactors, or bug fixes that shaped the workflow
+
+Focus on *why* the code evolved, not just *when*. Major evolutions are: creation, significant refactors, behavior changes, bug fixes that changed the flow, and additions of new paths or states.
+
+## Output: code guide
+
+Produce a guide with one section per affected workflow or feature. Each section should be self-contained enough that a reviewer or planner can understand the workflow without reading the code themselves.
+
+### Workflow: <name>
+
+- **Purpose**: What this workflow does and why it exists in the system
+- **Key files**: The primary files and entry points, with file:line references
+- **Data flow**: How data moves through the workflow (high-level, not line-by-line)
+- **Major evolutions**: Key changes from git history. When was it created? What refactors or behavior changes shaped it? What drove those changes? Cite commit hashes or dates.
+- **Constraints and design decisions**: From comments, memories, and docs. Known constraints, tradeoffs, intentional design choices, and gotchas.
+- **Current state**: Any open issues, TODOs, known limitations, or incomplete migrations
+
+## Scope discipline
+
+Only research workflows that the change actually touches. Do not research every workflow in the codebase. If a changed file participates in three workflows but the change only affects one, research only that one.
+
+If the change is small and touches a single workflow, the guide may be one section. If the change is cross-cutting, the guide may have several sections. Let the change determine the scope.
+
+## What this skill is NOT
+
+- It is not a code review. Do not evaluate the quality of the code or flag issues. That is the job of the review specialists.
+- It is not a project context builder. That is the job of thatch-review-context, which gathers project metadata (tickets, PRs, TODOs, deferred work). This skill gathers code-level context (flows, comments, git history, evolutions).
+- It is not a memory writer. Do not call thatch_memory_remember. If you discover durable facts, note them in the guide; the session-reflection or fact-extractor skills will persist them later.
+`;
+
 // ---------------------------------------------------------------------------
 // Session reflection — end-of-session memory recording guidance
 // ---------------------------------------------------------------------------
@@ -976,7 +1080,20 @@ Produce the context brief in the format the skill prescribes (project context, t
 
 If context is sparse (no PR description, no ticket references, no relevant memories), note that the change appears standalone. Even a sparse brief is valuable: it tells specialists you looked and found nothing, so they do not need to repeat the search.
 
-## Step 3: Estimate complexity
+## Step 3: Research affected workflows
+
+Dispatch a sub-agent using the Task tool to research the code workflows affected by this change. Pass the sub-agent:
+- The git range and changed files (from Step 1)
+- The project context brief (from Step 2)
+- Instructions to load the thatch-workflow-research skill and follow its methodology
+
+The sub-agent produces a code guide with one section per affected workflow or feature. Wait for it to complete and collect the guide.
+
+This guide gives specialists the code-level context (purpose, data flow, evolutions, constraints) they need to avoid false positives about intentional behavior and long-standing design decisions, and reduces duplicate code-tracing across the five specialist lenses.
+
+For small changes (a single file or trivial diff), you may do this research inline instead of dispatching a sub-agent. Use your judgment: if the workflow research would require reading more than 3-4 files, dispatch a sub-agent to preserve your context for orchestration.
+
+## Step 4: Estimate complexity
 
 Estimate the review effort in scrum points (1-13 scale):
 - **1**: Trivial — typo fix, config tweak, single-line change.
@@ -990,7 +1107,7 @@ Points reflect *review complexity*, not implementation effort.
 
 Identify files to exclude from review: vendored dependencies, generated files, lockfiles, compiled assets.
 
-## Step 4: Partition (if > 3 points)
+## Step 5: Partition (if > 3 points)
 
 For changes estimated at more than 3 points, partition into review units of approximately 3 points each:
 - Group files by logical component or feature, not by directory.
@@ -1000,7 +1117,7 @@ For changes estimated at more than 3 points, partition into review units of appr
 
 For changes estimated at 3 points or fewer, skip partitioning — dispatch one set of specialists covering the full scope. A single 3-point unit is not large enough to warrant decomposition.
 
-## Step 5: Dispatch specialist sub-agents
+## Step 6: Dispatch specialist sub-agents
 
 For each review unit, dispatch sub-agents using the Task tool. Each sub-agent runs one specialist lens on one review unit. The five specialists are:
 
@@ -1019,7 +1136,7 @@ For the integration review unit (5+ points), dispatch a sub-agent focused on:
 - Boundary correctness — race conditions, ordering dependencies, shared state issues at boundaries.
 - Top-level coherence — does the overall change make sense as a unit?
 
-## Step 6: Synthesize
+## Step 7: Synthesize
 
 After all sub-agents complete, load the thatch-review-synthesizer skill to verify findings, deduplicate across specialists, classify (CONFIRMED/REJECTED/UNVERIFIABLE), and produce the final severity-grouped report.
 
@@ -1041,6 +1158,7 @@ When dispatching each sub-agent, include in the prompt:
 - The specialist focus (from the five specialists above)
 - The diff stat for this unit's files
 - **The project context brief** from Step 2, filtered to what is relevant to this unit's scope. Explicitly list any deferred work that falls within this unit's files, and call out TODO ($ticket) markers the specialists should recognize as intentional.
+- **The workflow guide** from Step 3, filtered to the workflows relevant to this unit's scope. Use it to understand the purpose and evolution of the code before flagging issues. It provides the code-level context (flows, contracts, history, constraints) that prevents false positives about intentional behavior and long-standing design decisions.
 - Any design context or specific concerns
 - Explicit scope boundaries ("your scope is X; do NOT review Y")
 - Instruction to produce markdown findings with: severity, category, file:line, finding, evidence, trigger scenario, reachability, source of truth, producer chain, provenance
@@ -1064,6 +1182,7 @@ const SHARED_SKILLS: SkillDef[] = [
   { name: "thatch-review-breadcrumbs", content: REVIEW_BREADCRUMBS },
   { name: "thatch-review-synthesizer", content: REVIEW_SYNTHESIZER },
   { name: "thatch-review-context", content: REVIEW_CONTEXT },
+  { name: "thatch-workflow-research", content: WORKFLOW_RESEARCH },
   { name: "thatch-session-reflection", content: SESSION_REFLECTION },
 ];
 

package/src/tool-defs.ts

@@ -40,6 +40,7 @@ function formatEntry(
   let meta = `[${entry.store}]`;
   if (entry.branch) meta += ` branch:${entry.branch}`;
   if (entry.confidence) meta += ` confidence:${entry.confidence}`;
+  if (entry.archived) meta += " archived:true";
   parts.push(meta, "", entry.content);
   return parts.join("\n");
 }
@@ -48,6 +49,7 @@ function formatRecallResult(entry: any): string {
   let meta = `store:${entry.store}`;
   if (entry.branch) meta += ` branch:${entry.branch}`;
   if (entry.confidence) meta += ` confidence:${entry.confidence}`;
+  if (entry.archived) meta += " archived:true";
   const score = entry._score.toFixed(3);
   return `[${meta}] [score:${score}]\n${entry.content}`;
 }
@@ -118,6 +120,11 @@ const rememberDef: ToolDef = {
     overwrite: z.boolean().optional().describe(
       "Set to true to replace an existing memory with the same label.",
     ),
+    archived: z.boolean().optional().describe(
+      "Mark this memory as a stable, long-term record that should not trigger hygiene nudges. " +
+      "When updating an already-archived memory, this param is REQUIRED — " +
+      "pass archived: true to keep it archived, or archived: false to unarchive.",
+    ),
   },
   async execute(args, ctx) {
     const store = (args.store as string) || ctx.defaultStore;
@@ -125,9 +132,6 @@ const rememberDef: ToolDef = {
     const content = `# ${label}\n\n${args.content as string}`;
     const embedding = await ctx.model.passageEmbed(content);
 
-    // Write-time collision check: the embedding is already computed, so
-    // scanning the store is nearly free. The save proceeds regardless —
-    // the agent decides whether and how to reconcile.
     const similar = ctx.db.findSimilar(store, embedding, {
       excludeSlug: ctx.db.slugify(label),
     });
@@ -136,6 +140,7 @@ const rememberDef: ToolDef = {
       branch: args.branch as string | undefined,
       confidence: args.confidence as number | undefined,
       overwrite: args.overwrite as boolean | undefined,
+      archived: args.archived as boolean | undefined,
     });
 
     if (!result.ok) return result.error;
@@ -172,6 +177,9 @@ const recallDef: ToolDef = {
     limit: z.number().int().min(1).max(20).optional().describe(
       "Maximum number of results. Default 10.",
     ),
+    includeArchived: z.boolean().optional().describe(
+      "Include archived memories in results. Default false — archived memories are excluded.",
+    ),
   },
   async execute(args, ctx) {
     const stores = args.store
@@ -183,6 +191,7 @@ const recallDef: ToolDef = {
     const results = ctx.db.recall(stores, queryEmbedding, {
       branch: args.branch as string | undefined,
       limit,
+      includeArchived: args.includeArchived as boolean | undefined,
     });
 
     if (results.length === 0) return "No matching memories found.";
@@ -212,6 +221,7 @@ const listDef: ToolDef = {
         let line = `[${store}] ${e.label}`;
         if (e.branch) line += ` (branch:${e.branch})`;
         if (e.confidence) line += ` (c:${e.confidence})`;
+        if (e.archived) line += " (archived)";
         line += ` (${e.updated_at})`;
         return line;
       })