opencode-thrum-pro 0.1.5 → 0.1.6

package/assets/skills/coordinator-assessing-agent-completion/SKILL.md

@@ -19,6 +19,30 @@ Apply the gate and containment checks below and reach your own
 conclusion. Destructive steps still follow the standing reap preconditions and
 pacing rules; nothing here shortcuts them.
 
+## Standing reap preconditions — ALL must hold
+
+Reaping an agent (removing its worktree) is safe only when every one of these is
+true. It is a gate, not a checklist to rationalize past:
+
+1. **Idle > 48h** — no activity in its transcript for more than two days (rank by
+   message CONTENT, not mtime; your own broadcasts reset mtime).
+2. **No messages exchanged in the last 24h** — nothing sent to it or from it.
+3. **Task complete AND nobody is waiting on it** — it finished and its
+   dispatcher/manager moved on, so a reply it waits for will never come. (A pushed
+   branch held on a still-queued merge is the one nuance — see the
+   held-pending-merge rule.)
+4. **Salvage done first** — its only-copy state is copied to a durable location and
+   verified (see Containment and the reap steps).
+
+**When a needed decision or merge is delayed, ESCALATE — never silently wait.** If an
+agent is parked past the 24h window on something its manager/owner has not acted on,
+raise it explicitly to whoever owns that decision, and re-raise on every subsequent
+run. If the human owner is unresponsive, escalate through your designated escalation
+contact (the human's proxy) rather than leaving the agent parked. A silent park is
+the failure this whole procedure exists to prevent: each run must drive a parked
+agent toward a terminal state — decision made / merge lands (reap-able) or deemed
+orphaned (reap).
+
 ## The instruments, in order of trust
 
 | Question | Instrument |
@@ -81,10 +105,42 @@ sentence IS the terminal statement; a working agent's merely contains one.
 **Name what it is waiting for, then prove that thing is dead or landed.**
 
 *"Held pending the coordinator merge"* is finished only if the merge landed or was
-abandoned. If the merge is still queued, the agent is **correctly** waiting and
-reaping it destroys live context that nobody else holds.
-
-**If you cannot name the blocker, it is not a candidate.**
+abandoned. If the merge is still queued, whether the agent is *correctly* waiting
+depends on its branch and its idle time — see the held-pending-merge rule below.
+
+**If you cannot name the blocker, it is not a candidate.** (This governs the
+*no-transcript* case — absence of evidence — not a named-but-stale merge wait.)
+
+## 🔴 The held-pending-merge case — a PUSHED branch changes the gate
+
+An agent parked "pending the merge" is judged by ONE thing first — **is its branch
+pushed?** — because a merge wait only makes sense if the merge king can reach the
+branch.
+
+- **Branch NOT pushed — broken at ANY idle age.** The merge king cannot access an
+  unpushed branch, so the wait can never resolve, and the agent's commits are also
+  the only copy (unsafe to reap). This is not a legitimate wait — it is a stuck one.
+  → Get the branch PUSHED (nudge the agent / its orchestrator to push it, or escalate
+  that it needs pushing). Never reap an unpushed held-pending-merge agent — pushing
+  first is both what unblocks the merge and what makes any later reap safe.
+- **Branch pushed, idle < 24h.** Legitimately waiting its turn in the merge queue.
+  Leave it (the pushed branch means the merge king can reach it and nothing is lost).
+- **Branch pushed, idle ≥ 24h.** The wait is no longer legitimate — a pushed branch
+  is not the only copy of anything, so any agent could carry the merge. Resolve it to
+  one of two clear states:
+  - **Merge HAPPENED** (branch is an ancestor of trunk, or was abandoned/superseded)
+    → the agent is **ORPHANED**, waiting for a response that will never come → **reap**
+    (salvage-first, and still subject to the standing reap preconditions).
+  - **Merge still PENDING** (branch not on trunk, not abandoned) → the merge king
+    forgot it or the queue is stuck → **ESCALATE** to the merge king (name the branch
+    tip + how long it has waited), and **re-escalate on every subsequent skill run**
+    until it resolves. Never leave it silently parked.
+
+**The escalation is the load-bearing half.** Because each skill run re-checks and
+re-escalates a still-pending merge, the condition is self-correcting: it drives toward
+one of two terminal states — the merge completes (agent then reap-able) or the agent
+is deemed orphaned (reap) — instead of a pushed-branch agent parked forever on a merge
+nobody is tracking. A silent park is exactly the failure this rule prevents.
 
 ## Containment, before anything is stood down
 
@@ -126,8 +182,8 @@ an empty/never-read premise as a match"*). `--force` does NOT bypass it; the gua
 correct. So the reap that actually frees load is worktree removal — but salvage BEFORE you remove,
 then remove PLAIN (no `--force`):
 
-1. Enumerate untracked+ignored `.thrum` content — BOTH flags, one flag alone misses a class
-   (thrum-j14q3): `git status --untracked-files=all --ignored -- .thrum`
+1. Enumerate untracked+ignored `.thrum` content — BOTH flags, one flag alone misses a class:
+   `git status --untracked-files=all --ignored -- .thrum`
 2. Salvage BOTH kinds to their canonical redirect paths, and `cmp`-verify each copy is
    byte-identical to its source:
    - `?? .thrum/agents/<agent>/sessions/*-restart.md` — the restart snapshot.
@@ -218,6 +274,42 @@ RSS-MB.
   you decide**. It is read-only and dry-run — it prints a kill-list, it never
   kills anything.
 
+## 🔴 Footguns — never do these (each measured, each cost real time or state)
+
+- **Never glob/`cp` `.thrum/context/*.md` when salvaging** — the glob matches the
+  shared `project_state.md` and overwrites the canonical copy with a stale worktree
+  copy. Salvage the agent-specific `<agent>.md` by exact name only.
+- **A worktree's `.thrum/` holds a redirect file to the main repo AND a physical
+  stale local copy of shared files** (e.g. `project_state.md`) — the physical
+  worktree copy is NOT canonical; never treat it as the source of truth or copy it
+  upward.
+- **Never use shell-specific builtins in a reap loop without checking the shell** —
+  `mapfile`/`readarray` are bash-only and silently fail in zsh (`command not
+  found`), so the salvage you thought ran did not. Use portable `while read` and
+  verify each salvaged file actually landed.
+- **`rm -rf` raises a confirmation modal that blocks the PARENT pane invisibly** —
+  use `rm -r` for scratch cleanup (identical deletion, no modal). Never `rm -rf`.
+- **`git worktree remove` (plain) silently deletes gitignored-only content (rc=0)**
+  and refuses (rc=128) only on untracked/modified files — salvage is the ONLY
+  protection for gitignored only-copy state.
+- **`git worktree remove` refuses while a just-salvaged untracked snapshot still
+  sits in the worktree** — remove that salvaged copy from the worktree first, then
+  plain-remove.
+- **Never `checkout`/`reset`/`restore`/`stash`/`clean` in a shared tree, even to
+  undo** — to restore a file to its committed version, write it with a plain
+  redirect from `git show <ref>:<path>`, not a checkout.
+- **Test the reap on ONE agent first and verify the EFFECT** (gone from the worktree
+  list AND disk), not just the exit code.
+- **Rank candidates by last-message CONTENT, not elapsed time** — your own
+  broadcasts reset every recipient's idle clock.
+- **`--force` on agent-delete does NOT bypass the CAS guard** on a stale agent — the
+  reap that frees load is worktree removal, not the delete.
+- **Reap order is `thrum tmux kill <session>` FIRST, THEN `git worktree remove`** —
+  removing the worktree alone leaves the agent's tmux session alive with a
+  now-deleted cwd, which the fleet flags as recurring "cwd drift" and whose runtime
+  process keeps consuming RAM/CPU. Kill the session, verify it's gone, then remove
+  the worktree.
+
 ## Why this fails dangerously if you skip the gate
 
 The failure direction is **false-GONE**: concluding a live agent is finished. It

package/assets/skills/coordinator-context-monitoring/SKILL.md

@@ -26,40 +26,51 @@ What's forbidden is a script that bypasses this skill and fires
 `thrum tmux restart --force` unconditionally (that violates
 `feedback_restart_discipline` — burn the runway, don't restart on schedule).
 
-## Coordinator self-restart — ALWAYS `/thrum:restart-extended`
+## Coordinator self-restart — ALWAYS the EXTENDED form, compact-extended FIRST
 
 This skill's tier ladder (Steps 3–5) governs how the coordinator restarts
 **other** agents. When the **coordinator restarts ITSELF**, a different rule
-applies and it is absolute:
+applies and it is absolute — but D5 (owner-ruled)
+REVERSES which command that is:
 
-> **The coordinator ALWAYS self-restarts via `/thrum:restart-extended`, NEVER
-> `/thrum:restart`.**
+> **The coordinator ALWAYS uses the EXTENDED snapshot grade for itself — never
+> the standard/compact form. Which command carries that grade is
+> runtime-directed: `/thrum:compact-extended` on any runtime with a verified
+> compact-equivalent skill (D6, the default), `/thrum:restart-extended` ONLY
+> as the fallback on a runtime without one (today: muse, copilot).**
+
+This is a REVERSAL of the prior absolute rule ("ALWAYS restart-extended, NEVER
+compact") — that rule is retired, not merely relaxed. Do not restore it.
 
 Rationale: the coordinator is the nerve center. Its handoff must carry the full
 16-section snapshot (wire contracts, capability matrix, cycle history, open
 L-questions, anticipated Q&A, design rationale) so the next session resumes
-steady-state coordination without re-deriving fleet state. The standard
-`/thrum:restart` compact format drops that load-bearing context and strands the
-next session. This holds regardless of which tier the coordinator's own context
-sits in — there is no ctx-band at which the coordinator downgrades to the
-compact restart.
+steady-state coordination without re-deriving fleet state — that requirement
+is UNCHANGED and is what "EXTENDED" governs; only the compact-vs-restart choice
+changed. Compacting (rather than restarting) additionally keeps the SAME
+process/session alive — sub-agents, background loops, and cron schedules the
+coordinator owns survive the compaction, where a restart would drop them.
+There is no ctx-band at which the coordinator downgrades to the standard/
+compact-grade snapshot — the tier ladder below governs OTHER agents, not this.
 
-Practical trigger points for coordinator self-restart:
+Practical trigger points for coordinator self-restart/compact:
 
 - A warn-tier context nudge fires on the coordinator's own pane (e.g. 70%+).
 - The coordinator hits a clean checkpoint and elects a fresh session.
 - Rate-limit / stuck-state recovery on the coordinator itself.
 
-In every one of these, run `/thrum:restart-extended`. (Captured as role-rule
-`coord-always-restart-extended` /
-`Coordinator ALWAYS uses /thrum:restart-extended`; this skill is the
-always-loaded home so the rule survives even when memory isn't consulted.)
+In every one of these: run `/thrum:compact-extended` if the coordinator's
+runtime has a compact equivalent (the default); `/thrum:restart-extended` only
+if it does not. (The role-rule `coord-always-restart-extended` — `Coordinator
+ALWAYS uses /thrum:restart-extended` — is RETIRED as of D5; see
+`thrum memory` for its retirement record. This skill is the always-loaded home
+so the CURRENT rule survives even when memory isn't consulted.)
 
 Note the distinction from Steps 3–5 below: those steps drive `/thrum:restart`
 (Step 4) and `/thrum:restart-extended` (Step 5) into
 **implementer/brainstormer** panes per their ctx tier — that tiering is correct
 for worker agents. The carve-out here is ONLY about the coordinator's own
-restart, which is unconditionally the extended form.
+restart/compact, which is unconditionally the extended grade, compact-first.
 
 ## How the scheduled sweep works (v0.10.6+ — thrum monitor)
 
@@ -274,10 +285,7 @@ brick.
 
 ## Subagent model selection
 
-> **Model tiers:** pass an explicit `model:` on every dispatch — `sonnet`
-> (low effort) mechanical, `sonnet` (medium effort) judgment, Opus only on
-> operator-ask or a skill step that names it. See the
-> `choosing-subagent-models` skill for the full policy.
+> **Model tiers:** pass an explicit `model:` on every dispatch; choose model and effort per the `choosing-subagent-models` skill (read `runtime.role_models` at the moment of use). Never let a sub-agent inherit your own model.
 
 ## Step 1 — Run the sweep
 
@@ -464,6 +472,8 @@ by typing the restart command directly into their input field:
 thrum tmux send <tmux_session_name> '/thrum:restart'
 ```
 
+If it exits 3 (Enter WITHHELD, text already typed) or 4 (verdict unknown), do NOT retype it: `thrum tmux capture` the pane and submit with `thrum tmux send <tmux_session_name> --keys Enter` only if no dialog is showing.
+
 (Find the tmux session name in sweep output — it's typically the worktree
 basename, e.g. `myepic-impl`, NOT the agent_id.)
 

package/assets/skills/coordinator-deploying-a-node/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: coordinator-deploying-a-node
+description: "Use when deploying a build to a single node, migrating or not — deploying a build, schema-migrating deploy, pro-bundle install plus service restart on a node, roll out a build to a node, ship to a node, single-node canary. Loads the deploy runbook — verifying the artifact actually CONTAINS the fix, install-before-restart ordering, verify-by-effect, and preventing store corruption on migration."
+---
+
+# Coordinator: Deploying a Build to a Single Node — migrating or not
+
+> This runbook covers EVERY deploy to a single node, migrating or not. Most sections apply to every deploy; only migration-weight and store-corruption specifics are bump-only.
+
+## 0. Pull-current first (ff-only)
+
+The absolute first action before anything else: fetch the control-plane repository and fast-forward to the orchestrator's pin.
+
+- Read the project's deployment adapter inside `.thrum/config.json` (`fleet.deployment`; reference at the deployment-adapter reference) to obtain `preflight.pull_command` and `preflight.pin_command`.
+- Run `preflight.pull_command` (must be ff-only; if not fast-forwardable, STOP and surface — never blind-merge in the shared tree).
+- Verify the delivered artifact actually CONTAINS the fix at the pinned SHA (adapter `artifact.commit_file` sidecar).
+
+This ensures the node's coordinator reasons from a checkout that is actually current before evaluating backup, install, or migration.
+
+> Example — Thrum project: pull via `git fetch origin && git merge --ff-only origin/<branch>` before any backup or install.
+
+## 1. Who executes — resolve the node's local coordinator (via adapter identity)
+
+The node's own coordinator drives the deploy locally on its own host. Never drive a node's build/install/restart from another host.
+
+- Resolve WHO via `topology.identity_resolution` (adapter `fleet.deployment.thrum.topology.identity_resolution` or `fleet.deployment.products.<id>.topology`) — a `daemon_id` join plus hostname and absence of `.thrum/redirect`, never by agent name or worktree name.
+- When connected-repo daemons share a host, respect the adapter-defined restart order within that host.
+
+If the target node has no working coordinator, state why explicitly before using any fallback.
+
+## 2. Back up before touching anything (via adapter backup command + sizing formula)
+
+- Run the project's backup command (`fleet.deployment.thrum.backup.command` or `fleet.deployment.products.<id>.backup.command`) and verify per `backup.verify`.
+- Size BEFORE you run it on a bloated node: apply the adapter's `backup.sizing_formula` (`free_at_completion = free_now - zip(stale current/) + size(stale current/) - size(live lane)`) — the stale `current/` is removed before the fresh export, so peak is not double-count. Retention runs last and does not bound the peak.
+- On failure, roll back via `backup.restore_command`; never delete the store.
+
+> Example — Thrum project: backup via `thrum backup`, sized per the formula above, verified with `sqlite3 ?mode=ro&immutable=1` read.
+
+## 3. Storage access — through the engine or control-plane CLI, never file-bypass
+
+Access the state store only through the engine or the control-plane CLI in read-only mode. Never bypass the storage engine's file ownership.
+
+- Via: `storage_access.via` (e.g., CLI or `?mode=ro`).
+- Forbidden: `storage_access.forbidden` (e.g., hand-copy of live `-wal`/`-shm`, concurrent `.backup` on live store).
+- A bare read-write open can fire a checkpoint that truncates the write log out from under live readers → sustained corruption. Always use `?mode=ro` where applicable.
+
+If the project has no WAL/SHM, this section is N/A — skip and note.
+
+## 4. Never wrap service start/restart in a blind timeout
+
+Run the project's service restart command (`fleet.deployment.thrum.service.restart_command` or product equivalent) without a blind timeout wrapper. A timeout that kills a migrating restart mid-migration manufactures a half-migrated store.
+
+- Adapter flag `service.never_timeout` is true.
+- Signal-window rules are adapter data: `migration.signal_rules` (`SIGQUIT` fatal-always, `SIGUSR1` fatal-before-socket). Respect them — do not send fatal signals in the forbidden window.
+
+> Example — Thrum project: restart via `thrum daemon restart`, never wrapped in `timeout`; mac path via `scripts/mac-daemon-restart-via-cron.sh`.
+
+## 5. Install from the delivered artifact (never rebuild on the node)
+
+Install from the identical bundle the orchestrator built, delivered to `artifact.distribution.drop_path`.
+
+- Verify BEFORE unpack that the delivered bundle's version/checksum/commit sidecar equals the orchestrator's pin (adapter `artifact.checksum`, `artifact.version_file`, `artifact.commit_file`).
+- Run `install.command` (from adapter). The node does not compile, sign, or rebuild — it installs.
+- Collect BEFORE readings (current version, state counters, checkpoint counts, health probes) before the install.
+
+> Example — Thrum project: install from the adapter's `artifact.distribution.drop_path` via the adapter's `install.command`.
+
+## 6. Measure from the running process, never the checkout
+
+Read version/state from the running service, not from the filesystem checkout.
+
+- Verify via `install.verify_by_effect` probes: version equals pin, NEW PID, service status reports pin, sidecar equals pin.
+- Do not trust installer exit 0 alone.
+
+## 7. Migrate via service restart — verify by effect
+
+Migration is performed by restarting the service after install; the service's own boot migration does the schema/data move.
+
+- Calibrate weight via `migration.weight_calibration` (heavy bulk-export vs light add-column) — do not assume a fixed duration.
+- Known signatures that require a cold-restart recovery: `migration.sigbus_signatures` (e.g., WAL-index recover signatures) and `migration.on_sigbus`.
+- Observe that the restarted service reports the new version/state and that health probes have converged (adapter `health.probes`, `health.convergence_wait`).
+
+## 8. Verify post-migration (liveness, health probes, checkpoint counts, agent liveness)
+
+Run adapter `health.probes` and compare BEFORE/AFTER:
+
+- Service alive and reporting pin.
+- State counters converged per `health.convergence_wait` (mechanism-derived, e.g., `3m`).
+- Crash log empty, expected agents live.
+
+For tandem daemons that share a host or depend on each other, verify the coordinated set per adapter.
+
+## 8a. Re-render configuration/templates if the build changes them
+
+If the build carries template or role changes, re-render between install and restart:
+
+- Commands: `templates.refresh_command` and `templates.deploy_command`.
+- Order: `templates.order` (`refresh→deploy` between `install.sh` and daemon restart).
+- Verify by effect (render output, then service restart).
+
+> Example — Thrum project: `thrum roles refresh` then `thrum roles deploy` between install and restart.
+
+## 8b. Plugin/skill refresh if the deploy carries skill changes
+
+If the bundle carries skill/plugin changes, refresh the plugin cache:
+
+- Refresh driver: `plugin.refresh` (version bump required — cache keyed by version).
+- Manifests: `plugin.manifests` (all skill-carrying manifests bumped in the same commit as the new skills).
+
+Do not hand-edit generated marketplace manifests.
+
+## 8c. Reconcile registry/phase after restart
+
+Re-verify the daemon registry and agent phases after restart (adapter `health.probes` includes phase reconciliation). Confirm the pinned version is durable across a clean cold-boot probe where applicable.
+
+## Red flags — STOP
+
+- Pull not ff-only.
+- Backup skipped or undersized.
+- Storage accessed via forbidden path (`storage_access.forbidden`).
+- Restart wrapped in a blind timeout or killed with `SIGQUIT`/`SIGUSR1` in a fatal window (`migration.signal_rules`).
+- Install rebuilt locally instead of from the delivered artifact.
+- Post-migration health not verified by observed effect.
+- Template re-render skipped when the build changed templates (`templates.order` violated).

package/assets/skills/coordinator-dispatching-work/SKILL.md

@@ -65,10 +65,7 @@ optimization.
 
 ## Subagent model selection
 
-> **Model tiers:** pass an explicit `model:` on every dispatch — `sonnet`
-> (low effort) mechanical, `sonnet` (medium effort) judgment, Opus only on
-> operator-ask or a skill step that names it. See the
-> `choosing-subagent-models` skill for the full policy.
+> **Model tiers:** pass an explicit `model:` on every dispatch; choose model and effort per the `choosing-subagent-models` skill (read `runtime.role_models` at the moment of use). Never let a sub-agent inherit your own model.
 
 ## Check the target's queue before you dispatch (R3)
 
@@ -162,13 +159,30 @@ re-dispatch overhead.
 3. Acceptance criteria as bullets
 4. The worktree path the work happens in
 5. An explicit reminder to pass `model:` on any sub-agents the implementer
-   spawns (sonnet-low for mechanical, sonnet-medium for judgment)
+   spawns (model and effort per `choosing-subagent-models`)
 6. Spec/plan paths to read before starting
 7. **Adjacent candidate beads** from the adjacency pass above, labeled as
    CANDIDATES with their validity explicitly unverified — plus the instruction to
    check them against the merged-forward tip and either fold them in or return
    them as completed
 
+## Anti-pattern-removal epics must ship a ratchet lens
+
+**Why:** during a prior owner-bypass remediation, judgment
+review alone let 11 new instances of the exact anti-pattern being removed
+land through the merge gate mid-sprint, because no mechanical check enforced
+a monotonic budget across diffs.
+
+**How to apply:** When dispatching an epic whose purpose is removing an
+existing anti-pattern (not just fixing one instance of it), the acceptance
+criteria MUST include a mechanical ratchet lens (see
+`coordinator-hotpath-merge-gate` § "Invariant-ratchet lenses") wired into
+`.thrum/hotpath-gate.json` as `always_run` before the epic is considered
+closeable — not as a follow-up. A judgment-only acceptance ("reviewer
+confirms the count went down") is insufficient; the count must be enforced
+by a standing mechanical budget the gate itself checks on every subsequent
+merge.
+
 ## Execution invariants — carry these in every implementation dispatch
 
 **Why:** A plan is a snapshot; trunk moves and reality drifts from it. Sprints
@@ -208,17 +222,16 @@ with a different name — do not rename in place.
 
 ## Propagate model-selection discipline downward
 
-**Why:** Sub-agents inherit the parent model by default. A coordinator on Opus
-that spawns an unspecified sub-agent gets Opus-cost work for tasks that need
-sonnet-low. The same trap repeats inside an implementer's worktree: if the
+**Why:** Sub-agents inherit the parent model by default. A coordinator whose own tier is
+costly that spawns an unspecified sub-agent gets costly work for tasks that need
+a cheap tier. The same trap repeats inside an implementer's worktree: if the
 implementer doesn't propagate the discipline, their own sub-agents silently
 inherit too. Cost compounds across a session.
 
 **How to apply:** Every dispatch prompt should include the model-selection rule
 explicitly: "When you spawn your own sub-agents, pass explicit `model:` —
-`sonnet` (low effort) for mechanical work (lint, tests, find/replace), `sonnet`
-(medium effort) for judgment work (review, complex implementation), `opus`
-only when justified. Default to sonnet over opus." Audit the dispatch prompt before sending.
+choose model and effort per the `choosing-subagent-models` skill (read
+`runtime.role_models` at the moment of use); never inherit your own model." Audit the dispatch prompt before sending.
 
 ## The impl-prompt review stamp satisfies pre-dispatch review
 

package/assets/skills/coordinator-hotpath-merge-gate/SKILL.md

@@ -117,23 +117,35 @@ rediscovering these the hard way:
    carrying dupes instead of the real content.
 6. Run full-package `-race`, not targeted `-run` — a targeted race run misses
    cross-test races.
-7. Build+test the MERGED-tree result as a SEPARATE condition — neither gate
+7. **`internal/daemon/rpc` must NEVER be run monolithically at gate time, in
+   either lane** — a bare package-level `go test [-race] ./internal/daemon/rpc`
+   starves and hits the configured `-timeout` wall in both the race and
+   non-race lane. The gate's OUTPUT must show the sharded runner actually
+   executed for RPC (`race-shard` / `package-shard --mode norace`, or
+   `scripts/test-run.sh race|norace ./internal/daemon/rpc`, or `make gate`
+   which shards both lanes automatically) — not just that some RPC test ran.
+   A bound-timeout with ZERO test failures is a FALSE RED, not a finding:
+   distinguish it from a genuine hang/deadlock via
+   `go run ./cmd/testgate classify-timeout --log <file> --shard-config <file>
+   --shard <name>` (fails closed — only BOUND-TIMEOUT exits 0; HANG and
+   UNCLASSIFIED both exit nonzero) before reporting it as a regression.
+8. Build+test the MERGED-tree result as a SEPARATE condition — neither gate
    currently runs a build of the actual post-merge tree; a clean pre-merge
    build/test does not prove the merged result compiles or passes.
-8. Use `rm -r`, NEVER `rm -rf`; use plain `git worktree remove` to drop a worktree, never
-   `--force` as the default (see item 12 below). A broad `ask` rule on `rm -rf *` outranks any narrow `/tmp` allow,
+9. Use `rm -r`, NEVER `rm -rf`; use plain `git worktree remove` to drop a worktree, never
+   `--force` as the default (see item 13 below). A broad `ask` rule on `rm -rf *` outranks any narrow `/tmp` allow,
    so `rm -rf` raises a human permission prompt EVERY time regardless of path —
    it stalls gate sub-agents mid-run waiting on a keystroke. `rm -r` runs free. Do NOT widen the ask rule
    to work around this; that entry is the only deletion protection on the box.
-9. Check the discriminator before picking a scratch path, don't assume from
-   the platform: `[ -L /tmp ]`. macOS (symlink) — create throwaway worktrees
-   under `/private/tmp`; a worktree under `/tmp` false-FAILs worktree-ancestor
-   tests via the symlink, producing a confident wrong gate result. Linux (real
-   dir) — `/tmp` is correct; `/private/tmp` may not exist there and must not
-   be created.
-10. Your report reaches the coordinator ONLY as your final returned text.
+10. Check the discriminator before picking a scratch path, don't assume from
+    the platform: `[ -L /tmp ]`. macOS (symlink) — create throwaway worktrees
+    under `/private/tmp`; a worktree under `/tmp` false-FAILs worktree-ancestor
+    tests via the symlink, producing a confident wrong gate result. Linux (real
+    dir) — `/tmp` is correct; `/private/tmp` may not exist there and must not
+    be created.
+11. Your report reaches the coordinator ONLY as your final returned text.
     Side-channel output is discarded. Put the whole verdict in the return value.
-11. **NEVER run `git stash`, `git checkout`, `git reset`, or any working-tree
+12. **NEVER run `git stash`, `git checkout`, `git reset`, or any working-tree
     mutation in the SHARED repo.** Do read-only inspection there (`git show
     <sha>:<path>`, `git log`, `git diff`) and do every build/test in a throwaway
     detached worktree. `git stash` is a SINGLE SHARED STACK across every
@@ -142,7 +154,7 @@ rediscovering these the hard way:
     hold uncommitted `State.md` they are actively re-authoring.
     If you believe you must mutate the shared tree, STOP and report instead —
     that is always a finding, never a step.
-12. **TEAR DOWN YOUR THROWAWAY WORKTREE WHEN THE GATE ENDS — after two checks,
+13. **TEAR DOWN YOUR THROWAWAY WORKTREE WHEN THE GATE ENDS — after two checks,
     in this order.** A required final step, not cleanup etiquette. Each
     abandoned worktree pins its HEAD commit against `gc` and adds a
     `.git/worktrees` admin entry, so the object store grows monotonically.
@@ -155,7 +167,7 @@ rediscovering these the hard way:
         it. Usually fine (a gate merge is reproducible by redoing it) but say so
         in your report rather than doing it silently.
     Then `git worktree remove <wt>` — **plain, no `--force`.** Its rc=128 refusal backstops
-    ONLY untracked/modified content (see rule 8 on `rm -r`) — it does NOT cover gitignored
+    ONLY untracked/modified content (see rule 9 on `rm -r`) — it does NOT cover gitignored
     content, which git removes silently with no refusal; a clean rc=0 is not proof nothing of
     value was in there (see coordinator-assessing-agent-completion's reap procedure). `--force`
     is a justified override only, never the default (see coordinator-merging-code §7a).
@@ -169,6 +181,21 @@ config entry (see `lens_scope_semantics` in the config), which still runs on
 every diff regardless of trigger directories. If the config has no
 `trigger_directories`, fail with guidance to run `project-hotpath-gate`.
 
+## Invariant-ratchet lenses
+
+A lens may declare `mandatory_test_command` (see `census_classification_coverage`
+and `write_owner_bypass_ratchet` in `.thrum/hotpath-gate.json`) instead of
+(or alongside) a pattern-match `question`/`required_evidence` pair. When
+present, PASS/FAIL is the command's own exit code — never a judgment call
+from reading the diff. This is the shape for any invariant that already has
+a mechanical detector: wire the detector as an `always_run` lens with a
+monotonic budget (a count that may only decrease, or an explicit
+waiver-tagged exception), so a diff cannot silently re-widen the invariant
+in the same change that appears to narrow it. `write_owner_bypass_ratchet`
+is the reference instance: it fails a merge that bumps a
+ceiling/aggregate in the ledger file without a `RATCHET-WAIVER:` tag, even
+when the ledger-equality test alone would pass.
+
 ## Delta re-gate continuity — walk the whole branch, read the whole function
 
 **Why:** A commit introducing a lock can be an ancestor of a delta-re-gate's
@@ -432,7 +459,7 @@ hoc test target nothing routes to. A merge that adds a `state.NewState(...)`
 call site in an `internal/daemon/rpc/*_test.go` file (test-fixture setup, not a
 handler) can leave it unclassified and desync the frozen census snapshot with
 no gate catching it — trunk went RED post-merge on 573mo v87 for exactly this
-reason (thrum-ykmly).
+reason.
 
 **Relationship to Lenses 1–10:** every other lens in this file is an
 LLM-judgment pattern check — grep a pattern, read the surrounding code, apply
@@ -476,7 +503,7 @@ diff on `TestCensusRegeneration`'s brittleness with zero added
 defect-prevention (`ClassificationCoverage` alone already catches the defect
 this lens exists for). `TestCensusRegeneration`'s own staleness is tracked
 separately (nd2j1/P1 owns the classification data; the brittle count-snapshot
-assertion itself is tracked as **thrum-33zzh** — "make advisory or drop the
+assertion itself is a distinct open question — "make advisory or drop the
 raw-count assertion"), not by this lens.
 
 **Severity:** Trigger fires and `mandatory_test_command` was not run before
@@ -520,10 +547,24 @@ otherwise leave them.
 
 ## If it fails
 
-Send it back as a normal review finding — same channel as dual-review output,
-folded into the same numbered list if dual review is still open, or as its own
-short reply if dual review already passed. Cite the offending function/file,
-which lens it failed, and the config value that triggered the finding.
+For a genuine hot-path/perf defect, a production-behaviour change, or a design
+judgment call: send it back as a normal review finding — same channel as
+dual-review output, folded into the same numbered list if dual review is still
+open, or as its own short reply if dual review already passed. Cite the
+offending function/file, which lens it failed, and the config value that
+triggered the finding.
+
+For mechanical bookkeeping only (census/shard regen via the tool, line-number
+or key refreshes, ledger totals/ceilings where the arithmetic is derivable, a
+per-entry waiver or citation comment recording a classification already
+established elsewhere (never a new safety judgment of your own), a nosec
+baseline hash for an already-reviewed pattern, comment wording, stale test
+expectations that merely follow a landed change): fix it yourself as a
+`GATE-AUTHORED` commit on your
+`gate/` branch, re-run ONLY the lens(es) the fix affects, and report
+`CLEAN-WITH-GATE-FIXES` listing each fix instead of bouncing it to the owner.
+When unsure which bucket a finding falls in, ask the coordinator with the exact
+diff — don't bounce reflexively.
 
 ## Efficacy tracking (v1 acceptance requirement)
 
@@ -563,6 +604,7 @@ rows.
 | `FALSE_POSITIVE`        | Gate flagged something correct — record which lens and why |
 | `SLIPPED`               | A wedge occurred AFTER merge that the gate did not catch   |
 | `SKIPPED_WITH_EVIDENCE` | Gate deliberately skipped (no trigger dirs), evidence cited |
+| `CLEAN-WITH-GATE-FIXES` | Gate found only mechanical bookkeeping gaps, fixed them itself as a GATE-AUTHORED commit, re-ran only the affected checks, merge proceeded |
 
 **Retrospective reclassification:** When triaging a new wedge or incident, grep
 `dev-docs/hotpath-gate-efficacy.md` for the merged branch/date. If the gate
@@ -591,4 +633,4 @@ gaps and lens improvements for the next version.
   first gate run, appended after each run)
 
 <!-- THRUM-GATE: stage=skill next=review -->
-<!-- THRUM-REVIEW: stage=skill verdict=Ready:Yes cycle=2 date=2026-07-10 -->
+<!-- THRUM-REVIEW: stage=skill verdict=Ready:Yes cycle=2 -->

package/assets/skills/coordinator-managing-state-and-lifecycle/SKILL.md

@@ -57,8 +57,11 @@ created from origin, unpushed commits can be lost or inaccessible.
 
 **How to apply:** Session close protocol — push the coordination branch every
 session end. **Read the branch name, never recall it:**
-`jq -r '.orchestration.merge_target' .thrum/config.json` (or your project's
-CLAUDE.md § Branching Strategy). Push every `feature/*` and `fix/*` branch too.
+`CONFIG=.thrum/config.json; [ -f .thrum/redirect ] && CONFIG="$(cat .thrum/redirect)/config.json"; jq -r '.orchestration.merge_target' "$CONFIG"`
+(a worktree's `.thrum/` holds only a `redirect` file pointing at the main
+repo's `.thrum` dir, so reading `.thrum/config.json` directly there returns
+empty) — or your project's CLAUDE.md § Branching Strategy. Push every
+`feature/*` and `fix/*` branch too.
 A docs/site branch pushes only when the site is ready to deploy; `main` and
 `release/*` go through the release flow.
 
@@ -77,10 +80,7 @@ batch — the visual tree exposes inversion immediately. For bulk epic creation
 (many tasks at once), spawn parallel sub-agents to issue the `bd create` calls;
 bd is fully concurrent-safe.
 
-> **Model tiers:** pass an explicit `model:` on every dispatch — `sonnet`
-> (low effort) mechanical, `sonnet` (medium effort) judgment, Opus only on
-> operator-ask or a skill step that names it. See the
-> `choosing-subagent-models` skill for the full policy.
+> **Model tiers:** pass an explicit `model:` on every dispatch; choose model and effort per the `choosing-subagent-models` skill (read `runtime.role_models` at the moment of use). Never let a sub-agent inherit your own model.
 
 ## Use `bd close --suggest-next` to surface unblocked work