@opengsd/gsd-core 1.14.0 → 1.15.0

package/gsd-core/workflows/ui-review.md

@@ -16,11 +16,16 @@ Valid GSD subagent types (use exact names — do not fall back to 'general-purpo
 ## 0. Initialize
 
 ```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
 RESPONSE_LANGUAGE=$(gsd_run query config-get response_language --raw --default "" 2>/dev/null || echo "")
+PHASE_ARG=$(echo "$ARGUMENTS" | sed -E 's/--ws[[:space:]]+[A-Za-z0-9._-]+//g' | xargs)
 INIT=$(gsd_run query init.phase-op "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_UI_REVIEWER=$(gsd_run query agent-skills gsd-ui-auditor)
+# workflow.ui_interaction_capture (default false): read here and handed to the auditor
+# through its <config> block — the agent carries no gsd_run resolver of its own.
+INTERACTION_CAPTURE=$(gsd_run query config-get workflow.ui_interaction_capture --raw 2>/dev/null || echo "false")
+[ "$INTERACTION_CAPTURE" = "true" ] || INTERACTION_CAPTURE="false"
 ```
 
 **If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
@@ -46,8 +51,14 @@ UI_REVIEW_FILE=$(ls "${PHASE_DIR}"/*-UI-REVIEW.md 2>/dev/null | head -1)
 
 **If `SUMMARY_FILES` empty:** Exit — "Phase {N} not executed. Run /gsd:execute-phase {N} first."
 
-**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
-**If `UI_REVIEW_FILE` non-empty:** Use AskUserQuestion:
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Antigravity, etc.) where `AskUserQuestion` is not available.
+**If `UI_REVIEW_FILE` non-empty:**
+
+**If `--auto`:** Auto-select "View" — keep the existing UI-REVIEW.md untouched and exit without
+re-auditing. Log: `[auto] UI-REVIEW.md exists — reusing as-is.` "Re-audit" is the regenerating
+choice; an unattended run reuses an existing artifact instead (#4776).
+
+**Otherwise:** Use AskUserQuestion:
 - header: "Existing UI Review"
 - question: "UI-REVIEW.md already exists for Phase {N}."
 - options:
@@ -94,10 +105,13 @@ ${AGENT_SKILLS_UI_REVIEWER}
 <config>
 phase_dir: {phase_dir}
 padded_phase: {padded_phase}
+interaction_capture: {interaction_capture}
 </config>
 ```
 
-Omit null file paths.
+Omit null file paths. `interaction_capture` is always present — the `$INTERACTION_CAPTURE` value read in step 0, `true` only when
+`workflow.ui_interaction_capture` is on; the auditor's `<screenshot_approach>` branches on it and
+falls back to its Playwright-only static capture when it is `false` or no Chrome binary resolves.
 
 <!-- #2508 runtime-aware-dispatch -->
 

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

@@ -64,7 +64,7 @@ unplanned phase from the roadmap (same logic as /gsd:plan-phase).
 Load GSD phase 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
+_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
 INIT=$(gsd_run query init.plan-phase "$PHASE")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```

package/gsd-core/workflows/undo.md

@@ -1,5 +1,5 @@
 <purpose>
-Safe git revert workflow. Rolls back GSD phase or plan commits using the phase manifest with dependency checks and a confirmation gate. Uses git revert --no-commit (NEVER git reset) to preserve history.
+Safe git revert workflow. Rolls back GSD phase or plan commits selected within the phase directory's own commit window with dependency checks and a confirmation gate. Uses git revert --no-commit (NEVER git reset) to preserve history.
 </purpose>
 
 <required_reading>
@@ -9,7 +9,7 @@ Safe git revert workflow. Rolls back GSD phase or plan commits using the phase m
 
 <process>
 ```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
 RESPONSE_LANGUAGE=$(gsd_run query config-get response_language --raw --default "" 2>/dev/null || echo "")
 ```
 
@@ -67,7 +67,7 @@ Recent GSD commits:
   3. ghi9012 fix(02-03): correct validation logic
 ```
 
-**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Antigravity, etc.) where `AskUserQuestion` is not available.
 Use AskUserQuestion to ask:
 - question: "Which commits to revert? Enter numbers (e.g., 1,3) or 'all'"
 - header: "Select"
@@ -78,30 +78,339 @@ Parse the user's selection into COMMITS list.
 
 **MODE=phase:**
 
-Read `.planning/.phase-manifest.json` if it exists.
+Resolve the phase's own directory, then anchor the selection window on it. `find-phase`
+resolves through `planningDir`, so under an active workstream this is that workstream's
+phase directory — not the root's same-numbered one.
 
-If the file exists and `manifest.phases?.[TARGET_PHASE]?.commits` is a non-empty array:
-  - Use `manifest.phases[TARGET_PHASE].commits` entries as COMMITS (each entry is a commit hash)
+```bash
+PHASE_DIR=$(gsd_run query find-phase "${TARGET_PHASE}" --raw 2>/dev/null)
+# find-phase answers relative to the PROJECT ROOT -- gsd-tools resolves it before dispatch --
+# not to this shell's cwd, so from a subdirectory a bare `git log -- "${PHASE_DIR}"` looks in
+# the wrong place and every path-scoped git call below comes back empty. Take the root from the
+# same owner and run those calls there. Unresolved, `.` keeps the behaviour at the root. A root
+# in a DIFFERENT repository from this shell's is refused below, never used.
+PROJECT_ROOT=$(gsd_run query planning inspect --pick generated_from.cwd --raw 2>/dev/null)
+```
+
+If `PHASE_DIR` is empty, the phase does not exist in the active scope:
+```
+Phase ${TARGET_PHASE} not found in the active planning scope. Nothing to revert.
+```
+Exit cleanly — do NOT fall back to an unbounded search.
+
+**Refuse an ARCHIVED resolution — it selects the wrong milestone, not merely too few
+commits.** `find-phase` searches the live `phases/` directory first, then every
+`milestones/v<X.Y>-phases/` directory in ascending version order, and its ambiguity check
+is scoped to a *single* directory — it does not span them (`cmdFindPhase`, `src/phase.cts`:
+the `matches.length > 1` test sits inside the per-`searchDir` loop). A phase number that is
+not live therefore resolves **silently to the oldest archived milestone that has one**,
+with no warning. Anchoring there is wrong in both directions at once: the oldest commit
+adding that path is the archival **move**, so the phase's real work predates the window and
+falls outside it, while the window runs forward from that archival through every later
+milestone — where the subject grep matches *their* same-numbered phase. Driven on a
+two-archived-milestone fixture, `--phase 03` selected v2.0's `feat(03-01): add search index`
+and excluded v1.0's own `feat(03-01): implement auth endpoint`. Feeding that to
+`git revert` is the cross-milestone contamination this workflow exists to close, so it
+fails closed.
+
+**Two archive layouts exist, and `find-phase` searches only one of them.** The phase locator
+(`listArchiveVersionDirs`, `src/phase-locator.cts`) enumerates both the flat
+`milestones/v<X.Y>-phases/<phase>/` archive and the workstream archive
+`milestones/ws-<name>-<date>/phases/<phase>/` that `workstream complete` writes. `cmdFindPhase`
+builds its own search list and admits only the first (`/^v\d+.*-phases$/`), so a phase that lives
+*only* in a `ws-*` archive resolves to nothing today and the not-found rule above fails closed.
+The refusal below still names both layouts, so it keeps holding if `find-phase` is ever taught the
+second one:
+
+```bash
+# Match the ARCHIVE LAYOUTS, never the bare token `milestones`. A bare `*/milestones/*`
+# REFUSES A LIVE PHASE whenever a workstream or project is itself named `milestones`
+# (driven: GSD_WORKSTREAM=milestones resolves `.planning/workstreams/milestones/phases/03-live`,
+# which that pattern classifies as archived). The two shapes are the locator's two:
+# `v<X.Y>-phases/<phase>` and `ws-<name>-<date>/phases/<phase>`. Blanking PHASE_DIR is
+# deliberate: the fail-closed rule below then also holds, so no path reaches selection even if
+# this refusal's prose is not honored.
+PHASE_DIR_ARCHIVED=""
+case "${PHASE_DIR}" in
+  */milestones/v[0-9]*-phases/*|milestones/v[0-9]*-phases/*|*/milestones/ws-*/phases/*|milestones/ws-*/phases/*)
+    PHASE_DIR_ARCHIVED="${PHASE_DIR}"; PHASE_DIR="" ;;
+esac
+# The phase directory must live in the SAME repository as the commits this workflow reverts. In a
+# `sub_repos` project, .planning/ sits in a parent repository and the code in child ones; from a
+# child, PROJECT_ROOT is the parent, and an anchor read there is a commit the child has never seen.
+# Compare the COMMON git directories -- the object database -- physically resolved; a different one
+# refuses. Common, not per-worktree: gsd-tools maps a linked worktree's planning to the MAIN
+# worktree, which is the same repository and holds every commit the linked one does.
+PHASE_DIR_FOREIGN=""
+if [ -n "${PHASE_DIR}" ] && [ -n "${PROJECT_ROOT}" ]; then
+  _gd_here=$(_d=$(git rev-parse --git-common-dir 2>/dev/null) && [ -n "$_d" ] && cd "$_d" && pwd -P) || _gd_here=""
+  _gd_root=$(cd "${PROJECT_ROOT}" 2>/dev/null && _d=$(git rev-parse --git-common-dir 2>/dev/null) && [ -n "$_d" ] && cd "$_d" && pwd -P) || _gd_root=""
+  if [ -z "$_gd_here" ] || [ "$_gd_here" != "$_gd_root" ]; then
+    PHASE_DIR_FOREIGN="${PROJECT_ROOT}"; PHASE_DIR=""
+  fi
+fi
+# A LIVE path can still be a previous occupant's. `--diff-filter=A` does not follow renames,
+# so re-creating a literal directory that an earlier milestone or workstream used anchors on
+# the EARLIER occupant's add. Nothing is under milestones/ to refuse -- find-phase returned the
+# live dir -- so ask the question the anchor depends on instead: did this exact path go EMPTY
+# somewhere in HEAD's history and come back? Git history owns that answer for every way a path
+# can be vacated -- a flat milestone archive, `workstream complete` moving the workstream into
+# milestones/ws-<name>-<date>/, a removed phase re-added under the same slug -- where a layout
+# glob answers only for the layouts it spells. `--no-renames` so a move-out reads as the deletion
+# it is at this path; `-m` so a merge that emptied it is seen too; `ls-tree` at that commit is
+# what separates "the directory went away" from an ordinary deleted plan file.
+PHASE_DIR_REUSED=""; PHASE_DIR_LIVE=""
+if [ -n "${PHASE_DIR}" ]; then
+  for _c in $(git -C "${PROJECT_ROOT:-.}" log -m --no-renames --diff-filter=D --format=%H -- "${PHASE_DIR}" 2>/dev/null); do
+    if [ -z "$(git -C "${PROJECT_ROOT:-.}" ls-tree -d "$_c" -- "${PHASE_DIR}" 2>/dev/null)" ]; then
+      PHASE_DIR_LIVE="${PHASE_DIR}"; PHASE_DIR_REUSED="$_c"; PHASE_DIR=""; break
+    fi
+  done
+fi
+```
+
+If `PHASE_DIR_ARCHIVED` is non-empty, stop — this message, not the not-found one:
+```
+Phase ${TARGET_PHASE} resolves to an ARCHIVED milestone directory (${PHASE_DIR_ARCHIVED}).
+Refusing: the anchor there is the archival commit, so the window would span later
+milestones and select their same-numbered phase instead of this one.
+Use /gsd:undo --last N and select commits explicitly.
+```
+If `PHASE_DIR_FOREIGN` is non-empty, stop with its own message:
+```
+Phase ${TARGET_PHASE} is planned in the repository at ${PHASE_DIR_FOREIGN}, not the one this
+command is running in. Refusing: that repository's history cannot bound commits in this one.
+Use /gsd:undo --last N here and select commits explicitly.
+```
+And if `PHASE_DIR_REUSED` is non-empty, stop with its own message:
+```
+Phase ${TARGET_PHASE} resolves to ${PHASE_DIR_LIVE}, but that path was emptied by commit
+${PHASE_DIR_REUSED} and re-created later. Refusing: the first commit adding this path belongs
+to the earlier occupant, so the window would open there and select its commits too.
+Use /gsd:undo --last N and select commits explicitly.
+```
+Exit cleanly in every case.
+
+Derive the selection window from `PHASE_DIR` (the `#3995` anchor, shared with
+`code-review.md`): the base is the parent of the first commit that added anything under
+the phase's own directory, and the tip is `HEAD`.
+
+```bash
+PHASE_START=$(git -C "${PROJECT_ROOT:-.}" log --format="%H" --diff-filter=A -- "${PHASE_DIR}" 2>/dev/null | tail -1)
+# Only a commit in HEAD's own history may anchor. A SHA from another repository has no resolvable
+# parent here, which the root-commit arm below would read as "root commit" and select all of HEAD;
+# one from another worktree's branch that HEAD does not contain bounds nothing on this branch.
+if [ -n "$PHASE_START" ] && ! git merge-base --is-ancestor "$PHASE_START" HEAD 2>/dev/null; then PHASE_START=""; fi
+UNDO_RANGE=""
+if [ -n "$PHASE_START" ]; then
+  if git rev-parse "${PHASE_START}^" >/dev/null 2>&1; then
+    UNDO_RANGE="${PHASE_START}^..HEAD"
+  else
+    # PHASE_START is the root commit — it has no parent to exclude. `${PHASE_START}..HEAD`
+    # would drop PHASE_START ITSELF, refusing a legitimate revert of the first commit.
+    UNDO_RANGE="HEAD"
+  fi
+fi
+```
+
+**Fail closed when no anchor resolves.** If `UNDO_RANGE` is empty, stop:
+```
+Cannot determine a reliable commit window for phase ${TARGET_PHASE} (no commit adds ${PHASE_DIR}).
+Re-run with /gsd:undo --last N and select commits explicitly.
+```
+Exit cleanly. An unbounded repository-wide search is never the fallback — that is the
+defect this anchor replaces.
+
+Select within the window. **No `--all`:** only commits reachable from `HEAD` may be
+reverted, because reverting a commit that is not in the current branch's history stages a
+change the branch never received.
+
+**Selection is a structural parse, not a substring grep (#4661).** The old
+`grep -E "\(0*${TARGET_PHASE}(-[0-9]+)?\):"` interpolated the id straight into a live ERE
+(`.`/`+` in the id became wildcard/quantifier metacharacters), was unanchored (a commit that
+only MENTIONED a scope was wrongly selected as a DECLARATION of it), and disagreed with
+plan mode's own grep on a breaking-change subject (`feat(03-01)!: ...`). `select-revert-commits`
+closes all three: it validates `${TARGET_PHASE}` (refusing before any git command runs on an
+invalid id), then parses each candidate commit's subject through the SAME anchored
+`type(scope)!:` conventional-commit header the changelog/PR-title gate uses and compares the
+DECLARED scope to `${TARGET_PHASE}` by exact string equality — plus a `${TARGET_PHASE}-` prefix,
+so a plan-scoped commit within this phase still selects, matching the old grep's `-NN` tolerance.
+It also zero-pads a plain unpadded `${TARGET_PHASE}` (e.g. `3` → `03`) before comparing, matching
+the old grep's `0*` tolerance for a digit-first id — never for a letter-first custom id
+(`PROJ-42`), where zero-padding would strip the meaningful prefix instead of matching it.
+
+```bash
+COMMITS=$(gsd_run query select-revert-commits --phase "${TARGET_PHASE}" --range "${UNDO_RANGE}" --raw || true)
+```
+
+Use matching commits as COMMITS.
 
-If the file does not exist, or `manifest.phases?.[TARGET_PHASE]` is missing:
-  - Display: "Manifest has no entry for phase ${TARGET_PHASE} (or file missing), falling back to git log search"
-  - Fallback: run git log and filter for the target phase scope:
-    ```bash
-    git log --oneline --no-merges --all | grep -E "\(0*${TARGET_PHASE}(-[0-9]+)?\):" | head -50
-    ```
-  - Use matching commits as COMMITS
+**Report truncation, never truncate silently.** If the selection exceeds 50 commits, show
+the count and stop rather than capping — a partial phase revert leaves a worse tree state
+than either reverting the phase or not:
+```
+Phase ${TARGET_PHASE} selects ${N} commits (>50). Refusing to revert a partial phase.
+Use /gsd:undo --plan NN-MM per plan, or /gsd:undo --last N.
+```
 
 ---
 
 **MODE=plan:**
 
-Run:
+Extract the phase number from `TARGET_PLAN` (the `NN` of `NN-MM`) and derive the same
+window from that phase's own directory — a plan number is unique within its phase, and a
+phase number only within its milestone and workstream.
+
 ```bash
-git log --oneline --no-merges --all | grep -E "\(${TARGET_PLAN}\)" | head -50
+PLAN_PHASE="${TARGET_PLAN%%-*}"
+PHASE_DIR=$(gsd_run query find-phase "${PLAN_PHASE}" --raw 2>/dev/null)
+# Project-root-relative, exactly as in MODE=phase: path-scoped git calls run from the root.
+PROJECT_ROOT=$(gsd_run query planning inspect --pick generated_from.cwd --raw 2>/dev/null)
+# Same archived-resolution refusal as MODE=phase, and for the same reason — an archived
+# anchor selects a LATER milestone's same-numbered phase. Blanking PHASE_DIR keeps the
+# fail-closed rule below load-bearing.
+PHASE_DIR_ARCHIVED=""
+case "${PHASE_DIR}" in
+  */milestones/v[0-9]*-phases/*|milestones/v[0-9]*-phases/*|*/milestones/ws-*/phases/*|milestones/ws-*/phases/*)
+    PHASE_DIR_ARCHIVED="${PHASE_DIR}"; PHASE_DIR="" ;;
+esac
+# Same-repository refusal as MODE=phase: a phase planned in another repository cannot anchor here.
+PHASE_DIR_FOREIGN=""
+if [ -n "${PHASE_DIR}" ] && [ -n "${PROJECT_ROOT}" ]; then
+  _gd_here=$(_d=$(git rev-parse --git-common-dir 2>/dev/null) && [ -n "$_d" ] && cd "$_d" && pwd -P) || _gd_here=""
+  _gd_root=$(cd "${PROJECT_ROOT}" 2>/dev/null && _d=$(git rev-parse --git-common-dir 2>/dev/null) && [ -n "$_d" ] && cd "$_d" && pwd -P) || _gd_root=""
+  if [ -z "$_gd_here" ] || [ "$_gd_here" != "$_gd_root" ]; then
+    PHASE_DIR_FOREIGN="${PROJECT_ROOT}"; PHASE_DIR=""
+  fi
+fi
+# A LIVE path can still be a previous occupant's -- same question, same answer as MODE=phase:
+# a path that went EMPTY in HEAD's history and came back anchors on the earlier occupant's add,
+# whatever vacated it. Ask git, not a layout glob. Fail closed; `--last N` is the route.
+PHASE_DIR_REUSED=""; PHASE_DIR_LIVE=""
+if [ -n "${PHASE_DIR}" ]; then
+  for _c in $(git -C "${PROJECT_ROOT:-.}" log -m --no-renames --diff-filter=D --format=%H -- "${PHASE_DIR}" 2>/dev/null); do
+    if [ -z "$(git -C "${PROJECT_ROOT:-.}" ls-tree -d "$_c" -- "${PHASE_DIR}" 2>/dev/null)" ]; then
+      PHASE_DIR_LIVE="${PHASE_DIR}"; PHASE_DIR_REUSED="$_c"; PHASE_DIR=""; break
+    fi
+  done
+fi
+PHASE_START=$(git -C "${PROJECT_ROOT:-.}" log --format="%H" --diff-filter=A -- "${PHASE_DIR}" 2>/dev/null | tail -1)
+# As in MODE=phase: an anchor outside HEAD's own history never reaches the root-commit arm.
+if [ -n "$PHASE_START" ] && ! git merge-base --is-ancestor "$PHASE_START" HEAD 2>/dev/null; then PHASE_START=""; fi
+UNDO_RANGE=""
+if [ -n "$PHASE_START" ]; then
+  if git rev-parse "${PHASE_START}^" >/dev/null 2>&1; then
+    UNDO_RANGE="${PHASE_START}^..HEAD"
+  else
+    # PHASE_START is the root commit — it has no parent to exclude. `${PHASE_START}..HEAD`
+    # would drop PHASE_START ITSELF, refusing a legitimate revert of the first commit.
+    UNDO_RANGE="HEAD"
+  fi
+fi
+```
+
+Apply the same fail-closed rule as MODE=phase when `PHASE_DIR` or `UNDO_RANGE` is empty —
+and the same three refusals, each with its own message, when `PHASE_DIR_ARCHIVED`,
+`PHASE_DIR_FOREIGN` or `PHASE_DIR_REUSED` is non-empty — then select within the window.
+
+**Same structural parse as MODE=phase (#4661), in plan mode:** the DECLARED scope must
+equal `${TARGET_PLAN}` EXACTLY — no phase-prefix tolerance. This is what makes
+`feat(03-01)!: breaking change` select identically in both modes, closing the disagreement
+the old phase-mode/plan-mode grep pair had on a breaking-change subject. `${TARGET_PLAN}`
+is validated (as two phase-number-shaped segments joined by the first `-`) before any git
+command runs, and each segment is zero-padded the same way as `${TARGET_PHASE}` above (e.g.
+`3-1` → `03-01`) — the old plan-mode grep never had this tolerance, so this is a deliberate
+widening, not a preserved behavior; it makes an unpadded `--plan` argument match a
+canonically-padded commit scope instead of silently matching nothing.
+
+```bash
+COMMITS=$(gsd_run query select-revert-commits --plan "${TARGET_PLAN}" --range "${UNDO_RANGE}" --raw || true)
 ```
 
 Use matching commits as COMMITS.
 
+**Report truncation, never truncate silently** — the same rule as MODE=phase. If the
+selection exceeds 50 commits, show the count and stop rather than capping:
+```
+Plan ${TARGET_PLAN} selects ${N} commits (>50). Refusing to revert a partial plan.
+Use /gsd:undo --last N and select commits explicitly.
+```
+
+---
+
+**Known residual — a revision range is ancestry, not chronology.** `PHASE_START^..HEAD`
+excludes everything reachable from `PHASE_START^`, which is the right bound for the
+ordinary linear case. It is not a *chronological* lower bound: a long-lived side branch
+created before the phase, carrying matching scopes, and merged in **after** `PHASE_START`
+is reachable from `HEAD` without being an ancestor of `PHASE_START^`, so it stays
+selectable. This is strictly narrower than the unbounded search it replaces, not a new
+exposure — but it is not zero.
+
+**Known residual — a RENAMED phase directory under-selects.** The anchor is
+`--diff-filter=A` on the phase directory's *current* path and does not follow renames, so
+for a phase whose directory has since moved the oldest add at that path is the **move**
+commit, and the phase's real work commits — which predate it — fall outside the window.
+For a rename *within* the live `phases/` tree the failure is under-selection: the undo
+reverts too little or refuses, never too much.
+
+The **archival** case is not that case, and is no longer a residual — it is refused above.
+It was previously documented here as under-selection only, which was wrong in the direction
+that matters: the window runs forward from the archival commit, so while the target's own
+work falls outside it, a *later* milestone's same-numbered phase falls inside and matches
+the subject grep. Driven on a two-archived-milestone fixture it selected the wrong
+milestone's commit and none of the right one's. Both modes now refuse an archived
+`PHASE_DIR` outright; `/gsd:undo --last N` is the route for a phase that has been archived.
+
+**Known residual — a phase directory introduced by a merge commit resolves no anchor.**
+`git log --diff-filter=A -- "${PHASE_DIR}"` does not walk merge diffs by default. A phase
+directory added on a side branch is still found, because the side-branch commit that added
+it is itself in history; the uncovered case is a directory that first appears *in the merge
+resolution itself*, which a **default** `git log` does not show: it suppresses merge diffs
+unless asked (`-m` prints the add once per parent, so the information exists — the anchor
+command simply does not request it). `PHASE_START` then resolves
+empty and both modes fail closed on a legitimate phase. Safe-direction only — it refuses
+rather than mis-selects — and untested: constructing the evil-merge fixture costs more than
+the branch is worth while the failure mode is a refusal. `/gsd:undo --last N` is the route
+if it is ever hit.
+
+**A re-created directory — same number AND same slug — is REFUSED, not a residual.** The
+anchor is the *current path*, and `--diff-filter=A` does not follow renames, so re-creating
+a literal directory an earlier occupant used (`03-auth` again, not merely phase `03` again)
+makes the oldest add at that path the **previous occupant's**. The archived refusal above
+cannot reach it — `find-phase` returns the **live** directory, so nothing is under
+`milestones/` to refuse. Driven before the guard: two milestones both using
+`.planning/phases/03-auth` anchored on the v1 plan commit and selected all four v1+v2 phase-03
+commits; a workstream completed into `milestones/ws-feat-<date>/` and then re-created as `feat`
+with the same `03-auth` did the same across the two workstream generations. The collision check
+closes both without a phase identity a directory name does not carry, and without restating any
+archive layout: a path that went empty in `HEAD`'s history and came back has had a previous
+occupant, so the anchor is untrustworthy and both modes refuse. `code-review.md` carries the
+same weakness on the same anchor, where it is read-only and merely widens a review scope; here
+it reverts, which is why this one is a refusal rather than a note.
+
+**Known residual — the collision check reads history, so it sees only what history shows.**
+Two edges, in opposite directions. It **misses** a single commit that both moves the directory
+away *and* re-creates it at the same path: the path is never empty in any commit's tree, so the
+history carries no vacancy to find, and the anchor opens on the earlier occupant. That takes a
+hand-assembled commit — it is not the shape of an archive followed by later planning — and the
+over-selection it allows still has to pass `confirm_revert`. It **over-refuses** when a side
+branch emptied the directory and the merge kept it: the vacancy is real in that branch's
+history, so the path reads as reused. Refusing too often costs a `--last N`; refusing too
+rarely reverts another occupant's work, which is why the check is keyed on the vacancy itself
+rather than on any narrower proof of ownership.
+
+**Known residual — concurrent workstreams.** The window above is scoped to the target
+phase's own directory, which is workstream-correct, but the commit subjects it filters
+are not: the executor's scope contract is `type({phase}-{plan})` with no workstream
+token, so two workstreams running the same phase number concurrently emit
+indistinguishable subjects and both fall inside each other's window. Narrowing the window plus the two
+refusals above removes the unreachable-branch class entirely and every previous-milestone
+route this workflow can detect — residual 2 is the one it cannot, since a merged side branch
+is genuinely reachable from `HEAD`. This last class
+needs a discriminator that does not exist in a commit subject today (`#3995`: *"Message
+subjects demonstrably do not carry enough information to identify a phase"*). Until one
+exists, `confirm_revert` is the backstop for it.
+
 ---
 
 **Empty check:**
@@ -118,11 +427,20 @@ Exit cleanly.
 
 Skip this step entirely for MODE=last.
 
+Resolve the active scope's planning root first — **both** modes below read from it. Under
+an active workstream the roadmap and phase directories describing the target are that
+workstream's, not the root's:
+
+```bash
+PLANNING_DIR=$(gsd_run query planning inspect --pick generated_from.planning_root --raw 2>/dev/null)
+[ -n "$PLANNING_DIR" ] || PLANNING_DIR=".planning"
+```
+
 ---
 
 **MODE=phase:**
 
-Read `.planning/ROADMAP.md` inline.
+Read `${PLANNING_DIR}/ROADMAP.md` inline.
 
 Search for phases that list a dependency on the target phase. Look for patterns like:
 - "Depends on: Phase ${TARGET_PHASE}"
@@ -130,7 +448,7 @@ Search for phases that list a dependency on the target phase. Look for patterns
 - "depends_on: [${TARGET_PHASE}]"
 
 For each dependent phase N found:
-1. Check if `.planning/phases/${N}-*/` directory exists
+1. Check if `${PLANNING_DIR}/phases/${N}-*/` directory exists
 2. If directory exists, check for any PLAN.md or SUMMARY.md files inside it
 
 If any downstream phase has started work, collect warnings:
@@ -145,7 +463,8 @@ If any downstream phase has started work, collect warnings:
 
 Extract the phase number from TARGET_PLAN (the NN part of NN-MM). Extract the plan number (the MM part).
 
-Look for later plans in the same phase directory (`.planning/phases/${NN}-*/`). For each later plan (plans with number > MM):
+Look for later plans in the same phase directory (`${PLANNING_DIR}/phases/${NN}-*/`, the
+same workstream-resolved root). For each later plan (plans with number > MM):
 1. Read the later plan's PLAN.md
 2. Check if its `<files>` sections or `consumes` fields reference outputs from the target plan
 
@@ -300,8 +619,8 @@ Show next steps:
 
 <success_criteria>
 - [ ] Arguments parsed correctly for all three modes
-- [ ] --phase mode reads .planning/.phase-manifest.json using manifest.phases[TARGET_PHASE].commits
-- [ ] --phase mode falls back to git log if manifest entry missing
+- [ ] --phase mode anchors selection on the phase's own directory (find-phase -> PHASE_START), never a repository-wide commit-subject grep
+- [ ] --phase and --plan modes fail closed when no anchor resolves, never widening to an unbounded search
 - [ ] Dependency check warns when downstream phases have started (MODE=phase)
 - [ ] Dependency check warns when later plans reference target plan outputs (MODE=plan)
 - [ ] Dirty-tree guard aborts if working tree has uncommitted changes

package/gsd-core/workflows/update.md

@@ -74,7 +74,7 @@ Parse output:
 - Line 1 = installed version (`0.0.0` means unknown version)
 - Line 2 = install scope (`LOCAL`, `GLOBAL`, or `UNKNOWN`)
 - Line 3 = target runtime (`claude`, `opencode`, `kilo`, `codex`, `antigravity`, `windsurf`); empty when no installed target is resolved
-- Line 4 = resolved GSD config dir (e.g. `/Users/me/.claude`, `/Users/me/.gemini`); empty when no installed target is resolved. Capture this as `GSD_DIR` and pass it to subsequent steps so they don't re-derive the runtime path.
+- Line 4 = resolved GSD config dir (e.g. `/Users/me/.claude`, `/Users/me/.gemini/antigravity`); empty when no installed target is resolved. Capture this as `GSD_DIR` and pass it to subsequent steps so they don't re-derive the runtime path.
 
 `update-context` reproduces the previous detection cascade — preferred-config-dir fast path, local-over-global with same-path dedup (so `CWD=$HOME` does not misdetect as LOCAL), env-var overrides (`CLAUDE_CONFIG_DIR`, `OPENCODE_CONFIG_DIR`, `KILO_CONFIG`, `XDG_CONFIG_HOME`, `CODEX_HOME`, …), and semver validation — but as a tested projection rather than ~280 lines of inline bash. Branch coverage lives in `tests/update-context.test.cjs`.
 
@@ -132,7 +132,7 @@ Extract `section_manifest` from `INIT_UPDATE` — gates the `channel-banner` sec
 <step name="check_latest_version">
 Check npm for latest version via the deterministic script. **Do NOT run `npm view` or `npm search` directly** — the package name must come from the script, not from a free choice at execution time. (#2992: LLM-driven prescriptions of npm package names produced wrong-package queries; moving the package name into a script constant closes that gap.)
 
-The `GSD_DIR` value emitted by `get_installed_version` (line 4) resolves to the runtime-specific config dir (`~/.claude/`, `~/.gemini/`, `~/.codex/`, etc.), so the script invocation works for every runtime — not just Claude. An unresolved target exits in `get_installed_version` before this step.
+The `GSD_DIR` value emitted by `get_installed_version` (line 4) resolves to the runtime-specific config dir (`~/.claude/`, `~/.gemini/antigravity/`, `~/.codex/`, etc.), so the script invocation works for every runtime — not just Claude. An unresolved target exits in `get_installed_version` before this step.
 
 `LATEST_RESULT` is a JSON document with the documented shape `{ ok: bool, version: string, reason: string, detail?: string }`. Parse it with the Node-only `uc_field` helper. When the script cannot run or returns nothing, preserve its failure as a meaningful diagnostic (#2993 CR feedback):
 
@@ -273,8 +273,8 @@ rm -f "$CHANGELOG_TMP"
 - `agents/gsd-*` files will be replaced
 
 (Paths are relative to detected runtime install location:
-global: `~/.claude/`, `~/.config/opencode/`, `~/.opencode/`, `~/.gemini/`, `~/.config/kilo/`, or `~/.codex/`
-local: `./.claude/`, `./.config/opencode/`, `./.opencode/`, `./.gemini/`, `./.kilo/`, or `./.codex/`)
+global: `~/.claude/`, `~/.config/opencode/`, `~/.opencode/`, `~/.gemini/antigravity/`, `~/.config/kilo/`, or `~/.codex/`
+local: `./.claude/`, `./.config/opencode/`, `./.opencode/`, `./.agents/`, `./.kilo/`, or `./.codex/`)
 
 Your custom files in other locations are preserved:
 - Custom commands not in `commands/gsd/` ✓
@@ -285,7 +285,7 @@ Your custom files in other locations are preserved:
 If you've modified any GSD files directly, they'll be automatically backed up to `gsd-local-patches/` and can be reapplied with `/gsd:update --reapply` after the update.
 ```
 
-**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Antigravity, etc.) where `AskUserQuestion` is not available.
 Use AskUserQuestion:
 - Question: "Proceed with update?"
 - Options:
@@ -312,7 +312,7 @@ First, resolve the config directory (`RUNTIME_DIR`) from the install scope
 detected in `get_installed_version`:
 
 ```bash
-# RUNTIME_DIR is the resolved config directory (e.g. ~/.config/opencode, ~/.gemini).
+# RUNTIME_DIR is the resolved config directory (e.g. ~/.config/opencode, ~/.gemini/antigravity).
 # get_installed_version emits it as GSD_DIR for a resolved LOCAL or GLOBAL install.
 # The unresolved-target gate exits before this step; the empty guard remains defensive.
 RUNTIME_DIR="$GSD_DIR"
@@ -526,7 +526,7 @@ already empty). Say nothing and continue — the update flow is unchanged.
 
 Otherwise, render the report. Each entry carries `path`, `outcome`, and a
 `warnings` array of `{code, detail}` produced by a compatibility pass against
-the just-installed release — a renamed workflow it `@`-references, a `/gsd:`
+the just-installed release — a renamed workflow it `@`-references, a slash
 command that no longer exists, missing skill frontmatter. Render each entry's
 warnings under its path. Entries whose `outcome` starts with `skipped_` will
 **not** be restored; list them separately, with their reason, so the user knows