opencode-thrum-pro 0.1.5 → 0.1.7

package/assets/skills/thrum/resources/MESSAGING.md

@@ -9,8 +9,11 @@
 3. **Receive** — `thrum inbox` or `thrum wait` (blocking)
 4. **Verify sent state** — `thrum sent` or `thrum message get <msg-id>`
 5. **Read** — Auto-marked read when displayed via `thrum inbox`; use
-   `thrum inbox --unread` to peek without marking. Explicit:
-   `thrum message read --all`
+   `thrum inbox --unread` to peek without marking. Explicit: `thrum message
+   read <id> [<id>...]`, or `thrum message read --all` (DRY RUN — lists
+   candidates, marks nothing) then `--apply` (marks the shown/seen ones) or
+   `--force` (marks ALL unread, seen or not; needs a fresh `--all` dry run
+   first).
 6. **Search — do not page through the inbox to find old messages.** The
    default page is 10, newest-first, so stale unread sorts LAST exactly when
    it has waited longest. Use `thrum message search "<term>"` (full-text,
@@ -22,15 +25,19 @@
 
 ## Addressing
 
-| Target              | Routing                                                       | When to use                          |
-| ------------------- | ------------------------------------------------------------- | ------------------------------------ |
-| `--to @lead_agent`  | **Direct** — routes to the named agent                        | Default for all task messages        |
-| `--to @coordinator` | **Role fanout** — ALL agents with that role (warning emitted) | Only when you want every coordinator |
-| `--to @everyone`    | **Broadcast** — all registered agents                         | Critical alerts                      |
-
-**Critical:** `@coordinator` is a role, not an agent name. Sending
-`--to @coordinator` fans out to every agent registered with that role. Use
-`thrum team` to find agent names, then send `--to @<name>` for direct messages.
+| Target                        | Routing                                          | When to use                     |
+| ------------------------------ | ------------------------------------------------- | -------------------------------- |
+| `--to @lead_agent`             | **Direct** — routes to the named agent            | Default for all task messages   |
+| `--to @agent_a --to @agent_b`  | **Explicit multi-recipient** — repeatable `--to`  | Several specific named agents   |
+
+**(P0 ruling):** one-to-many fan-out — `--broadcast`,
+`@everyone`, and role-based mentions/groups (e.g. `--to @coordinator` fanning
+out to every agent with that role) — was removed by design across the whole
+product. Do not restore it. `--to` and `--mention` only resolve exact agent
+IDs now; a bare role name that is not also an agent ID matches nobody. Use
+`thrum team` to find agent names, then send `--to @<name>` for direct
+messages, or address a scoped agent-type group for a fixed, explicit set of
+recipients.
 
 - **Reply:** `thrum reply <msg-id>` — same audience as original; takes **no
   `--to`** (recipient derived from the message)

package/assets/skills/thrum/resources/WORKTREES.md

@@ -86,7 +86,7 @@ thrum sent     # Verifies what this worktree sent and who read it
 thrum reply <msg-id> --stdin <<'EOF'
 Integration tests passing, ready to merge
 EOF
-thrum message read --all  # Mark all messages as read
+thrum message read --all --force  # Mark ALL unread as read (run `read --all` alone first — dry run)
 ```
 
 ## File Coordination

package/assets/skills/thrum-memory/SKILL.md

@@ -59,7 +59,7 @@ thrum memory search --tag substrate --kind arch_decision
 Show a single memory by ID:
 
 ```bash
-thrum memory show thrum-mem-01HQXZP3V8K2N7M0YJWQ8R5T6F
+thrum memory show thrum-mem-01EXAMPLE00000000000000000
 ```
 
 Edit a single field (other zoom levels stay intact; only changed-zoom embeddings

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

@@ -1,7 +1,7 @@
 # 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.
+> **Model and effort:** per `choosing-subagent-models`. The verdict call needs judgement; the searching does not.
 
 ---
 

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

@@ -20,15 +20,13 @@ never a write to their queue (see the `using-the-queue` skill).
 
 ```bash
 thrum queue list
-thrum queue list | awk -F'\t' 'NF>1{print $2}' | sort | uniq -c   # status counts
+thrum queue list --json | jq -r '.bundles[].status' | 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).
+reconcile against and report the delta from. Use `--json` for the tally, not
+the text table: the JSON machine surface (`{"bundles": [...]}`) is a stable
+contract, while the text table's column layout and footer line are not.
 
 Two staleness classes to expect:
 
@@ -112,7 +110,7 @@ Give each sub-agent:
   `merge-base`, `status` ONLY — never `checkout`/`reset`/`restore`/`stash`/
   `clean`/`rebase`/`commit`/`push`, in any directory; never enter another
   worktree.
-- pinned `model:` (sonnet; intended tier is low for mechanical lookups — the
+- pinned `model:` (per `choosing-subagent-models`; a cheap tier for mechanical lookups — the
   Agent tool takes no `effort`, so carry the tier via the agent definition or
   the tmux launch flags).
 
@@ -135,7 +133,7 @@ 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
+thrum queue list --json | jq -r '.bundles[].status' | sort | uniq -c
 ```
 
 One line: dropped N, added M, reclassified K; note anything left deliberately

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

@@ -126,6 +126,36 @@ resubmit — do not recompute the whole board inside one invocation.
 - HTML files: no script/style/iframe/event-handlers — the render side strips
   them, but author clean anyway.
 
+## Widget schema
+
+```json
+{"title": "<board title>", "widgets": [
+  {"id": "hdr",  "type": "stat-row", "stats": [{"label": "<label>", "value": "<value>"}]},
+  {"id": "rows", "type": "list",     "title": "<list title>", "rows": [{"id": "r0", "text": "<one-line markdown>"}]},
+  {"id": "note", "type": "card",     "title": "<card title>", "body": "<markdown>"},
+  {"id": "grp",  "type": "section",  "label": "<section label>"}
+]}
+```
+
+- `stat-row` takes `stats`, `list` takes `rows` (each row has its own `id`), `card` takes
+  `title` + `body`, `section` takes `label`. Widget `id`s are the upsert key — keep them stable.
+- Write the document to a file; `thrum dashboard set --doc-file <f>`. Pass `--replace` when one
+  generator owns the whole board.
+- Regenerate the board from a script that prints one summary line, run from the agent's own
+  session. A daemon-spawned monitor process is an unauthenticated caller (identity is
+  kernel-verified per process) and cannot write the board, whatever environment it carries, so
+  schedule the monitor as a reminder (`--schedule`, `--match`, `--notify-on-success`) and run
+  the generator when the reminder arrives. The cron schedule is evaluated in the daemon's local
+  time zone, not UTC.
+
+## The board is for the human reader, not an audit trail
+
+- Show what the reader needs to decide or know; filter out coordinator mechanics.
+- A "landed since deploy" list shows feature/fix branch landings only — no trunk-sync merges,
+  pull merges, or artifact commits.
+- An "orchestrators" view shows each orchestrator's open work, not liveness.
+- When the owner asks for a change, change the generator, not the snapshot.
+
 ## When to reach for the dashboard (vs a nudge vs a message)
 
 - **Dashboard:** state the human will consume VISUALLY and possibly answer

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

@@ -63,22 +63,46 @@ Three distinct fields, do not conflate them:
 | `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 list [--status <s>] [--stage <s>] [--agent <id>]` | List your queue (or another agent's); `--status`/`--stage` AND-combine when both given |
 | `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 block <bundle-id> [--reason "..."]` | -> blocked (records the reason; `--reason` required) |
 | `thrum queue done <bundle-id>` | -> done (TEMPORARY waypoint, not deleted; `start` reopens it; clears block_reason) |
+| `thrum queue wait <bundle-id> [--reason "..."]` | -> waiting (alias for `queue update --status=waiting`; `--reason` optional) |
+| `thrum queue ready <bundle-id>` | -> ready (alias for `queue update --status=ready`) |
+| `thrum queue update <bundle-id> [flags]` | General partial update: `--status`, `--stage`, `--reason` (status_reason), `--title`, `--ref` (repeatable, replaces existing refs), `--priority`, `--assigned-by`, `--assigned-to-remove` - at least one required; `--status=blocked` requires `--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 note <bundle-id> --stdin` (or `--body-file <f>`) | Append a dated progress note (append-only; shown by `show`, last note previewed by `list`) |
 | `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) |
+| `thrum queue item update <bundle-id> <item-id> [flags]` | Partial item update: `--title`, `--assigned-by`, `--ref` (repeatable, replaces existing refs), `--priority` - at least one required |
 
 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.**
 
+### Status and stage: two independent axes
+
+A bundle carries two orthogonal fields, both settable via `queue update`:
+
+- **`status`** - `pending`, `in_progress`, `waiting`, `ready`, `blocked`,
+  `done`. Says whether the owning agent can or must act now. `start` / `block`
+  / `done` / `wait` / `ready` are all just `queue update --status=<x>` under a
+  short name; `wait` and `ready` are exact aliases with no independent
+  behavior of their own.
+- **`stage`** - `intake`, `planning`, `dispatched`, `implementation`,
+  `integration`, `review`, `rework`, `gate`, `merge`, `deploy`,
+  `verification`, `cleanup`. Says where the bundle sits in its workflow,
+  independent of status. Optional; never set on items, bundle-only. Set/read
+  via `queue update --stage <s>` / `queue list --stage <s>` / `queue show`.
+
+`status_reason` (set via `--reason` on `update`/`block`/`wait`) is the
+general reason field; `--status=blocked` requires it, `wait` accepts it
+optionally, other transitions clear it.
+
 ## Common Flows
 
 **Add work you're taking on (the normal case):**
@@ -139,6 +163,50 @@ close only the bundles a check proves done, and skip the rest. Two checks only:
 Do NOT read each bundle's full history - the sweep is those two checks against
 merged/closed state, nothing more.
 
+## Identity-field mutation: queue vs. state (two intentional shapes)
+
+`queue update` / `queue item update` and `state set` handle identity-field
+mutation differently. This is an intentional two-shape convention chosen per
+domain, not an inconsistency - do not "fix" one to match the other.
+
+**`queue.update` / `queue.item.update`**: wrapped by `RejectIdentityKeysHandler`,
+which returns a typed `*queue.ErrImmutableField` error (`queue: cannot modify
+immutable field %q`) if a raw identity key (`id`, `agent_id`, `created_at` for
+bundles; `id`, `created_at` for items) appears in the wire payload at all -
+checked BEFORE decode, fail-closed. Note: `QueueUpdateRequest`/
+`QueueItemUpdateRequest` have no JSON fields for these identity keys anyway,
+so this wrapper is defense-in-depth, not load-bearing on its own.
+
+**`state.set`**: no reject path at all, and that is by design, per field:
+- **Kind/Scope** are the addressing key - a different `(Kind,Scope)` pair
+  addresses a DIFFERENT record, so setting them isn't a mutation attempt and
+  there's nothing to reject.
+- **Class** is derived server-side from the kind registry; no wire field
+  exists for a caller to even attempt to set it.
+- **CreatedAt** is server-stamped once at creation (on the fleet tier it's
+  actually derived from `UpdatedAt` at read time rather than stored
+  independently); not client-spoofable, and `StateSetRequest` has no field to
+  smuggle it through.
+- **EstablishedBy** is influenceable only via `CallerAgentID` on a
+  non-peercred transport (browser/WS, unit tests) - but that is a general,
+  already-documented property of the RPC layer (identity trust depends on
+  transport), not something unique to `state.set`, and it is explicitly out
+  of scope per `docs/security_model/master.md` §1.5: "Thrum does not attempt
+  to prevent agent identity forgery" is an owner ruling, stated as
+  [INTENDED] and permanent, not tracked as debt.
+
+**The convention, stated plainly:** queue rejects raw identity keys at the
+wire as defense-in-depth (even though its request types don't have those
+fields anyway); state has no reject path because its identity/system-derived
+fields are either addressing semantics (not a mutation) or server-derived/
+unspoofable (nothing to reject). Two different but each internally-consistent
+shapes, chosen by domain, not an oversight.
+
+Non-goal: fail-closed reject-symmetry for `state.set` (mirroring queue's
+`RejectIdentityKeysHandler`) is a possible future non-security hardening
+preference, not built here - out of scope per `docs/security_model/master.md`
+§1.5.
+
 ## Common Mistakes
 
 - **Treating `add`/`done` as the work itself.** The queue *tracks* your work; it
@@ -162,9 +230,12 @@ merged/closed state, nothing more.
   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.
+- **Reaching for a `remove`/item-`drop` verb.** Removal (of a bundle and every
+  item inside it) happens only at the bundle level via `drop` - there is no
+  finer-grained delete. Renaming/re-titling is NOT in this category: `queue
+  update --title` and `queue item update --title` are the supported post-create
+  edit path for a bundle's or item's title (and other fields - stage, refs,
+  priority, assigned-by).
 - **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

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

@@ -42,8 +42,8 @@ time** — writing a fleet row without a fresh by-effect check, even to
 ## 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.
+  (`thrum state list`), update as you go. Prime injects only a capped digest
+  of agent-local state; `thrum state list` shows all.
 - **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
@@ -71,6 +71,48 @@ 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.
 
+## Field Mutability Matrix
+
+`Entry` (`internal/state/types.go`) has five mutability classes, not one
+uniform "immutable field" guard:
+
+- **immutable-identity** — part of the `(Kind, Scope)` addressing key, or
+  fixed at creation with no update path. "Changing" one of these isn't an
+  edit, it addresses a different record.
+- **mutable-whole-object** — caller-settable via `state set`, which is
+  always a full upsert (overwrite), never a field-level PATCH. Need a
+  partial update? GET, edit client-side, SET the full value back.
+- **mutable** — caller-settable via specific `state set` flags,
+  independent of Value.
+- **system-derived** — recomputed server-side from non-caller input
+  (registry declaration, resolved caller identity); any caller-supplied
+  value for these is ignored, not merely defaulted.
+- **derived** — set only as an automatic side effect of a `state set`
+  call, never independently caller-directed.
+
+| Field | Class | How it's set/changed | Notes |
+|---|---|---|---|
+| `Kind` | immutable-identity | Parsed from the CLI/RPC target at call time | Part of the addressing key; a new `Kind` is a new record, not an edit. |
+| `Scope` | immutable-identity | Parsed from the CLI/RPC target at call time | Same addressing-key reasoning as `Kind`. No error on "change" — it creates an independent entry (`TestStateHandler_HandleSet_DifferentScope_CreatesIndependentEntry`). |
+| `Value` | mutable-whole-object | `state set --value` | Every `state set` is a full upsert; no field-level PATCH RPC/CLI surface exists. |
+| `AsOf` | mutable (fleet only) | `state set --as-of` | Server only checks that it *parses* as a timestamp; nothing compares it against the previous stored `AsOf` or rejects a bump with no real change — a documented, deliberately unenforced soft-gap. |
+| `Method` | mutable (fleet only) | `state set --method` | Forced to `relayed` server-side whenever the request carries `FromMessage`, overriding any caller-claimed value. Outside that one rule, a caller-supplied `Method` is accepted as-is with no check that it reflects how the value was actually established. |
+| `VerifyCmd` | mutable (fleet only) | `state set --verify-cmd` | Plain caller-settable field. |
+| `FreshnessOwner` | mutable (fleet only) | `state set --freshness-owner` | Plain caller-settable field. |
+| `OriginDaemon` | system-derived | Stamped by sync/durable-lane plumbing | Exact assignment site outside `internal/state` is unconfirmed; not caller-settable via `state set`. |
+| `Class` | system-derived, immutable-per-caller | Declared per-`Kind` in the code registry (`registry.go` `KindDef.Class`), stamped server-side on every write | `StateSetRequest` has no `class` wire field at all — a raw request that smuggles an unrecognized `class` key is silently dropped, not rejected (`TestStateHandler_HandleSet_ClassFieldOnWireIsSilentlyDropped`). Changes only if the registry declaration itself changes. |
+| `EstablishedBy` | system-derived, immutable-per-caller | Re-resolved from the caller's identity on every write (`resolveCallerAgent` / `guard.DaemonResolve`), fleet tier only | No dedicated wire field to set directly — only `CallerAgentID`, fed through identity resolution, can influence it. On peercred transports the claim is verified against kernel evidence; on non-peercred transports (browser/WS, unit tests) an unverified claim is accepted verbatim. Local tier never populates this field (always `""`). |
+| `CreatedAt` | immutable-identity (local tier only) | Stamped once at first insert | Local tier: preserved across updates by the store's rewrite path (`local_store.go` `Set`), not validated/rejected — it's simply never reassigned. Fleet tier: **not** independently preserved — there's no separate `created_at` column, so `fleet_store.go`'s `toEntry()` derives it from `UpdatedAt` on every read; do not assume local/fleet parity here. |
+| `UpdatedAt` | derived | Automatic side effect of every `state set` | Never independently caller-directed. |
+
+None of this is a uniform "reject the write" guard (that mechanism —
+`RejectIdentityKeysHandler` / `ErrImmutableField` — belongs to `thrum queue`,
+a different subsystem, not state). State's actual enforcement is a mix:
+addressing semantics for the identity fields (no error, just a different
+record), silent wire-level drop for `Class`/`EstablishedBy` (no field to
+send them on), and preserve-on-rewrite for local-tier `CreatedAt` (no
+validation, just never overwritten).
+
 ## Common Flows
 
 **Deploy runbook, after verifying a box's serving SHA:**
@@ -91,6 +133,47 @@ thrum state list
 effect, then `thrum state set` with the fresh value and `--method
 by_effect`. Never "correct" a row you have not personally re-measured.
 
+## Consolidating your agent-harness memories into state (durable overflow)
+
+Your **agent-harness memories** — the memory index your runtime auto-loads at
+session start (each runtime has its own: a `MEMORY.md`-style index on some,
+an equivalent auto-injected file on Codex/Cursor/Copilot/others) — has a **load
+size cap**. Past that cap the runtime **silently drops the tail entries** at
+wake: they are invisible exactly when you most need them. Thrum state is an
+uncapped, queryable durable store, so it is the right overflow home.
+
+**Technique (scope-preserving — the only safe way to shrink the index):**
+
+1. **Classify, don't cut.** For each auto-loaded entry ask: *if this were
+   absent at wake, would I take a WRONG action, or merely a SLOWER one?*
+   WRONG-if-absent (destructive-op guards, owner rulings, disbelieve-the-
+   instrument traps, habits that must interrupt a confident wrong answer) STAY
+   in the auto-loaded index. SLOWER-if-absent (things you would just look up
+   once you know the topic exists) are demotable.
+2. **Demote by MOVING, never by shortening.** Relocate each demotable entry
+   **verbatim** into a thrum state entry (e.g. `thrum state set --kind
+   reference --scope <agent>_discipline_index`) and/or your runtime's secondary
+   lookup file. Leave a short **bidirectional pointer**: the auto-loaded index
+   keeps a one-line pointer to the state entry; the state entry names the topic
+   file the full detail lives in. **Never merge two entries, summarise to save
+   bytes, or delete** — summarising discards the SCOPE that makes an entry true,
+   which is the whole failure this guards against. The per-topic detail files
+   are never touched.
+3. **Reduction comes only from relocation.** Prove conservation:
+   `entries_removed_from_index == entries_added_to_state` (set equality, not
+   just count). Target comfortably under the load cap; do not chase a smaller
+   number by demoting genuine must-fire entries.
+4. **Use a high-reasoning subagent to index both stores** and PROPOSE the moves
+   (it produces the new index, the state value, and a verification checklist);
+   you review the judgment calls (which must-fire entries to keep) and apply.
+   Watch for **line-packing collateral**: if two entries share one physical
+   line, demoting one must not drag its line-mate out with it.
+5. **Refuse the size-nag hook.** A `PostToolUse` hook may fire after an index
+   edit demanding "compact / merge or drop stale entries." Merge and drop are
+   forbidden by this contract; the sanctioned action is verbatim relocation,
+   which you have already done. Being under the load cap is the goal, not the
+   hook's smaller aspirational number.
+
 ## Common Mistakes
 
 - **Normalising the deploy table to one SHA "because that's probably

package/assets/skills/verify-against-plan/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: verify-against-plan
-description: "Use after implementation is complete to verify the code covers every requirement from the plan / design spec - runs alongside code-review as the second pass in the Code Review Protocol. Outputs structured findings - missing scope, unmet acceptance criteria, silent deviations from the spec, newly-introduced surprises."
+description: "Use after implementation is complete to verify the code covers every requirement from the plan / design spec - runs alongside code-review as the second pass in the Code Review Protocol. Takes an optional design= input so requirements that only the design doc states are checked too. Outputs structured findings - missing scope, unmet acceptance criteria, silent deviations from the spec, newly-introduced surprises."
 ---
 
 # Verify Against Plan
 
 ## Inputs
 
-Two inputs are required. Missing either is a pre-flight bail.
+Two inputs are required and one is optional. Missing a required input is a
+pre-flight bail.
 
 ### 1. Plan or spec path (required)
 
@@ -29,6 +30,17 @@ file-structure and acceptance-criteria anchors the skill compares against.
 - **Worktree path** — infer the branch and diff from the worktree's current
   state. E.g. `<workspace>/thrum/plugin-skills-slate`.
 
+### 3. Design doc path (optional): `design=<path>`
+
+A markdown design doc or spec the implementation must also honour. The plan
+stays the authoritative anchor; the design is a second source of requirements.
+Omit it and the skill behaves exactly as before (plan only). When supplied, the
+skill also runs the **Design-doc pass** below.
+
+Pass it when the plan implements all or part of a design: `design=<absolute path
+to the design spec>`. A path that is missing, empty or unreadable is a
+pre-flight bail (check 1b), never a silent skip.
+
 ### Context-inferred defaults
 
 When the caller supplies no explicit scope, infer:
@@ -45,6 +57,12 @@ When the caller supplies no explicit scope, infer:
 /verify-against-plan plan=dev-docs/plans/YYYY-MM-DD-topic-plan.md branch=feat/plugin-skills-slate
 ```
 
+**With a design doc (requirements only the design states are checked too):**
+
+```text
+/verify-against-plan plan=<plan file> design=<design file> branch=feat/plugin-skills-slate
+```
+
 **Context-inferred (from current worktree):**
 
 ```text
@@ -62,6 +80,11 @@ clear error — do not proceed with partial inputs.
    file is non-empty markdown. Error message on failure names the path and the
    issue (missing / empty / unreadable).
 
+   1b. **Design doc exists and is readable (only when `design=` is supplied).**
+   Same shape as check 1: the path resolves and the file is non-empty markdown,
+   and the error names the path and the issue. Unlike the plan, a design doc is
+   not required to have a File Structure table or an Acceptance section.
+
 2. **Implementation scope resolves to a non-empty diff.** For branch or
    commit-range inputs, `git diff` must produce at least one changed file. An
    empty diff means either the branch is at merge-base or the range is
@@ -81,7 +104,7 @@ clear error — do not proceed with partial inputs.
    Regex: `^\*\*Authored-against:\*\* \`([0-9a-f]+)\` target: \`([^\`]+)\``
    (sha → capture group 1, merge_target → capture group 2)
 
-   (Canonical stamp definition: `claude-plugin/commands/_stamp-protocol.md`. The
+   (Canonical stamp definition: the /thrum:stamp-protocol skill. The
    stamp follows the same literal `grep -F` / fixed-field-order / case-sensitive /
    ASCII-only convention as the `THRUM-REVIEW` marker — see
    `coordinator-running-brainstorm-cycles` skill § "Footer → commit → stamp".)
@@ -135,7 +158,7 @@ clear error — do not proceed with partial inputs.
    present" outcome above, since this check only needs the stamp's
    `<sha>`/`<merge_target>`, not the plan's cited-files list. Run the
    ordered, short-circuiting two-check sequence defined canonically in
-   `_stamp-protocol.md` § "Read-time provenance re-derivation" (SHA-resolves
+   `stamp-protocol.md` § "Read-time provenance re-derivation" (SHA-resolves
    first, then merge-status) against the stamp's `<sha>`/`<merge_target>` —
    the exact commands live there as the single source of truth; this section
    states outcomes and severity only:
@@ -160,10 +183,98 @@ clear error — do not proceed with partial inputs.
    that the callee package was actually searched and the cost formula uses
    realistic production scale, not a test-fixture number.
 
-Only when checks 1–3 pass should the comparison pass begin. Checks 4, 5, and 6
+Only when checks 1–3 (and 1b, when `design=` is supplied) pass should the
+comparison pass begin. Checks 4, 5, and 6
 run alongside and contribute findings; a missing stamp never blocks, and check 6
 only fires when the diff actually touches a hot root.
 
+## Design-doc pass (only when `design=` is supplied)
+
+Runs after the plan comparison and reports on the same scale. It exists because
+a design doc can carry a requirement that no plan task mentions, and a plan-only
+review can never see that gap.
+
+**1. Extract requirements, mechanically.** Enumerate in DOCUMENT ORDER and number
+them R1..Rn, recording `<design file>:<line>` and the verbatim quote for each.
+Nothing is extracted by judgment; exactly these rules apply:
+
+- **Section items.** Under any heading whose title contains (case-insensitive)
+  `requirement`, `acceptance`, `success criteria`, `invariant`, `constraint`,
+  `non-goal` or `out of scope`, EVERY bullet, numbered item or table row is one
+  requirement. The section runs until the next heading of the same or a higher
+  level. A nested sub-bullet is its own requirement only if it carries its own
+  MUST/SHALL; otherwise it belongs to its parent item.
+- **Standalone MUST sentences.** Outside those sections, every sentence that
+  contains `MUST`, `MUST NOT`, `SHALL` or `SHALL NOT` in capitals is one
+  requirement.
+- **Non-goals.** Items under `non-goal` / `out of scope` headings are NEGATIVE
+  requirements: the diff must not implement them.
+- **Skipped, exactly:** everything else — background, motivation, alternatives
+  considered, open questions, examples, and lowercase "must"/"shall"/"should"
+  prose.
+
+If the design has no extracted requirement, say so in one informational line
+("design supplied but no extractable requirements") and continue plan-only;
+never report that as design coverage. Let N be the number extracted.
+
+**2. Scope them, mechanically.** A requirement Rk is CHECKED if and only if
+EITHER of these holds; otherwise it is OUTSIDE:
+
+- **(a) Name match.** Build the set of names from (i) every path segment and
+  backticked token in the plan's File Structure table and (ii) every path
+  segment of the diff's changed paths and every identifier on its added or
+  removed lines. Drop generic names (`internal`, `src`, `cmd`, `pkg`, `lib`,
+  `docs`, `test`, `tests`, `main`, `index`, `util`, `utils`, `common`) and names
+  shorter than 4 characters. Rk is CHECKED when its text contains any remaining
+  name as a whole word, case-insensitively (`export` matches `export/handler.go`;
+  it does not match `exports`).
+- **(b) Cited heading.** Rk sits under a design heading whose exact title also
+  appears verbatim in the plan.
+
+Requirements that are OUTSIDE are never flagged; they are counted so silence
+cannot pass for coverage, and C + O must equal N:
+
+```text
+**Design scope:** <N> extracted: <C> checked, <O> outside this plan's scope, not checked
+```
+
+A checked Rk that the plan explicitly defers or excludes is not a finding; cite
+the plan's exclusion instead.
+
+**3. Compare.** Each checked Rk is MET, ABSENT or DEVIATED against the diff and
+the branch-HEAD code (a requirement already satisfied by unchanged code is MET;
+cite where). An Rk that a plan item also covers is reported once, under the plan
+finding.
+
+**4. Report.** Same four fields and the same BLOCKING / IMPORTANT / MINOR
+buckets; the first field is labelled `Design reference` instead of
+`Plan reference`, so consolidation is unchanged:
+
+```markdown
+### BLOCKING #2 — <short descriptor>
+
+- **Design reference:** <design file>:<line> — "<verbatim requirement>"
+- **Implementation state:** <code path>:<line> or "absent"
+- **Why it matters:** <the design requirement or invariant this ties back to>
+- **Suggested resolution:** <add the missing code, or flag the design/plan gap for the coordinator>
+```
+
+Severity: an unmet MUST, acceptance criterion or stated invariant is BLOCKING; a
+silent deviation (different name, shape or behavior) or a violated non-goal is
+IMPORTANT; a documentation or reference gap is MINOR.
+
+**Example.** Design line 9 reads "The export endpoint MUST reject request bodies
+over 1 MiB with HTTP 413." The plan lists only the audit-log task and its File
+Structure names `export/handler.go` and `audit/audit.go`; the diff adds only
+audit logging. Plan-only, nothing is flagged. With `design=`, that requirement is
+extracted (it sits under a Requirements heading), CHECKED by name match (`export`
+is a name from the File Structure and the diff), ABSENT from the code, and
+reported as a BLOCKING finding quoting design line 9 with implementation state
+`absent`. A second requirement in the same design, "The billing service MUST
+retry failed charges three times", contains no name from the plan or the diff, so
+it is OUTSIDE: counted in the `Design scope` line, never flagged, even though it
+is a MUST that the diff does not implement.
+
 ## Output format
 
 Findings go to stdout in this exact shape so the coordinator can consolidate the
@@ -173,6 +284,8 @@ dual-review batch without reformatting.
 ## Verify-Against-Plan Findings
 
 **Plan:** <path> **Implementation:** <branch> (<N> commits, <M> files changed)
+**Design:** <path> (only when design= was supplied)
+**Design scope:** <N> extracted: <C> checked, <O> outside this plan's scope, not checked (only when design= was supplied)
 **Summary:** <N> BLOCKING, <N> IMPORTANT, <N> MINOR
 
 ---
@@ -303,7 +416,8 @@ not insubordination.
 
 ## Scope discipline
 
-This skill has ONE job: does the code match what the plan said it would do?
+This skill has ONE job: does the code match what the plan (and the design doc,
+when `design=` is supplied) said it would do?
 
 It does NOT:
 
@@ -316,7 +430,8 @@ It does NOT:
   branch.
 - **Review the plan itself** — pre-implementation plan review is handled by
   `superpowers:writing-plans` (built-in reviewer). If the plan is wrong, that's
-  a separate workflow.
+  a separate workflow. The same holds for the design doc: it is a source to
+  check the code against, not something this skill critiques.
 
 If a finding would belong in any of the above categories, omit it from
 verify-against-plan output. Coordinator will pick up quality / security /

package/assets/skills/watcher-archetype/SKILL.md

@@ -82,3 +82,21 @@ lives in the domain's scanner, never in agent prose.
 The watcher's config lives at `.thrum/agents/<id>/` at the repo root
 (resolve via `.thrum/redirect` from a worktree) — see the role preamble for
 the per-wake read. It runs as a `scheduled_agent` job.
+
+## Escalation
+
+### 🔴 HUMAN-NEEDED escalation goes to the owner by message, never pane-only
+
+When you need a human decision, resolve the owner from CONFIG — never hardcode
+a name — and deliver it as a message, not pane text:
+
+    OWNER=$(jq -r '.permission_supervisors[] | select(startswith("@user:"))' .thrum/config.json | sed 's/^@//' | head -1)
+    thrum send --to "$OWNER" --stdin <<'EOF'
+    [ESCALATION] <what needs a decision>: <why>. Action needed: <what>.
+    EOF
+
+Writing the escalation only into your own pane is not delivery — nobody reads
+watcher panes. If you get no response within 15 minutes, resend and verify
+delivery (`thrum sent --unread`) before assuming it was seen. SAFE recognized
+modals stay approver-of-record and are approved directly, unchanged — this
+rule applies only to escalations that need a human decision.

package/assets/skills/writing-durable-markdown/SKILL.md

@@ -58,6 +58,11 @@ shorten data.
 No issue IDs, no dates, no agent names, no measurements in customer-facing files.
 The tracker references the change; the change never references the tracker.
 
+## A directive has no author and no history
+
+State the rule; never name who ruled it. Never show a before-and-after — the
+previous wording is deleted, not exhibited.
+
 ## A skill is generic — never specific to the repo you edit from
 
 Write the rule so it holds for any repo running the skill. No repo names, config