@openrig/cli 0.5.4 → 0.5.6

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

@@ -1,134 +1,98 @@
 ---
 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).
+description: "Use when a human decision, access grant, external action, or escalation must survive the operator's absence, or when an orchestrator or PM has a judgment-worthy update for the operator."
 metadata:
+  cli_surfaces_referenced:
+    - gateway human add
+    - gateway human list
+    - queue block
+    - queue handoff
+    - queue transitions
+    - send
   openrig:
-    stage: provisional   # operator-directed, freshly authored 2026-07-30; hardens as agents use it
-    audience: ALL agents (universal); orchestrators + PMs are the primary discretionary senders
+    stage: provisional
+    audience: all agents
     sibling_skills:
       - queue-handoff
-      - status-not-chat-orchestrator
       - human-in-the-loop
       - openrig-user
 ---
 
 # Messaging the Human
 
-## The one-line mechanism
+The human is an addressable participant, but their attention is scarce and they
+may not be at a terminal. Anything that must survive their absence needs a
+durable queue row; the gateway turns the human blocker on that row into the
+external notification.
+
+Any seat may contact the human directly for a real escalation. Orchestrators
+and product managers may also send updates they judge the human would want to
+know. Do not add a routing intermediary merely because of your role.
+
+## The supported route
+
+First discover the registered human identity. Never invent or remember an
+address:
+
+```bash
+rig gateway human list --json
+```
+
+Use `humans[].entityId` to derive the durable blocker as `<entityId>@host`.
+The entity id must use the human-seat prefix (`human` or `human-...`); if it
+does not, stop and repair the registration rather than guessing. The returned
+`humans[].address` is the gateway delivery address, not the `--on` value. If no
+unambiguous registered human is returned, stop: registration is lifecycle work
+(`rig gateway human add --help`), not an address to guess.
+
+Keep the work row owned by the agent who must resume it, then park that row on
+the registered human:
+
+```bash
+rig queue block <qitem-id> --on <entityId>@host \
+  --summary "<decision owed>" \
+  --evidence-ref "<durable artifact the human should judge>" \
+  --continuation "<what resumes after the answer>"
+```
+
+The gateway resolves the registered human to the configured connector, sends
+the Slack notification, and records its receipt on the same row. Confirm the
+effect from the append-only history:
 
 ```bash
-rig send operator-human@your-rig "your message"
+rig queue transitions <qitem-id>
 ```
 
-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
-
-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.
-
-### 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
-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) |
+The row is the obligation and the audit trail. Slack is the attention leg. A
+reply resolves the durable blocker and wakes the row owner; it does not create
+a second private work stream.
+
+## When to use it
+
+Escalate directly when only the human can supply the missing capability:
+
+- a decision or irreversible judgment only they own;
+- access, credentials, authority, or capacity only they can grant;
+- an external action only they can perform;
+- a security-class or provider/model-fallback event they need to know about.
+
+Orchestrators and product managers may additionally send meaningful milestone,
+environment, or completion updates. Prefer signal over routine narration.
+
+## Boundaries
+
+- `rig send` sends text to an agent's terminal. It is not the Slack route and
+  does not create a durable human obligation.
+- An unregistered or ambiguous human identity must fail loudly. Register or
+  repair the identity; never downgrade it to an agent seat or a guessed
+  `@external` address.
+- Agent-to-agent work that needs closure uses `rig queue handoff`, not this
+  human-blocker path.
+- Deferred work that is not imminent belongs in the mission workspace, not on
+  the queue.
+
+## Writing the escalation
+
+Lead with what is blocked and the exact decision or action needed. Point at the
+durable evidence instead of pasting a second copy, and name the continuation so
+the system can resume the right work when the answer arrives.

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

@@ -1,27 +1,27 @@
 ---
 name: mission-slice-sop
-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`."
+description: >-
+  Use when starting, building, handing off, restoring, or closing a mission or slice under the default lightweight SDLC.
 metadata:
   openrig:
     stage: shipped
     sibling_skills:
-      - mission-slice-intent-proof-sop
       - queue-handoff
       - seat-continuity-and-handover
       - claude-compaction-restore
 ---
 
-# Mission/Slice SOP — how you work a mission & slice
+# Mission/Slice SOP — Part A
 
 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.**
 
+**Full convention SSOT:** repo `docs/reference/sdlc-conventions.md`; installed `$OPENRIG_HOME/reference/sdlc-conventions.md`. This skill is the concise Part-A teaching surface and does not replace the full convention.
+
 ## 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.
+**Part B is defined in the SSOT above and applies only when the human operator — or an orchestrator explicitly relaying that decision — assigns it to a named piece of work.** You may not select it yourself. If you believe something earns it, say so in one sentence and **continue on Part A** until told otherwise.
 
 ## Proportionality — this SOP serves shipping; it is not the work itself
 
@@ -35,22 +35,23 @@ The working product is the deliverable. This bookkeeping exists so the work surv
 
 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 current file contract
 
 > 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. 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 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/`) — what you actually verified, stated honestly. A couple of honest, LOOKed-at lines beat an elaborate contract.
+- **Slice:** `SPEC.md`, `PROGRESS.md`, `PROOF.md`, and `proof/`.
+- **Mission:** `SPEC.md` and `NOTES.md`.
 
 ## Per-file rules — WHO / WHEN / HOW
 
+### SPEC.md
+- **WHO:** the planning owner authors it; builders and reviewers read it as the scope and intent source.
+- **WHEN:** at creation and whenever scope changes.
+- **HOW:** a slice carries `intent:` in frontmatter and opens with `## Intent`, `## Mini-requirements`, and `## Proof contract`. A mission carries its intent and mission-level specification in the same authored node file. Keep depth proportional to the work.
+
 ### 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.
+- **WHEN:** on material delivery-state changes and at acceptance.
 - **HOW:** one line per outcome (checkbox), link down for detail; keep frontmatter `stage`/`verified` honest.
 
 ### PROOF.md + proof/
@@ -58,17 +59,11 @@ These three are a division of labour, not a chain of gates. One agent may hold a
 - **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
+### NOTES.md
 - **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.**
+- **WHEN:** on material mission-context changes; 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.
-
-### README.md
-- **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) → **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."
@@ -94,7 +89,6 @@ When you `rig capture` a pane, **greyed / ghost autocomplete suggestions are NOT
 ## Moment-of-truth checklist
 
 - **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.
+- **Finishing a slice?** → does `PROOF.md` say what you actually verified, by effect, including what is NOT covered? `PROGRESS.md` updated? mission `NOTES.md` refreshed? handed off via `rig queue handoff`?
+- **Compacting?** → file your state in mission `NOTES.md`; on restore, read it plus the active slice's `SPEC.md`, `PROGRESS.md`, and `PROOF.md`.
+- **Starting on a mission?** → read mission `SPEC.md`, `NOTES.md`, and the conventions SSOT.