/batch-scheduler

name: batch-scheduler
user-invocable: true
version: 4.10.0
argument-hint: "[--json-only] [--issues-file <json>] [--no-state] [--remote <url>]"
description: >
  Deterministic batch planner: read the live work graph and emit
  parallel-execution batches (order-respecting, collision-free) as the fixed
  `batch-plan@3` machine envelope — which issues can run together now, which
  are blocked and by what, which unit is really in flight, which pairs would
  rewrite the same file, which surface each lane occupies, what changed.
  Triggers: "batch scheduler", "what can run in parallel", "plan the
  batches", "batch plan".

Batch Scheduler (the parallel planner's sensor)

One pass that answers the parallel question the single-next sensor cannot: **which open issues can run together right now, in which lane, in which order** — emitted as the fixed `batch-plan@3` machine envelope. The **script is the deterministic producer**: `scripts/batch-scheduler.mjs` reads the live work graph and prints the document. This skill runs the script, reads the JSON, and interprets it against [the plan grammar](references/PLAN.md) — it never assembles the envelope by hand.

Turn contract

Load and verify the **canonical** [Turn contract](../orchestration-envelope/references/TURN_CONTRACT.md) before ending every turn; the **read-only profile** substitutes boxes 1–5 (the one sanctioned side effect is the planner's own untracked state file, declared here). Skill-specific additions:

✓ The script was RUN — `bun scripts/batch-scheduler.mjs [--json-only] [--root
  <dir>] [--issues-file <json>] [--no-state] [--remote <url>]` (node is the
  fallback when bun is absent); the envelope is the script's stdout, never
  assembled by the model
✓ Every degraded dimension is named in the envelope `degraded[]` and reported
  to the human — a degraded plan is never presented as complete truth
✓ Every finding (`cycle`, `orphaned-soft-dep`, `prose-native-mismatch`,
  `file-overlap`, `stale-claim`) is reported with its issue numbers — findings
  are never silently dropped, never auto-fixed, and `file-overlap` is never
  turned into a re-batch by this skill
✓ `worktree` and `command` are REPORTED, never executed — the planner plans,
  it does not launch (no worktree creation, no session spawn, ever)
✓ The human-readable summary is printed (unless `--json-only`), then the
  machine envelope is the ABSOLUTE last output
✓ Nothing was edited, committed, pushed, or created except the script's own
  state file (`.agentic-workflow/batches.json`, untracked) — read-only
  everywhere else

When to use

• Before launching parallel work: "what can run together now, and on which

surfaces?" — replaces the hand-computed batch plan that died every session.

• When starting a work session with several open issues: batch 1 is the

runnable-now set; the per-issue `command` starts its lane.

• **Not** for sequential next-step recommendation (`workflow-status` owns

that), for quality judgment (`review-change`/`audit-pr`), or for launching (you or the #295 panel own that).

Step 0 — Discover the project (always first)

Per the agent guide's **Workflow conventions** + **documentation map**. The script reads what it needs itself — the location index (`docs/ROADMAP.md`, via the shared `index-document.mjs` parsers), the open issues and their native `blocked-by` relations from the forge, the prose `## Dependencies` rows and `## Where`/`## In scope` sections from issue bodies, and the unit docs under `docs/fix/` + `docs/features/`. Read them yourself only to interpret a field the script emitted.

Process

1. Run the script. Defaults read the current repository and the live forge — the issue list, the native `blocked-by` relations, **one** `gh pr list` for launch evidence, and the local git plumbing (branches, worktrees, the diff against the trunk) — and persist the plan's claimed lanes to `.agentic-workflow/batches.json` (untracked, durable) so the next run recognizes what is already claimed or launched. Flags:

• `--json-only` — envelope alone (drivers, tests).
• `--issues-file <json>` — inject a fetched issue cache instead of calling

the forge; a cache without native relations fetches them live (one GraphQL call) or degrades declared.

• `--no-state` — pure read; writes nothing. It cannot be combined with

`--mark-launched` (that pair is a usage error, exit 2).

• `--remote <url>` — name the forge explicitly when `origin` is not a

GitHub URL (a scratch clone); it names it for the issue list and the relations call alike.

• `--mark-launched <n>` — record that you launched issue N's lane outside

the sensor (the only manual write). 2. Read the envelope against [the plan grammar](references/PLAN.md): `batches[]` in order (batch 1 = runnable now), each lane one surface with its size hint and its issue rows (`number`, `worktree`, `command`, `reason.kind` + `detail`, `claimed` — live only for that lane, `triaged`), `blocked[]` with the open blockers that gate each issue, `launched[]` with the **evidence** that marked each unit in flight (an open PR or an unmerged branch — a unit doc never decides), `label_blocked[]` with the hold labels, `new_issues[]` and `closed_since[]` with the lifecycle delta, `findings[]` with the unresolvable spots, `degraded[]` with anything that could not be read, and `summary` as the totals. 3. Print the human summary: one line per lane in batch 1 (surface, size hint, issues with their commands), then the blocked issues with their blockers, then the label-blocked issues with their labels, then the untriaged issues (`triaged: false` — scope undetermined; co-scheduling provisional until their lane triage runs), then every finding, then every degradation. **Launch nothing yourself** — hand the per-issue `command` to the user or the panel, and let them decide how many lanes to run (the size hints inform that choice;