docs: v1.41.0 release documentation — CHANGELOG promotion, release notes, FEATURES update (#3219)

- Promote CHANGELOG [Unreleased] → [1.41.0] - 2026-05-07; add fresh [Unreleased] header - Fix CONFIGURATION.md version labels: 'added in v1.40' → 'added in v1.41' for models and dynamic_routing - Create docs/RELEASE-v1.41.0.md in compact v1.39.0 bullet format - Rewrite docs/RELEASE-v1.40.0-rc.1.md to compact bullet format (removes wall-of-text entries) - Add docs/FEATURES.md v1.41.0 section (features 126–131: per-phase models, dynamic routing, update banner, issue-driven orchestration, graphify staleness, MVP SDK verbs) - Update docs/FEATURES.md TOC - Trim README "Notable extras" table (highlight page, not a command menu) Fixes #3218 Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-07 00:19:26 -04:00
parent 0ed360e652
commit c0be29607a
6 changed files with 434 additions and 185 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,9 @@ All notable changes to GSD will be documented in this file.

 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

-## [Unreleased](https://github.com/gsd-build/get-shit-done/compare/v1.39.1...HEAD)
+## [Unreleased](https://github.com/gsd-build/get-shit-done/compare/v1.41.0...HEAD)
+
+## [1.41.0](https://github.com/gsd-build/get-shit-done/compare/v1.40.0...v1.41.0) - 2026-05-07

 ### Fixed

--- a/README.md
+++ b/README.md
@@ -162,17 +162,7 @@ The main loop:
 | `/gsd-complete-milestone` | Archive milestone and tag release |
 | `/gsd-new-milestone` | Start next version |

-Notable extras:
-
-| Command | What it does |
-|---------|--------------|
-| `/gsd-quick` | Ad-hoc tasks with GSD guarantees — skips planning overhead |
-| `/gsd-map-codebase` | Analyze an existing codebase before starting a new project |
-| `/gsd-autonomous` | Drive all remaining phases without stopping |
-| `/gsd-forensics` | Post-mortem a failed or stuck run |
-| `/gsd-help` | Full command reference inside your runtime |
-
-For the complete command reference — workstreams, workspaces, phase management, code quality, backlog, session tools — see **[docs/COMMANDS.md](docs/COMMANDS.md)**.
+For ad-hoc tasks, autonomous mode, codebase analysis, forensics, and the full command surface — see **[docs/COMMANDS.md](docs/COMMANDS.md)**.

 ---

--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -697,7 +697,7 @@ OpenCode's `task` interface do not accept an inline `model` parameter, so
 running `gsd install <runtime>` after editing `model_overrides` is required
 for the change to take effect. See issue #2256.

-### Per-Phase-Type Models (`models`) — added in v1.40
+### Per-Phase-Type Models (`models`) — added in v1.41

 > Express tuning at the **phase** level (planning, research, execution, verification) without learning the agent taxonomy. Added in [#3023](https://github.com/gsd-build/get-shit-done/pull/3030).

@@ -781,7 +781,7 @@ $ gsd config-set models.research sonnet

 Direct edits to `.planning/config.json` are looser — the resolver simply ignores values it doesn't recognize and falls through to the profile tier — so a typo doesn't silently break tier resolution.

-### Dynamic Routing with Failure-Tier Escalation (`dynamic_routing`) — added in v1.40
+### Dynamic Routing with Failure-Tier Escalation (`dynamic_routing`) — added in v1.41

 > Start cheap, escalate only when the agent fails the gate. Added in [#3024](https://github.com/gsd-build/get-shit-done/pull/3031).

--- a/docs/FEATURES.md
+++ b/docs/FEATURES.md
@@ -149,6 +149,13 @@
  - [Namespace Meta-Skills (Two-Stage Routing)](#123-namespace-meta-skills-two-stage-routing)
  - [Context-Window Utilization Guard](#124-context-window-utilization-guard)
  - [Phase-Lifecycle Status-Line Read-Side](#125-phase-lifecycle-status-line-read-side)
+- [v1.41.0 Features](#v1410-features)
+  - [Per-Phase-Type Model Selection](#126-per-phase-type-model-selection)
+  - [Dynamic Routing with Failure-Tier Escalation](#127-dynamic-routing-with-failure-tier-escalation)
+  - [Update Banner Opt-In](#128-update-banner-opt-in)
+  - [Issue-Driven Orchestration Guide](#129-issue-driven-orchestration-guide)
+  - [Graphify Commit-Based Staleness](#130-graphify-commit-based-staleness)
+  - [MVP Mode SDK Resolution Layer](#131-mvp-mode-sdk-resolution-layer)
 - [v1.32 Features](#v132-features)
  - [STATE.md Consistency Gates](#69-statemd-consistency-gates)
  - [Autonomous `--to N` Flag](#70-autonomous---to-n-flag)
@@ -2698,3 +2705,152 @@ Users who run a memory / knowledge-base MCP server (for example, ExoCortex-style
 - REQ-LIFECYCLE-03: All four fields default to undefined; existing STATE.md files render byte-for-byte identically.

 **Reference issue:** [#2833](https://github.com/gsd-build/get-shit-done/issues/2833) — see [`docs/STATE-MD-LIFECYCLE.md`](STATE-MD-LIFECYCLE.md) for the full field reference and rendering rules.
+
+---
+
+## v1.41.0 Features
+
+### 126. Per-Phase-Type Model Selection
+
+**Purpose:** Express model tuning at the phase level (planning, research, execution, verification) without learning the full agent taxonomy. Sits between per-agent `model_overrides` (precise, verbose) and the global `model_profile` tier (coarse, uniform).
+
+**Config key:** `models` in `.planning/config.json`
+
+**Phase-type slots:**
+
+| Slot | Agents assigned |
+|------|-----------------|
+| `planning` | `gsd-planner`, `gsd-roadmapper`, `gsd-pattern-mapper` |
+| `discuss` | (reserved for future subagent) |
+| `research` | `gsd-phase-researcher`, `gsd-project-researcher`, `gsd-research-synthesizer`, `gsd-codebase-mapper`, `gsd-ui-researcher` |
+| `execution` | `gsd-executor`, `gsd-debugger`, `gsd-doc-writer` |
+| `verification` | `gsd-verifier`, `gsd-plan-checker`, `gsd-integration-checker`, `gsd-nyquist-auditor`, `gsd-ui-checker`, `gsd-ui-auditor`, `gsd-doc-verifier` |
+| `completion` | (reserved for future subagent) |
+
+**Accepted values:** `"opus"` / `"sonnet"` / `"haiku"` / `"inherit"`
+
+**Resolution precedence (highest → lowest):**
+
+```text
+1. model_overrides[<agent>]
+2. dynamic_routing.tier_models[<tier>]   (when enabled)
+3. models[<phase_type>]                  (this feature)
+4. model_profile
+5. Runtime default
+```
+
+**Requirements:**
+- REQ-PHASE-MODELS-01: Six named `models.*` slots accepted by `config-schema.cjs` and `config-schema.ts`; `config-set` rejects unknown phase-types.
+- REQ-PHASE-MODELS-02: Configs without a `models` block behave byte-for-byte identically to pre-v1.41 behavior.
+- REQ-PHASE-MODELS-03: `discuss` and `completion` are accepted by the schema for forward compatibility; setting them today is a no-op until a subagent maps to each.
+
+**Reference issue:** [#3023](https://github.com/gsd-build/get-shit-done/pull/3030)
+
+---
+
+### 127. Dynamic Routing with Failure-Tier Escalation
+
+**Purpose:** Pay for the cheap tier by default; escalate to a more capable model automatically when the orchestrator detects a soft failure (verification inconclusive, plan-check FLAG, etc.).
+
+**Config key:** `dynamic_routing` in `.planning/config.json`
+
+**Behavior:**
+- `enabled: false` (default) — feature is off; all agents use the precedence chain unchanged.
+- `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`.
+
+**Composition:** `model_overrides` always wins; `dynamic_routing.tier_models[<tier>]` resolves above `models.<phase_type>` and `model_profile`.
+
+**Requirements:**
+- REQ-DYNROUTE-01: `dynamic_routing.enabled` acts as a master switch; when `false` or block is absent, zero behavior change.
+- REQ-DYNROUTE-02: New resolver `resolveModelForTier(cwd, agent, attempt)` in `core.cjs` is the single call-site for orchestrator integration.
+- REQ-DYNROUTE-03: `max_escalations` caps the escalation chain to prevent runaway cost.
+
+**Reference issue:** [#3024](https://github.com/gsd-build/get-shit-done/pull/3031)
+
+---
+
+### 128. Update Banner Opt-In
+
+**Purpose:** Surface update availability to users who have declined or bypassed the GSD statusline, without requiring the statusline.
+
+**Behavior:**
+- At install time, if the installer detects no GSD statusline, it offers an opt-in `SessionStart` hook.
+- The hook reads the existing `~/.cache/gsd/gsd-update-check.json` cache — the same cache used by the statusline — and prints a banner only when an update is available.
+- Silent when up-to-date.
+- Failure diagnostics rate-limited to once per 24 h.
+- Cleanly removed by `npx get-shit-done-cc --uninstall`.
+
+**Requirements:**
+- REQ-BANNER-01: Banner does not install without explicit opt-in.
+- REQ-BANNER-02: No additional network requests — reuses the existing background update-check cache.
+- REQ-BANNER-03: Uninstall path removes the banner hook.
+
+**Reference issue:** [#2795](https://github.com/gsd-build/get-shit-done/pull/2795)
+
+---
+
+### 129. Issue-Driven Orchestration Guide
+
+**Purpose:** Document a recipe for driving the full GSD workflow from a GitHub / Linear / Jira issue, mapping tracker-centric concepts onto existing GSD primitives.
+
+**Document:** [`docs/issue-driven-orchestration.md`](issue-driven-orchestration.md)
+
+**Covered workflow:**
+1. Create an isolated workspace per issue (`/gsd-new-workspace`)
+2. Run the manager dashboard to get oriented (`/gsd-manager`)
+3. Execute autonomously (`/gsd-autonomous`)
+4. Verify and review (`/gsd-verify-work`, `/gsd-review`)
+5. Ship and close the issue (`/gsd-ship`)
+
+No new commands or daemon process — purely a documentation artifact that maps existing primitives onto a tracker-driven workflow.
+
+**Reference issue:** [#2840](https://github.com/gsd-build/get-shit-done/pull/2840)
+
+---
+
+### 130. Graphify Commit-Based Staleness
+
+**Purpose:** Surface whether the architecture graph was built from the current commit or an older one, complementing the existing mtime-based stale signal.
+
+**Command:** `/gsd-graphify status`
+
+**New fields returned (graphify v0.7+ graphs):**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `built_at_commit` | string | Commit SHA the graph was built from |
+| `current_commit` | string | Current `git HEAD` |
+| `commits_behind` | number | How many commits behind HEAD the graph is |
+| `commit_stale` | boolean \| null | `true`=stale, `false`=current, `null`=unavailable (pre-v0.7, non-git) |
+
+**Rendered output (when signal is available):**
+```
+Source commit: abc1234 (3 commits behind HEAD)
+```
+
+**Security:** `built_at_commit` validated as 4–40 hex chars before reaching `git` — a hostile `graph.json` cannot inject dashed options into argv.
+
+**Fallback:** pre-v0.7 graphs and non-git checkouts return `commit_stale: null`; callers fall back to the existing mtime-based `stale` flag. No behavior change for existing users.
+
+**Reference issue:** [#3170](https://github.com/gsd-build/get-shit-done/issues/3170)
+
+---
+
+### 131. MVP Mode SDK Resolution Layer
+
+**Purpose:** Replace per-workflow MVP-mode predicate duplication with three canonical SDK query verbs. All consuming workflows now call a single source of truth instead of inlining 4–8 bash lines each.
+
+**New query verbs:**
+
+| Verb | Returns | Used by |
+|------|---------|---------|
+| `gsd-sdk query phase.mvp-mode <N>` | `{active, source, roadmap_mode, config_mvp_mode, cli_flag_present}` | `plan-phase`, `execute-phase`, `verify-work`, `progress` |
+| `gsd-sdk query task.is-behavior-adding <plan-file>` | `{is_behavior_adding, checks: {tdd_true, has_behavior_block, has_source_files}, reason}` | `gsd-executor` agent |
+| `gsd-sdk query user-story.validate "<text>"` | `{valid, slots: {role, capability, outcome}, errors[]}` | `gsd-verifier`, `/gsd-mvp-phase` |
+
+**Resolution precedence for `phase.mvp-mode`:**
+CLI flag → ROADMAP `**Mode:** mvp` → `workflow.mvp_mode` config → `false`
+
+**Bug fix:** `roadmap.get-phase --pick mode` in the SDK's `roadmap.ts` previously returned `null` for phases with `**Mode:** mvp`, causing MVP_MODE to silently fall through to false on the native dispatch path. Restores parity with the CJS implementation.
+
+**Reference issue:** [#3178](https://github.com/gsd-build/get-shit-done/pull/3178)
--- a/docs/RELEASE-v1.40.0-rc.1.md
+++ b/docs/RELEASE-v1.40.0-rc.1.md
@@ -12,197 +12,99 @@ npx get-shit-done-cc@next

 rc.1 opens the 1.40.0 train. The headline change is the **skill-surface
 consolidation** ([#2790](https://github.com/gsd-build/get-shit-done/issues/2790))
-and the new **two-stage hierarchical routing** that sits on top of it
+and the new **two-stage hierarchical namespace routing** that sits on top of it
 ([#2792](https://github.com/gsd-build/get-shit-done/issues/2792)) — together
-they take the cold-start system-prompt overhead from listing 86 flat skills
-down to 6 namespace routers. The release also adds the read-side of the
-phase-lifecycle status-line, hardens the multi-runtime install converters,
-and clears a backlog of small correctness fixes against Gemini, Copilot,
-Codex, and the canary publish workflow.
+they drop the cold-start system-prompt overhead from ~2,150 tokens (86 flat skills)
+to ~120 tokens (6 namespace routers). The release also adds the read-side of the
+phase-lifecycle status-line, hardens multi-runtime installs, and clears a backlog of
+correctness fixes for Gemini, Copilot, Codex, and the canary publish workflow.

 ### Added

- **Six namespace meta-skills with keyword-tag descriptions**
-  ([#2792](https://github.com/gsd-build/get-shit-done/issues/2792)) — replace
-  the flat eager skill listing with a two-stage hierarchical routing layer.
-  The model sees 6 namespace routers instead of 86 entries, selects a
-  namespace, then routes to the sub-skill. Namespaces:
-  `gsd:workflow` (phase pipeline), `gsd:project` (project lifecycle),
-  `gsd:review` (quality gates), `gsd:context` (codebase intelligence),
-  `gsd:manage` (config / workspace / workstreams), `gsd:ideate`
-  (exploration / capture). Descriptions use pipe-separated keyword tags
-  (≤ 60 chars) per the Tool Attention research showing keyword-dense tags
-  outperform prose for routing at ~40% the token cost.
+- **Six namespace meta-skills with keyword-tag descriptions** — replace the flat
+  86-skill listing with a two-stage hierarchical routing layer. The model sees 6
+  namespace routers (`gsd:workflow`, `gsd:project`, `gsd:review`, `gsd:context`,
+  `gsd:manage`, `gsd:ideate`) instead of 86 entries; selects a namespace, then routes
+  to the sub-skill. Existing sub-skills are unchanged and still invocable directly.
+  ([#2792](https://github.com/gsd-build/get-shit-done/issues/2792))

-  | | Entries | Approx tokens |
-  |---|---|---|
-  | Pre-1.40 full install | 86 | ~2,150 |
-  | Namespace meta-skills | 6 | ~120 |
+- **`/gsd-health --context` utilization guard** — context-window quality guard with
+  two thresholds: 60 % warns ("consider `/gsd-thread`"), 70 % is critical ("reasoning
+  quality may degrade"). Also exposed as `gsd-tools validate context`.
+  ([#2792](https://github.com/gsd-build/get-shit-done/issues/2792))

-  Existing sub-skills are unchanged and still invocable directly — the
-  namespace skills are additive.
+- **Phase-lifecycle status-line — read-side** — `parseStateMd()` now reads four new
+  STATE.md frontmatter fields: `active_phase`, `next_action`, `next_phases`, and
+  `progress`. `formatGsdState()` gains scenes for in-flight, idle, and progress
+  display. Write-side wiring follows in a later RC.
+  ([#2833](https://github.com/gsd-build/get-shit-done/issues/2833))

- **`/gsd-health --context` utilization guard**
-  ([#2792](https://github.com/gsd-build/get-shit-done/issues/2792)) — adds a
-  context-window quality guard with two thresholds: 60 % utilization warns
-  ("consider `/gsd-thread`"), 70 % is critical ("reasoning quality may
-  degrade"; matches the fracture-point per recent context-attention
-  research). Exposed via `/gsd-health --context` and as a structured
-  `gsd-tools validate context` command for status-line / hook callers.
-
- **Phase-lifecycle status-line — read-side**
-  ([#2833](https://github.com/gsd-build/get-shit-done/issues/2833)) —
-  `parseStateMd()` now reads four new STATE.md frontmatter fields:
-  `active_phase` (phase number when orchestrator is in-flight),
-  `next_action` (recommended next command when idle), `next_phases` (YAML
-  flow array of next phase numbers), and `progress` (nested
-  completed/total/percent block). `formatGsdState()` gains scenes for
-  in-flight, idle, and progress display. All fields default to undefined,
-  so existing STATE.md files keep rendering as before. Write-side and
-  status-line wiring follow in a later RC.
+- **`--minimal` install flag** (alias `--core-only`) — writes only the six core
+  skills needed for the main workflow loop; no `gsd-*` subagents. Drops cold-start
+  overhead from ~12k tokens to ~700. Useful for local LLMs with 32K–128K context.
+  ([#2762](https://github.com/gsd-build/get-shit-done/issues/2762))

 ### Changed

- **Skill surface consolidated 86 → 59 `commands/gsd/*.md` entries**
-  ([#2790](https://github.com/gsd-build/get-shit-done/issues/2790)) — four
-  new grouped skills replace clusters of micro-skills:
-  - `capture` — folds add-todo (default), note (`--note`), add-backlog
-    (`--backlog`), plant-seed (`--seed`), check-todos (`--list`)
-  - `phase` — folds add-phase (default), insert-phase (`--insert`),
-    remove-phase (`--remove`), edit-phase (`--edit`)
-  - `config` — folds settings-advanced (`--advanced`),
-    settings-integrations (`--integrations`), set-profile (`--profile`)
-  - `workspace` — folds new-workspace (`--new`), list-workspaces
-    (`--list`), remove-workspace (`--remove`)
+- **Skill surface consolidated 86 → 59 `commands/gsd/*.md` entries** — four new
+  grouped skills replace clusters of micro-skills (`capture`, `phase`, `config`,
+  `workspace`); six existing parents absorb wrap-up and sub-operations as flags
+  (`update --sync/--reapply`, `sketch --wrap-up`, `spike --wrap-up`,
+  `map-codebase --fast/--query`, `code-review --fix`, `progress --do/--next`).
+  Zero functional loss — 31 micro-skills deleted, all behavior preserved via flags.
+  ([#2790](https://github.com/gsd-build/get-shit-done/issues/2790))

-  Six existing parents absorb wrap-up and sub-operations as flags:
-  `update --sync / --reapply`, `sketch --wrap-up`, `spike --wrap-up`,
-  `map-codebase --fast / --query`, `code-review --fix`,
-  `progress --do / --next`. Zero functional loss — every removed
-  micro-skill's behavior survives via a flag on a consolidated parent.
-  31 micro-skills deleted outright; `autonomous.md` corrected to call
-  `gsd:code-review --fix` (was invoking deleted `gsd:code-review-fix`).
+- **Canary release workflow now publishes from `dev` branch only** — aligns with
+  the branch→dist-tag policy (`dev` → `@canary`, `main` → `@next`/`@latest`).
+  `workflow_dispatch` on `main` now completes build/test/dry-run validation but
+  skips publish and tag.
+  ([#2868](https://github.com/gsd-build/get-shit-done/issues/2868))

- **Canary release workflow now publishes from `dev` branch only**
-  ([#2868](https://github.com/gsd-build/get-shit-done/issues/2868)) —
-  `.github/workflows/canary.yml` swaps its four publish-step guards from
-  `refs/heads/main` to `refs/heads/dev`, aligning with the new branch →
-  dist-tag policy (`dev` → `@canary`, `main` → `@next` / `@latest`).
-  `workflow_dispatch` runs on `main` (or any other branch) now complete
-  build / test / dry-run validation but skip publish + tag, instead of the
-  prior behaviour where `main` published and `dev` silently no-op'd.
-
- **PRs missing `Closes #NNN` are auto-closed**
-  ([#2872](https://github.com/gsd-build/get-shit-done/issues/2872)) — the
-  `Issue link required` workflow now auto-closes any PR opened without a
-  closing keyword that links a tracking issue, posting a comment that
-  points to the contribution guide. Matches the documented project gate.
+- **PRs missing `Closes #NNN` are auto-closed** — the `Issue link required`
+  workflow now auto-closes any PR opened without a closing keyword, posting a
+  comment that points to the contribution guide.
+  ([#2872](https://github.com/gsd-build/get-shit-done/issues/2872))

 ### Fixed

- **Gemini slash commands are namespaced as `/gsd:<cmd>` instead of
-  `/gsd-<cmd>`** ([#2768](https://github.com/gsd-build/get-shit-done/issues/2768),
-  [#2783](https://github.com/gsd-build/get-shit-done/issues/2783)) — Gemini
-  CLI namespaces commands under `gsd:` so `/gsd-plan-phase` was
-  unexecutable. The Gemini install path now converts every body-text
-  reference via a roster-checked regex (boundary lookbehind + extension-
-  aware lookahead + roster lookup, defense-in-depth) and consistently
-  rewrites command files, agent bodies, and final-banner / patch-reapply
-  hints to colon form. The roster fail-loud guard prevents silent
-  no-op'ing if the source `commands/gsd/` directory is ever missing.
+- **Gemini slash commands now namespaced as `/gsd:<cmd>` instead of `/gsd-<cmd>`** —
+  Gemini CLI namespaces commands under `gsd:` so `/gsd-plan-phase` was unexecutable.
+  The install path now converts every body-text reference via a roster-checked regex,
+  consistently rewriting command files, agent bodies, and banners.
+  ([#2768](https://github.com/gsd-build/get-shit-done/issues/2768),
+  [#2783](https://github.com/gsd-build/get-shit-done/issues/2783))

- **GSD slash-command namespace drift cleaned up across docs, workflows
-  and autocomplete** ([#2858](https://github.com/gsd-build/get-shit-done/pull/2858))
-  — remaining stale `/gsd:<cmd>` references in active surfaces now use
-  canonical `/gsd-<cmd>`, escaped workflow `Skill(skill="gsd:...")`
-  prompts now use hyphenated skill names, `scripts/fix-slash-commands.cjs`
-  rewrites retired colon syntax to hyphen syntax, and the extract-
-  learnings command file is now `extract-learnings.md` so generated
-  Claude / Qwen skill autocomplete exposes `gsd-extract-learnings`
-  instead of `gsd-extract_learnings`.
+- **GSD slash-command namespace drift cleaned up across docs, workflows, and
+  autocomplete** — remaining stale `/gsd:<cmd>` references now use canonical
+  `/gsd-<cmd>`; `scripts/fix-slash-commands.cjs` rewrites retired colon syntax.
+  ([#2858](https://github.com/gsd-build/get-shit-done/pull/2858))

- **`SKILL.md` description quoted for Copilot / Antigravity / Trae /
-  CodeBuddy** ([#2876](https://github.com/gsd-build/get-shit-done/issues/2876))
-  — descriptions starting with a YAML 1.2 flow indicator (`[BETA] …`,
-  `{`, `*`, `&`, `!`, `|`, `>`, `%`, `@`, backtick) are parsed as flow
-  sequences / mappings by strict YAML loaders and crash gh-copilot's
-  frontmatter loader. Six emission sites now wrap the description in
-  `yamlQuote(...)` (= `JSON.stringify`, a valid YAML 1.2 double-quoted
-  scalar). The Claude variant already routed through `yamlQuote`; the
-  others are now in line.
+- **`SKILL.md` description quoted for Copilot / Antigravity / Trae / CodeBuddy** —
+  descriptions starting with a YAML 1.2 flow indicator crashed gh-copilot's strict
+  YAML loader. Six emission sites now wrap descriptions in `yamlQuote(...)`.
+  ([#2876](https://github.com/gsd-build/get-shit-done/issues/2876))

- **`gsd-tools` invocations use the absolute installed path**
-  ([#2851](https://github.com/gsd-build/get-shit-done/issues/2851)) — bare
-  `gsd-tools …` calls inside skill bodies relied on PATH resolution that
-  is not guaranteed in every runtime; replaced with the absolute path
-  emitted at install time.
+- **`gsd-tools` invocations use the absolute installed path** — bare `gsd-tools …`
+  calls inside skill bodies relied on PATH resolution not guaranteed in every runtime;
+  replaced with the absolute path emitted at install time.
+  ([#2851](https://github.com/gsd-build/get-shit-done/issues/2851))

- **Codex installer preserves trailing newline when stripping legacy
-  hooks** ([#2866](https://github.com/gsd-build/get-shit-done/issues/2866))
-  — the legacy-hook strip in the Codex installer ran against files with
-  no terminating newline at EOF and emitted a config that lost the
-  newline, breaking downstream parsers. Strip path now normalises EOF.
+- **Codex installer preserves trailing newline when stripping legacy hooks** — the
+  legacy-hook strip ran against files with no terminating newline at EOF, breaking
+  downstream parsers.
+  ([#2866](https://github.com/gsd-build/get-shit-done/issues/2866))

 ---

 ## What was in rc.7

-[`RELEASE-v1.39.0-rc.7.md`](RELEASE-v1.39.0-rc.7.md) — first 1.39.0 RC to
-roll the post-rc.5 fixes from `main` into the release branch. Includes
-the `extractCurrentMilestone` fenced-code-block fix
-([#2787](https://github.com/gsd-build/get-shit-done/issues/2787)),
-`audit-uat` frontmatter parse fix
-([#2788](https://github.com/gsd-build/get-shit-done/issues/2788)), the
-≤ 100-char skill description budget + lint gate
-([#2789](https://github.com/gsd-build/get-shit-done/issues/2789)), the
-`gsd-sdk` workstream + binary-collision fixes
-([#2791](https://github.com/gsd-build/get-shit-done/issues/2791)),
-`OpenCode` per-tier model overrides
-([#2794](https://github.com/gsd-build/get-shit-done/issues/2794)),
-`roadmap update-plan-progress --phase` flag handling
-([#2796](https://github.com/gsd-build/get-shit-done/issues/2796)),
-`context_window` allowlist entry
-([#2798](https://github.com/gsd-build/get-shit-done/issues/2798)),
-`/gsd-ingest-docs` init dispatch
-([#2801](https://github.com/gsd-build/get-shit-done/issues/2801)),
-`config-get --default` flag
-([#2803](https://github.com/gsd-build/get-shit-done/issues/2803)),
-`find-phase` archived-phase null
-([#2805](https://github.com/gsd-build/get-shit-done/issues/2805)),
-SKILL.md hyphen-form name migration
-([#2808](https://github.com/gsd-build/get-shit-done/issues/2808)),
-canary workflow `workflow_dispatch`
-([#2828](https://github.com/gsd-build/get-shit-done/issues/2828)),
-`gsd-sdk` local-mode resolve
-([#2829](https://github.com/gsd-build/get-shit-done/issues/2829)),
-OpenCode `@file` HOME expansion
-([#2831](https://github.com/gsd-build/get-shit-done/issues/2831)),
-`gsd-sdk auto` Codex detection
-([#2832](https://github.com/gsd-build/get-shit-done/issues/2832)),
-CR-INTEGRATION hyphen alignment
-([#2835](https://github.com/gsd-build/get-shit-done/issues/2835)),
-`audit-open` SUMMARY filename + UAT terminal status
-([#2836](https://github.com/gsd-build/get-shit-done/issues/2836)),
-SUMMARY rescue with gitignored `.planning/`
-([#2838](https://github.com/gsd-build/get-shit-done/issues/2838)),
-transactional cleanup tail for `/gsd-code-review-fix`
-([#2839](https://github.com/gsd-build/get-shit-done/issues/2839)).
-
-## What was in rc.5 / rc.6
-
-[`RELEASE-v1.39.0-rc.5.md`](RELEASE-v1.39.0-rc.5.md) and
-[`RELEASE-v1.39.0-rc.6.md`](RELEASE-v1.39.0-rc.6.md). rc.6 was a
-content-identical republish of rc.5; rc.5 hardened the Codex hooks
-migrator across five edge-cases
-([#2809](https://github.com/gsd-build/get-shit-done/issues/2809)).
-
-## What was in rc.4
-
-[`RELEASE-v1.39.0-rc.4.md`](RELEASE-v1.39.0-rc.4.md) — the `--minimal`
-install flag landed
-([#2762](https://github.com/gsd-build/get-shit-done/issues/2762)) along
-with the Codex `~/.codex/config.toml` corruption fix
-([#2760](https://github.com/gsd-build/get-shit-done/issues/2760)).
+[`RELEASE-v1.39.0-rc.7.md`](RELEASE-v1.39.0-rc.7.md) — first 1.39.0 RC to roll in
+post-rc.5 fixes from `main`. Includes the `extractCurrentMilestone` fenced-code-block
+fix ([#2787](https://github.com/gsd-build/get-shit-done/issues/2787)), `audit-uat`
+frontmatter parse fix ([#2788](https://github.com/gsd-build/get-shit-done/issues/2788)),
+skill description budget + lint gate ([#2789](https://github.com/gsd-build/get-shit-done/issues/2789)),
+`gsd-sdk` workstream + binary-collision fixes ([#2791](https://github.com/gsd-build/get-shit-done/issues/2791)),
+and nine additional correctness fixes across OpenCode, Codex, and Gemini runtimes.

 ---

@@ -226,9 +128,9 @@ npm install -g get-shit-done-cc@1.40.0-rc.1

 ## What's next

- Soak rc.1 against real installs across Claude Code, Codex, Copilot,
-  Gemini, OpenCode, and Antigravity runtimes.
+- Soak rc.1 against real installs across Claude Code, Codex, Copilot, Gemini,
+  OpenCode, and Antigravity runtimes.
 - Wire write-side phase-lifecycle status-line on top of the
  [#2833](https://github.com/gsd-build/get-shit-done/issues/2833) read-side.
- Run `finalize` on the release workflow to promote `1.40.0` to `latest`
-  once the train has soaked.
+- Run `finalize` on the release workflow to promote `1.40.0` to `latest` once
+  the train has soaked.
--- a/docs/RELEASE-v1.41.0.md
+++ b/docs/RELEASE-v1.41.0.md
@@ -0,0 +1,199 @@
+# v1.41.0 Release Notes
+
+Stable release. Published to npm under the `latest` tag.
+
+```bash
+npx get-shit-done-cc@latest
+```
+
+---
+
+## What's in this release
+
+1.41.0 is a quality and infrastructure release. The headline additions are **per-phase-type model selection** and **dynamic routing** — two new config blocks that give you granular cost control without learning the agent taxonomy. The release also ships the **MVP mode SDK resolution layer** (three canonical query verbs replacing per-workflow bash duplication), the **optional update banner** for non-statusline users, and the **issue-driven orchestration guide**. Underneath that, 25+ correctness fixes cover Homebrew node path stability, planner directive fidelity, secure-phase retroactive audit, cross-runtime installs, and statusline parsing.
+
+### Added
+
+- **Per-phase-type model selection (`models` block)** — express "Opus for planning,
+  Sonnet for the rest" in two config lines without learning the agent taxonomy. Six
+  named slots (`planning` / `discuss` / `research` / `execution` / `verification` /
+  `completion`) accept tier aliases (`opus` / `sonnet` / `haiku` / `inherit`). Fully
+  backward compatible.
+  ([#3023](https://github.com/gsd-build/get-shit-done/pull/3030))
+
+- **Dynamic routing with failure-tier escalation (`dynamic_routing` block)** — start
+  cheap, escalate only when the orchestrator detects a soft failure (inconclusive
+  verification, plan-check FLAG). Disabled by default; composes with `model_overrides`
+  and `models.<phase_type>` via the same precedence chain.
+  ([#3024](https://github.com/gsd-build/get-shit-done/pull/3031))
+
+- **Optional update banner for non-GSD statusline users** — when the installer detects
+  no GSD statusline, it offers an opt-in `SessionStart` hook that surfaces update
+  availability via the existing `~/.cache/gsd/gsd-update-check.json` cache. Silent when
+  up-to-date; removed cleanly by `--uninstall`.
+  ([#2795](https://github.com/gsd-build/get-shit-done/pull/2795))
+
+- **Issue-driven orchestration guide** — new
+  [`docs/issue-driven-orchestration.md`](issue-driven-orchestration.md) recipe that maps
+  tracker issues (GitHub / Linear / Jira) onto existing GSD primitives: workspace →
+  discuss → plan → execute → verify → review → ship.
+  ([#2840](https://github.com/gsd-build/get-shit-done/pull/2840))
+
+### Changed
+
+- **MVP mode SDK resolution layer — three canonical query verbs** — three new verbs
+  centralize the MVP-mode predicates previously duplicated across workflows:
+  `gsd-sdk query phase.mvp-mode <N>` (precedence resolver), `task.is-behavior-adding`
+  (Behavior-Adding Task predicate), and `user-story.validate` (User Story regex). All
+  consuming workflows now call the verb instead of inlining 4–8 bash lines each. Also
+  fixes a silent SDK bug where `roadmap.get-phase --pick mode` returned `null` for
+  phases with `**Mode:** mvp` set.
+  ([#3178](https://github.com/gsd-build/get-shit-done/pull/3178))
+
+- **`/gsd-graphify status` surfaces commit-based staleness** — reads `built_at_commit`
+  from graphify v0.7+ graphs, compares against `git HEAD`, and adds four new fields
+  (`built_at_commit`, `current_commit`, `commits_behind`, `commit_stale`). Pre-v0.7
+  graphs return `commit_stale: null` and fall back to the existing mtime-based signal.
+  ([#3170](https://github.com/gsd-build/get-shit-done/issues/3170))
+
+- **MVP concept index and domain glossary** — seven MVP-related terms added to
+  `CONTEXT.md`; new `references/mvp-concepts.md` indexes the six MVP reference files.
+  No behavior change.
+  ([#3176](https://github.com/gsd-build/get-shit-done/pull/3176))
+
+### Fixed
+
+- **Stable node path on Homebrew** — `resolveNodeRunner()` now maps versioned Cellar
+  paths to the stable Homebrew symlinks. Prevents `dyld: Library not loaded` errors
+  after `brew upgrade node`.
+  ([#3181](https://github.com/gsd-build/get-shit-done/issues/3181))
+
+- **Milestone-archive layout support** — `validate consistency`, `validate health`, and
+  `find-phase` now scan `.planning/milestones/v*-phases/` in addition to the flat
+  `.planning/phases/` layout, eliminating spurious W006 warnings.
+  ([#3164](https://github.com/gsd-build/get-shit-done/issues/3164))
+
+- **`/gsd-graphify build` runs inline instead of spawning a sub-agent** — the
+  post-extraction clustering phase was SIGTERM'd when the sub-agent exited, leaving no
+  `graph.json` / `graph.html` / `GRAPH_REPORT.md` artifacts.
+  ([#3166](https://github.com/gsd-build/get-shit-done/issues/3166))
+
+- **Planner directive language restored** — 10 `CRITICAL`/`MANDATORY`/`MUST` emphasis
+  markers were silently removed from `gsd-planner.md` in v1.38.4, weakening planner
+  adherence to user decisions and requirement coverage. All restored.
+  ([#3138](https://github.com/gsd-build/get-shit-done/issues/3087))
+
+- **`secure-phase` retroactive-STRIDE mode for legacy phases** — phases with no
+  `<threat_model>` blocks no longer rubber-stamp a clean `SECURITY.md`; the auditor
+  now builds a register from implementation files before verifying mitigations.
+  ([#3142](https://github.com/gsd-build/get-shit-done/issues/3120))
+
+- **Global skills resolution now uses the correct runtime home directory** —
+  `buildAgentSkillsBlock()` hardcoded `~/.claude/skills` for all runtimes. The new
+  `runtime-homes.cjs` module maps all 15 supported runtimes to their canonical skills
+  directory.
+  ([#3126](https://github.com/gsd-build/get-shit-done/issues/3126))
+
+- **`state.begin-phase` is now idempotent** — wave-resume calls no longer overwrite
+  `Current Plan`, `stopped_at`, or `Last Activity Description` with stale values from
+  the last `plan-phase` run.
+  ([#3127](https://github.com/gsd-build/get-shit-done/issues/3127))
+
+- **`gsd-validate-commit.sh` hook catches all git commit forms** — the previous bash
+  regex missed `git -C /path commit`, `GIT_AUTHOR_NAME=x git commit`, and
+  `/usr/bin/git commit`. New `hooks/lib/git-cmd.js` token-walk classifier handles all
+  forms correctly.
+  ([#3141](https://github.com/gsd-build/get-shit-done/issues/3129))
+
+- **`/gsd-plan-phase` no longer auto-dispatches to a subagent on OpenCode** — the
+  `agent: gsd-planner` frontmatter directive caused OpenCode to run the orchestrator in
+  a context where the `Agent` tool is unavailable. Directive removed.
+  ([#3156](https://github.com/gsd-build/get-shit-done/issues/3156))
+
+- **`/gsd-quick` worktree-merge resurrection guard** — the inverted `PRE_MERGE_FILES`
+  grep that deleted freshly-created files (including `SUMMARY.md`) is replaced with the
+  git-history check used by `execute-phase.md`.
+  ([#3195](https://github.com/gsd-build/get-shit-done/issues/3195))
+
+- **`gsd-health` no longer raises W019 for `RETROSPECTIVE.md`** — registered in
+  `CANONICAL_EXACT` in `artifacts.cjs` to match its established status as a milestone
+  completion artifact.
+  ([#3200](https://github.com/gsd-build/get-shit-done/issues/3198))
+
+- **`--sdk` flag now wired into SDK deployment** — `hasSdk` was parsed but never
+  passed to `installSdkIfNeeded`, so `--sdk` silently skipped deployment.
+  ([#3033](https://github.com/gsd-build/get-shit-done/issues/3033))
+
+- **Installer shell-path probe for SDK shim** — no longer prints "✓ GSD SDK ready"
+  when the shim is unreachable from the user's interactive shells; probes
+  `$SHELL -lc 'printf %s "$PATH"'` instead of the installer subprocess PATH.
+  ([#3028](https://github.com/gsd-build/get-shit-done/issues/3020))
+
+- **Windows update-check no longer silently fails** — passes `shell: true` on Windows
+  so `npm.cmd` resolves via PATHEXT; without this the statusline "⬆ /gsd-update"
+  indicator never rendered on Windows.
+  ([#3102](https://github.com/gsd-build/get-shit-done/issues/3103))
+
+- **Community `.sh` hooks use `#!/usr/bin/env bash`** — the previous `#!/bin/bash`
+  shebang fails on NixOS, minimal Alpine images, and some container runtimes.
+  ([#3194](https://github.com/gsd-build/get-shit-done/issues/3194))
+
+- **Gemini local install no longer duplicates `/gsd:*` commands** — when GSD is
+  already installed at user scope, a subsequent `--gemini --local` install skips the
+  workspace scope. Previously both scopes received all 65 command files and Gemini's
+  conflict detector renamed everything.
+  ([#3037](https://github.com/gsd-build/get-shit-done/issues/3037))
+
+- **Workstream resolution in `init.milestone-op` and `roadmap.analyze`** — both
+  handlers now respect `--ws`, `GSD_WORKSTREAM`, and `.planning/active-workstream`.
+  Workstream-scoped repos no longer exit with "Nothing left to do" from reading the
+  root `.planning/` directory.
+  ([#3196](https://github.com/gsd-build/get-shit-done/issues/3196),
+  [#3207](https://github.com/gsd-build/get-shit-done/pull/3207))
+
+- **`gsd-tools config-set workflow._auto_chain_active` no longer rejected** — the key
+  was added to the SDK schema but not mirrored to `config-schema.cjs`; users routed
+  through `gsd-tools` saw "Unknown config key."
+  ([#3197](https://github.com/gsd-build/get-shit-done/issues/3197))
+
+- **Statusline state rendering is type-robust and YAML-list compatible** — milestone
+  completion renders for numeric and string `percent` values; `next_phases` parses both
+  flow-array and block-list YAML.
+  ([#3153](https://github.com/gsd-build/get-shit-done/issues/3153))
+
+- **Codex SessionStart hook uses absolute Node binary path** — bare `node` in
+  `config.toml` failed with exit 127 under GUI/minimal-PATH runtimes.
+  ([#3022](https://github.com/gsd-build/get-shit-done/issues/3017))
+
+- **`config-set resolve_model_ids` and `workflow._auto_chain_active` accepted** — both
+  keys were documented or written by internal workflows but missing from the allowlists.
+  ([#3162](https://github.com/gsd-build/get-shit-done/issues/3162))
+
+---
+
+## What was in 1.40.0
+
+[`RELEASE-v1.40.0-rc.1.md`](RELEASE-v1.40.0-rc.1.md) — skill-surface consolidation
+(86 → 59, [#2790](https://github.com/gsd-build/get-shit-done/issues/2790)), six
+namespace meta-skills ([#2792](https://github.com/gsd-build/get-shit-done/issues/2792)),
+`/gsd-health --context` utilization guard, phase-lifecycle status-line read-side
+([#2833](https://github.com/gsd-build/get-shit-done/issues/2833)), and Gemini
+colon-form slash-command conversion.
+
+---
+
+## Installing
+
+```bash
+# npm (global)
+npm install -g get-shit-done-cc@latest
+
+# npx (one-shot)
+npx get-shit-done-cc@latest
+
+# Pin to this exact version
+npm install -g get-shit-done-cc@1.41.0
+```
+
+The installer is idempotent — re-running on an existing install updates in-place,
+preserving your `.planning/` directory and local patches.