@openrig/cli 0.4.4 → 0.4.7

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/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/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.
 
 ---
 
@@ -250,19 +256,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 +297,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. |
 
 ---
 

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

@@ -0,0 +1,108 @@
+---
+name: messaging-the-human
+description: |
+  When and who should send a message to the human operator, at
+  operator-human@your-rig — which routes straight to his Slack. Role-gated:
+  orchestrators and PMs use discretion to send anything worth his attention
+  (blockers, ships/completions, changes, good news); every other agent may
+  message him ONLY for a real blocker he can personally unblock, and routes
+  everything else through an orchestrator. Use to protect a scarce human's
+  manage-by-exception attention. NOT for agent-to-agent coordination (send/queue
+  a peer) or durable agent work-handoffs (use the queue to the owning seat).
+metadata:
+  openrig:
+    stage: provisional   # operator-directed, freshly authored 2026-07-30; hardens as agents use it
+    audience: ALL agents (universal); orchestrators + PMs are the primary discretionary senders
+    sibling_skills:
+      - queue-handoff
+      - status-not-chat-orchestrator
+      - human-in-the-loop
+      - openrig-user
+---
+
+# Messaging the Human
+
+## The one-line mechanism
+
+```bash
+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.
+
+## The mental model: the human is a scarce attention resource managing by exception
+
+There is one human. He is single-threaded across many agents, so his attention
+is the bottleneck of the whole system. He operates **by exception**: he wants to
+be pulled in when it genuinely matters and left alone when it doesn't. Every
+message you send spends a slice of that scarce attention.
+
+So the rule is not "can I reach him" (you can, trivially — one `rig send`). The
+rule is **should this reach him, coming from me**. Two things decide that: **who
+you are** (your role sets how much of his attention you're trusted to spend) and
+**what it is** (does it clear the bar for that role). Get the altitude wrong in
+either direction and you fail him: spam his Slack with noise, or sit silently on
+something he needed to know or could have unblocked.
+
+## WHO sends WHAT
+
+### If you are an ORCHESTRATOR or a PRODUCT MANAGER — use discretion
+
+You are the primary channel to the human. You may send **more than blockers** —
+anything you judge he would want to know:
+
+- something **shipped**, **completed**, or a **milestone** was hit
+- something **important happened**, or something **changed**
+- **environmental** changes (infra, hosts, tools, external state)
+- **good news**
+- anything that needs his attention, or is simply **good for him to know**
+
+There is no hard trigger here — it is judgment, and you are trusted with it. The
+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.
+
+### If you are ANY OTHER agent — blockers only
+
+You may message the human **only** when you are **blocked** and **he** is the one
+who can unblock you. That authority is universal — you do **not** have to be an
+orchestrator to raise a real blocker. But a blocker is the **only** thing you may
+send him directly.
+
+For anything that is **not** a blocker — an update, an idea, a question, an
+interesting finding — do **not** message the human. Send it to your
+**orchestrator**, who decides whether it is the human's role to handle or whether
+it is handled another way. The orchestrator/PM layer is the filter that protects
+the human's attention; routing through it is how the system keeps his queue at
+manage-by-exception altitude.
+
+## What counts as a real blocker (for non-orchestrator / non-PM agents)
+
+You are **blocked** AND **only the human** can clear it:
+
+- a **decision** only he can make,
+- **access / a credential / an authority** only he holds,
+- an **external action** only he can take (something in the real world, an
+  account or service he owns).
+
+Not a blocker: "I'd like a second opinion," "which approach do you prefer,"
+"here's a cool thing I found." Those go to your **orchestrator**. And if an
+orchestrator or PM *could* unblock you, route to them first — reserve the human
+for what genuinely only he can do.
+
+## How to write it (so it earns the interruption)
+
+- **Lead with the point.** Blocker: what is blocked + exactly what you need from
+  him. Update: the headline first, detail after.
+- **Full absolute paths.** No internal jargon he can't parse. **No backticks** in
+  `rig send` bodies (they trigger shell substitution).
+- `rig send` is an **ephemeral conversation** to his Slack. For a durable *agent*
+  work-handoff, use the queue to the owning seat — not the human.
+
+## Quick reference
+
+| You are… | You may send the human… |
+|---|---|
+| Orchestrator / PM | anything worth his attention — blockers, ships, completions, changes, good news (your discretion) |
+| Any other agent | a real blocker only he can unblock — **and nothing else** (everything else → your orchestrator) |

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

@@ -1,20 +1,9 @@
 ---
 name: mission-slice-sop
-description: Use when working a mission or slice — the full SDLC flow (intent → mini-requirements + proof contract → mockups → plan-lock → build → QA visual compare → `rig proof` drops → proof-lock) plus how to track, prove, hand off, and carry state across agents and compaction via the canonical files (PROGRESS.md / PROOF.md / MISSION_NOTES.md / MISSION_BRIEF.md / README.md / IMPLEMENTATION-PRD.md). Covers the convention sections the Living Notes UI projects, the two locks, the three role contracts, per-file WHO/WHEN/HOW rules, the four-legs lifecycle, hot-potato queue handoffs, the moment-of-truth checklist, the deterministic `rig scope audit` backstop, and the ghost-text capture gotcha.
+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."
 metadata:
   openrig:
     stage: shipped
-    last_verified: "2026-07-06"
-    distribution_scope: product-bound
-    source_evidence: |
-      Authored + embedded in release-0.4.3 slice 32 (mission-slice-sop);
-      moved into the canonical product skill source and updated in
-      release-0.4.4 slice 23 (operationalize the SDLC control plane) to
-      teach the full SDLC flow the Living Notes UI projects: the convention
-      sections, the proof-contract pairing, the two staged-approval locks,
-      C1 proof drops, and the three role contracts. Conventions SSOT:
-      docs/reference/sdlc-conventions.md (shipped with the CLI package).
-      The deterministic backstop is the `rig scope audit` classifier.
     sibling_skills:
       - queue-handoff
       - seat-continuity-and-handover
@@ -23,7 +12,10 @@ 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` — the audit classifier is the source of truth for adherence. The conventions themselves live in ONE place: **`docs/reference/sdlc-conventions.md`** (shipped with the CLI package) — this skill teaches the flow; the SSOT defines the formats.
+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.
+
+## 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)
 
@@ -38,7 +30,10 @@ intent → mini-requirements + proof contract → (UI slices: mockups)
 
 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).
@@ -52,7 +47,7 @@ intent → mini-requirements + proof contract → (UI slices: mockups)
 
 ## 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. They are NOT side-artifacts to "maintain"; keeping them current *is* the work.
+> 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.
 
 - **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.
@@ -108,8 +103,8 @@ When you `rig capture` a pane, **greyed / ghost autocomplete suggestions are NOT
 
 ## Moment-of-truth checklist
 
-- **Starting a slice?** → intent recorded verbatim? mini-requirements + proof contract authored? mockups attached (UI slices)? plan locked (`--scope spec`)?
+- **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?
 - **Committing?** → PROGRESS updated?
 - **Compacting?** → filed your state in MISSION_NOTES?
-- **Starting on a mission?** → read the mission README (incl. this SOP) + MISSION_NOTES + `docs/reference/sdlc-conventions.md`?
+- **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)?