* test(#3676): add failing tests for quick-batch dispatch core Failing-first tests for Phase 4 of epic #3344 (ADR-1239 "Quick-batch binding"): quick-batch-dispatch.test.cjs / .property.test.cjs cover the new pure decision-logic module (arg validation, effective concurrency, deterministic merge order, spawn backpressure, verification/merge routing, cleanup-entry construction — design doc rows 3-15,24,26-28, 30-36,39; property rows 51-53). quick-batch-update-items.test.cjs covers the new updateBatchItems export on src/quick-batch.cts (rows 15,22-23, including the negative cycle-rejection case). quick-batch-command-router.test.cjs covers the new gsd-tools quick-batch CLI family (rows 46-47). These reference modules/ exports that do not exist yet. * feat(#3676): implement quick-batch dispatch core, updateBatchItems, and command router Phase 4 of epic #3344 (ADR-1239 "Quick-batch binding") CORE decision layer — CLI verbs and pure orchestration logic only; no workflow markdown, no Agent()/git-worktree I/O. - src/quick-batch-dispatch.cts (new): pure decision functions consumed by the (separate, follow-up) /gsd:quick-batch workflow markdown — parseQuickBatchArgs, computeEffectiveConcurrency, computeMergeOrder, computeSpawnPlan, routeVerificationOutcome, routeMergeOutcome, buildCleanupManifestEntry (the last parses caller-supplied plan text via the existing parsePlanDocument; no filesystem access). - src/quick-batch.cts: adds updateBatchItems, resolving the design doc's Open Question 1 as ONE additive export on this module instead of the second, independent BATCH.json writer the design doc originally proposed. Reuses the same withPlanningLock transaction shape, computeWaves, and platformWriteSync call resumeBatch/ completeQuickItem already use; fails closed without persisting on an unknown item, an unknown/self dependency, or an introduced cycle. - src/quick-batch-command-router.cts (new): gsd-tools quick-batch CLI family, wired into HOST_COMMAND_ROUTERS (gsd-core/bin/gsd-tools.cjs) as a first-party always-on command (like /gsd:quick), not the opt-in capability-registry path graphify uses. Verbs: create/update/resume/ complete (wrap quick-batch.cts) and effective-concurrency/ merge-eligible/spawn-plan/verification-routing/merge-routing/ cleanup-entry/parse-args (wrap quick-batch-dispatch.cts). Design doc rows covered: 3-15, 22-24, 26-28, 30-39, 46-47. Property rows 51-53. Rows covering workflow markdown / Agent() dispatch / `git worktree` behavior (16-21, 25, 29, 40-45, 48-50) remain for the follow-up markdown-authoring pass, per the phase brief's explicit scope boundary. * docs(#3676): register quick-batch-dispatch/command-router modules in bookkeeping surfaces New-.cts-module ripple for the two Phase 4 modules (epic #3344, ADR-1239 "Quick-batch binding"): .gitignore (compiled .cjs artifacts, ADR-457 build-at-publish), eslint.config.mjs (lint the .cts source, not the emitted .cjs), docs/INVENTORY.md + docs/INVENTORY-MANIFEST.json (via `node scripts/gen-inventory-manifest.cjs --write`, after `npm run build:lib`), and CONTEXT.md glossary entries for "Quick-Batch Dispatch Core Module" and "Quick-Batch Command Router Module", plus an update to the existing "Quick-Batch Core Primitives Module" entry documenting the new updateBatchItems export. * test(#3676): fold updateBatchItems tests into quick-batch.test.cjs (fix lint-test-file-count) scripts/lint-test-file-count.cjs buckets any quick-batch-*.test.cjs file under the quick-batch production module by longest-prefix match, and that module is already at its 2-file cap (quick-batch.test.cjs + quick-batch.property.test.cjs). The standalone tests/quick-batch-update-items.test.cjs added in the prior commit pushed it to 3 and failed `npm run lint:ci`. Fold its content into quick-batch.test.cjs (append-only — no existing test in that file is modified) and update the CONTEXT.md glossary reference to match. Surfaced while re-running `GITHUB_BASE_REF=next npm run lint:ci` after `npm ci` (this worktree previously had no local node_modules, which also made gen-scripts-cli-exit/gen-hooks-cli-exit/gen-exit-code-* unable to resolve typescript — resolved by npm ci, no code change needed there). `npm run lint:ci` and `npx tsc -p tsconfig.build.json --noEmit` are both green after this fix. * test(#3676): add failing tests for the quick-batch command/workflow markdown Failing-first tests for Phase 4's markdown-authoring pass (epic #3344, ADR-1239 "Quick-batch binding"): gsd-quick-batch-workflow.test.cjs covers commands/gsd/quick-batch.md's frontmatter/objective/process, gsd-core/workflows/quick-batch.md's byte-size boundary (row 49, ADR 1610 NEW_FILE_CAP) and step-fragment count, the isolation model (rows 20-22), the executor single-writer invariant (row 18), merge validation reusing the existing bounded primitive (row 25), the optional research/plan-checker/verification leaves (rows 16,17,19, 30,31), planning-failure blocking execution (row 29), the submodule guard (rows 36,44), and the new agents/gsd-planner.md quick-batch mode (rows 13-15). gsd-quick-batch-quick-regression.test.cjs covers row 48 (ordinary /gsd:quick stays byte-identical). Named `gsd-quick-batch-*` (not `quick-batch-*`) so lint-test-file-count's longest-prefix bucketing doesn't fold these markdown-only tests into the already-capped quick-batch/quick-batch-dispatch/ quick-batch-command-router production-module buckets from the CORE pass. These reference files that do not exist yet. * feat(#3676): author the quick-batch command, workflow, and planner mode Phase 4 markdown-authoring pass (epic #3344, ADR-1239 "Quick-batch binding") — the orchestration layer that calls into Pass 1's CLI verbs (src/quick-batch-command-router.cts). - commands/gsd/quick-batch.md (new): frontmatter/objective/process, delegates argument validation to `quick-batch parse-args` (parseQuickBatchArgs) rather than re-deriving the grammar. - gsd-core/workflows/quick-batch.md (new, 11843 bytes — under ADR 1610's 32768-byte NEW_FILE_CAP for a brand-new file) + 9 lazy-loaded step fragments under gsd-core/workflows/quick-batch/steps/: resume-mode, batch-init, research-phase (flag:--research), planner-wave (+ nested plan-checker-loop when --validate), worktree-dispatch, merge-wave, verification-wave (flag:--validate), completion. Covers design doc rows 3-45: capacity/isolation resolution (reusing dispatch-isolation-gate.md verbatim), per-DAG- layer planning with full-task-catalog prompts and always-required depends_on/files_modified frontmatter, serialized worktree create/ merge/cleanup via the existing worktree.cleanup-wave primitive, deterministic wave-order merging, verification routing (human_needed/gaps_found), the executor single-writer invariant, submodule fail-loud guard, and #1941 fork-base auto-degrade. - agents/gsd-planner.md: additive new `load_mode_context` bullet for `**Mode:** quick-batch`, pointing at the new gsd-core/references/planner-quick-batch.md reference (documents the always-required depends_on/files_modified contract, reusing the existing frontmatter grammar — no new keys). Existing modes byte-identical, only a new bullet added. - src/init.cts (+init-command-router.cts, +command-aliases.cts): cmdInitQuickBatch / `init.quick-batch` — model profiles, commit_docs, roadmap/planning existence checks, and the section_manifest field gating research-phase/verification-wave (reuses the existing flag:--research/flag:--validate WHEN_VOCABULARY atoms — no new atom needed). Rows 16-21, 25, 29, 36, 38, 39, 44, 46-50 covered structurally by the prior test(#3676) commit; rows 3-15, 22-24, 26-28, 30-35, 37, 40-43, 45 covered by construction (verb wiring, single-writer prompt constraints, crash-window resume via unmodified Phase 3 primitives). * docs(#3676): regenerate skills/inventory/section-manifest/install-tree; baseline the intentional word-splitting pattern npm run regen:derived output for the new command/workflow/reference (epic #3344, ADR-1239 "Quick-batch binding"): - skills/gsd-quick-batch/SKILL.md (generated from commands/gsd/quick-batch.md) - docs/INVENTORY.md rows for /gsd-quick-batch, quick-batch.md, planner-quick-batch.md, and the quick-batch-dispatch.cjs/ quick-batch-command-router.cjs CLI-module rows' now-live `/gsd-quick-batch` cross-reference (was "(separate, follow-up)") + docs/INVENTORY-MANIFEST.json (`node scripts/gen-inventory-manifest.cjs --write`) - gsd-core/workflows/section-manifest.json (`npm run gen:section-manifest`) — research-phase/verification-wave gsd:section entries for the new quick-batch workflow - tests/fixtures/install-tree/*.json (`npm run gen:install-tree`) — the new command/workflow/skill/reference files now ship to every runtime scripts/lint-workflow-shellcheck-baseline.json: 3 new entries for gsd-core/workflows/quick-batch.md's intentional flag-token/$ARGUMENTS word-splitting (SC2046/SC2086) — the same deliberate unquoted-optional- flag pattern gsd-core/workflows/quick.md already carries baselined (e.g. `$DISCUSS_PARAM $RESEARCH_PARAM` in quick.md's own Step 2); quoting would break the intended "omit this arg when the flag is false" splitting. * fix(#3676): close prompt-injection and argv/glob-injection gaps in quick-batch leaf dispatch Security review pass findings, both confirmed real: 1. HIGH — prompt injection, no boundaries. Every leaf-dispatch fragment interpolated the raw, attacker-influenced task ${description} (and the shared ${TASK_CATALOG_TABLE}, broadcasting every item's raw description into every planner's prompt in the layer) straight into Agent() prompt bodies with no boundary. Fixed by wrapping every such interpolation in a <security_context> + DATA_START/DATA_END boundary, matching the CONCRETE convention already implemented in this repo (agents/gsd-debug-session-manager.md, agents/gsd-debugger.md, gsd-core/workflows/debug.md) — commands/gsd/quick.md's own <security_notes> only asserts this convention in prose, so the debug-agent files are the real precedent followed here. Added a new <security_notes> block to commands/gsd/quick-batch.md (it had none) documenting both this fix and the one below. 2. MEDIUM — unquoted $ARGUMENTS -> argv/glob injection. gsd-core/workflows/quick-batch.md and commands/gsd/quick-batch.md both ran `gsd_run quick-batch parse-args --raw -- $ARGUMENTS` UNQUOTED, causing shell word-splitting and pathname expansion on raw task-list text before the parser ever saw it. Fixed at the source: added a `--text <string>` form to the `parse-args` verb (src/quick-batch-command-router.cts) that accepts the ENTIRE $ARGUMENTS as ONE quoted argv element and does the whitespace split itself, in Node — which is never glob-aware, unlike the shell. Both call sites now use `--text "$ARGUMENTS"`. The `-- <tokens>` form is kept for direct/test callers that already have a real argv array. The SC2086 baseline entry added for the original unquoted line is now stale (`node scripts/lint-workflow-shellcheck.cjs` no longer reports it) and has been removed; the two SC2046 entries for the UNRELATED, still-unquoted `$([ "$VALIDATE_MODE" = true ] && echo --validate)`-style conditional-flag splitting remain — that line only ever expands to one of a few known-safe literal strings (never raw user text), matching quick.md's own already-baselined convention exactly. Tests: quick-batch-command-router.test.cjs covers the new --text form (token splitting, glob-shaped text passing through literally unexpanded, whitespace-only input). gsd-quick-batch-workflow.test.cjs asserts the DATA_START/DATA_END boundary on every leaf prompt (research-phase/planner-wave/plan-checker-loop/verification-wave, including the shared task catalog) and the quoted --text call sites. * fix(#3676): strengthen test-depth gaps in rows 9, 18, 24, 34, 35 Spec review pass findings — the test matrix claimed "yes" coverage these assertions did not actually support: - Row 9 (--jobs 0/-1/abc hostile case): previously asserted rejection only. Added an end-to-end assertion (tests/quick-batch-command-router.test.cjs, committed alongside the security fix that touches the same file) that .planning/quick-batches/ is never created for any rejected value — createBatch is genuinely never reached. - Row 18 (--resume <unknown-batch-id>): previously only exercised a hand-corrupted BATCH.json, never a genuinely nonexistent batch directory. Added the real nonexistent-id case (also in quick-batch-command-router.test.cjs). - Row 24 (post-planning updateBatchItems racing a concurrent completeQuickItem for a different item, both through withPlanningLock): zero test existed. Added a property test (tests/quick-batch.property.test.cjs, appended — Phase 3's own file, no existing test touched) exercising both call orders and asserting no lost update in the final on-disk manifest — the same technique Phase 3's own row-15 lock-contention property test uses (sequential calls through the real lock; a working mutex makes any interleaving equivalent to some serial order, so this is the same claim a literal concurrent-thread test would make without OS-level threading). - Row 34 (worktree preserved on merge_failed) and row 35 (undeclared- deletion detection): both were previously asserted only at the pure routeMergeOutcome level. Added tests/gsd-quick-batch-merge-integration.test.cjs using the SAME real-git-fixture pattern tests/worktree-safety.test.cjs already establishes for executeWorktreeWaveCleanupPlan (real repo, real worktree, a REAL merge conflict / a REAL file deletion diffed against declared_deletions) — asserting the actual worktree directory survives on disk, not just that a pure function returns a preserveWorktree:true field. Named gsd-quick-batch-* so lint-test- file-count's bucketing doesn't fold it into any capped module bucket. Row 48 (/gsd:quick regression) intentionally left as-is per the reviewer's own framing: the byte-identity claim is already mechanically proven by the changed-path diff (git diff --name-only empty on those two paths IS byte-identity), and a genuine execution- level regression test would require actually running the workflow — out of scope for this repo's unit-test model (no other quick.md regression test in this repo does that either). * docs(#3676): add the changeset and user-facing docs the command needed Standards review pass findings — both HARD: - Missing changeset. None of the 6 prior #3676 commits touched .changeset/*. /gsd-quick-batch is a new user-facing command; CLAUDE.md/CONTRIBUTING.md require one. Added .changeset/silly-rams-caper.md (type: Added, pr: 0 placeholder — backfilled after the PR opens, matching CLAUDE.md's own documented convention and Phase 3's own precedent, #4190's .changeset/mellow-yaks-squeak.md). Uses the docs-convention hyphen form `/gsd-quick-batch` throughout, never the source-artifact colon form (`scripts/lint-docs-command-form.cjs` confirms 0 violations; that check scans docs/**, not .changeset/, so it was never actually in scope for the fragment itself, but the wording still follows the doc convention for consistency, matching how Phase 3's own fragment named the not-yet-shipped command). - Missing docs. Added docs/how-to/batch-quick-tasks.md (Diátaxis how-to, matching docs/how-to/handle-quick-and-fast-tasks.md's existing convention for /gsd-quick /gsd-fast) covering --jobs, --validate, --research, --resume, --file, the capacity/isolation interaction, and resume/failure recovery. Cross-linked from docs/README.md's how-to index and from handle-quick-and-fast-tasks.md's own "Related" section. Added a /gsd-quick-batch section to docs/COMMANDS.md (same table format as the existing /gsd-quick entry) and docs/features/quick-batch.md (REQ-QB-01..12, same frontmatter shape as docs/features/quick-mode.md) — regenerated docs/FEATURES.md (179 features) and skills/gsd-quick-batch/SKILL.md via the standard generators. * fix(#3676): close docs-parity, attribution, and generated-registry gaps gsd-test caught gsd-test's real run against 155e8975b3 found 43 failures, all rooted in this phase's own new command/workflow never being registered across ~10 independent generated/hand-maintained registries this repo keeps in parity by convention. Root-caused each, no test weakened or special-cased. - help.md ↔ commands/gsd/ bidirectional parity (docs-parity-live- registry.test.cjs): added a /gsd:quick-batch entry to gsd-core/workflows/help/modes/full.md (the real help.md content; gsd-core/workflows/help.md is a thin dispatcher) documenting every flag (--file/--jobs/--validate/--research/--resume), matching the existing /gsd:quick entry's format. - gen-section-manifest.test.cjs: quick-batch.md's `gsd_run query init.quick-batch` invocation used inline `$([ ... ] && echo --flag)` substitutions, which never satisfy the test's exact-whitespace-token / assigned-variable detection (the trailing `))` glued onto `--research` in the compound substitution broke the "exact token" match). Rewrote to the same VALIDATE_PARAM/RESEARCH_PARAM two-line pattern gsd-core/workflows/quick.md's own Step 2 already uses. - runtime-launcher-parity.test.cjs: the 8 quick-batch/steps/*.md fragments that call gsd_run each needed their OWN embedded copy of the canonical shim preamble (every workflow .md that calls gsd_run carries its own copy — reading one file does not persist shell state into another). Ran `node scripts/sync-runtime-launcher.cjs`, which inserted it before each file's first gsd_run call. plan-checker-loop.md correctly has none — it never calls gsd_run directly. - Namespace routing (skill-manifest.test.cjs, install-nested- layout.test.cjs, runtime-artifact-layout-surface.test.cjs): added `quick-batch` to commands/gsd/ns-workflow.md's `requires:` array and routing table (same namespace `quick` already routes through), and to src/clusters.cts's `utility` cluster (same cluster `quick` already belongs to). Verified by hand-running installRuntimeArtifacts + applySurface for augment/cline against a real temp install: exactly 6 top-level gsd-ns-* router dirs, gsd-quick-batch correctly nested under gsd-ns-workflow/skills/, never re-flattened. - mcp-server-catalog.test.cjs: hardcoded command count 71 -> 72 (a brand-new command is a real count change, not a bug this test should hide). - model-omit-when-inherit-guard.test.cjs: added the canonical `<!-- #2517 model-omit-on-inherit -->` marker block to gsd-core/workflows/quick-batch.md (every leaf dispatch — planner/ researcher/checker/executor/verifier — lives in a steps/ fragment, read combined with the host by this test's own readWorkflowCombined, same as quick.md's own research-phase.md carries it for its gated section). Also fixed a genuine pre-existing inconsistency in the test's own "#2711: the guarded set is derived from dispatch sites" check: its `nonDispatching` computation read the BARE host file while `derived` (the set it's checked against) reads the combined host+steps content — inconsistent with that same test file's own #2994 doc comment explaining why the combined read is necessary. quick-batch.md is the first workflow whose EVERY model="{...}" dispatch site lives in a mandatory (never gated) steps/ fragment — extracted to stay under ADR-1610's tighter NEW_FILE_CAP for a brand-new file — which is what exposed the mismatch. Fixed by using the same readWorkflowCombined read in both places. - skill-frontmatter-contract.test.cjs: shortened commands/gsd/quick-batch.md's frontmatter `description` from 107 to 91 chars (<=100 budget), and added `quick-batch.md` to the hand- maintained KNOWN_SKILLS consolidation allowlist with a #3676 justification comment (a genuinely new first-party command, not a consolidation of an existing skill). - workflow-fragments-emission.install.test.cjs: added `quick-batch.md` to the hand-maintained MARKED_WORKFLOWS set (composeWorkflow is deliberately NOT a no-op for it — its research-phase/verification- wave sections are gated). - Regenerated all downstream artifacts (npm run build:lib && npm run regen:derived && npm run gen:plugin-skills -- --write && npm run gen:features -- --write): skills/gsd-quick-batch/SKILL.md, skills/gsd-ns-workflow/SKILL.md, install-tree fixtures for augment/cline/hermes/qwen/trae/zcode. - emitted-attribution.test.cjs: agents/gsd-planner.md's #3676 addition (one new `load_mode_context` bullet pointing at the new gsd-core/references/planner-quick-batch.md reference) grew the file 124 bytes without an acknowledgment trailer. Acknowledged below — the growth is the deliberate, additive, single-bullet change from the earlier feat(#3676) commit, not drift. Verified: npm run build:lib clean, npx tsc -p tsconfig.build.json --noEmit clean, GITHUB_BASE_REF=next npm run lint:ci fully green (includes lint-workflow-shellcheck, lint-test-file-count, lint-docs-command-form). The deep install/spawn/registry tests gsd-test actually runs (docs-parity-live-registry, gen-section-manifest, runtime-launcher-parity, install-nested-layout, runtime-artifact-layout-surface, skill-manifest, skill-frontmatter- contract, mcp-server-catalog, model-omit-when-inherit-guard, workflow-fragments-emission) are not part of lint:ci — each fix above was independently verified by hand-invoking the exact production function the failing test calls (installRuntimeArtifacts, applySurface, composeWorkflow, the CLUSTERS union, the section-manifest forwarding regex) against the real repo tree and confirming the expected shape. Emitted-Drift-Ack-Growth: gsd-planner.md — additive #3676 quick-batch mode bullet in load_mode_context (one new line pointing at gsd-core/references/planner-quick-batch.md); not drift. * fix(#3676): trim the /gsd:quick-batch help.md entry to fit the LARGE tier line budget skill-frontmatter-contract.test.cjs's "feature #3039: tiered help — size budgets" enforces a SEPARATE line-count ceiling for gsd-core/workflows/help/modes/full.md (FULL_BUDGET = 844 lines, tighten-only ratchet, scripts/lib/allowlist-ratchet.cjs's assertTightCeiling) — independent of the skill-frontmatter description- length budget and consolidation allowlist I touched in the prior round; those are unrelated checks in the same test FILE, not the same check. Root cause: the /gsd:quick-batch entry I added to full.md in the docs-parity fix round was 17 lines, pushing the file from 834 to 851 lines — 7 over the 844 ceiling. Condensed the entry (merged the per-flag bullet list into one dense "Flags:" line, dropped from 3 Usage examples to 1) to 844 lines exactly — at the ceiling with zero slack, which assertTightCeiling accepts (it only fails on actualMax > ceiling, or on slack > grace when the ceiling is too LOOSE — zero slack triggers neither). Verified after trimming: full.md still contains a live /gsd:quick-batch reference (bidirectional parity) and all 5 argument-hint flags (--jobs/--validate/--research/--resume/--file) still appear as literal tokens (docs-parity-live-registry.test.cjs's own flag-coverage check, re-run by hand against the trimmed content). Verified: npm run build:lib clean, npx tsc -p tsconfig.build.json --noEmit clean, GITHUB_BASE_REF=next npm run lint:ci fully green. * docs(#3676): backfill changeset pr number to 4212 Follow-up to fix(#3676) commits — .changeset/silly-rams-caper.md's pr:0 placeholder backfilled with the real PR number now that gh api POST /pulls has returned it (#4212). Matches CLAUDE.md's PR Number Handling convention and Phase 3's own #4190 precedent (708c5a3f8c). Doc-only (root-level .changeset/*.md fragment), exempt from a fresh gsd-test run per pre-pr-gate.sh's DOC_ONLY_RE. * fix(#3676): resolve prompt-injection-scan false positive on test fixture tests/quick-batch.test.cjs:232's row 11b regression proves the task-list parser carries a prompt-injection-shaped task description through createBatch as inert data, never interpreted. The fixture has to be a real "ignore all previous instructions..." phrase or the test asserts nothing, but the full-file --diff scan flagged it once unrelated edits in the same file pulled it into the changed-file set. Add the file to prompt-injection-scan.sh's ALLOWLIST, matching the sanctioned, precedented exemption already used for other legitimate security-regression fixtures (tests/windsurf-conversion.test.cjs, tests/health-validation.test.cjs, tests/continuation-grammar-parity.test.cjs) per DEFECT.PROMPT-INJECTION-SCAN-COLLISION. --------- Co-authored-by: sim <sim@local>
This commit is contained in:
Tom Boucher
@@ -998,6 +998,31 @@ Granular flags are composable: `--discuss --research --validate` is equivalent t
|
||||
/gsd-quick resume my-task-slug # Resume a quick task
|
||||
```
|
||||
|
||||
### `/gsd-quick-batch`
|
||||
|
||||
Batch several `/gsd-quick`-shaped tasks together — one coordinator plans, dispatches, and merges them as one run (#3676, epic #3344, ADR-1239 "Quick-batch binding"). See [Batch quick tasks](how-to/batch-quick-tasks.md) for a walkthrough.
|
||||
|
||||
| Argument | Description |
|
||||
|----------|-------------|
|
||||
| Inline task list | A bulleted or numbered list, ≥2 items, one per line |
|
||||
| `--file <path>` | Read the task list from a file instead of inline text |
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--jobs auto\|N` | `auto` (default) uses the negotiated dispatch capacity as-is; `N` caps effective concurrency at `min(task count, N, capacity)` |
|
||||
| `--validate` | Per-item plan-checker loop (max 2 iterations) + post-merge verification |
|
||||
| `--research` | Per-item researcher dispatched before planning |
|
||||
| `--resume <batch-id>` | Skip task-list parsing and batch creation; dispatch only the batch's still-eligible items |
|
||||
|
||||
**Not supported in v1:** `--discuss` and `--full` are rejected with a usage error before any dispatch — run `/gsd-quick --discuss`/`--full` per item instead.
|
||||
|
||||
```bash
|
||||
/gsd-quick-batch "- fix the login timeout\n- add the retry banner" # inline list
|
||||
/gsd-quick-batch --file .planning/my-tasks.md # from a file
|
||||
/gsd-quick-batch --jobs 3 --validate "- item one\n- item two\n- item three"
|
||||
/gsd-quick-batch --resume 260101-abc # resume an interrupted batch
|
||||
```
|
||||
|
||||
### `/gsd-autonomous`
|
||||
|
||||
Run all remaining phases autonomously.
|
||||
|
||||
@@ -25,6 +25,7 @@
|
||||
- [Freeform Routing](#12-freeform-routing)
|
||||
- [Note Capture](#13-note-capture)
|
||||
- [Auto-Advance (Next)](#14-auto-advance-next)
|
||||
- [Quick Batch Mode](#4015-quick-batch-mode)
|
||||
- [Quality Assurance Features](#quality-assurance-features)
|
||||
- [Nyquist Validation](#15-nyquist-validation)
|
||||
- [Plan Checking](#16-plan-checking)
|
||||
@@ -603,6 +604,28 @@
|
||||
| Phase executed but no VERIFICATION.md | Run `/gsd-verify-work` |
|
||||
| All phases complete | Suggest `/gsd-complete-milestone` |
|
||||
|
||||
---
|
||||
|
||||
### 4015. Quick Batch Mode
|
||||
|
||||
**Command:** `/gsd-quick-batch [--file <path>] [--jobs auto|N] [--validate] [--research] [--resume <batch-id>]`
|
||||
|
||||
**Purpose:** Batch several `/gsd-quick`-shaped tasks together — one coordinator plans, dispatches, and merges them as a single run, with per-item leaves and deterministic merge ordering (ADR-1239 "Quick-batch binding").
|
||||
|
||||
**Requirements:**
|
||||
- REQ-QB-01: System MUST accept an inline task list (≥2 items) or `--file <path>`
|
||||
- REQ-QB-02: System MUST reject `--discuss` and `--full` with a usage error before any dispatch
|
||||
- REQ-QB-03: System MUST reject a malformed `--jobs` value before any dispatch
|
||||
- REQ-QB-04: System MUST resolve effective concurrency as `min(task count, jobsN, capacity)` for `--jobs N`, or `capacity` alone for `--jobs auto`
|
||||
- REQ-QB-05: System MUST force a mutating (worktree/executor) wave's concurrency to 1 when isolation is `none`, without capping a non-mutating (research/planning-only) wave
|
||||
- REQ-QB-06: System MUST dispatch a planner per eligible item per DAG layer, providing the full batch task catalog and always requiring `depends_on`/`files_modified` frontmatter
|
||||
- REQ-QB-07: System MUST recompute execution waves after each planning layer from the planners' declared dependencies/files
|
||||
- REQ-QB-08: System MUST serialize worktree create/merge/cleanup while allowing already-created worktrees to run concurrently
|
||||
- REQ-QB-09: System MUST merge items strictly in the deterministic wave order, never completion order
|
||||
- REQ-QB-10: System MUST NOT call the STATE.md completion primitive for an item routed to `human_needed`
|
||||
- REQ-QB-11: System MUST fail an item routed to `gaps_found`/`merge_failed`/`scope_violation` without rollback, without an automatic retry, and with its worktree preserved
|
||||
- REQ-QB-12: System MUST support `--resume <batch-id>` to re-derive eligibility and dispatch only still-runnable items, refusing closed on an unknown batch id or a diverged base revision
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -88,6 +88,7 @@
|
||||
"/gsd-profile-user",
|
||||
"/gsd-progress",
|
||||
"/gsd-quick",
|
||||
"/gsd-quick-batch",
|
||||
"/gsd-resume-work",
|
||||
"/gsd-review",
|
||||
"/gsd-review-backlog",
|
||||
@@ -169,6 +170,7 @@
|
||||
"pr-branch.md",
|
||||
"profile-user.md",
|
||||
"progress.md",
|
||||
"quick-batch.md",
|
||||
"quick.md",
|
||||
"reapply-patches.md",
|
||||
"remove-phase.md",
|
||||
@@ -264,6 +266,7 @@
|
||||
"planner-load-graph-context.md",
|
||||
"planner-mvp-mode.md",
|
||||
"planner-preconditions.md",
|
||||
"planner-quick-batch.md",
|
||||
"planner-reversibility.md",
|
||||
"planner-reviews.md",
|
||||
"planner-revision.md",
|
||||
@@ -478,6 +481,8 @@
|
||||
"prohibition-enforcement.cjs",
|
||||
"project-root.cjs",
|
||||
"prompt-budget.cjs",
|
||||
"quick-batch-command-router.cjs",
|
||||
"quick-batch-dispatch.cjs",
|
||||
"quick-batch.cjs",
|
||||
"real-home-guard.cjs",
|
||||
"refactor-trigger-command-router.cjs",
|
||||
@@ -635,6 +640,15 @@
|
||||
"plan-phase/steps/windows-troubleshooting.md",
|
||||
"progress/steps/forensic-audit.md",
|
||||
"progress/steps/mvp-display.md",
|
||||
"quick-batch/steps/batch-init.md",
|
||||
"quick-batch/steps/completion.md",
|
||||
"quick-batch/steps/merge-wave.md",
|
||||
"quick-batch/steps/plan-checker-loop.md",
|
||||
"quick-batch/steps/planner-wave.md",
|
||||
"quick-batch/steps/research-phase.md",
|
||||
"quick-batch/steps/resume-mode.md",
|
||||
"quick-batch/steps/verification-wave.md",
|
||||
"quick-batch/steps/worktree-dispatch.md",
|
||||
"quick/steps/discussion-phase.md",
|
||||
"quick/steps/plan-checker-loop.md",
|
||||
"quick/steps/quick-verification.md",
|
||||
|
||||
@@ -24,9 +24,9 @@ Full roster at `agents/gsd-*.md`. The "Primary doc" column flags whether [`docs/
|
||||
| gsd-assumptions-analyzer | Produces evidence-backed assumptions for discuss-phase (assumptions mode). | `discuss-phase-assumptions` workflow | primary |
|
||||
| gsd-advisor-researcher | Researches a single gray-area decision during discuss-phase advisor mode. | `discuss-phase` workflow (advisor mode) | primary |
|
||||
| gsd-research-synthesizer | Combines parallel researcher outputs into a unified SUMMARY.md. | `/gsd-new-project` | primary |
|
||||
| gsd-planner | Creates executable phase plans with task breakdown and goal-backward verification. | `/gsd-plan-phase`, `/gsd-quick` | primary |
|
||||
| gsd-planner | Creates executable phase plans with task breakdown and goal-backward verification. | `/gsd-plan-phase`, `/gsd-quick`, `/gsd-quick-batch` | primary |
|
||||
| gsd-roadmapper | Creates project roadmaps with phase breakdown and requirement mapping. | `/gsd-new-project` | primary |
|
||||
| gsd-executor | Executes GSD plans with atomic commits and deviation handling. | `/gsd-execute-phase`, `/gsd-quick` | primary |
|
||||
| gsd-executor | Executes GSD plans with atomic commits and deviation handling. | `/gsd-execute-phase`, `/gsd-quick`, `/gsd-quick-batch` | primary |
|
||||
| gsd-plan-checker | Verifies plans will achieve phase goals (8 verification dimensions). | `/gsd-plan-phase` (verification loop) | primary |
|
||||
| gsd-integration-checker | Verifies cross-phase integration and end-to-end flows. | `/gsd-audit-milestone` | primary |
|
||||
| gsd-ui-checker | Validates UI-SPEC.md design contracts against quality dimensions. | `/gsd-ui-phase` (validation loop) | primary |
|
||||
@@ -97,6 +97,7 @@ These six routers are descriptor-only entries that the model picks first; the bo
|
||||
| `/gsd-ship` | Create PR, run review, and prepare for merge after verification. | [commands/gsd/ship.md](../commands/gsd/ship.md) |
|
||||
| `/gsd-fast` | Execute a trivial task inline — no subagents, no planning overhead. | [commands/gsd/fast.md](../commands/gsd/fast.md) |
|
||||
| `/gsd-quick` | Execute a quick task with GSD guarantees (atomic commits, state tracking) but skip optional agents. | [commands/gsd/quick.md](../commands/gsd/quick.md) |
|
||||
| `/gsd-quick-batch` | Batch several `/gsd-quick`-shaped tasks together — one coordinator plans, dispatches, and merges them (#3676, epic #3344, ADR-1239 "Quick-batch binding"). | [commands/gsd/quick-batch.md](../commands/gsd/quick-batch.md) |
|
||||
| `/gsd-ui-review` | Retroactive 6-pillar visual audit of implemented frontend code. | [commands/gsd/ui-review.md](../commands/gsd/ui-review.md) |
|
||||
| `/gsd-code-review` | Review source files changed during a phase for bugs, security, and code-quality problems; use `--fix` to auto-apply findings. | [commands/gsd/code-review.md](../commands/gsd/code-review.md) |
|
||||
| `/gsd-eval-review` | Retroactively audit an executed AI phase's evaluation coverage; produces EVAL-REVIEW.md. | [commands/gsd/eval-review.md](../commands/gsd/eval-review.md) |
|
||||
@@ -236,6 +237,7 @@ Full roster at `gsd-core/workflows/*.md`. Workflows are thin orchestrators that
|
||||
| `pr-branch.md` | Create a clean branch for pull requests by filtering `.planning/` commits. | `/gsd-pr-branch` |
|
||||
| `profile-user.md` | Orchestrate the full developer profiling flow — consent, session scan, profile generation. | `/gsd-profile-user` |
|
||||
| `progress.md` | Progress rendering — project context, position, and next-action routing. | `/gsd-progress` |
|
||||
| `quick-batch.md` | Batch several `/gsd-quick`-shaped tasks together — planner/researcher/checker/executor/verifier leaves per item, deterministic wave dispatch and merge, one coordinator owning every shared write (#3676, epic #3344, ADR-1239 "Quick-batch binding"). | `/gsd-quick-batch` |
|
||||
| `quick.md` | Quick-task execution with GSD guarantees (atomic commits, state tracking). | `/gsd-quick` |
|
||||
| `reapply-patches.md` | Reapply local modifications after a GSD update. | `/gsd-update --reapply` |
|
||||
| `remove-phase.md` | Remove a future phase from the roadmap and renumber subsequent phases. | `/gsd-phase --remove` |
|
||||
@@ -418,6 +420,7 @@ The `gsd-planner` agent is decomposed into a core agent plus reference modules t
|
||||
| `planner-chunked.md` | Chunked mode return formats (`## OUTLINE COMPLETE`, `## PLAN COMPLETE`) for Windows stdio hang mitigation. |
|
||||
| `planner-gap-closure.md` | Gap-closure mode behavior (reads VERIFICATION.md, targeted replanning). |
|
||||
| `planner-guidance.md` | Expository planner guidance: philosophy, task types/sizing, interface-first ordering, user setup, dependency graph, granularity calibration, and structured-return templates. |
|
||||
| `planner-quick-batch.md` | Quick-batch mode behavior (#3676, epic #3344, ADR-1239 "Quick-batch binding"): `depends_on`/`files_modified` frontmatter ALWAYS required (never gated on `--validate`), referencing only sibling `quick_id`s from the batch task catalog — reuses the existing frontmatter grammar, no new keys. |
|
||||
| `planner-reviews.md` | Cross-AI review integration (reads REVIEWS.md from `/gsd-review`). |
|
||||
| `planner-revision.md` | Plan revision patterns for iterative refinement. |
|
||||
| `planner-source-audit.md` | Planner source-audit and authority-limit rules. |
|
||||
@@ -603,7 +606,9 @@ Full listing: `gsd-core/bin/lib/*.cjs`.
|
||||
| `profile-pipeline-command-router.cjs` | ADR-959 capability command router for the profile-pipeline command family — dispatches scan-sessions, extract-messages, profile-sample (pipeline phase) and write-profile, profile-questionnaire, generate-dev-preferences, generate-claude-profile, generate-claude-md (output phase); phase 6 cutover |
|
||||
| `profile-pipeline.cjs` | User behavioral profiling data pipeline, session file scanning |
|
||||
| `prompt-budget.cjs` | Pure token-budget accounting for review prompts — estimates tokens, applies deterministic trim priority (head-shrink PROJECT.md, proportional plan truncation, drop context/research/requirements, hard-fail guard), returns structured metadata for `review.max_prompt_tokens` (#3081) |
|
||||
| `quick-batch.cjs` | Quick-batch core primitives (#3675, ADR-1239 "Quick-batch binding") — task-list parsing (inline + path-confined `--file`), collision-safe `YYMMDD-xxx` quick-id preallocation under `withPlanningLock` (checked against both on-disk `.planning/quick/` entries and sibling `.planning/quick-batches/*/BATCH.json` manifests), `BATCH.json` schema/validation/resume (fail-closed on corrupt JSON, schema violations, out-of-batch dependency references, cycles, or a missing worktree path), deterministic wave construction combining dependency-DAG layering with `partitionByFileOverlap` over normalized `planned_files`, and exactly-once STATE.md completion via `hasQuickTaskRow`'s own idempotency check ahead of the unmodified `appendQuickTaskRow`. No agent dispatch, no worktree creation, no user-facing command — Phase 4/#3676's job. Compiled from `src/quick-batch.cts` |
|
||||
| `quick-batch-command-router.cjs` | Thin CJS subcommand router for `gsd-tools quick-batch` (#3676, Phase 4 of epic #3344 / ADR-1239 "Quick-batch binding"; compiled from `src/quick-batch-command-router.cts`, gitignored) — a first-party, always-on command family wired directly into `HOST_COMMAND_ROUTERS` (like `state`/`phase`), NOT the opt-in capability-registry/`activationKey` path `graphify` uses. Verbs: `create`/`update`/`resume`/`complete` (thin wrappers over `quick-batch.cjs`'s durable manifest read/write) and `effective-concurrency`/`merge-eligible`/`spawn-plan`/`verification-routing`/`merge-routing`/`cleanup-entry`/`parse-args` (thin wrappers over `quick-batch-dispatch.cjs`'s pure decision logic). Follows `graphify-command-router.cts`'s `routeHubCommandFamily` shape, which gives the Hub's `makeUnknownCommand` handling for free on an unrecognized subcommand |
|
||||
| `quick-batch-dispatch.cjs` | Quick-batch dispatch decision core (#3676, Phase 4 of epic #3344 / ADR-1239 "Quick-batch binding"; compiled from `src/quick-batch-dispatch.cts`, gitignored) — PURE decision logic consumed by the `/gsd-quick-batch` workflow markdown: `parseQuickBatchArgs` (rejects `--discuss`/`--full`, validates `--jobs auto\|N`, before any dispatch), `computeEffectiveConcurrency` (`min(taskCount, jobsN, capacity)`, `isolation:'none'` forces a MUTATING wave to concurrency 1, a non-mutating research-only wave is unaffected), `computeMergeOrder` (deterministic wave-order merge prefix — never completion order, an out-of-order finisher waits), `computeSpawnPlan` (backpressure — a refused/capacity-exhausted spawn returns to `pending`, never increases fan-out, never `failed`), `routeVerificationOutcome`/`routeMergeOutcome` (small explicit state-transition functions for `human_needed`/`gaps_found`/`merge_failed`/`scope_violation` routing — a scope violation or merge failure always preserves the worktree), and `buildCleanupManifestEntry` (derives a `worktree.cleanup-wave` entry's `files_modified`/`declared_deletions` FRESH from an item's own PLAN.md via the existing `parsePlanDocument`, never from `BATCH.json`). No `Agent()` dispatch, no `git worktree` I/O — those stay in workflow markdown |
|
||||
| `quick-batch.cjs` | Quick-batch core primitives (#3675, ADR-1239 "Quick-batch binding") — task-list parsing (inline + path-confined `--file`), collision-safe `YYMMDD-xxx` quick-id preallocation under `withPlanningLock` (checked against both on-disk `.planning/quick/` entries and sibling `.planning/quick-batches/*/BATCH.json` manifests), `BATCH.json` schema/validation/resume (fail-closed on corrupt JSON, schema violations, out-of-batch dependency references, cycles, or a missing worktree path), deterministic wave construction combining dependency-DAG layering with `partitionByFileOverlap` over normalized `planned_files`, and exactly-once STATE.md completion via `hasQuickTaskRow`'s own idempotency check ahead of the unmodified `appendQuickTaskRow`. Also exports `updateBatchItems` (#3676) — the ONE additive post-planning mutator: applies caller-resolved `depends_on`/`planned_files` updates, recomputes `wave` for every item via the existing `computeWaves`, and fails closed WITHOUT persisting on an unknown item, an unknown/self dependency, or an introduced cycle, inside the SAME `withPlanningLock` transaction shape `resumeBatch`/`completeQuickItem` already use — never a second, independent writer against `BATCH.json`. No agent dispatch, no worktree creation, no user-facing command — Phase 4/#3676's job. Compiled from `src/quick-batch.cts` |
|
||||
| `observability/redaction.cjs` | Arg redaction policy for dispatch events — args omitted from every emitted event by default, opt-in verbatim inclusion via `GSD_AUDIT_ARGS=1`; stateless env read, no module-level caching (#177) |
|
||||
| `real-home-guard.cjs` | Real-home confinement guard (#3712; renamed from `test-home-guard.cjs` — a source filename matching Node's `test-*` convention is collected and executed as a test by the remote runner) — refuses any of the six writers that resolve a kind `home` — `installRuntimeArtifacts`, `uninstallRuntimeArtifacts`, `applySurface`, `migrateLegacyDevPreferencesToSkill`, plus the descriptor-dependent `installOpencodeFamilySkills` and `installAgentsKindStandalone` when a `node --test` run would resolve a kind's global `home` override (codex skills -> `$HOME/.agents`, ADR-1239/#2088) inside the real passwd home, which silently pruned every `gsd-*` skill there; compares homes by filesystem identity (`st_dev`+`st_ino`) rather than by pathname, since a case-variant, symlinked, or bind-mounted HOME names one directory under two names; fails CLOSED unless both homes identify or one is definitively absent (the pathname-equality shortcut in `sameDirectory` can answer yes without identifying, so the marker branch requires the marker to identify separately before it may allow anything); a destination inside the real home is exempted only when HOME differs from the passwd home, the passwd home is not itself beneath that HOME (`/Users`, `C:\Users` are not sandboxes), and the destination resolves beneath it (Windows puts the temp root inside the home, so containment alone cannot tell a sandbox from the danger); where no passwd entry is readable it falls back to `sandboxHome()`'s path-valued marker, which must identify AND contain every resolved destination — a marker matching HOME attests only that HOME was sandboxed, so on its own it waved through a layout captured before the sandbox that still named the real `~/.agents`; it remains a deliberate weakening rather than a closed door, since nothing there can contradict a marker naming the real home; does not defend against a subordinate bind mount of the real directory into the sandbox (realpath cannot unify bind-mounted spellings) or a cross-process TOCTOU swap; inert for normal installs outside a Node test context |
|
||||
| `refactor-trigger-command-router.cjs` | ADR-959 capability command router for `gsd-tools refactor` (issue #1953) — dispatches evaluate/status/accept/decline subcommands for the complexity-triggered refactor capability; owns capability-activation gating, git invocation (via the `git-base-branch.cjs` `phaseStartCommit`/`changedFilesSince` adapters), config reads, phase-directory resolution, and the optional broken-windows ledger integration around the pure `complexity-trigger.cjs` leaf |
|
||||
|
||||
@@ -51,6 +51,7 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md)
|
||||
- [Catch complexity before it compounds](how-to/act-on-a-refactor-proposal.md) — enable the post-execute refactor hook, read a proposal's score vs. anchor delta, and accept or decline it
|
||||
- [Run phases autonomously](how-to/run-phases-autonomously.md) — use autonomous mode for unattended phase execution
|
||||
- [Handle quick and fast tasks](how-to/handle-quick-and-fast-tasks.md) — use `/gsd-quick` and `/gsd-fast` for ad-hoc work outside the phase loop
|
||||
- [Batch quick tasks](how-to/batch-quick-tasks.md) — run several `/gsd-quick`-shaped tasks together with `/gsd-quick-batch`, understand capacity/isolation, and recover a failed or interrupted batch
|
||||
- [Configure model profiles](how-to/configure-model-profiles.md) — switch between quality, balanced, and budget model tiers
|
||||
- [Control which host runtime GSD reports](how-to/control-the-reported-host-runtime.md) — read the `agent_runtime` ladder, understand what host detection looks at, and pin the runtime when detection is not what you want
|
||||
- [Set up cross-AI review](how-to/set-up-cross-ai-review.md) — configure a second AI to review code produced by the primary agent
|
||||
|
||||
23
docs/features/quick-batch.md
Normal file
23
docs/features/quick-batch.md
Normal file
@@ -0,0 +1,23 @@
|
||||
---
|
||||
id: 4015
|
||||
title: Quick Batch Mode
|
||||
group: Planning Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-quick-batch [--file <path>] [--jobs auto|N] [--validate] [--research] [--resume <batch-id>]`
|
||||
|
||||
**Purpose:** Batch several `/gsd-quick`-shaped tasks together — one coordinator plans, dispatches, and merges them as a single run, with per-item leaves and deterministic merge ordering (ADR-1239 "Quick-batch binding").
|
||||
|
||||
**Requirements:**
|
||||
- REQ-QB-01: System MUST accept an inline task list (≥2 items) or `--file <path>`
|
||||
- REQ-QB-02: System MUST reject `--discuss` and `--full` with a usage error before any dispatch
|
||||
- REQ-QB-03: System MUST reject a malformed `--jobs` value before any dispatch
|
||||
- REQ-QB-04: System MUST resolve effective concurrency as `min(task count, jobsN, capacity)` for `--jobs N`, or `capacity` alone for `--jobs auto`
|
||||
- REQ-QB-05: System MUST force a mutating (worktree/executor) wave's concurrency to 1 when isolation is `none`, without capping a non-mutating (research/planning-only) wave
|
||||
- REQ-QB-06: System MUST dispatch a planner per eligible item per DAG layer, providing the full batch task catalog and always requiring `depends_on`/`files_modified` frontmatter
|
||||
- REQ-QB-07: System MUST recompute execution waves after each planning layer from the planners' declared dependencies/files
|
||||
- REQ-QB-08: System MUST serialize worktree create/merge/cleanup while allowing already-created worktrees to run concurrently
|
||||
- REQ-QB-09: System MUST merge items strictly in the deterministic wave order, never completion order
|
||||
- REQ-QB-10: System MUST NOT call the STATE.md completion primitive for an item routed to `human_needed`
|
||||
- REQ-QB-11: System MUST fail an item routed to `gaps_found`/`merge_failed`/`scope_violation` without rollback, without an automatic retry, and with its worktree preserved
|
||||
- REQ-QB-12: System MUST support `--resume <batch-id>` to re-derive eligibility and dispatch only still-runnable items, refusing closed on an unknown batch id or a diverged base revision
|
||||
126
docs/how-to/batch-quick-tasks.md
Normal file
126
docs/how-to/batch-quick-tasks.md
Normal file
@@ -0,0 +1,126 @@
|
||||
# How to batch quick tasks
|
||||
|
||||
`/gsd-quick-batch` runs several `/gsd-quick`-shaped tasks together as ONE
|
||||
coordinated run: one coordinator parses the task list, plans and dispatches
|
||||
each item (planner, and optionally researcher/plan-checker/verifier leaves),
|
||||
merges them in a deterministic order, and owns every shared write
|
||||
(`BATCH.json`, `STATE.md`, worktree create/merge/cleanup) so the leaves never
|
||||
race each other (ADR-1239 "Quick-batch binding").
|
||||
|
||||
Use it instead of running `/gsd-quick` N separate times when you have several
|
||||
independent (or lightly interdependent) small tasks you want planned and
|
||||
executed together, with parallelism where the tasks allow it.
|
||||
|
||||
For the single-task case, see [Handle quick and fast tasks](handle-quick-and-fast-tasks.md).
|
||||
|
||||
---
|
||||
|
||||
## Basic use
|
||||
|
||||
Pass an inline task list — a bulleted or numbered list, at least 2 items,
|
||||
one per line:
|
||||
|
||||
```bash
|
||||
/gsd-quick-batch
|
||||
- Fix the login timeout on mobile Safari
|
||||
- Add a retry banner when the API call fails
|
||||
- Update the README's setup instructions
|
||||
```
|
||||
|
||||
Or point at a file containing the list:
|
||||
|
||||
```bash
|
||||
/gsd-quick-batch --file .planning/my-tasks.md
|
||||
```
|
||||
|
||||
Each item gets its own quick id, its own directory under
|
||||
`.planning/quick/`, and (when isolation is available) its own worktree — the
|
||||
same artifact shape a standalone `/gsd-quick` task produces, just planned and
|
||||
dispatched together.
|
||||
|
||||
---
|
||||
|
||||
## Flags
|
||||
|
||||
| Flag | What it does |
|
||||
|------|-------------|
|
||||
| `--jobs auto\|N` | `auto` (default) uses the negotiated dispatch capacity as-is. `N` caps effective concurrency at `min(task count, N, capacity)` — never more than the number of tasks, never more than what the runtime negotiated. A non-numeric or non-positive `N` is rejected before any dispatch. |
|
||||
| `--validate` | Enables the per-item plan-checker loop (max 2 iterations, same cap as `/gsd-quick --validate`) and post-merge verification. |
|
||||
| `--research` | Dispatches a focused researcher per item before planning. |
|
||||
| `--resume <batch-id>` | Skips task-list parsing and batch creation entirely — loads the existing batch and dispatches only its still-eligible items. |
|
||||
|
||||
**Not supported in v1:** `--discuss` and `--full` are rejected with a usage
|
||||
error before any dispatch. If a task genuinely needs a discussion phase, run
|
||||
it through `/gsd-quick --discuss` on its own instead of including it in a
|
||||
batch.
|
||||
|
||||
```bash
|
||||
/gsd-quick-batch --jobs 2 --validate --research # research, up to 2 concurrent, plan-checked + verified
|
||||
/gsd-quick-batch --resume 260101-abc # resume an interrupted batch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How capacity and isolation interact
|
||||
|
||||
Effective concurrency is computed from three things: `--jobs`, the
|
||||
negotiated dispatch capacity (how many subagents your runtime can run at
|
||||
once), and — for the mutating stage (worktree create → execute → merge) —
|
||||
the isolation mode:
|
||||
|
||||
| Isolation | Effect on the mutating (executor/worktree) stage |
|
||||
|---|---|
|
||||
| `harness-worktree` / `orchestrator-worktree` | Runs up to the effective concurrency computed above. |
|
||||
| `none` (no worktree isolation available, or `workflow.use_worktrees=false`) | Forced to concurrency **1**, regardless of `--jobs` or capacity — everything executes sequentially on the primary checkout. |
|
||||
|
||||
This cap applies **only** to the mutating stage. Planning and research are
|
||||
never worktree-isolated, so they run at full effective concurrency even when
|
||||
isolation is `none`.
|
||||
|
||||
Worktree creation, merging, and cleanup are always serialized one at a time
|
||||
(`git worktree add`/`git merge`/`git worktree remove` never overlap) —
|
||||
concurrency is about how many already-created worktrees' agents run at once,
|
||||
not about the git operations themselves. Merges apply in the same
|
||||
deterministic order the batch's dependency/file-overlap waves were computed
|
||||
in, never in whichever order an executor happens to finish first.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies and file overlap
|
||||
|
||||
Before planning, `/gsd-quick-batch` has no signal about which items depend
|
||||
on each other or touch the same files — every item starts in the same wave.
|
||||
Each item's planner is shown the full batch's task catalog (every item's id
|
||||
and description) and is required to declare, in its plan's frontmatter,
|
||||
which sibling items (if any) it depends on and which files it will touch.
|
||||
After each planning round, the coordinator recomputes execution waves from
|
||||
those declarations — independent items with disjoint files run in parallel;
|
||||
a dependent item's wave always comes strictly after its dependency's.
|
||||
|
||||
---
|
||||
|
||||
## Resuming and failure recovery
|
||||
|
||||
A batch's `BATCH.json` (`.planning/quick-batches/<batch-id>/`) tracks every
|
||||
item's status. Re-run with `--resume <batch-id>` at any point — including
|
||||
after a crash — and the coordinator re-derives which items are still
|
||||
runnable:
|
||||
|
||||
| Outcome | What happens | Recoverable via `--resume`? |
|
||||
|---|---|---|
|
||||
| Item completes normally | Marked `complete`; a `Quick Tasks Completed` STATE.md row is appended. | N/A |
|
||||
| Verifier reports `human_needed` (`--validate` only) | Terminal for that item — no STATE row is appended. Review it yourself, then fix and re-run if needed. | Yes, once resolved |
|
||||
| Verifier reports `gaps_found` (`--validate` only) | The item is marked `failed`. Its already-merged commit is **not** rolled back, and there is no automatic gap-fix retry. | Yes — resume re-evaluates it |
|
||||
| A merge conflicts, or a committed diff includes an undeclared file deletion | The item is marked `failed` with a reason; its worktree is **preserved** (never deleted) so you can inspect what happened. | Yes, after you resolve the worktree by hand |
|
||||
| An item this item depends on failed | The dependent item is automatically marked `blocked` on the next `--resume`. | Yes, once the blocking item is resolved |
|
||||
|
||||
Items unrelated to a failure continue normally in the same or a later batch
|
||||
run — one item's problem never blocks the rest of the batch.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Handle quick and fast tasks](handle-quick-and-fast-tasks.md)
|
||||
- [Commands](../COMMANDS.md)
|
||||
- [Docs index](../README.md)
|
||||
@@ -168,6 +168,7 @@ Four cases look similar from the outside but mean different things:
|
||||
|
||||
## Related
|
||||
|
||||
- [Batch quick tasks](batch-quick-tasks.md) — run several `/gsd-quick`-shaped tasks together with `/gsd-quick-batch`
|
||||
- [The phase loop](../explanation/the-phase-loop.md)
|
||||
- [Context engineering](../explanation/context-engineering.md)
|
||||
- [Commands](../COMMANDS.md)
|
||||
|
||||
Reference in New Issue
Block a user