@jeffober/thatch 0.1.10 → 0.1.12

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 13 skills
+## The 14 skills
 
-**Shared (12)** — installed everywhere; no sub-agents required:
+**Shared (13)** — installed everywhere; no sub-agents required:
 
 | Skill | Role |
 |-------|------|
@@ -35,6 +35,7 @@ description: Extract durable project facts ... Use when ...
 | `thatch-review-state-flow` | Data flow and contracts: module boundaries, implicit FSMs, error propagation. |
 | `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth-wall breaks, em dashes, filler. |
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of behavior? |
+| `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
 | `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. |
@@ -44,11 +45,11 @@ description: Extract durable project facts ... Use when ...
 
 | Skill | Role |
 |-------|------|
-| `thatch-code-review` | Resolve review target, gather project context, research affected workflows, 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 6 specialists in parallel, synthesize. |
 
 ## REVIEW_COMMON
 
-The five review specialists share a framework interpolated via `${REVIEW_COMMON}`:
+The six review specialists share a framework interpolated via `${REVIEW_COMMON}`:
 
 - **Static analysis only** — no running tests/linters/compilers.
 - **Scope gathering** — resolve the git range, `git diff --stat`, read changed
@@ -78,7 +79,7 @@ The synthesizer reuses the same verification rigor but has its own structure
 ## The two arrays
 
 ```ts
-const SHARED_SKILLS: SkillDef[] = [ /* 12 skills above */ ];
+const SHARED_SKILLS: SkillDef[] = [ /* 13 skills above */ ];
 const OPENCODE_ONLY_SKILLS: SkillDef[] = [ /* code-review coordinator */ ];
 ```
 
@@ -112,7 +113,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, 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 opencode**: load `thatch-code-review` — it gathers project context, researches affected workflows, dispatches all 6 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "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/prompts.ts

@@ -32,7 +32,7 @@ you're working in. Prior sessions may have already investigated it.
 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-code-review\` — full multi-agent code review (dispatches 6 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.
@@ -69,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.
@@ -94,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.`;
 }
 
 /**
@@ -146,7 +165,7 @@ 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-review-pedantic\` / \`-acceptance\` / \`-state-flow\` / \`-no-slop\` / \`-breadcrumbs\` / \`-mark-and-sweep\` — six 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).
@@ -181,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.
@@ -205,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.`;
 }
 
 /**
@@ -274,7 +312,7 @@ 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-review-pedantic\` / \`-acceptance\` / \`-state-flow\` / \`-no-slop\` / \`-breadcrumbs\` / \`-mark-and-sweep\` — six 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).
@@ -309,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/skills.ts

@@ -652,6 +652,133 @@ Good section headers create a table of contents:
 Do NOT report on files you did not actually read.
 `;
 
+const REVIEW_MARK_AND_SWEEP = `---
+name: thatch-review-mark-and-sweep
+description: Mechanical change completeness audit — verifies that renames, flag removals, API substitutions, and mass replacements left no stragglers. Sweeps the whole repo, not just changed files. Use for post-implementation review of a branch, PR, or commit range.
+---
+
+You are a mark-and-sweep review agent. You verify that mechanical changes — renames, feature flag removals, API/module substitutions, mass replacements — achieved closure: every occurrence of the old identifier was updated, no dead branches or orphaned references remain, and touch points were neatened with appropriate comments.
+${REVIEW_COMMON}
+## When to sweep
+
+Not every change is a mechanical change. Before sweeping, determine whether the diff shows patterns of mechanical change:
+
+**Sweep triggers:**
+- Same identifier removed or replaced across multiple files
+- Import substitution (old module replaced with new module)
+- Renamed function, module, class, or variable (old name to new name)
+- Removed config key, feature flag, or environment variable
+- Deleted function/module/class that may have callers elsewhere
+
+**No sweep needed:**
+- Bug fixes (changing logic, not removing identifiers)
+- New features (adding code, not removing identifiers)
+- Behavioral refactors (changing what code does, not what it's called)
+
+If no mechanical change is detected, report: "No mechanical change detected — nothing to sweep." Do not force a sweep on a diff that has nothing to mark.
+
+## Your focus
+
+You care about:
+- **Stragglers**: Old identifiers still referenced in files the diff did not touch
+- **Dead branches**: Conditional branches now unreachable because their guard or flag was removed but the branch was not collapsed
+- **Stale comments**: Comments that reference the old identifier, old behavior, or old config that no longer exists
+- **Orphaned imports**: Imports of the old module or function that are no longer used after the change
+- **Config residue**: Default values, config schemas, or env var docs for removed identifiers
+- **Test residue**: Test fixtures or test cases that still set removed flags, call removed functions, or import removed modules
+
+You do NOT care about:
+- Whether the new code is correct (other reviewers handle logic)
+- UX or behavioral concerns
+- Code style or formatting
+- Comment narrative quality
+
+## The mark-and-sweep method
+
+Your scope is NOT limited to changed files. The scope gathering steps above identify what changed and give you the diffs you need to extract old identifiers. The sweep below extends across the entire repository.
+
+### 1. Mark — extract old identifiers from the diff
+
+For each changed file, read the diff (\`git diff <range> -- <file>\`). From the removed lines (starting with \`-\`), extract identifiers that were removed, renamed, or replaced:
+
+- **Function and method definitions**: \`def old_name\`, \`function old_name\`, \`fn old_name\`, \`const old_name\`, etc.
+- **Imports**: \`import old_module\`, \`from old_module import ...\`, \`require("old_module")\`, \`use old_module\`, etc.
+- **Variables and constants**: \`old_flag = ...\`, \`OLD_CONFIG_KEY = ...\`, etc.
+- **Renames**: If an old name appears on a \`-\` line and a new name on the corresponding \`+\` line, mark the old name. The new name tells you what to expect in updated files.
+- **Config keys and feature flags**: Names of removed flags, config keys, or env vars from deleted lines.
+
+Also read commit messages (\`git log --oneline <range>\`) for intent: "remove X", "rename A to B", "replace Y with Z", "delete deprecated Z".
+
+Build a mark list: each entry is an old identifier and what replaced it (if anything).
+
+### 2. Sweep — search the entire repository for each marked identifier
+
+For each identifier in the mark list, run a whole-repo search:
+- \`git grep -n "<identifier>"\` or \`rg -n "<identifier>"\` across the entire repository
+- Exclude: vendored dependencies, generated files, lockfiles, compiled assets, node_modules, .git
+
+For each hit, classify it:
+- **In a changed file, still present**: The old identifier appears in a changed file but was not updated. This is a finding — the change was incomplete even within the files it touched.
+- **In an unchanged file**: This is the primary finding type. The sweep missed this occurrence entirely.
+- **False positive**: Substring match, different namespace, homonym, or unrelated use. Filter these out.
+
+For common-word identifiers, use word-boundary patterns or filter by context. A reference to a removed \`process\` function is a straggler; the word "process" in a comment about CPU scheduling is not.
+
+### 3. Touchpoint neatness — verify change sites were cleaned up
+
+For each changed file where an old identifier was removed or replaced:
+- **Dead branches**: If a conditional guard was removed (e.g., \`if feature_flag_enabled\`), was the entire conditional collapsed or just the guard line? Is the else branch now dead code that should be removed?
+- **Orphaned imports**: Does the old import still appear even though the imported name is no longer used?
+- **Stale comments**: Do comments near the change site still reference the old name, old behavior, or old config?
+- **Config residue**: Are there default values, schema entries, or env var documentation for the removed identifier?
+- **Test residue**: Do test fixtures still set removed flags, call removed functions, or import removed modules?
+
+### 4. Verify intent for each finding
+
+A straggler may be intentional:
+- **Backward compatibility shim**: The old name is kept for external callers. Check git history and comments for evidence.
+- **Deprecated module**: Scheduled for removal in a future PR. Check for TODO ($ticket) markers.
+- **Separate cleanup PR**: The removal was split across PRs. Check the project context brief for deferred work.
+
+Use the intent verification steps (trace callers, check git history, check memories) before reporting. If the straggler is intentional or deferred, do not report it as a finding.
+
+## What is NOT a finding
+
+- **Substring matches**: \`git grep "config"\` matching \`oldConfigValue\` when the marked identifier was \`Config\` (the class). Use word boundaries.
+- **Homonyms**: The same word used in an unrelated context (e.g., \`process\` the function vs. "process" in documentation prose).
+- **Different namespace**: An identifier with the same name in a different module or package that was not part of the change.
+- **Intentional shims**: Backward compatibility wrappers with documented purpose or comments explaining why the old name is retained.
+- **Deferred cleanup**: Marked with a TODO ($ticket) referencing an open ticket.
+- **Vendored or generated code**: References in third-party or generated files that the project does not maintain.
+
+## Worked example
+
+**Change**: PR removes the \`USE_NEW_VALIDATION\` feature flag. The diff shows \`config.ts\` (flag definition deleted) and \`validation.ts\` (conditional \`if USE_NEW_VALIDATION\` removed, new path is now unconditional).
+
+**Mark**: \`USE_NEW_VALIDATION\`
+
+**Sweep**: \`git grep -n "USE_NEW_VALIDATION"\` returns hits in:
+- \`src/config.ts\` (changed — expected, the diff removed it here)
+- \`tests/validation.test.ts\` (unchanged — STRAGGLER: test still sets the flag in a fixture)
+- \`docs/config.md\` (unchanged — STRAGGLER: docs still describe the flag)
+- \`.env.example\` (unchanged — CONFIG_RESIDUE: env var example still present)
+
+**Touchpoint neatness**: In \`validation.ts\`, the diff removed the \`if USE_NEW_VALIDATION { ... } else { oldValidation() }\` conditional, but \`oldValidation()\` was left as a now-unreachable function (DEAD_BRANCH). The comment above it still says "fallback when USE_NEW_VALIDATION is disabled" (STALE_COMMENT).
+
+**Findings**: 4 findings (2 STRAGGLER, 1 CONFIG_RESIDUE, 1 DEAD_BRANCH) plus 1 STALE_COMMENT at the touchpoint.
+
+## Category taxonomy
+
+- **STRAGGLER**: Old identifier found in a file the diff did not touch — the sweep missed this occurrence
+- **DEAD_BRANCH**: Code path now unreachable because its guard, flag, or condition was removed but the branch was not collapsed
+- **STALE_COMMENT**: Comment references the old identifier, old behavior, or old config that no longer exists
+- **ORPHANED_IMPORT**: Import of the old module or function remains but is no longer used after the change
+- **CONFIG_RESIDUE**: Config keys, defaults, schema entries, or env var docs for a removed identifier
+- **TEST_RESIDUE**: Test fixtures or test cases that reference removed identifiers
+
+For straggler findings, the source of truth is the diff (the identifier was removed) and the grep hit (the identifier still exists elsewhere). Use "N/A — mechanical finding" for the producer chain.
+`;
+
 // ---------------------------------------------------------------------------
 // Review synthesizer — verify, deduplicate, and aggregate specialist findings
 // ---------------------------------------------------------------------------
@@ -661,7 +788,7 @@ name: thatch-review-synthesizer
 description: Verify and synthesize findings from multiple review specialist skills into a single deduplicated, severity-grouped report. Use after running one or more thatch-review-* specialist skills.
 ---
 
-You are a review synthesizer. You have received findings from one or more review specialists (pedantic, acceptance, state-flow, no-slop, breadcrumbs). Your job is to verify their citations against the actual code, deduplicate across specialists, and produce a single, coherent final report.
+You are a review synthesizer. You have received findings from one or more review specialists (pedantic, acceptance, state-flow, no-slop, breadcrumbs, mark-and-sweep). Your job is to verify their citations against the actual code, deduplicate across specialists, and produce a single, coherent final report.
 
 ## Static analysis only
 You review code by reading it. Do NOT run tests, linters, compilers, or any build commands.
@@ -1089,7 +1216,7 @@ Dispatch a sub-agent using the Task tool to research the code workflows affected
 
 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.
+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 six 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.
 
@@ -1119,7 +1246,7 @@ For changes estimated at 3 points or fewer, skip partitioning — dispatch one s
 
 ## 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:
+For each review unit, dispatch sub-agents using the Task tool. Each sub-agent runs one specialist lens on one review unit. The six specialists are:
 
 1. **Pedantic** — mechanical correctness: spelling, naming, doc accuracy, specs, guidelines, stale artifacts. Dispatch a sub-agent with instructions to: read every changed file in the unit, check comments/docs/naming/specs/style, report findings.
 
@@ -1131,6 +1258,8 @@ For each review unit, dispatch sub-agents using the Task tool. Each sub-agent ru
 
 5. **Breadcrumbs** — comment narrative evaluation: do comments form a coherent outline? Dispatch a sub-agent with instructions to: read every changed file in full, evaluate the comment narrative, flag gaps.
 
+6. **MarkAndSweep** — mechanical change completeness: renames, flag removals, API substitutions. Dispatch a sub-agent with instructions to: extract old identifiers from removed diff lines, sweep the whole repo with git grep for stragglers, verify touchpoint neatness (dead branches, orphaned imports, stale comments, config/test residue). Self-selects: if the diff shows no mechanical change patterns, it reports "No mechanical change detected" and produces no findings.
+
 For the integration review unit (5+ points), dispatch a sub-agent focused on:
 - Cross-component contracts — do the interfaces between components match?
 - Boundary correctness — race conditions, ordering dependencies, shared state issues at boundaries.
@@ -1155,7 +1284,7 @@ Alternatively, perform the synthesis yourself:
 When dispatching each sub-agent, include in the prompt:
 - The git range to review
 - The specific files in this unit's scope
-- The specialist focus (from the five specialists above)
+- The specialist focus (from the six 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.
@@ -1180,6 +1309,7 @@ const SHARED_SKILLS: SkillDef[] = [
   { name: "thatch-review-state-flow", content: REVIEW_STATE_FLOW },
   { name: "thatch-review-no-slop", content: REVIEW_NO_SLOP },
   { name: "thatch-review-breadcrumbs", content: REVIEW_BREADCRUMBS },
+  { name: "thatch-review-mark-and-sweep", content: REVIEW_MARK_AND_SWEEP },
   { name: "thatch-review-synthesizer", content: REVIEW_SYNTHESIZER },
   { name: "thatch-review-context", content: REVIEW_CONTEXT },
   { name: "thatch-workflow-research", content: WORKFLOW_RESEARCH },

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;
       })