@openrig/cli 0.5.1 → 0.5.3

package/daemon/assets/plugins/openrig-core/skills/claude-compaction-restore/scripts/restore-from-jsonl.mjs

@@ -3,12 +3,26 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import crypto from "node:crypto";
 
 const TEXT_LIMIT = 4000;
-// P6(C) injectable output-root (mirrors precompact-hook.mjs): per-run isolation when
-// OPENRIG_COMPACTION_OUT_ROOT is set, real /tmp default in production. Guards a direct
-// invocation (the hook passes --out explicitly) against the same cross-writer collision.
-const DEFAULT_OUT = process.env.OPENRIG_COMPACTION_OUT_ROOT || "/tmp/claude-compaction-restore";
+const BASE64_RUN = 800; // strip contiguous base64 runs at least this long (screenshots, data URIs)
+
+function sha256(text) {
+  return crypto.createHash("sha256").update(String(text ?? "")).digest("hex").slice(0, 16);
+}
+
+// R3: replace binary / base64 payloads (data: URIs, long base64 runs) with a compact marker,
+// so a single screenshot block does not blow the transcript into un-chunkable size.
+function stripBinary(text) {
+  let s = String(text ?? "");
+  s = s.replace(/data:([\w.+-]+\/[\w.+-]+)?;base64,[A-Za-z0-9+/=\s]{200,}/g,
+    (m, mime) => `[binary omitted: ~${m.length} bytes${mime ? `, ${mime}` : ""}]`);
+  s = s.replace(new RegExp(`[A-Za-z0-9+/]{${BASE64_RUN},}={0,2}`, "g"),
+    (m) => `[base64 omitted: ~${m.length} bytes]`);
+  return s;
+}
+const DEFAULT_OUT = "/tmp/claude-compaction-restore";
 
 function parseArgs(argv) {
   const args = {
@@ -86,8 +100,9 @@ function stringifyContent(content) {
       .map((block) => {
         if (typeof block === "string") return block;
         if (block?.type === "text") return block.text ?? "";
+        if (block?.type === "image") return `[image omitted: ${block.source?.media_type ?? "image"}]`;
         if (block?.type === "tool_use") return `[tool_use:${block.name}] ${JSON.stringify(block.input ?? {})}`;
-        if (block?.type === "tool_result") return `[tool_result] ${truncate(stringifyContent(block.content), TEXT_LIMIT)}`;
+        if (block?.type === "tool_result") return `[tool_result] ${truncate(stripBinary(stringifyContent(block.content)), TEXT_LIMIT)}`;
         return JSON.stringify(block);
       })
       .join("\n");
@@ -239,6 +254,8 @@ function analyze(jsonlPath, cwd) {
   const records = readJsonLines(jsonlPath);
   const registry = createRegistry();
   const transcript = [];
+  const narrative = []; // R4: message-turns only (assistant/user text), no tool bodies
+  const readTargets = new Map(); // R1: tool_use_id -> file_path for Read calls
   const cwdCounts = new Map();
   let sessionId = null;
 
@@ -262,20 +279,26 @@ function analyze(jsonlPath, cwd) {
 
     if (typeof content === "string") {
       transcript.push(`\n## ${role}\n\n${content}`);
+      narrative.push(`\n## ${role}\n\n${content}`);
       for (const file of extractPaths(content, cwd)) registry.add(file, "mentioned", `${role}:text`);
       continue;
     }
 
     if (!Array.isArray(content)) continue;
     const parts = [];
+    const narrativeParts = [];
     for (const block of content) {
       if (block?.type === "text") {
         parts.push(block.text ?? "");
+        narrativeParts.push(block.text ?? "");
         for (const file of extractPaths(block.text ?? "", cwd)) registry.add(file, "mentioned", `${role}:text`);
       } else if (block?.type === "tool_use") {
         const name = block.name ?? "unknown";
         const input = block.input ?? {};
         parts.push(`\n[tool_use:${name}]\n${JSON.stringify(input, null, 2)}`);
+        if (name === "Read" && block.id && (input.file_path || input.path)) {
+          readTargets.set(block.id, input.file_path || input.path);
+        }
         const kind = toolKind(name, input);
         if (input.file_path) registry.add(normalizeFile(input.file_path, cwd), kind, `tool:${name}:file_path`);
         if (input.path) registry.add(normalizeFile(input.path, cwd), kind, `tool:${name}:path`);
@@ -284,12 +307,21 @@ function analyze(jsonlPath, cwd) {
           for (const file of extractPaths(text, cwd)) registry.add(file, kind, `tool:${name}:input`);
         }
       } else if (block?.type === "tool_result") {
-        const resultText = stringifyContent(block.content);
-        parts.push(`\n[tool_result]\n${truncate(resultText, TEXT_LIMIT)}`);
+        const resultText = stripBinary(stringifyContent(block.content));
+        const target = block.tool_use_id && readTargets.get(block.tool_use_id);
+        if (target) {
+          // R1: a Read result reproduces a whole file — emit a pointer, not the body.
+          // The live file is current; this transcript copy is a snapshot that may be stale.
+          const lineCount = resultText.split("\n").length;
+          parts.push(`\n[tool_result: Read ${target} — ${lineCount} lines, sha256 ${sha256(resultText)} — READ THE LIVE FILE; this snapshot may be stale]`);
+        } else {
+          parts.push(`\n[tool_result]\n${truncate(resultText, TEXT_LIMIT)}`);
+        }
         for (const file of extractPaths(resultText, cwd)) registry.add(file, "mentioned", "tool_result");
       }
     }
     if (parts.length) transcript.push(`\n## ${role}\n\n${parts.join("\n")}`);
+    if (narrativeParts.some((p) => String(p).trim())) narrative.push(`\n## ${role}\n\n${narrativeParts.join("\n")}`);
   }
 
   const rankedFiles = registry
@@ -300,12 +332,17 @@ function analyze(jsonlPath, cwd) {
   const cwdRanked = [...cwdCounts.entries()].sort((a, b) => b[1] - a[1]);
   const effectiveCwd = cwdRanked[0]?.[0] ?? cwd;
 
+  const transcriptText = transcript.join("\n");
+  const narrativeText = narrative.join("\n");
   return {
     sessionId,
     jsonlPath,
     cwd: effectiveCwd,
     records: records.length,
-    transcript: transcript.join("\n"),
+    transcript: transcriptText,
+    narrative: narrativeText,
+    transcriptTokens: Math.round(transcriptText.length / 4),
+    narrativeTokens: Math.round(narrativeText.length / 4),
     files: rankedFiles,
     docs: discoverDocs(effectiveCwd),
   };
@@ -346,10 +383,18 @@ function restoreInstructions(summary, outputPaths) {
   lines.push("You have just been compacted or are restoring a compacted Claude Code seat. Your mental model is compressed and unreliable.");
   lines.push("");
   lines.push(`- JSONL transcript: \`${summary.jsonlPath}\``);
-  lines.push(`- Reconstructed transcript: \`${outputPaths.transcript}\``);
+  lines.push(`- Reconstructed transcript: \`${outputPaths.transcript}\` (~${summary.transcriptTokens ?? "?"} tokens — do NOT read front-to-back)`);
+  lines.push(`- Narrative companion (READ THIS FIRST): \`${outputPaths.narrative}\` (~${summary.narrativeTokens ?? "?"} tokens — message turns only, no tool bodies)`);
   lines.push(`- Touched-file triage: \`${outputPaths.touchedFiles}\``);
   lines.push(`- Working directory inferred: \`${summary.cwd}\``);
   lines.push("");
+  lines.push("## Read budget (the restore must leave room for the work)");
+  lines.push("");
+  lines.push(`- The full transcript is ~${summary.transcriptTokens ?? "?"} tokens. **Reading it front-to-back can consume the window the restore exists to rebuild.**`);
+  lines.push(`- Default order: read the **narrative companion first** (~${summary.narrativeTokens ?? "?"} tokens — message turns + decisions), tail-first (most recent first).`);
+  lines.push("- Drop to the full transcript only for a specific question the narrative can't answer. File bodies inside tool-results are pointers now — **read the live file, not the transcript snapshot.**");
+  lines.push("- Read to a budget with a stopping rule; report depth honestly (an honest PARTIAL beats a false completion). See the skill's *Required Read-Depth Audit*.");
+  lines.push("");
   lines.push("## Required Sequence");
   lines.push("");
   lines.push("1. Read this file and `touched-files.md`.");
@@ -378,31 +423,25 @@ function restoreInstructions(summary, outputPaths) {
   return lines.join("\n");
 }
 
-// A3-R3 injectable clock (slice 51-01): the packet output-dir timestamped path
-// defaults to real wall-clock, but becomes deterministic when the shared hermetic
-// env-var OPENRIG_TEST_CLOCK_NOW is set (an ISO instant). Empty/absent = production.
-function nowIso() {
-  const injected = process.env.OPENRIG_TEST_CLOCK_NOW;
-  return typeof injected === "string" && injected.trim().length > 0 ? injected : new Date().toISOString();
-}
-
 function writeOutputs(summary, outRoot) {
-  const stamp = nowIso().replace(/[:.]/g, "-");
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
   const base = path.join(outRoot, `${summary.sessionId ?? "unknown-session"}-${stamp}`);
   fs.mkdirSync(base, { recursive: true });
 
   const outputPaths = {
     dir: base,
     transcript: path.join(base, "transcript.txt"),
+    narrative: path.join(base, "transcript-narrative.txt"),
     touchedFiles: path.join(base, "touched-files.md"),
     instructions: path.join(base, "restore-instructions.md"),
     summary: path.join(base, "restore-summary.json"),
   };
 
   fs.writeFileSync(outputPaths.transcript, summary.transcript || "(no message transcript reconstructed)\n");
+  fs.writeFileSync(outputPaths.narrative, summary.narrative || "(no narrative reconstructed)\n");
   fs.writeFileSync(outputPaths.touchedFiles, markdownFileList(summary.files));
   fs.writeFileSync(outputPaths.instructions, restoreInstructions(summary, outputPaths));
-  fs.writeFileSync(outputPaths.summary, JSON.stringify({ ...summary, transcript: undefined, outputPaths }, null, 2));
+  fs.writeFileSync(outputPaths.summary, JSON.stringify({ ...summary, transcript: undefined, narrative: undefined, outputPaths }, null, 2));
 
   return outputPaths;
 }
@@ -421,6 +460,9 @@ function main() {
     jsonlPath,
     outputDir: outputPaths.dir,
     transcript: outputPaths.transcript,
+    narrative: outputPaths.narrative,
+    transcriptTokens: summary.transcriptTokens,
+    narrativeTokens: summary.narrativeTokens,
     touchedFiles: outputPaths.touchedFiles,
     instructions: outputPaths.instructions,
     fileCount: summary.files.length,
@@ -432,7 +474,8 @@ function main() {
     console.log(`Restore packet: ${result.outputDir}`);
     console.log(`Instructions: ${result.instructions}`);
     console.log(`Touched files: ${result.touchedFiles}`);
-    console.log(`Transcript: ${result.transcript}`);
+    console.log(`Narrative (read first): ${result.narrative} (~${result.narrativeTokens} tokens)`);
+    console.log(`Transcript (drill-down): ${result.transcript} (~${result.transcriptTokens} tokens)`);
   }
 }
 

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

@@ -1,7 +1,11 @@
 ---
 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 compaction recovery (use claude-compaction-restore for that) or for specific operational procedures.
+description: >-
+  Use when the system around you does not make sense yet: you just booted into a seat and do not
+  know how the pieces fit; someone said rig, pod, seat, fleet, topology, or slice and you are not
+  certain what they mean here; you are unsure what kind of rig you are in or what it is for; you do
+  not know how skills reach you or where context comes from; or you are about to act on a guess
+  about how OpenRig works. Gives the runtime mental model fast, so you stop guessing.
 metadata:
   cli_surfaces_referenced:
     - ask

package/daemon/assets/plugins/openrig-core/skills/messaging-the-human/SKILL.md

@@ -28,8 +28,10 @@ metadata:
 rig send operator-human@your-rig "your message"
 ```
 
-That goes straight to the human's Slack. That is the entire *how*. Everything
-below is the *when* and the *who* — which is the part that actually matters.
+That goes straight to the human's Slack — that is the *how* for **text**. For **images**
+(screenshots, renders), send through the **image connector** instead; text and images are separate
+live channels today (a release upgrade will unify them). Either way the *how* is trivial; everything
+below is the *when* and the *who* — the part that actually matters.
 
 ## The mental model: the human is a scarce attention resource managing by exception
 
@@ -63,6 +65,30 @@ test is: **"would he want to know this?"** If yes, send it. Lean toward sending
 genuine signal and real good news; do not manufacture noise or narrate routine
 churn. Discernment is the skill: you are curating his attention, not flooding it.
 
+### The v0 event classes — reach out on these, unprompted
+
+"Use discretion" left the *when* unspecified, so it did not happen — the channel exists and nobody
+reaches for it. Here are the **named event classes** that should trigger a proactive message —
+anchors for the judgment, not an exhaustive gate:
+
+- **Model-fallback boots** — a seat that came up on a fallback model instead of its pinned one. Send
+  on **every occurrence**; a silent downgrade is exactly what the human needs to see.
+- **Capacity / authority requests** — you need a fork/spin-up authorization, a spend-or-limit call, or
+  any authority only the human holds. This is a **guaranteed-answer** path — don't sit blocked on it.
+- **Security-category flags** — anything in the security / consequence-boundary class.
+- **Acceptance / milestone moments** — a slice proven, a release cut, a real "it's done and it works."
+- **Human-addressed work blocked beyond its settle window** — a decision or request routed to the
+  human that has sat past the time it should have moved.
+- **Idle / stall alarms** — the line stopped and isn't resuming (the idle-detector's signal).
+
+These are v0, drawn from real rulings; treat them as the anchors that make the *when* concrete. New
+classes earn their place the same way — from a real event the human wanted to know about.
+
+**Why this is a norm, not a nicety — WORKS ≠ USED.** A channel that *works* is not a channel that is
+*used*. This path is proven only when agents **reach for it unprompted** across the lifecycle — a
+boot, a blocker, a ship, an alarm. If the channel exists and nobody reaches for it, the human is
+blind by default. Reaching out on these classes is the job, not an interruption of it.
+
 ### If you are ANY OTHER agent — blockers only
 
 You may message the human **only** when you are **blocked** and **he** is the one

package/daemon/assets/plugins/openrig-core/skills/mission-slice-sop/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: mission-slice-sop
-description: "Use when working a mission or slice: the SDLC flow (intent -> mini-requirements + proof contract -> mockups -> plan-lock -> build -> QA -> `rig proof` drops -> proof-lock), and how to track, prove, and hand off state across agents and compaction via PROGRESS.md / PROOF.md / MISSION_NOTES.md. Covers the two locks, role contracts, hot-potato queue handoff, and the `rig scope audit` backstop."
+description: "Use when working a mission or slice: the canonical files (README / IMPLEMENTATION-PRD / PROGRESS / MISSION_NOTES / MISSION_BRIEF / PROOF), who owns what and when, how planning feeds building + review + QA, how to hand off through the queue, and how to survive compaction. This is the LIGHT default. It does NOT include the intent/plan-lock/proof-lock ceremony — that is a separate assigned overlay, `mission-slice-intent-proof-sop`."
 metadata:
   openrig:
     stage: shipped
     sibling_skills:
+      - mission-slice-intent-proof-sop
       - queue-handoff
       - seat-continuity-and-handover
       - claude-compaction-restore
@@ -12,99 +13,88 @@ metadata:
 
 # Mission/Slice SOP — how you work a mission & slice
 
-Use this skill to actually **do** mission/slice work the way OpenRig expects: author the convention sections, track on the canonical files, prove on them, hand off through them, and survive compaction on them. **Do the work described here; do not merely explain the protocol.** The deterministic backstop is `rig scope audit` — an **advisory, fail-open** check (it records and advises, never blocks a write; see Proportionality below), not an authority you serve. The conventions themselves live in ONE document: **`docs/reference/sdlc-conventions.md`** in the repo, materialized by the daemon at **`$OPENRIG_HOME/reference/sdlc-conventions.md`** (default `~/.openrig/reference/sdlc-conventions.md`) on an installed package — this skill teaches the flow; the SSOT defines the formats.
+Use this skill to actually **do** mission/slice work: track on the canonical files, record what you proved, hand off through them, and survive compaction on them. **Do the work described here; do not merely explain the protocol.**
+
+## THIS IS THE LIGHT DEFAULT — read this before anything else
+
+**The default for any slice is the inner loop:** ground yourself → build → **test with your own eyes** → iterate → **ONE** full-breadth review at the end. That is the whole process. It is not a reduced form of a better process; it IS the process.
+
+**The intent / plan-lock / proof-contract / proof-lock ceremony is NOT part of this skill.** It lives in a separate overlay, **`mission-slice-intent-proof-sop`**, and you **may not select it yourself**. It applies only when the mission owner — or an orchestrator explicitly relaying the mission owner — **assigns it to a named piece of work**. If you believe something earns it, say so in one sentence and **continue on the light path** until told otherwise.
+
+Why the split exists, plainly: this document used to carry both, so every slice loaded the full apparatus and a one-line documentation change could draw a multi-round gate. If you find yourself building a proof contract, requesting a pre-edit gate, or asking a peer to gate something you can verify yourself — you have picked up the overlay without being assigned it. Put it down.
 
 ## Proportionality — this SOP serves shipping; it is not the work itself
-The working product is the deliverable. This bookkeeping exists so the work survives handoff, compaction, and review — nothing more. **Match it to stakes:** OpenRig core = full ceremony; Studio Box / SDK / app slices = pragmatic — the mini-requirements may BE the whole PRD, and a couple of honest, LOOKed proof lines beat an elaborate contract. The `rig scope audit` backstop is **advisory and fail-open** (its own SSOT says so): it never blocks a build and is not a gate you clear before proceeding. If you're spending more time on the convention files or the audit than on the running product, stop and go build. Running the full apparatus on a small change is the letter-worship failure, not diligence.
-
-## The SDLC flow (intent → proof)
-
-```
-intent → mini-requirements + proof contract → (UI slices: mockups)
-      → plan-lock (rig scope slice approve --scope spec)
-      → build the LOCKED set
-      → QA: mockup ↔ delivered VISUAL compare
-      → proof drops (rig proof add <slice> …)
-      → proof-lock (rig scope slice approve --scope delivery)
-```
-
-1. **Record intent** verbatim in the slice's `## Intent` section (`rig scope slice create` scaffolds it — every template kind).
-2. **Author the mini-requirements + proof contract**: `## Mini-requirements` is the concise one-glance tier (approval starts there); `## Proof contract` is a checkbox list of promised deliverables, each written as an observable outcome. UI deliverables name their planned mockup. The IMPLEMENTATION-PRD opens with the mini-requirements; everything between intent and proof is **elastic** — for a small slice the mini-requirements may BE the whole PRD.
-   - **PARSER CONTRACT (README AND IMPLEMENTATION-PRD, from first draft — a parser contract, not stylistic):** each doc carries a verbatim, **undecorated** `## Mini-requirements` heading with a **numbered list**, and a verbatim, **undecorated** `## Proof contract` heading whose checkbox (`- [ ]`) lines are **character-identical** across the two files. `rig scope audit` parses the PRD's `## Proof contract`; a prose rollup (e.g. `## Required proof …`) or any renamed/decorated heading trips **`proof_contract_missing_or_malformed`** and forces a post-lock format patch. Never rename or decorate these two headings, and keep the PRD's checkbox lines byte-for-byte equal to the README's.
-   - **REFERENCE-NOT-RESTATE (public / runnable examples — an honesty rail, from first draft):** any example that shows output or a value the referenced file/command **derives** — repo/runtime counts, current-state totals, hashes, timestamps — must **reference the source/derivation, omit the volatile value, or pin an explicitly stable fixture**; never hardcode the live count/state in a public or shipped doc. "Illustrative" derived output is a lie on a timer: `OK registry (2 manifests)` goes false the instant an entry lands. Write the invariant form (`OK registry (<N> manifests)`, N = entries in `registry.json`) or name the fixture instead of the momentary number. Restated derivable state in a public doc is a defect `rig scope audit` will not catch — the author owns it.
-3. **Plan-lock**: `rig scope slice approve <slice> --scope spec` — "the PRD matches the intent; THIS artifact set is what gets built." One daemon-side write: frontmatter stamp + append-only audit row.
-   - **PRE-PLAN-LOCK SELF-CHECK (advisory, not a gate):** before requesting `--scope spec`, it's worth running `rig scope audit --mission <mission> --json` and clearing any real **format** defect (e.g. `proof_contract_missing_or_malformed`) so the parser can read your proof contract — that's a genuine machine-parsing need, cheap to fix. But the audit is fail-open: findings do NOT block the lock or the build, and you do NOT need a zero-findings score to proceed. Fix what's real, skip what isn't, keep moving.
-4. **Build the locked set** — look at the mockups, not just the spec text.
-5. **QA visual compare**: for each deliverable, load the planned mockup, produce the real artifact in a test/demo environment, visually compare, and record the verdict.
-6. **Drop proof**: `rig proof add <slice> --artifact-type qa --verdict PASS --candidate-sha <tip> --money-evidence "…" --evidences "1,3" --media "walk.webm,panel.png" --self-check "…"` — the C1 header's closed sets validate at drop time; `--evidences` joins the drop to its proof-contract items and `--media` names the curated proof/-relative media the drop stands behind (that pairing + media set is what the UI's DELIVERED section renders).
-7. **Proof-lock**: `rig scope slice approve <slice> --scope delivery` — the terminal sign-off. Approval is freeze/sign-off, **never** proven-green: proven-green requires the recorded C1 verdicts.
+
+The working product is the deliverable. This bookkeeping exists so the work survives handoff, compaction, and review — nothing more. **Match it to stakes.** The `rig scope audit` backstop is **advisory and fail-open**: it never blocks a build and is not a gate you clear before proceeding. If you're spending more time on the convention files or the audit than on the running product, stop and go build. Running the full apparatus on a small change is the letter-worship failure, not diligence.
 
 ## The three role contracts
 
-- **Planning agent:** authors intent + mini-requirements + the proof contract; produces mockups for UI deliverables and attaches them to the locked set (a UI slice with no mockup is an incomplete plan; non-UI slices have none — not a gate); locks the plan.
-- **Build agent:** builds against the LOCKED set only; looks at the mockups.
-- **QA agent (owns the compare):** visually compares planned vs delivered per deliverable, records verdict + note via proof drops, and **curates** the canonical proof set (bounded, mapped to deliverables; the fix-loop pile stays in `proof/`, one drill-in down). On mismatch: fix-and-re-review or kick back with the reason — never escalate a raw mismatch to the human.
+- **Planning agent:** records what the slice is for and what "done" looks like, in the slice's own words; produces mockups for UI deliverables so the builder has something to look at (a UI slice with no mockup is an incomplete plan; non-UI slices have none — not a gate).
+- **Build agent:** builds it, and **looks at the mockups**. Verifies by running the thing.
+- **QA agent (owns the compare):** compares planned vs delivered per deliverable, records the verdict and the note. On mismatch: fix-and-re-review, or kick back with the reason — never escalate a raw mismatch to the human.
+
+These three are a division of labour, not a chain of gates. One agent may hold all three on a small slice.
 
 ## The canonical files (the operating surface)
 
-> The canonical files below are the **operating surface of the work** — you track on them, prove on them, hand off through them, and survive compaction on them. Keep them current because that is what lets the work survive handoff, compaction, and review — but they **serve** the product, they are not the product. If you're polishing these files while the actual thing isn't shipping, you've inverted it: go build, then update them.
+> These files are the **operating surface of the work** — you track on them, record on them, hand off through them, and survive compaction on them. Keep them current because that is what lets the work survive. But they **serve** the product; they are not the product. If you're polishing files while the actual thing isn't shipping, you've inverted it: go build, then update them.
 
-- **README.md** (mission + slice) — the overview, OPENING with the convention sections (`## Intent` / `## Mini-requirements` / `## Proof contract`). The **mission README carries this SOP at its bottom.**
-- **IMPLEMENTATION-PRD.md** — the full PRD; opens with the mini-requirements; the `## Proof contract` here is what the UI's DELIVERED pairing joins proof against.
+- **README.md** (mission + slice) — the overview. The **mission README carries this SOP at its bottom.**
+- **IMPLEMENTATION-PRD.md** — the plan, at whatever depth the work actually needs. For a small slice this may be a few lines. Elastic by design.
 - **PROGRESS.md** — the live delivery state. One line per outcome; links down for detail.
-- **MISSION_NOTES.md** — the accruing handoff + tribal-knowledge doc. Blank-slate onboarding + **compaction-restore** read it. `§1` top-of-mind + per-seat `§A–§X`.
+- **MISSION_NOTES.md** — the accruing handoff + tribal-knowledge doc. Blank-slate onboarding and **compaction-restore** read it. `§1` top-of-mind + per-seat `§A–§X`.
 - **MISSION_BRIEF.md** — the steering doc (the UI "Steering" tab). The 7-section schema.
-- **PROOF.md** (+ `proof/`) — acceptance evidence. **A slice is not done until every proof-contract item has evidence.**
+- **PROOF.md** (+ `proof/`) — what you actually verified, stated honestly. A couple of honest, LOOKed-at lines beat an elaborate contract.
 
 ## Per-file rules — WHO / WHEN / HOW
 
 ### PROGRESS.md
 - **WHO:** the orchestrator owns `§1` (current state); every agent logs its own outcomes.
-- **WHEN:** after every slice-done **AND every commit**; on any material state change.
-- **HOW:** one line per outcome (checkbox), link down for detail (workstream-continuity format); keep frontmatter `stage`/`verified` honest.
+- **WHEN:** after every slice-done **and every commit**; on any material state change.
+- **HOW:** one line per outcome (checkbox), link down for detail; keep frontmatter `stage`/`verified` honest.
 
 ### PROOF.md + proof/
 - **WHO:** the impl/QA pair that worked the slice.
-- **WHEN:** a slice is **NOT "done"** until every proof-contract item has evidence.
-- **HOW:** proof maps **1:1 to the proof contract's deliverables** — put media under `proof/`, then ATTACH it with `rig proof add <slice> … --evidences <item> --media <files>` (the drop writes the C1 header the DELIVERED pairing joins on) + a line in PROOF.md stating what it proves. **Hand-placing files in `proof/` without a drop is the anti-pattern** — the deliverable stays unpaired and `unverified`. No proof → not done.
+- **WHEN:** before you call a slice done.
+- **HOW:** say what you verified and how you verified it — **by effect**: you ran it and looked at the result. Put supporting media under `proof/`. State plainly what is proven and what is **not**; an honest "this half is untested" is worth more than a checkmark. If a drop verb is in play for this slice, prefer it over hand-placing files so the artifact carries its own provenance.
 
 ### MISSION_NOTES.md
-- **WHO:** any agent updates `§1` (top-of-mind); each seat owns + appends to its own `§A–§X` section.
+- **WHO:** any agent updates `§1` (top-of-mind); each seat owns and appends to its own `§A–§X`.
 - **WHEN:** on any material change; a compacting agent **files its state here BEFORE compaction and reads it on restore.**
 - **HOW:** accruing tribal knowledge — `§1` ≤ 5–15 lines (gates, open decisions, surprises); per-seat continuation entries (latest = truth; other seats read-only). Pointer-first; don't duplicate.
 
 ### MISSION_BRIEF.md
-- **WHO:** product/design (steering owner).
-- **WHEN:** when steering changes.
-- **HOW:** the 7-section steering schema (the UI "Steering" tab reads it).
+- **WHO:** product/design (steering owner). **WHEN:** when steering changes. **HOW:** the 7-section steering schema.
 
 ### README.md
-- **WHO:** the author at creation; refreshed on rescope.
-- **WHEN:** at mission/slice creation + when scope/theme changes.
-- **HOW:** overview + honest frontmatter (`id`/`stage`/`verified`) + the convention sections up top; the mission README carries this SOP at its bottom.
+- **WHO:** the author at creation; refreshed on rescope. **WHEN:** at creation + when scope/theme changes. **HOW:** overview + honest frontmatter (`id`/`stage`/`verified`); the mission README carries this SOP at its bottom.
 
 ## The lifecycle (4 legs)
 
-**SCAFFOLD** (`rig scope` creates the files from templates — every slice kind emits the convention sections + `proof/` + the IMPLEMENTATION-PRD skeleton) → **POPULATE** (agents fill them as work happens, per the rules above) → **PROJECT** (the Living Notes UI reads them into INTENT → PLAN → DELIVERED) → **VERIFY** (`rig scope audit` checks adherence). "Loose freeform write + deterministic verify."
+**SCAFFOLD** (`rig scope` creates the files from templates) → **POPULATE** (agents fill them as work happens) → **PROJECT** (the Living Notes UI reads them into INTENT → PLAN → DELIVERED) → **VERIFY** (`rig scope audit`, advisory). "Loose freeform write + deterministic verify."
 
 ## Hot-potato (handoffs)
 
-End every turn by passing the ball — a `rig queue` handoff to the next agent (close the qitem with a `closure_reason`). The **durable ball-pass is the queue close, not a chat message.** Never go idle without a handoff.
+End every turn by passing the ball — a `rig queue handoff` to the next agent. The handoff verb is **transactional**: it closes the source as handed-off and mints the successor owned by `--to`, so the baton cannot be dropped. A handoff terminates only at the orchestrator seat, which holds the context to judge whether a park is legitimate.
+
+**A plain `rig queue create` row is informational** — a durable message. It is not a baton and does not carry this obligation. Use `handoff` when you are passing real work; use `create` when you are informing.
+
+Never go idle holding a baton.
 
 ## Verify (deterministic backstop)
 
-Run `rig scope audit` at slice-close. It flags: committed-without-touching-PROGRESS; slice-marked-done-without-PROOF; active-mission-without-MISSION_NOTES; MISSION_BRIEF off-schema; proof artifacts violating the C1 header; missing IMPLEMENTATION-PRD on a building slice; missing convention sections (`## Intent`, a well-formed `## Proof contract`, the UI-slice mockup ref). Every convention check is **advisory / fail-open** — it records and advises, never blocks a write. **Fix the flag, don't suppress it.**
+Run `rig scope audit` at slice-close. Every convention check is **advisory / fail-open** — it records and advises, never blocks a write. Fix what's real, skip what isn't, keep moving. **A clean audit score is not required to proceed.**
 
 ## Reading terminal captures — KNOWN GOTCHA: ghost-text autocomplete is NOT real
 
-When you `rig capture` a pane, **greyed / ghost autocomplete suggestions are NOT real content** — they are autocomplete *previews* (shell autosuggestion, the input-box ghost-text completion), not typed, staged, or committed input. **This is known, expected, and has been faking agents out a lot** — reading a ghost suggestion in a peer's input box as "staged text they're about to send," or as a real prompt, and then reasoning/acting on a string that was never actually there.
+When you `rig capture` a pane, **greyed / ghost autocomplete suggestions are NOT real content** — they are autocomplete *previews*, not typed, staged, or committed input. **This has been faking agents out a lot**: reading a ghost suggestion in a peer's input box as "staged text they're about to send," then reasoning on a string that was never there.
 
-**Rule:** ignore ghost/autosuggest text entirely. Only *committed/rendered* pane output is real. If a `❯` input line shows text, treat it as an autocomplete artifact unless you have independent evidence it was actually entered. Do not build decisions (or worry about "colliding with staged text") on ghost text. When it matters, verify at source (git, the queue, the actual event) — never off a capture's ghost line.
+**Rule:** ignore ghost/autosuggest text entirely. Only *committed/rendered* pane output is real. When it matters, verify at source (git, the queue, the actual event) — never off a capture's ghost line.
 
 ## Moment-of-truth checklist
 
-- **Starting a slice?** → intent recorded verbatim? **PRD carries a verbatim numbered `## Mini-requirements` + a verbatim `## Proof contract` whose `- [ ]` lines are character-identical to the README's** (parser contract)? **no example restates derivable state** — counts/hashes/timestamps referenced, omitted, or pinned to a stable fixture, never hardcoded (reference-not-restate)? mockups attached (UI slices)? ran `rig scope audit` and fixed any real **format** defect so the parser reads the proof contract (advisory — a clean score is NOT required to lock)?
-- **Finishing a slice?** → every proof-contract item has curated evidence via `rig proof add … --evidences --media` (C1 drops — never only hand-placed files)? PROGRESS updated? MISSION_NOTES `§1` refreshed? proof locked (`--scope delivery`)? Handed off via queue?
+- **Starting a slice?** → do you know what it's for and what done looks like? mockups attached (UI slices)? **Are you on the light path?** (You are, unless the mission owner assigned the overlay.)
+- **Finishing a slice?** → does PROOF.md say what you actually verified, by effect, including what is NOT covered? PROGRESS updated? MISSION_NOTES `§1` refreshed? handed off via `rig queue handoff`?
 - **Committing?** → PROGRESS updated?
 - **Compacting?** → filed your state in MISSION_NOTES?
-- **Starting on a mission?** → read the mission README (incl. this SOP) + MISSION_NOTES + the conventions SSOT (`docs/reference/sdlc-conventions.md` in the repo, `$OPENRIG_HOME/reference/sdlc-conventions.md` on an installed package)?
+- **Starting on a mission?** → read the mission README (incl. this SOP) + MISSION_NOTES + the conventions SSOT.

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

@@ -1,6 +1,7 @@
 ---
 name: openrig-skills
-description: "Use when you're operating OpenRig and don't know which skill or context applies — this is the index of what ships with OpenRig, when to reach for each, and how to load it. Start here from a cold boot when nothing else is projected."
+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
@@ -16,6 +17,27 @@ Skills are **progressive disclosure**: a skill's *name + description* sit in you
 
 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 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
 
 ### Always loaded — the universal spine (open its body when its moment hits)

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

@@ -1,6 +1,9 @@
 ---
 name: openrig-user
-description: Use when operating OpenRig with the `rig` CLI and you need the shipped command surface for identity, inventory, communication, lifecycle, specs, recovery, or agent-facing JSON output.
+description: >-
+  Use when a specific `rig` command, subcommand, or flag is already known and you need its exact
+  syntax, JSON shape, defaults, or error meaning. NOT for natural capability discovery, open-ended
+  how-do-I questions, or choosing which OpenRig move applies.
 ---
 
 # OpenRig User
@@ -919,7 +922,9 @@ Manage and compose context (any text/markdown) into reusable **packs**. Every pi
 ```bash
 rig context list                     # what's in the library
 rig context show <ref>               # read a piece or pack
-rig context add <ref> --from <file>  # put a piece in the store
+rig context add <source-dir>         # install an existing pack directory into the store
+rig context preview <ref>            # assemble + show a pack WITHOUT delivering it
+rig context sync                     # re-walk discovery roots, refresh the library index
 rig context rm <ref>
 rig context compose --out packs/<ref> --from <fileA> <fileB> ...   # ordered pieces -> a durable pack
 ```

package/daemon/assets/plugins/openrig-core/skills/orienting-to-an-inherited-seat/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog — orienting-to-an-inherited-seat
+
+**`SKILL.md` carries the practice; this file carries how it got there.** Rationale, superseded
+wording, and the incidents that produced a rule live here so the instruction surface stays
+instructional.
+
+---
+
+## 2026-08-13 — "the channel does not expire" (Rule 3)
+
+### The incident
+
+A successor (orch-advisor tenure 4, v-openrig-build) concluded mid-conversation that its reach-back
+window had closed at cutover, and reasoned from that for several turns before being challenged.
+
+It was wrong. `rig ask --wake` ships in CLI 0.5.1, the predecessor's session record was intact and
+resumable, and the seat's own lineage carried a wake rule explicitly marked active from the
+retirement row onward. **One `rig ask --help` would have settled it.**
+
+### What produced the error
+
+Two artifacts asserted a bound that does not exist, and the successor inherited one side of a
+contradiction without checking:
+
+- the handover packet: *"I am a transcript after retirement, not a conversation. Ask while the
+  window is open."*
+- the operating-model README: *"Until this seat is retired, ask it directly... After that it is a
+  transcript: greppable, not conversational."*
+
+Both were written by an author who knew better — the same tenure authored the correct wake rule in
+the lineage. The charitable reading of "greppable, not conversational" is a **posture** claim (treat
+a woken tenure as testimony), which is right. It is phrased as a **capability** claim, and it was
+read as one.
+
+### Why the fix is worded positively
+
+The generalisable form: **prose that talks a capable reader out of a capability it has.** This is
+worse than a missing trigger. `PREMISE-capable-and-underinformed.md` already records that
+affordances without triggers go unused (*"you may consult your predecessor"* → zero consultations
+across a lineage). This is one turn worse — a **counter-trigger**. The successor did not fail to
+reach for the channel; it concluded the channel was absent.
+
+So Rule 3 now states the true bound positively rather than warning about the bad wording. Rule 2
+(*the packet is testimony, checked not believed*) already covers refusing a stale packet claim, and
+naming the specific bad sentence in `SKILL.md` would install the doubt it is trying to prevent.
+
+### Also added
+
+- **The real bound**, which had never been written down anywhere: the predecessor's own context
+  wall, hit *while answering* — yielding a truncated answer, an unclear error, or nothing. That is
+  one exhausted tenure, not a closed channel.
+- **Ask repeatedly, across the first working day.** Observed in the same handover: the successor's
+  only high-value question arrived after hours of work with the artifacts, when a reconciliation
+  failed. Questions formed at orientation are shallow.
+- **The live-resume tier**, which existed and was undocumented: resume a tenure into a named tmux
+  pane and message it with `rig send` for multi-turn work.
+- **`rig ask --wake` reliability caveat.** The verb is a thin wrapper over the harness resume and is
+  not yet well-exercised (mission owner, 2026-08-13). A failing wrapper must not be read as a closed
+  channel — fall back to `claude -p --resume`.
+
+### Standing
+
+Not yet re-tested. The next handover is the test: if a successor uses the channel more than once and
+without prompting, the fix worked. **Zero unprompted consultations remains the baseline to beat.**