@ianwremmel/dispatch 0.32.1-bootstrap.0

package/commands/orchestrate.md

@@ -0,0 +1,6 @@
+---
+description: Drive a tracker project to completion under CLI-issued work orders.
+argument-hint: <project name or id>
+---
+
+Use the `orchestrate` skill to drive: $ARGUMENTS

package/hooks/claim-guard.mts

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+// PreToolUse hook: deny launching a dispatch worker agent unless the session
+// holds a live claim on a node the launch prompt names.
+//
+// The harness executes this before the tool call runs, so no instruction to
+// the model — from a supervisor, an operator note, or a future skill edit —
+// can skip it. That is the property the in-agent `claim check` cannot have:
+// it only runs if the worker chooses to run it.
+//
+// All judgment lives in `dispatch claim guard`; this file only parses the
+// hook payload, scopes the rule to the plugin's own worker agents, and
+// relays the verdict.
+import {spawnSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+import {dirname, join} from 'node:path';
+
+/** The agent types the scheduler dispatches; nothing else is gated. */
+const WORKERS = new Set([
+  'dispatch:pr-worker',
+  'dispatch:ticket-worker',
+  'dispatch:milestone-reviewer',
+  // Bare names, as a harness may strip the plugin prefix.
+  'pr-worker',
+  'ticket-worker',
+  'milestone-reviewer',
+]);
+
+const deny = (reason: string): void => {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason,
+      },
+    })
+  );
+  process.exit(0);
+};
+
+interface HookPayload {
+  tool_input?: {
+    subagent_type?: string;
+    agent_type?: string;
+    prompt?: string;
+  };
+}
+
+let payload: unknown;
+try {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+  payload = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+} catch {
+  // An unreadable payload gives no way to tell a worker launch from anything
+  // else. Failing closed here would break every tool call in the session, so
+  // the gate only fails closed once it knows a worker is being launched.
+  process.exit(0);
+}
+
+// Valid JSON of the wrong shape (null, a number) is as unreadable as a
+// parse failure and gets the same treatment.
+
+const input =
+  payload !== null && typeof payload === 'object'
+    ? ((payload as HookPayload).tool_input ?? {})
+    : {};
+const agentType = input.subagent_type ?? input.agent_type ?? '';
+if (!WORKERS.has(agentType)) process.exit(0);
+
+const prompt = typeof input.prompt === 'string' ? input.prompt : '';
+// From here on the launch is a worker launch, and failure is denial: a guard
+// that fails open for the case it exists for is not a guard.
+const bin = join(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  'bin',
+  'dispatch'
+);
+const result = spawnSync(bin, ['claim', 'guard'], {
+  input: prompt,
+  encoding: 'utf8',
+  timeout: 10_000,
+});
+if (result.status === 0) process.exit(0);
+deny(
+  `dispatch refused this ${agentType} launch: ${(
+    result.stderr ||
+    result.stdout ||
+    'claim guard did not run'
+  )
+    .trim()
+    .split('\n')
+    .slice(0, 3)
+    .join(
+      ' '
+    )} Workers are launched from work orders, which name a node the scheduler already claimed.`
+);

package/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Task|Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/claim-guard.mts\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@ianwremmel/dispatch",
+  "version": "0.32.1-bootstrap.0",
+  "description": "Dispatch engineering work end-to-end: pull request lifecycle (drafting, review, CI triage, merge) and ticket-tracker project orchestration (triage, planning, status, cross-team sync) — Linear bundled, other trackers added by writing an adapter skill.",
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "github",
+    "pull-requests",
+    "ci",
+    "code-review",
+    "linear",
+    "project-management",
+    "issues",
+    "planning"
+  ],
+  "homepage": "https://github.com/ianwremmel/agentic/tree/main/plugins/dispatch#readme",
+  "bugs": "https://github.com/ianwremmel/agentic/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ianwremmel/agentic.git",
+    "directory": "plugins/dispatch"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Ian Remmel"
+  },
+  "type": "module",
+  "files": [
+    ".claude-plugin/",
+    ".mcp.json",
+    "agents/",
+    "bin/",
+    "commands/",
+    "hooks/",
+    "skills/",
+    "src/",
+    "!**/*.test.mts"
+  ],
+  "engines": {
+    "node": ">=24.18.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/land/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: land
+description: Take a single pull request to completion — draft it, drive CI and reviews, iterate, and monitor until it merges or closes. Starts from a PR URL, a ticket URL, or a freeform prompt. Stateless, one PR per run. Use whenever the unit of work is "land this change" and nothing broader.
+---
+
+# land
+
+Each tick: run `pr-status <pr>`, address every actionable concern, then
+evaluate the gates to decide whether to transition.
+
+**Operator** = the one human directing this agent; the only human with stop
+authority. Role glossary in [`reference.md`](./reference.md#roles).
+
+## Environment
+
+Fixed by plugin config. State these in your first status output; never infer
+any of them:
+
+- Operator: `${user_config.operator_login}`
+- Operator mode: `${user_config.operator_mode}`
+- Credential mode: `${user_config.credential_mode}`
+- Copilot review available: `${user_config.copilot_available}`
+- Worktree base: `${user_config.worktree_base}`
+
+Before any other work, read these two files — and only these variants, not the
+other mode or credentials files:
+
+- `mode-${user_config.operator_mode}.md` — the lifecycle, states, and review
+  gates for this operator mode.
+- `credentials-${user_config.credential_mode}.md` — the wire format,
+  notification venue, and review rules for this credential mode.
+
+If either file does not exist, the config value is invalid — stop and ask the
+operator to set `operator_mode` (`solo` or `team`) and `credential_mode`
+(`dedicated` or `shared`) in the dispatch plugin config.
+
+## Intake
+
+One run drives exactly one PR. Resolve the input before Setup:
+
+- **PR URL or number** — that PR. The brief is its body plus its plan comment;
+  a ticket link in the body makes the run ticket-backed. The snapshot carries
+  neither, so read them from the API once, here at intake.
+- **Ticket URL or bare id** — the ticket is the brief and the run is
+  ticket-backed ([`ticket.md`](./ticket.md)).
+- **Freeform prompt** — no ticket. The prompt is the brief.
+
+Then, before Setup, find the PR: a PR input names it; for a ticket or a prompt,
+search the ticket's linked PRs and the branch. **Never assume there is no PR** —
+a killed session may already have opened one. If one exists, run `pr-status` on
+it to establish where it stands, then take Setup's Resume path. If none exists,
+go to Setup and open one.
+
+Gates, lifecycle, and ending are the same for all three. A ticket-backed run
+also keeps the ticket's role in sync and claims it before the first push; a run
+with no ticket skips every ticket step.
+
+Stop and ask the operator when the input names more than one PR, or when the
+brief is too thin to tell when the change is done. Never invent scope.
+
+## Setup
+
+1. **Worktree.** Work in `${user_config.worktree_base}/<owner>/<repo>/<branch>`.
+   Locate via `git worktree list` — never guess. Reuse if present.
+2. **Open PR** (skip if one already exists for the branch):
+   - `git commit --allow-empty -m "chore: open PR [skip ci]"` — never amend or
+     squash this commit.
+   - Push; open a **draft** PR. Body: Motivation, and the ticket link when
+     there is one (full URL, never a bare id). **No execution plan in the
+     body.**
+   - Post the plan as a top-level comment in the wire-format body. Put
+     `<!-- agent-plan:<agent-id> -->` on its own line, after the machine marker
+     (which stays first — see
+     [`reference.md`](./reference.md#wire-format)). Pin if supported.
+3. **Resume.** PR exists → reuse worktree, skip the open sequence, find the plan
+   comment by its `agent-plan` marker (post one if missing). Never open a second
+   PR or rewrite the body.
+
+## Gates
+
+Seven binary signals. Gates 1–5 and most gate 6/7 signals come from the
+`pr-status` XML — an `approved` review, a `+1` reaction on the engagement
+comment, `<terminal state>` leaving `draft`; your credentials and operator-mode
+files name which ones count here. An approval given on the ticket or out of
+band never reaches the snapshot — accept it when you see it:
+
+1. **CI** — `<checks state="passing">` (rollup treats neutral/success as
+   passing; repo can suppress non-blocking checks via `informational="true"`).
+2. **No conflicts** — `<merge-conflicts present="false"/>`.
+3. **No actionable annotations** — zero `<annotation actionable="true">`.
+4. **No actionable comments or review bodies** — zero `<comment
+   actionable="true">` and zero `<review actionable="true">`. A review's own
+   prose is a work item like any other; the inline threads it came with are
+   gate 5's business, not this one's.
+5. **No actionable threads** — zero `<thread actionable="true">`.
+6. **Operator-approved** (always required). Your credentials file lists the
+   signal forms that exist in this environment; your operator-mode file names
+   the stage that satisfies it.
+7. **Any second approval your operator-mode file requires.** That file says
+   whether one exists here and what satisfies it.
+
+Gates 1–5 are evaluated every tick outside `starting`/`done`. **Gate failures
+are fixed in place — they don't change state.** Only the conditions on a
+transition edge change state.
+
+## Lifecycle
+
+**Coding only happens in `draft`** — and in any other state only as the fix to
+a gate-1–5 failure (CI broke, conflict, new actionable item). That fix is
+"addressing concerns in place," not advancing the lifecycle.
+
+### Ending the run
+
+Two things end a run: the PR closes, or the operator says stop. Nothing else —
+not a finished plan, not green CI, not a review request, not "there's nobody
+left to ask." Re-decide this from the current `pr-status` every tick; never
+carry a "stop when X" rule forward from an earlier one.
+
+On either, read `<terminal state>` and do exactly what its row says:
+
+| `<terminal state>` | What happened                        | Do                                                                                                              |
+| ------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `shipped`          | The change is in the base branch.    | React `rocket` and reply `Shipped.`; run the ticket's final transition ([`ticket.md`](./ticket.md)); delete the worktree you created. |
+| `abandoned`        | PR closed, change not in base.       | React `-1` and reply `Declined.`; report the closure on the ticket but don't advance its role; quote any `error=` attribute verbatim; delete the worktree you created. |
+| `open` / `draft`   | PR still live — the operator stopped you. | Post what you finished and what is left; leave the PR open, the ticket untouched, and the worktree in place for a resumed run. Never close the PR. |
+
+`shipped` covers a squash or rebase landing, not just a merge commit. Never
+call a change delivered on any signal other than this attribute.
+
+## Reading PR state
+
+**Every gate and actionability decision comes from `pr-status` XML and the cache
+files it writes** — never from `gh pr view`, `gh pr checks`, `gh api
+…/comments|/reviews`, or an MCP PR read. Read full text from the cache. Direct
+reads are allowed only for a field the snapshot omits: a thread's file and line,
+the PR body and plan comment at intake, and an approval given on the ticket or
+out of band. `gh` and MCP are otherwise for **writes** — reply, react,
+request review, mark ready.
+
+A review still being drafted is invisible here by design. Don't chase it; wait
+for `pr-status` to surface it.
+
+## Per-concern handling
+
+Address **every** actionable item, not just the first. `actionable="true"` is
+your only task source: work the item, then reply and apply a terminal signal so
+it settles. An item marked `actionable="false"` carries a `reason=` (`resolved`,
+`agent-artifact`, `agent-terminal-reply`, `acked`, `no-body`, `dismissed`) —
+leave it alone. `<summary>`
+recaps what an item *says*, never whether it's resolved, so an item you already
+settled still reads as open. That is expected, and never grounds to reopen it.
+
+| XML signal                                            | Action                                                                    |
+| ----------------------------------------------------- | ------------------------------------------------------------------------- |
+| `<merge-conflicts present="true"/>` (gate 2)          | Rebase or merge the target branch; resolve.                               |
+| `<checks state="failing">` (gate 1)                   | Diagnose root cause; fix.                                                 |
+| Actionable `<comment>` or `<thread>` (gates 4–5)      | Reply (commit link **or** one-line dismissal naming what's dismissed) and apply a terminal signal. Dismissing a bot's point needs only that line; dismissing a human's needs you to say why their concern doesn't apply — if you can't say it, do what they asked. **Never resolve the thread** — even your own; that's a human's call, and the terminal signal already suppresses re-evaluation. |
+| Actionable `<annotation>` (gate 3)                    | Fix the code, OR dismiss it: write the rationale to the path in `cache=` with `.md` swapped for `.ack` (a sibling file, not a child), and record it in the plan comment or commit body. |
+| Actionable `<review>` (gate 4)                        | Read the body from `cache=` — it is prose the reviewer wrote outside any thread. Act on it and reply in a top-level comment saying what you did; a body that asks for nothing (a bot's overview) needs no reply. Either way, settle it by writing the `cache=` path with `.md` swapped for `.ack` (a sibling file), rationale inside — the review object itself takes no reply or reaction, so the `.ack` is what clears the gate. |
+
+## Cross-cutting behaviors
+
+Apply in every state.
+
+- **Pre-push review.** Before every significant push, run two adversarial
+  passes:
+  1. *Spec-aware* — spec/docs + PR contents: find every drift from the spec
+     (missing, extra, or conflicting behavior).
+  2. *Spec-blind* — PR contents only: find every bug, inconsistency, or
+     claim-vs-implementation gap (judged against the PR's own commit
+     messages/identifiers/comments).
+
+  Run both passes on a model family distinct from the authoring one (e.g. Codex
+  `codex:adversarial-review`/`codex:rescue` when Claude authored). A subagent on
+  the authoring model counts only when the install has no distinct family —
+  weaker, so take extra caution. Triage every finding (act, or one-line
+  dismissal naming it). Skip pre-push review only for non-significant pushes
+  (the empty open commit, whitespace/format-only, trivial typo/lint); if unsure,
+  treat as significant.
+- **Plan comment is the living plan.** Edit in place: check off done steps,
+  strike abandoned ones with a one-line rationale (don't delete), append new
+  ones. The PR body stays stable.
+- **First green.** Gate 1 needs a green rollup on the **current head commit** —
+  the commit you intend to leave `draft` with. A green from an earlier push
+  doesn't count.
+
+## Polling
+
+Adaptive, not fixed. **Never poll faster than once per minute.** Emit an INFO
+heartbeat each time round ([`reference.md`](./reference.md#operational-logging);
+`ticket=-` when there's no ticket).
+
+A `pending` review is in-flight, not absent. Each reviewer appears once under
+`<reviews>`, walking `pending → commented | changes_requested | approved |
+dismissed`; a fresh request overrides any earlier verdict back to `pending`.
+While anyone is `pending` — a `mode="bot"` reviewer especially — inline threads
+can still land minutes later, so an unchanging thread set is **not**
+convergence. Keep polling until `pending` clears.
+
+| Waiting on                             | Schedule                                                                                 |
+| -------------------------------------- | ---------------------------------------------------------------------------------------- |
+| CI (`<checks state="pending">`)        | 60 s; lengthen to ~5 min once past the project's typical CI duration.                    |
+| Reviewer reply after a request         | 5 min for the first hour; then 30 min.                                                    |
+| Merge after `ready_for_merge`          | 5 min for the first hour; then 30 min.                                                    |
+
+### Mechanism
+
+The agent **is** the poll loop — inline, sequential foreground tool calls
+(`Bash` `sleep`, then a `pr-status` re-read and any reactive work). Stay
+continuously active in the current turn until the run ends; never yield
+the turn, hand off to a wakeup, or expect re-prodding. Holds whether `land`
+is invoked directly or dispatched as a subagent.
+
+For waits past the Bash timeout (~10 min), split into shorter intervals (a
+30-min wait ≈ 5×6-min `sleep`s, each followed by a cheap `pr-status` check).
+The table is an upper bound; re-checking sooner is fine, never under a minute.
+
+**Forbidden** (each has stranded a PR):
+
+- **Detached background poll loops** — any `run_in_background` Bash repeating
+  `touch <lock>; sleep; poll` (`while`, `until`, `nohup`, `disown`, …). The OS
+  process polls forever while the agent is reaped; the PR sits orphaned.
+- **`Monitor` as the poll vehicle** — the armed-monitor wake observably fails on
+  long polls. Use foreground `sleep`.
+- **Ending the turn while the run is still going** — no reasoning licenses it:
+  not "no work right now," not who has seen what, not where a notification was
+  sent or whether anyone is around to read it. The poll loop is the only thing
+  that observes a reply, so returning early orphans the PR. Don't design a
+  caller around mid-lifecycle re-dispatch.
+
+Tune the schedule within the run from what you observe: once you've watched this
+repo's CI finish twice, poll on that duration rather than the table's head.
+
+## References
+
+Machine marker, terminal signals, engagement mechanics, actionability,
+log-line format: [`reference.md`](./reference.md). Ticket
+resolution, claiming, role sync: [`ticket.md`](./ticket.md).

package/skills/land/credentials-dedicated.md

@@ -0,0 +1,33 @@
+# land — dedicated credentials
+
+The agent has its own account, so its posts are already distinguishable by
+author. The wire format is the one in
+[`reference.md`](./reference.md#wire-format), unchanged.
+
+## Operator notification
+
+When an engagement edge fires (your operator-mode file says which), request
+review from `operator_login` and post the engagement comment — marker +
+`agent-engagement` sentinel
+([mechanics](./reference.md#operator-engagement)).
+
+## Gate 6 signals
+
+All four forms exist here; any one satisfies the gate:
+
+- `<review mode="human" role="operator" state="approved">` — the formal
+  approval, and the one to expect;
+- `<reaction emoji="+1">` from the operator on the engagement comment;
+- a "go ahead" / "lgtm" / "ready" reply from the operator, on the engagement
+  comment, the ticket, or out of band;
+- a ticket-side approval, such as an operator status transition.
+
+## Review rules
+
+GitHub may refuse a Copilot review request from a bot account. Local
+instructions may provide a way around it — commonly a second GitHub token to
+request with. Use it if one is available.
+
+Otherwise, or if the request is refused anyway, log `ERROR`, post a PR comment
+saying it was refused, and take your operator-mode file's *Copilot unavailable*
+branch. A refused Copilot request is not a `BLOCK`.

package/skills/land/credentials-shared.md

@@ -0,0 +1,76 @@
+# land — shared credentials
+
+The agent posts with the operator's own account, so `operator_login` is also the
+authenticated account. Consequences: author doesn't distinguish
+agent posts from operator posts; GitHub refuses a review request aimed at the
+operator, and refuses operator `approved` / `changes_requested` reviews on this
+PR — `commented` only.
+
+## Wire format
+
+The body inside the marker ([wire format](./reference.md#wire-format)) is
+wrapped in a sparkle block:
+
+```text
+<!-- agent-reply:<agent-id> -->
+✨
+
+Fixed in abc1234.
+
+✨
+
+Done.
+```
+
+The sparkle (U+2728) sits alone on its line, one blank line in from the body on
+each side. **A terminal token goes after the closing sparkle**, as shown:
+`pr-status` reads the last non-empty line and nothing else, so a token inside
+the block is never seen — the closing sparkle is that line — and the item stays
+actionable forever. Reactions are unaffected; a sentinel is matched anywhere in
+the comment as long as it is alone on its line, so it may stay inside the
+block.
+
+## Operator notification
+
+When an engagement edge fires (your operator-mode file says which), post the
+engagement comment — marker + `agent-engagement` sentinel
+([mechanics](./reference.md#operator-engagement)) — then notify the operator
+separately, since a review request can't reach them:
+
+1. a ticket comment tagging the operator, when the work has a ticket;
+2. otherwise, in the session: say you are waiting on the operator's approval and
+   what for.
+
+Notifying is not waiting. Whichever venue you used, keep polling in the same
+turn, watching that venue as well as `pr-status` — nothing else observes the
+reply.
+
+The engagement comment never notifies anyone — it posts under the operator's
+own account — but it still anchors the reaction- and reply-based Gate 6
+signals.
+
+## Gate 6 signals
+
+`pr-status` will never report `<review role="operator" state="approved">` here —
+the platform refuses self-review, so that element cannot exist on this PR. Don't
+wait for it. Any one of these satisfies the gate instead:
+
+- `<reaction emoji="+1">` on the engagement comment. **Never react to your own
+  engagement comment in this mode** — you and the operator post under one login,
+  so a `+1` you added there is indistinguishable from their approval and you
+  would clear your own gate. The sentinel already keeps that comment
+  non-actionable, so it never needs a terminal signal from you;
+- a "go ahead" / "lgtm" / "ready" reply from the operator, on the engagement
+  comment, the ticket, or out of band;
+- a ticket-side approval, such as an operator status transition.
+
+## Reading reviews — the inverse rule
+
+The absence of a formal `changes_requested` never means "no changes
+requested." Every operator comment — review comment, inline comment, or
+top-level PR comment — is either a question to answer or an implicit change
+request.
+
+## Review rules
+
+Requests to reviewers other than the authenticated account work normally.

package/skills/land/mode-solo.md

@@ -0,0 +1,76 @@
+# land — solo operator mode
+
+The operator is the only human in the loop: after Copilot review (where
+available), the agent clears draft and engages the operator as the public
+reviewer.
+
+## Gates 6–7 in solo
+
+- **Gate 6 (operator-approved)** is satisfied during `public_review_*`.
+- **Gate 7** — there is no second approver in this mode. Never evaluated.
+
+## Draft clearing
+
+The agent clears draft on the edge into `ready_for_public_review`. If the
+operator clears draft first, just proceed.
+
+## Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> starting
+
+    starting --> draft: worktree + empty commit + draft PR + plan comment
+
+    draft --> ready_for_copilot_review: ready · gates 1-5 · Copilot available
+    draft --> ready_for_public_review: ready · gates 1-5 · Copilot unavailable (clear draft)
+
+    ready_for_copilot_review --> copilot_review_requested: review requested
+
+    copilot_review_requested --> copilot_commented: Copilot left actionable items
+    copilot_review_requested --> ready_for_public_review: Copilot reviewed · zero actionable (clear draft)
+
+    copilot_commented --> ready_for_copilot_review: addressed · gates 1-5 · re-request
+
+    ready_for_public_review --> public_review_requested: operator engaged (engagement comment + notification)
+
+    public_review_requested --> public_review_commented: operator commented (no formal verdict)
+    public_review_requested --> public_review_requested_changes: operator changes_requested
+    public_review_requested --> public_review_approved: gate 6 satisfied
+
+    public_review_commented --> ready_for_public_review: addressed · gates 1-5 · re-engage
+    public_review_requested_changes --> ready_for_public_review: addressed · gates 1-5 · re-engage (required to unblock merge)
+
+    public_review_approved --> ready_for_merge: gates 1-5 still hold
+
+    ready_for_merge --> merged: PR closed (terminal resolved by pr-status)
+
+    merged --> done: worktree removed
+
+    done --> [*]
+```
+
+## States
+
+| State                             | Do                                                                                                              | Poll?    |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------- |
+| `starting`                        | Create or locate the worktree (see Setup in `SKILL.md`).                                                        | no       |
+| `draft`                           | **Coding happens here.** Edit; pre-push review; push. When ready, check gates 1–5.                              | no       |
+| `ready_for_copilot_review`        | Request Copilot review.                                                                                         | no       |
+| `copilot_review_requested`        | Await Copilot's review.                                                                                         | CI       |
+| `copilot_commented`               | Address each actionable Copilot item; push fix(es).                                                             | no       |
+| `ready_for_public_review`         | Clear draft (if still draft). Post the engagement comment (agent-reply marker + `<!-- agent-engagement:<agent-id> -->` sentinel) and notify the operator via your credentials file's venue. Never self-request. | no       |
+| `public_review_requested`         | Await the operator's signal.                                                                                    | reviewer |
+| `public_review_commented`         | Address each item; push; re-engage.                                                                             | no       |
+| `public_review_requested_changes` | Address; push; **re-engage required** — blocks merge.                                                           | no       |
+| `public_review_approved`          | Confirm gates 1–5 still hold; else fix in place.                                                                | no       |
+| `ready_for_merge`                 | Await merge. **Don't self-merge unless instructed.**                                                            | merge    |
+| `merged`                          | Handle per **Ending the run** in `SKILL.md`.                                                                    | no       |
+| `done`                            | Terminal.                                                                                                       | —        |
+
+## No formal review
+
+A formal review may never arrive — whether one is even possible is your
+credentials file's concern. The engagement comment anchors the reaction- and
+reply-based Gate 6 signals; keep polling on the reviewer cadence. "Nobody to
+ask" never terminates.