@openrig/cli 0.5.5 → 0.5.6

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

@@ -1,14 +1,9 @@
 # SDLC conventions — the markdown control plane
 
-> **Succession rule (source of truth):** this document was derived from the
-> corrective review-surface redesign spec
-> (`CORRECTIVE-REDESIGN-review-surface-2026-07-05`, DRAFT v0.2, §2–§6,
-> grounded against openrig main `c27f2aff`, 2026-07-05/06). **Once shipped,
-> THIS repo document is the living SSOT for the SDLC conventions going
-> forward**; the corrective spec is the historical design record. Scaffold
-> templates, the advisory scope audit, the `mission-slice-sop` skill, and the
-> shipped bootstrap overlay all point HERE — they must not restate this
-> document in full (restatement is how drift is born).
+> **Source of truth:** this repo document is the living SSOT for the SDLC
+> conventions. Scaffold templates, the advisory scope audit, the
+> `mission-slice-sop` skill, and the shipped bootstrap overlay all point HERE —
+> they must not restate this document in full (restatement is how drift is born).
 
 OpenRig is a software factory the human steers from a high altitude. The human
 records intent; agents turn intent into a plan, the plan into a build, the
@@ -18,47 +13,41 @@ conventions define "well-formed." Everything here is **advisory / fail-open
 for agents**: nothing below blocks a write; the audit records and advises.
 
 
-## WHERE YOU ARE DECIDES WHICH LOOP YOU RUN — the VM inner loop vs the host outer loop
-
-The parent host's SDLC was being applied wholesale to the VM. **They are different worlds with
-different responsibilities**, and conflating them is what turned this document into friction.
-
-| | **INNER LOOP — the VM** | **OUTER LOOP — the parent host** |
-|---|---|---|
-| **question it answers** | *does it actually work?* | *does what was delivered match what was intended?* |
-| **method** | ground → fix → upgrade in place → **run it and look** → iterate | intent-vs-delivered comparison, commit-message review, privacy/leak scrub, release management, publish |
-| **definition of done** | to the best of our knowledge the code is **completely functional and works**, and needs **no heavy refactoring** to be release-ready | the release is shippable and honest |
-| **ceremony** | **Part A only.** Part B is not the default here. | **Part B applies.** The release itself earns it. |
-
-**WHY the ceremony belongs there and not here — the rule that makes this self-enforcing:** the
-proof ceremony is a **protocol for transmitting confidence to someone who was not there.**
-Plan-lock, proof contracts, C1 drops and intent-vs-delivered all exist so a reader who did NOT
-watch the work happen can verify that it did. On the host that is exactly the situation, so the
-artifacts must carry the confidence. **On the VM the builder IS there** — they ran it and looked at
-it. Running the ceremony there re-encodes, at high cost, something already known, for an audience
-standing in the room.
-
-**WHERE A FIX GOES — go where the validation is POSSIBLE, not where the ceremony lives:**
-
-- **Needs a live daemon to verify → the VM.** That is the only place it CAN be verified. (Worked
-  example: proving the ACTIVITY telemetry was really fixed required cutting the runtime over and
-  reading real values; no amount of host-side review could establish it.)
-- **Verifiable by reading — docs, comment scrubs, message hygiene → the host.**
-
-**The VM's north star for a release:** hand the host code that, to the best of our knowledge, is
-completely functional and works. Not a proof pack. **Effect-verified functionality.**
-
-
 ## HOW TO READ THIS DOCUMENT — two parts, and only one of them is the default
 
 | | applies | contents |
 |---|---|---|
 | **PART A — THE SIMPLE SDLC** | **ALWAYS. This is the default.** | artifact conventions, proportionality, the advisory audit, the honesty rails |
-| **PART B — THE RIGOROUS OVERLAY** | **ONLY when the founder, or an orchestrator relaying the founder, ASSIGNS the heavy path to a NAMED piece of work** | the proof-contract format, the two locks, C1 proof drops, the locked role contracts |
+| **PART B — THE RIGOROUS OVERLAY** | **ONLY when the human operator, or an orchestrator relaying that decision, ASSIGNS the heavy path to a NAMED piece of work** | the proof-contract format, the two locks, C1 proof drops, the locked role contracts |
 
 **You may not select Part B for yourself.** If you believe something earns it, say so in ONE
 sentence and continue on Part A until told otherwise. Part A corresponds to the `mission-slice-sop`
-skill; Part B to `mission-slice-intent-proof-sop`.
+skill; Part B is defined below and applies only when assigned.
+
+
+## THE COMPONENT MENU — this document is a menu, not a pipeline
+
+The SDLC is assembled from **components chosen per mission**, not a single mandated flow.
+This document describes the components and carries recommendations; a mission (or the team
+running it) picks per phase. Multiple valid options can exist for the same phase — choosing
+one does not deprecate the others. Nothing below deletes or overrides an existing component.
+
+| phase | components available today |
+|---|---|
+| **PRODUCT / MISSION PREPARATION** | **The product-management pass** — the layer above planning, run by the advisor/PM seat before planners touch a mission. The build is a lossy compression pipeline (PM intent → planner spec → builder code); nothing leaks downward by proximity, so this pass grounds in the raw sources, synthesizes ONE scope of record, presents owner decisions decision-ready, mints slices at plan time, deposits the full design contract INLINE in each design-bearing spec (owner words verbatim, settled decisions, evidence, shape of done, anti-goals), routes the complete reading list and internet-research assignments from the spec itself, frames each slice's planning-dial rung with its reason, and rereads every spec as the narrow downstream reader. The measuring stick: SPEC.md alone, plus what it explicitly routes to, reproduces the intent in a reader with none of the author's context. Full reference: `product-management-pass.md`. |
+| **PLAN** | **The planning dial** — planning rigor is a spectrum chosen per piece: P0 mini-requirements and pointers (simple, reversible work) · P1 an authored spec with a proof contract (the default) · P2 plus a research round before the spec freezes, run BEFORE build dispatch · P3 plus an adversarial pass by a non-author, judged against product goals, landing amendments with proof-contract teeth · P4 plus a blind from-scratch design diffed against priors before proceeding. Dial up by what the piece is, exactly as build care is priced below. Full reference: `planning-dial.md`. |
+| **BUILD** | **Part A, the simple flow** (below — the default) · **the wave model** — slices build in parallel in disjoint file territories, an integrator merges serially, and independent review fires once per wave (two reviewers with different vantages, never the writers; fix rounds re-earn verdicts at one final revision; per-slice discipline stays failing-test-first and verify-by-effect). The wave IS the care dial: what shares a wave decides how much review each piece gets · **Part B, the rigorous overlay** (below — only when assigned). These combine: a wave can carry one Part-B piece. Full wave reference: `wave-sdlc.md`. |
+| **DISPATCH DATA** | **The execution-data conventions (S27)** — three tiny data disciplines that make execution state derivable instead of hand-tabulated, consumed by `rig view show execution`. **EC-1, edges in frontmatter:** every open slice carries its hard edges in `depends_on:` (an inline JSON array; an explicit `[]` is a statement, absence is INDETERMINATE); soft/serialization edges are one machine-readable Territory line, exactly `SOFT-AFTER: [ids] — reason`. **EC-2, wave-as-data:** wave composition + review model live on a durable queue row tagged `wave-map` + `format:wave-map-v1` whose body carries one fenced ```json block (`{format:"wave-map-v1", mission, waves:[{id, slices, serialized_order?, review_model?}]}`) — composition only, never status labels (status derives at read time); the planning dial recorded at lock surfaces as the frontmatter field `approved-spec-dial:` beside the approve stamp. **EC-3, dispatch names the worktree:** build batons carry the exact body line `worktree_path=<path>` from dispatch onward — it is Q1's join key; batons without it join by naming only and the view marks them `fragile_join`. Existing batons are never rewritten. |
+| **RELEASE** | The release ceremony conventions (publication identity, honest release notes) and the CAPABILITY-DELTA LIFECYCLE LAW: each release's delta is authored at the fence, bound to the exact published cut; canon absorbs its named items; the canon header then names the delta, which expires it — verify the expiry fired, and never cite an expired delta. Full statement: `release-boundary.md` §6. |
+| **BOUNDARY** | **The release boundary** — housekeeping run once per fence so the next release starts clean: seats reset or re-primed per their continuity needs, memory distilled (keep what changed a decision recently), every queue swept by destination and dispositioned, substrate torn down, boards frozen as records, a clean-box baseline captured. A checklist of judgment guides, not gates. Full reference: `release-boundary.md`. |
+
+> Full reference documents for each component (graduated 2026-08-28): the
+> product-management pass — `product-management-pass.md` · the
+> planning dial — `planning-dial.md` · the wave model — `wave-sdlc.md` · the release
+> boundary (including the capability-delta lifecycle law) — `release-boundary.md` ·
+> the mission install — `mission-install.md` (lands with its own slice). The
+> summaries above remain the one-glance description; this document remains the SSOT
+> pointer for the whole menu.
 
 # PART A — THE SIMPLE SDLC (applies always)
 
@@ -92,7 +81,7 @@ Each slice directory carries:
   - **`## Intent`** — the recorded intent, verbatim. The UI projects this
     text as the INTENT section.
   - **`## Mini-requirements`** — the concise, one-glance requirement tier
-    (numbered list). This is the founder's first structured catchpoint;
+    (numbered list). This is the human operator's first structured catchpoint;
     approval starts here.
   - **`## Proof contract`** — a checkbox list of promised deliverables (see
     §3). The UI's DELIVERED section pairs each item with its proof.
@@ -149,21 +138,9 @@ either being wrong (for example, one over the frontmatter block and one over
 the whole file). Coverage is what makes a cited hash verifiable rather than
 merely impressive.
 
-**Canonical convention (the ONE origin — cite it, do not restate it here),
-cited in the form that convention itself prescribes — path + section anchor +
-dated whole-file hash:**
-
-- **path:** `artifact-cross-citation-path-plus-lineage.md` (internal authoring convention — not shipped in this public repo)
-- **anchor:** *A cited hash STATES ITS COVERAGE — span is part of the definition*
-  (2026-08-08)
-- **hash:** `sha256 14d9a273d542648ab1e0a82c7fd98e8a8c59cb02a83be76b8af9abfb717b34d2`
-  — **coverage: WHOLE FILE, bytes as stored, INCLUDING the trailing newline**
-  (0x0a terminal byte verified), 229 lines, as-of 2026-08-08.
-
-The **path + anchor is the AUTHORITY**; the whole-file hash **DATES** the
-citation. That artifact is a living doc: the hash goes stale at the next
-legitimate append, the anchor does not — the CURRENT-line convention applied to
-a citation.
+**Use path + anchor as the authority and a whole-file hash only to date the
+citation.** The address survives legitimate content changes; the digest does not.
+
 ## A4. When implementation finds the intent rested on something that does not exist
 
 A slice's intent can only be honoured to the extent its assumptions hold. Sometimes implementation
@@ -217,16 +194,15 @@ reported as unknown, not failure.
   emits an intent-bearing `SPEC.md` + `NOTES.md`. Core emits only this
   mode-neutral shape; mode plugins add richer material through the extension
   seam rather than teaching core a mode.
-- **Skills — TWO, matching this document's two parts**: `mission-slice-sop`
-  teaches **Part A**, the light default; `mission-slice-intent-proof-sop`
-  teaches **Part B**, the assigned overlay. Assigned-only, never self-selected.
+- **Skill**: `mission-slice-sop` teaches **Part A**, the light default. **Part B**
+  is defined below and applies only when assigned — never self-selected.
 - **Bootstrap**: the shipped agent overlay points fresh seats at the skill
   and this document at boot.
 
 # PART B — THE RIGOROUS OVERLAY (assigned only)
 
-> **ENTRY CONDITION:** everything below applies **only** when the founder — or an orchestrator
-> explicitly relaying the founder — has assigned the heavy path to a **named** piece of work.
+> **ENTRY CONDITION:** everything below applies **only** when the human operator — or an orchestrator
+> explicitly relaying that decision — has assigned the heavy path to a **named** piece of work.
 > If you arrived here without an assignment, stop and use Part A.
 >
 > **Rails:** the locks are **two, and only two**. Nothing here authorizes a second gate round on
@@ -346,9 +322,6 @@ 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:
 
@@ -364,6 +337,6 @@ the scratch context read or wrote state it never owned, and whether anything vis
 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.
+(`daemon-db-path.ts`) — deliberate split-path configuration remains legitimate and
+untouched. This rule governs **inheritance into scratch contexts**, where nobody
+decided anything: strip what you did not choose, then choose.

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

@@ -0,0 +1,113 @@
+# The wave SDLC — parallel build, wave-level review, composition as the care dial
+
+Graduated 2026-08-28 from the working playbook of the team that proved it live; the
+team-specific custody mechanics stay in that team's playbook. Lock stamps in this
+model are ADDITIVE: approval appends metadata and never rewrites authored bytes, so
+a candidate's identity survives its own approval.
+
+## The model in one paragraph
+
+Slices build IN PARALLEL across every build-class seat, each in a DISJOINT FILE
+TERRITORY, each merged serially by one integrator the moment its candidate freezes
+with builder-proven receipts. Independent review happens ONCE PER WAVE over the wave's
+whole accumulated range — two reviewers with different vantages (ideally different
+runtimes), never the writers — and their findings drive fix rounds that re-earn both
+verdicts at the round's final revision. Checks stay per-slice (failing-test-first
+proof, verify-by-effect, honest receipts); rounds happen per-wave.
+
+## The mechanics
+
+1. **PLAN:** wave entries in the plan of record; the planner shapes specs; the plan
+   authority locks them. Every slice gets a real workspace or proof has no home.
+2. **DISPATCH:** batons fan out with EXCLUSIVE file territories. THE BRIEF IS THE
+   UNIT: every assignment carries the goal, the acceptance criteria, the complete
+   context routes (exact paths), the territory — and this standing grant: "Navigate
+   the implementation yourself: derive what you need, research, spawn readers,
+   decide your own build order. Ask when stuck; the orchestrator is here to help."
+   DEFAULT SCOPE IS THE WHOLE SPEC, built in one sustained run to ONE frozen
+   candidate. Handing out anything smaller requires naming the reason on the brief
+   itself (an unresolved decision, a live territory conflict, a genuine
+   fork-in-the-road risk) — an unexplained small chunk is a dispatch defect.
+   Territory overlap = serialize. Conflict discovered mid-build = STOP AND RULE.
+   Why: the builder holds the spec and the code; decisions about how to build
+   belong where the building context lives. Detailed sequencing instructions were
+   scaffolding when models were weak; today they are a cage, and per-command
+   routing is the failure mode, not diligence.
+   THE BRIEF IS A MAP, NOT THE TERRITORY. Distillation is welcome — for a minimal
+   slice the brief may honestly be richer than the spec — but it is never the
+   receiver's ONLY context: the builder's first act is self-onboarding from the
+   routed reading list (the mission-install pattern at slice scale), then checking
+   the map against the ground it actually stands on. Nobody knows the ground floor
+   better than the builder; the wide angle lives a layer up. When the ground
+   disagrees with the map, that is a finding to raise — not a reason to follow
+   the map off a cliff.
+3. **BUILD:** failing-test-first against a pristine base with committed final test
+   bytes; freeze a single candidate revision; receipts cite the FINAL revision
+   (re-earned after any rebase).
+4. **MERGE:** integrator-only, serially, verified at source each time (candidate
+   parent equals pre-merge tip; changed files equal declared territory). Merge
+   announcements are REBASE TRIGGERS for every open candidate.
+5. **WAVE REVIEW:** fires when the wave's build completes. Two independent reviewers,
+   base-scoped at the tip, writers excluded from reviewing their own work. The two
+   gates ask DIFFERENT questions — does the structure hold, versus does each claim
+   survive contact with source. That is the design, not redundancy.
+   Reviewers also review for DRIFT, not only defects: does the built thing still
+   match the acceptance criteria the brief stated — is this still the doghouse the
+   owner asked for, or did locally-defensible steps accrete toward a moon base?
+   Plot-loss is a first-class finding with the same standing as a logic defect.
+   Reviews also DISPOSE each miss by cause: CONTEXT-GAP — the spec or its routes
+   lacked what the moment needed (a planning finding; the fix lands in the spec) —
+   versus JUDGMENT-GAP — the context was there and the call was wrong (a builder
+   finding; the fix is a check). One word in the verdict artifact. The rate this
+   produces is the calibration the dispatch shape tunes on.
+6. **FIX ROUNDS:** findings become forward-fix candidates (merges stand; merged is
+   not running). One re-review pass per round re-earns both legs at the final
+   revision. Narrow rechecks for narrow corrections.
+7. **SEAL:** both legs clear at one revision = wave sealed; the next slot opens.
+
+## THE WAVE IS THE CARE DIAL
+
+Wave COMPOSITION is the control surface for how carefully a piece is handled: a
+large, complicated, or load-bearing slice gets a wave OF ITS OWN (its review ceremony
+fires for it alone); a big piece can even split across waves. This decouples what an
+older model conflated: mission and slice workspaces stay flexible organizational
+containers; waves are the separate layer that sequences work, assigns it, and prices
+its handling care. Care is a per-piece property, never a per-mission one.
+
+## When to use it
+
+Many small-to-medium, root-caused, evidence-backed slices; enough seats to
+parallelize; territories that partition cleanly; an integrator who can merge serially
+and verify fast.
+
+## When NOT to use it
+
+Design-uncertain or shared-region work (one slice, classic two-leg review, or a
+design session first). Anything irreversible within the hour (publish, cutover,
+destructive operations) — that is the heavy path. And when no independent non-writing
+reviewers exist: nothing ever self-reviews; without them the wave gate is theater.
+
+## Failure modes, with the mitigations that worked (dated observations, 2026-08)
+
+- **Freeze-merge races:** a candidate freezes seconds before a merge moves the tip.
+  Mitigation: zero-overlap restack with content-identity proof (stable patch-id) in
+  an isolated worktree; builder-side self-catch on merge announcements.
+- **Evidence theater:** a failing test that fails for the wrong reason reads
+  identical to a real one. Mitigation: reviewers re-derive the failures
+  independently; false characterizations retire to a correction history, never a
+  silent rewrite.
+- **Presence-not-absence tests:** asserting the true line exists while the false
+  line still prints. Rule: pin the ABSENCE of the false claim in every encoding.
+- **Phantom checkout status:** merge-by-reference leaves a shared checkout's index
+  stale. Never build or commit from a shared checkout; sync its index at fences.
+
+## Measured outcome from the proving run (dated, one team, 2026-08)
+
+Eight slices plus five fix candidates plus two addenda built and merged in ~2.5 hours
+across five writing seats; two wave passes plus three fix-round passes replaced ~20
+per-slice review rounds. Defect yield went UP: the reviewers' findings never
+overlapped once across three consecutive verdicts, and the builders' green suites had
+missed every one of them — wave-level review sees cross-slice seams per-slice review
+structurally cannot. Correction latency: one live defect went found→root-caused→
+specced→locked→built→merged in 24 minutes, because no review round stood between a
+locked spec and a building seat.

package/daemon/policies/builtin/standard.policy.md

@@ -16,10 +16,10 @@ destructive_class: [delete_everything, drop_persistent_store, reset_or_discard_v
 The everyday software-factory posture for INTERACTIVE dev. Routine work runs without prompts; the consequential outward and history-rewriting acts defer to the human.
 
 - **default_posture: allow** — routine dev (toolchain, arbitrary shell, install deps, scoped file deletion, network, topology) runs without a prompt.
-- **allow: [push_to_remote]** — routine `git push` is allowed (pinned explicitly; the founder rejected gating push as a default).
-- **ask: [create_pr, publish_package, merge_or_release, force_push]** — outward/release/history-rewriting acts ASK the human. **ASK ≠ deny**: OpenRig bakes no block; ASK = defer to the human, the founder's explicit beyond-floor default. `force_push` is additionally best-effort on Claude (prefix rules can't reliably split `git push --force`), so ASK is the honest disposition, not a can't-enforce deny.
+- **allow: [push_to_remote]** — routine `git push` is allowed (pinned explicitly; the policy design rejects gating push as a default).
+- **ask: [create_pr, publish_package, merge_or_release, force_push]** — outward/release/history-rewriting acts ASK the human. **ASK ≠ deny**: OpenRig bakes no block; ASK = defer to the human, the policy's explicit beyond-floor default. `force_push` is additionally best-effort on Claude (prefix rules can't reliably split `git push --force`), so ASK is the honest disposition, not a can't-enforce deny.
 - **destructive_class → ask** — `delete_everything`, `drop_persistent_store`, `reset_or_discard_vcs` default to ASK, never a silent block (best-effort-safe).
 
 **INTERACTIVE-dev posture:** an `ask` freezes an autonomous seat by design — autonomous fleets use Open or YOLO, not Standard.
 
-**FLOOR (always on, flag surface):** Claude `acceptEdits` + Codex `workspace-write` (the edit/sandbox floor); Pi `--no-approve` is a resource-TRUST posture, not a permission floor (Pi has no permission surface). **Translation is the skill's job** (harness-neutral intent → per-harness format, caveated). Grounded in schema `a8dba0d9`; the ask-set is pinned per cold-transfer `627abbb6`.
+**FLOOR (always on, flag surface):** Claude `acceptEdits` + Codex `workspace-write` (the edit/sandbox floor); Pi `--no-approve` is a resource-TRUST posture, not a permission floor (Pi has no permission surface). **Translation is the skill's job** (harness-neutral intent → per-harness format, caveated).

package/daemon/policies/builtin/yolo.policy.md

@@ -11,10 +11,15 @@ description: Full-bypass posture — the flag-surface YOLO opt-in. Everything ru
 
 The maximum-permissive built-in. The seat runs the harness with its full-bypass launch flag: Claude `--dangerously-skip-permissions`, Codex full-bypass, Pi `--approve`. Nothing prompts; nothing is denied. Use only for fully-trusted autonomous work where any pause is unacceptable.
 
-**APPLICATION is deterministic, NOT skill-translated.** YOLO is a `surface: flag` policy: it resolves to a stable launch flag, so it is applied by the deterministic flag-surface opt-in — the rip-out slice's YOLO setting (OPR.0.4.8.2). The `applying-a-permission-policy` skill does **NOT** translate this policy; it simply points at that setting. This is the two-surface distinction: the flag surface is stable enough for deterministic code, so it does not pay the skill-indirection tax.
+**APPLICATION is deterministic, NOT skill-translated.** YOLO is a `surface: flag`
+policy: it resolves to a stable launch flag and is applied directly by the runtime
+flag-surface opt-in. The `applying-a-permission-policy` skill does **NOT** translate
+this policy; it points at that setting. The flag surface is stable enough for
+deterministic code, so it does not pay the skill-indirection tax.
 
 **Config policies are MOOT when YOLO is on.** The full-bypass launch flag overrides any Claude prefix rules / Codex posture, so an attached config-surface policy (Locked/Standard/Open) has no effect while YOLO is active. Pick YOLO OR a config policy, not both.
 
 **Guardrails come from skills + starter markdown, not permission-blocking** — a YOLO seat is bounded by what its skills and operating context tell it to do, since the permission layer imposes nothing.
 
-**Naming lineage:** the founder's FINAL DESIGN named the fourth built-in **Operator**. The two-surface refinement (2026-08-03) subsumed Operator into this flag-surface full-bypass built-in and renamed it **YOLO** to name the posture plainly; the picker presents all four named postures (Locked / Standard / Open / YOLO) uniformly. Grounded in schema `a8dba0d9`.
+**Naming:** YOLO names the full-bypass posture plainly; the picker presents all four
+named postures (Locked / Standard / Open / YOLO) uniformly.

package/daemon/specs/agents/shared/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/specs/agents/shared/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/specs/agents/shared/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/specs/agents/shared/skills/core/openrig-skills/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: openrig-skills
+description: "Use when you're operating OpenRig and need the right skill or context for fleet recovery, seat handover, new-seat orientation, a watchdog wake, cross-host reach to an agent on another machine, rig packaging, an OpenRig upgrade, systematic debugging, queue triage, or implementation planning; also use when you don't know what applies or nothing is projected on cold boot."
+allowed-tools: Bash(rig:*)
+metadata:
+  openrig:
+    stage: shipped
+---
+
+# OpenRig skills — the index (start here)
+
+You're running inside OpenRig. OpenRig ships a set of **skills** — small documents that tell you *when* to do something and *how*. This file is the map: what ships, when to reach for each, and how to load it. If you don't know which skill applies, or nothing is projected into your context, **start here.**
+
+## How OpenRig context works (30 seconds)
+
+Skills are **progressive disclosure**: a skill's *name + description* sit in your context ambiently (the "hot tier"); its *body* loads only when you open it. So you don't pre-read everything — you pattern-match a skill's "when" to your moment, then open just that one. This file is the index over the whole shipped set. (For the full model of building/operating agent software, open `software-for-agents`.)
+
+Every row below names **how to reach the skill** — already-hot, or an exact load path. No row is a dead end.
+
+## Loading an entry on demand — `rig context get`
+
+Don't guess a file path or a name. Go **ask → ref → load** in three steps:
+
+1. **Discover** — run `rig context list` for every shipped entry's **ref** and name. The *when* for
+   each is the index below (or `rig context list --json`, which carries each entry's purpose) — match
+   your moment there.
+2. **Select** — match your moment to a row's *when* and take its **ref**. Refs are canonical full paths
+   that mirror the library layout — `skills/<namespace>/<name>` (e.g. `skills/core/rig-lifecycle`,
+   `skills/process/systematic-debugging`). A unique bare name (e.g. `watchdog`) also resolves; any
+   slash-bearing ref is an exact lookup and fails loud if it does not exist.
+3. **Load** — `rig context get skills/<namespace>/<name>`:
+
+```
+rig context get skills/core/rig-lifecycle
+```
+
+The router itself is available through both forms it teaches:
+`rig context get openrig-skills` and `rig context get skills/core/openrig-skills`.
+
+The content is served **from the installed CLI**, so what you load always matches your running version —
+no path-guessing, no frozen-fork drift. (The daemon assembles the same bundle `rig context preview`
+shows an operator — `get` is the agent-facing pull.)
+
+## The index
+
+> Membership rule (`layout.skills[*].edges.length > 0`): every public skill with at least one product edge in the generated edge layout appears exactly once in this index; no other skill appears.
+
+### Always loaded — the universal spine (open its body when its moment hits)
+These are auto-delivered to every rig; their name+description are already in your context. Open the body when the "when" matches.
+
+- **forming-an-openrig-mental-model** — first boot, or you're unsure how the pieces fit. The runtime mental model.
+- **openrig-operating-model** — you do not know where context or work belongs, or you are about to duplicate knowledge. The two-tree placement and trace-to-root model.
+- **openrig-user** — you need a `rig` CLI command (send / queue / ps / whoami / scope / broadcast). The daily CLI surface.
+- **applying-a-permission-policy** — a rig or seat has a permission policy attached, or you're setting one up: translate it into the live harness configuration.
+- **claude-compaction-restore** — you just compacted (Claude). Restore from durable evidence before resuming real work.
+- **delegating-work** — deciding who should do a task: you, a spawned subagent, or a durable peer seat that already holds the context.
+- **session-compaction-and-restore** — preparing for, or recovering from, compaction (any runtime). The write- and read-side protocol.
+- **queue-handoff** — you're passing durable work to another seat or ending your turn. The queue is the work ledger, not chat.
+- **refocusing** — a long-running seat may have lost the product outcome, crossed a major boundary, or compacted and needs a fresh path-based trace.
+- **seat-continuity-and-handover** — handing your seat's work across a restart or to another owner.
+- **orienting-to-an-inherited-seat** — you just inherited an existing seat through a planned handover and need to verify its identity, state, and testimony.
+- **retiring-and-inheriting-a-seat** — you're planning a seat transition and need to retire the current occupant into a fresh successor without losing continuity.
+- **mission-slice-sop** — you're working a mission/slice (the SDLC: intent → mini-requirements + proof contract → build → QA → proof). The operating manual.
+- **messaging-the-human** — composing a message to the human. Plain language, no insider jargon.
+- **software-for-agents** — you want the full first-load model of how agent software is built and operated here.
+- **openrig-skills** — this index (you're reading it). Always loaded; the entry point to everything below.
+
+### Load when your role or task calls for it (repo-shipped, profile-selected)
+These ship in the OpenRig repo and reach a seat when its profile selects them. To use one, select it in your profile's `uses.skills`, or open it directly at `packages/daemon/specs/agents/shared/skills/core/<skill>/SKILL.md`.
+
+- **openrig-architect** — authoring a rig or topology (NOT for changing OpenRig itself — that's `openrig-builder`).
+- **openrig-cmux** — driving the `cmux` terminal provider.
+- **openrig-herdr** — opening/managing seat terminals via the default proof-gated provider.
+- **agent-startup-and-context-ingestion** — a seat is booting and ingesting its startup context.
+- **topology-mutation-and-seat-management** — adding, removing, renaming seats or otherwise mutating rig topology.
+- **rig-lifecycle** — rig up / down / pause / resume lifecycle operations.
+- **rig-bundles-and-shareable-artifacts** — packaging or installing a rig bundle / shareable artifact.
+- **cross-host-rig-commands** — reaching seats or queues on another host (`--host`).
+- **openrig-upgrade** — upgrading OpenRig or the daemon.
+- **agent-starters** — composing an agent's starter context / priming packs.
+- **specification-system** — authoring or reading AgentSpecs and rig specs.
+- **human-in-the-loop** — deciding when to involve the human vs. proceed on your own authority.
+- **watchdog** — monitoring or recovering a seat (health, restore, stuck state).
+- **session-source-fork** — forking a session's source/context.
+- **context-engineering** — designing context systems. Provisional and non-normative: current OpenRig skills, explicit rulings, and measured practice outrank it on any conflict.
+
+Pod handbooks (load when you're in that pod):
+- **orchestration-team** — you're orchestrating a rig: dispatching, monitoring, keeping the loop moving.
+- **development-team** — you're on the dev pod: building and shipping product changes.
+- **review-team** — you're reviewing: fresh scrutiny, anti-slop, empirical verification.
+- **oversight-team** — you're in an oversight pod: monitor boundaries and route findings without taking over the work.
+
+Product-management craft (load when shaping/reviewing work):
+- **requirements-writer** — turning intent into clear requirements.
+- **plan-review** — reviewing a plan before it's built.
+- **exec-summary** — writing a decision-ready summary for a human.
+- **office-hours** — running a structured advisory / decision session.
+- **context-builder** — assembling the context a task or seat needs.
+- **backlog-capture** — capturing and shaping backlog items.
+- **ui-mockup** — producing a UI mockup for a slice.
+
+### Vendored craft — load when you're coding (ships with upstream provenance)
+General engineering skills OpenRig ships as vendored copies. Open when the task matches; they carry "modified by OpenRig" provenance.
+
+- **test-driven-development** — implementing a feature or bugfix: write the failing test first.
+- **verification-before-completion** — about to claim done / passing / fixed: run the check and read the output first.
+- **systematic-debugging** — debugging: find the root cause before the fix.
+- **writing-plans** — writing an implementation plan.
+- **executing-plans** — working through a written plan.
+- **brainstorming** — divergent ideation before converging.
+- **using-superpowers** — discovering and using the vendored "superpowers" skill set.
+- **agent-browser** — driving a browser (screenshot / screencast) from an agent.
+- **frontend-design** — designing frontend / UI.
+- **dogfood** — web-QA / dogfooding a shipped UI.
+
+## Need more than what ships here?
+
+This index covers the **shipped** surface. A dev host carries far more (factory, architecture, PM-craft, studio skills) reached through the host's own routers/codemaps — if you're on a builder host and need something not listed above, that deeper routing is the next hop, not a wall. (Host-scale routing is the subject of the context-routing architecture doc; at product scale, this one file is the whole map.)