opencode-thrum-pro 0.1.0

package/assets/skills/trace-spec-to-plan/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: trace-spec-to-plan
+description: "Use before converting a plan into epics/beads/worktrees, and whenever you need to know whether a plan actually implements its spec. Walks EVERY requirement in the spec forward into the plan, one item at a time, and reports PLANNED / NAME-ONLY / ABSENT / PARTIAL. Distinct from verify-against-source, which reads the ARTIFACT and asks 'does this honor its source' — this reads the SPEC and asks 'where did this land'. Triggers - about to run project-setup, about to create epics or beads, plan review, 'does the plan cover the spec', 'did we miss anything', 'is the plan complete'."
+---
+
+# Trace Spec → Plan
+
+**Announce at start:** "I'm using trace-spec-to-plan to walk every spec requirement into the plan."
+
+## Why this exists
+
+> 🔑 **A reviewer reading an artifact cannot see what isn't in it.**
+
+That sentence is the whole justification. Every other review in the pipeline reads the **plan** and asks *"is this sound?"* — so it can only find defects in what is present. **Absence has nothing to look at.**
+
+⇒ **This replaces ad-hoc extra audits in the standard flow rather than supplementing them.**
+
+## When it runs
+
+**Immediately before `project-setup` creates epics and beads.** That is the last moment the spec is still in the room. Once a requirement is missing from the plan **and** absent from the beads, the beads become the working set, nobody consults the spec again, and the gap stops being discoverable at all.
+
+Also valid: any time someone asks whether a plan is complete against its source.
+
+### Two hard preconditions
+
+🚫 **NEVER run by the plan's own author.** Self-review cannot catch a requirement the author never perceived — same person, same anchoring, same blind spot. **Dispatch it.**
+
+⚠️ **Run against a FROZEN plan.** A sweep racing live edits produces stale findings that cost more to triage than they are worth.
+
+## Sizing — the judgment call
+
+1. **COUNT THE SPEC ITEMS FIRST, NOT PAGES.** Include every sub-item: `A3.1–3.4`, `P1–P8`, each ruled-out branch, each contradiction disposition, each named sequencing constraint. A spec that reads as "20-something sections" was **~65 discrete requirements**.
+2. **≤ ~15 items ⇒ one agent. More ⇒ partition at ~12–15 items per agent.**
+3. 🔴 **PARTITION BY SPEC ITEM, NEVER BY PLAN SECTION.** Section-partitioning manufactures false ABSENTs whenever a requirement is covered in a phase that auditor wasn't given. **Every agent searches the WHOLE plan for its own items.**
+4. Write the shared instructions to **one file** (`resources/sweep-agent-prompt.md`) and give each agent only its item list. Keeps dispatches short and identical.
+5. Use `efficient-multi-agent-research` for launch-and-wait mechanics.
+
+## The four verdicts
+
+| Verdict | Means |
+|---|---|
+| **PLANNED** | A task exists with concrete steps that would make the requirement true — files named, code or commands shown. |
+| **NAME-ONLY** | The plan mentions, quotes, or asserts the requirement — but no task carries out steps. |
+| **ABSENT** | Not mentioned anywhere. |
+| **PARTIAL** | Part is planned; a named part is not. Say which. |
+
+🔑 **NAME-ONLY IS THE LOAD-BEARING VERDICT AND THE ONE AN AGENT WILL AVOID ASSIGNING.** It feels harsh against well-written prose, and PLANNED is always the cheaper answer. **A requirement restated in a warning box, a doc comment, an architecture paragraph, or a Definition-of-Done row is NAME-ONLY unless a task carries out steps.**
+
+### Worked example — the judgement that decides this skill's value
+
+```go
+// assess computes one agent's verdict from the joined snapshot. It decides
+// from PROCESS EVIDENCE — PID pair union session presence — and never from a
+// self-written timestamp. It writes nothing.
+func assess(s *Snapshot, j *Joined, agentID string) Verdict
+```
+
+A correct doc comment restating the spec, a precise signature, and it is **consumed by a task elsewhere in the plan**. It reads as covered.
+
+**Verdict: NAME-ONLY.** There is no body and no task anywhere implements one. That function *was* the reconciler. **The tell is not the quality of the prose — it is that no step produces the thing.**
+
+## Three questions per requirement
+
+1. **Is there a task?** Naming a mechanism is not doing it.
+2. 🔴 **Does the plan contain every step to make it true — INCLUDING CREATING SUBSTRATE THAT DOES NOT EXIST YET?** Open the real struct / table / interface at the plan's authored-against SHA. **A mechanism operating on a substrate that cannot hold the data is a silent no-op.** *Highest-yield question here:* a paired-write primitive was fully and correctly specified while the struct lacked the field and the table lacked the column.
+3. **Would anything FAIL if it regressed?** A property with an implementation but no failing test is not achieved. **A manual grep in a Definition of Done cannot fail next month.**
+
+## Framing — do not get this backwards
+
+🔴 **A gap is a MISSING STEP IN THE PLAN, never a defect in the spec.** The spec is owner-ruled. If a requirement needs a field that does not exist, **the plan must add the field** — that is what plans are for.
+
+**Never report a requirement as "impossible" and never suggest narrowing one.** "Impossible" points the next reader at scoping down the spec, which is the opposite of the repair.
+
+🚫 **The spec is never edited by this skill or its findings.** A finding that appears to require a spec change is an escalation to the owner, never an action.
+
+## Reporting rules
+
+- **Write the report to a FILE first and append as you go.** The final message is a summary; the file is the deliverable. *(Dispatched agents have completed full audits whose final text never reached the parent. The agent does not notice.)*
+- **Record PLANNED items too.** A map that lists only holes cannot show what is safe to build on, and cannot be checked for completeness.
+- **Report what could not be resolved**, naming the search run — never guess. An honest "unresolved" is what makes the PLANNED verdicts worth anything.
+- 🔴 **If a partition returns ALL PLANNED with zero NAME-ONLY, hand-verify two PLANNED rows at random and show the working.** **An all-clear is the result most likely to be produced by not looking.**
+
+## After the sweep — the dispatcher's job
+
+1. **Consolidate into ONE numbered list** across all partitions. Never act on partial batches.
+2. **Filter stale findings** if the plan moved during the sweep — and say so rather than counting them.
+3. **Close every gap before epics are created.** That is the entire point of running it here; a filed-and-deferred gap is the failure this skill exists to prevent.
+4. **Spot-verify any finding that names a file, line, or symbol** before acting. Auditors misread cites, and a correction carries the same evidence bar as the finding it replaces.
+
+## What this does NOT cover
+
+**Compositional defects.** Per-item traversal cannot see *"every phase individually fine, the whole broken."* Measured example: an end state that would run **two concurrent reconcilers**, violating the premise of the design's own no-multi-writer ruling — while every individual requirement was satisfied.
+
+⇒ **Pair this with a compositional pass.** They are different lenses and neither substitutes for the other. **The standard flow wants two audits, not eight.**
+
+## Failure modes of this skill itself
+
+| Failure | Symptom | Guard |
+|---|---|---|
+| Folded into `verify-against-source` as redundant | "we already check coverage" | The traversal direction differs; keep both |
+| Run by the plan's author | Everything PLANNED | Dispatch it |
+| Partitioned by plan section | False ABSENTs | Partition by spec item |
+| Agent avoids NAME-ONLY | Zero NAME-ONLY across a large partition | Mandatory hand-verify of two rows |
+| Findings filed, not fixed | Gaps reach the beads anyway | Close before epics |

package/assets/skills/trace-spec-to-plan/resources/sweep-agent-prompt.md

@@ -0,0 +1,57 @@
+# Sweep agent — shared instructions
+
+> Dispatcher: write this file once, then give each agent ONLY its item list and its report path. Keeps dispatches short and identical.
+> **Model:** sonnet · **Effort:** medium. The verdict call needs judgement; the searching does not.
+
+---
+
+For each assigned spec requirement: is it in the plan, and does the plan actually **plan to implement it** rather than merely name it?
+
+## 🔴 WRITE YOUR REPORT TO YOUR ASSIGNED FILE FIRST, then append as you go
+
+Create it with headings before any analysis. **Your final message is a SUMMARY; the FILE is the deliverable.**
+
+Agents have completed full audits whose final text never reached the parent, and other dispatches left no artifact at all — that work is unrecoverable, and an idle notification is indistinguishable from "did nothing" and "did everything, and it vanished."
+
+## CONSTRAINTS
+
+- READ-ONLY git ONLY: `show`, `log`, `diff`, `grep`, `rev-parse`, `merge-base`, `status`. NEVER `checkout`, `reset`, `restore`, `stash`, `clean`, `rebase`, `commit`, `push` — in ANY directory.
+- Operate ONLY in the worktree named in your dispatch. Write ONLY your report file.
+- `rm -r`, never `rm -rf`. Work synchronously. No background children. Any sub-agent needs explicit `model:` and `effort:`.
+- Read the plan in ~400-line windows. **Search the WHOLE plan for each of your items** — coverage may live in any phase.
+- Verify code claims at the plan's **authored-against SHA** with `git show <sha>:<path>`. **The working tree may be on a different base**; reading it yields wrong line numbers.
+
+## THE VERDICTS
+
+| Verdict | Means |
+|---|---|
+| **PLANNED** | A task exists with concrete steps that would make the requirement true — files named, code or commands shown. |
+| **NAME-ONLY** | The plan mentions, quotes, or asserts it — but no task carries out steps. |
+| **ABSENT** | Not mentioned anywhere. |
+| **PARTIAL** | Part planned, a named part not. Say which. |
+
+🔑 **NAME-ONLY IS THE FINDING THAT MATTERS AND IT IS EASY TO MISS**, because good plans quote their spec often. **Quoting a rule is not implementing it.** A requirement restated in a warning box, a doc comment, an architecture paragraph, or a Definition-of-Done row is **NAME-ONLY unless a task carries out steps.**
+
+**Worked example.** A function declared as a bare signature with a correct doc comment restating the spec, consumed by a task elsewhere — **NAME-ONLY**, because no step produces a body. The tell is not prose quality; it is that nothing produces the thing.
+
+## THREE QUESTIONS PER ITEM
+
+1. **Is there a task?**
+2. 🔴 **Does the plan include every step to make it true — INCLUDING CREATING SUBSTRATE THAT DOES NOT EXIST YET?** Open the real struct/table/interface at the authored-against SHA. **A mechanism over a substrate that cannot hold the data is a SILENT NO-OP.** Weight this heaviest.
+3. **Would anything FAIL if it regressed?** An implementation with no failing test has not achieved the property.
+
+## FRAMING — do not get this backwards
+
+🔴 **A gap is a MISSING STEP IN THE PLAN, never a defect in the spec.** If a requirement needs a field that does not exist, the correct finding is **"the plan is missing a task that adds the field"** — never "impossible", and never a suggestion to narrow the requirement. The spec is owner-ruled and correct; the plan is what is incomplete.
+
+## REPORTING
+
+- **Record PLANNED items too** — the complete map is the deliverable, not just the holes.
+- **Report what you could not resolve**, naming the search you ran. Never guess. Pair any zero with a control showing the search can return something.
+- 🔴 **If ALL your items come back PLANNED with zero NAME-ONLY, hand-verify two PLANNED rows at random and show your working.** An all-clear is the result most likely to be produced by not looking.
+
+## OUTPUT (into your file)
+
+A table: `Item · Spec line · Verdict · Plan task/line · One-line justification`
+Then every NAME-ONLY / ABSENT / PARTIAL with the **concrete missing step**.
+Then COVERAGE: items checked, and anything unresolved.

package/assets/skills/update-queue/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: update-queue
+description: "Use to reconcile your own thrum queue against ground truth - 'update my queue', 'audit my queue', 'my queue is stale', 'reconcile the queue', 'clean up done bundles', or at any session start / lull when you are about to conclude nothing is pending. Verifies each live bundle against git + beads + merge state, drops rot, adds missing committed work. Any role. A repeatable subset of a full multi-agent reconcile - scoped to YOUR queue only."
+---
+
+# Thrum: Update Your Queue (reconcile against ground truth)
+
+Reconcile YOUR OWN `thrum queue` so its status matches reality: drop finished
+rot, verify each live bundle against git + beads + merge state, add committed
+work that is missing. Scoped to your queue only — cross-agent reconciles are a
+larger pass (see the final section). Run it at session start, at a lull, or
+whenever the queue can no longer be trusted at a glance.
+
+Edit only your OWN queue. Handing work to another agent is a message,
+never a write to their queue (see the `using-the-queue` skill).
+
+---
+
+## Step 1 — Snapshot the denominator
+
+```bash
+thrum queue list
+thrum queue list | awk -F'\t' 'NF>1{print $2}' | sort | uniq -c   # status counts
+```
+
+Read the whole list yourself. The status counts are the before-number to
+reconcile against and report the delta from. `-F'\t'` is load-bearing: bundle
+rows are tab-delimited, but `queue list` also prints a space-delimited footer
+(`Oldest bundle updated …`) to stdout — under default whitespace splitting that
+footer's second word lands in the status tally and corrupts the denominator.
+The tab delimiter drops it (footer has no tab ⇒ NF=1).
+
+Two staleness classes to expect:
+
+- **done-rot** — bundles left `done` from prior sessions, never dropped.
+- **zombie live** — bundles marked `in_progress`/`blocked` (or `pending`) whose
+  work has actually landed or been superseded.
+
+`done` is a waypoint, not a resting place — it stays visible and `start`
+reopens it. Only `drop` removes a bundle, and it deletes every item inside.
+
+## Step 2 — Drop done-rot (cheap, no verification)
+
+Every `done` bundle you are not deliberately keeping this session → `drop`.
+Batch it:
+
+```bash
+thrum queue list | awk -F'\t' '$2=="done"{print $1}' | while read id; do
+  thrum queue drop "$id" && echo "dropped: $id"
+done
+```
+
+Keep a done bundle past this step only as a deliberate act (e.g. it may reopen
+on a pending review finding) — never as the default.
+
+## Step 3 — Verify each live bundle against ground truth
+
+For every `in_progress`/`blocked` bundle, and any `pending` you suspect has
+landed, use its lookup key to check reality. The key is the bundle's
+`--ref bead:<id>` and/or a branch/SHA named in its title:
+
+```bash
+thrum queue show <bundle-id>          # read refs + title to get the key
+bd show <bead-id>                     # open vs closed  (NEVER `bd list --all`)
+git merge-base --is-ancestor <sha> origin/<trunk> && echo MERGED || echo NOT-MERGED
+git --no-pager log --oneline --merges origin/<trunk> | grep <branch-or-sha>  # find the merge commit
+```
+
+🔴 **`--is-ancestor` answers "is this SHA reachable", not "is this content
+present".** A squash- or cherry-pick-merged branch is NOT an ancestor yet its
+content is on trunk — for those, `git diff <sha> origin/<trunk> -- <files>`
+(empty ⇒ content landed), never ancestry alone.
+
+🔴 **Run the check so it COULD come back negative.** Point the same
+merge/ancestor check at one bundle you KNOW is still open — it must report
+NOT-MERGED. A verification that cannot fail is not verifying; this control is
+what separated the in-depth audit from a guess.
+
+Classify each bundle from the evidence:
+
+| Evidence | Verdict | Action |
+|---|---|---|
+| Bead closed AND content on trunk | merged | `done` then `drop` |
+| Bead open / branch not landed | still open | keep (`start` if wrongly `done`) |
+| Some work landed, more owed | partial | keep; make its status reflect reality |
+| Work replaced by newer bundle/approach | superseded | `drop` |
+| Committed/dispatched work with NO bundle | missing | add in Step 5 |
+| Evidence unclear | unsure | keep — never drop on a guess |
+
+Two-phase close for a landed bundle (make the state machine explicit):
+
+```bash
+thrum queue done <bundle-id> && thrum queue drop <bundle-id>
+```
+
+## Step 4 — Delegate the cross-referencing when it does not fit in one pass
+
+More than ~6 live bundles to verify → dispatch read-only sub-agents, one slice
+each, rather than checking them inline (see `efficient-multi-agent-research`).
+Consume consolidated verdicts and make every drop/keep/add/start call yourself
+— the sub-agents only gather evidence.
+
+Give each sub-agent:
+
+- its slice of bundles (id + ref + title),
+- the exact recipe from Step 3 (`bd show`, `--is-ancestor` + the content-diff
+  caveat, the discriminating control),
+- the verdict table above as the required return format
+  (`bundle-id → merged | open | partial | superseded | unsure`, with the
+  one-line evidence for each),
+- **READ-ONLY git fence**: `show`, `log`, `diff`, `grep`, `rev-parse`,
+  `merge-base`, `status` ONLY — never `checkout`/`reset`/`restore`/`stash`/
+  `clean`/`rebase`/`commit`/`push`, in any directory; never enter another
+  worktree.
+- pinned `model:` + `effort:` (sonnet, low for mechanical lookups).
+
+## Step 5 — Add missing committed work
+
+Work you have actually committed to that has no bundle is invisible after a
+restart. Add each — branches you own, dispatches you accepted, in-flight epics
+— with its backlog ref:
+
+```bash
+thrum queue add --title "<what>" --ref bead:<id> --priority <N>
+```
+
+## Step 6 — Accept ambiguity, then report
+
+Anything still `unsure` stays. A false negative (keeping stale work) is cheap;
+a false positive (`drop` deletes the bundle and its items) is not — never drop
+on a guess.
+
+Re-run the status counts and report the delta:
+
+```bash
+thrum queue list | awk -F'\t' 'NF>1{print $2}' | sort | uniq -c
+```
+
+One line: dropped N, added M, reclassified K; note anything left deliberately
+unsure for a deeper pass.
+
+---
+
+## What this skill is NOT
+
+This reconciles YOUR queue. A whole-fleet or cross-agent reconcile — auditing
+what every agent is doing, routing orphaned work, re-deriving ownership — is a
+larger, coordinator-scoped pass. This is the routine, repeatable subset you run
+on your own queue to keep it trustworthy between those.

package/assets/skills/using-the-queue/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: using-the-queue
+description: "Use when an agent tracks its own committed work or needs to see who is doing what - keeping a task list of what you are working on, recording work someone assigned you, promoting a backlog bead or issue into active work, lifting an assignment out of a message you received, routing work to another agent, checking what another agent has on its plate, or moving a task through pending / in_progress / blocked / done. Also use when you reach a lull, go idle, or finish a thread and are about to conclude 'nothing pending' - reconcile your committed work against the queue before deciding you are done. Covers the full thrum queue CLI - bundles, embedded items, status, assignment provenance, and reading another agent's queue."
+---
+
+# Using the Thrum Queue
+
+## Overview
+
+`thrum queue` is a per-agent, local-only, daemon-resident list of the work an
+agent has committed to. One queue per `agent_id`; you EDIT your own, anyone may
+READ any queue. It is not beads and not a message inbox - beads is the shared
+backlog of what COULD be done; the queue is the private, short-lived list of
+what an agent IS doing right now, and it is gone when the agent is deleted.
+
+**One rule governs everything else: the queue never crosses agents by itself.**
+You only ever write your OWN queue. Assigning, handing off, and cross-box status
+all travel as MESSAGES; the receiving agent adds the work to its own queue. No
+command writes another agent's queue.
+
+## When to Use
+
+- You need a task list of what you are actively working on.
+- Someone messaged you an assignment and you want it tracked as committed work.
+- You are promoting a backlog item (a bead / thrum-issue) into active work.
+- You are a coordinator/orchestrator routing work and want to record who you
+  handed a bundle to.
+- You need to see what another agent is working on or how loaded it is.
+- You are moving a task between pending / in_progress / blocked / done, or
+  clearing finished work out.
+
+## Mental Model
+
+- **Bundle** = one unit of committed work (the only top-level record). Carries a
+  title, optional backlog `refs`, a status, a priority, and provenance.
+- **Item** = a short checklist entry EMBEDDED inside a bundle. Items are never
+  standalone and never linked across bundles. There is no nesting - a bundle
+  holds items, nothing deeper.
+- **`title` carries the whole content** - there is no body field (40 KB cap).
+- **Local-only**: `.thrum/var/queue/<agent>.jsonl`, projected to SQLite, rebuilt
+  on cold boot, included in `thrum backup`. Never peer-synced.
+
+## Who-is-doing-what (read this if that is your goal)
+
+Three distinct fields, do not conflate them:
+
+- **`assigned_by`** - provenance: which agent assigned this to me. Auto-filled
+  when a bundle/item is created with `--from-message` (from the message author).
+  Answers "who gave me this."
+- **`assigned_to`** - routing metadata I put on MY OWN bundle via
+  `thrum queue assign`. It is informational only. **It does NOT write the
+  named agent's queue and does NOT hand the work off.** Answers "who I intend
+  this for." The actual handoff is a separate `thrum send`; that agent runs
+  `thrum queue add --from-message` to pull it into its own queue.
+- **`thrum queue list --agent <id>` / `show <id> --agent <id>`** - read another
+  agent's queue directly. Answers "what is agent X working on / how loaded is
+  it." Read-only, no permission gate.
+
+## Quick Reference
+
+| Command | Does |
+|---|---|
+| `thrum queue add --title "..."` | Create a bundle in your queue |
+| `thrum queue add --from-message <msg_id>` | Special case: lift ONE specific message you received (content->title, author->assigned_by, refs->refs). Use the exact msg-id you're acting on - never head-1 of the inbox |
+| `thrum queue add --ref bead:<id>` | Promote a backlog item into active work |
+| `thrum queue list [--status <s>] [--agent <id>]` | List your queue (or another agent's) |
+| `thrum queue show <bundle-id> [--agent <id>]` | Full detail for one bundle |
+| `thrum queue start <bundle-id>` | -> in_progress (clears block_reason) |
+| `thrum queue block <bundle-id> [--reason "..."]` | -> blocked (records the reason) |
+| `thrum queue done <bundle-id>` | -> done (TEMPORARY waypoint, not deleted; `start` reopens it; clears block_reason) |
+| `thrum queue drop <bundle-id>` | DELETE bundle + all its items, any status (the one destructive verb - drop promptly once a done bundle's record stops being useful) |
+| `thrum queue assign <bundle-id> <agent-id>...` | Append agent(s) to assigned_to (routing metadata only) |
+| `thrum queue item add <bundle-id> --title "..."` | Add one embedded item |
+| `thrum queue item batch-add <bundle-id> --title "..." --title "..."` | Add several items in one call (shared --ref/--priority) |
+| `thrum queue item start/block/done <bundle-id> <item-id>` | Item-level status (start/done clear the item's block_reason) |
+
+Optional: `--ref <type>:<value>` (repeatable), `--priority N` (higher sorts
+first), and `--from-message` (special case, below). `add` / `item add` require at
+least one of `--title` or `--from-message`; explicit `--title` wins over
+`--from-message`. **`--title` is the normal way to add work.**
+
+## Common Flows
+
+**Add work you're taking on (the normal case):**
+```
+thrum queue add --title "Ship the X migration"
+```
+
+**Promote a backlog bead into active work:**
+```
+thrum queue add --title "Ship the X migration" --ref bead:thrum-abc12 --priority 5
+```
+
+**Lift a SPECIFIC message you received** (special case - mainly an
+orchestrator/agent taking a dispatch it was handed):
+```
+thrum queue add --from-message <msg_id>
+```
+Copies the message's content into the bundle title, its author into
+`assigned_by`, its refs into `refs`, then discards the message ID. 🔴 Pass the
+EXACT id of the assignment you are acting on, matched to its sender - NEVER pipe
+`inbox --unread | head -1`, which grabs whatever is newest (often a monitor
+alert or an unrelated message) and stores it as your title. For anything you
+create yourself, use `--title`.
+
+**Hand work to another agent** (two steps, in this order - there is no one-shot):
+```
+thrum queue assign <bundle-id> @impl_foo      # record intent on YOUR bundle
+thrum send --to @impl_foo --stdin <<'EOF'      # actually route it
+Assigned you <bundle>: <what + refs>. Add it with: thrum queue add --from-message <this msg id>
+EOF
+```
+
+**See what an agent has on its plate:**
+```
+thrum queue list --agent @impl_foo --status in_progress
+```
+
+**Finish vs discard:** `done` is a WAYPOINT, not a resting place - it marks a
+bundle done and KEEPS it visible (`start` reopens it), but it is not where
+finished work should live. `drop` DELETES it and every item inside, regardless
+of status. Reconcile at session start and natural breakpoints: `done` then a
+prompt `drop` is the normal close-out; `drop` alone is fine too. Don't let a
+done bundle outlive your next reconcile unless you deliberately keep it.
+
+**Close on a TRIGGER, not a reminder.** The moment a bundle's branch merges into
+trunk, OR its last referenced bead closes, `done` + `drop` it in that same turn -
+closure is part of the merge/close act, exactly as `add` is part of dispatch. A
+bundle whose branch is an ancestor of trunk, or whose beads are all closed, is
+completed-but-open rot; do not leave it for "later". `add` has a natural trigger
+(dispatch) and gets done reliably; the close has no trigger unless you make the
+merge/close BE the trigger.
+
+**Reconcile is a bounded sweep, not a review.** At session start / breakpoint,
+close only the bundles a check proves done, and skip the rest. Two checks only:
+- branch is an ancestor of trunk (`git merge-base --is-ancestor <tip> origin/<trunk>`) -> `done` + `drop`
+- every `bead:` ref is closed (`bd show <id>`) -> `done` + `drop`
+
+Do NOT read each bundle's full history - the sweep is those two checks against
+merged/closed state, nothing more.
+
+## Common Mistakes
+
+- **Treating `add`/`done` as the work itself.** The queue *tracks* your work; it
+  does not perform it. `add` is not dispatching — the dispatch is the
+  `thrum send` / merge / deploy the bundle *mirrors*. `done` means the tracked
+  work actually landed, not "I'm finished thinking about it." Marking bundles
+  `done` when nothing was dispatched or deployed is a false record, exactly like
+  filing a bead and calling the bug fixed — and it inflates the queue while
+  little actually ships. Verify the thing landed before `done` (branch merged /
+  bead closed / deploy confirmed); otherwise it is still `in_progress` or
+  `blocked`.
+- **Piping a guessed id into `--from-message` (e.g. `inbox --unread | head -1`).**
+  That grabs whatever is newest - often a monitor alert or an unrelated message -
+  and stores it as your bundle title. `--from-message` takes the EXACT id of the
+  assignment you are lifting, matched to its sender; for anything self-created use
+  `--title`.
+- **Expecting `assign` to put work in the other agent's queue.** It does not -
+  it only tags your own bundle. Always follow it with a `thrum send`; the
+  recipient adds it themselves via `--from-message` (with that message's exact id).
+- **Leaving done bundles to pile up.** `done` never removes anything - the
+  bundle stays, and only `drop` deletes it. Drop each done bundle promptly once
+  its record stops being useful; a queue full of undropped done bundles is the
+  primary rot mode.
+- **Reaching for a `remove`/`rename`/item-`drop` verb.** They do not exist by
+  design: removal happens only at the bundle level via `drop`; titles are set at
+  creation and not edited.
+- **Trying to edit another agent's queue.** Impossible by design - you only
+  write your own. Cross-agent work is messaging plus the recipient's own `add`.
+- **Treating the queue as durable/shared history.** It is local, private, and
+  deleted with the agent. Anything that must survive belongs in beads or a
+  committed doc, referenced from the bundle via `--ref`.

package/assets/skills/using-thrum-state/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: using-thrum-state
+description: "Use when reading or writing thrum state - checking your own agent-local current state at session start, updating your status/next-actions, reading a fleet fact like deploy state or topology before acting on it, citing a SHA or box fact in a decision, deciding whether a fleet row is fresh enough to trust, or responding to a freshness-sweep ping. Also use before writing any fleet row - deploy state, topology, worktree, agent pool, or a standing ruling - to confirm you are writing from a by-effect measurement, not a guess. Triggers on: citing a fleet fact, deploying, restarting a daemon, migrating schema, reconciling state at session start, receiving a stale-row ping."
+---
+
+# Using Thrum State
+
+## Overview
+
+`thrum state` is a two-tier current-value store. **Agent-local** state
+(`thrum state set/get/list/show/delete` with an undeclared or `personal_state`
+kind) is your own standing status — reconcile it like your queue, at session
+start and every breakpoint. **Fleet state** (deploy_state, topology,
+worktree, agent_pool, ruling) is different in kind: it describes a fact
+about a DIFFERENT machine that changes elsewhere, with no owner present when
+it goes stale.
+
+**The governing invariant: a fleet row is a timestamped measurement, not a
+current truth.** Every row carries `as_of`/`method`/`established_by` — read
+them before you act.
+
+## When to Use
+
+- Checking your own agent-local current state at session start.
+- Updating your own status/next-actions.
+- Reading a fleet fact (deploy state, topology) before acting on it.
+- Citing a SHA or box fact in a decision.
+- Deciding whether a fleet row is fresh enough to trust.
+- Responding to a freshness-sweep ping.
+- Writing any fleet row (deploy state, topology, worktree, agent pool, or a
+  standing ruling) — confirm you are writing from a by-effect measurement,
+  not a guess, before you do.
+
+## The named rot mode: "the tidied row"
+
+A normalized or guessed value that reads byte-identically to a measured
+one. This is how a coordinator acts on a confidently-wrong SHA. The
+corrected intuition: **`as_of` is a measurement time, not a last-edit
+time** — writing a fleet row without a fresh by-effect check, even to
+"fix" a value you believe is stale, is exactly this failure.
+
+## Reconcile, don't just read
+
+- **Agent-local** (all roles): check at session start
+  (`thrum state list`), update as you go. Carried-over state is NOT
+  auto-injected into prime — you must ask.
+- **Fleet** (coordinators write; everyone reads): before citing a fleet
+  fact in a decision, check `as_of`/`method`. Past the kind's threshold
+  (`thrum state describe <kind>`)? Re-verify by effect before acting, or
+  say explicitly that you're acting on a stale value and why that's
+  acceptable this once.
+
+**Unmeasured ≠ measured-negative.** An absent row does not mean "at tip" or
+"clean" — it means nobody has measured it. Do not read absence as a
+negative result.
+
+## Quick Reference
+
+| Command | Effect |
+|---|---|
+| `thrum state set --kind <k> --scope <s> --value '<json>'` | Upsert (create or overwrite) |
+| `thrum state get <kind>:<scope>` | Read one entry |
+| `thrum state list [--kind <k>] [--agent <id>]` | List entries |
+| `thrum state show <kind>:<scope>` | Full metadata for one entry |
+| `thrum state delete <kind>:<scope>` | Remove outright (fleet: tombstones) |
+| `thrum state describe <kind>` | Dump a declared kind's field shape + threshold |
+| `thrum state history <kind>:<scope>` | Append-only write history (recovers LWW losers) |
+
+`--method by_effect` when you measured it directly; `--method asserted`
+when you're stating it without a live check; a write relayed from a message
+is forced to `--method relayed` (low-trust) — never choose `relayed`
+yourself.
+
+## Common Flows
+
+**Deploy runbook, after verifying a box's serving SHA:**
+
+```bash
+thrum state set --kind deploy_state --scope box-a \
+  --value '{"serving_sha":"<sha>","schema":77}' --method by_effect
+```
+
+**Session-start reconcile (agent-local):**
+
+```bash
+thrum state list
+# update anything stale; nothing auto-loads, so do this every session
+```
+
+**Responding to a freshness-sweep ping:** re-verify the named row by
+effect, then `thrum state set` with the fresh value and `--method
+by_effect`. Never "correct" a row you have not personally re-measured.
+
+## Common Mistakes
+
+- **Normalising the deploy table to one SHA "because that's probably
+  right."** This is the tidied-row catastrophe. Re-verify by effect or
+  leave it stale-flagged.
+- Writing the same fact to both agent-local AND fleet state (coordinators
+  especially — see the coordinator preamble's anti-double-add rule).
+- Choosing `--method relayed` yourself instead of letting a message-relay
+  path force it.
+- Treating an absent fleet row as a negative result instead of "nobody has
+  measured this."