@opengsd/gsd-core 1.11.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-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-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,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,11 +289,12 @@ 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. |
@@ -278,6 +305,7 @@ Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research":
 | `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 |
@@ -398,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. 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/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/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/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.

package/gsd-core/references/universal-anti-patterns.md

@@ -34,7 +34,7 @@ Reference: `gsd-core/references/questioning.md` for the full anti-pattern list.
 
 ## State Management Anti-Patterns
 
-15. **No direct Write/Edit to STATE.md or ROADMAP.md for mutations.** Always use `gsd-tools query` for registered state/roadmap handlers (e.g. `state.update`, `state.advance-plan`, `roadmap.update-plan-progress`), or legacy `node …/gsd-tools.cjs` for CLI-only commands. Direct Write tool usage bypasses safe update logic and is unsafe in multi-session environments. Exception: first-time creation of STATE.md from template is allowed.
+15. **No direct Write/Edit to STATE.md or ROADMAP.md for mutations.** Always use `gsd_run query` for registered state/roadmap handlers (e.g. `state.update`, `state.advance-plan`, `roadmap.update-plan-progress`), or legacy `node …/gsd-tools.cjs` for CLI-only commands. Direct Write tool usage bypasses safe update logic and is unsafe in multi-session environments. Exception: first-time creation of STATE.md from template is allowed.
 
 ## Behavioral Rules
 
@@ -53,7 +53,7 @@ Reference: `gsd-core/references/questioning.md` for the full anti-pattern list.
 ## GSD-Specific Rules
 
 24. **Do not** check for `mode === 'auto'` or `mode === 'autonomous'` -- GSD uses `yolo` config flag. Check `yolo: true` for autonomous mode, absence or `false` for interactive mode.
-25. **Prefer `gsd-tools query`** for orchestration when a handler exists; when shelling out to the legacy CLI, use **`gsd-tools.cjs`** (not `gsd-tools.js` or any other filename) — GSD ships the programmatic API as CommonJS for Node.js CLI compatibility.
+25. **Prefer `gsd_run query`** for orchestration when a handler exists; when shelling out to the legacy CLI, go through the same `gsd_run` launcher rather than naming the shim file. The shim is not on PATH under any name ending in `.cjs`, and an agent that meets the bare filename falls back to searching the filesystem for it — on Git Bash for Windows that is a full-drive `find.exe` traversal (#3809). `gsd_run` resolves the CommonJS shim itself across every runtime home.
 26. **Plan files MUST follow `{padded_phase}-{NN}-PLAN.md` pattern** (e.g., `01-01-PLAN.md`). Never use `PLAN-01.md`, `plan-01.md`, or any other variation -- gsd-tools detection depends on this exact pattern.
 27. **Do not start executing the next plan before writing the SUMMARY.md for the current plan** -- downstream plans may reference it via `@` includes.
 

package/gsd-core/references/verify-command-path-resolvability.md

@@ -0,0 +1,42 @@
+# Verify Command Path Resolvability (#2401)
+
+> Reference file for gsd-plan-checker agent. Loaded on-demand via `@` reference.
+
+**Question:** Does each `<automated>` command's target directory actually resolve from the
+executor's cwd (the project root)? Format sanity above asks whether the *pattern* can match;
+this asks whether the command can *run at all*.
+
+**Do not hand-reason the filesystem.** #2401 is precisely the failure of doing so: this
+checker flagged a bad `cd ../../frontend` (correct), then prescribed two successively-wrong
+replacement paths — the second citing a `package.json` that did not exist. Consume the
+deterministic probe result, never re-derive it yourself.
+
+`gsd-core/workflows/plan-phase.md` already runs the probe **before** spawning this checker and
+interpolates the result into the verification prompt as `{VERIFY_PATHS}`, inside a
+`<verify_command_path_probe>` block. This dimension reads that already-supplied JSON — it never
+invokes `gsd_run check verify-command-paths` itself. If `{VERIFY_PATHS}` is absent from the
+prompt, treat this dimension as silent (nothing to check) rather than trying to run the probe.
+
+The probe never executes command text (PLAN.md is untrusted, LLM-authored). It recognizes two
+grounded forms — a leading `cd <literal>` chain and `npm --prefix <literal>` — and refuses to
+guess at anything else.
+
+**Process:** for each row in `.commands`, act on `severity` only:
+
+| `severity` | `reason` | Action |
+|---|---|---|
+| `blocker` | `missing_dir` / `no_manifest` | **BLOCKER** — quote `rawTarget` and `target` verbatim |
+| `warning` | `dynamic_path` / `outside_root` / `script_missing` / `manifest_unreadable` | **WARNING** |
+| `none` | — | silent |
+
+Rules:
+- **Report, never prescribe.** State the target that failed to resolve and what was missing.
+  Choosing the replacement is the planner's job — it now receives the prior phase's proven
+  commands (see `prior_verify_commands` in the planning context).
+- `status: pending_creation` means an earlier task in this phase creates that directory. **Not
+  a finding.** Say nothing.
+- `unresolvable` means the probe could not ground the path (a variable, glob, substitution, or
+  `~`). That is a WARNING, never a BLOCKER — and never a licence to guess the literal path.
+- A non-empty `readError` means the probe **could not look**. Report that as a WARNING in its
+  own words; it is not a clean bill of health.
+- `MISSING …` sentinels are Dimension 8's business — this dimension stays silent on them.

package/gsd-core/references/verify-mvp-mode.md

@@ -14,7 +14,7 @@ The user-flow form mirrors what a real user does: open, fill, click, see. No HTT
 ## When this framing applies
 
 The framing fires when:
-- The phase under verification has `**Mode:** mvp` in ROADMAP.md (parsed via `gsd-tools query roadmap.get-phase --pick mode`).
+- The phase under verification has `**Mode:** mvp` in ROADMAP.md (parsed via `gsd_run query roadmap.get-phase --pick mode`).
 - AND the phase has a user-story-formatted goal (set by `/gsd mvp-phase` per Phase 2): "As a [user role], I want to [capability], so that [outcome]."
 
 If the phase has `mode: mvp` but the goal is NOT in user-story format, the verifier surfaces this as a discrepancy and asks the user to run `/gsd mvp-phase` to reformat the goal — same pattern as the planner agent under MVP_MODE (per `gsd-core/references/planner-mvp-mode.md`).

package/gsd-core/references/workstream-flag.md

@@ -109,19 +109,19 @@ This ensures workstream scope chains automatically through the workflow:
 ## CLI Usage
 
 ```bash
-# All gsd-tools query commands accept --ws
-gsd-tools query state.json --ws feature-a
-gsd-tools query find-phase 3 --ws feature-b
+# All gsd_run query commands accept --ws
+gsd_run query state.json --ws feature-a
+gsd_run query find-phase 3 --ws feature-b
 
 # Session-local switching without --ws on every command
-GSD_SESSION_KEY=my-terminal-a gsd-tools query workstream.set feature-a
-GSD_SESSION_KEY=my-terminal-a gsd-tools query state.json
-GSD_SESSION_KEY=my-terminal-b gsd-tools query workstream.set feature-b
-GSD_SESSION_KEY=my-terminal-b gsd-tools query state.json
+GSD_SESSION_KEY=my-terminal-a gsd_run query workstream.set feature-a
+GSD_SESSION_KEY=my-terminal-a gsd_run query state.json
+GSD_SESSION_KEY=my-terminal-b gsd_run query workstream.set feature-b
+GSD_SESSION_KEY=my-terminal-b gsd_run query state.json
 
 # Workstream CRUD
-gsd-tools query workstream.create <name>
-gsd-tools query workstream.list
-gsd-tools query workstream.status <name>
-gsd-tools query workstream.complete <name>
+gsd_run query workstream.create <name>
+gsd_run query workstream.list
+gsd_run query workstream.status <name>
+gsd_run query workstream.complete <name>
 ```

package/gsd-core/templates/README.md

@@ -18,7 +18,7 @@ These files live directly at `.planning/` — not inside phase subdirectories.
 | `REQUIREMENTS.md` | `requirements.md` | `/gsd:new-milestone` | Functional requirements with traceability |
 | `MILESTONES.md` | `milestone.md` | `/gsd:complete-milestone` | Log of completed milestones with accomplishments |
 | `BACKLOG.md` | *(inline)* | `/gsd-add-backlog` | Pending ideas and deferred work |
-| `LEARNINGS.md` | *(inline)* | `/gsd:extract-learnings`, `/gsd:execute-phase` | Phase retrospective learnings for future plans |
+| `LEARNINGS.md` | *(inline)* | `/gsd:extract-learnings`, `/gsd:execute-phase` (gated: `features.global_learnings`) | Phase retrospective learnings for future plans |
 | `THREADS.md` | *(inline)* | `/gsd:thread` | Persistent discussion threads |
 | `config.json` | `config.json` | `/gsd:new-project`, `/gsd:health --repair` | Project-specific GSD configuration |
 | `CLAUDE.md` | `claude-md.md` | `/gsd-profile` | Auto-assembled Claude Code context file |

package/gsd-core/templates/SECURITY.md

@@ -1,11 +1,11 @@
 ---
-phase: {N}
-slug: {phase-slug}
+phase: "{N}"
+slug: "{phase-slug}"
 status: draft
 # threats_open = count of OPEN threats at or above workflow.security_block_on severity (the blocking gate)
 threats_open: 0
 asvs_level: 1
-created: {date}
+created: "{date}"
 ---
 
 # Phase {N} — Security