Canonical owner for the GitHub Projects V2 queue board contract: board shape, the Status
column vocabulary, and Next Up pickup rules. It also carries the one-time
Setup guide and the day-to-day Usage guide for the queue helpers.
When a dev-loop operator opts into the GitHub Projects queue path, queue helpers read queue ordering from a project board and write status transitions back, relying on deterministic field/column names and failing safely when the board is absent or misconfigured.
The queue board MUST be linked to the target repository via linkProjectV2ToRepository.
User-level (unlinked) projects are not supported for queue ordering and must be migrated.
Board state is an optional scheduling input; it does not replace GitHub issue/PR state as the source of truth. This contract introduces no new local queue file (see Relationship to queue mode).
GitHub Projects is optional. Without a board, queue helpers fall back to positional argument ordering. Setting up a board is a one-time operator action, not a startup requirement.
Tooling never mutates project/field structure without explicit operator invocation of the
bootstrap wrapper (node <dev-loops-package-root>/cli/index.mjs queue ensure; node <dev-loops-package-root>/cli/index.mjs project ensure is a back-compat
alias). Runtime queue operations only read/write item position and Status field values.
Every operator-facing scripts/projects/* queue command MUST resolve the board from
.devloops (tracker.board; number or title) when --project is omitted; an explicit --project overrides. The structural halves
(the applyDevloopsBoard call and projectTitle delegation forwarding) are enforced by
test/contracts/queue-board-resolution-contract.test.mjs, which inspects commands that read
--project/args.project and exempts the _resolve-project.mjs helper itself and the board
bootstrap ensure-queue-board.mjs. Omitted-flag and override behaviors are covered
behaviorally where suites exist (resolve-active-board-item, list-queue-items); the
remaining siblings are covered structurally only.
Tooling resolves the owner (user or organization) from the repository slug
(--repo <owner/name>, first component) and looks up the project among that owner's
Projects V2 instances. The recommended title is "Dev Loop Queue"; GitHub assigns the
project number on creation.
Project lookup is by exact title match against the configured title, over a paginated
projectsV2 listing. If no project with the configured title exists, tooling fails closed;
it does not create a project silently.
The board must have a Status field of type single-select. It is the only required
field; all queue-state read/write operations key off Status. Tooling identifies the field by
name ("Status") and uses its field ID and option IDs in item mutations.
The Status field MUST contain these four columns; this is the single canonical definition of the board-column vocabulary — other queue docs reference it by ID instead of restating it. Tooling keys off the option names:
| Column | Meaning |
|---|---|
| Backlog | Unprioritized intake. Default Status for newly added items. Position within Backlog carries no scheduling meaning — the driver never picks from Backlog. Promoting an item to Next Up is the deliberate prioritization step. |
| Next Up | The normative pickup order. The driver picks only from this column, by POSITION ascending. |
| In Progress | Currently running through the dev-loop. |
| Done | Completed (merged or explicitly closed). |
Columns are case-sensitive exact matches. "backlog", "BACKLOG", or "Backlog " do not
match. The bootstrap wrapper creates these four columns. Operators may add additional
Status options.
Operators MUST NOT remove or rename the four conventional columns — tooling fails closed
when expected columns are missing.
The authorized --repair-rename path below restores recognized equivalents to the canonical
names; it does not rename a canonical column away.
Queue ordering is the GitHub Projects V2 item POSITION (ascending) within a
Status-filtered query (items with orderBy: { field: POSITION, direction: ASC } and a
Status filterBy). The operator sets it by drag-drop in the board UI or with the reorder
helper (updateProjectV2ItemPosition); tooling reads it and does not enforce its own order.
Ordering is column-scoped. --limit N takes the first N items of the ordered result.
The whole-board ProjectV2.items listing can lag behind GitHub and leave out newly added
items for hours, so list-queue-items and the reorder before/after snapshot can miss them.
Tooling does not work around this. Move and reorder do not depend on the listing. A number
ref is looked up from the issue side (issueOrPullRequest(number).projectItems, filtered to
the configured project and to unarchived items). An item node ID ref is looked up with
node(id) and must belong to the configured project and repository. A lookup miss, a
project mismatch, a repository mismatch, or an archived item fails closed with
ITEM_NOT_FOUND (exit 3). A number lookup that finds the item on the configured project
succeeds even if the response also carries errors for other projects. Otherwise, any
GraphQL error other than NOT_FOUND fails as GRAPHQL_ERROR (exit 2).
Tooling never silently assumes board state is correct. Every operation that depends on the board validates preconditions first:
| Situation | Behavior | Exit code |
|---|---|---|
| No board configured (not opted in) | Fall back to positional ordering; no board mutations | N/A (normal) |
| Board not found by title | Operation fails; no fallback to creation | 3 |
| Board exists but Status field missing | Operation fails; manual reconciliation needed | 3 |
| Board exists but Status field missing expected column | Operation fails; manual reconciliation needed | 3 |
| GitHub API returns error | Operation fails; queue continues with next item | 2 |
| Item not found on board (move/add operation) | Operation fails; no silent creation | 3 |
The node <dev-loops-package-root>/cli/index.mjs queue ensure bootstrap wrapper has relaxed fail-closed behavior: it
creates a missing project and/or Status field with conventional columns. It MUST be
the only tool that mutates project structure; runtime queue helpers (list, move, add,
reorder) MUST NOT create or modify project/field structure. It is safe to re-run: when
the board and Status field already exist, it exits clean with the existing project details.
When tooling fails closed, it emits a structured JSON error on stderr in one of two shapes:
- Domain error (any error thrown from the command's
main, including argument validation such asINVALID_REPO):{ ok, error, code }, and each helper'sclassifyExitCodemaps thecodeto the exit status per Error format. - Argument-parse error (exit 1, the
parseCliArgspath): the standardformatCliErrorshape{ ok, error }with an optional one-linehint(e.g."run with --help for usage") and nocode. AnINVALID_*validation error frommainalso exits 1 but uses the domain envelope.
When the Status field exists but has non-standard columns, node <dev-loops-package-root>/cli/index.mjs queue ensure calls
updateProjectV2Field to add missing standard columns (Backlog, Next Up, In Progress,
Done) instead of throwing. This covers a subset of standard columns, entirely
non-standard columns (e.g. Todo/Doing/Done), and a mix. Default auto-repair does NOT
remove or rename existing columns. Column removal/reordering remains a manual operation in
the GitHub Projects UI.
The bootstrap wrapper recognizes a bounded set of semantically equivalent Status column names, for example Ready for Next Up and Doing for In Progress.
Without an explicit repair flag, the wrapper:
- Reports detected rename candidates in
repairs.renameCandidates. - Does not rename existing columns.
- Does not add a standard column that would duplicate an equivalent column already on the board.
- Still adds any standard columns that are missing and not covered by an equivalent.
With --repair-rename (node <dev-loops-package-root>/cli/index.mjs queue ensure --repo <owner/name> --repair-rename), after
the operator reviews the reported candidates, the wrapper:
- Renames recognized equivalent columns to the canonical standard names.
- Adds any remaining missing standard columns.
- Leaves unrecognized columns and item assignments untouched, and never removes a column.
When multiple existing columns map to the same standard column, the wrapper MUST report an irreconcilable conflict in repairs.conflicts and MUST NOT perform any mutation. The operator must resolve the ambiguity manually.
When a queue board is configured, the queue driver may optionally write bounded Status transitions back to the board. This is opt-in and fail-open: if the board is absent, misconfigured, or the GitHub API fails, the queue run continues and reports the sync problem in the result.
| Queue event | Default target Status | Configurable override | Notes |
|---|---|---|---|
Item picked up by runQueue |
In Progress |
none | Fired after the entry transitions to running. |
runEntry succeeds |
Done |
none | Fired when the entry reaches done. |
runEntry throws (any failure) |
Backlog |
queue.nonSuccessStatus |
Fired before the entry is marked failed/blocked. |
Board integration is active only when .devloops at repo root identifies a board
(tracker.board, see Configuration shape). queue.nonSuccessStatus
optionally overrides the non-success column.
The queue driver returns a boardSync array on each entry result, one element per attempted
transition: { "ok": true, "skipped": false, "result": { "ok": true, "item": { "newColumn": "In Progress" } } }.
move-queue-item.mjs owns the inner result shape. When the board is not configured or the
sync fails in fail-open mode, skipped is true and a reason explains why.
When a queue board is configured, the conductor MUST keep the board synchronized with actual issue/PR state continuously — reconciling at each lifecycle transition and through periodic reconciliation — instead of waiting for a human to notice drift. This is the operating conductor's obligation, distinct from the queue driver's opt-in, fail-open automated Status writes in Lifecycle status transitions; it is normative for any conductor working the queue, including headless and cross-repository runs. Each trigger below has a required board effect:
| Trigger | Required board effect |
|---|---|
| File / enqueue an item for the queue | The item MUST be placed on a real column via add-queue-item.mjs — --next-up when it is refined and queued to work, --column Backlog when it is tracked but not yet prioritized (or not yet refined) — and MUST NOT be left off the board. Promotion into Next Up remains subject to QUEUE-ENQUEUE-REFINEMENT-GATE. |
| Dispatch a runner on an item | The conductor MUST immediately set the item to In Progress via move-queue-item.mjs --to-column "In Progress" and MUST re-read the item to confirm the move landed rather than assuming the runner did it; an in-flight item MUST NOT stay outside In Progress. |
| Merge or close the item | The item MUST be in Done. |
| Reprioritize or block the item | The item's column MUST be updated to match: reprioritized items move between Backlog and Next Up, and a blocked item MUST be moved back to Backlog. The conductor MUST NOT promote an unrefined issue into Next Up, upholding the refinement bar of QUEUE-ENQUEUE-REFINEMENT-GATE. |
| Periodic reconcile | The conductor MUST proactively enumerate board items with list-queue-items.mjs, compare each against the underlying issue/PR state, and correct any mismatch without being asked. |
The conductor MUST perform every board read and column mutation through the canonical projects scripts (add-queue-item.mjs, move-queue-item.mjs, list-queue-items.mjs); it MUST NOT hand-roll gh api graphql calls to synchronize the board. The column vocabulary is owned by QUEUE-COLUMN-CANONICAL, and the structural-mutation boundary by QUEUE-BOOTSTRAP-ONLY-MUTATOR.
When a queue board is configured, Next Up is the normative, fail-closed pickup source — not a soft hint. The driver MUST pick only from the Next Up column, by POSITION ascending, and MUST NOT auto-pull from Backlog or fall back to non-board local queue order under any circumstance.
node <dev-loops-package-root>/cli/index.mjs queue runfirst reconciles the board'sNext Upitems into.pi/dev-loop-queue.json(appending a queued entry for anyNext Upissue not already present). The driver then queriesNext Upby POSITION ascending before the first dispatch, and dispatches only those items, in that order.- An entry present in the local queue but absent from
Next Upis never auto-picked. Working an item requires moving it toNext Upfirst. - **Empty `Next Up` (successful query, zero items) → fail closed.** The driver **MUST** idle/stop with an explicit, machine-readable outcome (`reason: "next-up-empty"`, message `"queue empty — prioritize Backlog items into Next Up"`) and **MUST NOT** fall back to Backlog or local order.
- **Board-query error (API/unreachable/unresolvable project) → surface and stop.** The driver **MUST** surface the error and stop (`reason: "board-query-error"`) and **MUST NOT** fall back to Backlog or local order. This is deliberately distinct from an empty `Next Up`: an outage never silently drains Backlog.
- **`Next Up` target with no local queue entry → fail closed.** When the resolved `Next Up` order contains one or more targets absent from `.pi/dev-loop-queue.json` (membership reconcile not run/persisted, or the board changed between reconcile and this query), the driver **MUST** stop with an actionable outcome (`reason: "next-up-target-missing-locally"`, the offending numbers in `missingTargets`, message `"Next Up contains items with no local queue entry — run membership reconcile / re-add them"`) rather than silently filtering them out and returning an empty idle, and **MUST NOT** pick from Backlog.
- **An issue MUST carry the refinement matrix before it enters `Next Up`.** When an enqueue resolves the target to the pickup column (`queue add --next-up`, or `--column` naming it), it gates on the check the draft gate uses: `ARTIFACT-TRACKER-ISSUE-REFINEMENT-FLOOR` in [Artifact Authority Contract](artifact-authority-contract.md) (`detectIssueRefinementArtifact`). A linked refinement doc (`tmp/refinement/*.md`) remains a complete artifact on its own. A checklist-only or matrix-missing issue blocks with `missing_ac_dod_matrix`, an empty/identifier-only matrix with `malformed_ac_dod_matrix`, and a matrix without an explicit Non-goals section with `missing_explicit_non_goals`, each with guidance naming the missing/invalid artifact. A complete artifact whose spec changed after the latest grill results comment also blocks (or diverts under `--auto`) with `spec_changed_since_grill`, per `GRILL-SUBLOOP-SPEC-CHANGED-SINCE-GRILL` in `docs/refinement-grill-state-graph.md`. The gate is issue-only: a PR targeting the pickup column is validated at the draft gate instead. Interactive enqueue **MUST** fail closed with `MISSING_REFINEMENT_ARTIFACT`, naming the missing sections. Headless (`--auto`) enqueue **MUST NOT** fail the run; it diverts the issue to the non-pickup park column (`nonSuccessBoardColumn`, which **MUST** differ from the pickup column) and records the diversion reason instead. The enqueue script enforces the gate and parks; the orchestration layer grills a parked issue (refiner / `loop-grill --auto`) and re-enqueues once refined. The draft gate remains the unconditional backstop for other enqueue paths.
Bare /loop-continue (in the dev-loops repo) / /dev-loops:loop-continue (in a consumer install) is the operator-facing pickup path; it MUST enforce the same Next Up normative source as the queue driver and MUST NOT pick from Backlog. It resolves a single continue target via scripts/projects/resolve-active-board-item.mjs:
- Exactly one
In Progressitem → continue it (source: "in-progress"). - Multiple
In Progressitems → fail closed (never guesses); the operator must pass an explicit/dev-loops:loop-continue #N(or/loop-continue #Nin the dev-loops repo itself). - Zero
In Progressitems → fall through to the HEAD ofNext Upby POSITION ascending (source: "next-up").- Empty
Next Up→ fail closed (idle) with the canonical"queue empty — prioritize Backlog items into Next Up". No Backlog pickup. Next Upquery error → surface and stop (fail closed). No fallback, no guessing.
- Empty
The live path never picks more than one target. It hands continue dev loop on #<number> to the dev-loop skill.
- A single-issue/PR run never reaches this gating. A specific
--issue/--prtarget goes through the dev-loop routing path, not the queue driver, soNext Upgating does not apply to it. The queue driver has no explicit-target flag;Next Upgating is unconditional for every item the driver picks. - No board configured. The driver keeps its local (topological/insertion) order from
.pi/dev-loop-queue.json, and the legacy "Queue is empty" message applies when that file has no pending entries.
The normative Next Up rule above currently assumes the default Next Up display name. Honoring a queue.statusColumns.next_up override (and its siblings in_progress/done) across the pickup-ordering and projects-script layer (resolveNextUpOrder, queue add, queue list, queue move) is not yet implemented — those layers key off the literal Next Up/In Progress/Done names even though board-sync respects statusColumns. Renaming the logical Next Up column via statusColumns is therefore not fully supported by this contract yet; that work is tracked in #1098.
With a configured board, local queue entries [#1, #2, #3], an entry #4 that is not in Next Up, and board Next Up order [#3, #1], the driver dispatches #3 then #1 and nothing else. If Next Up is empty, the driver idles with "queue empty — prioritize Backlog items into Next Up" and never touches Backlog.
Queue board configuration lives under .devloops at repo root. All keys are optional;
the queue path works without a board.
tracker:
board:
# GitHub Projects V2 project number for direct lookup (overrides title-based discovery).
number: 1
# Board title for Projects V2 lookup (used when number is not set).
title: "Dev Loop Queue"
queue:
# Maximum parallel entries the queue may process concurrently.
maxParallel: 3
# Maximum bug issues the queue driver may auto-file in one run.
maxAutoFiledIssues: 10
# Maximum retry attempts per entry for recoverable failures.
reDispatchMaxRetries: 1
# Optional fallback column for non-success outcomes.
nonSuccessStatus: Backlogtracker.boardis the only board key and the opt-in signal. The formerqueue-section board alias was removed at the v1.0.0 cut (ADR 0017). With nonumberand notitle, the Projects path is inactive: positional ordering applies and no board transitions run.titlelooks up the project by exact title under the repo owner.numberlooks it up directly and takes precedence when both are set.- When a board is set but the project does not exist, queue operations that depend on board ordering fail closed; a missing board is not equivalent to "not opted in".
- Board settings are read only from
.devloopsat the repo root. The shipped defaults (packages/core/src/config/extension-defaults.yaml) and the repo-local.pi/dev-loop/defaults.*layer deliberately omit these keys.
Helpers consume these minimal GraphQL operations:
| Operation | Purpose | Used by |
|---|---|---|
projectsV2 query (user/org) |
List projects by owner, find by title | bootstrap, list, move, add, reorder |
createProjectV2 mutation |
Create project board | bootstrap only |
createProjectV2Field mutation |
Create Status field with columns | bootstrap only |
linkProjectV2ToRepository mutation |
Link a project board to a repository | bootstrap only |
updateProjectV2Field mutation |
Add columns to an existing Status field | bootstrap auto-repair only |
fields query (with ProjectV2SingleSelectField) |
Read Status field + options | bootstrap, list, move, add |
items query (with orderBy + filterBy) |
List items in a column by POSITION | list, reorder (before/after snapshot only) |
issueOrPullRequest query (with projectItems) |
Find an item by issue/PR number | move, reorder |
node query (as ProjectV2Item) |
Find an item by item node ID and verify its project and repository | move, reorder |
updateProjectV2ItemFieldValue mutation |
Set Status on an item (move between columns) | move |
addProjectV2ItemById mutation |
Add an existing issue/PR to the project | add |
updateProjectV2ItemPosition mutation |
Reorder an item within/between columns | reorder |
This contract explicitly does not define:
- Full Kanban automation — the queue helpers only read ordering and set Status; they do not react to Status changes.
- Local persistence replacement — no new local queue file.
- Bi-directional sync — the queue tooling runs no background process that mirrors local state to board state or the reverse. Continuous reconciliation is the conductor's responsibility (QUEUE-BOARD-SYNC-CONTINUOUS).
- Framework/library abstraction — all helpers are thin wrappers around
gh api graphql.
The queue-mode SPEC (docs/specs/queue-mode/SPEC.md) uses .pi/dev-loop-queue.json for
durable entry lifecycle tracking. This contract adds an optional Projects-board scheduling
input on top of it. When no board is configured, queue ordering falls back to positional
arguments as the SPEC describes.
One-time setup for the board that dev-loops queue helpers read and write. When configured,
the board is authoritative for queue membership and ordering, not just status (see
Queue pickup ordering). Add work through the board, not by
hand-editing .pi/dev-loop-queue.json.
Run the idempotent bootstrap wrapper:
node <dev-loops-package-root>/cli/index.mjs queue ensure --repo mfittko/dev-loopsThis creates a project named "Dev Loop Queue" (default) under the mfittko user:
{
"ok": true,
"project": {
"id": "PVT_kwDO...",
"number": 1,
"title": "Dev Loop Queue",
"url": "https://github.com/users/mfittko/projects/1",
"statusFieldId": "PVTSSF_lADO..."
}
}Use --title "My Queue" for a custom title. Record the board in .devloops
(tracker.board number or title) so later helper invocations resolve it without
--project (QUEUE-BOARD-DEVLOOPS-RESOLUTION).
Open the project URL from the wrapper output and confirm the Status field has the four
canonical columns (QUEUE-COLUMN-CANONICAL, Conventional columns).
To create the board manually via GitHub UI:
- Go to your GitHub profile → Projects tab
- Click New project
- Select Board layout
- Name it "Dev Loop Queue"
- Add a Status field (type: Single select)
- Add options:
Backlog,Next Up,In Progress,Done - Record the project number from the URL:
https://github.com/users/<owner>/projects/<number>
After manual creation, the wrapper's idempotent re-run detects the existing board and Status field and emits the same machine-readable JSON payload.
The board Status column follows the dev-loop's own state machine. A pure mapping
(boardColumnForLoopState(loopState, mapping) in
packages/core/src/loop/queue-board-sync.mjs) resolves each loop/lifecycle state
to a logical column, then to a configured display name.
| Loop / lifecycle state | Logical column | Default display name |
|---|---|---|
issue_opened, issue_intake, refinement, no_pr |
next_up |
Next Up |
pr_draft, implementation, local_implementation_active, pr_ready_no_feedback, waiting_for_copilot_review, ready_to_rerequest_review, unresolved_feedback_present, already_fixed_needs_reply_resolve, waiting_for_ci, blocked_needs_user_decision, other in-flight states |
in_progress |
In Progress |
final_approval_ready, pre_approval_gate |
ready_for_review |
In Progress (unless overridden, see below) |
merged, issue_closed, done, merge |
done |
Done |
| any unmapped state | in_progress |
In Progress (safe default) |
The mapping is stateless: it depends only on the current state, so a reverted state
moves the column backward (a reopened merged PR maps back from Done to In Progress).
An open draft PR (pr_draft) stays In Progress; the item returns to Next Up only
when it reverts to a pre-PR state (no_pr). No "furthest reached" column is persisted.
Both overrides live under the opt-in queue section in .devloops; board sync itself is
enabled by a configured board (tracker.board). When no board is configured or sync is
disabled, status sync is a no-op with no GitHub API calls and no board mutations.
queue.statusColumns renames the display name of a logical column:
tracker:
board:
number: 7
queue:
statusColumns:
next_up: "Todo"
in_progress: "Doing"
ready_for_review: "Ready for Review" # opt-in column; otherwise final_approval_ready stays "In Progress"
done: "Shipped"queue.stateColumnMap remaps an individual loop state to a different logical
column (rarely needed):
tracker:
board:
number: 7
queue:
stateColumnMap:
blocked_needs_user_decision: next_up- Board not configured / disabled — sync returns
{ ok: true, skipped: true }and performs no GitHub calls (AC2/AC6). - Item not on the board — sync is a logged no-op (
{ ok: true, skipped: true }), never an error, so a missing board item can never break the loop (AC4).
node <dev-loops-package-root>/cli/index.mjs queue reorder wraps the updateProjectV2ItemPosition mutation. In
addition to the flag form (--item [--after]), it exposes three
subcommands. A <ref> is an issue/PR number or a project item node ID,
and every form works for both issues and PRs.
# Move issue/PR #630 to the top of its current Status column
node <dev-loops-package-root>/cli/index.mjs queue reorder move-to-top 630 --repo mfittko/dev-loops --project 1
# Move #630 immediately after #625
node <dev-loops-package-root>/cli/index.mjs queue reorder move-after 630 625 --repo mfittko/dev-loops --project 1
# Set an explicit order: 103 first, then 101, then 102
node <dev-loops-package-root>/cli/index.mjs queue reorder order 103 101 102 --repo mfittko/dev-loops --project 1The subcommand forms emit JSON with the resolved item, after_ref, and the column order
before and after the change. Each snapshot entry carries itemId, issueNumber,
prNumber (one of the latter two is null), and status. order returns a moves array
(one entry per chained position mutation) plus the same before/after snapshots.
orderis not atomic. It applies N sequentialupdateProjectV2ItemPositionmutations with no rollback. If it fails partway, the board is left partially reordered and the thrown error reports how many moves completed (for exampleorder partially applied: 1 of 3 moves completed). Re-running the sameorder <ref1> <ref2> ...command is idempotent and is the supported recovery path.
Add --dry-run to any form to print the intended GraphQL mutation(s), including the chained
mutations for order, without executing them. The output is { ok, dryRun: true, mutations, before }; the flag form returns the same shape with a single mutation.
A ref that does not resolve to an item in the target Project fails closed with
ITEM_NOT_FOUND (exit code 3).
node <dev-loops-package-root>/cli/index.mjs queue archive-done archives items (via archiveProjectV2Item) whose issue or PR
has been closed for at least the given duration, regardless of their Status column. It is
operator-triggered (no webhooks) and scoped to the single repo passed via --repo.
# Archive items whose issue/PR closed more than 30 days ago (default)
node <dev-loops-package-root>/cli/index.mjs queue archive-done --repo mfittko/dev-loops --project 1
# Custom threshold (units: h = hours, d = days, w = weeks)
node <dev-loops-package-root>/cli/index.mjs queue archive-done --repo mfittko/dev-loops --project 1 --older-than 7d
# Preview without mutating
node <dev-loops-package-root>/cli/index.mjs queue archive-done --repo mfittko/dev-loops --project 1 --dry-runThe output reports ok, olderThan, scanned (the integer count of all board items of
the repo, including open, closed and archived), archivable (the integer count of the
closed-duration subset), and archived (one entry per archived item; each entry carries
itemId, issueNumber, prNumber, closedAt). A --dry-run result carries
dryRun: true and mutations (the planned archive mutations) and has no archived
field. Open items (even in the Done column) and already-archived items
are never touched.
Day-to-day guide for the queue helpers. Queue management lives under
node <dev-loops-package-root>/cli/index.mjs queue <subcommand> (node <dev-loops-package-root>/cli/index.mjs queue --help); node <dev-loops-package-root>/cli/index.mjs project <subcommand> is
a back-compat alias. Helpers emit machine-readable JSON on stdout and structured errors on
stderr, and accept --help. The board resolves from .devloops per
QUEUE-BOARD-DEVLOOPS-RESOLUTION; --project <number|id> overrides it.
# List all items in a project
node <dev-loops-package-root>/cli/index.mjs queue list --repo mfittko/dev-loops --project 1
# List only items in "Next Up" column
node <dev-loops-package-root>/cli/index.mjs queue list --repo mfittko/dev-loops --project 1 --column "Next Up"
# Limit to top 5 items
node <dev-loops-package-root>/cli/index.mjs queue list --repo mfittko/dev-loops --project 1 --limit 5
# Human-readable board triage: aligned number/status/title columns
# (JSON stays the default; --table composes with --column/--limit)
node <dev-loops-package-root>/cli/index.mjs queue list --repo mfittko/dev-loops --project 1 --table# Add issue #42 to the Backlog column (default = unprioritized intake).
# Backlog items are NEVER auto-picked; promote to Next Up to schedule them.
node <dev-loops-package-root>/cli/index.mjs queue add --repo mfittko/dev-loops --project 1 --item 42
# Enqueue for immediate work: land directly in Next Up (the normative pickup
# queue). --next-up is sugar for --column "Next Up".
node <dev-loops-package-root>/cli/index.mjs queue add --repo mfittko/dev-loops --project 1 --item 42 --next-up
# Add issue #42 to a specific column (--status is a back-compat alias for --column)
node <dev-loops-package-root>/cli/index.mjs queue add --repo mfittko/dev-loops --project 1 --item 42 --column "Next Up"# Move issue #42 from its current column to In Progress
node <dev-loops-package-root>/cli/index.mjs queue move --repo mfittko/dev-loops --project 1 --item 42 --to-column "In Progress"
# Move a project item by its node ID
node <dev-loops-package-root>/cli/index.mjs queue move --repo mfittko/dev-loops --project 1 --item "PVTI_..." --to-column "Done"# Move issue #42 to the top of the column
node <dev-loops-package-root>/cli/index.mjs queue reorder --repo mfittko/dev-loops --project 1 --item 42
# Move issue #42 after issue #17
node <dev-loops-package-root>/cli/index.mjs queue reorder --repo mfittko/dev-loops --project 1 --item 42 --after 17
# Reorder by project item node IDs
node <dev-loops-package-root>/cli/index.mjs queue reorder --repo mfittko/dev-loops --project 1 --item "PVTI_abc" --after "PVTI_xyz"On failure, helpers emit structured JSON on stderr:
{"ok": false, "error": "Item #999 not found in project \"<title>\" for repo \"owner/name\"", "code": "ITEM_NOT_FOUND"}Exit codes (from each helper's classifyExitCode):
1— usage or argument error (INVALID_*)2— GitHub API error (the default for an unmappedcode)3— project, field, column, or item not found (*_NOT_FOUND)4— refinement gate: an enqueue into the pickup column with no AC/DoD matrix (MISSING_REFINEMENT_ARTIFACT,add/moveonly — see QUEUE-ENQUEUE-REFINEMENT-GATE)
An issue-less lightweight PR (resolve-dev-loop-startup.mjs --lightweight alone, per
ARTIFACT-LIGHTWEIGHT-PLAN-FILE-EXCLUSIVE)
has no tracker issue, so it appears on the board as a PR item only.
scripts/github/create-pr.mjs --lightweight owns enqueuing that PR item on creation
(In Progress, on a board-configured repo); a tracker-backed PR never triggers this call.
The queue runner is a deterministic adapter over the board, not the orchestration
harness. It moves an item to Done (and marks the entry done) only as a reflection of a
real terminal signal supplied by an orchestrator (e.g. the item's linked PR merged). When
no orchestrator is wired into the current harness, node <dev-loops-package-root>/cli/index.mjs queue run is a no-op: it
leaves every board column unchanged and reports reason: "no-orchestrator" (#913).
- the queue-mode SPEC (
docs/specs/queue-mode/SPEC.md) — full queue mode specification - Issue #625 — parent epic