@opengsd/gsd-core 1.17.0 → 1.19.0

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

@@ -19,6 +19,10 @@ Read all files referenced by the invoking prompt's execution_context before star
 Parse arguments and load project state:
 
 ```bash
+IFS= read -rd '' GSD_ARGS <<'GSD_ARGS_END' || true
+$ARGUMENTS
+GSD_ARGS_END
+GSD_ARGS=${GSD_ARGS%$'\n'}
 _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
 PHASE_ARG="${1}"
 
@@ -28,8 +32,20 @@ PHASE_ARG="${1}"
 # logic (e.g., --all and --auto imply --fix). Resolved BEFORE the init call below so
 # the section-manifest gate forwards the RESOLVED (post-implication) fix decision, not
 # just a literal --fix token check.
+# gsd-resolve-lib begin code-review-flags.cjs (#5640): load helpers from the installed runtime, not the cwd
+_gsd_lib_probe="code-review-flags.cjs"
+_gsd_rt="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+_gsd_gr="$(command -v gsd_run 2>/dev/null || true)"
+case "$_gsd_gr" in /*) ;; *) _gsd_gr="" ;; esac # a gsd_run shell function prints its bare name: not a path
+[ -n "$_gsd_gr" ] && _gsd_gr="$(dirname "$(node -p "require('fs').realpathSync(process.argv[1])" "$_gsd_gr" 2>/dev/null || echo "$_gsd_gr")")/lib"
+GSD_LIB_DIR=""
+_gsd_pick() { for _gsd_d; do if [ -n "$_gsd_d" ] && [ -f "$_gsd_d/$_gsd_lib_probe" ]; then GSD_LIB_DIR="$_gsd_d"; return 0; fi; done; return 1; }
+_gsd_pick "${GSD_TOOLS:+${GSD_TOOLS%/*}/lib}" "$_gsd_rt/gsd-core/bin/lib" "$_gsd_rt/.claude/gsd-core/bin/lib" "$_gsd_rt/.codex/gsd-core/bin/lib" "$_gsd_gr" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib" || true
+if [ -z "$GSD_LIB_DIR" ]; then echo "ERROR: code-review-flags.cjs not found in the GSD runtime. Looked in: ${GSD_TOOLS:+${GSD_TOOLS%/*}/lib, }${_gsd_rt}/gsd-core/bin/lib (and its .claude and .codex forms), ${_gsd_gr:-next to gsd_run (not on PATH)}, ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib, ${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib. Reinstall: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+export GSD_LIB_DIR
+# gsd-resolve-lib end
 FLAGS_JSON=$(node -e "
-  const { parseCodeReviewFlags } = require('./gsd-core/bin/lib/code-review-flags.cjs');
+  const { parseCodeReviewFlags } = require(require('path').join(process.env.GSD_LIB_DIR, 'code-review-flags.cjs'));
   const flags = parseCodeReviewFlags(process.argv.slice(1));
   process.stdout.write(JSON.stringify(flags));
 " -- "$@" 2>/dev/null)
@@ -47,7 +63,7 @@ FILES_OVERRIDE=$(echo "$FLAGS_JSON" | node -e "process.stdout.write(JSON.parse(r
 FIX_PARAM=""
 if [ "$FIX_FLAG" = "true" ]; then FIX_PARAM="--fix"; fi
 
-GSD_WS=$(echo " $ARGUMENTS" | sed -nE 's/.* --ws +([A-Za-z0-9][A-Za-z0-9._-]*).*/--ws \1/p' | head -n 1)
+GSD_WS=$(echo " $GSD_ARGS" | sed -nE 's/.* --ws +([A-Za-z0-9][A-Za-z0-9._-]*).*/--ws \1/p' | head -n 1)
 INIT=$(gsd_run query init.code-review ${GSD_WS:+--ws=${GSD_WS##* }} "${PHASE_ARG}" $FIX_PARAM)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_REVIEWER=$(gsd_run query agent-skills gsd-code-reviewer ${GSD_WS:+--ws=${GSD_WS##* }})
@@ -121,12 +137,25 @@ If FILES_OVERRIDE is set (from --files flag):
 ```bash
 if [ -n "$FILES_OVERRIDE" ]; then
   REVIEW_FILES=()
-  REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+  # #5519: compare the repository root and each resolved path in ONE form. On Windows Git Bash,
+  # `git rev-parse --show-toplevel` (a native program) reports a mixed path (C:/Users/..) while
+  # GNU `realpath` reports an MSYS POSIX path (/c/Users/..); the two never share a prefix, so
+  # every entry looked "outside". `cygpath -m` exists exactly where the forms differ and maps both
+  # to the mixed form; elsewhere the value passes through unchanged.
+  _gsd_norm_path() {
+    if command -v cygpath >/dev/null 2>&1; then cygpath -m "$1"; else printf '%s' "$1"; fi
+  }
+  REPO_ROOT=$(_gsd_norm_path "$(git rev-parse --show-toplevel 2>/dev/null)")
   
   for file_path in "${FILES_ARRAY[@]}"; do
-    # Security: validate path is within repository (prevent path traversal)
-    ABS_PATH=$(realpath -m "${file_path}" 2>/dev/null || echo "${file_path}")
-    if [[ "$ABS_PATH" != "$REPO_ROOT"* ]]; then
+    # Security: validate path is within repository (prevent path traversal). Compare on a path
+    # boundary: the root itself or anything under "<root>/" — a sibling such as "<root>-other"
+    # shares the prefix but is not inside.
+    ABS_PATH=$(_gsd_norm_path "$(realpath -m "${file_path}" 2>/dev/null || echo "${file_path}")")
+    # Fail closed on two shapes that cannot be trusted: an empty root (git failed, so nothing can be
+    # "inside" it) and a path that still holds ".." segments (a resolved path never does, so it was
+    # not resolved — no GNU realpath).
+    if [ -z "$REPO_ROOT" ] || [[ "$ABS_PATH" == */../* || "$ABS_PATH" == */.. ]] || [[ "$ABS_PATH" != "$REPO_ROOT" && "$ABS_PATH" != "$REPO_ROOT"/* ]]; then
       echo "Error: File path outside repository, skipping: ${file_path}"
       continue
     fi
@@ -433,8 +462,20 @@ DEPTH_PAYLOAD=$(printf '%s\n' "${REVIEW_FILES[@]}" | FLAG_DEPTH="$DEPTH_OVERRIDE
   }));
 ")
 
+# gsd-resolve-lib begin code-review-depth.cjs (#5640): load helpers from the installed runtime, not the cwd
+_gsd_lib_probe="code-review-depth.cjs"
+_gsd_rt="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+_gsd_gr="$(command -v gsd_run 2>/dev/null || true)"
+case "$_gsd_gr" in /*) ;; *) _gsd_gr="" ;; esac # a gsd_run shell function prints its bare name: not a path
+[ -n "$_gsd_gr" ] && _gsd_gr="$(dirname "$(node -p "require('fs').realpathSync(process.argv[1])" "$_gsd_gr" 2>/dev/null || echo "$_gsd_gr")")/lib"
+GSD_LIB_DIR=""
+_gsd_pick() { for _gsd_d; do if [ -n "$_gsd_d" ] && [ -f "$_gsd_d/$_gsd_lib_probe" ]; then GSD_LIB_DIR="$_gsd_d"; return 0; fi; done; return 1; }
+_gsd_pick "${GSD_TOOLS:+${GSD_TOOLS%/*}/lib}" "$_gsd_rt/gsd-core/bin/lib" "$_gsd_rt/.claude/gsd-core/bin/lib" "$_gsd_rt/.codex/gsd-core/bin/lib" "$_gsd_gr" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib" || true
+if [ -z "$GSD_LIB_DIR" ]; then echo "ERROR: code-review-depth.cjs not found in the GSD runtime. Looked in: ${GSD_TOOLS:+${GSD_TOOLS%/*}/lib, }${_gsd_rt}/gsd-core/bin/lib (and its .claude and .codex forms), ${_gsd_gr:-next to gsd_run (not on PATH)}, ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib, ${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib. Reinstall: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+export GSD_LIB_DIR
+# gsd-resolve-lib end
 DEPTH_JSON=$(echo "$DEPTH_PAYLOAD" | node -e "
-  const { resolveCodeReviewDepth } = require('./gsd-core/bin/lib/code-review-depth.cjs');
+  const { resolveCodeReviewDepth } = require(require('path').join(process.env.GSD_LIB_DIR, 'code-review-depth.cjs'));
   const input = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf-8'));
   process.stdout.write(JSON.stringify(resolveCodeReviewDepth(input)));
 ")
@@ -733,9 +774,21 @@ if [ -n "$FALLOW_JSON_PATH" ] && [ -f "$FALLOW_JSON_PATH" ]; then
   # Normalize fallow's raw report into the compact {summary, findings[]} contract
   # the reviewer consumes (real fallow schema -> normalized findings).
   FALLOW_NORMALIZED_PATH="${PHASE_DIR}/FALLOW-normalized.json"
+  # gsd-resolve-lib begin fallow-runner.cjs (#5640): load helpers from the installed runtime, not the cwd
+  _gsd_lib_probe="fallow-runner.cjs"
+  _gsd_rt="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+  _gsd_gr="$(command -v gsd_run 2>/dev/null || true)"
+  case "$_gsd_gr" in /*) ;; *) _gsd_gr="" ;; esac # a gsd_run shell function prints its bare name: not a path
+  [ -n "$_gsd_gr" ] && _gsd_gr="$(dirname "$(node -p "require('fs').realpathSync(process.argv[1])" "$_gsd_gr" 2>/dev/null || echo "$_gsd_gr")")/lib"
+  GSD_LIB_DIR=""
+  _gsd_pick() { for _gsd_d; do if [ -n "$_gsd_d" ] && [ -f "$_gsd_d/$_gsd_lib_probe" ]; then GSD_LIB_DIR="$_gsd_d"; return 0; fi; done; return 1; }
+  _gsd_pick "${GSD_TOOLS:+${GSD_TOOLS%/*}/lib}" "$_gsd_rt/gsd-core/bin/lib" "$_gsd_rt/.claude/gsd-core/bin/lib" "$_gsd_rt/.codex/gsd-core/bin/lib" "$_gsd_gr" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib" || true
+  if [ -z "$GSD_LIB_DIR" ]; then echo "ERROR: fallow-runner.cjs not found in the GSD runtime (looked in ${_gsd_rt}/gsd-core/bin/lib (and its .claude and .codex forms), ${_gsd_gr:-next to gsd_run (not on PATH)}, ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib, ${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib); continuing without it." >&2; fi
+  export GSD_LIB_DIR
+  # gsd-resolve-lib end
   FALLOW_SRC="$FALLOW_JSON_PATH" FALLOW_OUT="$FALLOW_NORMALIZED_PATH" node -e "
     const fs = require('fs');
-    const { normalizeFallowReportFile } = require('./gsd-core/bin/lib/fallow-runner.cjs');
+    const { normalizeFallowReportFile } = require(require('path').join(process.env.GSD_LIB_DIR, 'fallow-runner.cjs'));
     const n = normalizeFallowReportFile(process.env.FALLOW_SRC);
     fs.writeFileSync(process.env.FALLOW_OUT, JSON.stringify(n, null, 2));
   " 2>/dev/null && FALLOW_EMBED_PATH="$FALLOW_NORMALIZED_PATH" || FALLOW_EMBED_PATH="$FALLOW_JSON_PATH"
@@ -939,6 +992,11 @@ grep -A 3 "^### CR-\|^### BL-\|^### WR-" "${REVIEW_PATH}" | head -n 12
 **Windows:** This workflow uses bash features (arrays, process substitution). On Windows, it requires
 Git Bash or WSL. Native PowerShell is not supported. The CI matrix (Ubuntu/macOS/Windows)
 runs under Git Bash on Windows runners, which provides bash compatibility.
+The `--files` containment check compares the repository root with each resolved path, and Git Bash
+reports them in different forms (`git rev-parse` returns `C:/Users/...`, GNU `realpath` returns
+`/c/Users/...`), so both are normalized with `cygpath -m` (shipped with Git Bash) before the
+comparison. Relative paths and absolute paths in either form are accepted when they are inside the
+repository (#5519).
 
 **macOS:** macOS ships with bash 3.2 (GPL licensing). This workflow does NOT use `mapfile` (bash 4+
 only) — all array construction uses portable `while IFS= read -r` loops compatible with bash 3.2.

package/gsd-core/workflows/complete-milestone/detail/elaboration.md

@@ -146,7 +146,11 @@ Check branching strategy and offer merge options.
 Use `init milestone-op` for context, or load config directly:
 
 ```bash
-GSD_WS=$(echo " $ARGUMENTS" | sed -nE 's/.* --ws +([A-Za-z0-9][A-Za-z0-9._-]*).*/--ws \1/p' | head -n 1) # Read-loaded file: write the command's original argument string in place of $ARGUMENTS
+IFS= read -rd '' GSD_ARGS <<'GSD_ARGS_END' || true
+$ARGUMENTS
+GSD_ARGS_END
+GSD_ARGS=${GSD_ARGS%$'\n'}
+GSD_WS=$(echo " $GSD_ARGS" | sed -nE 's/.* --ws +([A-Za-z0-9][A-Za-z0-9._-]*).*/--ws \1/p' | head -n 1) # Read-loaded file: write the command's original argument string in place of $GSD_ARGS
 INIT=$(gsd_run query init.execute-phase ${GSD_WS:+--ws=${GSD_WS##* }} "1")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 INIT_CM=$(gsd_run query init.complete-milestone ${GSD_WS:+--ws=${GSD_WS##* }})

package/gsd-core/workflows/complete-milestone/steps/project-md-evolution-review.md

@@ -0,0 +1,145 @@
+<step name="evolve_project_full_review">
+
+Full PROJECT.md evolution review at milestone completion.
+
+Read all phase summaries:
+
+```bash
+_SUMMARIES=( .planning/phases/*-*/*-SUMMARY.md )
+if [ -e "${_SUMMARIES[0]}" ]; then cat "${_SUMMARIES[@]}"; fi
+```
+
+**Full review checklist:**
+
+1. **"What This Is" accuracy:**
+   - Compare current description to what was built
+   - Update if product has meaningfully changed
+
+2. **Core Value check:**
+   - Still the right priority? Did shipping reveal a different core value?
+   - Update if the ONE thing has shifted
+
+3. **Business Context check (only if the section is present):**
+   - Skip entirely if PROJECT.md has no `## Business Context` section
+   - Customer, revenue model, and success metric still accurate after shipping?
+   - Update any field that drifted; refresh the linked strategy doc reference if it moved
+
+4. **Requirements audit:**
+
+   **Validated section:**
+   - All Active requirements shipped this milestone → Move to Validated
+   - Format: `- ✓ [Requirement] — v[X.Y]`
+
+   **Active section:**
+   - Remove requirements moved to Validated
+   - Add new requirements for next milestone
+   - Keep unaddressed requirements
+
+   **Out of Scope audit:**
+   - Review each item — reasoning still valid?
+   - Remove irrelevant items
+   - Add requirements invalidated during milestone
+
+5. **Context update:**
+   - Current codebase state (LOC, tech stack)
+   - User feedback themes (if any)
+   - Known issues or technical debt
+
+6. **Key Decisions audit:**
+   - Extract all decisions from milestone phase summaries
+   - Add to Key Decisions table with outcomes
+   - Mark ✓ Good, ⚠️ Revisit, or — Pending
+
+7. **Constraints check:**
+   - Any constraints changed during development? Update as needed
+
+Update PROJECT.md inline. Update "Last updated" footer:
+
+```markdown
+---
+*Last updated: [date] after v[X.Y] milestone*
+```
+
+**Example full evolution (v1.0 → v1.1 prep):**
+
+Before:
+
+```markdown
+## What This Is
+
+A real-time collaborative whiteboard for remote teams.
+
+## Core Value
+
+Real-time sync that feels instant.
+
+## Requirements
+
+### Validated
+
+(None yet — ship to validate)
+
+### Active
+
+- [ ] Canvas drawing tools
+- [ ] Real-time sync < 500ms
+- [ ] User authentication
+- [ ] Export to PNG
+
+### Out of Scope
+
+- Mobile app — web-first approach
+- Video chat — use external tools
+```
+
+After v1.0:
+
+```markdown
+## What This Is
+
+A real-time collaborative whiteboard for remote teams with instant sync and drawing tools.
+
+## Core Value
+
+Real-time sync that feels instant.
+
+## Requirements
+
+### Validated
+
+- ✓ Canvas drawing tools — v1.0
+- ✓ Real-time sync < 500ms — v1.0 (achieved 200ms avg)
+- ✓ User authentication — v1.0
+
+### Active
+
+- [ ] Export to PNG
+- [ ] Undo/redo history
+- [ ] Shape tools (rectangles, circles)
+
+### Out of Scope
+
+- Mobile app — web-first approach, PWA works well
+- Video chat — use external tools
+- Offline mode — real-time is core value
+
+## Context
+
+Shipped v1.0 with 2,400 LOC TypeScript.
+Tech stack: Next.js, Supabase, Canvas API.
+Initial user testing showed demand for shape tools.
+```
+
+**Step complete when:**
+
+- [ ] "What This Is" reviewed and updated if needed
+- [ ] Core Value verified as still correct
+- [ ] Business Context checked (or confirmed absent)
+- [ ] All shipped requirements moved to Validated
+- [ ] New requirements added to Active for next milestone
+- [ ] Out of Scope reasoning audited
+- [ ] Context updated with current state
+- [ ] All milestone decisions added to Key Decisions
+- [ ] "Last updated" footer reflects milestone completion
+
+</step>

package/gsd-core/workflows/complete-milestone/steps/release-map.md

@@ -0,0 +1,80 @@
+<step name="release_map">
+
+Per-repository release mapping (#3628, ADR-3628). Runs only when the init JSON has `repo_tagging` set to `per_repo` AND a non-empty `sub_repos` list. A GSD milestone version names planned work; each repository has its own release version, so no `v[X.Y]` tag is created in the current directory on this path.
+
+This file is read twice: Part 1 from `archive_milestone`, Part 2 from `push_release_tags`.
+
+Text mode: when `TEXT_MODE` is active, replace every `AskUserQuestion` with a numbered plain-text list.
+
+Working directory for the two JSON files: `RELEASE_MAP_DIR="${TMPDIR:-/tmp}/gsd-release-map-v[X.Y]"`, created with `mkdir -p "$RELEASE_MAP_DIR"`; the map file is `"$RELEASE_MAP_DIR/release-map.json"`. Shell state does not persist between commands, so re-derive these paths in every command that uses them. Write both JSON files with the Write tool; never build them with `echo`, a heredoc or any shell interpolation of the answers.
+
+## Part 1 — Collect, preflight, confirm, tag (runs inside `archive_milestone`, before `milestone complete`)
+
+1. **Collect one entry per repository in `sub_repos`.** For each repository ask for:
+   - `status`: `released`, `deployed`, or `unreleased`.
+   - `release`: the repository's release version. When a tag is created it becomes the tag name, so it must match `^[A-Za-z0-9][A-Za-z0-9._+-]{0,199}$`; re-ask on a mismatch, never alter or skip it. Leave it empty for an `unreleased` repository and never invent one.
+   - `reference`: a commit SHA or pull request reference (free text).
+   - `environment`: free text, for example `production`, `npm`, `development`.
+   - tag choice: `create` (create an annotated tag named `release`; requires a non-empty `release`) or `skip` (record the repository, create nothing). An `unreleased` repository defaults to `skip`.
+
+   Every text field is limited to 200 characters and a map to 256 entries; re-ask when a value is longer. If `git_create_tag` from init is `false`, do not ask the tag choice: every entry is recorded with a `tag` of `none`, no `tags.json` is built, and steps 3, 5 and 6 are skipped (the tag verb and the tag-state update); step 4 asks "Record this release map?" instead. Part 2 does not run.
+
+2. **Build `release-map.json`** (array of `{ "repo", "release", "reference", "environment", "status", "tag" }`) with provisional tag states: `created` for a `create` entry, `skipped` for a `skip` entry, `none` when tagging is disabled. When tags are requested, also build `tags.json` in the same directory: `{ "repo": "<repo>", "tag": "<release>", "ref": "<ref>" }` for each `create` entry and `{ "repo": "<repo>", "skip": true }` for each `skip` entry. `ref` is the entry's `reference`, lowercased, only when it matches `^[0-9a-f]{7,40}$`; any other reference text (for example `PR #412`) is recorded but the tag is placed on the repository's current `HEAD`.
+
+3. **Validate everything before anything is written:**
+
+   ```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; }; _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_run query milestone release-tags --map "$RELEASE_MAP_DIR/tags.json" --dry-run
+   gsd_run query milestone.complete "v[X.Y]" --dry-run --release-map "$RELEASE_MAP_DIR/release-map.json"
+   ```
+
+   If the first reports `ok: false`, show each error with its repository and `reason`; a `tag_conflict` means the tag already exists at a different commit and is never overwritten. If the second fails, it lists every release map problem. Let the user correct the entries or abort, and repeat. Do not continue while either check fails.
+
+4. **One consolidated confirmation.** Show a single table and ask once (AskUserQuestion: "Create these tags? Nothing is pushed." — Create / Edit / Cancel). Include the commit each tag will be placed on (`commit`, shortened, from the dry-run result) and say so when the tag lands on the repository's current `HEAD` rather than a given SHA or when the result reports `detached_head`:
+
+   ```text
+   Milestone v[X.Y] — [Name]
+
+   Repository  Release     Reference   Environment  Tag     Commit
+   dashboard   v5.78.0     PR #412     production   create  HEAD (a1b2c3d)
+   composers   unreleased  abc1234     development  skip    —
+   ```
+
+   On Cancel, stop: nothing has been written and `milestone complete` is not called.
+
+5. **Create the tags:**
+
+   ```bash
+   gsd_run query milestone release-tags --map "$RELEASE_MAP_DIR/tags.json"
+   ```
+
+   If the command exits non-zero, report every repository's status and the `created` list (`repo:tag` pairs already written). Stop before `milestone complete`; running the same command again is safe, it retries only what failed and reports tags already written as `already_tagged`. Tags are placed on commits that already exist in each repository, so merge or squash a repository's release branch before running this flow if the tag must sit on the merged commit.
+
+6. **Record the outcome in the map.** Rewrite `release-map.json` so each `create` entry's `tag` is that repository's `status` from the result (`created` or `already_tagged`); leave `skipped` and `none` as they are. Valid `status` values are `released`, `deployed`, `unreleased`; valid `tag` values are `created`, `already_tagged`, `skipped`, `none`.
+
+7. **Archive the map with the milestone** by adding `--release-map "$RELEASE_MAP_DIR/release-map.json"` to every `milestone complete` call in `archive_milestone`. The map is stored as recorded, whether or not any tag was created.
+
+## Part 2 — Push confirmation (runs after the archive, in place of the single-repository push prompt)
+
+Nothing is pushed by default. For each repository whose entry has `tag` of `created` or `already_tagged`, one at a time. Take `REPO`, `REMOTE` and `TAG` only from the validated release map and the repository's own `git remote` list, and write them into the commands below as single-quoted literals.
+
+Choose the remote: `origin` when `git -C "$REPO" remote` lists it; when there are several remotes and none is `origin`, show the list and ask which one; when there is none, report that and move on. Then show where the push would go (the push URL, with any embedded credentials removed before it is shown):
+
+```bash
+git -C "$REPO" remote get-url --push "$REMOTE"
+```
+
+Ask a separate question naming the repository, the tag, the remote and that URL:
+
+`Push tag <tag> from <repo> to remote <remote> (<url>)? (y/n)`
+
+Only on `y`, push that one tag, with `GIT_TERMINAL_PROMPT=0` exported:
+
+```bash
+git -C "$REPO" push -- "$REMOTE" "refs/tags/$TAG"
+```
+
+A decline, a failed push, or a push that does not finish is reported for that repository only; continue with the next repository. Never push branches, never push several tags in one command, and never push without the answer for that repository.
+
+</step>