@openrig/cli 0.5.8 → 0.5.10

package/daemon/assets/claude-statusline-context.cjs

@@ -42,6 +42,7 @@ process.stdin.on("end", () => {
       },
       session_id: raw.session_id ?? null,
       session_name: raw.session_name ?? null,
+      occupant_generation: process.env.OPENRIG_OCCUPANT_GENERATION || process.env.RIGGED_OCCUPANT_GENERATION || null,
       transcript_path: raw.transcript_path ?? null,
       sampled_at: new Date().toISOString(),
     };

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 (17):** canonical OpenRig operating knowledge, including the public `refocusing` skill and
+**Skills (19):** canonical OpenRig operating knowledge, including the public `refocusing` skill and
 its path-only topology/work trace.
 
 **Hooks:** activity tracking, compaction continuity, and the default-on refocus channel. Refocus is

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

@@ -0,0 +1,92 @@
+---
+name: agent-operated-software
+description: >-
+  Use when designing, building, operating, or diagnosing an ongoing application whose live backend
+  or control loop includes OpenRig agents, including applications with a Markdown, YAML, or JSON
+  agent control plane or a thin surface over specialist agent roles.
+metadata:
+  openrig:
+    stage: provisional
+    audience: any agent building or operating an agent-backed application
+    sibling_skills:
+      - agent-operated-workflows
+      - forming-an-openrig-mental-model
+      - mission-slice-sop
+      - openrig-user
+---
+
+# Agent-Operated Software
+
+**Agent-Operated Software** is an ongoing application whose functioning runtime includes an OpenRig
+agent or rig in its live backend or control loop. The application surface can be thin: structured
+state and specialist roles do the work, while the UI makes that work legible and steerable.
+
+## Start with the shared taxonomy
+
+- **AI-enabled software:** application code owns the control loop and calls a model as one capability.
+- **Agent-Operated Workflow:** an agent owns one bounded procedure with a start and stop condition;
+  see `agent-operated-workflows`.
+- **Agent-Operated Software:** agents participate in an ongoing application's functioning runtime.
+
+An application may compose many Agent-Operated Workflows. A bounded workflow does not by itself make
+its surrounding product Agent-Operated Software, and a model call is neither category unless an agent
+owns part of the control loop.
+
+## Agents are part of the backend
+
+In this architecture, behavior is not located only in functions. It is distributed across agents,
+skills, instructions, bootstrap files, schemas, Markdown, YAML, JSON, folders, and deterministic
+tools. A surprising result may therefore be a code defect or a coherence gap in this control plane.
+Trace the path that actually produced the behavior before choosing which layer to repair.
+
+This is not permission to tolerate defects in OpenRig core or another rock-solid substrate. There,
+reproduce the bug, fix the code, and hold the full gate. The faster coherence-first posture belongs
+to recoverable agent-operated application layers whose state and behavior can be inspected and
+repaired cheaply.
+
+## Markdown is the control plane
+
+Markdown is maximally useful to an agent while remaining legible enough for a human to steer. Put
+intent, work state, evidence, and decisions into stable addressed artifacts rather than private chat
+or an opaque custom database. Keep schemas and conventions aligned with the running behavior: the
+agent population acts on those files as executable context.
+
+Use **progressive disclosure**. A skill's name and description are the hot trigger; its body is cold
+procedure. Descriptions say when to load, not how to work. The body should route the reader to exact
+sources instead of copying them into another doctrine fork.
+
+Scripts can act as prompts. A good script returns the context or exact effect an agent needs; when it
+cannot, its failure teaches what it observed, why it stopped, and safe next actions. Keep deterministic
+mechanics in tools and judgment in agents.
+
+## Make artifacts self-certifying
+
+When a tool produces an artifact, do not make every consumer invent a completeness test:
+
+1. Write to a partial path, never the final path.
+2. Verify the property that can actually be wrong, such as duration, streams, resolution, or schema.
+3. Flush and atomically rename the partial artifact to its final path.
+4. Write the manifest, then a `.done` sentinel last.
+
+Consumers fail closed on the shared proof. A filename or exit code is not content verification.
+
+## Build with an agent SDLC
+
+Map work onto **intent -> plan -> spec -> build -> verify -> review -> QA -> done**. The human supplies
+steering, judgment, taste, and the call on irreversible ambiguity; agents perform and coordinate the
+technical work. Locks freeze the agreed spec and accepted delivery so multiple seats can work without
+guessing whether the target moved.
+
+For studio applications, the running product is usually the best iteration surface. A separate mockup
+earns its cost only when it resolves a real design uncertainty that the running app cannot expose as
+cheaply. This removes a redundant artifact, not the visual review or proof contract.
+
+## Repair the narrowest authoritative layer
+
+Find the generator or source that every affected agent actually consumes. Fix a code defect in code;
+fix a missing trigger in the skill; fix a malformed contract in its schema. Then verify through the
+consumer. Editing a rendered or installed copy creates a temporary fork, not a repair.
+
+The payoff compounds: a correction to the shared application control plane changes the next agent's
+starting point. That is how an ongoing agent-operated system improves without making one human its
+permanent router.

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

@@ -0,0 +1,79 @@
+---
+name: agent-operated-workflows
+description: >-
+  Use when a bounded real-world procedure has a deterministic happy path but brownfield, variable,
+  or partially knowable state; when an operation must resume from verified evidence; or when deciding
+  whether agent judgment or ordinary code should own a procedure's control loop.
+metadata:
+  openrig:
+    stage: provisional
+    audience: any agent operating or designing a bounded procedure
+    sibling_skills:
+      - agent-operated-software
+      - openrig-user
+      - systematic-debugging
+---
+
+# Agent-Operated Workflows
+
+An **Agent-Operated Workflow** is a bounded procedure whose control loop belongs to an agent. The
+agent observes, interprets, sequences bounded actions, verifies their effects, adapts, and escalates
+genuine ambiguity. Deterministic code remains the exact substrate; it does not pretend to understand
+every state of a brownfield world.
+
+## Name the architecture before using it
+
+- **AI-enabled software:** application code owns the control loop and calls a model as one capability.
+- **Agent-Operated Workflow:** an agent owns one bounded procedure with a start and stop condition.
+- **Agent-Operated Software:** an OpenRig agent or rig participates in an ongoing application's live
+  backend or control loop. It may run many workflows; see `agent-operated-software`.
+
+Calling a model is not enough. A deterministic program that consults a model still owns its loop.
+
+## Decide whether the agent earns the loop
+
+Use an agent when the happy path is deterministic but the environment is brownfield, variable,
+partially knowable, or disproportionately expensive to model exhaustively. The judgment is in
+discovering what is true and choosing the next safe act.
+
+Prefer ordinary code when the state space is closed and code is simpler and more reliable than
+judgment. A parser, fixed data transformation, or fully enumerated state machine does not become
+better because an agent drives it.
+
+## Keep ownership explicit
+
+| Owner | Responsibility |
+|---|---|
+| Runbook | owns policy, the mental model, checkpoints, stop conditions, and escalation rules |
+| Deterministic tools | own context gathering and bounded exact actions |
+| Agent | owns interpretation, sequencing, adaptation, and effect verification |
+| Human | owns destructive ambiguity and product policy |
+
+The runbook guides judgment; tools enforce the invariants that must not be arguable.
+
+## Operate
+
+1. Establish identity, durable state, the runbook, and the promised outcome.
+2. Inspect with side-effect-free reads or an explicit plan mode.
+3. Choose one bounded action from observed state; do not mechanically replay the happy path.
+4. Verify the effect at the consumer or state surface that could prove it wrong.
+5. Record an observable checkpoint before moving on, so another agent can resume.
+6. Continue, stop at the declared condition, or escalate with evidence and the decision needed.
+
+An interrupted or timed-out mutation is **indeterminate**, never failed by assumption and never safe
+to retry blind. Where a compatibility period is safer, separate reversible preparation from the
+destructive finalizer. Idempotence is a claim to prove per action, not a label for the whole run.
+
+## Build
+
+Expose composable verbs, not an optimistic end-to-end controller. Help is inert. Read and plan modes
+are explicit. Mutations are narrow and independently readable. A failure should say what was
+observed, why the tool stopped, what remains unchanged, the safe next choices, and where its evidence
+lives. Keep checkpoints durable, effects observable, and recovery possible without private developer
+knowledge.
+
+A capability composition is a reusable recipe; this is the execution architecture that operates
+capabilities toward an outcome. Promote a proven workflow to the composition shelf only after use.
+
+**Reference implementation:** Release 0.5.9 Slice 05 is the first **Agent-Operated Migration**. Its
+runbook and helpers remain there; this skill carries the reusable contract, not a duplicate procedure.

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

@@ -24,8 +24,8 @@ metadata:
       - openrig-builder
       - openrig-architect
       - openrig-upgrade
-      - ai-dev-workflows
-      - software-for-agents
+      - agent-operated-workflows
+      - agent-operated-software
 ---
 
 # Forming an OpenRig Mental Model

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

@@ -1,98 +1,85 @@
 ---
 name: messaging-the-human
-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."
+description: "Use when project policy calls for a human decision or update, a human delivery is pending or failed, or a reply must resume the right work."
 metadata:
   cli_surfaces_referenced:
-    - gateway human add
     - gateway human list
-    - queue block
-    - queue handoff
+    - gateway human show
+    - queue create
     - queue transitions
+    - queue block
     - send
   openrig:
     stage: provisional
     audience: all agents
     sibling_skills:
       - queue-handoff
-      - human-in-the-loop
       - openrig-user
 ---
 
 # Messaging the Human
 
-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.
+Project World supplies **when and why** to contact a human. This skill supplies
+transport-neutral mechanics; installing it does not create an approval gate or
+choose a connector. If policy leaves a material decision ambiguous, identify the
+missing authority. Do not convert a solvable technical failure into a human gate.
 
-## The supported route
+## Discover, check, send, inspect
 
-First discover the registered human identity. Never invent or remember an
-address:
+Discover the registered participants and inspect the chosen human:
 
 ```bash
 rig gateway human list --json
+rig gateway human show <entityId> --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.
+Use the returned `address` (`<entityId>@external`), not a username, remembered
+seat, connector handle, or guessed kernel address. Where several humans exist,
+use the decision ownership in Project World. An absent or ambiguous registration
+needs a named registration correction, not a fallback address.
 
-Keep the work row owned by the agent who must resume it, then park that row on
-the registered human:
+Check readiness: configured, enabled, active, ready, reason, and next action.
+`indeterminate` is not ready. Follow the reported next inspection; do not enable
+or reconfigure a connector merely to make the check pass.
+
+Write the decision, evidence, and continuation in a body file. The sole outbound
+human-message primitive is:
 
 ```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>"
+rig queue create --destination <entityId>@external \
+  --summary "<decision or update>" --body-file <packet-file> \
+  --evidence-ref <durable-evidence> --verify --json
 ```
 
-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:
+If an existing agent-owned row must wait, block it on the **new live qitem ID**
+(`rig queue block <work-id> --on <human-qitem-id> ...`), not on the human address.
+Completion of the human qitem resumes its dependants. Blocking on the human as
+well would issue another notification for the same decision.
+
+The row persists before bounded delivery verification. Read its qitem ID and
+verification result; `posted` proves connector posting, **not human readership**.
+`transport-failed`, `never-posted`, or a pending/indeterminate result leaves the
+row intact. Inspect that same row and its next action; never create a second row
+or blindly resend because verification timed out.
 
 ```bash
 rig queue transitions <qitem-id>
 ```
 
-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
+A correlated reply binds to that exact human and qitem and records the resolution
+that resumes the owner. Check the recorded result before claiming the decision
+arrived; a delivery receipt alone is not acceptance.
 
-- `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.
+## Existing blockers and other channels
 
-## Writing the escalation
+An existing agent-owned row may be blocked on `<entityId>@host`. That is an
+internal custody label resolved through the human registry to the same external
+participant; it is not a second delivery address. Keep the owner and continuation
+on that row. Inspect its existing delivery receipt before considering another
+request, so a legacy blocker does not produce a duplicate message. Never derive
+`@host` from the current rig name.
 
-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.
+`rig send` reaches an agent's terminal only. It is not a human transport or a
+durable human obligation. Agent-to-agent work uses the queue handoff path.
+Connector-specific configuration and handles belong to registry/readiness tools,
+not to project-independent message instructions.

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

@@ -17,11 +17,25 @@ Use this skill to actually **do** mission/slice work: track on the canonical fil
 
 **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.
-
-**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.
+## Resolve the work first
+
+Run `rig whoami --json`, then resolve `project.yaml -> mission.yaml -> active
+slice.yaml -> selected component or wave map -> addressed context`. The complete
+lookup and precedence rule is `docs/reference/product-journey-sdlc.md#resolve-the-selected-path`
+(installed: `$OPENRIG_HOME/reference/product-journey-sdlc.md#resolve-the-selected-path`).
+Read the selected addresses and source needed for this task; skills available in
+your profile are capabilities, not a mandatory reading list. No composition means
+light Part A. Role names and idle seats add no gates. Explicit rigor and authored
+wave boundaries retain their named checks.
+
+The light inner loop is ground yourself → build → test with your own eyes →
+iterate → record and return the whole outcome. The builder may hold this check
+on a tiny change. Independent review runs only when selected, and once at an
+authored wave boundary rather than once per slice.
+
+Part B is defined in the conventions SSOT and runs only when explicitly assigned
+to named work. If you believe it is needed, state the reason to the owner and
+continue on the selected path until that choice changes.
 
 ## Proportionality — this SOP serves shipping; it is not the work itself
 

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

@@ -13,7 +13,7 @@ You're running inside OpenRig. OpenRig ships a set of **skills** — small docum
 
 ## How OpenRig context works (30 seconds)
 
-Skills are **progressive disclosure**: a skill's *name + description* sit in your context ambiently (the "hot tier"); its *body* loads only when you open it. So you don't pre-read everything — you pattern-match a skill's "when" to your moment, then open just that one. This file is the index over the whole shipped set. (For the full model of building/operating agent software, open `software-for-agents`.)
+Skills are **progressive disclosure**: a skill's *name + description* sit in your context ambiently (the "hot tier"); its *body* loads only when you open it. So you don't pre-read everything — you pattern-match a skill's "when" to your moment, then open just that one. This file is the index over the whole shipped set. (For bounded procedures, open `agent-operated-workflows`; for ongoing agent-backed applications, open `agent-operated-software`.)
 
 Every row below names **how to reach the skill** — already-hot, or an exact load path. No row is a dead end.
 
@@ -63,7 +63,9 @@ These are auto-delivered to every rig; their name+description are already in you
 - **retiring-and-inheriting-a-seat** — you're planning a seat transition and need to retire the current occupant into a fresh successor without losing continuity.
 - **mission-slice-sop** — you're working a mission/slice (the SDLC: intent → mini-requirements + proof contract → build → QA → proof). The operating manual.
 - **messaging-the-human** — composing a message to the human. Plain language, no insider jargon.
-- **software-for-agents** — you want the full first-load model of how agent software is built and operated here.
+- **agent-operated-workflows** — a bounded real-world procedure needs an agent to interpret state and operate exact tools, or you are deciding whether ordinary code should own the loop.
+- **agent-operated-software** — you are designing or operating an ongoing application whose live backend includes OpenRig agents.
+- **software-for-agents** — compatibility redirect for the former `agent-operated-software` name; remove in 0.6.0.
 - **openrig-skills** — this index (you're reading it). Always loaded; the entry point to everything below.
 
 ### Load when your role or task calls for it (repo-shipped, profile-selected)

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

@@ -175,7 +175,7 @@ section.
 
 ### Instantiate the canonical workspace scaffold
 
-Agent-actionable. Idempotent on existing dirs without `--force`.
+Agent-actionable. The operation is additive and preserves existing files.
 
 ```bash
 rig config init-workspace
@@ -187,19 +187,15 @@ rig config init-workspace --dry-run --json
 configured `workspace.root` (default `~/.openrig/workspace`):
 
 - `missions/` — release missions + slices
-- `artifacts/` — work artifacts produced inside the workspace
-- `evidence/` — non-dogfood evidence (release evidence, proof packets, etc.)
-- `progress/` — progress index + per-mission rails
-- `field-notes/` — operator + agent observations
-- `specs/` — spec library (rig + agent + workflow YAML lives here)
-- `dogfood-evidence/` — dogfood proof packets + run artifacts
-
-The scaffold seeds one example mission (`getting-started`) with multiple
-slices, and drops a workspace README.md + STEERING.md so a fresh install has
-browsable Project content. `--root <path>` targets a non-default root for
-this call; `--dry-run` reports what would be created without writing.
-`--force` overwrites existing FILES but never deletes
-directories — operator content is safe.
+- `exhaust/` — project-local coordination exhaust
+- `SPEC.md` — project intent
+- `project.yaml` — project catalog selections and mission root
+- `workspace.yaml` — project registration
+- `.gitignore` — local OpenRig state and exhaust exclusions
+
+`--root <path>` targets a non-default root for this call; `--dry-run` reports
+what would be created without writing. `--force` is deprecated compatibility
+and still preserves existing files.
 
 ### Redirect the workspace root
 
@@ -235,8 +231,8 @@ Agent-actionable. Same surface as the canonical scaffold above; the
 rig config init-workspace --root /path/to/new/workspace
 ```
 
-The command creates the root dir if missing (idempotent: existing root +
-populated subdirs is a no-op). Run
+The command additively creates any missing canonical entries and preserves
+every existing one; only a complete six-entry scaffold is a no-op. Run
 `rig workspace validate /path/to/new/workspace --json` after to confirm the
 contract holds.
 
@@ -721,6 +717,31 @@ rig env logs <rig>
 rig env down <rig>
 ```
 
+### Bounded agent self-scout
+
+Use the typed health projection before reading raw coordination history. The
+default query is the current seat; widen deliberately when the evidence points
+beyond it:
+
+```bash
+rig health --json
+rig health --rig <rig-id> --json
+rig health --instance --json
+rig health explain <finding-id> --json
+```
+
+Follow the returned stable finding ID and `suggestedInspection`. Use `explain`
+when the summary matters: it returns the same canonical record with its bounded
+window, freshness, literal detector rule, evidence references, and next
+inspection. Human output projects those same fields; it does not calculate a
+second score.
+
+An empty result means only that no records matched the bounded query. It is
+**not a healthy assertion**. Stale, unavailable, contradictory, and
+indeterminate evidence stays explicit. Never read raw SQLite for a self-scout,
+and never turn a finding into an acknowledgement, notification, queue row, or
+remediation automatically: `rig health` is strictly read-only.
+
 ## Transcript and Communication
 
 ### Transcript access