@openrig/cli 0.5.10 → 0.5.11

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/openrig-architect/SKILL.md

@@ -21,8 +21,7 @@ metadata:
       - openrig-upgrade
       - forming-an-openrig-mental-model
       - ai-dev-workflows
-    notes: |
-      Description was already correct (starts with "Use when..."; lists specific authoring triggers including the diagnose-bad-rig case). Final sentence ("Covers the full authoring lifecycle from user intent to validated, launchable rig.") is workflow-summary-adjacent; on next iteration, consider trimming. For factory-adoption cycle, kept as-is to match product source-of-truth.
+
 ---
 
 # OpenRig Architect
@@ -33,43 +32,33 @@ Your job is to take a user's intent — "I need a team that does X" — and prod
 
 You also diagnose problems when a rig launches but agents aren't behaving as intended.
 
-## Before You Design: Required Reading
-
-Load these before starting any design work. The quality of your output depends on the depth of knowledge you bring.
-
-**Required (read all of these):**
-
-1. **`openrig-user` skill** — full OpenRig CLI surface. You must know the operator primitives. If your runtime supports skills, load it by name. Otherwise, look for it at `~/.openrig/skills/openrig-user/SKILL.md` (the runtime install dogfood mirror — packaged skills land here) or inside the OpenRig installation under `packages/daemon/specs/agents/shared/skills/core/openrig-user/SKILL.md`. The `~/.openrig/reference/` directory holds reference docs (rig-spec.md, agent-spec.md, etc.), NOT skills.
-
-2. **OpenRig reference docs** — these are installed at `~/.openrig/reference/` when the daemon starts. Read all of them:
-   - `~/.openrig/reference/rig-spec.md` — canonical RigSpec YAML reference. Every field, validation rule, default.
-   - `~/.openrig/reference/agent-spec.md` — canonical AgentSpec YAML reference. Same depth.
-   - `~/.openrig/reference/agent-startup-guide.md` — how to think about what goes into agent startup. Context loading vs deterministic config, when to use skills vs guidance, the layering model, current support matrix.
-   - `~/.openrig/reference/edge-types.md` — what edges do today vs what they're intended to do.
-
-   If `~/.openrig/reference/` doesn't exist yet, start the daemon first (`rig daemon start`) — it copies the reference docs on startup.
-
-**Read as worked examples:**
-
-3. **Shipped starter specs** — the OpenRig installation includes proven starter topologies. Find them by running `rig specs ls`. Read the ones that are relevant to your design task, especially:
-   - `implementation-pair` — the smallest effective development unit (2 agents)
-   - `secrets-manager` — a managed-app rig with services integration and a specialist agent
-
-**Read if present on this host:**
-
-4. **Host-level doctrine** in your host's topology doc, if it keeps one. If this file exists, it supersedes the baseline process below for complex or high-stakes rigs. Specifically:
-   - §3 defines the canonical rig classes (kernel, project, ephemeral, infra-build, managed-app). Classify before designing.
-   - §4 defines context-sharing patterns (pods as context domains, pair pattern, HA via mental-model-ha skill + substrate session logs, terminal nodes as common-room, chatroom/substrate/transcripts/Corpus).
-   - **§7 is the canonical 12-step rig-spec authoring SOP for high-stakes rigs — use it instead of the baseline "Design Process" below when the rig is ≥4 members, uses HA, is a managed-app, or will be shared/copied.** The baseline below still applies to small/focused rigs.
-   - §10 contains the host's bootstrap sequence so you know where your new rig fits.
-   - §12 has the naming canon and vocabulary mapping to shipped terms.
-5. **`building-agent-software` skill** if available in your skill catalog. Design principles for agent-facing tools and surfaces. Relevant when your rig ships a new CLI, service, or managed app.
-
-**Load as needed:**
-- Domain-specific skills when designing specialist agents — find shipped skills inside the OpenRig installation under the `specs/agents/` tree
-- If the design session is long and you're running inside a managed rig, use `rig whoami --json` to recover your identity after compaction
-
-Do not skip the required reading. A rig architect who doesn't know the spec format will produce specs that don't validate. An architect who doesn't know the startup layering model will produce agents that boot without knowing their role. An architect who doesn't check for host-level doctrine will reinvent conventions the host has already established.
+## Before you design: select the relevant sources
+
+Start with the user's outcome, the current project authority, and the part of
+the format you will author. Load the selected paths from public onboarding;
+consult additional skills when their triggers apply. A design task does not
+require reading the whole command library.
+
+- Read the relevant sections of `rig-spec.md` and `agent-spec.md` before writing
+  those declarations. Consult `agent-startup-guide.md` for startup/loadout work
+  and `edge-types.md` when selecting relationships. Resolve the installed
+  reference root from the actual OpenRig installation; `~/.openrig/reference/`
+  is a default, not a fixed location. If it is absent, use the matching source
+  repository docs or report the missing reference. Reading does not require
+  starting or changing a daemon.
+- Use current `rig <command> --help` for command shape. Load `openrig-user` for
+  the specific CLI surface needed, through the installed skill/context catalog.
+- Inspect relevant starter specs with `rig specs ls`. Treat them as examples to
+  validate against the current environment, not proof that your new rig works.
+- If the environment declares host or project doctrine, read the actual
+  applicable authority and reconcile it with the task. Do not assume a filename,
+  section number, rig classification or fixed authoring SOP. Missing authority
+  is a question to resolve when it changes the design.
+- Load domain-specific guidance for specialist roles. When authoring an
+  agent-facing tool, consult `building-agent-software` if available.
+
+Keep the spec, startup layering, role responsibilities and selected proof
+standard explicit. Scale the reading and checks to what the design changes.
 
 ## The Design Process
 
@@ -152,14 +141,17 @@ To verify the current builtin set on this host, run `rig specs ls` and look for
 
 Each member needs a `runtime` and optionally a `model`.
 
-**Runtime selection:**
-- `claude-code` — Claude Code. Best for: complex reasoning, architecture, code review, orchestration. Supports `/loop` for recurring tasks, rich hooks system, MCP servers.
-- `codex` — Codex. Best for: parallel work, implementation, testing. Different approval model. Less reliable for recurring tasks.
-- `terminal` — Infrastructure nodes. Servers, log tails, build watchers. Not an agent — a process.
-
-**Runtime diversity is valuable.** Using both Claude Code and Codex in the same rig gives you different reasoning perspectives. The `product-team` starter uses Claude Code for the lead/impl/design/r1 roles and Codex for peer/qa/r2 roles. This is deliberate — model diversity catches different classes of issues.
+Choose from the installed, authenticated runtimes and the project's current
+execution policy. `claude-code` and `codex` are agent runtimes; `terminal` is an
+infrastructure process. Their model availability, hooks, approval behavior and
+continuation support differ. Check the relevant installed interfaces rather
+than ranking vendors permanently in a reusable role skill.
 
-**Model selection** is optional. The runtime's default model is usually fine. Override only when you have a specific reason (e.g., a complex architecture agent might benefit from a specific model).
+Pin a model when the work or environment requires it, and verify the active
+runtime reports that model before relying on its result. Select reviewers and
+support roles by consequence, competence and the declared policy. Runtime
+diversity can provide different methods; it does not by itself prove independence
+or make any model suitable for a task.
 
 ### Step 5: Design Edge Topology
 
@@ -181,7 +173,8 @@ This is where most rigs succeed or fail. The topology is mechanical; the startup
 **Minimum for every rig:**
 1. Each agent has a `guidance/role.md` — who they are, what they do
 2. The rig has a `CULTURE.md` — how the team works together
-3. Each agent gets `openrig-user` skill — so they know how to use the rig primitives
+3. Each agent gets the selected onboarding path and can discover the relevant
+   command/skill references when needed
 
 **For serious rigs, also include:**
 4. `startup/context.md` per agent — boot-time grounding (project info, environment details)

package/daemon/specs/agents/shared/skills/core/openrig-upgrade/SKILL.md

@@ -44,6 +44,22 @@ host, use the host's normal operator ceremony. On a recovery-friendly build VM,
 the orchestrator may adopt a tested runtime directly, but still observes each
 step and stops on unexplained drift.
 
+## When recovery crosses an instance boundary
+
+Before either lane changes runtime state, record one host-qualified executor and
+explicitly select the queue store that owns the recovery ruling. State whether
+the original owner continues, waits, or transfers; an open obligation in another
+store is not exclusive custody of this ruling. If the original store is down,
+retain its owner's disposition in the surviving ruling and communicate it to
+that owner before a competing executor acts.
+
+A refused claim means reconcile ownership with the ruling owner before any
+further runtime action; it does not authorize continuing under a separate older
+row. A return names the full executor address and deliberately selected store.
+Read the resulting row there, including source, destination, body, and the
+original owner's disposition, before resuming. Receipt creation alone does not
+establish that a waiting lane received or accepted the transfer.
+
 ## The loop
 
 For every step:

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

@@ -95,8 +95,8 @@ The primitive must NOT report "restored the original agent" or "resumed
 the original seat" or "snapshot." The correct framing is **"forked from
 source session"** / **"started from prior conversation source."**
 
-Negative-grep over adapter source confirms ZERO `restored` / `resumed` /
-`snapshot` strings in fork code paths.
+Check the actual user-facing outcome and persisted identity; wording alone
+does not prove the intended continuity was created.
 
 ## Hard boundaries (do-not list; verbatim)
 
@@ -128,14 +128,17 @@ Mutual exclusion between `resumeToken` (restore path) and `forkSource`
 For `seat handover over fork` composition, the binding outcome is
 independent (see `seat-continuity-and-handover` skill).
 
-## Active-daemon caveat (live-runtime gap)
+## Verify the running implementation
 
-2026-04-30 live scale-out dogfood found: source checkout contained fork
-support, but active daemon was running from a pre-fork commit. **Verify
-the active daemon/runtime commit contains the fork path before live
-proof.** Isolated daemon proof at the target commit can prove the
-feature safely; live forked scale-out remains unproven until the active
-daemon parity is verified.
+A source checkout and the running daemon can contain different implementations.
+Before an authorized fork, check the target daemon's build identity and support
+for the requested source. A source or isolated test establishes only that cut's
+behavior; it does not prove the live runtime uses it.
+
+Record the actual parent history, new seat identity, new continuity token and
+independent binding outcome. Preserve errors and incomplete results rather than
+reporting a fresh launch or restored original seat as a successful fork. These
+checks confer no authority to launch, replace or retire a live seat.
 
 ## Currently shipped (v1) vs deferred
 
@@ -148,7 +151,6 @@ Shipped at openrig `c7b6df1` (2026-04-30):
 - Honest UX literal contract (`continuityOutcome: forked`)
 
 Deferred:
-- Tier 2 real-runtime fork proof (disposable Tart VM cycle, human-gated)
 - Claude `artifact_path` mode (schema currently refuses with deferred message)
 - Provenance columns (`parent_native_id` / `created_via` for queryable RSI consumer)
 - Cross-host fork (source on host A, new seat on host B) — depends on `cross-host-rig-commands`

package/daemon/specs/agents/shared/skills/core/topology-mutation-and-seat-management/SKILL.md

@@ -79,13 +79,11 @@ clean test fixture. The useful matrix:
 A clean-fixture proof is necessary but not sufficient. Live-rig proof
 catches the failure modes that fixture-mode misses.
 
-## Why important strategically
+## Stable roles during topology changes
 
-The current coordination experiments repeatedly need new queues,
-watchdogs, humans, and test seats — which makes this family
-**strategically important.** Seat continuity work will eventually
-separate stable seat identity from runtime occupant identity (see
-`seat-continuity-and-handover`).
+Capacity changes must preserve useful roles, routing and durable work. Distinguish
+adding or removing a seat from replacing its occupant; use
+`seat-continuity-and-handover` for the latter.
 
 ## Currently shipped surfaces
 
@@ -101,14 +99,18 @@ Per `cli-reference.md` v0.2.0:
 - `rig attach --self --rig <rigId> --node <logicalId>`
 - `rig unclaim <sessionRef>` / `rig release <rigId>`
 
-## Active proof gap (current)
+## Choose the proving environment and authority
 
-The 2026-04-30 topology mutation add-seat proof pass is **active**.
-Product Lab shaped it; planner authored `IMPLEMENTATION.md`; driver
-landed the smallest honest CLI retry-guidance patch for failed
-`rig expand` recovery. **Remaining proof is the Section B disposable-rig
-runtime matrix, blocked on operator posture** and owned by
-`orch-lead@your-rig`.
+Select an isolated active rig or an explicitly authorized live target for the
+relevant operation. Record its running build, before/after topology, continuity
+and outstanding work. A passing schema check or isolated fixture does not prove
+an existing live rig was changed correctly. A runtime timeout is indeterminate
+until its durable and process effects are reconciled; do not retry blindly.
+
+The matrix above is verification guidance, not permission to modify another
+rig. Name the operation's owner and scope, preserve the state needed for recovery,
+and retain missing or failed checks in the result. No local experiment or
+unfinished proof obligation is implied by loading this skill.
 
 ## See also
 

package/daemon/specs/agents/shared/skills/pm/exec-summary/SKILL.md

@@ -13,7 +13,7 @@ A single `executive-summary.md` file in the feature folder. 600-800 words exclud
 
 Before writing, silently gather all context from the feature folder:
 
-1. **requirements.md** — acceptance criteria, business rules, scope, user stories
+1. **SPEC.md** — acceptance criteria, business rules, scope, user stories
 2. **background.md** — customer drivers, competitive context, regulatory considerations
 3. **validation.md** — demand evidence, status quo, desperate user, narrowest wedge
 4. **supporting/mockup-ascii.md** — visual mockups (pull 2-3 key screens)

package/daemon/specs/agents/shared/skills/pm/plan-review/SKILL.md

@@ -39,7 +39,7 @@ Rate these dimensions (0-10):
 Read all available docs in the feature folder:
 - **validation.md** — office hours verdict, demand evidence, wedge scope (if exists)
 - **background.md** — customer drivers, competitive context (if exists)
-- **requirements.md** — the main document to review
+- **SPEC.md** — the main document to review
 - **supporting/** — mockups, data files, visual references
 
 ### Step 2: Run All Three Reviews
@@ -50,7 +50,7 @@ Read all available docs in the feature folder:
 ## Plan Review: [Feature Name]
 
 **Date**: [date]
-**Reviewed**: [requirements.md path]
+**Reviewed**: [SPEC.md path]
 
 ### Strategy Assessment
 **Score: [1-10]**

package/daemon/specs/agents/shared/skills/pm/requirements-writer/SKILL.md

@@ -23,7 +23,7 @@ Before starting the conversation, silently gather context:
 
 1. **Check for validation.md** (office hours output): If it exists, read it — it contains demand evidence, the desperate user, the narrowest wedge, and the GO/REFINE/PAUSE verdict. Use it to skip questions the PM already answered.
 2. **Check for background.md**: May have customer drivers, competitive context, and regulatory considerations.
-3. **Check for existing requirements**: Look for any existing specs on this feature.
+3. **Check for existing requirements**: Use the selected slice's `SPEC.md`. If only legacy `requirements.md` exists, preserve it as input/history and reconcile it into `SPEC.md` before downstream mockup/review/summary work. Maintain one requirements authority.
 4. **Check for shipped features**: Look for related as-built specs.
 
 If validation.md exists with a GO verdict, you can skip demand/scope questions and jump straight to acceptance criteria.

package/daemon/specs/agents/shared/skills/pm/ui-mockup/SKILL.md

@@ -27,7 +27,7 @@ Self-contained HTML files that look like the real app. Portable, no dependencies
 Rules:
 - Match the application's existing styling exactly
 - Use real data from the codebase
-- Only show what's in requirements.md
+- Only show what's in SPEC.md
 - Self-contained single HTML file
 - Screen switcher nav to toggle between screens via JavaScript
 - Keep under 1,000 lines
@@ -46,7 +46,7 @@ Rules:
 ### Step 1: Understand What to Mockup
 
 Read feature folder docs first:
-- **requirements.md** — acceptance criteria define what screens are needed
+- **SPEC.md** — acceptance criteria define what screens are needed
 - **validation.md** — the narrowest wedge tells you what's most important to show
 - **background.md** — customer drivers and competitive context inform what to emphasize
 
@@ -70,7 +70,7 @@ Then ask the PM about fidelity level and specific screens.
 ## Guidelines
 
 - **Use real data.** Real names, real ranges, real hierarchies.
-- **Only show what's in requirements.md.** Don't add features beyond the requirement.
+- **Only show what's in SPEC.md.** Don't add features beyond the requirement.
 - **Less is more.** 3-5 screens beats 10.
 - **Match the app exactly.** Read existing code and match styling patterns.
 - **Tell the PM what's real vs mocked.**