@opengsd/gsd-core 1.11.0 → 1.13.0

package/gsd-core/references/planner-coupling.md

@@ -0,0 +1,42 @@
+# Planner Coupling — Same-Wave Shared Mutable State
+
+> Progressive-disclosure reference for `agents/gsd-planner.md`. The planner agent
+> reads this file when assigning waves (issue #3724). The slim pointer in
+> `agents/gsd-planner.md` → `assign_waves` routes here; the canonical schema row
+> for `coupling_justified` lives in `docs/reference/plan-md.md`. The verifying
+> side is `agents/gsd-plan-checker.md` Dimension 3b (#1954).
+
+## The rule
+
+`files_modified`/`files_deleted` overlap is not the only coupling between
+same-wave plans. If two plans in the same wave touch the same **mutable
+resource** through their task actions — a config key, DB table/row, migration,
+env var, singleton, cache — with at least one writer, or one plan produces a
+prerequisite the other consumes, the pair is coupled through shared state even
+though no file overlaps: under parallel execution the outcome depends on which
+executor gets there first.
+
+Resolve it one of three ways, in order of preference:
+
+1. **Declare the edge** — add the producing plan to the consumer's
+   `depends_on`. Wave assignment then orders them automatically.
+2. **Re-wave** — move one plan to a later wave when the dependency direction
+   is unclear but an ordering is still wanted.
+3. **Justify the pair** — when the coupling is deliberate and genuinely
+   order-independent (both orders produce a correct result), record it in
+   either plan's frontmatter, one `"plan-id: reason"` entry per coupled peer:
+
+   ```yaml
+   coupling_justified: ["03-02: both plans append independent keys to config; order irrelevant"]
+   ```
+
+   The plan-checker's Dimension 3b recognizes the declaration and does not
+   flag the pair, so a deliberately coupled plan set passes verification
+   without serializing waves it was designed to run in parallel.
+
+## Why declare it up front
+
+Dimension 3b flags same-wave plan pairs with an undeclared shared-mutable-state
+dependency (advisory severity — it never blocks). Declaring the edge, re-waving,
+or justifying the pair at plan time means the first checker pass comes back
+clean instead of surfacing an advisory the planner then has to interpret.

package/gsd-core/references/planner-failing-direction.md

@@ -0,0 +1,53 @@
+# Stated Failing Direction (#3172)
+
+> Reference file for the gsd-planner agent. Loaded on-demand via `@` reference from the
+> `<failing_direction_contract>` block of the planner spawn prompt in
+> `gsd-core/workflows/plan-phase.md` — NOT from `agents/gsd-planner.md`, which is frozen
+> under a 49152-LF-char cap, so planner-side rules are projected onto its spawn contract
+> (the #3297 / #3645 precedent).
+
+**Every runnable `<automated>` command needs a `<fails_when>` sibling naming what output
+constitutes failure.** A command with no expressible failure mode is not an acceptance test.
+
+```xml
+<verify>
+  <automated>npm --prefix apps/api test -- auth.spec.ts</automated>
+  <fails_when>non-zero exit, or "0 passed" in the summary line</fails_when>
+</verify>
+```
+
+**Why.** #3172: six plans shipped 21 `<automated>` commands that could not run at all — a
+`--lib` target against a binary-only package. They sat inside the very blocks that decide whether
+work is done, so the acceptance criteria for those plans were improvised at execution time by
+three separate executors instead of reviewed at planning time. Cargo happened to exit non-zero,
+so it failed loudly. The identical mistake with a command that exits 0 on a no-op — a test-name
+filter matching nothing — passes green and silently. Naming the failure signal is what makes the
+difference visible while you are still authoring the plan.
+
+**The authoring test, applied to yourself:** *if this command were silently doing nothing, what
+in its output would tell me?* If you cannot answer, you do not yet have an acceptance command —
+you have a command. Fix the command, do not invent a statement for it.
+
+## Rules
+
+- **One statement per runnable command**, placed immediately after it. Within a task, each
+  `<fails_when>` binds to the nearest preceding `<automated>`, and the first statement after a
+  command is the binding one. Two commands need two statements.
+- **Name an observable signal**, not the word "failure". `non-zero exit`, `"0 passed" in the
+  summary`, `the coverage line is absent`, `stderr contains "ECONNREFUSED"` are signals. *"the
+  command fails"*, *"it doesn't work"*, *"an error occurs"* are restatements and will be flagged.
+- **Short is fine.** `non-zero exit` is complete. There is no minimum length and no required
+  keyword.
+- **`TBD`, `TODO`, `N/A`, `none`, `unknown`, `?`, `-` are rejected outright** as whole values.
+  A statement you cannot write is a command you should not ship.
+- **Any characters are safe.** `exit code > 0`, `stderr contains "FAIL" && exit != 0` are ordinary
+  prose here — that is exactly why this is an element and not an attribute.
+- **The `MISSING — Wave 0 must create …` sentinel is exempt.** It is not a runnable command, so
+  it has no failure mode to state. Do not attach a `<fails_when>` to one.
+
+## Where the failing direction comes from
+
+Prefer the signal the tool actually emits over one you imagine. When
+`prior_verify_commands` supplies a command a prior phase already proved, the failure signal that
+command produces is the one to state — you have seen its output. When you author a new command,
+name the signal from the tool's documented output shape, not from a guess about it.

package/gsd-core/references/planner-human-verify-mode.md

@@ -50,8 +50,22 @@ Choose `mid-flight` when you genuinely need the work to stop before any subseque
 
 `checkpoint:decision` and `checkpoint:human-action` tasks are still emitted in `end-of-phase` mode. Those gate the work itself (a choice the executor needs from the user, or an auth step only the user can perform), not post-hoc verification of completed work. Only `checkpoint:human-verify` is suppressed.
 
+## The tracer feedback gate (executor-side, #3299)
+
+This mode is not purely a planner concern. The **tracer feedback gate** — the executor's early integration checkpoint after a `type="tracer"` task, in `workflows/execute-plan.md` and `agents/gsd-executor.md` — synthesizes a `checkpoint:human-verify` at runtime that no planner ever emitted, so planner-side suppression cannot reach it.
+
+That gate predates this mode (added by #2294; `end-of-phase` became the default in #3309, whose scope was the planner and verifier only), and until #3299 it branched on auto-mode alone. The result was that under the documented default, an interactive run halted after **every** tracer whose evidence was purely a test verdict, asking the user to retype a result the executor had just computed.
+
+The gate now honors `human_verify_mode`.
+
+The full precedence chain lives in `gsd-core/references/checkpoints.md` → "Tracer feedback gate (#3299)"; it is evaluated in order, and `gate="blocking-human"` outranks everything. Summary: an interactive `end-of-phase` run with an automated-only `<verify>` re-runs it and continues with no checkpoint (HALT on failure, unconditionally); `mid-flight`, `<human-check>`, and `blocking-human` all still STOP; the auto-mode branch is unchanged.
+
+**Why a tracer carrying `<human-check>` still halts rather than deferring to the end-of-phase UAT batch.** Deferring would be the more uniform reading of this mode — `<human-check>` on an `auto` task defers, so arguably it should defer on a tracer too. It deliberately does not, for three reasons. First, and decisively: **the end-of-phase harvest does not cover tracers.** `agents/gsd-verifier.md` collects `<verify><human-check>` blocks from `auto` tasks; deferring a tracer's human evidence without first widening that seam would drop the evidence on the floor entirely — strictly worse than halting. Second, the tracer gate exists to stop expansion being layered onto an unproven slice; deferring its human evidence would let every expansion task build on a slice no human has confirmed, the exact failure the gate was introduced to prevent. Third, the reported defect is scoped to tracers with *no* human-observable evidence, and fail-closed is the safe direction outside that scope. If uniformity is later preferred, the harvest must be widened to tracers in the same change — record that decision here rather than re-deriving it.
+
+`workflow.human_verify_mode` is **absent from `SCHEMA_DEFAULTS`** in `src/config.cts`, so `query config-get workflow.human_verify_mode` exits non-zero with `Key not found` on any project whose `config.json` predates #3309 — it does not resolve the documented `end-of-phase` default. Every consumer must therefore pass `--default end-of-phase` explicitly.
+
 ## Compatibility with other modes
 
 - **`workflow.tdd_mode`**: orthogonal. TDD tasks still emit `tdd="true"` and `<behavior>`; the `<verify>` block carries the human-check sub-element when `human_verify_mode = end-of-phase`.
 - **`MVP_MODE`**: orthogonal. Vertical-slice ordering is unchanged. The first task remains a failing end-to-end test; later auto tasks may carry `<verify><human-check>` instead of standalone checkpoint tasks.
-- **`workflow.auto_advance` / `_auto_chain_active`**: in mid-flight mode these auto-approve checkpoint:human-verify halts. In end-of-phase mode there are no halts to auto-approve, so the flags have no effect on this code path.
+- **`workflow.auto_advance` / `_auto_chain_active`**: in mid-flight mode these auto-approve checkpoint:human-verify halts. In end-of-phase mode there are no *planner-emitted* halts to auto-approve, so the flags have no effect on the planner's output. They are not inert at execution time, though: the executor-side tracer feedback gate above synthesizes its own checkpoint, and the auto-mode branch takes precedence over `human_verify_mode` there — except for `gate="blocking-human"`, which is evaluated first and STOPs in every mode (#3299).

package/gsd-core/references/planner-quick-batch.md

@@ -0,0 +1,71 @@
+# Quick-Batch Mode — Planner Reference
+
+Triggered when `<planning_context>` declares `**Mode:** quick-batch`
+(#3676, epic #3344, ADR-1239 "Quick-batch binding"). One dispatch = one
+item's plan — the SAME single-plan, 1-3-task scope as `/gsd:quick`'s own
+`quick`/`quick-full` modes, with one fixed difference: **`depends_on` and
+`files_modified` frontmatter are ALWAYS required, regardless of whether
+`--validate` was requested.** This reuses the EXISTING frontmatter grammar
+(the same keys full phase planning already emits — see the frontmatter
+schema table above); it is not a new schema.
+
+**Why always, not gated on `--validate`.** The coordinating workflow
+(`gsd-core/workflows/quick-batch.md`) recomputes every item's execution wave
+from these two fields after each DAG layer's planners return (`quick-batch
+update`, wrapping `updateBatchItems`) — without them, every item stays in
+wave 0 forever and the batch cannot parallelize independent items or
+sequence dependent ones correctly. This is load-bearing dispatch input, not
+an optional quality signal.
+
+### `depends_on` — reference SIBLING items by `quick_id`, never invent one
+
+The `<planning_context>` you receive includes a **full batch task catalog** —
+every item's `quick_id` + description, not just your own. When your item's
+implementation genuinely requires another item's item to land first (shared
+file, prerequisite API, sequencing the user implied), declare it:
+
+```yaml
+depends_on: ["260101-abc"]   # a quick_id from the task catalog
+```
+
+- Reference ONLY `quick_id`s from the task catalog you were given. Never
+  reference a plan id from a phase, another batch, or a value you invented.
+- Empty array (`depends_on: []`) is the correct, common answer when your item
+  is genuinely independent — do not manufacture a dependency to seem
+  thorough.
+- A dependency on your OWN `quick_id` (self-reference) or on an id outside
+  the catalog is rejected by `quick-batch update` and blocks the whole
+  layer's persistence — when uncertain, prefer `[]` over a guess.
+
+### `files_modified` — every path your plan's tasks will touch
+
+```yaml
+files_modified: ["src/foo.ts", "tests/foo.test.ts"]
+```
+
+Used two ways downstream, both from THIS field (never re-derived from your
+plan's prose): (1) `partitionByFileOverlap` splits same-wave items that
+would touch the same file into separate waves, so two isolated worktrees
+never race on one path; (2) at merge time the coordinator reads it FRESH from
+your PLAN.md (not from what you declared here at planning time — keep the
+frontmatter accurate if you revise the plan) for the advisory scope-
+conformance check.
+
+### `files_deleted` — only if your plan removes a file
+
+```yaml
+files_deleted: ["legacy/old-module.ts"]
+```
+
+Optional; omit entirely when your plan deletes nothing. If your plan DOES
+delete a file and you omit this, the merge's deletions guard blocks that
+deletion as undeclared — there is no "authorize everything" fallback.
+
+### What quick-batch mode does NOT need
+
+Same exclusions as `/gsd:quick`'s own modes: no `requirements` (no ROADMAP
+linkage — a quick-batch item is not a phase), no `estimate` block, no
+`user_setup` unless genuinely needed. `must_haves` is required only when the
+calling prompt's own `<constraints>` says so (mirrors `--validate`'s
+existing quick-full behavior) — that instruction rides the prompt, not this
+reference.

package/gsd-core/references/planner-reviews.md

@@ -40,3 +40,50 @@ Use standard PLANNING COMPLETE return format, adding a reviews section:
 |---------|--------|
 | {concern} | {why — out of scope, disagree, etc.} |
 ```
+
+### Step 5: Write the ledger into PLAN.md (#3806)
+
+The two tables above are not only the planner's return payload — they are also the **canonical
+Review Dispositions Ledger**, and they belong in the affected PLAN.md itself, in this exact shape.
+`gsd-core/workflows/plan-phase.md` (`<review_incorporation_contract>`) and
+`agents/gsd-plan-checker.md` (Review Incorporation dimension) both point back to this section for
+the ledger's shape rather than restating it — this is the one place it is defined.
+
+## Review Dispositions Ledger
+
+Add or extend a `## Review Dispositions Ledger` section in the affected PLAN.md, containing one
+`### Round {N} — {REVIEWS_sha}` subsection per reviews-mode round that touched this plan, where
+`{REVIEWS_sha}` is the commit that wrote the REVIEWS.md snapshot being ruled on (the short sha from
+`git log -1 --format=%h -- <phase_dir>/<NN>-REVIEWS.md`, after `workflows/review.md`'s REVIEWS.md
+commit step). Under each round heading, use the two tables from Step 4 above, unchanged in shape:
+
+```markdown
+## Review Dispositions Ledger
+
+### Round 1 — a1b2c3d
+
+### Review Feedback Addressed
+| Concern | Severity | How Addressed |
+|---------|----------|---------------|
+| {concern} | HIGH | Plan {N}, Task {M}: {how} |
+
+### Review Feedback Deferred
+| Concern | Reason |
+|---------|--------|
+| {concern} | {why — out of scope, disagree, etc.} |
+```
+
+**Anchoring.** Any reference to a specific REVIEWS.md line cites `L##@{REVIEWS_sha}` (e.g.
+`L32@a1b2c3d`) — a bare line number is meaningless once the next round rewrites REVIEWS.md
+wholesale. `{Concern}` and `{Reason}` stay free text; do not invent a reviewer/severity enum — the
+reviewer roster is capability-owned and open to third-party additions (see each capability's
+`reviewer.reviewsSection`).
+
+**Append-only.** A later round never edits or deletes a prior round's tables. To overturn a prior
+round's verdict, add a new row in the current round's table whose Reason/How Addressed names the
+round and concern it supersedes (e.g. "Supersedes Round 1 Deferred: {concern} — now addressed in
+Plan 3").
+
+**Out of scope for this contract.** A deterministic lint/check verb that mechanically enforces this
+shape is a separate, later addition (#3806 part 2) — this section defines the format only. Legacy
+PLAN.md content written before this convention existed is not migrated or flagged by it.

package/gsd-core/references/planner-revision.md

@@ -21,12 +21,43 @@ issues:
   - plan: "16-01"
     dimension: "task_completeness"
     severity: "blocker"
+    required_property: "Every `auto` task has a `<verify>` separating pass from fail"
     description: "Task 2 missing <verify> element"
     fix_hint: "Add verification command for build output"
 ```
 
 Group by plan, dimension, severity.
 
+**What binds and what does not.** `required_property` (the invariant that must hold),
+`description` (the evidence it does not) and `severity` are binding. `fix_hint` is **one
+example** of a route to that property — an illustration, never an instruction. You address an
+issue by making `required_property` true; the hint's own mechanism is optional.
+
+An older checker may return an issue with no `required_property`. Derive it from `dimension`
++ `description` and state the derived property in your revision summary. Never treat the
+absence of the field as licence to apply `fix_hint` literally.
+
+**Prefer the smallest sufficient mechanism.** If a smaller change than the hint makes
+`required_property` true, take it — that fully addresses the issue and must be reported as
+addressed, naming the property satisfied and the mechanism used.
+
+### Step 2.5: Constraint Re-check (before any edit)
+
+Before editing, re-read the constraints already in force:
+
+- Locked decisions in CONTEXT.md (`## Decisions`) and deferred ideas (`## Deferred Ideas`)
+- Active capability / project guidance (CLAUDE.md, `.claude/skills/`, `.agents/skills/`)
+- Constraints the existing plans already encode (chosen mechanism, scope boundary, must_haves)
+
+A `fix_hint` conflicts when applying it would contradict any of those. Applying it anyway is
+a contract violation, not a judgement call. When a hint conflicts — or when the property is
+unreachable without breaking a constraint — do NOT edit around it and do NOT burn a revision
+iteration on it: emit `## REVISION_CONFLICT` (Step 7) for that issue, apply every
+non-conflicting issue normally, and return.
+
+A hint that merely proposes a *bigger* mechanism than needed is not a conflict. Take the
+smaller route under Step 2 and report it as addressed.
+
 ### Step 3: Revision Strategy
 
 | Dimension | Strategy |
@@ -38,15 +69,25 @@ Group by plan, dimension, severity.
 | scope_sanity | Split into multiple plans |
 | must_haves_derivation | Derive and add must_haves to frontmatter |
 
+Each strategy is the usual route, not the only one. Any change that makes the issue's
+`required_property` true is a valid strategy.
+
 ### Step 4: Make Targeted Updates
 
 **DO:** Edit specific flagged sections, preserve working parts, update waves if dependencies change.
+Choose the smallest mechanism that makes each issue's `required_property` true — explicitly
+including a mechanism smaller than, or different from, the one its `fix_hint` names.
 
-**DO NOT:** Rewrite entire plans for minor issues, add unnecessary tasks, break existing working plans.
+**DO NOT:** Rewrite entire plans for minor issues, add unnecessary tasks, break existing working
+plans, or apply a `fix_hint` that contradicts a constraint from Step 2.5 — that one goes to
+`## REVISION_CONFLICT` instead.
 
 ### Step 5: Validate Changes
 
-- [ ] All flagged issues addressed
+- [ ] Every flagged issue's `required_property` now holds — reached by its `fix_hint` OR by a
+      smaller/different mechanism (both count as addressed), OR raised as `## REVISION_CONFLICT`
+- [ ] No `fix_hint` applied that contradicts a locked decision, capability guidance, or an
+      existing plan constraint (Step 2.5)
 - [ ] No new issues introduced
 - [ ] Wave numbers still valid
 - [ ] Dependencies still correct
@@ -55,7 +96,7 @@ Group by plan, dimension, severity.
 ### Step 6: Commit
 
 ```bash
-gsd-tools query commit "fix($PHASE): revise plans based on checker feedback" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
+gsd_run query commit "fix($PHASE): revise plans based on checker feedback" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
 ```
 
 ### Step 7: Return Revision Summary
@@ -85,3 +126,35 @@ gsd-tools query commit "fix($PHASE): revise plans based on checker feedback" --f
 |-------|--------|
 | {issue} | {why - needs user input, architectural change, etc.} |
 ```
+
+### Step 7b: Return Revision Conflict (when Step 2.5 found one)
+
+Emit this INSTEAD OF `## REVISION COMPLETE` when at least one issue could not be addressed
+without contradicting a constraint. Non-conflicting issues you already fixed stay listed under
+`### Changes Made` so the work is not lost. The orchestrator routes this to the user or to the
+configured plan-review convergence loop; it does not count as a failed revision iteration.
+
+```markdown
+## REVISION_CONFLICT
+
+**Conflicts:** {N}  |  **Issues addressed anyway:** {M}
+
+| Issue | required_property | Conflicts with | Why the hint cannot be applied |
+|-------|-------------------|----------------|-------------------------------|
+| {dimension}/{plan} | {property} | {locked decision D-nn / CLAUDE.md rule / plan constraint} | {one line} |
+
+### Alternatives Considered
+
+| Issue | Alternative | Satisfies required_property? | Cost of adopting |
+|-------|-------------|------------------------------|------------------|
+| {dimension}/{plan} | {smaller or different mechanism} | {yes / partially — how} | {what it changes} |
+
+### Changes Made
+
+{table of the non-conflicting issues you DID address, same shape as REVISION COMPLETE}
+```
+
+**Every field is one line of plain text.** No newlines inside a cell, and never begin a field with
+`#`, `-`, `|` or a code fence. These fields are appended to a shared markdown file that a later
+reader scans by heading; a field that starts a heading truncates that scan and hides conflicts
+below it.

package/gsd-core/references/planner-verify-command-grounding.md

@@ -0,0 +1,17 @@
+# Verify Command Grounding (#2401)
+
+> Reference file for gsd-planner agent. Loaded on-demand via `@` reference.
+
+**Inherit the command that already worked.** The planning context carries
+`prior_verify_commands` — the `<automated>` commands from the most recent prior phase that had
+any, surfaced **at every context window**, not only on 1M-class models. When this phase's build
+or test story is the same one a prior phase already proved, **reuse that command verbatim**
+rather than re-deriving a path. Re-invention is what produced `cd ../../frontend && npm run
+lint` against a directory that holds no `package.json`, and cost two revision cycles.
+
+Ground every path you do author: a command's `cd` target or `npm --prefix` target must be a
+directory that exists (or that an earlier task in this phase creates) and, for an npm/make
+command, must hold the matching `package.json`/`Makefile`. `npm --prefix <dir> run <script>` is
+preferred over `cd <dir> && npm run <script>` — it does not depend on the executor's cwd. If
+`prior_verify_commands` is empty and you cannot ground a path, say so in the plan instead of
+guessing one.

package/gsd-core/references/planning-config.md

@@ -6,11 +6,13 @@ Configuration options for `.planning/` directory behavior.
 ```json
 "planning": {
   "commit_docs": true,
+  "pr_strict": false,
   "search_gitignored": false
 },
 "git": {
   "branching_strategy": "none",
   "base_branch": null,
+  "protected_branches": ["develop", "staging"],
   "phase_branch_template": "gsd/phase-{phase}-{slug}",
   "milestone_branch_template": "gsd/{milestone}-{slug}",
   "quick_branch_template": null
@@ -27,15 +29,18 @@ Configuration options for `.planning/` directory behavior.
 | Option | Default | Description |
 |--------|---------|-------------|
 | `commit_docs` | `true` | Whether to commit planning artifacts to git |
+| `pr_strict` | `false` | Filter mode for `/gsd:pr-branch`. `false` keeps structural planning state (STATE.md, ROADMAP.md, MILESTONES.md, PROJECT.md, REQUIREMENTS.md, milestones/) in the PR branch; `true` drops every `.planning/` path |
 | `search_gitignored` | `false` | Add `--no-ignore` to broad rg searches |
 | `git.branching_strategy` | `"none"` | Git branching approach: `"none"`, `"phase"`, or `"milestone"` |
 | `git.base_branch` | `null` (auto-detect) | Target branch for PRs and merges (e.g. `"master"`, `"develop"`). When `null`, auto-detects from `git symbolic-ref refs/remotes/origin/HEAD`, falling back to `"main"`. |
+| `git.protected_branches` | (none) | Optional array of non-empty strings naming additional shared branches that should trigger protected-branch warnings |
 | `git.create_tag` | `true` | Create git tags on milestone completion |
 | `git.phase_branch_template` | `"gsd/phase-{phase}-{slug}"` | Branch template for phase strategy |
 | `git.milestone_branch_template` | `"gsd/{milestone}-{slug}"` | Branch template for milestone strategy |
 | `git.quick_branch_template` | `null` | Optional branch template for quick-task runs |
 | `workflow.use_worktrees` | `true` | Whether executor agents run in isolated git worktrees. Set to `false` to disable worktrees — agents execute sequentially on the main working tree instead. Recommended for solo developers or when worktree merges cause issues. Note: if your branch is ahead of `origin/HEAD` (a diverged milestone or feature branch), GSD auto-degrades to sequential and prints a warning; set `worktree.baseRef:"head"` in `.claude/settings.local.json` to restore parallel execution. See the branch-divergence note below. |
 | `workflow.subagent_timeout` | `300000` | Timeout in milliseconds for parallel subagent tasks (e.g. codebase mapping). Increase for large codebases or slower models. Default: 300000 (5 minutes). |
+| `workflow.inline_plan_threshold` | `2` | Plans with this many tasks or fewer execute inline (Pattern C) instead of spawning a subagent. Avoids ~14K token spawn overhead for small plans. Set to `0` to always spawn subagents. |
 | `workflow.test_command` | `null` | Custom shell command run as the regression/test gate by execute-phase, audit-fix, and post-merge-gate. When unset, GSD auto-detects (Makefile / package.json / Cargo.toml / go.mod / pyproject.toml). Example: `npm test`. |
 | `workflow.build_command` | `null` | Custom shell command run as the build gate by the post-merge gate. When unset, the build step is skipped/auto-detected. Example: `npm run build`. |
 | `workflow.inline_plan_threshold` | `2` | Plans with this many tasks or fewer execute inline (Pattern C) instead of spawning a subagent. Avoids ~14K token spawn overhead for small plans. Set to `0` to always spawn subagents. |
@@ -45,6 +50,26 @@ Configuration options for `.planning/` directory behavior.
 | `response_language` | `null` | Language for user-facing questions and prompts across all phases/subagents (e.g. `"Portuguese"`, `"Japanese"`, `"Spanish"`). When set, all spawned agents include a directive to respond in this language. |
 </config_schema>
 
+`git.protected_branches` has no persisted default. When it is absent, only the resolved base branch
+is protected, preserving existing project behavior. Every configured item must be a non-empty
+string. The configured list extends the resolved base branch; it never replaces the base or changes
+the resolution ladder. A match produces an advisory warning at execute-phase and ship and does not
+change `git.branching_strategy: "none"`.
+
+Matching is by exact branch name — there is no glob or prefix support, so a git-flow
+layout must name each `release/*` or `hotfix/*` branch it wants protected. An entry that
+is not a non-empty string is ignored with a warning naming it, and the remaining names
+still apply.
+
+```json
+{
+  "git": {
+    "branching_strategy": "none",
+    "protected_branches": ["develop", "staging"]
+  }
+}
+```
+
 <commit_docs_behavior>
 
 **When `commit_docs: true` (default):**
@@ -61,15 +86,15 @@ Configuration options for `.planning/` directory behavior.
 
 ```bash
 # Commit with automatic commit_docs + gitignore checks:
-gsd-tools query commit "docs: update state" --files .planning/STATE.md
+gsd_run query commit "docs: update state" --files .planning/STATE.md
 
 # Load config via state load (returns JSON):
-INIT=$(gsd-tools query state.load)
+INIT=$(gsd_run query state.load)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # commit_docs is available in the JSON output
 
 # Or use init commands which include commit_docs:
-INIT=$(gsd-tools query init.execute-phase "1")
+INIT=$(gsd_run query init.execute-phase "1")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # commit_docs is included in all init command outputs
 ```
@@ -81,7 +106,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 **Commit via CLI (handles checks automatically):**
 
 ```bash
-gsd-tools query commit "docs: update state" --files .planning/STATE.md
+gsd_run query commit "docs: update state" --files .planning/STATE.md
 ```
 
 The CLI checks `commit_docs` config and gitignore status internally — no manual conditionals needed.
@@ -169,14 +194,14 @@ To use uncommitted mode:
 
 Use `init execute-phase` which returns all config as JSON:
 ```bash
-INIT=$(gsd-tools query init.execute-phase "1")
+INIT=$(gsd_run query init.execute-phase "1")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # JSON output includes: branching_strategy, phase_branch_template, milestone_branch_template
 ```
 
 Or use `state load` for the config values:
 ```bash
-INIT=$(gsd-tools query state.load)
+INIT=$(gsd_run query state.load)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # Parse branching_strategy, phase_branch_template, milestone_branch_template from JSON
 ```
@@ -242,6 +267,7 @@ Generated from `CONFIG_DEFAULTS` (configuration.cjs) and `VALID_CONFIG_KEYS` (co
 | `resolve_model_ids` | boolean\|string | `false` | `false`, `true`, `"omit"` | Map model aliases to full Claude IDs; `"omit"` returns empty string |
 | `context` | string\|null | `null` | `"dev"`, `"research"`, `"review"` | Execution context profile that adjusts agent behavior: `"dev"` for development tasks, `"research"` for investigation/exploration, `"review"` for code review workflows |
 | `review.models.<cli>` | string\|null | `null` | Any model ID string | Per-CLI model override for /gsd:review (e.g., `review.models.gemini`). Falls back to CLI default when null. |
+| `review.max_prompt_tokens` | number\|null | `null` | Any positive integer, or `null` | Central, cross-lane default cap (in estimated tokens) on the assembled review prompt; `null` means no trim. A per-lane `review.max_prompt_tokens_per_reviewer.<slug>` value overrides it for that lane: `-1` means unset (inherits this global default), `0` means "do not trim that lane" (not unset — it is an explicit, standing opt-out). _Alias:_ `max_prompt_tokens` is the flat-key form used in `CONFIG_DEFAULTS`; `review.max_prompt_tokens` is the canonical namespaced form. |
 
 ### Workflow Fields
 
@@ -263,21 +289,23 @@ Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research":
 | `workflow.ui_phase` | boolean | `true` | `true`, `false` | Generate UI-SPEC.md for frontend phases |
 | `workflow.ui_safety_gate` | boolean | `true` | `true`, `false` | Require safety gate approval for UI changes |
 | `workflow.text_mode` | boolean | `false` | `true`, `false` | Use plain-text numbered lists instead of AskUserQuestion menus |
-| `workflow.research_before_questions` | boolean | `false` | `true`, `false` | Run research before interactive questions in discuss phase |
+| `workflow.research_before_questions` | boolean | `false` | `true`, `false` | Run research before interactive questions in discuss phase (also honored on the `/gsd:quick` path, #3894). _Alias:_ `research_before_questions` is the flat-key form used in `CONFIG_DEFAULTS`; `workflow.research_before_questions` is the canonical namespaced form. |
 | `workflow.discuss_mode` | string | `"discuss"` | `"discuss"`, `"assumptions"` | Default mode for discuss-phase: `"discuss"` runs interactive questioning; `"assumptions"` analyzes codebase and surfaces assumptions instead |
 | `workflow.skip_discuss` | boolean | `false` | `true`, `false` | Skip discuss phase entirely |
 | `workflow.use_worktrees` | boolean | `true` | `true`, `false` | Run executor agents in isolated git worktrees |
 | `workflow.subagent_timeout` | number | `300000` | Any positive integer (ms) | Timeout for parallel subagent tasks (default: 5 minutes) |
+| `workflow.inline_plan_threshold` | number | `2` | `0`–`10` | Plans with ≤N tasks execute inline instead of spawning a subagent |
 | `workflow.test_command` | string\|null | `null` | Any shell command | Regression/test gate command run by execute-phase, audit-fix, and post-merge-gate. Unset → GSD auto-detects (Makefile / package.json / Cargo.toml / go.mod / pyproject.toml). |
 | `workflow.build_command` | string\|null | `null` | Any shell command | Build gate command run by the post-merge gate. Unset → build step auto-detected/skipped. |
 | `workflow.mvp_mode` | boolean | `false` | `true`, `false` | Persist the MVP-mode flag in config so every phase defaults to MVP framing without requiring `--mvp` on the CLI. Resolved via the chain: `--mvp` CLI flag → ROADMAP.md `**Mode:** mvp` field → this config value → `false`. When `true`, the planner, executor, verifier, and discovery surfaces (progress, stats, graphify) all treat the phase as an MVP vertical slice (UI → API → DB) of one user-visible capability. |
 | `workflow.context_guard_mode` | string | `"warn"` | `"auto"`, `"warn"`, `"off"` | Context exhaustion guard mode for `execute-phase`. Before each wave, the orchestrator self-assesses context pressure using degradation signals from `context-budget.md`. `"warn"` (default): emit a warning and recommend `/gsd:pause-work` when POOR tier is detected. `"auto"`: automatically invoke `/gsd:pause-work` before the next wave when POOR tier is detected. `"off"`: disable the guard. The guard is heuristic — no programmatic context-% API exists. |
-| `workflow.plan_chunked` | boolean | `false` | `true`, `false` | Enable chunked planning mode. When `true`, the plan-phase orchestrator splits the single long-lived planner Task into a short outline Task followed by N short per-plan Tasks (~3–5 min each). Each plan is committed individually for crash resilience. Particularly useful on Windows where long-lived Tasks may hang on stdio. Also activated by the `--chunked` flag. |
+| `workflow.plan_chunked` | boolean | `false` | `true`, `false` | Enable chunked planning mode. When `true`, the plan-phase orchestrator splits the single long-lived planner Task into a short outline Task followed by N short per-plan Tasks (~3–5 min each). Each plan is committed individually for crash resilience. Particularly useful on Windows where long-lived Tasks may hang on stdio. Also activated by the `--chunked` flag. See `planning.chunked_parallel` below for concurrent per-plan dispatch. |
 | `workflow.specless_probe_fallback` | boolean | `true` | `true`, `false` | Gate the SPEC-less probe fallback in `plan-phase`. When `true` (default), a phase that did not supply a `## Edge Coverage` / `## Prohibitions` SPEC section (header absent or present-but-empty) runs the existing probe protocol — the deterministic `edge-probe.cjs` for edges and an in-planner LLM recall pass for prohibitions — and authors the resulting predicates into PLAN.md `must_haves` (section-level precedence: a SPEC-supplied section is never re-run or overwritten). When `false`, the fallback is skipped but the skip is recorded: plan-phase emits a visible "probe fallback disabled" marker, never a silent skip. |
 | `workflow.code_review_command` | string\|null | `null` | Any shell command | External code-review command integrated into `/gsd:ship`. The diff is piped to the command via stdin; the command must output JSON with a `verdict` field (`"APPROVED"` or `"REVISE"`). Non-zero exit or `"REVISE"` verdict blocks the ship workflow. When unset, the built-in review flow runs. Example: `my-review-tool --review`. |
 | `workflow.inline_plan_threshold` | number | `2` | `0`–`10` | Plans with ≤N tasks execute inline instead of spawning a subagent |
 | `workflow.code_review` | boolean | `true` | `true`, `false` | Enable built-in code review step in the ship workflow |
 | `workflow.code_review_depth` | string | `"standard"` | `"quick"`, `"standard"`, `"deep"` | Depth level for code review analysis in the ship workflow |
+| `workflow.code_review_depth_overrides` | array | `[]` | Array of `{paths, depth}` rule objects | Ordered path-scoped depth rules for `/gsd:code-review` (#2554). Each rule's `paths` are matched against the review's changed-file set by whole-segment directory-path prefix (`src/auth` matches `src/auth/token.ts`, never `src/authfoo/x.ts`); matching is case-sensitive. Glob syntax (`*`, `?`) is a configuration error. One matched file escalates the entire review — depth is not applied per file. Resolution order: `--depth=` flag → strongest matching rule → `workflow.code_review_depth` → `standard`. A malformed rule halts the review with a typed error rather than falling back silently. |
 | `workflow._auto_chain_active` | boolean | `false` | `true`, `false` | Internal: tracks whether autonomous chaining is active |
 | `workflow.security_enforcement` | boolean | `true` | `true`, `false` | Enable threat-model-anchored security verification via `/gsd:secure-phase`. When `false`, security checks are skipped entirely |
 | `workflow.security_asvs_level` | number | `1` | `1`, `2`, `3` | OWASP ASVS verification level. Level 1 = opportunistic, Level 2 = standard, Level 3 = comprehensive. Scales both planner threat-disposition rigor (which threats must be mitigated vs. accepted) and auditor verification depth (grep-level → boundary-placement check → full data-flow trace). See `gsd-core/references/security-asvs-levels.md`. |
@@ -300,6 +328,7 @@ Set via `git.*` namespace (e.g., `"git": { "branching_strategy": "phase" }`).
 |-----|------|---------|----------------|-------------|
 | `git.branching_strategy` | string | `"none"` | `"none"`, `"phase"`, `"milestone"` | Git branching approach for phase/milestone isolation |
 | `git.base_branch` | string\|null | `null` (auto-detect) | Any branch name | Target branch for PRs and merges; auto-detects from `origin/HEAD` when `null` |
+| `git.protected_branches` | array of non-empty strings | (none) | Non-empty branch names | Optional protected names added to the resolved base branch for execute-phase and ship warnings |
 | `git.create_tag` | boolean | `true` | `true`, `false` | Create git tags on milestone completion |
 | `git.phase_branch_template` | string | `"gsd/phase-{phase}-{slug}"` | Template with `{phase}`, `{slug}` | Branch naming template for `phase` strategy |
 | `git.milestone_branch_template` | string | `"gsd/{milestone}-{slug}"` | Template with `{milestone}`, `{slug}` | Branch naming template for `milestone` strategy |
@@ -375,6 +404,7 @@ These can be set at top level or nested under `planning.*` (e.g., `"planning": {
 |-----|------|---------|----------------|-------------|
 | `planning.commit_docs` | boolean | `true` | `true`, `false` | Alias for top-level `commit_docs` |
 | `planning.search_gitignored` | boolean | `false` | `true`, `false` | Alias for top-level `search_gitignored` |
+| `planning.chunked_parallel` | boolean | `false` | `true`, `false` | Opt-in for `workflow.plan_chunked`'s per-plan loop (§8.5.2 of `chunked-planning-mode.md`, #3777). When `true`, the runnable per-plan planners within one outline Wave are dispatched concurrently (one message, `run_in_background=true` each) instead of one at a time, honoring the outline's Wave column as the schedule (`Depends On` is expected to name only an earlier Wave and is not separately parsed — batching strictly by Wave already respects it). Gated on the negotiated `dispatch-capacity` query (#3673): a host that declares no `maxConcurrency` (capacity resolves to `1`) stays serial regardless of this setting. Default `false` is byte-identical to the pre-#3777 serial loop. Trade-off: per-plan commits interleave within a batch instead of strictly one-at-a-time, and a stalled plan's retry no longer blocks sibling plans in the same batch from having already committed. |
 
 ---
 
@@ -398,7 +428,7 @@ Several config fields affect each other or trigger special behavior:
 
 8. **`sub_repos` auto-sync** -- On every config load, GSD scans for child directories with `.git` and updates the `sub_repos` array if the filesystem has changed. Legacy `multiRepo: true` is automatically migrated to a detected `sub_repos` array.
 
-9. **`workflow.use_worktrees` and branch divergence** -- When `use_worktrees` is `true` (default), executor worktrees are forked from `origin/HEAD` -- by the host's own harness on `dispatch.isolation: harness-worktree` runtimes (Claude Code, Cursor), or by GSD itself on `orchestrator-worktree` runtimes (Codex, OpenCode, Kimi, Kimi Code). The divergence behavior below is identical either way, because the fork base is a property of the repository rather than of whoever creates the worktree. If your current branch has commits that `origin/HEAD` does not (for example an unmerged milestone or feature branch), GSD automatically degrades to sequential execution for that run and prints a one-line `⚠ Worktree base mismatch` warning. To restore parallel execution permanently, set `worktree.baseRef:"head"` in `.claude/settings.local.json` (run `node gsd-tools.cjs worktree set-baseref`). This makes the harness fork worktrees from the live HEAD instead of `origin/HEAD`. Both fresh installs and upgrades of GSD Core set this automatically (no-clobber) when `use_worktrees` is enabled; you can also run the command manually at any time. Setting `workflow.use_worktrees: false` is the alternative if worktrees are not needed at all. On a runtime whose declared `dispatch.isolation` is `none`, an explicit `true` is a config the execution workflows fail closed on; `/gsd:health` reports it as warning `W025` and `/gsd:settings` offers to repair it (#2486).
+9. **`workflow.use_worktrees` and branch divergence** -- When `use_worktrees` is `true` (default), executor worktrees are forked from `origin/HEAD` -- by the host's own harness on `dispatch.isolation: harness-worktree` runtimes (Claude Code, Cursor), or by GSD itself on `orchestrator-worktree` runtimes (Codex, OpenCode, Kimi, Kimi Code). The divergence behavior below is identical either way, because the fork base is a property of the repository rather than of whoever creates the worktree. If your current branch has commits that `origin/HEAD` does not (for example an unmerged milestone or feature branch), GSD automatically degrades to sequential execution for that run and prints a one-line `⚠ Worktree base mismatch` warning. To restore parallel execution permanently, set `worktree.baseRef:"head"` in `.claude/settings.local.json` (run `gsd_run worktree set-baseref`). This makes the harness fork worktrees from the live HEAD instead of `origin/HEAD`. Both fresh installs and upgrades of GSD Core set this automatically (no-clobber) when `use_worktrees` is enabled; you can also run the command manually at any time. Setting `workflow.use_worktrees: false` is the alternative if worktrees are not needed at all. On a runtime whose declared `dispatch.isolation` is `none`, an explicit `true` is a config the execution workflows fail closed on; `/gsd:health` reports it as warning `W025` and `/gsd:settings` offers to repair it (#2486).
 
 ---
 

package/gsd-core/references/response-language-directive.md

@@ -0,0 +1,9 @@
+# Response-Language Directive (#2529)
+
+**If `response_language` is set** (in the init JSON this workflow parses, or in `.planning/config.json`): ALL user-facing output of this workflow MUST be in that language — narration between tool calls, status updates, progress notes, findings, banners, report prose, questions (AskUserQuestion or plain text), and summaries. Technical terms, code, file paths, commands, and identifiers stay in English.
+
+Literal English report/banner templates embedded in a workflow are a structural SOURCE, not literal output to copy verbatim — render their prose translated into `{response_language}` while keeping headings' structural markers, table columns, IDs, commands, and file paths unchanged. Exception: blocks a workflow explicitly requires to be emitted byte-for-byte (e.g. pre-rendered checkpoints) are output exactly as rendered.
+
+Pass `response_language: {value}` into every spawned subagent prompt so any user-facing output they produce stays in the configured language.
+
+Workflows take this contract in one of three forms (REQ-LANG-03): an `@`-reference to this file; their own inline directive naming the same narration class; or, for a fragment loaded by a covered parent, inheritance from that parent. Coverage is enforced by `scripts/lint-response-language-coverage.cjs` — a new workflow cannot ship without one of the three, and the lint checks this file's own wording too, so a weakened directive here uncovers every workflow that imports it rather than passing silently. Workflow-specific directives (e.g. `execute-phase-response-language.md`) take precedence where present.

package/gsd-core/references/reviewer-instances.md

@@ -106,3 +106,34 @@ with an argv array and `shell: false`.
 - **Shared-adapter caveat:** when ≥2 invoked instances share the same base `cli`, print a
   one-line caveat immediately after the frontmatter (before the first section), e.g.:
   `> Note: opencode-deepseek and opencode-mimo share the opencode adapter; their consensus is cross-model, not cross-tool.`
+
+---
+
+## Interaction with the convergence loop (#2398)
+
+Running 2+ instances changes how `/gsd:plan-review-convergence` counts HIGHs. Its **consensus gate**
+(`plan-review-convergence.md`, step 5a, immediately before the counting rules) engages only when two
+or more reviewers actually ran in a cycle — which is precisely the configuration this file enables.
+
+Under that gate, a HIGH raised by exactly one instance is treated by what the claim asserts:
+
+- an **existence-class** claim (a symbol, file, flag, commit or ID exists / is absent / says X)
+  counts toward `current_high` only if source-grounding confirms it or another reviewer raised the
+  same concern;
+- a **judgment-class** claim (a design or correctness property) counts unless that instance's own
+  section opens with an evidence-quality discount marker — `[reviewed-without-source-citations]`
+  (#3194) or `[reviewed-without-repo-access]` (#2176).
+
+Judgment-class findings are deliberately exempt from the corroboration requirement: instances catch
+materially different classes of issue, so demanding two of them independently raise the same
+architectural concern would suppress the findings this feature exists to surface.
+
+A suppressed HIGH is still reported, tagged `(single-reviewer, unconfirmed)`. If every instance that
+ran carries a discount marker the gate disengages entirely, so a cycle in which nothing was verified
+can never be counted as converged.
+
+**Practical consequence for this file's use case:** instances of uneven reliability are safe to
+configure. A weak instance that returns no `file:line` evidence gets stamped, and its lone
+judgment-class HIGHs stop forcing replan cycles — while any instance that does produce grounded
+evidence keeps full blocking weight, alone, on exactly the architectural findings it was added to
+catch.