The review-queue/v1 JSON document

This text is LLM generated.

review-queue --json prints one JSON object describing what is waiting on cgwalters. The same code ranks and filters this output and the app's queue, so the two always agree. (For contributors: the types are QueueJson and EntryJson in src/cli/export.ts.)

Compatibility: within review-queue/v1, fields are only added. Removing or renaming a field, or changing its meaning or type, bumps the schema to review-queue/v2. Consumers should check schema and ignore fields they don't know. Fields marked optional are left out when they don't apply (jq's .field then reads null).

Top level

Field Type Meaning
schema "review-queue/v1" This document's schema.
generatedAt string When it was read (ISO 8601, UTC).
filter string The filter applied, as the app's token: all, composefs (all upstream work: every org but cgwalters-bot and cgwalters-forge), infra (those two orgs), org:NAME, org:none, optionally +P0..+P3 or +none.
counts.entries number Top-level entries.
counts.rows number Entries plus their nested asks.
counts.open number Rows that need him: those whose action isn't wait or see-asks (a parent whose work is its nested asks).
entries array Ranked entries (below).
warnings string[] Data that couldn't be read (say, the forge search); the queue may then be incomplete.

Direct GitHub PR searches reject missing/non-array items, GitHub's incomplete_results, and results beyond the five-page (500-item) read bound. The affected PR list is unavailable, not known empty; the queue retains its board entries and reports the failed read in warnings. No extra requests or automatic retries are made beyond that bound. Service-backed reads are unchanged.

Entries

Entries use the app's order: priority (P0 first, no priority last), then oldest first, except that answered asks and then PRs waiting on the bot come last. An ask about an item in the queue is nested in that item's asks, not listed twice.

Field Type Meaning
key string Stable id: pr:owner/repo#n or item:PVTI_... (the board item's node id, as bot-board names it).
kind string pr (a forge draft PR, or another of the bot's PRs that waits on him or on the bot), question, review, chore (the bot's asks, tracker issues), or item (another board item).
title string Its title.
where string owner/repo#n; draft item for a board draft; item for a board item with no issue or PR the API shows (say, redacted).
priority string or null The board's Priority. A forge PR takes its board item's.
rankPriority string or null What it ranks by: its own, or a more urgent open nested ask's.
org string or null The organization it targets, lowercase: the board's Org field, else a target:<org> label, else the issue's owner; a forge PR counts as its upstream.
since string or null When it started waiting (ISO 8601).
settled boolean He answered it, or the bot closed it: waiting on the bot.
bug boolean Needs human, but the bot asked nothing about it.
url string or null The issue or PR on github.com.
appUrl string The entry in the control app, where it can be acted on.
verdict object, optional PRs: state, his latest review against the head (none when he hasn't reviewed, approved, approved-older, changes-requested, changes-requested-older, promoted), a label, and the review's url. A forge PR he approved at its head stays listed until he sends /promote; wait, not the state, says whose turn it is.
wait object, optional PRs: whose turn it is beyond the verdict. onBot: he requested changes and the bot hasn't pushed or replied since, so its action is wait (not open), listed last. reasons: what he is asked to do, any of review-requested, updated (the bot responded to his change request), resign (approve the head so the bot can add his DCO sign-off), rerun (a required check failed).
blocks string, optional For a top-level ask: the item it blocks, which isn't in the queue.
why string, optional The board item's Why.
gists string[], optional Gists to read, on a Draft item.
question object, optional An open question: ask (the Q: line), options (letter, text, recommended), recommendation.
ask string, optional A review or chore ask's Ask: line.
action object The suggested action: verb, a one-line summary, optionally a reason, and targets, the URLs to act on when the ask names them (the PRs a review ask names, the workflow runs a chore asks to rerun).
asks array The asks nested under it, as entries.

action.verb is one of:

Examples

# What needs me in the composefs org itself, most urgent first
review-queue --json --filter org:composefs | jq -r '.entries[] | "\(.rankPriority) \(.where) \(.action.verb)"'
# Quick wins: reruns and gists to read, anywhere in the queue
review-queue --json | jq '[.entries[] | ., .asks[] | select(.action.verb == "rerun" or .action.verb == "read")]'
# Open questions with the bot's recommendation
review-queue --json | jq -r '.entries[] | ., .asks[] | select(.question) | "\(.url)\n  \(.question.ask)\n  recommended: \(.question.recommendation // "none")"'