@openrig/cli 0.5.5 → 0.5.6

package/daemon/assets/plugins/openrig-core/skills/seat-continuity-and-handover/references/apprentice-successor-seat-cutover.md

@@ -0,0 +1,256 @@
+# Apprentice-Successor Seat Cutover SOP
+
+Status: operator-proven on 2026-08-28; curated on 2026-08-30 with the physical-seat correction
+
+Use this runbook after an apprentice successor has completed its install, observation,
+and acceptance gates and the authorized decision-maker has explicitly called the
+cutover. It covers the mechanical transition from the temporary successor seat to a
+stable desk seat while preserving the incumbent as wakeable memory.
+
+This SOP does not decide whether a successor is ready. The desk, owner, or other
+named authority owns that judgment. The operator owns the mechanics and proof.
+
+## Required Inputs
+
+Record these on one durable operator baton before mutation:
+
+- authoritative cutover instruction and decision-maker;
+- target rig and host;
+- stable target logical ID, node ID, and canonical session name;
+- successor logical ID, node ID, canonical session name, and exact provider resume token;
+- incumbent exact provider resume token;
+- required runtime, model, cwd, `OPENRIG_HOME`, `OPENRIG_URL`, and managed runtime `PATH`;
+- old-occupant disposition, including whether it remains wakeable;
+- duty-custody artifact or ledger entry the successor must accept;
+- queue rows or staged messages that must survive the swap;
+- receipt destinations.
+
+Do not infer a provider token from a label. Derive it from the live session record and
+corroborate it against the active provider history file.
+
+## Invariants
+
+1. The stable seat identity stays stable. Successor lineage belongs in provenance, not
+   in a suffixed live seat name.
+2. The exact accepted provider history moves. No compact, summary, fork, or accidental
+   stale-history restore is allowed.
+3. Desk authority stays frozen from the incumbent's idle acknowledgment until the new
+   occupant passes its post-cutover self-check.
+4. The incumbent remains wakeable by its exact provider token when the ruled disposition
+   is advisory reserve. Preserving the canonical physical pane does not require preserving
+   the incumbent process in that pane.
+5. A staged prompt is not durable merely because it is visible in a pane. Reconcile it
+   against the outbox or another durable source before stopping that pane.
+6. Seat binding, provider history, process environment, queue identity, and Herder
+   client attachment are separate surfaces. Verify each one.
+7. A timed-out operation is indeterminate. Read back by effect before retrying.
+
+## Phase 1: Fence And Preflight
+
+1. Claim the durable operator baton.
+2. Ask the incumbent and successor to finish their current atomic action and return to
+   idle prompts. Require explicit acknowledgments.
+3. Freeze desk actions, folds, rulings, routing, and owner-facing writes.
+4. Read the full baton and the named duty-custody artifact.
+5. Derive live state:
+
+```bash
+rig whoami --json
+rig seat status <target-seat> --json
+rig ps --nodes --rig <rig> --json
+```
+
+6. In the host database, read the latest target and successor session rows. Confirm the
+   exact successor resume token and the incumbent token.
+7. Confirm both provider history files exist and that the successor file is actively
+   written.
+8. Inspect the successor pane and durable outbox for staged-but-unsent input. Record a
+   disposition for every such input before stopping the seat.
+9. Record all Herder/tmux clients currently attached to the incumbent session.
+10. Take a bounded rig snapshot and record its ID.
+
+Stop if identity, token, model, authority, custody, or staged-input evidence disagrees.
+
+## Phase 2: Quiesce The Temporary Successor
+
+Use supported lifecycle surfaces. The correct detach verb depends on the current
+session origin:
+
+- `claimed` or `adopted`: use `rig unclaim` as prescribed by the CLI;
+- `launched`: use `rig seat stop <successor-seat>`; `rig unclaim` will correctly refuse.
+
+Run `rig seat clean` only if a remaining managed record actually needs cleaning. A
+`nothing_to_clean` result after a successful stop is acceptable.
+
+Do not use `rig down`, kill a provider, clear the provider history, or start a generic
+fresh occupant.
+
+## Phase 3: Realize The Exact Candidate
+
+Start an isolated, discoverable candidate from the exact accepted provider token. Give
+it the target seat's canonical environment from its first byte:
+
+```text
+OPENRIG_SESSION_NAME=<target-session>
+OPENRIG_NODE_ID=<target-node-id>
+OPENRIG_RUNTIME=<runtime>
+OPENRIG_HOME=<home>
+OPENRIG_URL=<url>
+PATH=<managed-runtime-bin>:<required-system-paths>
+```
+
+Launch the provider with the exact model, token, and canonical name. Put `PATH` in the
+provider process environment itself. Setting tmux session environment alone is not
+sufficient because an intervening login shell can replace it.
+
+Register or discover the candidate and record its discovery ID. Before committing,
+verify its process argv and environment directly:
+
+- exact resume token;
+- exact model;
+- canonical `--name`;
+- canonical target node and session environment;
+- `node` and `rig` resolvable from the managed runtime path.
+
+## Phase 4: Commit The Binding
+
+Run the supported handover against the discovery record:
+
+```bash
+rig seat handover <target-seat> \
+  --source discovered:<discovery-id> \
+  --reason <durable-reason> \
+  --operator <operator-seat> \
+  --json
+```
+
+Read back the result. Require:
+
+- `handover_result=complete`;
+- target node unchanged;
+- continuity outcome names the actual mode, normally `resumed`;
+- provenance points to the previous occupant;
+- a new target session row exists.
+
+Do not rename panes before this commit is durable.
+
+## Phase 5: Preserve The Physical Seat, Reconcile, And Preserve Memory
+
+The canonical tmux session, window, and pane are part of the stable seat when humans or
+agents have attached clients. Do not make those clients chase a renamed session.
+
+1. In the original canonical pane, stop only the incumbent provider process. Keep the tmux
+   session, window, and pane unchanged.
+2. Keep the incumbent's exact provider token in the lineage ledger as the cold-advisor
+   handle. It need not retain a permanently renamed tmux pane.
+3. Stop the staged successor process only after its accepted token is durable, then resume
+   that exact successor token inside the original canonical pane with the canonical name,
+   model, cwd, environment, and managed `PATH`.
+4. Reconcile the canonical target session through the supported seat surface and persist
+   the exact resume token using the audited token-input surface.
+5. Verify the canonical seat has exactly one managed occupant, the old token remains
+   wakeable, and the empty staging session is removed.
+
+Renaming the incumbent and staging sessions is a repair fallback for a run that already
+changed the physical session, never the default cutover. A resumed reserve can retain a
+boot-time canonical name in its own argv or environment; that residue does not make it the
+bound seat. Fence reserve replies in their body and treat the topology binding as authority.
+
+## Phase 6: Post-Cutover Self-Check
+
+Keep authority frozen. Ask the new occupant to derive, not assume:
+
+1. `rig whoami --json`: stable logical ID, node ID, canonical session, runtime, edges;
+2. `rig queue whoami`: canonical destination and open-row census;
+3. active provider UUID from the newest live history file;
+4. effective model from live provider records, not only the spec pin;
+5. duty-custody artifact read and accepted;
+6. all cutover-window queue rows accounted for;
+7. `command -v node` and `command -v rig` from the agent's own tool shell;
+8. a narrow hook/tool action proving no startup-environment failure.
+
+If any surface fails, preserve the exact provider UUID and repair only the disagreeing
+surface. Relaunch the same history if needed. Repeat the full self-check before
+unfreezing authority.
+
+## Phase 7: Unfreeze And Transfer Custody
+
+After a clean self-check:
+
+1. explicitly unfreeze desk authority;
+2. transfer each staged or cutover-window instruction exactly once;
+3. require the new occupant to verify the effects by read-back;
+4. notify the routing lead and incumbent reserve of completion;
+5. leave the incumbent reserve idle, uncompacted, and authority-free.
+
+## Phase 8: Verify Herder Views
+
+Clients follow the physical tmux session and pane, not the logical binding. The default
+physical-seat cutover should leave every recorded client attached to the same canonical
+pane. Read the attachments back. If a repair fallback already renamed the session, retarget
+each affected client explicitly:
+
+```bash
+rig seat switch-client <target-seat> --client <tty> --json
+```
+
+Read back all client attachments. A correct cutover can otherwise still look wrong in
+the grid or focus tab.
+
+## Completion Proof
+
+The receipt must include:
+
+- operator baton and authority source;
+- snapshot ID;
+- stable and temporary node IDs;
+- old and new provider UUIDs;
+- discovery, handover, and final session IDs;
+- final process argv and critical environment;
+- `rig seat status` result;
+- target and successor inventory states;
+- queue-row reconciliation;
+- staged-input disposition and effect proof;
+- reserve pane/name/token and fence;
+- Herder client attachments;
+- new occupant's self-check and first verified desk acts;
+- deviations, failed attempts, and remaining product gaps;
+- receipt path and SHA-256.
+
+Close the baton only after the receipt exists and the new occupant has performed at
+least one authority-bearing act verified by effect.
+
+## Traps Proven In The 2026-08-28 Run
+
+- A dry-run can accept a managed successor while the live handover refuses
+  `successor_already_managed`. Quiesce the temporary seat first.
+- Generic launch/restore selection can choose an older seat history. Launch the exact
+  accepted resume token.
+- Handover can bind a candidate without stopping the incumbent. Apply the ruled
+  disposition explicitly.
+- Reconciliation can create the right session identity without carrying the resume
+  token. Persist and read it back.
+- A canonical-looking process can still have a broken tool `PATH`. Verify from inside
+  the provider's own tool shell.
+- Renaming sessions makes Herder clients follow the retired pane. Preserve the physical
+  canonical pane by default; retarget explicitly only when repairing an already-renamed run.
+- Pane input can be visible but absent from JSONL. Reconcile the durable outbox before
+  stopping the pane.
+- Reserve messages can render with the stable seat name because boot-time environment
+  survives unbinding. The reserve must self-identify and remain explicitly fenced.
+- Success output is not effect proof. Read back queue closure, binding, client movement,
+  and transferred instructions.
+
+## Productization Candidates
+
+The manual sequence identifies useful first-class product work:
+
+- handover directly from an already-managed successor seat;
+- an exact-resume-token candidate launcher;
+- first-class `advise`/memory disposition for the old occupant;
+- atomic binding plus token persistence;
+- managed environment validation before commit;
+- staged-input custody reporting;
+- verify-or-repair all Herder client attachments for a logical seat;
+- reserve attribution distinct from canonical seat attribution;
+- one receipt that reports continuity and seat-binding outcomes independently.

package/daemon/assets/plugins/openrig-core/skills/seat-continuity-and-handover/references/orchestrator-role.md

@@ -0,0 +1,40 @@
+# Orchestrator Role In Apprentice Handover
+
+The orchestrator owns the judgment boundary, not the successor's work and not the mechanic's
+keystrokes. Keep the incumbent productive, keep the successor authority-free, and keep the
+mechanic fenced until a named owner makes the one decision no instrument can derive.
+
+## The invariant floor
+
+- Prove fresh identity and the pinned model before installing context, because every later
+  receipt is about the wrong occupant if the starting history or model diverged.
+- Require the successor to derive its own layer-5 delta and have it checked, because reading
+  a deposit does not install it.
+- Enumerate standing-duty custody at every boundary, because recurring work is easiest to
+  lose while visible one-off work carries cleanly.
+- Keep the predecessor's verbatim reach-back handle and pre-formed questions, because an
+  affordance without a trigger goes unused.
+- Route mechanics through `apprentice-successor-seat-cutover.md`, because one portable SOP
+  is safer than role-local copies that drift.
+
+## Authority and gates
+
+The **word is the gate**. Until the named owner words acceptance and an effect receipt records
+it, the successor may observe, ask, and produce bounded evidence but may not act as the stable
+seat. G0–G3 are a useful receipt vocabulary when the succession uses that model; a declared
+simpler model is valid when stakes do not earn all four. Missing records and deliberately
+skipped gates must remain distinguishable.
+
+The apprenticeship is a conversation, not a gauntlet. Choose evidence whose rigor matches the
+cost and reversibility of a wrong succession. Never turn the experiment apparatus into culture.
+
+## Before routing cutover
+
+Confirm the owner word, gate receipts or declared simpler model, complete deposits, explicit
+duty custody, reserve disposition, exact successor token, and one-active-walker ownership.
+Create an owned mechanic baton; awareness-only is not custody. The baton may prepare and prove,
+but it never auto-rebinds.
+
+After the mechanic reports effect, verify READY from source: canonical seat identity, current
+model, current generation, canonical tmux pane, queue census, duty acceptance, and usable width.
+Only then unfreeze authority.

package/daemon/assets/plugins/openrig-core/skills/software-for-agents/SKILL.md

@@ -1,10 +1,15 @@
 ---
 name: software-for-agents
 description: |
-  Use when building, modifying, or diagnosing an OpenRig or studio-box system; when surprising behavior
-  looks like a code bug but may come from Markdown, YAML, JSON, bootstrap files, schemas, skills, or
-  conventions; or when deciding whether an agent-built studio app needs a separate mockup phase. NOT for
-  treating defects in OpenRig core or rigs.to as tolerable control-plane drift.
+  Load this FIRST, before you assume how anything here works — especially before building, modifying, or
+  "fixing a bug" in an OpenRig or studio-box system, or when something behaves unexpectedly and you're
+  about to treat it as a code bug. You are almost certainly NOT operating in traditional software. This
+  is a self-improving MARKDOWN CONTROL PLANE: the substrate is markdown + YAML + JSON + folder structure
+  (skills, instructions, bootstrap files, schemas, conventions), and most "bugs" are coherence gaps in
+  that layer, not broken functions. Read this to form the correct mental model so your fixes land at the
+  precise spot that stops the footgun for every future rig — not just patch a symptom. It also covers why STUDIO APPS skip the mockup phase — for an agent-built app the build is as fast as the mockup, so the PRD is the fleshed intent (velocity as method, not a quality waiver). NOTE: the
+  bug-tolerance in this model is SCOPED to agent-managed software; the OpenRig core and rigs.to stay
+  rock-solid — see the scope block up top before you apply anything here.
 metadata:
   openrig:
     stage: factory-approved

package/daemon/assets/vm-preview-fixtures/README.md

@@ -1,48 +1,26 @@
 # VM Preview Fixtures
 
-Sample data the Tart preview VM uses to populate the "populated" daemon with
-a representative "lived-in" environment. See
-`<substrate-shared-docs>/openrig-work/conventions/vm-preview/README.md` for the
-operator workflow and the rationale behind the two-daemon model.
+Sample data used by the Tart preview environment to give one OpenRig daemon
+representative content while a second daemon remains empty for comparison.
 
 ## Contents
 
-- `workflows/` — workflow_spec YAML files. The operator copies these into the
-  populated daemon's `<workspace.specs_root>/workflows/` directory; slice 11's
-  folder-discovery scanner auto-discovers them on the next
-  `GET /api/specs/library` call.
+- `workflows/` — public example workflow specifications. The basic-loop sample
+  demonstrates a complete intake-to-close handoff without depending on a
+  private rig or machine.
 
-- `queue-items/` — placeholder for future qitem fixture content (TODO; slice
-  follow-up will add).
+## Use
 
-- `rigs/` — placeholder for future rig-instance fixtures (TODO; slice
-  follow-up will add). For v0, the operator manually instantiates a sample
-  rig via `rig up product-team` against the populated daemon (see bootstrap
-  script).
+Run `scripts/vm-bootstrap/two-daemon-start.sh`, then copy the workflow YAML
+files into the populated daemon's configured `<workspace.specs_root>/workflows/`
+directory. The daemon discovers them on the next workflow-library listing.
 
 ## Conventions
 
-Fixture YAML files use the canonical placeholder paths per banked
-`feedback_test_fixture_example_path_placeholder.md`:
-
-- Username-bearing paths: `/Users/example/...` (never a real contributor
-  username)
-- Substrate-relative refs: `<substrate-shared-docs>/...`
-
-## v0 scope
-
-Slice 22 (release-0.3.1) ships the INFRASTRUCTURE for the two-daemon model:
-
-- **Process-env pattern**: `OPENRIG_HOME=<dir> rig daemon start ...` — each
-  `rig` invocation gets its own state directory at process import time.
-  No CLI flag (an earlier attempt at `--openrig-home` was dropped because
-  it only threaded into the spawned child, not the parent-side lifecycle
-  bookkeeping; see substrate convention doc for the architecture note).
-- Bootstrap script (`scripts/vm-bootstrap/two-daemon-start.sh`)
-- This fixtures directory + a sample workflow YAML
-- Convention doc in substrate
-
-Authoring rich populated content (~13-node openrig-velocity rig + 20 qitems
-+ getting-started mission narrative) is deferred to follow-up content slices
-that have clearer ownership (slice 21 onboarding-conveyor will likely
-contribute getting-started mission content).
+- Use `/Users/example/...` for username-bearing paths.
+- Use symbolic configuration paths such as `<workspace.specs_root>` instead of
+  machine-specific locations.
+- Use generic logical roles and IDs rather than concrete session, host, or rig
+  instance addresses.
+- Describe the product behavior the fixture demonstrates; omit release history,
+  internal ownership, and implementation planning.

package/daemon/assets/vm-preview-fixtures/workflows/sample-basic-loop.yaml

@@ -1,8 +1,7 @@
-# VM-preview fixture for slice 22 founder-walk-vm-populated-env.
-# Derived from the 0.3.0 basic-loop starter; renamed to avoid colliding
-# with the built-in spec when this fixture file is dropped into a
-# populated daemon's workspace.specs_root/workflows/ directory.
-# Slice 11's folder-discovery scanner auto-discovers it on next list.
+# Example workflow for the populated VM preview.
+# Its distinct ID avoids colliding with the built-in basic-loop specification
+# when copied into the populated daemon's configured workflows directory.
+# The daemon discovers it on the next workflow-library listing.
 workflow:
   id: vm-preview-basic-loop
   version: 1

package/daemon/context-packs/onboarding-width/manifest.yaml

@@ -1,6 +1,9 @@
 # Public capability and source-map width for the default onboarding walk.
 name: onboarding-width
-version: "0.5.5"
+version: "0.5.6"
+# OPR.0.5.6.10 — affordances knowledge (what this system can do) is world
+# content under the coining-session definitions.
+taxonomy: world
 purpose: "The public capability map and source map referenced by the default onboarding walk."
 files:
   - path: public-what-you-can-do.md

package/daemon/context-packs/onboarding-width/public-reference-material.md

@@ -57,7 +57,7 @@ library actually does today, anything that changed after your training cutoff, w
 world rather than in this repo.
 
 **And the failure is the same one this page already warns about, pointed outward.** An agent that
-does not know the corpus exists invents instead of looking. An agent that does not know these exist
+does not know the external sources below exist invents instead of looking. An agent that does not know these exist
 **answers from its training snapshot and states it as current** — and an invented answer and a
 known one look identical once you have stated one.
 

package/daemon/context-packs/skills/core/agent-starters/manifest.yaml

@@ -1,7 +1,8 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "agent-starters"
-version: "0.5.5"
+version: "0.5.6"
+taxonomy: "skills"
 purpose: "Use when creating, refreshing, packaging, inspecting, promoting, or deprecating a named per-seat starting point — Agent Starter manifest authoring, the 6-state lifecycle (captured → named → inspectable → used → promoted → deprecated), provenance honesty, and refusal rules. NOT a VM image; a managed starting point composed from agent role + startup context + optional native session source + provenance."
 files:
   - path: "SKILL.md"

package/daemon/context-packs/skills/core/agent-startup-and-context-ingestion/SKILL.md

@@ -102,7 +102,7 @@ culture / pod / member / operator) handles the layering.
 
 ## See also
 
-- `mission-slice-sop` skill — the universal operating procedure for working a mission/slice (the canonical SPEC.md, NOTES.md, PROGRESS.md, PROOF.md, and proof/ surfaces); every agent should reach for it at startup, so this general reading contract points at it here (do NOT duplicate the SOP into seat-specific startup files).
+- `mission-slice-sop` skill — the universal operating procedure for working a mission/slice (the canonical PROGRESS/PROOF/MISSION_NOTES/MISSION_BRIEF files); every agent should reach for it at startup, so this general reading contract points at it here (do NOT duplicate the SOP into seat-specific startup files).
 - `writing-skills-for-openrig` skill — authoring discipline for skill content (what doesn't belong in startup)
 - `forming-an-openrig-mental-model` skill — orientation for new agents
 - `session-compaction-and-restore` skill — restore-time startup ingestion

package/daemon/context-packs/skills/core/agent-startup-and-context-ingestion/manifest.yaml

@@ -1,7 +1,8 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "agent-startup-and-context-ingestion"
-version: "0.5.5"
+version: "0.5.6"
+taxonomy: "skills"
 purpose: "Use when designing or auditing how an agent becomes useful after launch — AGENTS.md overlays, role files, skills, rig specs, workflow specs, startup checklists, refocus messages, \"rig context\" surface. Covers the 4 failure modes that make startup context fail (old rig spec misses current operating mode; current agents never told about new guidance; startup file as dumping ground; orchestrator transmits implementation without preserving product intent)."
 files:
   - path: "SKILL.md"

package/daemon/context-packs/skills/core/cross-host-rig-commands/SKILL.md

@@ -30,11 +30,8 @@ operator pattern (`ssh <host> rig <cmd>`) with declared host identity,
 explicit cross-host invocation path, preserved `--verify` semantics, and
 4 named failure modes.
 
-**Current-host note (2026-07-14):** this skill still preserves the original
-SSH-v0 doctrine below, but the live host registry may also contain HTTP
-read-through/tunnel entries such as `your-vm` and `your-other-vm`. Use the
-host registry entry as ground truth for transport shape, and use
-`conventions/multi-host-naming/README.md` for host-id naming. HTTP entries
+The live host registry may contain SSH or HTTP read-through/tunnel entries.
+Use each registry entry as ground truth for transport shape. HTTP entries
 require `url` plus exactly one of `bearer_file` or `bearer_env`.
 
 **v0 is CLI-side shell-out only — `packages/daemon/` is NOT touched.**
@@ -73,24 +70,20 @@ differs from the interactive verbs (`send`/`capture`/`ps`/`whoami`):
 
 ## Host registry shape (`~/.openrig/hosts.yaml`)
 
-Host ids should follow the OpenRig-work multi-host naming convention:
-`conventions/multi-host-naming/README.md`. In this environment that means
-physical hosts such as `your-vm`, local OpenRig development VMs such as
-`your-vm`, persistent product VMs such as `your-other-vm`, and VPS hosts such
-as `your-vps`. Keep old aliases during migration until no live routing
-depends on them.
+Host ids must be non-empty and unique. Choose stable, operator-meaningful ids
+that describe the destination without depending on transient network details.
 
 ```yaml
 hosts:
   - id: a-test-vm
     transport: ssh                       # v0 supports "ssh" only
     target: a-test-vm.local         # DNS name, SSH config alias, or IP
-    user: wrandom                        # optional
+    user: example-user                   # optional
     notes: "Tart VM"                     # optional
   - id: laptop-b
     transport: ssh
     target: laptop-b.tail-scale-net
-    user: wrandom
+    user: example-user
 ```
 
 Validation rules:

package/daemon/context-packs/skills/core/cross-host-rig-commands/manifest.yaml

@@ -1,7 +1,8 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "cross-host-rig-commands"
-version: "0.5.5"
+version: "0.5.6"
+taxonomy: "skills"
 purpose: "Use when issuing `rig` commands against a remote host via `--host <id>` flag (single-hop SSH to a host declared in `~/.openrig/hosts.yaml`). Covers the 4 structured failure modes (ssh-unreachable / permission-gate / remote-daemon-unreachable / remote-command-failed), the `--verify` honest pass-through (SSH success is NOT verify success), and the host-registry shape. v0 supports `rig send / capture / ps / whoami --host <id>`."
 files:
   - path: "SKILL.md"

package/daemon/context-packs/skills/core/human-in-the-loop/manifest.yaml

@@ -1,7 +1,8 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "human-in-the-loop"
-version: "0.5.5"
+version: "0.5.6"
+taxonomy: "skills"
 purpose: "Use when classifying a slice closeout (auto-continue / human gate / park), routing a real decision to a human, or designing a human queue/dashboard surface. Treats humans as durable network participants with attention surfaces, queues, and decision records — escalation lands as a durable attention item, not a chat message. Approval is NOT required for every clean closeout; the default RSI conveyor continues unless an explicit human gate is reached."
 files:
   - path: "SKILL.md"

package/daemon/context-packs/skills/core/messaging-the-human/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: messaging-the-human
+description: "Use when a human decision, access grant, external action, or escalation must survive the operator's absence, or when an orchestrator or PM has a judgment-worthy update for the operator."
+metadata:
+  cli_surfaces_referenced:
+    - gateway human add
+    - gateway human list
+    - queue block
+    - queue handoff
+    - queue transitions
+    - send
+  openrig:
+    stage: provisional
+    audience: all agents
+    sibling_skills:
+      - queue-handoff
+      - human-in-the-loop
+      - openrig-user
+---
+
+# Messaging the Human
+
+The human is an addressable participant, but their attention is scarce and they
+may not be at a terminal. Anything that must survive their absence needs a
+durable queue row; the gateway turns the human blocker on that row into the
+external notification.
+
+Any seat may contact the human directly for a real escalation. Orchestrators
+and product managers may also send updates they judge the human would want to
+know. Do not add a routing intermediary merely because of your role.
+
+## The supported route
+
+First discover the registered human identity. Never invent or remember an
+address:
+
+```bash
+rig gateway human list --json
+```
+
+Use `humans[].entityId` to derive the durable blocker as `<entityId>@host`.
+The entity id must use the human-seat prefix (`human` or `human-...`); if it
+does not, stop and repair the registration rather than guessing. The returned
+`humans[].address` is the gateway delivery address, not the `--on` value. If no
+unambiguous registered human is returned, stop: registration is lifecycle work
+(`rig gateway human add --help`), not an address to guess.
+
+Keep the work row owned by the agent who must resume it, then park that row on
+the registered human:
+
+```bash
+rig queue block <qitem-id> --on <entityId>@host \
+  --summary "<decision owed>" \
+  --evidence-ref "<durable artifact the human should judge>" \
+  --continuation "<what resumes after the answer>"
+```
+
+The gateway resolves the registered human to the configured connector, sends
+the Slack notification, and records its receipt on the same row. Confirm the
+effect from the append-only history:
+
+```bash
+rig queue transitions <qitem-id>
+```
+
+The row is the obligation and the audit trail. Slack is the attention leg. A
+reply resolves the durable blocker and wakes the row owner; it does not create
+a second private work stream.
+
+## When to use it
+
+Escalate directly when only the human can supply the missing capability:
+
+- a decision or irreversible judgment only they own;
+- access, credentials, authority, or capacity only they can grant;
+- an external action only they can perform;
+- a security-class or provider/model-fallback event they need to know about.
+
+Orchestrators and product managers may additionally send meaningful milestone,
+environment, or completion updates. Prefer signal over routine narration.
+
+## Boundaries
+
+- `rig send` sends text to an agent's terminal. It is not the Slack route and
+  does not create a durable human obligation.
+- An unregistered or ambiguous human identity must fail loudly. Register or
+  repair the identity; never downgrade it to an agent seat or a guessed
+  `@external` address.
+- Agent-to-agent work that needs closure uses `rig queue handoff`, not this
+  human-blocker path.
+- Deferred work that is not imminent belongs in the mission workspace, not on
+  the queue.
+
+## Writing the escalation
+
+Lead with what is blocked and the exact decision or action needed. Point at the
+durable evidence instead of pasting a second copy, and name the continuation so
+the system can resume the right work when the answer arrives.

package/daemon/context-packs/skills/core/messaging-the-human/manifest.yaml

@@ -0,0 +1,10 @@
+# GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
+# Package-time projection of a canonical skill; regenerated every build.
+name: "messaging-the-human"
+version: "0.5.6"
+taxonomy: "skills"
+purpose: "Use when a human decision, access grant, external action, or escalation must survive the operator's absence, or when an orchestrator or PM has a judgment-worthy update for the operator."
+files:
+  - path: "SKILL.md"
+    role: "instruction"
+    summary: "Use when a human decision, access grant, external action, or escalation must survive the operator's absence, or when an orchestrator or PM has a judgment-worthy update for the operator."

package/daemon/context-packs/skills/core/openrig-architect/manifest.yaml

@@ -1,7 +1,8 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "openrig-architect"
-version: "0.5.5"
+version: "0.5.6"
+taxonomy: "skills"
 purpose: "Use when designing multi-agent topologies that run ON OpenRig — authoring RigSpec and AgentSpec files for new rigs, creating agent startup content (guidance / skills / culture), or diagnosing why a launched rig's agents aren't behaving as intended. NOT for changing OpenRig itself (use openrig-builder); NOT for ordinary CLI operation of an existing rig (use openrig-user). Covers the full authoring lifecycle from user intent to validated, launchable rig."
 files:
   - path: "SKILL.md"