@openrig/cli 0.5.5 → 0.5.7

package/daemon/context-packs/skills/queue-handoff/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: queue-handoff
+description: Use when ending a turn, finishing a slice, blocked on another agent's work, or escalating to a human — durable work handoff via queue items so the system keeps moving across compactions, missed messages, and interruptions. Covers the hot-potato terminal-turn-rule (active work ends by passing the ball, not by going idle), default-nudge semantics, and when `--no-nudge` is appropriate for intentional cold park or human gate.
+metadata:
+  cli_surfaces_referenced:
+    - queue
+    - queue create
+    - queue handoff
+    - queue handoff-and-complete
+  openrig:
+    stage: factory-approved
+    sibling_skills:
+      - workflow-runtime
+      - watchdog
+      - refocus
+      - looping-workflows
+      - intake-routing
+      - human-in-the-loop
+      - dispatching-parallel-agents
+      - subagent-driven-development
+      - structured-ack-dispatch
+      - control-plane-capabilities
+      - status-not-chat-orchestrator
+      - control-plane-queue
+      - control-plane-watchdog
+      - control-plane-workflows
+      - control-plane-delivery-loop
+      - control-plane-rollout-manager
+---
+
+# Queue Handoff
+
+Durable work handoff via queue items. Lets the system keep moving
+through compactions, missed messages, and interruptions by passing the
+ball forward instead of leaving work suspended in chat or in-flight
+without an owner.
+
+## Use this when
+
+- **Ending a turn on substantive work.** Active work should end by
+  passing the ball to an owner or to the human — never by going idle
+  with the rig appearing dormant.
+- **Finishing a slice that has a clear next step.** Default-nudge:
+  receiver gets a wake-ping plus the durable queue item.
+- **Blocked on another agent's work.** Park the qitem with
+  `closure_reason: blocked_on` and the blocker qitem id.
+- **Escalating to the human.** Make the escalation a durable attention
+  item, not just a chat message.
+
+## Don't use this when
+
+- The work is genuinely complete and there's no follow-on owner. Use
+  `closure_reason: no-follow-on` (terminal completion) or
+  `canceled`/`denied` as appropriate.
+- The handoff would be too small and turn work into bureaucracy. Bundle
+  the work into a coherent slice instead of decomposing every step.
+- The handoff would be too broad and lose ownership/proof/closure
+  criteria. Shape the qitem so the receiver knows the expected next
+  action and closure evidence.
+
+## The hot-potato terminal-turn-rule
+
+Active work ends by passing the ball to a named next owner or to the
+human. The qitem state machine enforces this:
+
+`pending → in-progress → done` requires `closure_reason` from one of:
+
+- `handed_off_to` — work continues at a different seat (target = new owner)
+- `blocked_on` — parked pending another qitem (target = blocker qitem id)
+- `denied` — receiver rejected the work
+- `canceled` — sender or receiver withdrew
+- `no-follow-on` — terminal completion, nothing else needed
+- `escalation` — kicked up to a higher tier (target = escalation target)
+
+Three of those (`handed_off_to`, `blocked_on`, `escalation`) additionally
+require `closure_target`. The daemon enforces this at the domain layer;
+every surface (CLI, MCP, future UI) inherits the same guarantee.
+
+**The drafted-park failure (draft ≠ throw).** The rule is about the *actual* pass, not the
+intention to pass. A turn that ends with a self-instruction **typed into your own prompt but left
+unsent** — a drafted go-ahead, a next-atom note you never sent — has **not** handed off; it has
+**parked**, and the seat sits idle for as long as nobody notices. Drafting the handoff feels like
+doing it; it isn't. **Your last act on a turn must be an EDIT or a SEND** — a committed change, a
+`rig send`, a `rig queue` handoff — **never a drafted prompt line left in the buffer.** If your
+final output is an instruction addressed to yourself, you haven't ended the turn, you've stalled it.
+
+**The dispatcher's other half — supersession closes your own outbox.** Ending your turn cleanly is
+only half the rule; the other half fires when *you* move the world. **When a phase transition or a
+fold receipt supersedes work you dispatched, close those dispatches yourself — with a citation to the
+event that superseded them.** Closure-on-supersession belongs to the **dispatcher, never the
+receiver.** Make it a habit: after every fold receipt / phase transition, run an **outbox audit** —
+*which of my open dispatches did this just make moot?* — and close them with the citation.
+
+*Why it must live with you:* stale dispatch-debt is **invisible to the dispatcher** because it lands
+on someone else's queue — the cost is externalized, so no feedback loop ever fires to make you clean
+it up. The receiver inherits debt they did not create and must burn cycles verifying it before they
+can hold cleanly; a queue full of stale-pending makes *check-before-holding* — the discipline you
+most want cheap — expensive, and it degrades the idle-detector's signal (a real owner looks the same
+as a stale dispatch). Close it at the source: the moment your own transition mooted it.
+
+**And after you hand off, PULL — don't idle with a stocked queue.** Handing the baton off ends the
+*sequential* thread; it does not end *your* turn if your own queue still holds work. The circulation
+pattern: finish → (1) hand the baton off so sequential work continues → (2) **check your OWN queue and
+pull the next item** rather than going idle → (3) go truly idle only when your queue is **exhausted**,
+then wait for the baton. An agent idling on top of a stocked queue is the single biggest utilization
+leak (see `orchestration-team` → *queue depth is the orchestrator's product*). This is pull-not-push at
+the seat level and needs no new machinery — the last act *after a handoff* is a **PULL**.
+
+## Default-nudge semantics (the syntax footgun)
+
+| Command | Nudges by default? | When to use |
+|---|---|---|
+| `rig queue create` | yes | New qitem created from scratch |
+| `rig queue handoff` | yes | Transactional close-as-handed-off + create-new |
+| `rig queue handoff-and-complete` | yes | Atomic close + create-new; default nudge wakes the new owner |
+
+**Footgun**: `--no-nudge` accidentally added to a live-loop handoff.
+The shipped 0.3.1 CLI nudges by default on every queue write surface
+(`rig queue create`, `rig queue handoff`, AND `rig queue handoff-and-complete`).
+The only suppression flag is `--no-nudge` — appropriate for intentional
+cold park, human-gate signal, or a deliberate poll-driven workflow, but
+NOT for live-loop handoffs where motion matters.
+
+**Rule**: in a live loop, omit `--no-nudge` and trust the default.
+`--no-nudge` is the opt-out, not the opt-in. If you find yourself
+reaching for `--notify`, stop — that flag does not exist on the
+shipped 0.3.1 CLI; you may be following a stale instruction that
+inverted the default-nudge polarity.
+
+## Queue-body hygiene (token + parse safety)
+
+The qitem body is durable DATA the daemon stores and replays on every
+`rig queue show <id>` / `--json` read. Keep it small and parse-safe — a
+bloated or malformed body costs every future reader, not just the
+recipient.
+
+- **No large command output in bodies.** Do NOT paste `rig ps`/`--nodes`
+  dumps, big JSON blobs, full proof output, diffs, or transcript chunks
+  into a qitem body. **Link the artifact PATH** (e.g.
+  `missions/<m>/<slice>/proof.md`) or **summarize in prose**, then point
+  at the file for the detail. A pasted dump makes `rig queue show <id>
+  --json` huge — a second-order token bloat: bloated DATA living in the
+  queue, distinct from the command-default output bombs the token-burn
+  emergency pack covers.
+- **Substantive bodies go through `--body-file`, not inline `--body`.**
+  For anything beyond a short line, write the body to a file and pass
+  `--body-file <path>` (or `-` for stdin). Inline `--body` with shell
+  metacharacters is fragile.
+- **No raw backticks in bodies.** Backticks in an inline body are shell
+  command-substitution and corrupt the payload (or execute). If you need
+  code/command spans, use `--body-file`, or drop the backticks and write
+  the command in plain text.
+
+Heuristic: if the thing you want to include is more than a few lines or
+contains shell metacharacters (backticks, `$`, quotes, newlines-with-pipes),
+it belongs in a file you LINK, not in the body you paste.
+
+Product backstop (defense-in-depth, NOT a substitute for this discipline):
+`rig queue show` oversized-body truncation/preview is tracked separately
+as slice OPR.0.4.1.3. The behavioral rule here is the primary, durable
+cure; the product truncation is the safety net.
+
+## Failure modes (6; verbatim)
+
+1. Agent ends a turn without a handoff, so the rig appears idle.
+2. Agent creates a queue item with `--no-nudge` inside a live loop, intending suppression of attention but breaking immediate motion. `--no-nudge` is for intentional cold park / human gate, not for routine live-loop handoffs. The opposite footgun — adding a `--notify` flag that does not exist on the shipped 0.3.1 CLI — comes from following stale instructions; the default already nudges.
+3. Queue item is too small and turns work into bureaucracy.
+4. Queue item is too broad and loses ownership, proof, or closure criteria.
+5. Human escalation happens in chat but not as a durable attention item.
+6. Agent pastes a large command dump (ps/nodes, big JSON, proof blob) into the qitem body, bloating the stored DATA so every future `rig queue show --json` read is huge. Link the proof PATH or summarize in prose; substantive bodies go through `--body-file`; no raw backticks inline.
+
+## Durable handoff field shape
+
+Every qitem carries:
+
+- `handed_off_to` — destination session (qualified `pod-member@rig` form)
+- `handed_off_from` — source session
+- `state` — one of: `pending | in-progress | done | blocked | failed | denied | canceled | handed-off`
+- `closure_reason` + `closure_target` — set on terminal closure per hot-potato rule
+
+**(0.5.0) `--body-context <ref>` — context riding the handoff.** `rig queue create … --body-context <ref>` attaches a composed context pack to the qitem. The snapshot rule: the qitem stores the **resolved content** in its body **plus the ref for provenance** — the handoff carries what was actually sent, and a later edit to the library never silently rewrites a past handoff's history. (The `rig context` noun composes the ref; the queue delivers it — the noun has no send.) See `openrig-user` → "Context packs and paced delivery."
+
+The fields are auditable on the daemon-backed `rig queue` surface. Watchdog
+policies and workflow runtime project new owners off these fields.
+
+If a daemon-backed coordination command fails, debug the command/runtime/schema
+edge directly — don't fall back to stale pre-upgrade assumptions.
+
+## See also
+
+- `looping-workflows` skill — operating discipline for self-driving rig-shaped loops; queue-handoff is its current handoff substrate
+- `intake-routing` skill — how raw signals enter the system and become routed work that flows through the queue

package/daemon/context-packs/skills/queue-handoff/manifest.yaml

@@ -0,0 +1,10 @@
+# GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
+# Package-time projection of a canonical skill; regenerated every build.
+name: "queue-handoff"
+version: "0.5.7"
+taxonomy: "skills"
+purpose: "Use when ending a turn, finishing a slice, blocked on another agent's work, or escalating to a human — durable work handoff via queue items so the system keeps moving across compactions, missed messages, and interruptions. Covers the hot-potato terminal-turn-rule (active work ends by passing the ball, not by going idle), default-nudge semantics, and when `--no-nudge` is appropriate for intentional cold park or human gate."
+files:
+  - path: "SKILL.md"
+    role: "instruction"
+    summary: "Use when ending a turn, finishing a slice, blocked on another agent's work, or escalating to a human — durable work handoff via queue items so the system keeps moving across compactions, missed messages, and interruptions. Covers the hot-potato terminal-turn-rule (active work ends by passing the ball, not by going idle), default-nudge semantics, and when `--no-nudge` is appropriate for intentional cold park or human gate."

package/daemon/context-packs/skills/refocusing/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: refocusing
+description: >-
+  Use when a long-running agent may have lost the product outcome, when context was compacted,
+  when work has crossed a major boundary, or when a fresh path-based trace is needed before the
+  next consequential action. Not for fresh-session orientation, waking an idle seat, or checkpoints.
+metadata:
+  openrig:
+    stage: product
+---
+
+# Refocusing
+
+Refocus preserves a long session's earned expertise while re-grounding it in current intent and
+lived context. It is not a restart, wake, or phase checkpoint.
+
+Run the bundled trace from this skill directory instead of reconstructing the hierarchy from memory:
+
+```bash
+python3 scripts/trace-to-root.py --trees both --depth light
+```
+
+Use `--trees topology|work|both` to select context domains and `--depth light|full` to control how
+much each node contributes. Light work traces compose `intent:` and name notes; full traces include
+the complete node and notes bodies. The script resolves `topology.root` and `workspace.root` with
+`rig config get`. When a current node cannot be derived, set `OPENRIG_REFOCUS_TOPOLOGY_NODE` or
+`OPENRIG_REFOCUS_WORK_NODE`, or pass the matching `--*-start` option.
+
+Read [references/refocus.md](references/refocus.md) when changing the automatic hook or its content
+ladder. A missing chain file is evidence: report the gap and continue; never follow pointers to invent
+a second parent.

package/daemon/context-packs/skills/refocusing/manifest.yaml

@@ -0,0 +1,14 @@
+# GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
+# Package-time projection of a canonical skill; regenerated every build.
+name: "refocusing"
+version: "0.5.7"
+taxonomy: "skills"
+purpose: "Use when a long-running agent may have lost the product outcome, when context was compacted, when work has crossed a major boundary, or when a fresh path-based trace is needed before the next consequential action. Not for fresh-session orientation, waking an idle seat, or checkpoints."
+files:
+  - path: "SKILL.md"
+    role: "instruction"
+    summary: "Use when a long-running agent may have lost the product outcome, when context was compacted, when work has crossed a major boundary, or when a fresh path-based trace is needed before the next consequential action. Not for fresh-session orientation, waking an idle seat, or checkpoints."
+  - path: "references/refocus.md"
+    role: "reference"
+  - path: "scripts/trace-to-root.py"
+    role: "reference"

package/daemon/context-packs/skills/refocusing/references/refocus.md

@@ -0,0 +1,22 @@
+# Refocus
+
+1. What is the person actually trying to get? Not your current task — the outcome.
+2. Does what you are doing RIGHT NOW move that? If you cannot say what a user gets, stop and say so.
+3. What have you concluded without opening the file or running the thing?
+
+Discomfort on any of these is the signal: drift feels like work.
+
+The `refocusing` skill carries the source-appropriate path-only trace. Its
+`scripts/trace-to-root.py` walks both current trees by default: topology `LEARNED.md`, then work
+`SPEC.md` intent plus `NOTES.md`. Change breadth with `OPENRIG_REFOCUS_TREES=topology|work|both`
+and read depth with `OPENRIG_REFOCUS_DEPTH=light|full`.
+
+Replace this default without editing the plugin. The content ladder, highest precedence first, is:
+
+1. `OPENRIG_REFOCUS_CONTENT_REF`, resolved by `rig context get`.
+2. `OPENRIG_REFOCUS_CONTENT_FILE`, an operator-authored file.
+3. `$OPENRIG_HOME/refocus/REFOCUS.md`, instance content.
+4. This shipped default.
+
+Fresh seats receive the separate onboarding assets `openrig-onboarding-01.md` and
+`openrig-onboarding-02.md`. This file only cites those assets; it does not copy their world install.

package/daemon/context-packs/skills/refocusing/scripts/trace-to-root.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+"""Render topology and work context by ascending directory paths only."""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+
+SHELVES = {"rigs", "pods", "seats", "missions", "slices"}
+
+
+def rig_output(*args):
+    try:
+        result = subprocess.run(
+            ["rig", *args], capture_output=True, text=True, timeout=10, check=False
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    value = (result.stdout or "").strip()
+    return value if result.returncode == 0 and value else None
+
+
+def configured_root(key, env_key):
+    value = os.environ.get(env_key) or rig_output("config", "get", key)
+    return Path(value).expanduser().resolve() if value else None
+
+
+def under_root(path, root):
+    try:
+        path.relative_to(root)
+        return True
+    except ValueError:
+        return False
+
+
+def ascent(start, root):
+    start = start.expanduser().resolve()
+    if not under_root(start, root):
+        return None, f"start is outside configured root: {start}"
+    nodes = []
+    current = start
+    while True:
+        if current.name not in SHELVES:
+            nodes.append(current)
+        if current == root:
+            break
+        parent = current.parent
+        if parent == current:
+            return None, f"could not reach configured root: {root}"
+        current = parent
+    return list(reversed(nodes)), None
+
+
+def read(path):
+    try:
+        return path.read_text(encoding="utf8", errors="replace")
+    except OSError:
+        return None
+
+
+def resolve_notes(node):
+    try:
+        result = subprocess.run(
+            ["rig", "scope", "resolve-notes", str(node), "--json"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        return None, "resolver command timed out"
+    except OSError as error:
+        return None, f"resolver command could not start: {error}"
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout or "").strip().splitlines()
+        suffix = f": {detail[0]}" if detail else ""
+        return None, f"resolver command exited {result.returncode}{suffix}"
+    try:
+        payload = json.loads(result.stdout)
+    except (json.JSONDecodeError, TypeError):
+        return None, "resolver command returned malformed JSON"
+    if not isinstance(payload, dict) or payload.get("ok") is not True or "resolution" not in payload:
+        return None, "resolver command returned an invalid success shape"
+    resolution = payload["resolution"]
+    if resolution is None:
+        return None, None
+    if not isinstance(resolution, dict):
+        return None, "resolver command returned an invalid resolution shape"
+    resolved_path = resolution.get("path")
+    resolved_name = resolution.get("name")
+    if not isinstance(resolved_path, str) or not isinstance(resolved_name, str):
+        return None, "resolver command returned an invalid resolution shape"
+    return (Path(resolved_path), resolved_name), None
+
+
+def intent(text):
+    if not text or not text.startswith("---"):
+        return None
+    match = re.match(r"^---\s*\n(.*?)\n---(?:\s*\n|$)", text, re.S)
+    if not match:
+        return None
+    lines = match.group(1).splitlines()
+    for index, line in enumerate(lines):
+        found = re.match(r"^intent:\s*(.*)$", line)
+        if not found:
+            continue
+        value = found.group(1).strip()
+        if value in {"|", ">", "|-", ">-", "|+", ">+"}:
+            block = []
+            for later in lines[index + 1:]:
+                if later and not later[0].isspace():
+                    break
+                block.append(later.strip())
+            return " ".join(part for part in block if part)
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in {"'", '"'}:
+            if value[0] == '"':
+                try:
+                    return json.loads(value)
+                except json.JSONDecodeError:
+                    pass
+            return value[1:-1]
+        return value or None
+    return None
+
+
+def light_learned(text):
+    if not text:
+        return ""
+    body = re.sub(r"^---\s*\n.*?\n---\s*\n", "", text, count=1, flags=re.S).strip()
+    if len(body) <= 800:
+        return body
+    boundary = body.rfind("\n", 0, 800)
+    return body[:boundary if boundary > 0 else 800].rstrip() + "\n[… use --depth full for the rest]"
+
+
+def render_topology(start, root, depth):
+    output = ["## TOPOLOGY TRACE", f"root: {root}", f"start: {start}"]
+    nodes, error = ascent(start, root)
+    if error:
+        return "\n".join(output + [f"TRACE GAP — {error}"])
+    for node in nodes:
+        chain_file = node / "LEARNED.md"
+        text = read(chain_file)
+        label = node.relative_to(root) or Path(".")
+        if text is None:
+            output.append(f"\n### {label}\nMISSING LINK — {chain_file}")
+            continue
+        body = text.strip() if depth == "full" else light_learned(text)
+        output.append(f"\n### {label} · LEARNED.md\n{body}")
+    return "\n".join(output)
+
+
+def render_work(start, root, depth):
+    output = ["## WORK TRACE", f"root: {root}", f"start: {start}"]
+    nodes, error = ascent(start, root)
+    if error:
+        return "\n".join(output + [f"TRACE GAP — {error}"])
+    for node in nodes:
+        label = node.relative_to(root) or Path(".")
+        spec = next((candidate for candidate in (node / "SPEC.md", node / "README.md") if candidate.is_file()), None)
+        if spec is None:
+            output.append(f"\n### {label}\nMISSING LINK — no SPEC.md or README.md at {node}")
+        else:
+            text = read(spec) or ""
+            if depth == "full":
+                body = text.strip()
+            else:
+                value = intent(text)
+                body = f"intent: {value}" if value else "MISSING INTENT — no readable intent: field"
+            output.append(f"\n### {label} · {spec.name}\n{body}")
+
+        notes, resolution_error = resolve_notes(node)
+        if resolution_error:
+            output.append(f"NOTES RESOLUTION GAP — {resolution_error} at {node}")
+        elif notes:
+            notes_path, notes_name = notes
+            if depth == "full":
+                notes_text = read(notes_path)
+                if notes_text is None:
+                    output.append(f"NOTES RESOLUTION GAP — resolved {notes_name} became unreadable at {notes_path}")
+                else:
+                    output.append(f"\nNOTES · {notes_name}\n{notes_text.strip()}")
+            else:
+                try:
+                    size = notes_path.stat().st_size
+                except OSError:
+                    output.append(f"NOTES RESOLUTION GAP — resolved {notes_name} became unreadable at {notes_path}")
+                else:
+                    output.append(f"NOTES · {notes_name} · {size} bytes · {notes_path}")
+        else:
+            output.append(f"NOTES GAP — no readable mission notes at {node}")
+    return "\n".join(output)
+
+
+def derive_topology_start(root):
+    explicit = os.environ.get("OPENRIG_REFOCUS_TOPOLOGY_NODE")
+    if explicit:
+        return Path(explicit)
+    raw = rig_output("whoami", "--json")
+    if not raw:
+        return None
+    try:
+        identity = json.loads(raw).get("identity", {})
+    except json.JSONDecodeError:
+        return None
+    rig = identity.get("rigName")
+    session = identity.get("sessionName")
+    if not rig or not session:
+        return None
+    seat = str(session).split("@", 1)[0]
+    return root / "rigs" / str(rig) / "seats" / seat
+
+
+def derive_work_start(root):
+    explicit = os.environ.get("OPENRIG_REFOCUS_WORK_NODE")
+    if explicit:
+        return Path(explicit)
+    current = Path.cwd().resolve()
+    if not under_root(current, root):
+        return None
+    while under_root(current, root):
+        if (current / "SPEC.md").is_file() or (current / "README.md").is_file():
+            return current
+        if current == root:
+            break
+        current = current.parent
+    return None
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--trees", choices=("topology", "work", "both"), default=os.environ.get("OPENRIG_REFOCUS_TREES", "both"))
+    parser.add_argument("--depth", choices=("light", "full"), default=os.environ.get("OPENRIG_REFOCUS_DEPTH", "light"))
+    parser.add_argument("--topology-start")
+    parser.add_argument("--work-start")
+    args = parser.parse_args()
+
+    sections = []
+    if args.trees in {"topology", "both"}:
+        root = configured_root("topology.root", "OPENRIG_TOPOLOGY_ROOT")
+        if root is None:
+            sections.append("## TOPOLOGY TRACE\nTRACE GAP — topology.root is unresolved")
+        else:
+            start = Path(args.topology_start) if args.topology_start else derive_topology_start(root)
+            sections.append(render_topology(start, root, args.depth) if start else
+                            "## TOPOLOGY TRACE\nTRACE GAP — current topology node is unresolved; set OPENRIG_REFOCUS_TOPOLOGY_NODE")
+
+    if args.trees in {"work", "both"}:
+        root = configured_root("workspace.root", "OPENRIG_WORKSPACE_ROOT")
+        if root is None:
+            sections.append("## WORK TRACE\nTRACE GAP — workspace.root is unresolved")
+        else:
+            start = Path(args.work_start) if args.work_start else derive_work_start(root)
+            sections.append(render_work(start, root, args.depth) if start else
+                            "## WORK TRACE\nTRACE GAP — current work node is unresolved; set OPENRIG_REFOCUS_WORK_NODE")
+
+    print("\n\n".join(sections))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/daemon/context-packs/skills/retiring-and-inheriting-a-seat/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog — retiring-and-inheriting-a-seat
+
+**`SKILL.md` carries the mechanic; this file carries how it got there.** Rationale, superseded
+designs, and the incidents that produced a rule live here so the instruction surface stays
+instructional.
+
+---
+
+## 2026-08-13 — wake is a verb now, and the packet must not bound the channel (Wake v0)
+
+### Two corrections to the same section
+
+**1 · The mechanism claim was stale.** The section read *"In v0 this is a practice + skill, not a
+`rig` verb — wrap it in a verb only when convenience and consistency earn it."* `rig ask --wake`
+had since shipped in CLI 0.5.1, with `--runtime` and `--wake-timeout` (default 180s). A retiring
+agent reading the old line would have told its successor a verb existed only in principle.
+
+The verb is a thin wrapper over the harness resume and is **not yet well-exercised** (mission owner,
+2026-08-13), so the fallback to `claude -p --resume` is stated inline rather than left implied. **A
+failing wrapper must never be read as a closed channel** — that inference was made once already and
+cost a successor several turns.
+
+**2 · The retiring side is where the reach-back failure is caused.** Across lineages on record, the
+successor consulting its predecessor has almost never happened, and the packet is what suppresses
+it. Two shapes, both observed in real packets on this rig:
+
+- **Bounding the channel in time** — *"ask while the window is open"*, *"after this I am a
+  transcript, not a conversation"*. Neither is true: a retired tenure stays resumable while its
+  session record exists, and the only real bound is its own context wall hit while answering. The
+  second phrasing measurably cost a successor a capability it had (see
+  `orienting-to-an-inherited-seat/CHANGELOG.md`, 2026-08-13).
+- **Offering access without a trigger** — *"predecessor consultation: not needed"* and *"you may
+  consult your predecessor"* each produced **zero consultations** from otherwise capable successors.
+
+The distinction worth preserving, because retiring agents keep collapsing it: *"treat my answers as
+testimony"* is a **posture** claim and it is correct. *"You can no longer converse with me"* is a
+**capability** claim and it is false. They get written as the same sentence.
+
+### Why the guidance is phrased as what to write
+
+Stated positively (*state that the channel does not expire; give your verbatim handle; pre-form the
+questions*) rather than as a list of forbidden sentences. A prohibition list in `SKILL.md` would
+draw attention to phrasings a retiring agent would otherwise never produce.
+
+### Standing
+
+The fix is unverified. The measurable outcome is whether the next successor asks unprompted, and
+more than once — the baseline is zero.