@opengsd/gsd-core 1.12.0 → 1.13.0

package/gsd-core/bin/lib/quick-batch-command-router.cjs

@@ -0,0 +1,285 @@
+"use strict";
+/**
+ * Quick-Batch command router — CLI subcommand dispatcher for
+ * `gsd-tools quick-batch` (#3676, Phase 4 of epic #3344 / ADR-1239).
+ *
+ * Quick-batch is a first-party, always-on command family (like `/gsd:quick`,
+ * which has no capability-registry entry), so this router is wired directly
+ * into `HOST_COMMAND_ROUTERS` (`gsd-core/bin/gsd-tools.cjs`) — NOT the opt-in
+ * capability-registry/`activationKey` path `graphify` uses. Shape follows
+ * `graphify-command-router.cts` (thin `routeHubCommandFamily` wrapper), which
+ * gives the Hub's `makeUnknownCommand` handling for free on an unknown
+ * subcommand (test-matrix row 47).
+ *
+ * Verbs wrap `src/quick-batch.cts` (durable manifest read/write — reused
+ * as-is) and `src/quick-batch-dispatch.cts` (pure decision logic, #3676's
+ * own new module). This router performs NO decision logic of its own beyond
+ * argument shaping — every behavioral rule lives in one of those two
+ * modules, per the design doc's "Do the simplest thing" law.
+ *
+ * Test seam: pass `_quickBatch`/`_quickBatchDispatch` in the options object
+ * to inject recording mocks instead of the real modules — same `_`-prefix
+ * convention `graphify-command-router.cts` uses.
+ *
+ * ADR-457 build-at-publish: compiled by tsc to
+ * gsd-core/bin/lib/quick-batch-command-router.cjs.
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const quickBatch = require("./quick-batch.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const quickBatchDispatch = require("./quick-batch-dispatch.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const commandRoutingHub = require("./command-routing-hub.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cjsCommandRouterAdapter = require("./cjs-command-router-adapter.cjs");
+const security_cjs_1 = require("./security.cjs");
+const { output, ERROR_REASON } = io;
+const { makeInvalidArgs } = commandRoutingHub;
+const { routeHubCommandFamily } = cjsCommandRouterAdapter;
+// ─── Small arg-parsing helpers (local — no new shared convention needed) ────
+/** `--flag value` lookup; undefined when the flag is absent. */
+function argValue(args, flag) {
+    const idx = args.indexOf(flag);
+    if (idx === -1)
+        return undefined;
+    return args[idx + 1];
+}
+function parseJsonArg(raw, label) {
+    if (raw === undefined) {
+        return { ok: false, reason: `${label} requires a JSON value` };
+    }
+    const parsed = (0, security_cjs_1.safeJsonParse)(raw, { maxLength: 1048576, label });
+    if (!parsed.ok) {
+        return { ok: false, reason: `${label} is not valid JSON: ${parsed.error ?? 'unknown parse error'}` };
+    }
+    return { ok: true, value: parsed.value };
+}
+// ─── Implementation ───────────────────────────────────────────────────────────
+function routeQuickBatchCommand({ args, cwd, raw, error, _quickBatch, _quickBatchDispatch }) {
+    const qb = _quickBatch ?? quickBatch;
+    const dispatch = _quickBatchDispatch ?? quickBatchDispatch;
+    /** Forward a `Result<T>` from either module straight to output()/error(). */
+    function emit(result) {
+        if (result && typeof result === 'object' && 'ok' in result) {
+            const r = result;
+            if (!r.ok) {
+                error(r.reason ?? 'quick-batch command failed', ERROR_REASON.USAGE);
+                return;
+            }
+            output(r.value, raw);
+            return;
+        }
+        output(result, raw);
+    }
+    routeHubCommandFamily({
+        family: 'quick-batch',
+        args,
+        subcommands: [
+            'create',
+            'update',
+            'resume',
+            'complete',
+            'effective-concurrency',
+            'merge-eligible',
+            'spawn-plan',
+            'filter-executed',
+            'verification-routing',
+            'merge-routing',
+            'cleanup-entry',
+            'parse-args',
+        ],
+        handlers: {
+            // `quick-batch create --file <path> [--base-revision <sha>] [--options <json>]`
+            create: () => {
+                const filePath = argValue(args, '--file');
+                if (!filePath) {
+                    return makeInvalidArgs('--file', 'Usage: gsd-tools quick-batch create --file <path> [--base-revision <sha>] [--options <json>]', ERROR_REASON.USAGE);
+                }
+                const parsed = qb.parseTaskListFromFile(cwd, filePath);
+                if (!parsed.ok) {
+                    return makeInvalidArgs('--file', parsed.reason ?? 'unable to parse task list', ERROR_REASON.USAGE);
+                }
+                const baseRevision = argValue(args, '--base-revision');
+                const optionsRaw = argValue(args, '--options');
+                let batchOptions;
+                if (optionsRaw !== undefined) {
+                    const optResult = parseJsonArg(optionsRaw, '--options');
+                    if (!optResult.ok)
+                        return makeInvalidArgs('--options', optResult.reason, ERROR_REASON.USAGE);
+                    batchOptions = optResult.value;
+                }
+                const items = (parsed.value ?? []).map((it) => ({ description: it.description }));
+                emit(qb.createBatch(cwd, items, { baseRevision, batchOptions }));
+            },
+            // `quick-batch update --batch <id> --updates <json>`
+            update: () => {
+                const batchId = argValue(args, '--batch');
+                if (!batchId) {
+                    return makeInvalidArgs('--batch', 'Usage: gsd-tools quick-batch update --batch <id> --updates <json>', ERROR_REASON.USAGE);
+                }
+                const updatesResult = parseJsonArg(argValue(args, '--updates'), '--updates');
+                if (!updatesResult.ok)
+                    return makeInvalidArgs('--updates', updatesResult.reason, ERROR_REASON.USAGE);
+                emit(qb.updateBatchItems(cwd, batchId, updatesResult.value));
+            },
+            // `quick-batch resume --batch <id> [--current-base-revision <sha>]`
+            resume: () => {
+                const batchId = argValue(args, '--batch');
+                if (!batchId) {
+                    return makeInvalidArgs('--batch', 'Usage: gsd-tools quick-batch resume --batch <id> [--current-base-revision <sha>]', ERROR_REASON.USAGE);
+                }
+                const currentBaseRevision = argValue(args, '--current-base-revision');
+                emit(qb.resumeBatch(cwd, batchId, currentBaseRevision !== undefined ? { currentBaseRevision } : {}));
+            },
+            // `quick-batch complete --batch <id> --quick-id <id> --description <t> --date <d> --commit <sha> [--directory <dir>]`
+            complete: () => {
+                const batchId = argValue(args, '--batch');
+                const quickId = argValue(args, '--quick-id');
+                const description = argValue(args, '--description');
+                const date = argValue(args, '--date');
+                const commit = argValue(args, '--commit');
+                if (!batchId || !quickId || !description || !date || !commit) {
+                    return makeInvalidArgs('--batch/--quick-id/--description/--date/--commit', 'Usage: gsd-tools quick-batch complete --batch <id> --quick-id <id> --description <t> --date <d> --commit <sha> [--directory <dir>]', ERROR_REASON.USAGE);
+                }
+                const directory = argValue(args, '--directory');
+                emit(qb.completeQuickItem(cwd, batchId, quickId, { description, date, commit, directory }));
+            },
+            // `quick-batch effective-concurrency --jobs <auto|N> --task-count <N> --capacity <N> --isolation <str> [--mutating]`
+            'effective-concurrency': () => {
+                const jobsRaw = argValue(args, '--jobs');
+                const taskCount = Number(argValue(args, '--task-count'));
+                const capacity = Number(argValue(args, '--capacity'));
+                const isolation = argValue(args, '--isolation') ?? '';
+                if (jobsRaw === undefined || !Number.isFinite(taskCount) || !Number.isFinite(capacity)) {
+                    return makeInvalidArgs('--jobs/--task-count/--capacity', 'Usage: gsd-tools quick-batch effective-concurrency --jobs <auto|N> --task-count <N> --capacity <N> --isolation <str> [--mutating]', ERROR_REASON.USAGE);
+                }
+                const jobs = jobsRaw === 'auto' ? 'auto' : Number(jobsRaw);
+                const mutating = args.includes('--mutating');
+                output({
+                    concurrency: dispatch.computeEffectiveConcurrency({ jobs, taskCount, capacity, isolation, mutating }),
+                }, raw);
+            },
+            // `quick-batch merge-eligible --wave-order <json-array> --ready <json-array>`
+            'merge-eligible': () => {
+                const waveOrderResult = parseJsonArg(argValue(args, '--wave-order'), '--wave-order');
+                if (!waveOrderResult.ok)
+                    return makeInvalidArgs('--wave-order', waveOrderResult.reason, ERROR_REASON.USAGE);
+                const readyResult = parseJsonArg(argValue(args, '--ready'), '--ready');
+                if (!readyResult.ok)
+                    return makeInvalidArgs('--ready', readyResult.reason, ERROR_REASON.USAGE);
+                output({
+                    mergeable: dispatch.computeMergeOrder(waveOrderResult.value, new Set(readyResult.value)),
+                }, raw);
+            },
+            // `quick-batch spawn-plan --eligible <json-array> --capacity <N> --in-flight <N> [--refused <json-array>]`
+            'spawn-plan': () => {
+                const eligibleResult = parseJsonArg(argValue(args, '--eligible'), '--eligible');
+                if (!eligibleResult.ok)
+                    return makeInvalidArgs('--eligible', eligibleResult.reason, ERROR_REASON.USAGE);
+                const capacity = Number(argValue(args, '--capacity'));
+                const currentInFlight = Number(argValue(args, '--in-flight'));
+                if (!Number.isFinite(capacity) || !Number.isFinite(currentInFlight)) {
+                    return makeInvalidArgs('--capacity/--in-flight', 'Usage: gsd-tools quick-batch spawn-plan --eligible <json-array> --capacity <N> --in-flight <N> [--refused <json-array>]', ERROR_REASON.USAGE);
+                }
+                let refused = [];
+                const refusedRaw = argValue(args, '--refused');
+                if (refusedRaw !== undefined) {
+                    const refusedResult = parseJsonArg(refusedRaw, '--refused');
+                    if (!refusedResult.ok)
+                        return makeInvalidArgs('--refused', refusedResult.reason, ERROR_REASON.USAGE);
+                    refused = refusedResult.value;
+                }
+                output(dispatch.computeSpawnPlan({ eligibleIds: eligibleResult.value, capacity, currentInFlight, refused }), raw);
+            },
+            // `quick-batch filter-executed --eligible <json-array> --executed <json-array>`
+            // Crash-window duplicate-dispatch guard (#3677): splits this round's
+            // eligible ids into `spawnEligible` (safe to dispatch) and
+            // `alreadyExecuted` (SUMMARY.md already exists on disk — caller
+            // determines this via its own filesystem check; NEVER re-dispatch
+            // these — merge-wave.md's own on-disk criterion picks them up).
+            'filter-executed': () => {
+                const eligibleResult = parseJsonArg(argValue(args, '--eligible'), '--eligible');
+                if (!eligibleResult.ok)
+                    return makeInvalidArgs('--eligible', eligibleResult.reason, ERROR_REASON.USAGE);
+                const executedResult = parseJsonArg(argValue(args, '--executed'), '--executed');
+                if (!executedResult.ok)
+                    return makeInvalidArgs('--executed', executedResult.reason, ERROR_REASON.USAGE);
+                output(dispatch.filterAlreadyExecuted(eligibleResult.value, executedResult.value), raw);
+            },
+            // `quick-batch verification-routing --status <passed|gaps_found|human_needed>`
+            'verification-routing': () => {
+                const status = argValue(args, '--status');
+                if (status !== 'passed' && status !== 'gaps_found' && status !== 'human_needed') {
+                    return makeInvalidArgs('--status', 'Usage: gsd-tools quick-batch verification-routing --status <passed|gaps_found|human_needed>', ERROR_REASON.USAGE);
+                }
+                output(dispatch.routeVerificationOutcome(status), raw);
+            },
+            // `quick-batch merge-routing --kind <merged|merge_failed|scope_violation> [--detail <text>]`
+            'merge-routing': () => {
+                const kind = argValue(args, '--kind');
+                if (kind !== 'merged' && kind !== 'merge_failed' && kind !== 'scope_violation') {
+                    return makeInvalidArgs('--kind', 'Usage: gsd-tools quick-batch merge-routing --kind <merged|merge_failed|scope_violation> [--detail <text>]', ERROR_REASON.USAGE);
+                }
+                const detail = argValue(args, '--detail');
+                output(dispatch.routeMergeOutcome(detail !== undefined ? { kind, detail } : { kind }), raw);
+            },
+            // `quick-batch cleanup-entry --agent-id <id|null> --worktree-path <p> --branch <b> --expected-base <b> [--allowed-bases <json-array>] --plan-content <text>`
+            'cleanup-entry': () => {
+                const agentIdRaw = argValue(args, '--agent-id');
+                const worktreePath = argValue(args, '--worktree-path');
+                const branch = argValue(args, '--branch');
+                const expectedBase = argValue(args, '--expected-base');
+                const planContent = argValue(args, '--plan-content');
+                if (!worktreePath || !branch || !expectedBase || planContent === undefined) {
+                    return makeInvalidArgs('--worktree-path/--branch/--expected-base/--plan-content', 'Usage: gsd-tools quick-batch cleanup-entry --worktree-path <p> --branch <b> --expected-base <b> --plan-content <text> [--agent-id <id>] [--allowed-bases <json-array>]', ERROR_REASON.USAGE);
+                }
+                let allowedBases;
+                const allowedBasesRaw = argValue(args, '--allowed-bases');
+                if (allowedBasesRaw !== undefined) {
+                    const allowedResult = parseJsonArg(allowedBasesRaw, '--allowed-bases');
+                    if (!allowedResult.ok)
+                        return makeInvalidArgs('--allowed-bases', allowedResult.reason, ERROR_REASON.USAGE);
+                    allowedBases = allowedResult.value;
+                }
+                output(dispatch.buildCleanupManifestEntry({
+                    agentId: agentIdRaw ?? null,
+                    worktreePath,
+                    branch,
+                    expectedBase,
+                    allowedBases,
+                    planContent,
+                }), raw);
+            },
+            // `quick-batch parse-args --text "<raw $ARGUMENTS string>"` (preferred —
+            // callers pass the ENTIRE, still-quoted $ARGUMENTS as ONE argv element;
+            // this handler does the whitespace split itself, in Node, so shell
+            // pathname expansion (globbing) on attacker-influenced task text never
+            // happens before this parser sees it — quoting `"$ARGUMENTS"` at the
+            // call site is what closes that off; splitting it here is what keeps
+            // the caller from having to word-split it unsafely beforehand).
+            // `quick-batch parse-args -- <already-tokenized args>` (legacy/direct
+            // form — still supported for a caller that already has a real argv
+            // array with no shell splitting involved, e.g. a test harness).
+            'parse-args': () => {
+                const textArg = argValue(args, '--text');
+                if (textArg !== undefined) {
+                    const rawArgs = textArg.trim().length === 0 ? [] : textArg.trim().split(/\s+/);
+                    emit(dispatch.parseQuickBatchArgs(rawArgs));
+                    return;
+                }
+                const sepIdx = args.indexOf('--');
+                const rawArgs = sepIdx === -1 ? [] : args.slice(sepIdx + 1);
+                emit(dispatch.parseQuickBatchArgs(rawArgs));
+            },
+        },
+        unknownMessage: (subcommand, available) => `Unknown quick-batch subcommand. Available: ${available.join(', ')}`,
+        error,
+        cwd,
+        raw,
+    });
+}
+module.exports = {
+    routeQuickBatchCommand,
+};

package/gsd-core/bin/lib/quick-batch-dispatch.cjs

@@ -0,0 +1,250 @@
+"use strict";
+/**
+ * Quick-Batch Dispatch Core (#3676, Phase 4 of epic #3344 / ADR-1239
+ * "Quick-batch binding").
+ *
+ * PURE decision logic for `/gsd:quick-batch`: argument validation, effective
+ * concurrency, deterministic merge ordering, spawn backpressure, and
+ * failure/verification routing. This module answers "what should happen
+ * next" — it NEVER performs `Agent()` dispatch, `git worktree` I/O, or writes
+ * `BATCH.json`/STATE.md itself. Those live in the workflow markdown (a
+ * separate follow-up pass) and in `src/quick-batch.cts` (durable manifest
+ * mutation, reused as-is).
+ *
+ * Capacity and isolation are CALLER-SUPPLIED inputs here — the CLI layer
+ * resolves those via the existing `dispatch-capacity`/`dispatch-isolation`
+ * queries (`gsd-core/bin/gsd-tools.cjs`'s `routeDispatchCapacity`/
+ * `routeDispatchIsolation`); this module never re-derives that negotiation.
+ *
+ * The one exception to "never performs I/O" is `buildCleanupManifestEntry`,
+ * which accepts a plan document's raw text (already read by the caller) and
+ * parses it via the existing `parsePlanDocument` (`src/plan-document.cts`) —
+ * no filesystem access happens inside this module.
+ *
+ * Design lock: `.gsd/phase/feat-3676-quick-batch-command-workflow/40-design.md`.
+ * Test matrix: `.gsd/phase/feat-3676-quick-batch-command-workflow/50-test-matrix.md`.
+ *
+ * ADR-457 build-at-publish: compiled by tsc to gsd-core/bin/lib/quick-batch-dispatch.cjs.
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planDocumentMod = require("./plan-document.cjs");
+const { parsePlanDocument } = planDocumentMod;
+/**
+ * Validate `/gsd:quick-batch` CLI args BEFORE any dispatch. Rejects
+ * `--discuss`/`--full` outright (v1 exclusion, design rows 7-9,13-15 — a
+ * mixed valid+rejected-flag invocation is still rejected: presence alone is
+ * sufficient, regardless of other flags), and rejects a malformed `--jobs`
+ * value (non-numeric or <= 0, row 5/9) before any dispatch. `--jobs` omitted
+ * defaults to `'auto'` (row 10).
+ */
+function parseQuickBatchArgs(args) {
+    if (!Array.isArray(args)) {
+        return { ok: false, reason: 'quick-batch args must be an array' };
+    }
+    if (args.includes('--discuss')) {
+        return { ok: false, reason: 'quick-batch does not support --discuss in v1 — use /gsd:quick --discuss per item instead' };
+    }
+    if (args.includes('--full')) {
+        return { ok: false, reason: 'quick-batch does not support --full in v1' };
+    }
+    let jobs = 'auto';
+    const jobsIdx = args.indexOf('--jobs');
+    if (jobsIdx !== -1) {
+        const raw = args[jobsIdx + 1];
+        if (raw === undefined || raw.startsWith('--')) {
+            return { ok: false, reason: 'quick-batch --jobs requires a value ("auto" or a positive integer)' };
+        }
+        if (raw === 'auto') {
+            jobs = 'auto';
+        }
+        else {
+            const n = Number(raw);
+            if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
+                return { ok: false, reason: `quick-batch --jobs must be "auto" or a positive integer, got ${JSON.stringify(raw)}` };
+            }
+            jobs = n;
+        }
+    }
+    const validate = args.includes('--validate');
+    const research = args.includes('--research');
+    let resume = null;
+    const resumeIdx = args.indexOf('--resume');
+    if (resumeIdx !== -1) {
+        const raw = args[resumeIdx + 1];
+        if (raw === undefined || raw.startsWith('--')) {
+            return { ok: false, reason: 'quick-batch --resume requires a batch id' };
+        }
+        resume = raw;
+    }
+    return { ok: true, value: { jobs, validate, research, resume } };
+}
+/**
+ * `--jobs auto` (or omitted) → capacity alone (rows 3,10). `--jobs N` →
+ * `min(taskCount, N, capacity)` (row 4). When `isolation === 'none'` and the
+ * wave is `mutating`, concurrency is forced to 1 regardless of `--jobs`/
+ * capacity (row 6) — a non-mutating wave is unaffected (row 12).
+ */
+function computeEffectiveConcurrency(input) {
+    let concurrency = input.jobs === 'auto'
+        ? input.capacity
+        : Math.min(input.taskCount, input.jobs, input.capacity);
+    if (input.isolation === 'none' && input.mutating) {
+        concurrency = Math.min(concurrency, 1);
+    }
+    return Math.max(concurrency, 0);
+}
+// ─── Deterministic merge ordering (design row 24; test-matrix rows 32-33) ───
+/**
+ * Given a wave's ORIGINAL dispatch order (`waveOrder`, as `computeWaves`
+ * assigned it) and the set of ids whose leaf has finished ("ready"),
+ * returns the prefix of `waveOrder` that is currently mergeable — merges
+ * happen strictly in wave order, so an item is only mergeable once every
+ * item before it in `waveOrder` is ALSO ready. An out-of-order completion
+ * (e.g. item 2 finishes before item 1) waits: `computeMergeOrder` returns
+ * only `[]` until item 1 is also ready.
+ */
+function computeMergeOrder(waveOrder, readyIds) {
+    const mergeable = [];
+    for (const id of waveOrder) {
+        if (!readyIds.has(id))
+            break;
+        mergeable.push(id);
+    }
+    return mergeable;
+}
+/**
+ * Pure backpressure model: given eligible items, a capacity ceiling, and a
+ * set of host-refused ids, decide which ids spawn now and which stay
+ * `pending`. Total in-flight (`currentInFlight + spawn.length`) never
+ * exceeds `capacity` at any point (row 27, property row 53). A refused id
+ * is never counted against capacity and never marked `failed` — it simply
+ * returns to `pending` for a later round.
+ */
+function computeSpawnPlan(input) {
+    const refusedSet = input.refused instanceof Set ? input.refused : new Set(input.refused ?? []);
+    let available = Math.max(input.capacity - input.currentInFlight, 0);
+    const spawn = [];
+    const pending = [];
+    for (const id of input.eligibleIds) {
+        if (refusedSet.has(id)) {
+            pending.push(id);
+            continue;
+        }
+        if (available > 0) {
+            spawn.push(id);
+            available -= 1;
+        }
+        else {
+            pending.push(id);
+        }
+    }
+    return { spawn, pending };
+}
+/**
+ * Route a verifier's status to an item action. `human_needed` is terminal
+ * for the item — the caller must NOT call `completeQuickItem` (row 30, no
+ * STATE row appended). `gaps_found` fails the item WITHOUT rollback and
+ * WITHOUT an automatic gap-fix retry (row 31,34). `passed` completes it.
+ */
+function routeVerificationOutcome(status) {
+    switch (status) {
+        case 'passed':
+            return { action: 'complete' };
+        case 'human_needed':
+            return { action: 'human_needed' };
+        case 'gaps_found':
+            return { action: 'fail', failureReason: 'verification reported gaps_found (no automatic gap-fix retry in v1)' };
+    }
+}
+/**
+ * Route a merge attempt's outcome to an item action. Both `merge_failed`
+ * (real conflict) and `scope_violation` (undeclared deletion / advisory
+ * scope drift escalated to a gate — see `executeWorktreeWaveCleanupPlan`)
+ * mark the item `failed` with a `failure_reason` and PRESERVE the worktree
+ * for diagnosis — this function never signals worktree removal (row 28,
+ * 34-35). `merged` completes the item.
+ */
+function routeMergeOutcome(outcome) {
+    switch (outcome.kind) {
+        case 'merged':
+            return { action: 'complete' };
+        case 'merge_failed':
+            return {
+                action: 'fail',
+                failureReason: outcome.detail ? `merge_failed: ${outcome.detail}` : 'merge_failed',
+                preserveWorktree: true,
+            };
+        case 'scope_violation':
+            return {
+                action: 'fail',
+                failureReason: outcome.detail ? `scope_violation: ${outcome.detail}` : 'scope_violation',
+                preserveWorktree: true,
+            };
+    }
+}
+/**
+ * Crash-window duplicate-dispatch guard
+ * (`.gsd/phase/feat-3677-quick-batch-hardening-acceptance/40-design.md` §1).
+ * `quick-batch resume`'s `eligible` is purely status/dependency-derived —
+ * it has no awareness that an item already finished executing (a real
+ * commit, `SUMMARY.md` written) before a coordinator crash left
+ * `BATCH.json` at `pending` (the STATE.md-row crash-window detection
+ * inside `resumeBatch` only fires once Step 9 has run). This mirrors the
+ * file-existence exclusion `planner-wave.md` already applies one layer
+ * earlier for `PLAN.md`, extracted as its own pure decision (rather than
+ * left as workflow prose only) so it is independently testable: given the
+ * eligible ids for this round and the subset the CALLER has already
+ * determined finished executing, splits them into ids safe to spawn now
+ * and ids that must never be re-dispatched.
+ */
+function filterAlreadyExecuted(eligibleIds, executedIds) {
+    const executedSet = executedIds instanceof Set ? executedIds : new Set(executedIds);
+    const spawnEligible = [];
+    const alreadyExecuted = [];
+    for (const id of eligibleIds) {
+        if (executedSet.has(id)) {
+            alreadyExecuted.push(id);
+        }
+        else {
+            spawnEligible.push(id);
+        }
+    }
+    return { spawnEligible, alreadyExecuted };
+}
+/**
+ * Build one `worktree.cleanup-wave` manifest entry for an item, deriving
+ * `files_modified`/`declared_deletions` FRESH from the item's own PLAN.md via
+ * the existing `parsePlanDocument` (never from `BATCH.json`'s `planned_files`
+ * alone — Open Question 2's accepted resolution). An empty `declared_deletions`
+ * for a plan that genuinely deletes nothing is indistinguishable from a plan
+ * that forgot to declare one — this is `partitionDeclaredDeletions`'s own
+ * pre-existing "absent/empty = declares nothing" convention, inherited here,
+ * not resolved.
+ */
+function buildCleanupManifestEntry(input) {
+    const parsed = parsePlanDocument(input.planContent);
+    const entry = {
+        agent_id: input.agentId,
+        worktree_path: input.worktreePath,
+        branch: input.branch,
+        expected_base: input.expectedBase,
+        files_modified: parsed.filesModified,
+        declared_deletions: parsed.filesDeleted,
+    };
+    if (input.allowedBases !== undefined) {
+        entry.allowed_bases = input.allowedBases;
+    }
+    return entry;
+}
+// ─── Exports ────────────────────────────────────────────────────────────────
+const quickBatchDispatch = {
+    parseQuickBatchArgs,
+    computeEffectiveConcurrency,
+    computeMergeOrder,
+    computeSpawnPlan,
+    routeVerificationOutcome,
+    routeMergeOutcome,
+    buildCleanupManifestEntry,
+    filterAlreadyExecuted,
+};
+module.exports = quickBatchDispatch;