refactor: deepen GSDTools query execution seams (#3085)

* refactor: deepen gsdtools query execution seams

* docs: add changeset for query seam deepening

* docs: fix changeset summary text

* fix: address coderabbit query seam findings

* test: address remaining coderabbit findings and notes

* refactor: use internal gsdtools error type import

.changeset/README.md

@@ -0,0 +1,44 @@
+# Changeset Fragments
+
+This directory holds **per-PR CHANGELOG fragments**. Every PR with user-facing changes drops one (or more) `<random-name>.md` files here describing its CHANGELOG entry. Fragments are consolidated into the top-level `CHANGELOG.md` at release time.
+
+## Why
+
+Two PRs that both edit the `### Fixed` block of `CHANGELOG.md` always conflict on merge — git can't pick a serialization order without human input. Two PRs that each add a fresh `.changeset/<unique-name>.md` never conflict because they don't share lines.
+
+See [#2975](https://github.com/gsd-build/get-shit-done/issues/2975) for the full rationale.
+
+## Adding a fragment
+
+```bash
+node scripts/changeset/new.cjs \
+  --type Fixed \
+  --pr 1234 \
+  --body "fix the thing — explain the user-visible change in one sentence"
+```
+
+This writes `.changeset/<adjective>-<noun>-<noun>.md` with frontmatter and a body. Three random words → concurrent PRs don't collide.
+
+## Format
+
+```md
+---
+type: Fixed
+pr: 1234
+---
+**`/gsd-foo` no longer drops trailing slashes** — explain the user-visible change.
+```
+
+Allowed `type:` values follow [Keep a Changelog](https://keepachangelog.com/): `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`.
+
+## Opting out
+
+PRs that legitimately have no user-facing impact can add the `no-changelog` label. CI honors it. When unsure, add the fragment.
+
+## At release time
+
+```bash
+node scripts/changeset/cli.cjs render --version vX.Y.Z --date YYYY-MM-DD
+```
+
+Reads every fragment, groups bullets by `type:`, replaces `## [Unreleased]` with a new `## [vX.Y.Z] - YYYY-MM-DD` block, opens a fresh `## [Unreleased]` above, deletes consumed fragments. Idempotent.

.changeset/blue-stones-topology.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+---
+
+**Query command dispatch deepened with Command Topology Module** — query dispatch now consumes a single topology seam that resolves command tokens, binds native handler adapters, and returns structured no-match diagnosis, improving locality and reducing dispatch seam drift.

.changeset/bold-finches-rally.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3058
+---
+**GSD transport raw-mode handling and timeout fallback hardened** — fixes undefined raw formatting edge case and adds raw-path coverage to prevent regressions.

.changeset/brave-mice-build.md

@@ -0,0 +1,8 @@
+---
+type: Changed
+pr: 3069
+---
+
+**query command metadata now flows through a canonical Command Definition Module seam** — registry assembly, mutation semantics, and alias generation consume one Interface (`family`, `canonical`, `aliases`, `mutation`, `output_mode`, `handler_key`) to improve locality and reduce drift.
+
+**query fallback error mapping cleanup** — the CJS fallback catch path now passes original `err` to `mapFallbackDispatchError` (follow-up to prior review feedback missed in PR #3066).

.changeset/bright-pumas-fold.md

@@ -0,0 +1,6 @@
+---
+type: Changed
+pr: 3075
+---
+
+**query architecture deepening pass** — extracted Query Runtime Context, Native Dispatch Adapter, and Query CLI Output Modules so dispatch policy, runtime context policy, and CLI projection logic each live behind focused seams with higher locality and leverage.

.changeset/calm-birds-greet.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 2990
+---
+gsd-code-fixer worktree no longer fails on the same-branch checkout — the agent now creates a new gsd-reviewfix/ branch via git worktree add -b and fast-forwards the user's branch on cleanup. See #2990.

.changeset/calm-ibex-jump.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 2986
+---
+Test suite for config-schema.cjs is now mutation-resistant — 95 typed assertions kill the 124 surviving Stryker mutants from the 4.62% baseline. Tests target static-key fast path, dynamic-pattern .some semantics, polarity, and regex-anchor tightening. See #2986.

.changeset/calm-tigers-frolic.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3008
+---
+**`tests/install-minimal.test.cjs:307` no longer races on shared `os.tmpdir()` under parallel CI** — the previous shape compared `listTmpStageDirs()` snapshots before and after the throw. Under `scripts/run-tests.cjs --test-concurrency=4`, `tests/install-minimal-all-runtimes.test.cjs` runs in a parallel process and creates/removes `gsd-minimal-skills-*` dirs in the shared OS tmpdir between snapshots, so `deepStrictEqual` failed deterministically when the parallel process happened to have a live stage dir during the snapshot window. Fix: stub `fs.mkdtempSync` to record THIS call's stage dir, then assert that exact path no longer exists after the throw — no global filesystem snapshot, no race. (#3008)

.changeset/codex-bare-node-fix.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3022
+---
+**Codex SessionStart hook now uses absolute Node binary path** — closes the gap left after #3002. The Codex install path wrote `command = "node ${path}"` directly into config.toml, bypassing `resolveNodeRunner()`. Under GUI/minimal-PATH runtimes (`/usr/bin:/bin:/usr/sbin:/sbin`), bare `node` failed to resolve, exit 127. Now routed through new `buildCodexHookBlock()` helper. Reinstall path migrates legacy bare-node entries via new `rewriteLegacyCodexHookBlock()`. See #3017.

.changeset/codex-discuss-fallback.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: TBD
+---
+**Codex skill adapter no longer instructs the agent to silently default discuss-phase decisions.** When `request_user_input` was rejected (Default mode), the generated adapter said "pick a reasonable default" — so `$gsd-discuss-phase` proceeded toward writing CONTEXT.md / DISCUSSION-LOG.md / checkpoints without ever asking the user. Adapter prose now requires the agent to STOP, present plain-text questions, and wait, with explicit named exceptions (`--auto`/`--all`/explicit user approval). See #3018.

.changeset/cool-monkeys-smell.md

@@ -0,0 +1,6 @@
+---
+type: Changed
+pr: 3074
+---
+
+**query CLI path extracted into a dedicated Query CLI Adapter Module** — `sdk/src/cli.ts` now delegates query-specific dispatch, error mapping, and output/exit handling to `sdk/src/query/query-cli-adapter.ts` for better locality and testability.

.changeset/curious-bears-march.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3012
+---
+**Post-install message and update.md no longer recommend the removed `/gsd-reapply-patches` command** — after PR #2824 consolidated 86 skills into ~58, `/gsd-reapply-patches` was folded into a flag (`/gsd-update --reapply`). The 1.39.1 hotfix (#2954) updated `help.md` but missed `bin/install.js`'s `reportLocalPatches` runtime emitter, `get-shit-done/workflows/update.md` Step 4, and the English + zh-CN/ja-JP/ko-KR doc set. Users hit "Unknown command" after every install with backed-up patches. All five runtime branches in `reportLocalPatches` (claude, opencode, kilo, copilot, gemini, codex, cursor) now emit the consolidated form. Regression: `tests/bug-3010-reapply-patches-references.test.cjs` scans `bin/install.js`, every workflow file, and every doc (excluding CHANGELOG history and help.md's deprecation notice) for stale recommendations. See #3010.

.changeset/docs-1-40-0-audit.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 0
+---
+**Documentation refreshed for v1.40.0** — full audit of `docs/` against the 1.40.0-rc.1 release surface. Updates command lists, walkthroughs, and inventory rows for the 86→59 skill consolidation (#2790), the six namespace meta-skills with two-stage routing (#2792), the `/gsd-health --context` guard, the phase-lifecycle status-line read-side (#2833), and the Gemini colon-form / non-Gemini hyphen-form slash-command split. Translations in ja-JP/ko-KR/zh-CN/pt-BR mirror the structural changes; new English prose is marked with `<!-- TODO i18n -->` for human translator follow-up. CHANGELOG.md `[Unreleased]` section regrouped under Feature/Enhancement/Fix headers.

.changeset/dynamic-routing.md

@@ -0,0 +1,5 @@
+---
+type: Added
+pr: TBD
+---
+**`dynamic_routing` block in `.planning/config.json` for failure-tier escalation (#3024).** Each agent declares a default tier (`light` / `standard` / `heavy`); when `dynamic_routing.enabled: true`, the resolver picks `tier_models[default_tier]` for the first spawn and escalates one tier up on orchestrator-detected soft failure (capped by `max_escalations`). Disabled by default — fully backward compatible. Composes with `model_overrides` (higher precedence) and `models.<phase_type>` (lower) for full cost-control flexibility. Adds new resolver `resolveModelForTier(cwd, agent, attempt)` to `core.cjs` for orchestrator integration.

.changeset/eager-hawks-rally.md

@@ -0,0 +1,5 @@
+---
+type: Added
+pr: 2975
+---
+**Changeset-fragment workflow** — eliminates CHANGELOG.md merge conflicts. Each PR drops `.changeset/<random-name>.md` with frontmatter (`type:`, `pr:`) plus a markdown body; the release-time `npm run changelog:render` consolidates fragments into `CHANGELOG.md` and deletes them. CI lint (`npm run lint:changeset`) requires a fragment on any PR touching user-facing files (`bin/`, `get-shit-done/`, `agents/`, `commands/`, `hooks/`, `sdk/src/`); contributors can opt out via the `no-changelog` label for purely internal changes. See [.changeset/README.md](.changeset/README.md) and CONTRIBUTING.md for the workflow.

.changeset/gemini-skip-local-when-global.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3037
+---
+**Gemini local install no longer duplicates `/gsd:*` commands across user and workspace scopes** — when GSD is already installed at the user scope (`~/.gemini/commands/gsd/`) and you run `npx get-shit-done-cc --gemini --local` in a project, the installer now skips writing `commands/gsd/` to `<project>/.gemini/` and prints a one-line warning explaining why. Previously, both scopes received the same 65 command files, and Gemini's conflict detector renamed every `/gsd:*` command to `/workspace.gsd:*` and `/user.gsd:*`, breaking the documented namespace. Closes #3037.

.changeset/happy-jays-greet.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 2994
+---
+/gsd-reapply-patches Step 5 verifier now resolves at runtime — moved scripts/verify-reapply-patches.cjs to get-shit-done/bin/ which is shipped by the installer. The legacy scripts/ directory is not copied to user installs. See #2994.

.changeset/happy-tigers-travel.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 3060
+---
+**Query mutation event mapping moved to dedicated module** — preserves event payloads while improving registry locality and test surface.

.changeset/help-passthrough.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3026
+---
+**`gsd-sdk query <subcommand> --help` now reaches the handler instead of returning top-level usage.** The query argv parser harvested `--help` as a global flag and `main()` short-circuited dispatch — there was no path to discover what arguments a query subcommand accepts. The parser now leaves `--help` in `queryArgv` so the handler/fallback can render contextual help. The `gsd-tools.cjs` fallback now renders top-level usage on `--help` (instead of erroring), preserving #1818's anti-hallucination invariant by NOT executing the destructive command. See #3019.

.changeset/humble-goats-swim.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 3060
+---
+**Alias-family handler maps moved to dedicated catalog module** — keeps command keys/order while reducing createRegistry coupling and improving family-level locality.

.changeset/install-shell-path-probe.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3028
+---
+**Installer no longer prints `✓ GSD SDK ready` when the shim is unreachable from the user's runtime shells.** The previous check used `process.env.PATH` from the install subprocess, which often differs from the user's later interactive shells (POSIX `~/.local/bin` not in login shell, node-version-manager PATH shims). Added `getUserShellPath()` helper that probes `$SHELL -lc 'printf %s "$PATH"'` and `isGsdSdkOnPath(pathString?)` overload that accepts an explicit PATH; the install-time check now downgrades to the actionable `⚠` diagnostic from PR #3014 when install-PATH and user-shell-PATH disagree. Windows cross-shell support tracked separately. See #3020.

.changeset/issue-driven-orchestration.md

@@ -0,0 +1,5 @@
+---
+type: Added
+pr: 2840
+---
+**`docs/issue-driven-orchestration.md` — recipe for driving GSD from a tracker issue** — new guide that maps Symphony-style orchestration concepts (workflow, isolated agent workspace, proof-of-work, human review gate, follow-up capture) onto existing GSD primitives (`/gsd-new-workspace`, `/gsd-manager`, `/gsd-autonomous`, `/gsd-verify-work`, `/gsd-review`, `/gsd-ship`, `STATE.md`, phase artifacts). Documentation only — no new commands, no daemon, no tracker integration.

.changeset/jolly-newts-roam.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 2994
+---
+/gsd-reapply-patches Step 5 verifier now resolves at runtime — moved scripts/verify-reapply-patches.cjs to get-shit-done/bin/ which is shipped by the installer. The legacy scripts/ directory is not copied to user installs. See #2994.

.changeset/jolly-pumas-dance.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 2979
+---
+Managed JS hooks now resolve under GUI/minimal-PATH runtimes — installer emits process.execPath (absolute, quoted, forward-slash-normalized) as the runner for every .js hook command instead of bare node. See #2979.

.changeset/lively-goats-run.md

@@ -0,0 +1,5 @@
+---
+type: Added
+pr: 2995
+---
+Post-install path smoke test for workflow-invoked scripts — audits every node ${GSD_HOME}/...cjs invocation in workflows resolves at the runtime-installed path. See #2995.

.changeset/lively-otters-gather.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3011
+---
+**Actionable diagnostic when `gsd-sdk` is not on PATH after install** — Windows users (and others on multi-shell setups) reported that the previous "GSD SDK files are present but `gsd-sdk` is not on your PATH" warning gave them no way to fix it: no path to look at, no shell-specific commands, no mention of the npx-cache caveat. New `formatSdkPathDiagnostic({ shimDir, platform, runDir })` helper returns a typed IR with the resolved shim location, platform-specific PATH-export commands (PowerShell / cmd.exe / Git Bash on Windows; `export PATH` on POSIX), and an npx-specific note when running under an `_npx` cache segment (where the shim may be written to a temp dir that won't persist). The console renderer in `bin/install.js` emits the lines from the IR; tests assert on the typed fields directly. (#3011)

.changeset/mcp-token-budget-docs.md

@@ -0,0 +1,5 @@
+---
+type: Added
+pr: 3032
+---
+**Documentation: MCP tool schema as a context-budget concern (#3025).** Adds new sections to `get-shit-done/references/context-budget.md` and `docs/USER-GUIDE.md` explaining that every enabled MCP server injects its tool schema into every turn — heavyweight servers (browser/playwright, Mac-tools, Windows-tools) can cost 20k+ tokens each, often dwarfing what `model_profile` tuning saves. The toggle lives in `.claude/settings.json` (`enabledMcpjsonServers` / `disabledMcpjsonServers`) and is a Claude Code harness concern, not a GSD concern. Includes a pre-phase audit checklist (browser, platform-specific, cross-project, duplicates) and notes the multiplier interaction with `model_profile`. Companion to #3023 (per-phase-type model map) and #3024 (dynamic routing); together they cover the three biggest cost levers.

.changeset/merry-foxes-climb.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 2997
+---
+SDK config-set/config-get and init responses no longer echo plaintext API keys. New sdk/src/query/secrets.ts ports SECRET_CONFIG_KEYS masking from CJS; init bundles only mask string values to preserve the boolean availability-flag contract. See #2997.

.changeset/merry-lynx-sing.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 2992
+---
+/gsd-update queries wrong npm package names — moved package name into a deterministic check-latest-version.cjs script and updated the workflow to use ${GSD_DIR} from get_installed_version. See #2992.

.changeset/merry-lynx-wander.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3007
+---
+**PR templates now point at the changeset workflow** — the `Fix`, `Enhancement`, and `Feature` PR templates previously asked contributors to tick `CHANGELOG.md updated`, which contradicted the post-#2978 rule that `CHANGELOG.md` must not be edited directly. Each checkbox now references `npm run changeset` (and the `no-changelog` opt-out where applicable).

.changeset/merry-moles-chatter.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 3060
+---
+**CLI query CJS fallback execution extracted to dedicated adapter module** — preserves logs/help passthrough behavior while improving fallback locality and testability.

.changeset/noble-badgers-roar.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 3060
+---
+**Query mutation event emission now uses a dedicated decorator seam** — preserves fire-and-forget behavior while reducing registry coupling and improving testability.

.changeset/per-phase-type-models.md

@@ -0,0 +1,5 @@
+---
+type: Added
+pr: 3030
+---
+**`models` block in `.planning/config.json` for per-phase-type model selection (#3023).** A new resolution layer between per-agent `model_overrides` and the `model_profile` tier table. Six named slots (`planning` / `discuss` / `research` / `execution` / `verification` / `completion`) accept tier aliases (`opus` / `sonnet` / `haiku` / `inherit`). Lets you express "Opus for planning, Sonnet for the rest" in two lines without learning the agent taxonomy. Fully backward compatible — configs without `models` behave exactly as today.

.changeset/plucky-ibex-gather.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 2998
+---
+gsd-pristine/ is now populated by the installer when local patches are detected — saveLocalPatches calls a new populatePristineDir helper that runs the install transform pipeline into a tmp staging dir and copies modified files into pristineDir. The reapply-patches Step 5 verifier no longer falls back to its over-broad heuristic. See #2998.

.changeset/plucky-moles-roam.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 2997
+---
+SDK config-set/config-get and init responses no longer echo plaintext API keys. New sdk/src/query/secrets.ts ports SECRET_CONFIG_KEYS masking from CJS; init bundles only mask string values to preserve the boolean availability-flag contract. See #2997.

.changeset/plucky-otters-roam.md

@@ -0,0 +1,5 @@
+---
+type: Added
+pr: 2995
+---
+Post-install path smoke test for workflow-invoked scripts — audits every node ${GSD_HOME}/...cjs invocation in workflows resolves at the runtime-installed path. See #2995.

.changeset/quick-geese-hum.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 3060
+---
+**Query fallback orchestration now shared** — CLI and SDK query dispatch now use one planning seam for native vs CJS fallback decisions with behavior parity preserved.

.changeset/rapid-goats-munch.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 3060
+---
+**Query/transport policy data now converged in shared module** — mutation and raw-output policy wiring now share one source of truth to reduce drift.

.changeset/research-flag-and-stale-refs.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 3042
+---
+**`/gsd-research-phase` consolidated into `/gsd-plan-phase --research-phase <N>`** — the standalone research command's slash-command stub was never registered (#3042). Rather than restore the orphan, the research-only capability now lives as a flag on `/gsd-plan-phase`. New modifiers: `--view` prints existing `RESEARCH.md` to stdout without spawning, `--research` forces refresh, otherwise prompts `update / view / skip` when `RESEARCH.md` already exists. Also scrubs four other stale slash-command references (`/gsd-check-todos`, `/gsd-new-workspace`, `/gsd-status`, residual `/gsd-plan-milestone-gaps`) across English + 4 localized doc sets (#3044). Closes #3042 and #3044.

.changeset/scrub-stale-command-routes.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3029
+---
+**`/gsd-code-review-fix` and `/gsd-plan-milestone-gaps` no longer surface as "Unknown command"** — both were consolidated by #2790 (`/gsd-code-review --fix` and inline gap planning in `/gsd-audit-milestone` respectively), but several user-facing surfaces still emitted the old slash forms in their offer text. Fixed audit-milestone offer blocks, gsd-complete-milestone routing, code-review/execute-phase offer text, gsd-code-fixer agent role card, and the doc surfaces (USER-GUIDE, FEATURES, INVENTORY, AGENTS, CONFIGURATION). Closes #3029, closes #3034.

.changeset/silly-foxes-wander.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 2990
+---
+gsd-code-fixer worktree no longer fails on the same-branch checkout — the agent now creates a new gsd-reviewfix/ branch via git worktree add -b and fast-forwards the user's branch on cleanup. See #2990.

.changeset/silly-newts-swim.md

@@ -0,0 +1,5 @@
+---
+type: Added
+pr: 2982
+---
+Extended no-source-grep lint to catch var-binding readFileSync.includes() pattern. Tests now fail when source-grep is hidden behind a parser wrapper. See #2982.

.changeset/steady-ravens-shape.md

@@ -0,0 +1,6 @@
+---
+type: Changed
+pr: 3065
+---
+
+**Dispatch policy seam now returns a structured result contract** across native and fallback query execution paths (`ok`, typed error `kind`, `details`, and final `exit_code`), with CLI consuming the unified result instead of mixed throw/result handling.

.changeset/sturdy-jays-glide.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 3060
+---
+**Query static command registrations now split into domain catalog modules** — preserves command order/strings while improving registry locality and maintenance.

.changeset/tidy-tunas-zip.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 3085
+---
+**`GSDTools` query execution internals now use deep Module seams** — refactors runtime composition, native/subprocess adapters, and output projection behind stable public interfaces for better locality and testability.

.changeset/typed-rivers-flow.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 2974
+---
+Migrated 8 test files from raw text matching (`stdout.includes(...)`, `assert.match(stderr, ...)`) to typed-IR assertions per CONTRIBUTING.md. Adds shared `ERROR_REASON` enum and `--json-errors` flag in `core.cjs`, typed `GRAPHIFY_REASON` in `graphify.cjs`, pure `buildSdkFailFastReport()` IR builder in `bin/install.js`, and Claude Code JSON envelope output (`hookSpecificOutput` with typed fields) for `gsd-session-state.sh` and `gsd-phase-boundary.sh`. Tests now assert on structured fields (`reason`, `context`, `state_present`, `planning_modified`, etc.) instead of substring matching. See #2974.

.changeset/update-banner-opt-in.md

@@ -0,0 +1,5 @@
+---
+type: Added
+pr: 2795
+---
+**Optional update banner for non-GSD statusline users** — when the installer detects you've declined or kept a non-GSD statusline, it now offers an opt-in `SessionStart` banner that surfaces update availability via the existing `~/.cache/gsd/gsd-update-check.json` cache. Silent when up-to-date, rate-limits failure diagnostics to once per 24h, removed cleanly by `npx get-shit-done-cc --uninstall`.

.changeset/witty-hawks-jump.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 2973
+---
+/gsd-profile-user --refresh writes dev-preferences.md to ~/.claude/skills/gsd-dev-preferences/SKILL.md instead of the legacy commands/gsd/ directory. Installer migrates any preserved legacy file to the new location. See #2973.

.changeset/witty-newts-greet.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 2992
+---
+/gsd-update queries wrong npm package names — moved package name into a deterministic check-latest-version.cjs script and updated the workflow to use ${GSD_DIR} from get_installed_version. See #2992.

.changeset/zesty-jays-wake.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 2979
+---
+Managed JS hooks now resolve under GUI/minimal-PATH runtimes — installer emits process.execPath (absolute, quoted, forward-slash-normalized) as the runner for every .js hook command instead of bare node. See #2979.

.changeset/zesty-moles-forage.md

@@ -0,0 +1,5 @@
+---
+type: Added
+pr: 2982
+---
+Extended no-source-grep lint to catch var-binding readFileSync.includes() pattern. Tests now fail when source-grep is hidden behind a parser wrapper. See #2982.

.coderabbit.yaml

@@ -0,0 +1,26 @@
+# CodeRabbit configuration — gsd-build/get-shit-done
+#
+# Schema: https://docs.coderabbit.ai/reference/yaml-template/
+#
+# Project context: GSD ships a CLI tool + an agent runtime, not a documented
+# public library. We carry rich JSDoc on internal helpers that warrant it
+# (see bin/install.js, get-shit-done/bin/lib/*.cjs) but we do not enforce a
+# blanket docstring coverage bar — see issue #2932 for rationale.
+
+reviews:
+  pre_merge_checks:
+    # Disable docstring coverage check.
+    #
+    # The check produces false-positive warnings on PRs whose new code is
+    # entirely test files: it counts test(...) / beforeEach / afterEach
+    # arrow-function callbacks as functions and then reports 0% coverage
+    # because nothing has JSDoc. There is no per-check path filter in CR's
+    # documented schema that would let us exclude tests/** while keeping
+    # the check active elsewhere, and the top-level path_filters approach
+    # would silence ALL CR review on tests (security scans, out-of-scope
+    # checks, line-level findings) which we want to keep.
+    #
+    # All other CR pre-merge checks (out-of-scope, security, title) remain
+    # at their defaults.
+    docstrings:
+      mode: off

.githooks/pre-commit

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if git diff --cached --name-only | grep -Eq "^sdk/src/query/command-manifest\.|^sdk/src/query/command-aliases\.generated\.ts$|^get-shit-done/bin/lib/command-aliases\.generated\.cjs$|^sdk/scripts/gen-command-aliases\.ts$"; then
+  npm run check:alias-drift
+fi

.githooks/pre-push

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+zero_sha='0000000000000000000000000000000000000000'
+blocked_regex="${GSD_BLOCKED_AUTHOR_REGEX:-}"
+
+# Local-only guard: no-op unless the developer opts in via env var, e.g.
+# export GSD_BLOCKED_AUTHOR_REGEX='@example-corp\.com$'
+if [[ -z "$blocked_regex" ]]; then
+  exit 0
+fi
+
+violations=()
+
+while read -r local_ref local_sha remote_ref remote_sha; do
+  # branch/tag deletion
+  if [[ "$local_sha" == "$zero_sha" ]]; then
+    continue
+  fi
+
+  if [[ "$remote_sha" == "$zero_sha" ]]; then
+    # New remote ref: inspect commits not already on any remote
+    commit_list=$(git rev-list "$local_sha" --not --remotes)
+  else
+    commit_list=$(git rev-list "$remote_sha..$local_sha")
+  fi
+
+  while read -r commit; do
+    [[ -z "$commit" ]] && continue
+    author_email=$(git show -s --format='%ae' "$commit")
+    lower_email=$(printf '%s' "$author_email" | tr '[:upper:]' '[:lower:]')
+    if printf '%s' "$lower_email" | grep -Eq "$blocked_regex"; then
+      violations+=("$commit <$author_email>")
+    fi
+  done <<< "$commit_list"
+done
+
+if [[ ${#violations[@]} -gt 0 ]]; then
+  {
+    echo "Push blocked: commit author email matched local blocked regex ($blocked_regex)."
+    echo "Rewrite author info before pushing these commits:"
+    for v in "${violations[@]}"; do
+      echo "  - $v"
+    done
+    echo "Suggested fix: git rebase -i <base> --exec \"git commit --amend --no-edit --author='Your Name <non-enterprise@email>'\""
+  } >&2
+  exit 1
+fi

.github/PULL_REQUEST_TEMPLATE/enhancement.md

@@ -73,7 +73,7 @@ Closes #
 - [ ] Changes are scoped to the approved enhancement — nothing extra included
 - [ ] All existing tests pass (`npm test`)
 - [ ] New or updated tests cover the enhanced behavior
-- [ ] CHANGELOG.md updated
+- [ ] `.changeset/` fragment added (`npm run changeset -- --type Changed --pr <NNN> --body "..."`) — or `no-changelog` label applied if not user-facing
 - [ ] Documentation updated if behavior or output changed
 - [ ] No unnecessary dependencies added
 

.github/PULL_REQUEST_TEMPLATE/feature.md

@@ -94,7 +94,7 @@ Closes #
 - [ ] Implementation scope matches the approved spec exactly
 - [ ] All existing tests pass (`npm test`)
 - [ ] New tests cover the happy path, error cases, and edge cases
-- [ ] CHANGELOG.md updated with a user-facing description of the feature
+- [ ] `.changeset/` fragment added with a user-facing description of the feature (`npm run changeset -- --type Added --pr <NNN> --body "..."`)
 - [ ] Documentation updated — commands, workflows, references, README if applicable
 - [ ] No unnecessary external dependencies added
 - [ ] Works on Windows (backslash paths handled)

.github/PULL_REQUEST_TEMPLATE/fix.md

@@ -63,7 +63,7 @@ Fixes #
 - [ ] Fix is scoped to the reported bug — no unrelated changes included
 - [ ] Regression test added (or explained why not)
 - [ ] All existing tests pass (`npm test`)
-- [ ] CHANGELOG.md updated if this is a user-facing fix
+- [ ] `.changeset/` fragment added if this is a user-facing fix (`npm run changeset -- --type Fixed --pr <NNN> --body "..."`) — or `no-changelog` label applied
 - [ ] No unnecessary dependencies added
 
 ## Breaking changes

.github/workflows/canary.yml

@@ -0,0 +1,157 @@
+# Release stream policy:
+#   dev   → @canary  (this workflow — preview builds for the long-lived integration branch)
+#   main  → @next    (RC train, see release.yml)
+#   main  → @latest  (stable cuts, see release.yml)
+#
+# Streams do not mix. The publish/tag steps below gate on `refs/heads/dev` so a
+# workflow_dispatch run on any other branch (including main) completes the
+# build/test/dry-run validation but does not publish or tag.
+
+name: Canary
+
+on:
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: 'Dry run (skip npm publish, tagging, and push)'
+        required: false
+        type: boolean
+        default: false
+
+concurrency:
+  group: canary
+  cancel-in-progress: false
+
+env:
+  NODE_VERSION: 24
+
+jobs:
+  canary:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+      id-token: write
+    environment: npm-publish
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f  # v6.3.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+
+      - name: Determine canary version
+        id: canary
+        run: |
+          # Strip any pre-release suffix from package.json version to get base (e.g. 1.39.0-rc.4 → 1.39.0)
+          RAW=$(node -p "require('./package.json').version")
+          BASE=$(echo "$RAW" | sed 's/-.*//')
+          # Find next sequential canary number from existing tags
+          N=1
+          while git tag -l "v${BASE}-canary.${N}" | grep -q .; do
+            N=$((N + 1))
+          done
+          CANARY_VERSION="${BASE}-canary.${N}"
+          echo "canary_version=$CANARY_VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump to canary version
+        env:
+          CANARY_VERSION: ${{ steps.canary.outputs.canary_version }}
+        run: |
+          npm version "$CANARY_VERSION" --no-git-tag-version
+          cd sdk && npm version "$CANARY_VERSION" --no-git-tag-version && cd ..
+
+      - name: Install and test
+        run: |
+          npm ci
+          npm test
+
+      - name: Build SDK dist for tarball
+        run: npm run build:sdk
+
+      - name: Verify tarball ships sdk/dist/cli.js (bug #2647)
+        run: bash scripts/verify-tarball-sdk-dist.sh
+
+      - name: Dry-run publish validation
+        run: |
+          npm publish --dry-run --tag canary
+          cd sdk && npm publish --dry-run --tag canary
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Tag and push
+        if: ${{ github.ref == 'refs/heads/dev' && !inputs.dry_run }}
+        env:
+          CANARY_VERSION: ${{ steps.canary.outputs.canary_version }}
+        run: |
+          git tag "v${CANARY_VERSION}"
+          git push origin "v${CANARY_VERSION}"
+
+      - name: Publish to npm (canary)
+        if: ${{ github.ref == 'refs/heads/dev' && !inputs.dry_run }}
+        run: npm publish --provenance --access public --tag canary
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish SDK to npm (canary)
+        if: ${{ github.ref == 'refs/heads/dev' && !inputs.dry_run }}
+        run: cd sdk && npm publish --provenance --access public --tag canary
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Verify publish
+        if: ${{ github.ref == 'refs/heads/dev' && !inputs.dry_run }}
+        env:
+          CANARY_VERSION: ${{ steps.canary.outputs.canary_version }}
+        run: |
+          PUBLISHED="NOT_FOUND"
+          SDK_PUBLISHED="NOT_FOUND"
+          for delay in 5 10 20 30 45; do
+            PUBLISHED=$(npm view get-shit-done-cc@"$CANARY_VERSION" version 2>/dev/null || echo "NOT_FOUND")
+            SDK_PUBLISHED=$(npm view @gsd-build/sdk@"$CANARY_VERSION" version 2>/dev/null || echo "NOT_FOUND")
+            if [ "$PUBLISHED" = "$CANARY_VERSION" ] && [ "$SDK_PUBLISHED" = "$CANARY_VERSION" ]; then
+              break
+            fi
+            echo "Not yet live (sleeping ${delay}s)..."
+            sleep "$delay"
+          done
+          if [ "$PUBLISHED" != "$CANARY_VERSION" ]; then
+            echo "::error::Published version verification failed. Expected $CANARY_VERSION, got $PUBLISHED"
+            exit 1
+          fi
+          echo "Verified: get-shit-done-cc@$CANARY_VERSION is live on npm"
+          if [ "$SDK_PUBLISHED" != "$CANARY_VERSION" ]; then
+            echo "::error::SDK version verification failed. Expected $CANARY_VERSION, got $SDK_PUBLISHED"
+            exit 1
+          fi
+          echo "Verified: @gsd-build/sdk@$CANARY_VERSION is live on npm"
+          CANARY_TAG=$(npm dist-tag ls get-shit-done-cc 2>/dev/null | grep "canary:" | awk '{print $2}')
+          echo "canary dist-tag points to: $CANARY_TAG"
+
+      - name: Summary
+        env:
+          CANARY_VERSION: ${{ steps.canary.outputs.canary_version }}
+          DRY_RUN: ${{ inputs.dry_run }}
+          PUBLISH_ELIGIBLE: ${{ github.ref == 'refs/heads/dev' && !inputs.dry_run }}
+          BRANCH_REF: ${{ github.ref }}
+        run: |
+          echo "## Canary v${CANARY_VERSION}" >> "$GITHUB_STEP_SUMMARY"
+          if [ "$DRY_RUN" = "true" ]; then
+            echo "**DRY RUN** — npm publish, tagging, and push skipped" >> "$GITHUB_STEP_SUMMARY"
+          elif [ "$PUBLISH_ELIGIBLE" != "true" ]; then
+            echo "**VALIDATION ONLY** — publish/tag skipped for \`${BRANCH_REF}\`; canary publish is gated to \`refs/heads/dev\`." >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "- Published to npm as \`canary\`" >> "$GITHUB_STEP_SUMMARY"
+            echo "- SDK also published: \`@gsd-build/sdk@${CANARY_VERSION}\` on \`canary\`" >> "$GITHUB_STEP_SUMMARY"
+            echo "- Tagged \`v${CANARY_VERSION}\`" >> "$GITHUB_STEP_SUMMARY"
+            echo "- Install: \`npx get-shit-done-cc@canary\`" >> "$GITHUB_STEP_SUMMARY"
+          fi

.github/workflows/changeset-required.yml

@@ -0,0 +1,24 @@
+name: Changeset Required
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  changeset-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+      - name: Run changeset lint
+        env:
+          GITHUB_BASE_REF: ${{ github.base_ref }}
+        run: node scripts/changeset/lint.cjs

.github/workflows/hotfix.yml

@@ -1,5 +1,27 @@
 name: Hotfix Release
 
+# Hotfix flow for X.YY.Z patch releases (Z > 0).
+#
+# create:
+#   - Branches hotfix/X.YY.Z from the highest existing vX.YY.* tag (1.27.2 from
+#     v1.27.1, 1.27.1 from v1.27.0). The base IS the cumulative-fix anchor for
+#     the previous patch.
+#   - Auto-cherry-picks every fix:/chore: commit on origin/main that isn't
+#     already in the base, oldest-first. Patch-equivalents (already applied)
+#     are skipped via `git cherry`. feat:/refactor: are NEVER auto-included.
+#   - Conflicts fail the workflow with the offending SHA so the operator can
+#     resolve manually on the branch and re-run finalize with auto_cherry_pick=false.
+#   - Step summary lists every included SHA so the eventual vX.YY.Z tag
+#     self-documents what shipped.
+#
+# finalize:
+#   - install-smoke gate (cross-platform, parity with release.yml/release-sdk.yml)
+#   - Bundles SDK as both loose tree (sdk/dist/cli.js) and recoverable tarball
+#     (sdk-bundle/gsd-sdk.tgz) — parity with release-sdk.yml so a hotfix shipped
+#     during the @gsd-build-token outage carries the same payload shape.
+#   - Publishes to @latest, tags vX.YY.Z, re-points @next → vX.YY.Z, opens
+#     merge-back PR.
+
 on:
   workflow_dispatch:
     inputs:
@@ -14,6 +36,11 @@ on:
         description: 'Patch version (e.g., 1.27.1)'
         required: true
         type: string
+      auto_cherry_pick:
+        description: 'Auto-cherry-pick fix:/chore: commits from origin/main since base tag (create only)'
+        required: false
+        type: boolean
+        default: true
       dry_run:
         description: 'Dry run (skip npm publish, tagging, and push)'
         required: false
@@ -54,10 +81,13 @@ jobs:
           MAJOR_MINOR=$(echo "$VERSION" | cut -d. -f1-2)
           TARGET_TAG="v${VERSION}"
           BRANCH="hotfix/${VERSION}"
-          BASE_TAG=$(git tag -l "v${MAJOR_MINOR}.*" \
+          # Append TARGET_TAG to the candidate list, then sort -V, then walk the
-            | grep -E "^v[0-9]+\.[0-9]+\.[0-9]+$" \
+          # sorted list and print whatever immediately precedes TARGET_TAG. This
+          # is semver-correct for multi-digit patches (v1.27.10 > v1.27.9) where
+          # a plain `awk '$1 < target'` lexicographic compare would mis-order.
+          BASE_TAG=$( ( git tag -l "v${MAJOR_MINOR}.*" | grep -E "^v[0-9]+\.[0-9]+\.[0-9]+$"; echo "$TARGET_TAG" ) \
             | sort -V \
-            | awk -v target="$TARGET_TAG" '$1 < target { last=$1 } END { if (last != "") print last }')
+            | awk -v target="$TARGET_TAG" '$1 == target { print prev; exit } { prev = $1 }')
           if [ -z "$BASE_TAG" ]; then
             echo "::error::No prior stable tag found for ${MAJOR_MINOR}.x before $TARGET_TAG"
             exit 1
@@ -95,29 +125,160 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 
-      - name: Create hotfix branch
+      - name: Create hotfix branch from base tag and push (skeleton)
-        if: inputs.dry_run != 'true'
+        env:
+          BRANCH: ${{ needs.validate-version.outputs.branch }}
+          BASE_TAG: ${{ needs.validate-version.outputs.base_tag }}
+          DRY_RUN: ${{ inputs.dry_run }}
+        run: |
+          set -euo pipefail
+          git checkout -b "$BRANCH" "$BASE_TAG"
+          # Push the skeleton branch up-front so any subsequent cherry-pick
+          # conflict leaves a remote artefact the operator can fetch, resolve,
+          # and re-push. Skipped on dry-run — local checkout still exercises
+          # the same cherry-pick + bump flow so conflicts are caught.
+          if [ "$DRY_RUN" != "true" ]; then
+            git push -u origin "$BRANCH"
+          fi
+
+      - name: Cherry-pick fix/chore commits from origin/main since base tag
+        if: ${{ inputs.auto_cherry_pick }}
+        env:
+          BRANCH: ${{ needs.validate-version.outputs.branch }}
+          BASE_TAG: ${{ needs.validate-version.outputs.base_tag }}
+          DRY_RUN: ${{ inputs.dry_run }}
+        run: |
+          set -euo pipefail
+          git fetch origin main:refs/remotes/origin/main
+
+          # `git cherry $BASE_TAG origin/main` lists every commit on main not
+          # patch-equivalent in BASE_TAG. + means needs picking, - means
+          # already applied (skipped silently).
+          CANDIDATES=$(git cherry "$BASE_TAG" origin/main | awk '/^\+ / {print $2}')
+
+          if [ -z "$CANDIDATES" ]; then
+            echo "No commits on origin/main beyond $BASE_TAG."
+            echo "## Cherry-pick summary" >> "$GITHUB_STEP_SUMMARY"
+            echo "" >> "$GITHUB_STEP_SUMMARY"
+            echo "Base: \`$BASE_TAG\` — no commits to consider." >> "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+
+          # Re-order chronologically (oldest first) for predictable application.
+          ORDERED=$(git log --reverse --format='%H' "$BASE_TAG..origin/main" \
+            | grep -F -f <(echo "$CANDIDATES") || true)
+
+          INCLUDED=""
+          SKIPPED=""
+          while IFS= read -r SHA; do
+            [ -z "$SHA" ] && continue
+            SUBJECT=$(git log -1 --format='%s' "$SHA")
+            # fix: or chore:, optional scope, optional ! breaking marker
+            if echo "$SUBJECT" | grep -qE '^(fix|chore)(\([^)]+\))?!?: '; then
+              echo "→ cherry-picking $SHA  $SUBJECT"
+              if ! git cherry-pick -x "$SHA"; then
+                # Abort restores HEAD to the last successful pick. On real
+                # runs, push that state so the operator can fetch, resolve
+                # $SHA manually, and finalize with auto_cherry_pick=false.
+                git cherry-pick --abort || true
+                if [ "$DRY_RUN" != "true" ]; then
+                  git push --force-with-lease origin "$BRANCH" || git push origin "$BRANCH" || true
+                fi
+                {
+                  echo "## Cherry-pick conflict"
+                  echo ""
+                  echo "Failed at: \`${SHA}\` — \`${SUBJECT}\`"
+                  echo ""
+                  if [ "$DRY_RUN" = "true" ]; then
+                    echo "**Dry run:** branch was not pushed, so the picks below were discarded with the runner."
+                    if [ -n "$INCLUDED" ]; then
+                      echo ""
+                      echo "Already-applied picks (lost — must be re-applied before resolving \`${SHA}\`):"
+                      echo ""
+                      echo "$INCLUDED"
+                    fi
+                    echo ""
+                    echo "**To resolve:** re-run \`create\` with \`auto_cherry_pick=true\` (real, not dry-run) to materialize the partial branch on origin, then resolve \`${SHA}\` manually. Re-running with \`auto_cherry_pick=false\` would recreate the branch from \`${BASE_TAG}\` and lose every pick listed above."
+                  else
+                    echo "Branch \`${BRANCH}\` was pushed with picks applied up to (but not including) the conflicting commit."
+                    echo ""
+                    echo "**To resolve:** \`git fetch origin && git checkout ${BRANCH} && git cherry-pick -x ${SHA}\`, fix the conflict, push, then re-run \`finalize\` with \`auto_cherry_pick=false\`."
+                  fi
+                } >> "$GITHUB_STEP_SUMMARY"
+                echo "::error::Cherry-pick of $SHA failed. See summary."
+                exit 1
+              fi
+              INCLUDED="${INCLUDED}- \`${SHA}\` ${SUBJECT}"$'\n'
+            else
+              echo "  skip $SHA  $SUBJECT  (not fix/chore)"
+              SKIPPED="${SKIPPED}- \`${SHA}\` ${SUBJECT}"$'\n'
+            fi
+          done <<< "$ORDERED"
+
+          {
+            echo "## Cherry-pick summary"
+            echo ""
+            echo "Base: \`$BASE_TAG\`"
+            echo ""
+            if [ -n "$INCLUDED" ]; then
+              echo "### Included (fix/chore)"
+              echo ""
+              echo "$INCLUDED"
+            else
+              echo "_No fix/chore commits to include._"
+              echo ""
+            fi
+            if [ -n "$SKIPPED" ]; then
+              echo "### Skipped (feat/refactor/etc — not auto-included)"
+              echo ""
+              echo "$SKIPPED"
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Bump version and push
         env:
           BRANCH: ${{ needs.validate-version.outputs.branch }}
           BASE_TAG: ${{ needs.validate-version.outputs.base_tag }}
           VERSION: ${{ inputs.version }}
+          DRY_RUN: ${{ inputs.dry_run }}
         run: |
-          git checkout -b "$BRANCH" "$BASE_TAG"
+          set -euo pipefail
-          # Bump version in package.json
           npm version "$VERSION" --no-git-tag-version
           git add package.json package-lock.json
+          # Keep sdk/package.json in lockstep (parity with release-sdk.yml).
+          if [ -f sdk/package.json ]; then
+            (cd sdk && npm version "$VERSION" --no-git-tag-version)
+            git add sdk/package.json
+            [ -f sdk/package-lock.json ] && git add sdk/package-lock.json
+          fi
           git commit -m "chore: bump version to $VERSION for hotfix"
-          git push origin "$BRANCH"
+          if [ "$DRY_RUN" != "true" ]; then
-          echo "## Hotfix branch created" >> "$GITHUB_STEP_SUMMARY"
+            git push origin "$BRANCH"
-          echo "- Branch: \`$BRANCH\`" >> "$GITHUB_STEP_SUMMARY"
+          else
-          echo "- Based on: \`$BASE_TAG\`" >> "$GITHUB_STEP_SUMMARY"
+            echo "DRY RUN — branch not pushed. Local checkout exercised the cherry-pick and bump flow."
-          echo "- Apply your fix, push, then run this workflow again with \`finalize\`" >> "$GITHUB_STEP_SUMMARY"
+          fi
+          {
+            echo "## Hotfix branch created"
+            echo ""
+            echo "- Branch: \`$BRANCH\`"
+            echo "- Based on: \`$BASE_TAG\`"
+            echo "- Apply additional manual fixes if needed, then run \`finalize\`."
+          } >> "$GITHUB_STEP_SUMMARY"
 
-  finalize:
+  install-smoke:
     needs: validate-version
     if: inputs.action == 'finalize'
+    permissions:
+      contents: read
+    uses: ./.github/workflows/install-smoke.yml
+    with:
+      ref: ${{ needs.validate-version.outputs.branch }}
+
+  finalize:
+    needs: [validate-version, install-smoke]
+    if: inputs.action == 'finalize'
     runs-on: ubuntu-latest
-    timeout-minutes: 10
+    timeout-minutes: 15
     permissions:
       contents: write
       pull-requests: write
@@ -140,31 +301,83 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 
+      - name: Detect prior publish (reconciliation mode)
+        id: prior_publish
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          EXISTING=$(npm view get-shit-done-cc@"$VERSION" version 2>/dev/null || true)
+          if [ -n "$EXISTING" ]; then
+            echo "::warning::get-shit-done-cc@${VERSION} is already on the registry — entering reconciliation mode (skip publish, continue with tag/release/PR/dist-tag)."
+            echo "skip_publish=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip_publish=false" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Install and test
         run: |
           npm ci
           npm run test:coverage
 
-      - name: Create PR to merge hotfix back to main
+      - name: Build SDK dist for tarball
-        if: ${{ !inputs.dry_run }}
+        run: npm run build:sdk
+
+      - name: Verify CC tarball ships sdk/dist/cli.js (bug #2647 guard)
+        run: bash scripts/verify-tarball-sdk-dist.sh
+
+      - name: Pack SDK as tarball and bundle into CC source tree
         env:
-          GH_TOKEN: ${{ github.token }}
-          BRANCH: ${{ needs.validate-version.outputs.branch }}
           VERSION: ${{ inputs.version }}
         run: |
-          EXISTING_PR=$(gh pr list --base main --head "$BRANCH" --state open --json number --jq '.[0].number')
+          set -e
-          if [ -n "$EXISTING_PR" ]; then
+          cd sdk
-            echo "PR #$EXISTING_PR already exists; updating"
+          npm pack
-            gh pr edit "$EXISTING_PR" \
+          TARBALL="gsd-build-sdk-${VERSION}.tgz"
-              --title "chore: merge hotfix v${VERSION} back to main" \
+          if [ ! -f "$TARBALL" ]; then
-              --body "Merge hotfix changes back to main after v${VERSION} release."
+            echo "::error::Expected $TARBALL but npm pack did not produce it."
-          else
+            ls -la
-            gh pr create \
+            exit 1
-              --base main \
-              --head "$BRANCH" \
-              --title "chore: merge hotfix v${VERSION} back to main" \
-              --body "Merge hotfix changes back to main after v${VERSION} release."
           fi
+          mkdir -p ../sdk-bundle
+          mv "$TARBALL" ../sdk-bundle/gsd-sdk.tgz
+          cd ..
+          ls -la sdk-bundle/
+
+      - name: Add sdk-bundle to CC files whitelist (in-tree, not committed)
+        run: |
+          node <<'NODE'
+          const fs = require('fs');
+          const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+          if (!Array.isArray(pkg.files)) {
+            console.error('::error::package.json files is not an array');
+            process.exit(1);
+          }
+          if (!pkg.files.includes('sdk-bundle')) {
+            pkg.files.push('sdk-bundle');
+            fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
+            console.log('Added sdk-bundle/ to package.json files whitelist');
+          }
+          NODE
+
+      - name: Verify CC tarball will contain sdk-bundle/gsd-sdk.tgz
+        run: |
+          set -e
+          TARBALL=$(npm pack --ignore-scripts 2>/dev/null | tail -1)
+          if [ -z "$TARBALL" ] || [ ! -f "$TARBALL" ]; then
+            echo "::error::npm pack produced no tarball"
+            exit 1
+          fi
+          if ! tar -tzf "$TARBALL" | grep -q "package/sdk-bundle/gsd-sdk.tgz"; then
+            echo "::error::CC tarball is missing package/sdk-bundle/gsd-sdk.tgz"
+            exit 1
+          fi
+          echo "✅ CC tarball contains sdk-bundle/gsd-sdk.tgz"
+          rm -f "$TARBALL"
+
+      - name: Dry-run publish validation
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --dry-run --tag latest
 
       - name: Tag and push
         if: ${{ !inputs.dry_run }}
@@ -185,55 +398,98 @@ jobs:
           fi
 
       - name: Publish to npm (latest)
-        if: ${{ !inputs.dry_run }}
+        if: ${{ !inputs.dry_run && steps.prior_publish.outputs.skip_publish != 'true' }}
-        run: npm publish --provenance --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --provenance --access public --tag latest
 
-      - name: Create GitHub Release
+      - name: Re-point next dist-tag at this hotfix
+        if: ${{ !inputs.dry_run }}
+        env:
+          VERSION: ${{ inputs.version }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          npm dist-tag add "get-shit-done-cc@${VERSION}" next
+          echo "✅ next dist-tag re-pointed to v${VERSION} (matches latest)"
+
+      - name: Create GitHub Release (idempotent)
         if: ${{ !inputs.dry_run }}
         env:
           GH_TOKEN: ${{ github.token }}
           VERSION: ${{ inputs.version }}
         run: |
-          gh release create "v${VERSION}" \
+          if gh release view "v${VERSION}" >/dev/null 2>&1; then
-            --title "v${VERSION} (hotfix)" \
+            echo "GitHub Release v${VERSION} already exists; ensuring --latest flag is set"
-            --generate-notes
+            gh release edit "v${VERSION}" --latest || true
+          else
+            gh release create "v${VERSION}" \
+              --title "v${VERSION} (hotfix)" \
+              --generate-notes \
+              --latest
+          fi
 
-      - name: Clean up next dist-tag
+      - name: Create PR to merge hotfix back to main
         if: ${{ !inputs.dry_run }}
         env:
+          GH_TOKEN: ${{ github.token }}
+          BRANCH: ${{ needs.validate-version.outputs.branch }}
           VERSION: ${{ inputs.version }}
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
-          # Point next to the stable release so @next never returns something
+          EXISTING_PR=$(gh pr list --base main --head "$BRANCH" --state open --json number --jq '.[0].number')
-          # older than @latest. This prevents stale pre-release installs.
+          if [ -n "$EXISTING_PR" ]; then
-          npm dist-tag add "get-shit-done-cc@${VERSION}" next 2>/dev/null || true
+            gh pr edit "$EXISTING_PR" \
-          echo "✓ next dist-tag updated to v${VERSION}"
+              --title "chore: merge hotfix v${VERSION} back to main" \
+              --body "Merge hotfix changes back to main after v${VERSION} release."
+          else
+            gh pr create \
+              --base main \
+              --head "$BRANCH" \
+              --title "chore: merge hotfix v${VERSION} back to main" \
+              --body "Merge hotfix changes back to main after v${VERSION} release."
+          fi
 
-      - name: Verify publish
+      - name: Verify publish landed on registry
         if: ${{ !inputs.dry_run }}
         env:
           VERSION: ${{ inputs.version }}
         run: |
-          sleep 10
+          PUBLISHED="NOT_FOUND"
-          PUBLISHED=$(npm view get-shit-done-cc@"$VERSION" version 2>/dev/null || echo "NOT_FOUND")
+          for delay in 5 10 20 30 45; do
+            PUBLISHED=$(npm view get-shit-done-cc@"$VERSION" version 2>/dev/null || echo "NOT_FOUND")
+            if [ "$PUBLISHED" = "$VERSION" ]; then
+              break
+            fi
+            echo "Waiting ${delay}s for registry to catch up (saw: $PUBLISHED)..."
+            sleep "$delay"
+          done
           if [ "$PUBLISHED" != "$VERSION" ]; then
-            echo "::error::Published version verification failed. Expected $VERSION, got $PUBLISHED"
+            echo "::error::Version $VERSION did not appear on the registry within timeout"
             exit 1
           fi
-          echo "✓ Verified: get-shit-done-cc@$VERSION is live on npm"
+          LATEST_VER=$(npm view get-shit-done-cc dist-tags.latest 2>/dev/null || echo "NOT_FOUND")
+          if [ "$LATEST_VER" != "$VERSION" ]; then
+            echo "::error::dist-tag 'latest' resolves to '$LATEST_VER', expected '$VERSION'"
+            exit 1
+          fi
+          echo "✓ Verified: get-shit-done-cc@$VERSION is live on @latest"
 
       - name: Summary
         env:
           VERSION: ${{ inputs.version }}
+          BASE_TAG: ${{ needs.validate-version.outputs.base_tag }}
           DRY_RUN: ${{ inputs.dry_run }}
         run: |
-          echo "## Hotfix v${VERSION}" >> "$GITHUB_STEP_SUMMARY"
+          {
-          if [ "$DRY_RUN" = "true" ]; then
+            echo "## Hotfix v${VERSION}"
-            echo "**DRY RUN** — npm publish, tagging, and push skipped" >> "$GITHUB_STEP_SUMMARY"
+            echo ""
-          else
+            echo "- Base (cumulative-fix anchor): \`${BASE_TAG}\`"
-            echo "- Published to npm as \`latest\`" >> "$GITHUB_STEP_SUMMARY"
+            if [ "$DRY_RUN" = "true" ]; then
-            echo "- Tagged \`v${VERSION}\`" >> "$GITHUB_STEP_SUMMARY"
+              echo "- **DRY RUN** — npm publish, tagging, and push skipped"
-            echo "- PR created to merge back to main" >> "$GITHUB_STEP_SUMMARY"
+            else
-          fi
+              echo "- Published to npm as \`latest\`"
+              echo "- \`next\` dist-tag re-pointed to v${VERSION}"
+              echo "- Tagged \`v${VERSION}\` (anchor for the next hotfix's cherry-pick base)"
+              echo "- SDK bundled at \`sdk-bundle/gsd-sdk.tgz\` inside CC tarball"
+              echo "- Merge-back PR opened against main"
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/release-sdk.yml

@@ -0,0 +1,790 @@
+# Release SDK Bundle
+#
+# Stopgap workflow_dispatch publish path: builds get-shit-done-cc with the
+# compiled SDK and the SDK .tgz bundled inside the CC tarball, then
+# publishes the CC package to ONE chosen dist-tag (dev | next | latest)
+# per run.
+#
+# Why this exists: @gsd-build/sdk publishes from canary.yml and release.yml
+# fail because the @gsd-build npm token is currently unavailable. CC users
+# do not consume @gsd-build/sdk directly — bin/gsd-sdk.js resolves
+# sdk/dist/cli.js from inside the installed CC package, so the bundled
+# copy is sufficient for full functionality. This workflow ships CC alone
+# (no separate @gsd-build/sdk publish attempt) and additionally bakes a
+# bundled gsd-sdk-<version>.tgz at sdk-bundle/gsd-sdk.tgz inside the CC
+# tarball as a recoverable npm-installable artifact.
+#
+# Existing canary.yml and release.yml are intentionally untouched. They
+# remain the canonical two-package publish path; restore them to primary
+# use once @gsd-build/sdk ownership is recovered.
+#
+# Tracking issues: #2925 (initial workflow), #2929 (CI-gate parity with release.yml)
+
+name: Release SDK Bundle
+
+on:
+  workflow_dispatch:
+    inputs:
+      action:
+        description: 'publish = normal dev/next/latest publish; hotfix = create hotfix/X.YY.Z branch from latest vX.YY.* tag, cherry-pick fix:/chore: from main, publish to @latest'
+        required: true
+        type: choice
+        default: publish
+        options:
+          - publish
+          - hotfix
+      tag:
+        description: 'npm dist-tag (publish action only; hotfix forces latest)'
+        required: false
+        type: choice
+        default: latest
+        options:
+          - dev
+          - next
+          - latest
+      version:
+        description: 'Version. publish: explicit (e.g. 1.50.0-dev.3) or empty to derive. hotfix: REQUIRED patch (e.g. 1.27.1, Z>0).'
+        required: false
+        type: string
+      ref:
+        description: 'Branch or ref to build from. Ignored for hotfix (workflow uses hotfix/X.YY.Z).'
+        required: false
+        type: string
+      auto_cherry_pick:
+        description: 'Hotfix only: auto-cherry-pick fix:/chore: commits from origin/main since base tag.'
+        required: false
+        type: boolean
+        default: true
+      dry_run:
+        description: 'Dry run (skip npm publish, git tag, and push). Hotfix branch creation/push also skipped.'
+        required: false
+        type: boolean
+        default: false
+
+# Per stream (dist-tag for publish, version for hotfix) — no concurrent publishes for the same stream.
+concurrency:
+  group: release-sdk-${{ inputs.action == 'hotfix' && format('hotfix-{0}', inputs.version) || inputs.tag }}
+  cancel-in-progress: false
+
+env:
+  NODE_VERSION: 24
+
+jobs:
+  # Resolves the effective git ref for this run.
+  #
+  # action=publish  → outputs inputs.ref verbatim (may be empty = workflow ref)
+  # action=hotfix   → branches hotfix/X.YY.Z from highest existing vX.YY.* tag,
+  #                   auto-cherry-picks fix:/chore: from origin/main, pushes,
+  #                   and outputs the new branch as ref. Idempotent: if branch
+  #                   already exists (operator pre-prepared it via hotfix.yml),
+  #                   we just check it out and re-run the cherry-pick step
+  #                   no-ops since `git cherry` will report nothing new.
+  prepare:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    outputs:
+      ref: ${{ steps.out.outputs.ref }}
+      base_tag: ${{ steps.hotfix.outputs.base_tag }}
+    steps:
+      - name: Validate hotfix inputs
+        if: inputs.action == 'hotfix'
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          if [ -z "$VERSION" ]; then
+            echo "::error::action=hotfix requires the 'version' input (e.g. 1.27.1)"
+            exit 1
+          fi
+          if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[1-9][0-9]*$'; then
+            echo "::error::Hotfix version must match X.YY.Z with Z>0 (got: $VERSION)"
+            exit 1
+          fi
+
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        if: inputs.action == 'hotfix'
+        with:
+          fetch-depth: 0
+
+      - name: Configure git identity
+        if: inputs.action == 'hotfix'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Prepare hotfix branch
+        id: hotfix
+        if: inputs.action == 'hotfix'
+        env:
+          VERSION: ${{ inputs.version }}
+          AUTO_CHERRY_PICK: ${{ inputs.auto_cherry_pick }}
+          DRY_RUN: ${{ inputs.dry_run }}
+        run: |
+          set -euo pipefail
+          # Stash the shipped-paths classifier from the dispatched ref's
+          # working tree BEFORE `git checkout -b ... "$BASE_TAG"` below
+          # overwrites it. Base tags predating #2980 don't have the
+          # classifier in their tree, so the loop must reference a
+          # location that survives the working-tree swap. Bug #2983.
+          CLASSIFIER_SRC="scripts/diff-touches-shipped-paths.cjs"
+          if [ ! -f "$CLASSIFIER_SRC" ]; then
+            echo "::error::shipped-paths classifier not found at $CLASSIFIER_SRC in dispatched ref — refusing to run"
+            exit 1
+          fi
+          CLASSIFIER="${RUNNER_TEMP}/diff-touches-shipped-paths.cjs"
+          cp "$CLASSIFIER_SRC" "$CLASSIFIER"
+          if [ ! -f "$CLASSIFIER" ]; then
+            echo "::error::failed to stage classifier at $CLASSIFIER"
+            exit 1
+          fi
+
+          MAJOR_MINOR=$(echo "$VERSION" | cut -d. -f1-2)
+          TARGET_TAG="v${VERSION}"
+          BRANCH="hotfix/${VERSION}"
+          # Semver-correct selection: append TARGET_TAG, sort -V, take preceding entry.
+          # Plain lexicographic compare mis-orders multi-digit patches (v1.27.10 vs v1.27.9).
+          BASE_TAG=$( ( git tag -l "v${MAJOR_MINOR}.*" | grep -E "^v[0-9]+\.[0-9]+\.[0-9]+$"; echo "$TARGET_TAG" ) \
+            | sort -V \
+            | awk -v target="$TARGET_TAG" '$1 == target { print prev; exit } { prev = $1 }')
+          if [ -z "$BASE_TAG" ]; then
+            echo "::error::No prior stable tag found for ${MAJOR_MINOR}.x before $TARGET_TAG"
+            exit 1
+          fi
+          echo "base_tag=$BASE_TAG" >> "$GITHUB_OUTPUT"
+          echo "branch=$BRANCH" >> "$GITHUB_OUTPUT"
+
+          # Idempotent branch creation — operator may have pre-prepared via hotfix.yml.
+          git fetch origin main:refs/remotes/origin/main
+          if git ls-remote --exit-code origin "refs/heads/$BRANCH" >/dev/null 2>&1; then
+            echo "Branch $BRANCH already exists on origin; checking out"
+            git fetch origin "$BRANCH"
+            git checkout "$BRANCH"
+            BRANCH_PRE_EXISTED=1
+          else
+            git checkout -b "$BRANCH" "$BASE_TAG"
+            BRANCH_PRE_EXISTED=0
+            # Push the skeleton up-front (real runs only) so cherry-pick conflicts
+            # leave a remote artefact the operator can resolve. Dry-run keeps
+            # everything local — no orphan branch created on origin.
+            if [ "$DRY_RUN" != "true" ]; then
+              git push -u origin "$BRANCH"
+            fi
+          fi
+
+          if [ "$AUTO_CHERRY_PICK" = "true" ]; then
+            CANDIDATES=$(git cherry HEAD origin/main | awk '/^\+ / {print $2}')
+            if [ -n "$CANDIDATES" ]; then
+              ORDERED=$(git log --reverse --format='%H' "${BASE_TAG}..origin/main" \
+                | grep -F -f <(echo "$CANDIDATES") || true)
+              INCLUDED=""
+              # POLICY_SKIPPED — commits intentionally not picked because they
+              # don't match the fix/chore filter (feat/refactor/docs/etc).
+              # CONFLICT_SKIPPED — fix/chore commits whose cherry-pick failed
+              # and were skipped per the full-automation policy (#2968).
+              # NON_SHIPPED_SKIPPED — fix/chore commits whose diff doesn't
+              # touch any path in the npm tarball's `files` whitelist
+              # (CI / test / docs / planning-only changes). They can't
+              # affect the published package's behavior, so picking them
+              # into a hotfix is meaningless — and picking workflow-file
+              # changes specifically would also fail the push step because
+              # the default GITHUB_TOKEN lacks the `workflow` scope. The
+              # shipped-paths filter is the precise root cause: bug #2980.
+              # Operators reviewing the run summary need these distinct so
+              # the manual-review queue (CONFLICT_SKIPPED) isn't buried in
+              # the noise from the other two buckets.
+              POLICY_SKIPPED=""
+              CONFLICT_SKIPPED=""
+              NON_SHIPPED_SKIPPED=""
+              while IFS= read -r SHA; do
+                [ -z "$SHA" ] && continue
+                SUBJECT=$(git log -1 --format='%s' "$SHA")
+                if echo "$SUBJECT" | grep -qE '^(fix|chore)(\([^)]+\))?!?: '; then
+                  # Merge commits with fix:/chore: titles can't be cherry-picked
+                  # without `-m <parent>` and we can't pick the parent
+                  # automatically. They fail BEFORE entering cherry-pick state
+                  # (no CHERRY_PICK_HEAD), so an unconditional `--skip` would
+                  # then fail and brick the loop. Skip them upfront with a
+                  # distinct reason. Bug #2968 / CodeRabbit on PR #2970.
+                  PARENT_COUNT=$(git rev-list --parents -n 1 "$SHA" | awk '{print NF - 1}')
+                  if [ "$PARENT_COUNT" -gt 1 ]; then
+                    REASON="merge commit — manual -m parent selection required"
+                    echo "↷ skipping $SHA — $REASON"
+                    CONFLICT_SKIPPED="${CONFLICT_SKIPPED}- \`${SHA}\` ${SUBJECT} ($REASON)"$'\n'
+                    continue
+                  fi
+                  # Pre-pick guard: a hotfix release can only be affected
+                  # by commits whose diff intersects the npm tarball's
+                  # shipped paths (package.json `files` whitelist plus
+                  # package.json itself, which `npm pack` always
+                  # includes). Commits that touch only CI workflows,
+                  # tests, docs, or planning artifacts cannot change what
+                  # ships, so picking them into a hotfix is meaningless.
+                  # As a side benefit, this excludes
+                  # `.github/workflows/*` changes whose push would
+                  # otherwise be rejected by GitHub because the default
+                  # GITHUB_TOKEN lacks the `workflow` scope. The filter
+                  # is implemented in
+                  # scripts/diff-touches-shipped-paths.cjs rather than
+                  # inline so the rules (read package.json `files`,
+                  # treat entries as file-OR-directory prefix, the
+                  # `package.json`-always-shipped rule) are
+                  # unit-testable. Bug #2980.
+                  #
+                  # Use $CLASSIFIER (staged at workflow-start, before
+                  # `git checkout -b ... "$BASE_TAG"` swapped the working
+                  # tree) rather than `scripts/...` directly — base tags
+                  # older than #2980 don't have the classifier in their
+                  # tree. Capture the exit code via PIPESTATUS and
+                  # dispatch on it: 0 = shipped, 1 = not shipped, 2+ =
+                  # classifier error → fail-fast (don't silently treat
+                  # tooling errors as informational skips). Bug #2983.
+                  #
+                  # PIPESTATUS capture must happen IMMEDIATELY after the
+                  # pipeline — the previous form (`pipeline || true; RC=
+                  # ${PIPESTATUS[1]}`) had a subtle bug: when the
+                  # pipeline fails (exit 1 or 2 — exactly the cases we
+                  # care about), `|| true` runs `true` as a one-command
+                  # pipeline, overwriting PIPESTATUS to (0). The fix is
+                  # to wrap the pipeline in `set +e`/`set -e` and snapshot
+                  # PIPESTATUS into a local array on the very next line.
+                  # CodeRabbit on PR #2984.
+                  set +e
+                  git diff-tree --no-commit-id --name-only -r "$SHA" \
+                    | node "$CLASSIFIER"
+                  PIPE_RC=("${PIPESTATUS[@]}")
+                  set -e
+                  DIFFTREE_RC="${PIPE_RC[0]}"
+                  CLASSIFIER_RC="${PIPE_RC[1]}"
+                  if [ "$DIFFTREE_RC" -ne 0 ]; then
+                    echo "::error::git diff-tree failed for $SHA (exit $DIFFTREE_RC) — refusing to classify on incomplete input."
+                    exit "$DIFFTREE_RC"
+                  fi
+                  case "$CLASSIFIER_RC" in
+                    0) ;;
+                    1)
+                      REASON="touches no shipped paths (CI / test / docs / planning only)"
+                      echo "↷ skipping $SHA — $REASON"
+                      NON_SHIPPED_SKIPPED="${NON_SHIPPED_SKIPPED}- \`${SHA}\` ${SUBJECT}"$'\n'
+                      continue
+                      ;;
+                    *)
+                      echo "::error::shipped-paths classifier failed for $SHA (exit $CLASSIFIER_RC). Refusing to silently skip — bug #2983."
+                      exit "$CLASSIFIER_RC"
+                      ;;
+                  esac
+                  echo "→ cherry-picking $SHA  $SUBJECT"
+                  # Pin merge.conflictStyle=merge on the cherry-pick so the
+                  # awk classifier below sees deterministic marker shapes —
+                  # diff3/zdiff3 would inject `||||||| ancestor` lines into
+                  # the HEAD section and cause context-missing conflicts to
+                  # misclassify as real. Bug #2966.
+                  if ! git -c merge.conflictStyle=merge cherry-pick -x --allow-empty --keep-redundant-commits "$SHA"; then
+                    # Full automation policy (bug #2968): any conflict the
+                    # cherry-pick can't auto-resolve is skipped, not aborted.
+                    # The hotfix run completes with whatever applies cleanly;
+                    # the CONFLICT_SKIPPED list below becomes the operator's
+                    # review queue (see "Cherry-pick summary" in the run
+                    # summary).
+                    #
+                    # Classify the conflict for the skip reason (operator-
+                    # facing diagnostic — doesn't change control flow):
+                    #   - context absent at base: HEAD section in every
+                    #     conflict marker is empty (the picked commit modifies
+                    #     code that doesn't exist at the base). Bug #2966.
+                    #   - merge conflict: HEAD section has content (both base
+                    #     and patch want different content for the same
+                    #     region). Typical when the base tag was cut from a
+                    #     branch that has diverged from main. Bug #2968.
+                    UNMERGED=$(git diff --name-only --diff-filter=U)
+                    REASON="merge conflict — manual review"
+                    if [ -n "$UNMERGED" ]; then
+                      ALL_EMPTY_HEAD=true
+                      while IFS= read -r CONFLICTED; do
+                        [ -z "$CONFLICTED" ] && continue
+                        # Guard the classifier against degenerate cases that
+                        # would otherwise skew toward "context absent" (the
+                        # auto-skip path) when they're actually unsafe to skip:
+                        #   - file missing or unreadable: don't pretend the
+                        #     conflict is benign; treat as real.
+                        #   - file listed as unmerged but no conflict markers
+                        #     present: anomalous git state; treat as real so
+                        #     the pick goes to the manual-review queue.
+                        # CodeRabbit on PR #2970.
+                        if [ ! -r "$CONFLICTED" ] || ! grep -q '^<<<<<<< ' "$CONFLICTED" 2>/dev/null; then
+                          ALL_EMPTY_HEAD=false
+                          break
+                        fi
+                        REAL=$(awk '
+                          /^<<<<<<< / { in_head=1; head=""; next }
+                          /^=======$/ && in_head { in_head=0; next }
+                          /^>>>>>>> / {
+                            if (head ~ /[^[:space:]]/) { print "real"; exit }
+                            head=""
+                            next
+                          }
+                          in_head { head = head $0 "\n" }
+                        ' "$CONFLICTED" 2>/dev/null || echo "real")
+                        if [ "$REAL" = "real" ]; then
+                          ALL_EMPTY_HEAD=false
+                          break
+                        fi
+                      done <<< "$UNMERGED"
+                      if [ "$ALL_EMPTY_HEAD" = "true" ]; then
+                        REASON="context absent at base"
+                      fi
+                    fi
+
+                    echo "↷ skipping $SHA — $REASON"
+                    # Guard `--skip`: cherry-pick can fail before entering the
+                    # conflict state (e.g. unreadable commit, empty-without-
+                    # --allow-empty edge cases the flag misses). Calling
+                    # `--skip` outside an in-progress cherry-pick exits non-
+                    # zero and would brick the loop. CodeRabbit on PR #2970.
+                    if git rev-parse -q --verify CHERRY_PICK_HEAD >/dev/null 2>&1; then
+                      git cherry-pick --skip
+                    fi
+                    CONFLICT_SKIPPED="${CONFLICT_SKIPPED}- \`${SHA}\` ${SUBJECT} ($REASON)"$'\n'
+                    continue
+                  fi
+                  INCLUDED="${INCLUDED}- \`${SHA}\` ${SUBJECT}"$'\n'
+                else
+                  POLICY_SKIPPED="${POLICY_SKIPPED}- \`${SHA}\` ${SUBJECT}"$'\n'
+                fi
+              done <<< "$ORDERED"
+              {
+                echo "## Cherry-pick summary"
+                echo ""
+                echo "Base: \`$BASE_TAG\` → Branch: \`$BRANCH\`$([ "$DRY_RUN" = "true" ] && echo " (DRY RUN — local only)")"
+                echo ""
+                if [ -n "$INCLUDED" ]; then
+                  echo "### Included (fix/chore)"
+                  echo ""
+                  echo "$INCLUDED"
+                else
+                  echo "_No fix/chore commits to include._"
+                fi
+                if [ -n "$NON_SHIPPED_SKIPPED" ]; then
+                  echo "### Skipped — touches no shipped paths (informational)"
+                  echo ""
+                  echo "These fix/chore commits don't touch any path in the npm tarball's \`files\` whitelist (or \`package.json\`), so they cannot change the published package's behavior. CI / test / docs / planning-only changes belong on \`main\`, not in a hotfix. No action needed."
+                  echo ""
+                  echo "$NON_SHIPPED_SKIPPED"
+                fi
+                if [ -n "$CONFLICT_SKIPPED" ]; then
+                  echo "### Skipped — cherry-pick conflict (manual review)"
+                  echo ""
+                  echo "$CONFLICT_SKIPPED"
+                fi
+                if [ -n "$POLICY_SKIPPED" ]; then
+                  echo "### Not auto-included (feat/refactor/docs/etc)"
+                  echo ""
+                  echo "$POLICY_SKIPPED"
+                fi
+              } >> "$GITHUB_STEP_SUMMARY"
+            fi
+          fi
+
+          # Bump version on the branch (committed) so downstream install-smoke +
+          # release jobs build the correct version. The release job's own in-tree
+          # bump becomes a no-op when the file already has the right version.
+          CURRENT=$(node -p "require('./package.json').version")
+          if [ "$CURRENT" != "$VERSION" ]; then
+            npm version "$VERSION" --no-git-tag-version
+            git add package.json package-lock.json
+            if [ -f sdk/package.json ]; then
+              (cd sdk && npm version "$VERSION" --no-git-tag-version)
+              git add sdk/package.json
+              [ -f sdk/package-lock.json ] && git add sdk/package-lock.json
+            fi
+            git commit -m "chore: bump version to $VERSION for hotfix"
+          fi
+          if [ "$DRY_RUN" != "true" ]; then
+            git push origin "$BRANCH"
+          else
+            echo "DRY RUN — cherry-picks applied locally; branch not pushed. Downstream install-smoke will run against \`$BASE_TAG\` (the cherry-pick verification above is the dry-run signal)."
+          fi
+
+      - name: Determine effective ref
+        id: out
+        env:
+          ACTION: ${{ inputs.action }}
+          INPUT_REF: ${{ inputs.ref }}
+          DRY_RUN: ${{ inputs.dry_run }}
+          BASE_TAG: ${{ steps.hotfix.outputs.base_tag }}
+          BRANCH: ${{ steps.hotfix.outputs.branch }}
+        run: |
+          if [ "$ACTION" = "hotfix" ]; then
+            if [ "$DRY_RUN" = "true" ]; then
+              echo "ref=$BASE_TAG" >> "$GITHUB_OUTPUT"
+            else
+              echo "ref=$BRANCH" >> "$GITHUB_OUTPUT"
+            fi
+          else
+            echo "ref=$INPUT_REF" >> "$GITHUB_OUTPUT"
+          fi
+
+  # Cross-platform install validation gate (parity with release.yml).
+  install-smoke:
+    needs: prepare
+    permissions:
+      contents: read
+    uses: ./.github/workflows/install-smoke.yml
+    with:
+      ref: ${{ needs.prepare.outputs.ref }}
+
+  release:
+    needs: [prepare, install-smoke]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: write  # tag + push + GitHub Release
+      id-token: write  # provenance
+      # The merge-back PR step (and the pull-request scope it required)
+      # was removed in #2983 — auto-cherry-pick hotfix flow only picks
+      # commits already on main, so there's nothing to merge back.
+    environment: npm-publish
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          fetch-depth: 0
+          ref: ${{ needs.prepare.outputs.ref }}
+
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f  # v6.3.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+
+      - name: Determine version
+        id: ver
+        env:
+          ACTION: ${{ inputs.action }}
+          INPUT_TAG: ${{ inputs.tag }}
+          INPUT_OVERRIDE: ${{ inputs.version }}
+        run: |
+          set -e
+          # Hotfix forces version=inputs.version and dist-tag=latest.
+          if [ "$ACTION" = "hotfix" ]; then
+            if [ -z "$INPUT_OVERRIDE" ]; then
+              echo "::error::action=hotfix requires the 'version' input"
+              exit 1
+            fi
+            VERSION="$INPUT_OVERRIDE"
+            EFFECTIVE_TAG="latest"
+            echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+            echo "tag=$EFFECTIVE_TAG" >> "$GITHUB_OUTPUT"
+            echo "→ Hotfix: will publish v${VERSION} to dist-tag '${EFFECTIVE_TAG}'"
+            exit 0
+          fi
+          RAW=$(node -p "require('./package.json').version")
+          BASE=$(echo "$RAW" | sed 's/-.*//')
+          if [ -n "$INPUT_OVERRIDE" ]; then
+            VERSION="$INPUT_OVERRIDE"
+          else
+            case "$INPUT_TAG" in
+              dev)
+                N=1
+                while git tag -l "v${BASE}-dev.${N}" | grep -q .; do
+                  N=$((N + 1))
+                done
+                VERSION="${BASE}-dev.${N}"
+                ;;
+              next)
+                N=1
+                while git tag -l "v${BASE}-rc.${N}" | grep -q .; do
+                  N=$((N + 1))
+                done
+                VERSION="${BASE}-rc.${N}"
+                ;;
+              latest)
+                VERSION="$BASE"
+                ;;
+              *)
+                echo "::error::Unknown tag '$INPUT_TAG' (expected dev|next|latest)"
+                exit 1
+                ;;
+            esac
+          fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=$INPUT_TAG" >> "$GITHUB_OUTPUT"
+          echo "→ Will publish v${VERSION} to dist-tag '${INPUT_TAG}'"
+
+      # Reconciliation mode: if version is already on npm (a prior run
+       # published successfully but a downstream step failed), don't hard-fail.
+       # Set a flag and skip the publish step below; tag/release/PR/dist-tag
+       # steps still execute so the rerun can finish reconciling state.
+      - name: Detect prior publish (reconciliation mode)
+        id: prior_publish
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+        run: |
+          EXISTING=$(npm view get-shit-done-cc@"$VERSION" version 2>/dev/null || true)
+          if [ -n "$EXISTING" ]; then
+            echo "::warning::get-shit-done-cc@${VERSION} is already on the registry — entering reconciliation mode (skip publish, continue with tag/release/PR/dist-tag)."
+            echo "skip_publish=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip_publish=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      # Tolerant tag-existence check (matches release.yml pattern). An
+      # operator re-running after a mid-flight publish-step failure should
+      # not be blocked just because the tag step succeeded last time. Only
+      # error if the existing tag points at a different commit than HEAD.
+      - name: Check git tag (skip if matches HEAD, error if mismatched)
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+        run: |
+          if git rev-parse -q --verify "refs/tags/v${VERSION}" >/dev/null; then
+            EXISTING_SHA=$(git rev-parse "refs/tags/v${VERSION}")
+            HEAD_SHA=$(git rev-parse HEAD)
+            if [ "$EXISTING_SHA" != "$HEAD_SHA" ]; then
+              echo "::error::git tag v${VERSION} already exists pointing at ${EXISTING_SHA}, but HEAD is ${HEAD_SHA}"
+              exit 1
+            fi
+            echo "::notice::tag v${VERSION} already exists at HEAD; tag step will skip"
+          fi
+
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump in-tree version (not committed)
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+        run: |
+          # --allow-same-version: prepare may have already committed this bump
+          # on the hotfix branch (release checks out BRANCH in real runs,
+          # BASE_TAG in dry-runs — only the latter has the older version).
+          npm version "$VERSION" --no-git-tag-version --allow-same-version
+          cd sdk && npm version "$VERSION" --no-git-tag-version --allow-same-version
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run full test suite with coverage (parity with release.yml)
+        run: npm run test:coverage
+
+      - name: Build SDK dist for tarball
+        run: npm run build:sdk
+
+      - name: Verify CC tarball ships sdk/dist/cli.js (bug #2647 guard)
+        run: bash scripts/verify-tarball-sdk-dist.sh
+
+      - name: Pack SDK as tarball and bundle into CC source tree
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+        run: |
+          set -e
+          cd sdk
+          npm pack
+          # npm pack emits gsd-build-sdk-<version>.tgz in the cwd
+          TARBALL="gsd-build-sdk-${VERSION}.tgz"
+          if [ ! -f "$TARBALL" ]; then
+            echo "::error::Expected $TARBALL but npm pack did not produce it. Listing sdk/:"
+            ls -la
+            exit 1
+          fi
+          mkdir -p ../sdk-bundle
+          mv "$TARBALL" ../sdk-bundle/gsd-sdk.tgz
+          cd ..
+          ls -la sdk-bundle/
+
+      - name: Add sdk-bundle to CC files whitelist (in-tree, not committed)
+        run: |
+          node <<'NODE'
+          const fs = require('fs');
+          const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+          if (!Array.isArray(pkg.files)) {
+            console.error('::error::package.json files is not an array');
+            process.exit(1);
+          }
+          if (!pkg.files.includes('sdk-bundle')) {
+            pkg.files.push('sdk-bundle');
+            fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
+            console.log('Added sdk-bundle/ to package.json files whitelist');
+          } else {
+            console.log('sdk-bundle/ already in files whitelist');
+          }
+          NODE
+
+      - name: Verify CC tarball will contain sdk-bundle/gsd-sdk.tgz
+        run: |
+          set -e
+          TARBALL=$(npm pack --ignore-scripts 2>/dev/null | tail -1)
+          if [ -z "$TARBALL" ] || [ ! -f "$TARBALL" ]; then
+            echo "::error::npm pack produced no tarball"
+            exit 1
+          fi
+          echo "Inspecting $TARBALL for sdk-bundle/gsd-sdk.tgz:"
+          if ! tar -tzf "$TARBALL" | grep -q "package/sdk-bundle/gsd-sdk.tgz"; then
+            echo "::error::CC tarball is missing package/sdk-bundle/gsd-sdk.tgz"
+            tar -tzf "$TARBALL" | grep -E "sdk-bundle|sdk/dist" | head -20
+            exit 1
+          fi
+          echo "✅ CC tarball contains sdk-bundle/gsd-sdk.tgz"
+          rm -f "$TARBALL"
+
+      - name: Dry-run publish validation
+        # Skip the rehearsal when the version is already on npm
+        # (reconciliation mode). `npm publish --dry-run` contacts the
+        # registry and fails with "You cannot publish over the
+        # previously published versions" if the version exists, even
+        # though no actual publish would be attempted. The real publish
+        # step (further down) is gated on the same condition; gate the
+        # rehearsal too so re-runs of an already-published hotfix don't
+        # fail here on a check that doesn't apply. Bug #2987.
+        if: ${{ steps.prior_publish.outputs.skip_publish != 'true' }}
+        env:
+          TAG: ${{ steps.ver.outputs.tag }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --dry-run --tag "$TAG"
+
+      - name: Tag and push
+        if: ${{ !inputs.dry_run }}
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+        run: |
+          if git rev-parse -q --verify "refs/tags/v${VERSION}" >/dev/null; then
+            echo "Tag v${VERSION} already exists at HEAD (per pre-flight check); skipping git tag step"
+          else
+            git tag "v${VERSION}"
+          fi
+          git push origin "v${VERSION}"
+
+      - name: Publish to npm (CC bundle, SDK included as both loose tree and .tgz)
+        if: ${{ !inputs.dry_run && steps.prior_publish.outputs.skip_publish != 'true' }}
+        env:
+          TAG: ${{ steps.ver.outputs.tag }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --provenance --access public --tag "$TAG"
+
+      # Keep `next` from going stale relative to `latest`. When publishing a
+      # stable release, also point `next` at it so users on `@next` don't
+      # get stuck on an older pre-release than what's now stable. Parity
+      # with release.yml#finalize "Clean up next dist-tag" step.
+      - name: Re-point next dist-tag at the new latest (only when tag=latest)
+        if: ${{ !inputs.dry_run && steps.ver.outputs.tag == 'latest' }}
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          npm dist-tag add "get-shit-done-cc@${VERSION}" next
+          echo "✅ next dist-tag re-pointed to v${VERSION} (matches latest)"
+
+      - name: Create GitHub Release (idempotent)
+        if: ${{ !inputs.dry_run }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.ver.outputs.version }}
+          TAG: ${{ steps.ver.outputs.tag }}
+        run: |
+          # Per-tag release flags:
+          #   dev, next → --prerelease (won't be highlighted as the latest release on the repo page)
+          #   latest    → --latest (becomes the highlighted release)
+          # Idempotent: if release already exists (rerun after a transient
+          # downstream failure), edit the latest flag instead of failing.
+          if gh release view "v${VERSION}" >/dev/null 2>&1; then
+            echo "GitHub Release v${VERSION} already exists; reconciling --latest flag"
+            if [ "$TAG" = "latest" ]; then
+              gh release edit "v${VERSION}" --latest || true
+            fi
+          elif [ "$TAG" = "latest" ]; then
+            gh release create "v${VERSION}" \
+              --title "v${VERSION}" \
+              --generate-notes \
+              --latest
+          else
+            gh release create "v${VERSION}" \
+              --title "v${VERSION}" \
+              --generate-notes \
+              --prerelease
+          fi
+          echo "✅ GitHub Release v${VERSION} ready"
+
+      # Merge-back PR step removed — bug #2983.
+      #
+      # The auto-cherry-pick hotfix flow only picks commits already on
+      # main (`git cherry HEAD origin/main` outputs unmerged commits;
+      # we filter to fix:/chore: from main). By construction every code
+      # commit on the hotfix branch is already on main. The only
+      # hotfix-branch-only commit is `chore: bump version to X.Y.Z for
+      # hotfix`, which would either no-op against main (already past
+      # X.Y.Z) or rewind main's in-progress version — strictly
+      # counterproductive in either case.
+      #
+      # The original merge-back step also failed in production with
+      # `GitHub Actions is not permitted to create or approve pull
+      # requests (createPullRequest)` (org policy), but even if the
+      # policy were lifted the PR would have nothing useful to merge.
+      # Run 25232968975 was the trigger for removal.
+
+      - name: Verify publish landed on registry
+        if: ${{ !inputs.dry_run }}
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+          TAG: ${{ steps.ver.outputs.tag }}
+        run: |
+          PUBLISHED="NOT_FOUND"
+          for delay in 5 10 20 30 45; do
+            PUBLISHED=$(npm view get-shit-done-cc@"$VERSION" version 2>/dev/null || echo "NOT_FOUND")
+            if [ "$PUBLISHED" = "$VERSION" ]; then
+              break
+            fi
+            echo "Waiting ${delay}s for registry to catch up (saw: $PUBLISHED)..."
+            sleep "$delay"
+          done
+          if [ "$PUBLISHED" != "$VERSION" ]; then
+            echo "::error::Version $VERSION did not appear on the registry within timeout"
+            exit 1
+          fi
+          TAG_VERSION=$(npm view get-shit-done-cc dist-tags."$TAG" 2>/dev/null || echo "NOT_FOUND")
+          if [ "$TAG_VERSION" != "$VERSION" ]; then
+            echo "::error::dist-tag '$TAG' resolves to '$TAG_VERSION', expected '$VERSION'"
+            exit 1
+          fi
+          echo "✅ get-shit-done-cc@${VERSION} live on dist-tag '${TAG}'"
+
+      - name: Summary
+        env:
+          ACTION: ${{ inputs.action }}
+          VERSION: ${{ steps.ver.outputs.version }}
+          TAG: ${{ steps.ver.outputs.tag }}
+          BASE_TAG: ${{ needs.prepare.outputs.base_tag }}
+          BRANCH: ${{ needs.prepare.outputs.ref }}
+          DRY_RUN: ${{ inputs.dry_run }}
+        run: |
+          {
+            if [ "$ACTION" = "hotfix" ]; then
+              echo "## Release SDK Bundle (hotfix): v${VERSION} → @${TAG}"
+              echo ""
+              echo "- Base (cumulative-fix anchor): \`${BASE_TAG}\`"
+              echo "- Branch: \`${BRANCH}\`"
+            else
+              echo "## Release SDK Bundle: v${VERSION} → @${TAG}"
+            fi
+            echo ""
+            if [ "$DRY_RUN" = "true" ]; then
+              echo "**DRY RUN** — npm publish, git tag, push, and GitHub Release were skipped."
+            else
+              echo "- Published \`get-shit-done-cc@${VERSION}\` to dist-tag \`${TAG}\`"
+              echo "- SDK bundled inside the CC tarball at:"
+              echo "  - \`sdk/dist/cli.js\` (loose tree, consumed by \`bin/gsd-sdk.js\` shim)"
+              echo "  - \`sdk-bundle/gsd-sdk.tgz\` (npm-installable artifact)"
+              echo "- Git tag \`v${VERSION}\` pushed"
+              echo "- GitHub Release \`v${VERSION}\` created"
+              if [ "$TAG" = "latest" ]; then
+                echo "- \`next\` dist-tag re-pointed at \`v${VERSION}\` (kept current with \`latest\`)"
+              fi
+              if [ "$ACTION" = "hotfix" ]; then
+                # Auto-cherry-pick hotfixes only pick commits already on
+                # main, so there's nothing to merge back. The merge-back
+                # PR step was removed in #2983; this line surfaces the
+                # explicit non-action so operators don't expect a PR
+                # that was never opened.
+                echo "- No merge-back PR (auto-picked commits are already on main)"
+              fi
+              echo "- Install: \`npm install -g get-shit-done-cc@${TAG}\`"
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/require-issue-link.yml

@@ -24,19 +24,20 @@ jobs:
             echo "found=false" >> "$GITHUB_OUTPUT"
           fi
 
-      - name: Comment and fail if no issue link
+      - name: Comment, close, and fail if no issue link
         if: steps.check.outputs.found == 'false'
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           # Uses GitHub API SDK — no shell string interpolation of untrusted input
           script: |
             const repoUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}`;
+            const prNumber = context.payload.pull_request.number;
             await github.rest.issues.createComment({
               owner: context.repo.owner,
               repo: context.repo.repo,
-              issue_number: context.payload.pull_request.number,
+              issue_number: prNumber,
               body: [
-                '## Missing issue link',
+                '## Missing issue link — PR auto-closed',
                 '',
                 'This PR does not reference an issue. **All PRs must link to an open issue** using a closing keyword in the PR body:',
                 '',
@@ -46,7 +47,13 @@ jobs:
                 '',
                 `If no issue exists for this change, [open one first](${repoUrl}/issues/new/choose), then update this PR body with the reference.`,
                 '',
-                'This PR will remain blocked until a valid `Closes #NNN`, `Fixes #NNN`, or `Resolves #NNN` line is present in the description.',
+                'To resume work after fixing the body: edit the PR description to add a valid `Closes #NNN`, `Fixes #NNN`, or `Resolves #NNN` line, then click **Reopen pull request**. The workflow will re-evaluate on reopen.',
               ].join('\n')
             });
-            core.setFailed('PR body must contain a closing issue reference (e.g. "Closes #123")');
+            await github.rest.pulls.update({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: prNumber,
+              state: 'closed',
+            });
+            core.setFailed('PR body must contain a closing issue reference (e.g. "Closes #123") — PR closed.');

.github/workflows/test.yml

@@ -88,6 +88,18 @@ jobs:
       - name: Build SDK dist (required by installer)
         run: npm run build:sdk
 
+      # Seam contract gate: keep manifest -> generated aliases -> registry/CJS adapters aligned.
+      # Run once per workflow on the primary Linux node to avoid redundant matrix cost.
+      - name: SDK seam coverage tests
+        if: matrix.os == 'ubuntu-latest' && matrix.node-version == 24
+        shell: bash
+        run: cd sdk && npx vitest run src/query/command-seam-coverage.test.ts
+
+      - name: SDK generated alias artifact drift check
+        if: matrix.os == 'ubuntu-latest' && matrix.node-version == 24
+        shell: bash
+        run: node sdk/scripts/check-command-aliases-fresh.mjs
+
       - name: Run tests with coverage
         shell: bash
         run: npm run test:coverage

.out-of-scope/agent-template-rendering.md

@@ -0,0 +1,104 @@
+# Render agent definitions from templates at install/config-change time
+
+**Source:** [#2758](https://github.com/gsd-build/get-shit-done/issues/2758)
+**Decision:** wontfix — closed on the technical merits
+**Date:** 2026-05-02
+
+## Proposal summary
+
+Move config-gated prose out of `agents/*.md` into `agents/templates/*.md.tmpl`,
+rendered at install time and after `.planning/config.json` writes via a new
+`gsd-sdk agents render` subcommand. Conditional branches resolve at render time
+(deterministic code) instead of at inference time (LLM interpretation).
+
+Three named benefits:
+
+1. Token reduction proportional to disabled features.
+2. Deterministic feature gating (impossible-by-construction vs. test-for).
+3. Single source of truth for contributor-facing gating.
+
+Cites PR #2279 (Codex/OpenCode model embedding at install time) as direct
+precedent for compile-time embedding.
+
+## Why GSD does not own this
+
+### 1. The determinism claim is theoretical, not observed
+
+The proposal's strongest argument is that config-gated branches in agent prose
+are a determinism failure surface. The actual patterns in the codebase today are
+already heavily mitigated:
+
+- The `use_worktrees` branch in `gsd-executor` is resolved deterministically via
+  `gsd-sdk query config-get` in bash — it is not LLM-interpreted.
+- "Skip if `workflow.X` is `false`" prose patterns are short, stable, and
+  follow a uniform "missing key = enabled" convention. There is no documented
+  history of LLMs running disabled checks or skipping enabled ones because of
+  this prose.
+
+A theoretical failure surface should not be traded for a real, high-risk
+patch-migration surface (`gsd-local-patches/` rebase logic, by the reporter's own
+admission "the highest-risk piece of the change"). The reporter was asked for
+documented evidence; none was provided.
+
+### 2. Token waste is small and bounded
+
+The codebase has roughly 5 `workflow.*` toggle references in agent files and
+~20 "Skip if" conditional-prose patterns total — most 1–2 sentences. The
+"real spend across multi-phase milestones" claim was not measured against
+`gsd-context-monitor` output despite being asked. Without a measured baseline,
+the token-savings argument is asserted rather than demonstrated, and the savings
+ceiling on ~20 short conditionals is small enough that it does not justify a new
+template-and-rendering subsystem with a CI-enforced template/generated split.
+
+### 3. The deterministic-gating need is already served
+
+PR #2279 established orchestrator-time config embedding for the cases that
+genuinely need deterministic resolution (model selection, reasoning effort,
+worktree mode). That mechanism is the right layer for orchestration-time
+decisions and can be extended toggle-by-toggle along the existing path without
+introducing a parallel templating subsystem. The proposal's own "Alternative #1"
+(continue the orchestrator-embedding pattern) was rejected on the grounds that
+agent-internal conditionals belong in the agent layer, but the asks behind the
+proposal — determinism, lower token cost — are equally satisfied by extending
+PR #2279 incrementally without a second mechanism.
+
+Adding a templating layer alongside orchestrator-embedding means two mechanisms
+own the same problem. The proposal does not specify a partition rule, and the
+reporter did not respond when asked for one.
+
+### 4. Patch-migration risk is disproportionate to benefit
+
+The `/gsd-reapply-patches` three-way-merge migration for `gsd-local-patches/`
+is, in the proposal's own words, the highest-risk piece of the change. It exists
+solely to absorb a contributor-workflow shift — the user-facing surface is
+unchanged. Risk that flows entirely from internal restructuring, where the
+benefit is unmeasured token savings and a theoretical determinism gain, is the
+wrong trade.
+
+The reduced-scope variant (Alternative #5: fresh installs only, defer the
+migration) avoids that specific risk but still ships a parallel mechanism for
+benefits that remain unmeasured and that PR #2279's path can absorb.
+
+## Re-open criteria
+
+This may be revisited if a contributor:
+
+- Provides measured token deltas via `gsd-context-monitor` against a
+  representative all-toggles-off config, and the delta is materially larger
+  than what extending PR #2279's orchestrator-embedding path one toggle at a
+  time would produce.
+- Documents a real LLM misinterpretation of an existing toggle conditional
+  (executor ignored `workflow.use_worktrees: false`, verifier ran when
+  `workflow.verifier: false`, etc.) — not a projected failure mode.
+- Proposes a clear partition rule between orchestrator-time embedding (PR #2279)
+  and any new install-time templating layer, so the two mechanisms do not
+  overlap.
+
+## Related
+
+- PR #2279 — Codex/OpenCode model embedding at install time (the established
+  precedent for deterministic compile-time embedding into agent files)
+- v1.37.0 release notes — shared-boilerplate extraction (reference files for
+  mandatory-initial-read, project-skills-discovery)
+- `get-shit-done/workflows/` — workflow-level config embedding before subagent
+  spawn (the path of least friction for incremental deterministic gating)

.out-of-scope/temporal-context.md

@@ -0,0 +1,56 @@
+# Temporal context as a first-class GSD signal
+
+**Source:** [#2756](https://github.com/gsd-build/get-shit-done/issues/2756)
+**Decision:** wontfix — closed without further engagement
+**Date:** 2026-05-02
+
+## Proposal summary
+
+Reporter proposed treating idle-time-between-turns as a first-class context signal in
+GSD. Three flavors floated across the issue:
+
+1. **Passive** — block at session resume injecting "you've been idle Nh, here's what was
+   open" into the orchestrator prompt.
+2. **Active** — `/resume-context` slash command.
+3. **Retrospective** — `HANDOFF.json` written at session end, read at next start.
+
+Framed initially as a `claude-inject-idle-time` plugin, with a request that GSD treat
+the pattern as core.
+
+## Why GSD does not own this
+
+- **Subagent gap unsolved.** Passive injection lands in the orchestrator's context
+  only. Subagents (the workers that actually do GSD's planning, execution, verification)
+  spawn fresh and never see the temporal signal. The proposal does not solve this, and
+  any GSD-core integration would inherit the gap. Until the subagent boundary is
+  addressed, "first-class temporal context" is at best a partial feature.
+- **`HANDOFF.json` duplicates existing artifacts.** GSD already persists session
+  continuity through `.planning/state/*` and per-phase artifacts (PLAN.md, RESEARCH.md,
+  REVIEW.md, VERIFICATION.md). A separate handoff file would either drift from those or
+  redundantly mirror them. The right primitive for "what was I doing" already exists.
+- **Statusline / TUI re-entry is platform-level, not GSD-level.** A statusline showing
+  idle time belongs in Claude Code itself or in a thin user plugin, not in GSD's phase
+  machinery.
+- **Scope is unstable.** Reporter agreed with the narrowed minimum ask ("doc mention
+  only, rest opt-in"), then partially retracted it in a follow-up comment ("very
+  integral to myself"). The maintainer asked which version of the ask should move
+  forward; reporter did not respond.
+
+## Re-open criteria
+
+This may be revisited if a reporter:
+
+- Engages with the subagent-gap problem and proposes a concrete mechanism for
+  temporal context to reach subagents (not just the orchestrator).
+- Demonstrates a use case `.planning/state/*` provably cannot serve.
+- Commits to a single stable scope (doc mention OR core integration OR plugin
+  reference) rather than oscillating between them mid-thread.
+
+A drive-by enhancement request that the author does not return to engage with after
+maintainer questions is not actionable. Future proposers: please plan to participate
+through to a triage decision rather than dropping an issue and moving on.
+
+## Related
+
+- `.planning/state/` — existing session-continuity artifacts
+- `get-shit-done/references/` — where any future plugin-interface doc would live

CHANGELOG.md

@@ -4,17 +4,136 @@ All notable changes to GSD will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [Unreleased](https://github.com/gsd-build/get-shit-done/compare/v1.38.5...HEAD)
+## [Unreleased](https://github.com/gsd-build/get-shit-done/compare/v1.39.1...HEAD)
 
-### Added
+### Feature
+
+- **Six namespace meta-skills with keyword-tag descriptions** — replace the flat 86-skill
+  listing with two-stage hierarchical routing. Model sees 6 namespace routers
+  (`gsd:workflow`, `gsd:project`, `gsd:review`, `gsd:context`, `gsd:manage`,
+  `gsd:ideate`) instead of 86 flat entries; selects a namespace, then routes to the
+  sub-skill. Descriptions use pipe-separated keyword tags (≤ 60 chars). Cuts cold-start
+  system-prompt overhead from ~2,150 tokens to ~120. Existing sub-skills are unchanged
+  and still invocable directly. (#2792)
+- **`/gsd-health --context` utilization guard** — context-window quality guard with two
+  thresholds: 60 % warns ("consider `/gsd-thread`"), 70 % is critical ("reasoning
+  quality may degrade"). Exposed via `/gsd-health --context` and as a structured
+  `gsd-tools validate context` command. (#2792)
+- **Phase-lifecycle status-line — read-side** — `parseStateMd()` now reads four new
+  STATE.md frontmatter fields: `active_phase`, `next_action`, `next_phases`, and
+  `progress` (nested completed/total/percent). `formatGsdState()` gains scenes for
+  in-flight, idle, and progress display. All fields default to undefined so existing
+  STATE.md files keep rendering. Write-side and status-line wiring follow in a later
+  RC. (#2833)
 - `--minimal` install flag (alias `--core-only`) writes only the main-loop core skills
   (`new-project`, `discuss-phase`, `plan-phase`, `execute-phase`, `help`, `update`) and
   zero `gsd-*` subagents. Cuts cold-start system-prompt overhead from ~12k tokens to
   ~700, useful for local LLMs with 32K–128K context (Sonnet 4.6 / Opus 4.7 don't need
   it). Re-run `gsd update` without `--minimal` to expand to the full surface. The
   install manifest now records `mode: "minimal" | "full"`. (#2762)
+- **`/gsd-edit-phase` command** — modify any field of an existing phase in ROADMAP.md
+  without changing its number or position. Supports `--force` to skip the confirmation
+  diff, validates `depends_on` references, and updates STATE.md on write. (#2617)
+- **Post-merge build & test gate** — execute-phase step 5.6 now runs in both parallel
+  and serial mode. Adds a build gate that auto-detects the build command from
+  `workflow.build_command` config, then falls back to Xcode (`.xcodeproj`), Makefile,
+  Justfile, Cargo, Go, Python, or npm. Xcode/iOS projects run `xcodebuild build` and
+  `xcodebuild test` automatically. (#2720)
+- **Extended runtime model profiles** — RUNTIME_PROFILE_MAP now covers `gemini`,
+  `qwen`, `opencode`, and `copilot` runtimes with full three-tier (fast/balanced/opus)
+  model mappings. Group B runtimes (kilo, cline, cursor, windsurf, augment, trae,
+  codebuddy, antigravity) fall through to the existing unknown-runtime fallback. (#2612)
+- **Workstream config inheritance** — when `GSD_WORKSTREAM` is set, the root
+  `.planning/config.json` is loaded first and deep-merged with the workstream config
+  (workstream wins on conflict). Explicit `null` in a workstream config now correctly
+  overrides a root value. (#2714)
+- **Manual canary release workflow** — `.github/workflows/canary.yml` publishes
+  `{base}-canary.{N}` builds of `get-shit-done-cc` and `@gsd-build/sdk` under the
+  `canary` dist-tag on demand via `workflow_dispatch` (manual trigger only — auto-publish
+  on every push to main was rejected because submission rate is too high). Includes an
+  optional `dry_run` boolean and the same publish-verification gate as `release.yml`. (#2828)
 
-### Fixed
+### Enhancement
+
+- **Test suite for `config-schema.cjs` is now mutation-resistant** — Stryker measured a 4.62% mutation score on `get-shit-done/bin/lib/config-schema.cjs` (6 killed, 124 survived out of 130). Surviving mutants flagged that existing tests were exercising paths but not verifying outputs: a polarity flip (`return true` → `return false`), a predicate swap (`.some` → `.every`), or a guard removal (`if (VALID_CONFIG_KEYS.has(...)) return true;` → unguarded fallthrough) all passed every test. New `tests/bug-2986-config-schema-mutation-killers.test.cjs` adds 95 tests across four suites that target each surviving mutant class: (1) parameterized `isValidConfigKey('${key}') === true` for every member of `VALID_CONFIG_KEYS` (kills the static-key-fast-path mutation), (2) representative dynamic-pattern keys that match exactly one pattern (kills the `.some` → `.every` mutation, with an inline mutual-exclusivity invariant check), (3) `strictEqual` against the literal boolean `true`/`false` instead of `assert.ok` truthy checks (kills polarity-flip mutations), (4) anchor-tightening cases that differ from valid keys by one character beyond the documented shape (kills regex-loosening mutations on `^`, `$`, and character-class boundaries). Tests use the lib's public surface (typed boolean assertions on `isValidConfigKey` return values), no source-grep. (#2986)
+- **Hotfix release flow now auto-incorporates fixes from `main` and bundles the SDK** — `hotfix.yml create` auto-cherry-picks every `fix:`/`chore:` commit on `origin/main` not yet shipped (oldest-first; patch-equivalents skipped via `git cherry`; `feat:`/`refactor:` excluded; conflicts halt with the offending SHA; run summary lists every included SHA). `hotfix.yml finalize` adds the `install-smoke` cross-platform gate, bundles `sdk-bundle/gsd-sdk.tgz` inside the CC tarball (parity with `release-sdk.yml`), tightens the `next` dist-tag re-point, and marks the GitHub Release `--latest`. `release-sdk.yml` gains `action: publish | hotfix` plus an `auto_cherry_pick` toggle, with a new `prepare` job that branches `hotfix/X.YY.Z` from the highest existing `vX.YY.*` tag and runs the same cherry-pick logic — idempotent if the branch was pre-prepared via `hotfix.yml`. Hotfix `vX.YY.Z` is now defined as everything in `vX.YY.{Z-1}` plus every `fix:`/`chore:` since that base, so each tag is the cumulative-fix anchor for the next. (#2955)
+- **Planning workspace seam extracted from `core.cjs` into `planning-workspace.cjs`** — path/workstream/lock behavior now lives in a dedicated module (`planningDir`, `planningPaths`, `planningRoot`, active-workstream routing, `withPlanningLock`). `core.cjs` keeps compatibility re-exports while call-sites migrate to direct imports, improving locality and reducing coupling. (#2900)
+- **Skill surface consolidated 86 → 59 `commands/gsd/*.md` entries** — four new
+  grouped skills (`capture`, `phase`, `config`, `workspace`) replace clusters of
+  micro-skills. Six existing parents absorb wrap-up and sub-operations as flags:
+  `update --sync/--reapply`, `sketch --wrap-up`, `spike --wrap-up`,
+  `map-codebase --fast/--query`, `code-review --fix`, `progress --do/--next`. Zero
+  functional loss; 31 micro-skills deleted. `autonomous.md` corrected to call
+  `gsd:code-review --fix` (was invoking deleted `gsd:code-review-fix`). (#2790)
+- **PRs missing `Closes #NNN` are auto-closed** — the `Issue link required` workflow
+  now auto-closes PRs opened without a closing keyword that links a tracking issue,
+  posting a comment that points to the contribution guide. (#2872)
+- **Canary release workflow now publishes from `dev` branch only** — `.github/workflows/canary.yml`
+  swaps its four publish-step guards from `refs/heads/main` to `refs/heads/dev`. Aligns the
+  workflow with the new branch→dist-tag policy (`dev` → `@canary`, `main` → `@next`/`@latest`).
+  Added a header comment documenting the policy. `workflow_dispatch` runs on `main` (or any
+  other branch) now complete build/test/dry-run validation but skip publish + tag, instead
+  of the previous behaviour where `main` published and `dev` silently no-op'd. (#2868)
+- **Skill descriptions trimmed to ≤ 100 chars across all `commands/gsd/*.md`** — three
+  anti-patterns eliminated: flag documentation already present in `argument-hint:` (e.g.
+  `discuss-phase` was 380 chars, now 76), `Triggers:` keyword-stuffing lists, and
+  numbered enumeration patterns. Range was 45–380 chars; now 45–99. (#2789)
+- **`scripts/lint-descriptions.cjs` added** — CI lint gate that fails if any
+  `commands/gsd/*.md` description exceeds 100 chars. Run via `npm run lint:descriptions`.
+  (#2789)
+- **Skill surface consolidated from 86 → 59 `commands/gsd/*.md` entries** — four new
+  grouped skills replace clusters of micro-skills: `capture` (add-todo, note, add-backlog,
+  plant-seed, check-todos), `phase` (add-phase, insert-phase, remove-phase, edit-phase),
+  `config` (settings-advanced, settings-integrations, set-profile), `workspace`
+  (new-workspace, list-workspaces, remove-workspace). Six parent skills absorb wrap-up
+  and sub-operations as flags: `update --sync/--reapply`, `sketch --wrap-up`,
+  `spike --wrap-up`, `map-codebase --fast/--query`, `code-review --fix`,
+  `progress --do/--next`. Zero functional loss. (#2790)
+- **`autonomous.md` corrected** — was invoking deleted `gsd:code-review-fix`; now calls
+  `gsd:code-review --fix`. (#2790)
+- **31 micro-skills deleted** — absorbed into consolidated parents or removed outright:
+  add-todo, note, add-backlog, plant-seed, check-todos, add-phase, insert-phase,
+  remove-phase, edit-phase, settings-advanced, settings-integrations, set-profile,
+  new-workspace, list-workspaces, remove-workspace, sync-skills, reapply-patches,
+  sketch-wrap-up, spike-wrap-up, scan, intel, code-review-fix, next, do,
+  join-discord, research-phase, session-report, from-gsd2, analyze-dependencies,
+  list-phase-assumptions, plan-milestone-gaps. All functionality preserved via flags on
+  consolidated skills. (#2790)
+- **`discuss-phase` lazy file loading** — entry-point `@file` directives replaced with
+  on-demand `Read()` calls gated behind mode routing. Tokens loaded at skill entry drop
+  from ~13k to near zero; only the branch actually invoked is loaded. (#2606)
+
+### Fix
+
+- **`gsd-pristine/` is now populated by the installer when local patches are detected** — `saveLocalPatches` declared a `pristineDir` variable and JSDoc'd "saves pristine copies (from manifest) to gsd-pristine/ to enable three-way merge during reapply-patches", but no code ever wrote to that directory. Effect: the `/gsd-reapply-patches` Step 5 verifier (#2972) silently degraded to its over-broad fallback heuristic ("every significant backup line"), exactly the silent-success-on-lost-content failure mode #2969 was designed to prevent. Fix: new `populatePristineDir({ packageSrc, pristineDir, modified, runtime, pathPrefix, isGlobal })` helper runs the install transform pipeline (`copyWithPathReplacement`) into a tmp staging dir, then copies out only the modified-file paths into `gsd-pristine/`. `saveLocalPatches` now accepts a `pristineCtx` and calls the helper when local patches are detected; the install entry point passes the package source root, runtime, pathPrefix, and isGlobal so transforms produce byte-identical output to what `copyWithPathReplacement` would have written under normal install. Soft-fails on transform errors (logs a warning, continues with empty pristine — no worse than pre-fix behavior). Pristine reflects the about-to-install version's content, which is what the verifier needs as the "what would survive without the user's modifications" baseline. Regression covered by `tests/bug-2998-pristine-dir-populated.test.cjs` (6 tests across two suites): asserts the helper is exported, returns 0 for empty modified list, writes one pristine file per source-existing path, skips ghost paths without corrupting pristine, and produces deterministic output (two runs with same inputs yield byte-identical pristine — the property `pristine_hashes` in `backup-meta.json` depends on). (#2998)
+- **`release-sdk` hotfix re-run no longer fails at `Dry-run publish validation` when the version is already on npm** — the `Detect prior publish (reconciliation mode)` step sets `skip_publish=true` when the package version is already on the registry, and the actual publish step honors that gate. The `Dry-run publish validation` step was missing the same guard, so any operator re-run of an already-published hotfix (the typical recovery path when later steps fail mid-flight) hit `npm publish --dry-run` first and got `npm error You cannot publish over the previously published versions: X.Y.Z` — `npm publish --dry-run` contacts the registry and rejects existing-version targets even though it doesn't actually publish. The dry-run validation step is now gated on the same `steps.prior_publish.outputs.skip_publish != 'true'` condition as the publish step. The rehearsal still runs on first publishes (where it has value); it skips only in the specific reconciliation case where the publish itself would be skipped. Trigger run: [25233855236](https://github.com/gsd-build/get-shit-done/actions/runs/25233855236/job/73995605643). Regression covered by `tests/bug-2987-dry-run-validation-skip-on-reconciliation.test.cjs`. (#2987)
+- **`release-sdk` hotfix flow hardened against silent classifier failures, missing-classifier-at-base-tag, and a vestigial merge-back PR step** — three issues surfaced by CodeRabbit's post-merge review of #2981 plus a production failure on the v1.39.1 release run. **(1)** `scripts/diff-touches-shipped-paths.cjs` reused exit code `1` for both the legitimate "no shipped paths" classifier result and Node's default uncaught-throw exit, so any tooling failure was indistinguishable from a normal skip. The script now uses `0` (shipped), `1` (not shipped), `2` (classifier error) with `try`/`catch` + `uncaughtException`/`unhandledRejection` handlers routing all failure paths to exit `2`. **(2)** The workflow's `git checkout -b "$BRANCH" "$BASE_TAG"` overwrote the working tree with the base tag's contents *before* the cherry-pick loop ran the classifier — but base tags predating the classifier's introduction (notably v1.39.0) don't have the file in their tree, so `node scripts/diff-touches-shipped-paths.cjs` would exit non-zero and silently drop every commit, producing an empty hotfix release. The classifier is now staged into `$RUNNER_TEMP` at the top of `Prepare hotfix branch` (before any working-tree-mutating git command), and the loop references that staged copy. The cherry-pick loop snapshots `$PIPESTATUS` into a local array (`PIPE_RC=("${PIPESTATUS[@]}")`) immediately after the classifier pipeline — under bracketed `set +e`/`set -e` — and dispatches via explicit `case`: `0` proceeds, `1` skips into `NON_SHIPPED_SKIPPED`, anything else emits `::error::shipped-paths classifier failed for $SHA (exit N)` and fails the workflow. CodeRabbit on PR #2984 caught a subtler bug in the first iteration: `pipeline \|\| true; RC=${PIPESTATUS[1]}` is broken because `\|\| true` runs `true` as its own one-command pipeline on the failure paths, overwriting `PIPESTATUS` to `(0)` and leaving `${PIPESTATUS[1]}` unset. The array-snapshot form is invariant against this. The same hardening also surfaces `git diff-tree`'s exit code (via `PIPE_RC[0]`); a non-zero diff-tree result now also fails the workflow rather than feeding partial input to the classifier. **(3)** Removed the `Open merge-back PR (hotfix only)` step. The auto-cherry-pick hotfix flow only picks commits already on main (`git cherry HEAD origin/main` outputs the unmerged ones), so by construction every code commit on the hotfix branch is already on main. The only hotfix-branch-only commit is the version-bump chore, which would either no-op against main or rewind main's in-progress version. The step also failed in production with `GitHub Actions is not permitted to create or approve pull requests (createPullRequest)` (org policy) on run [25232968975](https://github.com/gsd-build/get-shit-done/actions/runs/25232968975). The `pull-requests: write` permission previously granted to the release job has been dropped in line with least-privilege. The run-summary line that previously echoed `Merge-back PR opened against main` has been replaced with `No merge-back PR (auto-picked commits are already on main)` so operators reading the summary see an accurate non-action statement (CodeRabbit on PR #2984). Regression covered by `tests/bug-2983-classifier-exit-codes-and-base-tag-staging.test.cjs` (15 assertions across exit-code semantics, classifier staging, error dispatch, PIPESTATUS-snapshot hardening, diff-tree fail-fast, merge-back removal, and run-summary accuracy). (#2983)
+- **`release-sdk` hotfix only cherry-picks commits that change what actually ships** — the `fix:`/`chore:` filter in `Prepare hotfix branch` was too broad: it picked any commit with that conventional-commit type regardless of whether the diff could affect the published npm package. CI-only fixes (release-sdk.yml itself, hotfix tooling, test-only commits) were getting cherry-picked into hotfix branches even though they cannot change the tarball — and the subset touching `.github/workflows/*` then caused the prepare job's `git push` to be rejected by GitHub because the default `GITHUB_TOKEN` lacks the `workflow` scope, aborting the run. v1.39.1 hit this on PR #2977 (run [25232010071](https://github.com/gsd-build/get-shit-done/actions/runs/25232010071)). The loop now pre-skips any candidate commit whose `git diff-tree` output doesn't intersect the npm tarball's shipped paths (entries in `package.json` `files`, plus `package.json` itself, which `npm pack` always includes). Skipped commits land in a new `NON_SHIPPED_SKIPPED` summary bucket framed as informational — non-shipping commits cannot affect the package, so the skip needs no operator action. The shipped-paths classifier lives in `scripts/diff-touches-shipped-paths.cjs` so its rules (file-OR-directory prefix matching `npm pack` semantics, the always-shipped rule for `package.json`, the lockfile-not-shipped rule) are unit-testable. Regression covered by `tests/bug-2980-hotfix-only-picks-shipping-changes.test.cjs`. (#2980)
+- **`release-sdk` hotfix workflow fails on real run with `npm error Version not changed`** — the `release` job's `Bump in-tree version (not committed)` step ran `npm version "$VERSION"` without `--allow-same-version`, so it errored on real (non-dry-run) hotfix runs because `prepare` had already committed the bump on the hotfix branch. The release job's checkout `ref` is asymmetric — `BRANCH` (already bumped) on real runs vs `BASE_TAG` (older version) on dry-runs — which is why dry-run never caught the bug. Both `npm version` calls in that step now pass `--allow-same-version`, matching the existing pattern in `release.yml:326`. (#2976)
+- **Stale deleted command references updated across workflow files** — `help.md`, `do.md`, `settings.md`, `discuss-phase.md`, `new-project.md`, `plan-phase.md`, `spike.md`, and `sketch.md` referenced command names removed in #2790; updated to new consolidated equivalents. (#2950)
+- **`spike --wrap-up` now dispatches correctly** — `/gsd-spike --wrap-up` was silently no-oping because the flag dispatch wiring was omitted when the micro-skill entry point was absorbed in #2790. (#2948)
+- **`config-get context_window` returns `200000` when key absent** — querying an unset `context_window` previously exited 1 with "Key not found", surfacing a confusing error in planning logs even though the workflow fallback worked correctly. `cmdConfigGet` now consults a `SCHEMA_DEFAULTS` map and returns the documented default (`200000`, exit 0) for absent schema-defaulted keys; unknown absent keys still error as before. (#2943)
+- **`gap-analysis` now parses non-`REQ-` requirement IDs and ignores traceability table headers** — `parseRequirements()` no longer hard-codes the `REQ-` prefix and now accepts uppercase prefixed IDs such as `TST-01`, `BACK-07`, and `INSP-04`; markdown table header rows (for example `| REQ-ID | ... |`) are excluded so header tokens are not reported as phantom uncovered requirements. Added regression coverage for mixed-prefix REQUIREMENTS files with traceability tables. (#2897)
+- **Gemini slash commands namespaced as `/gsd:<cmd>` instead of `/gsd-<cmd>`** —
+  Gemini CLI namespaces commands under `gsd:`, so `/gsd-plan-phase` was unexecutable.
+  Body-text references in commands, agents, banners, and patch-reapply hints are now
+  converted via a roster-checked regex (boundary lookbehind + extension-aware
+  lookahead + roster lookup, defense-in-depth). The roster fail-loud guard prevents
+  silent no-op'ing if `commands/gsd/` is ever missing. (#2768, #2783)
+- **`SKILL.md` description quoted for Copilot / Antigravity / Trae / CodeBuddy** —
+  descriptions starting with a YAML 1.2 flow indicator (`[BETA]`, `{`, `*`, `&`, `!`,
+  `|`, `>`, `%`, `@`, backtick) crashed gh-copilot's strict YAML loader. Six emission
+  sites now wrap descriptions in `yamlQuote(...)` (= `JSON.stringify`, a valid YAML
+  1.2 double-quoted scalar). (#2876)
+- **`gsd-tools` invocations use the absolute installed path** — bare `gsd-tools …`
+  calls inside skill bodies relied on PATH resolution that is not guaranteed in every
+  runtime; replaced with the absolute path emitted at install time. (#2851)
+- **Codex installer preserves trailing newline when stripping legacy hooks** — the
+  legacy-hook strip in the Codex installer ran against files with no terminating
+  newline at EOF and emitted a config that lost the newline, breaking downstream
+  parsers. (#2866)
+- **GSD slash command namespace drift cleaned up across docs, workflows, and autocomplete** — remaining active `/gsd:<cmd>` references now use canonical `/gsd-<cmd>`, escaped workflow `Skill(skill=\"gsd:...\")` prompts now use hyphenated skill names, `scripts/fix-slash-commands.cjs` rewrites retired colon syntax to hyphen syntax, and the extract-learnings command file now uses `extract-learnings.md` so generated Claude/Qwen skill autocomplete exposes `gsd-extract-learnings` instead of `gsd-extract_learnings`. (#2855)
+- **`extractCurrentMilestone` no longer truncates ROADMAP.md at heading-like lines inside fenced code blocks** — the milestone-end search now scans line-by-line while tracking ` ``` ` / `~~~` fence state, so a line like `# Ops runbook (v1.0 compat)` inside a code block no longer acts as a milestone boundary. Previously, any phase defined after such a block was invisible to `roadmap analyze`, `roadmap get-phase`, `/gsd-autonomous`, and all phase-number commands. (#2787)
 - **Codex install no longer corrupts existing `~/.codex/config.toml`** — the installer
   now defensively strips legacy `[agents]` (single-bracket) and `[[agents]]` (sequence)
   blocks regardless of GSD marker presence (both invalid in current Codex schema), emits
@@ -26,6 +145,181 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   values, and unsupported value types. Both pre-write helper failures and write-time
   failures restore the pre-install snapshot and abort with a clear error rather than
   warn-and-continue. (#2760)
+- **Codex hooks migrator correctness hardening** — four edge-cases in the
+  `[[hooks.<Event>]]` → `[[hooks.<Event>.hooks]]` migration path fixed: (1) the TOML
+  key parser in hook-body classification now uses `parseTomlKey()` instead of a bare
+  regex, so hyphenated keys (e.g. `status-message`) and quoted keys are no longer
+  silently dropped; (2) `buildNestedBlock` no longer synthesises an empty
+  `[[hooks.TYPE.hooks]]` sub-table for matcher-only sections that carry no handler
+  fields — previously produced a broken entry with `type = "command"` but no
+  `command`; (3) the `legacyMapSections` filter now uses the parsed segment count
+  instead of dot-splitting the path string, preventing three-segment tables such as
+  `[hooks.SessionStart.hooks]` from being misclassified as event entries (same class
+  of bug fixed for `staleNamespacedAotSections` in the previous round); (4) regression
+  test added: `[[hooks."before.tool"]]` (a quoted key containing a dot) is correctly
+  treated as a two-segment namespace and not split on the inner dot. (#2809)
+- **Codex `[[agents]]` reverted to `[agents.<name>]` struct format** — the sequence
+  format introduced in #2645 is rejected by codex-cli 0.124.0 with "invalid type:
+  sequence, expected struct AgentsToml". Reverted to struct format which is correct for
+  0.120.0+. The self-healing stripper handles both formats for configs written by prior
+  GSD versions. (#2727)
+- **Codex legacy `[hooks]` map format auto-migrated** — Codex 0.124.0 requires
+  `[[hooks]]` array-of-tables; old GSD installs that wrote `[hooks.shell]` map-style
+  now self-heal on the next `gsd install --codex`. (#2637)
+- **`gsd-sdk` PATH verification tightened** — installer now probes for an executable
+  `gsd-sdk` shim on PATH after confirming `sdk/dist/cli.js` is present, and attempts
+  to materialize one via symlink at `~/.local/bin/gsd-sdk` when absent. Only prints
+  `✓ GSD SDK ready` when the probe succeeds. (#2775, #2777)
+- **USER-PROFILE.md no longer triggers false "locally modified" warning** — the file
+  was both preserved across reinstalls and tracked in `gsd-file-manifest.json`, causing
+  the stale-hash diff to fire on every profile refresh. `USER_OWNED_ARTIFACTS` is now a
+  single source of truth used by both the preserve and manifest write paths. (#2771)
+- **All `gsd-sdk query` handlers now respect `--ws`** — 18+ handlers accepted
+  `_workstream` but never forwarded it to `planningPaths`/`loadConfig`. Workstream now
+  scopes path resolution correctly in `initNewProject`, `configGet`, `configSet`,
+  `commit`, `validateHealth`, and all other handlers. (#2731)
+- **`resolveModel` threads workstream** — config-query `resolveModel` ignored
+  `_workstream` unlike `configGet`/`configPath`, so different workstreams with different
+  `model_profile` settings would get the root profile instead of their own. (#2742)
+- **`parseMustHavesBlock` quoted strings** — fully-quoted truths containing `:` (e.g.
+  `"App-side UUIDv4: generated locally"`) fell into the kv-parse branch, the regex
+  failed, and `current` stayed as `{}`, crashing `annotate-dependencies` with
+  `TypeError: t.trim is not a function`. Fixed in both `frontmatter.cjs` and
+  `roadmap.cjs`. (#2757, #2734)
+- **`gsd state complete-phase` subcommand** — was missing; unknown subcommands fell
+  through to `cmdStateLoad`. Now updates `Status`, `Last Activity`, and
+  `Current Position` to `COMPLETE`. (#2735)
+- **Non-string `depends_on` values preserved** — numeric YAML scalars and kv-shaped
+  truths were silently dropped by `annotate-dependencies` via an early `typeof t !==
+  'string'` skip. A `coerceTruthToString` helper now coerces numbers/booleans and
+  extracts a string field from object-shaped items. (#2770)
+- **Worktree isolation scoped to submodule-touching plans** — the previous guard
+  unconditionally set `USE_WORKTREES=false` when `.gitmodules` existed. Now parses
+  submodule paths and intersects per-plan `files_modified`; only plans that touch a
+  submodule path skip worktree isolation. (#2772)
+- **Worktree cleanup uses inclusion filter** — the exclusion-based cleanup
+  (`grep -v "$(pwd)$"`) failed in multi-workspace and cross-drive Windows setups,
+  destroying the workspace's `.git` pointer. Cleanup now targets only
+  `.claude/worktrees/agent-*` paths, which agent-spawned worktrees always use. (#2774)
+- **`Requirements:` header variants all parse correctly** — both `**Requirements:**`
+  (colon inside bold) and `**Requirements**:` (colon outside bold) now match in
+  `extractReqIds` and the `phase complete` traceability sweep. (#2769)
+- **`gsd-sdk query commit` paths passed via `--files`** — 81 invocations across 50
+  files were passing paths positionally, which appended them to the commit subject and
+  triggered the wholesale-stage fallback. All sites updated. (#2767)
+- **Phase detection in bullet/bold ROADMAP formats** — `phaseAdd`'s regex only matched
+  heading format (`## Phase N:`), missing bullet checklist and bold entries. Broadened
+  to all three formats with filesystem fallback on zero matches. (#2726)
+- **Plan-line overwrite when `**Plans:**` is empty** — `\s*` after `**Plans:**`
+  matched newlines, causing `[^\n]+` to consume the first plan checkbox. Replaced with
+  `[ \t]*` (horizontal whitespace only) and added section-boundary lookahead. (#2728)
+- **Phase-lifecycle `<details>`-wrapped active milestone** — `replaceInCurrentMilestone`
+  silently dropped replacements when the active milestone was itself inside a `<details>`
+  block (the after-slice was empty). Falls back to locating the last complete
+  `<details>…</details>` span. (#2641)
+- **Phase-lifecycle project-code-prefixed directory names** — filesystem fallback regex
+  `/^(\d+)-/` missed directories like `CK-45-foundation`. Updated to
+  `/^(?:[A-Z][A-Z0-9]*-)?(\d+)-/i`.
+- **`roadmap.update-plan-progress` regex** — `\s*` crossing newlines shared the same
+  corruption vector as `planCountPattern`; replaced with `[ \t]*` plus section-boundary
+  lookahead.
+- **`replaceInCurrentMilestone` fast-path guard** — the `after.trim().length > 0`
+  check incorrectly triggered when `after` contained only footer text, returning
+  unchanged content instead of falling through to the slow path.
+- **`graphify` CLI updated to subcommand form** — `graphify . --update` was removed in
+  v0.4.x in favour of `graphify update .`. Version detection now tries
+  `graphify --version` before falling back to the Python importlib query. (#2732)
+- **LM Studio model identity validated in review workflow** — captures the full API
+  response and compares the top-level `.model` field against `LM_STUDIO_MODEL`, emitting
+  a warning when the served model differs. Empty-content responses no longer write error
+  text into the review temp file (same fix applied to llama.cpp). (#2721)
+- **SDK `globalDefaults` preserved for nested config keys** — `workflow`, `git`,
+  `hooks`, `agent_skills`, and `features` sections were missing the `globalDefaults`
+  spread at the correct precedence level, silently dropping user values from
+  `~/.gsd/defaults.json`. (#2673)
+- **`MODEL_ALIAS_MAP` updated to `claude-opus-4-7`** — both `MODEL_ALIAS_MAP` and
+  `RUNTIME_PROFILE_MAP.claude.opus` were pinned to `claude-opus-4-6`. (#2733)
+- **Orchestrators wait for subagents before continuing** — 26 GSD workflow files now
+  include an explicit `ORCHESTRATOR RULE` blockquote immediately after every `Task()`
+  spawn, preventing the Codex parallel-work anti-pattern where the parent continues
+  reading files and producing conflicting output. (#2729)
+- **`audit-uat` parser reads `human_verification:` from frontmatter array** — the
+  previous body-only regex was too strict and missed valid UAT items declared in YAML
+  frontmatter, surfacing false-positive open gaps at every `/gsd-complete-milestone`
+  audit. (#2788)
+- **`gsd-sdk` binary collision with `@gsd-build/sdk` resolved** — workstream-aware
+  query registry now respects `GSD_WORKSTREAM` env var; `gsd-tools` bin alias added so
+  the two SDK packages no longer fight over the `gsd-sdk` name in `node_modules/.bin`.
+  (#2791)
+- **OpenCode generated agents embed `model_profile_overrides.opencode.<tier>`** —
+  per-tier model overrides set via `/gsd-settings-advanced` are now propagated into the
+  generated agent files instead of being silently ignored. (#2794)
+- **`roadmap update-plan-progress` accepts `--phase` flag form** — SDK arg-parsing
+  regression in v0.1.0 silently dropped `--phase`/`--name`/`--plans` flags, causing
+  `state.begin-phase` and `roadmap update-plan-progress` to corrupt STATE.md. (#2796)
+- **`context_window` added to `VALID_CONFIG_KEYS` allowlist** — `/gsd-settings-advanced`
+  could not set `context_window` because the key was missing from the allowlist used by
+  `config-set` validation. (#2798)
+- **`gsd-tools init` dispatches `ingest-docs` handler** — `/gsd-ingest-docs` was broken
+  in v1.38.5 because the workflow called `gsd-sdk` (now `gsd-tools`) but no
+  `ingest-docs` init handler was registered. (#2801)
+- **`config-get` honors `--default <value>` flag** — fallback for missing keys was
+  ported from the CJS implementation (#1893) into the SDK. (#2803)
+- **`find-phase` returns `null` for archived phases** — when the current-milestone
+  phase had no directory yet, `init.plan-phase` / `init.execute-phase` returned the
+  archived prior-milestone directory instead of `null`, causing wrong-phase work. (#2805)
+- **SKILL.md frontmatter `name:` migrated to hyphen form** — files that still used the
+  deprecated colon form (`gsd:cmd`) caused autocomplete to suggest `/gsd:command`.
+  Frontmatter now uses canonical `gsd-cmd` hyphen names. (#2808)
+- **`gsd-sdk` resolvable in local-mode installs** — the previous `isLocal` short-circuit
+  in `installSdkIfNeeded()` returned before the PATH probe + self-link path could run
+  (the same path that fixed npx-cache global installs in #2775). When `sdk/dist/cli.js`
+  is present, local installs now run the same probe-and-link flow as global installs.
+  (#2829)
+- **OpenCode `@file` references use absolute paths on all platforms** — OpenCode does
+  not shell-expand `$HOME` in `@file` references on any platform, but the Windows-only
+  guard from #2376 left macOS/Linux producing literal `@$HOME/...` strings that resolved
+  to `command/$HOME/...` (file not found). Guard now applies to OpenCode unconditionally.
+  (#2831)
+- **`gsd-sdk auto` detects Codex runtime correctly** — `auto` mode ignored
+  `runtime: codex` and routed through `@anthropic-ai/claude-agent-sdk`, producing the
+  `[FAILED] $0.00 0.1s` symptom on autonomous runs. New `runtime-gate` raises a clear
+  error for non-Claude runtimes; `resolveModel()` is now runtime-aware (honours
+  `GSD_RUNTIME` env precedence) and never injects a Claude profile id under non-Claude
+  runtimes. (#2832)
+- **CR-INTEGRATION tests aligned with hyphen-form skill names** — tests previously
+  asserted `gsd:code-review` (colon) against `autonomous.md` which now uses the canonical
+  hyphen form. Tests now parse `Skill(skill="...")` invocations structurally and reject
+  the legacy colon form. (#2835)
+- **`audit-open` quick-task scanner accepts `${quick_id}-SUMMARY.md`** — the previous
+  bare-`SUMMARY.md` filename check produced false-positive `status: missing` for every
+  documented quick task. UAT terminal-status enum also adds `resolved` (matches
+  `execute-phase.md`'s post-gap-closure terminal); `help.md` one-liner reconciled with
+  the canonical `quick.md` workflow. (#2836)
+- **`quick.md` / `execute-phase.md` SUMMARY rescue handles gitignored `.planning/`** —
+  rescue blocks used `git ls-files --exclude-standard` which honoured `.gitignore`,
+  silently no-op'ing when `.planning/` was excluded; the worktree was then deleted with
+  the SUMMARY. Replaced with filesystem-level `find` + idempotent `cp` that bypasses git
+  entirely. (#2838)
+- **`/gsd-code-review-fix` cleanup tail is transactional** — JSON recovery sentinel at
+  `${phase_dir}/.review-fix-recovery-pending.json` is written after `git worktree add`
+  succeeds and removed only after `git worktree remove` returns. A new run that finds a
+  pre-existing sentinel force-removes the orphan worktree before starting fresh, making
+  the agent self-healing across crashes. (#2839)
+
+
+## [1.39.1] - 2026-05-01
+
+Hotfix release. Cherry-picks user-facing fixes from `main` onto the v1.39.0 stable
+line. Install: `npm install -g get-shit-done-cc@latest` (or `@1.39.1` to pin).
+
+### Fixed
+
+- **`gsd-sdk query agent-skills` emits raw `<agent_skills>` block instead of JSON-wrapped string** — workflows that embed via `$(gsd-sdk query agent-skills <agent>)` were receiving a JSON-quoted string literal mid-prompt (e.g. `"<agent_skills>\n…"`), silently breaking all `<agent_skills>` injection into spawned subagents. The CLI dispatcher now honors an opt-in `format: 'text'` field on `QueryResult` and writes such results raw via `process.stdout.write`; `--pick` always returns JSON regardless. (#2917)
+- **`sketch --wrap-up` now dispatches correctly** — `/gsd-sketch --wrap-up` was silently no-oping because the flag dispatch wiring was omitted when the micro-skill entry point was absorbed in #2790. (#2949)
+- **`help.md` no longer advertises eight slash commands removed by the #2824 consolidation** — `/gsd-do`, `/gsd-note`, `/gsd-check-todos`, `/gsd-plant-seed`, `/gsd-research-phase`, `/gsd-list-phase-assumptions`, `/gsd-plan-milestone-gaps`, and `/gsd-join-discord` were removed when 86 skills were folded into 59. `help.md` was not updated alongside, so users typing the documented commands hit *Unknown command*. Each entry is now either rewritten to the surviving flag-based dispatcher (e.g., `/gsd-do …` → `/gsd-progress --do "…"`, `/gsd-note` → `/gsd-capture --note`, `/gsd-plant-seed` → `/gsd-capture --seed`, `/gsd-check-todos` → `/gsd-capture --list`) or removed for skills with no replacement. A regression test now asserts every `/gsd-*` reference in `help.md` has a matching `commands/gsd/*.md` stub. (#2954)
+- **`--sdk` install on Windows now writes a callable `gsd-sdk` shim** — `npx get-shit-done-cc@latest --claude --global --sdk` on Windows previously left `gsd-sdk` off PATH because `trySelfLinkGsdSdk` returned `null` unconditionally on `win32` (a missed gap from #2775's POSIX self-link, not an intentional deferral). The function now dispatches to a Windows counterpart that writes the standard npm shim triple (`gsd-sdk.cmd`, `gsd-sdk.ps1`, and a Bash wrapper) to npm's global bin, so `gsd-sdk` resolves in a fresh shell across cmd.exe, PowerShell, and Cygwin/MSYS/Git-Bash. A new regression guard in `tests/no-unconditional-win32-skip.test.cjs` blocks any future `if (process.platform === 'win32') return null;` skip-only branches in `bin/install.js`. (#2962)
+- **`/gsd-reapply-patches` Step 5 gate is now deterministic — no more silent content drops** — the prior gate parsed a Claude-generated *Hunk Verification Table* whose `verified: yes` rows were filled in without actually checking content presence, leading to merged files that lost user-added blocks (e.g., a `<visual_companion>` section, an `--execute-only` flag block) while the workflow reported success. The gate now invokes a Node script (`scripts/verify-reapply-patches.cjs`) that diffs each backup against the pristine baseline, computes the user-added significant lines, and asserts each one is present in the merged file. Exits non-zero with a per-file diagnostic on any miss; the workflow halts and surfaces the JSON output to the user. The verifier ignores low-signal lines (too short, pure whitespace, decorative comments) so trivial differences don't trigger false failures. Out of scope here: the manifest-baseline tightening described in #2969 Failure 1 — that's separate work. (#2969)
 
 ## [1.38.5] - 2026-04-25
 

CONTEXT.md

@@ -0,0 +1,41 @@
+# Context
+
+## Domain terms
+
+### Dispatch Policy Module
+Module owning dispatch error mapping, fallback policy, timeout classification, and CLI exit mapping contract.
+
+Canonical error kind set:
+- `unknown_command`
+- `native_failure`
+- `native_timeout`
+- `fallback_failure`
+- `validation_error`
+- `internal_error`
+
+### Command Definition Module
+Canonical command metadata Interface powering alias, catalog, and semantics generation.
+
+### Query Runtime Context Module
+Module owning query-time context resolution for `projectDir` and `ws`, including precedence and validation policy used by query adapters.
+
+### Native Dispatch Adapter Module
+Adapter Module that satisfies native query dispatch at the Dispatch Policy seam, so policy modules consume a focused dispatch Interface instead of closure-wired call sites.
+
+### Query CLI Output Module
+Module owning projection from dispatch results/errors to CLI `{ exitCode, stdoutChunks, stderrLines }` output contract.
+
+### Query Execution Policy Module
+Module owning query transport routing policy projection (`preferNative`, fallback policy, workstream subprocess forcing) at execution seam.
+
+### Query Subprocess Adapter Module
+Adapter Module owning subprocess execution contract for query commands (JSON/raw invocation, `@file:` indirection parsing, timeout/exit error projection).
+
+### Query Command Resolution Module
+Canonical command normalization and resolution Interface (`query-command-resolution-strategy`) used by internal query/transport paths after dead-wrapper convergence.
+
+### Command Topology Module
+Module owning command resolution, policy projection (`mutation`, `output_mode`), unknown-command diagnosis, and handler Adapter binding at one seam for query dispatch.
+
+### Query Pre-Project Config Policy Module
+Module policy that defines query-time behavior when `.planning/config.json` is absent: use built-in defaults for parity-sensitive query Interfaces, and emit parity-aligned empty model ids for pre-project model resolution surfaces.

CONTRIBUTING.md

@@ -81,6 +81,20 @@ PRs that arrive without a properly-labeled linked issue are closed automatically
 
 ## Pull Request Guidelines
 
+### Architecture & Domain Standards (Maintainer-Defined)
+
+The following files are maintainer-owned coding standards and must be treated as canonical when contributing:
+
+- `CONTEXT.md` — domain language and module naming standards
+- `docs/adr/` — Architecture Decision Records (ADRs) for accepted architectural decisions
+
+Contributor requirements:
+- Read `CONTEXT.md` before naming or refactoring modules/interfaces/seams.
+- Use `CONTEXT.md` vocabulary consistently in code comments, tests, issue/PR text, and docs for the touched area.
+- Check relevant ADRs in `docs/adr/` before proposing or implementing architectural changes.
+- If a change intentionally revisits an ADR decision, call it out explicitly in the linked issue and PR rationale.
+- Do not rewrite maintainer intent in `CONTEXT.md`/ADRs as part of drive-by cleanup; propose focused updates tied to approved scope.
+
 **Every PR must link to an approved issue.** PRs without a linked issue are closed without review, no exceptions.
 
 - **No draft PRs** — draft PRs are automatically closed. Only open a PR when it is complete, tested, and ready for review. If your work is not finished, keep it on your local branch until it is.
@@ -91,6 +105,23 @@ PRs that arrive without a properly-labeled linked issue are closed automatically
 - **CI must pass** — all matrix jobs (Ubuntu × Node 22, 24; macOS × Node 24) must be green
 - **Scope matches the approved issue** — if your PR does more than what the issue describes, the extra changes will be asked to be removed or moved to a new issue
 
+## CHANGELOG Entries — Drop a Fragment
+
+**Do not edit `CHANGELOG.md` directly.** Two PRs that both append to a `### Fixed` block always conflict on merge — git can't pick a serialization order without a human. Instead, every PR with user-facing changes drops a fragment file in `.changeset/`.
+
+```bash
+npm run changeset -- --type Fixed --pr <YOUR_PR_NUMBER> \
+  --body "**\`/gsd-foo\` no longer drops trailing slashes** — explain the user-visible change."
+```
+
+This writes `.changeset/<adjective>-<noun>-<noun>.md`. Three random words → concurrent PRs never collide. Allowed `type:` values follow [Keep a Changelog](https://keepachangelog.com/): `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`.
+
+Fragments are consolidated into `CHANGELOG.md` at release time by the release workflow. See [`.changeset/README.md`](.changeset/README.md) for the format spec and [#2975](https://github.com/gsd-build/get-shit-done/issues/2975) for the rationale.
+
+**CI enforcement:** the `Changeset Required` workflow (`scripts/changeset/lint.cjs`) fails any PR that touches `bin/`, `get-shit-done/`, `agents/`, `commands/`, `hooks/`, or `sdk/src/` without a `.changeset/*.md` fragment.
+
+**Opt-out:** PRs with no user-facing impact (test refactors, lint config changes, CI tweaks, formatting-only changes) can add the `no-changelog` label. The lint honors it. When unsure whether a change is user-facing, **add the fragment**.
+
 ## Testing Standards
 
 All tests use Node.js built-in test runner (`node:test`) and assertion library (`node:assert`). **Do not use Jest, Mocha, Chai, or any external test framework.**
@@ -281,6 +312,7 @@ Some tests legitimately read source files. There are six recognized categories:
 | `docs-parity` | A reference doc must stay in sync with source-defined constants (e.g., `CONFIG_DEFAULTS`). The source is the canonical list; there is no runtime API to enumerate it. |
 | `integration-test-input` | A source file is used as a real fixture input to a transformation function under test — the file is not inspected for strings but passed as data. |
 | `structural-implementation-guard` | A feature's interception or wiring point is not reachable end-to-end via `runGsdTools`. Used temporarily until a behavioral path exists. |
+| `pending-migration-to-typed-ir` | **Tracked for correction, not exempted.** Test was identified by the lint as carrying a raw-text-matching pattern that contradicts the rule above. Each annotated file MUST cite the open migration issue (e.g. `// allow-test-rule: pending-migration-to-typed-ir [#NNNN]`) so the tracking is auditable. New tests cannot use this category — they must refactor production to expose typed IR. The annotation is removed when the test is corrected. |
 
 Annotate with a standalone `//` comment before the file's opening block comment:
 
@@ -296,6 +328,68 @@ Annotate with a standalone `//` comment before the file's opening block comment:
 
 The annotation **must** be a standalone `// allow-test-rule:` line, not inside a `/** */` block comment — the CI linter scans for the pattern `// allow-test-rule:`.
 
+### Prohibited: Raw Text Matching on Test Outputs (file content, stdout, stderr)
+
+**Source-grep is not just `readFileSync` of a `.cjs` file.** The same anti-pattern shows up wherever a test pattern-matches against text that a system-under-test produced, regardless of whether that text came from a source file, a rendered shim, a child process's stdout, or a free-form `reason` string. **All forms are forbidden.**
+
+The following are all violations of the same rule:
+
+```javascript
+// BAD — substring match on text written by the code under test
+const cmdContent = fs.readFileSync(path.join(tmpDir, 'gsd-sdk.cmd'), 'utf8');
+assert.ok(cmdContent.includes(`@node ${jsonQuoted} %*`), '.cmd embeds shim path');
+
+// BAD — regex match on a child process's human-readable stdout formatter
+const r = cp.spawnSync(SCRIPT, ['--patches-dir', dir]);
+assert.match(r.stdout, /Failures: 1/);
+assert.match(r.stdout, /not a regular file/);
+
+// BAD — "structured parser" that hides string ops behind a function wrapper
+function parseCmdShim(content) {
+  const lines = content.split('\r\n').filter((l) => l.length > 0);
+  return { header: lines[0], usesCRLF: content.includes('\r\n') };
+}
+
+// BAD — assert.match on a free-form `reason` string from a JSON report
+assert.ok(/not a regular file/.test(report.results[0].reason));
+```
+
+Each of these passes on accidental near-matches (a comment containing `@node` somewhere, a stack trace that happens to say `Failures: 1`, a mis-typed reason that still contains the substring you're matching) and fails on harmless reformatting (changing `Failures: 1` to `1 failure`, swapping CRLF rendering style, rewording the error prose).
+
+#### The rule
+
+> **Tests assert on typed structured values. If the code under test produces text, the code under test must also expose a structured intermediate representation, and the test must assert on that IR — never on the rendered text.**
+
+Concretely: for any system-under-test that produces text output (a file renderer, a CLI formatter, an error-message builder), the production code MUST expose a typed alternative that the test consumes:
+
+| Output kind | Required structured surface | What the test asserts on |
+|---|---|---|
+| Rendered file (shim, template, generated code) | A pure builder function returning the IR (`{ invocation, eol, fileNames, render }`) | `triple.invocation.target === expected`, `triple.eol.cmd === '\r\n'` |
+| CLI human-formatter output | A `--json` mode that emits the same data structurally | `report.results[0].reason === REASON.FAIL_INSTALLED_NOT_REGULAR_FILE` |
+| Error / status / reason | A frozen enum (`Object.freeze({ FAIL_X: 'fail_x', ... })`) | `assert.equal(result.reason, REASON.FAIL_X)` |
+| File presence after a write | `fs.statSync().isFile()`, `.size > 0`, `.mtimeMs` advances | Filesystem facts; never read the file content back |
+
+#### Concrete examples from this repo
+
+`buildWindowsShimTriple(shimSrc)` in `bin/install.js` is the canonical IR pattern: pure function, no I/O, returns `{ invocation, eol, fileNames, render }`. `trySelfLinkGsdSdkWindows` calls it and writes `triple.render[kind]()` to disk. Tests assert on `triple.invocation.target`, `triple.eol.cmd`, `Object.keys(triple).sort()` — never on the rendered text. Filesystem-level tests assert `fs.statSync(target).size === Buffer.byteLength(triple.render.cmd())` to prove the writer writes what the renderer produces, **without comparing content**.
+
+`scripts/verify-reapply-patches.cjs` exposes a frozen `REASON` enum and emits it through `--json`. Tests assert `report.results[0].reason === REASON.FAIL_USER_LINES_MISSING`. The human formatter exists for operator console output only — tests must not depend on its prose. Adding a new reason code requires updating the `REASON` enum, the `--json` output, AND the test that locks `Object.keys(REASON).sort()` — three coordinated changes that prevent the code surface from drifting from the test surface.
+
+#### Hiding grep behind a function is still grep
+
+`parseCmdShim`, `parsePs1Invocation`, etc. that internally do `content.split(...)`, `lines[1].trim()`, `content.includes(...)` are still string manipulation. The fact that the entry point looks like a parser doesn't change what's happening underneath — the test is still asserting on the lexical shape of rendered text. The fix is not "wrap the grep in a function with a typed-looking return value." The fix is to **eliminate the rendered text from the test path entirely** by surfacing the IR.
+
+#### When you cannot eliminate text matching
+
+There are exactly two cases where text content is the legitimate object of a test, both already covered by the existing exemption matrix:
+
+1. `source-text-is-the-product` — workflow `.md` / agent `.md` / command `.md` files where the deployed text IS what the runtime loads.
+2. `docs-parity` — a reference doc must mirror source-defined constants and there is no runtime enumeration API.
+
+For everything else, if a test reaches for `.includes()` / `.startsWith()` / `assert.match(text, /…/)`, the production code is missing a typed surface. **Add the typed surface; do not work around it.**
+
+**CI enforcement:** `scripts/lint-no-source-grep.cjs` is being extended (see issue tracker for the latest scope) to flag `String#includes`/`String#startsWith`/`String#endsWith`/`assert.match` on `readFileSync` results and on `cp.spawnSync` stdout/stderr in test files, with the same `// allow-test-rule:` exemption mechanism.
+
 ### Node.js Version Compatibility
 
 **Node 22 is the minimum supported version.** Node 24 is the primary CI target. All tests must pass on both.
@@ -345,6 +439,73 @@ node --test tests/core.test.cjs
 npm run test:coverage
 ```
 
+### Pre-PR Seam Checks (Manifest/Alias Routing)
+
+If you touched any of the command-manifest or generated alias files, run:
+
+```bash
+npm run check:alias-drift
+```
+
+This verifies generated alias artifacts are in sync with manifest source-of-truth.
+
+Optional local pre-commit hook entry (Git-native):
+
+```bash
+# one-time setup
+mkdir -p .githooks
+cat > .githooks/pre-commit <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+
+if git diff --cached --name-only | grep -Eq "^sdk/src/query/command-manifest\.|^sdk/src/query/command-aliases\.generated\.ts$|^get-shit-done/bin/lib/command-aliases\.generated\.cjs$|^sdk/scripts/gen-command-aliases\.ts$"; then
+  npm run check:alias-drift
+fi
+EOF
+chmod +x .githooks/pre-commit
+git config core.hooksPath .githooks
+```
+
+Optional local pre-push hook to block a private author-email pattern:
+
+```bash
+# set locally in your shell profile (example)
+export GSD_BLOCKED_AUTHOR_REGEX='@example-corp\\.com$'
+
+cat > .githooks/pre-push <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+
+zero_sha='0000000000000000000000000000000000000000'
+blocked_regex="${GSD_BLOCKED_AUTHOR_REGEX:-}"
+[[ -z "$blocked_regex" ]] && exit 0
+violations=()
+
+while read -r local_ref local_sha remote_ref remote_sha; do
+  [[ "$local_sha" == "$zero_sha" ]] && continue
+  if [[ "$remote_sha" == "$zero_sha" ]]; then
+    commits=$(git rev-list "$local_sha" --not --remotes)
+  else
+    commits=$(git rev-list "$remote_sha..$local_sha")
+  fi
+  while read -r commit; do
+    [[ -z "$commit" ]] && continue
+    email=$(git show -s --format='%ae' "$commit" | tr '[:upper:]' '[:lower:]')
+    if printf '%s' "$email" | grep -Eq "$blocked_regex"; then
+      violations+=("$commit <$email>")
+    fi
+  done <<< "$commits"
+done
+
+if [[ ${#violations[@]} -gt 0 ]]; then
+  echo "Push blocked: commit author email matched local blocked regex ($blocked_regex)." >&2
+  printf '  - %s\n' "${violations[@]}" >&2
+  exit 1
+fi
+EOF
+chmod +x .githooks/pre-push
+```
+
 ### CI Test Quality Checks
 
 The following checks run on every PR in addition to the test suite:
@@ -357,6 +518,14 @@ Run locally before pushing: `npm run lint:tests`
 
 ### Test Requirements by Contribution Type
 
+### Architecture-Aware Testing Requirements
+
+When work touches architecture, routing, policy, registry assembly, or command semantics:
+- Write tests against module **interfaces** and seam behavior, not implementation trivia.
+- Prefer invariant/contract tests that protect ADR-backed behavior and `CONTEXT.md` terminology.
+- Ensure tests validate canonical behavior through the defined seam (for example: structured result contracts, canonical command metadata, and adapter parity), not source-text coupling.
+- If ADRs define expected behavior, tests should assert those expectations directly.
+
 The required tests differ depending on what you are contributing:
 
 **Bug Fix:** A regression test is required. Write the test first — it must demonstrate the original failure before your fix is applied, then pass after the fix. A PR that fixes a bug without a regression test will be asked to add one. "Tests pass" does not prove correctness; it proves the bug isn't present in the tests that exist.

README.ja-JP.md

@@ -75,15 +75,17 @@ GSDはそれを解決します。Claude Codeを信頼性の高いものにする
 
 ビルトインの品質ゲートが本当の問題を検出します：スキーマドリフト検出はマイグレーション漏れのORM変更をフラグし、セキュリティ強制は検証を脅威モデルに紐付け、スコープ削減検出はプランナーが要件を暗黙的に落とすのを防止します。
 
-### v1.32.0 ハイライト
+### v1.39.0 ハイライト
 
-- **STATE.md整合性ゲート** — `state validate`がSTATE.mdとファイルシステムの差分を検出、`state sync`が実際のプロジェクト状態から再構築
+完全なリストは [v1.39.0 リリースノート](https://github.com/gsd-build/get-shit-done/releases/tag/v1.39.0) を参照してください。
-- **`--to N`フラグ** — 自律実行を特定のフェーズ完了後に停止
+
-- **リサーチゲート** — RESEARCH.mdに未解決の質問がある場合、計画をブロック
+- **`--minimal` インストールプロファイル** — エイリアス `--core-only`。メインループの6スキル（`new-project`、`discuss-phase`、`plan-phase`、`execute-phase`、`help`、`update`）のみをインストールし、`gsd-*` サブエージェントはゼロ。コールドスタート時のシステムプロンプトのオーバーヘッドを ~12kトークンから ~700トークンへ削減（≥94%減）。32K〜128Kコンテキストのローカル LLM やトークン課金 API に有効。
-- **検証マイルストーンスコープフィルタリング** — 後のフェーズで対処されるギャップは「ギャップ」ではなく「延期」としてマーク
+- **`/gsd-edit-phase`** — `ROADMAP.md` 上の既存フェーズの任意フィールドをその場で編集（番号や位置は変更されない）。`--force` で確認 diff をスキップ、`depends_on` の参照を検証し、書き込み時に `STATE.md` も更新。
-- **読み取り後編集ガード** — 非Claudeランタイムでの無限リトライループを防止するアドバイザリーフック
+- **マージ後ビルド & テストゲート** — `execute-phase` のステップ 5.6 が `workflow.build_command` の設定を自動検出し、無ければ Xcode（`.xcodeproj`）、Makefile、Justfile、Cargo、Go、Python、npm の順にフォールバック。Xcode/iOS プロジェクトでは `xcodebuild build` と `xcodebuild test` を自動実行。並列・直列両モードで動作。
-- **コンテキスト削減** — Markdownのトランケーションとキャッシュフレンドリーなプロンプト順序でトークン使用量を削減
+- **ランタイム別レビューモデル選択** — `review.models.<cli>` で各外部レビュー CLI（codex、gemini など）が使うモデルをプランナー/実行プロファイルとは独立に指定可能。
-- **4つの新ランタイム** — Trae、Kilo、Augment、Cline（合計12ランタイム）
+- **ワークストリーム設定の継承** — `GSD_WORKSTREAM` が設定されている場合、ルートの `.planning/config.json` を先に読み込み、ワークストリーム設定をディープマージ（衝突時はワークストリーム側が優先）。ワークストリーム設定で明示的に `null` を指定するとルート値を上書き可能。
+- **手動カナリアリリースワークフロー** — `.github/workflows/canary.yml` が `workflow_dispatch` 経由で `dev` ブランチから `{base}-canary.{N}` ビルドを `@canary` dist-tag に手動公開（`get-shit-done-cc` と `@gsd-build/sdk`）。
+- **スキルの統合：86 → 59** — 4つの新しいグループ化スキル（`capture`、`phase`、`config`、`workspace`）が31のマイクロスキルを吸収。既存の親スキル6つはラップアップやサブ操作をフラグ化：`update --sync/--reapply`、`sketch --wrap-up`、`spike --wrap-up`、`map-codebase --fast/--query`、`code-review --fix`、`progress --do/--next`。機能の欠損なし。
 
 ---
 
@@ -597,6 +599,7 @@ lmn012o feat(08-02): create registration endpoint
 |---------|--------------|
 | `/gsd-add-phase` | ロードマップにフェーズを追加 |
 | `/gsd-insert-phase [N]` | フェーズ間に緊急作業を挿入 |
+| `/gsd-edit-phase [N] [--force]` | 既存フェーズの任意フィールドをその場で編集 — 番号と位置は変更されない |
 | `/gsd-remove-phase [N]` | 将来のフェーズを削除し番号を振り直し |
 | `/gsd-list-phase-assumptions [N]` | 計画前にClaudeの意図するアプローチを確認 |
 | `/gsd-plan-milestone-gaps` | 監査で見つかったギャップを埋めるフェーズを作成 |

README.ko-KR.md

@@ -75,15 +75,17 @@ GSD가 그걸 고칩니다. Claude Code를 신뢰할 수 있게 만드는 컨텍
 
 내장 품질 게이트가 실제 문제를 잡아냅니다: 스키마 드리프트 감지는 마이그레이션 누락된 ORM 변경을 플래그하고, 보안 강제는 검증을 위협 모델에 고정시키고, 스코프 축소 감지는 플래너가 요구사항을 몰래 빠뜨리는 걸 방지합니다.
 
-### v1.32.0 하이라이트
+### v1.39.0 하이라이트
 
-- **STATE.md 일관성 게이트** — `state validate`가 STATE.md와 파일시스템 간 드리프트를 감지, `state sync`가 실제 프로젝트 상태에서 재구성
+전체 목록은 [v1.39.0 릴리스 노트](https://github.com/gsd-build/get-shit-done/releases/tag/v1.39.0)를 참고하세요.
-- **`--to N` 플래그** — 자율 실행을 특정 단계 완료 후 중지
+
-- **리서치 게이트** — RESEARCH.md에 미해결 질문이 있으면 기획을 차단
+- **`--minimal` 설치 프로파일** — 별칭 `--core-only`. 메인 루프 6개 스킬(`new-project`, `discuss-phase`, `plan-phase`, `execute-phase`, `help`, `update`)만 설치하고 `gsd-*` 서브에이전트는 설치하지 않음. 콜드 스타트 시스템 프롬프트 오버헤드를 ~12k 토큰에서 ~700 토큰으로 축소(≥94% 감소). 32K–128K 컨텍스트의 로컬 LLM이나 토큰 과금 API에 유용.
-- **검증 마일스톤 스코프 필터링** — 이후 단계에서 처리될 격차는 "격차"가 아닌 "지연됨"으로 표시
+- **`/gsd-edit-phase`** — `ROADMAP.md`에 있는 기존 단계의 임의 필드를 그 자리에서 수정(번호와 위치는 변경되지 않음). `--force`는 확인 diff를 건너뛰고, `depends_on` 참조를 검증하며 쓰기 시 `STATE.md`도 갱신.
-- **읽기-후-편집 가드** — 비Claude 런타임에서 무한 재시도 루프를 방지하는 어드바이저리 훅
+- **머지 후 빌드 & 테스트 게이트** — `execute-phase` 5.6 단계가 `workflow.build_command` 설정을 우선 자동 감지하고, 없으면 Xcode(`.xcodeproj`), Makefile, Justfile, Cargo, Go, Python, npm 순으로 폴백. Xcode/iOS 프로젝트는 `xcodebuild build` 및 `xcodebuild test`를 자동 실행. 병렬·직렬 모드 모두에서 동작.
-- **컨텍스트 축소** — 마크다운 잘라내기 및 캐시 친화적 프롬프트 순서로 토큰 사용량 절감
+- **런타임별 리뷰 모델 선택** — `review.models.<cli>`로 각 외부 리뷰 CLI(codex, gemini 등)가 플래너/실행 프로파일과 독립적으로 자체 모델을 선택할 수 있음.
-- **4개의 새 런타임** — Trae, Kilo, Augment, Cline (총 12개 런타임)
+- **워크스트림 설정 상속** — `GSD_WORKSTREAM`이 설정되면 루트 `.planning/config.json`을 먼저 로드한 뒤 워크스트림 설정을 딥 머지(충돌 시 워크스트림 우선). 워크스트림 설정에서 명시적 `null`은 루트 값을 덮어씀.
+- **수동 카나리 릴리스 워크플로** — `.github/workflows/canary.yml`이 `workflow_dispatch`로 `dev` 브랜치에서 `{base}-canary.{N}` 빌드를 `@canary` dist-tag로 수동 게시(`get-shit-done-cc`와 `@gsd-build/sdk`).
+- **스킬 통합: 86 → 59** — 4개의 새로운 그룹 스킬(`capture`, `phase`, `config`, `workspace`)이 31개의 마이크로 스킬을 흡수. 기존 6개의 부모 스킬은 래퍼업/하위 동작을 플래그로 흡수: `update --sync/--reapply`, `sketch --wrap-up`, `spike --wrap-up`, `map-codebase --fast/--query`, `code-review --fix`, `progress --do/--next`. 기능 손실 없음.
 
 ---
 
@@ -594,6 +596,7 @@ lmn012o feat(08-02): create registration endpoint
 |---------|------------|
 | `/gsd-add-phase` | 로드맵에 단계 추가 |
 | `/gsd-insert-phase [N]` | 단계 사이에 긴급 작업 삽입 |
+| `/gsd-edit-phase [N] [--force]` | 기존 단계의 임의 필드를 그 자리에서 수정 — 번호와 위치는 그대로 |
 | `/gsd-remove-phase [N]` | 미래 단계 제거, 번호 재정렬 |
 | `/gsd-list-phase-assumptions [N]` | 기획 전 Claude의 의도된 접근 방식 확인 |
 | `/gsd-plan-milestone-gaps` | 감사에서 발견된 갭을 해소하기 위한 단계 생성 |

README.md

@@ -4,7 +4,7 @@
 
 **English** · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja-JP.md) · [한국어](README.ko-KR.md)
 
-**A light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Qwen Code, Cline, and CodeBuddy.**
+**A light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Qwen Code, Hermes Agent, Cline, and CodeBuddy.**
 
 **Solves context rot — the quality degradation that happens as Claude fills its context window.**
 
@@ -89,11 +89,17 @@ People who want to describe what they want and have it built correctly — witho
 
 Built-in quality gates catch real problems: schema drift detection flags ORM changes missing migrations, security enforcement anchors verification to threat models, and scope reduction detection prevents the planner from silently dropping your requirements.
 
-### v1.37.0 Highlights
+### v1.39.0 Highlights
 
-- **Spiking & sketching** — `/gsd-spike` runs 2–5 focused experiments with Given/When/Then verdicts; `/gsd-sketch` produces 2–3 interactive HTML mockup variants per design question — both store artifacts in `.planning/` and pair with wrap-up commands to package findings into project-local skills
+See the [v1.39.0 release notes](https://github.com/gsd-build/get-shit-done/releases/tag/v1.39.0) for the full list.
-- **Agent size-budget enforcement** — Tiered line-count limits (XL: 1 600, Large: 1 000, Default: 500) keep agent prompts lean; violations surface in CI
+
-- **Shared boilerplate extraction** — Mandatory-initial-read and project-skills-discovery logic extracted to reference files, reducing duplication across a dozen agents
+- **`--minimal` install profile** — alias `--core-only`, writes only the six main-loop skills (`new-project`, `discuss-phase`, `plan-phase`, `execute-phase`, `help`, `update`) and zero `gsd-*` subagents. Cuts cold-start system-prompt overhead from ~12k tokens to ~700 (≥94% reduction). Useful for local LLMs with 32K–128K context and token-billed APIs.
+- **`/gsd-edit-phase`** — modify any field of an existing phase in `ROADMAP.md` in place, without changing its number or position. `--force` skips the confirmation diff; `depends_on` references are validated and `STATE.md` is updated on write.
+- **Post-merge build & test gate** — `execute-phase` step 5.6 now auto-detects the build command from `workflow.build_command`, then falls back to Xcode (`.xcodeproj`), Makefile, Justfile, Cargo, Go, Python, or npm. Xcode/iOS projects get `xcodebuild build` + `xcodebuild test` automatically. Runs in both parallel and serial mode.
+- **Per-runtime review-model selection** — `review.models.<cli>` lets each external review CLI (codex, gemini, etc.) pick its own model independently of the planner/executor profile.
+- **Workstream config inheritance** — when `GSD_WORKSTREAM` is set, the root `.planning/config.json` is loaded first and deep-merged with the workstream config (workstream wins on conflict). Explicit `null` in a workstream config now correctly overrides a root value.
+- **Manual canary release workflow** — `.github/workflows/canary.yml` publishes `{base}-canary.{N}` builds of `get-shit-done-cc` and `@gsd-build/sdk` to the `@canary` dist-tag from `dev` on demand via `workflow_dispatch`.
+- **Skill consolidation: 86 → 59** — four new grouped skills (`capture`, `phase`, `config`, `workspace`) absorb 31 micro-skills. Six existing parents absorb wrap-up and sub-operations as flags: `update --sync/--reapply`, `sketch --wrap-up`, `spike --wrap-up`, `map-codebase --fast/--query`, `code-review --fix`, `progress --do/--next`. Zero functional loss.
 
 ---
 
@@ -104,11 +110,11 @@ npx get-shit-done-cc@latest
 ```
 
 The installer prompts you to choose:
-1. **Runtime** — Claude Code, OpenCode, Gemini, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Qwen Code, CodeBuddy, Cline, or all (interactive multi-select — pick multiple runtimes in a single install session)
+1. **Runtime** — Claude Code, OpenCode, Gemini, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Qwen Code, Hermes Agent, CodeBuddy, Cline, or all (interactive multi-select — pick multiple runtimes in a single install session)
 2. **Location** — Global (all projects) or local (current project only)
 
 Verify with:
-- Claude Code / Gemini / Copilot / Antigravity / Qwen Code: `/gsd-help`
+- Claude Code / Gemini / Copilot / Antigravity / Qwen Code / Hermes Agent: `/gsd-help`
 - OpenCode / Kilo / Augment / Trae / CodeBuddy: `/gsd-help`
 - Codex: `$gsd-help`
 - Cline: GSD installs via `.clinerules` — verify by checking `.clinerules` exists
@@ -179,6 +185,10 @@ npx get-shit-done-cc --trae --local         # Install to ./.trae/
 npx get-shit-done-cc --qwen --global        # Install to ~/.qwen/
 npx get-shit-done-cc --qwen --local         # Install to ./.qwen/
 
+# Hermes Agent
+npx get-shit-done-cc --hermes --global      # Install to ~/.hermes/ (honors $HERMES_HOME)
+npx get-shit-done-cc --hermes --local       # Install to ./.hermes/
+
 # CodeBuddy
 npx get-shit-done-cc --codebuddy --global   # Install to ~/.codebuddy/
 npx get-shit-done-cc --codebuddy --local    # Install to ./.codebuddy/
@@ -192,7 +202,7 @@ npx get-shit-done-cc --all --global      # Install to all directories
 ```
 
 Use `--global` (`-g`) or `--local` (`-l`) to skip the location prompt.
-Use `--claude`, `--opencode`, `--gemini`, `--kilo`, `--codex`, `--copilot`, `--cursor`, `--windsurf`, `--antigravity`, `--augment`, `--trae`, `--qwen`, `--codebuddy`, `--cline`, or `--all` to skip the runtime prompt.
+Use `--claude`, `--opencode`, `--gemini`, `--kilo`, `--codex`, `--copilot`, `--cursor`, `--windsurf`, `--antigravity`, `--augment`, `--trae`, `--qwen`, `--hermes`, `--codebuddy`, `--cline`, or `--all` to skip the runtime prompt.
 The GSD SDK CLI (`gsd-sdk`) is installed automatically (required by `/gsd-*` commands). Pass `--no-sdk` to skip the SDK install, or `--sdk` to force a reinstall.
 
 </details>
@@ -641,7 +651,7 @@ You're never locked in. The system adapts.
 
 | Command | What it does |
 |---------|--------------|
-| `/gsd-new-workspace` | Create isolated workspace with repo copies (worktrees or clones) |
+| `/gsd-workspace --new` | Create isolated workspace with repo copies (worktrees or clones) |
 | `/gsd-list-workspaces` | Show all GSD workspaces and their status |
 | `/gsd-remove-workspace` | Remove workspace and clean up worktrees |
 
@@ -685,9 +695,9 @@ You're never locked in. The system adapts.
 |---------|--------------|
 | `/gsd-add-phase` | Append phase to roadmap |
 | `/gsd-insert-phase [N]` | Insert urgent work between phases |
+| `/gsd-edit-phase [N] [--force]` | Modify any field of an existing phase in place — number and position unchanged |
 | `/gsd-remove-phase [N]` | Remove future phase, renumber |
 | `/gsd-list-phase-assumptions [N]` | See Claude's intended approach before planning |
-| `/gsd-plan-milestone-gaps` | Create phases to close gaps from audit |
 
 ### Session
 
@@ -729,7 +739,7 @@ You're never locked in. The system adapts.
 | `/gsd-settings` | Configure model profile and workflow agents |
 | `/gsd-set-profile <profile>` | Switch model profile (quality/balanced/budget/inherit) |
 | `/gsd-add-todo [desc]` | Capture idea for later |
-| `/gsd-check-todos` | List pending todos |
+| `/gsd-capture --list` | List pending todos |
 | `/gsd-debug [desc]` | Systematic debugging with persistent state |
 | `/gsd-do <text>` | Route freeform text to the right GSD command automatically |
 | `/gsd-note <text>` | Zero-friction idea capture — append, list, or promote notes to todos |
@@ -746,6 +756,8 @@ You're never locked in. The system adapts.
 
 GSD stores project settings in `.planning/config.json`. Configure during `/gsd-new-project` or update later with `/gsd-settings`. For the full config schema, workflow toggles, git branching options, and per-agent model breakdown, see the [User Guide](docs/USER-GUIDE.md#configuration-reference).
 
+When `GSD_WORKSTREAM` is set, GSD loads the root `.planning/config.json` first and deep-merges the workstream's `config.json` on top — workstream values win on conflict, and an explicit `null` in a workstream config overrides a root value.
+
 ### Core Settings
 
 | Setting | Options | Default | What it controls |
@@ -774,6 +786,8 @@ Use `inherit` when using non-Anthropic providers (OpenRouter, local models) or t
 
 Or configure via `/gsd-settings`.
 
+Per-runtime review-model overrides live under `review.models.<cli>` (e.g. `review.models.codex`, `review.models.gemini`) and let each external review CLI pick its own model independently of the planner/executor profile.
+
 ### Workflow Agents
 
 These spawn additional agents during planning/execution. They improve quality but add tokens and time.
@@ -789,6 +803,7 @@ These spawn additional agents during planning/execution. They improve quality bu
 | `workflow.skip_discuss` | `false` | Skip discuss-phase in autonomous mode |
 | `workflow.text_mode` | `false` | Text-only mode for remote sessions (no TUI menus) |
 | `workflow.use_worktrees` | `true` | Toggle worktree isolation for execution |
+| `workflow.build_command` | _(auto-detect)_ | Override the post-merge build gate command. Falls back to Xcode (`.xcodeproj`), Makefile, Justfile, Cargo, Go, Python, or npm; Xcode/iOS projects also run `xcodebuild test`. |
 
 Use `/gsd-settings` to toggle these, or override per-invocation:
 - `/gsd-plan-phase --skip-research`
@@ -919,6 +934,7 @@ npx get-shit-done-cc --antigravity --global --uninstall
 npx get-shit-done-cc --augment --global --uninstall
 npx get-shit-done-cc --trae --global --uninstall
 npx get-shit-done-cc --qwen --global --uninstall
+npx get-shit-done-cc --hermes --global --uninstall
 npx get-shit-done-cc --codebuddy --global --uninstall
 npx get-shit-done-cc --cline --global --uninstall
 
@@ -935,6 +951,7 @@ npx get-shit-done-cc --antigravity --local --uninstall
 npx get-shit-done-cc --augment --local --uninstall
 npx get-shit-done-cc --trae --local --uninstall
 npx get-shit-done-cc --qwen --local --uninstall
+npx get-shit-done-cc --hermes --local --uninstall
 npx get-shit-done-cc --codebuddy --local --uninstall
 npx get-shit-done-cc --cline --local --uninstall
 ```

README.pt-BR.md

@@ -73,15 +73,17 @@ Para quem quer descrever o que precisa e receber isso construído do jeito certo
 
 Quality gates embutidos capturam problemas reais: detecção de schema drift sinaliza mudanças ORM sem migrations, segurança ancora verificação a modelos de ameaça, e detecção de redução de escopo impede o planner de descartar requisitos silenciosamente.
 
-### Destaques v1.32.0
+### Destaques v1.39.0
 
-- **Gates de consistência STATE.md** — `state validate` detecta divergência entre STATE.md e o filesystem; `state sync` reconstrói a partir do estado real do projeto
+Lista completa nas [notas de release v1.39.0](https://github.com/gsd-build/get-shit-done/releases/tag/v1.39.0).
-- **Flag `--to N`** — Para a execução autônoma após completar uma fase específica
+
-- **Research gate** — Bloqueia planejamento quando RESEARCH.md tem perguntas abertas não resolvidas
+- **Perfil de instalação `--minimal`** — alias `--core-only`. Instala apenas os 6 skills do loop principal (`new-project`, `discuss-phase`, `plan-phase`, `execute-phase`, `help`, `update`) e nenhum subagente `gsd-*`. Reduz o overhead do system prompt no cold-start de ~12k para ~700 tokens (≥94% de redução). Útil para LLMs locais com contexto de 32K–128K e APIs cobradas por token.
-- **Filtro de escopo do verificador** — Lacunas abordadas em fases posteriores são marcadas como "adiadas", não como lacunas
+- **`/gsd-edit-phase`** — edita qualquer campo de uma fase existente em `ROADMAP.md` no lugar, sem alterar o número ou a posição. `--force` pula o diff de confirmação; referências em `depends_on` são validadas e o `STATE.md` é atualizado na escrita.
-- **Guard de leitura antes de edição** — Hook consultivo previne loops de retry infinitos em runtimes não-Claude
+- **Build & test gate pós-merge** — o passo 5.6 de `execute-phase` agora detecta automaticamente o comando de build em `workflow.build_command`, com fallback para Xcode (`.xcodeproj`), Makefile, Justfile, Cargo, Go, Python ou npm. Projetos Xcode/iOS rodam `xcodebuild build` e `xcodebuild test` automaticamente. Funciona em modo paralelo e serial.
-- **Redução de contexto** — Truncamento de Markdown e ordenação de prompts cache-friendly para menor uso de tokens
+- **Modelo de review por runtime** — `review.models.<cli>` permite que cada CLI externa de review (codex, gemini, etc.) escolha seu próprio modelo, independente do perfil de planner/executor.
-- **4 novos runtimes** — Trae, Kilo, Augment e Cline (12 runtimes no total)
+- **Herança de configuração de workstream** — quando `GSD_WORKSTREAM` está definido, o `.planning/config.json` raiz é carregado primeiro e merge-deep com o config da workstream (workstream vence em conflito). Um `null` explícito no config da workstream sobrescreve corretamente o valor raiz.
+- **Workflow manual de canary release** — `.github/workflows/canary.yml` publica builds `{base}-canary.{N}` de `get-shit-done-cc` e `@gsd-build/sdk` na dist-tag `@canary` a partir de `dev`, sob demanda via `workflow_dispatch`.
+- **Consolidação de skills: 86 → 59** — 4 novos skills agrupados (`capture`, `phase`, `config`, `workspace`) absorvem 31 micro-skills. 6 skills pais existentes absorvem wrap-up e sub-operações como flags: `update --sync/--reapply`, `sketch --wrap-up`, `spike --wrap-up`, `map-codebase --fast/--query`, `code-review --fix`, `progress --do/--next`. Sem perda funcional.
 
 ---
 

README.zh-CN.md

@@ -73,15 +73,17 @@ GSD 解决的就是这个问题。它是让 Claude Code 变得可靠的上下文
 
 适合那些想把自己的需求说明白，然后让系统正确构建出来的人，而不是假装自己在运营一个 50 人工程组织的人。
 
-### v1.32.0 亮点
+### v1.39.0 亮点
 
-- **STATE.md 一致性检查** — `state validate` 检测 STATE.md 与文件系统之间的偏差；`state sync` 从实际项目状态重建
+完整列表请参阅 [v1.39.0 发行说明](https://github.com/gsd-build/get-shit-done/releases/tag/v1.39.0)。
-- **`--to N` 标志** — 在完成特定阶段后停止自主执行
+
-- **研究门控** — 当 RESEARCH.md 有未解决的开放问题时阻止规划
+- **`--minimal` 安装档** — 别名 `--core-only`。仅安装主循环的 6 个核心技能（`new-project`、`discuss-phase`、`plan-phase`、`execute-phase`、`help`、`update`），不安装任何 `gsd-*` 子代理。将冷启动系统提示开销从 ~12k token 降至 ~700 token（≥94% 减少）。适合 32K–128K 上下文的本地 LLM 和按 token 计费的 API。
-- **验证里程碑范围过滤** — 后续阶段将处理的差距标记为"延迟"而非差距
+- **`/gsd-edit-phase`** — 就地修改 `ROADMAP.md` 中已有阶段的任意字段，不改变其编号或位置。`--force` 跳过确认 diff，验证 `depends_on` 引用，并在写入时更新 `STATE.md`。
-- **读取后编辑保护** — 咨询性 hook 防止非 Claude 运行时的无限重试循环
+- **合并后构建与测试门** — `execute-phase` 步骤 5.6 优先自动检测 `workflow.build_command` 配置，否则按 Xcode（`.xcodeproj`）、Makefile、Justfile、Cargo、Go、Python、npm 顺序回退。Xcode/iOS 项目自动运行 `xcodebuild build` 和 `xcodebuild test`。在并行与串行模式下均生效。
-- **上下文缩减** — Markdown 截断和缓存友好的 prompt 排序，降低 token 使用量
+- **每运行时评审模型选择** — `review.models.<cli>` 让每个外部评审 CLI（codex、gemini 等）独立于规划/执行档选择自己的模型。
-- **4 个新运行时** — Trae、Kilo、Augment 和 Cline（共 12 个运行时）
+- **工作流设置继承** — 设置 `GSD_WORKSTREAM` 后，先加载根 `.planning/config.json`，再与该工作流的配置进行深合并（冲突时工作流优先）。工作流配置中显式 `null` 会覆盖根值。
+- **手动 canary 发布工作流** — `.github/workflows/canary.yml` 通过 `workflow_dispatch` 从 `dev` 分支按需将 `{base}-canary.{N}` 构建（`get-shit-done-cc` 与 `@gsd-build/sdk`）发布到 `@canary` dist-tag。
+- **技能整合：86 → 59** — 4 个新分组技能（`capture`、`phase`、`config`、`workspace`）吸收了 31 个微技能。6 个已有父技能将收尾与子操作合并为标志：`update --sync/--reapply`、`sketch --wrap-up`、`spike --wrap-up`、`map-codebase --fast/--query`、`code-review --fix`、`progress --do/--next`。功能无损失。
 
 ---
 
@@ -589,6 +591,7 @@ lmn012o feat(08-02): create registration endpoint
 |------|------|
 | `/gsd-add-phase` | 在路线图末尾追加 phase |
 | `/gsd-insert-phase [N]` | 在 phase 之间插入紧急工作 |
+| `/gsd-edit-phase [N] [--force]` | 就地修改已有 phase 的任意字段 — 编号与位置保持不变 |
 | `/gsd-remove-phase [N]` | 删除未来 phase，并重编号 |
 | `/gsd-list-phase-assumptions [N]` | 在规划前查看 Claude 打算采用的方案 |
 | `/gsd-plan-milestone-gaps` | 为 audit 发现的缺口创建 phase |

VERSIONING.md

@@ -67,15 +67,38 @@ main                              ← stable, always deployable
 
 ### Patch Release (Hotfix)
 
-For critical bugs that can't wait for the next minor release.
+For fixes that need to ship without waiting for the next minor.
 
-1. Trigger `hotfix.yml` with version (e.g., `1.27.1`)
+A hotfix `vX.YY.Z` cumulatively includes everything in `vX.YY.{Z-1}` plus every `fix:`/`chore:` commit landed on `main` since that base. The base tag is the anchor — `git cherry $BASE_TAG main` reveals exactly which commits are still unshipped, and the new `vX.YY.Z` tag becomes the next hotfix's base, so the cycle is self-documenting.
-2. Workflow creates `hotfix/1.27.1` branch from the latest patch tag for that minor version (e.g., `v1.27.0` or `v1.27.1`)
+
-3. Cherry-pick or apply fix on the hotfix branch
+#### Two paths
-4. Push — CI runs tests automatically
+
-5. Trigger `hotfix.yml` finalize action
+**Path A — `hotfix.yml` (canonical, two-step):**
-6. Workflow runs full test suite, bumps version, tags, publishes to `latest`
+
-7. Merge hotfix branch back to main
+1. Trigger `hotfix.yml` with `action=create`, `version=1.27.1`, `auto_cherry_pick=true` (default).
+   - Workflow detects `BASE_TAG` = highest `v1.27.*` < `v1.27.1` (so `1.27.1` branches from `v1.27.0`; `1.27.2` would branch from `v1.27.1`).
+   - Branches `hotfix/1.27.1` from `BASE_TAG`.
+   - Auto-cherry-picks every `fix:`/`chore:` commit on `origin/main` not already in the base, oldest-first. Patch-equivalents are skipped via `git cherry`. `feat:`/`refactor:` are **never** auto-included.
+   - On conflict the workflow halts with the offending SHA. Resolve manually on the branch, then re-run finalize with `auto_cherry_pick=false`.
+   - Bumps `package.json` (and `sdk/package.json`), pushes the branch, and lists every included SHA in the run summary.
+2. (Optional) push additional manual commits to `hotfix/1.27.1`.
+3. Trigger `hotfix.yml` with `action=finalize`. The workflow:
+   - Runs `install-smoke` cross-platform gate.
+   - Runs full test suite + coverage.
+   - Builds SDK, bundles `sdk-bundle/gsd-sdk.tgz` inside the CC tarball (parity with `release-sdk.yml`).
+   - Tags `v1.27.1`, publishes to `@latest`, re-points `@next → v1.27.1`.
+   - Opens merge-back PR against `main`.
+
+**Path B — `release-sdk.yml` (stopgap, one-shot):**
+
+Active while the `@gsd-build/sdk` npm token is unavailable; bundles the SDK inside the CC tarball.
+
+1. Trigger `release-sdk.yml` with `action=hotfix`, `version=1.27.1`, `auto_cherry_pick=true`.
+   - The `prepare` job creates the branch and cherry-picks (same logic as Path A).
+   - `install-smoke` runs against the new branch.
+   - The `release` job tags, publishes to `@latest`, re-points `@next`, opens merge-back PR.
+   - Idempotent: if `hotfix/1.27.1` already exists (e.g. you ran `hotfix.yml create` first), the prepare job checks it out and re-runs cherry-pick as a no-op.
+2. `dry_run=true` exercises the full pipeline without pushing the branch or publishing.
 
 ### Minor Release (Standard Cycle)
 

agents/gsd-code-fixer.md

@@ -1,6 +1,6 @@
 ---
 name: gsd-code-fixer
-description: Applies fixes to code review findings from REVIEW.md. Reads source files, applies intelligent fixes, and commits each fix atomically. Spawned by /gsd-code-review-fix.
+description: Applies fixes to code review findings from REVIEW.md. Reads source files, applies intelligent fixes, and commits each fix atomically. Spawned by /gsd-code-review --fix.
 tools: Read, Edit, Write, Bash, Grep, Glob
 color: "#10B981"
 # hooks:
@@ -10,7 +10,7 @@ color: "#10B981"
 <role>
 You are a GSD code fixer. You apply fixes to issues found by the gsd-code-reviewer agent.
 
-Spawned by `/gsd-code-review-fix` workflow. You produce REVIEW-FIX.md artifact in the phase directory.
+Spawned by `/gsd-code-review --fix` workflow. You produce REVIEW-FIX.md artifact in the phase directory.
 
 Your job: Read REVIEW.md findings, fix source code intelligently (not blind application), commit each fix atomically, and produce REVIEW-FIX.md report.
 
@@ -214,32 +214,145 @@ If a finding references multiple files (in Fix section or Issue section):
 
 This agent runs as a background process that makes commits. Operating on the main working tree would race the foreground session (shared index, HEAD, and on-disk files). Instead, every instance runs in its own isolated worktree.
 
+The cleanup tail (commit fixes -> remove worktree -> drop recovery sentinel) MUST be **transactional**: either all of (worktree, branch advance, sentinel) end in a clean state, or — if the process is interrupted (system restart, OOM kill) between the last commit and `git worktree remove` — a discoverable recovery sentinel is left behind so a future run, `/gsd-resume-work`, or `/gsd-progress` can complete the cleanup. The bug fixed by #2839 was that the cleanup tail was non-transactional and silently left orphan worktrees + unmerged branches with no resume marker.
+
 ```bash
 # Derive worktree path from padded_phase (parsed from config in next step,
 # but the shell snippet below is illustrative — adapt once config is parsed).
 # In practice: parse padded_phase from config first, then run:
 branch=$(git branch --show-current)
 test -n "$branch" || { echo "Detached HEAD is not supported for review-fix (#2686)"; exit 1; }
+
+# Recovery-sentinel handling (#2839):
+# Path is ${phase_dir}/.review-fix-recovery-pending.json. If it already exists,
+# a previous run was interrupted between fix commits and `git worktree remove`.
+# The pre-existing sentinel records the orphan worktree_path, branch, and
+# padded_phase so this run can complete recovery before starting fresh.
+sentinel="${phase_dir}/.review-fix-recovery-pending.json"
+if [ -f "$sentinel" ]; then
+  echo "Detected pre-existing recovery sentinel from a prior interrupted run: $sentinel"
+  # Recovery must extract BOTH worktree_path AND reviewfix_branch (#3001 CR):
+  # if a prior run died after `git worktree remove` but before
+  # `git branch -D`, the orphan branch survives and clutters `git branch`
+  # output forever. Emit both fields newline-separated so we can read them
+  # independently.
+  prior_recovery=$(node -e '
+    const fs = require("fs");
+    try {
+      const parsed = JSON.parse(fs.readFileSync(process.argv[1], "utf-8"));
+      process.stdout.write((parsed.worktree_path || "") + "\n" + (parsed.reviewfix_branch || ""));
+    } catch (err) {
+      process.stderr.write(`Warning: malformed recovery sentinel ${process.argv[1]}: ${err.message}\n`);
+      process.stdout.write("\n");
+    }
+  ' "$sentinel")
+  prior_wt="$(printf '%s' "$prior_recovery" | sed -n '1p')"
+  prior_branch="$(printf '%s' "$prior_recovery" | sed -n '2p')"
+  if [ -n "$prior_wt" ] && git worktree list --porcelain | grep -q "^worktree $prior_wt$"; then
+    echo "Removing orphan worktree from prior run: $prior_wt"
+    git worktree remove "$prior_wt" --force || true
+  fi
+  if [ -n "$prior_branch" ]; then
+    # Best-effort: branch may already be gone (cleaned by an earlier
+    # partial recovery, or never created if `git worktree add -b` itself
+    # failed). `|| true` keeps recovery non-fatal.
+    echo "Removing orphan reviewfix branch from prior run: $prior_branch"
+    git branch -D "$prior_branch" 2>/dev/null || true
+  fi
+  rm -f "$sentinel"
+fi
+
 wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")
-git worktree add "$wt" "$branch"
+
+# Create a temp branch from the current branch tip so the worktree
+# attaches to that NEW branch rather than the user's currently-checked-out
+# branch (#2990: git refuses to check out the same branch in two
+# worktrees by default; the original `git worktree add "$wt" "$branch"`
+# failed before the agent could do any work). The temp branch shares
+# history with $branch up to the moment of creation, so commits made
+# inside the worktree fast-forward $branch on cleanup.
+reviewfix_branch="gsd-reviewfix/${padded_phase}-$$"
+git worktree add -b "$reviewfix_branch" "$wt" "$branch"
+
+# Write the recovery sentinel ONLY AFTER `git worktree add` succeeds.
+# Writing it before would leave a sentinel pointing at a worktree that does
+# not exist if `git worktree add` itself failed.
+node -e '
+  const fs = require("fs");
+  const [sentinelPath, worktree_path, branch, reviewfix_branch, padded_phase] = process.argv.slice(1);
+  fs.writeFileSync(sentinelPath, JSON.stringify({
+    worktree_path,
+    branch,
+    reviewfix_branch,
+    padded_phase,
+    started_at: new Date().toISOString()
+  }, null, 2));
+' "$sentinel" "$wt" "$branch" "$reviewfix_branch" "$padded_phase"
+
 cd "$wt"
 ```
 
 Concrete steps:
-1. Parse `padded_phase` from the `<config>` block (needed for the path).
+1. Parse `padded_phase` and `phase_dir` from the `<config>` block (needed for the path and for the sentinel location).
 2. Resolve the current branch: `branch=$(git branch --show-current)`. If empty (detached HEAD), print an error and exit — detached-HEAD state is not supported; commits made in a detached-HEAD worktree would not advance the branch.
-3. Create a unique worktree path: `wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")`. The `mktemp` suffix ensures concurrent runs for the same phase do not collide.
+3. **Recovery check (#2839, #2990):** If `${phase_dir}/.review-fix-recovery-pending.json` already exists, a prior run was interrupted. Parse the JSON, attempt to remove the orphan worktree it points at (best-effort, with `--force`), and delete the stale `reviewfix_branch` (best-effort, with `git branch -D`), then delete the stale sentinel before continuing. This makes a re-run of `/gsd-code-review --fix` self-healing.
-4. Run `git worktree add "$wt" "$branch"` — this attaches the worktree to the current branch so commits advance it.
+4. Create a unique worktree path: `wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")`. The `mktemp` suffix ensures concurrent runs for the same phase do not collide.
-5. All subsequent file reads, edits, and commits happen inside `$wt`.
+5. Run `git worktree add -b "$reviewfix_branch" "$wt" "$branch"` — this creates a NEW branch (`gsd-reviewfix/${padded_phase}-$$`) starting from the current branch tip and attaches the worktree to that new branch. Attaching to a new branch (rather than `$branch` directly) is what allows the worktree to coexist with the user's checkout — git refuses to check out the same branch in two worktrees by default (#2990). Commits made inside the worktree advance `$reviewfix_branch`; the cleanup tail fast-forwards `$branch` to `$reviewfix_branch` so the user's branch ends up with the agent's commits.
+6. **Write the recovery sentinel** at `${phase_dir}/.review-fix-recovery-pending.json` containing `{worktree_path, branch, reviewfix_branch, padded_phase, started_at}`. Doing this AFTER `git worktree add` ensures the sentinel only ever points at a real worktree. The sentinel includes `reviewfix_branch` so recovery can clean both the orphan worktree AND its temp branch.
+7. All subsequent file reads, edits, and commits happen inside `$wt` (which is on `$reviewfix_branch`, not `$branch`).
 
-**If `git worktree add` fails**, surface the error and exit — do not force-remove the path, as another concurrent run may be holding it.
+**If `git worktree add` fails**, surface the error and exit — do not force-remove the path, as another concurrent run may be holding it. Do not write the sentinel (the worktree does not exist). Do not delete `$reviewfix_branch` either; if `-b` failed, no temp branch was created.
+
+**Cleanup tail (transactional, ALWAYS — even on failure):** After writing REVIEW-FIX.md and before returning to the orchestrator, run the cleanup in this exact order:
 
-**Cleanup (ALWAYS — even on failure):** After writing REVIEW-FIX.md and before returning to the orchestrator, run:
 ```bash
+# Step 1 (#2990): fast-forward $branch to capture the commits the agent
+# made on $reviewfix_branch. Run from the main repo (not $wt) — the user's
+# checkout owns $branch. --ff-only ensures we never silently drop or
+# rewrite history if the user committed to $branch concurrently; on
+# divergence, this fails loudly and the temp branch is left for the
+# user to inspect/merge manually. We deliberately resolve the main repo
+# path via `git worktree list --porcelain` rather than assuming $PWD,
+# because the agent ran inside $wt.
+# Strip the literal "worktree " prefix and print the rest of the line, then
+# exit on the first match. This preserves paths that contain spaces
+# (awk '$2' would truncate "/path/with spaces/repo" to "/path/with").
+main_repo="$(git worktree list --porcelain | awk '/^worktree / { sub(/^worktree /, ""); print; exit }')"
+ff_status=0
+# Capture the exit code of `git merge` directly. `if ! cmd; then ff_status=$?`
+# captures the exit code of the `!` operator (always 1 when the inner cmd
+# failed) — masking the real merge exit code. Use the success/else split
+# instead so $? in the else-branch is the merge command's exit code.
+if git -C "$main_repo" merge --ff-only "$reviewfix_branch" 2>&1; then
+  ff_status=0
+else
+  ff_status=$?
+  echo "WARN: could not fast-forward $branch to $reviewfix_branch (exit $ff_status)."
+  echo "      The temp branch $reviewfix_branch is preserved for manual merge."
+fi
+
+# Step 2: drop the worktree. If this succeeds and the process is then
+# killed, the next run finds a sentinel pointing at a worktree that no
+# longer exists — the recovery branch handles this gracefully (best-effort
+# remove + sentinel delete). If we reversed the order (sentinel removed
+# first, then worktree remove), an interruption between the two steps
+# would leave NO sentinel and an orphan worktree — exactly the bug from
+# #2839.
 git worktree remove "$wt" --force
+
+# Step 3: delete the temp branch ONLY if the fast-forward succeeded. If
+# it didn't, leaving the branch lets the user inspect/merge manually.
+if [ "$ff_status" -eq 0 ]; then
+  git -C "$main_repo" branch -D "$reviewfix_branch" || true
+fi
+
+# Step 4: drop the recovery sentinel ONLY after `git worktree remove`
+# returns successfully. This atomic-ish ordering is what makes the
+# cleanup tail transactional from the orchestrator's perspective.
+rm -f "$sentinel"
 ```
 
-This cleanup is unconditional — register it mentally as a finally-block obligation. If the agent exits early (config error, no findings, etc.), still run `git worktree remove "$wt" --force` before exit.
+This cleanup is unconditional — register it mentally as a finally-block obligation. If the agent exits early (config error, no findings, etc.), still run the cleanup tail in order (fast-forward → worktree remove → temp branch delete → sentinel rm) before exit. The sentinel must NEVER be removed before `git worktree remove` succeeds. The temp branch must NEVER be deleted while the fast-forward is in a diverged state.
 </step>
 
 <step name="load_context">
@@ -471,7 +584,9 @@ _Iteration: {N}_
 
 <critical_rules>
 
-**ALWAYS run inside the isolated worktree** — set up via `branch=$(git branch --show-current)` + `wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")` + `git worktree add "$wt" "$branch"` at the very start (see `setup_worktree` step). Using `mktemp` ensures concurrent runs do not collide. Attaching to `$branch` (not `HEAD`) ensures commits advance the branch. Every file read, edit, and commit must happen inside `$wt`. Run `git worktree remove "$wt" --force` unconditionally when done (treat it as a finally block). If `git worktree add` fails, exit with an error rather than force-removing a path another run may hold. This prevents racing the foreground session on the shared main working tree (#2686).
+**ALWAYS run inside the isolated worktree** — set up via `branch=$(git branch --show-current)` + `wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")` + `git worktree add -b "$reviewfix_branch" "$wt" "$branch"` at the very start (see `setup_worktree` step). Using `mktemp` ensures concurrent runs do not collide. Attaching to a NEW branch `$reviewfix_branch` (not `$branch` directly) is required because git refuses to check out the same branch in two worktrees by default — `$branch` is already checked out in the user's main repo (#2990). Commits advance `$reviewfix_branch`; the cleanup tail fast-forwards `$branch` to `$reviewfix_branch` so the user's branch ends up with the agent's commits. Every file read, edit, and commit must happen inside `$wt`. Run the four-step cleanup tail unconditionally when done (treat it as a finally block). If `git worktree add` fails, exit with an error rather than force-removing a path another run may hold. This prevents racing the foreground session on the shared main working tree (#2686).
+
+**ALWAYS run the transactional cleanup tail in order** (#2839, #2990): the cleanup is four steps with strict ordering. (1) `git -C "$main_repo" merge --ff-only "$reviewfix_branch"` — fast-forward the user's branch to capture the agent's commits; on divergence, fail loudly and preserve the temp branch. (2) `git worktree remove "$wt" --force`. (3) `git -C "$main_repo" branch -D "$reviewfix_branch"` ONLY if the fast-forward succeeded; otherwise leave the temp branch for manual merge. (4) `rm -f "$sentinel"` (the recovery sentinel at `${phase_dir}/.review-fix-recovery-pending.json`). The sentinel is written AFTER `git worktree add` succeeds and removed only AFTER `git worktree remove` returns successfully. The temp branch is deleted only when the fast-forward succeeded. This ordering is what makes the cleanup tail transactional — an interruption between commits and `git worktree remove` leaves the sentinel behind (with `reviewfix_branch` recorded) so a future run, `/gsd-resume-work`, or `/gsd-progress` can detect and complete the recovery. Reversing the order recreates the orphan-worktree bug.
 
 **ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
 

agents/gsd-executor.md

@@ -358,6 +358,30 @@ If RED or GREEN gate commits are missing, add a warning to SUMMARY.md under a `#
 <task_commit_protocol>
 After each task completes (verification passed, done criteria met), commit immediately.
 
+**0. Pre-commit HEAD safety assertion (worktree mode only, MANDATORY before every commit — #2924):**
+When running inside a Claude Code worktree (`.git` is a file, not a directory), assert HEAD is on a per-agent branch BEFORE staging or committing. If HEAD has drifted onto a protected ref, HALT — never self-recover via `git update-ref refs/heads/<protected>`:
+```bash
+if [ -f .git ]; then  # worktree
+  HEAD_REF=$(git symbolic-ref --quiet HEAD || echo "DETACHED")
+  ACTUAL_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+  # Deny-list: never commit on a protected ref.
+  if [ "$HEAD_REF" = "DETACHED" ] || \
+     echo "$ACTUAL_BRANCH" | grep -Eq '^(main|master|develop|trunk|release/.*)$'; then
+    echo "FATAL: refusing to commit — worktree HEAD is on '$ACTUAL_BRANCH' (expected per-agent branch)." >&2
+    echo "DO NOT use 'git update-ref' to rewind the protected branch — surface as blocker (#2924)." >&2
+    exit 1
+  fi
+  # Positive allow-list: HEAD must be on the canonical Claude Code worktree-agent
+  # branch namespace (`worktree-agent-<id>`). This catches feature/* and any other
+  # arbitrary branch that the deny-list would silently allow (#2924).
+  if ! echo "$ACTUAL_BRANCH" | grep -Eq '^worktree-agent-[A-Za-z0-9._/-]+$'; then
+    echo "FATAL: refusing to commit — worktree HEAD '$ACTUAL_BRANCH' is not in the worktree-agent-* namespace." >&2
+    echo "Agent commits must live on per-agent branches; surface as blocker (#2924)." >&2
+    exit 1
+  fi
+fi
+```
+
 **1. Check modified files:** `git status --short`
 
 **2. Stage task-related files individually** (NEVER `git add .` or `git add -A`):
@@ -426,6 +450,15 @@ back, those deletions appear on the main branch, destroying prior-wave work (#20
 - `git rm` on files not explicitly created by the current task
 - `git checkout -- .` or `git restore .` (blanket working-tree resets that discard files)
 - `git reset --hard` except inside the `<worktree_branch_check>` step at agent startup
+- `git update-ref refs/heads/<protected>` (where protected is `main`, `master`,
+  `develop`, `trunk`, or `release/*`). This is an absolute prohibition (#2924).
+  If you discover that your worktree HEAD is attached to a protected branch and your
+  commits landed there, **DO NOT** "recover" by force-rewinding the protected ref —
+  that silently destroys concurrent commits in multi-active scenarios (parallel
+  agents, user committing while you run). HALT and surface a blocker. The setup-time
+  `<worktree_branch_check>` and per-commit `<pre_commit_head_assertion>` are the
+  correct prevention; if either fails, the workflow MUST stop, not self-heal.
+- `git push --force` / `git push -f` to any branch you did not create.
 
 If you need to discard changes to a specific file you modified during this task, use:
 ```bash

commands/gsd/add-backlog.md

@@ -1,79 +0,0 @@
----
-name: gsd:add-backlog
-description: Add an idea to the backlog parking lot (999.x numbering)
-argument-hint: <description>
-allowed-tools:
-  - Read
-  - Write
-  - Bash
----
-
-<objective>
-Add a backlog item to the roadmap using 999.x numbering. Backlog items are
-unsequenced ideas that aren't ready for active planning — they live outside
-the normal phase sequence and accumulate context over time.
-</objective>
-
-<process>
-
-1. **Read ROADMAP.md** to find existing backlog entries:
-   ```bash
-   cat .planning/ROADMAP.md
-   ```
-
-2. **Find next backlog number:**
-   ```bash
-   NEXT=$(gsd-sdk query phase.next-decimal 999 --raw)
-   ```
-   If no 999.x phases exist, start at 999.1.
-
-3. **Add to ROADMAP.md** under a `## Backlog` section. If the section doesn't exist, create it at the end.
-   Write the ROADMAP entry BEFORE creating the directory — this ensures directory existence is always
-   a reliable indicator that the phase is already registered, which prevents false duplicate detection
-   in any hook that checks for existing 999.x directories (#2280):
-
-   ```markdown
-   ## Backlog
-
-   ### Phase {NEXT}: {description} (BACKLOG)
-
-   **Goal:** [Captured for future planning]
-   **Requirements:** TBD
-   **Plans:** 0 plans
-
-   Plans:
-   - [ ] TBD (promote with /gsd-review-backlog when ready)
-   ```
-
-4. **Create the phase directory:**
-   ```bash
-   SLUG=$(gsd-sdk query generate-slug "$ARGUMENTS" --raw)
-   mkdir -p ".planning/phases/${NEXT}-${SLUG}"
-   touch ".planning/phases/${NEXT}-${SLUG}/.gitkeep"
-   ```
-
-5. **Commit:**
-   ```bash
-   gsd-sdk query commit "docs: add backlog item ${NEXT} — ${ARGUMENTS}" --files .planning/ROADMAP.md ".planning/phases/${NEXT}-${SLUG}/.gitkeep"
-   ```
-
-6. **Report:**
-   ```
-   ## 📋 Backlog Item Added
-
-   Phase {NEXT}: {description}
-   Directory: .planning/phases/{NEXT}-{slug}/
-
-   This item lives in the backlog parking lot.
-   Use /gsd-discuss-phase {NEXT} to explore it further.
-   Use /gsd-review-backlog to promote items to active milestone.
-   ```
-
-</process>
-
-<notes>
-- 999.x numbering keeps backlog items out of the active phase sequence
-- Phase directories are created immediately, so /gsd-discuss-phase and /gsd-plan-phase work on them
-- No `Depends on:` field — backlog items are unsequenced by definition
-- Sparse numbering is fine (999.1, 999.3) — always uses next-decimal
-</notes>

commands/gsd/add-phase.md

@@ -1,43 +0,0 @@
----
-name: gsd:add-phase
-description: Add phase to end of current milestone in roadmap
-argument-hint: <description>
-allowed-tools:
-  - Read
-  - Write
-  - Bash
----
-
-<objective>
-Add a new integer phase to the end of the current milestone in the roadmap.
-
-Routes to the add-phase workflow which handles:
-- Phase number calculation (next sequential integer)
-- Directory creation with slug generation
-- Roadmap structure updates
-- STATE.md roadmap evolution tracking
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/add-phase.md
-</execution_context>
-
-<context>
-Arguments: $ARGUMENTS (phase description)
-
-Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls.
-</context>
-
-<process>
-**Follow the add-phase workflow** from `@~/.claude/get-shit-done/workflows/add-phase.md`.
-
-The workflow handles all logic including:
-1. Argument parsing and validation
-2. Roadmap existence checking
-3. Current milestone identification
-4. Next phase number calculation (ignoring decimals)
-5. Slug generation from description
-6. Phase directory creation
-7. Roadmap entry insertion
-8. STATE.md updates
-</process>

commands/gsd/add-todo.md

@@ -1,47 +0,0 @@
----
-name: gsd:add-todo
-description: Capture idea or task as todo from current conversation context
-argument-hint: [optional description]
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - AskUserQuestion
----
-
-<objective>
-Capture an idea, task, or issue that surfaces during a GSD session as a structured todo for later work.
-
-Routes to the add-todo workflow which handles:
-- Directory structure creation
-- Content extraction from arguments or conversation
-- Area inference from file paths
-- Duplicate detection and resolution
-- Todo file creation with frontmatter
-- STATE.md updates
-- Git commits
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/add-todo.md
-</execution_context>
-
-<context>
-Arguments: $ARGUMENTS (optional todo description)
-
-State is resolved in-workflow via `init todos` and targeted reads.
-</context>
-
-<process>
-**Follow the add-todo workflow** from `@~/.claude/get-shit-done/workflows/add-todo.md`.
-
-The workflow handles all logic including:
-1. Directory ensuring
-2. Existing area checking
-3. Content extraction (arguments or conversation)
-4. Area inference
-5. Duplicate checking
-6. File creation with slug generation
-7. STATE.md updates
-8. Git commits
-</process>

commands/gsd/ai-integration-phase.md

@@ -1,6 +1,6 @@
 ---
 name: gsd:ai-integration-phase
-description: Generate AI design contract (AI-SPEC.md) for phases that involve building AI systems — framework selection, implementation guidance from official docs, and evaluation strategy
+description: Generate an AI-SPEC.md design contract for phases that involve building AI systems.
 argument-hint: "[phase number]"
 allowed-tools:
   - Read

commands/gsd/analyze-dependencies.md

@@ -1,34 +0,0 @@
----
-name: gsd:analyze-dependencies
-description: Analyze phase dependencies and suggest Depends on entries for ROADMAP.md
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-<objective>
-Analyze the phase dependency graph for the current milestone. For each phase pair, determine if there is a dependency relationship based on:
-- File overlap (phases that modify the same files must be ordered)
-- Semantic dependencies (a phase that uses an API built by another phase)
-- Data flow (a phase that consumes output from another phase)
-
-Then suggest `Depends on` updates to ROADMAP.md.
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/analyze-dependencies.md
-</execution_context>
-
-<context>
-No arguments required. Requires an active milestone with ROADMAP.md.
-
-Run this command BEFORE `/gsd-manager` to fill in missing `Depends on` fields and prevent merge conflicts from unordered parallel execution.
-</context>
-
-<process>
-Execute the analyze-dependencies workflow from @~/.claude/get-shit-done/workflows/analyze-dependencies.md end-to-end.
-Present dependency suggestions clearly and apply confirmed updates to ROADMAP.md.
-</process>

commands/gsd/capture.md

@@ -0,0 +1,62 @@
+---
+name: gsd:capture
+description: Capture ideas, tasks, notes, and seeds to their destination
+argument-hint: "[--note | --backlog | --seed | --list] [text]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Capture ideas, tasks, notes, and seeds to their appropriate destination in the GSD system.
+
+Mode routing:
+- **default** (no flag): Capture as a structured todo for later work → add-todo workflow
+- **--note**: Zero-friction idea capture (append/list/promote) → note workflow
+- **--backlog**: Add an idea to the backlog parking lot (999.x numbering) → add-backlog workflow
+- **--seed**: Capture a forward-looking idea with trigger conditions → plant-seed workflow
+- **--list**: List pending todos and select one to work on → check-todos workflow
+</objective>
+
+<routing>
+
+| Flag | Destination | Workflow |
+|------|-------------|----------|
+| (none) | Structured todo in .planning/todos/ | add-todo |
+| --note | Timestamped note file, list, or promote | note |
+| --backlog | ROADMAP.md backlog section (999.x) | add-backlog |
+| --seed | .planning/seeds/SEED-NNN-slug.md | plant-seed |
+| --list | Interactive todo browser + action router | check-todos |
+
+</routing>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/add-todo.md
+@~/.claude/get-shit-done/workflows/note.md
+@~/.claude/get-shit-done/workflows/add-backlog.md
+@~/.claude/get-shit-done/workflows/plant-seed.md
+@~/.claude/get-shit-done/workflows/check-todos.md
+@~/.claude/get-shit-done/references/ui-brand.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+
+Parse the first token of $ARGUMENTS:
+- If it is `--note`: strip the flag, pass remainder to note workflow
+- If it is `--backlog`: strip the flag, pass remainder to add-backlog workflow
+- If it is `--seed`: strip the flag, pass remainder to plant-seed workflow
+- If it is `--list`: pass remainder (optional area filter) to check-todos workflow
+- Otherwise: pass all of $ARGUMENTS to add-todo workflow
+</context>
+
+<process>
+1. Parse the leading flag (if any) from $ARGUMENTS.
+2. Load and execute the appropriate workflow end-to-end based on the routing table above.
+3. Preserve all workflow gates from the target workflow (directory structure, duplicate detection, commits, etc.).
+</process>

commands/gsd/check-todos.md

@@ -1,45 +0,0 @@
----
-name: gsd:check-todos
-description: List pending todos and select one to work on
-argument-hint: [area filter]
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - AskUserQuestion
----
-
-<objective>
-List all pending todos, allow selection, load full context for the selected todo, and route to appropriate action.
-
-Routes to the check-todos workflow which handles:
-- Todo counting and listing with area filtering
-- Interactive selection with full context loading
-- Roadmap correlation checking
-- Action routing (work now, add to phase, brainstorm, create phase)
-- STATE.md updates and git commits
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/check-todos.md
-</execution_context>
-
-<context>
-Arguments: $ARGUMENTS (optional area filter)
-
-Todo state and roadmap correlation are loaded in-workflow using `init todos` and targeted reads.
-</context>
-
-<process>
-**Follow the check-todos workflow** from `@~/.claude/get-shit-done/workflows/check-todos.md`.
-
-The workflow handles all logic including:
-1. Todo existence checking
-2. Area filtering
-3. Interactive listing and selection
-4. Full context loading with file summaries
-5. Roadmap correlation checking
-6. Action offering and execution
-7. STATE.md updates
-8. Git commits
-</process>

commands/gsd/code-review-fix.md

@@ -1,52 +0,0 @@
----
-name: gsd:code-review-fix
-description: Auto-fix issues found by code review in REVIEW.md. Spawns fixer agent, commits each fix atomically, produces REVIEW-FIX.md summary.
-argument-hint: "<phase-number> [--all] [--auto]"
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
-  - Write
-  - Edit
-  - Task
----
-<objective>
-Auto-fix issues found by code review. Reads REVIEW.md from the specified phase, spawns gsd-code-fixer agent to apply fixes, and produces REVIEW-FIX.md summary.
-
-Arguments:
-- Phase number (required) — which phase's REVIEW.md to fix (e.g., "2" or "02")
-- `--all` (optional) — include Info findings in fix scope (default: Critical + Warning only)
-- `--auto` (optional) — enable fix + re-review iteration loop, capped at 3 iterations
-
-Output: {padded_phase}-REVIEW-FIX.md in phase directory + inline summary of fixes applied
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/code-review-fix.md
-</execution_context>
-
-<context>
-Phase: $ARGUMENTS (first positional argument is phase number)
-
-Optional flags parsed from $ARGUMENTS:
-- `--all` — Include Info findings in fix scope. Default behavior fixes Critical + Warning only.
-- `--auto` — Enable fix + re-review iteration loop. After applying fixes, re-run code-review at same depth. If new issues found, iterate. Cap at 3 iterations total. Without this flag, single fix pass only.
-
-Context files (CLAUDE.md, REVIEW.md, phase state) are resolved inside the workflow via `gsd-sdk query init.phase-op` and delegated to agent via config blocks.
-</context>
-
-<process>
-This command is a thin dispatch layer. It parses arguments and delegates to the workflow.
-
-Execute the code-review-fix workflow from @~/.claude/get-shit-done/workflows/code-review-fix.md end-to-end.
-
-The workflow (not this command) enforces these gates:
-- Phase validation (before config gate)
-- Config gate check (workflow.code_review)
-- REVIEW.md existence check (error if missing)
-- REVIEW.md status check (skip if clean/skipped)
-- Agent spawning (gsd-code-fixer)
-- Iteration loop (if --auto, capped at 3 iterations)
-- Result presentation (inline summary + next steps)
-</process>

commands/gsd/code-review.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:code-review
 description: Review source files changed during a phase for bugs, security issues, and code quality problems
-argument-hint: "<phase-number> [--depth=quick|standard|deep] [--files file1,file2,...]"
+argument-hint: "<phase-number> [--depth=quick|standard|deep] [--files file1,file2,...] [--fix [--all] [--auto]]"
 allowed-tools:
   - Read
   - Bash
@@ -22,6 +22,9 @@ Arguments:
   - standard: Per-file analysis with language-specific checks (~5-15 min, default)
   - deep: Cross-file analysis including import graphs and call chains (~15-30 min)
 - `--files file1,file2,...` (optional) — explicit comma-separated file list, skips SUMMARY/git scoping (highest precedence for scoping)
+- `--fix` (optional) — after review completes (or if REVIEW.md already exists), auto-apply fixes found. Spawns gsd-code-fixer agent. Accepts sub-flags:
+  - `--all` — include Info findings in fix scope (default: Critical + Warning only)
+  - `--auto` — enable fix + re-review iteration loop, capped at 3 iterations
 
 Output: {padded_phase}-REVIEW.md in phase directory + inline summary of findings
 </objective>

commands/gsd/complete-milestone.md

@@ -43,7 +43,10 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
 
    - Look for `.planning/v{{version}}-MILESTONE-AUDIT.md`
    - If missing or stale: recommend `/gsd-audit-milestone` first
-   - If audit status is `gaps_found`: recommend `/gsd-plan-milestone-gaps` first
+   - If audit status is `gaps_found`: recommend closing the gaps inline
+     (the audit output already enumerates them — insert closure phases
+     via `/gsd-phase --insert <N>` plus the standard
+     discuss/plan/execute chain) before proceeding.
    - If audit status is `passed`: proceed to step 1
 
    ```markdown
@@ -54,8 +57,11 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
    requirements coverage, cross-phase integration, and E2E flows.
 
    {If audit has gaps:}
-   ⚠ Milestone audit found gaps. Run `/gsd-plan-milestone-gaps` to create
+   ⚠ Milestone audit found gaps. The audit output already enumerates the
-   phases that close the gaps, or proceed anyway to accept as tech debt.
+   unsatisfied requirements, cross-phase issues, and broken flows — insert
+   a closure phase per gap with `/gsd-phase --insert <N>` and run the
+   standard `/gsd-discuss-phase` → `/gsd-plan-phase` → `/gsd-execute-phase`
+   chain. Or proceed anyway to accept the gaps as tech debt.
 
    {If audit passed:}
    ✓ Milestone audit passed. Proceeding with completion.

commands/gsd/config.md

@@ -0,0 +1,57 @@
+---
+name: gsd:config
+description: Configure GSD settings — workflow toggles, advanced knobs, integrations, and model profile
+argument-hint: "[--advanced | --integrations | --profile <name>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Configure GSD settings interactively with a single consolidated command.
+
+Mode routing:
+- **default** (no flag): Common-case toggles (model, research, plan_check, verifier, branching) → settings workflow
+- **--advanced**: Power-user knobs (planning tuning, timeouts, branch templates, cross-AI execution) → settings-advanced workflow
+- **--integrations**: Third-party API keys, code-review CLI routing, agent-skill injection → settings-integrations workflow
+- **--profile <name>**: Switch model profile (quality|balanced|budget|inherit) → set-profile (inline)
+</objective>
+
+<routing>
+
+| Flag | Action | Workflow |
+|------|--------|----------|
+| (none) | Interactive 5-question common-case config prompt | settings |
+| --advanced | Power-user knobs: planning, execution, discussion, cross-AI, git, runtime | settings-advanced |
+| --integrations | API keys (Brave/Firecrawl/Exa), review CLI routing, agent skills | settings-integrations |
+| --profile &lt;name&gt; | Switch model profile without interactive prompt | gsd-sdk config-set-model-profile |
+
+</routing>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/settings.md
+@~/.claude/get-shit-done/workflows/settings-advanced.md
+@~/.claude/get-shit-done/workflows/settings-integrations.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+
+Parse the first token of $ARGUMENTS:
+- If it is `--advanced`: strip the flag, execute settings-advanced workflow
+- If it is `--integrations`: strip the flag, execute settings-integrations workflow
+- If it starts with `--profile`: extract the profile name (remainder after `--profile`), then:
+  1. **Pre-flight check (#2439):** verify `gsd-sdk` is on PATH via `command -v gsd-sdk`.
+     If absent, emit the install hint `Install GSD via 'npm i -g get-shit-done'` and stop —
+     do NOT invoke `gsd-sdk` directly (avoids the opaque `command not found: gsd-sdk` failure).
+  2. Run: `gsd-sdk query config-set-model-profile <profile-name> --raw` and display the output verbatim.
+- Otherwise: execute settings workflow (no argument needed)
+</context>
+
+<process>
+1. Parse the leading flag (if any) from $ARGUMENTS.
+2. Load and execute the appropriate workflow end-to-end, or run the inline SDK command for --profile.
+3. Preserve all workflow gates from the target workflow.
+</process>

commands/gsd/discuss-phase.md

@@ -1,6 +1,6 @@
 ---
 name: gsd:discuss-phase
-description: Gather phase context through adaptive questioning before planning. Use --all to skip area selection and discuss all gray areas interactively. Use --auto to skip interactive questions (Claude picks recommended defaults). Use --chain for interactive discuss followed by automatic plan+execute. Use --power for bulk question generation into a file-based UI (answer at your own pace).
+description: Gather phase context through adaptive questioning before planning.
 argument-hint: "<phase> [--all] [--auto] [--chain] [--batch] [--analyze] [--text] [--power]"
 allowed-tools:
   - Read

commands/gsd/do.md

@@ -1,30 +0,0 @@
----
-name: gsd:do
-description: Route freeform text to the right GSD command automatically
-argument-hint: "<description of what you want to do>"
-allowed-tools:
-  - Read
-  - Bash
-  - AskUserQuestion
----
-<objective>
-Analyze freeform natural language input and dispatch to the most appropriate GSD command.
-
-Acts as a smart dispatcher — never does the work itself. Matches intent to the best GSD command using routing rules, confirms the match, then hands off.
-
-Use when you know what you want but don't know which `/gsd-*` command to run.
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/do.md
-@~/.claude/get-shit-done/references/ui-brand.md
-</execution_context>
-
-<context>
-$ARGUMENTS
-</context>
-
-<process>
-Execute the do workflow from @~/.claude/get-shit-done/workflows/do.md end-to-end.
-Route user intent to the best GSD command and invoke it.
-</process>

commands/gsd/edit-phase.md

@@ -1,35 +0,0 @@
----
-name: gsd:edit-phase
-description: Edit any field of an existing roadmap phase in place, preserving number and position
-argument-hint: <phase-number> [--force]
-allowed-tools:
-  - Read
-  - Write
-  - Bash
----
-
-<objective>
-Modify any field of an existing phase in ROADMAP.md in place.
-
-Supports:
-- Editing individual fields (title, description/goal, requirements, success criteria, depends_on)
-- Full regeneration of all fields from a clarified intent
-- Guarded edits: refuses in_progress/completed phases unless --force is passed
-- Depends-on validation: blocks invalid references with a clear error
-- Diff + confirmation before writing
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/edit-phase.md
-</execution_context>
-
-<context>
-Arguments: $ARGUMENTS (format: <phase-number> [--force])
-
-Roadmap and state are resolved in-workflow via `init phase-op` and targeted reads.
-</context>
-
-<process>
-Execute the edit-phase workflow from @~/.claude/get-shit-done/workflows/edit-phase.md end-to-end.
-Preserve all validation gates (phase existence, status guard, depends_on validation, diff + confirmation).
-</process>

commands/gsd/eval-review.md

@@ -1,6 +1,6 @@
 ---
 name: gsd:eval-review
-description: Retroactively audit an executed AI phase's evaluation coverage — scores each eval dimension as COVERED/PARTIAL/MISSING and produces an actionable EVAL-REVIEW.md with remediation plan
+description: Audit an executed AI phase's evaluation coverage and produce an EVAL-REVIEW.md remediation plan.
 argument-hint: "[phase number]"
 allowed-tools:
   - Read

commands/gsd/forensics.md

@@ -1,7 +1,7 @@
 ---
 type: prompt
 name: gsd:forensics
-description: Post-mortem investigation for failed GSD workflows — analyzes git history, artifacts, and state to diagnose what went wrong
+description: Post-mortem investigation for failed GSD workflows — diagnoses what went wrong.
 argument-hint: "[problem description]"
 allowed-tools:
   - Read

commands/gsd/from-gsd2.md

@@ -1,47 +0,0 @@
----
-name: gsd:from-gsd2
-description: Import a GSD-2 (.gsd/) project back to GSD v1 (.planning/) format
-argument-hint: "[--path <dir>] [--force]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-type: prompt
----
-
-<objective>
-Reverse-migrate a GSD-2 project (`.gsd/` directory) back to GSD v1 (`.planning/`) format.
-
-Maps the GSD-2 hierarchy (Milestone → Slice → Task) to the GSD v1 hierarchy (Milestone sections in ROADMAP.md → Phase → Plan), preserving completion state, research files, and summaries.
-
-**CJS-only:** `from-gsd2` is not on the `gsd-sdk query` registry; call `gsd-tools.cjs` as shown below (see `docs/CLI-TOOLS.md`).
-</objective>
-
-<process>
-
-1. **Locate the .gsd/ directory** — check the current working directory (or `--path` argument):
-   ```bash
-   node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" from-gsd2 --dry-run
-   ```
-   If no `.gsd/` is found, report the error and stop.
-
-2. **Show the dry-run preview** — present the full file list and migration statistics to the user. Ask for confirmation before writing anything.
-
-3. **Run the migration** after confirmation:
-   ```bash
-   node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" from-gsd2
-   ```
-   Use `--force` if `.planning/` already exists and the user has confirmed overwrite.
-
-4. **Report the result** — show the `filesWritten` count, `planningDir` path, and the preview summary.
-
-</process>
-
-<notes>
-- The migration is non-destructive: `.gsd/` is never modified or removed.
-- Pass `--path <dir>` to migrate a project at a different path than the current directory.
-- Slices are numbered sequentially across all milestones (M001/S01 → phase 01, M001/S02 → phase 02, M002/S01 → phase 03, etc.).
-- Tasks within each slice become plans (T01 → plan 01, T02 → plan 02, etc.).
-- Completed slices and tasks carry their done state into ROADMAP.md checkboxes and SUMMARY.md files.
-- GSD-2 cost/token ledger, database state, and VS Code extension state cannot be migrated.
-</notes>

commands/gsd/health.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:health
 description: Diagnose planning directory health and optionally repair issues
-argument-hint: [--repair]
+argument-hint: "[--repair] [--context]"
 allowed-tools:
   - Read
   - Bash
@@ -10,6 +10,14 @@ allowed-tools:
 ---
 <objective>
 Validate `.planning/` directory integrity and report actionable issues. Checks for missing files, invalid configurations, inconsistent state, and orphaned plans.
+
+`--context` runs an orthogonal check: the running session's context utilization. The workflow asks for the model's tokensUsed + contextWindow, calls `gsd-sdk query validate.context`, and renders one of three states:
+
+| Utilization | State    | Action                                                |
+|-------------|----------|-------------------------------------------------------|
+| < 60%       | healthy  | no action — context is comfortable                    |
+| 60% – 70%   | warning  | recommend `/gsd-thread` to start fresh                |
+| ≥ 70%       | critical | reasoning quality may degrade past the fracture point |
 </objective>
 
 <execution_context>
@@ -18,5 +26,5 @@ Validate `.planning/` directory integrity and report actionable issues. Checks f
 
 <process>
 Execute the health workflow from @~/.claude/get-shit-done/workflows/health.md end-to-end.
-Parse --repair flag from arguments and pass to workflow.
+Parse `--repair` and `--context` flags from arguments and pass to workflow.
 </process>

commands/gsd/inbox.md

@@ -1,6 +1,6 @@
 ---
 name: gsd:inbox
-description: Triage and review all open GitHub issues and PRs against project templates and contribution guidelines
+description: Triage and review open GitHub issues and PRs against project templates and contribution guidelines.
 argument-hint: "[--issues] [--prs] [--label] [--close-incomplete] [--repo owner/repo]"
 allowed-tools:
   - Read

commands/gsd/ingest-docs.md

@@ -1,6 +1,6 @@
 ---
 name: gsd:ingest-docs
-description: Scan a repo for mixed ADRs, PRDs, SPECs, and DOCs and bootstrap or merge the full .planning/ setup from them. Classifies each doc in parallel, synthesizes a consolidated context with a conflicts report, and routes to new-project or merge-milestone depending on whether .planning/ already exists.
+description: Bootstrap or merge a .planning/ setup from existing ADRs, PRDs, SPECs, and docs in a repo.
 argument-hint: "[path] [--mode new|merge] [--manifest <file>] [--resolve auto|interactive]"
 allowed-tools:
   - Read

commands/gsd/insert-phase.md

@@ -1,31 +0,0 @@
----
-name: gsd:insert-phase
-description: Insert urgent work as decimal phase (e.g., 72.1) between existing phases
-argument-hint: <after> <description>
-allowed-tools:
-  - Read
-  - Bash
----
-
-<objective>
-Insert a decimal phase for urgent work discovered mid-milestone that must be completed between existing integer phases.
-
-Uses decimal numbering (72.1, 72.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions.
-
-Purpose: Handle urgent work discovered during execution without renumbering entire roadmap.
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/insert-phase.md
-</execution_context>
-
-<context>
-Arguments: $ARGUMENTS (format: <after-phase-number> <description>)
-
-Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls.
-</context>
-
-<process>
-Execute the insert-phase workflow from @~/.claude/get-shit-done/workflows/insert-phase.md end-to-end.
-Preserve all validation gates (argument parsing, phase verification, decimal calculation, roadmap updates).
-</process>

commands/gsd/intel.md

@@ -1,179 +0,0 @@
----
-name: gsd:intel
-description: "Query, inspect, or refresh codebase intelligence files in .planning/intel/"
-argument-hint: "[query <term>|status|diff|refresh]"
-allowed-tools:
-  - Read
-  - Bash
-  - Task
----
-
-**STOP -- DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's command system. Using the Read tool on this file wastes tokens. Begin executing Step 0 immediately.**
-
-## Step 0 -- Banner
-
-**Before ANY tool calls**, display this banner:
-
-```
-GSD > INTEL
-```
-
-Then proceed to Step 1.
-
-## Step 1 -- Config Gate
-
-Check if intel is enabled by reading `.planning/config.json` directly using the Read tool.
-
-**DO NOT use the gsd-tools config get-value command** -- it hard-exits on missing keys.
-
-1. Read `.planning/config.json` using the Read tool
-2. If the file does not exist: display the disabled message below and **STOP**
-3. Parse the JSON content. Check if `config.intel && config.intel.enabled === true`
-4. If `intel.enabled` is NOT explicitly `true`: display the disabled message below and **STOP**
-5. If `intel.enabled` is `true`: proceed to Step 2
-
-**Disabled message:**
-
-```
-GSD > INTEL
-
-Intel system is disabled. To activate:
-
-  gsd-sdk query config-set intel.enabled true
-
-Then run /gsd-intel refresh to build the initial index.
-```
-
----
-
-## Step 2 -- Parse Argument
-
-Parse `$ARGUMENTS` to determine the operation mode:
-
-| Argument | Action |
-|----------|--------|
-| `query <term>` | Run inline query (Step 2a) |
-| `status` | Run inline status check (Step 2b) |
-| `diff` | Run inline diff check (Step 2c) |
-| `refresh` | Spawn intel-updater agent (Step 3) |
-| No argument or unknown | Show usage message |
-
-**Usage message** (shown when no argument or unrecognized argument):
-
-```
-GSD > INTEL
-
-Usage: /gsd-intel <mode>
-
-Modes:
-  query <term>  Search intel files for a term
-  status        Show intel file freshness and staleness
-  diff          Show changes since last snapshot
-  refresh       Rebuild all intel files from codebase analysis
-```
-
-### Step 2a -- Query
-
-Run:
-
-```bash
-gsd-sdk query intel.query <term>
-```
-
-Parse the JSON output and display results:
-- If the output contains `"disabled": true`, display the disabled message from Step 1 and **STOP**
-- If no matches found, display: `No intel matches for '<term>'. Try /gsd-intel refresh to build the index.`
-- Otherwise, display matching entries grouped by intel file
-
-**STOP** after displaying results. Do not spawn an agent.
-
-### Step 2b -- Status
-
-Run:
-
-```bash
-gsd-sdk query intel.status
-```
-
-Parse the JSON output and display each intel file with:
-- File name
-- Last `updated_at` timestamp
-- STALE or FRESH status (stale if older than 24 hours or missing)
-
-**STOP** after displaying status. Do not spawn an agent.
-
-### Step 2c -- Diff
-
-Run:
-
-```bash
-gsd-sdk query intel.diff
-```
-
-Parse the JSON output and display:
-- Added entries since last snapshot
-- Removed entries since last snapshot
-- Changed entries since last snapshot
-
-If no snapshot exists, suggest running `refresh` first.
-
-**STOP** after displaying diff. Do not spawn an agent.
-
----
-
-## Step 3 -- Refresh (Agent Spawn)
-
-Display before spawning:
-
-```
-GSD > Spawning intel-updater agent to analyze codebase...
-```
-
-Spawn a Task:
-
-```
-Task(
-  description="Refresh codebase intelligence files",
-  prompt="You are the gsd-intel-updater agent. Your job is to analyze this codebase and write/update intelligence files in .planning/intel/.
-
-Project root: ${CWD}
-Prefer: gsd-sdk query <subcommand> (installed gsd-sdk on PATH). Legacy: node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs
-
-Instructions:
-1. Analyze the codebase structure, dependencies, APIs, and architecture
-2. Write JSON intel files to .planning/intel/ (stack.json, api-map.json, dependency-graph.json, file-roles.json, arch-decisions.json)
-3. Each file must have a _meta object with updated_at timestamp
-4. Use `gsd-sdk query intel.extract-exports <file>` to analyze source files
-5. Use `gsd-sdk query intel.patch-meta <file>` to update timestamps after writing
-6. Use `gsd-sdk query intel.validate` to check your output
-
-When complete, output: ## INTEL UPDATE COMPLETE
-If something fails, output: ## INTEL UPDATE FAILED with details."
-)
-```
-
-Wait for the agent to complete.
-
----
-
-## Step 4 -- Post-Refresh Summary
-
-After the agent completes, run:
-
-```bash
-gsd-sdk query intel.status
-```
-
-Display a summary showing:
-- Which intel files were written or updated
-- Last update timestamps
-- Overall health of the intel index
-
----
-
-## Anti-Patterns
-
-1. DO NOT spawn an agent for query/status/diff operations -- these are inline CLI calls
-2. DO NOT modify intel files directly -- the agent handles writes during refresh
-3. DO NOT skip the config gate check
-4. DO NOT use the gsd-tools config get-value CLI for the config gate -- it exits on missing keys