@ianwremmel/dispatch 0.32.1-bootstrap.0

package/skills/land/mode-team.md

@@ -0,0 +1,103 @@
+# land — team operator mode
+
+The operator directs the agent but is one of several humans. Review happens in
+two stages. First the operator reviews alone, while the PR is still a draft.
+Then the operator — never the agent — clears draft, and the rest of the team
+reviews. The team stage is a plain review request, not an engagement.
+
+## Gates 6–7 in team
+
+- **Gate 6 (operator-approved)** is satisfied during `private_review_*`. Draft
+  clearing is one of its signals here: it is the operator's alone to do, so
+  `<terminal state>` moving off `draft` is an approval in its own right. The
+  remaining signals are the ones your credentials file lists.
+- **Gate 7 (team-approved)** is satisfied during `public_review_*`: at least
+  one `<review mode="human" role="team" state="approved">` from a non-self,
+  non-operator reviewer and no current `changes_requested`.
+
+## Draft clearing
+
+The agent **never** clears draft; the operator does. Poll on the reviewer
+cadence until the PR is no longer a draft, then proceed to
+`ready_for_public_review`.
+
+## 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_private_review: ready · gates 1-5 · Copilot unavailable
+
+    ready_for_copilot_review --> copilot_review_requested: review requested
+
+    copilot_review_requested --> copilot_commented: Copilot left actionable items
+    copilot_review_requested --> ready_for_private_review: Copilot reviewed · zero actionable
+
+    copilot_commented --> ready_for_copilot_review: addressed · gates 1-5 · re-request
+
+    ready_for_private_review --> private_review_requested: operator engagement sent
+
+    private_review_requested --> private_review_commented: operator commented (no formal verdict)
+    private_review_requested --> private_review_requested_changes: operator changes_requested
+    private_review_requested --> private_review_approved: gate 6 satisfied
+
+    private_review_commented --> ready_for_private_review: addressed · gates 1-5 · re-engage
+    private_review_requested_changes --> ready_for_private_review: addressed · gates 1-5 · re-engage (required to unblock)
+
+    private_review_approved --> ready_for_public_review: operator cleared draft
+
+    ready_for_public_review --> public_review_requested: team review requested (operator excluded)
+    ready_for_public_review --> public_review_requested: no eligible reviewer (skip request)
+
+    public_review_requested --> public_review_commented: reviewer commented (no formal verdict)
+    public_review_requested --> public_review_requested_changes: reviewer changes_requested
+    public_review_requested --> public_review_approved: gate 7 satisfied
+
+    public_review_commented --> ready_for_public_review: addressed · gates 1-5 · re-request
+    public_review_requested_changes --> ready_for_public_review: addressed · gates 1-5 · re-request (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_private_review`         | Engage the operator while in draft: post the engagement comment (agent-reply marker + `<!-- agent-engagement:<agent-id> -->` sentinel) and notify via your credentials file's venue. | no       |
+| `private_review_requested`         | Await the operator's signal.                                                                                    | reviewer |
+| `private_review_commented`         | Address each item; push; re-engage.                                                                            | no       |
+| `private_review_requested_changes` | Address; push; **re-engage required** — blocks public review.                                                  | no       |
+| `private_review_approved`          | Poll until the PR is no longer a draft (see Draft clearing), then → `ready_for_public_review`.                   | reviewer |
+| `ready_for_public_review`          | Request review from team reviewer(s), **excluding the operator**. Never self-request.                           | no       |
+| `public_review_requested`          | Await the public reviewer.                                                                                      | reviewer |
+| `public_review_commented`          | Address each item; push; re-request.                                                                            | no       |
+| `public_review_requested_changes`  | Address; push; **re-request 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 eligible reviewer
+
+If no non-self, non-operator reviewer exists in `ready_for_public_review`,
+skip the request but still transition to `public_review_requested` and keep
+polling on the reviewer cadence. Gate 7 is then unreachable — the PR merges
+out-of-band, the agent observes closure on a poll, and `merged → done` fires.
+Same for the sole-reviewer case: the operator approves privately, clears draft,
+and merges. A closed PR ends the run from any state — see **Ending the run** in
+`SKILL.md`. "Nobody to ask" never terminates.

package/skills/land/reference.md

@@ -0,0 +1,152 @@
+# land — protocol reference
+
+## Roles
+
+- **Agent** — the agentic coding assistant doing the work (this skill).
+- **Operator** — the one individual directing the agent; almost certainly
+  human; the only human with stop authority.
+- **Reviewer** — any participant leaving review feedback (Copilot, another agent,
+  or a human). The operator may also be a reviewer.
+
+The credential mode is plugin config, stated in the skill's Environment
+section and described by your credentials file. Never infer it from account
+names.
+
+## Wire format
+
+Every agent-authored post (new post or thread reply — not reactions) carries one
+machine marker as its **first line**, alone, no leading whitespace:
+
+```text
+<!-- agent-reply:<agent-id> -->
+```
+
+That marker is the whole of the universal format. Your credentials file gives
+the body format for this environment — follow it exactly, and add nothing it
+doesn't call for.
+
+The plan-comment sentinel `<!-- agent-plan:<agent-id> -->` goes **inside** the
+body, **alone on its own line** — that is what `pr-status` matches, and a
+sentinel sharing a line with prose is not seen at all, leaving the comment
+actionable forever.
+
+## Terminal signals
+
+A terminal signal means "finished with this item"; it suppresses re-evaluation
+next poll. Anything else means "still working." The agent signals finished
+**only** via a terminal signal — it MUST NOT resolve the thread, even one it
+opened. Platform-resolved threads are read (see
+[Actionability](#actionability)) but never written by the agent.
+
+Reactions settle a **top-level comment** and are preferred there. They never
+settle a thread — `pr-status` doesn't read them on threads; use a
+terminal-tagged reply instead.
+
+| Reaction | Meaning                               |
+| -------- | ------------------------------------- |
+| `+1`     | Terminal — addressed / agreed         |
+| `-1`     | Terminal — rejected (with a reply)    |
+| `rocket` | Terminal — shipped / merged / applied |
+| `eyes`   | Non-terminal — seen, in progress      |
+
+Text tokens are the terminal mechanism on threads, and on any platform without
+reactions. When you emit one it must be the **last non-empty line of the whole
+comment** — after any closing wrapper your credentials file adds, not inside it. Emit only
+these three. The reader is more lenient
+than the writer: `pr-status` also accepts `✓`, `✅`, `acknowledged`, `wontfix`,
+`dismissed`, and `resolved`, so a reviewer's stray "resolved" can settle an
+item — don't rely on it, and don't add to this set:
+
+| Token       | Meaning               |
+| ----------- | --------------------- |
+| `Done.`     | Terminal (≡ `+1`)     |
+| `Declined.` | Terminal (≡ `-1`)     |
+| `Shipped.`  | Terminal (≡ `rocket`) |
+
+## Review rules
+
+- An agent MUST NOT request review from the account it is authenticated as.
+- Per-credential-mode rules are in your credentials file.
+- The self-request prohibition constrains the *request*, not the loop — the
+  no-eligible-reviewer handling in the operator-mode files (skip the request,
+  keep polling) still applies.
+
+### Operator engagement
+
+`land` engages the operator on the edge your operator-mode file marks. Each
+engagement is two parts:
+
+1. **Notification** — the venue your credentials file prescribes.
+2. **Engagement comment** — a top-level PR comment with the
+   `<!-- agent-reply:<agent-id> -->` marker on its first line and the
+   engagement sentinel `<!-- agent-engagement:<agent-id> -->` alone on a line of
+   its own anywhere after it. Post it in both credential modes; it anchors the
+   reaction- and reply-based Gate 6 signals.
+
+The sentinel makes the comment classify **non-actionable** (like the plan
+comment) — without it, the agent's own soliciting comment stays actionable
+forever, failing Gate 4 and blocking draft-clear/merge. Do **not** terminal-tag
+it instead: the agent is awaiting approval, not finished.
+
+## Actionability
+
+`pr-status` classifies each item `actionable="true|false"` by the rules below.
+
+A comment or thread is **non-actionable** iff any of:
+
+- it's one of the calling agent's artifact comments — an `agent-plan` or
+  `agent-engagement` sentinel AND author = the calling gh identity (the author
+  match keeps a human quoting a marker actionable).
+- the newest comment was written by the calling agent (author = calling
+  identity) AND carries an `agent-reply` marker AND its last non-empty line is a
+  terminal token from the table above (case-insensitive, trailing period
+  optional). The author match keys on the gh-authenticated login.
+- the calling agent reacted to it with a terminal reaction (`+1`/`-1`/`rocket`;
+  comments only). Top-level comments have no reply threading, so this is the
+  only signal that can settle a comment someone else authored.
+- the platform has explicitly resolved the thread (threads only).
+
+A reviewer reply after the agent's last turn re-actionables the item. An
+annotation is actionable unless `<cache>/<id>.ack` exists.
+
+A `<review>` carries the review's own prose, separate from its inline threads.
+It is actionable unless the body is empty (`reason="no-body"` — a bare verdict,
+or a reviewer who hasn't reviewed yet), the review it came from was dismissed,
+or `<cache>/<id>.ack` exists. A bare verdict over an earlier substantive review
+keeps the earlier body, so `state` and the body can come from different reviews.
+A review body has no reply thread and no reactions, so `.ack` is the only way to
+settle one. Answer first — reply in a top-level comment — unless the body asks
+for nothing, in which case the `.ack` rationale is the whole answer.
+
+## Operational logging
+
+One line per entry:
+
+```text
+<timestamp> <kind> ticket=<ticket-url> pr=<pr-url> ticket-role=<role> pr-state=<state> | <message>
+```
+
+- `<timestamp>` — RFC 3339 with offset, second precision.
+- `ticket=`/`pr=` — full URLs, never bare IDs; `-` when absent.
+- `ticket-role=` — a role name from [`ticket.md`](./ticket.md); `-` on
+  PR-only runs.
+- `<pr-state>` — `draft` | `open` | `shipped` | `abandoned`; `-` when no PR.
+
+Kinds `land` emits:
+
+| Kind         | When                                                                                    |
+| ------------ | --------------------------------------------------------------------------------------- |
+| `INFO`       | Heartbeats while polling; substantive non-state events.                                 |
+| `WAIT`       | Entering a poll; message names the venue and awaited outcome.                           |
+| `RESUME`     | The awaited condition is met and work resumes.                                          |
+| `ERROR`      | Errors surfaced but not immediately fatal.                                              |
+| `BLOCK`      | A "report and stop" path — an unclaimable ticket, a refused required request.            |
+| `TRANSITION` | (Ticket-backed runs) a ticket role change.                                              |
+
+Each ticket role change also gets a state-change comment on the ticket, in wire
+format. Body exactly:
+
+```text
+State: <prev-role> → <new-role>
+Rationale: <one line>
+```

package/skills/land/ticket.md

@@ -0,0 +1,94 @@
+# land — ticket-backed runs
+
+Applies only when Intake resolved a ticket.
+
+## Resolving the tracker
+
+A ticket URL names its own tracker (`linear.app/<workspace>/issue/DEV-123` →
+`linear`); a bare id (`DEV-123`) uses `${user_config.tracker}`. Linear bindings
+are below. For any other tracker, map its states onto these roles yourself
+through its MCP server. A native state whose role is ambiguous maps to no
+role — see Claim.
+
+## Roles
+
+Speak these role names, never a tracker's own state names.
+
+| Role          | Meaning                                          |
+| ------------- | ------------------------------------------------ |
+| `available`   | Eligible to be picked up.                        |
+| `in-progress` | Actively being worked.                           |
+| `in-review`   | Primary work complete; iterating with reviewers. |
+| `delivered`   | Merged or deployed; not yet verified.            |
+| `verified`    | Validated against the ticket's aims. Read-only.  |
+| `canceled`    | Will not be done.                                |
+
+Forward path — `available → in-progress → in-review → delivered`. Never invent
+a native state. When the tracker can't express the target role, stop at the
+last role it can, say so, and let the operator close it: with no `delivered`
+state, the ticket stays `in-review` when the PR ships.
+
+## Transitions
+
+| Ticket edge               | Fires when                                                             |
+| ------------------------- | ---------------------------------------------------------------------- |
+| `available → in-progress` | Claiming, before the first push (below).                               |
+| `in-progress → in-review` | The run reaches its first `*_review_requested` state.                 |
+| `→ delivered`             | `<terminal state="shipped">`, **only if this PR completes the ticket**. |
+
+A ticket that needs more than one PR stays `in-review` when this one lands:
+record the shipped PR in a ticket comment and say which aims remain. Never
+write `verified`; a run ends at `delivered`.
+
+`<terminal state="abandoned">` transitions nothing. Report the closure on the
+ticket and stop.
+
+Every transition emits a `TRANSITION` log line and a state-change comment on
+the ticket ([format](./reference.md#operational-logging)).
+
+## Claim
+
+Steps 1–3 run before the first push:
+
+1. Resolve the current role and act on it:
+   - `available` — claimable; continue.
+   - `in-progress` or `in-review` assigned to **you** — a resumed run. Skip
+     steps 2–3.
+   - `in-progress` or `in-review` **unassigned** — claimable; do step 2, skip
+     step 3.
+   - `in-progress` or `in-review` assigned to **anyone else** — they are on it.
+     Report and stop.
+   - anything else, including a native state that maps to no role — not
+     claimable. Report and stop; moving it is the operator's call.
+2. Assign the ticket to yourself.
+3. Transition the ticket `available → in-progress`.
+4. Once the PR exists, comment its URL on the ticket unless it is already
+   there, and put the ticket's full URL (never a bare id) in the PR body.
+
+## Linear bindings
+
+| Operation      | Call                                                                                                          |
+| -------------- | ------------------------------------------------------------------------------------------------------------- |
+| fetch brief    | `get_issue(id, includeRelations=true)`; `list_comments(issueId)` when the acceptance criteria live in comments |
+| resolve role   | `get_issue(id).state` → `list_issue_statuses(team)` → the role map below                                       |
+| own identity   | `get_user("me")`                                                                                              |
+| assign self    | `save_issue(id, assignee="me")`                                                                               |
+| transition     | `save_issue(id, state=<substate mapping to the target role>)`                                                 |
+| ticket comment | `save_comment(issueId, body)`                                                                                 |
+| react          | `unsupported` — use the text tokens                                                                           |
+
+Match `list_issue_statuses(team)` names case-insensitively:
+
+| Native substate | Role          |
+| --------------- | ------------- |
+| Todo            | `available`   |
+| In Progress     | `in-progress` |
+| In Review       | `in-review`   |
+| Delivered       | `delivered`   |
+| Done            | `verified`    |
+| Canceled        | `canceled`    |
+
+`Delivered` is a custom substate. A substate this table doesn't name maps to no role. A team's custom `Blocked` sits in Linear's `Unstarted` group and is
+not `available`.
+
+Read the ticket's team before writing a state; substates are per-team.

package/skills/orchestrate/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: orchestrate
+description: Drive one or more tracker projects to completion — build the dependency graph, then execute the CLI's work orders as they arrive, launching ticket-worker, pr-worker, and milestone-reviewer agents. Use when the unit of work is a whole project, not one ticket.
+---
+
+# orchestrate
+
+**The CLI decides; you execute.** Never work out which tickets are missing,
+what to dispatch next, or whether anything is complete — every decision
+arrives as an instruction, and you answer it. You never read ticket bodies or
+judge CI state; workers do.
+
+The `dispatch` commands below are also tools on the plugin's MCP server
+(`mcp ack` → the `mcp_ack` tool). When the server is attached, call the tools:
+the server pushes queued instructions after each tool call.
+
+**In plan mode, decline** and ask the operator to re-invoke outside it — this
+skill launches agents and writes state.
+
+## Start
+
+1. Resolve each project name the operator gave to its project id. Load
+   `tracker-adapter-${user_config.tracker}` and use its lookup; without an
+   adapter, drive the tracker's MCP server directly.
+2. Run `dispatch refresh --tracker <tracker> --project <ids>` — one
+   comma-separated value, not repeated flags.
+3. Stop and wait — work arrives as instructions, each handled per the table
+   below, until `project_complete` covers every project the operator named or
+   the operator says stop.
+
+Add `--rebuild` only when the operator asks for a rebuild from scratch.
+
+## Answering instructions
+
+| Instruction                | Do this                                                                                          |
+| -------------------------- | ------------------------------------------------------------------------------------------------ |
+| `probe`                    | Run `dispatch mcp ack --server <id>` with the id the event carries. Work orders wait on it.      |
+| `scan_project`             | Launch a background `build-graph` agent, passing the event's projects and cursor.               |
+| `fetch_ticket`             | Launch a background `build-graph` agent, passing the event's ticket.                            |
+| `refresh_ticket`           | Launch a background `build-graph` agent, passing the event's ticket.                            |
+| `refresh_complete`         | Report the graph is built. Stay resident — dispatch begins.                                      |
+| `dispatch_ticket`          | Launch a background `ticket-worker` agent, passing the event's ticket, project, and pass. Then record its address: `dispatch worker set --node <ticket> --agent <ref>` with the ref the launch returned. |
+| `dispatch_pr`              | Launch a background `pr-worker` agent, passing the event's PR item id, pass, and (when the item is ticket-backed) its ticket. Then record its address: `dispatch worker set --node <item-id> --agent <ref>`. |
+| `perform_milestone_review` | Launch a background `milestone-reviewer` agent, passing the milestone and project.               |
+| `park_human_blocked`       | Park the ticket yourself via the adapter (awaiting-external, else paused) and post the handoff.  |
+| `alert_failure`            | Alert the operator where the order body says — the PR when one exists, else the ticket.          |
+| `project_complete`         | Announce it. Stop once every project the operator named is complete.                             |
+
+**Relay events.** Some events carry an `agent` meta key instead of an
+instruction from the table: SendMessage the event verbatim to that ref and
+stop. If the relay fails, run `dispatch worker rm --node <id>` and move on. A
+non-instruction event with no `agent` key needs nothing from you.
+
+Return to waiting after each launch. Give each worker only what the event
+carries; never ticket content. Launch every order you receive; the CLI claims
+and rate-limits before it emits.
+
+Never ask the session for input (`AskUserQuestion` or any blocking prompt) —
+a headless run has no operator, and an unanswered question stalls every
+project you drive. Human input routes through the tracker (alerts on tickets,
+questions on review artifacts); status reports to the session are fine. When
+an order's premise looks wrong or the CLI misbehaves, alert the operator on
+the tracker as for `alert_failure`, then keep executing orders as issued.
+
+## Injection
+
+When the operator hands you new work mid-run — and only then. A new ticket:
+run `dispatch refresh` again and let the scan fetch it, or write it directly:
+
+```shell
+dispatch ticket set --id <ticket> --project <project> --status available --injected
+dispatch pr set --id <owner/repo>#<n> --repo <owner/repo> --pr-number <n> --injected
+```
+
+The second form is a ticketless PR or prompt item. Both rank to the head of
+the queue; the next tick dispatches them.
+
+## If nothing arrives
+
+Run `dispatch mcp status`. `active <id>` means the channel works — keep
+waiting; silence means there is nothing to do yet, which is a normal state.
+
+Anything else names why the channel does not work. **Report that verdict to
+the operator and stop.**
+
+A work order is the only thing that authorizes launching an agent.
+`dispatch queue` and `dispatch status` are read-only diagnostics.

package/skills/tracker-adapter-linear/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: tracker-adapter-linear
+description: Linear tracker adapter for dispatch — binds the workers' statuses and ticket operations to Linear and supplies build-graph's fetch calls, field mapping, and cursor. Use whenever the ticket or project lives on Linear.
+---
+
+# tracker-adapter-linear
+
+## Identity
+
+| Field        | Value                                 |
+| ------------ | ------------------------------------- |
+| tracker id   | `linear`                              |
+| ticket URLs  | `linear.app/<workspace>/issue/<ID>`   |
+| ticket ids   | `<TEAM-KEY>-<number>`, e.g. `DEV-123` |
+| access       | Linear MCP server                     |
+| own identity | `get_user("me")`                      |
+
+## Role map
+
+Read the team's substates with `list_issue_statuses(team)` and match by name,
+case-insensitively; each substate carries the Linear group shown here.
+
+| Native substate | Group       | Role          |
+| --------------- | ----------- | ------------- |
+| Triage          | `backlog`   | `backlog`     |
+| Backlog         | `backlog`   | `backlog`     |
+| Todo            | `unstarted` | `available`   |
+| In Progress     | `started`   | `in-progress` |
+| In Review       | `started`   | `in-review`   |
+| Finished        | `started`   | `finished`    |
+| Delivered       | `started`   | `delivered`   |
+| Done            | `completed` | `verified`    |
+| Canceled        | `canceled`  | `canceled`    |
+| Duplicate       | `canceled`  | `canceled`    |
+
+`Finished` and `Delivered` are custom substates; a team without them collapses
+the forward path (`in-review → delivered`, or `in-review → verified` where
+neither exists). `paused` and `awaiting-external` are unmapped by default: a
+team that needs them adds Backlog substates and maps them in its own copy of
+this adapter. Until then a park has no substate to land on and is an `ERROR` —
+moving a ticket to plain `Backlog` is not a park.
+
+A substate this table doesn't name is handled per consumer:
+
+- **a worker** (transitioning the acting ticket): an `ERROR`, not a guess —
+  its Linear group narrows the role but doesn't pick it (a team's custom
+  `Blocked` substate sits in `Unstarted` and is not `available`).
+  Map it in your own copy.
+- **build-graph** (sweeping whole projects, foreign teams included): map it
+  only when its lifecycle meaning is unambiguous (a `Merged` substate is
+  `delivered`); otherwise escalate to the operator — a wrong role silently
+  dispatches, or strands, real work.
+
+## Operations
+
+| Operation          | Binding                                                                                                        |
+| ------------------ | -------------------------------------------------------------------------------------------------------------- |
+| fetch brief        | `get_issue(id, includeRelations=true)`; `list_comments(issueId)` when the acceptance criteria live in comments |
+| resolve role       | `get_issue(id).state` → `list_issue_statuses(team)` → the role map above                                       |
+| own identity       | `get_user("me")`                                                                                               |
+| claim guard        | `get_issue(id).assignee`                                                                                       |
+| assign self        | `save_issue(id, assignee="me")`                                                                                |
+| transition         | `save_issue(id, state=<substate mapping to the target role>)`                                                  |
+| ticket comment     | `save_comment(issueId, body)`                                                                                  |
+| read comments      | `list_comments(issueId)` — match the alert sentinel; replies carry `parentId`                                  |
+| react              | `unsupported` — no reaction call in the Linear MCP server; use the text tokens                                 |
+| file ticket        | `save_issue(title, team, description)` — same team as the ticket unless the brief says otherwise               |
+| subtask            | `save_issue(title, team, parentId=<parent>)`                                                                   |
+| blocks edge        | `save_issue(id=<blocker>, blocks=[<blocked>])` (append-only)                                                   |
+| one-edge neighbors | `get_issue(id, includeRelations=true)` → `blockedBy` / `blocks`                                                |
+
+## Quirks
+
+- Linear tickets are per-team: read the acting ticket's team before writing a
+  state or filing into it, and don't reuse another team's substate names.
+- Linear archives completed work; an archived task's `Done`/`Canceled` status
+  still counts toward its milestone, so `build-graph` must not `task rm` it.
+
+## Review artifact (milestone-review)
+
+The review artifact is a **project status update**. Status updates are
+project-scoped, not per-milestone, so the body must carry the milestone id
+(the episode sentinel does) to keep concurrent milestones' reviews distinct.
+
+| Operation              | Binding                                                                                                                                 |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| milestone brief        | `get_milestone(project, query)` — the goal lives in its description                                                                     |
+| find review artifact   | `get_status_updates(type="project", project)` → the newest update whose body carries the episode sentinel with this milestone's id      |
+| post review artifact   | `save_status_update(type="project", project, body, health)` — `onTrack` when the goal is achieved, `atRisk` otherwise                   |
+| update review artifact | `save_status_update(id, body, health)` — same update; the pending→outcome edit when human input resolved                                |
+| artifact thread        | `list_comments(statusUpdateId)` / `save_comment(statusUpdateId)`; one thread per update — reply via `parentId`; tag with `@displayName` |
+| file follow-up         | `save_issue(title, team, description, project, milestone)` — `milestone` takes a name or id; pick the team per Quirks                   |
+
+Member DoD comments and canceled-member rationales are ticket reads — use the
+Operations bindings above (`fetch brief`, `read comments`).
+
+## Graph fetch (build-graph)
+
+`build-graph` owns the loop and the CLI; this section supplies the Linear side.
+
+Per selected project:
+
+| Step         | Call                                                 | Take                                                |
+| ------------ | ---------------------------------------------------- | --------------------------------------------------- |
+| Project      | `list_projects` (`query`)                            | `id`, `name`                                        |
+| Milestones   | `list_milestones` (`project`)                        | `id`, `name`, `sortOrder`                           |
+| Tasks        | `list_issues` (`project`, `limit: 250`, `updatedAt`) | see the mapping below                               |
+| Dependencies | `get_issue` (`id`, `includeRelations: true`)         | `relations.blocks[].id`, `relations.blockedBy[].id` |
+
+- `list_issues` does not return relations. `get_issue` every task in the delta,
+  in parallel batches.
+- Page on `hasNextPage` / `cursor` (that `cursor` is pagination, not the sync
+  cursor).
+- A `blockedBy` id outside the delta still gets its edge. Do not chase it —
+  the CLI records a placeholder and sends a `fetch_ticket` instruction if it
+  wants the ticket.
+
+### Map to CLI flags
+
+| CLI                                       | Linear                                              |
+| ----------------------------------------- | --------------------------------------------------- |
+| `ticket set --id`                         | `id` (the identifier `CLC-945`, not the UUID)       |
+| `ticket set --project`                    | `projectId`                                         |
+| `ticket set --status`                     | `status`, mapped by the Role map above              |
+| `ticket set --priority`                   | `priority.value`; omit when `0` (`0` = no priority) |
+| `ticket set --url / --title`              | `url` / `title`                                     |
+| `ticket set --branch-hint`                | `gitBranchName`                                     |
+| `ticket set --labels`                     | `labels`, comma-joined                              |
+| `ticket set --updated-at`                 | `updatedAt`                                         |
+| `edge add --blocker <t> --blocked <m>`    | membership: `projectMilestone.id` per ticket        |
+| `edge set --node --direction blockers`    | `relations.blockedBy[].id`, comma-joined            |
+
+**Milestone order.** Sort milestones by `sortOrder` and chain adjacent pairs:
+`edge add --blocker <prev> --blocked <next>`.
+
+### Cursor
+
+The sync cursor is the latest `updatedAt` you fetched. A `scan_project`
+instruction hands it to you as `list_issues`' `updatedAt` filter ("updated
+after"); report it back with `dispatch refresh done --tracker linear
+--cursor <ts>`. Both a status change and a relation change bump `updatedAt`,
+so one delta sees both.

package/src/commands/CLAUDE.md

@@ -0,0 +1,12 @@
+# Commands
+
+One file per command, discovered automatically — no registry. The folder path is
+the invocation path: `foo/bar.mts` → `dispatch foo bar`, and a `foo.mts` beside a
+`foo/` directory makes that node both runnable and a namespace.
+
+A command subclasses `AbstractCommand` (`../lib/command`); that contract — the
+`Command` export, the `name` matching the file basename, `options`, `env`, `run` —
+lives there and is enforced by `discover`. `greet.mts` is the worked example.
+
+Skill-invoked commands must resolve inside the plugin directory, so keep
+everything a command needs under `plugins/dispatch`.