docs(queue): exclude parked selector candidates #372

Merged
timothy merged 1 commits from codex/237-selector-eligibility into main 2026-07-16 19:25:10 +02:00
+28 -17
View File
@@ -67,21 +67,27 @@ silently expanding orchestrator reconnaissance. Global Codex hook enforcement is
**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` effort. Give it #237's
body and last ~6 comments, then have it query live candidates as a cascade in this exact tier order:
**arc → open milestone → open `review` → unmilestoned/unreviewed `priority: high` → `priority: medium`
→ `priority: low`**. Deduplicate candidates, apply the live eligibility exclusions at each tier, and stop
as soon as five eligible issues have been accumulated (or all tiers are exhausted). It returns only that
ranked top-five shortlist, with one-line rationales and live-state evidence; a small result packet is the
desired behavior, but an empty or undersized higher tier must fall through to the next tier. The
orchestrator receives only that compact packet, then performs a focused live recheck of the winner before
claiming. If the cheap worker lacks a repository-scoped issue-list tool, it must return a tool limitation;
the orchestrator then performs only the mechanical tier queries (repository + state + milestone/label),
passes at most the bounded raw candidate rows back to the cheap worker, and leaves all filtering/ranking to
that worker. Never substitute an owner-wide/global search or treat that tool limitation as an empty tier.
**arc → OPEN issues assigned to OPEN milestones → open `review` → unmilestoned/unreviewed
`priority: high` → `priority: medium` → `priority: low`**. Every candidate row represents an issue
(or eligible reviewer audit): milestone records provide tier metadata and are NEVER pickup candidates.
An OPEN milestone with zero eligible OPEN issues contributes zero candidates. Deduplicate candidates,
apply the live eligibility exclusions at each tier (including automatic exclusion of `parked` issues),
and stop as soon as five eligible issues have been accumulated (or all tiers are exhausted). It returns
only that ranked top-five shortlist, with one-line rationales and live-state evidence; a small result
packet is the desired behavior, but an empty or undersized higher tier must fall through to the next tier.
The orchestrator receives only that compact packet, then performs a focused live recheck of the winner
before claiming. If the cheap worker lacks a repository-scoped issue-list tool, it must immediately return
the literal result `TOOL_LIMITATION`; it must not rank issue IDs mentioned in tracker prose, turn milestone
records into candidates, or infer that any tier is empty. The orchestrator then performs only the mechanical
tier queries (repository + state + milestone/label), passes at most the bounded raw ISSUE rows back to the
cheap worker, and leaves all filtering/ranking to that worker. Never substitute an owner-wide/global search
or treat that tool limitation as an empty tier.
Do not load implementation docs or issue bodies into the selector. If the client cannot route a
cheaper subagent, run the selector in a separate low-cost session before starting or resuming the orchestrator
and pass in its packet. **Do not fall back to inline sorting or an equally expensive selector.** If no cheaper
route or session is available, pause and request the selector packet rather than consuming orchestrator tokens
on queue ranking. If the user names an issue, skip selection and only verify that issue's live claimability.
on queue ranking. If the user names an issue, skip selection and only verify that issue's live claimability;
this explicit user choice is the sole path by which a `parked` issue may be worked.
FIRST read `AGENTS.md` and `CLAUDE.md` when present, then `docs/README.md`, the convention docs it
indexes, and the Lessons below. Apply both client instruction files; where they differ, follow the
@@ -115,9 +121,11 @@ Then work the queue:
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. Candidate
discovery is a bounded cascade, not a full inventory: query **arc → open milestone → open `review`
→ unmilestoned/unreviewed `priority: high` → `priority: medium` → `priority: low`**, carrying
eligible unique results forward until the shortlist contains five issues or all tiers are exhausted.
discovery is a bounded cascade, not a full inventory: query **arc → OPEN issues assigned to OPEN
milestones → open `review` → unmilestoned/unreviewed `priority: high` → `priority: medium` →
`priority: low`**, carrying eligible unique results forward until the shortlist contains five issues
or all tiers are exhausted. Milestone records are tier metadata, NEVER pickup candidates; an OPEN
milestone with zero eligible OPEN issues contributes zero candidates.
This priority-label fall-through is mandatory: an empty arc/milestone/review pool is never evidence
that the queue is empty. Each priority tier queries all OPEN `timothy/ersatztv` issues carrying that
label, not only IDs mentioned in #237 or recent comments, and excludes pull requests. Treat an
@@ -133,13 +141,16 @@ Then work the queue:
`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 returns the highest-ranked eligible candidate plus up to four fallbacks. Apply this
strict tier order: **(1)** open arc items in #237 arc order; **(2)** issues in an OPEN milestone;
strict tier order: **(1)** open arc items in #237 arc order; **(2)** OPEN issues assigned to an OPEN
milestone;
**(3)** OPEN `review`-labeled issues and eligible reviewer-repo audits; **(4)** remaining
unmilestoned/unreviewed `priority: high` issues; **(5)** `priority: medium`; **(6)** `priority: low`.
Within milestone and review tiers, order by `priority: high` > `medium` > `low`; for otherwise equal
candidates preserve #237's explicit eligible order, then use lowest issue number. At every tier exclude
pull requests, CLOSED issues, `in-progress` claims, issues blocked by a CLOSED milestone, containers whose
children are the pickups, and reviewer audits that are already claimed or have a posted deliverable.
pull requests, CLOSED issues, `in-progress` claims, `parked` issues, issues blocked by a CLOSED milestone,
containers whose children are the pickups, and reviewer audits that are already claimed or have a posted
deliverable. `parked` means excluded from every automatic tier; work it only when the user explicitly
names it.
Query the next tier only while fewer than five eligible unique candidates have been collected; do not
enumerate the remainder after the shortlist is full.
The orchestrator then makes one focused Gitea read to confirm the proposed winner is still OPEN,