@openrig/cli 0.5.6 → 0.5.8

package/daemon/context-packs/skills/seat-continuity-and-handover/references/apprentice-successor-seat-cutover.md

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

package/daemon/context-packs/skills/seat-continuity-and-handover/references/orchestrator-role.md

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

package/daemon/context-packs/skills/session-compaction-and-restore/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: session-compaction-and-restore
+description: Use when reasoning about what survives compaction/context-loss/restart/seat-refresh, designing a high-fidelity restore packet, or distinguishing native runtime resume vs fork vs artifact-backed mental-model rebuild. Covers the 4 failure modes that prevent honest restore (compacted seat drops hot potato; restore packet preserves details but loses product intent; runtime resume mistaken for handover or fork; rebuilt seat starts with stale instructions).
+metadata:
+  cli_surfaces_referenced:
+    - whoami
+  openrig:
+    stage: factory-approved
+    sibling_skills:
+      - claude-compaction-restore
+      - mental-model-ha
+      - scope-recovery
+      - agent-startup-and-context-ingestion
+      - agent-starters
+      - composable-priming-packs
+      - session-source-fork
+      - seat-continuity-and-handover
+      - retiring-and-inheriting-a-seat
+      - claude-compact-in-place
+      - pre-maintenance-agent-preservation
+---
+
+# Session Compaction and Restore
+
+Preserving useful working state across **compaction, context loss,
+restart, or seat refresh.** Includes Claude compaction restore, Codex
+resume/fork mechanics, transcript-based mental-model rebuilds, and
+durable handoff packets.
+
+**Long-lived seats are valuable only if they can survive context
+pressure.** If compaction turns a senior seat into a cold-started
+agent, users will avoid persistent topologies and fall back to
+throwaway agents.
+
+## Use this when
+
+- A seat is approaching compaction or just compacted
+- Designing a high-fidelity restore packet for an active workflow
+- Distinguishing native runtime resume vs fork vs artifact-backed mental-model rebuild
+- Reasoning about what should be preserved vs reconstructable
+- Auditing a restore for product-intent preservation (not just detail preservation)
+
+## Don't use this when
+
+- The session is fresh and has no working state to preserve
+- The intent is to *create* a new seat from a primed source — that's `session-source-fork` or `agent-starters`
+- The packet is a one-off snapshot for human review — restore packets are for re-entering active work
+
+## The 5 distinctions (do not collapse)
+
+Per the cross-runtime restore/reentry packet standard:
+
+| Mode | What it means | Outcome literal |
+|---|---|---|
+| **Native resume** | Continue the same managed seat with native runtime token | `resumed` |
+| **Fork** | New managed seat from prior native runtime conversation; new post-fork token | `forked` |
+| **Rebuild** | Fresh-launch seeded with operator-declared artifacts in trust-precedence order | `rebuilt` |
+| **Artifact-backed mental-model rebuild** | Restored seat derives understanding from a packet rather than native runtime continuity | (case of `rebuilt`) |
+| **Fresh launch** | New agent without prior continuity | `fresh` |
+
+These are load-bearing distinctions. **Do NOT collapse `fork` into
+artifact-backed reentry; do NOT collapse `rebuild` into fork.**
+
+## The three mechanisms — who owns each (verified vs main d37a08ad, 2026-07-21)
+
+The outcomes above ride on three DISTINCT mechanisms; keep them separate:
+
+1. **Claude built-in `/compact`** — a Claude Code HARNESS feature, **not OpenRig
+   code**. OpenRig only *emits* the literal `/compact` toward the pane after a prep
+   turn; there is no compaction algorithm in the OpenRig repo. Provider-owned.
+2. **OpenRig-managed restore** — the enforcer + hook bridge: a precompact hook
+   WRITES a restore packet; a bridge READER injects exactly ONE restore directive
+   back via the harness hook channel (`hookSpecificOutput.additionalContext`),
+   seat-isolated. The OpenRig-owned half.
+3. **Codex session continuity** — resume/rollout tokens (`codex resume <token>`),
+   a separate path from the Claude mechanisms. Never conflate with Claude restore.
+
+**Safety boundary (ties to `native-session-file-lab-boundary`):** no supported
+OpenRig path EDITS provider-owned native **session / auth / transcript** files to
+inject context. Context enters ONLY through sanctioned channels: the hook
+`additionalContext`, a normal user message via `rig send`, or Codex resume tokens.
+Precise nuance: OpenRig *does* write `~/.codex/config.toml` — but only to install
+OpenRig activity **hooks** and `[features]`, never session or auth state. So the
+rule is "never edits native session/auth/transcript files," NOT "never touches any
+provider-owned file."
+
+## Current CLI surface (operator / kernel seats; verified vs main d37a08ad)
+
+Managed compaction/restore is driven by five shipped verbs — pick per intent, and
+stay durable-substrate-first (the packet/artifacts are the truth; the CLI is the trigger):
+
+- **`rig compact <session>`** — guided managed compaction for ONE Claude seat
+  (prep → `/compact` → restore → audit). Non-Claude seats rejected. ~180s.
+- **`rig compact-plan`** — READ-ONLY triage; *does not compact*. Flags `--rig`,
+  `--refresh`, `--threshold-tokens`, `--threshold-percent`. (Codex seats flagged
+  `codex_not_managed_by_claude_compact_in_place`.)
+- **`rig restore-check`** — restore-readiness probe across running rigs; read-only;
+  exit 0/1/2. Flags `--full`, `--ready`, `--rig`, `--no-queue`, `--no-hooks`.
+- **`rig restore-packet {write,read,validate}`** — the cross-runtime restore
+  packet (v0): write / read / validate the durable packet this skill's contract defines.
+- **`rig restore <snapshotId> --rig <rigId>`** — ⚠ RIG SNAPSHOT restore (infra), a
+  DIFFERENT mechanism — NOT session-context restore. Do not conflate.
+
+## Failure modes (4)
+
+1. **A compacted seat forgets active workflow state and drops the hot potato.** Compaction without continuity preservation is silent failure.
+2. **A restore packet preserves details but loses the user's product intent.** Restore must preserve *why this work matters*, not just *what was happening*.
+3. **A runtime resume is mistaken for a seat handover or fork.** These have different continuity outcomes and provenance — don't conflate.
+4. **A rebuilt seat starts with stale instructions that conflict with current workflow mode.** Restore must include current state, not just historical state.
+
+## Proof standard
+
+Proof should include a deliberate compaction/restart of a seat with
+active work, followed by **measured recovery**: identity, current
+workflow, next owner, relevant files, and constraints all restored
+without human re-briefing.
+
+## Canonical packet contract (16-field, v0)
+
+The cross-runtime restore/reentry packet standard v0 defines:
+
+- Source/target identity
+- Runtimes
+- Workspace root, default repo, role pointer
+- Bounded latest transcript
+- Touched-path inventory
+- Durable work pointers
+- Current work + next owner
+- Caveats + authority boundaries
+- Omitted classes + redaction policy
+- Source-trust ranking
+- Generated-at + generator version
+
+Plus a 6-item restored-seat acceptance checklist.
+
+Source-trust ranking applies when restored seat ingests packet evidence:
+**`rig whoami` > target rigspec > bounded latest transcript > full
+transcript > touched-files > `restore-summary.json`.**
+
+## Memory surfaces consumed at restore time
+
+This primitive consumes multiple externalized memory surfaces. Per the
+externalized-memory-surfaces convention's 13-row first inventory pass,
+the primary rows for restore are:
+
+| Row | Surface |
+|---|---|
+| 1 | Transcripts |
+| 2 | Durable chat |
+| 3 | Startup replay context |
+| 5 | Checkpoints |
+| 12 | Restore/reentry packets and Agent Starters |
+
+The umbrella's authority-rank + permission-posture columns govern which
+surfaces a restore path can write vs only read.
+
+## See also
+
+- `claude-compaction-restore` skill — the Claude Code restore SOP (PreCompact hook + JSONL restore script for post-compaction recovery)
+- `mental-model-ha` skill — HA-pair compaction recovery (different scenario; sister primitive)
+- `session-source-fork` skill — `fork` mode for native-runtime-continuity-based restoration
+- `seat-continuity-and-handover` skill — occupant-creation primitives (resume/fork/rebuild/fresh) that this primitive instantiates
+- `externalized-memory-surfaces` skill — umbrella convention listing all surfaces this primitive consumes

package/daemon/context-packs/skills/session-compaction-and-restore/manifest.yaml

@@ -0,0 +1,10 @@
+# GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
+# Package-time projection of a canonical skill; regenerated every build.
+name: "session-compaction-and-restore"
+version: "0.5.8"
+taxonomy: "skills"
+purpose: "Use when reasoning about what survives compaction/context-loss/restart/seat-refresh, designing a high-fidelity restore packet, or distinguishing native runtime resume vs fork vs artifact-backed mental-model rebuild. Covers the 4 failure modes that prevent honest restore (compacted seat drops hot potato; restore packet preserves details but loses product intent; runtime resume mistaken for handover or fork; rebuilt seat starts with stale instructions)."
+files:
+  - path: "SKILL.md"
+    role: "instruction"
+    summary: "Use when reasoning about what survives compaction/context-loss/restart/seat-refresh, designing a high-fidelity restore packet, or distinguishing native runtime resume vs fork vs artifact-backed mental-model rebuild. Covers the 4 failure modes that prevent honest restore (compacted seat drops hot potato; restore packet preserves details but loses product intent; runtime resume mistaken for handover or fork; rebuilt seat starts with stale instructions)."

package/daemon/context-packs/skills/software-for-agents/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: software-for-agents
+description: |
+  Use when building, modifying, or diagnosing an OpenRig or studio-box system; when surprising behavior
+  looks like a code bug but may come from Markdown, YAML, JSON, bootstrap files, schemas, skills, or
+  conventions; or when deciding whether an agent-built studio app needs a separate mockup phase. NOT for
+  treating defects in OpenRig core or rigs.to as tolerable control-plane drift.
+metadata:
+  openrig:
+    stage: factory-approved
+    audience: any agent building on OpenRig or a studio box — the first-load mental model
+    sibling_skills:
+      - forming-an-openrig-mental-model
+      - openrig-program-manager
+      - mission-slice-sop
+      - openrig-user
+---
+
+# Software for agents — the markdown control plane
+
+## Where this applies — and where it does NOT (read this first)
+
+This mental model — *most bugs are coherence gaps, not code*; *ship-and-flag when unsure*; iterate fast —
+is scoped to **agent-managed software: the studio-box mini-apps and any agent-in-the-middle / rapidly-
+evolving lightweight UI** where an agent sits in the loop and downstream cleanup is cheap. It is NOT a
+universal license.
+
+**It does NOT apply to TRADITIONAL software held to a rock-solid, no-bugs bar:** the **OpenRig CLI
+surfaces**, the **OpenRig repo** (daemon / CLI / UI / adapters), and the **rigs.to website**. There, a bug
+is a bug — reproduce it, fix it in code, hold the full-rigor gate. Do NOT treat a real defect there as a
+markdown coherence gap, and do NOT "ship and flag." If you are building or fixing OpenRig core or rigs.to,
+the tolerance in this skill is OFF and `product-is-the-truth-not-the-proof` governs. **Know which lane
+you're in before you apply anything below.**
+
+---
+
+You inherited the accumulated footgun-map of thousands of rigs that ran before you. They found and
+solved most of the traps. Your job is to find the *next* one and patch it at the precise optimal spot
+in the substrate, so the rig after you starts from a higher ledge. That is the actual work. Whatever
+you were "assigned" (a video, a feature, a fix) is the vehicle for surfacing it.
+
+## 1. This is not traditional software — it's a control plane made of markdown
+
+In traditional software a bug is a broken function you fix in code. Here, the system you operate in is
+an **agent-in-the-middle** system whose substrate is **markdown + YAML + JSON + folders**: skills,
+instructions, bootstrap files (`CLAUDE.md`/`AGENTS.md`), schemas, `culture.md`, mission/slice notes,
+conventions. **The agents ARE the backend.** So most "bugs" are not broken code — they are **coherence
+failures in the markdown layer**: an instruction that's unclear or missing, a schema that drifted from
+its documented state, a convention living in one seat's head instead of a skill.
+
+**Consequence:** when something surprises you, your first hypothesis is *"the control plane is unclear
+or drifted here,"* not *"the code is broken."* Sometimes it IS the code (fix it — don't overfit on
+markdown; see §5, and mind the scope block above: in OpenRig core / rigs.to the code IS the first
+hypothesis). But the highest-leverage fixes in the agent-managed layer are usually: make the substrate
+coherent again at the exact spot the confusion arose. Keep the markdown/schemas/conventions in sync with
+reality and the system **self-improves** — the next rig inherits the patched substrate and never re-hits it.
+
+## 2. Progressive disclosure — skills are a hot tier, not a manual
+
+Skills are misnamed. They are a **progressive-disclosure primitive**. Think CPU cache / hot storage
+tier: the **name + description of every skill is always ambiently loaded** — a hot tier of awareness
+the agent carries without opening anything. That is enormous leverage, good or bad. So:
+
+- **Write skill name + description as TRIGGERS** — *why/when do you reach for this?* — not as titles.
+  The hot tier's whole job is to fire when an agent doesn't yet know it needs the skill (the
+  "you don't know what you don't know" problem). This skill's own description is written that way.
+- **Reaching for a skill unfurls a trail.** A good skill routes you — breadcrumbs, pointers, maps —
+  so it becomes *inevitable* you find the exact context on disk for what you're doing.
+- **If the context doesn't exist, generate it.** A skill can ship **scripts** that produce context
+  optimally shaped for a decision, or that execute a fiddly API surface so you don't stumble through 12
+  tool calls discovering it. Use a **script as a prompt**: run it — if it works, the result IS your
+  context; if it fails, it should fail in a way that *teaches* you how the system works, so you can
+  read the script, understand the edge case, and do the thing manually. Scripts belong in the skill
+  folder next to the SKILL.md.
+
+## 2b. Self-certifying artifacts — the convention 5 seats (both models) converged on
+
+The single most expensive failure class in production is **not being able to tell a finished artifact
+from an unfinished one.** A mid-write file read as final; a render OOM-killed mid-write left a corrupt
+`.mp4` that passed a filename check; a truncated clip passed a duration check and froze on playback. In
+one build, five seats — Claude *and* Codex, independently — each invented a *different* ad-hoc
+completeness check (ffprobe moov, duration compare, filename convention, manifest assetExists, ffmpeg
+input count). Five blind spots. So make it ONE shared primitive:
+
+**When you author ANY tool that produces an artifact (render / composite / export / cut), it must
+self-certify:**
+1. Write to `<name>.partial` (never the final path directly).
+2. **Verify the content** — the specific property that can be wrong, not a proxy: moov atom present,
+   duration matches the intended window, audio stream present, colorspace/hue correct, resolution =
+   delivery res. (Filename ≠ correct; duration ≠ complete; "clean-encoded" ≠ right.)
+3. **`fsync`, then atomically `rename`** `<name>.partial` → `<name>` (rename is atomic; a half-written
+   file never appears at the real path).
+4. Write the manifest, then a **`.done` sentinel LAST.**
+
+Then *"is this finished?"* is **one `stat` of `<name>.done`** — identical for every tool, seat, watcher,
+and a compacted agent restoring cold (who is least equipped to know what was mid-write when the lights
+went out). **Consumers fail closed:** e.g. a swap-into-slot (`restore_occupant`) must refuse an artifact
+lacking `.done` or failing the verify-gate. This convention collapses the whole "content over filename,
+disk over memory" discipline into one check the substrate enforces for you. Build the sentinel; the
+workarounds disappear. (Code-side companion: a fail-closed verify-gate wired into the swap verb — a
+coordinated build with the tool owner, not a solo markdown edit.)
+
+## 3. Build it like software — piggyback on what agents are trained for
+
+Agents are fine-tuned to write code and build software; the harness itself is a terminal/coding
+instrument. So **whatever you're asked to build — even a video — map the process to a software SDLC**
+and you inherit all that baked-in muscle memory. This is why, e.g., the mini-NLE's beats carry
+reference IDs like `1.1 / 2.1`: a storyboard is the **human-facing visual metaphor**, but underneath it
+is a **specification** — sections, beats, success criteria, the thing being built.
+
+Use an **agent SDLC**, not the antiquated human one (which was shaped around human-org weaknesses):
+**intent → plan → spec → build → verify → review → QA → done.** The human slots in as **steering,
+judgment, taste, review**; the agents do the technical nitty-gritty, in parallel, fast. Map any
+"build X with agents" task onto this and the primitives (specs, locks, proof, verification) become
+intuitive instead of alien.
+
+## 4. Phases and the LOCK gate (spec-locking, not just "done")
+
+Building runs in **phases**, and each phase has a **lock gate** — you don't advance until the taste/
+steering owner has locked it. This is exactly *don't start building until the PRD is locked by product*:
+
+- **Storyboard / intent phase** — done on the **canvas** now (the highest-bandwidth human↔agent surface:
+  the human steers, chats, annotates/circles; agents build structure fast). Iterate here; get the
+  storyboard through the canvas gate. (Canvas largely replaced the NLE's old in-timeline storyboard.)
+- **Plan phase (brief, in the NLE)** — build the spine with placeholders so the human can click through
+  the main-stage player and *feel the flow* (sequencing problems surface when placeholders are strung
+  together with audio). **Lock every beat** = the spec is approved; this is what unlocks parallel build.
+- **Fill phase** — many agents build each beat in parallel, in clear lanes. **Lock a beat when it's
+  final** (`/api/approve`): lock means *don't touch, we're good, signal to everyone incl. the human.*
+  Unlock to revise. **All beats locked = done.**
+
+The lock is the "finished" primitive at the editorial layer. Locking a whole phase's beats before the
+next phase is the discipline that lets 10 agents work in parallel without catastrophic collisions —
+everyone knows the target, their lane, and who judges done (the **producer owns the final product**).
+
+## 4b. Studio apps skip the mockup phase — the build IS the mockup
+
+For a **studio app**, do not run a separate mockup phase. The whole point of the Studio is that a mockup
+buys you almost nothing here: **as fast as it takes to build a mockup, you can build the running app** —
+an unlock made possible by agentic engineering. A mockup is only ever a device to flesh out the PRD; once
+the PRD and its settled answers exist, that phase is **done**. The Studio is a lightweight, rapid-velocity,
+agent-in-the-middle leveraged system: build apps fast, iterate on them fast.
+
+The phase model above collapses accordingly:
+
+1. **The PRD + settled answers ARE the fleshed intent** — no separate mockup gate, no plan-lock-on-mockups step.
+2. **Spec-lock the WHAT** — `rig scope slice approve --scope spec` locks the intent the PRD already fleshed.
+3. **BUILD the app**, then **iterate on the RUNNING app at mockup speed** — the running thing is the
+   iteration surface, not an image.
+4. **LOOK is on the running screens** (any "mockup" proof tag now points at the running app's screens),
+   then **proof-lock** — `rig scope slice approve --scope delivery`. A slice is not done until every
+   proof-contract item has evidence from the **running app**.
+
+**Velocity is the METHOD, not a quality waiver.** The LOOK is still a real LOOK; the proof contract still
+binds at delivery. You are removing a redundant artifact, not lowering the bar.
+
+**Scope — this does NOT generalize** (consistent with the scope block at the top): it applies to the
+studio-app / agent-in-the-middle loop only. Outside that loop, a **locked design mockup that a slice must
+match is still legitimate** — do not strip mockups from traditional or design-locked work. Know which lane
+you're in. For the build mechanics, see the studio's build skill (`building-studio-apps`); this section is
+the *why* and *when*.
+
+## 5. Where to fix — and don't overfit on markdown
+
+- **Precise-spot discipline:** find the *one* place a coherence fix belongs (the skill, the schema, the
+  bootstrap, `culture.md`) so it can't recur — not a symptom patch. Ask: *what would have prevented
+  this for every future rig?*
+- **Don't overfit on the markdown layer** — deterministic code bugs exist and you should fix them. The
+  studio-box apps (NLE, canvas, media manager, shell) live in the **studio-box repo**, portable across
+  hosts (VPS/Mac/VM). **A code fix there fixes ALL studio boxes, not just this host** — so: clear bug or
+  broadly-useful feature → ship it; host-specific behavior → make it optional/guarded. When unsure, ship
+  and flag it; downstream cleanup beats you becoming the bottleneck. *(This ship-and-flag latitude is the
+  studio-box / agent-managed lane only — re-read the scope block: OpenRig core + rigs.to hold the
+  rock-solid bar, no ship-and-flag.)*
+- **Culture lives in `culture.md`** — the rig's social contract / constitution: how the team
+  coordinates, the parallel-agent lanes, the phase-locking discipline, who owns the final call.
+  Coordination is largely **emergent** (bottom-up, evolutionary pressure across thousands of rigs) — but
+  once a pattern proves out, *write it down there* so it's inherited, not re-discovered.
+
+## The one-line seed
+You're not maintaining code; you're **gardening a self-improving control plane made of markdown and
+schemas, using software-engineering muscle memory, with the lock as your spec-gate** — and every
+footgun you patch at the right spot (in the agent-managed lane) makes every future rig better. See also:
+`forming-an-openrig-mental-model` (the OpenRig runtime), `mission-slice-sop` (the SDLC operating
+procedure), `openrig-user` (the CLI surface), `product-is-the-truth-not-the-proof` (the doctrine that
+governs the rock-solid lane). *(The "agents ARE the backend" idea — agent-in-the-middle — is inlined in
+§1; a standalone `agent-in-the-middle` skill is a future candidate, not yet authored.)*