diff --git a/docs/handoffs/chicorytv-issue-queue.md b/docs/handoffs/chicorytv-issue-queue.md index a2945a9a8..72de79083 100644 --- a/docs/handoffs/chicorytv-issue-queue.md +++ b/docs/handoffs/chicorytv-issue-queue.md @@ -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 : 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,