@opengsd/gsd-core 1.13.0 → 1.15.0

package/gsd-core/references/execute-phase-wave-guard.md

@@ -1,10 +1,10 @@
 0.5. **Inter-wave worktree base re-check (wave N+1 guard — #1369):**
 
    After Wave N merges and tracking commits advance orchestrator HEAD, Claude Code's
-   `isolation="worktree"` still forks new worktrees from `origin/HEAD` (the "fresh" base),
-   not the live HEAD. This means Wave N+1 worktrees would be created from the stale
-   pre-Wave-N base, causing the `worktree_branch_check` guard inside each executor to halt
-   immediately with a base-mismatch fatal.
+   `isolation="worktree"` forks new worktrees from `origin/HEAD` (the "fresh" base) unless
+   `worktree.baseRef:"head"` is set — not the live HEAD. Without the setting, Wave N+1
+   worktrees would be created from the stale pre-Wave-N base, causing the
+   `worktree_branch_check` guard inside each executor to halt with a base-mismatch fatal.
 
    **Run this check at the start of every wave when `USE_WORKTREES != "false"` and
    `ISOLATION = "harness-worktree"`** (#2652 — the harness caches the fork base, so this is a
@@ -30,10 +30,21 @@
    this check and may re-enable worktree isolation once `origin/HEAD` matches HEAD again
    (e.g. via `git fetch` or a push that advances it).
 
-   **Why `worktree.baseRef:"head"` does not avoid this degrade (#48, #3659):** the runtime
-   harness does not read project-settings `baseRef` — an isolated dispatch always forks from
-   `origin/HEAD` regardless of the setting, so the check compares against the real fork base
-   and degrades whenever HEAD has diverged. Parallel worktrees return once HEAD is
-   merged/pushed so `origin/HEAD` matches it. The setting still restores parallel execution
-   on runtimes where GSD itself creates the worktrees (orchestrator-managed isolation:
-   Codex, OpenCode, Kimi, Kimi Code). See #683 for the base-ref configuration detail.
+   **How `worktree.baseRef:"head"` interacts with this degrade (#3659, #4588):** with the
+   setting in place the check trusts it and does not compare — the worktree creator forks from the
+   orchestrator HEAD (GSD's own `git worktree add` by construction; the Claude Code harness as
+   measured from all three settings layers, #4588; Cursor unmeasured), so outside the two
+   exceptions below this guard only fires when the setting
+   is absent and HEAD has diverged from `origin/HEAD`. Parallel worktrees then return once HEAD
+   is merged/pushed so `origin/HEAD` matches it, or once the setting is applied. The exceptions
+   (#4588): a supplied `--observed-fork-base` is compared against HEAD instead of trusted, in
+   both modes; and on a harness-created run with no observation, a Claude Code `WorktreeCreate`
+   hook in any of those settings files — or one of them that does not parse, so a hook cannot be
+   ruled out — withholds the trust: the hook creates the worktree without applying the setting,
+   so the check compares against `origin/HEAD` anyway and a mismatch degrades with
+   `baseref-head-bypassed-by-hook`. The #4868 prior-worktree observation does not lift that
+   degrade: a worktree at HEAD records nothing about which creator left it there, so one the
+   plain harness created before the hook was configured reads the same as one the hook created
+   (#4881). On a hook host only `--observed-fork-base` restores a trusted verdict. The exit-42
+   guard in each executor remains the backstop on a host that does not honor the setting.
+   See #683 for the base-ref configuration detail.

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/loop-hook-dispatch.md

@@ -57,6 +57,24 @@ Dispatch the referenced unit. Exactly one of `ref.skill`, `ref.agent`, or `ref.c
 
 Wait for the result before continuing to the next hook or the next step.
 
+**`supportsReviewerLanes` (optional, boolean).** A `step` entry may carry
+`supportsReviewerLanes: true` alongside `ref` (#4209). A workflow opts a step into external
+reviewer-lane dispatch by calling `gsd_run review-lane dispatch-step --cap-id <capId> --point
+<point> --explicit <slugs> ...` — `dispatch-step` resolves its OWN active hook for `<point>` (via
+`resolveActiveHooksForPoint`, the same in-process resolver `loop render-hooks` itself calls) and
+checks whether `<capId>`'s hook carries this field before proceeding; the workflow does not
+resolve or gate on the trait itself, only passes the two flags naming which step it is. When the
+trait reads exactly `true`, `dispatch-step` routes through `dispatchReviewerLanes`, the one
+interpreter in `src/reviewer-step-dispatch.cts` that reuses the existing reviewer-lane selection,
+planning, and invocation machinery, so any explicitly selected reviewer lane also reviews the
+same scope. Absent or `false` is inert: `dispatch-step` itself is a no-op (a non-boolean value is
+rejected by `capability-validator.cjs` at load time, so it never reaches `dispatch-step` at all).
+This is the only place a step opts into reviewer-lane support: a capability beyond `code-review`
+reuses it by declaring the same trait on its own step and calling `dispatch-step` with
+`--cap-id`/`--point`, with zero bespoke TRAIT-RESOLUTION code of its own. The workflow still owns
+matching its own CLI flags against the reviewer-lane roster and assembling the evidence block
+handed to its consolidator — those are NOT part of what this trait makes reusable.
+
 A `step` is **advisory by construction**: it never blocks or redirects the host workflow —
 that is what a `gate` is for. Each dispatch is best-effort; on error record a warning and
 continue, honoring `onError`.

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

@@ -58,6 +58,10 @@ Model profiles control which Claude model each GSD agent uses. This allows balan
 3. **Profile table** — the per-agent column from the active `model_profile`
 4. **Runtime default** — when nothing else applies
 
+Steps 2–4 select the *tier*; a `model_profile_overrides.<runtime>.<tier>` entry then
+maps that tier to a concrete model (#4192 — honored on the claude runtime as well, so
+pinning composes with tiering instead of replacing it).
+
 ### Why two layers above the profile?
 
 - **Profile** is a global tier strategy (everyone runs balanced).
@@ -96,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.
 
@@ -215,8 +219,11 @@ is (highest → lowest):
    (see §Dynamic Routing — escalation steps tier up per attempt counter)
 4. If no dynamic_routing match, check models[phase_type] for a phase-type tier
    (see §Per-Phase-Type Model Map for the agent → phase-type mapping)
-5. If no phase-type slot, look up agent in profile table
-6. Pass model parameter to Task call
+5. Check model_profile_overrides.<runtime>.<tier> for a per-tier model override
+   (honored on the claude runtime too — #4192; verbatim unless it maps to the
+   current tier alias)
+6. If no phase-type slot, look up agent in profile table
+7. Pass model parameter to Task call
 ```
 
 `model` and `effort` resolve through different mechanisms at different
@@ -246,7 +253,9 @@ Override specific agents without changing the entire profile:
 }
 ```
 
-Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `haiku`, `inherit`, or any fully-qualified model ID (e.g., `"o3"`, `"openai/o3"`, `"google/gemini-2.5-pro"`).
+Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `haiku`, `fable`, `inherit`, or any fully-qualified model ID (e.g., `"o3"`, `"openai/o3"`, `"google/gemini-2.5-pro"`). `fable` is a Claude Code Agent-tool alias, not a GSD profile tier — it has no column in the profile table above.
+
+On the Claude runtime, fully-qualified Claude model IDs are honored as explicit generation pins (#4192): an ID that names the current tier default (e.g. `"claude-sonnet-5"`) resolves to its tier alias — the same model in the form the Agent tool always accepts — while any other ID (e.g. `"claude-opus-4-7"`) resolves verbatim, with a warn-once stderr note that setups accepting only tier aliases will not honor a full ID. To pin a generation for a whole tier rather than one agent, set `model_profile_overrides.claude.<tier>` (see docs/CONFIGURATION.md — Runtime-Aware Profiles).
 
 ## Switching Profiles
 

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
@@ -289,6 +290,7 @@ 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.compact_content` | boolean | `false` | `true`, `false` | Compact content mode (#4139, ADR-4139) — per-project boolean selecting terser payloads. Six workflows branch on it via spine+detail: `plan-phase` (#4402, pilot), `execute-phase`, `docs-update`, `new-project`, `verify-work`, `complete-milestone` (#4405). The rest of the eager-window corpus was reviewed and recorded as not worth splitting (`docs/PARTITION-RULES.md`). Lazily-`Read` workflow fragments and `gsd-core/templates/**` templates use a `.compact.md` sibling instead (#4406, `gsd-core/references/compact-content-gate.md` § "Streams 1b and 4") — wired today for `help --full` and the sequential-execution `SUMMARY.md`/`USER-SETUP.md` reads. Agent-skill payloads (#4407, § "Stream 2") use the same `.compact.md` sibling shape, resolved in code by the `gsd_run query agent-skills` CLI seam rather than prose, for the non-Claude persona fallback only |
 | `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 |
@@ -312,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.
@@ -360,6 +370,8 @@ Set via `hooks.*` namespace (e.g., `"hooks": { "context_warnings": true }`).
 | Key | Type | Default | Allowed Values | Description |
 |-----|------|---------|----------------|-------------|
 | `hooks.context_warnings` | boolean | `true` | `true`, `false` | Show warnings when context budget is exceeded |
+| `hooks.context_warning_threshold` | number | `35` | Greater than 0 and at most 100, and strictly greater than `hooks.context_critical_threshold`. `config-set` refuses 0: nothing is below it, so no critical value could satisfy the pair | Percent of context window REMAINING at or below which the monitor emits CONTEXT WARNING. An out-of-domain value falls back **per key**; both keys revert to their defaults only when the RESOLVED pair violates `critical < warning`. Read from the root project config — a workstream-scoped `config-set` does not reach this hook. Inert on a runtime with no context-monitor hook installed, Codex among them (#2586); see [context-monitor.md](../../docs/context-monitor.md) (#4285) |
+| `hooks.context_critical_threshold` | number | `25` | At least 0 and less than 100, and strictly less than `hooks.context_warning_threshold`. `config-set` refuses 100: nothing is above it, so no warning value could satisfy the pair | Percent of context window REMAINING at or below which the monitor escalates to CONTEXT CRITICAL. Setting only one of the pair is checked against the other's default, so tune both when moving either past the other. Same root-config scope, and the same installed-monitor prerequisite, as the key above (#4285) |
 
 ### Learnings Fields
 
@@ -428,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>
@@ -273,8 +295,12 @@ When `workflow.tdd_mode` is enabled in config, the RED/GREEN/REFACTOR gate seque
 After completing a `type: tdd` plan, the executor validates the git log:
 ```bash
 # The commit protocol promises no zero-padding for ${PHASE}/${PLAN} — strip both and
-# match the commit-scope position anchored (#4003).
-PHASE_N=$((10#${PHASE})); PLAN_N=$((10#${PLAN}))
+# match the commit-scope position anchored (#4003). #4619: PHASE may be decimal/
+# N-segment; zero-strip only the leading integer segment, escape the rest.
+# #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
 # Check for GREEN gate commit  

package/gsd-core/references/thinking-models-planning.md

@@ -34,13 +34,29 @@ For each significant decision in this plan, ask what undoing it would cost three
 
 This is the reasoning step that produces the rating. The taxonomy itself, the emission rules, and the anti-patterns live in @~/.claude/gsd-core/references/planner-reversibility.md — do not maintain a second classification here.
 
-## 5. Curse of Knowledge Counter
+## 5. Occam's Razor
+
+**Counters:** Plans that prescribe avoidable dependencies, abstractions, files, or speculative flexibility before execution begins.
+
+This check complements the planner's RESEARCH.md `dont_hand_roll` guidance and the plan checker's Dimension 12 (Pattern Compliance): those sources identify capabilities and established patterns, while this check orders otherwise sufficient implementation choices. The executor applies the related check later in `thinking-models-execution.md`, after the plan has already selected an approach.
+
+After preserving locked user decisions and complete requirement coverage, choose the first option that is demonstrably sufficient for the task's `<done>` condition:
+
+1. Existing project behavior, helper, or established pattern
+2. Standard-library capability
+3. Native platform capability
+4. Already-installed dependency
+5. Minimum new implementation
+
+This ordering is a sufficiency check, not permission to make the task smaller. It must never reduce requested scope or override locked user decisions, requirement coverage, security, validation, accessibility, error handling, or verification. The planner uses it when choosing implementation actions; the plan checker flags a new abstraction or dependency only when a higher rung is demonstrably sufficient.
+
+## 6. Curse of Knowledge Counter
 
 **Counters:** Plan-to-executor ambiguity from compressed instructions.
 
 For each `<action>` step, re-read it as if you have NEVER seen this codebase. Is every noun unambiguous (which file? which function? which endpoint?)? Is every verb specific (add WHERE? modify HOW?)? If a step could be interpreted two ways, rewrite it. Include file paths, function names, and expected behavior in every action step.
 
-## 6. Base Rate Neglect Counter
+## 7. Base Rate Neglect Counter
 
 **Counters:** Planners ignoring low-confidence research caveats.
 

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/verification-patterns.md

@@ -309,14 +309,17 @@ grep -r "$hook_name()" src/ --include="*.tsx" --include="*.ts" | grep -v "$hook_
 # .env file exists
 [ -f ".env" ] || [ -f ".env.local" ]
 
-# Required variable is defined
-grep -E "^$VAR_NAME=" .env .env.local 2>/dev/null
+# Required variable is defined (in the environment: dotenv/direnv/the framework has loaded it)
+printenv "$VAR_NAME" >/dev/null
 ```
 
 **Substantive check:**
 ```bash
-# Variable has actual value (not placeholder)
-grep -E "^$VAR_NAME=.+" .env .env.local 2>/dev/null | grep -v "your-.*-here|xxx|placeholder|TODO" -i
+# Variable has an actual value (not a placeholder) -- tests the shape, never prints the value;
+# exit 0 = real value, exit 1 = missing or placeholder (case-insensitive)
+v=$(printenv "$VAR_NAME"); case "$(printf %s "$v" | tr '[:upper:]' '[:lower:]')" in
+  ""|*your-*-here*|*xxx*|*placeholder*|*todo*) exit 1;;
+esac
 
 # Value looks valid for type:
 # - URLs should start with http
@@ -324,6 +327,16 @@ grep -E "^$VAR_NAME=.+" .env .env.local 2>/dev/null | grep -v "your-.*-here|xxx|
 # - Booleans should be true/false
 ```
 
+When the variable is not present in the agent's own environment (a framework that loads
+`.env.local` itself at runtime does not export it to the shell that runs these checks),
+ask the user to confirm it is set rather than reading `.env` directly. Variable NAMES can
+still be checked against `.env.example`, which the secret-read guard exempts from its
+protected-file patterns.
+
+One guard-matching note worth knowing when auditing docs for `.env` mentions: the guard
+treats a grep PATTERN whose last path segment is a secret file name as a file operand, so
+`grep -n "\.env" file.md` is denied while `grep -n "\.env\b" file.md` is allowed.
+
 **Stub patterns specific to env:**
 ```bash
 # RED FLAGS - These are stubs:

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.