@opengsd/gsd-core 1.14.0 → 1.16.0

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

@@ -15,9 +15,9 @@ The user-flow form mirrors what a real user does: open, fill, click, see. No HTT
 
 The framing fires when:
 - 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]."
+- 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`).
+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`).
 
 ## Generated UAT script structure under MVP mode
 

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

@@ -77,13 +77,43 @@ and broader temp hygiene is left to OS temp cleanup or future maintenance work.
 
 ## Routing Propagation
 
-All workflow routing commands include `${GSD_WS}` which:
-- Expands to `--ws <name>` when a workstream is active
-- Expands to empty string in flat mode (backward compatible)
+Every workstream-scoped workflow parses the `--ws <name>` it was started with out of
+`$ARGUMENTS` in each shell fence that needs it (fences are separate shells, so nothing is
+carried over between them) and sets `GSD_WS`:
+- `GSD_WS` is `--ws <name>` when the command was started with `--ws`, and empty otherwise
+  (flat mode, backward compatible). It is always re-assigned, so a stale value never leaks in.
+- Every `gsd_run query agent-skills <agent>` and `gsd_run query init.*` call in those
+  workflows forwards it as the single token `${GSD_WS:+--ws=${GSD_WS##* }}`. The explicit
+  flag has the highest priority above, so the workstream a command was started for wins over
+  the session pointer and the shared marker. The single-token form is required because zsh
+  does not word-split an unquoted `$GSD_WS`.
+- Workflows recognize the documented spelling `--ws <name>`; `--ws=<name>` is accepted by the
+  CLI itself but is not parsed out of `$ARGUMENTS` by workflows.
+- Routing suggestions (`/gsd:plan-phase {X} ${GSD_WS}`) carry the same value to the next command.
+- Project and workspace lifecycle workflows (`new-project`, `new-workspace`,
+  `list-workspaces`, `remove-workspace`, `update`) are root-scoped and do not forward it.
+
+`tests/agent-skills.test.cjs` scans every fenced call in `gsd-core/workflows/` so a new call
+that omits the flag fails CI.
 
 This ensures workstream scope chains automatically through the workflow:
 `new-milestone → discuss-phase → plan-phase → execute-phase → transition`
 
+## Reserved names
+
+`none` (case-insensitive) cannot name a workstream. `--ws none`, `--ws=none`, `GSD_WORKSTREAM=none`
+and a pointer of `none` are all rejected with a "reserved" error, and `workstream create` and
+`workstream set` refuse it unconditionally. The one exception on the read side is a
+`.planning/workstreams/none/` directory that already exists: it stays addressable with `--ws none`
+so projects that used the name before it was reserved keep working (the directory name must match
+exactly; `NONE` is still rejected). Such a grandfathered directory is reachable through `--ws` and
+`GSD_WORKSTREAM` only, because `workstream set none` refuses unconditionally. To force flat mode,
+omit `--ws`, unset `GSD_WORKSTREAM`, or clear the pointer (`workstream set --clear`). The rejection
+happens before any command runs, so a stale `GSD_WORKSTREAM=none` in the environment must be unset
+first. The reserved list has a single owner
+(`RESERVED_WORKSTREAM_NAMES` in `src/workstream-name-policy.cts`); near-misses such as `none1` or
+`nonexistent` are ordinary names.
+
 ## Directory Structure
 
 ```

package/gsd-core/references/worktree-path-safety.md

@@ -175,3 +175,324 @@ fi
 **Prefer relative paths** for all Edit/Write operations. When an absolute path is
 unavoidable, always derive it from `git rev-parse --show-toplevel` run inside the
 worktree — never from `pwd` captured in the orchestrator context.
+
+---
+
+## `<automated>` command guard — step 0c (#4767)
+
+The plan's `<automated>` text is where an orchestrator-cwd absolute path most often
+arrives: the planner saw absolute paths in its own context and wrote one into the
+command. Run as written, `cd /abs/main-checkout/… && <test>` leaves the worktree, runs
+against the main tree, and **passes on code this worktree changed and the main tree did
+not** — a green verify that verified nothing. Before executing any `<automated>` command,
+scan its text for absolute paths and halt if one is outside the worktree. Fail loud; never
+rewrite the prefix silently (#3050) — a rewritten command hides the defective plan, and the
+next executor meets it again.
+
+```bash
+# WT_ROOT as in step 0b. MAIN_ROOT is the checkout this worktree was created from — the one an
+# orchestrator-cwd path points at.
+WT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+MAIN_ROOT=$(cd "$(git rev-parse --git-common-dir)/.." 2>/dev/null && pwd -P)
+# Resolve a path the way the shell would land in it. A relative path is taken from the second
+# argument — the cwd a chained `cd` has reached so far — or the worktree root. An existing directory resolves through `cd && pwd -P`; a file through its directory (a
+# symlinked file through its link target first), so a symlink or `..` hop inside the worktree that
+# lands in the main checkout is seen for what it is; a path that does not exist yet — a Wave-0
+# scaffold — is normalized lexically and must still PASS when it sits under the worktree. Never
+# `readlink -m` / `realpath -m` — GNU-only. `_norm` splits with `read -ra` (no glob expansion) and
+# expands the array with the `${a[@]+"${a[@]}"}` idiom (bash < 4.4 errors on an empty array under -u).
+_norm(){ local -a out=() seg; local s; IFS=/ read -ra seg <<<"$1"
+  for s in ${seg[@]+"${seg[@]}"}; do case "$s" in ''|.) ;; ..) [ ${#out[@]} -gt 0 ] && unset 'out[${#out[@]}-1]' ;; *) out+=("$s") ;; esac; done
+  printf '/%s' ${out[@]+"${out[@]}"}; [ ${#out[@]} -gt 0 ] || printf '/'; }
+_resolve(){ local p t; case "$1" in /*) p=$1 ;; *) p="${2:-$WT_ROOT}/$1" ;; esac
+  if [ -L "$p" ] && ! [ -d "$p" ]; then t=$(readlink "$p"); case "$t" in /*) p=$t ;; *) p="$(dirname -- "$p")/$t" ;; esac; fi
+  ( cd -- "$p" 2>/dev/null && pwd -P ) \
+  || ( cd -- "$(dirname -- "$p")" 2>/dev/null && printf '%s/%s' "$(pwd -P)" "$(basename -- "$p")" ) \
+  || _norm "$p"; }
+_outside_wt(){ case "$1" in "$WT_ROOT"|"$WT_ROOT"/*) return 1 ;; *) return 0 ;; esac; }
+# A shell word as the planner wrote it: runs of bare characters, "…" / '…' spans, and backslash
+# escapes, in any mix (`"/x"/y`, `"O'Reilly"`, `path\ with\ space`, `release=main`). `_unquote`
+# walks it with the shell's own three quoting states and returns the string the shell would pass.
+_TOK='("[^"]*"|'"'"'[^'"'"']*'"'"'|\\.|[^[:space:]"'"'"';|&()])+'
+_unquote(){ local s=$1 out='' q='' c i
+  for ((i=0; i<${#s}; i++)); do c=${s:i:1}
+    if [ -z "$q" ]; then case "$c" in '"'|"'") q=$c ;; '\') i=$((i+1)); out+=${s:i:1} ;; *) out+=$c ;; esac
+    elif [ "$q" = '"' ]; then case "$c" in '"') q='' ;; '\') i=$((i+1)); out+=${s:i:1} ;; *) out+=$c ;; esac
+    else case "$c" in "'") q='' ;; *) out+=$c ;; esac; fi
+  done; printf '%s' "$out"; }
+# True when raw shell text contains an unquoted single `&` or `|`. `&&` and
+# `||` keep the current shell's cwd; the single forms cross a process boundary.
+_resets_cwd(){ local s=$1 q='' i c p n; for ((i=0;i<${#s};i++)); do c=${s:i:1}
+    if [ -z "$q" ]; then case "$c" in
+      "'"|'"') q=$c ;; '\') i=$((i+1)) ;;
+      '&'|'|') p=''; n=''; [ "$i" -gt 0 ] && p=${s:i-1:1}; [ "$i" -lt $((${#s}-1)) ] && n=${s:i+1:1};
+        [ "$p" = "$c" ] || [ "$n" = "$c" ] || return 0 ;;
+    esac
+    elif [ "$q" = '"' ]; then case "$c" in '"') q='' ;; '\') i=$((i+1)) ;; esac
+    else [ "$c" = "'" ] && q=''; fi
+  done; return 1; }
+# The relocating verbs — `cd` / `pushd` (bare, `builtin`/`command`-prefixed, env-prefixed, or with
+# `--`) and a tool's own directory flag (`npm`/`npx`/`pnpm` `--prefix`, `yarn --cwd`, `pnpm -C`,
+# `make -C`, `git -C`; both `--flag <p>` and `--flag=<p>`) at the start of a segment, including after a
+# `(`/`{` opener or a `&` background operator. Each match is stripped of its prefix with an ANCHORED sed,
+# so the target is taken verbatim, unquoted, and compared LITERALLY — never interpolated into a regex.
+_VERB='((builtin|command)[[:space:]]+)?(cd|pushd)([[:space:]]+--)?'
+_ENV='([A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+)*'
+# `&` joins the operator set; grep is line-oriented, so a newline is already covered by `^`.
+# CONTROL KEYWORDS (`if`, `then`, `do`, …) WERE TRIED HERE AND REVERTED, and the reason is the rule
+# this fence is built on rather than a detail: these operators are matched against RAW TEXT, with no
+# awareness of quoting, so a keyword that is also an ordinary English word turns prose inside a
+# quoted argument into a command boundary — `grep -F 'if cd ../main; then' README.md` halted on a
+# command that relocates nothing. That buys a rare false negative (`if cd ../main; then …`) at the
+# cost of a realistic false positive, and this guard's whole posture is that the false-positive
+# direction is the one that gets it routed around. The residual is disclosed instead.
+# Spell the literal ERE operators as bracket expressions. `\|` / `\(` / `\{`
+# are GNU-tolerated but undefined by POSIX and BSD sed rejects the same boundary
+# expression with "unbalanced brackets" before the scan can run (#4767).
+_OPEN='(^|&&|&|;|[|][|]|[|]|[(]|[{])[[:space:]]*'
+# LAUNCHERS are a NAMED set, not `[^&;|]*`. A wrapper reached through a launcher is still a wrapper,
+# and the set admits an absolute path (`/usr/bin/env`) and an option with a SEPARATE operand
+# (`env -u FOO`, `timeout --signal TERM`, `stdbuf -o L`). Which options TAKE an operand is
+# TOOL-SCOPED for the same reason `_DIR`'s flags are: `-i` takes one on `stdbuf` and NONE on `env`,
+# so a flat set consumed the COMMAND after an operandless flag and `env -i echo bash -c '…'` —
+# which runs `echo` — halted. `command` and `exec` are deliberately NOT in the set: `command -v
+# bash` is a name PROBE that executes nothing, and halting it is the false-positive direction
+# again. The cost is that a genuine `command bash -c …` is not unwrapped; that is disclosed.
+# but a catch-all leading run also unwraps interpreter TEXT that is merely an argument — `echo bash -c
+# 'cd ../main'` halted on a command that executes nothing. A spurious unwrap is NOT harmless: the scans
+# halt on a path the shell would never visit. Name the launchers instead.
+_LOPT='([[:space:]]+-[^[:space:]]+|[[:space:]]+[A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*)*'
+# THE SHAPE IS `(<generic opts> <opt> <operand>)* <generic opts>`, NOT `<generic opts> (<opt>
+# <operand>)* <generic opts>`. The second admits only ONE contiguous run of operand-taking options,
+# so a generic option BETWEEN two of them ends the run and hides everything after it:
+# `env -u FOO --debug -u BAR -C ../main` relocates and passed silently. Interleaving is the normal
+# way these tools are invoked, so the grammar has to allow it. Same shape for timeout and stdbuf.
+# env's own separate-operand options, factored out because BOTH consumers need them: $_LAUNCH, so a
+# payload behind `env -u FOO bash -c …` is unwrapped, and $_DIR, so `env -u FOO -C ../main` is still
+# seen as a relocation. Generic $_LOPT cannot consume `FOO`, so without this the option HID the flag.
+_ENVOPT='('"$_LOPT"'[[:space:]]+(-u|--unset)[[:space:]]+'"$_TOK"')*'"$_LOPT"
+# $_LAUNCH needs a WIDER env group than $_DIR does, and the difference is deliberate. $_DIR must leave
+# `-C`/`--chdir` UNCONSUMED — that flag is the thing it is looking for. $_LAUNCH must consume it, or
+# `env -C scripts bash -c '…'` has its relocation seen and its PAYLOAD never unwrapped, which is the
+# bypass class this whole guard is about. Two groups, one per consumer.
+_ENVOPTL='('"$_LOPT"'[[:space:]]+((-u|--unset)[[:space:]]+|(-C|--chdir)([[:space:]]+|=))'"$_TOK"')*'"$_LOPT"
+_LAUNCH='((/[^[:space:]]*/)?((env|setsid|nohup)'"$_ENVOPTL"'|timeout('"$_LOPT"'[[:space:]]+(-s|--signal|-k|--kill-after)[[:space:]]+[^[:space:]]+)*'"$_LOPT"'[[:space:]]+[0-9]+[smhd]?|(stdbuf|nice|ionice)('"$_LOPT"'[[:space:]]+(-i|-o|-e|-n|-c)[[:space:]]+[^[:space:]]+)*'"$_LOPT"')[[:space:]]+)*'
+# The directory flags are TOOL-SCOPED, because the same spelling is not the same flag on every tool:
+# `git archive --prefix=../main/ HEAD` names archive MEMBERS and changes no directory, so a flat
+# six-tool `--prefix` halts a legitimate command. `--prefix`/`--cwd`/`--dir`/`-C` belong to the node
+# package managers; `-C`/`--directory` to make and git. $_LAUNCH leads it for $_EXEC's reason — a
+# recognised tool behind `env` is still that tool.
+_DIR='(('"$_LAUNCH"')(npm|npx|pnpm|yarn)[[:space:]]+([^&;|]*[[:space:]]+)?(--prefix|--cwd|--dir|-C)|('"$_LAUNCH"')(make|git)[[:space:]]+([^&;|]*[[:space:]]+)?(-C|--directory)|('"$_LAUNCH"')(/[^[:space:]]*/)?env'"$_ENVOPT"'[[:space:]]+(--chdir|-C))[[:space:]=]+'
+# Command-string interpreters. `eval "cd <main> && x"`, `sh -c "…"`, `bash -c '…'`, `node -e '…'` bury
+# the real command inside ONE opaque quoted token, and that defeats BOTH scans below at once: the
+# relocating verb never sits at a boundary scan 1 recognizes, and scan 2's tokenizer swallows the whole
+# quoted span, which after unquoting does not begin with `/`. These are ordinary portability idioms, not
+# obfuscation — a planner imitating a CI script reaches for one without any adversarial intent — so the
+# payload is UNWRAPPED and re-scanned rather than trusted or rejected wholesale. $_LAUNCH lets the
+# launcher forms a planner actually writes — `env bash -c`, a `timeout`-wrapped `bash -c`,
+# `nohup sh -c` — reach the same unwrap as a bare one, and an absolute or option-bearing
+# interpreter (`/bin/bash -c`, `bash --noprofile -c`) with it.
+_EXEC='('"$_LAUNCH"')((/[^[:space:]]*/)?(sh|bash|zsh|dash|ksh)([[:space:]]+--[a-z-]+)*[[:space:]]+-[a-z]*c|(/[^[:space:]]*/)?(python3?|node|perl|ruby)([[:space:]]+--[a-z-]+)*[[:space:]]+-[a-z]*[ce]|eval)[[:space:]]+'
+# `eval` runs in the current shell, unlike the other interpreters above; its payload's final cwd must
+# therefore flow into the next event. A subprocess payload is scanned from the reached cwd and then
+# restores its caller's cwd.
+_EVAL='eval[[:space:]]+'
+# ONE ordered pass per scanned string, each event tagged `C` (a cd/pushd — moves the cwd), `N` (a
+# tool's directory flag — resolved from the cwd reached so far but does NOT move it), `E` (`eval`,
+# whose cwd change persists), or `W` (a subprocess interpreter, whose cwd change does not). Ordering
+# is load-bearing: scanning every outer relocation before an earlier payload lets a later `cd` supply
+# that payload with a cwd the shell has not reached yet. `_scan` is a FUNCTION so an unwrapped payload
+# reaches the SAME event scan as the top-level command; it halts with
+# `exit 1`, never a return code, so a halt inside a payload is exactly as fatal as one outside; and it
+# ends `return 0` so a trailing non-`C` target cannot make the function itself look failed under `set -e`.
+CUR=$WT_ROOT
+_scan(){ local CMD=$1 D=$2 RAW BODY BFR REST K Q T R P S PREFIX LDS LD _T _P
+  _T=$( printf '%s' "$CMD" | grep -oE "${_OPEN}(${_ENV}${_EXEC}|${_ENV}${_VERB}[[:space:]]+|${_DIR})${_TOK}" \
+        | sed '/^$/d' )
+  # 1. Every relocating target, relative or absolute, resolved from the cwd the command has reached
+  # (chained `cd scripts && cd ..` lands back at the root and passes; `cd scripts && cd ../..` does
+  # not): outside the worktree → halt. A target the shell would expand (`~`, `$VAR`, `$(…)`) cannot
+  # be evaluated here and passes through — the plan-checker's probe already reports those as
+  # `dynamic_path`, and `$(git rev-parse --show-toplevel)` is the form step 0b itself recommends.
+  REST=$CMD
+  while IFS= read -r RAW; do
+    [ -n "$RAW" ] || continue
+    # Preserve process boundaries even when an unrecognized command sits between
+    # one and the next recognized event (`cd x & echo y && bash -c ...`).
+    BFR=${REST%%"$RAW"*}; REST=${REST#*"$RAW"}
+    if _resets_cwd "$BFR" || _resets_cwd "$RAW"; then CUR=$WT_ROOT; fi
+    BODY=$(printf '%s' "$RAW" | sed -E "s/^(&&|&|;|[|][|]|[|]|[(]|[{])?[[:space:]]*//")
+    # Classify with the same grep implementation that produced the event and
+    # remove the matched prefix literally. Expanding these composed EREs into a
+    # multi-expression BSD sed program fails with "unbalanced brackets" on
+    # macOS even though BSD grep accepts the event expression (#4767).
+    if _P=$(printf '%s' "$BODY" | grep -oE "^${_ENV}${_EVAL}"); then K=E
+    elif _P=$(printf '%s' "$BODY" | grep -oE "^${_ENV}${_EXEC}"); then K=W
+    elif _P=$(printf '%s' "$BODY" | grep -oE "^${_DIR}"); then K=N
+    else _P=$(printf '%s' "$BODY" | grep -oE "^${_ENV}${_VERB}[[:space:]]+"); K=C
+    fi
+    Q=${BODY#"$_P"}; T=$(_unquote "$Q")
+    case "$K" in
+      E) [ "$D" -ge 4 ] || _walk "$T" "$((D+1))" ;;
+      W) if [ "$D" -lt 4 ]; then
+           S=$CUR
+           # `_EXEC` is longer than `_DIR`, so a wrapper reached through
+           # `env -C/--chdir` wins grep's leftmost-longest match. Recover that
+           # launcher's relocation here: validate it, start the child there,
+           # then restore the parent cwd when the payload scan returns.
+           PREFIX=${BODY%"$Q"}
+           LDS=$(printf '%s' "$PREFIX" | grep -oE "(^|[[:space:]])(-C|--chdir)([[:space:]]+|=)${_TOK}" \
+             | sed -E 's/^[[:space:]]*(-C|--chdir)([[:space:]]+|=)//' || true)
+           while IFS= read -r LD; do
+             [ -n "$LD" ] || continue
+             LD=$(_unquote "$LD"); R=$(_resolve "$LD" "$CUR")
+             if _outside_wt "$R"; then
+               echo "FATAL: <automated> command relocates to $LD -> $R, outside the worktree ($WT_ROOT) — it would verify the wrong checkout. Rewrite the plan's command root-relative (cwd is the checkout root); do not rewrite it in place." >&2
+               exit 1
+             fi
+             CUR=$R
+           done <<EOF_LAUNCH_DIRS
+$LDS
+EOF_LAUNCH_DIRS
+           _walk "$T" "$((D+1))"; CUR=$S
+         fi ;;
+      C|N)
+        R=$(_resolve "$T" "$CUR")
+        if _outside_wt "$R"; then
+          echo "FATAL: <automated> command relocates to $T -> $R, outside the worktree ($WT_ROOT) — it would verify the wrong checkout. Rewrite the plan's command root-relative (cwd is the checkout root); do not rewrite it in place." >&2
+          exit 1
+        fi
+        [ "$K" = C ] && CUR=$R ;;
+    esac
+  done <<EOF_TARGETS
+$_T
+EOF_TARGETS
+  # 2. Any other absolute word that resolves under the MAIN checkout — a file argument, a redirect,
+  # an include — is the same defect by a different verb; system paths such as /dev/null or /usr/bin
+  # are neither and pass.
+  while IFS= read -r P; do
+    [ -n "$P" ] || continue
+    P=$(_unquote "$P"); case "$P" in [A-Za-z_]*=*|--*=*) P=${P#*=} ;; esac   # FOO=/x, --flag=/x
+    case "$P" in /*) ;; *) continue ;; esac
+    R=$(_resolve "$P")
+    _outside_wt "$R" || continue
+    case "$R" in
+      "$MAIN_ROOT"|"$MAIN_ROOT"/*)
+        echo "FATAL: <automated> command names $P (-> $R) inside the main checkout, outside the worktree ($WT_ROOT) — it would verify the wrong checkout. Rewrite the plan's command root-relative (cwd is the checkout root); do not rewrite it in place." >&2
+        exit 1 ;;
+    esac
+  done <<EOF_ABS
+$(printf '%s' "$CMD" | grep -oE "$_TOK")
+EOF_ABS
+  return 0; }
+# EVERY s-COMMAND THAT INTERPOLATES ONE OF THESE REGEXES USES `#`, NOT `/`. $_EXEC, $_LAUNCH and
+# (through $_LAUNCH) $_DIR all contain a literal `/` from their absolute-path groups, and a `/`
+# inside the pattern closes an `s/…/…/` early: sed dies `unknown option to 's'` on STDERR inside a
+# command substitution, the extracted list comes back EMPTY, and the scan silently stops happening
+# while every command reads as a clean pass. It is written as a rule about ALL of them rather than
+# about the one that had a slash first, because that is exactly how it recurred: $_EXEC was fixed,
+# then $_LAUNCH gained `(/[^[:space:]]*/)?` and took $_DIR down with it. Both driven, not theorised.
+# 3. The ordered event scan unwraps each interpreter payload in place, to a bounded depth — a wrapper
+# inside a wrapper is still a wrapper, and the bound is what keeps a pathological nest finite.
+# A payload the shell would build at run time (`bash -c $CMD`) is not a literal token here and passes
+# through as a dynamic_path, exactly as scan 1 treats an expansion.
+_walk(){ _scan "$1" "$2"; }
+_walk "$AUTOMATED_CMD" 0
+```
+
+A halt here is a plan defect, not an executor deviation: report it via the checkpoint return
+format naming the task and the offending command verbatim, and stop. The plan-checker's path
+probe (`check verify-command-paths`) warns on the *outside-orchestrator-root* case before
+execution; this guard is the one that sees the executor's actual root.
+
+### What this guard does NOT see — step 0c's stated boundary
+
+The two scans recognize **fixed sets** — relocating verbs, directory flags, interpreters, launchers,
+command boundaries — and the domain they act on, shell a planner may write, can acquire a member without
+this file changing. So the boundary is written out rather than left to be rediscovered, and each entry
+says what follows from it.
+
+**The largest one first, because it is the one a reader will otherwise assume away:**
+
+- **A RELATIVE path argument to a command that is not a recognized relocating verb.**
+  `python3 -m pytest ../main/tests`, `node ../main/test.js`, `make -f ../main/Makefile`, a redirect from
+  `../main/file` — all pass. The catch-all scan evaluates only words that begin with `/`, so it never
+  resolves a relative one, and the verb scan does not fire because none of these relocates. This is the
+  widest gap in the guard and it is not new. Closing it means resolving every relative word in the
+  command against the reached cwd, which halts on ordinary in-worktree arguments unless it can tell a
+  path from a flag value from a bare string — a much larger change than this guard is, and one that
+  fails toward false positives, which is the direction that gets a guard deleted.
+
+The rest, in descending order of how likely a planner is to reach them:
+
+- **Spellings that hide the verb from a text scan.** `cd$IFS/x` and its relatives split at run time, so
+  no static tokenizer sees a `cd` at a boundary. Deliberate: the guard's domain is what a planner
+  plausibly writes, not an adversary.
+- **Anything the shell builds at run time.** `cd $VAR`, `cd "$(…)"`, `~`, and equally `bash -c "$CMD"` —
+  the payload is not a literal token, so there is nothing to unwrap. These pass through by design;
+  `check verify-command-paths` reports them as `dynamic_path` before execution, and
+  `$(git rev-parse --show-toplevel)` is the form step 0b recommends.
+- **A command boundary outside `$_OPEN`'s set — and the set is matched against RAW TEXT.** `&&` `&`
+  `;` `|` `(` `{` open a command. Control keywords (`if cd ../main; then …`) are deliberately NOT in
+  the set: these operators have no awareness of quoting, so a keyword that is also an ordinary English
+  word turns prose inside a quoted argument into a boundary — `grep -F 'if cd ../main; then' README.md`
+  halted on a command that relocates nothing. The same quote-blindness is why
+  `echo 'note; bash -c "cd ../main"'` halts on its `;`: an over-halt on quoted data is the standing
+  cost of scanning text, and it is paid in the loud direction.
+- **A launcher outside `$_LAUNCH`'s set**, and therefore an interpreter or directory flag behind it.
+  `env` `timeout` `nohup` `stdbuf` `nice` `ionice` `setsid` are recognized, named by bare word or
+  absolute path, with options that take a separate operand (`env -u FOO`, `timeout --signal TERM`).
+  The set is named rather than a catch-all deliberately: a catch-all also unwrapped interpreter text
+  that was merely an *argument* (`echo bash -c '…'`), and halting on a command that executes nothing
+  is the false-positive direction. `command` and `exec` are excluded for that same reason —
+  `command -v bash` is a name probe.
+- **An interpreter outside `$_EXEC`'s set.** The set is stated because the entries above name only the
+  handful a planner reaches for most, which reads as the whole of it — `perl -e 'chdir "/main"'` IS
+  unwrapped and rescanned. Recognized, each named by a bare word OR an absolute path: `sh` `bash`
+  `zsh` `dash` `ksh`, and `python3`/`python` `node` `perl` `ruby`. The option is a short-option
+  CLUSTER, not the literal flag — `-[a-z]*c` for the shells and `-[a-z]*[ce]` for the rest — so
+  `-c`, `-ec` and even `-abc` all match. Recognized as a BARE WORD ONLY, with no absolute-path
+  form: `eval`; `/bin/eval 'cd ../main'` is NOT seen (driven).
+  Not recognized: an interpreter with no entry (`awk`, `php`, a shell not listed), whose payload stays
+  one opaque token, so only an absolute path written as a bare word in it is caught by the catch-all
+  scan. **The two lists are delimited on purpose** — the parity test in
+  `tests/executor-mvp-tdd-section.test.cjs` reads only the span between `Recognized,` and
+  `Not recognized:`, matching BACKTICKED TOKENS rather than substrings, because a containment check over the whole section is satisfied by a name that
+  appears here saying it is UNsupported: adding `awk` to `$_EXEC` with this prose untouched passed
+  that test, driven by the pre-push review of the round that added it.
+- **An interpreter option that takes an operand.** `bash --noprofile -c` is recognized;
+  `bash -O extglob -c` is not, because `_EXEC` admits long options without values, and widening it to
+  consume operands risks swallowing the `-c` it is looking for.
+- **A genuine `command bash -c …` or `exec bash -c …` is not unwrapped.** Those two words were removed
+  from `$_LAUNCH` to stop `command -v bash` — a name probe that executes nothing — from halting. A
+  deliberate trade of a rare false negative for a common false positive, recorded so it reads as a
+  decision rather than an omission.
+- **A payload behind a RELOCATING launcher is scanned from the command's cwd, not the launcher's.**
+  `env -C scripts bash -c 'cd ..'` lands back inside the worktree in reality, and halts here, because
+  the `-C` target is checked but is not threaded into the payload's starting cwd. An over-halt, in the
+  loud direction, on a shape a planner is unlikely to write.
+- **An operand-taking option ordering outside the grammar.** Options that take a separate operand
+  are matched interleaved with ordinary ones, so `env -u FOO --debug -u BAR -C ../main` is seen; a
+  spelling outside each tool's own list still is not.
+- **A launcher form outside the grammar**: `env -S 'cmd args'`, a launcher named through a quoted
+  string, or an option-with-operand spelling not in the tool's list. Which options take an operand is
+  TOOL-SCOPED (`-i` takes one on `stdbuf`, none on `env`); a flat list consumed the command itself
+  after an operandless flag.
+- **`_DIR`'s tool-to-flag run is still a catch-all**, so a pass-through argument that happens to spell
+  a directory flag can over-halt: `npm run package -- --prefix=../main/` halts although the flag goes
+  to the script, not to npm. Pre-existing, and again in the loud direction.
+- **A non-shell payload whose path is computed.** `python3 -c` / `node -e` payloads are scanned *as
+  shell text*, which catches a path written as a literal word (`os.chdir('/main')`) and not one the
+  program assembles (`os.path.join(root, '..')`).
+- **Wrapping nested more than four deep.** `_walk` bounds its own recursion.
+- **A directory flag on a tool outside the recognized set.** `--prefix`/`--cwd`/`--dir`/`-C` on `npm`
+  `npx` `pnpm` `yarn`, `-C`/`--directory` on `make` `git`, and `--chdir`/`-C` on `env` itself — the
+  last because `env` is not only a launcher, it relocates — including behind a launcher. The
+  scoping is per-tool because the same spelling is not the same flag everywhere: `git archive
+  --prefix=` names archive members and changes no directory. For an unrecognized tool the **absolute**
+  form of its flag is still caught by the catch-all; what is uncovered is the **relative** form.
+
+The enumerations are the parts that rot: they mirror a toolchain this file does not own. Adding a tool
+is one alternation in `_DIR` plus a row in each of the two tables in
+`tests/executor-mvp-tdd-section.test.cjs`. The guard is the executor's last containment check, not its
+only one — a halt it misses still has to get past `check verify-command-paths` at plan time.

package/gsd-core/templates/README.md

@@ -17,7 +17,7 @@ These files live directly at `.planning/` — not inside phase subdirectories.
 | `STATE.md` | `state.md` | `/gsd:new-project`, `/gsd:health --repair` | Current session state, active phase, last activity |
 | `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 |
+| `BACKLOG.md` | *(inline)* | `/gsd:capture --backlog` | Pending ideas and deferred work |
 | `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 |

package/gsd-core/templates/UAT.md

@@ -66,7 +66,7 @@ blocked: [N]
 
 <!-- YAML format for plan-phase --gaps consumption -->
 - truth: "[expected behavior from test]"
-  status: failed
+  status: failed | resolved
   reason: "User reported: [verbatim response]"
   severity: blocker | major | minor | cosmetic
   test: [N]
@@ -74,6 +74,10 @@ blocked: [N]
   artifacts: []      # Filled by diagnosis
   missing: []        # Filled by diagnosis
   debug_session: ""  # Filled by diagnosis
+  resolved_by: ""    # Written by verify-work's reconcile_gaps (#1921) when
+                      # an executed gap-closure plan resolves this gap —
+                      # never author this directly. Plan basename.
+  resolved_at: ""     # Written alongside resolved_by (#1921).
 ```
 
 ---
@@ -107,6 +111,18 @@ blocked: [N]
 - APPEND only when issue found (YAML format)
 - After diagnosis: fill `root_cause`, `artifacts`, `missing`, `debug_session`
 - This section feeds directly into /gsd:plan-phase --gaps
+- `status: resolved` (#1921, #4983): when `/gsd:verify-work`'s `reconcile_gaps`
+  step finds an executed gap-closure plan (a `*-PLAN.md` naming this entry's
+  `gap_id` with a matching `*-SUMMARY.md`), it updates the entry IN PLACE —
+  `status: failed` → `status: resolved` — and adds `resolved_by` (the
+  resolving plan's basename) and `resolved_at` (the date). A resolved entry
+  is no longer surfaced as an open gap, and its matching `### N.` test's
+  `result: issue` no longer blocks `phase uat-passed` — but only when
+  `resolved_by` names a plan that actually exists in the phase directory with
+  a matching SUMMARY; a hand-written `status: resolved` with no valid
+  `resolved_by` still blocks (src/uat-predicate.cts's `isTestGapResolved`).
+  A later regression against the same test gets a fresh `gap_id`, never a
+  reopened resolved one.
 
 </section_rules>
 

package/gsd-core/templates/config.json

@@ -41,18 +41,9 @@
     "min_plans_for_parallel": 2
   },
   "gates": {
-    "confirm_project": true,
-    "confirm_phases": true,
-    "confirm_roadmap": true,
-    "confirm_breakdown": true,
-    "confirm_plan": true,
     "execute_next_plan": true,
-    "issues_review": true,
-    "confirm_transition": true
-  },
-  "safety": {
-    "always_confirm_destructive": true,
-    "always_confirm_external_services": true
+    "confirm_transition": true,
+    "confirm_milestone_scope": true
   },
   "hooks": {
     "context_warnings": true

package/gsd-core/templates/verification-report.md

@@ -16,7 +16,7 @@ covered_files: # #4155 — see agents/gsd-verifier.md's "Create VERIFICATION.md"
   - .planning/phases/XX-name/{phase_num}-{plan}-PLAN.md
   - .planning/phases/XX-name/{phase_num}-{plan}-SUMMARY.md
   - src/{changed-file}.cts
-covered_digest: "v1:sha256:{digest from verification.fingerprint}"
+covered_digest: "v3:sha256:{digest from verification.fingerprint}"
 behavior_unverified: 0 # Count of ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truths (present + wired, behavior not exercised)
 behavior_unverified_items: # Only if behavior_unverified > 0 — the truths above as structured items; emitted regardless of overall status
   - truth: "Observable truth whose state transition or cancellation/cleanup/ordering invariant no test exercises"

package/gsd-core/workflows/_runtime-launcher.snippet.sh

@@ -1 +1 @@
-_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() { set -- "${CLAUDE_CONFIG_DIR:-$HOME/.claude}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}" "$HOME/.gemini/antigravity-ide" "$HOME/.gemini/antigravity-cli" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}" "${CLINE_CONFIG_DIR:-$HOME/.cline}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}" "${CODEX_HOME:-$HOME/.codex}" "${COPILOT_CONFIG_DIR:-${COPILOT_HOME:-$HOME/.copilot}}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}" "${HERMES_HOME:-$HOME/.hermes}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}" "${KIMI_CONFIG_DIR:-$HOME/.config/agents}" "$HOME/.agents" "${KIMI_CODE_HOME:-$HOME/.kimi-code}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}" "${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}" "${TRAE_CONFIG_DIR:-$HOME/.trae}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}" "${ZCODE_CONFIG_DIR:-$HOME/.zcode}" "${GROK_AGENTS_HOME:-$HOME/.agents}"; for _h; do _gsd_at "$_h/gsd-core/bin/${_GSD_SHIM_NAME}" && return 0; 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 _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/workflows/add-backlog.md

@@ -21,7 +21,7 @@ cat .planning/ROADMAP.md
 ## Step 2: Find next backlog number
 
 ```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() { set -- "${CLAUDE_CONFIG_DIR:-$HOME/.claude}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}" "$HOME/.gemini/antigravity-ide" "$HOME/.gemini/antigravity-cli" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}" "${CLINE_CONFIG_DIR:-$HOME/.cline}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}" "${CODEX_HOME:-$HOME/.codex}" "${COPILOT_CONFIG_DIR:-${COPILOT_HOME:-$HOME/.copilot}}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}" "${HERMES_HOME:-$HOME/.hermes}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}" "${KIMI_CONFIG_DIR:-$HOME/.config/agents}" "$HOME/.agents" "${KIMI_CODE_HOME:-$HOME/.kimi-code}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}" "${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}" "${TRAE_CONFIG_DIR:-$HOME/.trae}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}" "${ZCODE_CONFIG_DIR:-$HOME/.zcode}" "${GROK_AGENTS_HOME:-$HOME/.agents}"; for _h; do _gsd_at "$_h/gsd-core/bin/${_GSD_SHIM_NAME}" && return 0; 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 _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
 NEXT=$(gsd_run query phase.next-decimal 999 --raw)
 ```
 

package/gsd-core/workflows/add-phase.md

@@ -13,15 +13,15 @@ Read all files referenced by the invoking prompt's execution_context before star
 <step name="parse_arguments">
 Parse the command arguments:
 - All arguments become the phase description
-- Example: `/gsd-add-phase Add authentication` → description = "Add authentication"
-- Example: `/gsd-add-phase Fix critical performance issues` → description = "Fix critical performance issues"
+- Example: `/gsd:phase "Add authentication"` → description = "Add authentication"
+- Example: `/gsd:phase "Fix critical performance issues"` → description = "Fix critical performance issues"
 
 If no arguments provided:
 
 ```
 ERROR: Phase description required
-Usage: /gsd-add-phase <description>
-Example: /gsd-add-phase Add authentication system
+Usage: /gsd:phase "<description>"
+Example: /gsd:phase "Add authentication system"
 ```
 
 Exit.
@@ -31,8 +31,9 @@ Exit.
 Load phase operation context:
 
 ```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
-INIT=$(gsd_run query init.phase-op "0")
+_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() { set -- "${CLAUDE_CONFIG_DIR:-$HOME/.claude}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}" "$HOME/.gemini/antigravity-ide" "$HOME/.gemini/antigravity-cli" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}" "${CLINE_CONFIG_DIR:-$HOME/.cline}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}" "${CODEX_HOME:-$HOME/.codex}" "${COPILOT_CONFIG_DIR:-${COPILOT_HOME:-$HOME/.copilot}}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}" "${HERMES_HOME:-$HOME/.hermes}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}" "${KIMI_CONFIG_DIR:-$HOME/.config/agents}" "$HOME/.agents" "${KIMI_CODE_HOME:-$HOME/.kimi-code}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}" "${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}" "${TRAE_CONFIG_DIR:-$HOME/.trae}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}" "${ZCODE_CONFIG_DIR:-$HOME/.zcode}" "${GROK_AGENTS_HOME:-$HOME/.agents}"; for _h; do _gsd_at "$_h/gsd-core/bin/${_GSD_SHIM_NAME}" && return 0; 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 _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
+GSD_WS=$(echo " $ARGUMENTS" | sed -nE 's/.* --ws +([A-Za-z0-9][A-Za-z0-9._-]*).*/--ws \1/p' | head -n 1)
+INIT=$(gsd_run query init.phase-op ${GSD_WS:+--ws=${GSD_WS##* }} "0")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -99,7 +100,7 @@ Roadmap updated: .planning/ROADMAP.md
 ---
 
 **Also available:**
-- `/gsd-add-phase <description>` — add another phase
+- `/gsd:phase "<description>"` — add another phase
 - Review roadmap
 
 ---