@jeffober/thatch 0.1.26 → 0.1.28

package/src/skills.ts

@@ -1,5 +1,6 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import pkg from "../package.json";
 
 export interface SkillFile {
   name: string;
@@ -42,14 +43,16 @@ function loadSharedSkills(): SkillDef[] {
     "thatch-review-highlights",
     "thatch-review-synthesizer",
     "thatch-review-context",
-    "thatch-workflow-research",
+    "thatch-code-archaeology",
     "thatch-review-followup",
     "thatch-change-walkthrough",
     "thatch-code-walkthrough",
     "thatch-session-reflection",
-    "pr-description",
-    "ticket-description",
-    "split-overlarge-pr",
+    "thatch-coding-workflow",
+    "thatch-pr-description",
+    "thatch-ticket-description",
+    "thatch-split-overlarge-pr",
+    "thatch-review-response",
   ];
   return names.map((name) => ({ name, content: loadSkillFile(name) }));
 }
@@ -63,11 +66,106 @@ function loadOpencodeOnlySkills(): SkillDef[] {
 export const SHARED_SKILLS: SkillDef[] = loadSharedSkills();
 export const OPENCODE_ONLY_SKILLS: SkillDef[] = loadOpencodeOnlySkills();
 
+// ---------------------------------------------------------------------------
+// Stale skill cleanup - runs before install on every skillsDir
+// ---------------------------------------------------------------------------
+
+// Skills renamed from non-prefixed to thatch-prefixed in v0.1.27. The old
+// names are cleaned up during install for a limited version window because
+// non-prefixed names could be adopted by third parties after we abandon them.
+// After RENAME_MIGRATION_MAX_VERSION, the cleanup stops and leftover stale
+// files are the user's responsibility.
+const RENAMED_SKILLS = new Set([
+  "pr-description",
+  "ticket-description",
+  "split-overlarge-pr",
+]);
+
+// Last version that ships the non-prefixed-to-prefixed migration cleanup.
+// Users who upgrade to this version or earlier get automatic cleanup of the
+// old skill directories. Users who skip past this version must manually
+// delete the stale directories.
+const RENAME_MIGRATION_MAX_VERSION = "0.1.35";
+
+function compareVersions(a: string, b: string): number {
+  const [aMaj, aMin, aPatch] = a.split(".").map(Number);
+  const [bMaj, bMin, bPatch] = b.split(".").map(Number);
+  if (aMaj !== bMaj) return aMaj - bMaj;
+  if (aMin !== bMin) return aMin - bMin;
+  return aPatch - bPatch;
+}
+
+/**
+ * Remove stale skill directories before installing the current set.
+ *
+ * Two cleanup rules:
+ *
+ * 1. Always: delete any `thatch-*` skill directory that is not in the current
+ *    install set. The `thatch-` prefix is our namespace - no third party should
+ *    use it, so unconditional removal is safe. This catches skills we've
+ *    renamed or removed in any release.
+ *
+ * 2. Version-gated: delete directories matching old non-prefixed skill names
+ *    (pr-description, ticket-description, split-overlarge-pr) through
+ *    RENAME_MIGRATION_MAX_VERSION. These names lack the thatch- prefix and
+ *    could be adopted by third parties after we abandon them, so the cleanup
+ *    is time-boxed. Users who upgrade past the window must manually clean up.
+ */
+function cleanupStaleSkills(skillsDir: string, currentNames: string[]): void {
+  const currentSet = new Set(currentNames);
+  let entries;
+  try {
+    entries = readdirSync(skillsDir, { withFileTypes: true });
+  } catch {
+    return; // dir doesn't exist or isn't readable - nothing to clean
+  }
+
+  const withinMigrationWindow =
+    compareVersions(pkg.version, RENAME_MIGRATION_MAX_VERSION) <= 0;
+
+  for (const entry of entries) {
+    // isDirectory() returns false for symlinks (even symlinked dirs), so
+    // check isSymbolicLink() too - a symlinked skill dir is just as stale
+    // as a regular one.
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    const name = entry.name;
+    const fullPath = join(skillsDir, name);
+
+    // Remove a stale entry. For symlinks, unlink the symlink itself - never
+    // follow the link, which could delete the target (e.g. a shared skill
+    // directory the user still wants). For regular dirs, recursive rm.
+    const remove = () => {
+      try {
+        if (entry.isSymbolicLink()) {
+          unlinkSync(fullPath);
+        } else {
+          rmSync(fullPath, { recursive: true, force: true });
+        }
+      } catch {
+        // best-effort - don't block install on cleanup failure
+      }
+    };
+
+    // Rule 1: stale thatch-* dirs (our namespace, always safe to remove).
+    if (name.startsWith("thatch-") && !currentSet.has(name)) {
+      remove();
+      continue;
+    }
+
+    // Rule 2: renamed non-prefixed dirs (version-gated, third-party risk).
+    if (RENAMED_SKILLS.has(name) && withinMigrationWindow) {
+      remove();
+    }
+  }
+}
+
 export function installSkills(
   skillsDir: string,
   skills: SkillDef[] = SHARED_SKILLS,
 ): SkillFile[] {
   mkdirSync(skillsDir, { recursive: true });
+  cleanupStaleSkills(skillsDir, skills.map((s) => s.name));
+
   const written: SkillFile[] = [];
 
   for (const skill of skills) {
@@ -78,7 +176,7 @@ export function installSkills(
     try {
       current = readFileSync(file, "utf8");
     } catch {
-      // missing file — first install
+      // missing file - first install
     }
 
     if (current !== skill.content) {

package/src/tool-defs.ts

@@ -14,7 +14,7 @@ const PREDICTION_DEDUP_COSINE = 0.85;
 const PREDICTION_QUERY_THRESHOLD = 0.45;
 
 /**
- * Shared context passed to every tool's execute function. Framework-agnostic —
+ * Shared context passed to every tool's execute function. Framework-agnostic -
  * neither opencode nor MCP specific. The plugin wires real defaults; tests and
  * the MCP server inject whatever they need.
  */
@@ -22,10 +22,22 @@ export interface CoreContext {
   db: ThatchDB;
   model: EmbeddingModel;
   defaultStore: string;
+  /** Peeks the extraction buffer for a session and returns the serialized
+   *  JSON payload (same shape as buildExtractionPayload). Returns null when
+   *  no interactions are queued. Used by the get_extraction_payload tool so
+   *  the sub-agent fetches the payload as a tool response instead of
+   *  receiving it inline in the nudge text. */
+  extractionPayloadProvider?: (sessionID: string) => string | null;
+  /** Drains a session's extraction queue. On the MCP path this deletes the
+   *  file-backed queue and resets the missed-nudge counter. On the opencode
+   *  path this is unused (the tool.execute.after hook handles drain via
+   *  childToParent). Called by extraction_done when the sub-agent passes
+   *  the parent's session_id. */
+  drainExtractionQueue?: (sessionID: string) => void;
 }
 
 /**
- * A tool definition — the single source of truth shared by the opencode plugin
+ * A tool definition - the single source of truth shared by the opencode plugin
  * wrapper (tools.ts) and the MCP server (mcp.ts). The `args` field is a ZodRawShape
  * (a plain object of Zod types), which opencode's `tool()` accepts directly and
  * the MCP server wraps in `z.object()` for validation and `z.toJSONSchema()` for
@@ -39,7 +51,7 @@ export interface ToolDef {
 }
 
 // ---------------------------------------------------------------------------
-// Formatting helpers — shared by all tools that render entries
+// Formatting helpers - shared by all tools that render entries
 // ---------------------------------------------------------------------------
 
 function formatEntry(
@@ -68,7 +80,7 @@ function formatRecallResult(entry: any): string {
 /**
  * Groups candidate pairs into connected components over the similarity graph,
  * so a topic fragmented across N entries reads as one cluster instead of
- * O(N²) pairs. Verdicts stay pairwise (markChecked) — this is presentation only.
+ * O(N²) pairs. Verdicts stay pairwise (markChecked) - this is presentation only.
  */
 function renderClusters(candidates: DedupCandidate[]): string {
   const parent = new Map<string, string>();
@@ -114,7 +126,7 @@ const rememberDef: ToolDef = {
     "reference material for a future instance of yourself with zero context.",
   args: {
     label: z.string().describe(
-      "Short descriptive title. Used for deduplication — same label in the same store is the same entry.",
+      "Short descriptive title. Used for deduplication - same label in the same store is the same entry.",
     ),
     content: z.string().describe(
       "The information to remember. Self-contained, understandable without session context.",
@@ -133,7 +145,7 @@ const rememberDef: ToolDef = {
     ),
     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 — " +
+      "When updating an already-archived memory, this param is REQUIRED - " +
       "pass archived: true to keep it archived, or archived: false to unarchive.",
     ),
   },
@@ -189,7 +201,7 @@ const recallDef: ToolDef = {
       "Maximum number of results. Default 10.",
     ),
     includeArchived: z.boolean().optional().describe(
-      "Include archived memories in results. Default false — archived memories are excluded.",
+      "Include archived memories in results. Default false - archived memories are excluded.",
     ),
   },
   async execute(args, ctx) {
@@ -299,7 +311,7 @@ const findDuplicatesDef: ToolDef = {
   description:
     "Find memories with unusually similar content that may be candidates " +
     "for consolidation. Uses cosine similarity on embeddings. Related pairs " +
-    "are grouped into clusters — a cluster of three or more usually means " +
+    "are grouped into clusters - a cluster of three or more usually means " +
     "one topic fragmented across entries that should be consolidated into " +
     "a single memory. Pairs already reviewed via dedup_mark_checked " +
     "are skipped.",
@@ -357,19 +369,74 @@ const markCheckedDef: ToolDef = {
  * Called in a PARENT session after dispatching the fact-extractor, it accepts
  * the buffer: entries move to a holding area and the nudge quiets, but they
  * are not dropped until the extractor completes. Called in a CHILD extractor
- * at the end of its run, it completes the parent's accepted entries —
+ * at the end of its run, it completes the parent's accepted entries -
  * including no-save runs that write no memory. If the child errors or is
  * deleted before either signal, the host requeues the entries so the facts
  * are not lost.
  *
  * The actual state changes happen in the host's post-tool hook
- * (tool.execute.after for opencode, PostToolBatch/appendBatch for MCP) —
+ * (tool.execute.after for opencode, PostToolBatch/appendBatch for MCP) -
  * this tool's execute function is a no-op confirmation. The tool exists so
  * the model has a recognizable tool name to key on. In the MCP path the
  * file-backed queue is consumed on this call (or on any memory_remember),
  * which is durable across interruption because the queue persists on disk
  * until then.
  */
+/**
+ * Fetches the queued extraction payload for a session. The sub-agent calls
+ * this with the parent's session ID to retrieve the tool interactions that
+ * need fact extraction, instead of receiving them inline in the nudge text.
+ * This keeps the full payload out of the main session's context window.
+ */
+const getExtractionPayloadDef: ToolDef = {
+  name: "get_extraction_payload",
+  description:
+    "Retrieve the queued tool interactions for extraction. Call this with " +
+    "the session_id from the extraction nudge to get the JSON payload " +
+    "(interactions, projectStore, globalStore). Then run the " +
+    "thatch-fact-extractor skill on the returned payload.",
+  args: {
+    session_id: z.string().describe(
+      "The session ID from the extraction nudge. This is the parent session " +
+      "whose tool interactions are queued for extraction.",
+    ),
+  },
+  async execute(args, ctx) {
+    if (!ctx.extractionPayloadProvider) {
+      return "Extraction payload retrieval is not available in this host.";
+    }
+    const payload = ctx.extractionPayloadProvider(args.session_id as string);
+    if (!payload) {
+      return "No queued tool interactions found for this session.";
+    }
+    return payload;
+  },
+};
+
+/**
+ * Extraction-buffer acknowledgment, with AMQP-style accept/complete roles.
+ *
+ * Called in a PARENT session after dispatching the fact-extractor, it accepts
+ * the buffer: entries move to a holding area and the nudge quiets, but they
+ * are not dropped until the extractor completes. Called in a CHILD extractor
+ * at the end of its run, it completes the parent's accepted entries -
+ * including no-save runs that write no memory. If the child errors or is
+ * deleted before either signal, the host requeues the entries so the facts
+ * are not lost.
+ *
+ * The actual state changes happen in the host's post-tool hook
+ * (tool.execute.after for opencode, PostToolBatch/appendBatch for MCP) -
+ * this tool's execute function is a no-op confirmation. The tool exists so
+ * the model has a recognizable tool name to key on. In the MCP path the
+ * file-backed queue is consumed on this call (or on any memory_remember),
+ * which is durable across interruption because the queue persists on disk
+ * until then.
+ *
+ * The optional session_id parameter lets a sub-agent drain the PARENT's
+ * file-backed queue on the MCP path, where the sub-agent's session ID
+ * differs from the parent's and appendBatch's self-detection would drain
+ * the wrong (empty) queue.
+ */
 const extractionDoneDef: ToolDef = {
   name: "extraction_done",
   description:
@@ -377,9 +444,20 @@ const extractionDoneDef: ToolDef = {
     "dispatching the fact-extractor to a sub-agent: accepts the buffer " +
     "(quiets the nudge) while keeping entries until the extractor completes. " +
     "In the fact-extractor sub-agent, call at the end of the run to mark the " +
-    "entries complete, even when nothing was worth saving.",
-  args: {},
-  async execute() {
+    "entries complete, even when nothing was worth saving. Pass session_id " +
+    "when running as a sub-agent to drain the parent session's queue.",
+  args: {
+    session_id: z.string().optional().describe(
+      "The parent session's ID, when called from a sub-agent on the MCP " +
+      "path. Drains the parent's file-backed queue. Omit when called from " +
+      "the parent session itself (opencode path handles drain via hooks).",
+    ),
+  },
+  async execute(args, ctx) {
+    const sessionID = args.session_id as string | undefined;
+    if (sessionID && ctx.drainExtractionQueue) {
+      ctx.drainExtractionQueue(sessionID);
+    }
     return "[acknowledged]";
   },
 };
@@ -502,7 +580,7 @@ const predictionUpdateDef: ToolDef = {
 
       // "create" on an existing prediction means the agent re-observed
       // the same preference in a new context. Link the edge and record
-      // provenance, but do NOT adjust confidence — "create" is
+      // provenance, but do NOT adjust confidence - "create" is
       // confidence-neutral, not a disconfirm.
       if (signal === "create") {
         ctx.db.addProvenance(predictionId, "create", rationale);
@@ -587,6 +665,7 @@ export const TOOL_DEFS: ToolDef[] = [
   findDuplicatesDef,
   markCheckedDef,
   extractionDoneDef,
+  getExtractionPayloadDef,
   predictionQueryDef,
   predictionUpdateDef,
   predictionListDef,

package/src/tools.ts

@@ -6,15 +6,25 @@ import { TOOL_DEFS, type CoreContext } from "./tool-defs";
 /**
  * Builds the opencode tool map from shared tool definitions. Each definition
  * in TOOL_DEFS is wrapped in opencode's `tool()` with a `thatch_` prefix
- * on the name — opencode uses the object key as the tool name, so the prefix
+ * on the name - opencode uses the object key as the tool name, so the prefix
  * lives here, not in the shared definitions.
  */
 export function createTools(
   db: ThatchDB,
   model: EmbeddingModel,
   defaultStore: string,
+  extensions?: {
+    extractionPayloadProvider?: CoreContext["extractionPayloadProvider"];
+    drainExtractionQueue?: CoreContext["drainExtractionQueue"];
+  },
 ): Record<string, ReturnType<typeof tool>> {
-  const ctx: CoreContext = { db, model, defaultStore };
+  const ctx: CoreContext = {
+    db,
+    model,
+    defaultStore,
+    extractionPayloadProvider: extensions?.extractionPayloadProvider,
+    drainExtractionQueue: extensions?.drainExtractionQueue,
+  };
 
   const tools: Record<string, ReturnType<typeof tool>> = {};
   for (const def of TOOL_DEFS) {

package/artifacts/skills/thatch-workflow-research.md

@@ -1,91 +0,0 @@
----
-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.