/issue-queue — manage, queue, and resolve backlog issues in bounded batches

What this does. Every open issue in the repository represents a pending deliverable, bug, or feature. When left unmanaged, the issue backlog rots into sprawling, un-prioritized, collision-prone work.

While /issue-orchestrator coordinates large-scale multi-wave campaigns across many workers, /issue-queue executes the atomic, bounded issue management and resolution pass: baseline and inspect the issue queue, partition issues into actionable cohorts (ready dispatchable leaves, epics needing decomposition, and scope triage), pick a bounded batch of 1–3 high-priority units, arbitrate lane leases (dos arbitrate), delegate implementation to a coordinated team of specialized subagents (researcher, worker, cross-validator, issue-auditor), independently witness the reproduction test and fix, prove burndown with --compare, and commit by explicit path.

The shape: baseline issue queue (fak issue-queue --json / fak dispatch order) → partition into ready/subdivide/triage cohorts → research & explore candidates (parallel researcher / explore subagents) → arbitrate leases (dos arbitrate) → parallel implementation wave (worker subagents via task) → adversarial verification & gap audit (cross-validator & issue-auditor subagents) → prove queue burndown (--compare) → commit cleanly by explicit path with (#N) and (fak <lane>) → release lease.

The Rule of Bounded Batches

Never attempt a repository-wide sweep in one pass. Enforce strict scoping:

1. Batch Scaling (4–8 issues): Scale the batch to 4–8 issues whenever candidate issues map to pairwise tree-disjoint lanes (dos.toml). Focus on atomic leaves with verified independent packages.
2. Shift-left proof by default: Every bug fix must ship with a reproduction unit test that fails before the fix and passes after. Features must ship with concrete unit/contract tests. Never accept mocks or self-report claims.
3. Queue taxonomy discipline:
   • Ready Leaves: Atomic S0/S1 tasks with a single witness and bounded package tree (internal/<lane>/).
   • Subdivide Queue: Epics or multi-subsystem issues (>15 expected steps or touching 3+ packages) routed to decomposition before dispatch.
   • Triage Queue: Issues with missing acceptance criteria, ambiguous scope, or missing likely files routed to repair before dispatch.
   • Cooling / Held Queue: Issues under backoff cooldown or held by active lane leases in .dos/lane-journal.jsonl.
4. Collision safety: Pre-dispatch lane arbitration via dos arbitrate is mandatory before touching files.
5. Coordinator stays clean via specialized subagents: Substantive investigation, code edits, and verification are delegated to isolated subagents via the task tool (Gemini 3.8 Flash high variant: high). The coordinator verifies, witnesses, and commits.
6. Non-forgeable witness: Issues are closed only by git ancestry on trunk (Fixes #N with (fak <lane>)), verified by dos commit-audit and dos verify.

Step 1 — Measure Baseline & Inventory Queue

Capture the open backlog baseline and inspect queue cohorts using allocated scratch storage (fak tree-doctor --scratch-dir issue-queue):

# Allocate scratch directory for queue artifacts:
fak tree-doctor --scratch-dir issue-queue

# Snapshot current issue queue state:
fak issue-queue --json > _scratch/issue-queue/baseline.json

# View top prioritized issues across lanes:
fak issue-queue --top 5

If querying live GitHub issues:

gh issue list --state open --json number,title,body,labels > _scratch/issue-queue/live-issues.json
fak issue-queue --from-issues _scratch/issue-queue/live-issues.json --json > _scratch/issue-queue/baseline.json
fak issue-queue --from-issues _scratch/issue-queue/live-issues.json --top 5

Note the headline queue metrics:

• Total Issues Evaluated: total backlog size.
• Dispatchable Ready Leaves: atomic S0/S1 issues ready for immediate dispatch.
• Subdivide Epics: oversized issues requiring decomposition.
• Triage Issues: issues requiring scope or acceptance criteria repair.
• Held Excluded: issues currently held by active leases in .dos/lane-journal.jsonl.

Step 2 — Parallel Scoping & Pre-Dispatch Arbitration

1. Select Bounded Target Batch (1–3 Issues)

Choose 1–3 target issues based on leverage:

• Option A: High Priority / High Centrality Hotspots (P0/P1, Core centrality): Issues in core leaves (gateway, engine, model, compute) with high inbound impact.
• Option B: Quick Leaf Wins (Highest Velocity): Self-contained bug fixes or feature additions sitting at 2–4 expected steps with bounded write surfaces.

2. Pre-Dispatch Research & Path Mapping (Parallel Subagents)

Launch parallel specialized discovery subagents in a single turn to research candidate context and verify disjoint boundaries without polluting coordinator context:

[
  {
    "tool": "task",
    "parameters": {
      "subagent_type": "researcher",
      "description": "Research #1024 gateway timeout context",
      "prompt": "Investigate issue #1024: Fix gateway streaming timeout.\nAnalyze relevant files under internal/gateway/, recent commits, and existing test patterns.\nReturn a compact receipt: (1) root cause hypothesis, (2) exact files to edit, (3) proposed reproduction test strategy."
    }
  },
  {
    "tool": "task",
    "parameters": {
      "subagent_type": "explore",
      "description": "Explore model KV cache paths",
      "prompt": "Inspect internal/model/ for KV cache allocation and recycling paths for issue #1035.\nVerify that its write tree is strictly confined to internal/model/ and shares no files with internal/gateway/."
    }
  }
]

(If an issue involves deep architectural or concurrency invariants, launch a deep-reason subagent for lock ordering and invariant analysis).

3. Verify Smallness & Contract

# Verify smallness / atomicity (single deliverable, witness == 1):
fak dispatch issue-smallness-lint --issue <number> --json

# Verify issue contract and structure:
fak-dev issue contract --from-issues _scratch/issue-queue/live-issues.json --json

4. Arbitrate Lane Leases

Verify lane lease availability before dispatch:

dos arbitrate --workspace . --lane <lane> --kind keyword --mode exclusive

(Or invoke the dos_arbitrate MCP tool).

• Outcome acquire: Admitted. Proceed to dispatch.
• Outcome refuse: Lane is held by a peer. Pick another candidate from the queue or wait out the lease.

Step 3 — Parallel Implementation Worker Wave

Launch all selected issues' implementation workers in parallel in a single turn using multiple task tool calls with subagent_type="worker" (using Gemini 3.8 Flash high variant: high). Each worker operates under strict package fences:

[
  {
    "tool": "task",
    "parameters": {
      "subagent_type": "worker",
      "description": "Implement fix for #1024",
      "prompt": "You are an isolated worker resolving issue #1024: Fix gateway streaming timeout.\nLane: gateway\nBoundaries: Edit ONLY files inside internal/gateway/. NEVER touch go.mod, go.sum, dos.toml, or root files.\nDeliverable:\n  1. Write an atomic reproduction test in internal/gateway/stream_timeout_test.go demonstrating the defect.\n  2. Implement the minimal fix in internal/gateway/.\n  3. Verify package tests pass.\nVerification: Execute ONLY package-scoped tests: `go test -v ./internal/gateway` and `go vet ./internal/gateway`. NEVER run `go test ./...`.\nReturn Contract: Return a compact 3-line receipt: (1) files created/modified, (2) package test results, (3) confirmation of fix."
    }
  },
  {
    "tool": "task",
    "parameters": {
      "subagent_type": "worker",
      "description": "Implement feature for #1035",
      "prompt": "You are an isolated worker resolving issue #1035: Add model KV cache recycling.\nLane: model\nBoundaries: Edit ONLY files inside internal/model/. NEVER touch go.mod, go.sum, dos.toml, or root files.\nDeliverable:\n  1. Write an atomic reproduction test in internal/model/kv_recycle_test.go.\n  2. Implement the KV cache recycling path in internal/model/.\n  3. Verify package tests pass.\nVerification: Execute ONLY package-scoped tests: `go test -v ./internal/model` and `go vet ./internal/model`. NEVER run `go test ./...`.\nReturn Contract: Return a compact 3-line receipt: (1) files created/modified, (2) package test results, (3) confirmation of feature."
    }
  }
]

Each worker executes the concrete implementation:

1. Reproduction Unit Test: Focused test reproducing the defect or specifying the contract.
2. Minimal Package Implementation: Code changes strictly confined to internal/<lane>/.
3. Package Verification: Scoped checks (go vet ./internal/<lane>, go test -v ./internal/<lane>).

Step 4 — Parallel Adversarial Cross-Validation & Gap Audit

The coordinator does NOT trust worker narration (dos-witness-claim). Instead, launch parallel verification subagents to independently audit the landed work before commit:

[
  {
    "tool": "task",
    "parameters": {
      "subagent_type": "cross-validator",
      "description": "Cross-validate #1024 and #1035",
      "prompt": "You are an adversarial cross-validator.\nTasks to verify: #1024 (internal/gateway) and #1035 (internal/model).\nResponsibilities:\n  1. Inspect `git diff internal/gateway` and `git diff internal/model` to verify that edits did not leak outside declared package boundaries.\n  2. Execute on-device tests: `go test -v ./internal/gateway` and `go test -v ./internal/model`.\n  3. Verify that reproduction tests genuinely assert the expected behavior and do not test trivial mocks.\nReturn a structured DOS-style proof verdict: VERIFIED or REJECTED with concrete command witnesses."
    }
  },
  {
    "tool": "task",
    "parameters": {
      "subagent_type": "issue-auditor",
      "description": "Audit QA gaps and follow-ons",
      "prompt": "You are an issue auditor inspecting the changes in internal/gateway and internal/model.\nUncover unhandled edge cases, boundary conditions, or failure modes in the newly added code.\nIf real follow-ons or gaps exist, draft structured GitHub issue tickets with clear reproduction steps and acceptance criteria."
    }
  }
]

Coordinator independently verifies:

1. Toolchain check: go vet ./internal/<lane> and go test -v ./internal/<lane>.
2. Diff boundary check: git diff --stat internal/<lane>.
3. Audit review: Incorporate cross-validator proof verdicts and any auditor follow-on tickets.

Step 5 — Re-Measure and Prove Queue Burndown

Re-evaluate the issue queue against the saved baseline to prove burndown:

# Re-snapshot issue state:
gh issue list --state open --json number,title,body,labels > _scratch/issue-queue/updated-issues.json
fak issue-queue --from-issues _scratch/issue-queue/updated-issues.json --compare _scratch/issue-queue/baseline.json

Confirm:

• Target issues are resolved and retired from the dispatchable count.
• Closed count delta reflects the completed batch.
• No new unclassified drift was introduced.

Step 6 — Commit Cleanly by Explicit Path

Commit each finished leaf independently on the trunk. Include a Conventional-Commits subject, signed-off DCO (-s), issue citation (#N), and required (fak <leaf>) trailer:

fak sync reconcile --apply
fak commit --path internal/<laneA> -m "fix(<laneA>): resolve <summary> (#1024) (fak <laneA>)"
fak commit --path internal/<laneB> -m "feat(<laneB>): add <summary> (#1035) (fak <laneB>)"
fak sync push

(Fallback: git commit -s -m "..." -- internal/<lane> without git add -A).

Verify git status shows your lanes are committed cleanly and no peer WIP was staged.

Step 7 — Release Lane Leases & Clean Scratch

Release all acquired lane leases:

dos lease-lane release --lane <laneA>
dos lease-lane release --lane <laneB>

Reap the campaign scratch directory:

fak tree-doctor --reap-scratch issue-queue --json

Report the one-line completion receipt to the operator with the checkable commit SHAs, issue numbers, and test witnesses.