@opengsd/gsd-core 1.14.0 → 1.15.0

package/gsd-core/references/gsd-run-resolver.md

@@ -4,5 +4,5 @@ Use this bootstrap block when a workflow must call `gsd-tools` from the active w
 Keep this resolver centralized; workflows should reference this file instead of copying the shell probe.
 
 ```bash
-_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif _gsd_at "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd_run is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; case "$(gsd_run runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@opengsd/gsd-core"'*'}') GSD_IDENTITY_STATUS=ok;; esac; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @opengsd/gsd-core - it is either a different package or an @opengsd/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; _gsd_id_ok() { case "$("$1" runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@opengsd/gsd-core"'*'}') return 0;; *) return 1;; esac; }; _gsd_homes() { _gsd_at "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif _gsd_homes; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; [ -n "$_G" ] && _gsd_id_ok "$_G"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and no identity-proving gsd_run is on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; _gsd_id_ok gsd_run && GSD_IDENTITY_STATUS=ok; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @opengsd/gsd-core - it is either a different package or an @opengsd/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
 ```

package/gsd-core/references/model-profiles.md

@@ -100,7 +100,7 @@ The three layers compose: `models` defaults a phase, `model_overrides` carves an
 - **Required when using non-Anthropic providers** (OpenRouter, local models, etc.) — otherwise GSD may call Anthropic models directly, incurring unexpected costs
 - Use when: you want GSD to follow your currently selected runtime model
 
-## Using Non-Claude Runtimes (Codex, OpenCode, Gemini CLI, Kilo)
+## Using Non-Claude Runtimes (Codex, OpenCode, Antigravity CLI, Kilo)
 
 When installed for a non-Claude runtime, the GSD installer sets `resolve_model_ids: "omit"` in `~/.gsd/defaults.json`. This returns an empty model parameter for all agents, so each agent uses the runtime's default model. No manual setup is needed.
 

package/gsd-core/references/phase-argument-parsing.md

@@ -27,16 +27,18 @@ Returns JSON with:
 
 ## Manual Normalization (Legacy)
 
-Zero-pad integer phases to 2 digits. Preserve decimal suffixes.
+Zero-pad the leading integer to 2 digits. Preserve a letter suffix and any dotted
+segments — the canonical grammar in `src/phase-id.cts` (`normalizePhaseName`):
+`8 → 08`, `2.1 → 02.1`, `3A → 03A`, `23.1.2 → 23.1.2`.
 
 ```bash
 # Normalize phase number
-if [[ "$PHASE" =~ ^[0-9]+$ ]]; then
-  # Integer: 8 → 08
-  PHASE=$(printf "%02d" "$PHASE")
-elif [[ "$PHASE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
-  # Decimal: 2.1 → 02.1
-  PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
+# #4748: one branch for the whole canonical token — digits, optional [A-Z],
+# dotted segments. Pad through $((10#…)) so an already-padded `08` is not read
+# as octal by printf; anything non-canonical passes through untouched.
+if [[ "$PHASE" =~ ^([0-9]+)([A-Z]?)((\.[0-9]+)*)$ ]]; then
+  PHASE_INT=${BASH_REMATCH[1]}
+  PHASE=$(printf "%02d" "$((10#$PHASE_INT))")${BASH_REMATCH[2]}${BASH_REMATCH[3]}
 fi
 ```
 

package/gsd-core/references/phase-id-convention.md

@@ -0,0 +1,28 @@
+# Bracket phase-ID convention
+
+The bracket convention is opt-in through `phase_id_convention: "bracket"`.
+Its compact grammar card below is generated from `src/phase-id-card.cts`; edit
+that module, not this block.
+
+<!-- PHASE-ID-CARD:START -->
+```text
+[GSD.02] 05.03-01
+ │   │   │  │   │
+ │   │   │  │   └── plan        01
+ │   │   │  └────── subphase    03
+ │   │   └───────── phase       05
+ │   └───────────── milestone   02
+ └───────────────── project     GSD
+
+milestone = bracket integer; dots = phase-levels; one hyphen = plan; no 'Phase' word, no vX.Y
+```
+<!-- PHASE-ID-CARD:END -->
+
+The display form is `[PROJECT.MM] PP[.SS][-LL]`: the bracket carries the
+project and milestone, dots join phase levels, and the single hyphen introduces
+the optional plan. A phase directory encodes the same identity without brackets:
+`PROJECT.MM-PP[.SS]-slug/`.
+
+Human-facing bracket surfaces omit both the literal `Phase` label and the
+legacy `vX.Y` milestone marker. Repositories using the unset, `sequential`, or
+`milestone-prefixed` conventions retain their existing display forms.

package/gsd-core/references/planner-gap-closure.md

@@ -60,3 +60,5 @@ autonomous: true
 gap_closure: true     # Flag for tracking
 ---
 ```
+
+**9. Number threat IDs after the phase's existing registers** (#4683): when `security_enforcement` is on, read the `<threat_model>` blocks of the phase's existing PLAN files and continue after their highest `T-{phase}-NN` — do not renumber from `T-{phase}-01`. Every ID already names a specific threat in an earlier plan; reusing it makes `SECURITY.md` rows and `VALIDATION.md`'s Threat Ref column ambiguous. `T-{phase}-SC` is reserved and every plan keeps it. The execute-phase init reports any cross-plan duplicates and hard-stops on them (`threat_id_duplicates`), so a collision surfaces here as a failed plan check.

package/gsd-core/references/planner-load-graph-context.md

@@ -2,35 +2,46 @@
 
 > Loaded by `gsd-planner` at the `load_graph_context` step.
 
-Check for knowledge graph:
-
-```bash
-ls .planning/graphs/graph.json 2>/dev/null
-```
-
-If graph.json exists, check freshness:
+Check for a knowledge graph and read its freshness in one call. `status` resolves the
+graph through `graphify.graph_path`, so it is also the presence gate — a bare
+`ls` of the default location misses an umbrella graph shared across sibling repos:
 
 ```bash
 _GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
 gsd_run graphify status
 ```
 
+If `exists` is `false`, continue without graph context — skip the rest of this step.
+
 If the status response has `stale: true`, note for later: "Graph is {age_hours}h old -- treat semantic relationships as approximate." Include this annotation inline with any graph context injected below.
 
-Query the graph for phase-relevant dependency context (single query per D-06):
+The same response carries `graph_path` — the resolved graph location. Substitute it for `<graph>` below. `graph_path` comes from `graphify.graph_path` in `.planning/config.json`, a config surface already trusted elsewhere; if it ever carried attacker-controlled content, the literal double-quoted substitution below would need escaping.
+
+Query the graph for phase-relevant dependency context (single query per D-06). Prefer the `graphify` CLI when it is on PATH; fall back to the built-in reader otherwise:
 
 ```bash
-gsd_run graphify query "<phase-goal-keyword>" --budget 2000
+if command -v graphify >/dev/null 2>&1; then
+  graphify query "<phase-goal-keyword>" --graph "<graph>" --budget 2000
+  graphify affected "<phase-goal-keyword>" --graph "<graph>" --depth 2
+else
+  gsd_run graphify query "<phase-goal-keyword>" --budget 2000
+fi
 ```
 
-Use the keyword that best captures the phase goal. Examples:
-- Phase "User Authentication" -> query term "auth"
+Why the CLI is preferred: it ranks seeds (IDF weighting, fuzzy matching) and applies context filters before traversal, where the built-in reader seeds by case-insensitive substring over label and description — so a term like "auth" seeds equally on `author` and `authorize` — and then expands a fixed two hops. `affected` answers "which subsystems may be affected by changes in this phase" directly, by reverse traversal; it has no built-in equivalent, so the fallback path runs the query alone.
+
+The two paths return **different shapes**: the CLI emits prose, the built-in emits JSON with per-edge confidence tiers and `budget_met`/`budget_estimate`. `--budget` caps rendered output on the CLI and estimated payload bytes in the built-in — same flag name, different unit. Read whichever you get; do not assume a stable shape and do not paste raw output into PLAN.md.
+
+Use the keyword that best captures the phase goal. Prefer the full domain word over a
+prefix of it — on the fallback path a prefix is matched as a substring, so "auth" also
+seeds on `author` and `authoring`. Examples:
+- Phase "User Authentication" -> query term "authentication"
 - Phase "Payment Integration" -> query term "payment"
 - Phase "Database Migration" -> query term "migration"
 
-If the query returns nodes and edges, incorporate as dependency context for planning:
+If the query returns related nodes, incorporate as dependency context for planning:
 - Which modules/files are semantically related to this phase's domain
 - Which subsystems may be affected by changes in this phase
 - Cross-document relationships that inform task ordering and wave structure
 
-If no results or graph.json absent, continue without graph context.
+If nothing comes back, continue without graph context.

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

@@ -15,3 +15,17 @@ command, must hold the matching `package.json`/`Makefile`. `npm --prefix <dir> r
 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.
+
+**Root-relative, never absolute (#4767).** The paths in your prompt's `<required_reading>` are
+absolute on purpose — a subagent's cwd may differ from the orchestrator's (#2376). That rule
+covers prompt *inputs* only. Every path in the plan *body* — `<files>`, `<verify>`, `<automated>`,
+task actions — is repo-root-relative, and every `<automated>` command assumes cwd at the checkout
+root. An absolute path copied from the prompt into `<automated>` pins the command to the
+orchestrator's checkout; under worktree isolation the executor's checkout is a different
+directory, so the command `cd`s into the main tree, finds it, runs, and **passes against code the
+worktree changed and the main tree did not**. The path probe reports such a target as
+`outside_root` (a warning), but only when the target is outside the *orchestrator's* root — an
+absolute path *inside* it is exactly the shape that passes the probe and still misfires under
+isolation. The authoring rule is the fix; the probe is the backstop. It binds `prior_verify_commands`
+too: a harvested command that carries an absolute path is re-rooted before reuse, never copied
+verbatim — it "worked" in a run that may have been verifying the wrong checkout.

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

@@ -40,6 +40,7 @@ Configuration options for `.planning/` directory behavior.
 | `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). |
+| `planner.stall_detection_enabled` | `true` | Default-on bounded stall detection for planner and plan-checker agents. Set to `false` to await runtime-native completion without watchdog polling; this gives up bounded automatic recovery if the completion handoff is lost. _Loader projection:_ `planner_stall_detection_enabled`. |
 | `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`. |
@@ -266,7 +267,7 @@ Generated from `CONFIG_DEFAULTS` (configuration.cjs) and `VALID_CONFIG_KEYS` (co
 | `context_window` | number | `200000` | `200000`, `1000000` | Context window size; set `1000000` for 1M-context models |
 | `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.models.<cli>` | string\|null | `null` | Any model ID string | Per-CLI model override for /gsd:review (e.g., `review.models.codex`). 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
@@ -313,6 +314,14 @@ Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research":
 | `workflow.security_block_on` | string | `"high"` | `"critical"`, `"high"`, `"medium"`, `"low"`, `"none"` | Minimum threat severity that blocks phase advancement. The auditor counts only open threats at or above this severity toward the blocking gate (SECURITY.md `threats_open`); `none` disables severity blocking. |
 | `workflow.post_planning_gaps` | boolean | `true` | `true`, `false` | Post-planning gap report (#2493). After plans are generated, scans REQUIREMENTS.md and CONTEXT.md `<decisions>` against all PLAN.md files and emits a unified `Source \| Item \| Status` table. Non-blocking. Set to `false` to skip Step 13e of plan-phase. _Alias:_ `post_planning_gaps` is the flat-key form used in `CONFIG_DEFAULTS`; `workflow.post_planning_gaps` is the canonical namespaced form. |
 
+### Planner Fields
+
+Set via the `planner.*` namespace. These settings affect only planner/plan-checker waits; executor stall controls are independent.
+
+| Key | Type | Default | Allowed Values | Description |
+|-----|------|---------|----------------|-------------|
+| `planner.stall_detection_enabled` | boolean | `true` | `true`, `false` | Default-on bounded stall detection for the standard planner, chunked outline/per-plan planners, plan-checker, and revision planner. `false` skips `gsd_stall_watch` polling but still awaits and consumes the real runtime-native agent result. It gives up bounded automatic recovery if the runtime loses the completion handoff. _Loader projection:_ `planner_stall_detection_enabled`. |
+
 ### Ship Fields
 
 Set via `ship.*` namespace in config.json. These fields affect `/gsd:ship` PRD-style pull request body composition only.
@@ -431,7 +440,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 `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).
+9. **`workflow.use_worktrees` and branch divergence** -- When `use_worktrees` is `true` (default) and `worktree.baseRef` is unset, 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`). GSD-created worktrees then fork from the live HEAD instead of `origin/HEAD` by construction, and the Claude Code harness does the same as measured from every settings layer (#4588; Cursor has not been measured — its exit-42 spawn-time guard is the backstop). A configured Claude Code `WorktreeCreate` hook is the exception: it creates the worktree without applying the setting, so GSD keeps comparing against `origin/HEAD` on such a host (#4588). A prior harness worktree at the current HEAD does not lift that comparison — it records no creator, so one left there before the hook was configured would read as evidence for the hook; pass `--observed-fork-base` for a trusted verdict (#4881). 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/tdd.md

@@ -178,10 +178,32 @@ cargo test    # Rust
 ```
 
 **5. Create first test file:**
-Follow project conventions for test location:
-- `*.test.ts` / `*.spec.ts` next to source
+Follow project conventions for test location. The RED-commit gate
+(`workflows/execute-phase.md`) recognises the patterns below at any depth, repo root
+included. Note the gate's pathspec is deliberately **wider than the project types the
+detection step above enumerates** — it costs nothing to recognise a convention the
+onboarding flow does not yet auto-detect, and a project using one should not have its
+RED commits go unseen:
+- `*.test.*` / `*.spec.*` next to source — JS/TS and anything sharing the convention
 - `__tests__/` directory
 - `tests/` directory at root
+- `*_test.go` — Go
+- `test_*.py` / `*_test.py` — Python (in addition to `tests/`)
+- `*_test.exs` — Elixir
+- `*_spec.rb` / `*_test.rb` — Ruby
+
+**Cost of the broad pathspec (#4379).** `*.spec.*` can match a non-test file that happens to carry
+the word — `api.spec.json`, `openapi.spec.yaml` — which lets the RED gate pass on a commit touching
+only that. This is not new: the previous `**/*.spec.*` already matched those at any nested path, so
+dropping the `**/` prefix only extends the same false-positive class to the repo root. It is
+accepted rather than narrowed, because narrowing it is a behaviour change to the
+currently-supported case and not part of making other languages visible.
+
+**Known gap — Rust (#4379).** `#[test]` conventionally lives inside the implementation file, so a
+Rust RED commit touches `src/*.rs` and no path-based gate can distinguish it from ordinary source.
+Widening the pathspec to cover it would match all source and make the gate meaningless. `cargo test`
+works; the RED-*commit* gate cannot see it, so a Rust project using `workflow.tdd_mode` should
+expect the gate to trip.
 
 Framework setup is a one-time cost included in the first TDD plan's RED phase.
 </framework_setup>
@@ -275,8 +297,9 @@ After completing a `type: tdd` plan, the executor validates the git log:
 # The commit protocol promises no zero-padding for ${PHASE}/${PLAN} — strip both and
 # match the commit-scope position anchored (#4003). #4619: PHASE may be decimal/
 # N-segment; zero-strip only the leading integer segment, escape the rest.
-PHASE_INT=${PHASE%%.*}; PHASE_FRAC=${PHASE#"$PHASE_INT"}
-PHASE_N="$((10#$PHASE_INT))${PHASE_FRAC//./\\.}"
+# #4748: it may also carry a letter suffix (03A), so split at the first non-digit.
+PHASE_INT=${PHASE%%[!0-9]*}; PHASE_REST=${PHASE#"$PHASE_INT"}
+PHASE_N="$((10#$PHASE_INT))${PHASE_REST//./\\.}"
 PLAN_N=$((10#${PLAN}))
 # Check for RED gate commit
 git log --oneline -E --grep="^test\((0*${PHASE_N})-(0*${PLAN_N})\):" | head -1

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

@@ -15,11 +15,16 @@ here. Forcing them into a closed compiled taxonomy is the wrong model.
 
 ## Inputs
 
-A list of UI elements, each a `{ id, text, elements? }` record where `text` is the
-researcher-authored description and `elements` is an optional author-supplied override of the
-element classification. The six element kinds are: `form`, `list-collection`, `nav`, `media`,
-`interactive-control`, `static-content`. When `elements` is absent, a heuristic classifier
-proposes kinds from the prose (propose-then-confirm) — the author may correct the kind.
+A list of UI elements, each a `{ id, text, text_en?, elements? }` record where `text` is the
+researcher-authored description, `elements` is an optional author-supplied override of the
+element classification, and `text_en` is an optional English translation of `text`
+(#4657). The element cues are English word-boundary patterns, so a non-English `text` (a
+project running with `response_language` set) classifies to zero kinds unless `text_en`
+carries a faithful English rendering — engine input, never user-facing output; `text`
+itself keeps the UI-SPEC's own language and is never translated. The six element kinds are:
+`form`, `list-collection`, `nav`, `media`, `interactive-control`, `static-content`. When
+`elements` is absent, a heuristic classifier proposes kinds from the prose
+(`text_en ?? text`, propose-then-confirm) — the author may correct the kind.
 
 ## Taxonomy (8 categories)
 

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

@@ -11,8 +11,9 @@ checker flagged a bad `cd ../../frontend` (correct), then prescribed two success
 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
+`gsd-core/workflows/plan-phase.md` — and, since #4767, quick mode's
+`quick/steps/plan-checker-loop.md` (via `--dir`) — 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.
@@ -37,6 +38,13 @@ Rules:
   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.
+- `outside_root` covers two shapes: a bare ancestor climb (`cd ../..`) and an **absolute target
+  outside the project root** (#4767). Both are ambiguous across worktrees; the absolute one is
+  pinned to a single checkout, so under worktree isolation it runs against the wrong tree and
+  passes. Report it as a WARNING with the target verbatim. Note the probe's root is the
+  *orchestrator's*: an absolute path inside it passes here and still misfires under isolation,
+  which is why the planner's path-form rule (root-relative, cwd at the checkout root) is the fix
+  and this probe the backstop.
 - 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.