@opengsd/gsd-core 1.10.0 → 1.12.0

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-guidance.md

@@ -162,24 +162,18 @@ Derive plans from actual work. Granularity determines compression tolerance, not
 Run `/clear` first for a fresh context window, then execute: `/gsd:execute-phase {phase}`
 ```
 
-## Gap Closure Plans Created Return Format
+## Gap Closure Return (artifact-based — #3440)
 
-```markdown
-## GAP CLOSURE PLANS CREATED
+Gap-closure completion has **no completion marker**: nothing consumes one. The return contract is the artifacts themselves — `verify-work.md` spawns you in `--gaps` mode, and your output is complete when the fix plans are on disk carrying `gap_closure: true` in their frontmatter; the spawning workflow detects the files (never a return string), and `/gsd:execute-phase {phase} --gaps-only` consumes them. (The former `GAP CLOSURE PLANS CREATED` completion marker was retired as vestigial — it had no dispatch branch anywhere.)
 
 **Phase:** {phase-name}
 **Closing:** {N} gaps from {VERIFICATION|UAT}.md
 
-### Plans
-
 | Plan | Gaps Addressed | Files |
 |------|----------------|-------|
 | {phase}-04 | [gap truths] | [files] |
 
-### Next Steps
-
-Execute: `/gsd:execute-phase {phase} --gaps-only`
-```
+**Next step for the orchestrator:** `/gsd:execute-phase {phase} --gaps-only`
 
 ## Checkpoint Reached / Revision Complete
 

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-preconditions.md

@@ -121,7 +121,7 @@ The executor agent reads `<precondition>` before any other task work:
 |---|---|
 | **Absent** | No visible change — execute the task exactly as today. Back-compat for every existing plan. |
 | **Met** | No visible change — proceed with the task. The precondition is logged in the SUMMARY only if it was non-trivial to verify. |
-| **Unmet** | STOP — return a `checkpoint:human-verify` (use `checkpoint_return_format`) with `**Blocked by:** Precondition not met: <precondition text>`. Do NOT partial-commit the task. Unmet preconditions are NEVER auto-approved — a missing prerequisite is not a verification step a human can rubber-stamp, it is a fact the executor cannot establish on its own. |
+| **Unmet** | STOP — return a `checkpoint:human-verify` reporting `**Gate:** blocking-human` (use `checkpoint_return_format`) with `**Blocked by:** Precondition not met: <precondition text>`. Do NOT partial-commit the task. Unmet preconditions are NEVER auto-approved — a missing prerequisite is not a verification step a human can rubber-stamp, it is a fact the executor cannot establish on its own. |
 
 ## Plan-structure validation
 

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

@@ -7,7 +7,7 @@ Triggered when orchestrator sets Mode to `reviews`. Replanning from scratch with
 **Execution contract:** REVIEWS.md is audit trail and feedback input, not a second execution contract. /gsd:execute-phase primarily consumes PLAN.md plus the normal phase context. Every current actionable review finding must therefore be incorporated into the relevant PLAN.md or explicitly deferred/rejected in that PLAN.md.
 
 ### Step 1: Load REVIEWS.md
-Read the reviews file from `<files_to_read>`. Parse:
+Read the reviews file from `<required_reading>`. Parse:
 - Per-reviewer feedback (strengths, concerns, suggestions)
 - Consensus Summary (agreed concerns = highest priority to address)
 - Divergent Views (investigate, make a judgment call)

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

@@ -55,7 +55,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

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,16 +29,19 @@ 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.test_command` | `null` | Custom shell command run as the regression/test gate by verify-phase, 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.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. |
 | `manager.flags.discuss` | `""` | Flags passed to `/gsd:discuss-phase` when dispatched from manager (e.g. `"--auto --analyze"`) |
@@ -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,25 +86,27 @@ 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
 ```
 
 **Auto-detection:** If `.planning/` is gitignored, `commit_docs` is automatically `false` regardless of config.json. This prevents git errors when users have `.planning/` in `.gitignore`.
 
+**Per-phase override:** `phase_commit_docs.<phase-id>` (e.g. `phase_commit_docs.03`) overrides `commit_docs` for one phase only, and wins over both the explicit config value and gitignore auto-detection — see `docs/CONFIGURATION.md#per-phase-override-phase_commit_docs` for the full precedence chain and examples.
+
 **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.
@@ -167,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
 ```
@@ -240,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
 
@@ -261,12 +289,13 @@ 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.test_command` | string\|null | `null` | Any shell command | Regression/test gate command run by verify-phase, execute-phase, audit-fix, and post-merge-gate. Unset → GSD auto-detects (Makefile / package.json / Cargo.toml / go.mod / pyproject.toml). |
+| `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. |
@@ -275,7 +304,8 @@ Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research":
 | `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"` | `"light"`, `"standard"`, `"deep"` | Depth level for code review analysis 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`. |
@@ -298,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 |
@@ -362,7 +393,7 @@ Set via `manager.*` namespace (e.g., `"manager": { "flags": { "discuss": "--auto
 |-----|------|---------|----------------|-------------|
 | `parallelization` | boolean\|object | `true` | `true`, `false`, `{ "enabled": true }` | Enable parallel wave execution; object form allows additional sub-keys |
 | `model_overrides` | object\|null | `null` | `{ "<agent-type>": "<model-id>" }` | Override model selection per agent type |
-| `agent_skills` | object | `{}` | `{ "<agent-type>": "<skill-set>" }` | Assign skill sets to specific agent types |
+| `agent_skills` | object | `{}` | `{ "<agent-type>": "<skill-set>" }` or `{ "<agent-type>": ["<skill-set>", "<skill-set>", ...] }` | Assign skill sets to specific agent types. Each value is a single skill-set path (string) or an array of skill-set paths — the array form assigns multiple skill sets to one agent type. Paths cannot be comma-joined into one string; each path must be its own array element |
 | `sub_repos` | array | `[]` | Array of relative path strings | Child directories with independent `.git` repos (auto-detected) |
 
 ### Planning Fields
@@ -380,7 +411,7 @@ These can be set at top level or nested under `planning.*` (e.g., `"planning": {
 
 Several config fields affect each other or trigger special behavior:
 
-1. **`commit_docs` auto-detection** -- When no explicit value is set in config.json and `.planning/` is in `.gitignore`, `commit_docs` automatically resolves to `false`. An explicit `true` or `false` in config always overrides auto-detection.
+1. **`commit_docs` resolution chain** -- Four tiers, highest wins: (1) `phase_commit_docs.<phase-id>` for the phase being committed, (2) an explicit `commit_docs` (or `planning.commit_docs`) value in config.json, (3) `.gitignore` auto-detection (`.planning/` in `.gitignore` resolves to `false`), (4) the manifest default (`true`). Precedence: per-phase → explicit config → gitignore auto-detect → default.
 
 2. **`branching_strategy` controls branch templates** -- The `phase_branch_template` and `milestone_branch_template` fields are only used when `branching_strategy` is set to `"phase"` or `"milestone"` respectively. When `branching_strategy` is `"none"`, all template fields are ignored.
 
@@ -396,7 +427,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.
+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/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.

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

@@ -70,7 +70,7 @@ issues. You must reduce the count or the loop will terminate.
 If issues persist after 3 revision cycles:
 
 1. Present remaining issues to the user
-2. Use gate prompt (pattern: yes-no from `references/gate-prompts.md`):
+2. Use gate prompt (pattern: yes-no from `gsd-core/references/gate-prompts.md`):
    question: "Issues remain after 3 revision attempts. Proceed with current output?"
    header: "Proceed?"
    options:

package/gsd-core/references/runtime-aware-dispatch.md

@@ -19,7 +19,7 @@ preserves named-dispatch behavior on older GSD installs that lack the query.
 
 The persona rides `${AGENT_SKILLS_<ROLE>}` (Phase 3 / #2510) regardless of the
 resolved type — on non-Claude runtimes with no `agent_skills` config,
-`gsd-tools query agent-skills <role>` returns the installed agent prompt as
+`gsd_run query agent-skills <role>` returns the installed agent prompt as
 the block. So a coder dispatch with the planner persona injected gives kimi-code
 the planner's behavior in the coder built-in's process.
 

package/gsd-core/references/specless-probe-fallback.md

@@ -127,7 +127,7 @@ verification: backstop }` in `must_haves.truths`, NOT a prose note (the verifier
 deterministically on the `verification: backstop` field; a parenthetical is unparseable — the #1110
 fragility; flat scalar `verification:` key, never a nested object, ADR-550 #1278). A `backstop` truth
 the verifier cannot confirm with explicit evidence abstains → `human_needed` (reason
-`insufficient_spec`), never a silent pass (#1154; `references/honest-verifier.md`). **Never
+`insufficient_spec`), never a silent pass (#1154; `gsd-core/references/honest-verifier.md`). **Never
 auto-dismiss** (a wrong dismissal is the exact silent failure this eliminates). An `unclassified` row
 stays **`unresolved`** (#1110) — never auto-resolved with backstop — and is surfaced to the planner as a flagged
 assumption. Pass `$COVERAGE` (+ the gate's `$SPECLESS_FALLBACK_DISABLED` note) into the gsd-planner

package/gsd-core/references/tdd.md

@@ -289,9 +289,7 @@ When `workflow.tdd_mode` is enabled, the execute-phase orchestrator inserts a co
 ### Review Checkpoint Format
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- TDD REVIEW — Phase {X}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+### TDD REVIEW — Phase {X}
 
 TDD Plans: {count} | Gate violations: {count}
 

package/gsd-core/references/ui-brand.md

@@ -2,14 +2,51 @@
 
 Visual patterns for user-facing GSD output. Orchestrators @-reference this file.
 
+## Separators and Banners
+
+**Never emit a fixed-width run of box-drawing characters.** A run of `━`, `─` or
+`═` is ordinary text to the host that renders your output. In a narrower pane it
+wraps, leaving orphan glyphs on a second line and coming apart from the heading it
+was meant to frame. Markdown adapts to the available width; a 53-character rule
+does not.
+
+Three forms, and nothing else:
+
+| Need | Emit |
+|---|---|
+| A titled section — stage, phase, checkpoint, completion, error | `### {TITLE}` (ATX heading) |
+| A break between two sections | `---` on its own line, **with a blank line above it** |
+| A framed panel of rows | `### {TITLE}` followed by the rows as plain lines |
+
+**The blank line above `---` is load-bearing, not cosmetic.** A `---` placed
+directly under a line of text is parsed as a setext heading underline for that
+line, not as a thematic break — the rule silently swallows the line above it. A
+blank line is what makes it a thematic break. (A blank line *after* `---` is
+optional: a thematic break is a leaf block, so whatever follows starts a new
+block either way. Add one where it reads better.)
+
+**A stage banner is a heading alone — do not put a `---` above it.** An ATX
+heading already separates, and it cannot be misparsed the way a bare `---` can.
+
+### Why this is unconditional, not per-runtime
+
+The alternative considered was a `rendersMarkdown` capability key, keeping
+line-art for terminal-oriented runtimes and Markdown for Markdown hosts. It was
+rejected: it needs a new descriptor key across every runtime plus the resolver,
+and it leaves two output conventions to keep in sync forever — the divergence
+class this repo already has a defect entry for. A heading and a thematic break
+carry the same structure in a plain terminal that a rule pair did, without
+committing to a width, so the second convention buys nothing. If a runtime ever
+turns up that genuinely needs line-art, add the key then, against that evidence.
+
+---
+
 ## Stage Banners
 
 Use for major workflow transitions.
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- GSD ► {STAGE NAME}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+### GSD ► {STAGE NAME}
 ```
 
 **Stage names (uppercase):**
@@ -25,20 +62,18 @@ Use for major workflow transitions.
 
 ---
 
-## Checkpoint Boxes
+## Checkpoint Panels
 
-User action required. 62-character width.
+User action required.
 
 ```
-╔══════════════════════════════════════════════════════════════╗
-║  CHECKPOINT: {Type}                                          ║
-╚══════════════════════════════════════════════════════════════╝
+### CHECKPOINT: {Type}
 
 {Content}
 
-──────────────────────────────────────────────────────────────
-→ {ACTION PROMPT}
-──────────────────────────────────────────────────────────────
+---
+
+**→ {ACTION PROMPT}**
 ```
 
 **Types:**
@@ -60,6 +95,9 @@ User action required. 62-character width.
 🎉 Milestone complete (only in banner)
 ```
 
+Status symbols are single characters, not runs — they do not wrap and are
+unaffected by the separator rule above.
+
 ---
 
 ## Progress Display
@@ -79,6 +117,9 @@ Tasks: 2/4 complete
 Plans: 3/5 complete
 ```
 
+The bar itself is a fixed 10-cell gauge, not a separator; it is intentionally
+fixed-width and stays as it is.
+
 ---
 
 ## Spawning Indicators
@@ -104,7 +145,7 @@ Plans: 3/5 complete
 Always at end of major completions.
 
 ```
-───────────────────────────────────────────────────────────────
+---
 
 ## ▶ Next Up
 
@@ -114,23 +155,19 @@ Always at end of major completions.
 
 `{copy-paste command}`
 
-───────────────────────────────────────────────────────────────
+---
 
 **Also available:**
 - `/gsd-alternative-1` — description
 - `/gsd-alternative-2` — description
-
-───────────────────────────────────────────────────────────────
 ```
 
 ---
 
-## Error Box
+## Error Panel
 
 ```
-╔══════════════════════════════════════════════════════════════╗
-║  ERROR                                                       ║
-╚══════════════════════════════════════════════════════════════╝
+### ERROR
 
 {Error description}
 
@@ -149,14 +186,21 @@ Always at end of major completions.
 | 3     | ○      | 0/2   | 0%       |
 ```
 
+Table rules use ASCII `-`, never box-drawing characters.
+
 ---
 
 ## Anti-Patterns
 
-- Varying box/banner widths
-- Mixing banner styles (`===`, `---`, `***`)
+- Fixed-width runs of `━`, `─` or `═` as separators — they wrap in a narrow pane
+- Box panels drawn with double-line box characters (U+2554, U+2557, U+255A, U+255D, U+2551, U+2560, U+2563) — the borders wrap independently of their contents. They are named here by code point rather than shown, because the guard below rejects the characters themselves anywhere in shipped content.
+- A `---` directly under a line of text with no blank line between — that is a setext heading underline, not a break, and it swallows the line above
+- Boxing a heading between two rules — the heading is the separator
+- Mixing banner styles (`===`, `***`)
 - Skipping `GSD ►` prefix in banners
 - Random emoji (`🚀`, `✨`, `💫`)
 - Missing Next Up block after completions
 
+Enforced by `tests/responsive-separators.test.cjs`.
+
 </ui_patterns>

package/gsd-core/references/ui-consideration-probe.md

@@ -69,5 +69,5 @@ closed). The **open subset is prose-owned in [domain-probes.md](./domain-probes.
 real-time/offline/optimistic-UI, deep accessibility (WCAG breadth), i18n / RTL depth, and
 emerging interaction paradigms (gesture/voice/reduced-motion/print) are open-ended and
 cue-triggered — they do not belong in this closed taxonomy. This probe **complements** the
-`gsd-ui-checker` six quality dimensions (it adds a state-coverage axis); it does not change the
+`gsd-ui-checker` seven quality dimensions (it adds a state-coverage axis); it does not change the
 BLOCK/FLAG/PASS enum or the dimensions themselves.