# GitHub Issues Queue Planner V01 Issue: [#358](https://github.com/pinklon/ai-capability-discipline/issues/358) References: - [#356 GitHub Issues queue-backed agent work engine MVP](https://github.com/pinklon/ai-capability-discipline/issues/356) - [PR #357 GitHub Issues queue-backed agent work engine MVP](https://github.com/pinklon/ai-capability-discipline/pull/357) - [#287 Queue-backed multi-agent work engine evaluation](https://github.com/pinklon/ai-capability-discipline/issues/287) - [#277 Backlog triage dependency and supersession workflow](https://github.com/pinklon/ai-capability-discipline/issues/277) ## Purpose This v01 follows PR #357 by adding the smallest repo-local read-only queue planner after the GitHub Issues queue-backed agent work engine MVP. The MVP defined work states, transition evidence, parallelism classes, lock and lease semantics, and closeout requirements. This planner turns those contracts into a deterministic report over committed work-item payload fixtures. The planner answers: - which work is ready - which work is blocked - which work can safely run in parallel - which work must run serially - which work has file, runtime, source-set, branch, lock, or lease conflicts - which work requires owner approval - which work is high-risk gated - which claimed work has stale-lock or collision risk - which validation and closeout evidence is required ## Non-Mutation Boundary This is a read-only queue planner. It reads a repo-local fixture and emits JSON or Markdown. It does not mutate live GitHub issues or PRs, labels, milestones, assignees, comments, issue state, PR state, branches, files outside the requested repo-local implementation, source sets, runtime config, or external systems. The planner does not add autonomous polling, scheduled execution, webhook-triggered execution, autonomous worker loops, planner-triggered implementation, Linear integration, Jira integration, a custom database, an external queue provider, or MCP behavior. The planner does not add webhook-triggered execution. It does not integrate Linear, Jira, a custom database, an external queue provider, or MCP behavior. The planner does not mutate source registries, Preview source sets, Production source sets, Cloudflare, provider/model configuration, runtime retrieval, browser-side retrieval, or package authority. It does not reopen #269 or #271 and it does not apply `codex-automerge`. ## Inputs The v01 input is a deterministic fixture: ```bash python3 -B scripts/github_issues_queue_planner.py --fixture validation/fixtures/github_issues_queue_planner_v01.json --format json python3 -B scripts/github_issues_queue_planner.py --fixture validation/fixtures/github_issues_queue_planner_v01.json --format markdown ``` The fixture includes: - safe parallel work - serial-required work - blocked-by-dependency work - owner-decision-required work - mutually exclusive file and runtime surface conflicts - high-risk gated work - stale lock evidence - active lock evidence - invalid terminal-state transition evidence - missing required labels - missing validation contract - missing closeout receipt requirement ## Planner Output The planner emits: - `plan_id` - `generated_at` - `input_source` - `summary` - `serial_lane` - `safe_parallel_lane` - `blocked_lane` - `owner_decision_lane` - `high_risk_gated_lane` - `lock_conflicts` - `stale_locks` - `invalid_items` - `required_owner_decisions` - `validation_requirements` - `closeout_requirements` - `non_mutation_confirmation` The `generated_at` value is fixture-derived so repeated local runs produce stable output for the same committed fixture. ## Parallelism Rules The planner classifies work with a conservative order: 1. Invalid payloads are flagged and excluded from normal execution lanes. 2. Missing or open dependencies route to the blocked lane. 3. Owner-decision items route to the owner decision lane with the exact decision prompt. 4. High-risk surfaces route to the high-risk gated lane. 5. Shared file, runtime, branch, active lock, or declared serial-required surfaces route to the serial lane. 6. Work with clear dependencies, no owner gate, no high-risk surface, no active lock, and no overlap routes to the safe parallel lane. ## Safe Parallelism Support Safe parallelism requires non-overlapping touched files, no shared runtime or source-set surface, no shared branch, no active lock collision, clear dependencies, required labels, validation commands, and closeout receipt requirements. The report records evidence paths for each safe-parallel candidate so a human reviewer can inspect why work is eligible to run beside another item. ## Owner Decision Gates Owner decision gates are explicit report entries, not implicit scheduler behavior. When work has ambiguous acceptance criteria, priority tradeoffs, unclear authority, or missing approval, the planner reports `owner clarification required` and does not promote the item into a normal execution lane. ## Collision Prevention The planner detects overlapping file and directory surfaces, shared runtime surfaces, shared branches, active lock conflicts, duplicate lock ids, stale locks, missing dependencies, missing required labels, missing validation contracts, missing closeout requirements, and high-risk work that lacks explicit approval. Collision findings route work to serial, blocked, high-risk, or invalid report sections rather than starting work. ## Validation And Closeout Evidence Each work item contributes validation and closeout requirements to the report. Missing validation commands and missing closeout receipt requirements are invalid-item findings because review-ready work in this repo needs deterministic validation and a closeout receipt. The focused validator proves that JSON output, Markdown output, lane classification, conflict detection, stale-lock detection, invalid-item detection, and non-mutation confirmation are present. It also checks that no live GitHub mutation path, subprocess execution path, network call, autonomous loop, webhook loop, external queue provider, or planner-triggered execution is introduced. ## Future Worker Relationship This planner could later feed a controlled worker, but it does not implement one now. A future worker would need a separate owner-approved issue, explicit transition validation, identity and permission boundaries, lock renewal behavior, failure handling, dry-run and review gates, and receipts before any execution path exists. The v01 report is therefore a planning artifact only. It makes queue state legible while preserving GitHub Issues, PRs, branches, validation receipts, and owner decisions as the control plane. ## Boundary Confirmations This issue confirms: - the planner is read-only - no live GitHub issue mutation was added - no live GitHub PR mutation was added - no autonomous worker loop was added - no autonomous polling was added - no webhook loop was added - no external queue provider was integrated - no Linear integration was added - no Jira integration was added - no custom database was added - no MCP behavior was added - no source registry was mutated - no Preview source set was mutated - no Production source set was mutated - no source was enabled, disabled, retired, promoted, or applied - no Cloudflare CLI/API was used - no Cloudflare Access/WAF change was made - no provider/model configuration was changed - no runtime retrieval semantics were changed - no browser-side provider calls were added - no browser-side current-source retrieval was added - package authority was not changed - #269 remains closed - #271 remains closed - #356 remains closed after PR #357 - `codex-automerge` was not applied ## Post-Closeout Next Action After this planner lands, the next action remains an owner decision point. Candidate follow-ups are live read-only export of GitHub issue payloads into committed fixtures, an issue-body payload template, or a separate controlled worker design. No follow-up should start automatically from this planner output.