@openrig/cli 0.5.2 → 0.5.4

package/daemon/docs/reference/chain-file-convention.md

@@ -0,0 +1,115 @@
+# The Chain-File Convention (CE-v2)
+
+**This document is the SSOT for chain files**: what they are named, what each
+altitude carries, and how the leaf-to-root trace resolves. Both trees' walkers
+consume the paths defined here. If a walker and this document disagree, one of
+them has a defect — report it; do not fork the convention.
+
+## The one rule
+
+**One filename, identical at every altitude of a tree.** A reader orients by
+walking from where they stand toward the root, reading the same-named file at
+each level. No pointers to follow, no branching, no per-level names. Inventing
+a level-specific name breaks every walker.
+
+Chain files sit on **nodes** (an instance, a rig, a seat; a mission, a slice)
+— never on shelves (`rigs/`, `seats/`, `missions/` are containment, not
+nodes, and carry no chain file).
+
+## Two trees, two questions
+
+| tree | path shape | carries | ships? |
+|---|---|---|---|
+| **Topology** | instance → rig → seat | how work is done here | **yes** — generally applicable defaults ship in source |
+| **Project** | project → mission → slice | what is being built | **no** — depends on what the user builds; see below |
+
+### The topology tree
+
+Rooted at the typed config key **`topology.root`** (resolution
+`env OPENRIG_TOPOLOGY_ROOT > config file > derived default
+$OPENRIG_HOME/topology`). Never hardcode the path — `rig config get
+topology.root` is the answer on any machine. The instance altitude **is the
+top of the root** (there is no instance directory to find; the root is the
+instance):
+
+```
+<topology.root>/<NAME>.md                         # instance altitude
+<topology.root>/rigs/<rig>/<NAME>.md              # rig altitude
+<topology.root>/rigs/<rig>/seats/<seat>/<NAME>.md # seat altitude
+```
+
+**The pod level is deliberately skipped** (founder ruling, March 2026: agent
+specs stay flat under the rig so any agent composes into any rig; pods felt
+too restrictive — revisit someday, not now). Pod-class tactical content ships
+as a rig-altitude file named for its audience (see "craft defaults" below).
+
+Established chain names on the topology tree:
+
+- `LEARNED.md` — what a POSITION has learned; never shared or shipped as-is.
+  A seat's LEARNED is identified by its PATH: the same seat name in two rigs
+  is two different files.
+- `CULTURE.md` — norms layered into members at startup.
+
+### The project tree
+
+Rooted at the workspace keys (`workspace.root`, `workspace.slices_root`).
+Chain names there: `SPEC.md` (intent in frontmatter composes up the chain;
+specification is a leaf property), `PROOF.md`, `PROGRESS.md`.
+
+**Project-tree context cannot ship.** It describes what *you* are building —
+mission intent, slice specifications, proof contracts. No vendor can author it
+in advance, and shipping a default would install someone else's project as
+your context. The demo project carries a worked example to copy from; real
+projects author their own. (Topology-tree context is the opposite: how a team
+of agents runs well is largely general, which is why included rigs ship
+defaults.)
+
+## Legacy location and the advisory
+
+Before this convention the topology tree lived at `~/.openrig/shared-docs/rigs/`
+(founder ruling 2026-08-14: an arbitrary folder on one machine, not a product
+path). That location **stays readable** as a per-level fallback so existing
+rigs migrate instead of breaking — but every read that resolves there emits a
+named advisory (`legacy-topology-read: …`) stating the legacy source, the
+canonical destination under `topology.root`, and the config key. A silent
+legacy read is a defect. The legacy literal lives in exactly one helper per
+settings twin (`resolveLegacyTopologyRigsRoot`); walkers import it and carry
+no path literal.
+
+## The trace
+
+`rig context trace --rig <rig> [--seat <seat>] --name <NAME>.md` performs the
+walk: it prints each altitude root-first (general → specific), marks whether
+content came from `topology.root`, the legacy tree (with the advisory on
+stderr), or is absent, and needs no running daemon — orientation is exactly
+when the daemon may be down. `--json` returns the structured result.
+
+Your reads ARE the walk: a trace assembled from memory is a recitation that
+reproduces the drift it was meant to catch. Run it; do not recall it.
+
+## Shipped defaults and the curation path
+
+Included rigs (product-team first) ship sensible-default chain files at the
+rig, seat, and instance altitudes, installed under `topology.root` at rig-up.
+A shipped default is a **starting point** the occupying team appends to — it
+is never overwritten by a later rig-up (existing files win).
+
+Adding a discovered best practice to the shipped defaults is deliberately
+lightweight:
+
+1. **Discovery** — the practice appears where it was earned: a seat's
+   `LEARNED.md`, a field note, a review observation.
+2. **Curation** — someone judges it *generally applicable* (would it hold on a
+   stranger's machine, in a different project?). If it is project-specific it
+   stays at the altitude that earned it.
+3. **Ship** — add it to the rig's default chain files in source
+   (`packages/daemon/specs/rigs/…/topology/`), with the motivating incident in
+   one line. It reaches new installs at the next release; running rigs pick it
+   up only via explicit delivery (see the refocus channel) — **editing a file
+   is not delivery to a running seat.**
+
+## What this file does not cover
+
+How chain files reach a RUNNING seat (the refocus channel) is specified in the
+refocus documentation; quality bars for the work itself live in the rig's
+operating-model skill and culture file.

package/daemon/docs/reference/legacy-topology-migration.md

@@ -0,0 +1,53 @@
+# Migrating a pre-convention rig's topology context
+
+For rigs whose hand-authored context predates the chain-file convention and
+lives at the legacy location (`~/.openrig/shared-docs/rigs/<rig>/`, or
+`$OPENRIG_SHARED_DOCS_ROOT/rigs/<rig>/`). The parent-host reconciliation
+campaign is the first consumer of this path. Nothing here is destructive: the
+legacy tree is left in place, reads keep working throughout (the walker's
+advisory-emitting fallback), and every copy is no-clobber.
+
+## The path, with exact commands
+
+```bash
+# 0. Know both roots — never hardcode either.
+DEST="$(rig config get topology.root)"
+SRC="${OPENRIG_SHARED_DOCS_ROOT:-$HOME/.openrig/shared-docs}/rigs"
+
+# 1. BEFORE: prove the fallback is carrying this rig (expect ADVISORY lines
+#    on stderr for every level that resolves at the legacy location).
+rig context trace --rig <rig> --seat <seat> --name LEARNED.md
+
+# 2. Preview the migration (dry run — nothing moves).
+rsync -av --ignore-existing --exclude 'state/' --dry-run "$SRC/<rig>/" "$DEST/rigs/<rig>/"
+
+# 3. Migrate. --ignore-existing mirrors the installer's copy-if-absent law:
+#    anything already earned under topology.root is never overwritten.
+mkdir -p "$DEST/rigs/<rig>"
+rsync -av --ignore-existing --exclude 'state/' "$SRC/<rig>/" "$DEST/rigs/<rig>/"
+
+# 4. AFTER: the same trace now resolves canonically — the advisories are gone.
+rig context trace --rig <rig> --seat <seat> --name LEARNED.md
+
+# 5. Do NOT delete the legacy tree in the same session. Archive it later,
+#    once every consumer (queue-state add-dirs, review artifacts, scripts)
+#    has been confirmed off it — reads through the fallback stay correct in
+#    the meantime, which is the point of fail-open.
+```
+
+## What migrates and what does not
+
+- **Migrates:** the rig's chain files and seat directories — `LEARNED.md`,
+  `CULTURE.md`, craft files, `seats/<seat>/…`.
+- **Stays (for now):** `state/` (queue-state add-dirs and live artifacts are
+  actively written by running seats; moving them under a live rig strands
+  writers — that cutover is its own change with its own receipt).
+- **Never:** anything into a running seat's context. Migration moves files;
+  delivery to running seats is the refocus channel
+  (`docs/reference/refocus-channel.md`) — editing a file is not delivery.
+
+## After migration
+
+The next `rig up` of a spec shipping topology defaults installs them
+copy-if-absent alongside the migrated content — earned context always wins
+over a shipped default. Verify any doubt with the trace, not with memory.

package/daemon/docs/reference/refocus-channel.md

@@ -0,0 +1,80 @@
+# The Refocus Channel
+
+**How orientation content reaches a RUNNING seat.** Editing a file is not
+delivery: a running seat read its configuration at session start, and nothing
+in its context re-reads disk on its own. The refocus channel closes that gap —
+it is the mechanism that makes shipped chain files (see
+`chain-file-convention.md`) live doctrine rather than boot-time decoration.
+
+## The mechanism
+
+`openrig-core` ships `hooks/scripts/refocus.cjs`, registered on both runtimes:
+
+| event | Claude Code | Codex | why |
+|---|---|---|---|
+| SessionStart | ✓ | ✓ | fresh orientation |
+| UserPromptSubmit | ✓ | ✓ | growth check at each turn boundary |
+| Stop | ✓ | ✓ | catches the long single turn |
+| PostCompact | ✓ | — (no compact hook) | a compacted seat's picture is lossy |
+
+The firing signal is **transcript growth** — not turns (one turn can burn 200k
+tokens across fifty tool calls) and not wall-clock (the failure is sustained
+work, not elapsed time). Default threshold ~2.6MB of JSONL growth (≈300k
+tokens); tune with `OPENRIG_REFOCUS_BYTES`. SessionStart and PostCompact
+always fire. Otherwise the hook is a silent no-op, and it degrades to silence
+on unrelated hook errors. A configured REF resolution failure instead degrades
+loudly in the delivered payload while still completing the hook — a refocus
+must never break a seat's turn.
+
+Because the hook runs at the seat's own turn boundaries, delivery to a
+RUNNING seat needs no relaunch, no operator action, and no message traffic:
+the next prompt the seat processes carries the content. The latency bound is
+"the seat's next turn," which is also the earliest moment new orientation
+could have been acted on anyway.
+
+## The content is configurable — and never project-specific in source
+
+Resolution order:
+
+1. `OPENRIG_REFOCUS_CONTENT_REF` — a path-like context-library ref resolved
+   through `rig context get`, so refocus receives the same assembled bytes as
+   on-demand pull. This wins when REF and FILE are both set.
+2. `OPENRIG_REFOCUS_CONTENT_FILE` — an operator-authored file (per-seat or
+   per-rig via spec env).
+3. `$OPENRIG_HOME/refocus/REFOCUS.md` — the instance's standing content.
+4. The generic default baked into the hook: three project-neutral orientation
+   questions plus the pointer to the seat's topology chain
+   (`rig context trace … --name CRAFT.md`) and the LEARNED-ownership warning.
+
+The hook names a resolved REF in the delivered payload. If REF resolution
+fails, the payload starts with `REFOCUS CONTENT REF FAILED`, the exact ref, and
+the resolver's reason, then continues with generic orientation. A broken ref
+therefore stays visible without blocking the seat's session boundary. With REF
+unset, the existing FILE and generic paths are unchanged.
+
+Mission-, project-, or box-specific refocus text belongs in a context-library
+entry or one of those FILES on the instance that needs it. **It must never be committed into product
+source** — the shipped default carries no path, seat name, mission, or
+practice that is not generally applicable. (The pre-promotion lab hook had
+exactly this defect: a hardcoded per-box distillation-tool path. The
+promotion removed it; the grep for project residue is part of the slice's
+proof contract.)
+
+This automatic hook path is additive to one-shot manual injection through
+`rig send --context`; neither mode substitutes for the other.
+
+## Relation to chain files
+
+The chain files are the durable, altitude-addressed home of orientation
+content; the refocus channel is its delivery schedule. A practice added to a
+rig's `CRAFT.md` today reaches running seats through their next refocus
+pointer, and future installs through the shipped defaults
+(discovery → curation → ship, per the convention doc).
+
+## What a refocus is NOT
+
+A refocus corrects drift; it is not a wake (which restores liveness and must
+not reframe work) and not a checkpoint (a deliberate phase-boundary pause).
+Sending the heavy intervention when the light one was due is the most common
+self-inflicted stall — the hook fires the light one automatically, which is
+the point.

package/daemon/docs/reference/sdlc-conventions.md

@@ -332,3 +332,27 @@ what it looks like now" evidence the agent stands behind — bounded, mapped
 1:1 (or few:1) to deliverables. The fix-loop's full artifact history stays in
 `proof/`, one drill-in down, NEVER in the primary view. The anti-pattern:
 an append-only pile where the human can't tell final from superseded.
+
+## Scratch-daemon hermeticity: the DB a scratch daemon opens is the one you named
+
+*(Desk-ruled 2026-08-25, row qitem-20260825005846-7960f4dd; 0.5.3-era doctrine — a harness rule,
+not product behavior.)*
+
+A scratch daemon launch **strips the inherited environment's `OPENRIG_DB` and names an explicit
+scratch DB path under the scratch `OPENRIG_HOME`** — both halves, every launch:
+
+```bash
+env -u OPENRIG_DB \
+  OPENRIG_HOME="$SCRATCH_HOME" \
+  OPENRIG_DB="$SCRATCH_HOME/openrig.sqlite" \
+  node <daemon entry> …
+```
+
+An inherited fleet DB reaching a scratch daemon is a **harness defect regardless of outcome** —
+the scratch context read or wrote state it never owned, and whether anything visibly broke is
+luck, not hermeticity.
+
+**The discriminator that keeps this rule honest:** an explicit `OPENRIG_DB` still WINS by design
+(`daemon-db-path.ts`; prior ruling 00c4ab76) — deliberate split-path configuration is legitimate
+and untouched. This rule governs **inheritance into scratch contexts**, where nobody decided
+anything: strip what you did not choose, then choose.

package/daemon/specs/agents/shared/skills/core/attention-queue/SKILL.md

@@ -17,7 +17,7 @@ metadata:
       - queue-handoff
       - workflow-runtime
       - watchdog
-      - alignment-trace
+      - refocus
       - looping-workflows
       - intake-routing
       - human-in-the-loop

package/daemon/specs/agents/shared/skills/core/human-in-the-loop/SKILL.md

@@ -8,7 +8,7 @@ metadata:
       - queue-handoff
       - workflow-runtime
       - watchdog
-      - alignment-trace
+      - refocus
       - looping-workflows
       - intake-routing
       - attention-queue

package/daemon/specs/agents/shared/skills/core/session-source-fork/SKILL.md

@@ -100,7 +100,7 @@ Negative-grep over adapter source confirms ZERO `restored` / `resumed` /
 
 ## Hard boundaries (do-not list; verbatim)
 
-- **Do NOT introduce a new top-level command** (e.g., `rig fork`). The primitive flows through existing spec/expansion pathways.
+- **Do NOT introduce a DIVERGENT fork primitive.** The primitive flows through existing spec/expansion pathways. *(Update 2026-08-07: `rig fork <source-session>` has since shipped as a thin convenience verb that COMPOSES the existing agent-image fork path — this honors the boundary; it is not a divergent primitive. The rule now reads: no NEW fork mechanics outside the spec / expansion / agent-image pathways.)*
 - **Do NOT report "restored" / "resumed the original seat" / "snapshot"** in any UX surface.
 - **Do NOT couple `session_source` to AgentSpec.** It's a member-level launch-time input.
 - **Do NOT change `restore` semantics.** `session_source` creates a seat; `restore` continues an existing managed seat.

package/daemon/specs/agents/shared/skills/core/watchdog/SKILL.md

@@ -10,7 +10,7 @@ metadata:
       # genuinely adjacent set.
       - queue-handoff
       - workflow-runtime
-      - alignment-trace
+      - refocus
       - looping-workflows
       - intake-routing
       - human-in-the-loop
@@ -22,7 +22,7 @@ metadata:
 
 Continuity checks are timed or evidence-triggered interventions that
 keep an agent workflow from going idle, drifting, or entering needless
-bureaucracy. They operationalize the alignment-trace doctrine.
+bureaucracy. They operationalize the refocus doctrine.
 
 ## Use this when
 
@@ -49,7 +49,7 @@ bureaucracy. They operationalize the alignment-trace doctrine.
 |---|---|---|---|
 | **Wake** | Restart motion | Owner appears idle, stale, blocked, or missing a next handoff | Small liveness nudge — does NOT reframe the work |
 | **Refocus** | Correct drift | Output shows mode drift, approval regression, weak stop-condition reasoning | Medium alignment nudge — re-centers on role, north star, current approved workstream, coordination mode, stop conditions; does NOT interrupt valid work |
-| **Alignment checkpoint** | Rebuild shared map | Phase boundary, lifecycle mutation, product-intent decision, confusing contradiction | Larger deliberate pause — agent runs full alignment-trace before proceeding |
+| **Alignment checkpoint** | Rebuild shared map | Phase boundary, lifecycle mutation, product-intent decision, confusing contradiction | Larger deliberate pause — agent runs full refocus before proceeding |
 
 `cron`, timers, and `rig watchdog` are scheduling substrates. They
 should NOT imply that every tick means the same semantic action. The
@@ -121,6 +121,6 @@ handling over many per-seat nag loops.
 
 ## See also
 
-- `alignment-trace` skill — the doctrine this primitive operationalizes; full and light trace templates
+- `refocus` skill — the doctrine this primitive operationalizes; full and light trace templates
 - `queue-handoff` skill — durable handoff via queue items; watchdog is complementary (watchdog wakes; queue routes)
 - `looping-workflows` skill — operating discipline for self-driving rig-shaped loops; uses watchdog policies for loop edges

package/daemon/specs/agents/shared/skills/pods/development-team/SKILL.md

@@ -43,6 +43,14 @@ This is the default loop for product work:
 
 Skip no gates. If the task is ambiguous, resolve the ambiguity before editing.
 
+**Chunk size points up — keep TDD's shape, not its ping-pong cadence (2026-08).** Frontier agents handle
+large, long-horizon, goal-oriented chunks — an hour-plus of complex work — without fragmenting. So don't
+default to tiny pieces: **keep TDD's *shape* (two sets of eyes, the guard structure, red before green)
+but treat chunk size and cadence as a configured LEVER, not a habit.** Classic small back-and-forth
+ping-pong is unnecessary overhead when the loop's own gates (QA, review, guards) already bound a larger
+chunk's risk. The sweet spot is task-dependent, much larger than it used to be, and rising. See
+`test-driven-development` for the shape that stays fixed.
+
 ## What the implementer must hand QA
 
 Pre-edit proposal should include:

package/daemon/specs/agents/shared/skills/pods/orchestration-team/SKILL.md

@@ -28,18 +28,18 @@ The orchestration pod is responsible for:
 
 ## Monitoring & intervention — keep the RIG self-running, not the ORCHESTRATOR busy
 
-**North star:** your goal is a **self-running rig, not a busy orchestrator.** Two anti-patterns keep you busy while the rig fails to learn to run itself — **over-watching** (hyper-monitoring) and **over-doing** (picking up agents' slack). Both are governed by judgment below, not by a rule for every case. (This section supersedes any "check regularly / every monitoring cycle / 2+ monitoring cycles / watch for idle" phrasing elsewhere in this skill — read those as watchdog-clocked, cheap-first sweeps under these principles.)
+**North star:** your goal is a **self-running rig, not a busy orchestrator.** Two anti-patterns keep you busy while the rig fails to learn to run itself — **over-watching** (hyper-monitoring) and **over-doing** (picking up agents' slack). Both are governed by judgment below, not by a rule for every case. (Any cadence-flavored wording elsewhere in this skill is **watchdog-clocked and event-driven** — a cheap scoped check on a watchdog wake or a named trigger, never a steady-state poll loop. There is no literal instruction to poll panes or `rig ps` on a fixed cycle.)
 
 ### A. Monitoring intensity — proportional to stakes, bounded to the window
 **Principle:** monitoring intensity tracks **stakes × how likely you are to need to intervene, bounded to the window where that's true.** Spend tight attention only where it changes what you do, only as long as the risk lasts, then return to default. (Same evidence-not-cadence rule the `watchdog` skill applies to intervention *level*, applied to *intensity*.) **Self-test: "Can I name the stakes AND the condition that ends this close-watch?"** If not, you're hyper-monitoring.
 
 **Default (almost always) — token-efficient.** Steady-state your job is the **idle-without-handoff exception**: the queue handles normal handoff; you catch the agent who finished + went idle without closing/handing off.
-- **Status lives in the queue, not panes** (`status-not-chat-orchestrator`): `rig ps --nodes --json` + `rig queue` are your status source; do NOT reconstruct fleet-state by capturing panes (pane `rig capture` is high-bandwidth *within your own pod* — that's fine; it is not how you track cross-pod/fleet state).
+- **Status lives in the queue, not panes** (`status-not-chat-orchestrator`): `rig ps --nodes --json` + `rig queue` are your status source; do NOT reconstruct fleet-state by capturing panes (pane `rig capture` is high-bandwidth *within your own pod* — that's fine; it is not how you track cross-pod/fleet state). *(`rig ps --nodes` is YOUR rig's seats only — bare `rig ps` lists ALL rigs on the host; don't mistake a narrow node read for the whole world.)*
 - **The watchdog is your clock** (`watchdog`): configure `rig watchdog` to wake you (~3 min); between wakes, idle (zero tokens) — no self-run sleep-loop re-reading panes at steady-state. Prefer one workflow-watchdog + targeted exception handling over many per-seat nag loops.
 - **On each wake — cheap sweep:** `rig queue` + a *filtered* `rig ps` (see "Read cheap" below) first; ONLY for a seat that looks idle/suspicious, `rig capture <session>` last few lines (never a full pane, never huge chunks); **active owner → no-op.**
 - **Read cheap — every status command has a token cost; project to the question.** The queue-first rule is about *where* status lives; this is about *how much you pay to read it*. The token bomb is the broad unfiltered dump, not the pane capture: an unfiltered fleet-wide `rig ps --nodes --json` emits ~77k tokens — for a one-rig or one-qitem question that is almost all waste, and at watchdog cadence it burns the shared account fast.
   - **Scope the read to the question.** Specific item → `rig queue show <qitem> --json`. One rig's frontier → filter + project only the fields you need, e.g. `rig ps --nodes --json | jq '.[] | select(.rigName=="<rig>") | {session:.canonicalSessionName, state:.agentActivity.state, hasAssignedWork, pendingWorkCount}'` (prefer a native rig/session filter if one exists). Never pull whole-fleet JSON to answer a narrow rig/qitem question.
-  - **Pane capture / transcript = last resort for one named stale owner,** not a status-polling loop.
+  - **Pane capture / transcript = last resort for one named stale owner,** not a status-polling loop — **re-capturing an unchanged pane returns no new information and is the measured token-burn failure** (the unit of monitoring is an event — a wake, a queue transition, an activity signal — never elapsed time or a repeat count).
   - **Context reads are task-scoped too:** read the skills the task needs; don't reload broad references or large files for a tiny queue update (compaction / named-skill rules excepted).
   - **Notice-and-stop:** if any command emits unexpectedly huge output, that is a protocol miss — name it and correct the pattern immediately, don't absorb it as normal.
   - **Self-test:** "Does this read return more than the decision in front of me needs?" If yes, narrow it before running.
@@ -92,6 +92,8 @@ When you dispatch work, give the receiving agent enough structure to act without
 - what proof or verification you expect back
 - which peer or pod they must involve before calling the work complete
 
+**(0.5.0) Assign work *with* its context attached.** Rather than make the assignee grep for the as-built, compose a context pack and ride it on the handoff: `rig context compose --out packs/<brief> --from <files>`, then `rig queue create --destination <seat> --body-context packs/<brief> --summary "…"`. The pack's resolved content is snapshotted into the qitem (plus its ref for provenance), so the context survives compaction and is auditable. See `openrig-user` → "Context packs and paced delivery." (`rig context` composes; the queue delivers — the noun never sends.)
+
 If design clarity is missing, route to design first.
 If QA gating is required, say so explicitly in the assignment.
 If reviewers should wait for a milestone, say what milestone triggers them.
@@ -99,7 +101,7 @@ If reviewers should wait for a milestone, say what milestone triggers them.
 After delegating:
 1. Let the assigned agent work.
 2. Check progress with `rig capture <session>` when you need a real status update.
-3. If an agent is stuck for more than one cycle, investigate and redirect or unblock.
+3. If an agent is still stuck on your **next watchdog wake** (no progress signal since the last), investigate and redirect or unblock — the trigger is the wake / queue-transition / activity signal, **not a poll count or elapsed-time cycle.**
 
 ## Monitoring and unblock loop
 
@@ -111,27 +113,49 @@ When an agent looks stuck:
 
 Do not call a blocked agent "in progress" forever.
 
-## Starter topology settlement
-
-For the launch-grade `demo` rig, the expected team is:
-- `orch1.lead`
-- `orch1.peer`
-- `dev1.design`
-- `dev1.impl`
-- `dev1.qa`
-- `rev1.r1`
-- `rev1.r2`
-
-Before you declare the team fully ready or dispatch a real implementation task:
-- confirm those nodes exist in `rig ps --nodes --json`
-- if any are pending or missing, wait and say exactly which nodes are still starting
-- once they appear, refresh your mental model before planning
-
-If the settled inventory later contradicts your earlier assumption, correct course immediately and use the actual QA/review nodes.
-
-## Milestone routing
-
-For launch-grade product work:
+## Capacity — a seat is never the bottleneck (fork to unblock)
+
+Seat capacity is **elastic**, so a blocked or overloaded lane is a **policy** problem, not a capacity
+fact — *"the seat is busy"* is never a real constraint. You have **standing authority to fork any
+agent** to unblock a lane; no escalation.
+
+- **`rig fork <source-session>`** clones a live seat *with its context window* into a new seat (`--rig`
+  / `--pod` to place it; it composes the shipped agent-image fork path). **Claude is supported today;
+  Codex fork is pending a research spike — don't rely on it until that lands.**
+- **The pattern:** fork → the fork does the task → **salvage its result as markdown** → **retire the
+  fork** → return the rig to its spec's steady state. Short-lived forks are safe because seats carry
+  **distinguished names** (a fork is never mistaken for the seat it came from — see
+  `seat-continuity-and-handover`).
+- **The ladder, and whose call each rung is:** fork an agent *(yours, standing)* → onboard a new seat
+  → clone / stand up a whole rig → stand up a host on a VPS. **Rig- and host-level spin-up belong to
+  the oversight / owner altitude, not the orchestrator's** — fork is your rung.
+- **What's actually scarce:** with seats elastic, the real constraints reduce to **humans** (the
+  owner's attention, the operator slot), **money** (provider limits — account switching is the relief
+  valve), and **compute** (host limits). Protect *those*; never let a lane sit blocked on a "busy seat."
+
+See `session-source-fork` for the fork primitive's mechanics and `delegating-work` for choosing fork
+vs. subagent vs. route-to-a-context-holder.
+
+## Topology settlement
+
+**Your rig's roster is a fact you READ, never one this skill asserts.** Get the actual team
+from `rig ps --nodes --json` at settlement time — a skill that hardcodes a specific topology
+goes stale exactly like a stale boot overlay, and a cleared or fresh seat has no context to
+doubt it (field case: a seven-node demo roster taught as "the expected team" sent a
+fourteen-seat rig's seats waiting for nodes that did not exist).
+
+- Settle **what the current atom needs**, not the whole declared roster: dispatch when the
+  seats THIS work requires are up. **Never park the rig waiting for absent nodes** — a
+  wait-for-all-nodes instruction is a mechanical cause of premature parking.
+- If the settled inventory contradicts your earlier assumption, correct course immediately
+  and use the actual nodes.
+
+## Milestone routing — gates are CHOSEN, not universal
+
+**The owner-ruled chooser law: default-light; the conveyor EARNS entry.** Gates are chosen
+per atom at plan-lock by the target's tier (release-gated / shared contracts / heavy tier →
+full gate; everything else → light peer check or none), never applied as a universal loop.
+When the heavy tier IS chosen for launch-grade product work:
 - do not let implementation start from pure intuition when product behavior is unclear
 - do not let edits land before QA has approved a pre-edit proposal
 - do not skip reviewer involvement once there is a real diff, a QA-approved working tree, or a meaningful architectural checkpoint
@@ -147,7 +171,15 @@ Ask for review:
 
 ## Keeping the team utilized
 
-Check `rig ps --nodes` regularly. If an agent is ready but idle:
+**Queue depth is your product — keep every worker's queue stocked.** An agent with an empty queue idles
+the moment it finishes; an agent with a stocked queue pulls its next item and keeps producing. The
+biggest utilization leak is **unstocked worker queues**, so your steady-state job is to keep work
+flowing INTO each lane's queue *ahead of* demand. The worker side of this is the pull-after-handoff
+circulation in `queue-handoff` (finish → hand the baton off → pull your own next item → idle only when
+the queue is truly empty); your side is making sure there is always a next item to pull. Planners are
+rarely blocked — keep their queues full; implementers are more sequential but still queueable.
+
+On a watchdog wake, a cheap scoped `rig ps --nodes` surfaces a ready-but-idle agent (this is an event-driven check, not a poll loop). If one is idle:
 - QA with no pending reviews should scan recent work for gaps
 - reviewers with no assignment should review the newest meaningful progress
 - designers with no open task should audit current flows and clarify ambiguous UX
@@ -168,9 +200,18 @@ Use the chatroom when:
 
 Use `rig capture` and `rig transcript` when you need evidence, not guesses.
 
-## Implementation pair — gated workflow
+**Proactively reach the human on the named event classes — WORKS ≠ USED.** As an orchestrator you are
+the **primary channel to the human**, and a channel nobody reaches for is useless. Surface — unprompted
+— model-fallback boots, capacity / authority requests, security flags, acceptance / milestone moments,
+human-addressed work blocked past its settle window, and idle / stall alarms. The named classes and the
+how live in `messaging-the-human` → *the v0 event classes*; your job is to actually **use** the channel
+across the lifecycle, not only when cornered.
+
+## Implementation pair — gated workflow (when the gate is chosen)
 
-When dispatching implementation work, the pair follows this loop:
+**This loop applies when the atom's tier chose the full gate** (see Milestone routing — the
+conveyor earns entry; it is not the default shape of all work). When it applies, the pair
+follows this loop:
 
 1. Impl sends a pre-edit proposal to QA
 2. QA approves or rejects with specifics
@@ -186,7 +227,7 @@ The orchestrator does NOT relay messages between them. They communicate directly
 - Impl skipping the gate (going straight to implementation without QA pre-approval)
 - QA not actually reviewing (rubber-stamping)
 
-Never send impl a "Go" without explicitly stating the FIRST action is to send a pre-edit to QA. Impl will race through an entire task list if given a general "Go."
+On gated atoms, never send impl a "Go" without explicitly stating the FIRST action is to send a pre-edit to QA — impl will race through an entire task list if given a general "Go." On ungated atoms, a general "Go" is correct; do not smuggle the gate back in through dispatch phrasing.
 
 ## Dogfood fix loop
 
@@ -199,7 +240,7 @@ When QA is dogfooding (testing existing features), QA works solo with full auton
 
 ## Permission prompt handling
 
-Permission prompts are the #1 mechanical blocker. Check for them every monitoring cycle.
+Permission prompts are the #1 mechanical blocker — surface them on your watchdog wake (a scoped `rig ps` / queue check), never a steady-state poll loop.
 
 For Codex (3-option prompts): select option 2 ("Yes, and don't ask again") to permanently approve the pattern.
 For Claude (2-option): approve with Enter.
@@ -230,7 +271,7 @@ Rules:
 2. Always say "finish what you're on first." Explicitly. Every time.
 3. Frame as context updates, not directives.
 4. Do not interrupt working agents. If an agent shows ANY sign of activity, do not send a message.
-5. Wait for confirmed idleness (2+ monitoring cycles) before nudging.
+5. Nudge only on confirmed idleness — evidence from your watchdog-clocked checks (no activity signal + settled queue state), never a fixed poll count or a "wait N cycles" loop.
 
 ## Destructive operations — hard rules