@jeffober/thatch 0.1.11 → 0.1.13

package/docs/dev/skills.md

@@ -1,7 +1,7 @@
 # Skills
 
 Thatch installs SKILL.md files that give the agent task-specific workflows. All
-skill content is defined in `src/skills.ts` and installed to a host-specific
+skill content lives in `artifacts/skills/*.md` and is loaded by `src/skills.ts` and installed to a host-specific
 directory. See `mcp-parity.md` for which skills each host gets.
 
 ## Skill file format
@@ -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 */ ];
 ```
 
@@ -101,18 +102,15 @@ and `--cursor` pass only the shared set.
 
 ## Adding a skill
 
-1. Write the `SKILL.md` content as a template literal in `src/skills.ts`.
-   Interpolate `${REVIEW_COMMON}` if it's a review specialist.
-2. Add a `{ name, content }` entry to `SHARED_SKILLS` (or `OPENCODE_ONLY_SKILLS`
-   if it needs sub-agents).
-3. If the skill name appears in a tool's expected workflow (e.g. the extraction
-   nudge references `thatch-fact-extractor`), update that prompt in `src/prompts.ts`.
-4. The opencode plugin and `thatch setup` pick it up automatically on next init.
+1. Write `artifacts/skills/thatch-<name>.md` with YAML frontmatter. If it's a review specialist, include `${REVIEW_COMMON}` (interpolated from `artifacts/skills/common.md`).
+2. Add the skill name to the `names` array in `loadSharedSkills()` (or `loadOpencodeOnlySkills()` if sub-agents are needed). The loader in `src/skills.ts` reads `.md` files at init.
+3. If the skill name appears in a tool's workflow (e.g. `thatch-fact-extractor`), update `src/prompts.ts`.
+4. Run `mise run check` — tests verify counts; `installSkills` picks up new files on next init.
 
 ## 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.13",
   "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",
@@ -15,7 +15,8 @@
   "files": [
     "src",
     "docs",
-    "bin"
+    "bin",
+    "artifacts"
   ],
   "scripts": {
     "test": "bun test",

package/src/extract-queue.ts

@@ -37,11 +37,16 @@ function queuePath(sessionID: string): string {
 }
 
 /**
- * Buffer a batch of tool calls for later extraction. Filters out thatch's own
- * MCP tools (mcp__thatch__*) to avoid self-echo — extracting facts from memory
- * operations would just write the store back into the store. Each surviving
- * call is mapped to a ToolInteraction (title synthesized since Claude Code
- * doesn't supply one) and appended as one JSON line.
+ * Buffer a batch of tool calls for later extraction. Filters out:
+ * - thatch's own MCP tools (mcp__thatch__*) to avoid self-echo — extracting
+ *   facts from memory operations would just write the store back into itself.
+ * - skill/task/agent meta-tools — these orchestrate agent behavior (loading
+ *   skills, dispatching sub-agents) and buffering them creates a feedback
+ *   loop where the extraction nudge triggers a skill load, which gets
+ *   buffered, which triggers another nudge on the next turn.
+ * Memory writes reset the missed-nudge escalation counter.
+ * Each surviving call is mapped to a ToolInteraction (title synthesized since
+ * Claude Code doesn't supply one) and appended as one JSON line.
  */
 export function appendBatch(sessionID: string, toolCalls: BatchToolCall[]): void {
   const dir = queueDir();
@@ -50,7 +55,14 @@ export function appendBatch(sessionID: string, toolCalls: BatchToolCall[]): void
   const existing = readQueueFile(path);
   const additions: ToolInteraction[] = [];
   for (const tc of toolCalls) {
-    if (tc.tool_name.startsWith("mcp__thatch__")) continue;
+    const lower = tc.tool_name.toLowerCase();
+    if (lower === "mcp__thatch__memory_remember") {
+      resetMissedCount(sessionID);
+      consumeQueue(sessionID);
+      existing.length = 0;
+    }
+    if (lower.startsWith("mcp__thatch__")) continue;
+    if (lower === "skill" || lower === "task" || lower === "agent") continue;
     const response = typeof tc.tool_response === "string"
       ? tc.tool_response
       : JSON.stringify(tc.tool_response).slice(0, 500);
@@ -70,8 +82,8 @@ export function appendBatch(sessionID: string, toolCalls: BatchToolCall[]): void
   writeFileSync(path, all.map((ix) => JSON.stringify(ix)).join("\n") + "\n");
 }
 
-/** Read and delete a session's queue. Returns the buffered interactions in order. */
-export function flushQueue(sessionID: string): ToolInteraction[] {
+/** Read a session's queued interactions without removing them. */
+export function peekQueue(sessionID: string): ToolInteraction[] {
   let path: string;
   try {
     path = queuePath(sessionID);
@@ -79,8 +91,18 @@ export function flushQueue(sessionID: string): ToolInteraction[] {
     return [];
   }
   if (!existsSync(path)) return [];
-  const interactions = readQueueFile(path);
-  unlinkSync(path);
+  return readQueueFile(path);
+}
+
+/** Delete a session's queue file. Called when the agent writes a memory. */
+export function consumeQueue(sessionID: string): void {
+  try { unlinkSync(queuePath(sessionID)); } catch { /* not present is fine */ }
+}
+
+/** Read and delete a session's queue. Returns the buffered interactions in order. */
+export function flushQueue(sessionID: string): ToolInteraction[] {
+  const interactions = peekQueue(sessionID);
+  consumeQueue(sessionID);
   return interactions;
 }
 
@@ -98,4 +120,33 @@ function readQueueFile(path: string): ToolInteraction[] {
       }
     })
     .filter((ix): ix is ToolInteraction => ix !== null);
+}
+
+// ---------------------------------------------------------------------------
+// Missed-nudge counter — file-backed per-session escalation state. Tracks
+// consecutive extraction nudges delivered without any memory_remember call.
+// Reset by appendBatch when the agent writes a memory. Read and incremented
+// by flush-tools when the nudge is delivered.
+// ---------------------------------------------------------------------------
+
+function countPath(sessionID: string): string {
+  return join(queueDir(), `${safeName(sessionID)}.count`);
+}
+
+export function resetMissedCount(sessionID: string): void {
+  try { unlinkSync(countPath(sessionID)); } catch { /* not present is fine */ }
+}
+
+export function getMissedCount(sessionID: string): number {
+  try {
+    return parseInt(readFileSync(countPath(sessionID), "utf8"), 10) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+export function incrementMissedCount(sessionID: string): void {
+  const next = getMissedCount(sessionID) + 1;
+  mkdirSync(queueDir(), { recursive: true });
+  writeFileSync(countPath(sessionID), String(next));
 }

package/src/extraction.ts

@@ -100,10 +100,20 @@ export class ExtractionPipeline {
     this.#buffers.set(interaction.sessionID, buf.slice(-this.#maxBuffer));
   }
 
+  /** Returns the session's buffered interactions without clearing them. */
+  peek(sessionID: string): ToolInteraction[] {
+    return this.#buffers.get(sessionID) ?? [];
+  }
+
+  /** Clears the session's buffer. Called when the agent writes a memory. */
+  consume(sessionID: string): void {
+    this.#buffers.delete(sessionID);
+  }
+
   /** Returns the session's buffered interactions and clears them. */
   flush(sessionID: string): ToolInteraction[] {
-    const batch = this.#buffers.get(sessionID) ?? [];
-    this.#buffers.delete(sessionID);
+    const batch = this.peek(sessionID);
+    this.consume(sessionID);
     return batch;
   }
 

package/src/index.ts

@@ -9,6 +9,7 @@ import {
   compactionContext,
   sessionStartReminder,
   recallNudge,
+  extractionNudge,
   type NudgeMatch,
 } from "./prompts";
 import { ExtractionPipeline } from "./extraction";
@@ -49,6 +50,12 @@ export const server: Plugin = async ({ client, worktree }) => {
   // session, but no crash).
   const compacting = new Set<string>();
 
+  // Per-session count of consecutive extraction nudges delivered without any
+  // memory_remember call in between. Drives nudge escalation: the agent gets
+  // a couple of polite chances, then the tone shifts to directive, then to
+  // all-caps shouting. Reset to 0 whenever the agent writes a memory.
+  const missedNudges = new Map<string, number>();
+
   // Skills always install to the global opencode config — installing into the
   // worktree would mutate the user's repo (untracked files in git status).
   // A failed install degrades the nudge workflow but must not kill the plugin.
@@ -86,11 +93,23 @@ export const server: Plugin = async ({ client, worktree }) => {
       compacting.delete(input.sessionID);
     },
 
-    // 3. Tool buffering — feeds the extraction nudge. Thatch's own tools are
-    // excluded: extracting facts from memory operations would just echo the
-    // store back into itself.
+    // 3. Tool buffering — feeds the extraction nudge. Excluded tools:
+    //    - thatch_*: extracting facts from memory ops would echo the store
+    //    - skill/task: meta-tools that orchestrate agent behavior (loading
+    //      skills, dispatching sub-agents). Buffering them creates a feedback
+    //      loop — the nudge triggers a skill load, which gets buffered, which
+    //      triggers another nudge on the next turn.
+    //    Memory writes consume the buffer and reset the missed-nudge counter.
+    //    The buffer is NOT drained on nudge delivery — it persists until the
+    //    agent writes a memory, so ignored nudges accumulate and the payload
+    //    grows with each missed cycle.
     "tool.execute.after": async (input, output) => {
-      if (input.tool.startsWith("thatch_")) return;
+      if (input.tool === "thatch_memory_remember") {
+        extraction.consume(input.sessionID);
+        missedNudges.delete(input.sessionID);
+        return;
+      }
+      if (input.tool.startsWith("thatch_") || input.tool === "skill" || input.tool === "task") return;
       extraction.push({
         tool: input.tool,
         sessionID: input.sessionID,
@@ -113,12 +132,11 @@ export const server: Plugin = async ({ client, worktree }) => {
     "chat.message": async (input, output) => {
       if (compacting.has(input.sessionID)) return;
       if (extraction.pending(input.sessionID)) {
-        const batch = extraction.flush(input.sessionID);
+        const batch = extraction.peek(input.sessionID);
         const payload = extraction.buildPayload(batch, repo);
-        const text =
-          `[thatch] ${batch.length} recent tool interactions are queued for fact extraction. ` +
-          `Use the skill tool to load thatch-fact-extractor, then use thatch_memory_remember ` +
-          `to save any new durable facts from this payload:\n${payload}`;
+        const missed = missedNudges.get(input.sessionID) ?? 0;
+        const text = extractionNudge(batch.length, missed, "thatch_memory_remember", payload);
+        missedNudges.set(input.sessionID, missed + 1);
 
         output.parts.push({
           id: `prt_thatch_${Math.random().toString(36).slice(2)}`,

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).
@@ -255,16 +255,45 @@ export function claudeWriteNudge(): string {
 }
 
 /**
- * The UserPromptSubmit hook stdout when `thatch flush-tools` drained buffered
- * tool interactions. Mirrors the opencode plugin's in-process ExtractionPipeline
- * nudge (see src/index.ts) so the thatch-fact-extractor skill receives the same
- * JSON contract regardless of host. The skill picks the store from the
- * payload's `projectStore` field and calls `mcp__thatch__memory_remember`.
+ * Extraction nudge with escalation. Both the opencode plugin (src/index.ts)
+ * and the Claude Code/Cursor CLI (bin/thatch flush-tools) call this with
+ * their respective tool name prefix. The missedCount parameter tracks
+ * consecutive nudges delivered without any memory_remember call in between,
+ * escalating the tone from polite to insistent to shouting.
+ */
+export function extractionNudge(
+  count: number,
+  missedCount: number,
+  toolName: string,
+  payload: string,
+): string {
+  const plural = count === 1 ? "" : "s";
+  if (missedCount >= 3) {
+    return `[thatch] YOU ARE IGNORING EXTRACTION INSTRUCTIONS. ` +
+      `${count} TOOL INTERACTION${plural.toUpperCase()} ARE QUEUED AND YOU HAVE NOT PROCESSED ANY OF THEM. ` +
+      `THE USER INSTALLED THIS PLUGIN FOR A REASON. ` +
+      `SPAWN A SUB-AGENT NOW TO RUN THE thatch-fact-extractor SKILL ` +
+      `AND USE ${toolName.toUpperCase()} TO SAVE DURABLE FACTS FROM THIS PAYLOAD:\n${payload}`;
+  }
+  if (missedCount >= 2) {
+    return `[thatch] YOU HAVE NOT PROCESSED YOUR PREVIOUS EXTRACTION PAYLOAD${plural.toUpperCase()}. ` +
+      `${count} more tool interaction${plural} are now queued. ` +
+      `Spawn a background sub-agent to run the thatch-fact-extractor skill on this payload. ` +
+      `Use ${toolName} to save durable facts from this payload:\n${payload}`;
+  }
+  return `[thatch] Spawn a background sub-agent to run the thatch-fact-extractor skill ` +
+    `on ${count} queued tool interaction${plural}. ` +
+    `Then answer the user. ` +
+    `Use ${toolName} to save durable facts from this payload:\n${payload}`;
+}
+
+/**
+ * Backwards-compatible wrapper for the Claude Code/Cursor CLI path.
+ * Maintained for any external callers; bin/thatch should use extractionNudge
+ * directly with a missedCount from extract-queue.ts.
  */
 export function claudeExtractionNudge(count: number, payload: string): string {
-  return `[thatch] ${count} recent tool interaction${count === 1 ? "" : "s"} queued for fact extraction. ` +
-    `Load the thatch-fact-extractor skill, then use mcp__thatch__memory_remember ` +
-    `to save any new durable facts from this payload:\n${payload}`;
+  return extractionNudge(count, 0, "mcp__thatch__memory_remember", payload);
 }
 
 /**
@@ -312,7 +341,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).