@openrig/cli 0.4.6 → 0.4.8

package/daemon/assets/guidance/CULTURE-default.md

@@ -0,0 +1,19 @@
+# OpenRig default culture
+
+This is the universal operating floor for every OpenRig team. A rig's own culture may add role- or domain-specific guidance on top of it.
+
+## Pragmatic truth-seeking
+
+Be plain and forthcoming. Say when something is wrong, show the evidence that matters, and change your mind quickly when the evidence changes. Do not agree performatively, and do not manufacture objections to look rigorous.
+
+## Principles over rules
+
+Use judgment from the goal in front of you. Keep hard rules for genuinely high-stakes boundaries: never destroy an authenticated owner environment, never push or publish without authorization, and never leak secrets.
+
+## Ship good, working product
+
+Bias toward action and deliver what the user asked for. Guardrails, reviews, and proofs serve the product; they are not the product. A real blocker should be named precisely while unblocked work continues.
+
+## Match rigor to stakes
+
+Use root-cause discipline, verify the real user path, and protect owner state. Be thorough where failure has real consequences and decisive on low-risk details. When process starts taking more attention than the product, simplify and get back to shipping.

package/daemon/assets/guidance/openrig-start.md

@@ -5,6 +5,11 @@ You are running inside an OpenRig-managed topology.
 This file is the thin bootstrap overlay, not the full OpenRig manual.
 Use it to recover identity, communicate, and regain context after launch or compaction.
 
+When you are unsure which packaged skill applies, start with the global `openrig-skills` index. It routes to every shipped skill in one hop:
+
+- Claude Code: `~/.claude/skills/openrig-skills/SKILL.md`
+- Codex: `~/.agents/skills/openrig-skills/SKILL.md`
+
 For the full OpenRig command surface, load the packaged `openrig-user` skill now.
 If your runtime supports skills, use that mechanism.
 If it does not auto-load skills reliably, read the packaged copy directly from your current project or workspace:
@@ -14,14 +19,15 @@ If it does not auto-load skills reliably, read the packaged copy directly from y
 
 That skill covers the broader surface, including chatroom, discovery, adopt/bind/attach, lifecycle, specs, bundles, and richer operator workflows.
 
-Your per-session startup guidance may also name additional packaged skills for your role and pod.
-Load those too. This shared overlay is only the common bootstrap floor, not the full operating manual for your seat.
+Your per-session startup guidance also names the process skills for your role and pod.
+Load AND invoke those now, before proceeding with any work, using your runtime's supported skill mechanism.
+This shared overlay is only the common bootstrap floor, not the full operating manual for your seat.
 
 ## Working missions and slices (the SDLC)
 
 If your seat works missions or slices, load the packaged `mission-slice-sop` skill BEFORE authoring or building — it teaches the flow the Living Notes UI projects: intent → mini-requirements + proof contract (→ mockups for UI slices) → plan-lock (`rig scope slice approve --scope spec`) → build the locked set → QA visual compare → `rig proof add … --media` drops (the C1 drop verb — never hand-place proof files) → proof-lock (`--scope delivery`).
 
-The conventions themselves (section names, proof-contract format, the two locks, C1 proof headers) live in ONE shipped document: `docs/reference/sdlc-conventions.md` (in the CLI package). `rig scope slice create` scaffolds the convention sections for every template kind; `rig scope audit` is the advisory backstop — it records and advises, it never blocks your work.
+The conventions themselves (section names, proof-contract format, the two locks, C1 proof headers) live in ONE shipped document: `docs/reference/sdlc-conventions.md` in the repo, materialized at `$OPENRIG_HOME/reference/sdlc-conventions.md` (default `~/.openrig/reference/sdlc-conventions.md`) on an installed package. `rig scope slice create` scaffolds the convention sections for every template kind; `rig scope audit` is the advisory backstop — it records and advises, it never blocks your work.
 
 ## Identity
 
@@ -50,7 +56,12 @@ Broadcast to all peers in your rig:
 rig broadcast --rig <name> "message"
 ```
 
-## Transcript Recovery
+## Secondary Transcript Check
+
+After compaction, recover work from durable artifacts first: the restore map,
+current `MISSION_NOTES.md`, and your owned queue items. Transcript output is a
+secondary check and may be unavailable or incomplete for some runtimes. Little
+or no output does not mean the session was quiet.
 
 Read recent transcript output:
 ```bash
@@ -64,4 +75,8 @@ rig transcript <session> --grep "pattern"
 
 ## After Compaction
 
-If you lose context, run `rig whoami --json` immediately. It tells you who you are, who your peers are, and how to reach them. Then use `rig transcript` to recover recent history.
+If you lose context, run `rig whoami --json` immediately. It tells you who you
+are, who your peers are, and how to reach them. Rebuild the work from the
+restore map, current `MISSION_NOTES.md`, and your owned queue items. Use
+`rig transcript` only as a secondary check; if it returns little or nothing,
+do not conclude that the session was quiet.

package/daemon/assets/plugins/openrig-core/README.md

@@ -4,7 +4,7 @@ Canonical OpenRig skills and hooks for cross-runtime agent topology coordination
 
 ## What this plugin ships
 
-**Skills (8):** the canonical OpenRig operating knowledge — how to use the `rig` CLI, how to design rig topologies, how to recover from compaction, how to hand work off durably between agents, and how to maintain seat continuity across handovers and restarts.
+**Skills (10):** the canonical OpenRig operating knowledge — how to use the `rig` CLI, how to design rig topologies, how to recover from compaction, how to hand work off durably between agents, and how to maintain seat continuity across handovers and restarts.
 
 **Hooks:** activity-tracking hooks (Claude Code: 4 events; Codex: 3 events) that POST agent state to the OpenRig daemon for real-time UI seat-status updates.
 

package/daemon/assets/plugins/openrig-core/skills/applying-a-permission-policy/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: applying-a-permission-policy
+description: "Use when a permission policy is attached to a rig/seat (rig.yaml permission_policy:), or a user asks you to apply one, and you must translate that harness-neutral policy into the target harness's LIVE permission config — Claude settings.json / Codex config.toml / Pi run flags. Agent-driven and interactive: you read the policy, ground yourself in YOUR harness version, show the diff, and ask before writing. NOT for defining policies (that's the policy spec) and NOT a set-and-forget updater."
+metadata:
+  openrig:
+    stage: established             # config cells VM-verified + cold-transfer PASSING (rerun #2, 627abbb6) + built-in SPEC FILES landed → skill translates FROM the spec (POINT-not-COPY). The two established criteria met 2026-08-04. Reviewed at push.
+    tested_against:                # VERSION STAMP — the whole point; re-verify at every harness bump
+      claude_code: "2.1.220 — VM-CONFIRMED 2026-08-03 (all cells)"
+      codex: "0.120.0 — VM-CONFIRMED 2026-08-03 (sandbox_mode/approval_policy; on-failure deprecated-but-accepted)"
+      pi: "0.83.0 — VM-CONFIRMED 2026-08-03: --approve/--no-approve govern PROJECT-RESOURCE TRUST, NOT tool permissions; Pi has NO permission surface (see Pi leg)"
+    verification_status: "Live-verified 2026-08-03/04 (dev-qa @ v-openrig-build). Claude 2.1.220 + Codex 0.120.0 config cells CONFIRMED live. Pi 0.83.0 divergence folded (flags = project-resource trust, not a permission gate). Cold-transfer rerun #1 blocked on the force_push/push_to_remote prefix collision → added the PREFIX-COLLISION rule. Cold-transfer rerun #2 (qitem 001c95fd, verdict SHA 627abbb6bf08ad2f350e2101f11438975def7b193b8da8bbcb747647239afc358): TRANSFERS — all 5 gate checks pass (collision resolved deterministically without asking; single ordinary write confirmation; defaultMode floor written; Codex workspace-write/on-request; Pi compute-nothing). Blocking collision/floor defect CLOSED → gate cleared, 4.8-shippable (provisional-with-passing-cold-transfer). Non-blocking seam closed: the built-in SPEC FILES landed (arch-accepted, source:builtin) → skill translates FROM the spec, interim in-skill pinned summary retired (POINT-not-COPY). stage:ESTABLISHED 2026-08-04 — both criteria met."
+---
+
+# Applying a permission policy
+
+## Translation is best-effort — read this first
+This skill provides the policy schema and OpenRig's best current understanding of how to translate it to each harness. That guidance is **best-effort and version-stamped**: harness permission surfaces change frequently across versions, so a mapping that is correct today can drift on a later release. When you apply a config-surface policy:
+- **Verify against the current docs for your installed harness version.** Treat this skill's tables as version-stamped starting points (see `tested_against`), not settled truth.
+- **Prefer testing in a protected or disposable environment first.** An incorrect write can lock a seat out or over-permit it, so confirm the format before applying it to a live seat.
+- **Hand-editing via the harness's own settings tools is always a valid path.** If a translation is uncertain, setting the policy directly — or asking the user to — is a legitimate outcome, not a failure.
+
+The reliable, deterministic parts are the **blunt instruments**: the YOLO full-bypass flag and the floor (Claude `acceptEdits` / Codex `workspace-write`), which ride the stable launch-flag surface. **Fine-grained config-rule translation — the allow/ask/deny prefix rules and the Codex posture — is the best-effort part** and carries no guarantee of exact fidelity. If a translation looks wrong, fall back to a blunt instrument or a direct hand-edit.
+
+## ⚠ Read this preamble first — why this is a SKILL, not a script (do not "improve" it into a deterministic updater)
+Harness permission formats are a **moving target**. The exact fact this skill is stamped against — Claude Code 2.1.220 permission rules are **prefix-only** (no flag-precise Bash match) — is *version-specific*; the rule grammar can change on the next point release. A hardcoded/deterministic updater would foot-gun the instant it does, and a wrong permission write can **lock a seat out or silently over-permit it**. So the maintained artifact is this caveated, version-stamped skill that an agent reads and applies **interactively, grounding in the live format** — never a code path that writes blindly. If you are tempted to replace this with a deterministic projector: that temptation is the bug this preamble exists to stop.
+
+## When to reach for this
+- A rig/seat has a policy attached (`rig.yaml … permission_policy: <file>`), and you're at **setup/preflight** — apply it (**mandatory for autonomous seats**, see the freeze warning).
+- A user asks "apply the Standard/Open/Locked/Operator policy here" or "set up permissions like <host>".
+- NOT for authoring policies (that's the policy spec) and NOT for daemon-level enforcement (OpenRig is agnostic — it injects nothing).
+
+## What you're translating (the boundary)
+INPUT = a **harness-neutral policy spec** (arch's schema): `default_posture`, `floor`, `allow`/`ask`/`deny` as **semantic actions** (`push_to_remote`, `delete_files`, …), `destructive_class`, `source: builtin|custom`. You TRANSLATE that intent → the harness's live config. You never invent policy; you never pre-bake harness config into the spec.
+
+## The apply flow (interactive — the interactive-ask IS the product)
+1. **Read the policy spec** + its `source:` marker (built-in read-only from the package = copy-to-customize before editing; custom = user space).
+2. **PREFLIGHT (mandatory) — ground yourself in THIS environment:**
+   - **daemon-HOME must equal seat-HOME**, or a user-level Claude write never reaches the seat (assessment iv). Check; if they differ, **stop and ask** — do not write into the wrong HOME.
+   - Read the harness's **actual current config file** + confirm its schema against your installed version (`claude --version`, the live settings.json shape, codex/pi versions). If the format differs from this skill's `tested_against`, trust the LIVE format and flag the drift.
+3. **Derive the per-harness config** from the semantic actions (see the three legs below). Compute the Codex posture-collapse + Pi bit.
+4. **Show the concrete DIFF before writing** (old → new, per file). Never a blind write.
+5. **Resolve best-effort actions by the built-in's rule FIRST, then ask only on genuine ambiguity.** Best-effort destructive actions (`force_push`, `delete_files`, `delete_everything`, `read_secrets`) default to **`ask`** (never a `deny` that can't be enforced) — apply that default rather than stopping to question-back. Surface a question only when the policy is genuinely ambiguous or the seat is interactive. **For a same-prefix collision (`push_to_remote` vs `force_push`, both `Bash(git push:*)`), NEVER ask — apply the deterministic PREFIX-COLLISION rule in the Claude leg.** (Live cold-transfers caught fresh agents *question-backing* — first on the `force_push` default, then on the prefix collision — instead of applying the fixed rule; both freeze an autonomous seat.) On a Claude-only fleet, if the policy denies `network_egress`, **say so explicitly**: it is NOT enforceable — Claude has no network gate, a `Bash(curl:*)`/`Bash(wget:*)` deny is best-effort, and `python`/`node` fetch bypasses it (live-verified: `urllib` reached HTTPS 200 under a curl/wget deny). Route real egress-gating to the Codex sandbox, or record it as advisory on Claude.
+6. **Back up the current config**, then write. Prefer the **user-level** file (`~/.claude/settings.json`) for durable policy — it's the clobber-resistant tier (deny wins across the union). **ALWAYS include `defaultMode: "acceptEdits"` in the Claude settings.json you write** — the floor key must be PRESENT in the file, or the config policy strips the floor. (This is the exact gap a live cold-transfer test FAILED on: the fresh agent wrote allow/deny lists but omitted `defaultMode`, leaving the seat below the floor.)
+7. **Verify** the write landed and the seat can see it (re-read; confirm `defaultMode: "acceptEdits"` is present; for an autonomous seat, confirm no `ask` will freeze it).
+
+## Two surfaces — and this skill writes only ONE of them
+Permissions live on two surfaces with opposite stability — which is the whole reason for the agent-driven split:
+- **LAUNCH-FLAG surface — STABLE (>1yr) → OpenRig sets it DETERMINISTICALLY, NOT this skill.** The flags OpenRig passes at boot: Claude `--permission-mode` / `--dangerously-skip-permissions`; Codex sandbox/bypass flags; Pi `--approve`/`--no-approve`. **Two things live here, both OpenRig-owned: the FLOOR (minimum, by default) and YOLO (full bypass, opt-in).**
+- **CONFIG-FILE surface — CHAOTIC → NEVER deterministic → THIS SKILL'S DOMAIN.** Claude `settings.json` allow/ask/deny + defaultMode; Codex `config.toml` approval rules. This is where the Locked / Standard / Open policies get applied — agent-driven, version-stamped, caveated. (Pi has **no permission surface at all** — its `--approve`/`--no-approve` flags govern project-resource trust, not tool permissions (VM-confirmed Pi 0.83.0); a permission policy does not translate to Pi. See the Pi leg.)
+
+**THE FLOOR (launch-flag, OpenRig-set — this skill KNOWS it, never WRITES it):** Claude `--permission-mode acceptEdits` (keep it); **Codex workspace-only** (stop forcing `danger-full-access` — ≈ Codex's own default ≈ setting-nothing = agnostic); Pi `--no-approve` (a project-resource-trust floor — Pi has no permission gate; see the Pi leg). **One consistent unconditional minimum** (no by-context switching — that mode idea is parked 5.0). A chosen config-file policy layers ON TOP of the floor.
+
+**YOLO MODE (launch-flag, OpenRig-set, opt-in — for people done with permissions):** OpenRig boots every seat with the full-bypass flag (Claude `--dangerously-skip-permissions`; Codex full-bypass). **When YOLO is on, CONFIG-FILE POLICY IS MOOT** — this skill does NOT apply a config policy (or explicitly notes it's overridden by the flag); don't fight the bypass. YOLO is OpenRig's deterministic job, not this skill's. (**Operator = YOLO mode** — subsumed.)
+
+## The three harness legs (skill-owned mapping knowledge, version-stamped + caveated)
+
+### Claude — `~/.claude/settings.json` (user-level, clobber-resistant)
+- **Action → prefix map** (VM-CONFIRMED @ Claude 2.1.220, 2026-08-03 — every row exercised through real Claude tool calls). `fidelity`: `clean` = the prefix honors intent; `best_effort` = prefix-only can't fully enforce → prefer `ask`, never a `deny` that lies.
+
+  | Semantic action | `permissions.*` prefix rule(s) | fidelity |
+  |---|---|---|
+  | push_to_remote | `Bash(git push:*)` | clean |
+  | force_push | ask the flag-first forms `Bash(git push --force:*)` `Bash(git push -f:*)` `Bash(git push --force-with-lease:*)`; base `Bash(git push:*)` follows push_to_remote (see the collision rule) | **best_effort** — catches flag-FIRST force; flag-LAST (`git push origin main --force`) leaks |
+  | create_pr | `Bash(gh pr create:*)` | clean |
+  | publish_package | `Bash(npm publish:*)` `Bash(pnpm publish:*)` `Bash(yarn publish:*)` `Bash(cargo publish:*)` | clean (multi-pattern) |
+  | merge_or_release | `Bash(git merge:*)` `Bash(git tag:*)` `Bash(gh release:*)` | best_effort — protected-branch semantics not expressible |
+  | delete_files | `Bash(rm:*)` | **best_effort** — target-first leak (`rm <t> -rf` slips); scope not boundable → default `ask` |
+  | delete_everything | `Bash(rm -rf:*)` `Bash(rm -fr:*)` | **best_effort** — same leak → default to `ask`, never a silent deny |
+  | reset_or_discard_vcs | `Bash(git reset:*)` `Bash(git clean:*)` `Bash(git checkout:*)` `Bash(git branch -D:*)` | best_effort |
+  | drop_persistent_store | `Bash(dropdb:*)` `Bash(docker volume rm:*)` (+ project-specific) | best_effort (open-ended) → `ask` |
+  | rig_up / rig_down | `Bash(rig up:*)` / `Bash(rig down:*)` | clean — ⚠ an `ask` here FREEZES an autonomous seat |
+  | mutate_topology | `Bash(rig add:*)` `Bash(rig remove:*)` `Bash(rig rename:*)` | clean |
+  | run_toolchain | `Bash(npm:*)` `Bash(npx:*)` `Bash(pnpm:*)` `Bash(yarn:*)` `Bash(node:*)` `Bash(tsc:*)` `Bash(vitest:*)` `Bash(jest:*)` | clean (the known set) |
+  | run_arbitrary_shell | `Bash(*)` — this IS the `default_posture` knob | clean |
+  | network_egress | `Bash(curl:*)` `Bash(wget:*)` (partial) | **best_effort** — Claude has NO native network gate; real floor = Codex sandbox (route it there) |
+  | read_secrets | `Read(./.env)` `Read(~/.ssh/**)` `Read(**/*secret*)` (path-scoped) | **best_effort** — path-based, not secret-aware |
+  | install_dependencies | `Bash(npm install:*)` `Bash(pip install:*)` `Bash(brew install:*)` | clean |
+- **PREFIX-ONLY caveat** — cannot flag-precisely gate (`force_push` vs `push_to_remote` both match `Bash(git push:*)`); **target-first leak** (`rm <target> -rf` slips a `Bash(rm -rf*)` deny). Actions marked `best_effort` in the taxonomy (`force_push`, `delete_files`, `read_secrets`) → surface the caveat and prefer `ask` over a `deny` you can't enforce (a `deny` that leaks lies).
+- **PREFIX-COLLISION resolution (deterministic — resolve it, NEVER ask).** When two actions collapse to the SAME base prefix with different dispositions — the canonical case is `push_to_remote`=allow + `force_push`=ask, both basing to `Bash(git push:*)` — you cannot put that base prefix in both `allow` and `ask`. Resolve without a question-back:
+  - **Push allowed + force asked (Standard / Open):** put the base `Bash(git push:*)` per push's disposition (`allow`), AND add the flag-first force forms to `ask` (`Bash(git push --force:*)`, `Bash(git push -f:*)`, `Bash(git push --force-with-lease:*)`). RECORD in your diff that this is best-effort — flag-LAST force (`git push origin main --force`) leaks past the flag-first ask rules and runs under the allow. Don't block on it.
+  - **Push denied (Locked):** `Bash(git push:*)` in `deny` already covers force — no conflict.
+  This is a FIXED rule, not a user decision — apply it and note the leak. (A live cold-transfer FAILED because a fresh agent *blocked asking* "how to resolve the force_push/push_to_remote collision" instead of applying this default.)
+- **`defaultMode: "acceptEdits"` is the FLOOR and MUST be written into every Claude settings.json you produce.** It is not a knob you tune, but it IS a key you must always include — a config policy that omits it strips the floor (the cold-transfer failure). Live-confirmed schema: `{"permissions":{"allow":[],"ask":[],"deny":[],"defaultMode":"acceptEdits"}}`.
+
+### Codex — `~/.codex/config.toml` (via the existing X10 `codex_config_fragment` splice path — reuse, don't invent)
+- Codex is **per-posture, not per-action**: the whole action set **collapses** to the nearest `{sandbox_mode, approval_policy}` pair. **Built-in → posture** (VM-CONFIRMED @ Codex 0.120.0, 2026-08-03 — each posture applied to a real seat: read-only blocked writes+egress, workspace-write allowed writes/blocked egress, danger-full-access allowed both):
+
+  | Built-in | `sandbox_mode` | `approval_policy` | Collapse note (surface this to the user) |
+  |---|---|---|---|
+  | Locked | `read-only` | `on-request` | read-only blocks all writes + egress, prompts on escalation — OVER-restricts `edit_files` vs the Claude floor |
+  | Standard ⭐ | `workspace-write` | `on-request` | workspace writes allowed, egress blocked by sandbox, prompt on escalation — UNDER-gates `create_pr` (no per-action ask; folds into the prompt) |
+  | Open | `danger-full-access` | `on-failure` | everything allowed, prompt only on failure — OVER-permits the `destructive_class` vs the Claude ask-gates |
+  | YOLO | *(flag-surface — full-bypass launch flag, NOT config.toml)* | — | not a config write; the rip-out adapter owns it |
+
+  Valid values (VM-confirmed @ Codex 0.120.0): `sandbox_mode` ∈ {read-only, workspace-write, danger-full-access}; `approval_policy` ∈ {on-request, on-failure, never, untrusted, granular} (`granular` observed live at 0.120.0). ⚠ `on-failure` (used by Open) is marked **deprecated** in 0.120.0 help but still accepted — revisit if a future Codex drops it.
+- Surface the collapse: "Codex can't gate per-action; this policy becomes sandbox=X approval=Y, which over-permits Z / under-permits W."
+
+### Pi — NO permission surface at all (VM-confirmed Pi 0.83.0 — the earlier "approval bit" reading was WRONG)
+- **Pi has no tool-permission gate — neither a config store NOR a permission-posture flag.** Live verification confirmed: Pi 0.83.0's `--approve`/`-a` and `--no-approve`/`-na` govern **project-resource trust** (whether project extensions/resources appear in RPC `get_commands`), **NOT** tool-call approval. There is no sandbox or permission mechanism to map a policy onto.
+- So a permission policy **does not translate to Pi**. Do NOT say `--approve` = "auto-approve all", or that a posture "collapses to a Pi approval bit" — that was an earlier misread, corrected here. This skill computes **nothing** for Pi.
+- Whatever the OpenRig adapter sets (`--no-approve` by default) is a project-resource-trust floor, not a permission posture — not this skill's to derive.
+- Behavior to know (resource-trust, NOT permission-gating): under default ask / `--no-approve`, a project resource is silently **absent** from RPC `get_commands`; it appears under `--approve`. Never mistake that for permission enforcement.
+- **Say this to the user for a Pi seat:** "Pi has no permission-policy surface today — the policy applies to Claude/Codex; Pi runs under its project-resource-trust flag unchanged."
+
+## ⚠ The two warnings that save real fleets
+- **`ask` FREEZES an autonomous/headless Claude seat** — it hangs on the first non-edit op. So for autonomous fleets apply **Open/YOLO** (or a policy with no asks) **at setup** — the floor only covers edits; bash still asks without an applied policy. Never leave an autonomous seat on a policy with live `ask` gates. (Pi has no permission ask at all — see the Pi leg; Codex prompts per its posture, not per-action.)
+- **daemon-HOME ≠ seat-HOME** silently voids user-level writes — always the preflight check above.
+
+## The built-ins — DEFINED by the shipped policy spec files (translate FROM the spec; POINT, don't COPY)
+The four built-in policies ship as read-only spec files (`source: builtin`, `policy_schema_version: 1`) — they are the AUTHORITATIVE definitions. **Do NOT restate their action-sets here.** An earlier in-skill copy drifted (it under-asked `publish_package`/`merge_or_release`, which the spec ASKs) — the exact reason POINT-don't-COPY is the rule. Read the attached/selected spec and translate its semantic-action sets (`default_posture` / `allow` / `ask` / `deny` / `destructive_class`) per the three legs above.
+- **Locked / Standard ⭐ / Open** — `surface: config`. Translate to the Claude / Codex config surface. **Standard ⭐** is the recommended default: routine dev incl. push allowed, the outward/release/history-rewriting acts (`create_pr`, `publish_package`, `merge_or_release`, `force_push`) ASK, destructive_class ASKs. Standard has live `ask` gates → not for a headless-autonomous Claude seat (use Open or YOLO). Locked = deny-default whitelist; Open = allow-default, destructive_class asks only.
+- **YOLO** — `surface: flag`, `launch_posture: full_bypass`. This skill does **NOT** translate it — it points at OpenRig's deterministic flag-surface opt-in (the rip-out YOLO setting). When YOLO is on, any config-surface policy is MOOT (the bypass overrides it). (Subsumes the former "Operator".)
+
+Built-ins ship read-only in the package (canonical names); copy-to-customize into user space (custom, user-named); the `source:` frontmatter marker travels on copy. Onboarding presents these as a required MENU (explain each + ask which; no-choice = the floor).
+
+## Boundary (keeps this the only maintained piece)
+This skill TRANSLATES + APPLIES only. It does **not** define policies (the policy spec does) and does **not** enforce at the daemon (OpenRig is agnostic). Spec = *what* (neutral intent); this skill = *how, on this harness version* (the caveated, version-stamped translation).
+
+---
+*Stage: ESTABLISHED (2026-08-04) — both criteria met: (1) cold-transfer PASSING (rerun #2, verdict SHA 627abbb6, all 5 gate checks TRANSFER); (2) the built-in policy SPEC FILES landed (`source: builtin`, arch-accepted) as the authoritative source — the skill now translates FROM the spec and the interim in-skill pinned summary is retired (POINT-not-COPY). Config cells VM-CONFIRMED (Claude 2.1.220 / Codex 0.120.0); Pi has no permission surface (compute-nothing). Reviewed at push. feedback.md maintained.*

package/daemon/assets/plugins/openrig-core/skills/claude-compaction-restore/SKILL.md

@@ -4,15 +4,17 @@ description: Use when a Claude Code session has just compacted, is about to comp
 metadata:
   openrig:
     stage: factory-approved
-    last_verified: "2026-05-04"
-    distribution_scope: product-bound
-    source_evidence: |
-      Load-bearing for any OpenRig seat that may compact. PreCompact hook
-      is wired into Claude Code's settings (e.g. ~/.claude/settings.json)
-      so the restore packet is generated automatically before compaction.
     sibling_skills:
+      - mental-model-ha
+      - scope-recovery
+      - session-compaction-and-restore
       - agent-startup-and-context-ingestion
+      - agent-starters
+      - composable-priming-packs
+      - session-source-fork
       - seat-continuity-and-handover
+      - claude-compact-in-place
+      - pre-maintenance-agent-preservation
 ---
 
 # Claude Compaction Restore
@@ -105,6 +107,7 @@ After the first restore pass, audit yourself before continuing.
 
 ## Guardrails
 
+- Compaction is survival, not housekeeping — never compact to free space, "lean" a seat, or capture/prepare an agent starter (the `rig agent-image` library). It is lossy (a compacted Claude is confident-but-hollow); compact only when a seat is genuinely near its context limit, with a before/after plan. A starter's value is being *functional*, not small — see the `agent-starters` skill.
 - Do not silently launch fresh after compaction.
 - Do not continue from memory when restore evidence exists.
 - Do not defer required restore reading until a later user task. The restore is

package/daemon/assets/plugins/openrig-core/skills/claude-compaction-restore/scripts/precompact-hook.mjs

@@ -41,10 +41,6 @@ function readInstructionFile(filePath) {
   return fs.readFileSync(expanded, "utf8");
 }
 
-function sanitizeKey(value) {
-  return value.replace(/[^a-zA-Z0-9_.@-]/g, "_");
-}
-
 function sessionKey(input) {
   const raw = [
     process.env.OPENRIG_SESSION_NAME,
@@ -55,65 +51,13 @@ function sessionKey(input) {
     input.sessionName,
     input.transcript_path ? path.basename(input.transcript_path, ".jsonl") : "",
   ].find((value) => typeof value === "string" && value.trim().length > 0) || "unknown-session";
-  return sanitizeKey(raw);
-}
-
-// OPR.0.4.1.09 (rev1-r2 hook-path leak fix): MUST match claude-compaction-enforcer.ts
-// declaredSeatOf EXACTLY — a seat is authoritative ONLY inside a WELL-FORMED leading
-// frontmatter fence (opened AND closed `---`); the body is NEVER scanned; malformed/absent
-// frontmatter -> null (generic). Duplicated (not imported) because this hook is a standalone
-// portable plugin asset that cannot import the compiled daemon TS; semantics are kept
-// identical so the enforcer and hook paths refuse wrong-seat extras the same way.
-function declaredSeatOf(content) {
-  const fm = /^\s*---\s*\n([\s\S]*?)\n---/.exec(content);
-  if (!fm) return null;
-  const m = /^[ \t]*(?:target[_-]?seat|seat|session(?:[_-]?name)?)[ \t]*:[ \t]*["']?([^"'\n#]+?)["']?[ \t]*$/im.exec(fm[1]);
-  return m ? m[1].trim() : null;
-}
-
-// OPR.0.4.1.09 (rev1-r2): resolve the seat-safe EXTRA-FILE CONTENT for
-// postCompactInstruction, mirroring the enforcer resolvePostCompactExtra: (1) prefer the
-// PER-SEAT extra post-compact-extra/<seat>.md; (2) else the GLOBAL messageFilePath. In
-// EITHER case a file whose WELL-FORMED frontmatter declares a DIFFERENT seat is REFUSED
-// (returns "") so a foreign-seat extra never leaks into the marker via the hook path
-// (the enforcer path already refused it). Generic/this-seat/malformed -> inject.
-function readSeatSafeExtraFile(input, globalFilePath) {
-  const seatKey = sessionKey(input);
-  const refusedIfForeign = (content) => {
-    const declared = declaredSeatOf(content);
-    return declared && sanitizeKey(declared) !== seatKey ? "" : content;
-  };
-  // 1. Per-seat extra preferred (seat-keyed path; still defensively seat-checked to match
-  //    the enforcer, which refuses a per-seat file declaring a different seat).
-  const perSeatPath = path.join(getOpenRigHome(), "compaction", "post-compact-extra", `${seatKey}.md`);
-  if (fs.existsSync(perSeatPath)) {
-    return refusedIfForeign(fs.readFileSync(perSeatPath, "utf8"));
-  }
-  // 2. Global messageFilePath fallback, seat-checked.
-  if (!globalFilePath) return "";
-  const content = readInstructionFile(globalFilePath);
-  if (!content) return "";
-  return refusedIfForeign(content);
+  return raw.replace(/[^a-zA-Z0-9_.@-]/g, "_");
 }
 
 function pendingMarkerPath(input) {
   return path.join(getOpenRigHome(), "compaction", "restore-pending", `${sessionKey(input)}.json`);
 }
 
-// OPR.0.4.1.09: pointer to this seat's per-seat post-compaction extra
-// (compaction/post-compact-extra/<seat>.md), surfaced by the bridge reader.
-// Returned ONLY when it EXISTS, so the marker never points at an unresolvable
-// restoreMapPath; null otherwise.
-function perSeatRestoreMapPath(input) {
-  const p = path.join(getOpenRigHome(), "compaction", "post-compact-extra", `${sessionKey(input)}.md`);
-  try {
-    fs.accessSync(p);
-    return p;
-  } catch {
-    return null;
-  }
-}
-
 function writePendingRestoreMarker(input, parsed, restoreInstruction, customMessage) {
   const markerPath = pendingMarkerPath(input);
   fs.mkdirSync(path.dirname(markerPath), { recursive: true });
@@ -130,8 +74,6 @@ function writePendingRestoreMarker(input, parsed, restoreInstruction, customMess
     expectedAck: "restored from packet at <path>; resumed at step <X>",
     deliveredAt: null,
     deliveryCount: 0,
-    // OPR.0.4.1.09: per-seat restore-map pointer (post-compact-extra/<seat>.md) or null.
-    restoreMapPath: perSeatRestoreMapPath(input),
   };
   fs.writeFileSync(markerPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
   return markerPath;
@@ -144,7 +86,7 @@ function writePendingRestoreMarker(input, parsed, restoreInstruction, customMess
 // enabled but restore text has not been written yet, use OpenRig's default
 // instruction to load the canonical restore skill. Inline instructions and
 // file-path content are both included when both are configured.
-function readClaudeCompactionMessage(input) {
+function readClaudeCompactionMessage() {
   const configPath = path.join(getOpenRigHome(), "config.json");
   let inline = "";
   let filePath = "";
@@ -173,20 +115,17 @@ function readClaudeCompactionMessage(input) {
 
   const parts = [];
   if (inline && inline.length > 0) {
-    // Inline has no file/seat to declare; keep as-is.
     parts.push(`Inline restore instruction:\n${inline}`);
   }
-  // OPR.0.4.1.09 (rev1-r2): the FILE portion is SEAT-SAFE — per-seat extra preferred, a
-  // foreign-seat global refused (mirrors the enforcer). Checked even when messageFilePath
-  // is unset, because the per-seat extra is an independent mechanism (the enforcer also
-  // checks the per-seat path regardless of the global config).
-  try {
-    const fileText = readSeatSafeExtraFile(input, filePath);
-    if (fileText) {
-      parts.push(`Additional restore instruction file:\n${fileText}`);
+  if (filePath && filePath.length > 0) {
+    try {
+      const fileText = readInstructionFile(filePath);
+      if (fileText) {
+        parts.push(`Additional restore instruction file (${filePath}):\n${fileText}`);
+      }
+    } catch {
+      // Keep any inline instruction; unreadable extra files degrade quietly.
     }
-  } catch {
-    // Keep any inline instruction; unreadable extra files degrade quietly.
   }
   if (parts.length > 0) return parts.join("\n\n");
   if (policyEnabled && !inlineConfigured && !filePathConfigured) {
@@ -208,7 +147,7 @@ try {
     args.push(input.transcript_path);
   }
 
-  const customMessage = readClaudeCompactionMessage(input);
+  const customMessage = readClaudeCompactionMessage();
 
   const result = spawnSync("node", args, { encoding: "utf8" });
   if (result.status !== 0) {

package/daemon/assets/plugins/openrig-core/skills/delegating-work/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: delegating-work
+description: "Use when you have a task and must decide WHO does it — yourself, a spawned subagent, or another agent in the topology that already holds the context. The rule: how much would a blank slate have to read in to do this correctly? A lot → route to a context-holding agent; a little → subagent; unsure → a real agent or yourself. NOT the mechanics of fanning out (that's dispatching-parallel-agents / subagent-driven-development) — this is the who/whether decision, and the failure mode that makes teams abandon subagents."
+metadata:
+  openrig:
+    stage: field-captured
+---
+
+# Delegating work — who should do this task?
+
+## The core question: context performance
+Getting work done well is a context problem. The agent best suited to a task is **the one who already holds the context that task requires.** Before you spawn a subagent or grind it out yourself, ask who that is.
+
+## The decision
+**Ask: how much would a blank slate have to read in before it could do this correctly?**
+
+- **A lot to read in → route to a real agent in the topology that already holds it.** This is what the role structure is FOR — reviewers, QA, implementers who have been on a project over time. An agent that already understands the work produces a better, safer result than any amount of briefing.
+- **A little — a prompt plus light grounding is enough → spawn a subagent.**
+- **Genuinely unsure → err toward a real agent, or do it yourself.**
+
+## Subagents are underused — reach for them far more
+For self-contained work that is fully specifiable in the prompt, spawn a subagent instead of spending your own context: tracing, research, grounding passes, summarizing, scanning log files, searching, fetching, web search, mechanical extraction with citations. This is the common shape and it is under-used.
+
+## The failure mode — the part that matters most
+**Subagents start as blank slates, and you cannot anticipate everything they need to know.** Give one a task where there is a lot to understand and it will have blind spots it does not know it has — it will complete the task and **return a false conclusion**, not from weakness but because it lacked the context to know what "correct" even looked like.
+
+This is the unknown-unknowns problem, and it is the single most common subagent failure: **a poorly-contextualized summary is worse than no summary, because it arrives looking like an answer.** Overreliance on subagents for context-heavy work causes more problems than it solves — and a team burned by it stops using subagents at all, which is the wrong correction. The fix is not "avoid subagents"; it is "match the task to the context it needs."
+
+## The practical test
+Before delegating to a blank slate, ask: **would a wrong-but-plausible answer here be detectable?** If the requester cannot check the result against something they already know — a citation they can open, a count they can re-run — the blind-spot risk is unacceptable, and that task belongs with an agent that holds the context.
+
+## Worked examples
+- **GOOD (→ subagent):** extract how four apps implement a UI mechanism, with `file:line` citations and an explicit instruction to report facts, not recommendations. Self-contained; the requester can verify the citations.
+- **BAD to delegate blind (→ routed to the context-holder):** an independent security re-sweep of a rewritten git branch, where knowing which commit range must stay byte-identical, and that "lightly obfuscated real values" is the thing to hunt, takes a paragraph to explain and one sentence to get wrong. It went to the agent already holding the context.
+
+## It generalizes
+This is really **"route work to whoever holds the context,"** with subagents as the option for work that needs none. The audience is **every agent** — implementers and QA seats make this call as much as orchestrators do.
+
+## Once you've decided
+- Decided on subagents for 2+ independent tasks → `dispatching-parallel-agents` (the fan-out mechanics).
+- Subagents executing a plan's independent tasks → `subagent-driven-development`.
+- Routing to a real agent you will direct over multiple rounds → `directing-partner-agents`.
+- The right context-holder is the human → `human-in-the-loop`.

package/daemon/assets/plugins/openrig-core/skills/forming-an-openrig-mental-model/SKILL.md

@@ -1,22 +1,27 @@
 ---
 name: forming-an-openrig-mental-model
 description: |
-  Use when an agent is newly oriented to OpenRig and needs to form an accurate mental model of the system fast — what rigs are, how skills load, what the topology shapes mean, what the product loop is. For agents booting into a new seat or returning to OpenRig work after time away. NOT for HA-pair compaction recovery (that's the pair-of-seats coordination pattern; orientation is a solo task) or for specific operational procedures.
+  Use when an agent is newly oriented to OpenRig and needs to form an accurate mental model of the system fast — what rigs are, how skills load, what the topology shapes mean, what the product loop is. For agents booting into a new seat or returning to OpenRig work after time away. NOT for compaction recovery (use claude-compaction-restore for that) or for specific operational procedures.
 metadata:
+  cli_surfaces_referenced:
+    - ask
+    - capture
+    - down
+    - ps
+    - send
+    - transcript
+    - up
+    - whoami
   openrig:
     stage: factory-approved
-    last_verified: "2026-05-04"
-    distribution_scope: product-bound
-    source_evidence: |
-      Authored 2026-05-02 in response to founder-observed pattern: agents
-      Distinct from HA-pair mental-model preservation (which is a
-      pair-of-seats coordination pattern). This skill serves the legitimate
-      need to form an initial mental model of OpenRig as a system.
     sibling_skills:
       - openrig-user
       - openrig-operator
+      - openrig-builder
       - openrig-architect
-    transfer_test: pending
+      - openrig-upgrade
+      - ai-dev-workflows
+      - software-for-agents
 ---
 
 # Forming an OpenRig Mental Model
@@ -165,13 +170,14 @@ cost when you reach for one.
 | Home | Purpose |
 |---|---|
 | `<rig-cwd>/.claude/skills/`, `<rig-cwd>/.agents/skills/` | Where the harness actually loads from. Populated by `rig up`. |
-| `~/.claude/skills/`, `~/.agents/skills/` | Your personal/global skills + the OpenRig bootstrap set (openrig-user, openrig-operator, openrig-architect, forming-an-openrig-mental-model, plus the rest of the openrig-core plugin skills). |
-| openrig-core plugin skills | Product built-in skills that ship with OpenRig (installed via the openrig-core plugin). |
-| `~/.openrig/skills/` | Runtime install home for OpenRig-shipped skills. |
+| `~/.claude/skills/`, `~/.agents/skills/` | Your personal / user-installed global skills, loaded by the harness itself (independent of OpenRig). NOT where OpenRig's own bootstrap skills live — those ship in the product (below) and project into the cwd `.claude/skills/` at `rig up`. |
+| `openrig/packages/daemon/{specs/agents/shared/skills,assets/plugins/*/skills}/` | Product skills that ship with OpenRig — the spec pool + the bundled plugin assets (openrig-user, openrig-operator, openrig-architect, forming-an-openrig-mental-model, queue-handoff, claude-compaction-restore, …). |
+| `~/.openrig/skills/` | Future runtime install home for OpenRig-shipped skills. |
+| the skills authoring workspace | Skill authoring source (not runtime-loaded). |
 
-The harness only sees the first two. Other locations are shipping and
-source-of-truth — they reach the harness via projection or NPM install,
-not directly.
+The harness only sees the first two. Other locations are authoring,
+shipping, and source-of-truth — they reach the harness via projection or
+NPM install, not directly.
 
 ---
 
@@ -237,6 +243,8 @@ If you're booting into a new seat in an OpenRig rig:
 
 You're now oriented enough to start doing useful work.
 
+**Permission policy (at setup):** OpenRig sets only a minimal usability floor on your harness permissions, then offers recommended policies you opt into (Locked / Standard / Open — or YOLO to bypass). If you're creating or bringing up a rig, that's a choice you make, not something OpenRig decides for you — see openrig-user's "Permission policy — pick one at setup" and the `applying-a-permission-policy` skill.
+
 ---
 
 ## Going deeper (canonical references)
@@ -250,19 +258,25 @@ For real depth, these are the load-bearing canonical docs:
 | `openrig/docs/reference/rig-spec.md` | The RigSpec YAML format — pods, members, edges, all fields |
 | `openrig/docs/reference/agent-spec.md` | The AgentSpec YAML format — resources, profiles, imports |
 | `openrig/docs/reference/agent-startup-guide.md` | The 7-layer startup layering model; delivery hints |
+| the product taxonomy | Canonical vocabulary (read literally) |
+| `substrate/shared-docs/HOST-TOPOLOGY.md` | Host-level doctrine — rig classes, context patterns, lifecycle, authoring SOP |
+| `substrate/shared-docs/SUBSTRATE-CONVENTIONS.md` | Filesystem layout doctrine for substrate |
 | `https://agentskills.io/specification` | The cross-runtime skill standard |
 
-If your team maintains a host-level topology doc (rig classes, context
-patterns, authoring SOPs), read its rig-authoring section before
-touching YAML for high-stakes rigs.
+If you're going to be authoring rigs, read `HOST-TOPOLOGY.md` §7 (the
+authoring SOP) before touching YAML.
+
+If you're going to be doing skill work, read
+the factory-design reference and the
+`operating-the-skill-library` skill that lives in
+`substrate/shared-docs/rigs/skill-library/agents/shared/skills/`.
 
 ---
 
 ## What this skill is NOT for
 
-- **HA pair compaction recovery.** Forming an initial mental model is a
-  solo orientation task — different from the pair-of-seats coordination
-  pattern that preserves a shared mental model across compactions.
+- **Compaction recovery.** That's `claude-compaction-restore`. Different
+  skill, different scenario.
 - **Operating a specific rig.** Specific rigs have their own DESIGN.md and
   CULTURE.md. Read those.
 - **Authoring a new rig.** Use the `openrig-architect` skill for that.
@@ -285,7 +299,7 @@ that fit your actual work.
 | "I should manage Codex's compaction the way I manage Claude's" | No. Codex auto-compacts cleanly; Claude doesn't. Different runtimes, different lifecycles. |
 | "MEMORY.md auto-loads, so I don't need to read it" | Maybe. Sometimes MEMORY.md auto-loads via system reminders; sometimes not. Don't assume. If your work touches the topics it covers, read it explicitly. |
 | "Skills inherit from a parent or compose like classes" | No. Skills are flat artifacts; composition happens via AgentSpec `profile.uses.skills` (structural) or soft cross-references in skill bodies (advisory). Not via OO-style inheritance. |
-| "Any folder I keep skill files in is the canonical runtime path" | No. The harness only loads from `<rig-cwd>/.claude/skills/`, `<rig-cwd>/.agents/skills/`, and the runtime-installed plugin skills. Other folders are authoring or source-of-truth. |
+| "The substrate `shared-docs/skills/` folder is the canonical runtime path" | No. The harness doesn't read there. It's an authoring workspace. Runtime loads from `.claude/skills/`, `.agents/skills/`, and product built-in. |
 
 ---