fix(coderabbit): resolve all 12 findings on PR #3152

MAJOR (security/correctness):
- commands/gsd/debug.md: add Write to allowed-tools (session file creation
  requires it — workflow explicitly says 'use Write tool, never heredoc')
- workflows/debug.md: add SLUG sanitization guard to steps 1b+1c (status/
  continue subcommands used raw user input in file paths — path traversal)
- workflows/thread.md: sanitize $ARGUMENTS in RESUME mode before file path
  construction (was bypassing the sanitization guard in CLOSE/STATUS modes)

MINOR (consistency/correctness):
- docs/INVENTORY-MANIFEST.json: remove stale top-level 'workflows' array
  (duplicate of families.workflows introduced in earlier update)
- commands/gsd/resume-work.md: normalize process to 'Execute end-to-end.'
- commands/gsd/settings.md: normalize process to 'Execute end-to-end.'
- commands/gsd/update.md: normalize otherwise branch to 'execute end-to-end.'
- docs/adr/0002: add Status: Accepted + Date header (ADR convention)
- workflows/extract-learnings.md: rename step extract_learnings → extract-learnings
- tests/extract-learnings.test.cjs: tighten step-name assertion to exact name

ARCHITECTURE:
- scripts/command-contract-helpers.cjs: extract CANONICAL_TOOLS, parseFrontmatter,
  executionContextRefs as shared module — single source of truth consumed by
  both lint script and test suite (prevents silent lint/test disagreement)
- scripts/lint-command-contract.cjs: require() helpers instead of duplicating
- tests/command-contract.test.cjs: require() helpers; move readFileSync calls
  inside test() callbacks (registration-time throws surface as named failures)

.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/adr-0002-command-contract-validation.md

@@ -0,0 +1,11 @@
+---
+type: Changed
+pr: 3152
+---
+**Command contract validation now enforced in CI (ADR-0002)** — \`scripts/lint-command-contract.cjs\` runs as a pre-test step and validates every \`commands/gsd/*.md\` file against five rules: \`name:\` present + \`gsd:\` prefix, \`description:\` non-empty, \`allowed-tools:\` entries canonical, \`execution_context\` @-refs resolve on disk, @-refs on their own line. Prevents the \`add-backlog.md\`-class gap from silently reappearing on consolidation PRs.
+
+**~900 tokens/invocation recovered** — prose \`@~/.claude/get-shit-done/...\` path tokens removed from \`<process>\` blocks in 39 command files. The \`<execution_context>\` block is now the single authoritative load declaration; the duplicate prose copies were inert but consumed context on every command invocation.
+
+**~3,750 tokens removed from eager session load** — \`/gsd-debug\` (9,603 → 1,703 chars) and \`/gsd-thread\` (7,868 → 585 chars) now follow the workflow-delegation pattern used by all other commands. Their implementations moved to \`get-shit-done/workflows/debug.md\` and \`get-shit-done/workflows/thread.md\`. Behavior is unchanged.
+
+\`get-shit-done/workflows/extract_learnings.md\` renamed to \`extract-learnings.md\` to match the hyphen convention of all other workflow files. Closes #3151.

.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/fix-3054-doc-anchor-and-token-check.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3114
+---
+**`/gsd-progress --next` doc migration is fully consistent** — command docs now use clear `--next` wording, FEATURES TOC anchors match renamed headings, and regression tests enforce stale-command detection via structured slash-command token checks.

.changeset/fix-3056-worktree-path-assertion.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3117
+---
+**Worktree prune regression checks are now path-normalized** — pruning safety tests now parse `git worktree list --porcelain` and assert structured normalized paths, preventing path-separator false negatives across platforms while preserving non-destructive prune guarantees.

.changeset/fix-3072-findings-probe-assertions.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3119
+---
+**Optional findings probe guard checks now use structured parsing** — regression tests now parse fenced bash blocks and validate sketch/spike findings probes as structured command records, ensuring non-fatal `|| true` guards are enforced without raw source grep assertions.

.changeset/fix-3087-planner-directive-language.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3138
+---
+**`gsd-planner.md` directive language restored** — 10 instances of `CRITICAL`/`MANDATORY`/`ALWAYS`/`MUST` emphasis were silently removed in v1.38.4 (PR #2489) without documentation, conflicting with that release's stated sycophancy-hardening intent. Downstream effect: planner output in v1.38.4–v1.40.x exhibited weaker adherence to user decisions and requirement coverage, as observed in #3087. Restored: `CRITICAL: User Decision Fidelity`, `CRITICAL: Never Simplify User Decisions`, `Multi-Source Coverage Audit (MANDATORY in every plan set)`, `Audit ALL four source types`, `Discovery is MANDATORY`, `ALWAYS split if:`, `requirements MUST list`, `CRITICAL: Every requirement ID MUST appear`, `ALWAYS use the Write tool`, and `CRITICAL — File naming convention`. Closes #3087.

.changeset/fix-3088-milestone-state-fallback-sections.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3122
+---
+**Milestone close now repairs missing STATE narrative sections** — when `## Current Position` or `## Operator Next Steps` headings are absent, milestone completion appends canonical sections so state remains deterministic and consistently points operators to `/gsd-new-milestone`.

.changeset/fix-3094-progress-stale-assumptions.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3111
+---
+**Progress routing command guidance remains canonical** — pre-planning assumption checks in progress routing now consistently assert and document `/gsd-discuss-phase` as the replacement path, with tests enforcing structured slash-command token checks.

.changeset/fix-3096-ai-integration-parallel-race.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3096
+---
+**`ai-integration-phase` Steps 7+8 now enforce sequential execution and Edit-only tool discipline** — when `gsd-ai-researcher` and `gsd-domain-researcher` were dispatched in parallel (an optimization an orchestrator could reasonably make since the sections appeared disjoint), `gsd-domain-researcher`'s `Write` call at finalization silently replaced the entire AI-SPEC.md with its pre-researcher copy, losing Sections 3/4. Confirmed at 40% incidence rate (2 of 5 agents on a real run). Fix adds an explicit sequential ordering note to Steps 7+8 ("MUST run sequentially — wait for Step 7 to complete before spawning Step 8") and injects Edit-only tool discipline into both agent prompts ("Use the Edit tool exclusively — NEVER use Write on this file"). Closes #3096.

.changeset/fix-3097-3099-executor-worktree-path.md

@@ -0,0 +1,11 @@
+---
+type: Fixed
+pr: 3097
+---
+**Executor agents now detect and halt on cwd-drift out of worktrees (#3097)** — when a Bash call `cd`'d out of a worktree, `[ -f .git ]` became false (main repo's `.git` is a directory), silently skipping all HEAD/branch guards and allowing commits to land on the main repo's branch. Adds step 0a (cwd-drift sentinel using `git rev-parse --git-dir` + a per-worktree sentinel file at `.git/worktrees/<name>/gsd-spawn-toplevel`) to `gsd-executor.md`'s `task_commit_protocol`. Closes #3097.
+
+---
+type: Fixed
+pr: 3099
+---
+**Executor agents now detect absolute paths that resolve outside the worktree (#3099)** — absolute paths constructed from the orchestrator's `pwd` (main repo root) resolved to the main repo when used in Edit/Write calls from a worktree, silently losing work. Adds step 0b (absolute-path guard using `WT_ROOT=$(git rev-parse --show-toplevel)`) with a clear warning and instructions to prefer relative paths. Both guards are documented in `references/worktree-path-safety.md` (loaded into every executor spawn prompt via `<execution_context>`). Closes #3099.

.changeset/fix-3120-secure-phase-empty-register.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3142
+---
+**`secure-phase` no longer rubber-stamps SECURITY.md for legacy phases with no `<threat_model>` blocks** — Step 3's short-circuit previously exited to Step 6 (write clean SECURITY.md) whenever `threats_open: 0`, regardless of whether zero threats meant "all mitigated" or "none were ever written". Legacy phases authored before `<threat_model>` blocks became canonical now trigger **retroactive-STRIDE mode** in Step 5: the auditor builds a register from implementation files before verifying mitigations. Step 2c now tracks `register_authored_at_plan_time` and Step 3 gates the skip on both `threats_open: 0 AND register_authored_at_plan_time: true`. Closes #3120.

.changeset/fix-3121-gsd-tools-commands-verb.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3121
+---
+**`gsd-sdk query commands` no longer returns "Unknown command"** — `commands` was referenced in `references/workstream-flag.md` and by agent tooling for verb discovery but had no SDK handler. A new `commandsList` handler in the native registry returns a sorted JSON array of all registered verb strings. `check.decision-coverage-plan` and `check.decision-coverage-verify` were already registered in the SDK native registry; the remaining gap was the `commands` introspection verb. Closes #3121.

.changeset/fix-3126-global-skills-base-runtime.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3126
+---
+**`global:` skill resolution now uses the correct runtime home directory** — `buildAgentSkillsBlock()` hardcoded `globalSkillsBase` to `~/.claude/skills` regardless of the active runtime, causing every `global:` skill lookup to silently fail on non-Claude runtimes (Cursor, Gemini, Codex, Windsurf, etc.). Introduces `get-shit-done/bin/lib/runtime-homes.cjs` — a first-class runtime→directory mapping module covering all 15 supported runtimes with their canonical env-var overrides. Notable specifics: Hermes Agent uses a nested `skills/gsd/<skillName>/` layout (#2841); Cline is rules-based and returns `null` (no skills directory); `CLAUDE_CONFIG_DIR` env var was previously missing for Claude. Warning messages now show the actual runtime-specific path. Closes #3126.

.changeset/fix-3127-state-begin-phase-idempotent.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3127
+---
+**`state.begin-phase` is now idempotent** — when called on a phase already in-flight (e.g. `--wave N` resume), it no longer overwrites `Current Plan`, `stopped_at` narrative, `Plan: N of M` body line, or `Last Activity Description` with stale values from the last `plan-phase` run. An idempotency guard reads the current `Status` field before writing: if it already contains `Executing Phase N`, only the `Last Activity` date and a resume-specific activity line are updated; all execution-progress fields are preserved. First-time execution (Status ≠ Executing) continues to write all fields as before. Closes #3127.

.changeset/fix-3128-roadmap-plan-count-slug.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3128
+---
+**`roadmap.cjs` plan_count now correctly detects `{N}-PLAN-{NN}-{slug}.md` files** — the manager-dashboard plan-count filter matched only `*-PLAN.md` and `PLAN.md`, missing the slug-form layout (`5-PLAN-01-setup.md`) that `gsd-plan-phase` actually writes. `init manager` returned `plan_count: 0` / `disk_status: "discussed"` for fully-planned phases, causing the manager to recommend and dispatch redundant background planner agents. Same regex flaw as #2893 (fixed in `phase.cjs` via PR #2896); `roadmap.cjs` was missed in that sweep. Fix applies the same `looksLikePlanFile` logic (with `PLAN-OUTLINE` and `pre-bounce` exclusions) to `countPhasePlansAndSummaries`. Closes #3128.

.changeset/fix-3129-validate-commit-bypass.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3141
+---
+**`gsd-validate-commit.sh` community hook now catches all git commit forms** — the previous `[[ "$CMD" =~ ^git[[:space:]]+commit ]]` bash regex silently bypassed Conventional Commits enforcement for `git -C /path commit`, `GIT_AUTHOR_NAME=x git commit`, and `/usr/bin/git commit`. Introduces `hooks/lib/git-cmd.js` — a token-walk classifier (`isGitSubcommand(cmd, sub)`) that correctly handles env-prefix assignments, `-C path` working-directory flags, full-path executables, `--git-dir=` options, and all git global boolean flags. The hook now delegates detection to this module — the single source of truth for all hooks that gate on git subcommands. Closes #3129.

.changeset/fix-3130-update-npx-robust.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3130
+---
+**`update.md` npx invocations hardened against cache-stale and Bash-tool token-routing failures** — the previous `npx -y get-shit-done-cc@latest` form had two failure modes: (1) npx serving a cached older version instead of `@latest`, and (2) Bash-tool wrappers misrouting the `@` token, producing `Unknown command: "get-shit-done-cc@latest"`. All three sibling invocations (local, global, unknown/fallback) now use `npx -y --package=get-shit-done-cc@latest -- get-shit-done-cc` — the `--package=` flag forces a fresh registry fetch and the `--` separator prevents token misrouting. Closes #3130.

.changeset/fix-3135-capture-backlog-workflow.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3135
+---
+**`/gsd-capture --backlog` now has a workflow to load** — PR #2824 consolidated `add-backlog` into the `--backlog` flag on `/gsd-capture` and wired `commands/gsd/capture.md` to delegate to `workflows/add-backlog.md` via `execution_context`. The workflow file was never created, leaving the routing with no implementation to load. Restores `get-shit-done/workflows/add-backlog.md` with the full process from the deleted `commands/gsd/add-backlog.md`: find next 999.x slot via `phase.next-decimal`, write ROADMAP entry before creating the phase directory (preserving the #2280 ordering invariant), create `.planning/phases/{N}-{slug}/`, and commit. Also fixes `docs/INVENTORY.md` which incorrectly attributed `--backlog` routing to `add-todo.md`. Adds a broad regression test that every `execution_context` `@`-reference in any `commands/gsd/*.md` resolves to an existing workflow file, preventing this class of gap from silently re-appearing. Closes #3135.

.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-moles-caper.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3043
+---
+milestone complete now scopes phase stats to the explicit version argument and errors when that version is missing from a versioned ROADMAP milestone section.

.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/plucky-pandas-sprint.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 3108
+---
+Query module architecture deepened with compatibility-preserving seams — command policy now derives from command definitions, and dispatch/topology/registry seams are consolidated for better locality while preserving existing query behavior.

.changeset/pr-3112-release-note.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3112
+---
+Fixes for issue #3112 were applied to keep command/workflow behavior and SDK parity aligned with current documented usage.

.changeset/pr-3113-release-note.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3113
+---
+Fixes for issue #3113 were applied to keep command/workflow behavior and SDK parity aligned with current documented usage.

.changeset/pr-3115-release-note.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3115
+---
+Fixes for issue #3115 were applied to keep command/workflow behavior and SDK parity aligned with current documented usage.

.changeset/pr-3116-release-note.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3116
+---
+Fixes for issue #3116 were applied to keep command/workflow behavior and SDK parity aligned with current documented usage.

.changeset/pr-3118-release-note.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3118
+---
+Fixes for issue #3118 were applied to keep command/workflow behavior and SDK parity aligned with current documented usage.

.changeset/pr-3123-release-note.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3123
+---
+Fixes for issue #3123 were applied to keep command/workflow behavior and SDK parity aligned with current documented usage.

.changeset/pr-3124-release-note.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3124
+---
+Fixes for issue #3124 were applied to keep command/workflow behavior and SDK parity aligned with current documented usage.

.changeset/pr-3125-release-note.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3125
+---
+Fixes for issue #3098 were applied to keep command/workflow behavior and SDK parity aligned with current documented usage.

.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/rewire-orphaned-workflows-3131.md

@@ -0,0 +1,6 @@
+---
+type: Changed
+pr: 3131
+---
+
+**Re-wired 4 orphaned workflows as flags on parent commands** — six workflows were mis-categorised as "outright deleted dead skills" during the #2790 consolidation; two were caught by prior PRs (#3045, #3038) and four are fixed here. New flags: `/gsd-discuss-phase --assumptions` (surfaces Claude's implementation assumptions before planning), `/gsd-pause-work --report` (generates a post-session summary in `.planning/reports/`), `/gsd-manager --analyze-deps` (scans ROADMAP phases for dependency relationships before parallel execution), `/gsd-import --from-gsd2` (reverse-migrates a GSD-2 `.gsd/` project back to GSD v1 `.planning/` format). Also sweeps 29 stale `/gsd-*` command references across 27 user-facing files (English + 4 locales). Closes #3131.

.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/ISSUE_TEMPLATE/bug_report.yml

@@ -90,7 +90,7 @@ body:
       label: What happened?
       description: Describe what went wrong. Be specific about which GSD command you were running.
       placeholder: |
-        When I ran `/gsd:plan`, the system...
+        When I ran `/gsd-plan`, the system...
     validations:
       required: true
 
@@ -111,8 +111,8 @@ body:
       placeholder: |
         1. Install GSD with `npx get-shit-done-cc@latest`
         2. Select runtime: Claude Code
-        3. Run `/gsd:init` with a new project
-        4. Run `/gsd:plan`
+        3. Run `/gsd-init` with a new project
+        4. Run `/gsd-plan`
         5. Error appears at step...
     validations:
       required: true

.github/ISSUE_TEMPLATE/chore.yml

@@ -0,0 +1,118 @@
+---
+name: Chore / Maintenance
+description: Internal improvements — refactoring, test quality, CI/CD, dependency updates, tech debt.
+labels: ["type: chore", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Internal maintenance work
+
+        Use this template for work that improves the **project's health** without changing user-facing behavior. Examples:
+        - Test suite refactoring or standardization
+        - CI/CD pipeline improvements
+        - Dependency updates
+        - Code quality or linting changes
+        - Build system or tooling updates
+        - Documentation infrastructure (not content — use Docs Issue for content)
+        - Tech debt paydown
+
+        If this changes how GSD **works** for users, use [Enhancement](./enhancement.yml) or [Feature Request](./feature_request.yml) instead.
+
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Pre-submission checklist
+      options:
+        - label: This does not change user-facing behavior (commands, output, file formats, config)
+          required: true
+        - label: I have searched existing issues — this has not already been filed
+          required: true
+
+  - type: input
+    id: chore_title
+    attributes:
+      label: What is the maintenance task?
+      description: A short, concrete description of what needs to happen.
+      placeholder: "e.g., Migrate test suite to node:assert/strict, Update c8 to v12, Add Windows CI matrix entry"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: chore_type
+    attributes:
+      label: Type of maintenance
+      options:
+        - Test quality (coverage, patterns, runner)
+        - CI/CD pipeline
+        - Dependency update
+        - Refactoring / code quality
+        - Build system / tooling
+        - Documentation infrastructure
+        - Tech debt
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: current_state
+    attributes:
+      label: Current state
+      description: |
+        Describe the current situation. What is the problem or debt? Include numbers where possible (test count, coverage %, build time, dependency age).
+      placeholder: |
+        73 of 89 test files use `require('node:assert')` instead of `require('node:assert/strict')`.
+        CONTRIBUTING.md requires strict mode. Non-strict assert allows type coercion in `deepEqual`,
+        masking potential bugs.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed_work
+    attributes:
+      label: Proposed work
+      description: |
+        What changes will be made? List files, patterns, or systems affected.
+      placeholder: |
+        - Replace `require('node:assert')` with `require('node:assert/strict')` across all 73 test files
+        - Replace `try/finally` cleanup with `t.after()` hooks per CONTRIBUTING.md standards
+        - Verify all 2148 tests still pass
+    validations:
+      required: true
+
+  - type: textarea
+    id: acceptance_criteria
+    attributes:
+      label: Done when
+      description: |
+        List the specific conditions that mean this work is complete. These should be verifiable.
+      placeholder: |
+        - [ ] All test files use `node:assert/strict`
+        - [ ] Zero `try/finally` cleanup blocks in test lifecycle code
+        - [ ] CI green on all matrix entries (Node 22/24, Ubuntu/macOS/Windows)
+        - [ ] No change to user-facing behavior
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area affected
+      options:
+        - Test suite
+        - CI/CD
+        - Build system
+        - Core library code
+        - Installer
+        - Documentation tooling
+        - Multiple areas
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional_context
+    attributes:
+      label: Additional context
+      description: Related issues, prior art, or anything else that helps scope this work.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -4,7 +4,7 @@ contact_links:
     url: https://github.com/gsd-build/get-shit-done/discussions
     about: v1.31.0 was not published to npm due to a hardware failure. Read the pinned announcement for the workaround before opening an issue.
   - name: Discord Community
-    url: https://discord.gg/gsd
+    url: https://discord.gg/mYgfVNfA2r
     about: Ask questions and get help from the community
   - name: Discussions
     url: https://github.com/gsd-build/get-shit-done/discussions

.github/ISSUE_TEMPLATE/enhancement.yml

@@ -0,0 +1,160 @@
+---
+name: Enhancement Proposal
+description: Propose an improvement to an existing feature. Read the full instructions before opening this issue.
+labels: ["enhancement", "needs-review"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## ⚠️ Read this before you fill anything out
+
+        An enhancement improves something that already exists — better output, expanded edge-case handling, improved performance, cleaner UX. It does **not** add new commands, new workflows, or new concepts. If you are proposing something new, use the [Feature Request](./feature_request.yml) template instead.
+
+        **Before opening this issue:**
+        - Confirm the thing you want to improve actually exists and works today.
+        - Read [CONTRIBUTING.md](../../CONTRIBUTING.md#-enhancement) — understand what `approved-enhancement` means and why you must wait for it before writing any code.
+
+        **What happens after you submit:**
+        A maintainer will review this proposal. If it is incomplete or out of scope, it will be **closed**. If approved, it will be labeled `approved-enhancement` and you may begin coding.
+
+        **Do not open a PR until this issue is labeled `approved-enhancement`.**
+
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Pre-submission checklist
+      description: You must check every box. Unchecked boxes are an immediate close.
+      options:
+        - label: I have confirmed this improves existing behavior — it does not add a new command, workflow, or concept
+          required: true
+        - label: I have searched existing issues and this enhancement has not already been proposed
+          required: true
+        - label: I have read CONTRIBUTING.md and understand I must wait for `approved-enhancement` before writing any code
+          required: true
+        - label: I can clearly describe the concrete benefit — not just "it would be nicer"
+          required: true
+
+  - type: input
+    id: what_is_being_improved
+    attributes:
+      label: What existing feature or behavior does this improve?
+      description: Name the specific command, workflow, output, or behavior you are enhancing.
+      placeholder: "e.g., `/gsd-plan` output, phase status display in statusline, context summary format"
+    validations:
+      required: true
+
+  - type: textarea
+    id: current_behavior
+    attributes:
+      label: Current behavior
+      description: |
+        Describe exactly how the thing works today. Be specific. Include example output or commands if helpful.
+      placeholder: |
+        Currently, `/gsd-status` shows:
+        ```
+        Phase 2/5 — In Progress
+        ```
+        It does not show the phase name, making it hard to know what phase you are actually in without
+        opening STATE.md.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed_behavior
+    attributes:
+      label: Proposed behavior
+      description: |
+        Describe exactly how it should work after the enhancement. Be specific. Include example output or commands.
+      placeholder: |
+        After the enhancement, `/gsd-status` would show:
+        ```
+        Phase 2/5 — In Progress — "Implement core auth module"
+        ```
+        The phase name is pulled from STATE.md and appended to the existing output.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reason_and_benefit
+    attributes:
+      label: Reason and benefit
+      description: |
+        Answer both of these clearly:
+
+        1. **Why is the current behavior a problem?** (Not just inconvenient — what goes wrong, what is harder than it should be, or what is confusing?)
+        2. **What is the concrete benefit of the proposed behavior?** (What becomes easier, faster, less error-prone, or clearer?)
+
+        Vague answers like "it would be better" or "it's more user-friendly" are not sufficient.
+      placeholder: |
+        **Why the current behavior is a problem:**
+        When working in a long session, the AI agent frequently loses track of which phase is active
+        and must re-read STATE.md. The numeric-only status gives no semantic context.
+
+        **Concrete benefit:**
+        Showing the phase name means the agent can confirm the active phase from the status output
+        alone, without an extra file read. This reduces context consumption in long sessions.
+    validations:
+      required: true
+
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope of changes
+      description: |
+        List the files and systems this enhancement would touch. Be complete.
+        An enhancement should have a narrow, well-defined scope. If your list is long, this might be a feature, not an enhancement.
+      placeholder: |
+        Files modified:
+        - `get-shit-done/commands/gsd/status.md` — update output format description
+        - `get-shit-done/bin/lib/state.cjs` — expose phase name in status() return value
+        - `tests/status.test.cjs` — update snapshot and add test for phase name in output
+        - `CHANGELOG.md` — user-facing change entry
+
+        No new files created. No new dependencies.
+    validations:
+      required: true
+
+  - type: textarea
+    id: breaking_changes
+    attributes:
+      label: Breaking changes
+      description: |
+        Does this change existing command output, file formats, or behavior that users or AI agents might depend on?
+        If yes, describe exactly what changes and how it stays backward compatible (or why it cannot).
+        Write "None" only if you are certain.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: |
+        What other ways could this be improved? Why is your proposed approach the right one?
+        If you haven't considered alternatives, take a moment before submitting.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area affected
+      options:
+        - Core workflow (init, plan, build, verify)
+        - Planning system (phases, roadmap, state)
+        - Context management (context engineering, summaries)
+        - Runtime integration (hooks, statusline, settings)
+        - Installation / setup
+        - Output / formatting
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional_context
+    attributes:
+      label: Additional context
+      description: Screenshots, related issues, or anything else that helps explain the proposal.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,44 +1,165 @@
 ---
 name: Feature Request
-description: Suggest a new feature or improvement
-labels: ["enhancement"]
+description: Propose a new feature. Read the full instructions before opening this issue.
+labels: ["feature-request", "needs-review"]
 body:
   - type: markdown
     attributes:
       value: |
-        Thanks for suggesting a feature! Please describe what you'd like to see.
+        ## ⚠️ Read this before you fill anything out
 
-  - type: textarea
-    id: problem
+        A feature adds something new to GSD — a new command, workflow, concept, or integration. Features have the **highest bar** for acceptance because every feature adds permanent maintenance burden to a project built for solo developers.
+
+        **Before opening this issue:**
+        - Check [Discussions](https://github.com/gsd-build/get-shit-done/discussions) — has this been proposed and declined before?
+        - Read [CONTRIBUTING.md](../../CONTRIBUTING.md#-feature) — understand what "approved-feature" means and why you must wait for it before writing code.
+        - Ask yourself: *does this solve a real problem for a solo developer working with an AI coding tool, or is it a feature I personally want?*
+
+        **What happens after you submit:**
+        A maintainer will review this spec. If it is incomplete, it will be **closed**, not revised. If it conflicts with GSD's design philosophy, it will be declined. If it is approved, it will be labeled `approved-feature` and you may begin coding.
+
+        **Do not open a PR until this issue is labeled `approved-feature`.**
+
+  - type: checkboxes
+    id: preflight
     attributes:
-      label: Problem or motivation
-      description: What problem does this solve? Why do you want this?
-      placeholder: "I'm frustrated when..."
+      label: Pre-submission checklist
+      description: You must check every box. Unchecked boxes are an immediate close.
+      options:
+        - label: I have searched existing issues and discussions — this has not been proposed and declined before
+          required: true
+        - label: I have read CONTRIBUTING.md and understand that I must wait for `approved-feature` before writing any code
+          required: true
+        - label: I have read the existing GSD commands and workflows and confirmed this feature does not duplicate existing behavior
+          required: true
+        - label: This feature solves a problem for solo developers using AI coding tools, not a personal preference or workflow I happen to like
+          required: true
+
+  - type: input
+    id: feature_name
+    attributes:
+      label: Feature name
+      description: A short, concrete name for this feature (not a sales pitch — just what it is).
+      placeholder: "e.g., Phase rollback command, Auto-archive completed phases, Cross-project state sync"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: feature_type
+    attributes:
+      label: Type of addition
+      description: What kind of thing is this feature adding?
+      options:
+        - New command (slash command or CLI flag)
+        - New workflow (multi-step process)
+        - New runtime integration
+        - New planning concept (phase type, state, etc.)
+        - New installation/setup behavior
+        - New output or reporting format
+        - Other (describe in spec)
     validations:
       required: true
 
   - type: textarea
-    id: solution
+    id: problem_statement
     attributes:
-      label: Proposed solution
-      description: How do you think this should work? Include example commands or workflows if possible.
+      label: The solo developer problem
+      description: |
+        Describe the concrete problem this solves for a solo developer using an AI coding tool. Be specific.
+
+        Good: "When a phase fails mid-way, there is no way to roll back state without manually editing STATE.md. This causes the AI agent to continue from a corrupted state, producing wrong plans."
+
+        Bad: "It would be nice to have a rollback feature." / "Other tools have this." / "I need this for my workflow."
       placeholder: |
-        A new command `/gsd:example` that...
+        When [specific situation], the developer cannot [specific thing], which causes [specific negative outcome].
+    validations:
+      required: true
+
+  - type: textarea
+    id: what_is_added
+    attributes:
+      label: What this feature adds
+      description: |
+        Describe exactly what is being added. Be specific about commands, output, behavior, and user interaction.
+        Include example commands or example output where possible.
+      placeholder: |
+        A new command `/gsd-rollback` that:
+        1. Reads the current phase from STATE.md
+        2. Reverts STATE.md to the previous phase's snapshot
+        3. Outputs a confirmation with the rolled-back state
+
+        Example usage:
+        ```
+        /gsd-rollback
+        > Rolled back from Phase 3 (failed) to Phase 2 (completed)
+        ```
+    validations:
+      required: true
+
+  - type: textarea
+    id: full_scope
+    attributes:
+      label: Full scope of changes
+      description: |
+        List every file, system, and area of the codebase this feature would touch. Be exhaustive.
+        If you cannot fill this out, you do not understand the codebase well enough to propose this feature yet.
+      placeholder: |
+        Files that would be created:
+        - `get-shit-done/commands/gsd/rollback.md` — new slash command definition
+
+        Files that would be modified:
+        - `get-shit-done/bin/lib/state.cjs` — add rollback() function
+        - `get-shit-done/bin/lib/phases.cjs` — expose phase snapshot API
+        - `tests/rollback.test.cjs` — new test file
+        - `docs/COMMANDS.md` — document new command
+        - `CHANGELOG.md` — entry for this feature
+
+        Systems affected:
+        - STATE.md schema (must remain backward compatible)
+        - Phase lifecycle state machine
+    validations:
+      required: true
+
+  - type: textarea
+    id: user_stories
+    attributes:
+      label: User stories
+      description: Write at least two user stories in the format "As a [user], I want [thing] so that [outcome]."
+      placeholder: |
+        1. As a solo developer, I want to roll back a failed phase so that I can re-attempt it without corrupting my project state.
+        2. As a solo developer, I want rollback to be undoable so that I don't accidentally lose completed work.
+    validations:
+      required: true
+
+  - type: textarea
+    id: acceptance_criteria
+    attributes:
+      label: Acceptance criteria
+      description: |
+        List the specific, testable conditions that must be true for this feature to be considered complete.
+        These become the basis for reviewer sign-off. Vague criteria ("it works") are not acceptable.
+      placeholder: |
+        - [ ] `/gsd-rollback` reverts STATE.md to the previous phase when current phase status is `failed`
+        - [ ] `/gsd-rollback` exits with an error if there is no previous phase to roll back to
+        - [ ] `/gsd-rollback` outputs the before/after phase names in its confirmation message
+        - [ ] Rollback is logged in the phase history so the AI agent can see it happened
+        - [ ] All existing tests still pass
+        - [ ] New tests cover the happy path, no-previous-phase case, and STATE.md corruption case
     validations:
       required: true
 
   - type: dropdown
     id: scope
     attributes:
-      label: Which area does this affect?
+      label: Which area does this primarily affect?
       options:
         - Core workflow (init, plan, build, verify)
         - Planning system (phases, roadmap, state)
         - Context management (context engineering, summaries)
         - Runtime integration (hooks, statusline, settings)
         - Installation / setup
-        - Documentation
-        - Other
+        - Documentation only
+        - Multiple areas (describe in scope section above)
     validations:
       required: true
 
@@ -46,7 +167,7 @@ body:
     id: runtimes
     attributes:
       label: Applicable runtimes
-      description: Which runtimes should this work with?
+      description: Which runtimes must this work with? Check all that apply.
       options:
         - label: Claude Code
         - label: Gemini CLI
@@ -58,18 +179,72 @@ body:
         - label: Windsurf
         - label: All runtimes
 
+  - type: textarea
+    id: breaking_changes
+    attributes:
+      label: Breaking changes assessment
+      description: |
+        Does this feature change existing behavior, command output, file formats, or APIs?
+        If yes, describe exactly what breaks and how existing users would migrate.
+        Write "None" only if you are certain.
+      placeholder: |
+        None — this adds a new command and does not modify any existing command behavior or file schemas.
+
+        OR:
+
+        STATE.md will gain a new `phase_history` array field. Existing STATE.md files without this field
+        will be treated as having an empty history (backward compatible). The rollback command will
+        decline gracefully if history is empty.
+    validations:
+      required: true
+
+  - type: textarea
+    id: maintenance_burden
+    attributes:
+      label: Maintenance burden
+      description: |
+        Every feature is code that must be maintained forever. Describe the ongoing cost:
+        - How does this interact with future changes to phases, state, or commands?
+        - Does this add external dependencies?
+        - Does this require documentation updates across multiple files?
+        - Will this create edge cases or interactions with other features?
+      placeholder: |
+        - No new dependencies
+        - The rollback function must be updated if the STATE.md schema ever changes
+        - Will need to be tested on each new Node.js LTS release
+        - The command definition must be kept in sync with any future command format changes
+    validations:
+      required: true
+
   - type: textarea
     id: alternatives
     attributes:
       label: Alternatives considered
-      description: Have you considered other approaches?
+      description: |
+        What other approaches did you consider? Why did you reject them?
+        If the answer is "I didn't consider any alternatives", this issue will be closed.
+      placeholder: |
+        1. Manual STATE.md editing — rejected because it requires the developer to understand the schema
+           and is error-prone. The AI agent cannot reliably guide this.
+        2. A `/gsd-reset` command that wipes all state — rejected because it is too destructive and
+           loses all completed phase history.
+    validations:
+      required: true
+
+  - type: textarea
+    id: prior_art
+    attributes:
+      label: Prior art and references
+      description: |
+        Does any other tool, project, or GSD discussion address this? Link to anything relevant.
+        If you are aware of a prior declined proposal for this feature, explain why this proposal is different.
     validations:
       required: false
 
   - type: textarea
-    id: context
+    id: additional_context
     attributes:
       label: Additional context
-      description: Any other information, screenshots, or examples.
+      description: Anything else — screenshots, recordings, related issues, or links.
     validations:
       required: false

.github/PULL_REQUEST_TEMPLATE/enhancement.md

@@ -0,0 +1,86 @@
+## Enhancement PR
+
+> **Using the wrong template?**
+> — Bug fix: use [fix.md](?template=fix.md)
+> — New feature: use [feature.md](?template=feature.md)
+
+---
+
+## Linked Issue
+
+> **Required.** This PR will be auto-closed if no valid issue link is found.
+> The linked issue **must** have the `approved-enhancement` label. If it does not, this PR will be closed without review.
+
+Closes #
+
+> ⛔ **No `approved-enhancement` label on the issue = immediate close.**
+> Do not open this PR if a maintainer has not yet approved the enhancement proposal.
+
+---
+
+## What this enhancement improves
+
+<!-- Name the specific command, workflow, or behavior being improved. -->
+
+## Before / After
+
+**Before:**
+<!-- Describe or show the current behavior. Include example output if applicable. -->
+
+**After:**
+<!-- Describe or show the behavior after this enhancement. Include example output if applicable. -->
+
+## How it was implemented
+
+<!-- Brief description of the approach. Point to the key files changed. -->
+
+## Testing
+
+### How I verified the enhancement works
+
+<!-- Manual steps or automated tests. -->
+
+### Platforms tested
+
+- [ ] macOS
+- [ ] Windows (including backslash path handling)
+- [ ] Linux
+- [ ] N/A (not platform-specific)
+
+### Runtimes tested
+
+- [ ] Claude Code
+- [ ] Gemini CLI
+- [ ] OpenCode
+- [ ] Other: ___
+- [ ] N/A (not runtime-specific)
+
+---
+
+## Scope confirmation
+
+<!-- Confirm the implementation matches the approved proposal. -->
+
+- [ ] The implementation matches the scope approved in the linked issue — no additions or removals
+- [ ] If scope changed during implementation, I updated the issue and got re-approval before continuing
+
+---
+
+## Checklist
+
+- [ ] Issue linked above with `Closes #NNN` — **PR will be auto-closed if missing**
+- [ ] Linked issue has the `approved-enhancement` label — **PR will be closed if missing**
+- [ ] Changes are scoped to the approved enhancement — nothing extra included
+- [ ] All existing tests pass (`npm test`)
+- [ ] New or updated tests cover the enhanced behavior
+- [ ] `.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
+
+## Breaking changes
+
+<!-- Does this enhancement change any existing behavior, output format, or API?
+     If yes, describe exactly what changes and confirm backward compatibility.
+     Write "None" if not applicable. -->
+
+None

.github/PULL_REQUEST_TEMPLATE/feature.md

@@ -0,0 +1,113 @@
+## Feature PR
+
+> **Using the wrong template?**
+> — Bug fix: use [fix.md](?template=fix.md)
+> — Enhancement to existing behavior: use [enhancement.md](?template=enhancement.md)
+
+---
+
+## Linked Issue
+
+> **Required.** This PR will be auto-closed if no valid issue link is found.
+> The linked issue **must** have the `approved-feature` label. If it does not, this PR will be closed without review — no exceptions.
+
+Closes #
+
+> ⛔ **No `approved-feature` label on the issue = immediate close.**
+> Do not open this PR if a maintainer has not yet approved the feature spec.
+> Do not open this PR if you wrote code before the issue was approved.
+
+---
+
+## Feature summary
+
+<!-- One paragraph. What does this feature add? Assume the reviewer has read the issue spec. -->
+
+## What changed
+
+### New files
+
+<!-- List every new file added and its purpose. -->
+
+| File | Purpose |
+|------|---------|
+| | |
+
+### Modified files
+
+<!-- List every existing file modified and what changed in it. -->
+
+| File | What changed |
+|------|-------------|
+| | |
+
+## Implementation notes
+
+<!-- Describe any decisions made during implementation that were not specified in the issue.
+     If any part of the implementation differs from the approved spec, explain why. -->
+
+## Spec compliance
+
+<!-- For each acceptance criterion in the linked issue, confirm it is met. Copy them here and check them off. -->
+
+- [ ] <!-- Acceptance criterion 1 from issue -->
+- [ ] <!-- Acceptance criterion 2 from issue -->
+- [ ] <!-- Add all criteria from the issue -->
+
+## Testing
+
+### Test coverage
+
+<!-- Describe what is tested and where. New features require new tests — no exceptions. -->
+
+### Platforms tested
+
+- [ ] macOS
+- [ ] Windows (including backslash path handling)
+- [ ] Linux
+
+### Runtimes tested
+
+- [ ] Claude Code
+- [ ] Gemini CLI
+- [ ] OpenCode
+- [ ] Codex
+- [ ] Copilot
+- [ ] Other: ___
+- [ ] N/A — specify which runtimes are supported and why others are excluded
+
+---
+
+## Scope confirmation
+
+- [ ] The implementation matches the scope approved in the linked issue exactly
+- [ ] No additional features, commands, or behaviors were added beyond what was approved
+- [ ] If scope changed during implementation, I updated the issue spec and received re-approval
+
+---
+
+## Checklist
+
+- [ ] Issue linked above with `Closes #NNN` — **PR will be auto-closed if missing**
+- [ ] Linked issue has the `approved-feature` label — **PR will be closed if missing**
+- [ ] All acceptance criteria from the issue are met (listed above)
+- [ ] Implementation scope matches the approved spec exactly
+- [ ] All existing tests pass (`npm test`)
+- [ ] New tests cover the happy path, error cases, and edge cases
+- [ ] `.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)
+
+## Breaking changes
+
+<!-- Describe any behavior, output format, file schema, or API changes that affect existing users.
+     For each breaking change, describe the migration path.
+     Write "None" only if you are certain. -->
+
+None
+
+## Screenshots / recordings
+
+<!-- If this feature has any visual output or changes the user experience, include before/after screenshots
+     or a short recording. Delete this section if not applicable. -->

.github/PULL_REQUEST_TEMPLATE/fix.md

@@ -0,0 +1,74 @@
+## Fix PR
+
+> **Using the wrong template?**
+> — Enhancement: use [enhancement.md](?template=enhancement.md)
+> — Feature: use [feature.md](?template=feature.md)
+
+---
+
+## Linked Issue
+
+> **Required.** This PR will be auto-closed if no valid issue link is found.
+
+Fixes #
+
+> The linked issue must have the `confirmed-bug` label. If it doesn't, ask a maintainer to confirm the bug before continuing.
+
+---
+
+## What was broken
+
+<!-- One or two sentences. What was the incorrect behavior? -->
+
+## What this fix does
+
+<!-- One or two sentences. How does this fix the broken behavior? -->
+
+## Root cause
+
+<!-- Brief explanation of why the bug existed. Skip for trivial typo/doc fixes. -->
+
+## Testing
+
+### How I verified the fix
+
+<!-- Describe manual steps or point to the automated test that proves this is fixed. -->
+
+### Regression test added?
+
+- [ ] Yes — added a test that would have caught this bug
+- [ ] No — explain why: <!-- e.g., environment-specific, non-deterministic -->
+
+### Platforms tested
+
+- [ ] macOS
+- [ ] Windows (including backslash path handling)
+- [ ] Linux
+- [ ] N/A (not platform-specific)
+
+### Runtimes tested
+
+- [ ] Claude Code
+- [ ] Gemini CLI
+- [ ] OpenCode
+- [ ] Other: ___
+- [ ] N/A (not runtime-specific)
+
+---
+
+## Checklist
+
+- [ ] Issue linked above with `Fixes #NNN` — **PR will be auto-closed if missing**
+- [ ] Linked issue has the `confirmed-bug` label
+- [ ] Fix is scoped to the reported bug — no unrelated changes included
+- [ ] Regression test added (or explained why not)
+- [ ] All existing tests pass (`npm test`)
+- [ ] `.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
+
+<!-- Does this fix change any existing behavior, output format, or API that users might depend on?
+     If yes, describe. Write "None" if not applicable. -->
+
+None

.github/dependabot.yml

@@ -0,0 +1,25 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - type: chore
+    commit-message:
+      prefix: "chore(deps):"
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - type: chore
+    commit-message:
+      prefix: "chore(ci):"

.github/pull_request_template.md

@@ -1,59 +1,40 @@
-## Linked Issue
+## ⚠️ Wrong template — please use the correct one for your PR type
 
-> **Required.** PRs without a linked issue are closed without review.
-> Open an issue first if one doesn't exist: https://github.com/gsd-build/get-shit-done/issues/new/choose
+Every PR must use a typed template. Using this default template is a reason for rejection.
 
-Closes #
+Select the template that matches your PR:
 
-## What
+| PR Type | When to use | Template link |
+|---------|-------------|---------------|
+| **Fix** | Correcting a bug, crash, or behavior that doesn't match documentation | [Use fix template](?template=PULL_REQUEST_TEMPLATE/fix.md) |
+| **Enhancement** | Improving an existing feature — better output, expanded edge cases, performance | [Use enhancement template](?template=PULL_REQUEST_TEMPLATE/enhancement.md) |
+| **Feature** | Adding something new — new command, workflow, concept, or integration | [Use feature template](?template=PULL_REQUEST_TEMPLATE/feature.md) |
 
-<!-- One sentence: what does this PR do? -->
+---
 
-## Why
+### Not sure which type applies?
 
-<!-- One sentence: why is this change needed? -->
+- If it **corrects broken behavior** → Fix
+- If it **improves existing behavior** without adding new commands or concepts → Enhancement
+- If it **adds something that doesn't exist today** → Feature
+- If you are not sure → open a [Discussion](https://github.com/gsd-build/get-shit-done/discussions) first
 
-## How
+---
 
-<!-- Brief description of the approach taken. Skip for trivial changes. -->
+### Reminder: Issues must be approved before PRs
 
-## Testing
+For **enhancements**: the linked issue must have the `approved-enhancement` label before you open this PR.
 
-### Platforms tested
+For **features**: the linked issue must have the `approved-feature` label before you open this PR.
 
-- [ ] macOS
-- [ ] Windows (including backslash path handling)
-- [ ] Linux
+PRs that arrive without a labeled, approved issue are closed without review.
 
-### Runtimes tested
+> **No draft PRs.** Draft PRs are automatically closed. Only open a PR when your code is complete, tests pass, and the correct template is used. See [CONTRIBUTING.md](../CONTRIBUTING.md).
 
-- [ ] Claude Code
-- [ ] Gemini CLI
-- [ ] OpenCode
-- [ ] Codex
-- [ ] Copilot
-- [ ] N/A (not runtime-specific)
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full process.
 
-### Test details
+---
 
-<!-- How did you verify this works? Manual steps, automated tests, etc. -->
-
-## Checklist
-
-- [ ] Issue linked above (`Closes #NNN`) — **PR will be auto-closed if missing**
-- [ ] Follows GSD style (no enterprise patterns, no filler)
-- [ ] Updates CHANGELOG.md for user-facing changes
-- [ ] No unnecessary dependencies added
-- [ ] Works on Windows (backslash paths tested)
-- [ ] Templates/references updated if behavior changed
-- [ ] Existing tests pass (`npm test`)
-
-## Breaking Changes
-
-<!-- List any breaking changes, or write "None" -->
-
-None
-
-## Screenshots / recordings
-
-<!-- If this is a visual change, add before/after screenshots. Delete this section if not applicable. -->
+<!-- If you believe your PR genuinely does not fit any of the above categories (e.g., CI/tooling changes,
+     dependency updates, or doc-only fixes with no linked issue), delete this file and describe your PR below.
+     Add a note explaining why none of the typed templates apply. -->

.github/workflows/auto-branch.yml

@@ -0,0 +1,85 @@
+name: Auto-Branch from Issue Label
+
+on:
+  issues:
+    types: [labeled]
+
+permissions:
+  contents: write
+  issues: write
+
+jobs:
+  create-branch:
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    if: >-
+      contains(fromJSON('["bug", "enhancement", "priority: critical", "type: chore", "area: docs"]'),
+      github.event.label.name)
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+
+      - name: Create branch
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const label = context.payload.label.name;
+            const issue = context.payload.issue;
+            const number = issue.number;
+
+            // Generate slug from title
+            const slug = issue.title
+              .toLowerCase()
+              .replace(/[^a-z0-9]+/g, '-')
+              .replace(/^-+|-+$/g, '')
+              .substring(0, 40);
+
+            // Map label to branch prefix
+            const prefixMap = {
+              'bug': 'fix',
+              'enhancement': 'feat',
+              'priority: critical': 'fix',
+              'type: chore': 'chore',
+              'area: docs': 'docs',
+            };
+            const prefix = prefixMap[label];
+            if (!prefix) return;
+
+            // For priority: critical, use fix/critical-NNN-slug to avoid
+            // colliding with the hotfix workflow's hotfix/X.Y.Z naming.
+            const branch = label === 'priority: critical'
+              ? `fix/critical-${number}-${slug}`
+              : `${prefix}/${number}-${slug}`;
+
+            // Check if branch already exists
+            try {
+              await github.rest.git.getRef({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                ref: `heads/${branch}`,
+              });
+              core.info(`Branch ${branch} already exists`);
+              return;
+            } catch (e) {
+              if (e.status !== 404) throw e;
+            }
+
+            // Create branch from main HEAD
+            const mainRef = await github.rest.git.getRef({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              ref: 'heads/main',
+            });
+
+            await github.rest.git.createRef({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              ref: `refs/heads/${branch}`,
+              sha: mainRef.data.object.sha,
+            });
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: number,
+              body: `Branch \`${branch}\` created.\n\n\`\`\`bash\ngit fetch origin && git checkout ${branch}\n\`\`\``,
+            });

.github/workflows/auto-label-issues.yml

@@ -10,7 +10,7 @@ jobs:
     permissions:
       issues: write
     steps:
-      - uses: actions/github-script@v8
+      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             await github.rest.issues.addLabels({

.github/workflows/branch-cleanup.yml

@@ -0,0 +1,123 @@
+name: Branch Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+  schedule:
+    - cron: '0 4 * * 0'  # Sunday 4am UTC — weekly orphan sweep
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: read
+
+jobs:
+  # Runs immediately when a PR is merged — deletes the head branch.
+  # Belt-and-suspenders alongside the repo's delete_branch_on_merge setting,
+  # which handles web/API merges but may be bypassed by some CLI paths.
+  delete-merged-branch:
+    name: Delete merged PR branch
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    if: github.event_name == 'pull_request' && github.event.pull_request.merged == true
+    steps:
+      - name: Delete head branch
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const branch = context.payload.pull_request.head.ref;
+            const protectedBranches = ['main', 'develop', 'release'];
+            if (protectedBranches.includes(branch)) {
+              core.info(`Skipping protected branch: ${branch}`);
+              return;
+            }
+            try {
+              await github.rest.git.deleteRef({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                ref: `heads/${branch}`,
+              });
+              core.info(`Deleted branch: ${branch}`);
+            } catch (e) {
+              // 422 = branch already deleted (e.g. by delete_branch_on_merge setting)
+              if (e.status === 422) {
+                core.info(`Branch already deleted: ${branch}`);
+              } else {
+                throw e;
+              }
+            }
+
+  # Runs weekly to catch any orphaned branches whose PRs were merged
+  # before this workflow existed, or that slipped through edge cases.
+  sweep-orphaned-branches:
+    name: Weekly orphaned branch sweep
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    steps:
+      - name: Delete branches from merged PRs
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const protectedBranches = new Set(['main', 'develop', 'release']);
+            const deleted = [];
+            const skipped = [];
+
+            // Paginate through all branches (100 per page)
+            let page = 1;
+            let allBranches = [];
+            while (true) {
+              const { data } = await github.rest.repos.listBranches({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                per_page: 100,
+                page,
+              });
+              allBranches = allBranches.concat(data);
+              if (data.length < 100) break;
+              page++;
+            }
+
+            core.info(`Scanning ${allBranches.length} branches...`);
+
+            for (const branch of allBranches) {
+              if (protectedBranches.has(branch.name)) continue;
+
+              // Find the most recent closed PR for this branch
+              const { data: prs } = await github.rest.pulls.list({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                head: `${context.repo.owner}:${branch.name}`,
+                state: 'closed',
+                per_page: 1,
+                sort: 'updated',
+                direction: 'desc',
+              });
+
+              if (prs.length === 0 || !prs[0].merged_at) {
+                skipped.push(branch.name);
+                continue;
+              }
+
+              try {
+                await github.rest.git.deleteRef({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  ref: `heads/${branch.name}`,
+                });
+                deleted.push(branch.name);
+              } catch (e) {
+                if (e.status !== 422) {
+                  core.warning(`Failed to delete ${branch.name}: ${e.message}`);
+                }
+              }
+            }
+
+            const summary = [
+              `Deleted ${deleted.length} orphaned branch(es).`,
+              deleted.length > 0 ? `  Removed: ${deleted.join(', ')}` : '',
+              skipped.length > 0 ? `  Skipped (no merged PR): ${skipped.length} branch(es)` : '',
+            ].filter(Boolean).join('\n');
+
+            core.info(summary);
+            await core.summary.addRaw(summary).write();

.github/workflows/branch-naming.yml

@@ -0,0 +1,38 @@
+name: Validate Branch Name
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+permissions: {}
+
+jobs:
+  check-branch:
+    runs-on: ubuntu-latest
+    timeout-minutes: 1
+    steps:
+      - name: Validate branch naming convention
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const branch = context.payload.pull_request.head.ref;
+
+            const validPrefixes = [
+              'feat/', 'fix/', 'hotfix/', 'docs/', 'chore/',
+              'refactor/', 'test/', 'release/', 'ci/', 'perf/', 'revert/',
+            ];
+
+            const alwaysValid = ['main', 'develop'];
+            if (alwaysValid.includes(branch)) return;
+            if (branch.startsWith('dependabot/') || branch.startsWith('renovate/')) return;
+            // GSD auto-created branches
+            if (branch.startsWith('gsd/') || branch.startsWith('claude/')) return;
+
+            const isValid = validPrefixes.some(prefix => branch.startsWith(prefix));
+            if (!isValid) {
+              const prefixList = validPrefixes.map(p => `\`${p}\``).join(', ');
+              core.warning(
+                `Branch "${branch}" doesn't follow naming convention. ` +
+                `Expected prefixes: ${prefixList}`
+              );
+            }

.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/close-draft-prs.yml

@@ -0,0 +1,51 @@
+name: Close Draft PRs
+
+on:
+  pull_request:
+    types: [opened, reopened, converted_to_draft]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  close-if-draft:
+    name: Reject draft PRs
+    if: github.event.pull_request.draft == true
+    runs-on: ubuntu-latest
+    steps:
+      - name: Comment and close draft PR
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const pr = context.payload.pull_request;
+            const repoUrl = context.repo.owner + '/' + context.repo.repo;
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: pr.number,
+              body: [
+                '## Draft PRs are not accepted',
+                '',
+                'This project only accepts completed pull requests. Draft PRs are automatically closed.',
+                '',
+                '**Why?** GSD requires all PRs to be ready for review when opened \u2014 with tests passing, the correct PR template used, and a linked approved issue. Draft PRs bypass these quality gates and create review overhead.',
+                '',
+                '### What to do instead',
+                '',
+                '1. Finish your implementation locally',
+                '2. Run `npm run test:coverage` and confirm all tests pass',
+                '3. Open a **non-draft** PR using the [correct template](https://github.com/' + repoUrl + '/blob/main/CONTRIBUTING.md#pull-request-guidelines)',
+                '',
+                'See [CONTRIBUTING.md](https://github.com/' + repoUrl + '/blob/main/CONTRIBUTING.md) for the full process.',
+              ].join('\n')
+            });
+
+            await github.rest.pulls.update({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: pr.number,
+              state: 'closed'
+            });
+
+            core.info('Closed draft PR #' + pr.number + ': ' + pr.title);

.github/workflows/hotfix.yml

@@ -0,0 +1,495 @@
+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:
+      action:
+        description: 'Action to perform'
+        required: true
+        type: choice
+        options:
+          - create
+          - finalize
+      version:
+        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
+        type: boolean
+        default: false
+
+concurrency:
+  group: hotfix-${{ inputs.version }}
+  cancel-in-progress: false
+
+env:
+  NODE_VERSION: 24
+
+jobs:
+  validate-version:
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    permissions:
+      contents: read
+    outputs:
+      base_tag: ${{ steps.validate.outputs.base_tag }}
+      branch: ${{ steps.validate.outputs.branch }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - name: Validate version format
+        id: validate
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          # Must be X.Y.Z where Z > 0 (patch release)
+          if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[1-9][0-9]*$'; then
+            echo "::error::Version must be a patch release (e.g., 1.27.1, not 1.28.0)"
+            exit 1
+          fi
+          MAJOR_MINOR=$(echo "$VERSION" | cut -d. -f1-2)
+          TARGET_TAG="v${VERSION}"
+          BRANCH="hotfix/${VERSION}"
+          # Append TARGET_TAG to the candidate list, then sort -V, then walk the
+          # 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 { 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"
+
+  create:
+    needs: validate-version
+    if: inputs.action == 'create'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    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 }}
+
+      - name: Check branch doesn't already exist
+        env:
+          BRANCH: ${{ needs.validate-version.outputs.branch }}
+        run: |
+          if git ls-remote --exit-code origin "refs/heads/$BRANCH" >/dev/null 2>&1; then
+            echo "::error::Branch $BRANCH already exists. Delete it first or use finalize."
+            exit 1
+          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: Create hotfix branch from base tag and push (skeleton)
+        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: |
+          set -euo pipefail
+          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"
+          if [ "$DRY_RUN" != "true" ]; then
+            git push origin "$BRANCH"
+          else
+            echo "DRY RUN — branch not pushed. Local checkout exercised the cherry-pick and bump flow."
+          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"
+
+  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: 15
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: write
+    environment: npm-publish
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          ref: ${{ needs.validate-version.outputs.branch }}
+          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: Configure git identity
+        run: |
+          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: 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: ${{ inputs.version }}
+        run: |
+          set -e
+          cd sdk
+          npm pack
+          TARBALL="gsd-build-sdk-${VERSION}.tgz"
+          if [ ! -f "$TARBALL" ]; then
+            echo "::error::Expected $TARBALL but npm pack did not produce it."
+            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');
+          }
+          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 }}
+        env:
+          VERSION: ${{ inputs.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::Tag v${VERSION} already exists pointing to different commit"
+              exit 1
+            fi
+            echo "Tag v${VERSION} already exists on current commit; skipping"
+          else
+            git tag "v${VERSION}"
+            git push origin "v${VERSION}"
+          fi
+
+      - name: Publish to npm (latest)
+        if: ${{ !inputs.dry_run && steps.prior_publish.outputs.skip_publish != 'true' }}
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --provenance --access public --tag latest
+
+      - 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: |
+          if gh release view "v${VERSION}" >/dev/null 2>&1; then
+            echo "GitHub Release v${VERSION} already exists; ensuring --latest flag is set"
+            gh release edit "v${VERSION}" --latest || true
+          else
+            gh release create "v${VERSION}" \
+              --title "v${VERSION} (hotfix)" \
+              --generate-notes \
+              --latest
+          fi
+
+      - 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 }}
+        run: |
+          EXISTING_PR=$(gh pr list --base main --head "$BRANCH" --state open --json number --jq '.[0].number')
+          if [ -n "$EXISTING_PR" ]; then
+            gh pr edit "$EXISTING_PR" \
+              --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 landed on registry
+        if: ${{ !inputs.dry_run }}
+        env:
+          VERSION: ${{ inputs.version }}
+        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
+          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}"
+            echo ""
+            echo "- Base (cumulative-fix anchor): \`${BASE_TAG}\`"
+            if [ "$DRY_RUN" = "true" ]; then
+              echo "- **DRY RUN** — npm publish, tagging, and push skipped"
+            else
+              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"