@jeffober/thatch 0.1.11 → 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.11",
+  "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/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.
@@ -165,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).
@@ -312,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).

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 },