@jeffober/thatch 0.2.0 → 0.2.2

package/README.md

@@ -194,8 +194,10 @@ Thatch gives your agent:
   auto-joining with `chat.autoRegister: false`).
 - **Slash commands** -- `/thatch/defrag` (consolidate duplicate memories),
   `/thatch/extract` (drain the extraction queue now), `/thatch/hygiene`
-  (tend stale and orphaned memories), and `/thatch/reflect` (persist what
-  the session learned) run on demand the same behaviors the nudges run on
+  (tend stale and orphaned memories), `/thatch/reflect` (persist what
+  the session learned), and `/thatch/refine` (refine a plan under the
+  project type's requirements, classifying the project first) run on
+  demand. The first four mirror the same behaviors the nudges run on
   their own schedule. Plus the opencode-only wrap-ups: `/thatch/compact` and
   `/thatch/exit` run a pre-flight checklist before a compaction or an exit:
   the agent flushes pending fact extraction, finishes promised memory

package/artifacts/skills/thatch-fact-extractor.md

@@ -18,7 +18,7 @@ The extraction nudge or dispatch prompt will give you a session ID. Call `get_ex
 4. Apply the durability test before saving: will this still be true and useful in a future session that knows nothing about this branch, commit, or session? If not, skip it. Do not store point-in-time values (migration indices, line numbers, file counts), commit hashes or branch history narratives (git is the source of truth), or anything re-derivable from the codebase faster than recalling it.
 5. Write for a future session with zero current context. No "we", "our session", "just now".
 6. Call `extraction_done` (with `session_id` set to the parent session's ID from the nudge) to mark the run complete. Do this even when nothing was worth saving: the parent session holds the buffered interactions until a completion signal arrives, and a memory write is not one on a no-save run.
-7. Your final message must be exactly: "Extraction complete." — do not list or summarize what you saved. The memories are in the store; the parent session does not need a report.
+7. Your final message must be exactly: "Extraction complete. This is the extractor's final report - a background-task completion, not an extraction nudge; the buffer is drained. Never re-dispatch an extractor because a completion arrived - a new extraction nudge is the only dispatch signal." - do not list or summarize what you saved. The memories are in the store; the parent session does not need a report. The frame rides with the completion on purpose: a bare "Extraction complete." was indistinguishable from nudge traffic mid-loop, and the parent model misread it as new work (the September 2026 re-dispatch loop).
 
 ## What to extract
 

package/artifacts/skills/thatch-memory-verify.md

@@ -20,7 +20,7 @@ This skill is the catch.
 
 Call `thatch_memory_show` with the label (or accept the memory content directly if dispatched by a coordinator that already read it).
 
-Note the `created_at` and `updated_at` dates. A memory that was last updated recently is less likely to be stale than one that has not been touched in months.
+Note the age line ("This memory was last updated N ago"). A memory that was last updated recently is less likely to be stale than one that has not been touched in months.
 
 ## Step 2: Classify Claims
 
@@ -111,6 +111,6 @@ If no corrections were needed, report "all claims verified, no updates needed."
 
 # Proactive Use
 
-When `thatch_memory_show` or `thatch_memory_recall` returns a memory with an old `updated_at` date (more than a few weeks), consider loading this skill to fact-check it before relying on its code-related claims. The `updated_at` date is included in the memory output for this purpose.
+When `thatch_memory_show` or `thatch_memory_recall` returns a memory whose age line shows it has not been updated in a while (more than a few weeks), consider loading this skill to fact-check it before relying on its code-related claims. The age prose ("This memory was last updated N ago") is included in the memory output for this purpose.
 
 This is not mandatory for every old memory. Use judgment: a memory about a stable architectural decision may be fine for months, while a memory about file locations or function names is more likely to drift.

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

@@ -1,6 +1,6 @@
 ---
 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).
+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. This is the generic core loop; when the project type should shape the refinement bar, load thatch-refine instead and it will apply a type delta on top of this loop. 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.
@@ -75,7 +75,8 @@ One reviewer per round in quick mode; one lens fan-out total in deep mode, then
 
 ## 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-refine`** - the type-aware entry point. Different project types need different refinement bars: a team codebase owes coordination and breadcrumbs, a personal project allows cleverness, a shared library owes API hygiene. When the user runs `/thatch/refine` or the project's type should shape the bar, load `thatch-refine` first; it classifies and hands back a thatch-refine-* delta to apply on top of this loop. This skill stays the generic core.
+- **`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-ticket-description` / `thatch-pr-description`** — if the refined plan feeds a ticket or PR description (or the session iterated on one using this skill), RE-LOAD the appropriate writing skill and draft within its contract. A plan is a working artifact for the session that wrote it; a ticket or PR description is a reader-facing document with its own sections, verbosity budget, and prose rules. Refinement output — findings, accepted risks, review rounds — is SOURCE MATERIAL for those skills, never a substitute for them. This holds the right level of detail for the medium and keeps the writing clear.
 - **`thatch-clear-writing`** — for any other human-facing text produced along the way (reports, comments, docs).

package/artifacts/skills/thatch-refine-infra.md

@@ -0,0 +1,66 @@
+---
+name: thatch-refine-infra
+description: Type-specific requirements for refining a plan that touches infrastructure (CI pipelines, Terraform, Kubernetes manifests, build and deploy configuration). Loaded by thatch-refine after classification; assumes the core loop in thatch-plan-refinement. Use when a wrong premise can break deploys or pipelines for everyone downstream.
+---
+
+You are refining a plan for an **infra** change: CI pipelines, Terraform,
+Kubernetes manifests, build and deploy configuration. The governing value
+is blast radius: a wrong premise here does not break one feature, it
+breaks every pipeline, environment, or developer downstream of it, often
+silently and often for everyone at once. Load `thatch-plan-refinement`
+for the core loop and apply the deltas below; where they disagree, these
+win.
+
+## What this type owes
+
+- **Near-absolute pattern-following.** Configuration is the worst place
+  for novelty. Copy the established pattern from a sibling pipeline,
+  module, or manifest even when a better one exists; propose the better
+  one as its own change, after this one lands.
+- **Rollback as a first-class deliverable.** Every change names how it
+  backs out, concretely (which command, which revert, which state to
+  re-apply), not "revert the commit if problems arise."
+- **Staged verification.** The plan verifies against a non-production
+  target first (staging environment, a canary job, a dry-run or plan
+  output) and names what a successful verification looks like before
+  production applies it.
+
+## How this changes the loop
+
+- **Deep mode is the default.** Infra changes almost always touch shared
+  persistent state that other consumers read, which is the core skill's
+  first deep-mode trigger.
+- **Premises verify against live state, not memory.** The most dangerous
+  infra premise is "the current setup is X" recalled from memory. Check
+  the actual manifests, the actual pipeline config, the actual running
+  versions, and cite where you checked. Terraform drift and manual
+  console changes make memory especially unreliable here.
+- **Consensus is unchanged**, but the reviewer prompt should emphasize
+  checking the rollback and verification sections explicitly.
+
+## Lens weights
+
+- **Hidden problems (pre-mortem) dominates.** The question is "who reads
+  this state that the plan does not know about?" - dependent pipelines,
+  environments sharing the module, developers relying on cache behavior,
+  jobs relying on timing. Enumerate the dependents by reading what
+  actually references the resource, not by recollection.
+- **Safe-to-modify is second.** An infra change landing in untested
+  configuration without a verification step is a finding.
+- **Alternatives and pattern/reuse mostly skip.** The pattern question
+  was answered above: follow it.
+
+## Extra plan sections
+
+- **Rollback plan.** Concrete and executable, as above.
+- **Verification step.** What runs in staging or dry-run first, and what
+  result counts as safe to proceed.
+- **Sequencing.** Infra changes often must land in an order (create
+  before reference, drain before delete). The plan states the order and
+  what breaks if it is violated.
+
+## Docs bar
+
+A one-paragraph change note for the team (what changed, why, how to
+roll back) is the deliverable. Config comments explain constraints the
+next person must not violate.

package/artifacts/skills/thatch-refine-oss-contribution.md

@@ -0,0 +1,68 @@
+---
+name: thatch-refine-oss-contribution
+description: Type-specific requirements for refining a plan for a contribution to an open source repository the user does not maintain. Loaded by thatch-refine after classification; assumes the core loop in thatch-plan-refinement. The maintainer's design authority and house style govern, and the diff stays minimal.
+---
+
+You are refining a plan for an **oss-contribution**: a change to a
+repository the user does not maintain. The governing value is the
+maintainer's design authority. It is their codebase; the contribution
+that gets merged is the one that fits their intent, not the one that
+would be best by your lights. Load `thatch-plan-refinement` for the core
+loop and apply the deltas below; where they disagree, these win.
+
+## What this type owes
+
+- **Conform to house style, even when it is worse.** A foreign codebase's
+  conventions are not up for improvement in this change. Do not import
+  patterns from other projects; do not refactor what the maintainer
+  wrote.
+- **Minimal diff.** No drive-by refactors, no reformatting of untouched
+  lines, no new dependencies, no new abstractions beyond what the change
+  strictly needs.
+- **The discussion comes first.** Significant design work waits until the
+  approach has a maintainer's nod: check CONTRIBUTING.md, search open
+  and closed issues and PRs for the same idea, and file or comment on
+  the proposal before investing in the implementation. A plan that
+  assumes acceptance is building on an unverified premise.
+
+## How this changes the loop
+
+- **Add a premise class: upstream status.** Every plan premise about the
+  maintainer's intent (is this wanted, is the approach acceptable, is
+  the issue still open) needs evidence: an issue thread, a maintainer
+  comment, a CONTRIBUTING instruction. No evidence means "unknown -
+  ask upstream," and the plan gates on that question, not on a guess.
+- **Consensus adds one test.** Alongside the core skill's consensus
+  criteria, the reviewer answers: "would a maintainer accept this
+  scope?" Scope findings are blockers. A contribution that solves the
+  issue plus three adjacent problems will sit unmerged.
+- **Round cap unchanged.** But a plan blocked on upstream discussion
+  pauses for the user to have that conversation; it does not loop.
+
+## Lens weights
+
+- **Pattern and reuse inverts.** In team code, existing patterns are a
+  strong default; here they are the requirement. A "better" pattern than
+  the house style is a finding against the plan, not for it.
+- **Hidden problems shrinks.** Consumers of internal state are the
+  maintainer's concern. Focus on the change's own footprint and its
+  interaction with in-flight upstream work (search open PRs for overlap).
+- **Alternatives mostly skips.** The maintainer chose the architecture.
+  The plan's job is fitting into it, and where the plan needs a
+  maintainer decision, that is an upstream question, not an alternatives
+  survey.
+
+## Extra plan sections
+
+- **Upstream discussion.** The issue or thread this change responds to,
+  and the maintainer signals (or absence of them) the plan relies on.
+- **House-style conformance.** The specific conventions the change will
+  follow, read from the project's own CONTRIBUTING and recent merged
+  PRs, not assumed.
+
+## Docs bar
+
+Match the project's own documentation conventions for any user-facing
+text (changelog entries, docs pages) and the house code-comment style.
+The writing skills still govern clarity, but the structure and tone
+follow the project's.

package/artifacts/skills/thatch-refine-personal.md

@@ -0,0 +1,61 @@
+---
+name: thatch-refine-personal
+description: Type-specific requirements for refining a plan in a solo personal project with no downstream consumers. Loaded by thatch-refine after classification; assumes the core loop in thatch-plan-refinement. Relaxes coordination requirements and allows cleverness and experimentation, while keeping premise verification honest.
+---
+
+You are refining a plan for a **personal** project: solo code with no
+downstream consumers. The coordination constraints that govern team code
+are relaxed. This is the place to show off cleverness and experiment with
+interesting techniques that would be inconsiderate in a shared codebase.
+Load `thatch-plan-refinement` for the core loop and apply the deltas
+below; where they disagree, these win.
+
+## What this type owes
+
+- **Almost nothing to anyone else.** No consistency obligation to
+  teammates, no reviewer to orient, no downstream API to protect.
+- **Still honest about facts.** Relaxed style does not mean relaxed
+  reality: every factual premise still carries a verified `file:line`
+  citation, and "unverified" is still marked. A plan built on a wrong
+  premise wastes your time in any project.
+
+## How this changes the loop
+
+- **The skip threshold drops.** Most personal-project plans can be tried
+  faster than they can be refined. Skip refinement whenever the change is
+  cheap to build and cheaper to rewrite; run the loop only when the plan
+  touches something expensive to get wrong (persistent state, a
+  hard-to-reverse migration, hours of build effort).
+- **Fewer rounds.** One quiet review round is enough consensus. The cap
+  drops from three rounds to two; a personal plan that has not converged
+  by then should just be built or abandoned.
+- **Degraded review is fine.** If the host cannot dispatch sub-agents, a
+  same-context self-review pass is usually enough. Saying so out loud, as
+  the core skill requires, is still worthwhile but the stakes are lower.
+
+## Lens weights
+
+- **Premise verification is the only load-bearing lens.** The fresh
+  reviewer's core job is checking the plan's factual model of the code.
+- **Pattern and reuse mostly skips.** There is no team to stay consistent
+  with. Flag reuse only when reinventing an existing wheel will genuinely
+  bite future-you.
+- **Alternatives turns exploratory.** The question shifts from "what is
+  safest?" to "what would I learn?" - one alternative worth trying for
+  the technique is a valid result even when the plan's choice is fine.
+- **Hidden problems shrinks to future-self.** The only consumer to
+  enumerate is you, six months from now, with no memory of this code.
+
+## Extra plan sections
+
+None required. Blast radius, migration plans, and reviewer orientation
+sections are skipped unless the change is in the expensive-to-get-wrong
+category that triggered refinement at all.
+
+## Docs bar
+
+- Future-self breadcrumbs only: comment the surprising spots, not the
+  obvious ones.
+- When a plan deliberately uses an experimental technique, record that in
+  one line (in the plan or a comment) so a future session knows the
+  oddity was chosen, not accidental.

package/artifacts/skills/thatch-refine-shared-lib.md

@@ -0,0 +1,69 @@
+---
+name: thatch-refine-shared-lib
+description: Type-specific requirements for refining a plan that touches a library's API surface, in any repo, including personal ones. Loaded by thatch-refine after classification; assumes the core loop in thatch-plan-refinement. Use whenever exported API, published packages, or downstream consumers are involved; API hygiene governs even solo projects.
+---
+
+You are refining a plan for a **shared-lib** change: work that touches an
+API other code consumes and keeps working against. This applies to any
+library with external callers, including a personal one. The governing
+value is API hygiene: you are writing for consumers you cannot see and
+cannot call back. Load `thatch-plan-refinement` for the core loop and
+apply the deltas below; where they disagree, these win.
+
+## What this type owes
+
+- **Flexible on input, strict on output.** Accept broad input types and
+  normalize them; return precise, well-defined types and never leak
+  internal representations. Callers write code against your output
+  shapes; widen what you accept, pin down what you emit.
+- **Keep special cases out of the API.** No caller-specific knobs, no
+  one-off escape hatches, no parameters that exist for exactly one
+  consumer. A special case is a design smell: handle it inside the
+  implementation or reject it at the boundary.
+- **Do not foreclose caller options.** Prefer returning data over making
+  decisions callers might want to make differently. Every shortcut the
+  library takes on the caller's behalf is a wall they hit later.
+- **Keep the surface small.** Every export is a permanent maintenance
+  promise. The best API change is often the one that exports nothing new.
+
+## How this changes the loop
+
+- **Deep mode is the default** for anything that adds, changes, or
+  removes an export. The abstraction gets locked in at ship time; after
+  release, changing it costs every consumer. This is the last cheap
+  moment to get the shape right.
+- **Alternatives works harder here.** "No better alternative found" must
+  be argued harder than the core skill's paragraph: enumerate the
+  plausible alternative shapes and say why the plan's shape wins for
+  callers, not just for the implementation.
+- **Backward compatibility findings are blockers by default.** A breaking
+  change without a deprecation path is a blocker, not a should-fix.
+
+## Lens weights
+
+- **Hidden problems reframes entirely.** Every consumer is a stranger;
+  you cannot grep your callers. Enumerate the contract the plan changes
+  and reason about the population of consumers you cannot see, including
+  the ones using the API in ways you never intended.
+- **Pattern and reuse applies to your own API first.** Consistency with
+  the library's existing API conventions is its own requirement: a
+  second method that disagrees with the first in naming or shape is a
+  finding even when both are internally fine.
+
+## Extra plan sections
+
+- **API surface diff.** Exactly what is exported, added, changed, or
+  removed, in a list a reviewer can check one line at a time.
+- **Semver impact and deprecation path.** The version bump this deserves,
+  what is deprecated, and how callers migrate.
+- **External documentation.** The docs and examples this change requires,
+  written for the reader: what the behavior is, when to use it, what it
+  does not do. "I'll document it later" is a finding.
+- **Caller migration notes.** For breaking or behavior-changing exports,
+  the note that goes in the changelog.
+
+## Docs bar
+
+Reader-facing documentation is a plan deliverable, not a follow-up. Draft
+it under the writing skills' contracts: define terms on first use,
+behavior stated precisely enough that a caller needs no source dive.

package/artifacts/skills/thatch-refine-spike.md

@@ -0,0 +1,53 @@
+---
+name: thatch-refine-spike
+description: Type-specific requirements for refining a plan for a throwaway prototype or time-boxed spike. Loaded by thatch-refine after classification; assumes the core loop in thatch-plan-refinement. Skips almost all of the loop, verifying only the premises the experiment's conclusion depends on.
+---
+
+You are refining a plan for a **spike**: throwaway code whose purpose is
+answering a question, not producing a maintained artifact. Almost all of
+the refinement loop is waste here. Load `thatch-plan-refinement` for the
+core loop, then apply the deltas below; where they disagree, these win.
+
+## What this type owes
+
+- **A stated question.** The plan opens with the question the spike
+  exists to answer, stated concretely enough that "done" is checkable
+  ("can Postgres full-text search handle our query volume?" not "explore
+  search options").
+- **A promotion test.** The plan states what would make this code worth
+  promoting into the real codebase versus rewriting it properly. Most
+  spikes end in a rewrite, and that is a success, not a failure.
+- **A time box.** The plan names its budget: hours or days, not open-
+  ended effort.
+
+## How this changes the loop
+
+- **Skip the loop by default.** No reviewer dispatch, no rounds, no
+  consensus machinery. One focused self-review pass is the whole
+  refinement: check the plan's few load-bearing premises, then build.
+- **Verify only conclusion-bearing premises.** The spike's conclusion is
+  only as good as the premises it depends on. If the experiment claims
+  "this approach is too slow," the benchmark setup and the
+  representativeness of the test data are the premises that matter, and
+  they get the verified-citation treatment. Everything else is
+  throwaway.
+- **Degraded review needs no apology.** The core skill's honest-degradation
+  notice is unnecessary; there is no real review to degrade.
+
+## Lens weights
+
+All specialist lenses skip except one consideration: **is the spike
+actually throwaway?** If the plan quietly assumes the prototype code will
+survive into production, stop and surface that. A spike that is really a
+production change wearing a costume should be refined under the type it
+actually is.
+
+## Extra plan sections
+
+- The question, the promotion test, and the time box above. Nothing else.
+
+## Docs bar
+
+No breadcrumb obligation. One comment or note recording the question and
+the answer is enough. The spike's real output is the answer, and it
+should be written down where the user will find it.

package/artifacts/skills/thatch-refine-team-app.md

@@ -0,0 +1,69 @@
+---
+name: thatch-refine-team-app
+description: Type-specific requirements for refining a plan in a multi-developer team codebase (production app or service shared by a team). Loaded by thatch-refine after classification; assumes the core loop in thatch-plan-refinement. Use when coordination cost, consistency, and reviewer comprehension are the governing constraints.
+---
+
+You are refining a plan for a **team-app** project: production code in a
+repository where multiple developers ship, review, and maintain each
+other's work. The governing value is org velocity through coordination and
+consistency. Code is read far more often than it is written, and most of
+its readers did not write it. Load `thatch-plan-refinement` for the core
+loop and apply the deltas below; where they disagree, these win.
+
+## What this type owes
+
+- **Consistency outranks local optimality.** Following the codebase's
+  existing pattern beats a "better" one that splits the codebase in two.
+  A novel approach must justify the divergence it imposes on every future
+  reader, not just prove it is cleverer.
+- **Implement for the junior reviewer.** The bar is that a developer with
+  no history in this area can review the change and debug it at 2am.
+  Cleverness is allowed only with a justification comment at the point of
+  cleverness, and only when the payoff is real.
+- **Intent is a deliverable.** Docstrings and comments are the breadcrumb
+  trail for the next maintainer. The plan says which comments and
+  docstrings it will write, and *why* is documented, not just *what*.
+
+## How this changes the loop
+
+- **Mode triage stays strict.** The skip threshold does not relax for
+  team code: anything another developer must review earns at least quick
+  mode. Established-pattern changes with no design decisions can still
+  skip, as the core skill already provides.
+- **Deep mode triggers broaden.** Beyond the core skill's triggers, deep
+  mode is warranted when the change alters a contract other teams build
+  on, or lands in an area with a history of review churn.
+- **Consensus is unchanged.** Same rounds, same cap, same escalation to
+  the user.
+
+## Lens weights
+
+- **Hidden problems (pre-mortem) carries the most signal.** In team code
+  the plan's biggest risk is an unenumerated consumer or an implicit
+  contract another team relies on.
+- **Safe-to-modify is second.** A plan that lands in an untested,
+  tangled section without a refactor-first dependency is a finding.
+- **Pattern and reuse tightens.** "Reuse the existing pattern" is the
+  default verdict, not one option among several. A plan that introduces a
+  parallel way to do something the codebase already does needs a strong,
+  evidenced reason.
+- **Alternatives stays a filter.** Two alternatives, one paragraph each,
+  as the core skill says; the judgment criterion is team cost, not
+  personal preference.
+
+## Extra plan sections
+
+- **Blast radius and consumers.** Who reads the state, tables, config, and
+  symbols this change touches, including other teams and services.
+- **Migration and rollback.** How the change ships safely and how it
+  backs out.
+- **Intent breadcrumbs.** The docstrings and comments the implementation
+  will write, and what future-reader question each answers.
+- **Reviewer orientation.** One paragraph a reviewer can read first: what
+  changed, why, and where to look.
+
+## Docs bar
+
+Comments and docstrings are part of the definition of done, and any
+reader-facing text produced along the way (PR description, ticket,
+changelog entry) is drafted under the writing skills' contracts.

package/artifacts/skills/thatch-refine.md

@@ -0,0 +1,84 @@
+---
+name: thatch-refine
+description: Classify the current project (audience, lifecycle, surface) and refine a plan under that type's requirements. Entry point for the thatch-refine-* family. Use when the user asks to refine a plan, runs /thatch/refine, or when a plan is about to be implemented and the project type should shape the refinement bar. For a bare "refine this plan" request, load this skill rather than thatch-plan-refinement directly - the router picks the type and applies its delta on top of the core loop.
+---
+
+You are the entry point for project-type-aware plan refinement. The core
+refinement loop (draft, fresh-context reviewer, revise, consensus) is the
+same everywhere; it lives in `thatch-plan-refinement`. What changes by
+project type is the bar: which lenses matter, what the plan must contain,
+how much documentation is owed, and when skipping refinement is honest.
+
+## The types
+
+| Type | Governing value | Skill |
+|------|-----------------|-------|
+| `team-app` | Coordination and consistency promote org velocity | `thatch-refine-team-app` |
+| `personal` | Freedom to experiment; low coordination cost | `thatch-refine-personal` |
+| `shared-lib` | API hygiene; never foreclose caller options | `thatch-refine-shared-lib` |
+| `spike` | Answering a question cheaply, not producing code | `thatch-refine-spike` |
+| `infra` | Blast radius across pipelines and environments | `thatch-refine-infra` |
+| `oss-contribution` | The maintainer's design authority | `thatch-refine-oss-contribution` |
+
+## Classification
+
+Classify on three axes, then pick the type whose requirements this plan
+must satisfy. Classify **the change**, not just the repo: a personal repo
+gaining a published API is a `shared-lib` plan for that change, even if the
+repo is `personal` overall.
+
+**Audience** - who reads and maintains this code.
+
+- Solo: one contributor in git history, no CODEOWNERS, no required reviews.
+- Team: CODEOWNERS, CONTRIBUTING.md, required PR review, multiple regular
+  authors.
+- Public: published package (npm/PyPI/etc. metadata, `publishConfig`), or
+  consumers outside the repo you cannot enumerate.
+
+**Lifecycle** - what this code owes anyone.
+
+- Production: protected main, CI gates, deploy configuration, semver
+  discipline.
+- Experimental: active WIP, churny main, thin or absent tests.
+- Throwaway: a question wearing a repository.
+
+**Surface** - what the change lives in.
+
+- Application: end-user or service code with no downstream importers.
+- Library: exported API that other code imports and keeps working against.
+- Infrastructure: CI, Terraform, k8s manifests, build and deploy config.
+
+Signals to gather (all cheap and read-only): `git log --format="%an" |
+sort -u | head`, presence of CODEOWNERS / CONTRIBUTING.md / required
+review config, package.json `private` and `publishConfig` fields, the
+publishing config of the relevant ecosystem, presence of `.github/workflows`,
+`terraform/` or k8s manifests, and what the package exports. Do not
+over-invest here; the classification should cost a minute, not a research
+pass.
+
+## Procedure
+
+1. If the user named a type explicitly (for example `/thatch/refine
+   shared-lib`), skip classification and use it.
+2. Otherwise gather the signals above and pick the type.
+3. State the classification in one line and why, and let the user override.
+   A wrong classification silently changes the requirements, so the user
+   sees the pick before it takes effect. When the signals conflict or are
+   too thin to pick, ask instead of guessing.
+4. Load `thatch-plan-refinement` (the core loop) and the type's skill.
+5. Run the core loop with the type skill's deltas applied. Where a delta
+   and the core skill disagree, the delta wins; that is its whole job.
+
+If no type fits (the repo serves a niche the table misses), run plain
+`thatch-plan-refinement` and say that the requirements are the generic
+ones.
+
+## Relationship to other skills
+
+- **`thatch-plan-refinement`** - the core loop. Always loaded; the type
+  skills only modify it.
+- **`thatch-coding-workflow`** - the procedure skill for executing the
+  refined plan. Refinement ends where it begins.
+- **`thatch-clear-writing`** and the writing skills - several type skills
+  make reader-facing documentation a plan deliverable. Draft that text
+  under the writing skills' contracts, not this one's.

package/docs/dev/README.md

@@ -127,7 +127,7 @@ methods. The v1 hook shapes:
 | `command.execute.before` | Arms the wrap-up greenlight check: `/thatch/compact` and `/thatch/exit` mark their session in `pendingWrapUp`. The next `session.status` idle resolves it by inspecting the final assistant message for the greenlight token and, when present, triggering the TUI action (`session_compact` via `executeCommand`, `app.exit` via `publish`; the exit path unregisters the session from the chat directory first). See [features/session-lifecycle.md](features/session-lifecycle.md). |
 | `experimental.compaction.autocontinue` | Clears the compacting flag so `chat.message` nudges resume. Without this, nudges that instruct tool calls would fire during summary generation where tools are blocked. The `chat.message` hook also clears the flag if it fires for a session still in the compacting set but the incoming message has no compaction-type part — this handles compaction failure, where the session would otherwise be stuck with nudges off forever. |
 | `tool.execute.after` | Buffers every non-`thatch_*`, non-`skill`, non-`task` tool call into the session's extraction buffer. (Skill/task are excluded — buffering them creates a feedback loop where the nudge triggers a skill load, which gets buffered, which triggers another nudge.) Memory writes (`thatch_memory_remember`) and `thatch_extraction_done` drain the buffer and reset the missed-nudge counter. For child sessions (`childToParent.has(sessionID)`), also tracks metrics: `remember` with `overwrite:false` → new++, `overwrite:true` → updated++, `forget` → deleted++. For `thatch_chat_*` tool calls, builds the transcript echo (`chatEchoText`) and posts it as a visible non-synthetic `noReply` part. This is a plugin hook, NOT a bus event — do not move it into the `event` handler; the event bus has no such event and it will silently never fire. |
-| `chat.message` | Two priority tiers: (a) if extraction buffer has interactions and the session is NOT in the `extracting` set (direct extraction in progress), **peeks** the buffer (does NOT drain it) and injects a synthetic text part carrying the extraction nudge with the session ID and fetch tool name (not the full payload) — the sub-agent calls `thatch_get_extraction_payload` to retrieve the interactions as a tool response, keeping the full payload out of the main session's context window. The buffer persists until the agent writes a memory or calls `thatch_extraction_done`, so ignored nudges repeat and escalate (polite → insistent → ALL-CAPS) via the `missedNudges` counter; (b) otherwise, embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). The same embedding also feeds the prediction auto-fire (`db.scorePredictionNudge`, injects `[thatch] User decision model`) and the behavior auto-fire (`db.scoreBehaviorNudge`, injects `[thatch] Situational behaviors`). All three nudges (recall, prediction, behavior) fire independently in separate try/catch blocks with separate synthetic parts. Chat transcript echoes (non-synthetic `noReply` parts whose text is entirely `[chat]`-prefixed bubbles) are skipped before any tier — no model turn reads them, so nudging them wastes an embedding. Skipped entirely while the session is compacting (tool calls are blocked during summary generation). |
+| `chat.message` | Two priority tiers: (a) if extraction buffer has interactions and the session is NOT in the `extracting` set (direct extraction in progress), **peeks** the buffer (does NOT drain it) and injects a synthetic text part carrying the extraction nudge with the session ID and fetch tool name (not the full payload) — the sub-agent calls `thatch_get_extraction_payload` to retrieve the interactions as a tool response, keeping the full payload out of the main session's context window. The buffer persists until the agent writes a memory or calls `thatch_extraction_done`, so ignored nudges repeat and escalate (polite → insistent → ALL-CAPS) via the `missedNudges` counter; (b) otherwise, embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). The same embedding also feeds the prediction auto-fire (`db.scorePredictionNudge`, injects `[thatch] User decision model`) and the behavior auto-fire (`db.scoreBehaviorNudge`, injects `[thatch] Situational behaviors`). All three nudges (recall, prediction, behavior) fire independently in separate try/catch blocks with separate synthetic parts. Chat transcript echoes (non-synthetic `noReply` parts whose text is entirely `[chat]`-prefixed bubbles) are skipped before any tier — no model turn reads them, so nudging them wastes an embedding. Skipped entirely while the session is compacting (tool calls are blocked during summary generation), and for task-dispatched sub-agent sessions (`childToParent` without `extractionChildren`) - their tool lists may exclude the thatch tools and their work is driven by the dispatch prompt. |
 | `event` | Subscribes to all session bus events. `session.created`: records `childToParent` + `parentSnapshots` (shallow copy of the parent's buffer for snapshot-aware drain), then sends the session-start reminder via `client.session.prompt` carrying the hygiene heartbeat (pending dedup pairs, stale count, orphaned branch memories) when any signal is non-zero. `session.status`: records the session's live status for the watcher and chat delivery gates; on idle, if the session is a child, drains its snapshot, fires a toast with `childMetrics`, and deletes the child session; if the session is a parent with pending tool interactions and not already extracting, calls `triggerExtraction` to create a direct-extraction child, then flushes pending watcher events and pending chat mail (the session just became deliverable). `session.error`: requeues the parent's buffer (child died without draining). `session.deleted`: cleans up `childToParent`, `parentSnapshots`, `childMetrics`, and `extracting`, cancels the session's watchers, and unregisters it from the chat directory (the crash path — a dead process fires no event — is covered by heartbeat staleness). `session.compacted`: clears the compacting flag so `chat.message` nudges resume. |
 | `dispose` | Stops the version checker, the watcher poller, and the chat poller, closes the DB. |
 
@@ -179,11 +179,15 @@ Two of these hooks were dead for weeks because failures were invisible.
 10. **Background completion narration is suppressed, not prevented.** When a
     background sub-agent completes, opencode injects a `<task_result>` block
     into the parent session and triggers a full model generation. Thatch
-    cannot cancel this turn (no pre-response hook). Two mitigations: the
-    fact-extractor skill's return value is constrained to the literal
-    "Extraction complete." so the injected block has no narratable content,
-    and the system prompt's "Background Task Completions" section instructs
-    the model not to narrate completions or treat them as approval to act.
+    cannot cancel this turn (no pre-response hook). The mitigations: the
+    fact-extractor skill's return value is a fixed string so the injected
+    block has nothing to narrate AND the string self-identifies as a
+    completion, not an extraction nudge (a bare "Extraction complete." was
+    misread mid-loop as new nudge traffic and re-dispatched - the September
+    2026 re-dispatch loop); the system prompt's "Background Task
+    Completions" section instructs the model not to narrate completions or
+    treat them as approval to act, and that a completion is never a
+    re-dispatch signal.
 11. **Prediction engine is a statistical model, not an LLM call.** The query
     (embed prompt, cosine-match against matchers, score linked predictions)
     is mechanical — same shape as `thatch_memory_recall` but against different
@@ -209,7 +213,7 @@ Two of these hooks were dead for weeks because failures were invisible.
 ## Data flow
 
 ```text
-thatch_memory_remember(label, content)
+thatch_memory_remember(label?, content)
   → model.passageEmbed("# label\n\ncontent") → Float32Array
   → db.findSimilar(store, embedding) — write-time collision check (no telemetry)
   → db.remember(store, label, content, embedding, model.name, opts)

package/docs/dev/features/cross-session-chat.md

@@ -191,7 +191,14 @@ rather than one so a single late poll cycle does not flap the roster.
 Heartbeat age is the ONLY liveness signal, by design. A host process id
 cannot serve: the same session is re-hosted by a new process on every
 `-s` resume, so a pid stamped on the row lies as soon as a different
-harness beats it (it says dead while the heartbeat proves alive). `isStale`
+harness beats it (it says dead while the heartbeat proves alive). RESTART
+grace: a new daemon re-hosts the dead one's hosted set under a bounded
+window (`CHAT_REHOST_GRACE_MS`, 24h, `THATCH_CHAT_REHOST_GRACE_MINUTES`
+to override) - open TUI tabs reconnect but emit no events until typed
+into, so without the grace they would read stale while alive-idle and
+mail to them would not wake the tab. Sessions that emit activity
+graduate to permanent hosting; still-silent ones (closed tabs) age out
+at the grace and go stale. `isStale`
 (src/chat.ts) is the single rule; `chatLiveness`, the `chat_send` note,
 and the broadcast skip all call it, so they cannot disagree. `chat_list`
 groups the result into Active and Stale sections - the stale section's

package/docs/dev/features/memory-store.md

@@ -58,7 +58,7 @@ The "global" store always exists — it is inserted at schema init (`INSERT OR I
 ### Write path (memory_remember)
 
 ```text
-agent calls memory_remember(label, content, opts)
+agent calls memory_remember(label?, content, opts) - label is derived from the content's first heading or line when omitted
   → model.passageEmbed("# label\n\ncontent")  →  Float32Array
   → db.findSimilar(store, embedding, { excludeSlug })  →  write-time collision check
   → db.remember(store, label, content, embedding, model.name, opts)

package/docs/dev/features/nudge-pipeline.md

@@ -49,6 +49,18 @@ not a compaction summary, compaction has already failed (the auto-continue
 never fired). Thatch clears the stale `compacting` flag and proceeds normally.
 See [compaction-recovery.md](compaction-recovery.md).
 
+#### Task sub-agent guard
+
+If the session is a child in `childToParent` but not in `extractionChildren`
+(a task-dispatched sub-agent), all nudge tiers are skipped and the hook
+returns before tier 1. Dispatched sub-agents may have restricted tool lists
+that exclude the thatch tools, and even where the tools exist the child is
+driven by its dispatch prompt, so a nudge only produces "No tool named"
+error rounds or noise. `extraction.requeueStaleAccepted()` still runs before
+the guard - it is session-independent maintenance. See
+[session-lifecycle.md](session-lifecycle.md) for the `extractionChildren`
+distinction.
+
 #### Tier 1---Extraction nudge (fallback path)
 
 Fires only when direct extraction was never triggered or threw (the session is