@opengsd/gsd-core 1.3.1 → 1.4.0-rc.2

package/gsd-core/workflows/help/modes/full.md

@@ -86,7 +86,7 @@ Create detailed execution plan for a specific phase.
 
 - `--skip-research` — bypass the research subagent
 - `--research-phase <N>` — research-only mode. Spawns the research agent for phase `<N>`, writes `RESEARCH.md`, then exits before the planner runs. Useful for cross-phase research, doc review before committing to a planning approach, and correction-without-replanning loops. Replaces the deleted `gsd-research-phase` standalone command (#3042).
-  - Modifiers: `--research` forces refresh (re-spawn researcher, no prompt). `--view` prints existing `RESEARCH.md` to stdout without spawning. With neither, prompts `update / view / skip` if `RESEARCH.md` already exists.
+  - Modifiers: `--research` forces refresh (re-spawn researcher). `--view` prints existing `RESEARCH.md` to stdout without spawning. With neither, auto-uses an existing `RESEARCH.md` (one-line notice, then clean exit).
 - `--gaps` — focus only on closing gaps from a prior plan-check
 - `--skip-verify` — skip the post-plan verifier loop
 - `--ingest <path-or-glob>` — pre-ingest external ADRs/PRDs/SPECs before planning (see *PRD Express Path* below)
@@ -100,7 +100,7 @@ Create detailed execution plan for a specific phase.
 - Multiple plans per phase supported (XX-01, XX-02, etc.)
 
 Usage: `/gsd:plan-phase 1`
-Usage: `/gsd:plan-phase --research-phase 2` — research only on phase 2 (prompts if `RESEARCH.md` exists)
+Usage: `/gsd:plan-phase --research-phase 2` — research only on phase 2 (auto-uses existing `RESEARCH.md`, no prompt)
 Usage: `/gsd:plan-phase --research-phase 2 --view` — print existing `RESEARCH.md`, no spawn
 Usage: `/gsd:plan-phase --research-phase 2 --research` — force-refresh, no prompt
 Result: Creates `.planning/phases/01-foundation/01-01-PLAN.md`
@@ -550,11 +550,12 @@ Usage: `/gsd:help --full`
 Usage: `/gsd:help debug`
 Usage: `/gsd:help --brief debug`
 
-**`/gsd:update [--sync] [--reapply]`**
+**`/gsd:update [--sync] [--reapply] [--next | --rc]`**
 Update GSD to latest version with changelog preview.
 
 - `--sync` — sync managed GSD skills across runtime roots (replaces the former `gsd-sync-skills`)
 - `--reapply` — reapply local modifications after an update (replaces the former `gsd-reapply-patches`)
+- `--next` (alias `--rc`) — install/refresh from the `@next` RC dist-tag instead of `@latest` (ADR #660); omit for the stable channel
 
 - Shows installed vs latest version comparison
 - Displays changelog entries for versions you've missed

package/gsd-core/workflows/ingest-docs.md

@@ -52,7 +52,8 @@ If `PATH_NOT_FOUND` or `MANIFEST_NOT_FOUND`: display error and exit.
 Run the init query:
 
 ```bash
-INIT=$(node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" init ingest-docs)
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+INIT=$(gsd_run init ingest-docs)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -295,7 +296,7 @@ Preview the merge diff to the user and gate via approve-revise-abort before writ
 Commit the ingest results:
 
 ```bash
-node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" commit \
+gsd_run commit \
   "docs: ingest {N} docs from {SCAN_PATH} (#2387)" --files \
   .planning/PROJECT.md \
   .planning/REQUIREMENTS.md \

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

@@ -32,7 +32,8 @@ Load all context in one call (paths only to minimize orchestrator 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}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
-INIT=$(gsd_run query init.plan-phase "$PHASE")
+GRAN_PARAM=""; if [[ "$ARGUMENTS" =~ (^|[[:space:]])--granularity[[:space:]]+([^[:space:]-][^[:space:]]*) ]]; then GRAN_PARAM="--granularity ${BASH_REMATCH[2]}"; fi
+INIT=$(gsd_run query init.plan-phase "$PHASE" $GRAN_PARAM)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_RESEARCHER=$(gsd_run query agent-skills gsd-phase-researcher)
 AGENT_SKILLS_PLANNER=$(gsd_run query agent-skills gsd-planner)
@@ -46,7 +47,7 @@ When `TDD_MODE` is `true`, the planner agent is instructed to apply `type: tdd`
 
 When `CONTEXT_WINDOW >= 500000`, the planner prompt includes the 3 most recent prior phase CONTEXT.md and SUMMARY.md files PLUS any phases explicitly listed in the current phase's `Depends on:` field in ROADMAP.md. Explicit dependencies always load regardless of recency (e.g., Phase 7 declaring `Depends on: Phase 2` always sees Phase 2's context). Bounded recency keeps the planner's context budget focused on recent work.
 
-Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `nyquist_validation_enabled`, `commit_docs`, `text_mode`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_reviews`, `has_plans`, `plan_count`, `phase_status` (#3569), `planning_exists`, `roadmap_exists`, `phase_req_ids`, `response_language`.
+Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `nyquist_validation_enabled`, `commit_docs`, `text_mode`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_reviews`, `has_plans`, `plan_count`, `phase_status` (#3569), `planning_exists`, `roadmap_exists`, `phase_req_ids`, `response_language`, `granularity`.
 
 **If `response_language` is set:** Include `response_language: {value}` in all spawned subagent prompts so any user-facing output stays in the configured language.
 
@@ -99,7 +100,7 @@ The gate fires only on `Complete`. `Executed` and `Needs Review` are not gated
 
 ## 2. Parse and Normalize Arguments
 
-Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--research-phase <N>`, `--gaps`, `--skip-verify`, `--skip-ui`, `--prd <filepath>`, `--ingest <path-or-glob>`, `--ingest-format <auto|nygard|madr|narrative>`, `--reviews`, `--text`, `--bounce`, `--skip-bounce`, `--chunked`, `--mvp`, `--tdd`, `--force` (override closed-phase gate, see §1.5)).
+Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--research-phase <N>`, `--gaps`, `--skip-verify`, `--skip-ui`, `--prd <filepath>`, `--ingest <path-or-glob>`, `--ingest-format <auto|nygard|madr|narrative>`, `--reviews`, `--text`, `--bounce`, `--skip-bounce`, `--chunked`, `--mvp`, `--tdd`, `--granularity <coarse|standard|fine>`, `--force` (override closed-phase gate, see §1.5)).
 
 **`--research-phase <N>` — research-only mode (#3042 + #3044).** When this flag is present, parse `<N>` as the phase number (overrides any positional phase argument), set `RESEARCH_ONLY=true`, and treat the rest of this workflow as a research-dispatch only — the planner spawn (step 8), plan-checker, verification, gaps, bounce, and post-planning-gaps blocks all skip on `RESEARCH_ONLY`. Use this for cross-phase research, doc review before committing to a planning approach, and correction-without-replanning loops. Replaces the deleted `/gsd-research-phase` command.
 
@@ -120,6 +121,8 @@ if $RESEARCH_ONLY && [[ "$ARGUMENTS" =~ (^|[[:space:]])--view([[:space:]]|$) ]];
 fi
 ```
 
+**`--granularity <coarse|standard|fine>` — CLI override (#703).** When present, this value is the resolved granularity passed to the planner — it wins over any per-phase `granularities.<type>` config, top-level `granularity` config, or project defaults. The init JSON always includes a `granularity` field reflecting the resolved value; read it from there. Invalid values (anything other than `coarse`, `standard`, `fine`) cause an error at the CLI boundary.
+
 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 Claude Code remote sessions (`/rc` mode) where TUI menus don't work through the Claude App.
 
 **MVP_MODE resolution.** Resolve `MVP_MODE` once via the centralized `phase.mvp-mode` query verb. Precedence (first hit wins): CLI flag → ROADMAP.md `**Mode:** mvp` → `workflow.mvp_mode` config → false. The verb is the single source of truth — do not re-implement the chain.
@@ -143,7 +146,7 @@ fi
 ```
 
 When `WALKING_SKELETON=true`:
-- Planner is instructed to produce `SKELETON.md` in the phase directory alongside `PLAN.md`. The template lives at `@~/.claude/gsd-core/references/skeleton-template.md`.
+- Planner is instructed to produce `SKELETON.md` in the phase directory alongside `PLAN.md`. The template lives at `~/.claude/gsd-core/references/skeleton-template.md` — the planner reads it when producing SKELETON.md (lazy; not loaded on non-skeleton runs).
 - The plan must scaffold project + routing + one real DB read/write + one real UI interaction + dev deployment — the thinnest possible end-to-end working slice.
 
 **Interaction with `--prd <filepath>`.** `--mvp` and `--prd` compose. The PRD express path (Step 3.5) creates `CONTEXT.md` from the PRD file and continues to research; the Walking Skeleton gate fires independently from the conditions above. When both are active on Phase 1 of a new project, the planner receives `WALKING_SKELETON=true` and PRD-derived context simultaneously — the PRD informs *what the skeleton should prove*. No precedence is needed; the two signals are orthogonal. See [`references/mvp-concepts.md`](../references/mvp-concepts.md) for the broader interaction map.
@@ -417,15 +420,15 @@ Pass `ai_spec_path` and `framework_line` to planner in step 7 so it can referenc
 
 **Skip if:** `--gaps` flag or `--skip-research` flag or `--reviews` flag.
 
-### 5.0. Research-Only Modifiers (`--view`, `--research`, prompt)
+### 5.0. Research-Only Modifiers (`--view`, `--research`)
 
 **Skip if:** `RESEARCH_ONLY` is `false`.
 
 Three branches in research-only mode (`--research-phase <N>`):
 
-1. **`--view`** (or user picks "View" in the prompt below): print `RESEARCH.md` to stdout, no spawn, exit. If `RESEARCH.md` is missing, error with: `--view requires an existing RESEARCH.md; drop --view to spawn the researcher.`
+1. **`--view`**: print `RESEARCH.md` to stdout, no spawn, exit. If `RESEARCH.md` is missing, error with: `--view requires an existing RESEARCH.md; drop --view to spawn the researcher.`
 2. **`--research`** (force-refresh): re-spawn researcher unconditionally — fall through to "Spawn gsd-phase-researcher" below.
-3. **Neither flag AND `has_research=true`:** emit `RESEARCH.md already exists for Phase ${PHASE}.` and prompt the user with three choices: `1. Update — re-spawn researcher and refresh RESEARCH.md`, `2. View — print existing RESEARCH.md and exit (no spawn)`, `3. Skip — exit without spawning or printing`. Map "Update" → fall through to spawn, "View" → set `VIEW_ONLY=true` and emit RESEARCH.md as in (1), "Skip" → exit cleanly. Mirrors the deleted `/gsd-research-phase` standalone's existing-artifact menu (#3042 parity).
+3. **Neither flag AND `has_research=true`:** auto-use the existing research and exit cleanly — do not prompt, do not re-spawn. Emit `RESEARCH.md already exists for Phase ${PHASE}, using it. To force-refresh, re-invoke with --research; to print, re-invoke with --view. Path: ${research_path}` then exit. The explicit-flag escape hatches cover any deviation; this matches §5.1's promptless auto-use of existing research, removing the §5.0/§5.1 inconsistency (#159).
 
 ```bash
 if [[ "$VIEW_ONLY" == "true" ]]; then
@@ -933,12 +936,13 @@ Each TDD plan gets one feature with RED/GREEN/REFACTOR gate sequence.
 </tdd_mode_active>
 ` : ''}
 
-**MVP_MODE:** ${MVP_MODE} (when true, follow vertical-slice rules from `@~/.claude/gsd-core/references/planner-mvp-mode.md`; when false, ignore MVP guidance entirely.)
-**WALKING_SKELETON:** ${WALKING_SKELETON} (when true, the first deliverable must be a Walking Skeleton — produce SKELETON.md alongside PLAN.md.)
+**MVP_MODE:** ${MVP_MODE} (when true, follow vertical-slice rules from `~/.claude/gsd-core/references/planner-mvp-mode.md`; when false, ignore MVP guidance entirely.)
+**WALKING_SKELETON:** ${WALKING_SKELETON} (when true, the first deliverable must be a Walking Skeleton — Read the template at `~/.claude/gsd-core/references/skeleton-template.md` and produce SKELETON.md alongside PLAN.md.)
+**Granularity:** {granularity}
 
 ${MVP_MODE === 'true' ? `
 <mvp_mode_active>
-**MVP Mode is ENABLED.** Follow vertical-slice planning rules from @~/.claude/gsd-core/references/planner-mvp-mode.md. Each plan must deliver a complete vertical slice — thin end-to-end functionality rather than horizontal layers.
+**MVP Mode is ENABLED.** Read `~/.claude/gsd-core/references/planner-mvp-mode.md` now and follow its vertical-slice planning rules. Each plan must deliver a complete vertical slice — thin end-to-end functionality rather than horizontal layers.
 </mvp_mode_active>
 ` : ''}
 </planning_context>

package/gsd-core/workflows/plan-review-convergence.md

@@ -63,7 +63,7 @@ Then re-run: /gsd:plan-review-convergence {PHASE}
 ## 2. Initialize
 
 ```bash
-INIT=$(node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" init plan-phase "$PHASE")
+INIT=$(gsd_run init plan-phase "$PHASE")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -76,7 +76,7 @@ Set `TEXT_MODE=true` if `--text` is present in $ARGUMENTS OR `text_mode` from in
 ## 3. Validate Phase + Pre-flight Gate
 
 ```bash
-PHASE_INFO=$(node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" roadmap get-phase "${PHASE}")
+PHASE_INFO=$(gsd_run roadmap get-phase "${PHASE}")
 ```
 
 **If `found` is false:** Error with available phases. Exit.
@@ -230,7 +230,7 @@ fi
 **If HIGH_COUNT == 0 (converged):**
 
 ```bash
-node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" state planned-phase --phase "${PHASE}" --name "${phase_name}" --plans "${PLAN_COUNT}"
+gsd_run state planned-phase --phase "${PHASE}" --name "${phase_name}" --plans "${PLAN_COUNT}"
 ```
 
 Display:

package/gsd-core/workflows/review.md

@@ -22,7 +22,7 @@ command -v codex >/dev/null 2>&1 && echo "codex:available" || echo "codex:missin
 command -v coderabbit >/dev/null 2>&1 && echo "coderabbit:available" || echo "coderabbit:missing"
 command -v opencode >/dev/null 2>&1 && echo "opencode:available" || echo "opencode:missing"
 command -v qwen >/dev/null 2>&1 && echo "qwen:available" || echo "qwen:missing"
-command -v cursor >/dev/null 2>&1 && echo "cursor:available" || echo "cursor:missing"
+command -v cursor-agent >/dev/null 2>&1 && echo "cursor:available" || echo "cursor:missing"
 command -v agy >/dev/null 2>&1 && echo "antigravity:available" || echo "antigravity:missing"
 
 # Check local model servers (OpenAI-compatible HTTP API — no CLI binary required)
@@ -248,9 +248,9 @@ fi
 **Codex:**
 ```bash
 if [ -n "$CODEX_MODEL" ] && [ "$CODEX_MODEL" != "null" ]; then
-  cat /tmp/gsd-review-prompt-{phase}.md | codex exec --model "$CODEX_MODEL" --skip-git-repo-check - 2>/dev/null > /tmp/gsd-review-codex-{phase}.md
+  cat /tmp/gsd-review-prompt-{phase}.md | codex exec --ephemeral --dangerously-bypass-hook-trust --model "$CODEX_MODEL" --skip-git-repo-check - 2>/dev/null > /tmp/gsd-review-codex-{phase}.md
 else
-  cat /tmp/gsd-review-prompt-{phase}.md | codex exec --skip-git-repo-check - 2>/dev/null > /tmp/gsd-review-codex-{phase}.md
+  cat /tmp/gsd-review-prompt-{phase}.md | codex exec --ephemeral --dangerously-bypass-hook-trust --skip-git-repo-check - 2>/dev/null > /tmp/gsd-review-codex-{phase}.md
 fi
 ```
 
@@ -284,9 +284,15 @@ fi
 
 **Cursor:**
 ```bash
-cat /tmp/gsd-review-prompt-{phase}.md | cursor agent -p --mode ask --trust 2>/dev/null > /tmp/gsd-review-cursor-{phase}.md
+# cursor-agent is a SEPARATE binary from the `cursor` IDE launcher; print mode (-p) takes the
+# prompt as an ARGUMENT, not stdin. A full review prompt can exceed the OS argument limit, so
+# reference the prompt file by path rather than inlining it. Capture stderr so a failure is
+# diagnosable instead of a silent empty result.
+CURSOR_PROMPT_ARG="Read the file at /tmp/gsd-review-prompt-{phase}.md in full and carry out the review request it contains. Output only the resulting markdown review. Do not edit any files."
+cursor-agent -p --mode ask --trust --output-format text "$CURSOR_PROMPT_ARG" 2>/tmp/gsd-review-cursor-{phase}.err > /tmp/gsd-review-cursor-{phase}.md
 if [ ! -s /tmp/gsd-review-cursor-{phase}.md ]; then
-  echo "Cursor review failed or returned empty output." > /tmp/gsd-review-cursor-{phase}.md
+  echo "Cursor review failed or returned empty output. stderr:" > /tmp/gsd-review-cursor-{phase}.md
+  cat /tmp/gsd-review-cursor-{phase}.err >> /tmp/gsd-review-cursor-{phase}.md
 fi
 ```
 
@@ -350,8 +356,19 @@ if [ -f "$_AGY_CACHE" ]; then
   fi
 fi
 
-# Step 1 — primary invocation: stdout works on macOS, Linux, and WSL
-agy -p "$(cat /tmp/gsd-review-prompt-{phase}.md)" 2>/dev/null > /tmp/gsd-review-antigravity-{phase}.md
+# Step 1 — primary invocation: stdout works on macOS, Linux, and WSL.
+# Bound the run with agy's OWN `--print-timeout` (issue #687). On a large,
+# file-path-rich prompt agy's agentic Cascade can loop on its code_search/grep
+# steps and never converge; `--print-timeout` is agy's native cap for print mode
+# (defaults to 5m — see maintainer note above), so we pass it explicitly to let a
+# stalled run self-terminate through the tool's own mechanism. A non-zero exit
+# (timeout or crash) discards any partial output so the Step 2 transcript fallback
+# / Step 3 stub take over.
+agy --print-timeout 300s -p "$(cat /tmp/gsd-review-prompt-{phase}.md)" 2>/dev/null > /tmp/gsd-review-antigravity-{phase}.md
+_AGY_RC=$?
+if [ "$_AGY_RC" -ne 0 ]; then
+  : > /tmp/gsd-review-antigravity-{phase}.md
+fi
 
 # Step 2 — transcript fallback: catches Windows agy -p stdout bug (and any future stdout-silent edge cases).
 # Reads only lines appended AFTER the pre-flight watermark. If agy failed before writing a new response,

package/gsd-core/workflows/ship.md

@@ -41,15 +41,12 @@ Verify the work is ready to ship:
 
 1. **Verification passed?**
    ```bash
-   VERIFICATION_FILE=$(ls ${PHASE_DIR}/*-VERIFICATION.md 2>/dev/null | head -1)
-   STATUS=$(sed -n '/^---$/,/^---$/p' "${VERIFICATION_FILE}" 2>/dev/null | grep -m1 "^status:" | cut -d: -f2 | tr -d ' ')
+   VERIFICATION=$(gsd_run query verification.status "${PHASE_DIR}" 2>/dev/null)
+   STATUS=$(printf '%s' "$VERIFICATION" | jq -r '.status' 2>/dev/null || echo "")
+   NEXT_ACTION=$(printf '%s' "$VERIFICATION" | jq -r '.next_action' 2>/dev/null || echo "")
+   NEXT_COMMAND=$(printf '%s' "$VERIFICATION" | jq -r '.next_command' 2>/dev/null || echo "")
    ```
-   The verifier emits exactly `passed`, `gaps_found`, or `human_needed` (see the status table in `execute-phase.md`); only `passed` may ship. Route on `${STATUS}` — on any non-`passed` value, block with `PHASE_VERIFICATION_INCOMPLETE` and state the matching next action:
-   - `passed` → verification complete; continue to the next preflight check.
-   - `gaps_found` → run `/gsd:plan-phase ${PHASE_NUMBER} --gaps` to plan the fixes, then re-run `/gsd:execute-phase` before shipping.
-   - `human_needed` → complete the manual tests in `${PHASE_DIR}/*-UAT.md`, then re-run the verify step until status is `passed`.
-   - empty (no `*-VERIFICATION.md`) → the verify step never completed; re-run `/gsd:execute-phase`.
-   - any other value → unexpected status `${STATUS}`; re-run `/gsd:execute-phase` verification.
+   Only `passed` may ship. If `$STATUS` is `passed`, verification is complete — continue to the next preflight check. Any other value (including `gaps_found`, `human_needed`, `missing`, and `unknown`) blocks with `PHASE_VERIFICATION_INCOMPLETE`: present `$NEXT_ACTION` to the user and, when `$NEXT_COMMAND` is non-empty, show it as the command to run next. The query already handles missing files and unexpected values, so no per-status arm is needed.
 
 2. **Clean working tree?**
    ```bash

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

@@ -56,7 +56,8 @@ Rotate through these perspectives — each naturally surfaces different blindspo
 ## Step 1: Initialize
 
 ```bash
-INIT=$(node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" init phase-op "${PHASE}")
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+INIT=$(gsd_run init phase-op "${PHASE}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 

package/gsd-core/workflows/update.md

@@ -75,6 +75,25 @@ If multiple runtime installs are detected and the invoking runtime cannot be det
 **If VERSION file missing (version resolves to `0.0.0`):** report the installed version as Unknown and proceed to install (treated as `0.0.0` for comparison).
 </step>
 
+<step name="parse_update_channel">
+Determine the release channel from `$ARGUMENTS`. This selects which npm dist-tag the entire update flow targets — `latest` (stable) by default, or `next` (the RC channel established by ADR #660) when the user opts in with `--next`/`--rc`:
+
+```bash
+case " $ARGUMENTS " in
+  *" --next "*|*" --rc "*)
+    TAG="next"
+    CHANNEL_LABEL="next (RC)"
+    ;;
+  *)
+    TAG="latest"
+    CHANNEL_LABEL="latest (stable)"
+    ;;
+esac
+```
+
+`TAG` is restricted to `latest`/`next` by `check-latest-version.cjs` (it rejects any other value with exit 2), so no arbitrary dist-tag can leak through. Omitting `--next`/`--rc` reproduces the prior behavior exactly: `TAG=latest`.
+</step>
+
 <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.)
 
@@ -91,7 +110,7 @@ if [ -z "$GSD_DIR" ]; then
   LATEST_VERSION=""
   LATEST_REASON="no_install_detected"
 else
-  LATEST_RESULT="$(node "$GSD_DIR/gsd-core/bin/check-latest-version.cjs" --json 2>/dev/null)"
+  LATEST_RESULT="$(node "$GSD_DIR/gsd-core/bin/check-latest-version.cjs" --json --tag "$TAG" 2>/dev/null)"
   LATEST_STATUS=$?
   # #2993 CR: when node is missing or the script doesn't exist, LATEST_RESULT
   # is empty and piping it to `jq` produces a parse error on stderr while
@@ -114,7 +133,7 @@ fi
 ```text
 Couldn't check for updates (reason: {LATEST_REASON}, exit: {LATEST_STATUS}).
 
-To update manually: `npx -y --package=@opengsd/gsd-core@latest -- gsd-core --global`
+To update manually: `npx -y --package=@opengsd/gsd-core@{TAG} -- gsd-core --global`
 ```
 
 Exit.
@@ -123,6 +142,14 @@ Exit.
 <step name="compare_versions">
 Compare installed vs latest:
 
+**Only when `TAG=next`** (the user passed `--next`/`--rc`), prepend a channel banner so they know they are leaving the stable line — add this line immediately after the `**Latest:**` line in whichever output block renders:
+
+**Channel:** {CHANNEL_LABEL}
+
+On the default stable channel (`TAG=latest`), do NOT add a channel line — the output must match the prior stable behavior exactly.
+
+When `TAG=next`, the "latest" value is the release candidate published under `@next` (e.g. `1.4.0-rc.1`). Apply standard semver precedence for prereleases (`1.4.0-rc.1` is newer than `1.3.1` but older than the final `1.4.0`). Do NOT treat an `-rc.N` suffix as a dev install or as "behind" — offer it as an available update.
+
 **If installed == latest:**
 ```
 ## GSD Update
@@ -174,7 +201,6 @@ EXTRACT_JSON=$(node "$GSD_DIR/gsd-core/scripts/changeset/cli.cjs" extract \
   --changelog "$CHANGELOG_TMP" \
   --json 2>/dev/null)
 EXTRACT_EXIT=$?
-rm -f "$CHANGELOG_TMP"
 
 if [ "$EXTRACT_EXIT" -eq 2 ]; then
   # Exit 2 = no releases in range (e.g. versions are equal or changelog is sparse)
@@ -188,6 +214,8 @@ else
     --to "$LATEST_VERSION" \
     --changelog "$CHANGELOG_TMP" 2>/dev/null || echo "(changelog unavailable)")
 fi
+# Clean up temp changelog now that both extract runs are done
+rm -f "$CHANGELOG_TMP"
 ```
 
 3. Display preview and ask for confirmation, using `$CHANGELOG_PREVIEW` from the extract step above:
@@ -326,17 +354,17 @@ RUNTIME_FLAG="--$TARGET_RUNTIME"
 
 **If LOCAL install:**
 ```bash
-npx -y --package=@opengsd/gsd-core@latest -- gsd-core "$RUNTIME_FLAG" --local
+npx -y --package=@opengsd/gsd-core@"$TAG" -- gsd-core "$RUNTIME_FLAG" --local
 ```
 
 **If GLOBAL install:**
 ```bash
-npx -y --package=@opengsd/gsd-core@latest -- gsd-core "$RUNTIME_FLAG" --global
+npx -y --package=@opengsd/gsd-core@"$TAG" -- gsd-core "$RUNTIME_FLAG" --global
 ```
 
 **If UNKNOWN install:**
 ```bash
-npx -y --package=@opengsd/gsd-core@latest -- gsd-core --claude --global
+npx -y --package=@opengsd/gsd-core@"$TAG" -- gsd-core --claude --global
 ```
 
 Capture output. If install fails, show error and exit.

package/hooks/dist/gsd-config-reload.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+// gsd-config-reload.js — FileChanged hook: hot-reload GSD config context
+// Fires when .planning/config.json is modified, created, or deleted.
+//
+// When the user edits .planning/config.json mid-session, this hook reads the
+// updated config and injects a summary as additionalContext so the agent knows
+// the new configuration without requiring a session restart.
+//
+// Input (from Claude Code):
+//   { session_id, cwd, hook_event_name: "FileChanged",
+//     file_path: "/abs/path/.planning/config.json", event: "change"|"add"|"unlink" }
+//
+// Output:
+//   { hookSpecificOutput: { hookEventName: "FileChanged", additionalContext: "..." } }
+//   or exits 0 silently (if config absent, unreadable, or event is "unlink").
+//
+// Enabled for all Claude Code installs. This hook is always-on — it is a
+// no-op when .planning/config.json is absent (ENOENT → exit 0).
+
+const fs = require('fs');
+const path = require('path');
+
+let input = '';
+// Timeout guard: if stdin does not close within 8s exit silently rather than
+// hanging until Claude Code kills the process and reports "hook error".
+const stdinTimeout = setTimeout(() => process.exit(0), 8000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => (input += chunk));
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const event = data.event; // "change" | "add" | "unlink"
+    const filePath = data.file_path || '';
+    const cwd = data.cwd || process.cwd();
+
+    // Only handle the GSD planning config — verify both basename and that the
+    // resolved path is .planning/config.json relative to cwd.  The hook
+    // matcher ('config.json') fires on any watched config.json; this guard
+    // ensures an unrelated config.json in node_modules/ or elsewhere does not
+    // inject spurious additionalContext.
+    const basename = path.basename(filePath);
+    if (basename !== 'config.json') {
+      process.exit(0);
+    }
+    const expectedPath = path.resolve(cwd, '.planning', 'config.json');
+    if (path.resolve(filePath) !== expectedPath) {
+      process.exit(0);
+    }
+
+    // On unlink (deletion) emit a brief notice and exit
+    if (event === 'unlink') {
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'FileChanged',
+          additionalContext:
+            'GSD config (.planning/config.json) was deleted. ' +
+            'Falling back to built-in defaults for this session.',
+        },
+      }));
+      process.exit(0);
+    }
+
+    // Read the updated config file
+    let config;
+    try {
+      const raw = fs.readFileSync(filePath, 'utf8');
+      config = JSON.parse(raw);
+    } catch (e) {
+      if (e && e.code === 'ENOENT') process.exit(0);
+      // Malformed JSON — inform the agent without crashing
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'FileChanged',
+          additionalContext:
+            'GSD config (.planning/config.json) was modified but could not be parsed. ' +
+            'Check the file for JSON syntax errors.',
+        },
+      }));
+      process.exit(0);
+    }
+
+    // Build a concise summary of key config fields the agent cares about
+    const lines = ['GSD config reloaded (.planning/config.json updated):'];
+
+    if (config.runtime) lines.push(`  runtime: ${config.runtime}`);
+    if (config.mode) lines.push(`  mode: ${config.mode}`);
+
+    // hooks section (opt-in toggles agents act on)
+    if (config.hooks && typeof config.hooks === 'object') {
+      const hookKeys = Object.entries(config.hooks)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(', ');
+      if (hookKeys) lines.push(`  hooks: { ${hookKeys} }`);
+    }
+
+    // workflow section (key toggles)
+    if (config.workflow && typeof config.workflow === 'object') {
+      const wfKeys = Object.entries(config.workflow)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(', ');
+      if (wfKeys) lines.push(`  workflow: { ${wfKeys} }`);
+    }
+
+    // model overrides (agents use these)
+    if (config.models && typeof config.models === 'object') {
+      const modelKeys = Object.entries(config.models)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(', ');
+      if (modelKeys) lines.push(`  models: { ${modelKeys} }`);
+    }
+
+    if (lines.length === 1) {
+      // No notable fields — still confirm the reload happened
+      lines.push('  (no notable keys changed)');
+    }
+
+    const additionalContext = lines.join('\n');
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'FileChanged',
+        additionalContext,
+      },
+    }));
+  } catch (e) {
+    // Silent fail — never block the session on a config reload error
+    process.exit(0);
+  }
+});

package/hooks/dist/gsd-context-monitor.js

@@ -150,7 +150,7 @@ process.stdin.on('end', () => {
         spawn(
           process.execPath,
           [gsdTools, 'state', 'record-session', '--stopped-at', stoppedAt],
-          { cwd, detached: true, stdio: 'ignore' }
+          { cwd, detached: true, stdio: 'ignore', windowsHide: true }
         ).unref();
         warnData.criticalRecorded = true;
         // Persist the sentinel so subsequent debounce cycles don't re-fire

package/hooks/dist/gsd-cursor-post-tool.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+// gsd-cursor-post-tool.js — Cursor postToolUse hook (issue #777)
+//
+// Cursor invokes this script after each tool call completes.
+// Protocol: JSON from Cursor on stdin; JSON response on stdout.
+//
+// Input schema (cursor postToolUse):
+//   { tool_name, tool_input, tool_output, duration,
+//     conversation_id, generation_id, model, hook_event_name,
+//     cursor_version, workspace_roots, user_email, transcript_path }
+//
+// Output schema (cursor postToolUse):
+//   { additional_context?: string }   ← injected as context after the tool use
+//
+// Behaviour:
+//   - After a write-class tool that targets .planning/, reminds the agent
+//     to keep STATE.md current.
+//   - Fails open: any error silently exits 0.
+//
+// Cursor docs: https://cursor.com/docs/hooks
+
+'use strict';
+
+const WRITE_TOOL_RE = /write|edit|replace|create|delete|remove|append|apply|patch|insert|mkdir/i;
+const PATH_KEY_RE = /^(path|file|file_?path|filepath|target_?path|target|dir|directory|uri|filename)$/i;
+const PLANNING_PATH_RE = /(^|[\\/])\.planning([\\/]|$)/;
+
+let raw = '';
+const stdinTimeout = setTimeout(() => {
+  // Timeout guard: exit silently rather than hanging.
+  process.exit(0);
+}, 10000);
+
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { raw += chunk; });
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    let input;
+    try { input = JSON.parse(raw || '{}'); } catch { process.stdout.write(JSON.stringify({})); return; }
+
+    const toolName = String(
+      input.tool_name || input.toolName || ''
+    ).toLowerCase();
+
+    const isWrite = WRITE_TOOL_RE.test(toolName);
+    if (!isWrite) { process.stdout.write(JSON.stringify({})); return; }
+
+    // Collect only PATH-bearing field values (not free-form content).
+    const paths = [];
+    const walk = (v, depth) => {
+      if (depth > 5 || paths.length > 64) return;
+      if (Array.isArray(v)) { for (const x of v) walk(x, depth + 1); return; }
+      if (v && typeof v === 'object') {
+        for (const k of Object.keys(v)) {
+          const val = v[k];
+          if (typeof val === 'string' && PATH_KEY_RE.test(k)) paths.push(val);
+          else walk(val, depth + 1);
+        }
+      }
+    };
+    walk(input.tool_input || input.toolInput || {}, 0);
+
+    if (paths.some((p) => PLANNING_PATH_RE.test(p))) {
+      process.stdout.write(JSON.stringify({
+        additional_context:
+          'GSD: .planning/ artifact updated — ensure STATE.md reflects the latest phase and progress.',
+      }));
+      return;
+    }
+  } catch { /* fall through to empty response */ }
+
+  process.stdout.write(JSON.stringify({}));
+});

package/hooks/dist/gsd-cursor-session-start.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+// gsd-cursor-session-start.js — Cursor sessionStart hook (issue #777)
+//
+// Cursor invokes this script at the start of each agent session.
+// Protocol: JSON from Cursor on stdin; JSON response on stdout.
+//
+// Input schema (cursor sessionStart):
+//   { session_id, is_background_agent, composer_mode, conversation_id,
+//     generation_id, model, hook_event_name, cursor_version,
+//     workspace_roots, user_email, transcript_path }
+//
+// Output schema (cursor sessionStart):
+//   { additional_context?: string }   ← injected into the session as context
+//
+// Behaviour:
+//   - If .planning/STATE.md is present, injects a brief state reminder.
+//   - If absent, nudges the user toward /gsd:new-project.
+//   - Fails open: any error silently exits 0 so a hook bug never wedges Cursor.
+//
+// Cursor docs: https://cursor.com/docs/hooks
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const MSG_PRESENT =
+  'GSD: .planning/STATE.md is present — review the current phase and any blockers before acting.';
+const MSG_ABSENT =
+  'GSD: no .planning/ workflow found — run /gsd:new-project to start a tracked workflow.';
+
+let raw = '';
+const stdinTimeout = setTimeout(() => {
+  // Timeout guard: exit silently rather than hanging.
+  process.exit(0);
+}, 10000);
+
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { raw += chunk; });
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const statePath = path.join(process.cwd(), '.planning', 'STATE.md');
+    const statePresent = fs.existsSync(statePath);
+    const msg = statePresent ? MSG_PRESENT : MSG_ABSENT;
+    process.stdout.write(JSON.stringify({ additional_context: msg }));
+  } catch {
+    // Fail open — never block a Cursor session because of a GSD hook error.
+    process.stdout.write(JSON.stringify({}));
+  }
+});