@jeffober/thatch 0.1.5 → 0.1.6

package/src/mcp.ts

@@ -3,6 +3,7 @@ import { ThatchDB } from "./db";
 import { BgeEmbeddingModel } from "./embeddings";
 import { detectRepo } from "./git";
 import { TOOL_DEFS, type CoreContext, type ToolDef } from "./tool-defs";
+import { SidebandServer, sidebandSocketPath } from "./sideband";
 
 // ---------------------------------------------------------------------------
 // JSON-RPC 2.0 types
@@ -79,6 +80,10 @@ function compileTools(): Map<string, CompiledTool> {
  * model loads lazily on the first tool call that needs it, so the server
  * starts instantly and only pays the ~34 MB download cost when a memory is
  * actually written or recalled.
+ *
+ * A Unix domain socket sideband is opened at startup so that one-shot hook
+ * processes (thatch flush-tools) can ask the warm MCP server to embed a
+ * prompt and search for matches without loading the model themselves.
  */
 export async function runMcpServer(): Promise<void> {
   const projectDir = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
@@ -94,6 +99,19 @@ export async function runMcpServer(): Promise<void> {
   const ctx: CoreContext = { db, model, defaultStore: repo };
   const tools = compileTools();
 
+  // The sideband socket lets one-shot hook processes (flush-tools) ask the
+  // warm MCP server to embed a prompt and search for matches — without
+  // loading the ~34 MB model themselves. If the socket can't be opened
+  // (permissions, tmpdir issues), the MCP server still works; only the
+  // prompt-aware recall nudge degrades.
+  const sockPath = sidebandSocketPath(dbPath);
+  const sideband = new SidebandServer(sockPath, model, db);
+  try {
+    sideband.start();
+  } catch (err) {
+    console.error(`[thatch] sideband socket failed: ${err}`);
+  }
+
   // Read stdin line by line. Each line is a complete JSON-RPC message.
   const decoder = new TextDecoder();
   let buf = "";
@@ -123,6 +141,7 @@ export async function runMcpServer(): Promise<void> {
     }
   }
 
+  sideband.stop();
   db.close();
 }
 

package/src/prompts.ts

@@ -202,3 +202,114 @@ export function claudeExtractionNudge(count: number, payload: string): string {
     `Load the thatch-fact-extractor skill, then use mcp__thatch__memory_remember ` +
     `to save any new durable facts from this payload:\n${payload}`;
 }
+
+/**
+ * Static instructions for Cursor's AGENTS.md. Same contract as
+ * claudeInstructions() — the host loads this at every session start, and the
+ * repo store name is auto-detected at runtime by the MCP server. Tool names
+ * use the same mcp__thatch__ prefix since Cursor discovers MCP tools via the
+ * same protocol.
+ */
+export function cursorInstructions(): string {
+  return `# Persistence
+
+Thatch provides persistent memory across Cursor sessions. Use it to persist
+knowledge so future sessions can build on what you've already learned.
+Tools are prefixed in Cursor: \`mcp__thatch__memory_remember\`,
+\`mcp__thatch__memory_recall\`, \`mcp__thatch__memory_list\`,
+\`mcp__thatch__memory_show\`, \`mcp__thatch__memory_forget\`,
+\`mcp__thatch__store_list\`, \`mcp__thatch__find_duplicates\`,
+\`mcp__thatch__dedup_mark_checked\`.
+Bare names used below for readability.
+
+## Stores
+
+- \`global\`: user preferences, personality, system environment (shared across projects)
+- Per-project stores: project-specific knowledge (auto-detected from git remote)
+- Use \`mcp__thatch__store_list\` to see active stores
+
+Memories can be scoped to a git branch via the \`branch\` param (feature design,
+WIP, PR status). Unscoped memories are project-wide and always included in search.
+
+## Session Startup
+
+1. \`memory_recall\` "user preferences and personality" (global store)
+2. \`memory_recall\` "project architecture and conventions" (project store)
+3. If on a non-main branch, \`memory_recall\` with the branch name
+4. \`memory_list\` and \`store_list\` to see what's available
+
+Before diving into code, \`memory_recall\` with a query relevant to the area
+you're working in. Prior sessions may have already investigated it.
+
+## When to Write
+
+**One signal is enough.** Do not wait for confirmation.
+Save immediately on: feedback, preferences, corrections, emotional signals,
+new project knowledge, conventions, architectural decisions, investigation results.
+
+## What to Store
+
+- **Global store**: user observations, agent personality, system environment
+- **Project store**: repo organization, infrastructure, languages/frameworks,
+  component relationships, conventions, operational playbooks
+- **Branch-scoped**: branch purpose, feature design decisions, PR status,
+  temporary workarounds
+- **Insights**: ALWAYS save non-obvious gotchas, patterns, and architectural
+  lessons discovered during implementation. Never prompt the user; just do it.
+
+## How to Write
+
+- \`memory_recall\` first to check for duplicates. Use overwrite: true to
+  update rather than creating a new entry.
+- One topic per memory. Write for a future instance with zero current context.
+- Confidence 1-2: single signal. 5-6: moderate. 9: explicitly stated.
+  10: hard constraint.
+
+## What NOT to Store
+
+Session-specific context, incomplete/unverified info, anything already in
+AGENTS.md, speculative conclusions.
+
+## Explicit Requests
+
+"Remember X" — save immediately.
+"Forget X" — \`memory_recall\` to find it, then \`memory_forget\`.`;
+}
+
+// ---------------------------------------------------------------------------
+// Prompt-aware recall nudge — fires when the user's prompt semantically
+// matches existing memories. Injected via opencode's chat.message hook
+// (in-process, warm model) or via the sideband socket for Claude Code/Cursor
+// (flush-tools CLI subcommand).
+// ---------------------------------------------------------------------------
+
+export interface NudgeMatch {
+  label: string;
+  score: number;
+}
+
+/**
+ * The recall nudge for the opencode plugin path. Uses the thatch_ tool prefix
+ * since opencode discovers tools directly from the plugin registration.
+ */
+export function recallNudge(matches: NudgeMatch[]): string {
+  return formatRecallNudge(matches, "thatch_memory_recall");
+}
+
+/**
+ * The recall nudge for the Claude Code / Cursor hook path. Uses the bare tool
+ * name (memory_recall) since the mcp__thatch__ prefix is verbose and the
+ * CLAUDE.md / AGENTS.md instructions already establish the bare-name convention.
+ */
+export function claudeRecallNudge(matches: NudgeMatch[]): string {
+  return formatRecallNudge(matches, "memory_recall");
+}
+
+function formatRecallNudge(matches: NudgeMatch[], toolName: string): string {
+  const n = matches.length;
+  const word = n === 1 ? "memory" : "memories";
+  const verb = n === 1 ? "relates" : "relate";
+  const labels = matches.slice(0, 2).map((m) => `"${m.label}"`).join(", ");
+  const etc = n > 2 ? ", etc." : "";
+  return `[thatch] ${n} ${word} ${verb} to this prompt (${labels}${etc}). Use ${toolName} before responding.`;
+}

package/src/setup.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { claudeInstructions } from "./prompts";
+import { claudeInstructions, cursorInstructions } from "./prompts";
 import { installSkills, type SkillFile } from "./skills";
 
 // ---------------------------------------------------------------------------
@@ -91,17 +91,26 @@ function writeMcpConfig(path: string, thatchBin: string): void {
 // ---------------------------------------------------------------------------
 
 const THATCH_MARKER = "# Persistence\n\nThatch provides persistent memory across Claude Code sessions.";
+const THATCH_END_MARKER = '"Forget X" — `memory_recall` to find it, then `memory_forget`.';
+const CURSOR_MARKER = "# Persistence\n\nThatch provides persistent memory across Cursor sessions.";
+const CURSOR_END_MARKER = THATCH_END_MARKER;
 
-function appendInstructions(path: string): void {
-  const instructions = claudeInstructions() + "\n";
-
+/**
+ * Idempotently append (or replace) a block of instructions in a markdown file.
+ * The block is delimited by startMarker and endMarker so re-running setup
+ * updates drifted content without clobbering surrounding text.
+ */
+function appendBlock(
+  path: string,
+  instructions: string,
+  startMarker: string,
+  endMarker: string,
+): void {
   if (existsSync(path)) {
     const existing = readFileSync(path, "utf8");
-    if (existing.includes(THATCH_MARKER)) {
-      // Already has thatch instructions — replace the block.
-      const startIdx = existing.indexOf("# Persistence\n\nThatch provides persistent memory across Claude Code sessions.");
+    if (existing.includes(startMarker)) {
+      const startIdx = existing.indexOf(startMarker);
       if (startIdx >= 0) {
-        const endMarker = '"Forget X" — `memory_recall` to find it, then `memory_forget`.';
         const endIdx = existing.indexOf(endMarker, startIdx);
         if (endIdx >= 0) {
           const afterEnd = endIdx + endMarker.length;
@@ -122,6 +131,14 @@ function appendInstructions(path: string): void {
   }
 }
 
+function appendInstructions(path: string): void {
+  appendBlock(path, claudeInstructions() + "\n", THATCH_MARKER, THATCH_END_MARKER);
+}
+
+function appendCursorInstructions(path: string): void {
+  appendBlock(path, cursorInstructions() + "\n", CURSOR_MARKER, CURSOR_END_MARKER);
+}
+
 // ---------------------------------------------------------------------------
 // settings.json — hook installation
 // ---------------------------------------------------------------------------
@@ -257,3 +274,149 @@ export function setupClaudeCode(
       : null,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Cursor setup — .cursor/mcp.json, AGENTS.md, .cursor/hooks.json, skills
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the Cursor config directory. Cursor stores config under `~/.cursor`
+ * by default. No documented env override exists (unlike Claude Code's
+ * CLAUDE_CONFIG_DIR), but we honor a hypothetical CURSOR_CONFIG_DIR for
+ * symmetry and forward-compatibility.
+ */
+function cursorConfigDir(homeDir: string): string {
+  return process.env.CURSOR_CONFIG_DIR ?? join(homeDir, ".cursor");
+}
+
+interface CursorSetupPaths {
+  mcpConfigPath: string;
+  agentsMdPath: string;
+  hooksPath: string;
+  skillsDir: string;
+  global: boolean;
+}
+
+function resolveCursorPaths(global: boolean, projectDir: string, homeDir: string): CursorSetupPaths {
+  const configDir = cursorConfigDir(homeDir);
+  const skillsDir = join(configDir, "skills");
+
+  if (global) {
+    return {
+      // Cursor's global MCP config is a simple file — no equivalent of
+      // `claude mcp add --scope user`. Writing ~/.cursor/mcp.json is enough.
+      mcpConfigPath: join(configDir, "mcp.json"),
+      agentsMdPath: join(configDir, "AGENTS.md"),
+      hooksPath: join(configDir, "hooks.json"),
+      skillsDir,
+      global: true,
+    };
+  }
+
+  return {
+    mcpConfigPath: join(projectDir, ".cursor", "mcp.json"),
+    agentsMdPath: join(projectDir, "AGENTS.md"),
+    hooksPath: join(projectDir, ".cursor", "hooks.json"),
+    skillsDir,
+    global: false,
+  };
+}
+
+/**
+ * Cursor hooks use a flat format (no nesting, no `type` field):
+ * { "version": 1, "hooks": { "event": [{ "command": "..." }] } }
+ */
+interface CursorHooksJson {
+  version: number;
+  hooks: {
+    [event: string]: { command: string }[];
+  };
+  [key: string]: unknown;
+}
+
+function writeCursorHooks(path: string, thatchBin: string): void {
+  let config: CursorHooksJson = { version: 1, hooks: {} };
+  if (existsSync(path)) {
+    try {
+      config = JSON.parse(readFileSync(path, "utf8"));
+    } catch {
+      // Corrupt — start fresh.
+    }
+  }
+  if (!config.version) config.version = 1;
+  if (!config.hooks) config.hooks = {};
+
+  // --json makes reminder output { additional_context: "..." } which Cursor
+  // injects into the session. Without --json, stdout is plain text (Claude
+  // Code style) and Cursor would not parse it.
+  const sessionStartCmd = `${thatchBin} reminder --json`;
+  // postToolUse fires per-tool (Cursor has no PostToolBatch equivalent).
+  // Silent — no stdout — so the agent loop is not delayed.
+  const bufferCmd = `${thatchBin} buffer-tool`;
+  // beforeSubmitPrompt is Cursor's UserPromptSubmit equivalent. Drains the
+  // queue and prints the extraction nudge as JSON additional_context.
+  const flushCmd = `${thatchBin} flush-tools --json`;
+
+  config.hooks.sessionStart = replaceCursorThatchHooks(config.hooks.sessionStart ?? [], sessionStartCmd);
+  config.hooks.postToolUse = replaceCursorThatchHooks(config.hooks.postToolUse ?? [], bufferCmd);
+  config.hooks.beforeSubmitPrompt = replaceCursorThatchHooks(config.hooks.beforeSubmitPrompt ?? [], flushCmd);
+
+  mkdirSync(join(path, ".."), { recursive: true });
+  writeFileSync(path, JSON.stringify(config, null, 2) + "\n");
+}
+
+function replaceCursorThatchHooks(
+  entries: { command: string }[],
+  command: string,
+): { command: string }[] {
+  const filtered = entries.filter((e) => !e.command?.includes("thatch"));
+  filtered.push({ command });
+  return filtered;
+}
+
+export interface CursorSetupResult {
+  mcpConfig: string;
+  agentsMd: string;
+  hooks: string;
+  skills: SkillFile[];
+  global: boolean;
+}
+
+/**
+ * Installs thatch into Cursor. Writes .cursor/mcp.json (or ~/.cursor/mcp.json
+ * for global), appends instructions to AGENTS.md, installs sessionStart +
+ * postToolUse + beforeSubmitPrompt hooks in .cursor/hooks.json, and installs
+ * skill files. All operations are idempotent.
+ *
+ * Cursor's global MCP config is a simple file write (unlike Claude Code which
+ * needs `claude mcp add --scope user`). Skills install to ~/.cursor/skills/
+ * (auto-discovered by Cursor, which also reads ~/.claude/skills/ for compat).
+ *
+ * @param thatchBin Absolute path to the thatch binary
+ * @param global Whether to install globally or project-locally
+ * @param projectDir The project directory (used for project-local installs)
+ * @param homeDir Home directory (defaults to os.homedir())
+ */
+export function setupCursor(
+  thatchBin: string,
+  global: boolean,
+  projectDir: string,
+  homeDir?: string,
+): CursorSetupResult {
+  const { homedir } = require("node:os");
+  const home = homeDir ?? homedir();
+  const paths = resolveCursorPaths(global, projectDir, home);
+
+  writeMcpConfig(paths.mcpConfigPath, thatchBin);
+  appendCursorInstructions(paths.agentsMdPath);
+  writeCursorHooks(paths.hooksPath, thatchBin);
+  const skills = installClaudeSkills(paths.skillsDir);
+
+  return {
+    mcpConfig: paths.mcpConfigPath,
+    agentsMd: paths.agentsMdPath,
+    hooks: paths.hooksPath,
+    skills,
+    global,
+  };
+}

package/src/sideband.ts

@@ -0,0 +1,207 @@
+import { createHash } from "node:crypto";
+import { unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createServer, connect, type Server, type Socket } from "node:net";
+import type { ThatchDB } from "./db";
+import type { EmbeddingModel } from "./embeddings";
+
+/**
+ * Deterministic socket path from the DB path. Both the MCP server and hook
+ * processes resolve the same DB path (from THATCH_DB_PATH or the default
+ * under XDG_CONFIG_HOME), so they independently arrive at the same socket
+ * path without any out-of-band coordination.
+ */
+export function sidebandSocketPath(dbPath: string): string {
+  const hash = createHash("sha256").update(dbPath).digest("hex").slice(0, 16);
+  return join(tmpdir(), `thatch-${hash}.sock`);
+}
+
+export interface SidebandMatch {
+  label: string;
+  score: number;
+  store: string;
+}
+
+interface MatchRequest {
+  method: "match";
+  text: string;
+  stores: string[];
+  threshold: number;
+  limit: number;
+}
+
+interface MatchResponse {
+  ok: boolean;
+  matches?: SidebandMatch[];
+  error?: string;
+}
+
+/**
+ * Serves embedding + semantic search requests over a Unix domain socket.
+ * The MCP server (long-lived, warm model) runs this so that one-shot hook
+ * processes can ask "does this prompt match any memories?" without loading
+ * the ~34 MB model themselves.
+ *
+ * The protocol is newline-delimited JSON: one request per connection, one
+ * response per connection. Requests are `{"method":"match","text":"...",
+ * "stores":[...],"threshold":N,"limit":N}`. Responses are `{"ok":true,
+ * "matches":[...]}` or `{"ok":false,"error":"..."}`.
+ */
+export class SidebandServer {
+  #server: Server | null = null;
+  #path: string;
+  #model: EmbeddingModel;
+  #db: ThatchDB;
+
+  constructor(path: string, model: EmbeddingModel, db: ThatchDB) {
+    this.#path = path;
+    this.#model = model;
+    this.#db = db;
+  }
+
+  /** Opens the socket. Cleans up any stale socket file from a crashed server. */
+  start(): void {
+    try {
+      unlinkSync(this.#path);
+    } catch {
+      // No stale socket — expected on first run.
+    }
+
+    this.#server = createServer((socket) => {
+      this.#handleConnection(socket);
+    });
+
+    this.#server.listen(this.#path);
+  }
+
+  /** Closes the socket and removes the socket file. */
+  stop(): void {
+    this.#server?.close();
+    this.#server = null;
+    try {
+      unlinkSync(this.#path);
+    } catch {
+      // Already gone.
+    }
+  }
+
+  get path(): string {
+    return this.#path;
+  }
+
+  #handleConnection(socket: Socket): void {
+    let buf = "";
+    socket.on("data", (chunk: Buffer) => {
+      buf += chunk.toString();
+      const nl = buf.indexOf("\n");
+      if (nl < 0) return;
+
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      this.#handleRequest(line, socket);
+    });
+    socket.on("error", () => {
+      // Client disconnected abruptly — nothing to do.
+    });
+  }
+
+  async #handleRequest(line: string, socket: Socket): Promise<void> {
+    let req: MatchRequest;
+    try {
+      req = JSON.parse(line);
+    } catch {
+      this.#respond(socket, { ok: false, error: "Invalid JSON" });
+      return;
+    }
+
+    if (req.method !== "match") {
+      this.#respond(socket, { ok: false, error: `Unknown method: ${req.method}` });
+      return;
+    }
+
+    try {
+      const embedding = await this.#model.queryEmbed(req.text);
+      const results = this.#db.search(req.stores, embedding, { limit: req.limit });
+      const matches: SidebandMatch[] = results
+        .filter((r) => r._score >= req.threshold)
+        .map((r) => ({
+          label: r.label,
+          score: Math.round(r._score * 1000) / 1000,
+          store: r.store,
+        }));
+      this.#respond(socket, { ok: true, matches });
+    } catch (err: any) {
+      this.#respond(socket, { ok: false, error: String(err?.message ?? err) });
+    }
+  }
+
+  #respond(socket: Socket, res: MatchResponse): void {
+    if (!socket.destroyed) {
+      socket.write(JSON.stringify(res) + "\n");
+    }
+  }
+}
+
+/**
+ * Connect to the sideband server and request semantic matches for a prompt.
+ * Returns null on any failure (server not running, stale socket, timeout) —
+ * callers must treat null as "skip the recall nudge" and fall back gracefully.
+ */
+export function sidebandMatch(
+  socketPath: string,
+  text: string,
+  stores: string[],
+  threshold: number,
+  limit: number,
+  timeoutMs = 2000,
+): Promise<SidebandMatch[] | null> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (val: SidebandMatch[] | null) => {
+      if (settled) return;
+      settled = true;
+      resolve(val);
+    };
+
+    const socket = connect(socketPath);
+    const req = JSON.stringify({ method: "match", text, stores, threshold, limit }) + "\n";
+    let buf = "";
+
+    const timer = setTimeout(() => {
+      socket.destroy();
+      done(null);
+    }, timeoutMs);
+
+    socket.on("error", () => {
+      clearTimeout(timer);
+      // Stale socket file left by a crashed server — clean it up so the next
+      // connection attempt doesn't hit ECONNREFUSED again.
+      try {
+        unlinkSync(socketPath);
+      } catch {
+        // Already gone or never existed.
+      }
+      done(null);
+    });
+
+    socket.on("connect", () => {
+      socket.write(req);
+    });
+
+    socket.on("data", (chunk: Buffer) => {
+      buf += chunk.toString();
+      const nl = buf.indexOf("\n");
+      if (nl < 0) return;
+
+      clearTimeout(timer);
+      try {
+        const res = JSON.parse(buf.slice(0, nl)) as MatchResponse;
+        done(res.ok ? (res.matches ?? []) : null);
+      } catch {
+        done(null);
+      }
+      socket.destroy();
+    });
+  });
+}

package/src/skills.ts

@@ -649,25 +649,33 @@ For each finding from the specialists:
 
 3. **Determine provenance.** Is the finding a new issue introduced by this change, or a pre-existing problem? Note pre-existing bugs separately.
 
-4. **Check runtime model applicability.** Can the finding realistically manifest in normal usage given the application's runtime model? A finding that requires conditions impossible in the actual runtime context is not a real bug (e.g., state accumulation in a short-lived process, concurrency in single-threaded code).
+**Finding type determines which steps apply next.** Steps 4-6 apply to behavioral findings (from acceptance, state-flow). Mechanical findings (from pedantic, no-slop, breadcrumbs — docs, naming, style, comments, prose) skip steps 4-6 and use the mechanical verification criteria in step 4m instead.
 
-5. **Prove the causal chain** for any finding about state, data shape, cross-module contracts, or behavior:
+4. **Check runtime model applicability (behavioral findings only).** Can the finding realistically manifest in normal usage given the application's runtime model? A finding that requires conditions impossible in the actual runtime context is not a real bug (e.g., state accumulation in a short-lived process, concurrency in single-threaded code).
+
+5. **Prove the causal chain (behavioral findings only)** for any finding about state, data shape, cross-module contracts, or behavior:
    - Identify the authoritative producer or source of the state/data.
    - Identify the transforms between producer and consumer.
    - Identify the consumer or branch where failure occurs.
    - Identify the real entrypoint/workflow that exercises this chain.
    If the only way to trigger the issue is by manually fabricating invalid data/state or bypassing the real producers/guards, reject the finding. If the citation is real but you cannot prove the producer chain, classify as UNVERIFIABLE rather than CONFIRMED.
 
-6. **Verify intent.** If the specialist flagged behavior as a bug but the code appears to work as designed, check whether the behavior is intentional:
+6. **Verify intent (behavioral findings only).** If the specialist flagged behavior as a bug but the code appears to work as designed, check whether the behavior is intentional:
    - Read the callers of the cited code to see if the pattern makes sense in context.
    - Check git log or git blame on the cited file for commit messages explaining the decision.
    - Use thatch_memory_recall to search for documented rationale.
    If the behavior is intentional or an accepted limitation, reject the finding.
 
+4m. **Mechanical verification (pedantic, no-slop, breadcrumbs, docs, naming, style, comments).** For mechanical findings, verification means:
+   - The cited text exists at the cited location (already confirmed in step 2).
+   - The finding is branch-introduced or newly made relevant by the change. Pre-existing issues go in the pre-existing appendix, not rejected.
+   - The cited text violates the stated guideline, specialist taxonomy, or project norm. Identify the source of truth: the specific guideline, convention, or writing norm being violated.
+   Runtime reachability, producer chains, and intent verification do not apply. A mechanical finding is not a "bug" and does not need a "trigger scenario."
+
 7. **Classify:**
-   - **CONFIRMED**: The cited code matches, the claim is accurate, the bug is reachable through realistic usage, you proved the workflow/producer chain where applicable, and the behavior is not intentional.
-   - **REJECTED**: The citation is wrong, the claim is inaccurate, the bug cannot manifest in the actual runtime context, or the behavior is an intentional design decision (explain why briefly). Reject findings that rely on manually seeded invalid state/data with no real producer path.
-   - **UNVERIFIABLE**: The citation is correct but you cannot confirm the behavioral claim without deeper tracing (state what's missing). This is the default for plausible claims that lack a proven trigger path, producer chain, or authoritative source of truth.
+   - **CONFIRMED**: For behavioral findings: the cited code matches, the claim is accurate, the bug is reachable through realistic usage, you proved the workflow/producer chain where applicable, and the behavior is not intentional. For mechanical findings: the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy.
+   - **REJECTED**: For behavioral findings: the citation is wrong, the claim is inaccurate, the bug cannot manifest in the actual runtime context, or the behavior is an intentional design decision (explain why briefly). Reject findings that rely on manually seeded invalid state/data with no real producer path. For mechanical findings: the cited text does not exist, does not violate the stated guideline, is unchanged legacy outside the touched scope, or the finding duplicates another confirmed finding.
+   - **UNVERIFIABLE**: The citation is correct but you cannot confirm the claim without deeper tracing. This is the default for plausible behavioral claims that lack a proven trigger path, producer chain, or authoritative source of truth. Mechanical findings should rarely be UNVERIFIABLE — if the text exists and violates the guideline, it is CONFIRMED.
 
 ## Deduplication
 
@@ -687,6 +695,8 @@ Assign final severity based on YOUR verification:
 
 You MUST produce the full report structure below. Do not simplify or omit sections. Every confirmed finding must include all numbered fields. If a section has no entries, write "None" — do not skip the section.
 
+Confirmed LOW findings are mandatory. Do not summarize them away or omit them for being non-functional. Pedantic, no-slop, breadcrumbs, docs, naming, style, and comment findings are first-class review findings when confirmed. Group them under LOW, but include every one.
+
 ### Scope
 - Branch/range reviewed
 - Design context (if provided)
@@ -858,13 +868,15 @@ For the integration review unit (5+ points), dispatch a sub-agent focused on:
 
 After all sub-agents complete, load the thatch-review-synthesizer skill to verify findings, deduplicate across specialists, classify (CONFIRMED/REJECTED/UNVERIFIABLE), and produce the final severity-grouped report.
 
+Confirmed LOW findings are mandatory in the final report, including mechanical findings (pedantic, no-slop, breadcrumbs, docs, naming, style, comments). Do not omit them for being non-functional.
+
 Alternatively, perform the synthesis yourself:
 1. Read each finding's cited location to verify evidence accuracy.
 2. Deduplicate findings flagged by multiple specialists.
 3. Group findings by root cause where multiple findings stem from the same issue.
-4. Classify each as CONFIRMED, REJECTED, or UNVERIFIABLE based on citation verification, reachability, and intent verification.
+4. Classify each as CONFIRMED, REJECTED, or UNVERIFIABLE. For behavioral findings, apply citation verification, reachability, and intent verification. For mechanical findings, verify the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy.
 5. Calibrate severity (BLOCKING > HIGH > MEDIUM > LOW) based on your verification.
-6. Produce a final report grouped by severity, with coverage gaps noted.
+6. Produce a final report grouped by severity, with coverage gaps noted. Include every confirmed LOW finding.
 
 ## Specialist briefing template