relayview-skills/docs/agents/queue.md

# Work Queue

How this repository decides what is next. The contract in one paragraph: exactly
one open issue labelled `type/roadmap` carries a `## Work Queue In Priority
Order` section; that order — with epic `## Child Issues In Priority Order`
sections beneath it — is repository priority. Dependency links gate execution;
status labels gate readiness. Neither ever overrides the written order. The
queue tree carries one invariant — every open issue except the roadmap itself
sits on exactly one priority list and blocks that parent — specified in full
in the gitea-issues `references/repository-queue.md` reference. Every open
direct child of the roadmap — epic or standalone entry — blocks the roadmap,
one edge per direct child and never edges to the whole backlog, so the Gitea
UI **Blocks** section links each level of the tree to the root.

Priority lists use `- [ ] #123 Title` and `- [x] #123 Title`. Physical order
sets priority; the checkbox is a progress display. A checked entry represents
a closed issue with `status/done`, including an epic accepted and closed
separately. `status/wontfix` and historical closed issues without
`status/done` stay unchecked. `queue inspect` reports disagreements; clicks
never change readiness, closure, or prerequisites. Convert numbered lists
through reviewed `checklist preview` and guarded `checklist apply`.

## Reading the queue

- **Health and explanations**: `queue inspect` — status counts, skipped
  entries, unqueued ready work, tree-invariant violations, structural
  anomalies.
- **Placement and reconciliation**: `queue roadmap` — targeted top-level order
  and current `content_version`, without dependency scans.
- **What is next**: `queue next` — read-only selection of the highest-priority
  executable leaf, with every higher-ranked skip explained.

Both are read-only. Inspecting never claims anything; claim separately with
`issue start --issue <number>`, which creates the `ISSUE-<number>` worktree and
moves the issue to `status/in-progress`.

## Changing the queue

Queue edits are explicit mutations, never side effects of other work:

- `queue init` — create the canonical roadmap if absent (idempotent).
- `queue insert --issue <n> --position <p> --expected-content-version <v>` —
  add a top-level epic, or a standalone issue with `--allow-standalone`.
  Inserting an open entry — epic or standalone — also links it as blocking
  the roadmap (reported separately from the body write).
- `queue reorder --issue <n> ... --expected-content-version <v>` — rewrite the
  top-level order, naming every current entry exactly once.
- `queue link-children preview` / `apply --confirm` — classify and repair the
  direct-child blocking edges to the roadmap (read-only preview; confirmed
  apply creates exactly the missing edges, streaming `[queue]` progress
  milestones with the terminal summary and exit status authoritative).

Mutations send the optimistic-locking `content_version` printed by `queue roadmap`.
On any ambiguous result, re-run `queue roadmap` and reconcile before retrying;
never blindly re-run a mutation.

## Adopting existing epics

Epics created before this contract may carry legacy child-order sections.
`epic migrate-children preview` inventories them read-only and classifies each
open epic; the owner confirms each proposed migration, and
`epic migrate-children apply --epic <n> --expected-content-version <v>`
rewrites one epic at a time under the queue contract's rules. Ambiguous epics
go back to the owner with their diagnostics. The gitea-issues
`references/repository-queue.md` reference documents the full contract.

## Moving to independent mode

In `legacy` mode, which this document describes, a native edge may mean
containment, navigation, or a prerequisite. A repository moves to
`independent` mode — edges mean prerequisites only — through a reviewed
migration, never a setup rerun: `migration preview --history --write-plan <file>` classifies every
edge read-only, the owner reviews the plan, `migration freeze` makes every
roadmap-driven helper fail closed, `migration apply --plan <file>` removes
only the projection edges the evidence proves and writes each placed
issue's `Parent:` line, `migration readiness` confirms nothing blocks, and a
reviewed commit of `relationship_mode = "independent"` activates it. The
gitea-issues `references/repository-queue.md` reference documents recovery
and rollback.

## Who enters the roadmap

Only two kinds of issue: a top-level delivery epic, and an explicitly
standalone actionable issue. Epic children never enter the roadmap — they stay
in the epic's child-priority list plus dependency links, under the
queue-tree invariant stated above.

## Default placement for new issues

Newly published work with no priority statement from the user enters at the
default position — the highest its dependencies allow, per the default rule
in the gitea-issues `references/create-and-organize.md` queue-placement
contract; an explicit statement from the user always wins. Creation and
placement remain two explicit, reconcilable operations either way, and
genuinely unresolved placement still publishes unqueued and stays visible
under "Unqueued ready work".

## After reviewed work merges

`pr cleanup` merges reviewed work and reconciles its issue. Continuation then
recommends exactly one follow-up, in order: newly unblocked dependents, the
current epic's next executable child, the roadmap's next executable leaf, or an
explicit blocked/empty result. Recommendations only — starting the next issue
needs its own authorization.