@jeffober/thatch 0.2.6 → 0.2.7

package/artifacts/skills/thatch-clear-writing.md

@@ -168,6 +168,17 @@ The wart shape, for code that looks wrong but is correct:
 Simple and good beats complex and great. Cut whole claims to shorten;
 never compress the survivors.
 
+## Documentation files
+
+Standalone documentation - package docs (a doc.go or package comment), READMEs, and anything under a docs/ directory - serves readers that symbol-anchored text never meets: someone onboarding and an expert looking up one fact, in the same pass. An inline comment or a docstring has the code as its context. A standalone doc has only its own order, so the standard is higher: clear sentences are the floor; the document must also serve the skimmer and the learner.
+
+- **The inverted pyramid, at the document and the section level.** Lead with the answer at the top of the doc, and again at the top of each section: what the thing is and what the reader gets, first; the mechanism after; caveats and edge cases last. The reader decides when to stop reading, so stopping early must be safe.
+- **Basics before advanced.** Each section stands on the ones before it. A reader who knows the basics can stop or skip ahead; a reader who does not gets each idea in the order they can absorb it.
+- **Scan anchors.** Bold the load-bearing phrases so a reader who skims only the bold fragments still gets the story; the first sentence of each section carries the section's point. Bold sparingly outside the opening sections; a doc bolded throughout cannot be skimmed.
+- **Presentation, not specificity.** These rules demand better order, never more content. Judge a doc against its own level of detail; do not add enumerations or file pointers the doc's level never promised.
+
+No section template follows from this. Headings and structure belong to the repo's own conventions; apply the intent, not a shape.
+
 ## Clarity pass
 
 Before you post, save, or send: reread the draft as a reader with zero context. Fix what they would stumble on. Do not announce the pass; just return clean prose.

package/artifacts/skills/thatch-code-review.md

@@ -58,7 +58,7 @@ Dispatch a sub-agent using the Task tool to research the code workflows affected
 
 The sub-agent produces a code guide with one section per affected workflow or feature. Wait for it to complete and collect the guide.
 
-This guide gives specialists the code-level context (purpose, data flow, evolutions, constraints) they need to avoid false positives about intentional behavior and long-standing design decisions, and reduces duplicate code-tracing across the nine specialist lenses.
+This guide gives specialists the code-level context (purpose, data flow, evolutions, constraints) they need to avoid false positives about intentional behavior and long-standing design decisions, and reduces duplicate code-tracing across the ten specialist lenses.
 
 If the context brief includes a sibling register (from Step 2's related-PR discovery), fold it into the guide per the `Cross-PR context` section of the thatch-code-archaeology skill — whether you dispatch a sub-agent or do this research inline. The traps the guide exists to catch are comments referencing sibling work, contracts consumed from a sibling, and ordering assumptions across the stack or train.
 
@@ -90,7 +90,7 @@ For changes estimated at 3 points or fewer, skip partitioning — dispatch one s
 
 ## Step 6: Dispatch specialist sub-agents
 
-For each review unit, dispatch sub-agents using the Task tool. Each sub-agent runs one specialist lens on one review unit. The nine specialists are:
+For each review unit, dispatch sub-agents using the Task tool. Each sub-agent runs one specialist lens on one review unit. The ten specialists are:
 
 1. **Pedantic** — mechanical correctness: spelling, naming, doc accuracy, specs, guidelines, stale artifacts, structural conventions. Dispatch a sub-agent with instructions to: read every changed file in the unit, check comments/docs/naming/specs/style, check new file and directory placements against the repo's existing layout, report findings.
 
@@ -102,13 +102,15 @@ For each review unit, dispatch sub-agents using the Task tool. Each sub-agent ru
 
 5. **NoSlop** — AI writing anti-pattern detection: change narration, fourth wall breaks, em dashes, hedging, filler. Dispatch a sub-agent with instructions to: read every changed file, scan all comments/docs/strings for slop.
 
-6. **Breadcrumbs** — comment narrative evaluation: do comments form a coherent outline? Dispatch a sub-agent with instructions to: read every changed file in full, evaluate the comment narrative, flag gaps.
+6. **Clarity** — prose clarity against the project's clear-writing rules, regardless of who wrote the text: made-up phrases, buzzwords, untranslated jargon, clause chains, buried leads, doc/code responsibility splits, plus document-level presentation in standalone docs (the inverted pyramid, scan anchors, basics before advanced). Dispatch a sub-agent with instructions to: read every changed file in full plus every changed doc, scan all comments/docstrings/error strings/UI strings/doc paragraphs for reader-cost prose, check standalone docs that are new or substantially rewritten for structure, report each finding with the plain-English fix (the replacement, the split, or the claim to cut).
 
-7. **MarkAndSweep** — mechanical change completeness: renames, flag removals, API substitutions. Dispatch a sub-agent with instructions to: extract old identifiers from removed diff lines, sweep the whole repo with git grep for stragglers, verify touchpoint neatness (dead branches, orphaned imports, stale comments, config/test residue). Self-selects: if the diff shows no mechanical change patterns, it reports "No mechanical change detected" and produces no findings.
+7. **Breadcrumbs** — comment narrative evaluation: do comments form a coherent outline? Dispatch a sub-agent with instructions to: read every changed file in full, evaluate the comment narrative, flag gaps.
 
-8. **Highlights** — positive finding detection: notably clever solutions, cleanup done along the way, documentation that meaningfully helps. Dispatch a sub-agent with instructions to: read every changed file in the unit and the before-state with git show, look for things that rise above baseline competence. Medium-high bar: no generic praise, no baseline competence. If nothing rises above the bar, it reports "No highlights" and produces no findings.
+8. **MarkAndSweep** — mechanical change completeness: renames, flag removals, API substitutions. Dispatch a sub-agent with instructions to: extract old identifiers from removed diff lines, sweep the whole repo with git grep for stragglers, verify touchpoint neatness (dead branches, orphaned imports, stale comments, config/test residue). Self-selects: if the diff shows no mechanical change patterns, it reports "No mechanical change detected" and produces no findings.
 
-9. **Technique** — teaching-grade lens on better ways to do it: helpers and internal packages the author may not have seen, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Dispatch a sub-agent with instructions to: read every changed file in the unit, verify any cited alternative exists and achieves the same behavior before reporting, frame notes generously, report all notes as informational. If nothing qualifies, it reports "No technique notes" and produces no findings.
+9. **Highlights** — positive finding detection: notably clever solutions, cleanup done along the way, documentation that meaningfully helps. Dispatch a sub-agent with instructions to: read every changed file in the unit and the before-state with git show, look for things that rise above baseline competence. Medium-high bar: no generic praise, no baseline competence. If nothing rises above the bar, it reports "No highlights" and produces no findings.
+
+10. **Technique** — teaching-grade lens on better ways to do it: helpers and internal packages the author may not have seen, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Dispatch a sub-agent with instructions to: read every changed file in the unit, verify any cited alternative exists and achieves the same behavior before reporting, frame notes generously, report all notes as informational. If nothing qualifies, it reports "No technique notes" and produces no findings.
 
 For the integration review unit (5+ points), dispatch a sub-agent focused on:
 - Cross-component contracts — do the interfaces between components match?
@@ -137,7 +139,7 @@ Pass the synthesizer:
 
 The final user-facing report MUST begin with a concise explanation of the workflow(s) this PR changes before listing findings. Use one `### Workflow changes` section, with one subheading per affected workflow when there are multiple. Use the before/now walkthrough shape from the thatch-pr-description skill: numbered step = existing behavior; `NOW` sub-bullet = what the PR changes; `N/A` for new stages. This gives the user a map of the change before the findings. Keep it short: 3-6 steps per workflow.
 
-Confirmed LOW findings are mandatory in the final report, including mechanical findings (pedantic, no-slop, breadcrumbs, docs, naming, style, comments, structural conventions). Do not omit them for being non-functional.
+Confirmed LOW findings are mandatory in the final report, including mechanical findings (pedantic, no-slop, clarity, breadcrumbs, docs, naming, style, comments, structural conventions). Do not omit them for being non-functional.
 
 Confirmed highlights (from the highlights specialist) appear in a `### Highlights` section after the workflow changes and before the confirmed findings. Most PRs will have none — that is expected. Do not pad with borderline calls. But when the highlights specialist found genuine standouts, include every one that passes the bar.
 
@@ -164,7 +166,7 @@ When dispatching each sub-agent, include in the prompt:
 - The git range to review
 - **The resolved head SHA of the range** — all file reads, file:line citations, and anchors MUST be computed against this ref (`git show <head-sha>:<path>`), never the working tree, which may be on a different branch than the change under review
 - The specific files in this unit's scope
-- The specialist focus (from the nine specialists above)
+- The specialist focus (from the ten specialists above)
 - The diff stat for this unit's files
 - **The project context brief** from Step 2, filtered to what is relevant to this unit's scope. Explicitly list any deferred work that falls within this unit's files, and call out TODO ($ticket) markers the specialists should recognize as intentional.
 - **The workflow guide** from Step 3, filtered to the workflows relevant to this unit's scope. Use it to understand the purpose and evolution of the code before flagging issues. It provides the code-level context (flows, contracts, history, constraints) that prevents false positives about intentional behavior and long-standing design decisions.

package/artifacts/skills/thatch-review-clarity.md

@@ -0,0 +1,101 @@
+---
+name: thatch-review-clarity
+description: Prose clarity in the change's comments, docstrings, error strings, and docs - made-up phrases, buzzwords, untranslated jargon, clause chains, buried leads, doc/code responsibility splits - plus document-level presentation in standalone docs, the inverted pyramid, scan anchors, basics before advanced - checked against the project's clear-writing rules regardless of who wrote the text. Use for post-implementation review of a branch, PR, or commit range.
+---
+
+You are a prose clarity review agent. Your sole job is to check the human-facing text in the change - code comments, docstrings, error messages, UI strings, and documentation - against the project's clear-writing rules.
+
+A clarity defect is reader cost, regardless of who wrote the text. Dense jargon a human wrote fails exactly like the same jargon from an AI. Do not guess at authorship; that is the no-slop lens's job.
+
+${REVIEW_COMMON}
+
+## The rules
+
+The full rule set is the thatch-clear-writing skill. The checks below are its review form. When both are loaded and they disagree, the skill wins.
+
+The reader is an engineer who knows the stack and general engineering vocabulary and has never touched this area. Every sentence must parse on first read. The concepts stay technical; the language stays simple.
+
+Brevity means fewer claims, not denser claims. When prose runs long, the fix is deleting a whole claim. Never report a fix that tightens a surviving sentence; tightening is what produces clause chains.
+
+## Categories
+
+### Made-up phrases
+Multi-word terms that sound technical but mean nothing: "identity contract", "canonical hash", "semantic alignment layer". Every term must exist somewhere - in the code, the docs, or standard engineering usage. If you cannot point to where it is defined, the label is the finding. The fix names what the thing does: what runs, what changes, what the reader gets.
+
+### Buzzwords
+"Leverage", "utilize", "facilitate", and any phrase that cannot be restated in plain English. If a phrase sounds like it is trying to sound smart, that is the finding. The fix uses the plain word or states the behavior.
+
+### Untranslated jargon
+A project-private label doing an explanation's job. Roadmap names, subsystem nicknames, ticket shorthand, and branch-local labels are not explanations. Say what the code does first (what reads, writes, blocks, retries, changes); the label may follow if it helps the reader connect prose to code. Ticket refs in place of behavior are this category: "the backfill worker", not "the TICKET-123 backfill worker". Code-domain nouns in prose are this category too: "a request waiting for a worker" not "a waiter".
+
+### Clause chains
+Multiple ideas crammed into one sentence, or noun stacks doing verb work: "the row read", "the waiter". The fix splits the sentence into full parallel sentences, each with its causal clause, or deletes a whole claim. Verbless chains (the telegraphic form) belong to the no-slop lens.
+
+### Buried leads
+A doc or docstring that saves the point for the end. Lead with the answer. Then the evidence. Then the caveats. The reader decides when to stop reading, so stopping early must be safe. Reading-order narration ("This guide will first cover X, then Y") opens with process instead of the point and is this category too.
+
+### Doc structure failures
+Standalone docs only (package docs, READMEs, docs/): the document's order fails the reader even when every sentence is clear.
+- A wall of paragraphs with no scan anchors: no bold on the load-bearing phrases, section leads that do not carry the section's point, so a skimmer cannot find what they came for.
+- Basics and advanced detail interleaved, so the reader who knows the basics cannot skip ahead and the reader who does not gets ideas out of order.
+
+Structure findings apply to docs that are new or substantially rewritten in the change; a lightly touched doc gets only its touched sections checked. No section template is imposed: the repo's own headings and conventions are never the finding. Check the order and the scan path within whatever shape the repo uses.
+
+### Doc/code responsibility splits
+Implementation detail in a README or package doc, where the doc comment next to the code owns the mechanism; or a guide-level essay in a code comment, where the README owns the overview. A README is not "the code but in english". State the invariant the design buys in the comment; keep the README a high-level guide.
+
+### Redundant glosses
+Parentheticals and asides that restate the sentence, the adjacent code, or what the surrounding convention already guarantees, instead of adding a distinct fact. Keep "(or has been killed on)". Cut "(the worker runs when the flag is unset)" after "It defaults to enabled". Do not document de facto conventions: if the framework or the migrations make something the default rule, the comment does not say so.
+
+## Reader model
+
+Symbol-anchored text and standalone docs fail differently, and the same text can be correct in one and a defect in the other.
+
+- **Inline comments and symbol docstrings** (a function, class, type, or constant doc comment) anchor to the immediate code. They may not re-explain visible code. One hop out (the caller, the callee, a guard, another writer) is the comment's context budget.
+- **Standalone docs** (package docs like a doc.go, READMEs, anything under a docs/ directory) serve readers that symbol-anchored text never meets: someone onboarding and an expert looking up one fact, in the same pass. Background and context that a comment must not carry are correct here; restating the same claim in multiple sections is still a defect. The sentence rules are the floor; the document must also serve the skimmer and the learner: the inverted pyramid at the document and section level, scan anchors (a reader who skims only the bold fragments still gets the story), and Basics before advanced (each section stands on the ones before it, so the reader who knows the basics can skip ahead and the reader who does not gets each idea in order).
+
+## What is NOT a finding
+
+- Genuine lists. An enumeration the reader needs is not a clause chain.
+- Load-bearing precision: pinned terms of art, error-class contracts (Postgres classes 40 and 55), SQL shapes in comments, cross-references that carry the why.
+- A term of art defined once and used afterwards. Defined terms are not untranslated jargon.
+- A metaphor verb attached to a stated mechanism ("the sweep heals the dropped ids", after the sweep's behavior is stated).
+- First-person informality: "This should not be possible. If we screwed up, ..." is the right voice, not a defect.
+- Wart comments: code that looks wrong but is correct, explained by naming the expected implementation, the crux, and why. This is the right shape, not sloppy prose.
+- A parenthetical that adds a distinct fact. These are placement rules, not presence bans: report the restatement or the dominance pattern, never the element itself.
+- Comments explaining why, tradeoffs, or non-obvious behavior.
+- UI strings whose tone is required by the feature or by an external protocol.
+- Presentation, not specificity. A doc-structure finding demands better order, never more content. Judge a doc against its own level of detail; do not report a doc for lacking enumerations or file pointers its own specificity never promised.
+- Unchanged legacy text outside the touched scope, unless the current change makes it newly wrong or newly suspicious.
+
+## Boundary with the other lenses
+
+- The **no-slop** lens owns AI-authorship tells: typography (em dashes, smart quotes), hedging, filler, verbosity, change narration, fourth wall breaks, stale artifacts, mechanism metaphors, and verbless telegraphic chains. Do not report those here. When a sentence is both unclear and an AI tell, leave it to no-slop.
+- The **breadcrumbs** lens owns narrative coherence: do the comments together tell the code's story? A missing comment is theirs. An unclear present comment is yours.
+- The **pedantic** lens owns factual accuracy and the repo's structural conventions (file placement, heading conventions): wrong names, wrong file refs, stale docs. Clear but wrong is theirs. Right but unreadable is yours. A violation of the repo's own doc conventions is theirs, never a structure finding here.
+
+## Method
+
+1. Use the diff stat from your scope gathering to identify changed files.
+2. For EVERY changed file, read the full current version. For changed markdown docs, read the full doc.
+3. Scan every comment, docstring, error message string, UI string, and doc paragraph.
+4. For standalone docs that are new or substantially rewritten in the change, also check the document: the inverted pyramid at the document and section level, scan anchors, Basics before advanced.
+5. For each violation, report the exact quoted text and the fix: the plain-English replacement, the split, or the claim to cut.
+
+Do NOT report on factual accuracy, narrative gaps, or AI tells. Only clarity.
+Do NOT report issues in files you did not actually read.
+
+Most findings are LOW. MEDIUM when the unclear prose can mislead a reader about behavior: a made-up phrase that names the wrong owner, a gloss that hides an UPDATE, a buried lead that hides a breaking change, or a doc whose structure hides the one fact the reader came for.
+
+## Category taxonomy
+
+- **MADE_UP_PHRASE**: A coined multi-word term that exists nowhere; the behavior must replace the label
+- **BUZZWORD**: A phrase that cannot be restated in plain English
+- **UNTRANSLATED_JARGON**: A project-private label, ticket ref, or code-domain noun doing an explanation's job
+- **CLAUSE_CHAIN**: Multiple ideas in one sentence, or noun stacks doing verb work; the fix splits or deletes whole claims
+- **BURIED_LEAD**: A doc or docstring that saves the point for the end, or opens with reading-order narration
+- **DOC_STRUCTURE**: A standalone doc whose order fails the skimmer or the learner (no scan anchors, interleaved basics and advanced detail, section leads off-point); the repo's own conventions are never the finding
+- **DOC_CODE_SPLIT**: Implementation detail in a README or package doc, or a guide-level essay in a code comment
+- **REDUNDANT_GLOSS**: A parenthetical or aside that restates the sentence, the adjacent code, or a framework default
+
+For clarity findings, the source of truth is the project's clear-writing rules and the surrounding code intent; use "N/A — mechanical finding" for the producer chain.

package/artifacts/skills/thatch-review-followup.md

@@ -275,7 +275,7 @@ After all findings have been dealt with (adequately addressed and replied to, or
 ### How to offer
 
 Present the offer as a choice:
-1. **Re-run the full structured review**: load `thatch-code-review` on the current HEAD. It will dispatch all nine specialists on the merge-base..HEAD range. The existing follow-up detection will cross-reference your prior comments. On Claude Code or Cursor (no sub-agent support), run each specialist skill in sequence, then run `thatch-review-synthesizer` to aggregate.
+1. **Re-run the full structured review**: load `thatch-code-review` on the current HEAD. It will dispatch all ten specialists on the merge-base..HEAD range. The existing follow-up detection will cross-reference your prior comments. On Claude Code or Cursor (no sub-agent support), run each specialist skill in sequence, then run `thatch-review-synthesizer` to aggregate.
 2. **End the re-review here**: the user confirmed their concerns were addressed (or decided how to handle the unaddressed ones) and does not want another full round.
 
 The offer is just an offer. The user may decline. They may have only wanted to confirm their concerns were addressed.

package/artifacts/skills/thatch-review-synthesizer.md

@@ -3,7 +3,7 @@ name: thatch-review-synthesizer
 description: Verify and synthesize findings from multiple review specialist skills into a single deduplicated, severity-grouped report. Cross-references prior review comments and sibling PR registers when provided. Use after running one or more thatch-review-* specialist skills.
 ---
 
-You are a review synthesizer. You have received findings from one or more review specialists (pedantic, acceptance, state-flow, economy, no-slop, breadcrumbs, mark-and-sweep, highlights, technique). Your job is to verify their citations against the actual code, deduplicate across specialists, and produce a single, coherent final report.
+You are a review synthesizer. You have received findings from one or more review specialists (pedantic, acceptance, state-flow, economy, no-slop, clarity, breadcrumbs, mark-and-sweep, highlights, technique). Your job is to verify their citations against the actual code, deduplicate across specialists, and produce a single, coherent final report.
 
 ## Static analysis only
 You review code by reading it. Do NOT run tests, linters, compilers, or any build commands.

package/bin/thatch

@@ -18,13 +18,25 @@ import { createDebugLog } from "../src/debug";
 
 const configHome = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
 const dbPath = process.env.THATCH_DB_PATH ?? join(configHome, "thatch", "thatch.db");
-const db: ThatchDB = new ThatchDB(dbPath, { chatOpenTabs: chatOpenTabsProvider(() => db.chatTabClosures()) });
 
-const [command, ...args] = process.argv.slice(2);
+const argv = process.argv.slice(2);
+
+// Help is checked before the DB is opened or any subcommand runs, and
+// against the WHOLE argument list - not just the leading flags - so
+// `thatch chat list -h` and `thatch -h chat list` print usage instead of
+// executing. Asking for help is not an error: exit 0, where a bad
+// command still exits 1.
+if (argv.includes("-h") || argv.includes("--help")) usage(0);
+
+const [command, ...args] = argv;
+
+const db: ThatchDB = new ThatchDB(dbPath, { chatOpenTabs: chatOpenTabsProvider(() => db.chatTabClosures()) });
 
-function usage(): never {
+function usage(exitCode = 1): never {
   console.error(`USAGE
   thatch --version, -v             Print version and exit
+  thatch -h, --help                Print this usage and exit (the flag
+                                    works anywhere in the command line)
   thatch stores                    List all stores
   thatch list   [store]            List memory labels in a store  
   thatch show   <label> [store]    Display a memory by label
@@ -52,13 +64,16 @@ function usage(): never {
                                    Full conversation as OpenAI chat-completions JSONL
   thatch session search <query> [--session <id>] [--regex] [--limit N]
                                    JSONL of matching parts across sessions (decoded content)
-  thatch chat list [--stale N|all]  Registered chat sessions. Default shows
-                                    only active (fresh-heartbeat) sessions:
-                                    name, session id, age, status, project,
-                                    topic. --stale adds the stale section:
-                                    N bounds it to sessions seen in the
-                                    last N days (default 1); all shows
-                                    every stale session.
+  thatch chat list [--recent] [--stale N|all]
+                                    Registered chat sessions. Default shows
+                                    only open sessions (plus MCP rows, which
+                                    read mail at their next prompt): name,
+                                    session id, age, status, project, topic.
+                                    Tab-less fresh sessions collapse into a
+                                    hidden-count note; --recent shows them.
+                                    --stale adds the stale section: N bounds
+                                    it to sessions seen in the last N days
+                                    (default 1); all shows every stale one.
   thatch chat tail [--once] [--limit N|all] [--match RE]
                    [--from NAME] [--to NAME] [--since DT] [--until DT]
                                    Follow cross-session chat as a JSONL
@@ -75,7 +90,7 @@ function usage(): never {
 
 Stores default to the repo detected from git remote. Use "global" for the
 global store. Use "all" with search to search project + global together.`);
-  process.exit(1);
+  process.exit(exitCode);
 }
 
 async function defaultStore(): Promise<string> {
@@ -425,29 +440,42 @@ async function sessionCommand(rest: string[]): Promise<void> {
 const CHAT_ROSTER_HEADER = ["NAME", "SESSION ID", "AGE", "STATUS", "PROJECT", "TOPIC"];
 
 /**
- * Renders the `chat list` roster as two sections - Active and Stale - each
- * an aligned-column table under a header row. Section headers are bold,
- * the stale explainer is muted italic; rows use green names, dim age,
- * green/red status, and a muted italic topic. The STATUS column carries
- * the liveness verdict: open (tab open now), recent (host alive, no open
- * tab), active/idle (MCP rows), stale (host presumed gone).
+ * Renders the `chat list` roster as three sections - Active, Recent, and
+ * Stale - each an aligned-column table under a header row. Section headers
+ * are bold, the Recent and Stale explainers are muted italic; rows use
+ * green names, dim age, green/yellow/red status, and a muted italic topic.
+ * The STATUS column carries the liveness verdict: open (tab open now),
+ * recent (host alive, no open tab), active/idle (MCP rows), stale (host
+ * presumed gone).
+ * showRecent = false (the CLI default without `--recent`) collapses the
+ * Recent section into a muted hidden-count note pointing at the flag.
+ * Unlike the Stale hide - which the caller does by pre-filtering rows
+ * before this function, dropping them silently - the recent hide needs
+ * the rows in hand to count them, so it happens here as a note. An
+ * all-recent roster therefore renders the note alone, with no section
+ * header: there is no Recent section on the page to head, while the
+ * stale hidden note rides under a header because its section IS
+ * displayed;
  * staleCapMs bounds how old a stale row is displayed (null = no bound);
  * rows past the cap collapse into a muted hidden-count note so the reader
  * knows rows exist that the window left out.
+ * now is the render's single clock sample: the split, every per-row
+ * verdict, and the caller's pre-filter must agree, or a row aging past
+ * the staleness boundary mid-render could land in two sections at once.
  * Color is applied only when stdout is an interactive terminal (and
  * NO_COLOR is unset), so piped output - grep, redirect, QA runners - stays
  * clean plain text.
  */
-function formatChatRoster(sessions: ChatSessionRow[], staleCapMs: number | null = null, openTabs?: ReadonlySet<string>): string {
+function formatChatRoster(sessions: ChatSessionRow[], staleCapMs: number | null = null, openTabs?: ReadonlySet<string>, showRecent = true, now = Date.now()): string {
   const colored = process.stdout.isTTY === true && !process.env.NO_COLOR;
   const paint = (code: string, s: string) => (colored ? `\x1b[${code}m${s}\x1b[0m` : s);
-  const { active, stale, staleHidden } = splitChatRoster(sortChatRoster(sessions), Date.now(), staleCapMs);
+  const { active, recent, stale, staleHidden } = splitChatRoster(sortChatRoster(sessions), now, staleCapMs, openTabs);
   const renderTable = (rows: ChatSessionRow[]) => {
     const cells = (r: ChatSessionRow) => [
       r.name,
       r.session_id,
       humanAge(r.last_seen),
-      chatLiveness(r, Date.now(), openTabs),
+      chatLiveness(r, now, openTabs),
       r.project ?? "unknown",
       r.topic ?? "",
     ];
@@ -476,6 +504,20 @@ function formatChatRoster(sessions: ChatSessionRow[], staleCapMs: number | null
   if (active.length > 0) {
     parts.push([paint("1", "# Active Sessions"), renderTable(active)].join("\n"));
   }
+  if (recent.length > 0) {
+    if (showRecent) {
+      const explainer = "These sessions have a fresh heartbeat but no open tab, so a wake may not reach them until their tab reopens; headless subordinates may still read mail on their own turns.";
+      parts.push([paint("1", "# Recent Sessions"), paint("3;90", explainer), renderTable(recent)].join("\n"));
+    } else {
+      // Bare note, no section header: there is no Recent section on the
+      // page, so a header would announce a section the view does not
+      // render. The stale hidden note rides under a header because with
+      // --stale its section IS rendered.
+      parts.push(
+        paint("3;90", `${recent.length} recent session${recent.length === 1 ? "" : "s"} hidden (alive, no open tab); --recent to show`),
+      );
+    }
+  }
   if (stale.length > 0 || staleHidden > 0) {
     const lines = [paint("1", "# Stale Sessions")];
     if (stale.length > 0) {
@@ -505,13 +547,24 @@ async function chatCommand(rest: string[]): Promise<void> {
       // sessions from burying the fresh signal. --stale all restores the
       // unbounded view. A bad value dies loudly rather than silently
       // shrinking the roster.
-      // Default: active sessions only. --stale [N|all] opts into the
-      // stale section - bare --stale keeps the one-day display cap, N
-      // bounds it, all removes it. The value is parsed by hand (not
-      // flagValue) because bare --stale is meaningful.
+      // Default: open sessions only (plus MCP rows, which read mail at
+      // their next prompt - "open" is meaningless for them). --recent
+      // opts into the Recent section (alive, no open tab). The two hidden
+      // defaults work differently: --recent's leaves a muted count note
+      // in the renderer (it needs the rows in hand to count them);
+      // --stale's drops the rows silently in the pre-filter below, and
+      // only the empty-roster message points at the flag. Unlike --stale
+      // it takes no window value: recent rows are bounded by the heartbeat
+      // window itself, so there is nothing to cap. The value is parsed by
+      // hand (not flagValue) because bare --stale is meaningful.
+      const showRecent = restArgs.includes("--recent");
       const showStale = restArgs.includes("--stale");
       const staleIdx = restArgs.indexOf("--stale");
-      const staleNext = showStale ? restArgs[staleIdx + 1] : undefined;
+      const rawNext = showStale ? restArgs[staleIdx + 1] : undefined;
+      // A token starting with "--" is a sibling flag (e.g. "--stale
+      // --recent"), not --stale's value: --stale stays bare instead of
+      // eating the flag.
+      const staleNext = rawNext !== undefined && rawNext.startsWith("--") ? undefined : rawNext;
       let staleCapMs: number | null = 24 * 60 * 60 * 1000;
       if (staleNext !== undefined) {
         if (staleNext === "all") staleCapMs = null;
@@ -523,17 +576,25 @@ async function chatCommand(rest: string[]): Promise<void> {
       // The open-tab set is read once per invocation at render time: rows
       // with a tab render "open", fresh rows without one "recent".
       const openTabs = chatOpenTabsProvider(() => db.chatTabClosures())();
-      let sessions = db.listChatSessions();
-      if (!showStale) sessions = sessions.filter((r) => chatLiveness(r, Date.now(), openTabs) !== "stale");
+      // One clock sample per render: the pre-filter, the split, and every
+      // per-row verdict must agree, or a row aging past the staleness
+      // boundary mid-render could land in two sections at once.
+      const now = Date.now();
+      const registered = db.listChatSessions();
+      // Stale rows are hidden here (not in the renderer) so the
+      // emptiness check can tell an empty directory from a stale-only
+      // one; recent rows are left in because formatChatRoster needs them
+      // to render the hidden-count note.
+      const sessions = registered.filter((r) => showStale || chatLiveness(r, now, openTabs) !== "stale");
       if (sessions.length === 0) {
         console.log(
-          showStale
+          registered.length === 0
             ? "No sessions registered. Sessions join the directory automatically on their first idle (opencode), or via chat_register."
             : "No active sessions. (Stale sessions are hidden; run with --stale to include them.)",
         );
         break;
       }
-      console.log(formatChatRoster(sessions, showStale ? staleCapMs : null, openTabs));
+      console.log(formatChatRoster(sessions, showStale ? staleCapMs : null, openTabs, showRecent, now));
       break;
     }
 

package/docs/dev/features/cli.md

@@ -27,7 +27,13 @@ The thatch CLI is a Bun script at `bin/thatch`. It provides memory inspection, M
 
 ## Global behavior
 
-- No `--version`, `--help`, `-h`, or short flags. No subcommand aliases.
+- `--version` and `-v` print the package version and exit 0.
+- `-h` and `--help` print usage and exit 0. The check runs before the DB
+  is opened and before any subcommand dispatch, and scans the WHOLE
+  argument list - not just the leading flags - so `thatch chat list -h`
+  and `thatch -h chat list` show usage instead of executing. Explicit
+  help exits 0 where a usage error exits 1.
+- No other short flags. No subcommand aliases.
 - 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).
@@ -47,12 +53,21 @@ Inherits stdio, exits with the child's exit code. Errors and exits 1 if none fou
 Read-only window on the cross-session chat directory ([cross-session-chat.md](cross-session-chat.md)):
 
 - `chat list` renders the roster as aligned columns under a header row
-  (NAME/AGE/STATUS/PROJECT/TOPIC), colorized only when stdout is a TTY
-  (`formatChatRoster()` in `bin/thatch`; pipes and QA runners get plain
-  text). Rows are split into Active and Stale sections by
-  `splitChatRoster()`; the status column is `chatLiveness()`'s verdict
+  (NAME/SESSION ID/AGE/STATUS/PROJECT/TOPIC), colorized only when stdout
+  is a TTY (`formatChatRoster()` in `bin/thatch`; pipes and QA runners
+  get plain text). Rows are split into Active, Recent, and Stale
+  sections by `splitChatRoster()` (it takes the open-tab set, so fresh
+  opencode rows split into open versus recent); the status column is
+  `chatLiveness()`'s verdict
   (`open`/`recent`/`stale` for opencode rows - the open-tab reader feeds
-  the open/recent split - `active`/`idle` for MCP rows).
+  the open/recent split - `active`/`idle` for MCP rows). The Recent and
+  Stale sections are flag-guarded, and the two guards hide differently:
+  without `--recent` the Recent section is replaced by a muted
+  hidden-count note (the renderer keeps the rows to count them), while
+  without `--stale` stale rows are dropped entirely by a pre-filter in
+  the command case - only the empty-roster message points at the flag.
+  `--stale [N|all]` reveals the stale rows under a one-day display cap
+  whose overflow collapses into a hidden-count note.
 - `chat tail` follows the message stream as JSONL: one `ChatTailEvent`
   per line via `formatChatTailJsonl()` (a bare `JSON.stringify`; no ANSI,
   no markdown rendering, no local-time conversion - the tail is a log for
@@ -114,7 +129,7 @@ Read-only window on the cross-session chat directory ([cross-session-chat.md](cr
 ## Key invariants
 
 - No arg-parsing library. Args are positional, parsed by hand from `process.argv.slice(2)`.
-- No `--version`, `--help`, `-h`, or short flags. No subcommand aliases.
+- `--version`/`-v` prints the version; `-h`/`--help` prints usage from anywhere in the argument list (checked upstream of dispatch, before the DB opens) and exits 0. No other short flags. No subcommand aliases.
 - DB opened once at startup, closed at end (except `mcp` which closes early).
 - Store name auto-detected from git remote. "global" is the shared store. "all" (search only) means project + global.
 - Unknown command or missing required arg calls `usage()` and exits 1.

package/docs/dev/features/commands.md

@@ -55,8 +55,8 @@ same source as the install list in src/skills.ts and both host
 instruction skill lists. `peer-review` weights org
 velocity and walks the project's persistent memory (the one tool it
 names, spelled through the `ToolNamer` so MCP renderings stay correct);
-`self-review` weights the reputation lenses (no-slop, technique,
-breadcrumbs) and iterates rounds until a round produces no meaningful
+`self-review` weights the reputation lenses (no-slop, clarity,
+technique, breadcrumbs) and iterates rounds until a round produces no meaningful
 findings. The couching also names the MCP `Focus:` line as a target
 source, because MCP prompts replace the file commands' `$ARGUMENTS`
 section with a `Focus:` line.

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

@@ -317,18 +317,26 @@ is restart persistence by design), so dead-window residue reads OPEN until
 its heartbeat ages out; tabs disabled degrades everything to RECENT.
 
 `chat_list`
-groups the result into Active and Stale sections - the stale section's
-explainer says what stale means, and each row renders its verdict -
+groups the result into Active, Recent, and Stale sections - the Recent
+and Stale sections' explainers say what those states mean, and each row
+renders its verdict -
 and `chat_send` states the recipient's
 liveness at send time, so a sender mailing a ghost learns it immediately
 instead of waiting on a wake that will never fire, and a sender mailing a
 tab-less session is told the wake is not guaranteed. Both roster surfaces
-order rows with `sortChatRoster` (also src/chat.ts): project first,
+order rows with `sortChatRoster` (also src/chat.ts) and split fresh
+opencode rows along the same open/recent boundary (`splitChatRoster`
+takes the open-tab set): project first,
 alphabetical, with no-project rows last; most recently seen first within
-a project. The CLI roster bounds
-the stale display to one day by default (`--stale N` in days, `--stale all`
-unbounded), collapsing older rows into a hidden-count note; the tool
-surface stays unbounded so an agent always sees the full directory.
+a project. The CLI roster guards the Recent and Stale sections behind
+flags, and the two guards hide differently: without `--recent` the
+tab-less rows collapse into a muted hidden-count note (revealed by the
+flag), while without `--stale` stale rows are dropped entirely; with
+`--stale [N|all]` they show under a one-day display cap that collapses
+older rows into a
+hidden-count note. The tool
+surface shows all three sections unbounded so an agent always sees the
+full directory.
 `session.deleted` is the graceful-exit fast path that unregisters immediately.
 
 ### Delivery, re-nudge, and the rate cap

package/docs/dev/skills.md

@@ -43,6 +43,7 @@ description: Extract durable project facts ... Use when ...
 | `thatch-review-state-flow` | Data flow and contracts: module boundaries, implicit FSMs, error propagation. |
 | `thatch-review-economy` | Design simplicity and maintainability: is the complexity earned? Evaluates both the overall change design (forest) and individual touch points (trees) for unnecessary complexity, redundancy, and simpler available alternatives. |
 | `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth-wall breaks, em dashes, filler. |
+| `thatch-review-clarity` | Prose clarity in comments, docstrings, error strings, and docs: made-up phrases, buzzwords, untranslated jargon, clause chains, buried leads, doc/code responsibility splits, checked against the project's clear-writing rules regardless of who wrote the text. |
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of behavior? |
 | `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
 | `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar against generic praise. |
@@ -79,7 +80,7 @@ description: Extract durable project facts ... Use when ...
 
 ## REVIEW_COMMON
 
-The seven problem-finding review specialists share a framework interpolated via `${REVIEW_COMMON}` (the technique and highlights specialists do not use it: technique reports informational notes and highlights finds positive things, each with its own structure):
+The problem-finding review specialists share a framework interpolated via `${REVIEW_COMMON}` (the technique and highlights specialists do not use it: technique reports informational notes and highlights finds positive things, each with its own structure):
 
 - **Static analysis only** — no running tests/linters/compilers.
 - **Scope gathering** — resolve the git range, `git diff --stat`, read changed

package/docs/user/README.md

@@ -202,7 +202,7 @@ requirements.
 | Tool | What it does |
 |------|-------------|
 | `thatch_chat_register` | Join the cross-session chat directory, so other sessions on this machine can message you. Display names are assigned by thatch, never chosen (a pool name plus a never-reused counter), so a name always refers to the same session. Call with no arguments to join, rejoin after unregistering, or check your name. On hosts without session context (Claude Code, Cursor), pass the name your thatch hook printed as `as`. |
-| `thatch_chat_list` | List registered sessions grouped into Active and Stale sections (stale = two missed heartbeats, about a minute; its host process has probably stopped), with how long ago each last checked in, each session's project and checkout kind (project root or linked worktree), its topic, and your unread count. |
+| `thatch_chat_list` | List registered sessions grouped into Active, Recent, and Stale sections (recent = alive but no open tab, so a wake may not be guaranteed; stale = two missed heartbeats, about a minute; its host process has probably stopped), with how long ago each last checked in, each session's project and checkout kind (project root or linked worktree), its topic, and your unread count. |
 | `thatch_chat_send` | Send a message to another registered session, by name or session id. The recipient is nudged when its session is idle. |
 | `thatch_chat_read` | Drain your inbox: all unread messages oldest-first, marked read. Senders identified by display name. |
 | `thatch_chat_unregister` | Leave the chat directory. |
@@ -331,6 +331,7 @@ response, walkthrough, and workflow skills that support the review pipeline:
 | `thatch-review-state-flow` | Data flow and contracts: module boundaries, implicit state machines, error propagation, separation of concerns. |
 | `thatch-review-economy` | Design simplicity and maintainability: is the complexity earned? Evaluates both the overall change design (forest) and individual touch points (trees) for unnecessary complexity, redundancy, and simpler available alternatives. |
 | `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth wall breaks, em dashes, hedging, filler. |
+| `thatch-review-clarity` | Prose clarity in comments, docstrings, error strings, and docs: made-up phrases, buzzwords, untranslated jargon, clause chains, buried leads, doc/code responsibility splits, checked against the project's clear-writing rules regardless of who wrote the text. |
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of the code's behavior? |
 | `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
 | `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar against generic praise. |
@@ -406,7 +407,7 @@ specialist in sequence, then synthesize:
 ```text
 1. Load thatch-review-pedantic, review branch feature-x, report findings.
 2. Load thatch-review-acceptance, review the same branch.
-3. ... repeat for state-flow, no-slop, breadcrumbs, mark-and-sweep ...
+3. ... repeat for state-flow, no-slop, clarity, breadcrumbs, mark-and-sweep ...
 4. Load thatch-review-synthesizer, verify and aggregate all findings.
 ```
 

package/docs/user/cli.md

@@ -4,6 +4,10 @@ Thatch ships with a command-line tool for inspecting memories and
 running maintenance tasks outside the agent. It requires `bun` on your
 PATH.
 
+`thatch --help` (or `-h`) prints the full command list and exits 0.
+The flag works anywhere in the command line: `thatch chat list -h`
+shows help instead of running the command.
+
 ## Memory inspection
 
 ```bash
@@ -45,7 +49,8 @@ Read-only access to the chat directory your opencode sessions share
 (see [cross-session-chat.md](cross-session-chat.md)):
 
 ```bash
-thatch chat list               # who is registered: name, age, project, topic
+thatch chat list               # who is open now: name, age, project, topic
+thatch chat list --recent      # also show alive sessions with no open tab
 thatch chat list --stale all   # also show stale sessions older than a day
 thatch chat tail               # follow sent and read events, live (JSONL)
 thatch chat tail --once        # print the last 20 messages and exit
@@ -55,21 +60,28 @@ thatch chat tail --from al --to bob        # substring match on names
 thatch chat tail --since 2026-09-12 --until "2026-09-13 09:00"   # a window
 ```
 
-`chat list` shows every registered session in two sections, Active and
-Stale, each as aligned columns under a header row: how long since its
-last heartbeat, its status (`open` - a tab is open now - or `recent` -
-host alive, no open tab - for opencode sessions;
-`active` or `idle` for Claude Code and Cursor sessions, which only beat
-when a prompt runs), its project, and its topic (the session's title) -
-the fastest way to answer "which session should I talk to about X?"
-Rows are grouped by project (alphabetical; sessions with no project
-last), most recently seen first within each project. A
-stale session has missed two heartbeats, about a minute: the opencode
-process hosting it has probably stopped. The stale section shows rows
-up to one day old by default; older ones collapse into a hidden-count
-note so long-dead sessions cannot bury the fresh signal. Pass
-`--stale N` (days) to widen the window or `--stale all` to see every
-stale row. Color is added only when the
+`chat list` renders the chat roster in three sections - Active, Recent,
+and Stale - each as aligned columns under a header row: how long since its last heartbeat, its status (`open` - a tab is open now - or
+`recent` - host alive, no open tab - for opencode sessions; `active` or
+`idle` for Claude Code and Cursor sessions, which only beat when a
+prompt runs), its project, and its topic (the session's title) - the
+fastest way to answer "which session should I talk to about X?" Rows
+are grouped by project (alphabetical; sessions with no project last),
+most recently seen first within each project.
+
+The default view shows the sessions you can wake or reach now: open
+sessions plus Claude Code and Cursor rows, which read mail at their
+next prompt. A recent session - its harness is alive but its tab is
+closed, so a wake may not reach it until the tab reopens - collapses
+into a muted hidden-count note pointing at `--recent`, which reveals
+the Recent section. A stale session has missed two heartbeats, about a
+minute: the opencode process hosting it has probably stopped. Its
+section is hidden too, behind `--stale`, but without a count note - the
+default view simply drops stale rows. The stale section
+shows rows up to one day old by default; older ones collapse into a
+hidden-count note so long-dead sessions cannot bury the fresh signal.
+Pass `--stale N` (days) to widen the window or `--stale all` to see
+every stale row. Color is added only when the
 output is a terminal; a pipe prints plain aligned text.
 
 `chat tail` prints the conversation as a JSONL event log: one JSON

package/docs/user/code-review.md

@@ -25,7 +25,7 @@ the review:
 3. **Research affected workflows**: load `thatch-code-archaeology`,
    trace the code paths the change touches.
 4. **Estimate complexity**: partition the diff into review units.
-5. **Dispatch specialists**: fan out the nine specialists as
+5. **Dispatch specialists**: fan out the specialists as
    parallel sub-agents, each with the context brief.
 6. **Synthesize**: the synthesizer reads all specialist output,
    verifies each finding (cited text exists, claim is accurate,
@@ -38,7 +38,7 @@ the review:
    sibling is not a defect, and inconsistencies between connected
    PRs surface as cross-PR notes.
 
-## The nine specialists
+## The specialists
 
 | Skill | What it checks |
 |-------|-------------|
@@ -47,6 +47,7 @@ the review:
 | `thatch-review-state-flow` | Module boundaries, implicit state machines, error propagation, separation of concerns. |
 | `thatch-review-economy` | Design simplicity and maintainability: is the complexity earned? Evaluates both the overall change design (forest) and individual touch points (trees) for unnecessary complexity, redundancy, and simpler available alternatives. |
 | `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth wall breaks, em dashes, hedging, filler. |
+| `thatch-review-clarity` | Prose clarity in comments, docstrings, error strings, and docs: made-up phrases, buzzwords, untranslated jargon, clause chains, buried leads, doc/code responsibility splits, checked against the project's clear-writing rules regardless of who wrote the text. |
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of the code's behavior? |
 | `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
 | `thatch-review-highlights` | Positive finding detection: clever solutions, cleanup done along the way, documentation that helps. Medium-high bar. |
@@ -61,7 +62,7 @@ Two slash commands run the same pipeline with the findings weighted for
 whose work is under review.
 
 - `/thatch/self-review` reviews your own completed work before you
-  submit it. The slop, technique, and breadcrumbs lenses weigh
+  submit it. The slop, clarity, technique, and breadcrumbs lenses weigh
   heaviest, simplicity is overweighted on shared projects, and
   technique or highlights findings that would simplify the design are
   surfaced for an adopt-or-dismiss decision rather than left as

package/docs/user/cross-session-chat.md

@@ -25,11 +25,12 @@ explicitly with `thatch_chat_register` (no arguments) - useful after
 `chat_unregister`, or just to check your assigned name. Once registered:
 
 - `thatch_chat_list` shows every registered session on the machine, grouped
-  into Active and Stale sections: active sessions' harness is alive; stale
+  into Active, Recent, and Stale sections: active sessions either have an
+  opencode tab open right now or are Claude Code and Cursor rows, which
+  read mail at their next prompt; recent ones are alive but have no open
+  tab, so a wake may not reach them until the tab reopens; stale
   ones have missed two heartbeats, about a minute (the opencode process
-  hosting them has probably stopped). Each active row also carries a
-  liveness verdict: `open` means the session has an opencode tab open
-  right now, `recent` means the harness is alive but no tab is open. Each
+  hosting them has probably stopped). Each
   row carries how long ago the session last
   checked in, its project, whether it runs in the project root or a linked
   git worktree, its topic, and your unread count

package/docs/user/skills.md

@@ -43,6 +43,7 @@ Skills are split into shared (all hosts) and opencode-only:
 | `thatch-review-state-flow` | Data flow and contracts: module boundaries, implicit state machines, error propagation, separation of concerns. |
 | `thatch-review-economy` | Design simplicity and maintainability: is the complexity earned? Evaluates both the overall change design (forest) and individual touch points (trees) for unnecessary complexity, redundancy, and simpler available alternatives. |
 | `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth wall breaks, em dashes, hedging, filler. |
+| `thatch-review-clarity` | Prose clarity in comments, docstrings, error strings, and docs: made-up phrases, buzzwords, untranslated jargon, clause chains, buried leads, doc/code responsibility splits, checked against the project's clear-writing rules regardless of who wrote the text. |
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of the code's behavior? |
 | `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
 | `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config. Works with OpenCode (as a plugin), Claude Code (as an MCP server), and Cursor (as an MCP server).",
   "type": "module",
   "main": "src/index.ts",

package/src/chat.ts

@@ -389,31 +389,41 @@ export function sortChatRoster(rows: ChatSessionRow[]): ChatSessionRow[] {
   });
 }
 
-/** Splits the roster for the two-section display: Active (wake-able or
- *  reachable - fresh opencode rows and every MCP row, which read mail at
- *  their next prompt) and Stale (opencode rows whose harness has stopped
- *  reporting; mail to them waits until they resume).
+/** Splits the roster for the three-section display: Active (wakeable or
+ *  reachable - opencode rows with an open tab, plus every MCP row, which
+ *  read mail at their next prompt), Recent (fresh opencode rows with no
+ *  open tab: the harness is alive and beating, but a wake may not reach
+ *  the session until its tab reopens - headless subordinates may still
+ *  read mail on their own turns), and Stale (opencode rows whose harness
+ *  has stopped reporting; mail to them waits until they resume).
+ *  openTabs refines fresh opencode rows into open versus recent; when
+ *  omitted every fresh opencode row degrades to recent, never a false
+ *  open (chatLiveness's rule).
  *  staleCapMs bounds how old a stale row the roster displays, so
  *  long-dead sessions cannot bury the fresh signal; hidden rows come
  *  back only as the staleHidden count, so the CLI can say what it left
  *  out. null (the default) shows every stale row - the tool surface has
  *  no cap, only the CLI applies one. */
-export function splitChatRoster(rows: ChatSessionRow[], now = Date.now(), staleCapMs: number | null = null): { active: ChatSessionRow[]; stale: ChatSessionRow[]; staleHidden: number } {
+export function splitChatRoster(rows: ChatSessionRow[], now = Date.now(), staleCapMs: number | null = null, openTabs?: ReadonlySet<string>): { active: ChatSessionRow[]; recent: ChatSessionRow[]; stale: ChatSessionRow[]; staleHidden: number } {
   const active: ChatSessionRow[] = [];
+  const recent: ChatSessionRow[] = [];
   const stale: ChatSessionRow[] = [];
   let staleHidden = 0;
   for (const row of rows) {
-    if (chatLiveness(row, now) === "stale") {
+    const verdict = chatLiveness(row, now, openTabs);
+    if (verdict === "stale") {
       if (staleCapMs !== null && now - Date.parse(row.last_seen) > staleCapMs) {
         staleHidden++;
       } else {
         stale.push(row);
       }
+    } else if (verdict === "recent") {
+      recent.push(row);
     } else {
       active.push(row);
     }
   }
-  return { active, stale, staleHidden };
+  return { active, recent, stale, staleHidden };
 }
 
 /**

package/src/commands.ts

@@ -192,7 +192,7 @@ ${reviewPipelineCouching}
 
 ## Self review mode rules
 
-- The reputation lenses weigh heaviest. NoSlop, Technique, and Breadcrumbs findings outrank same-severity findings from the other lenses. AI-writing tells, vague comments, and a missing narrative are exactly what this review exists to catch before anyone else sees them.
+- The reputation lenses weigh heaviest. NoSlop, Clarity, Technique, and Breadcrumbs findings outrank same-severity findings from the other lenses. AI-writing tells, unclear prose, and a missing narrative are exactly what this review exists to catch before anyone else sees them.
 - Overweight simplicity on shared projects. Prefer findings that make the design easier to understand, easier to test, and more reliable: fewer assumptions, less surface area for bugs and side effects.
 - Technique and highlights findings are decisions, not footnotes. Each one that would produce a simpler, clearer, or more reliable design is surfaced for an adopt-or-dismiss decision before submission. Work through them with the user one at a time; do not leave them as informational asides.
 - Iterate rounds. After each round, work the findings with the user: fix each, or explicitly decline it with a reason. Then run another full round on the updated state. A round is meaningful when it produces a MEDIUM or higher finding, or a technique or slop finding worth adopting. A round producing only LOW mechanical findings gets them fixed but does not trigger another round. Stop at the first round with no meaningful findings, and never run more than three rounds.`,

package/src/prompts.ts

@@ -19,6 +19,7 @@ export const REVIEW_SPECIALISTS: readonly string[] = [
   "thatch-review-state-flow",
   "thatch-review-economy",
   "thatch-review-no-slop",
+  "thatch-review-clarity",
   "thatch-review-breadcrumbs",
   "thatch-review-mark-and-sweep",
   "thatch-review-highlights",

package/src/tool-defs.ts

@@ -2139,7 +2139,10 @@ const chatRegisterDef: ToolDef = {
 
 /** Lists registered sessions with liveness. Stale means the session's host
  *  process has not heartbeat-ed it recently - it is gone or hung. Fresh
- *  rows split into open (a tab is open now) and recent (no known tab). */
+ *  rows split into open (a tab is open now) and recent (no known tab).
+ *  The three sections render unguarded by design, unlike the CLI's
+ *  --recent/--stale guards: an agent choosing a recipient always needs
+ *  the full directory, including the tab-less rows it may still reach. */
 const chatListDef: ToolDef = {
   name: "chat_list",
   description:
@@ -2159,7 +2162,7 @@ const chatListDef: ToolDef = {
     }
     const unread = ctx.db.unreadChatCount(identity.sessionID);
     const openTabs = ctx.openTabs?.() ?? new Set<string>();
-    const { active, stale } = splitChatRoster(sortChatRoster(sessions));
+    const { active, recent, stale } = splitChatRoster(sortChatRoster(sessions), Date.now(), null, openTabs);
     const line = (s: (typeof sessions)[number]) => {
       const self = s.session_id === identity.sessionID;
       const liveness = chatLiveness(s, Date.now(), openTabs);
@@ -2177,6 +2180,15 @@ const chatListDef: ToolDef = {
     if (active.length > 0) {
       sections.push(`# Active Sessions\n\n${active.map(line).join("\n")}`);
     }
+    if (recent.length > 0) {
+      sections.push(
+        `# Recent Sessions\n\n` +
+          `_These sessions are alive but have no open tab: a wake may not reach them ` +
+          `until their tab reopens, though headless subordinates may still read mail ` +
+          `on their own turns._\n\n` +
+          `${recent.map(line).join("\n")}`,
+      );
+    }
     if (stale.length > 0) {
       sections.push(
         `# Stale Sessions\n\n` +