@jeffober/thatch 0.1.46 → 0.1.47

package/README.md

@@ -175,8 +175,8 @@ Thatch gives your agent:
   or quiet notifications entirely.
 
 Plus **skills** for memory workflows, structured multi-specialist code
-review, review response, change and feature walkthroughs, memory verification,
-knowledge export, and writing tasks
+review, review response, plan refinement, change and feature walkthroughs,
+memory verification, knowledge export, and writing tasks
 (PR descriptions, tickets, PR splitting).
 
 See the [user guide](https://github.com/sysread/thatch/wiki/Guide%3A-Overview) for the full tool list, CLI

package/artifacts/skills/thatch-plan-refinement.md

@@ -0,0 +1,80 @@
+---
+name: thatch-plan-refinement
+description: Refine a plan for a code change by dispatching a fresh-context reviewer subagent to hunt for gaps, unverified premises, and unexpected side effects, then revising and re-reviewing until consensus. Use when a plan is about to be implemented, when the user asks to refine, stress-test, or double-check a plan, or after a plan revision that incorporated prior findings. Quick mode is one fresh reviewer per round; deep mode adds a specialist lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology).
+---
+
+You are refining a plan before code exists. A plan written by the same context that researched the problem inherits that context's blind spots. A reviewer with no stake in the plan and no memory of writing it finds what the author cannot. Refinement is the loop: draft, review, revise, repeat until consensus. Each pass tightens the plan; a round with no findings means the plan is done, not that the loop failed.
+
+This is the plan-stage counterpart to code review: code review applies multi-lens scrutiny to a diff that exists; refinement applies it to a plan, where findings cost nothing to fix.
+
+## Mode triage
+
+Pick the mode before starting, and say which you picked.
+
+**Skip refinement** for single-file mechanical changes, typo or docs-only changes, and changes that follow an established pattern with no design decisions. A single self-review pass is enough; running this loop on a five-line change is waste.
+
+**Quick mode (default)** — one fresh-context reviewer per round. Use for everything that is not trivial and not deep-mode material.
+
+**Deep mode** — adds a one-time specialist lens fan-out (see below) before the consensus rounds. Use when the plan: touches shared or persistent state (database tables, files, config) that other consumers read; spans many files or multiple hosts/processes; introduces a new abstraction, table, or contract; or when the user asks for depth. Deep mode runs the lenses ONCE, in the first round; the remaining rounds are quick-mode consensus on the revised plan.
+
+## The loop
+
+1. **Draft the plan.** Every factual premise carries a `file:line` citation you personally verified. A premise you did not check is a guess wearing a citation; verify it or mark it unverified.
+2. **Dispatch one reviewer** (read-only). The prompt must instruct it to:
+   - Verify each premise against the actual code, with `file:line` evidence.
+   - Give each plan step a verdict: CORRECT, NEEDS ADJUSTMENT (how), or WRONG (why).
+   - Hunt for gaps by severity (blocker / should-fix / nice-to-have), unexpected side effects, blast radius, and the question "how does this fail in production?" — concurrency, stale state, multi-host interactions, test flakiness, and behavior changes for existing callers.
+   - Say explicitly when it cannot verify something, rather than guessing.
+3. **Revise the plan** from the findings. Fix what is wrong, adjust what needs adjusting, and record what you rejected and why.
+4. **Dispatch a NEW reviewer with fresh context** on the revised plan. Never continue the prior reviewer's session, and never tell it what previous reviewers said — prior findings anchor the next reviewer, and it will inherit the earlier reviewer's blind spots instead of finding its own. Present the revised plan as if it were the original.
+5. **Consensus** is a round where the reviewer reports no blockers, no unaddressed should-fixes, and the plan's premises all verify. Two consecutive quiet rounds is strong consensus; one is enough to build.
+6. **Cap at three review rounds.** If the plan has not converged by then, stop looping and put the remaining disagreements in front of the user — continued revision usually means the design problem, not the plan, is unresolved.
+
+## Deep mode: the lenses
+
+Run each lens as its own fresh read-only agent, in parallel where the host allows. The lenses see the plan plus the problem context — never prior review findings. Before the fan-out, run `thatch_memory_recall` for the plan's topic and include what comes back as a "prior knowledge from project memory" block in every lens prompt: lens agents are plain read-only sub-agents WITHOUT thatch MCP tools, so the coordinator is the only side of the fan-out that can reach project memory — a lens told to "consult project memory" will report a spurious unverifiable-input hole instead (observed in the first dogfood run). Mark the block as unverified context, not established fact; the archaeology lens treats it as a lead to check, not a source to cite. Collect the results, synthesize (dedupe by root cause, severity-group, keep only verified findings), revise the plan, then continue with quick-mode rounds.
+
+**Pattern and reuse.** Find existing patterns, helpers, and abstractions in the codebase that the plan could reuse or extend instead of adding new surface. The verification gate: the lens must READ the code it cites and show the contract fits the plan's need — a pattern claim from memory or a name match is not evidence, and a wrong "reuse X" sends the design down a bad path. Output: reusable candidates with `file:line` and fit analysis, or an explicit "none found".
+
+**Alternatives.** Research materially different solutions to the same problem and judge the juice-to-squeeze ratio against the plan's actual constraint set. Budget: at most two alternatives, each argued in a paragraph — this lens is a filter, not a survey. "No better alternative found" is a valid, expected, honest output; padding with straw men is worse than an empty result.
+
+**Hidden problems (pre-mortem).** Enumerate every consumer of each symbol, table, file, and config value the plan touches (grep, not memory). Enumerate state the plan writes, moves, or invalidates, and who reads it after the change — including other hosts, processes, and hook paths sharing the same database or files. Then mentally apply the change and diff the failure modes: what breaks downstream, what silently changes meaning. This lens owns the question "who knows about this state that the plan does not?"
+
+**Safe-to-modify audit.** For each code section the plan must touch: is there test coverage that would catch a regression (name the test), and is the section in shape to modify without a rewrite? Verdict per section: **safe**, **refactor-first** (the plan gains an explicit dependency: refactor before the change), or **stop-and-ask** (structural problem — surface to the user before building). Audit only sections the plan touches; auditing the whole repo is out of scope. A missing-coverage section is refactor-first or stop-and-ask, never "safe, we'll add tests later" — coverage comes before the change, not after.
+
+**Archaeology (intent).** For the code in the change's path, find out WHY it is the way it is: git history (commits, PR descriptions and review discussions, merge messages), ticket history, code comments, and docs — all reachable from a read-only agent via git and the gh CLI. Project memory arrives only via the coordinator-injected prior-knowledge block in your prompt (you have no memory tools); treat it as a lead to verify, not a citable source. Every intent claim cites its evidence. Where the evidence runs out, record exactly that — "unknown, not enough detail available" — and stop. NEVER construct a plausible intent from how the code looks: unstated intent is treated as unknown, and the plan must not build on assumed intent. The deliverable is a map of evidenced intent plus an explicit unknowns list, so the plan can ask the user about the unknowns instead of hallucinating past them.
+
+## Dispatching across hosts
+
+The fan-out needs sub-agents, and every host has them — couch the instructions per host, the same way code review does:
+
+- **opencode**: Task tool, read-only explore-type agent, one agent per lens.
+- **Claude Code**: Agent tool; the skill runs inline, each lens is one Agent dispatch.
+- **Cursor**: background subagents, one per lens.
+
+Single level of dispatch only — lenses never dispatch further agents. If the host or session cannot dispatch sub-agents, degrade honestly: run each lens as a separate focused self-review pass in sequence, and tell the user the review is weaker than the real thing (same-context review misses what fresh-context review catches).
+
+## When the user insists on proceeding with open findings
+
+Do not argue, and do not silently drop the findings. Reduce the risk of building with known holes:
+
+- For each open finding, attach an explicit mitigation or mark it as an accepted risk. A mitigation is one of: a test that guards the risky behavior, a rollout or feature-flag plan, a log or assertion that makes the failure loud when it happens, or a documented rollback path.
+- "We discussed it and the user said go" is not a mitigation. Name what will catch the failure if the reviewer was right.
+- Present the list of accepted risks to the user in one place before implementation starts, and keep it with the plan so a future session can see what was knowingly left open.
+
+## Reviewer prompt rules
+
+- Give the reviewer the problem context and the plan. Give it neither your research transcript nor earlier review findings.
+- Demand `file:line` evidence for every claim, and explicit "unverified" where it cannot check.
+- Ask it to state whether the plan's own list of affected surfaces is complete or over-broad. Plan authors over-scope and under-scope in equal measure.
+- Tell it the repo is read-only for this task.
+
+## Cost control
+
+One reviewer per round in quick mode; one lens fan-out total in deep mode, then quick rounds. Foreground dispatches — the loop is sequential by design, and the fresh-context requirement, not reviewer count, is what buys independence. Parallel reviewers multiply context spend without adding much signal at plan stage.
+
+## Relationship to other skills
+
+- **`thatch-code-archaeology`** — the research skill for understanding the code; its output is often the plan's input. The archaeology lens is a targeted, plan-scoped re-run of its git-history step, not a replacement for it.
+- **`thatch-coding-workflow`** — the procedure skill for executing the refined plan. Refinement ends where coding-workflow begins.
+- **`thatch-code-review`** — the post-implementation multi-lens pipeline. Same machinery, different artifact and stage. Findings from code review that reveal a plan flaw are a signal to refine the plan for the NEXT change, not to loop backwards.

package/bin/thatch

@@ -3,7 +3,7 @@
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import pkg from "../package.json" with { type: "json" };
-import { ThatchDB } from "../src/db";
+import { ThatchDB, repoPathCache } from "../src/db";
 import { detectRepo } from "../src/git";
 import { BgeEmbeddingModel } from "../src/embeddings";
 import { hygieneReport } from "../src/hygiene";
@@ -75,9 +75,13 @@ global store. Use "all" with search to search project + global together.`);
 
 async function defaultStore(): Promise<string> {
   try {
-    return await detectRepo();
+    // The cache recovers identity when the project directory is gone
+    // (deleted worktree). Same unknown-to-global mapping the tool layer
+    // applies, so the CLI never lands on a literal "unknown" store.
+    const repo = await detectRepo(undefined, repoPathCache(db));
+    return repo === "unknown" ? "global" : repo;
   } catch {
-    return "unknown";
+    return "global";
   }
 }
 
@@ -97,7 +101,10 @@ async function chatHookLine(hookSessionID?: string, transcriptPath?: string): Pr
   if (!chatEnabled(loadConfig(dbPath).config)) return "";
   let repo: string | null = null;
   try {
-    repo = await detectRepo();
+    const detected = await detectRepo(undefined, repoPathCache(db));
+    // unknown-to-global: chat registration must follow the same store the
+    // tools would read, even when the project directory is gone.
+    repo = detected === "unknown" ? "global" : detected;
   } catch {
     return "";
   }
@@ -730,7 +737,7 @@ switch (command) {
     const worktree = projectDir();
     let hygiene: string | null = null;
     try {
-      hygiene = await hygieneReport(db, repo, worktree);
+      hygiene = await hygieneReport(db, repo, worktree, repoPathCache(db));
     } catch (err) {
       console.error(`[thatch] hygiene report failed: ${err}`);
     }
@@ -768,7 +775,7 @@ switch (command) {
   case "hygiene": {
     const repo = await defaultStore();
     const worktree = projectDir();
-    const hygiene = await hygieneReport(db, repo, worktree);
+    const hygiene = await hygieneReport(db, repo, worktree, repoPathCache(db));
     console.log(hygiene ?? "Store is healthy.");
     break;
   }
@@ -1003,7 +1010,8 @@ switch (command) {
       const { detectSkew, readNpmCacheForUpdate } = await import("../src/version-check");
 
       let repo = "unknown";
-      try { repo = await detectRepo(); } catch {}
+      try { repo = await detectRepo(undefined, repoPathCache(db)); } catch {}
+      if (repo === "unknown") repo = "global";
 
       // Version checks (best-effort, no network, instant):
       //   - Skew: the running MCP server's version file differs from this
@@ -1214,7 +1222,8 @@ switch (command) {
       }
 
       let repo = "unknown";
-      try { repo = await detectRepo(); } catch {}
+      try { repo = await detectRepo(undefined, repoPathCache(db)); } catch {}
+      if (repo === "unknown") repo = "global";
 
       const { sidebandPredictions, sidebandSocketPath } = await import("../src/sideband");
       const { predictionNudge } = await import("../src/prompts");

package/docs/dev/README.md

@@ -22,7 +22,7 @@ Shared core
   ├── tool-defs.ts    → single source of truth: zod schemas + execute logic
   ├── db.ts           → SQLite CRUD, cosine search (recall + search), dedup verdicts
   ├── embeddings.ts   → embedding model via transformers.js
-  ├── git.ts          → detect repo identity (store name)
+  ├── git.ts          → detect repo identity (store name) + worktree-deletion recovery (repo_paths cache)
   ├── hygiene.ts      → hygiene report (pending dedups, stale, orphaned branches)
   ├── prompts.ts      → system prompt, compaction, reminders, recall/prediction/behavior nudges, prompt cores, CLAUDE.md instructions
   ├── commands.ts     → /thatch slash-command registry: actions from prompt cores + wrap-ups, per-host sync
@@ -72,7 +72,7 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `index.ts` | OpenCode plugin entry. Wires DB, model, extraction; registers tools and hooks; installs skills. Internal state beyond the extraction pipeline: `extracting` set (parent IDs with an active direct-extraction child), `childMetrics` map (new/updated/deleted counts per child session), and `triggerExtraction(parentID)` (creates a child session via the SDK client and prompts it with the extraction payload). |
 | `setup.ts` | `thatch setup --claude` / `--cursor` installer. Writes MCP config (`.mcp.json` / `.cursor/mcp.json`), appends to CLAUDE.md / AGENTS.md (idempotent), installs hooks in settings.json / hooks.json, installs skills. |
 | `hygiene.ts` | Hygiene report: pending dedup pairs, stale count, orphaned branch memories. Shared by the plugin's session-start hook and the CLI's `thatch reminder` command. |
-| `git.ts` | Parse `owner/repo` from git remote. Worktree-safe fallback chain. |
+| `git.ts` | Parse `owner/repo` from git remote. Worktree-safe fallback chain, plus recovery from the `repo_paths` cache when the directory is deleted, and the spawn-cwd fallback. See [features/repo-identity.md](features/repo-identity.md). |
 | `db.ts` | SQLite schema, CRUD for entries/stores, brute-force cosine search (`search` = pure scoring, `recall` = search + telemetry stamping), dedup-pair verdict tracking. Prediction tables: matchers, predictions, edges, provenance. `scorePredictionNudge` is the shared auto-fire entry point for both host paths. Behavior tables: same four-table shape (matchers, behaviors, edges, provenance) with `scoreBehaviorNudge` as the shared entry point. |
 | `embeddings.ts` | Lazy-load the embedding model. Expose `queryEmbed`/`passageEmbed` and the model `name` (stored as an informational tag). `MockEmbeddingModel` for tests. |
 | `extraction.ts` | Per-session in-memory ring buffer (cap 20) that buffers non-thatch tool interactions and serializes them into the JSON payload the `get_extraction_payload` tool returns. The in-memory pipeline is opencode-only, but the payload builders (`buildExtractionPayload`, `deriveTitle`) are shared by both paths — `extract-queue.ts` imports `deriveTitle`, `mcp.ts` imports `buildExtractionPayload` for the extraction payload provider. `summarizeArgs` is used internally by `buildExtractionPayload`. |
@@ -86,7 +86,7 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `sideband.ts` | Unix domain socket server + client. The MCP server (long-lived, warm model) runs `SidebandServer` so one-shot hook processes can ask it to embed a prompt and search for matches without loading the model themselves. Handles three methods: `match` (recall nudge), `predictions` (prediction auto-fire), and `behaviors` (behavior auto-fire). Socket path is a hash of the DB path — both processes compute it independently. |
 | `prompts.ts` | Text constants: opencode system prompt, compaction context, session-start reminder, prompt-aware recall nudge (`recallNudge` / `claudeRecallNudge`), prediction nudge (`predictionNudge`), behavior nudge (`behaviorNudge`), prediction verb selection (`predictionVerb`), watcher notification (`watcherNotificationNudge`), version warning (`versionWarningNudge`), chat wake notification (`chatNotificationNudge`), chat transcript echo text and echo recognizer (`chatEchoText` / `isChatEchoParts`), Claude Code CLAUDE.md instructions, Cursor AGENTS.md instructions, Claude Code hook text. Also the prompt cores (`defragCore`, `hygieneCore`, `reflectCore`, `extractionCore`) - host-agnostic behavior instruction bodies shared by nudges and `/thatch` commands, parameterized by a `ToolNamer` for per-host tool spellings. See [features/commands.md](features/commands.md). |
 | `commands.ts` | Slash-command registry and sync. `actionDefs(tool)` renders the on-demand actions (defrag, extract, hygiene, reflect) from the prompt cores; the wrap-up commands (compact, exit) are bespoke greenlight-gated templates. Renderers produce full command files for opencode (`installOpencodeCommands`, synced by the plugin at init) and Claude Code (`installClaudeCommands`, synced by setup); `compilePrompts` in `mcp.ts` exposes the same actions as MCP prompts for Cursor. A parity-guard test pins the three sets to the documented exclusions. See [features/commands.md](features/commands.md). |
-| `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (fact-extractor, dedup-classifier, project-primer, the review specialists, review synthesizer, review context, code archaeology, review followup, review response, change walkthrough, code walkthrough, session reflection, coding-workflow, thatch-pr-description, thatch-ticket-description, thatch-split-overlarge-pr, memory-verify, knowledge-export — work on all three hosts) and `OPENCODE_ONLY_SKILLS` (code-review coordinator — requires sub-agent support, not installed for Claude Code or Cursor). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
+| `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (fact-extractor, dedup-classifier, project-primer, the review specialists, review synthesizer, review context, code archaeology, review followup, review response, change walkthrough, code walkthrough, session reflection, coding-workflow, plan-refinement, thatch-pr-description, thatch-ticket-description, thatch-split-overlarge-pr, memory-verify, knowledge-export — work on all three hosts) and `OPENCODE_ONLY_SKILLS` (code-review coordinator — requires sub-agent support, not installed for Claude Code or Cursor). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
 | `scoring-engine.ts` | Generic four-table scoring engine with Bayesian confidence. Shared base for prediction and behavior engines — each wraps it with table-specific names. |
 | `prediction.ts` | Thin wrapper around `ScoringEngine` with prediction-specific table names. |
 | `behavior.ts` | Thin wrapper around `ScoringEngine` with behavior-specific table names. |

package/docs/dev/features/cli.md

@@ -31,7 +31,7 @@ The thatch CLI is a Bun script at `bin/thatch`. It provides memory inspection, M
 - Unknown command or missing required arg calls `usage()` and exits 1.
 - Args are positional, parsed by hand from `process.argv.slice(2)`. No arg-parsing library.
 - DB opened once at startup, closed at end (except `mcp` which closes early).
-- Stores default to git remote detected by `detectRepo()`; "unknown" on failure. "global" is the shared store. "all" (search only) means project + global.
+- Stores default to git remote detected by `detectRepo()`; "unknown" (no git repo, or a deleted project directory with no cache entry) degrades to "global". "global" is the shared store. "all" (search only) means project + global.
 
 ## prime
 

package/docs/dev/features/database.md

@@ -18,6 +18,7 @@ The tables fall into these groups:
 | Prediction engine | `prediction_matchers`, `predictions`, `prediction_edges`, `prediction_provenance` | User decision model |
 | Behavior engine | `behavior_matchers`, `behaviors`, `behavior_edges`, `behavior_provenance` | LLM self-discipline rules |
 | Cross-session chat | `chat_sessions`, `chat_messages` | Session directory + message inbox (shared across opencode processes) |
+| Repo identity | `repo_paths` | Worktree-to-main-checkout cache for identity recovery after deletion |
 
 The prediction and behavior engines share the same four-table shape (matchers, items, edges, provenance) with different table names. They are separate because the semantics differ: predictions model what the user wants; behaviors model what the LLM should do.
 
@@ -264,6 +265,30 @@ chat_messages(
 
 See [cross-session-chat.md](cross-session-chat.md) for the delivery model.
 
+### repo_paths
+
+```sql
+repo_paths(
+  worktree_path TEXT PRIMARY KEY,
+  main_path     TEXT NOT NULL,
+  repo_slug     TEXT NOT NULL,
+  resolved_at   INTEGER NOT NULL
+)
+```
+
+- Records, per worktree directory (realpath-canonicalized key), the main
+  checkout path and the repo identity that `detectRepo` resolved while the
+  directory was alive. Read after the directory is deleted -- the recovery
+  and validation rules live in [repo-identity.md](repo-identity.md).
+- Written by `detectRepo` on successful remote or common-dir resolution,
+  never from the basename fallback. Rows are evicted only on definitive
+  invalidation (the main checkout exists but is no longer the recorded
+  repo); a missing main checkout keeps the row, since a re-clone may be in
+  progress.
+
+See [repo-identity.md](repo-identity.md) for the resolution and eviction
+rules.
+
 ## Schema migration
 
 `recall_count`, `last_recalled_at`, and `archived` are added to pre-existing databases by an idempotent column migration at init. The migration uses `PRAGMA table_info` to check for the column's existence, then `ALTER TABLE ADD COLUMN` if missing. This handles databases created before these columns existed.

package/docs/dev/features/multi-host.md

@@ -42,7 +42,9 @@ startup.
 `experimental.chat.system.transform` hook. The hook calls `systemPrompt(repo)`
 and pushes the result into `output.system` every turn. No files are written.
 The repo name is baked in at runtime, so the prompt always reflects the current
-worktree.
+worktree. Identity detection reads the session's own directory (not just the
+framework worktree) and recovers from the `repo_paths` cache when that
+directory was deleted - see [repo-identity.md](repo-identity.md).
 
 **Tools**: registered through opencode's `tool()` wrapper in `src/tools.ts`,
 which adds the `thatch_` prefix. The agent sees `thatch_memory_remember`,

package/docs/dev/features/qa-system.md

@@ -126,7 +126,7 @@ with isolated `HOME`, `XDG_CONFIG_HOME`, `THATCH_DB_PATH`, and
 `THATCH_QUEUE_DIR` environment variables. The repo is read-only during QA —
 sessions run inside `/tmp/thatch-qa/<uc-name>/` copies.
 
-The `thatch-qa` skill (`.opencode/skills/thatch-qa/SKILL.md`) instructs the
+The `qa` skill (`.opencode/skills/qa/SKILL.md`) instructs the
 LLM on how to execute a single use case in the isolated directory. The skill's
 safety contract is intentionally fixed text — do not paraphrase it.
 

package/docs/dev/features/repo-identity.md

@@ -0,0 +1,110 @@
+# Repo identity
+
+## What it does
+
+Every thatch surface keys memory on a repo identity string (the "project
+store"). Identity is resolved once per process at init by `detectRepo()`,
+then threaded as the default store to tools, prompts, nudges, and chat
+registration. This feature covers how identity is resolved, and how it
+survives the deletion of the directory identity was resolved from -- the
+worktree-merged-and-cleaned-up case.
+
+The same resolution also decides where git subprocesses spawn: watchers
+and branch listing run `git`/`bash` with `cwd` set to the project
+directory, which stops working when that directory is deleted.
+
+## How it works
+
+### Resolution chain (`detectRepo`, src/git.ts)
+
+1. Parse `owner/repo` from `git remote get-url origin`.
+2. Fall back to the basename of the main checkout, resolved from
+   `git rev-parse --path-format=absolute --git-common-dir`. The absolute
+   flag makes the output uniform: a linked worktree reports the MAIN
+   checkout's `.git`, a root checkout reports its own -- so the basename
+   is the repo, never the worktree/branch directory.
+3. Fall back to the directory basename (existing, non-git directories).
+4. When the directory no longer exists, steps 1-2 cannot run (spawning
+   with a deleted cwd rejects), so the `repo_paths` cache is consulted;
+   a miss returns `"unknown"` -- never the basename, which for a worktree
+   is the branch name and would mint a plausible-but-wrong store.
+
+Callers treat `"unknown"` as unknown identity: the tool layer maps it to
+the global store, and the CLI's `defaultStore()` applies the same mapping.
+
+### The `repo_paths` cache (src/db.ts)
+
+One row per worktree directory (realpath-canonicalized key): the main
+checkout path and the repo slug recorded while the directory was alive.
+Writes happen only on successful resolution via steps 1-2, never from the
+basename fallback. Access is injected (`RepoPathCache` interface, adapted
+by `repoPathCache(db)` in src/db.ts) so src/git.ts stays database-free.
+
+Path-form handling matters on macOS, where `/var/...` and
+`/private/var/...` are the same directory in different forms. Writes
+canonicalize with `realpathSync` (the directory exists at write time);
+reads try the raw path first, then the parent-realpath form, because a
+deleted directory cannot itself be realpathed.
+
+### Recovery and eviction rules
+
+A cache hit is validated against the CURRENT state of its main checkout
+before it is trusted:
+
+| Observation | Verdict |
+|-------------|---------|
+| Main checkout missing (`statSync` throws) | Keep row, degrade to `"unknown"` -- a re-clone may be in progress |
+| Spawn failure against main checkout | Keep row (transient) |
+| Main checkout live but `git rev-parse` exits nonzero | Evict (definitive: no longer a repo) |
+| `git remote get-url origin` parses to a different slug | Evict (definitive: path recycled or re-cloned from elsewhere) |
+| Remote matches (or, with no remote, the slug still equals the main checkout's basename) | Valid -- identity recovered |
+
+Eviction is definitive-only. A wrongly evicted row permanently downgrades
+identity to `"unknown"`, which is worse than serving a stale row for one
+more call.
+
+### The spawn-cwd fallback (`resolveSpawnCwd`, src/git.ts)
+
+`resolveSpawnCwd(dir, cache)` returns the directory when it exists, else
+the validated main checkout from the cache, else null. Worktrees share
+`refs/heads` and config with the main checkout -- only HEAD and the index
+are per-worktree -- so git reads are equivalent from either. Consumers:
+
+- `listBranches` falls back to the main checkout instead of returning
+  `[]` (which made hygiene skip the orphaned-branch check).
+- The opencode plugin wraps its watcher `commandRunner` with
+  `withCwdFallback` (src/watchers.ts): the spawn cwd is resolved per poll,
+  so a watcher whose worktree dies mid-watch recovers instead of spinning
+  ENOENT errors until the TTL. The fallback is logged once per dead
+  directory.
+- `watch_command_create` accepts a `cd` override, validated at
+  registration by the baseline run (a nonexistent path is rejected).
+
+## Key invariants
+
+- Identity resolution returns a correct slug or `"unknown"` -- never a
+  plausible wrong name. A wrong-but-plausible name defeats the
+  degrade-to-global safety net.
+- The cache is only written from live resolutions, and only via the
+  remote or common-dir probes.
+- Eviction is definitive-only.
+- The cache key is the realpath at write time; reads try raw and
+  parent-realpath forms.
+
+## Interactions with other features
+
+- Database ([database.md](database.md)): the `repo_paths` table.
+- Watchers ([watchers.md](watchers.md)): the per-poll cwd fallback wraps
+  the watcher command runner; `watch_command_create` takes `cd`.
+- Hygiene ([hygiene.md](hygiene.md)): `listBranches` falls back to the
+  cached main checkout, so the orphaned-branch check survives worktree
+  deletion.
+
+## Source files
+
+- `src/git.ts` -- resolution chain, cache validation, spawn-cwd fallback
+- `src/db.ts` -- `repo_paths` table, accessors, `repoPathCache` adapter
+- `src/index.ts` -- plugin init order (DB before detection), identity from
+  the session directory, watcher runner wrapper
+- `src/mcp.ts` -- MCP server init order
+- `bin/thatch` -- CLI `defaultStore()` and hook-line identity resolution

package/docs/dev/features/watchers.md

@@ -138,6 +138,14 @@ The command source stretches the fetch/diff recipe in two ways:
    holding the pipe write-ends past the kill - without the race, the
    drains never resolve and the shared poll cycle stalls forever.
 
+The spawn cwd is resolved per poll by the plugin's command runner
+(`withCwdFallback`): the watcher's directory when it still exists, else
+the cached main checkout (see [repo-identity.md](repo-identity.md)), so a
+watcher whose worktree is deleted mid-watch recovers instead of spinning
+ENOENT errors until the TTL. `watch_command_create` also accepts a `cd`
+override for conditions that must be checked somewhere other than the
+project directory; it is validated by the registration-time baseline run.
+
 `createCommand()` runs the command once at registration as baseline
 validation, like `createPr()`'s baseline fetch: exit 0 at baseline
 means the condition is already met (refused, so the caller proceeds

package/docs/dev/skills.md

@@ -55,6 +55,7 @@ description: Extract durable project facts ... Use when ...
 | `thatch-code-walkthrough` | Explain a feature, module, or workflow to the user as a teaching walkthrough: identify the code area (optionally from a branch or PR), research how it works, teach it with file:line citations and analogies, list the key files. |
 | `thatch-session-reflection` | End-of-session memory recording (project, user, tools, self). |
 | `thatch-coding-workflow` | Plan and execute code changes with a task-list-driven workflow. Use when implementing features, fixing bugs, or making multi-file changes. |
+| `thatch-plan-refinement` | Refine a plan before implementing it: fresh-context reviewer rounds until consensus, with an optional deep-mode lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology). |
 | `thatch-pr-description` | Draft PR descriptions with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, project-context research, clarity checks, and bold+italic emphasis for scanning. |
 | `thatch-ticket-description` | Draft ticket/issue descriptions with clear sections, project-context research, clarity checks, and bold+italic emphasis for scanning. |
 | `thatch-split-overlarge-pr` | Split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main. |