docs(queue): enforce milestone-aware picker ranking #348

Merged
timothy merged 2 commits from codex/queue-picker-claim-comments into main 2026-07-14 08:03:47 +02:00
+19 -7
View File
@@ -60,7 +60,8 @@ enforcement is tracked in `timothy/server-management#592`; the wider Claude-hook
**When the user has not named an issue, queue selection is mechanical fast/small work, never orchestrator
work.** Dispatch exactly one selector on the cheapest suitable model at low or minimal effort. Give it only
#237's body, last ~6 comments, live issue/milestone/label state, and the reviewer-repo candidate list; it
#237's body, last ~6 comments, every OPEN milestone and its OPEN issues, OPEN `review`-labeled
issues, and the reviewer-repo candidate list plus each candidate's claim/deliverable comments; it
returns a ranked shortlist of at most three issue IDs with one-line rationales and live-state evidence. The
orchestrator receives only that compact packet, then performs a focused live recheck of the winner before
claiming. Do not load implementation docs or issue bodies into the selector. If the client cannot route a
@@ -100,17 +101,23 @@ Then work the queue:
any inline marker or a prior comment's "next": the **current gate = the lowest-numbered OPEN arc
item in #237's arc list**; its open children are the gate cluster (query them by the `review`
label). Cross-check every arc / "recommended" item's real open/closed state (issue **and**
milestone) before trusting it — do NOT hardcode which issue is the frontier; read it. ALSO list
milestone) before trusting it — do NOT hardcode which issue is the frontier; read it. Candidate
discovery MUST enumerate every OPEN issue in every OPEN milestone plus OPEN `review`-labeled
issues; do not limit the pool to tracker prose or recent comments. Treat an umbrella/epic as a
container rather than a pickup when #237 names its eligible children. ALSO list
open `ersatztv`-labeled issues in **timothy/adversarial-reviewer** — unclaimed audits there are
pickup candidates too (read-only, parallel-safe; see the tracker's "Pending adversarial reviews"
section). If the Gitea MCP is down, hit the REST API directly (use credentials supplied by the
environment or your global client instructions; never print them):
section). Reviewer audits are claimed by comment: a claim remains active until a later comment
explicitly releases or abandons it, and a posted audit/review deliverable is completed work even
when its issue stays open for implementer replies. If the Gitea MCP is down, hit the REST API
directly (use credentials supplied by the environment or your global client instructions; never
print them):
`curl -u <user>:<pass> http://192.168.1.95:3000/api/v1/repos/timothy/ersatztv/issues/237`.
**The authoritative pickup + ranking protocol lives in #237's "Session protocol" section — this is a summary; if the two ever disagree, #237 wins.**
2. The selector picks the highest-ranked OPEN, un-`in-progress` candidate and returns at most two
fallbacks. **Rank by labels, not just arc position** (labels are live state; prose is not):
(1) arc order in #237, then
(2) **gate vs backlog** — an item marked gate by the `review` label OR membership in an open gate
(2) **milestone/review tier vs backlog** — an item with the `review` label OR membership in an OPEN
milestone outranks anything unmilestoned; then (3) **`priority:`** label — `high` > `medium` >
`low` within a tier. Pick order across the three pools: the **arc frontier** (lowest-numbered open
arc item) first; an unclaimed Blocker/High **priority-pickup** (`review` + `priority: high`, e.g.
@@ -120,9 +127,14 @@ Then work the queue:
Do not reread the full tracker or comments for selection. If the prose says "recommended next / now
unblocked" but the issue (or its milestone) is already CLOSED, it is done — skip it and fix the
stale line in your session comment. Prose lags live state; live state wins; milestone + `priority:`
labels decide gate-vs-backlog, not the prose. (This mirrors #237's Session-protocol ranking — #237 is canonical.)
labels decide gate-vs-backlog, not the prose. For an equal milestone/review tier and equal priority,
preserve #237's explicit eligible order, then use lowest issue number as the deterministic fallback;
never invent a fix-size, recency, or perceived-relevance tiebreaker. (This mirrors #237's
Session-protocol ranking — #237 is canonical.)
3. **Claim it**: add the `in-progress` label + a "claiming" comment on the issue(s);
reviewer-repo audits are claimed by comment only.
reviewer-repo audits are claimed by comment only. Treat that claim as live until a later comment
explicitly releases or abandons it, and exclude audits with a posted deliverable even while the
issue remains open for implementer replies.
4. Read the issue bodies (they carry the task context/evidence) and work the item under the
HARD CONSTRAINTS below.
5. Finish by following the session-end protocol in #237: run the **H12 qualification audit**