@openrig/cli 0.5.9 → 0.5.11

package/daemon/specs/agents/shared/skills/core/agent-startup-and-context-ingestion/SKILL.md

@@ -24,8 +24,7 @@ metadata:
 
 How an agent becomes useful after launch: **AGENTS.md overlays, role
 files, skills, rig specs, workflow specs, startup checklists, refocus
-messages**, and any future "rig context" command or skill-librarian
-surface.
+messages**, and the current `rig context` retrieval and profile surface.
 
 It is the current concrete startup path inside the broader
 context-engineering-and-retrieval primitive. Startup gets a seat into
@@ -58,13 +57,28 @@ is scattered or stale, agents execute the wrong thing very efficiently.
 3. **A startup file becomes a dumping ground and loses the map-to-canonical-sources role.** Startup should point AT canonical sources; it shouldn't TRY to be one.
 4. **The orchestrator transmits implementation instructions without preserving product intent.** Instructions decay; intent travels.
 
-## Proof standard
+## Task-scoped startup
+
+Run `rig whoami --json`, then resolve `project.yaml -> mission.yaml -> active
+slice.yaml -> selected component or wave map -> addressed context`. The complete
+lookup and precedence rule is `docs/reference/product-journey-sdlc.md#resolve-the-selected-path`
+(installed: `$OPENRIG_HOME/reference/product-journey-sdlc.md#resolve-the-selected-path`).
+Read the selected addresses and source needed for this task; skills available in
+your profile are capabilities, not a mandatory reading list. No composition means
+light Part A. Role names and idle seats add no gates. Explicit rigor and authored
+wave boundaries retain their named checks.
 
-Startup proof should:
+Startup files are address maps, not universal reading mandates. Do not preload
+unrelated planning/review doctrine or require per-file ACKs and quizzes. Skill
+availability is distinct from loading its full body. An old packet does not choose
+the current work. Missing selected context is a named gap to resolve.
 
-1. **Launch or refresh** a seat
-2. **Inspect** what it actually read
-3. **Verify** it can state the current role, mode, active constraints, and next handoff convention **in its own words**
+## Proof standard
+
+In a disposable fresh session, observe the actual reads and resulting next action.
+Test no-selection, explicit rigor, and wave-boundary cases. An edit is not evidence
+that an already-running seat adopted it; adoption needs an authorized refresh or
+next-launch observation. Do not clear or re-prime a live seat merely to test prose.
 
 ## Cross-runtime startup paths (5; do not collapse)
 
@@ -76,14 +90,16 @@ reentry case, distinct from reusable Agent Starters / priming packs):
 
 ## Memory surfaces consumed at startup
 
-Per the externalized-memory-surfaces convention's 13-row inventory:
-
-- **Row 7** — AGENTS/role/CULTURE/startup overlays (primary)
-- **Row 3** — startup replay context (primary)
-- **Row 12** — restore/reentry packets and Agent Starters (cross-runtime startup path)
+Inventory the selected startup inputs: AGENTS/role/CULTURE overlays, replay
+context, and any declared restore packet or starter. Record where each comes
+from, whether it is current, and why this task needs it. An available skill or
+old packet does not select the work.
 
-The umbrella's authority-rank + permission-posture columns govern which
-surfaces a startup ingestion path can write vs only read.
+Use the task-scoped startup path above to resolve current authority. Permission
+to read an input is not permission to rewrite its source; writes follow the
+active project/rig policy and assignment. Load
+`skills/openrig-operating-model/SKILL.md` with `rig context get` when deciding
+where durable context belongs.
 
 ## Startup files vs skills (the distinction)
 
@@ -102,11 +118,11 @@ 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` — load when starting assigned mission/slice work; the light artifact and handoff procedure for SPEC.md, NOTES.md, PROGRESS.md and proof. It does not choose the SDLC for the task.
 - `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
 - `agent-starters` skill — reusable starter manifests that compose startup context
 - `composable-priming-packs` skill — manifests that produce primed sessions
-- `externalized-memory-surfaces` skill — umbrella convention for memory surfaces this primitive consumes
+- `openrig-operating-model` skill — placement and authority of durable context
 - `openrig/docs/reference/agent-startup-guide.md` (product reference doc; not a skill) — the 7-layer additive startup model + delivery hints

package/daemon/specs/agents/shared/skills/core/cross-host-rig-commands/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: cross-host-rig-commands
-description: 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>`.
+description: Use when addressing a registered remote OpenRig host, choosing its transport, or interpreting a cross-host result.
 metadata:
   cli_surfaces_referenced:
     - capture
     - daemon start
     - host list
-    - host show
+    - host add
+    - host doctor
     - ps
     - send
     - whoami
@@ -22,167 +23,102 @@ metadata:
       - extension-and-user-workspace
 ---
 
-# Cross-Host Rig Commands
+# Cross-host rig commands
 
-A first-class OpenRig surface for issuing `rig` commands against a
-remote host via single-hop SSH. v0 productizes the existing SSH-envelope
-operator pattern (`ssh <host> rig <cmd>`) with declared host identity,
-explicit cross-host invocation path, preserved `--verify` semantics, and
-4 named failure modes.
+Use a registered host address and the entry's declared transport. SSH entries
+run a remote CLI through a single-hop shell; HTTP entries use the remote daemon.
+These paths have different prerequisites and command coverage. Check the exact
+command's help and the target installation before a consequential operation.
 
-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`.
+## Choose and inspect the destination
 
-**v0 is CLI-side shell-out only — `packages/daemon/` is NOT touched.**
-The remote host has its own managed `rig` available on `$PATH`.
-
-## Use this when
-
-- Driving a Tart VM from the host (the immediate cross-host consumer)
-- Operating Mac host A against Mac host B
-- Reading remote state via `rig ps --host` / `rig whoami --host`
-- Sending or capturing on a remote rig session (`rig send/capture --host <id>`)
-- Authoring a `~/.openrig/hosts.yaml` registry entry
-
-## Don't use this when
-
-- The target is local. Don't pass `--host` for local commands.
-- You need multi-hop SSH (host A → host B → host C). v0 is single-hop only.
-- You want reverse direction (remote initiates back to local). v0 is originator-pull only.
-- Cross-host **seat handover** (moving a durable owned seat across hosts) — deferred to higher-level primitives. (Cross-host **queue writes**, by contrast, now ship — see "Cross-host queue writes" below.)
-- The transport isn't SSH. v0 supports `transport: ssh` only.
-
-## Cross-host queue writes (updated 2026-07-21 vs main d37a08ad)
-
-Cross-host **queue writes** are no longer deferred — they ship — but the rule
-differs from the interactive verbs (`send`/`capture`/`ps`/`whoami`):
-
-- **Queue writes are EXPLICIT-only.** Address the target host explicitly with
-  `--host <id>` or the `member@rig@<host>` form. A queue write **never** follows a
-  persisted host selection.
-- **`host select` stickiness does NOT apply to queue.** `host select` affects the
-  `resolveEffectiveHost` verbs (`send`/`capture`/`ps`/`whoami`) — those follow the
-  selected host — but a queue write ignores it and requires explicit addressing.
-- **Host address parsing differs** between the interactive verbs and the queue
-  verbs; do not assume the interactive form carries over. When unsure, address the
-  host explicitly.
-
-## Host registry shape (`~/.openrig/hosts.yaml`)
-
-Host ids must be non-empty and unique. Choose stable, operator-meaningful ids
-that describe the destination without depending on transient network details.
+`rig host list` shows registered hosts. `rig host add --help` describes registry
+writes; `rig host doctor --help` describes reachability checks. Inspect the
+configured OpenRig home rather than assuming the default `~/.openrig/hosts.yaml`.
+Registry changes affect later routing, so make them within the requested scope.
 
 ```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: example-user                   # optional
-    notes: "Tart VM"                     # optional
-  - id: laptop-b
+  - id: test-vm
     transport: ssh
-    target: laptop-b.tail-scale-net
+    target: test-vm.local
     user: example-user
+  - id: remote-dev
+    transport: http
+    url: http://remote-dev.example:7433
+    bearer_env: REMOTE_RIG_TOKEN
 ```
 
-Validation rules:
+The registry requires a hosts array, unique non-empty ids and a supported
+transport. SSH needs a non-empty target; user and notes are optional. HTTP needs
+a URL and accepts at most one of bearer_env or bearer_file. Omitting both is
+valid for a tokenless target. A configured but unavailable bearer is a permission
+failure, not anonymous fallback. Host ids also have reserved-name validation;
+use the actual validator's error rather than inventing an alias that collides.
 
-- `hosts` required, non-null array
-- Each entry: `id` required (non-empty, unique), `transport` required (`ssh` only), `target` required
-- `user` and `notes` optional
-- Operator-managed file; v0 does NOT include any sub-command to add/remove/list hosts (operators edit YAML directly)
-- Missing or invalid file returns a clear error pointing at the canonical path
-
-## CLI surface (v0 shipped)
+## Address the intended operation
 
 ```bash
-rig send <session> "msg" --host <id> --verify
-rig capture <session> --host <id>
-rig ps --host <id> [--nodes] [...]
-rig whoami --host <id>
+rig send dev-worker@example-rig "check the assigned result" --host remote-dev --verify
+rig capture dev-worker@example-rig --host remote-dev
+rig ps --host remote-dev --nodes --json
+rig whoami --host remote-dev
 ```
 
-Forwards every shaping flag (`--nodes`, `--full`, `--limit`, `--fields`,
-`--summary`, `--filter`, `--json`) to the remote `rig` invocation. The
-remote rig's output is verbatim passthrough on success.
-
-## The 4 structured failure modes (load-bearing API contract)
-
-The CLI distinguishes 4 failure modes; operators get an actionable error
-per mode; JSON output preserves the `failedStep` enum:
-
-| Mode | Cause | Action |
-|---|---|---|
-| `ssh-unreachable` | SSH itself failed (connection refused, host key mismatch, DNS failure, timeout) | Verify SSH access and the registry entry |
-| `permission-gate` | SSH hit auth/permission gate (Permission denied, Keychain) | Error includes hint to keychain-over-SSH field note (L4-3 D6) |
-| `remote-daemon-unreachable` | SSH succeeded but remote `rig` reported the remote daemon was not reachable | `ssh <target> rig daemon start` |
-| `remote-command-failed` | SSH succeeded but remote `rig` exited non-zero for some other reason; remote stderr is surfaced | Read remote stderr; debug remote command |
-
-Each is distinct and routable. Don't conflate them.
-
-## `--verify` honest pass-through (load-bearing)
-
-`--verify` against a remote target must:
-
-- **Propagate** the verification request to the remote daemon (or remote `rig` invocation that talks to it)
-- **Bring back a structured verification result** (true/false + reason if false), NOT just SSH exit code 0
-- **Distinguish "SSH succeeded but verify returned false" from "SSH itself failed"** — these are different operator actions
-
-**SSH success is NOT verify success.** The remote rig is authoritative
-on `--verify`; its `Verified: yes/no` line is surfaced verbatim. Verified
-at 3 layers (executor unit, command integration, source impl).
-
-## Hard boundaries (do-not list)
-
-- **Do NOT collapse `--verify` honest result into SSH exit code.** Operators and agents rely on the distinction.
-- **Do NOT silently retry SSH failures inside the primitive.** Surface them; let the caller decide.
-- **Do NOT introduce non-SSH transports in v0.** Goal is productizing the existing shipped pattern, not replacing it.
-- **Do NOT touch host-side daemon code as part of v0.** Cross-host shape is on the originator side.
-
-## Cross-host annotation
-
-Every cross-host invocation is observable as cross-host:
-
-- **Operator output**: `[via host=<id> (<target>)]` annotation
-- **JSON output**: `cross_host: { host, target }` field
-
-Annotation is PRESENT when `--host` is set and ABSENT otherwise
-(compat regression).
-
-## Currently shipped (v0) vs deferred
-
-Shipped at openrig `cdce3a6` (2026-04-30):
-- `--host <id>` flag on `rig send / capture / ps / whoami` (initial 2 commands; promoted to 4 at `6b7043a` same day)
-- Read-only host registry validation
-- Single-hop SSH executor with 4-mode `failedStep` enum
-- `--verify` honest pass-through
-- Cross-host annotation (operator + JSON)
-- Daemon untouched
-
-Deferred:
-- Tier 2 real-runtime cross-host proof (disposable Tart VM cycle)
-- `rig host list / show` read-only sub-namespace (only if host count grows past comfortable manual editing)
-- Non-SSH transports
-- Multi-hop SSH
-- Reverse direction (remote initiates)
-- Connection pooling/caching
+These coordination commands select SSH or HTTP from the registry entry. They
+do not silently try another transport when one fails. A host-qualified target
+can be convenient, but confirm its parsing and any persisted host selection
+with the particular command. Explicit --host is preferable for consequential
+cross-host work.
+
+Queue destinations use explicit --host or a supported host-qualified destination;
+queue writes do not follow persisted host selection. The CLI separates the host
+from the canonical seat in the routing envelope. Different queue subcommands
+have different flags: check their help instead of copying a flag from send.
+A local success message alone does not establish remote persistence or pickup.
+
+## Read failures at the layer that failed
+
+| Signal | What to inspect |
+|---|---|
+| registry-load-failed / unknown-host | Registry path, entry and exact destination |
+| ssh-unreachable | SSH connection, target and transport diagnostics |
+| permission-gate | The configured SSH or HTTP credentials and target policy |
+| remote-daemon-unreachable | Target listener and actual running daemon identity |
+| remote-command-not-found | Remote CLI installation and executable lookup |
+| remote-command-failed | The remote operation's own status and error |
+
+The exact result taxonomy depends on the path. HTTP failures expose the remote
+status/error; SSH distinguishes the shell transport from the remote command.
+Do not start or replace a remote daemon merely because a diagnostic suggests it;
+first establish the target's state and the authority for that lifecycle action.
+A timed-out write may have reached its destination. Reconcile its durable effect
+before retrying.
+
+## Verification and attribution
+
+Transport success is not delivery verification or agent consumption. SSH forwards
+--verify and returns the remote CLI result. HTTP preserves the remote transport
+verdict and explicitly reports that the local pane-effect check did not run
+cross-host. Inspect that result and the destination effect required by the task;
+never replace it with “SSH exited zero” or “HTTP returned successfully.”
+
+Cross-host output names the host/target; JSON envelopes carry cross_host metadata.
+The precise envelope differs by command and transport. Preserve the underlying
+remote result when passing evidence onward.
+
+A target's host suffix selects a destination; a sender's origin identifies where
+a reply belongs. Use the rendered reply address and verify its host mapping.
+Current send derives the sender from the executing seat context, not a caller's
+--from assertion. It adds origin-host identity at cross-host forwarding; do not
+assume local sends have the same suffix. Unknown identity remains unknown.
+
+This guide describes the implemented command paths, not proof of a live remote
+journey on your installation. Forks, handovers and other lifecycle compositions
+need their own supported command and scoped authority; reading remote state
+does not authorize them.
 
 ## See also
 
-- `seat-continuity-and-handover` skill — host-aware seat-binding semantics for cross-host handover (deferred to v1 on top of this v0 baseline)
-- `openrig-user` skill — the local CLI surface that cross-host commands wrap
-
-## Sender identity carries the ORIGIN host (51-09, 2026-08-06)
-
-The `@host` sugar on a TARGET is **addressing** (`member@rig@<host>` routes to that host).
-The **From:** sender now ALWAYS carries the **origin** host: a cross-host (and local) message's
-signature is **`member@rig@<originHost>`** — the sender reflects the host it was sent from, so a
-received signature names the ORIGIN, and the `↩ Reply:` hint round-trips **verbatim** back to that
-origin (never a same-named local lookalike). This is the always-suffix rule — deterministic and
-collision-proof: a signature means one thing to every receiver. (This SUPERSEDES the pre-51-09
-asymmetry — "the sender carries no `@host` suffix" — that pm@your-rig flagged as a core gap on
-2026-07-25; 51-09 closed it.) Per BR-1 the host is NEVER folded into the session string on the
-wire: the CLI edge renders/strips it, the daemon refuses an in-band 3-part destination with a
-teaching hint, and a stale 2-part same-name destination is closed by `--host` + that teaching —
-not by any in-string magic.
+- openrig-user — exact command reference
+- seat-continuity-and-handover — stable seat and occupant outcomes

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

@@ -1,98 +1,85 @@
 ---
 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."
+description: "Use when project policy calls for a human decision or update, a human delivery is pending or failed, or a reply must resume the right work."
 metadata:
   cli_surfaces_referenced:
-    - gateway human add
     - gateway human list
-    - queue block
-    - queue handoff
+    - gateway human show
+    - queue create
     - queue transitions
+    - queue block
     - 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.
+Project World supplies **when and why** to contact a human. This skill supplies
+transport-neutral mechanics; installing it does not create an approval gate or
+choose a connector. If policy leaves a material decision ambiguous, identify the
+missing authority. Do not convert a solvable technical failure into a human gate.
 
-## The supported route
+## Discover, check, send, inspect
 
-First discover the registered human identity. Never invent or remember an
-address:
+Discover the registered participants and inspect the chosen human:
 
 ```bash
 rig gateway human list --json
+rig gateway human show <entityId> --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.
+Use the returned `address` (`<entityId>@external`), not a username, remembered
+seat, connector handle, or guessed kernel address. Where several humans exist,
+use the decision ownership in Project World. An absent or ambiguous registration
+needs a named registration correction, not a fallback address.
 
-Keep the work row owned by the agent who must resume it, then park that row on
-the registered human:
+Check readiness: configured, enabled, active, ready, reason, and next action.
+`indeterminate` is not ready. Follow the reported next inspection; do not enable
+or reconfigure a connector merely to make the check pass.
+
+Write the decision, evidence, and continuation in a body file. The sole outbound
+human-message primitive is:
 
 ```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>"
+rig queue create --destination <entityId>@external \
+  --summary "<decision or update>" --body-file <packet-file> \
+  --evidence-ref <durable-evidence> --verify --json
 ```
 
-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:
+If an existing agent-owned row must wait, block it on the **new live qitem ID**
+(`rig queue block <work-id> --on <human-qitem-id> ...`), not on the human address.
+Completion of the human qitem resumes its dependants. Blocking on the human as
+well would issue another notification for the same decision.
+
+The row persists before bounded delivery verification. Read its qitem ID and
+verification result; `posted` proves connector posting, **not human readership**.
+`transport-failed`, `never-posted`, or a pending/indeterminate result leaves the
+row intact. Inspect that same row and its next action; never create a second row
+or blindly resend because verification timed out.
 
 ```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
+A correlated reply binds to that exact human and qitem and records the resolution
+that resumes the owner. Check the recorded result before claiming the decision
+arrived; a delivery receipt alone is not acceptance.
 
-- `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.
+## Existing blockers and other channels
 
-## Writing the escalation
+An existing agent-owned row may be blocked on `<entityId>@host`. That is an
+internal custody label resolved through the human registry to the same external
+participant; it is not a second delivery address. Keep the owner and continuation
+on that row. Inspect its existing delivery receipt before considering another
+request, so a legacy blocker does not produce a duplicate message. Never derive
+`@host` from the current rig name.
 
-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.
+`rig send` reaches an agent's terminal only. It is not a human transport or a
+durable human obligation. Agent-to-agent work uses the queue handoff path.
+Connector-specific configuration and handles belong to registry/readiness tools,
+not to project-independent message instructions.