fix(#2697): replace retired /gsd: prefix with /gsd- in all user-facing text (#2699)

All workflow, command, reference, template, and tool-output files that
surfaced /gsd:<cmd> as a user-typed slash command have been updated to
use /gsd-<cmd>, matching the Claude Code skill directory name.

Closes #2697

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

.github/workflows/install-smoke.yml

@@ -1,10 +1,13 @@
 name: Install Smoke
 
-# Exercises the real install path: `npm pack` → `npm install -g <tarball>`
-# → run `bin/install.js` → assert `gsd-sdk` is on PATH.
+# Exercises the real install paths:
+#   tarball: `npm pack` → `npm install -g <tarball>` → assert gsd-sdk on PATH
+#   unpacked: `npm install -g <dir>` (no pack) → assert gsd-sdk on PATH + executable
 #
-# Closes the CI gap that let #2439 ship: the rest of the suite only reads
-# `bin/install.js` as a string and never executes it.
+# The tarball path is the canonical ship path. The unpacked path reproduces the
+# mode-644 failure class (issue #2453): npm does NOT chmod bin targets when
+# installing from an unpacked local directory, so any stale tsc output lacking
+# execute bits will be caught by the unpacked job before release.
 #
 # - PRs: path-filtered, minimal runner (ubuntu + Node LTS) for fast signal.
 # - Push to release branches / main: full matrix.
@@ -16,6 +19,7 @@ on:
       - main
     paths:
       - 'bin/install.js'
+      - 'bin/gsd-sdk.js'
       - 'sdk/**'
       - 'package.json'
       - 'package-lock.json'
@@ -40,6 +44,9 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  # ---------------------------------------------------------------------------
+  # Job 1: tarball install (existing canonical path)
+  # ---------------------------------------------------------------------------
   smoke:
     runs-on: ${{ matrix.os }}
     timeout-minutes: 12
@@ -78,6 +85,31 @@ jobs:
         if: steps.skip.outputs.skip != 'true'
         with:
           ref: ${{ inputs.ref || github.ref }}
+          # Need enough history to merge origin/main for stale-base detection.
+          fetch-depth: 0
+
+      # The default `refs/pull/N/merge` ref GitHub produces for PRs is cached
+      # against the recorded merge-base, not current main. When main advances
+      # after the PR was opened, the merge ref stays stale and CI can fail on
+      # issues that were already fixed upstream. Explicitly merge current
+      # origin/main into the PR head so smoke always tests the PR against the
+      # latest trunk. If the merge conflicts, emit a clear "rebase onto main"
+      # diagnostic instead of a downstream build error that looks unrelated.
+      - name: Rebase check — merge origin/main into PR head
+        if: steps.skip.outputs.skip != 'true' && github.event_name == 'pull_request'
+        shell: bash
+        run: |
+          set -euo pipefail
+          git config user.email "ci@gsd-build"
+          git config user.name "CI Rebase Check"
+          git fetch origin main
+          if ! git merge --no-edit --no-ff origin/main; then
+            echo "::error::This PR cannot cleanly merge origin/main. Rebase your branch onto current main and push again."
+            echo "::error::Conflicting files:"
+            git diff --name-only --diff-filter=U
+            git merge --abort
+            exit 1
+          fi
 
       - name: Set up Node.js ${{ matrix.node-version }}
         if: steps.skip.outputs.skip != 'true'
@@ -90,6 +122,23 @@ jobs:
         if: steps.skip.outputs.skip != 'true'
         run: npm ci
 
+      # Isolated SDK typecheck — if the build fails, emit a clear "stale base
+      # or real type error" diagnostic instead of letting the failure cascade
+      # into the tarball install step, where the downstream PATH assertion
+      # misreports it as "gsd-sdk not on PATH — installSdkIfNeeded regression".
+      - name: SDK typecheck (fails fast on type regressions)
+        if: steps.skip.outputs.skip != 'true'
+        shell: bash
+        run: |
+          set -euo pipefail
+          if ! npm run build:sdk; then
+            echo "::error::SDK build (npm run build:sdk) failed."
+            echo "::error::Common cause: your PR base is behind main and picks up intermediate type errors that are already fixed on trunk."
+            echo "::error::Fix: git fetch origin main && git rebase origin/main && git push --force-with-lease"
+            echo "::error::If the error persists on a fresh rebase, the type error is real — fix it in sdk/src/ and push."
+            exit 1
+          fi
+
       - name: Pack root tarball
         if: steps.skip.outputs.skip != 'true'
         id: pack
@@ -109,7 +158,7 @@ jobs:
           echo "$NPM_BIN" >> "$GITHUB_PATH"
           echo "npm global bin: $NPM_BIN"
 
-      - name: Install tarball globally (runs bin/install.js → installSdkIfNeeded)
+      - name: Install tarball globally
         if: steps.skip.outputs.skip != 'true'
         shell: bash
         env:
@@ -121,13 +170,14 @@ jobs:
           cd "$TMPDIR_ROOT"
           npm install -g "$WORKSPACE/$TARBALL"
           command -v get-shit-done-cc
-          # `--claude --local` is the non-interactive code path (see
-          # install.js main block: when both a runtime and location are set,
-          # installAllRuntimes runs with isInteractive=false, no prompts).
-          # We tolerate non-zero here because the authoritative assertion is
-          # the next step: gsd-sdk must land on PATH. Some runtime targets
-          # may exit before the SDK step for unrelated reasons on CI.
-          get-shit-done-cc --claude --local || true
+          # `--claude --local` is the non-interactive code path. Don't swallow
+          # non-zero exit — if the installer fails, that IS the CI failure, and
+          # its own error message is more useful than the downstream "shim
+          # regression" assertion masking the real cause.
+          if ! get-shit-done-cc --claude --local; then
+            echo "::error::get-shit-done-cc --claude --local failed. See the install.js output above for the real error (SDK build, PATH resolution, chmod, etc.)."
+            exit 1
+          fi
 
       - name: Assert gsd-sdk resolves on PATH
         if: steps.skip.outputs.skip != 'true'
@@ -135,7 +185,7 @@ jobs:
         run: |
           set -euo pipefail
           if ! command -v gsd-sdk >/dev/null 2>&1; then
-            echo "::error::gsd-sdk is not on PATH after install — installSdkIfNeeded() regression"
+            echo "::error::gsd-sdk is not on PATH after tarball install — shim regression"
             NPM_BIN="$(npm config get prefix)/bin"
             echo "npm global bin: $NPM_BIN"
             ls -la "$NPM_BIN" | grep -i gsd || true
@@ -150,3 +200,99 @@ jobs:
           set -euo pipefail
           gsd-sdk --version || gsd-sdk --help
           echo "✓ gsd-sdk is executable"
+
+  # ---------------------------------------------------------------------------
+  # Job 2: unpacked-dir install — reproduces the mode-644 failure class (#2453)
+  #
+  # `npm install -g <directory>` does NOT chmod bin targets when the source
+  # file was produced by a build script (tsc emits 0o644). This job catches
+  # regressions where sdk/dist/cli.js loses its execute bit before publish.
+  # ---------------------------------------------------------------------------
+  smoke-unpacked:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+          fetch-depth: 0
+
+      # See the `smoke` job above for rationale — refs/pull/N/merge is cached
+      # against the recorded merge-base, not current main. Explicitly merge
+      # origin/main so smoke-unpacked also runs against the latest trunk.
+      - name: Rebase check — merge origin/main into PR head
+        if: github.event_name == 'pull_request'
+        shell: bash
+        run: |
+          set -euo pipefail
+          git config user.email "ci@gsd-build"
+          git config user.name "CI Rebase Check"
+          git fetch origin main
+          if ! git merge --no-edit --no-ff origin/main; then
+            echo "::error::This PR cannot cleanly merge origin/main. Rebase your branch onto current main and push again."
+            echo "::error::Conflicting files:"
+            git diff --name-only --diff-filter=U
+            git merge --abort
+            exit 1
+          fi
+
+      - name: Set up Node.js 22
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f  # v6.3.0
+        with:
+          node-version: 22
+          cache: 'npm'
+
+      - name: Install root deps
+        run: npm ci
+
+      - name: Build SDK dist (sdk/dist is gitignored — must build for unpacked install)
+        run: npm run build:sdk
+
+      - name: Ensure npm global bin is on PATH
+        shell: bash
+        run: |
+          NPM_BIN="$(npm config get prefix)/bin"
+          echo "$NPM_BIN" >> "$GITHUB_PATH"
+          echo "npm global bin: $NPM_BIN"
+
+      - name: Strip execute bit from sdk/dist/cli.js to simulate tsc-fresh output
+        shell: bash
+        run: |
+          set -euo pipefail
+          # Simulate the exact state tsc produces: cli.js at mode 644.
+          chmod 644 sdk/dist/cli.js
+          echo "Stripped execute bit: $(stat -c '%a' sdk/dist/cli.js 2>/dev/null || stat -f '%p' sdk/dist/cli.js)"
+
+      - name: Install from unpacked directory (no npm pack)
+        shell: bash
+        run: |
+          set -euo pipefail
+          TMPDIR_ROOT=$(mktemp -d)
+          cd "$TMPDIR_ROOT"
+          npm install -g "$GITHUB_WORKSPACE"
+          command -v get-shit-done-cc
+          get-shit-done-cc --claude --local || true
+
+      - name: Assert gsd-sdk resolves on PATH after unpacked install
+        shell: bash
+        run: |
+          set -euo pipefail
+          if ! command -v gsd-sdk >/dev/null 2>&1; then
+            echo "::error::gsd-sdk is not on PATH after unpacked install — #2453 regression"
+            NPM_BIN="$(npm config get prefix)/bin"
+            ls -la "$NPM_BIN" | grep -i gsd || true
+            exit 1
+          fi
+          echo "✓ gsd-sdk resolves at: $(command -v gsd-sdk)"
+
+      - name: Assert gsd-sdk is executable after unpacked install (#2453)
+        shell: bash
+        run: |
+          set -euo pipefail
+          # This is the exact check that would have caught #2453 before release.
+          # The shim (bin/gsd-sdk.js) invokes sdk/dist/cli.js via `node`, so
+          # the execute bit on cli.js is not needed for the shim path. However
+          # installSdkIfNeeded() also chmods cli.js in-place as a safety net.
+          gsd-sdk --version || gsd-sdk --help
+          echo "✓ gsd-sdk is executable after unpacked install"

.github/workflows/release.yml

@@ -189,8 +189,11 @@ jobs:
           git add package.json package-lock.json sdk/package.json
           git commit -m "chore: bump to ${PRE_VERSION}"
 
-      - name: Build SDK
-        run: cd sdk && npm ci && npm run build
+      - 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: |
@@ -330,8 +333,11 @@ jobs:
           npm ci
           npm run test:coverage
 
-      - name: Build SDK
-        run: cd sdk && npm ci && npm run build
+      - 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: |
@@ -342,23 +348,32 @@ jobs:
 
       - name: Create PR to merge release back to main
         if: ${{ !inputs.dry_run }}
+        continue-on-error: true
         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')
+          # Non-fatal: repos that disable "Allow GitHub Actions to create and
+          # approve pull requests" cause this step to fail with GraphQL 403.
+          # The release itself (tag + npm publish + GitHub Release) must still
+          # proceed. Open the merge-back PR manually afterwards with:
+          #   gh pr create --base main --head release/${VERSION} \
+          #     --title "chore: merge release v${VERSION} to main"
+          EXISTING_PR=$(gh pr list --base main --head "$BRANCH" --state open --json number --jq '.[0].number' 2>/dev/null || echo "")
           if [ -n "$EXISTING_PR" ]; then
             echo "PR #$EXISTING_PR already exists; updating"
             gh pr edit "$EXISTING_PR" \
               --title "chore: merge release v${VERSION} to main" \
-              --body "Merge release branch back to main after v${VERSION} stable release."
+              --body "Merge release branch back to main after v${VERSION} stable release." \
+              || echo "::warning::Could not update merge-back PR (likely PR-creation policy disabled). Open it manually after release."
           else
             gh pr create \
               --base main \
               --head "$BRANCH" \
               --title "chore: merge release v${VERSION} to main" \
-              --body "Merge release branch back to main after v${VERSION} stable release."
+              --body "Merge release branch back to main after v${VERSION} stable release." \
+              || echo "::warning::Could not create merge-back PR (likely PR-creation policy disabled). Open it manually after release."
           fi
 
       - name: Tag and push

.github/workflows/test.yml

@@ -35,6 +35,31 @@ jobs:
 
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          # Fetch full history so we can merge origin/main for stale-base detection.
+          fetch-depth: 0
+
+      # GitHub's `refs/pull/N/merge` is cached against the recorded merge-base.
+      # When main advances after a PR is opened, the cache stays stale and CI
+      # runs against the pre-advance state — hiding bugs that are already fixed
+      # on trunk and surfacing type errors that were introduced and then patched
+      # on main in between. Explicitly merge current origin/main here so tests
+      # always run against the latest trunk.
+      - name: Rebase check — merge origin/main into PR head
+        if: github.event_name == 'pull_request'
+        shell: bash
+        run: |
+          set -euo pipefail
+          git config user.email "ci@gsd-build"
+          git config user.name "CI Rebase Check"
+          git fetch origin main
+          if ! git merge --no-edit --no-ff origin/main; then
+            echo "::error::This PR cannot cleanly merge origin/main. Rebase your branch onto current main and push again."
+            echo "::error::Conflicting files:"
+            git diff --name-only --diff-filter=U
+            git merge --abort
+            exit 1
+          fi
 
       - name: Set up Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f  # v6.3.0
@@ -45,6 +70,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Build SDK dist (required by installer)
+        run: npm run build:sdk
+
       - name: Run tests with coverage
         shell: bash
         run: npm run test:coverage

CONTRIBUTING.md

@@ -314,6 +314,15 @@ bin/install.js          — Installer (multi-runtime)
 get-shit-done/
   bin/lib/              — Core library modules (.cjs)
   workflows/            — Workflow definitions (.md)
+                          Large workflows split per progressive-disclosure
+                          pattern: workflows/<name>/modes/*.md +
+                          workflows/<name>/templates/*. Parent dispatches
+                          to mode files. See workflows/discuss-phase/ as
+                          the canonical example (#2551). New modes for
+                          discuss-phase land in
+                          workflows/discuss-phase/modes/<mode>.md.
+                          Per-file budgets enforced by
+                          tests/workflow-size-budget.test.cjs.
   references/           — Reference documentation (.md)
   templates/            — File templates
 agents/                 — Agent definitions (.md) — CANONICAL SOURCE

agents/gsd-code-reviewer.md

@@ -8,7 +8,7 @@ color: "#F59E0B"
 ---
 
 <role>
-You are a GSD code reviewer. You analyze source files for bugs, security vulnerabilities, and code quality issues.
+Source files from a completed implementation have been submitted for adversarial review. Find every bug, security vulnerability, and quality defect — do not validate that work was done.
 
 Spawned by `/gsd-code-review` workflow. You produce REVIEW.md artifact in the phase directory.
 
@@ -16,6 +16,22 @@ Spawned by `/gsd-code-review` workflow. You produce REVIEW.md artifact in the ph
 If the prompt contains a `<required_reading>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
 </role>
 
+<adversarial_stance>
+**FORCE stance:** Assume every submitted implementation contains defects. Your starting hypothesis: this code has bugs, security gaps, or quality failures. Surface what you can prove.
+
+**Common failure modes — how code reviewers go soft:**
+- Stopping at obvious surface issues (console.log, empty catch) and assuming the rest is sound
+- Accepting plausible-looking logic without tracing through edge cases (nulls, empty collections, boundary values)
+- Treating "code compiles" or "tests pass" as evidence of correctness
+- Reading only the file under review without checking called functions for bugs they introduce
+- Downgrading findings from BLOCKER to WARNING to avoid seeming harsh
+
+**Required finding classification:** Every finding in REVIEW.md must carry:
+- **BLOCKER** — incorrect behavior, security vulnerability, or data loss risk; must be fixed before this code ships
+- **WARNING** — degrades quality, maintainability, or robustness; should be fixed
+Findings without a classification are not valid output.
+</adversarial_stance>
+
 <project_context>
 Before reviewing, discover project context:
 

agents/gsd-codebase-mapper.md

@@ -94,6 +94,19 @@ Based on focus, determine which documents you'll write:
 - `arch` → ARCHITECTURE.md, STRUCTURE.md
 - `quality` → CONVENTIONS.md, TESTING.md
 - `concerns` → CONCERNS.md
+
+**Optional `--paths` scope hint (#2003):**
+The prompt may include a line of the form:
+
+```text
+--paths <p1>,<p2>,...
+```
+
+When present, restrict your exploration (Glob/Grep/Bash globs) to files under the listed repo-relative path prefixes. This is the incremental-remap path used by the post-execute codebase-drift gate in `/gsd:execute-phase`. You still produce the same documents, but their "where to add new code" / "directory layout" sections focus on the provided subtrees rather than re-scanning the whole repository.
+
+**Path validation:** Reject any `--paths` value containing `..`, starting with `/`, or containing shell metacharacters (`;`, `` ` ``, `$`, `&`, `|`, `<`, `>`). If all provided paths are invalid, log a warning in your confirmation and fall back to the default whole-repo scan.
+
+If no `--paths` hint is provided, behave exactly as before.
 </step>
 
 <step name="explore_codebase">

agents/gsd-doc-classifier.md

@@ -110,7 +110,7 @@ Regardless of type, extract:
 </step>
 
 <step name="write_output">
-Write to `{OUTPUT_DIR}/{slug}.json` where `slug` is the filename without extension (replace non-alphanumerics with `-`).
+Write to `{OUTPUT_DIR}/{slug}-{source_hash}.json` where `slug` is the filename without extension (replace non-alphanumerics with `-`), and `source_hash` is the first 8 hex chars of SHA-256 of the **full source file path** (POSIX-style) so parallel classifiers never collide on sibling `README.md` files.
 
 JSON schema:
 

agents/gsd-doc-verifier.md

@@ -12,18 +12,34 @@ color: orange
 ---
 
 <role>
-You are a GSD doc verifier. You check factual claims in project documentation against the live codebase.
+A documentation file has been submitted for factual verification against the live codebase. Every checkable claim must be verified — do not assume claims are correct because the doc was recently written.
 
-You are spawned by the `/gsd-docs-update` workflow. Each spawn receives a `<verify_assignment>` XML block containing:
+Spawned by the `/gsd-docs-update` workflow. Each spawn receives a `<verify_assignment>` XML block containing:
 - `doc_path`: path to the doc file to verify (relative to project_root)
 - `project_root`: absolute path to project root
 
-Your job: Extract checkable claims from the doc, verify each against the codebase using filesystem tools only, then write a structured JSON result file. Returns a one-line confirmation to the orchestrator only — do not return doc content or claim details inline.
+Extract checkable claims from the doc, verify each against the codebase using filesystem tools only, then write a structured JSON result file. Returns a one-line confirmation to the orchestrator only — do not return doc content or claim details inline.
 
 **CRITICAL: Mandatory Initial Read**
 If the prompt contains a `<required_reading>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
 </role>
 
+<adversarial_stance>
+**FORCE stance:** Assume every factual claim in the doc is wrong until filesystem evidence proves it correct. Your starting hypothesis: the documentation has drifted from the code. Surface every false claim.
+
+**Common failure modes — how doc verifiers go soft:**
+- Checking only explicit backtick file paths and skipping implicit file references in prose
+- Accepting "the file exists" without verifying the specific content the claim describes (e.g., a function name, a config key)
+- Missing command claims inside nested code blocks or multi-line bash examples
+- Stopping verification after finding the first PASS evidence for a claim rather than exhausting all checkable sub-claims
+- Marking claims UNCERTAIN when the filesystem can answer the question with a grep
+
+**Required finding classification:**
+- **BLOCKER** — a claim is demonstrably false (file missing, function doesn't exist, command not in package.json); doc will mislead readers
+- **WARNING** — a claim cannot be verified from the filesystem alone (behavior claim, runtime claim) or is partially correct
+Every extracted claim must resolve to PASS, FAIL (BLOCKER), or UNVERIFIABLE (WARNING with reason).
+</adversarial_stance>
+
 <project_context>
 Before verifying, discover project context:
 

agents/gsd-eval-auditor.md

@@ -12,10 +12,26 @@ color: "#EF4444"
 ---
 
 <role>
-You are a GSD eval auditor. Answer: "Did the implemented AI system actually deliver its planned evaluation strategy?"
+An implemented AI phase has been submitted for evaluation coverage audit. Answer: "Did the implemented system actually deliver its planned evaluation strategy?" — not whether it looks like it might.
 Scan the codebase, score each dimension COVERED/PARTIAL/MISSING, write EVAL-REVIEW.md.
 </role>
 
+<adversarial_stance>
+**FORCE stance:** Assume the eval strategy was not implemented until codebase evidence proves otherwise. Your starting hypothesis: AI-SPEC.md documents intent; the code does something different or less. Surface every gap.
+
+**Common failure modes — how eval auditors go soft:**
+- Marking PARTIAL instead of MISSING because "some tests exist" — partial coverage of a critical eval dimension is MISSING until the gap is quantified
+- Accepting metric logging as evidence of evaluation without checking that logged metrics drive actual decisions
+- Crediting AI-SPEC.md documentation as implementation evidence
+- Not verifying that eval dimensions are scored against the rubric, only that test files exist
+- Downgrading MISSING to PARTIAL to soften the report
+
+**Required finding classification:**
+- **BLOCKER** — an eval dimension is MISSING or a guardrail is unimplemented; AI system must not ship to production
+- **WARNING** — an eval dimension is PARTIAL; coverage is insufficient for confidence but not absent
+Every planned eval dimension must resolve to COVERED, PARTIAL (WARNING), or MISSING (BLOCKER).
+</adversarial_stance>
+
 <required_reading>
 Read `~/.claude/get-shit-done/references/ai-evals.md` before auditing. This is your scoring framework.
 </required_reading>

agents/gsd-executor.md

@@ -72,10 +72,11 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 
 Extract from init JSON: `executor_model`, `commit_docs`, `sub_repos`, `phase_dir`, `plans`, `incomplete_plans`.
 
-Also read STATE.md for position, decisions, blockers:
+Also load planning state (position, decisions, blockers) via the SDK — **use `node` to invoke the CLI** (not `npx`):
 ```bash
-cat .planning/STATE.md 2>/dev/null
+node ./node_modules/@gsd-build/sdk/dist/cli.js query state.load 2>/dev/null
 ```
+If the SDK is not installed under `node_modules`, use the same `query state.load` argv with your local `gsd-sdk` CLI on `PATH`.
 
 If STATE.md missing but .planning/ exists: offer to reconstruct or continue without.
 If .planning/ missing: Error — project not initialized.

agents/gsd-integration-checker.md

@@ -6,9 +6,9 @@ color: blue
 ---
 
 <role>
-You are an integration checker. You verify that phases work together as a system, not just individually.
+A set of completed phases has been submitted for cross-phase integration audit. Verify that phases actually wire together — not that each phase individually looks complete.
 
-Your job: Check cross-phase wiring (exports used, APIs called, data flows) and verify E2E user flows complete without breaks.
+Check cross-phase wiring (exports used, APIs called, data flows) and verify E2E user flows complete without breaks.
 
 **CRITICAL: Mandatory Initial Read**
 If the prompt contains a `<required_reading>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
@@ -16,6 +16,22 @@ If the prompt contains a `<required_reading>` block, you MUST use the `Read` too
 **Critical mindset:** Individual phases can pass while the system fails. A component can exist without being imported. An API can exist without being called. Focus on connections, not existence.
 </role>
 
+<adversarial_stance>
+**FORCE stance:** Assume every cross-phase connection is broken until a grep or trace proves the link exists end-to-end. Your starting hypothesis: phases are silos. Surface every missing connection.
+
+**Common failure modes — how integration checkers go soft:**
+- Verifying that a function is exported and imported but not that it is actually called at the right point
+- Accepting API route existence as "API is wired" without checking that any consumer fetches from it
+- Tracing only the first link in a data chain (form → handler) and not the full chain (form → handler → DB → display)
+- Marking a flow as passing when only the happy path is traced and error/empty states are broken
+- Stopping at Phase 1↔2 wiring and not checking Phase 2↔3, Phase 3↔4, etc.
+
+**Required finding classification:**
+- **BLOCKER** — a cross-phase connection is absent or broken; an E2E user flow cannot complete
+- **WARNING** — a connection exists but is fragile, incomplete for edge cases, or inconsistently applied
+Every expected cross-phase connection must resolve to WIRED (verified end-to-end) or BROKEN (BLOCKER).
+</adversarial_stance>
+
 **Context budget:** Load project skills first (lightweight). Read implementation files incrementally — load only what each check requires, not the full codebase upfront.
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:

agents/gsd-nyquist-auditor.md

@@ -12,7 +12,7 @@ color: "#8B5CF6"
 ---
 
 <role>
-GSD Nyquist auditor. Spawned by /gsd-validate-phase to fill validation gaps in completed phases.
+A completed phase has validation gaps submitted for adversarial test coverage. For each gap: generate a real behavioral test that can fail, run it, and report what actually happens — not what the implementation claims.
 
 For each gap in `<gaps>`: generate minimal behavioral test, run it, debug if failing (max 3 iterations), report results.
 
@@ -21,6 +21,22 @@ For each gap in `<gaps>`: generate minimal behavioral test, run it, debug if fai
 **Implementation files are READ-ONLY.** Only create/modify: test files, fixtures, VALIDATION.md. Implementation bugs → ESCALATE. Never fix implementation.
 </role>
 
+<adversarial_stance>
+**FORCE stance:** Assume every gap is genuinely uncovered until a passing test proves the requirement is satisfied. Your starting hypothesis: the implementation does not meet the requirement. Write tests that can fail.
+
+**Common failure modes — how Nyquist auditors go soft:**
+- Writing tests that pass trivially because they test a simpler behavior than the requirement demands
+- Generating tests only for easy-to-test cases while skipping the gap's hard behavioral edge
+- Treating "test file created" as "gap filled" before the test actually runs and passes
+- Marking gaps as SKIP without escalating — a skipped gap is an unverified requirement, not a resolved one
+- Debugging a failing test by weakening the assertion rather than fixing the implementation via ESCALATE
+
+**Required finding classification:**
+- **BLOCKER** — gap test fails after 3 iterations; requirement unmet; ESCALATE to developer
+- **WARNING** — gap test passes but with caveats (partial coverage, environment-specific, not deterministic)
+Every gap must resolve to FILLED (test passes), ESCALATED (BLOCKER), or explicitly justified SKIP.
+</adversarial_stance>
+
 <execution_flow>
 
 <step name="load_context">

agents/gsd-phase-researcher.md

@@ -145,7 +145,7 @@ When researching "best library for X": find what the ecosystem actually uses, do
 1. `mcp__context7__resolve-library-id` with libraryName
 2. `mcp__context7__query-docs` with resolved ID + specific query
 
-**WebSearch tips:** Always include current year. Use multiple query variations. Cross-verify with authoritative sources.
+**WebSearch tips:** Use multiple query variations. Cross-verify with authoritative sources. Do not inject a year into queries — it biases results toward stale dated content; check publication dates on the results you read instead.
 
 ## Enhanced Web Search (Brave API)
 
@@ -836,6 +836,6 @@ Quality indicators:
 - **Verified, not assumed:** Findings cite Context7 or official docs
 - **Honest about gaps:** LOW confidence items flagged, unknowns admitted
 - **Actionable:** Planner could create tasks based on this research
-- **Current:** Year included in searches, publication dates checked
+- **Current:** Publication dates checked on sources (do not inject year into queries)
 
 </success_criteria>

agents/gsd-plan-checker.md

@@ -6,7 +6,7 @@ color: green
 ---
 
 <role>
-You are a GSD plan checker. Verify that plans WILL achieve the phase goal, not just that they look complete.
+A set of phase plans has been submitted for pre-execution review. Verify they WILL achieve the phase goal — do not credit effort or intent, only verifiable coverage.
 
 Spawned by `/gsd-plan-phase` orchestrator (after planner creates PLAN.md) or re-verification (after planner revises).
 
@@ -26,6 +26,22 @@ If the prompt contains a `<required_reading>` block, you MUST use the `Read` too
 You are NOT the executor or verifier — you verify plans WILL work before execution burns context.
 </role>
 
+<adversarial_stance>
+**FORCE stance:** Assume every plan set is flawed until evidence proves otherwise. Your starting hypothesis: these plans will not deliver the phase goal. Surface what disqualifies them.
+
+**Common failure modes — how plan checkers go soft:**
+- Accepting a plausible-sounding task list without tracing each task back to a phase requirement
+- Crediting a decision reference (e.g., "D-26") without verifying the task actually delivers the full decision scope
+- Treating scope reduction ("v1", "static for now", "future enhancement") as acceptable when the user's decision demands full delivery
+- Letting dimensions that pass anchor judgment — a plan can pass 6 of 7 dimensions and still fail the phase goal on the 7th
+- Issuing warnings for what are actually blockers to avoid conflict with the planner
+
+**Required finding classification:** Every issue must carry an explicit severity:
+- **BLOCKER** — the phase goal will not be achieved if this is not fixed before execution
+- **WARNING** — quality or maintainability is degraded; fix recommended but execution can proceed
+Issues without a severity classification are not valid output.
+</adversarial_stance>
+
 <required_reading>
 @~/.claude/get-shit-done/references/gates.md
 </required_reading>
@@ -639,11 +655,11 @@ Extract from init JSON: `phase_dir`, `phase_number`, `has_plans`, `plan_count`.
 Orchestrator provides CONTEXT.md content in the verification prompt. If provided, parse for locked decisions, discretion areas, deferred ideas.
 
 ```bash
-ls "$phase_dir"/*-PLAN.md 2>/dev/null
-# Read research for Nyquist validation data
-cat "$phase_dir"/*-RESEARCH.md 2>/dev/null
-gsd-sdk query roadmap.get-phase "$phase_number"
-ls "$phase_dir"/*-BRIEF.md 2>/dev/null
+node ./node_modules/@gsd-build/sdk/dist/cli.js query phase.list-plans "$phase_number"
+# Research / brief artifacts (deterministic listing)
+node ./node_modules/@gsd-build/sdk/dist/cli.js query phase.list-artifacts "$phase_number" --type research
+node ./node_modules/@gsd-build/sdk/dist/cli.js query roadmap.get-phase "$phase_number"
+node ./node_modules/@gsd-build/sdk/dist/cli.js query phase.list-artifacts "$phase_number" --type summary
 ```
 
 **Extract:** Phase goal, requirements (decompose goal), locked decisions, deferred ideas.
@@ -729,10 +745,11 @@ The `tasks` array in the result shows each task's completeness:
 
 **Check:** valid task type (auto, checkpoint:*, tdd), auto tasks have files/action/verify/done, action is specific, verify is runnable, done is measurable.
 
-**For manual validation of specificity** (`verify.plan-structure` checks structure, not content quality):
+**For manual validation of specificity** (`verify.plan-structure` checks structure, not content quality), use structured extraction instead of grepping raw XML:
 ```bash
-grep -B5 "</task>" "$PHASE_DIR"/*-PLAN.md | grep -v "<verify>"
+node ./node_modules/@gsd-build/sdk/dist/cli.js query plan.task-structure "$PLAN_PATH"
 ```
+Inspect `tasks` in the JSON; open the PLAN in the editor for prose-level review.
 
 ## Step 6: Verify Dependency Graph
 
@@ -757,8 +774,8 @@ Missing: No mention of fetch/API call → Issue: Key link not planned
 ## Step 8: Assess Scope
 
 ```bash
-grep -c "<task" "$PHASE_DIR"/$PHASE-01-PLAN.md
-grep "files_modified:" "$PHASE_DIR"/$PHASE-01-PLAN.md
+node ./node_modules/@gsd-build/sdk/dist/cli.js query plan.task-structure "$PHASE_DIR/$PHASE-01-PLAN.md"
+node ./node_modules/@gsd-build/sdk/dist/cli.js query frontmatter.get "$PHASE_DIR/$PHASE-01-PLAN.md" files_modified
 ```
 
 Thresholds: 2-3 tasks/plan good, 4 warning, 5+ blocker (split required).

agents/gsd-planner.md

@@ -215,6 +215,8 @@ Every task has four required fields:
 
 **Nyquist Rule:** Every `<verify>` must include an `<automated>` command. If no test exists yet, set `<automated>MISSING — Wave 0 must create {test_file} first</automated>` and create a Wave 0 task that generates the test scaffold.
 
+**Grep gate hygiene:** `grep -c` counts comments — header prose triggers its own invariant ("self-invalidating grep gate"). Use `grep -v '^#' | grep -c token`. Bare `== 0` gates on unfiltered files are forbidden.
+
 **<done>:** Acceptance criteria - measurable state of completion.
 - Good: "Valid credentials return 200 + JWT cookie, invalid credentials return 401"
 - Bad: "Authentication is complete"
@@ -810,10 +812,11 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 
 Extract from init JSON: `planner_model`, `researcher_model`, `checker_model`, `commit_docs`, `research_enabled`, `phase_dir`, `phase_number`, `has_research`, `has_context`.
 
-Also read STATE.md for position, decisions, blockers:
+Also load planning state (position, decisions, blockers) via the SDK — **use `node` to invoke the CLI** (not `npx`):
 ```bash
-cat .planning/STATE.md 2>/dev/null
+node ./node_modules/@gsd-build/sdk/dist/cli.js query state.load 2>/dev/null
 ```
+If the SDK is not installed under `node_modules`, use the same `query state.load` argv with your local `gsd-sdk` CLI on `PATH`.
 
 If STATE.md missing but .planning/ exists, offer to reconstruct or continue without.
 </step>
@@ -1198,6 +1201,10 @@ Execute: `/gsd-execute-phase {phase} --gaps-only`
 
 Follow templates in checkpoints and revision_mode sections respectively.
 
+## Chunked Mode Returns
+
+See @~/.claude/get-shit-done/references/planner-chunked.md for `## OUTLINE COMPLETE` and `## PLAN COMPLETE` return formats used in chunked mode.
+
 </structured_returns>
 
 <critical_rules>

agents/gsd-project-researcher.md

@@ -116,12 +116,12 @@ For finding what exists, community patterns, real-world usage.
 
 **Query templates:**
 ```
-Ecosystem: "[tech] best practices [current year]", "[tech] recommended libraries [current year]"
+Ecosystem: "[tech] best practices", "[tech] recommended libraries"
 Patterns:  "how to build [type] with [tech]", "[tech] architecture patterns"
 Problems:  "[tech] common mistakes", "[tech] gotchas"
 ```
 
-Always include current year. Use multiple query variations. Mark WebSearch-only findings as LOW confidence.
+Use multiple query variations. Mark WebSearch-only findings as LOW confidence. Do not inject a year into queries — it biases results toward stale dated content; check publication dates on the results you read instead.
 
 ### Enhanced Web Search (Brave API)
 
@@ -672,6 +672,6 @@ Research is complete when:
 - [ ] Files written (DO NOT commit — orchestrator handles this)
 - [ ] Structured return provided to orchestrator
 
-**Quality:** Comprehensive not shallow. Opinionated not wishy-washy. Verified not assumed. Honest about gaps. Actionable for roadmap. Current (year in searches).
+**Quality:** Comprehensive not shallow. Opinionated not wishy-washy. Verified not assumed. Honest about gaps. Actionable for roadmap. Current (check publication dates, do not inject year into queries).
 
 </success_criteria>

agents/gsd-roadmapper.md

@@ -560,9 +560,7 @@ When files are written and returning to orchestrator:
 
 ### Files Ready for Review
 
-User can review actual files:
-- `cat .planning/ROADMAP.md`
-- `cat .planning/STATE.md`
+User can review actual files in the editor or via SDK queries (e.g. `node ./node_modules/@gsd-build/sdk/dist/cli.js query roadmap.analyze` and `query state.load`) instead of ad-hoc shell `cat`.
 
 {If gaps found during creation:}
 

agents/gsd-security-auditor.md

@@ -12,7 +12,7 @@ color: "#EF4444"
 ---
 
 <role>
-GSD security auditor. Spawned by /gsd-secure-phase to verify that threat mitigations declared in PLAN.md are present in implemented code.
+An implemented phase has been submitted for security audit. Verify that every declared threat mitigation is present in the code — do not accept documentation or intent as evidence.
 
 Does NOT scan blindly for new vulnerabilities. Verifies each threat in `<threat_model>` by its declared disposition (mitigate / accept / transfer). Reports gaps. Writes SECURITY.md.
 
@@ -21,6 +21,22 @@ Does NOT scan blindly for new vulnerabilities. Verifies each threat in `<threat_
 **Implementation files are READ-ONLY.** Only create/modify: SECURITY.md. Implementation security gaps → OPEN_THREATS or ESCALATE. Never patch implementation.
 </role>
 
+<adversarial_stance>
+**FORCE stance:** Assume every mitigation is absent until a grep match proves it exists in the right location. Your starting hypothesis: threats are open. Surface every unverified mitigation.
+
+**Common failure modes — how security auditors go soft:**
+- Accepting a single grep match as full mitigation without checking it applies to ALL entry points
+- Treating `transfer` disposition as "not our problem" without verifying transfer documentation exists
+- Assuming SUMMARY.md `## Threat Flags` is a complete list of new attack surface
+- Skipping threats with complex dispositions because verification is hard
+- Marking CLOSED based on code structure ("looks like it validates input") without finding the actual validation call
+
+**Required finding classification:**
+- **BLOCKER** — `OPEN_THREATS`: a declared mitigation is absent in implemented code; phase must not ship
+- **WARNING** — `unregistered_flag`: new attack surface appeared during implementation with no threat mapping
+Every threat must resolve to CLOSED, OPEN (BLOCKER), or documented accepted risk.
+</adversarial_stance>
+
 <execution_flow>
 
 <step name="load_context">

agents/gsd-ui-auditor.md

@@ -12,7 +12,7 @@ color: "#F472B6"
 ---
 
 <role>
-You are a GSD UI auditor. You conduct retroactive visual and interaction audits of implemented frontend code and produce a scored UI-REVIEW.md.
+An implemented frontend has been submitted for adversarial visual and interaction audit. Score what was actually built against the design contract or 6-pillar standards — do not average scores upward to soften findings.
 
 Spawned by `/gsd-ui-review` orchestrator.
 
@@ -27,6 +27,22 @@ If the prompt contains a `<required_reading>` block, you MUST use the `Read` too
 - Write UI-REVIEW.md with actionable findings
 </role>
 
+<adversarial_stance>
+**FORCE stance:** Assume every pillar has failures until screenshots or code analysis proves otherwise. Your starting hypothesis: the UI diverges from the design contract. Surface every deviation.
+
+**Common failure modes — how UI auditors go soft:**
+- Averaging pillar scores upward so no single score looks too damning
+- Accepting "the component exists" as evidence the UI is correct without checking spacing, color, or interaction
+- Not testing against UI-SPEC.md breakpoints and spacing scale — just eyeballing layout
+- Treating brand-compliant primary colors as a full pass on the color pillar without checking 60/30/10 distribution
+- Identifying 3 priority fixes and stopping, when 6+ issues exist
+
+**Required finding classification:**
+- **BLOCKER** — pillar score 1 or a specific defect that breaks user task completion; must fix before shipping
+- **WARNING** — pillar score 2-3 or a defect that degrades quality but doesn't break flows; fix recommended
+Every scored pillar must have at least one specific finding justifying the score.
+</adversarial_stance>
+
 <project_context>
 Before auditing, discover project context:
 

agents/gsd-verifier.md

@@ -12,9 +12,9 @@ color: green
 ---
 
 <role>
-You are a GSD phase verifier. You verify that a phase achieved its GOAL, not just completed its TASKS.
+A completed phase has been submitted for goal-backward verification. Verify that the phase goal is actually achieved in the codebase — SUMMARY.md claims are not evidence.
 
-Your job: Goal-backward verification. Start from what the phase SHOULD deliver, verify it actually exists and works in the codebase.
+Goal-backward verification. Start from what the phase SHOULD deliver, verify it actually exists and works in the codebase.
 
 @~/.claude/get-shit-done/references/mandatory-initial-read.md
 
@@ -22,6 +22,22 @@ Your job: Goal-backward verification. Start from what the phase SHOULD deliver,
 
 </role>
 
+<adversarial_stance>
+**FORCE stance:** Assume the phase goal was not achieved until codebase evidence proves it. Your starting hypothesis: tasks completed, goal missed. Falsify the SUMMARY.md narrative.
+
+**Common failure modes — how verifiers go soft:**
+- Trusting SUMMARY.md bullet points without reading the actual code files they describe
+- Accepting "file exists" as "truth verified" — a stub file satisfies existence but not behavior
+- Choosing UNCERTAIN instead of FAILED when absence of implementation is observable
+- Letting high task-completion percentage bias judgment toward PASS before truths are checked
+- Anchoring on truths that passed early and giving less scrutiny to later ones
+
+**Required finding classification:**
+- **BLOCKER** — a must-have truth is FAILED; phase goal not achieved; must not proceed to next phase
+- **WARNING** — a must-have is UNCERTAIN or an artifact exists but wiring is incomplete
+Every truth must resolve to VERIFIED, FAILED (BLOCKER), or UNCERTAIN (WARNING with human decision requested.
+</adversarial_stance>
+
 <required_reading>
 @~/.claude/get-shit-done/references/verification-overrides.md
 @~/.claude/get-shit-done/references/gates.md

bin/gsd-sdk.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * bin/gsd-sdk.js — back-compat shim for external callers of `gsd-sdk`.
+ *
+ * When the parent package is installed globally (`npm install -g get-shit-done-cc`
+ * or `npx get-shit-done-cc`), npm creates a `gsd-sdk` symlink in the global bin
+ * directory pointing at this file. npm correctly chmods bin entries from a tarball,
+ * so the execute-bit problem that afflicted the sub-install approach (issue #2453)
+ * cannot occur here.
+ *
+ * This shim resolves sdk/dist/cli.js relative to its own location and delegates
+ * to it via `node`, so `gsd-sdk <args>` behaves identically to
+ * `node <packageDir>/sdk/dist/cli.js <args>`.
+ *
+ * Call sites (slash commands, agent prompts, hook scripts) continue to work without
+ * changes because `gsd-sdk` still resolves on PATH — it just comes from this shim
+ * in the parent package rather than from a separately installed @gsd-build/sdk.
+ */
+
+'use strict';
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const cliPath = path.resolve(__dirname, '..', 'sdk', 'dist', 'cli.js');
+
+const result = spawnSync(process.execPath, [cliPath, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+process.exit(result.status ?? 1);

commands/gsd/insert-phase.md

@@ -4,7 +4,6 @@ description: Insert urgent work as decimal phase (e.g., 72.1) between existing p
 argument-hint: <after> <description>
 allowed-tools:
   - Read
-  - Write
   - Bash
 ---
 

commands/gsd/quick.md

@@ -71,7 +71,7 @@ For each directory found:
 - Check if PLAN.md exists
 - Check if SUMMARY.md exists; if so, read `status` from its frontmatter via:
   ```bash
-  gsd-sdk query frontmatter.get .planning/quick/{dir}/SUMMARY.md status 2>/dev/null
+  gsd-sdk query frontmatter.get .planning/quick/{dir}/SUMMARY.md status
   ```
 - Determine directory creation date: `stat -f "%SB" -t "%Y-%m-%d"` (macOS) or `stat -c "%w"` (Linux); fall back to the date prefix in the directory name (format: `YYYYMMDD-` prefix)
 - Derive display status:

commands/gsd/reapply-patches.md

@@ -129,7 +129,7 @@ The quality of the merge depends on having a **pristine baseline** — the origi
 
 Check for baseline sources in priority order:
 
-### Option A: Git history (most reliable)
+### Option A: Pristine hash from backup-meta.json + git history (most reliable)
 If the config directory is a git repository:
 ```bash
 CONFIG_DIR=$(dirname "$PATCHES_DIR")
@@ -137,15 +137,35 @@ if git -C "$CONFIG_DIR" rev-parse --git-dir >/dev/null 2>&1; then
   HAS_GIT=true
 fi
 ```
-When `HAS_GIT=true`, use `git log` to find the commit where GSD was originally installed (before user edits). For each file, the pristine baseline can be extracted with:
+When `HAS_GIT=true`, use the `pristine_hashes` recorded in `backup-meta.json` to locate the correct baseline commit. For each file, iterate commits that touched it and find the one whose blob SHA-256 matches the recorded pristine hash:
 ```bash
-git -C "$CONFIG_DIR" log --diff-filter=A --format="%H" -- "{file_path}"
+# Get the expected pristine SHA-256 from backup-meta.json
+PRISTINE_HASH=$(jq -r ".pristine_hashes[\"${file_path}\"] // empty" "$PATCHES_DIR/backup-meta.json")
+
+BASELINE_COMMIT=""
+if [ -n "$PRISTINE_HASH" ]; then
+  # Walk commits that touched this file, pick the one matching the pristine hash
+  while IFS= read -r commit_hash; do
+    blob_hash=$(git -C "$CONFIG_DIR" show "${commit_hash}:${file_path}" 2>/dev/null | sha256sum | cut -d' ' -f1)
+    if [ "$blob_hash" = "$PRISTINE_HASH" ]; then
+      BASELINE_COMMIT="$commit_hash"
+      break
+    fi
+  done < <(git -C "$CONFIG_DIR" log --format="%H" -- "${file_path}")
+fi
+
+# Fallback: if no pristine hash in backup-meta (older installer), use first-add commit
+if [ -z "$BASELINE_COMMIT" ]; then
+  BASELINE_COMMIT=$(git -C "$CONFIG_DIR" log --diff-filter=A --format="%H" -- "${file_path}" | tail -1)
+fi
 ```
-This gives the commit that first added the file (the install commit). Extract the pristine version:
+Extract the pristine version from the matched commit:
 ```bash
-git -C "$CONFIG_DIR" show {install_commit}:{file_path}
+git -C "$CONFIG_DIR" show "${BASELINE_COMMIT}:${file_path}"
 ```
 
+**Why this matters:** `git log --diff-filter=A` returns the commit that *first added* the file, which is the wrong baseline on repos that have been through multiple GSD update cycles. The `pristine_hashes` field in `backup-meta.json` records the SHA-256 of the file as it existed in the pre-update GSD release — matching against it finds the correct baseline regardless of how many updates have occurred.
+
 ### Option B: Pristine snapshot directory
 Check if a `gsd-pristine/` directory exists alongside `gsd-local-patches/`:
 ```bash

commands/gsd/settings-advanced.md

@@ -0,0 +1,39 @@
+---
+name: gsd:settings-advanced
+description: Power-user configuration — plan bounce, timeouts, branch templates, cross-AI execution, runtime knobs
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Interactive configuration of GSD power-user knobs that don't belong in the common-case `/gsd-settings` prompt.
+
+Routes to the settings-advanced workflow which handles:
+- Config existence ensuring (workstream-aware path resolution)
+- Current settings reading and parsing
+- Sectioned prompts: Planning Tuning, Execution Tuning, Discussion Tuning, Cross-AI Execution, Git Customization, Runtime / Output
+- Config merging that preserves every unrelated key
+- Confirmation table display
+
+Use `/gsd-settings` for the common-case toggles (model profile, research/plan_check/verifier, branching strategy, context warnings). Use `/gsd-settings-advanced` once those are set and you want to tune the internals.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/settings-advanced.md
+</execution_context>
+
+<process>
+**Follow the settings-advanced workflow** from `@~/.claude/get-shit-done/workflows/settings-advanced.md`.
+
+The workflow handles all logic including:
+1. Config file creation with defaults if missing (via `gsd-sdk query config-ensure-section`)
+2. Current config reading
+3. Six sectioned AskUserQuestion batches with current values pre-selected
+4. Numeric-input validation (non-numeric rejected, empty input keeps current)
+5. Answer parsing and config merging (preserves unrelated keys)
+6. File writing (atomic)
+7. Confirmation table display
+</process>

commands/gsd/settings-integrations.md

@@ -0,0 +1,44 @@
+---
+name: gsd:settings-integrations
+description: Configure third-party API keys, code-review CLI routing, and agent-skill injection
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Interactive configuration of GSD's third-party integration surface:
+- Search API keys: `brave_search`, `firecrawl`, `exa_search`, and
+  the `search_gitignored` toggle
+- Code-review CLI routing: `review.models.{claude,codex,gemini,opencode}`
+- Agent-skill injection: `agent_skills.<agent-type>`
+
+API keys are stored plaintext in `.planning/config.json` but are masked
+(`****<last-4>`) in every piece of interactive output. The workflow never
+echoes plaintext to stdout, stderr, or any log.
+
+This command is deliberately distinct from `/gsd-settings` (workflow toggles)
+and any `/gsd-settings-advanced` tuning surface. It handles *connectivity*,
+not pipeline shape.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/settings-integrations.md
+</execution_context>
+
+<process>
+**Follow the settings-integrations workflow** from
+`@~/.claude/get-shit-done/workflows/settings-integrations.md`.
+
+The workflow handles:
+1. Resolving `$GSD_CONFIG_PATH` (flat vs workstream)
+2. Reading current integration values (masked for display)
+3. Section 1 — Search Integrations: Brave / Firecrawl / Exa / search_gitignored
+4. Section 2 — Review CLI Routing: review.models.{claude,codex,gemini,opencode}
+5. Section 3 — Agent Skills Injection: agent_skills.<agent-type>
+6. Writing values via `gsd-sdk query config-set` (which merges, preserving
+   unrelated keys)
+7. Masked confirmation display
+</process>

commands/gsd/sketch.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:sketch
-description: Rapidly sketch UI/design ideas using throwaway HTML mockups with multi-variant exploration
-argument-hint: "<design idea to explore> [--quick]"
+description: Sketch UI/design ideas with throwaway HTML mockups, or propose what to sketch next (frontier mode)
+argument-hint: "[design idea to explore] [--quick] [--text] or [frontier]"
 allowed-tools:
   - Read
   - Write
@@ -10,11 +10,20 @@ allowed-tools:
   - Grep
   - Glob
   - AskUserQuestion
+  - WebSearch
+  - WebFetch
+  - mcp__context7__resolve-library-id
+  - mcp__context7__query-docs
 ---
 <objective>
 Explore design directions through throwaway HTML mockups before committing to implementation.
 Each sketch produces 2-3 variants for comparison. Sketches live in `.planning/sketches/` and
-integrate with GSD commit patterns, state tracking, and handoff workflows.
+integrate with GSD commit patterns, state tracking, and handoff workflows. Loads spike
+findings to ground mockups in real data shapes and validated interaction patterns.
+
+Two modes:
+- **Idea mode** (default) — describe a design idea to sketch
+- **Frontier mode** (no argument or "frontier") — analyzes existing sketch landscape and proposes consistency and frontier sketches
 
 Does not require `/gsd-new-project` — auto-creates `.planning/sketches/` if needed.
 </objective>
@@ -41,5 +50,5 @@ Design idea: $ARGUMENTS
 
 <process>
 Execute the sketch workflow from @~/.claude/get-shit-done/workflows/sketch.md end-to-end.
-Preserve all workflow gates (intake, decomposition, variant evaluation, MANIFEST updates, commit patterns).
+Preserve all workflow gates (intake, decomposition, target stack research, variant evaluation, MANIFEST updates, commit patterns).
 </process>

commands/gsd/spike-wrap-up.md

@@ -27,5 +27,5 @@ project history. Output skill goes to `./.claude/skills/spike-findings-[project]
 
 <process>
 Execute the spike-wrap-up workflow from @~/.claude/get-shit-done/workflows/spike-wrap-up.md end-to-end.
-Preserve all curation gates (per-spike review, grouping approval, CLAUDE.md routing line).
+Preserve all workflow gates (auto-include, feature-area grouping, skill synthesis, CLAUDE.md routing line, intelligent next-step routing).
 </process>

commands/gsd/spike.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:spike
-description: Rapidly spike an idea with throwaway experiments to validate feasibility before planning
-argument-hint: "<idea to validate> [--quick]"
+description: Spike an idea through experiential exploration, or propose what to spike next (frontier mode)
+argument-hint: "[idea to validate] [--quick] [--text] or [frontier]"
 allowed-tools:
   - Read
   - Write
@@ -10,11 +10,20 @@ allowed-tools:
   - Grep
   - Glob
   - AskUserQuestion
+  - WebSearch
+  - WebFetch
+  - mcp__context7__resolve-library-id
+  - mcp__context7__query-docs
 ---
 <objective>
-Rapid feasibility validation through focused, throwaway experiments. Each spike answers one
-specific question with observable evidence. Spikes live in `.planning/spikes/` and integrate
-with GSD commit patterns, state tracking, and handoff workflows.
+Spike an idea through experiential exploration — build focused experiments to feel the pieces
+of a future app, validate feasibility, and produce verified knowledge for the real build.
+Spikes live in `.planning/spikes/` and integrate with GSD commit patterns, state tracking,
+and handoff workflows.
+
+Two modes:
+- **Idea mode** (default) — describe an idea to spike
+- **Frontier mode** (no argument or "frontier") — analyzes existing spike landscape and proposes integration and frontier spikes
 
 Does not require `/gsd-new-project` — auto-creates `.planning/spikes/` if needed.
 </objective>
@@ -33,9 +42,10 @@ Idea: $ARGUMENTS
 
 **Available flags:**
 - `--quick` — Skip decomposition/alignment, jump straight to building. Use when you already know what to spike.
+- `--text` — Use plain-text numbered lists instead of AskUserQuestion (for non-Claude runtimes).
 </context>
 
 <process>
 Execute the spike workflow from @~/.claude/get-shit-done/workflows/spike.md end-to-end.
-Preserve all workflow gates (decomposition, risk ordering, verification, MANIFEST updates, commit patterns).
+Preserve all workflow gates (prior spike check, decomposition, research, risk ordering, observability assessment, verification, MANIFEST updates, commit patterns).
 </process>

commands/gsd/sync-skills.md

@@ -0,0 +1,19 @@
+---
+name: gsd:sync-skills
+description: Sync managed GSD skills across runtime roots so multi-runtime users stay aligned after an update
+allowed-tools:
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Sync managed `gsd-*` skill directories from one canonical runtime's skills root to one or more destination runtime skills roots.
+
+Routes to the sync-skills workflow which handles:
+- Argument parsing (--from, --to, --dry-run, --apply)
+- Runtime skills root resolution via install.js --skills-root
+- Diff computation (CREATE / UPDATE / REMOVE per destination)
+- Dry-run reporting (default — no writes)
+- Apply execution (copy and remove with idempotency)
+- Non-GSD skill preservation (only gsd-* dirs are touched)
+</objective>

commands/gsd/thread.md

@@ -38,7 +38,7 @@ ls .planning/threads/*.md 2>/dev/null
 For each thread file found:
 - Read frontmatter `status` field via:
   ```bash
-  gsd-sdk query frontmatter.get .planning/threads/{file} status 2>/dev/null
+  gsd-sdk query frontmatter.get .planning/threads/{file} status
   ```
 - If frontmatter `status` field is missing, fall back to reading markdown heading `## Status: OPEN` (or IN PROGRESS / RESOLVED) from the file body
 - Read frontmatter `updated` field for the last-updated date

docs/AGENTS.md

@@ -343,18 +343,26 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 
 | Property | Value |
 |----------|-------|
-| **Spawned by** | `/gsd-map-codebase` |
+| **Spawned by** | `/gsd-map-codebase`, post-execute drift gate in `/gsd:execute-phase` |
 | **Parallelism** | 4 instances (tech, architecture, quality, concerns) |
 | **Tools** | Read, Bash, Grep, Glob, Write |
 | **Model (balanced)** | Haiku |
 | **Color** | Cyan |
-| **Produces** | `.planning/codebase/*.md` (7 documents) |
+| **Produces** | `.planning/codebase/*.md` (7 documents, with `last_mapped_commit` frontmatter) |
 
 **Key behaviors:**
 - Read-only exploration + structured output
 - Writes documents directly to disk
 - No reasoning required — pattern extraction from file contents
 
+**`--paths <p1,p2,...>` scope hint (#2003):**
+Accepts an optional `--paths` directive in its prompt. When present, the
+mapper restricts Glob/Grep/Bash exploration to the listed repo-relative path
+prefixes — this is the incremental-remap path used by the post-execute
+codebase-drift gate. Path values that contain `..`, start with `/`, or
+include shell metacharacters are rejected. Without the hint, the mapper
+runs its default whole-repo scan.
+
 ---
 
 ### gsd-debugger

docs/ARCHITECTURE.md

@@ -76,6 +76,7 @@ Every agent spawned by an orchestrator gets a clean context window (up to 200K t
 ### 2. Thin Orchestrators
 
 Workflow files (`get-shit-done/workflows/*.md`) never do heavy lifting. They:
+
 - Load context via `gsd-sdk query init.<workflow>` (or legacy `gsd-tools.cjs init <workflow>`)
 - Spawn specialized agents with focused prompts
 - Collect results and route to the next step
@@ -84,6 +85,7 @@ Workflow files (`get-shit-done/workflows/*.md`) never do heavy lifting. They:
 ### 3. File-Based State
 
 All state lives in `.planning/` as human-readable Markdown and JSON. No database, no server, no external dependencies. This means:
+
 - State survives context resets (`/clear`)
 - State is inspectable by both humans and agents
 - State can be committed to git for team visibility
@@ -95,6 +97,7 @@ Workflow feature flags follow the **absent = enabled** pattern. If a key is miss
 ### 5. Defense in Depth
 
 Multiple layers prevent common failure modes:
+
 - Plans are verified before execution (plan-checker agent)
 - Execution produces atomic commits per task
 - Post-execution verification checks against phase goals
@@ -107,6 +110,7 @@ Multiple layers prevent common failure modes:
 ### Commands (`commands/gsd/*.md`)
 
 User-facing entry points. Each file contains YAML frontmatter (name, description, allowed-tools) and a prompt body that bootstraps the workflow. Commands are installed as:
+
 - **Claude Code:** Custom slash commands (`/gsd-command-name`)
 - **OpenCode / Kilo:** Slash commands (`/gsd-command-name`)
 - **Codex:** Skills (`$gsd-command-name`)
@@ -118,6 +122,7 @@ User-facing entry points. Each file contains YAML frontmatter (name, description
 ### Workflows (`get-shit-done/workflows/*.md`)
 
 Orchestration logic that commands reference. Contains the step-by-step process including:
+
 - Context loading via `gsd-sdk query` init handlers (or legacy `gsd-tools.cjs init`)
 - Agent spawn instructions with model resolution
 - Gate/checkpoint definitions
@@ -126,9 +131,37 @@ Orchestration logic that commands reference. Contains the step-by-step process i
 
 **Total workflows:** see [`docs/INVENTORY.md`](INVENTORY.md#workflows) for the authoritative count and full roster.
 
+#### Progressive disclosure for workflows
+
+Workflow files are loaded verbatim into Claude's context every time the
+corresponding `/gsd:*` command is invoked. To keep that cost bounded, the
+workflow size budget enforced by `tests/workflow-size-budget.test.cjs`
+mirrors the agent budget from #2361:
+
+| Tier      | Per-file line limit |
+|-----------|--------------------|
+| `XL`      | 1700 — top-level orchestrators (`execute-phase`, `plan-phase`, `new-project`) |
+| `LARGE`   | 1500 — multi-step planners and large feature workflows |
+| `DEFAULT` | 1000 — focused single-purpose workflows (the target tier) |
+
+`workflows/discuss-phase.md` is held to a stricter <500-line ceiling per
+issue #2551. When a workflow grows beyond its tier, extract per-mode bodies
+into `workflows/<workflow>/modes/<mode>.md`, templates into
+`workflows/<workflow>/templates/`, and shared knowledge into
+`get-shit-done/references/`. The parent file becomes a thin dispatcher that
+Reads only the mode and template files needed for the current invocation.
+
+`workflows/discuss-phase/` is the canonical example of this pattern —
+parent dispatches, modes/ holds per-flag behavior (`power.md`, `all.md`,
+`auto.md`, `chain.md`, `text.md`, `batch.md`, `analyze.md`, `default.md`,
+`advisor.md`), and templates/ holds CONTEXT.md, DISCUSSION-LOG.md, and
+checkpoint.json schemas that are read only when the corresponding output
+file is being written.
+
 ### Agents (`agents/*.md`)
 
 Specialized agent definitions with frontmatter specifying:
+
 - `name` — Agent identifier
 - `description` — Role and purpose
 - `tools` — Allowed tool access (Read, Write, Edit, Bash, Grep, Glob, WebSearch, etc.)
@@ -141,6 +174,7 @@ Specialized agent definitions with frontmatter specifying:
 Shared knowledge documents that workflows and agents `@-reference` (see [`docs/INVENTORY.md`](INVENTORY.md#references-41-shipped) for the authoritative count and full roster):
 
 **Core references:**
+
 - `checkpoints.md` — Checkpoint type definitions and interaction patterns
 - `gates.md` — 4 canonical gate types (Confirm, Quality, Safety, Transition) wired into plan-checker and verifier
 - `model-profiles.md` — Per-agent model tier assignments
@@ -156,6 +190,7 @@ Shared knowledge documents that workflows and agents `@-reference` (see [`docs/I
 - `common-bug-patterns.md` — Common bug patterns for code review and verification
 
 **Workflow references:**
+
 - `agent-contracts.md` — Formal interface between orchestrators and agents
 - `context-budget.md` — Context window budget allocation rules
 - `continuation-format.md` — Session continuation/resume format
@@ -190,7 +225,7 @@ The planner agent (`agents/gsd-planner.md`) was decomposed from a single monolit
 
 ### Templates (`get-shit-done/templates/`)
 
-Markdown templates for all planning artifacts. Used by `gsd-tools.cjs template fill` and `scaffold` commands to create pre-structured files:
+Markdown templates for all planning artifacts. Used by `gsd-sdk query template.fill` / `phase.scaffold` (and legacy `gsd-tools.cjs template fill` / top-level `scaffold`) to create pre-structured files:
 - `project.md`, `requirements.md`, `roadmap.md`, `state.md` — Core project files
 - `phase-prompt.md` — Phase execution prompt template
 - `summary.md` (+ `summary-minimal.md`, `summary-standard.md`, `summary-complex.md`) — Granularity-aware summary templates
@@ -224,27 +259,29 @@ See [`docs/INVENTORY.md`](INVENTORY.md#hooks-11-shipped) for the authoritative 1
 
 Node.js CLI utility (`gsd-tools.cjs`) with domain modules split across `get-shit-done/bin/lib/` (see [`docs/INVENTORY.md`](INVENTORY.md#cli-modules-24-shipped) for the authoritative roster):
 
-| Module | Responsibility |
-|--------|---------------|
-| `core.cjs` | Error handling, output formatting, shared utilities |
-| `state.cjs` | STATE.md parsing, updating, progression, metrics |
-| `phase.cjs` | Phase directory operations, decimal numbering, plan indexing |
-| `roadmap.cjs` | ROADMAP.md parsing, phase extraction, plan progress |
-| `config.cjs` | config.json read/write, section initialization |
-| `verify.cjs` | Plan structure, phase completeness, reference, commit validation |
-| `template.cjs` | Template selection and filling with variable substitution |
-| `frontmatter.cjs` | YAML frontmatter CRUD operations |
-| `init.cjs` | Compound context loading for each workflow type |
-| `milestone.cjs` | Milestone archival, requirements marking |
-| `commands.cjs` | Misc commands (slug, timestamp, todos, scaffolding, stats) |
-| `model-profiles.cjs` | Model profile resolution table |
-| `security.cjs` | Path traversal prevention, prompt injection detection, safe JSON parsing, shell argument validation |
-| `uat.cjs` | UAT file parsing, verification debt tracking, audit-uat support |
-| `docs.cjs` | Docs-update workflow init, Markdown scanning, monorepo detection |
-| `workstream.cjs` | Workstream CRUD, migration, session-scoped active pointer |
-| `schema-detect.cjs` | Schema-drift detection for ORM patterns (Prisma, Drizzle, etc.) |
-| `profile-pipeline.cjs` | User behavioral profiling data pipeline, session file scanning |
-| `profile-output.cjs` | Profile rendering, USER-PROFILE.md and dev-preferences.md generation |
+
+| Module                 | Responsibility                                                                                      |
+| ---------------------- | --------------------------------------------------------------------------------------------------- |
+| `core.cjs`             | Error handling, output formatting, shared utilities                                                 |
+| `state.cjs`            | STATE.md parsing, updating, progression, metrics                                                    |
+| `phase.cjs`            | Phase directory operations, decimal numbering, plan indexing                                        |
+| `roadmap.cjs`          | ROADMAP.md parsing, phase extraction, plan progress                                                 |
+| `config.cjs`           | config.json read/write, section initialization                                                      |
+| `verify.cjs`           | Plan structure, phase completeness, reference, commit validation                                    |
+| `template.cjs`         | Template selection and filling with variable substitution                                           |
+| `frontmatter.cjs`      | YAML frontmatter CRUD operations                                                                    |
+| `init.cjs`             | Compound context loading for each workflow type                                                     |
+| `milestone.cjs`        | Milestone archival, requirements marking                                                            |
+| `commands.cjs`         | Misc commands (slug, timestamp, todos, scaffolding, stats)                                          |
+| `model-profiles.cjs`   | Model profile resolution table                                                                      |
+| `security.cjs`         | Path traversal prevention, prompt injection detection, safe JSON parsing, shell argument validation |
+| `uat.cjs`              | UAT file parsing, verification debt tracking, audit-uat support                                     |
+| `docs.cjs`             | Docs-update workflow init, Markdown scanning, monorepo detection                                    |
+| `workstream.cjs`       | Workstream CRUD, migration, session-scoped active pointer                                           |
+| `schema-detect.cjs`    | Schema-drift detection for ORM patterns (Prisma, Drizzle, etc.)                                     |
+| `profile-pipeline.cjs` | User behavioral profiling data pipeline, session file scanning                                      |
+| `profile-output.cjs`   | Profile rendering, USER-PROFILE.md and dev-preferences.md generation                                |
+
 
 ---
 
@@ -255,10 +292,10 @@ Node.js CLI utility (`gsd-tools.cjs`) with domain modules split across `get-shit
 ```
 Orchestrator (workflow .md)
     │
-    ├── Load context: gsd-tools.cjs init <workflow> <phase>
+    ├── Load context: gsd-sdk query init.<workflow> <phase> (or legacy gsd-tools.cjs init)
     │   Returns JSON with: project info, config, state, phase details
     │
-    ├── Resolve model: gsd-tools.cjs resolve-model <agent-name>
+    ├── Resolve model: gsd-sdk query resolve-model <agent-name>
     │   Returns: opus | sonnet | haiku | inherit
     │
     ├── Spawn Agent (Task/SubAgent call)
@@ -269,27 +306,29 @@ Orchestrator (workflow .md)
     │
     ├── Collect result
     │
-    └── Update state: gsd-tools.cjs state update/patch/advance-plan
+    └── Update state: gsd-sdk query state.update / state.patch / state.advance-plan (or legacy gsd-tools.cjs)
 ```
 
 ### Primary Agent Spawn Categories
 
 Conceptual spawn-pattern taxonomy for the 21 primary agents. For the authoritative 31-agent roster (including the 10 advanced/specialized agents such as `gsd-pattern-mapper`, `gsd-code-reviewer`, `gsd-code-fixer`, `gsd-ai-researcher`, `gsd-domain-researcher`, `gsd-eval-planner`, `gsd-eval-auditor`, `gsd-framework-selector`, `gsd-debug-session-manager`, `gsd-intel-updater`), see [`docs/INVENTORY.md`](INVENTORY.md#agents-31-shipped).
 
-| Category | Agents | Parallelism |
-|----------|--------|-------------|
-| **Researchers** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4 parallel (stack, features, architecture, pitfalls); advisor spawns during discuss-phase |
-| **Synthesizers** | gsd-research-synthesizer | Sequential (after researchers complete) |
-| **Planners** | gsd-planner, gsd-roadmapper | Sequential |
-| **Checkers** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | Sequential (verification loop, max 3 iterations) |
-| **Executors** | gsd-executor | Parallel within waves, sequential across waves |
-| **Verifiers** | gsd-verifier | Sequential (after all executors complete) |
-| **Mappers** | gsd-codebase-mapper | 4 parallel (tech, arch, quality, concerns) |
-| **Debuggers** | gsd-debugger | Sequential (interactive) |
-| **Auditors** | gsd-ui-auditor, gsd-security-auditor | Sequential |
-| **Doc Writers** | gsd-doc-writer, gsd-doc-verifier | Sequential (writer then verifier) |
-| **Profilers** | gsd-user-profiler | Sequential |
-| **Analyzers** | gsd-assumptions-analyzer | Sequential (during discuss-phase) |
+
+| Category         | Agents                                                                                  | Parallelism                                                                               |
+| ---------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| **Researchers**  | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4 parallel (stack, features, architecture, pitfalls); advisor spawns during discuss-phase |
+| **Synthesizers** | gsd-research-synthesizer                                                                | Sequential (after researchers complete)                                                   |
+| **Planners**     | gsd-planner, gsd-roadmapper                                                             | Sequential                                                                                |
+| **Checkers**     | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor          | Sequential (verification loop, max 3 iterations)                                          |
+| **Executors**    | gsd-executor                                                                            | Parallel within waves, sequential across waves                                            |
+| **Verifiers**    | gsd-verifier                                                                            | Sequential (after all executors complete)                                                 |
+| **Mappers**      | gsd-codebase-mapper                                                                     | 4 parallel (tech, arch, quality, concerns)                                                |
+| **Debuggers**    | gsd-debugger                                                                            | Sequential (interactive)                                                                  |
+| **Auditors**     | gsd-ui-auditor, gsd-security-auditor                                                    | Sequential                                                                                |
+| **Doc Writers**  | gsd-doc-writer, gsd-doc-verifier                                                        | Sequential (writer then verifier)                                                         |
+| **Profilers**    | gsd-user-profiler                                                                       | Sequential                                                                                |
+| **Analyzers**    | gsd-assumptions-analyzer                                                                | Sequential (during discuss-phase)                                                         |
+
 
 ### Wave Execution Model
 
@@ -305,6 +344,7 @@ Wave Analysis:
 ```
 
 Each executor gets:
+
 - Fresh 200K context window (or up to 1M for models that support it)
 - The specific PLAN.md to execute
 - Project context (PROJECT.md, STATE.md)
@@ -317,14 +357,13 @@ When the context window is 500K+ tokens (1M-class models like Opus 4.6, Sonnet 4
 - **Executor agents** receive prior wave SUMMARY.md files and the phase CONTEXT.md/RESEARCH.md, enabling cross-plan awareness within a phase
 - **Verifier agents** receive all PLAN.md, SUMMARY.md, CONTEXT.md files plus REQUIREMENTS.md, enabling history-aware verification
 
-The orchestrator reads `context_window` from config (`gsd-tools.cjs config-get context_window`) and conditionally includes richer context when the value is >= 500,000. For standard 200K windows, prompts use truncated versions with cache-friendly ordering to maximize context efficiency.
+The orchestrator reads `context_window` from config (`gsd-sdk query config-get context_window`, or legacy `gsd-tools.cjs config-get`) and conditionally includes richer context when the value is >= 500,000. For standard 200K windows, prompts use truncated versions with cache-friendly ordering to maximize context efficiency.
 
 #### Parallel Commit Safety
 
 When multiple executors run within the same wave, two mechanisms prevent conflicts:
 
-1. **`--no-verify` commits** — Parallel agents skip pre-commit hooks (which can cause build lock contention, e.g., cargo lock fights in Rust projects). The orchestrator runs `git hook run pre-commit` once after each wave completes.
-
+1. `--no-verify` commits — Parallel agents skip pre-commit hooks (which can cause build lock contention, e.g., cargo lock fights in Rust projects). The orchestrator runs `git hook run pre-commit` once after each wave completes.
 2. **STATE.md file locking** — All `writeStateMd()` calls use lockfile-based mutual exclusion (`STATE.md.lock` with `O_EXCL` atomic creation). This prevents the read-modify-write race condition where two agents read STATE.md, modify different fields, and the last writer overwrites the other's changes. Includes stale lock detection (10s timeout) and spin-wait with jitter.
 
 ---
@@ -372,7 +411,9 @@ plan-phase
     ├── Research gate (blocks if RESEARCH.md has unresolved open questions)
     ├── Phase Researcher → RESEARCH.md
     ├── Planner (with reachability check) → PLAN.md files
-    └── Plan Checker → Verify loop (max 3x)
+    ├── Plan Checker → Verify loop (max 3x)
+    ├── Requirements coverage gate (REQ-IDs → plans)
+    └── Decision coverage gate (CONTEXT.md `<decisions>` → plans, BLOCKING — #2492)
     │
     ▼
 state planned-phase → STATE.md (Planned/Ready to execute)
@@ -383,6 +424,7 @@ execute-phase (context reduction: truncated prompts, cache-friendly ordering)
     ├── Executor per plan → code + atomic commits
     ├── SUMMARY.md per plan
     └── Verifier → VERIFICATION.md
+        └── Decision coverage gate (CONTEXT.md decisions → shipped artifacts, NON-BLOCKING — #2492)
     │
     ▼
 verify-work → UAT.md (user acceptance testing)
@@ -430,6 +472,7 @@ UI-SPEC.md (per phase) ───────────────────
 ```
 
 Equivalent paths for other runtimes:
+
 - **OpenCode:** `~/.config/opencode/` or `~/.opencode/`
 - **Kilo:** `~/.config/kilo/` or `~/.kilo/`
 - **Gemini CLI:** `~/.gemini/`
@@ -454,8 +497,8 @@ Equivalent paths for other runtimes:
 │   ├── ARCHITECTURE.md
 │   └── PITFALLS.md
 ├── codebase/               # Brownfield mapping (from /gsd-map-codebase)
-│   ├── STACK.md
-│   ├── ARCHITECTURE.md
+│   ├── STACK.md            # YAML frontmatter carries `last_mapped_commit`
+│   ├── ARCHITECTURE.md     # for the post-execute drift gate (#2003)
 │   ├── CONVENTIONS.md
 │   ├── CONCERNS.md
 │   ├── STRUCTURE.md
@@ -489,6 +532,30 @@ Equivalent paths for other runtimes:
 └── continue-here.md        # Context handoff (from pause-work)
 ```
 
+### Post-Execute Codebase Drift Gate (#2003)
+
+After the last wave of `/gsd:execute-phase` commits, the workflow runs a
+non-blocking `codebase_drift_gate` step (between `schema_drift_gate` and
+`verify_phase_goal`). It compares the diff `last_mapped_commit..HEAD`
+against `.planning/codebase/STRUCTURE.md` and counts four kinds of
+structural elements:
+
+1. New directories outside mapped paths
+2. New barrel exports at `(packages|apps)/<name>/src/index.*`
+3. New migration files
+4. New route modules under `routes/` or `api/`
+
+If the count meets `workflow.drift_threshold` (default 3), the gate either
+**warns** (default) with the suggested `/gsd:map-codebase --paths …` command,
+or **auto-remaps** (`workflow.drift_action = auto-remap`) by spawning
+`gsd-codebase-mapper` scoped to the affected paths. Any error in detection
+or remap is logged and the phase continues — drift detection cannot fail
+verification.
+
+`last_mapped_commit` lives in YAML frontmatter at the top of each
+`.planning/codebase/*.md` file; `bin/lib/drift.cjs` provides
+`readMappedCommit` and `writeMappedCommit` round-trip helpers.
+
 ---
 
 ## Installer Architecture
@@ -499,16 +566,16 @@ The installer (`bin/install.js`, ~3,000 lines) handles:
 2. **Location selection** — Global (`--global`) or local (`--local`)
 3. **File deployment** — Copies commands, workflows, references, templates, agents, hooks
 4. **Runtime adaptation** — Transforms file content per runtime:
-   - Claude Code: Uses as-is
-   - OpenCode: Converts commands/agents to OpenCode-compatible flat command + subagent format
-   - Kilo: Reuses the OpenCode conversion pipeline with Kilo config paths
-   - Codex: Generates TOML config + skills from commands
-   - Copilot: Maps tool names (Read→read, Bash→execute, etc.)
-   - Gemini: Adjusts hook event names (`AfterTool` instead of `PostToolUse`)
-   - Antigravity: Skills-first with Google model equivalents
-   - Trae: Skills-first install to `~/.trae` / `./.trae` with no `settings.json` or hook integration
-   - Cline: Writes `.clinerules` for rule-based integration
-   - Augment Code: Skills-first with full skill conversion and config management
+  - Claude Code: Uses as-is
+  - OpenCode: Converts commands/agents to OpenCode-compatible flat command + subagent format
+  - Kilo: Reuses the OpenCode conversion pipeline with Kilo config paths
+  - Codex: Generates TOML config + skills from commands
+  - Copilot: Maps tool names (Read→read, Bash→execute, etc.)
+  - Gemini: Adjusts hook event names (`AfterTool` instead of `PostToolUse`)
+  - Antigravity: Skills-first with Google model equivalents
+  - Trae: Skills-first install to `~/.trae` / `./.trae` with no `settings.json` or hook integration
+  - Cline: Writes `.clinerules` for rule-based integration
+  - Augment Code: Skills-first with full skill conversion and config management
 5. **Path normalization** — Replaces `~/.claude/` paths with runtime-specific paths
 6. **Settings integration** — Registers hooks in runtime's `settings.json`
 7. **Patch backup** — Since v1.17, backs up locally modified files to `gsd-local-patches/` for `/gsd-reapply-patches`
@@ -545,11 +612,13 @@ Runtime Engine (Claude Code / Gemini CLI)
 
 ### Context Monitor Thresholds
 
-| Remaining Context | Level | Agent Behavior |
-|-------------------|-------|----------------|
-| > 35% | Normal | No warning injected |
-| ≤ 35% | WARNING | "Avoid starting new complex work" |
-| ≤ 25% | CRITICAL | "Context nearly exhausted, inform user" |
+
+| Remaining Context | Level    | Agent Behavior                          |
+| ----------------- | -------- | --------------------------------------- |
+| > 35%             | Normal   | No warning injected                     |
+| ≤ 35%             | WARNING  | "Avoid starting new complex work"       |
+| ≤ 25%             | CRITICAL | "Context nearly exhausted, inform user" |
+
 
 Debounce: 5 tool uses between repeated warnings. Severity escalation (WARNING→CRITICAL) bypasses debounce.
 
@@ -564,12 +633,14 @@ Debounce: 5 tool uses between repeated warnings. Severity escalation (WARNING→
 ### Security Hooks (v1.27)
 
 **Prompt Guard** (`gsd-prompt-guard.js`):
+
 - Triggers on Write/Edit to `.planning/` files
 - Scans content for prompt injection patterns (role override, instruction bypass, system tag injection)
 - Advisory-only — logs detection, does not block
 - Patterns are inlined (subset of `security.cjs`) for hook independence
 
 **Workflow Guard** (`gsd-workflow-guard.js`):
+
 - Triggers on Write/Edit to non-`.planning/` files
 - Detects edits outside GSD workflow context (no active `/gsd-` command or Task subagent)
 - Advises using `/gsd-quick` or `/gsd-fast` for state-tracked changes
@@ -581,18 +652,20 @@ Debounce: 5 tool uses between repeated warnings. Severity escalation (WARNING→
 
 GSD supports multiple AI coding runtimes through a unified command/workflow architecture:
 
-| Runtime | Command Format | Agent System | Config Location |
-|---------|---------------|--------------|-----------------|
-| Claude Code | `/gsd-command` | Task spawning | `~/.claude/` |
-| OpenCode | `/gsd-command` | Subagent mode | `~/.config/opencode/` |
-| Kilo | `/gsd-command` | Subagent mode | `~/.config/kilo/` |
-| Gemini CLI | `/gsd-command` | Task spawning | `~/.gemini/` |
-| Codex | `$gsd-command` | Skills | `~/.codex/` |
-| Copilot | `/gsd-command` | Agent delegation | `~/.github/` |
-| Antigravity | Skills | Skills | `~/.gemini/antigravity/` |
-| Trae | Skills | Skills | `~/.trae/` |
-| Cline | Rules | Rules | `.clinerules` |
-| Augment Code | Skills | Skills | Augment config |
+
+| Runtime      | Command Format | Agent System     | Config Location          |
+| ------------ | -------------- | ---------------- | ------------------------ |
+| Claude Code  | `/gsd-command` | Task spawning    | `~/.claude/`             |
+| OpenCode     | `/gsd-command` | Subagent mode    | `~/.config/opencode/`    |
+| Kilo         | `/gsd-command` | Subagent mode    | `~/.config/kilo/`        |
+| Gemini CLI   | `/gsd-command` | Task spawning    | `~/.gemini/`             |
+| Codex        | `$gsd-command` | Skills           | `~/.codex/`              |
+| Copilot      | `/gsd-command` | Agent delegation | `~/.github/`             |
+| Antigravity  | Skills         | Skills           | `~/.gemini/antigravity/` |
+| Trae         | Skills         | Skills           | `~/.trae/`               |
+| Cline        | Rules          | Rules            | `.clinerules`            |
+| Augment Code | Skills         | Skills           | Augment config           |
+
 
 ### Abstraction Points
 
@@ -602,4 +675,4 @@ GSD supports multiple AI coding runtimes through a unified command/workflow arch
 4. **Path conventions** — Each runtime stores config in different directories
 5. **Model references** — `inherit` profile lets GSD defer to runtime's model selection
 
-The installer handles all translation at install time. Workflows and agents are written in Claude Code's native format and transformed during deployment.
+The installer handles all translation at install time. Workflows and agents are written in Claude Code's native format and transformed during deployment.

docs/CLI-TOOLS.md

@@ -1,29 +1,71 @@
 # GSD CLI Tools Reference
 
-> Programmatic API reference for `gsd-tools.cjs`. Used by workflows and agents internally. For user-facing commands, see [Command Reference](COMMANDS.md).
+> Surface-area reference for `get-shit-done/bin/gsd-tools.cjs` (legacy Node CLI). Workflows and agents should prefer `gsd-sdk query` or `@gsd-build/sdk` where a handler exists — see [SDK and programmatic access](#sdk-and-programmatic-access). For slash commands and user flows, see [Command Reference](COMMANDS.md).
 
 ---
 
 ## Overview
 
-`gsd-tools.cjs` is a Node.js CLI utility that replaces repetitive inline bash patterns across GSD's ~50 command, workflow, and agent files. It centralizes: config parsing, model resolution, phase lookup, git commits, summary verification, state management, and template operations.
+`gsd-tools.cjs` centralizes config parsing, model resolution, phase lookup, git commits, summary verification, state management, and template operations across GSD commands, workflows, and agents.
 
-**Preferred for new orchestration:** Many of the same operations are available as `gsd-sdk query <command>` (see `sdk/src/query/index.ts` and `docs/QUERY-HANDLERS.md`). Use that in workflows and examples where the handler exists; keep `node … gsd-tools.cjs` for commands not yet in the registry (for example graphify) or when you need CJS-only flags.
 
-**Location:** `get-shit-done/bin/gsd-tools.cjs`
-**Modules:** see the [Module Architecture](#module-architecture) table; the `get-shit-done/bin/lib/` directory is authoritative.
+|                    |                                                                                                                                                                                                        |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Shipped path**   | `get-shit-done/bin/gsd-tools.cjs`                                                                                                                                                                      |
+| **Implementation** | 20 domain modules under `get-shit-done/bin/lib/` (the directory is authoritative)                                                                                                                        |
+| **Status**         | Maintained for parity tests and CJS-only entrypoints; `gsd-sdk query` / SDK registry are the supported path for new orchestration (see [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md)). |
+
+
+**Usage (CJS):**
 
-**Usage:**
 ```bash
 node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
 ```
 
-**Global Flags:**
-| Flag | Description |
-|------|-------------|
-| `--raw` | Machine-readable output (JSON or plain text, no formatting) |
-| `--cwd <path>` | Override working directory (for sandboxed subagents) |
-| `--ws <name>` | Target a specific workstream context (SDK only) |
+**Global flags (CJS):**
+
+
+| Flag           | Description                                                                  |
+| -------------- | ---------------------------------------------------------------------------- |
+| `--raw`        | Machine-readable output (JSON or plain text, no formatting)                  |
+| `--cwd <path>` | Override working directory (for sandboxed subagents)                         |
+| `--ws <name>`  | Workstream context (also honored when the SDK spawns this binary; see below) |
+
+
+---
+
+## SDK and programmatic access
+
+Use this when authoring workflows, not when you only need the command list below.
+
+**1. CLI — `gsd-sdk query <argv…>`**
+
+- Resolves argv with the same **longest-prefix** rules as the typed registry (`resolveQueryArgv` in `sdk/src/query/registry.ts`). Unregistered commands **fail fast** — use `node …/gsd-tools.cjs` only for handlers not in the registry.
+- Full matrix (CJS command → registry key, CLI-only tools, aliases, golden tiers): [sdk/src/query/QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md).
+
+**2. TypeScript — `@gsd-build/sdk` (`GSDTools`, `createRegistry`)**
+
+- `GSDTools` (used by `PhaseRunner`, `InitRunner`, and `GSD.createTools()`) always shells out to `gsd-tools.cjs` via `execFile` — there is no in-process registry path on this class. For typed, in-process dispatch use `createRegistry()` from `sdk/src/query/index.ts`, or invoke `gsd-sdk query` (see [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md)).
+- Conventions: mutation event wiring, `GSDError` vs `{ data: { error } }`, locks, and stubs — [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md).
+
+**CJS → SDK examples (same project directory):**
+
+
+| Legacy CJS                               | Preferred `gsd-sdk query` (examples) |
+| ---------------------------------------- | ------------------------------------ |
+| `node gsd-tools.cjs init phase-op 12`    | `gsd-sdk query init phase-op 12`     |
+| `node gsd-tools.cjs phase-plan-index 12` | `gsd-sdk query phase-plan-index 12`  |
+| `node gsd-tools.cjs state json`          | `gsd-sdk query state json`           |
+| `node gsd-tools.cjs roadmap analyze`     | `gsd-sdk query roadmap analyze`      |
+
+
+**SDK state reads:** `gsd-sdk query state json` / `state.json` and `gsd-sdk query state load` / `state.load` currently share one native handler (rebuilt STATE.md frontmatter — CJS `cmdStateJson`). The legacy CJS `state load` payload (`config`, `state_raw`, existence flags) is still **CLI-only** via `node …/gsd-tools.cjs state load` until a separate registry handler exists. Full routing and golden rules: [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md).
+
+**CLI-only (not in registry):** e.g. **graphify**, **from-gsd2** / **gsd2-import** — call `gsd-tools.cjs` until registered.
+
+**Mutation events (SDK):** `QUERY_MUTATION_COMMANDS` in `sdk/src/query/index.ts` lists commands that may emit structured events after a successful dispatch. Exceptions called out in QUERY-HANDLERS: `state validate` (read-only), `skill-manifest` (writes only with `--write`), `intel update` (stub).
+
+**Golden parity:** Policy and CJS↔SDK test categories are documented under **Golden parity** in [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md).
 
 ---
 
@@ -373,7 +415,7 @@ node gsd-tools.cjs from-gsd2 [--path <dir>] [--force] [--dry-run]
 node gsd-tools.cjs commit <message> [--files f1 f2] [--amend] [--no-verify]
 ```
 
-> **`--no-verify`**: Skips pre-commit hooks. Used by parallel executor agents during wave-based execution to avoid build lock contention (e.g., cargo lock fights in Rust projects). The orchestrator runs hooks once after each wave completes. Do not use `--no-verify` during sequential execution — let hooks run normally.
+> `--no-verify`: Skips pre-commit hooks. Used by parallel executor agents during wave-based execution to avoid build lock contention (e.g., cargo lock fights in Rust projects). The orchestrator runs hooks once after each wave completes. Do not use `--no-verify` during sequential execution — let hooks run normally.
 
 # Web search (requires Brave API key)
 node gsd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]
@@ -430,3 +472,30 @@ User-facing entry point: `/gsd-graphify` (see [Command Reference](COMMANDS.md#gs
 | Audit | `lib/audit.cjs` | Phase/milestone audit queue handlers; `audit-open` helper |
 | GSD2 Import | `lib/gsd2-import.cjs` | Reverse-migration importer from GSD-2 projects (backs `/gsd-from-gsd2`) |
 | Intel | `lib/intel.cjs` | Queryable codebase intelligence index (backs `/gsd-intel`) |
+
+---
+
+## Reviewer CLI Routing
+
+`review.models.<cli>` maps a reviewer flavor to a shell command invoked by the code-review workflow. Set via [`/gsd-settings-integrations`](COMMANDS.md#gsd-settings-integrations) or directly:
+
+```bash
+gsd-sdk query config-set review.models.codex    "codex exec --model gpt-5"
+gsd-sdk query config-set review.models.gemini   "gemini -m gemini-2.5-pro"
+gsd-sdk query config-set review.models.opencode "opencode run --model claude-sonnet-4"
+gsd-sdk query config-set review.models.claude   ""   # clear — fall back to session model
+```
+
+Slugs are validated against `[a-zA-Z0-9_-]+`; empty or path-containing slugs are rejected. See [`docs/CONFIGURATION.md`](CONFIGURATION.md#code-review-cli-routing) for the full field reference.
+
+## Secret Handling
+
+API keys configured via `/gsd-settings-integrations` (`brave_search`, `firecrawl`, `exa_search`) are written plaintext to `.planning/config.json` but are masked (`****<last-4>`) in every `config-set` / `config-get` output, confirmation table, and interactive prompt. See `get-shit-done/bin/lib/secrets.cjs` for the masking implementation. The `config.json` file itself is the security boundary — protect it with filesystem permissions and keep it out of git (`.planning/` is gitignored by default).
+
+---
+
+## See also
+
+- [sdk/src/query/QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md) — registry matrix, routing, golden parity, intentional CJS differences
+- [Architecture](ARCHITECTURE.md) — where `gsd-sdk query` fits in orchestration
+- [Command Reference](COMMANDS.md) — user-facing `/gsd:` commands

docs/COMMANDS.md

@@ -562,6 +562,24 @@ Interactive command center for managing multiple phases from one terminal.
 /gsd-manager                        # Open command center dashboard
 ```
 
+**Checkpoint Heartbeats (#2410):**
+
+Background `execute-phase` runs emit `[checkpoint]` markers at every wave and plan
+boundary so the Claude API SSE stream never idles long enough to trigger
+`Stream idle timeout - partial response received` on multi-plan phases. The
+format is:
+
+```
+[checkpoint] phase {N} wave {W}/{M} starting, {count} plan(s), {P}/{Q} plans done
+[checkpoint] phase {N} wave {W}/{M} plan {plan_id} starting ({P}/{Q} plans done)
+[checkpoint] phase {N} wave {W}/{M} plan {plan_id} complete ({P}/{Q} plans done)
+[checkpoint] phase {N} wave {W}/{M} complete, {P}/{Q} plans done ({ok}/{count} ok)
+```
+
+If a background phase fails partway through, grep the transcript for `[checkpoint]`
+to see the last confirmed boundary. The manager's background-completion handler
+uses these markers to report partial progress when an agent errors out.
+
 **Manager Passthrough Flags:**
 
 Configure per-step flags in `.planning/config.json` under `manager.flags`. These flags are appended to each dispatched command:
@@ -1037,12 +1055,73 @@ Manage parallel workstreams for concurrent work on different milestone areas.
 
 ### `/gsd-settings`
 
-Interactive configuration of workflow toggles and model profile.
+Interactive configuration of workflow toggles and model profile. Questions are grouped into six visual sections:
+
+- **Planning** — Research, Plan Checker, Pattern Mapper, Nyquist, UI Phase, UI Gate, AI Phase
+- **Execution** — Verifier, TDD Mode, Code Review, Code Review Depth _(conditional — only when Code Review is on)_, UI Review
+- **Docs & Output** — Commit Docs, Skip Discuss, Worktrees
+- **Features** — Intel, Graphify
+- **Model & Pipeline** — Model Profile, Auto-Advance, Branching
+- **Misc** — Context Warnings, Research Qs
+
+All answers are merged via `gsd-sdk query config-set` into the resolved project config path (`.planning/config.json` for a standard install, or `.planning/workstreams/<active>/config.json` when a workstream is active), preserving unrelated keys. After confirmation, the user may save the full settings object to `~/.gsd/defaults.json` so future `/gsd-new-project` runs start from the same baseline.
 
 ```bash
 /gsd-settings                       # Interactive config
 ```
 
+### `/gsd-settings-advanced`
+
+Interactive configuration of power-user knobs — plan bounce, subagent timeouts, branch templates, cross-AI delegation, context window, and runtime output. Use after `/gsd-settings` once the common-case toggles are dialed in.
+
+Six sections, each a focused prompt batch:
+
+| Section | Keys |
+|---------|------|
+| Planning Tuning | `workflow.plan_bounce`, `workflow.plan_bounce_passes`, `workflow.plan_bounce_script`, `workflow.subagent_timeout`, `workflow.inline_plan_threshold` |
+| Execution Tuning | `workflow.node_repair`, `workflow.node_repair_budget`, `workflow.auto_prune_state` |
+| Discussion Tuning | `workflow.max_discuss_passes` |
+| Cross-AI Execution | `workflow.cross_ai_execution`, `workflow.cross_ai_command`, `workflow.cross_ai_timeout` |
+| Git Customization | `git.base_branch`, `git.phase_branch_template`, `git.milestone_branch_template` |
+| Runtime / Output | `response_language`, `context_window`, `search_gitignored`, `graphify.build_timeout` |
+
+Current values are pre-selected; an empty input keeps the existing value. Numeric fields reject non-numeric input and re-prompt. Null-allowed fields (`plan_bounce_script`, `cross_ai_command`, `response_language`) accept an empty input as a clear. Writes route through `gsd-sdk query config-set`, which preserves every unrelated key.
+
+```bash
+/gsd-settings-advanced              # Six-section interactive config
+```
+
+See [CONFIGURATION.md](CONFIGURATION.md) for the full schema and defaults.
+
+### `/gsd-settings-integrations`
+
+Interactive configuration of third-party integrations and cross-tool routing.
+Distinct from `/gsd-settings` (workflow toggles) — this command handles
+connectivity: API keys, reviewer CLI routing, and agent-skill injection.
+
+Covers:
+
+- **Search integrations:** `brave_search`, `firecrawl`, `exa_search` API keys,
+  and the `search_gitignored` toggle.
+- **Code-review CLI routing:** `review.models.{claude,codex,gemini,opencode}`
+  — a shell command per reviewer flavor.
+- **Agent-skill injection:** `agent_skills.<agent-type>` — skill names
+  injected into an agent's spawn frontmatter. Agent-type slugs are validated
+  against `[a-zA-Z0-9_-]+` so path separators and shell metacharacters are
+  rejected.
+
+API keys are stored plaintext in `.planning/config.json` but displayed masked
+(`****<last-4>`) in every interactive output, confirmation table, and
+`config-set` stdout/stderr line. Plaintext is never echoed, never logged,
+and never written to any file outside `config.json` by this workflow.
+
+```bash
+/gsd-settings-integrations           # Interactive config (three sections)
+```
+
+See [`docs/CONFIGURATION.md`](CONFIGURATION.md) for the per-field reference and
+[`docs/CLI-TOOLS.md`](CLI-TOOLS.md) for the reviewer-CLI routing contract.
+
 ### `/gsd-set-profile`
 
 Quick profile switch.

docs/CONFIGURATION.md

@@ -21,7 +21,7 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new
     "search_gitignored": false,
     "sub_repos": []
   },
-  "context_profile": null,
+  "context": null,
   "workflow": {
     "research": true,
     "plan_check": true,
@@ -30,10 +30,12 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new
     "nyquist_validation": true,
     "ui_phase": true,
     "ui_safety_gate": true,
+    "ui_review": true,
     "node_repair": true,
     "node_repair_budget": 2,
     "research_before_questions": false,
     "discuss_mode": "discuss",
+    "max_discuss_passes": 3,
     "skip_discuss": false,
     "tdd_mode": false,
     "text_mode": false,
@@ -43,13 +45,15 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new
     "plan_bounce": false,
     "plan_bounce_script": null,
     "plan_bounce_passes": 2,
+    "plan_chunked": false,
     "code_review_command": null,
     "cross_ai_execution": false,
     "cross_ai_command": null,
     "cross_ai_timeout": 300,
     "security_enforcement": true,
     "security_asvs_level": 1,
-    "security_block_on": "high"
+    "security_block_on": "high",
+    "post_planning_gaps": true
   },
   "hooks": {
     "context_warnings": true,
@@ -108,11 +112,15 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new
 |---------|------|---------|---------|-------------|
 | `mode` | enum | `interactive`, `yolo` | `interactive` | `yolo` auto-approves decisions; `interactive` confirms at each step |
 | `granularity` | enum | `coarse`, `standard`, `fine` | `standard` | Controls phase count: `coarse` (3-5), `standard` (5-8), `fine` (8-12) |
-| `model_profile` | enum | `quality`, `balanced`, `budget`, `inherit` | `balanced` | Model tier for each agent (see [Model Profiles](#model-profiles)) |
+| `model_profile` | enum | `quality`, `balanced`, `budget`, `adaptive`, `inherit` | `balanced` | Model tier for each agent (see [Model Profiles](#model-profiles)). `adaptive` was added per [#1713](https://github.com/gsd-build/get-shit-done/issues/1713) / [#1806](https://github.com/gsd-build/get-shit-done/issues/1806) and resolves the same way as the other tiers under runtime-aware profiles. |
+| `runtime` | string | `claude`, `codex`, or any string | (none) | Active runtime for [runtime-aware profile resolution](#runtime-aware-profiles-2517). When set, profile tiers (opus/sonnet/haiku) resolve to runtime-native model IDs. Today only the Codex install path emits per-agent model IDs from this resolver; other runtimes (`opencode`, `gemini`, `qwen`, `copilot`, …) consume the resolver at spawn time and gain dedicated install-path support in [#2612](https://github.com/gsd-build/get-shit-done/issues/2612). When unset (default), behavior is unchanged from prior versions. Added in v1.39 |
+| `model_profile_overrides.<runtime>.<tier>` | string \| object | per-runtime tier override | (none) | Override the runtime-aware tier mapping for a specific `(runtime, tier)`. Tier is one of `opus`, `sonnet`, `haiku`. Value is either a model ID string (e.g. `"gpt-5-pro"`) or `{ model, reasoning_effort }`. See [Runtime-Aware Profiles](#runtime-aware-profiles-2517). Added in v1.39 |
 | `project_code` | string | any short string | (none) | Prefix for phase directory names (e.g., `"ABC"` produces `ABC-01-setup/`). Added in v1.31 |
 | `response_language` | string | language code | (none) | Language for agent responses (e.g., `"pt"`, `"ko"`, `"ja"`). Propagates to all spawned agents for cross-phase language consistency. Added in v1.32 |
+| `context_window` | number | any integer | `200000` | Context window size in tokens. Set `1000000` for 1M-context models (e.g., `claude-opus-4-7[1m]`). Values `>= 500000` enable adaptive context enrichment (full-body reads of prior SUMMARY.md, deeper anti-pattern reads). Configured via `/gsd-settings-advanced`. |
 | `context_profile` | string | `dev`, `research`, `review` | (none) | Execution context preset that applies a pre-configured bundle of mode, model, and workflow settings for the current type of work. Added in v1.34 |
 | `claude_md_path` | string | any file path | `./CLAUDE.md` | Custom output path for the generated CLAUDE.md file. Useful for monorepos or projects that need CLAUDE.md in a non-root location. Defaults to `./CLAUDE.md` at the project root. Added in v1.36 |
+| `claude_md_assembly.mode` | enum | `embed`, `link` | `embed` | Controls how managed sections are written into CLAUDE.md. `embed` (default) inlines content between GSD markers. `link` writes `@.planning/<source-path>` instead — Claude Code expands the reference at runtime, reducing CLAUDE.md size by ~65% on typical projects. `link` only applies to sections that have a real source file; `workflow` and fallback sections always embed. Per-block overrides: `claude_md_assembly.blocks.<section>` (e.g. `claude_md_assembly.blocks.architecture: link`). Added in v1.38 |
 | `context` | string | any text | (none) | Custom context string injected into every agent prompt for the project. Use to provide persistent project-specific guidance (e.g., coding conventions, team practices) that every agent should be aware of |
 | `phase_naming` | string | any string | (none) | Custom prefix for phase directory names. When set, overrides the auto-generated phase slug (e.g., `"feature"` produces `feature-01-setup/` instead of the roadmap-derived slug) |
 | `brave_search` | boolean | `true`/`false` | auto-detected | Override auto-detection of Brave Search API availability. When unset, GSD checks for `BRAVE_API_KEY` env var or `~/.gsd/brave_api_key` file |
@@ -124,6 +132,41 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new
 
 ---
 
+## Integration Settings
+
+Configured interactively via [`/gsd-settings-integrations`](COMMANDS.md#gsd-settings-integrations). These are *connectivity* settings — API keys and cross-tool routing — and are intentionally kept separate from `/gsd-settings` (workflow toggles).
+
+### Search API keys
+
+API key fields accept a string value (the key itself). They can also be set to the sentinels `true`/`false`/`null` to override auto-detection from env vars / `~/.gsd/*_api_key` files (legacy behavior, see rows above).
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `brave_search` | string \| boolean \| null | `null` | Brave Search API key used for web research. Displayed as `****<last-4>` in all UI / `config-set` output; never echoed plaintext |
+| `firecrawl` | string \| boolean \| null | `null` | Firecrawl API key for deep-crawl scraping. Masked in display |
+| `exa_search` | string \| boolean \| null | `null` | Exa Search API key for semantic search. Masked in display |
+
+**Masking convention (`get-shit-done/bin/lib/secrets.cjs`):** keys 8+ characters render as `****<last-4>`; shorter keys render as `****`; `null`/empty renders as `(unset)`. Plaintext is written as-is to `.planning/config.json` — that file is the security boundary — but the CLI, confirmation tables, logs, and `AskUserQuestion` descriptions never display the plaintext. This applies to the `config-set` command output itself: `config-set brave_search <key>` returns a JSON payload with the value masked.
+
+### Code-review CLI routing
+
+`review.models.<cli>` maps a reviewer flavor to a shell command. The code-review workflow shells out using this command when a matching flavor is requested.
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `review.models.claude` | string | (session model) | Command for Claude-flavored review. Defaults to the session model when unset |
+| `review.models.codex` | string | `null` | Command for Codex review, e.g. `"codex exec --model gpt-5"` |
+| `review.models.gemini` | string | `null` | Command for Gemini review, e.g. `"gemini -m gemini-2.5-pro"` |
+| `review.models.opencode` | string | `null` | Command for OpenCode review, e.g. `"opencode run --model claude-sonnet-4"` |
+
+The `<cli>` slug is validated against `[a-zA-Z0-9_-]+`. Empty or path-containing slugs are rejected by `config-set`.
+
+### Agent-skill injection (dynamic)
+
+`agent_skills.<agent-type>` extends the `agent_skills` map documented below. Slug is validated against `[a-zA-Z0-9_-]+` — no path separators, no whitespace, no shell metacharacters. Configured interactively via `/gsd-settings-integrations`.
+
+---
+
 ## Workflow Toggles
 
 All workflow toggles follow the **absent = enabled** pattern. If a key is missing from config, it defaults to `true`.
@@ -137,10 +180,12 @@ All workflow toggles follow the **absent = enabled** pattern. If a key is missin
 | `workflow.nyquist_validation` | boolean | `true` | Test coverage mapping during plan-phase research |
 | `workflow.ui_phase` | boolean | `true` | Generate UI design contracts for frontend phases |
 | `workflow.ui_safety_gate` | boolean | `true` | Prompt to run /gsd-ui-phase for frontend phases during plan-phase |
+| `workflow.ui_review` | boolean | `true` | Run visual quality audit (`/gsd-ui-review`) after phase execution in autonomous mode. When `false`, the UI audit step is skipped. |
 | `workflow.node_repair` | boolean | `true` | Autonomous task repair on verification failure |
 | `workflow.node_repair_budget` | number | `2` | Max repair attempts per failed task |
 | `workflow.research_before_questions` | boolean | `false` | Run research before discussion questions instead of after |
 | `workflow.discuss_mode` | string | `'discuss'` | Controls how `/gsd-discuss-phase` gathers context. `'discuss'` (default) asks questions one-by-one. `'assumptions'` reads the codebase first, generates structured assumptions with confidence levels, and only asks you to correct what's wrong. Added in v1.28 |
+| `workflow.max_discuss_passes` | number | `3` | Maximum number of question rounds in discuss-phase before the workflow stops asking. Useful in headless/auto mode to prevent infinite discussion loops. |
 | `workflow.skip_discuss` | boolean | `false` | When `true`, `/gsd-autonomous` bypasses the discuss-phase entirely, writing minimal CONTEXT.md from the ROADMAP phase goal. Useful for projects where developer preferences are fully captured in PROJECT.md/REQUIREMENTS.md. Added in v1.28 |
 | `workflow.text_mode` | boolean | `false` | Replaces AskUserQuestion TUI menus with plain-text numbered lists. Required for Claude Code remote sessions (`/rc` mode) where TUI menus don't render. Can also be set per-session with `--text` flag on discuss-phase. Added in v1.28 |
 | `workflow.use_worktrees` | boolean | `true` | When `false`, disables git worktree isolation for parallel execution. Users who prefer sequential execution or whose environment does not support worktrees can disable this. Added in v1.31 |
@@ -149,6 +194,8 @@ All workflow toggles follow the **absent = enabled** pattern. If a key is missin
 | `workflow.plan_bounce` | boolean | `false` | Run external validation script against generated plans. When enabled, the plan-phase orchestrator pipes each PLAN.md through the script specified by `plan_bounce_script` and blocks on non-zero exit. Added in v1.36 |
 | `workflow.plan_bounce_script` | string | (none) | Path to the external script invoked for plan bounce validation. Receives the PLAN.md path as its first argument. Required when `plan_bounce` is `true`. Added in v1.36 |
 | `workflow.plan_bounce_passes` | number | `2` | Number of sequential bounce passes to run. Each pass feeds the previous pass's output back into the validator. Higher values increase rigor at the cost of latency. Added in v1.36 |
+| `workflow.post_planning_gaps` | boolean | `true` | Unified post-planning gap report (#2493). After all plans are generated and committed, scans REQUIREMENTS.md and CONTEXT.md `<decisions>` against every PLAN.md in the phase directory, then prints one `Source \| Item \| Status` table. Word-boundary matching (REQ-1 vs REQ-10) and natural sort (REQ-02 before REQ-10). Non-blocking — informational report only. Set to `false` to skip Step 13e of plan-phase. |
+| `workflow.plan_chunked` | boolean | `false` | Enable chunked planning mode. When `true` (or when `--chunked` flag is passed to `/gsd-plan-phase`), the orchestrator splits the single long-lived planner Task into a short outline Task followed by N short per-plan Tasks (~3-5 min each). Each plan is committed individually for crash resilience. If a Task hangs and the terminal is force-killed, rerunning with `--chunked` resumes from the last completed plan. Particularly useful on Windows where long-lived Tasks may hang on stdio. Added in v1.38 |
 | `workflow.code_review_command` | string | (none) | Shell command for external code review integration in `/gsd-ship`. Receives changed file paths via stdin. Non-zero exit blocks the ship workflow. Added in v1.36 |
 | `workflow.tdd_mode` | boolean | `false` | Enable TDD pipeline as a first-class execution mode. When `true`, the planner aggressively applies `type: tdd` to eligible tasks (business logic, APIs, validations, algorithms) and the executor enforces RED/GREEN/REFACTOR gate sequence. An end-of-phase collaborative review checkpoint verifies gate compliance. Added in v1.36 |
 | `workflow.cross_ai_execution` | boolean | `false` | Delegate phase execution to an external AI CLI instead of spawning local executor agents. Useful for leveraging a different model's strengths for specific phases. Added in v1.36 |
@@ -159,6 +206,8 @@ All workflow toggles follow the **absent = enabled** pattern. If a key is missin
 | `workflow.pattern_mapper` | boolean | `true` | Run the `gsd-pattern-mapper` agent between research and planning to map new files to existing codebase analogs |
 | `workflow.subagent_timeout` | number | `600` | Timeout in seconds for individual subagent invocations. Increase for long-running research or execution phases |
 | `workflow.inline_plan_threshold` | number | `3` | Maximum number of tasks in a phase before the planner generates a separate PLAN.md file instead of inlining tasks in the prompt |
+| `workflow.drift_threshold` | number | `3` | Minimum number of new structural elements (new directories, barrel exports, migrations, route modules) introduced during a phase before the post-execute codebase-drift gate takes action. See [#2003](https://github.com/gsd-build/get-shit-done/issues/2003). Added in v1.39 |
+| `workflow.drift_action` | string | `warn` | What to do when `workflow.drift_threshold` is exceeded after `/gsd-execute-phase`. `warn` prints a message suggesting `/gsd-map-codebase --paths …`; `auto-remap` spawns `gsd-codebase-mapper` scoped to the affected paths. Added in v1.39 |
 
 ### Recommended Presets
 
@@ -178,6 +227,17 @@ All workflow toggles follow the **absent = enabled** pattern. If a key is missin
 | `planning.search_gitignored` | boolean | `false` | Add `--no-ignore` to broad searches to include `.planning/` |
 | `planning.sub_repos` | array of strings | `[]` | Paths of nested sub-repos relative to the project root. When set, GSD-aware tooling scopes phase-lookup, path-resolution, and commit operations per sub-repo instead of treating the outer repo as a monorepo |
 
+### Project-Root Resolution in Multi-Repo Workspaces
+
+When `sub_repos` is set and `gsd-tools.cjs` or `gsd-sdk query` is invoked from inside a listed child repo, both CLIs walk up to the parent workspace that owns `.planning/` before dispatching handlers. Resolution order (checked at each ancestor up to 10 levels, never above `$HOME`):
+
+1. If the starting directory already has its own `.planning/`, it is the project root (no walk-up).
+2. Parent has `.planning/config.json` listing the starting directory's top-level segment in `sub_repos` (or the legacy `planning.sub_repos` shape).
+3. Parent has `.planning/config.json` with legacy `multiRepo: true` and the starting directory is inside a git repo.
+4. Parent has `.planning/` and an ancestor up to the candidate parent contains `.git` (heuristic fallback).
+
+If none match, the starting directory is returned unchanged. Explicit `--project-dir /path/to/workspace` is idempotent under this resolution.
+
 ### Auto-Detection
 
 If `.planning/` is in `.gitignore`, `commit_docs` is automatically `false` regardless of config.json. This prevents git errors.
@@ -190,6 +250,7 @@ If `.planning/` is in `.gitignore`, `commit_docs` is automatically `false` regar
 |---------|------|---------|-------------|
 | `hooks.context_warnings` | boolean | `true` | Show context window usage warnings via context monitor hook |
 | `hooks.workflow_guard` | boolean | `false` | Warn when file edits happen outside GSD workflow context (advises using `/gsd-quick` or `/gsd-fast`) |
+| `statusline.show_last_command` | boolean | `false` | Append `last: /<cmd>` suffix to the statusline showing the most recently invoked slash command. Opt-in; reads the active session transcript to extract the latest `<command-name>` tag (closes #2538) |
 
 The prompt injection guard hook (`gsd-prompt-guard.js`) is always active and cannot be disabled — it's a security feature, not a workflow toggle.
 
@@ -247,7 +308,7 @@ Any GSD agent type can receive skills. Common types:
 
 ### How It Works
 
-At spawn time, workflows call `node gsd-tools.cjs agent-skills <type>` to load configured skills. If skills exist for the agent type, they are injected as an `<agent_skills>` block in the Task() prompt:
+At spawn time, workflows call `gsd-sdk query agent-skills <type>` (or legacy `node gsd-tools.cjs agent-skills <type>`) to load configured skills. If skills exist for the agent type, they are injected as an `<agent_skills>` block in the Task() prompt:
 
 ```xml
 <agent_skills>
@@ -264,7 +325,7 @@ If no skills are configured, the block is omitted (zero overhead).
 Set skills via the CLI:
 
 ```bash
-node gsd-tools.cjs config-set agent_skills.gsd-executor '["skills/my-skill"]'
+gsd-sdk query config-set agent_skills.gsd-executor '["skills/my-skill"]'
 ```
 
 ---
@@ -292,10 +353,10 @@ Toggle optional capabilities via the `features.*` config namespace. Feature flag
 
 ```bash
 # Enable a feature
-node gsd-tools.cjs config-set features.global_learnings true
+gsd-sdk query config-set features.global_learnings true
 
 # Disable a feature
-node gsd-tools.cjs config-set features.thinking_partner false
+gsd-sdk query config-set features.thinking_partner false
 ```
 
 The `features.*` namespace is a dynamic key pattern — new feature flags can be added without modifying `VALID_CONFIG_KEYS`. Any key matching `features.<name>` is accepted by the config system.
@@ -394,6 +455,8 @@ Control confirmation prompts during workflows.
 
 Settings for the security enforcement feature (v1.31). All follow the **absent = enabled** pattern. These keys live under `workflow.*` in `.planning/config.json` — matching the shipped template and the runtime reads in `workflows/plan-phase.md`, `workflows/execute-phase.md`, `workflows/secure-phase.md`, and `workflows/verify-work.md`.
 
+These keys live under `workflow.*` — that is where the workflows and installer write and read them. Setting them at the top level of `config.json` is silently ignored.
+
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
 | `workflow.security_enforcement` | boolean | `true` | Enable threat-model-anchored security verification via `/gsd-secure-phase`. When `false`, security checks are skipped entirely |
@@ -402,6 +465,60 @@ Settings for the security enforcement feature (v1.31). All follow the **absent =
 
 ---
 
+## Decision Coverage Gates (`workflow.context_coverage_gate`)
+
+When `discuss-phase` writes implementation decisions into CONTEXT.md
+`<decisions>`, two gates ensure those decisions survive the trip into
+plans and shipped code (issue #2492).
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `workflow.context_coverage_gate` | boolean | `true` | Toggle for both decision-coverage gates. When `false`, both the plan-phase translation gate and the verify-phase validation gate skip silently. |
+
+### What the gates do
+
+**Plan-phase translation gate (BLOCKING).** Runs immediately after the
+existing requirements coverage gate, before plans are committed. For each
+trackable decision in `<decisions>`, it checks that the decision id
+(`D-NN`) or its text appears in at least one plan's `must_haves`,
+`truths`, or body. A miss surfaces the missing decision by id and refuses
+to mark the phase planned.
+
+**Verify-phase validation gate (NON-BLOCKING).** Runs alongside the other
+verify steps. Searches every shipped artifact (PLAN.md, SUMMARY.md, files
+modified, recent commit subjects) for each trackable decision. Misses are
+written to VERIFICATION.md as a warning section but do **not** flip the
+overall verification status. The asymmetry is deliberate — by verify time
+the work is done, and a fuzzy substring miss should not fail an otherwise
+green phase.
+
+### How to write decisions the gates accept
+
+The discuss-phase template already produces `D-NN`-numbered decisions.
+The gate is happiest when:
+
+1. Every plan that implements a decision **cites the id** somewhere —
+   `must_haves.truths: ["D-12: bit offsets exposed"]` or a `D-12:` mention
+   in the plan body. Strict id match is the cheapest, deterministic path.
+2. Soft phrase matching is a fallback for paraphrases — if a 6+-word slice
+   of the decision text appears verbatim in a plan/summary, it counts.
+
+### Opt-outs
+
+A decision is **not** subject to the gates when any of the following
+apply:
+
+- It lives under the `### Claude's Discretion` heading inside `<decisions>`.
+- It is tagged `[informational]`, `[folded]`, or `[deferred]` in its
+  bullet (e.g., `- **D-08 [informational]:** Naming style for internal
+  helpers`).
+
+Use these escape hatches when a decision genuinely doesn't need plan
+coverage — implementation discretion, future ideas captured for the
+record, or items already deferred to a later phase.
+
+---
+
 ## Review Settings
 
 Configure per-CLI model selection for `/gsd-review`. When set, overrides the CLI's default model for that reviewer.
@@ -503,6 +620,17 @@ Override specific agents without changing the entire profile:
 
 Valid override values: `opus`, `sonnet`, `haiku`, `inherit`, or any fully-qualified model ID (e.g., `"openai/o3"`, `"google/gemini-2.5-pro"`).
 
+`model_overrides` can be set in either `.planning/config.json` (per-project)
+or `~/.gsd/defaults.json` (global). Per-project entries win on conflict and
+non-conflicting global entries are preserved, so you can tune a single
+agent's model in one repo without re-setting global defaults. This applies
+uniformly across Claude Code, Codex, OpenCode, Kilo, and the other
+supported runtimes. On Codex and OpenCode, the resolved model is embedded
+into each agent's static config at install time — `spawn_agent` and
+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.
+
 ### Non-Claude Runtimes (Codex, OpenCode, Gemini CLI, Kilo)
 
 When GSD is installed for a non-Claude runtime, the installer automatically sets `resolve_model_ids: "omit"` in `~/.gsd/defaults.json`. This causes GSD to return an empty model parameter for all agents, so each agent uses whatever model the runtime is configured with. No additional setup is needed for the default case.
@@ -540,6 +668,64 @@ The intent is the same as the Claude profile tiers -- use a stronger model for p
 | `true` | Maps aliases to full Claude model IDs (`claude-opus-4-6`) | Claude Code with API that requires full IDs |
 | `"omit"` | Returns empty string (runtime picks its default) | Non-Claude runtimes (Codex, OpenCode, Gemini CLI, Kilo) |
 
+### Runtime-Aware Profiles (#2517)
+
+When `runtime` is set, profile tiers (`opus`/`sonnet`/`haiku`) resolve to runtime-native model IDs instead of Claude aliases. This lets a single shared `.planning/config.json` work cleanly across Claude and Codex.
+
+**Built-in tier maps:**
+
+| Runtime | `opus` | `sonnet` | `haiku` | reasoning_effort |
+|---------|--------|----------|---------|------------------|
+| `claude` | `claude-opus-4-6` | `claude-sonnet-4-6` | `claude-haiku-4-5` | (not used) |
+| `codex` | `gpt-5.4` | `gpt-5.3-codex` | `gpt-5.4-mini` | `xhigh` / `medium` / `medium` |
+
+**Codex example** — one config, tiered models, no large `model_overrides` block:
+
+```json
+{
+  "runtime": "codex",
+  "model_profile": "balanced"
+}
+```
+
+This resolves `gsd-planner` → `gpt-5.4` (xhigh), `gsd-executor` → `gpt-5.3-codex` (medium), `gsd-codebase-mapper` → `gpt-5.4-mini` (medium). The Codex installer embeds `model = "..."` and `model_reasoning_effort = "..."` in each generated agent TOML.
+
+**Claude example** — explicit opt-in resolves to full Claude IDs (no `resolve_model_ids: true` needed):
+
+```json
+{
+  "runtime": "claude",
+  "model_profile": "quality"
+}
+```
+
+**Per-runtime overrides** — replace one or more tier defaults:
+
+```json
+{
+  "runtime": "codex",
+  "model_profile": "quality",
+  "model_profile_overrides": {
+    "codex": {
+      "opus": "gpt-5-pro",
+      "haiku": { "model": "gpt-5-nano", "reasoning_effort": "low" }
+    }
+  }
+}
+```
+
+**Precedence (highest to lowest):**
+
+1. `model_overrides[<agent>]` — explicit per-agent ID always wins.
+2. **Runtime-aware tier resolution** (this section) — when `runtime` is set and profile is not `inherit`.
+3. `resolve_model_ids: "omit"` — returns empty string when no `runtime` is set.
+4. Claude-native default — `model_profile` tier as alias (current default).
+5. `inherit` — propagates literal `inherit` for `Task(model="inherit")` semantics.
+
+**Backwards compatibility.** Setups without `runtime` set see zero behavior change — every existing config continues to work identically. Codex installs that auto-set `resolve_model_ids: "omit"` continue to omit the model field unless the user opts in by setting `runtime: "codex"`.
+
+**Unknown runtimes.** If `runtime` is set to a value with no built-in tier map and no `model_profile_overrides[<runtime>]`, GSD falls back to the Claude-alias safe default rather than emit a model ID the runtime cannot accept. To support a new runtime, populate `model_profile_overrides.<runtime>.{opus,sonnet,haiku}` with valid IDs.
+
 ### Profile Philosophy
 
 | Profile | Philosophy | When to Use |

docs/FEATURES.md

@@ -802,6 +802,45 @@
 | `TESTING.md` | Test infrastructure, coverage, patterns |
 | `INTEGRATIONS.md` | External services, APIs, third-party dependencies |
 
+**Incremental remap — `--paths` (#2003):** The mapper accepts an optional
+`--paths <p1,p2,...>` scope hint. When provided, it restricts exploration
+to the listed repo-relative prefixes instead of scanning the whole tree.
+This is the pathway used by the post-execute codebase-drift gate to refresh
+only the subtrees the phase actually changed. Each produced document carries
+`last_mapped_commit` in its YAML frontmatter so drift can be measured
+against the mapping point, not HEAD.
+
+### 27a. Post-Execute Codebase Drift Detection
+
+**Introduced by:** #2003
+**Trigger:** Runs automatically at the end of every `/gsd:execute-phase`
+**Configuration:**
+- `workflow.drift_threshold` (integer, default `3`) — minimum new
+  structural elements before the gate acts.
+- `workflow.drift_action` (`warn` | `auto-remap`, default `warn`) —
+  warn-only or spawn `gsd-codebase-mapper` with `--paths` scoped to
+  affected subtrees.
+
+**What counts as drift:**
+- New directory outside mapped paths
+- New barrel export at `(packages|apps)/*/src/index.*`
+- New migration file (supabase/prisma/drizzle/src/migrations/…)
+- New route module under `routes/` or `api/`
+
+**Non-blocking guarantee:** any internal failure (missing STRUCTURE.md,
+git errors, mapper spawn failure) logs a single line and the phase
+continues. Drift detection cannot fail verification.
+
+**Requirements:**
+- REQ-DRIFT-01: System MUST detect the four drift categories from `git diff
+  --name-status last_mapped_commit..HEAD`
+- REQ-DRIFT-02: Action fires only when element count ≥ `workflow.drift_threshold`
+- REQ-DRIFT-03: `warn` action MUST NOT spawn any agent
+- REQ-DRIFT-04: `auto-remap` action MUST pass sanitized `--paths` to the mapper
+- REQ-DRIFT-05: Detection/remap failure MUST be non-blocking for `/gsd:execute-phase`
+- REQ-DRIFT-06: `last_mapped_commit` round-trip through YAML frontmatter
+  on each `.planning/codebase/*.md` file
+
 ---
 
 ## Utility Features

docs/INVENTORY-MANIFEST.json

@@ -1,5 +1,5 @@
 {
-  "generated": "2026-04-20",
+  "generated": "2026-04-23",
   "families": {
     "agents": [
       "gsd-advisor-researcher",
@@ -103,6 +103,8 @@
       "/gsd-session-report",
       "/gsd-set-profile",
       "/gsd-settings",
+      "/gsd-settings-advanced",
+      "/gsd-settings-integrations",
       "/gsd-ship",
       "/gsd-sketch",
       "/gsd-sketch-wrap-up",
@@ -110,6 +112,7 @@
       "/gsd-spike",
       "/gsd-spike-wrap-up",
       "/gsd-stats",
+      "/gsd-sync-skills",
       "/gsd-thread",
       "/gsd-ui-phase",
       "/gsd-ui-review",
@@ -149,6 +152,7 @@
       "extract_learnings.md",
       "fast.md",
       "forensics.md",
+      "graduation.md",
       "health.md",
       "help.md",
       "import.md",
@@ -183,6 +187,8 @@
       "scan.md",
       "secure-phase.md",
       "session-report.md",
+      "settings-advanced.md",
+      "settings-integrations.md",
       "settings.md",
       "ship.md",
       "sketch-wrap-up.md",
@@ -191,6 +197,7 @@
       "spike-wrap-up.md",
       "spike.md",
       "stats.md",
+      "sync-skills.md",
       "transition.md",
       "ui-phase.md",
       "ui-review.md",
@@ -226,6 +233,7 @@
       "model-profiles.md",
       "phase-argument-parsing.md",
       "planner-antipatterns.md",
+      "planner-chunked.md",
       "planner-gap-closure.md",
       "planner-reviews.md",
       "planner-revision.md",
@@ -234,6 +242,7 @@
       "project-skills-discovery.md",
       "questioning.md",
       "revision-loop.md",
+      "scout-codebase.md",
       "sketch-interactivity.md",
       "sketch-theme-system.md",
       "sketch-tooling.md",
@@ -253,13 +262,17 @@
       "workstream-flag.md"
     ],
     "cli_modules": [
+      "artifacts.cjs",
       "audit.cjs",
       "commands.cjs",
       "config-schema.cjs",
       "config.cjs",
       "core.cjs",
+      "decisions.cjs",
       "docs.cjs",
+      "drift.cjs",
       "frontmatter.cjs",
+      "gap-checker.cjs",
       "graphify.cjs",
       "gsd2-import.cjs",
       "init.cjs",
@@ -272,6 +285,7 @@
       "profile-pipeline.cjs",
       "roadmap.cjs",
       "schema-detect.cjs",
+      "secrets.cjs",
       "security.cjs",
       "state.cjs",
       "template.cjs",

docs/INVENTORY.md

@@ -54,7 +54,7 @@ Full roster at `agents/gsd-*.md`. The "Primary doc" column flags whether [`docs/
 
 ---
 
-## Commands (82 shipped)
+## Commands (85 shipped)
 
 Full roster at `commands/gsd/*.md`. The groupings below mirror `docs/COMMANDS.md` section order; each row carries the command name, a one-line role derived from the command's frontmatter `description:`, and a link to the source file. `tests/command-count-sync.test.cjs` locks the count against the filesystem.
 
@@ -163,8 +163,11 @@ Full roster at `commands/gsd/*.md`. The groupings below mirror `docs/COMMANDS.md
 | `/gsd-sketch-wrap-up` | Package sketch design findings into a persistent project skill for future build conversations. | [commands/gsd/sketch-wrap-up.md](../commands/gsd/sketch-wrap-up.md) |
 | `/gsd-profile-user` | Generate developer behavioral profile and Claude-discoverable artifacts. | [commands/gsd/profile-user.md](../commands/gsd/profile-user.md) |
 | `/gsd-settings` | Configure GSD workflow toggles and model profile. | [commands/gsd/settings.md](../commands/gsd/settings.md) |
+| `/gsd-settings-advanced` | Power-user configuration — plan bounce, timeouts, branch templates, cross-AI execution, runtime knobs. | [commands/gsd/settings-advanced.md](../commands/gsd/settings-advanced.md) |
+| `/gsd-settings-integrations` | Configure third-party API keys, code-review CLI routing, and agent-skill injection. | [commands/gsd/settings-integrations.md](../commands/gsd/settings-integrations.md) |
 | `/gsd-set-profile` | Switch model profile for GSD agents (quality/balanced/budget/inherit). | [commands/gsd/set-profile.md](../commands/gsd/set-profile.md) |
 | `/gsd-pr-branch` | Create a clean PR branch by filtering out `.planning/` commits. | [commands/gsd/pr-branch.md](../commands/gsd/pr-branch.md) |
+| `/gsd-sync-skills` | Sync managed GSD skill directories across runtime roots for multi-runtime users. | [commands/gsd/sync-skills.md](../commands/gsd/sync-skills.md) |
 | `/gsd-update` | Update GSD to latest version with changelog display. | [commands/gsd/update.md](../commands/gsd/update.md) |
 | `/gsd-reapply-patches` | Reapply local modifications after a GSD update. | [commands/gsd/reapply-patches.md](../commands/gsd/reapply-patches.md) |
 | `/gsd-help` | Show available GSD commands and usage guide. | [commands/gsd/help.md](../commands/gsd/help.md) |
@@ -172,7 +175,7 @@ Full roster at `commands/gsd/*.md`. The groupings below mirror `docs/COMMANDS.md
 
 ---
 
-## Workflows (79 shipped)
+## Workflows (83 shipped)
 
 Full roster at `get-shit-done/workflows/*.md`. Workflows are thin orchestrators that commands reference internally; most are not read directly by end users. Rows below map each workflow file to its role (derived from the `<purpose>` block) and, where applicable, to the command that invokes it.
 
@@ -206,6 +209,7 @@ Full roster at `get-shit-done/workflows/*.md`. Workflows are thin orchestrators
 | `extract_learnings.md` | Extract decisions, lessons, patterns, and surprises from completed phase artifacts. | `/gsd-extract-learnings` |
 | `fast.md` | Execute a trivial task inline without subagent overhead. | `/gsd-fast` |
 | `forensics.md` | Forensics investigation of failed workflows — git, artifacts, and state analysis. | `/gsd-forensics` |
+| `graduation.md` | Cluster recurring LEARNINGS.md items across phases and surface HITL promotion candidates. | `transition.md` (graduation_scan step) |
 | `health.md` | Validate `.planning/` directory integrity and report actionable issues. | `/gsd-health` |
 | `help.md` | Display the complete GSD command reference. | `/gsd-help` |
 | `import.md` | Ingest external plans with conflict detection against existing project decisions. | `/gsd-import` |
@@ -241,6 +245,8 @@ Full roster at `get-shit-done/workflows/*.md`. Workflows are thin orchestrators
 | `secure-phase.md` | Retroactive threat-mitigation audit for a completed phase. | `/gsd-secure-phase` |
 | `session-report.md` | Session report — token usage, work summary, outcomes. | `/gsd-session-report` |
 | `settings.md` | Configure GSD workflow toggles and model profile. | `/gsd-settings`, `/gsd-set-profile` |
+| `settings-advanced.md` | Configure GSD power-user knobs — plan bounce, timeouts, branch templates, cross-AI execution, runtime knobs. | `/gsd-settings-advanced` |
+| `settings-integrations.md` | Configure third-party API keys (Brave/Firecrawl/Exa), `review.models.<cli>` CLI routing, and `agent_skills.<agent-type>` injection with masked (`****<last-4>`) display. | `/gsd-settings-integrations` |
 | `ship.md` | Create PR, run review, and prepare for merge after verification. | `/gsd-ship` |
 | `sketch.md` | Explore design directions through throwaway HTML mockups with 2-3 variants per sketch. | `/gsd-sketch` |
 | `sketch-wrap-up.md` | Curate sketch findings and package them as a persistent `sketch-findings-[project]` skill. | `/gsd-sketch-wrap-up` |
@@ -248,6 +254,7 @@ Full roster at `get-shit-done/workflows/*.md`. Workflows are thin orchestrators
 | `spike.md` | Rapid feasibility validation through focused, throwaway experiments. | `/gsd-spike` |
 | `spike-wrap-up.md` | Curate spike findings and package them as a persistent `spike-findings-[project]` skill. | `/gsd-spike-wrap-up` |
 | `stats.md` | Project statistics rendering — phases, plans, requirements, git metrics. | `/gsd-stats` |
+| `sync-skills.md` | Cross-runtime GSD skill sync — diff and apply `gsd-*` skill directories across runtime roots. | `/gsd-sync-skills` |
 | `transition.md` | Phase-boundary transition workflow — workstream checks, state advancement. | `execute-phase.md`, `/gsd-next` |
 | `ui-phase.md` | Generate UI-SPEC.md design contract via gsd-ui-researcher. | `/gsd-ui-phase` |
 | `ui-review.md` | Retroactive 6-pillar visual audit via gsd-ui-auditor. | `/gsd-ui-review` |
@@ -262,7 +269,7 @@ Full roster at `get-shit-done/workflows/*.md`. Workflows are thin orchestrators
 
 ---
 
-## References (49 shipped)
+## References (51 shipped)
 
 Full roster at `get-shit-done/references/*.md`. References are shared knowledge documents that workflows and agents `@-reference`. The groupings below match [`docs/ARCHITECTURE.md`](ARCHITECTURE.md#references-get-shit-donereferencesmd) — core, workflow, thinking-model clusters, and the modular planner decomposition.
 
@@ -296,6 +303,7 @@ Full roster at `get-shit-done/references/*.md`. References are shared knowledge
 | `continuation-format.md` | Session continuation/resume format. |
 | `domain-probes.md` | Domain-specific probing questions for discuss-phase. |
 | `gate-prompts.md` | Gate/checkpoint prompt templates. |
+| `scout-codebase.md` | Phase-type→codebase-map selection table for discuss-phase scout step (extracted via #2551). |
 | `revision-loop.md` | Plan revision iteration patterns. |
 | `universal-anti-patterns.md` | Universal anti-patterns to detect and avoid. |
 | `artifact-types.md` | Planning artifact type definitions. |
@@ -341,28 +349,33 @@ The `gsd-planner` agent is decomposed into a core agent plus reference modules t
 | Reference | Role |
 |-----------|------|
 | `planner-antipatterns.md` | Planner anti-patterns and specificity examples. |
+| `planner-chunked.md` | Chunked mode return formats (`## OUTLINE COMPLETE`, `## PLAN COMPLETE`) for Windows stdio hang mitigation. |
 | `planner-gap-closure.md` | Gap-closure mode behavior (reads VERIFICATION.md, targeted replanning). |
 | `planner-reviews.md` | Cross-AI review integration (reads REVIEWS.md from `/gsd-review`). |
 | `planner-revision.md` | Plan revision patterns for iterative refinement. |
 | `planner-source-audit.md` | Planner source-audit and authority-limit rules. |
 
-> **Subdirectory:** `get-shit-done/references/few-shot-examples/` contains additional few-shot examples (`plan-checker.md`, `verifier.md`) that are referenced from specific agents. These are not counted in the 49 top-level references.
+> **Subdirectory:** `get-shit-done/references/few-shot-examples/` contains additional few-shot examples (`plan-checker.md`, `verifier.md`) that are referenced from specific agents. These are not counted in the 51 top-level references.
 
 ---
 
-## CLI Modules (25 shipped)
+## CLI Modules (30 shipped)
 
 Full listing: `get-shit-done/bin/lib/*.cjs`.
 
 | Module | Responsibility |
 |--------|----------------|
+| `artifacts.cjs` | Canonical artifact registry — known `.planning/` root file names; used by `gsd-health` W019 lint |
 | `audit.cjs` | Audit dispatch, audit open sessions, audit storage helpers |
 | `commands.cjs` | Misc CLI commands (slug, timestamp, todos, scaffolding, stats) |
 | `config-schema.cjs` | Single source of truth for `VALID_CONFIG_KEYS` and dynamic key patterns; imported by both the validator and the config-schema-docs parity test |
 | `config.cjs` | `config.json` read/write, section initialization; imports validator from `config-schema.cjs` |
 | `core.cjs` | Error handling, output formatting, shared utilities, runtime fallbacks |
+| `decisions.cjs` | Shared parser for CONTEXT.md `<decisions>` blocks (D-NN entries); used by `gap-checker.cjs` and intended for #2492 plan/verify decision gates |
 | `docs.cjs` | Docs-update workflow init, Markdown scanning, monorepo detection |
+| `drift.cjs` | Post-execute codebase structural drift detector (#2003): classifies file changes into new-dir/barrel/migration/route categories and round-trips `last_mapped_commit` frontmatter |
 | `frontmatter.cjs` | YAML frontmatter CRUD operations |
+| `gap-checker.cjs` | Post-planning gap analysis (#2493): unified REQUIREMENTS.md + CONTEXT.md decisions vs PLAN.md coverage report (`gsd-tools gap-analysis`) |
 | `graphify.cjs` | Knowledge-graph build/query/status/diff for `/gsd-graphify` |
 | `gsd2-import.cjs` | External-plan ingest for `/gsd-from-gsd2` |
 | `init.cjs` | Compound context loading for each workflow type |
@@ -375,6 +388,7 @@ Full listing: `get-shit-done/bin/lib/*.cjs`.
 | `profile-pipeline.cjs` | User behavioral profiling data pipeline, session file scanning |
 | `roadmap.cjs` | ROADMAP.md parsing, phase extraction, plan progress |
 | `schema-detect.cjs` | Schema-drift detection for ORM patterns (Prisma, Drizzle, etc.) |
+| `secrets.cjs` | Secret-config masking convention (`****<last-4>`) for integration keys managed by `/gsd-settings-integrations` — keeps plaintext out of `config-set` output |
 | `security.cjs` | Path traversal prevention, prompt injection detection, safe JSON/shell helpers |
 | `state.cjs` | STATE.md parsing, updating, progression, metrics |
 | `template.cjs` | Template selection and filling with variable substitution |

docs/README.md

@@ -26,4 +26,4 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md)
 - **All commands at a glance:** [Command Reference](COMMANDS.md)
 - **Configuring GSD:** [Configuration Reference](CONFIGURATION.md)
 - **How the system works internally:** [Architecture](ARCHITECTURE.md)
-- **Contributing or extending:** [CLI Tools Reference](CLI-TOOLS.md) + [Agent Reference](AGENTS.md)
+- **Contributing or extending:** [CLI Tools Reference](CLI-TOOLS.md) + [Agent Reference](AGENTS.md)

docs/USER-GUIDE.md

@@ -165,18 +165,61 @@ By default, `/gsd-discuss-phase` asks open-ended questions about your implementa
 **Enable:** Set `workflow.discuss_mode` to `'assumptions'` via `/gsd-settings`.
 
 **How it works:**
+
 1. Reads PROJECT.md, codebase mapping, and existing conventions
 2. Generates a structured list of assumptions (tech choices, patterns, file locations)
 3. Presents assumptions for you to confirm, correct, or expand
 4. Writes CONTEXT.md from confirmed assumptions
 
 **When to use:**
+
 - Experienced developers who already know their codebase well
 - Rapid iteration where open-ended questions slow you down
 - Projects where patterns are well-established and predictable
 
 See [docs/workflow-discuss-mode.md](workflow-discuss-mode.md) for the full discuss-mode reference.
 
+### Decision Coverage Gates
+
+The discuss-phase captures implementation decisions in CONTEXT.md under a
+`<decisions>` block as numbered bullets (`- **D-01:** …`). Two gates — added
+for issue #2492 — ensure those decisions survive into plans and shipped
+code.
+
+**Plan-phase translation gate (blocking).** After planning, GSD refuses to
+mark the phase planned until every trackable decision appears in at least
+one plan's `must_haves`, `truths`, or body. The gate names each missed
+decision by id (`D-07: …`) so you know exactly what to add, move, or
+reclassify.
+
+**Verify-phase validation gate (non-blocking).** During verification, GSD
+searches plans, SUMMARY.md, modified files, and recent commit messages for
+each trackable decision. Misses are logged to VERIFICATION.md as a warning
+section; verification status is unchanged. The asymmetry is deliberate —
+the blocking gate is cheap at plan time but hostile at verify time.
+
+**Writing decisions the gate can match.** Two match modes:
+
+1. **Strict id match (recommended).** Cite the decision id anywhere in a
+   plan that implements it — `must_haves.truths: ["D-12: bit offsets
+   exposed"]`, a bullet in the plan body, a frontmatter comment. This is
+   deterministic and unambiguous.
+2. **Soft phrase match (fallback).** If a 6+-word slice of the decision
+   text appears verbatim in any plan or shipped artifact, it counts. This
+   forgives paraphrasing but is less reliable.
+
+**Opting a decision out.** If a decision genuinely should not be tracked —
+an implementation-discretion note, an informational capture, a decision
+already deferred — mark it one of these ways:
+
+- Move it under the `### Claude's Discretion` heading inside `<decisions>`.
+- Tag it in its bullet: `- **D-08 [informational]:** …`,
+  `- **D-09 [folded]:** …`, `- **D-10 [deferred]:** …`.
+
+**Disabling the gates.** Set
+`workflow.context_coverage_gate: false` in `.planning/config.json` (or via
+`/gsd-settings`) to skip both gates silently. Default is `true`.
+
 ---
 
 ## UI Design Contract
@@ -189,16 +232,19 @@ AI-generated frontends are visually inconsistent not because Claude Code is bad
 
 ### Commands
 
-| Command | Description |
-|---------|-------------|
-| `/gsd-ui-phase [N]` | Generate UI-SPEC.md design contract for a frontend phase |
-| `/gsd-ui-review [N]` | Retroactive 6-pillar visual audit of implemented UI |
+
+| Command              | Description                                              |
+| -------------------- | -------------------------------------------------------- |
+| `/gsd-ui-phase [N]`  | Generate UI-SPEC.md design contract for a frontend phase |
+| `/gsd-ui-review [N]` | Retroactive 6-pillar visual audit of implemented UI      |
+
 
 ### Workflow: `/gsd-ui-phase`
 
 **When to run:** After `/gsd-discuss-phase`, before `/gsd-plan-phase` — for phases with frontend/UI work.
 
 **Flow:**
+
 1. Reads CONTEXT.md, RESEARCH.md, REQUIREMENTS.md for existing decisions
 2. Detects design system state (shadcn components.json, Tailwind config, existing tokens)
 3. shadcn initialization gate — offers to initialize if React/Next.js/Vite project has none
@@ -216,6 +262,7 @@ AI-generated frontends are visually inconsistent not because Claude Code is bad
 **Standalone:** Works on any project, not just GSD-managed ones. If no UI-SPEC.md exists, audits against abstract 6-pillar standards.
 
 **6 Pillars (scored 1-4 each):**
+
 1. Copywriting — CTA labels, empty states, error states
 2. Visuals — focal points, visual hierarchy, icon accessibility
 3. Color — accent usage discipline, 60/30/10 compliance
@@ -227,10 +274,12 @@ AI-generated frontends are visually inconsistent not because Claude Code is bad
 
 ### Configuration
 
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `workflow.ui_phase` | `true` | Generate UI design contracts for frontend phases |
-| `workflow.ui_safety_gate` | `true` | plan-phase prompts to run /gsd-ui-phase for frontend phases |
+
+| Setting                   | Default | Description                                                 |
+| ------------------------- | ------- | ----------------------------------------------------------- |
+| `workflow.ui_phase`       | `true`  | Generate UI design contracts for frontend phases            |
+| `workflow.ui_safety_gate` | `true`  | plan-phase prompts to run /gsd-ui-phase for frontend phases |
+
 
 Both follow the absent=enabled pattern. Disable via `/gsd-settings`.
 
@@ -248,6 +297,7 @@ The preset string becomes a first-class GSD planning artifact, reproducible acro
 ### Registry Safety Gate
 
 Third-party shadcn registries can inject arbitrary code. The safety gate requires:
+
 - `npx shadcn view {component}` — inspect before installing
 - `npx shadcn diff {component}` — compare against official
 
@@ -365,12 +415,14 @@ Workstreams let you work on multiple milestone areas concurrently without state
 
 ### Commands
 
-| Command | Purpose |
-|---------|---------|
-| `/gsd-workstreams create <name>` | Create a new workstream with isolated planning state |
-| `/gsd-workstreams switch <name>` | Switch active context to a different workstream |
-| `/gsd-workstreams list` | Show all workstreams and which is active |
-| `/gsd-workstreams complete <name>` | Mark a workstream as done and archive its state |
+
+| Command                            | Purpose                                              |
+| ---------------------------------- | ---------------------------------------------------- |
+| `/gsd-workstreams create <name>`   | Create a new workstream with isolated planning state |
+| `/gsd-workstreams switch <name>`   | Switch active context to a different workstream      |
+| `/gsd-workstreams list`            | Show all workstreams and which is active             |
+| `/gsd-workstreams complete <name>` | Mark a workstream as done and archive its state      |
+
 
 ### How It Works
 
@@ -393,6 +445,7 @@ All user-supplied file paths (`--text-file`, `--prd`) are validated to resolve w
 The `security.cjs` module scans for known injection patterns (role overrides, instruction bypasses, system tag injections) in user-supplied text before it enters planning artifacts.
 
 **Runtime Hooks:**
+
 - `gsd-prompt-guard.js` — Scans Write/Edit calls to `.planning/` for injection patterns (always active, advisory-only)
 - `gsd-workflow-guard.js` — Warns on file edits outside GSD workflow context (opt-in via `hooks.workflow_guard`)
 
@@ -573,6 +626,20 @@ claude --dangerously-skip-permissions
 # (normal phase workflow from here)
 ```
 
+**Post-execute drift detection (#2003).** After every `/gsd:execute-phase`,
+GSD checks whether the phase introduced enough structural change
+(new directories, barrel exports, migrations, or route modules) to make
+`.planning/codebase/STRUCTURE.md` stale. If it did, the default behavior is
+to print a one-shot warning suggesting the exact `/gsd:map-codebase --paths …`
+invocation to refresh just the affected subtrees. Flip the behavior with:
+
+```bash
+/gsd:settings workflow.drift_action auto-remap       # remap automatically
+/gsd:settings workflow.drift_threshold 5             # tune sensitivity
+```
+
+The gate is non-blocking: any internal failure logs and the phase continues.
+
 ### Quick Bug Fix
 
 ```bash
@@ -598,11 +665,13 @@ claude --dangerously-skip-permissions
 
 ### Speed vs Quality Presets
 
-| Scenario | Mode | Granularity | Profile | Research | Plan Check | Verifier |
-|----------|------|-------|---------|----------|------------|----------|
-| Prototyping | `yolo` | `coarse` | `budget` | off | off | off |
-| Normal dev | `interactive` | `standard` | `balanced` | on | on | on |
-| Production | `interactive` | `fine` | `quality` | on | on | on |
+
+| Scenario    | Mode          | Granularity | Profile    | Research | Plan Check | Verifier |
+| ----------- | ------------- | ----------- | ---------- | -------- | ---------- | -------- |
+| Prototyping | `yolo`        | `coarse`    | `budget`   | off      | off        | off      |
+| Normal dev  | `interactive` | `standard`  | `balanced` | on       | on         | on       |
+| Production  | `interactive` | `fine`      | `quality`  | on       | on         | on       |
+
 
 **Skipping discuss-phase in autonomous mode:** When running in `yolo` mode with well-established preferences already captured in PROJECT.md, set `workflow.skip_discuss: true` via `/gsd-settings`. This bypasses the discuss-phase entirely and writes a minimal CONTEXT.md derived from the ROADMAP phase goal. Useful when your PROJECT.md and conventions are comprehensive enough that discussion adds no new information.
 
@@ -637,6 +706,7 @@ cd ~/gsd-workspaces/feature-b
 ```
 
 Each workspace gets:
+
 - Its own `.planning/` directory (fully independent from source repos)
 - Git worktrees (default) or clones of specified repos
 - A `WORKSPACE.md` manifest tracking member repos
@@ -647,9 +717,9 @@ Each workspace gets:
 
 ### Programmatic CLI (`gsd-sdk query` vs `gsd-tools.cjs`)
 
-For automation and copy-paste from docs, prefer **`gsd-sdk query`** with a registered subcommand (see [CLI-TOOLS.md](CLI-TOOLS.md) and [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md)). The legacy **`node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs`** CLI remains supported for dual-mode operation.
+For automation and copy-paste from docs, prefer **`gsd-sdk query`** with a registered subcommand (see [CLI-TOOLS.md — SDK and programmatic access](CLI-TOOLS.md#sdk-and-programmatic-access) and [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md)). The legacy `node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs` CLI remains supported for dual-mode operation.
 
-**Not yet on `gsd-sdk query` (use CJS):** `state validate`, `state sync`, `audit-open`, `graphify`, `from-gsd2`, and any subcommand not listed in the registry.
+**CLI-only (not in the query registry):** **graphify**, **from-gsd2** / **gsd2-import** — call `gsd-tools.cjs` (see [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md)). **Two different `state` JSON shapes in the legacy CLI:** `state json` (frontmatter rebuild) vs `state load` (`config` + `state_raw` + flags). **`gsd-sdk query` today:** both `state.json` and `state.load` resolve to the frontmatter-rebuild handler — use `node …/gsd-tools.cjs state load` when you need the CJS `state load` shape. See [CLI-TOOLS.md](CLI-TOOLS.md#sdk-and-programmatic-access) and QUERY-HANDLERS.
 
 ### STATE.md Out of Sync
 
@@ -725,6 +795,19 @@ To assign different models to different agents on a non-Claude runtime, add `mod
 
 The installer auto-configures `resolve_model_ids: "omit"` for Gemini CLI, OpenCode, Kilo, and Codex. If you're manually setting up a non-Claude runtime, add it to `.planning/config.json` yourself.
 
+#### Switching from Claude to Codex with one config change (#2517)
+
+If you want tiered models on Codex without writing a large `model_overrides` block, set `runtime: "codex"` and pick a profile:
+
+```json
+{
+  "runtime": "codex",
+  "model_profile": "balanced"
+}
+```
+
+GSD will resolve each agent's tier (`opus`/`sonnet`/`haiku`) to the Codex-native model and reasoning effort defined in the runtime tier map (`gpt-5.4` xhigh / `gpt-5.3-codex` medium / `gpt-5.4-mini` medium). The Codex installer embeds both `model` and `model_reasoning_effort` into each agent's TOML automatically. To override a single tier, add `model_profile_overrides.codex.<tier>`. See [Runtime-Aware Profiles](CONFIGURATION.md#runtime-aware-profiles-2517).
+
 See the [Configuration Reference](CONFIGURATION.md#non-claude-runtimes-codex-opencode-gemini-cli-kilo) for the full explanation.
 
 ### Installing for Cline
@@ -782,6 +865,7 @@ If `npx get-shit-done-cc` fails due to npm outages or network restrictions, see
 When a workflow fails in a way that isn't obvious -- plans reference nonexistent files, execution produces unexpected results, or state seems corrupted -- run `/gsd-forensics` to generate a diagnostic report.
 
 **What it checks:**
+
 - Git history anomalies (orphaned commits, unexpected branch state, rebase artifacts)
 - Artifact integrity (missing or malformed planning files, broken cross-references)
 - State inconsistencies (ROADMAP status vs. actual file presence, config drift)
@@ -916,22 +1000,24 @@ If the installer crashes with `EPERM: operation not permitted, scandir` on Windo
 
 ## Recovery Quick Reference
 
-| Problem | Solution |
-|---------|----------|
-| Lost context / new session | `/gsd-resume-work` or `/gsd-progress` |
-| Phase went wrong | `git revert` the phase commits, then re-plan |
-| Need to change scope | `/gsd-add-phase`, `/gsd-insert-phase`, or `/gsd-remove-phase` |
-| Milestone audit found gaps | `/gsd-plan-milestone-gaps` |
-| Something broke | `/gsd-debug "description"` (add `--diagnose` for analysis without fixes) |
-| STATE.md out of sync | `state validate` then `state sync` |
-| Workflow state seems corrupted | `/gsd-forensics` |
-| Quick targeted fix | `/gsd-quick` |
-| Plan doesn't match your vision | `/gsd-discuss-phase [N]` then re-plan |
-| Costs running high | `/gsd-set-profile budget` and `/gsd-settings` to toggle agents off |
-| Update broke local changes | `/gsd-reapply-patches` |
-| Want session summary for stakeholder | `/gsd-session-report` |
-| Don't know what step is next | `/gsd-next` |
-| Parallel execution build errors | Update GSD or set `parallelization.enabled: false` |
+
+| Problem                              | Solution                                                                 |
+| ------------------------------------ | ------------------------------------------------------------------------ |
+| Lost context / new session           | `/gsd-resume-work` or `/gsd-progress`                                    |
+| Phase went wrong                     | `git revert` the phase commits, then re-plan                             |
+| Need to change scope                 | `/gsd-add-phase`, `/gsd-insert-phase`, or `/gsd-remove-phase`            |
+| Milestone audit found gaps           | `/gsd-plan-milestone-gaps`                                               |
+| Something broke                      | `/gsd-debug "description"` (add `--diagnose` for analysis without fixes) |
+| STATE.md out of sync                 | `state validate` then `state sync`                                       |
+| Workflow state seems corrupted       | `/gsd-forensics`                                                         |
+| Quick targeted fix                   | `/gsd-quick`                                                             |
+| Plan doesn't match your vision       | `/gsd-discuss-phase [N]` then re-plan                                    |
+| Costs running high                   | `/gsd-set-profile budget` and `/gsd-settings` to toggle agents off       |
+| Update broke local changes           | `/gsd-reapply-patches`                                                   |
+| Want session summary for stakeholder | `/gsd-session-report`                                                    |
+| Don't know what step is next         | `/gsd-next`                                                              |
+| Parallel execution build errors      | Update GSD or set `parallelization.enabled: false`                       |
+
 
 ---
 
@@ -975,3 +1061,4 @@ For reference, here is what GSD creates in your project:
       XX-UI-REVIEW.md     # Visual audit scores (from /gsd-ui-review)
   ui-reviews/             # Screenshots from /gsd-ui-review (gitignored)
 ```
+

docs/gsd-sdk-query-migration-blurb.md

@@ -4,7 +4,7 @@ Copy-paste friendly for Discord and GitHub comments.
 
 ---
 
-**@gsd-build/sdk** replaces the untyped, monolithic `gsd-tools.cjs` subprocess with a typed, tested, registry-based query system and **`gsd-sdk query`**, giving GSD structured results, classified errors (`GSDQueryError`), and golden-verified parity with the old CLI. That gives the framework one stable contract instead of a fragile, very large CLI that every workflow had to spawn and parse by hand.
+**@gsd-build/sdk** replaces the untyped, monolithic `gsd-tools.cjs` subprocess with a typed, tested, registry-based query system and **`gsd-sdk query`**, giving GSD structured results, classified errors (`GSDError` with `ErrorClassification`), and golden-verified parity with the old CLI. That gives the framework one stable contract instead of a fragile, very large CLI that every workflow had to spawn and parse by hand.
 
 **What users can expect**
 

docs/ja-JP/README.md

@@ -10,7 +10,7 @@ Get Shit Done（GSD）フレームワークの包括的なドキュメントで
 | [機能リファレンス](FEATURES.md) | 全ユーザー | 全機能の詳細ドキュメントと要件 |
 | [コマンドリファレンス](COMMANDS.md) | 全ユーザー | 全コマンドの構文、フラグ、オプション、使用例 |
 | [設定リファレンス](CONFIGURATION.md) | 全ユーザー | 設定スキーマ、ワークフロートグル、モデルプロファイル、Git ブランチ |
-| [CLI ツールリファレンス](CLI-TOOLS.md) | コントリビューター、エージェント作成者 | `gsd-tools.cjs` のプログラマティック API（ワークフローおよびエージェント向け） |
+| [CLI ツールリファレンス](CLI-TOOLS.md) | コントリビューター、エージェント作成者 | CJS `gsd-tools.cjs` と **`gsd-sdk query` / SDK** のガイド |
 | [エージェントリファレンス](AGENTS.md) | コントリビューター、上級ユーザー | 全18種の専門エージェント — 役割、ツール、スポーンパターン |
 | [ユーザーガイド](USER-GUIDE.md) | 全ユーザー | ワークフローのウォークスルー、トラブルシューティング、リカバリー |
 | [コンテキストモニター](context-monitor.md) | 全ユーザー | コンテキストウィンドウ監視フックのアーキテクチャ |

docs/ko-KR/README.md

@@ -12,7 +12,7 @@ Get Shit Done (GSD) 프레임워크의 종합 문서입니다. GSD는 AI 코딩
 | [Feature Reference](FEATURES.md) | 전체 사용자 | 요구사항이 포함된 전체 기능 및 함수 문서 |
 | [Command Reference](COMMANDS.md) | 전체 사용자 | 모든 명령어의 구문, 플래그, 옵션 및 예제 |
 | [Configuration Reference](CONFIGURATION.md) | 전체 사용자 | 전체 설정 스키마, 워크플로우 토글, 모델 프로필, git 브랜칭 |
-| [CLI Tools Reference](CLI-TOOLS.md) | 기여자, 에이전트 작성자 | 워크플로우 및 에이전트를 위한 `gsd-tools.cjs` 프로그래매틱 API |
+| [CLI Tools Reference](CLI-TOOLS.md) | 기여자, 에이전트 작성자 | CJS `gsd-tools.cjs` + **`gsd-sdk query`/SDK** 안내 |
 | [Agent Reference](AGENTS.md) | 기여자, 고급 사용자 | 18개 전문 에이전트의 역할, 도구, 스폰 패턴 |
 | [User Guide](USER-GUIDE.md) | 전체 사용자 | 워크플로우 안내, 문제 해결, 복구 방법 |
 | [Context Monitor](context-monitor.md) | 전체 사용자 | 컨텍스트 윈도우 모니터링 훅 아키텍처 |

docs/pt-BR/CLI-TOOLS.md

@@ -1,7 +1,7 @@
 # Referência de Ferramentas CLI
 
 Resumo em Português das ferramentas CLI do GSD.  
-Para API completa (assinaturas, argumentos e comportamento detalhado), consulte [CLI-TOOLS.md em inglês](../CLI-TOOLS.md).
+Para API completa (assinaturas, argumentos e comportamento detalhado), consulte [CLI-TOOLS.md em inglês](../CLI-TOOLS.md) — inclui a secção **SDK and programmatic access** (`gsd-sdk query`, `@gsd-build/sdk`).
 
 ---
 

docs/pt-BR/README.md

@@ -12,7 +12,7 @@ Documentação abrangente do framework Get Shit Done (GSD) — um sistema de met
 | [Referência de configuração](CONFIGURATION.md) | Todos os usuários | Schema completo de configuração, toggles e perfis |
 | [Referência de recursos](FEATURES.md) | Todos os usuários | Recursos e requisitos detalhados |
 | [Referência de agentes](AGENTS.md) | Contribuidores, usuários avançados | Agentes especializados, papéis e padrões de orquestração |
-| [Ferramentas CLI](CLI-TOOLS.md) | Contribuidores, autores de agentes | API programática `gsd-tools.cjs` |
+| [Ferramentas CLI](CLI-TOOLS.md) | Contribuidores, autores de agentes | Superfície CJS `gsd-tools.cjs` + guia **`gsd-sdk query`/SDK** |
 | [Monitor de contexto](context-monitor.md) | Todos os usuários | Arquitetura de monitoramento da janela de contexto |
 | [Discuss Mode](workflow-discuss-mode.md) | Todos os usuários | Modo suposições vs entrevista no `discuss-phase` |
 | [Referências](references/) | Todos os usuários | Guias complementares de decisão, verificação e padrões |

docs/zh-CN/references/decimal-phase-calculation.md

@@ -2,11 +2,11 @@
 
 为紧急插入计算下一个小数阶段编号。
 
-## 使用 gsd-tools
+## 使用 gsd-sdk query
 
 ```bash
 # 获取阶段 6 之后的下一个小数阶段
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phase next-decimal 6
+gsd-sdk query phase.next-decimal 6
 ```
 
 输出：
@@ -32,14 +32,13 @@ node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phase next-decimal 6
 ## 提取值
 
 ```bash
-DECIMAL_INFO=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phase next-decimal "${AFTER_PHASE}")
-DECIMAL_PHASE=$(printf '%s\n' "$DECIMAL_INFO" | jq -r '.next')
-BASE_PHASE=$(printf '%s\n' "$DECIMAL_INFO" | jq -r '.base_phase')
+DECIMAL_PHASE=$(gsd-sdk query phase.next-decimal "${AFTER_PHASE}" --pick next)
+BASE_PHASE=$(gsd-sdk query phase.next-decimal "${AFTER_PHASE}" --pick base_phase)
 ```
 
 或使用 --raw 标志：
 ```bash
-DECIMAL_PHASE=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phase next-decimal "${AFTER_PHASE}" --raw)
+DECIMAL_PHASE=$(gsd-sdk query phase.next-decimal "${AFTER_PHASE}" --raw)
 # 返回: 06.1
 ```
 
@@ -57,9 +56,9 @@ DECIMAL_PHASE=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phase next-
 小数阶段目录使用完整的小数编号：
 
 ```bash
-SLUG=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" generate-slug "$DESCRIPTION" --raw)
+SLUG=$(gsd-sdk query generate-slug "$DESCRIPTION" --raw)
 PHASE_DIR=".planning/phases/${DECIMAL_PHASE}-${SLUG}"
 mkdir -p "$PHASE_DIR"
 ```
 
-示例：`.planning/phases/06.1-fix-critical-auth-bug/`
+示例：`.planning/phases/06.1-fix-critical-auth-bug/`

docs/zh-CN/references/git-integration.md

@@ -51,7 +51,7 @@ Phases:
 提交内容：
 
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: initialize [project-name] ([N] phases)" --files .planning/
+gsd-sdk query commit "docs: initialize [project-name] ([N] phases)" .planning/
 ```
 
 </format>
@@ -129,7 +129,7 @@ SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
 提交内容：
 
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
+gsd-sdk query commit "docs({phase}-{plan}): complete [plan-name] plan" .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
 ```
 
 **注意：** 代码文件不包含 - 已按任务提交。
@@ -149,7 +149,7 @@ Current: [task name]
 提交内容：
 
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
+gsd-sdk query commit "wip: [phase-name] paused at task [X]/[Y]" .planning/
 ```
 
 </format>

docs/zh-CN/references/git-planning-commit.md

@@ -1,13 +1,15 @@
 # Git 规划提交
 
-使用 gsd-tools CLI 提交规划工件，它会自动检查 `commit_docs` 配置和 gitignore 状态。
+通过 `gsd-sdk query commit` 提交规划工件，它会自动检查 `commit_docs` 配置和 gitignore 状态（与旧版 `gsd-tools.cjs commit` 行为相同）。
 
 ## 通过 CLI 提交
 
-始终使用 `gsd-tools.cjs commit` 处理 `.planning/` 文件 — 它会自动处理 `commit_docs` 和 gitignore 检查：
+先传提交说明，再传文件路径（位置参数）。`commit` 不要使用 `--files`（该标志仅用于 `commit-to-subrepo`）。
+
+对 `.planning/` 文件始终使用此方式 —— 它会自动处理 `commit_docs` 与 gitignore 检查：
 
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
+gsd-sdk query commit "docs({scope}): {description}" .planning/STATE.md .planning/ROADMAP.md
 ```
 
 如果 `commit_docs` 为 `false` 或 `.planning/` 被 gitignore，CLI 会返回 `skipped`（带原因）。无需手动条件检查。
@@ -17,7 +19,7 @@ node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs({scope}): {des
 将 `.planning/` 文件变更合并到上次提交：
 
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "" --files .planning/codebase/*.md --amend
+gsd-sdk query commit "" .planning/codebase/*.md --amend
 ```
 
 ## 提交消息模式
@@ -35,4 +37,4 @@ node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "" --files .planning
 
 - config 中 `commit_docs: false`
 - `.planning/` 被 gitignore
-- 无变更可提交（用 `git status --porcelain .planning/` 检查）
+- 无变更可提交（用 `git status --porcelain .planning/` 检查）

docs/zh-CN/references/planning-config.md

@@ -36,19 +36,19 @@
 - 用户必须将 `.planning/` 添加到 `.gitignore`
 - 适用于：OSS 贡献、客户项目、保持规划私有
 
-**使用 gsd-tools.cjs（推荐）：**
+**使用 `gsd-sdk query`（推荐）：**
 
 ```bash
 # 提交时自动检查 commit_docs + gitignore：
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: update state" --files .planning/STATE.md
+gsd-sdk query commit "docs: update state" .planning/STATE.md
 
 # 通过 state load 加载配置（返回 JSON）：
-INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state load)
+INIT=$(gsd-sdk query state.load)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # commit_docs 在 JSON 输出中可用
 
 # 或使用包含 commit_docs 的 init 命令：
-INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init execute-phase "1")
+INIT=$(gsd-sdk query init.execute-phase "1")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # commit_docs 包含在所有 init 命令输出中
 ```
@@ -58,7 +58,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 **通过 CLI 提交（自动处理检查）：**
 
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: update state" --files .planning/STATE.md
+gsd-sdk query commit "docs: update state" .planning/STATE.md
 ```
 
 CLI 在内部检查 `commit_docs` 配置和 gitignore 状态 —— 无需手动条件判断。
@@ -146,14 +146,14 @@ CLI 在内部检查 `commit_docs` 配置和 gitignore 状态 —— 无需手动
 
 使用 `init execute-phase` 返回所有配置为 JSON：
 ```bash
-INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init execute-phase "1")
+INIT=$(gsd-sdk query init.execute-phase "1")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # JSON 输出包含：branching_strategy, phase_branch_template, milestone_branch_template
 ```
 
 或使用 `state load` 获取配置值：
 ```bash
-INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state load)
+INIT=$(gsd-sdk query state.load)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # 从 JSON 解析 branching_strategy, phase_branch_template, milestone_branch_template
 ```

get-shit-done/bin/gsd-tools.cjs

@@ -49,6 +49,7 @@
  *   roadmap get-phase <phase>          Extract phase section from ROADMAP.md
  *   roadmap analyze                    Full roadmap parse with disk status
  *   roadmap update-plan-progress <N>   Update progress table row from disk (PLAN vs SUMMARY counts)
+ *   roadmap annotate-dependencies <N>  Add wave dependency notes + cross-cutting constraints to ROADMAP.md
  *
  * Requirements Operations:
  *   requirements mark-complete <ids>   Mark requirement IDs as complete in REQUIREMENTS.md
@@ -111,6 +112,7 @@
  *   verify artifacts <plan-file>       Check must_haves.artifacts
  *   verify key-links <plan-file>       Check must_haves.key_links
  *   verify schema-drift <phase> [--skip]  Detect schema file changes without push
+ *   verify codebase-drift                Detect structural drift since last codebase map (#2003)
  *
  * Template Fill:
  *   template fill summary --phase N    Create pre-filled SUMMARY.md
@@ -186,6 +188,7 @@ const profileOutput = require('./lib/profile-output.cjs');
 const workstream = require('./lib/workstream.cjs');
 const docs = require('./lib/docs.cjs');
 const learnings = require('./lib/learnings.cjs');
+const gapChecker = require('./lib/gap-checker.cjs');
 
 // ─── Arg parsing helpers ──────────────────────────────────────────────────────
 
@@ -480,6 +483,12 @@ async function runCommand(command, args, cwd, raw, defaultValue) {
       } else if (subcommand === 'prune') {
         const { 'keep-recent': keepRecent, 'dry-run': dryRun } = parseNamedArgs(args, ['keep-recent'], ['dry-run']);
         state.cmdStatePrune(cwd, { keepRecent: keepRecent || '3', dryRun: !!dryRun }, raw);
+      } else if (subcommand === 'milestone-switch') {
+        // Bug #2630: reset STATE.md frontmatter + Current Position for new milestone.
+        // NB: the flag is `--milestone`, not `--version` — gsd-tools reserves
+        // `--version` as a globally-invalid help flag (see NEVER_VALID_FLAGS above).
+        const { milestone, name } = parseNamedArgs(args, ['milestone', 'name']);
+        state.cmdStateMilestoneSwitch(cwd, milestone, name, raw);
       } else {
         state.cmdStateLoad(cwd, raw);
       }
@@ -592,8 +601,10 @@ async function runCommand(command, args, cwd, raw, defaultValue) {
       } else if (subcommand === 'schema-drift') {
         const skipFlag = args.includes('--skip');
         verify.cmdVerifySchemaDrift(cwd, args[2], skipFlag, raw);
+      } else if (subcommand === 'codebase-drift') {
+        verify.cmdVerifyCodebaseDrift(cwd, raw);
       } else {
-        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links, schema-drift');
+        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links, schema-drift, codebase-drift');
       }
       break;
     }
@@ -690,8 +701,10 @@ async function runCommand(command, args, cwd, raw, defaultValue) {
         roadmap.cmdRoadmapAnalyze(cwd, raw);
       } else if (subcommand === 'update-plan-progress') {
         roadmap.cmdRoadmapUpdatePlanProgress(cwd, args[2], raw);
+      } else if (subcommand === 'annotate-dependencies') {
+        roadmap.cmdRoadmapAnnotateDependencies(cwd, args[2], raw);
       } else {
-        error('Unknown roadmap subcommand. Available: get-phase, analyze, update-plan-progress');
+        error('Unknown roadmap subcommand. Available: get-phase, analyze, update-plan-progress, annotate-dependencies');
       }
       break;
     }
@@ -706,6 +719,13 @@ async function runCommand(command, args, cwd, raw, defaultValue) {
       break;
     }
 
+    case 'gap-analysis': {
+      // Post-planning gap checker (#2493) — unified REQUIREMENTS.md +
+      // CONTEXT.md <decisions> coverage report against PLAN.md files.
+      gapChecker.cmdGapAnalysis(cwd, args.slice(1), raw);
+      break;
+    }
+
     case 'phase': {
       const subcommand = args[1];
       if (subcommand === 'next-decimal') {
@@ -764,7 +784,8 @@ async function runCommand(command, args, cwd, raw, defaultValue) {
         verify.cmdValidateConsistency(cwd, raw);
       } else if (subcommand === 'health') {
         const repairFlag = args.includes('--repair');
-        verify.cmdValidateHealth(cwd, { repair: repairFlag }, raw);
+        const backfillFlag = args.includes('--backfill');
+        verify.cmdValidateHealth(cwd, { repair: repairFlag, backfill: backfillFlag }, raw);
       } else if (subcommand === 'agents') {
         verify.cmdValidateAgents(cwd, raw);
       } else {
@@ -1200,10 +1221,6 @@ async function runCommand(command, args, cwd, raw, defaultValue) {
         'agents',
         path.join('commands', 'gsd'),
         'hooks',
-        // OpenCode/Kilo flat command dir
-        'command',
-        // Codex/Copilot skills dir
-        'skills',
       ];
 
       function walkDir(dir, baseDir) {

get-shit-done/bin/lib/artifacts.cjs

@@ -0,0 +1,52 @@
+/**
+ * Canonical GSD artifact registry.
+ *
+ * Enumerates the file names that gsd workflows officially produce at the
+ * .planning/ root level. Used by gsd-health (W019) to flag unrecognized files
+ * so stale or misnamed artifacts don't silently mislead agents or reviewers.
+ *
+ * Add entries here whenever a new workflow produces a .planning/ root file.
+ */
+
+'use strict';
+
+// Exact-match canonical file names at .planning/ root
+const CANONICAL_EXACT = new Set([
+  'PROJECT.md',
+  'ROADMAP.md',
+  'STATE.md',
+  'REQUIREMENTS.md',
+  'MILESTONES.md',
+  'BACKLOG.md',
+  'LEARNINGS.md',
+  'THREADS.md',
+  'config.json',
+  'CLAUDE.md',
+]);
+
+// Pattern-match canonical file names (regex tests on the basename)
+// Each pattern includes the name of the workflow that produces it as a comment.
+const CANONICAL_PATTERNS = [
+  /^v\d+\.\d+(?:\.\d+)?-MILESTONE-AUDIT\.md$/i,  // gsd-complete-milestone (pre-archive)
+  /^v\d+\.\d+(?:\.\d+)?-.*\.md$/i,               // other version-stamped planning docs
+];
+
+/**
+ * Return true if `filename` (basename only, no path) matches a canonical
+ * .planning/ root artifact — either an exact name or a known pattern.
+ *
+ * @param {string} filename - Basename of the file (e.g. "STATE.md")
+ */
+function isCanonicalPlanningFile(filename) {
+  if (CANONICAL_EXACT.has(filename)) return true;
+  for (const pattern of CANONICAL_PATTERNS) {
+    if (pattern.test(filename)) return true;
+  }
+  return false;
+}
+
+module.exports = {
+  CANONICAL_EXACT,
+  CANONICAL_PATTERNS,
+  isCanonicalPlanningFile,
+};

get-shit-done/bin/lib/config-schema.cjs

@@ -25,7 +25,6 @@ const VALID_CONFIG_KEYS = new Set([
   'workflow.discuss_mode',
   'workflow.skip_discuss',
   'workflow.auto_prune_state',
-  'workflow._auto_chain_active',
   'workflow.use_worktrees',
   'workflow.code_review',
   'workflow.code_review_depth',
@@ -34,15 +33,24 @@ const VALID_CONFIG_KEYS = new Set([
   'workflow.plan_bounce',
   'workflow.plan_bounce_script',
   'workflow.plan_bounce_passes',
+  'workflow.plan_chunked',
+  'workflow.post_planning_gaps',
   'workflow.security_enforcement',
   'workflow.security_asvs_level',
   'workflow.security_block_on',
+  'workflow.drift_threshold',
+  'workflow.drift_action',
   'git.branching_strategy', 'git.base_branch', 'git.phase_branch_template', 'git.milestone_branch_template', 'git.quick_branch_template',
   'planning.commit_docs', 'planning.search_gitignored', 'planning.sub_repos',
   'workflow.cross_ai_execution', 'workflow.cross_ai_command', 'workflow.cross_ai_timeout',
   'workflow.subagent_timeout',
   'workflow.inline_plan_threshold',
   'hooks.context_warnings',
+  'hooks.workflow_guard',
+  'workflow.context_coverage_gate',
+  'statusline.show_last_command',
+  'workflow.ui_review',
+  'workflow.max_discuss_passes',
   'features.thinking_partner',
   'context',
   'features.global_learnings',
@@ -50,10 +58,14 @@ const VALID_CONFIG_KEYS = new Set([
   'project_code', 'phase_naming',
   'manager.flags.discuss', 'manager.flags.plan', 'manager.flags.execute',
   'response_language',
+  'context_window',
   'intel.enabled',
   'graphify.enabled',
   'graphify.build_timeout',
   'claude_md_path',
+  'claude_md_assembly.mode',
+  // #2517 — runtime-aware model profiles
+  'runtime',
 ]);
 
 /**
@@ -61,9 +73,14 @@ const VALID_CONFIG_KEYS = new Set([
  * Each entry has a `test` function and a human-readable `description`.
  */
 const DYNAMIC_KEY_PATTERNS = [
-  { test: (k) => /^agent_skills\.[a-zA-Z0-9_-]+$/.test(k),   description: 'agent_skills.<agent-type>' },
-  { test: (k) => /^review\.models\.[a-zA-Z0-9_-]+$/.test(k), description: 'review.models.<cli-name>' },
-  { test: (k) => /^features\.[a-zA-Z0-9_]+$/.test(k),        description: 'features.<feature_name>' },
+  { test: (k) => /^agent_skills\.[a-zA-Z0-9_-]+$/.test(k),                   description: 'agent_skills.<agent-type>' },
+  { test: (k) => /^review\.models\.[a-zA-Z0-9_-]+$/.test(k),                 description: 'review.models.<cli-name>' },
+  { test: (k) => /^features\.[a-zA-Z0-9_]+$/.test(k),                        description: 'features.<feature_name>' },
+  { test: (k) => /^claude_md_assembly\.blocks\.[a-zA-Z0-9_]+$/.test(k),      description: 'claude_md_assembly.blocks.<section>' },
+  // #2517 — runtime-aware model profile overrides: model_profile_overrides.<runtime>.<tier>
+  // <runtime> is a free string (so users can map non-built-in runtimes); <tier> is enum-restricted.
+  { test: (k) => /^model_profile_overrides\.[a-zA-Z0-9_-]+\.(opus|sonnet|haiku)$/.test(k),
+    description: 'model_profile_overrides.<runtime>.<opus|sonnet|haiku>' },
 ];
 
 /**

get-shit-done/bin/lib/config.cjs

@@ -11,6 +11,7 @@ const {
   formatAgentToModelMapAsTable,
 } = require('./model-profiles.cjs');
 const { VALID_CONFIG_KEYS, isValidConfigKey } = require('./config-schema.cjs');
+const { isSecretKey, maskSecret } = require('./secrets.cjs');
 
 const CONFIG_KEY_SUGGESTIONS = {
   'workflow.nyquist_validation_enabled': 'workflow.nyquist_validation',
@@ -24,6 +25,8 @@ const CONFIG_KEY_SUGGESTIONS = {
   'workflow.code_review_level': 'workflow.code_review_depth',
   'workflow.review_depth': 'workflow.code_review_depth',
   'review.model': 'review.models.<cli-name>',
+  'sub_repos': 'planning.sub_repos',
+  'plan_checker': 'workflow.plan_check',
 };
 
 function validateKnownConfigKeyPath(keyPath) {
@@ -117,6 +120,7 @@ function buildNewProjectConfig(userChoices) {
       plan_bounce_script: null,
       plan_bounce_passes: 2,
       auto_prune_state: false,
+      post_planning_gaps: CONFIG_DEFAULTS.post_planning_gaps,
       security_enforcement: CONFIG_DEFAULTS.security_enforcement,
       security_asvs_level: CONFIG_DEFAULTS.security_asvs_level,
       security_block_on: CONFIG_DEFAULTS.security_block_on,
@@ -331,7 +335,44 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
     error(`Invalid context value '${value}'. Valid values: ${VALID_CONTEXT_VALUES.join(', ')}`);
   }
 
+  // Codebase drift detector (#2003)
+  const VALID_DRIFT_ACTIONS = ['warn', 'auto-remap'];
+  if (keyPath === 'workflow.drift_action' && !VALID_DRIFT_ACTIONS.includes(String(parsedValue))) {
+    error(`Invalid workflow.drift_action '${value}'. Valid values: ${VALID_DRIFT_ACTIONS.join(', ')}`);
+  }
+  if (keyPath === 'workflow.drift_threshold') {
+    if (typeof parsedValue !== 'number' || !Number.isInteger(parsedValue) || parsedValue < 1) {
+      error(`Invalid workflow.drift_threshold '${value}'. Must be a positive integer.`);
+    }
+  }
+
+  // Post-planning gap checker (#2493)
+  if (keyPath === 'workflow.post_planning_gaps') {
+    if (typeof parsedValue !== 'boolean') {
+      error(`Invalid workflow.post_planning_gaps '${value}'. Must be a boolean (true or false).`);
+    }
+  }
+
   const setConfigValueResult = setConfigValue(cwd, keyPath, parsedValue);
+
+  // Mask secrets in both JSON and text output. The plaintext is written
+  // to config.json (that's where secrets live on disk); the CLI output
+  // must never echo it. See lib/secrets.cjs.
+  if (isSecretKey(keyPath)) {
+    const masked = maskSecret(parsedValue);
+    const maskedPrev = setConfigValueResult.previousValue === undefined
+      ? undefined
+      : maskSecret(setConfigValueResult.previousValue);
+    const maskedResult = {
+      ...setConfigValueResult,
+      value: masked,
+      previousValue: maskedPrev,
+      masked: true,
+    };
+    output(maskedResult, raw, `${keyPath}=${masked}`);
+    return;
+  }
+
   output(setConfigValueResult, raw, `${keyPath}=${parsedValue}`);
 }
 
@@ -374,6 +415,14 @@ function cmdConfigGet(cwd, keyPath, raw, defaultValue) {
     error(`Key not found: ${keyPath}`);
   }
 
+  // Never echo plaintext for sensitive keys via config-get. Plaintext lives
+  // in config.json on disk; the CLI surface always shows the masked form.
+  if (isSecretKey(keyPath)) {
+    const masked = maskSecret(current);
+    output(masked, raw, masked);
+    return;
+  }
+
   output(current, raw, String(current));
 }
 

get-shit-done/bin/lib/core.cjs

@@ -266,6 +266,7 @@ const CONFIG_DEFAULTS = {
   security_enforcement: true, // workflow.security_enforcement — threat-model-anchored security verification via /gsd-secure-phase
   security_asvs_level: 1, // workflow.security_asvs_level — OWASP ASVS verification level (1=opportunistic, 2=standard, 3=comprehensive)
   security_block_on: 'high', // workflow.security_block_on — minimum severity that blocks phase advancement ('high' | 'medium' | 'low')
+  post_planning_gaps: true, // workflow.post_planning_gaps — unified post-planning gap report (#2493): scan REQUIREMENTS.md + CONTEXT.md decisions vs all PLAN.md files
 };
 
 function loadConfig(cwd) {
@@ -287,26 +288,40 @@ function loadConfig(cwd) {
     // Auto-detect and sync sub_repos: scan for child directories with .git
     let configDirty = false;
 
-    // Migrate legacy "multiRepo: true" boolean → sub_repos array
+    // Migrate legacy "multiRepo: true" boolean → planning.sub_repos array.
+    // Canonical location is planning.sub_repos (#2561); writing to top-level
+    // would be flagged as unknown by the validator below (#2638).
     if (parsed.multiRepo === true && !parsed.sub_repos && !parsed.planning?.sub_repos) {
       const detected = detectSubRepos(cwd);
       if (detected.length > 0) {
-        parsed.sub_repos = detected;
         if (!parsed.planning) parsed.planning = {};
+        parsed.planning.sub_repos = detected;
         parsed.planning.commit_docs = false;
         delete parsed.multiRepo;
         configDirty = true;
       }
     }
 
-    // Keep sub_repos in sync with actual filesystem
-    const currentSubRepos = parsed.sub_repos || parsed.planning?.sub_repos || [];
+    // Self-heal legacy/buggy installs: strip any stale top-level sub_repos,
+    // preserving its value as the planning.sub_repos seed if that slot is empty.
+    if (Object.prototype.hasOwnProperty.call(parsed, 'sub_repos')) {
+      if (!parsed.planning) parsed.planning = {};
+      if (!parsed.planning.sub_repos) {
+        parsed.planning.sub_repos = parsed.sub_repos;
+      }
+      delete parsed.sub_repos;
+      configDirty = true;
+    }
+
+    // Keep planning.sub_repos in sync with actual filesystem
+    const currentSubRepos = parsed.planning?.sub_repos || [];
     if (Array.isArray(currentSubRepos) && currentSubRepos.length > 0) {
       const detected = detectSubRepos(cwd);
       if (detected.length > 0) {
         const sorted = [...currentSubRepos].sort();
         if (JSON.stringify(sorted) !== JSON.stringify(detected)) {
-          parsed.sub_repos = detected;
+          if (!parsed.planning) parsed.planning = {};
+          parsed.planning.sub_repos = detected;
           configDirty = true;
         }
       }
@@ -339,6 +354,13 @@ function loadConfig(cwd) {
       );
     }
 
+    // #2517 — Validate runtime/tier values for keys that loadConfig handles but
+    // can be edited directly into config.json (bypassing config-set's enum check).
+    // This catches typos like `runtime: "codx"` and `model_profile_overrides.codex.banana`
+    // at read time without rejecting back-compat values from new runtimes
+    // (review findings #10, #13).
+    _warnUnknownProfileOverrides(parsed, '.planning/config.json');
+
     const get = (key, nested) => {
       if (parsed[key] !== undefined) return parsed[key];
       if (nested && parsed[nested.section] && parsed[nested.section][nested.field] !== undefined) {
@@ -374,6 +396,7 @@ function loadConfig(cwd) {
       plan_checker: get('plan_checker', { section: 'workflow', field: 'plan_check' }) ?? defaults.plan_checker,
       verifier: get('verifier', { section: 'workflow', field: 'verifier' }) ?? defaults.verifier,
       nyquist_validation: get('nyquist_validation', { section: 'workflow', field: 'nyquist_validation' }) ?? defaults.nyquist_validation,
+      post_planning_gaps: get('post_planning_gaps', { section: 'workflow', field: 'post_planning_gaps' }) ?? defaults.post_planning_gaps,
       parallelization,
       brave_search: get('brave_search') ?? defaults.brave_search,
       firecrawl: get('firecrawl') ?? defaults.firecrawl,
@@ -390,10 +413,23 @@ function loadConfig(cwd) {
       project_code: get('project_code') ?? defaults.project_code,
       subagent_timeout: get('subagent_timeout', { section: 'workflow', field: 'subagent_timeout' }) ?? defaults.subagent_timeout,
       model_overrides: parsed.model_overrides || null,
+      // #2517 — runtime-aware profiles. `runtime` defaults to null (back-compat).
+      // When null, resolveModelInternal preserves today's Claude-native behavior.
+      // NOTE: `runtime` and `model_profile_overrides` are intentionally read
+      // flat-only (not via `get()` with a workflow.X fallback) — they are
+      // top-level keys per docs/CONFIGURATION.md. The lighter-touch decision
+      // here was to document the constraint rather than introduce nested
+      // resolution edge cases for two new keys (review finding #9). The
+      // schema validation in `_warnUnknownProfileOverrides` runs against the
+      // raw `parsed` blob, so direct `.planning/config.json` edits surface
+      // unknown runtime/tier names at load time, not silently (review finding #10).
+      runtime: parsed.runtime || null,
+      model_profile_overrides: parsed.model_profile_overrides || null,
       agent_skills: parsed.agent_skills || {},
       manager: parsed.manager || {},
       response_language: get('response_language') || null,
       claude_md_path: get('claude_md_path') || null,
+      claude_md_assembly: parsed.claude_md_assembly || null,
     };
   } catch {
     // Fall back to ~/.gsd/defaults.json only for truly pre-project contexts (#1683)
@@ -414,6 +450,9 @@ function loadConfig(cwd) {
         plan_checker: globalDefaults.plan_checker ?? defaults.plan_checker,
         verifier: globalDefaults.verifier ?? defaults.verifier,
         nyquist_validation: globalDefaults.nyquist_validation ?? defaults.nyquist_validation,
+        post_planning_gaps: globalDefaults.post_planning_gaps
+          ?? globalDefaults.workflow?.post_planning_gaps
+          ?? defaults.post_planning_gaps,
         parallelization: globalDefaults.parallelization ?? defaults.parallelization,
         text_mode: globalDefaults.text_mode ?? defaults.text_mode,
         resolve_model_ids: globalDefaults.resolve_model_ids ?? defaults.resolve_model_ids,
@@ -1284,8 +1323,11 @@ function extractCurrentMilestone(content, cwd) {
   // Milestone headings look like: ## v2.0, ## Roadmap v2.0, ## ✅ v1.0, etc.
   const headingLevel = sectionMatch[1].match(/^(#{1,3})\s/)[1].length;
   const restContent = content.slice(sectionStart + sectionMatch[0].length);
+  // Exclude phase headings (e.g. "### Phase 12: v1.0 Tech-Debt Closure") from
+  // being treated as milestone boundaries just because they mention vX.Y in
+  // the title. Phase headings always start with the literal `Phase `. See #2619.
   const nextMilestonePattern = new RegExp(
-    `^#{1,${headingLevel}}\\s+(?:.*v\\d+\\.\\d+|✅|📋|🚧)`,
+    `^#{1,${headingLevel}}\\s+(?!Phase\\s+\\S)(?:.*v\\d+\\.\\d+|✅|📋|🚧)`,
     'mi'
   );
   const nextMatch = restContent.match(nextMilestonePattern);
@@ -1334,9 +1376,19 @@ function getRoadmapPhaseInternal(cwd, phaseNum) {
 
   try {
     const content = extractCurrentMilestone(fs.readFileSync(roadmapPath, 'utf-8'), cwd);
-    const escapedPhase = escapeRegex(phaseNum.toString());
-    // Match both numeric (Phase 1:) and custom (Phase PROJ-42:) headers
-    const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+${escapedPhase}:\\s*([^\\n]+)`, 'i');
+    // Strip leading zeros from purely numeric phase numbers so "03" matches "Phase 3:"
+    // in canonical ROADMAP headings. Non-numeric IDs (e.g. "PROJ-42") are kept as-is.
+    const normalized = /^\d+$/.test(String(phaseNum))
+      ? String(phaseNum).replace(/^0+(?=\d)/, '')
+      : String(phaseNum);
+    const escapedPhase = escapeRegex(normalized);
+    // Match both numeric and custom (Phase PROJ-42:) headers.
+    // For purely numeric phases allow optional leading zeros so both "Phase 1:" and
+    // "Phase 01:" are matched regardless of whether the ROADMAP uses padded numbers.
+    const isNumeric = /^\d+$/.test(String(phaseNum));
+    const phasePattern = isNumeric
+      ? new RegExp(`#{2,4}\\s*Phase\\s+0*${escapedPhase}:\\s*([^\\n]+)`, 'i')
+      : new RegExp(`#{2,4}\\s*Phase\\s+${escapedPhase}:\\s*([^\\n]+)`, 'i');
     const headerMatch = content.match(phasePattern);
     if (!headerMatch) return null;
 
@@ -1438,32 +1490,220 @@ const MODEL_ALIAS_MAP = {
   'haiku': 'claude-haiku-4-5',
 };
 
+/**
+ * #2517 — runtime-aware tier resolution.
+ * Maps `model_profile` tiers (opus/sonnet/haiku) to runtime-native model IDs and
+ * (where supported) reasoning_effort settings.
+ *
+ * Each entry: { model: <id>, reasoning_effort?: <level> }
+ *
+ * `claude` mirrors MODEL_ALIAS_MAP — present for symmetry so `runtime: "claude"`
+ * resolves through the same code path. `codex` defaults are taken from the spec
+ * in #2517. Unknown runtimes fall back to the Claude alias to avoid emitting
+ * provider-specific IDs the runtime cannot accept.
+ */
+const RUNTIME_PROFILE_MAP = {
+  claude: {
+    opus:   { model: 'claude-opus-4-6' },
+    sonnet: { model: 'claude-sonnet-4-6' },
+    haiku:  { model: 'claude-haiku-4-5' },
+  },
+  codex: {
+    opus:   { model: 'gpt-5.4',        reasoning_effort: 'xhigh' },
+    sonnet: { model: 'gpt-5.3-codex',  reasoning_effort: 'medium' },
+    haiku:  { model: 'gpt-5.4-mini',   reasoning_effort: 'medium' },
+  },
+};
+
+const RUNTIMES_WITH_REASONING_EFFORT = new Set(['codex']);
+
+/**
+ * Tier enum allowed under `model_profile_overrides[runtime][tier]`. Mirrors the
+ * regex in `config-schema.cjs` (DYNAMIC_KEY_PATTERNS) so loadConfig surfaces the
+ * same constraint at read time, not only at config-set time (review finding #10).
+ */
+const RUNTIME_OVERRIDE_TIERS = new Set(['opus', 'sonnet', 'haiku']);
+
+/**
+ * Allowlist of runtime names the install pipeline currently knows how to emit
+ * native model IDs for. Synced with `getDirName` in `bin/install.js` and the
+ * runtime list in `docs/CONFIGURATION.md`. Free-string runtimes outside this
+ * set are still accepted (#2517 deliberately leaves the runtime field open) —
+ * a warning fires once at loadConfig so a typo like `runtime: "codx"` does not
+ * silently fall back to Claude defaults (review findings #10, #13).
+ */
+const KNOWN_RUNTIMES = new Set([
+  'claude', 'codex', 'opencode', 'kilo', 'gemini', 'qwen',
+  'copilot', 'cursor', 'windsurf', 'augment', 'trae', 'codebuddy',
+  'antigravity', 'cline',
+]);
+
+const _warnedConfigKeys = new Set();
+/**
+ * Emit a one-time stderr warning for unknown runtime/tier keys in a parsed
+ * config blob. Idempotent across calls — the same (file, key) pair only warns
+ * once per process so loadConfig can be called repeatedly without spamming.
+ *
+ * Does NOT reject — preserves back-compat for users on a runtime not yet in the
+ * allowlist (the new-runtime case must always be possible without code changes).
+ */
+function _warnUnknownProfileOverrides(parsed, configLabel) {
+  if (!parsed || typeof parsed !== 'object') return;
+
+  const runtime = parsed.runtime;
+  if (runtime && typeof runtime === 'string' && !KNOWN_RUNTIMES.has(runtime)) {
+    const key = `${configLabel}::runtime::${runtime}`;
+    if (!_warnedConfigKeys.has(key)) {
+      _warnedConfigKeys.add(key);
+      try {
+        process.stderr.write(
+          `gsd: warning — config key "runtime" has unknown value "${runtime}". ` +
+          `Known runtimes: ${[...KNOWN_RUNTIMES].sort().join(', ')}. ` +
+          `Resolution will fall back to safe defaults. (#2517)\n`
+        );
+      } catch { /* stderr might be closed in some test harnesses */ }
+    }
+  }
+
+  const overrides = parsed.model_profile_overrides;
+  if (!overrides || typeof overrides !== 'object') return;
+  for (const [overrideRuntime, tierMap] of Object.entries(overrides)) {
+    if (!KNOWN_RUNTIMES.has(overrideRuntime)) {
+      const key = `${configLabel}::override-runtime::${overrideRuntime}`;
+      if (!_warnedConfigKeys.has(key)) {
+        _warnedConfigKeys.add(key);
+        try {
+          process.stderr.write(
+            `gsd: warning — model_profile_overrides.${overrideRuntime}.* uses ` +
+            `unknown runtime "${overrideRuntime}". Known runtimes: ` +
+            `${[...KNOWN_RUNTIMES].sort().join(', ')}. (#2517)\n`
+          );
+        } catch { /* ok */ }
+      }
+    }
+    if (!tierMap || typeof tierMap !== 'object') continue;
+    for (const tierName of Object.keys(tierMap)) {
+      if (!RUNTIME_OVERRIDE_TIERS.has(tierName)) {
+        const key = `${configLabel}::override-tier::${overrideRuntime}.${tierName}`;
+        if (!_warnedConfigKeys.has(key)) {
+          _warnedConfigKeys.add(key);
+          try {
+            process.stderr.write(
+              `gsd: warning — model_profile_overrides.${overrideRuntime}.${tierName} ` +
+              `uses unknown tier "${tierName}". Allowed tiers: opus, sonnet, haiku. (#2517)\n`
+            );
+          } catch { /* ok */ }
+        }
+      }
+    }
+  }
+}
+
+// Internal helper exposed for tests so per-process warning state can be reset
+// between cases that intentionally exercise the warning path repeatedly.
+function _resetRuntimeWarningCacheForTests() {
+  _warnedConfigKeys.clear();
+}
+
+/**
+ * #2517 — Resolve the runtime-aware tier entry for (runtime, tier).
+ *
+ * Single source of truth shared by core.cjs (resolveModelInternal /
+ * resolveReasoningEffortInternal) and bin/install.js (Codex/OpenCode TOML emit
+ * paths). Always merges built-in defaults with user overrides at the field
+ * level so partial overrides keep the unspecified fields:
+ *
+ *   `{ codex: { opus: "gpt-5-pro" } }`           keeps reasoning_effort: 'xhigh'
+ *   `{ codex: { opus: { reasoning_effort: 'low' } } }` keeps model: 'gpt-5.4'
+ *
+ * Without this field-merge, the documented string-shorthand example silently
+ * dropped reasoning_effort and a partial-object override silently dropped the
+ * model — both reported as critical findings in the #2609 review.
+ *
+ * Inputs:
+ *   - runtime: string (e.g. 'codex', 'claude', 'opencode')
+ *   - tier:    'opus' | 'sonnet' | 'haiku'
+ *   - overrides: optional `model_profile_overrides` blob (may be null/undefined)
+ *
+ * Returns `{ model: string, reasoning_effort?: string } | null`.
+ */
+function resolveTierEntry({ runtime, tier, overrides }) {
+  if (!runtime || !tier) return null;
+
+  const builtin = RUNTIME_PROFILE_MAP[runtime]?.[tier] || null;
+  const userRaw = overrides?.[runtime]?.[tier];
+
+  // String shorthand from CONFIGURATION.md examples — `{ codex: { opus: "gpt-5-pro" } }`.
+  // Treat as `{ model: "gpt-5-pro" }` so the field-merge below still preserves
+  // reasoning_effort from the built-in defaults.
+  let userEntry = null;
+  if (userRaw) {
+    userEntry = typeof userRaw === 'string' ? { model: userRaw } : userRaw;
+  }
+
+  if (!builtin && !userEntry) return null;
+  // Field-merge: user fields win, built-in fills the gaps.
+  return { ...(builtin || {}), ...(userEntry || {}) };
+}
+
+/**
+ * Convenience wrapper used by resolveModelInternal / resolveReasoningEffortInternal.
+ * Pulls runtime + overrides out of a loaded config and delegates to resolveTierEntry.
+ */
+function _resolveRuntimeTier(config, tier) {
+  return resolveTierEntry({
+    runtime: config.runtime,
+    tier,
+    overrides: config.model_profile_overrides,
+  });
+}
+
 function resolveModelInternal(cwd, agentType) {
   const config = loadConfig(cwd);
 
-  // Check per-agent override first — always respected regardless of resolve_model_ids.
+  // 1. Per-agent override — always respected; highest precedence.
   // Users who set fully-qualified model IDs (e.g., "openai/gpt-5.4") get exactly that.
   const override = config.model_overrides?.[agentType];
   if (override) {
     return override;
   }
 
-  // resolve_model_ids: "omit" — return empty string so the runtime uses its configured
-  // default model. For non-Claude runtimes (OpenCode, Codex, etc.) that don't recognize
-  // Claude aliases (opus/sonnet/haiku/inherit). Set automatically during install. See #1156.
+  // 2. Compute the tier (opus/sonnet/haiku) for this agent under the active profile.
+  const profile = String(config.model_profile || 'balanced').toLowerCase();
+  const agentModels = MODEL_PROFILES[agentType];
+  const tier = agentModels ? (agentModels[profile] || agentModels['balanced']) : null;
+
+  // 3. Runtime-aware resolution (#2517) — only when `runtime` is explicitly set
+  // to a non-Claude runtime. `runtime: "claude"` is the implicit default and is
+  // treated as a no-op here so it does not silently override `resolve_model_ids:
+  // "omit"` (review finding #4). Deliberate ordering for non-Claude runtimes:
+  // explicit opt-in beats `resolve_model_ids: "omit"` so users on Codex installs
+  // that auto-set "omit" can still flip on tiered behavior by setting runtime
+  // alone. inherit profile is preserved verbatim.
+  if (config.runtime && config.runtime !== 'claude' && profile !== 'inherit' && tier) {
+    const entry = _resolveRuntimeTier(config, tier);
+    if (entry?.model) return entry.model;
+    // Unknown runtime with no user-supplied overrides — fall through to Claude-safe
+    // default rather than emit an ID the runtime can't accept.
+  }
+
+  // 4. resolve_model_ids: "omit" — return empty string so the runtime uses its
+  // configured default model. For non-Claude runtimes (OpenCode, Codex, etc.) that
+  // don't recognize Claude aliases. Set automatically during install. See #1156.
   if (config.resolve_model_ids === 'omit') {
     return '';
   }
 
-  // Fall back to profile lookup
-  const profile = String(config.model_profile || 'balanced').toLowerCase();
-  const agentModels = MODEL_PROFILES[agentType];
+  // 5. Profile lookup (Claude-native default).
   if (!agentModels) return 'sonnet';
   if (profile === 'inherit') return 'inherit';
-  const alias = agentModels[profile] || agentModels['balanced'] || 'sonnet';
+  // `tier` is guaranteed truthy here: agentModels exists, and MODEL_PROFILES
+  // entries always define `balanced`, so `agentModels[profile] || agentModels.balanced`
+  // resolves to a string. Keep the local for readability — no defensive fallback.
+  const alias = tier;
 
-  // resolve_model_ids: true — map alias to full Claude model ID
-  // Prevents 404s when the Task tool passes aliases directly to the API
+  // resolve_model_ids: true — map alias to full Claude model ID.
+  // Prevents 404s when the Task tool passes aliases directly to the API.
   if (config.resolve_model_ids) {
     return MODEL_ALIAS_MAP[alias] || alias;
   }
@@ -1471,6 +1711,41 @@ function resolveModelInternal(cwd, agentType) {
   return alias;
 }
 
+/**
+ * #2517 — Resolve runtime-specific reasoning_effort for an agent.
+ * Returns null unless:
+ *   - `runtime` is explicitly set in config,
+ *   - the runtime supports reasoning_effort (currently: codex),
+ *   - profile is not 'inherit',
+ *   - the resolved tier entry has a `reasoning_effort` value.
+ *
+ * Never returns a value for Claude — keeps reasoning_effort out of Claude spawn paths.
+ */
+function resolveReasoningEffortInternal(cwd, agentType) {
+  const config = loadConfig(cwd);
+  if (!config.runtime) return null;
+  // Strict allowlist: reasoning_effort only propagates for runtimes whose
+  // install path actually accepts it. Adding a new runtime here is the only
+  // way to enable effort propagation — overrides cannot bypass the gate.
+  // Without this, a typo in `runtime` (e.g. `"codx"`) plus a user override
+  // for that typo would leak `xhigh` into a Claude or unknown install
+  // (review finding #3).
+  if (!RUNTIMES_WITH_REASONING_EFFORT.has(config.runtime)) return null;
+  // Per-agent override means user supplied a fully-qualified ID; reasoning_effort
+  // for that case must be set via per-agent mechanism, not tier inference.
+  if (config.model_overrides?.[agentType]) return null;
+
+  const profile = String(config.model_profile || 'balanced').toLowerCase();
+  if (profile === 'inherit') return null;
+  const agentModels = MODEL_PROFILES[agentType];
+  if (!agentModels) return null;
+  const tier = agentModels[profile] || agentModels['balanced'];
+  if (!tier) return null;
+
+  const entry = _resolveRuntimeTier(config, tier);
+  return entry?.reasoning_effort || null;
+}
+
 // ─── Summary body helpers ─────────────────────────────────────────────────
 
 /**
@@ -1481,11 +1756,28 @@ function resolveModelInternal(cwd, agentType) {
  */
 function extractOneLinerFromBody(content) {
   if (!content) return null;
+  // Normalize EOLs so matching works for LF and CRLF files.
+  const normalized = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
   // Strip frontmatter first
-  const body = content.replace(/^---\n[\s\S]*?\n---\n*/, '');
-  // Find the first **...** line after a # heading
-  const match = body.match(/^#[^\n]*\n+\*\*([^*]+)\*\*/m);
-  return match ? match[1].trim() : null;
+  const body = normalized.replace(/^---\n[\s\S]*?\n---\n*/, '');
+  // Find the first **...** span on a line after a # heading.
+  // Two supported template forms:
+  //   1) Labeled:  **One-liner:** Real prose here.   (bug #2660 — new template)
+  //   2) Bare:     **Real prose here.**              (legacy template)
+  // For (1), the first bold span ends in a colon and the prose that follows
+  // on the same line is the one-liner. For (2), the bold span itself is the
+  // one-liner.
+  const match = body.match(/^#[^\n]*\n+\*\*([^*\n]+)\*\*([^\n]*)/m);
+  if (!match) return null;
+  const boldInner = match[1].trim();
+  const afterBold = match[2];
+  // Labeled form: bold span is a "Label:" prefix — capture prose after it.
+  if (/:\s*$/.test(boldInner)) {
+    const prose = afterBold.trim();
+    return prose.length > 0 ? prose : null;
+  }
+  // Bare form: the bold content itself is the one-liner.
+  return boldInner.length > 0 ? boldInner : null;
 }
 
 // ─── Misc utilities ───────────────────────────────────────────────────────────
@@ -1509,6 +1801,50 @@ function getMilestoneInfo(cwd) {
   try {
     const roadmap = fs.readFileSync(path.join(planningDir(cwd), 'ROADMAP.md'), 'utf-8');
 
+    // 0. Prefer STATE.md milestone: frontmatter as the authoritative source.
+    // This prevents falling through to a regex that may match an old heading
+    // when the active milestone's 🚧 marker is inside a <summary> tag without
+    // **bold** formatting (bug #2409).
+    let stateVersion = null;
+    if (cwd) {
+      try {
+        const statePath = path.join(planningDir(cwd), 'STATE.md');
+        if (fs.existsSync(statePath)) {
+          const stateRaw = fs.readFileSync(statePath, 'utf-8');
+          const m = stateRaw.match(/^milestone:\s*(.+)/m);
+          if (m) stateVersion = m[1].trim();
+        }
+      } catch { /* intentionally empty */ }
+    }
+
+    if (stateVersion) {
+      // Look up the name for this version in ROADMAP.md
+      const escapedVer = escapeRegex(stateVersion);
+      // Match heading-format: ## Roadmap v2.9: Name  or  ## v2.9 Name
+      const headingMatch = roadmap.match(
+        new RegExp(`##[^\\n]*${escapedVer}[:\\s]+([^\\n(]+)`, 'i')
+      );
+      if (headingMatch) {
+        // If the heading line contains ✅ the milestone is already shipped.
+        // Fall through to normal detection so the NEW active milestone is returned
+        // instead of the stale shipped one still recorded in STATE.md.
+        if (!headingMatch[0].includes('✅')) {
+          return { version: stateVersion, name: headingMatch[1].trim() };
+        }
+        // Shipped milestone — do not early-return; fall through to normal detection below.
+      } else {
+        // Match list-format: 🚧 **v2.9 Name** or 🚧 v2.9 Name
+        const listMatch = roadmap.match(
+          new RegExp(`🚧\\s*\\*?\\*?${escapedVer}\\s+([^*\\n]+)`, 'i')
+        );
+        if (listMatch) {
+          return { version: stateVersion, name: listMatch[1].trim() };
+        }
+        // Version found in STATE.md but no name match in ROADMAP — return bare version
+        return { version: stateVersion, name: 'milestone' };
+      }
+    }
+
     // First: check for list-format roadmaps using 🚧 (in-progress) marker
     // e.g. "- 🚧 **v2.1 Belgium** — Phases 24-28 (in progress)"
     // e.g. "- 🚧 **v1.2.1 Tech Debt** — Phases 1-8 (in progress)"
@@ -1520,11 +1856,14 @@ function getMilestoneInfo(cwd) {
       };
     }
 
-    // Second: heading-format roadmaps — strip shipped milestones in <details> blocks
+    // Second: heading-format roadmaps — strip shipped milestones.
+    // <details> blocks are stripped by stripShippedMilestones; heading-format ✅ markers
+    // are excluded by the negative lookahead below so a stale STATE.md version (or any
+    // shipped ✅ heading) never wins over the first non-shipped milestone heading.
     const cleaned = stripShippedMilestones(roadmap);
-    // Extract version and name from the same ## heading for consistency
+    // Negative lookahead skips headings that contain ✅ (shipped milestone marker).
     // Supports 2+ segment versions: v1.2, v1.2.1, v2.0.1, etc.
-    const headingMatch = cleaned.match(/## .*v(\d+(?:\.\d+)+)[:\s]+([^\n(]+)/);
+    const headingMatch = cleaned.match(/## (?!.*✅).*v(\d+(?:\.\d+)+)[:\s]+([^\n(]+)/);
     if (headingMatch) {
       return {
         version: 'v' + headingMatch[1],
@@ -1566,7 +1905,7 @@ function getMilestonePhaseFilter(cwd) {
   }
 
   const normalized = new Set(
-    [...milestonePhaseNums].map(n => (n.replace(/^0+/, '') || '0').toLowerCase())
+    [...milestonePhaseNums].map(n => (n.replace(/^0+(?=\d)/, '') || '0').toLowerCase())
   );
 
   function isDirInMilestone(dirName) {
@@ -1702,6 +2041,13 @@ module.exports = {
   getArchivedPhaseDirs,
   getRoadmapPhaseInternal,
   resolveModelInternal,
+  resolveReasoningEffortInternal,
+  RUNTIME_PROFILE_MAP,
+  RUNTIMES_WITH_REASONING_EFFORT,
+  KNOWN_RUNTIMES,
+  RUNTIME_OVERRIDE_TIERS,
+  resolveTierEntry,
+  _resetRuntimeWarningCacheForTests,
   pathExistsInternal,
   generateSlugInternal,
   getMilestoneInfo,

get-shit-done/bin/lib/decisions.cjs

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * Shared parser for CONTEXT.md `<decisions>` blocks.
+ *
+ * Used by:
+ *   - gap-checker.cjs (#2493 post-planning gap analysis)
+ *   - intended for #2492 (plan-phase decision gate, verify-phase decision validator)
+ *
+ * Format produced by discuss-phase.md:
+ *
+ *   <decisions>
+ *   ## Implementation Decisions
+ *
+ *   ### Category
+ *   - **D-01:** Decision text
+ *   - **D-02:** Another decision
+ *   </decisions>
+ *
+ * D-IDs outside the <decisions> block are ignored. Missing block returns [].
+ */
+
+/**
+ * Parse the <decisions> section of a CONTEXT.md string.
+ *
+ * @param {string|null|undefined} contextMd - File contents, may be empty/missing.
+ * @returns {Array<{id: string, text: string}>}
+ */
+function parseDecisions(contextMd) {
+  if (!contextMd || typeof contextMd !== 'string') return [];
+  const blockMatch = contextMd.match(/<decisions>([\s\S]*?)<\/decisions>/);
+  if (!blockMatch) return [];
+  const block = blockMatch[1];
+
+  const decisionRe = /^\s*-\s*\*\*(D-[A-Za-z0-9_-]+):\*\*\s*(.+?)\s*$/gm;
+  const out = [];
+  const seen = new Set();
+  let m;
+  while ((m = decisionRe.exec(block)) !== null) {
+    const id = m[1];
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push({ id, text: m[2] });
+  }
+  return out;
+}
+
+module.exports = { parseDecisions };

get-shit-done/bin/lib/drift.cjs

@@ -0,0 +1,378 @@
+/**
+ * Codebase Drift Detection (#2003)
+ *
+ * Detects structural drift between a committed codebase and the
+ * `.planning/codebase/STRUCTURE.md` map produced by `gsd-codebase-mapper`.
+ *
+ * Four categories of drift element:
+ *   - new_dir    → a newly-added file whose directory prefix does not appear
+ *                  in STRUCTURE.md
+ *   - barrel     → a newly-added barrel export at
+ *                  (packages|apps)/<name>/src/index.(ts|tsx|js|mjs|cjs)
+ *   - migration  → a newly-added migration file under one of the recognized
+ *                  migration directories (supabase, prisma, drizzle, src/migrations, …)
+ *   - route      → a newly-added route module under a `routes/` or `api/` dir
+ *
+ * Each file is counted at most once; when a file matches multiple categories
+ * the most specific category wins (migration > route > barrel > new_dir).
+ *
+ * Design decisions (see PR for full rubber-duck):
+ *   - The library is pure. It takes parsed git diff output and returns a
+ *     structured result. The CLI/workflow layer is responsible for running
+ *     git and for spawning mappers.
+ *   - `last_mapped_commit` is stored as YAML-style frontmatter at the top of
+ *     each `.planning/codebase/*.md` file. This keeps the baseline attached
+ *     to the file, survives git moves, and avoids a sidecar JSON.
+ *   - The detector NEVER throws on malformed input — it returns a
+ *     `{ skipped: true }` result. The phase workflow depends on this
+ *     non-blocking guarantee.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+const DRIFT_CATEGORIES = Object.freeze(['new_dir', 'barrel', 'migration', 'route']);
+
+// Category priority when a single file matches multiple rules.
+// Higher index = more specific = wins.
+const CATEGORY_PRIORITY = { new_dir: 0, barrel: 1, route: 2, migration: 3 };
+
+const BARREL_RE = /^(packages|apps)\/[^/]+\/src\/index\.(ts|tsx|js|mjs|cjs)$/;
+
+const MIGRATION_RES = [
+  /^supabase\/migrations\/.+\.sql$/,
+  /^prisma\/migrations\/.+/,
+  /^drizzle\/meta\/.+/,
+  /^drizzle\/migrations\/.+/,
+  /^src\/migrations\/.+\.(ts|js|sql)$/,
+  /^db\/migrations\/.+\.(sql|ts|js)$/,
+  /^migrations\/.+\.(sql|ts|js)$/,
+];
+
+const ROUTE_RES = [
+  /^(apps|packages)\/[^/]+\/src\/routes\/.+\.(ts|tsx|js|jsx|mjs|cjs)$/,
+  /^src\/routes\/.+\.(ts|tsx|js|jsx|mjs|cjs)$/,
+  /^src\/api\/.+\.(ts|tsx|js|jsx|mjs|cjs)$/,
+  /^(apps|packages)\/[^/]+\/src\/api\/.+\.(ts|tsx|js|jsx|mjs|cjs)$/,
+];
+
+// A conservative allowlist for `--paths` arguments passed to the mapper:
+// repo-relative path components separated by /, containing only
+// alphanumerics, dash, underscore, and dot (no `..`, no `/..`).
+const SAFE_PATH_RE = /^(?!.*\.\.)(?:[A-Za-z0-9_.][A-Za-z0-9_.\-]*)(?:\/[A-Za-z0-9_.][A-Za-z0-9_.\-]*)*$/;
+
+// ─── Classification ──────────────────────────────────────────────────────────
+
+/**
+ * Classify a single file path into a drift category or null.
+ *
+ * @param {string} file - repo-relative path, forward slashes.
+ * @returns {'barrel'|'migration'|'route'|null}
+ */
+function classifyFile(file) {
+  if (typeof file !== 'string' || !file) return null;
+  const norm = file.replace(/\\/g, '/');
+  if (MIGRATION_RES.some((r) => r.test(norm))) return 'migration';
+  if (ROUTE_RES.some((r) => r.test(norm))) return 'route';
+  if (BARREL_RE.test(norm)) return 'barrel';
+  return null;
+}
+
+/**
+ * True iff any prefix of `file` (dir1, dir1/dir2, …) appears as a substring
+ * of `structureMd`. Used to decide whether a file is in "mapped territory".
+ *
+ * Matching is deliberately substring-based — STRUCTURE.md is free-form
+ * markdown, not a structured manifest. If the map mentions `src/lib/` the
+ * check `structureMd.includes('src/lib')` holds.
+ */
+function isPathMapped(file, structureMd) {
+  const norm = file.replace(/\\/g, '/');
+  const parts = norm.split('/');
+  // Check prefixes from longest to shortest; any hit means "mapped".
+  for (let i = parts.length - 1; i >= 1; i--) {
+    const prefix = parts.slice(0, i).join('/');
+    if (structureMd.includes(prefix)) return true;
+  }
+  // Finally, if even the top-level dir is mentioned, count as mapped.
+  if (parts.length > 0 && structureMd.includes(parts[0] + '/')) return true;
+  if (parts.length > 0 && structureMd.includes('`' + parts[0] + '`')) return true;
+  return false;
+}
+
+// ─── Main detection ──────────────────────────────────────────────────────────
+
+/**
+ * Detect codebase drift.
+ *
+ * @param {object} input
+ * @param {string[]} input.addedFiles - files with git status A (new)
+ * @param {string[]} input.modifiedFiles - files with git status M
+ * @param {string[]} input.deletedFiles - files with git status D
+ * @param {string|null|undefined} input.structureMd - contents of STRUCTURE.md
+ * @param {number} [input.threshold=3] - min number of drift elements that triggers action
+ * @param {'warn'|'auto-remap'} [input.action='warn']
+ * @returns {object} result
+ */
+function detectDrift(input) {
+  try {
+    if (!input || typeof input !== 'object') {
+      return skipped('invalid-input');
+    }
+    const {
+      addedFiles,
+      modifiedFiles,
+      deletedFiles,
+      structureMd,
+    } = input;
+    const threshold = Number.isInteger(input.threshold) && input.threshold >= 1
+      ? input.threshold
+      : 3;
+    const action = input.action === 'auto-remap' ? 'auto-remap' : 'warn';
+
+    if (structureMd === null || structureMd === undefined) {
+      return skipped('missing-structure-md');
+    }
+    if (typeof structureMd !== 'string') {
+      return skipped('invalid-structure-md');
+    }
+
+    const added = Array.isArray(addedFiles) ? addedFiles.filter((x) => typeof x === 'string') : [];
+    const modified = Array.isArray(modifiedFiles) ? modifiedFiles : [];
+    const deleted = Array.isArray(deletedFiles) ? deletedFiles : [];
+
+    // Build elements. One element per file, highest-priority category wins.
+    /** @type {{category: string, path: string}[]} */
+    const elements = [];
+    const seen = new Map();
+
+    for (const rawFile of added) {
+      const file = rawFile.replace(/\\/g, '/');
+      const specific = classifyFile(file);
+      let category = specific;
+      if (!category) {
+        if (!isPathMapped(file, structureMd)) {
+          category = 'new_dir';
+        } else {
+          continue; // mapped, known, ordinary file — not drift
+        }
+      }
+      // Dedup: if we've already counted this path at higher-or-equal priority, skip
+      const prior = seen.get(file);
+      if (prior && CATEGORY_PRIORITY[prior] >= CATEGORY_PRIORITY[category]) continue;
+      seen.set(file, category);
+    }
+
+    for (const [file, category] of seen.entries()) {
+      elements.push({ category, path: file });
+    }
+
+    // Sort for stable output.
+    elements.sort((a, b) =>
+      a.category === b.category
+        ? a.path.localeCompare(b.path)
+        : a.category.localeCompare(b.category),
+    );
+
+    const actionRequired = elements.length >= threshold;
+    let directive = 'none';
+    let spawnMapper = false;
+    let affectedPaths = [];
+    let message = '';
+
+    if (actionRequired) {
+      directive = action;
+      affectedPaths = chooseAffectedPaths(elements.map((e) => e.path));
+      if (action === 'auto-remap') {
+        spawnMapper = true;
+      }
+      message = buildMessage(elements, affectedPaths, action);
+    }
+
+    return {
+      skipped: false,
+      elements,
+      actionRequired,
+      directive,
+      spawnMapper,
+      affectedPaths,
+      threshold,
+      action,
+      message,
+      counts: {
+        added: added.length,
+        modified: modified.length,
+        deleted: deleted.length,
+      },
+    };
+  } catch (err) {
+    // Non-blocking: never throw from this function.
+    return skipped('exception:' + (err && err.message ? err.message : String(err)));
+  }
+}
+
+function skipped(reason) {
+  return {
+    skipped: true,
+    reason,
+    elements: [],
+    actionRequired: false,
+    directive: 'none',
+    spawnMapper: false,
+    affectedPaths: [],
+    message: '',
+  };
+}
+
+function buildMessage(elements, affectedPaths, action) {
+  const byCat = {};
+  for (const e of elements) {
+    (byCat[e.category] ||= []).push(e.path);
+  }
+  const lines = [
+    `Codebase drift detected: ${elements.length} structural element(s) since last mapping.`,
+    '',
+  ];
+  const labels = {
+    new_dir: 'New directories',
+    barrel: 'New barrel exports',
+    migration: 'New migrations',
+    route: 'New route modules',
+  };
+  for (const cat of ['new_dir', 'barrel', 'migration', 'route']) {
+    if (byCat[cat]) {
+      lines.push(`${labels[cat]}:`);
+      for (const p of byCat[cat]) lines.push(`  - ${p}`);
+    }
+  }
+  lines.push('');
+  if (action === 'auto-remap') {
+    lines.push(`Auto-remap scheduled for paths: ${affectedPaths.join(', ')}`);
+  } else {
+    lines.push(
+      `Run /gsd-map-codebase --paths ${affectedPaths.join(',')} to refresh planning context.`,
+    );
+  }
+  return lines.join('\n');
+}
+
+// ─── Affected paths ──────────────────────────────────────────────────────────
+
+/**
+ * Collapse a list of drifted file paths into a sorted, deduplicated list of
+ * the top-level directory prefixes (depth 2 when the repo uses an
+ * `<apps|packages>/<name>/…` layout; depth 1 otherwise).
+ */
+function chooseAffectedPaths(paths) {
+  const out = new Set();
+  for (const raw of paths || []) {
+    if (typeof raw !== 'string' || !raw) continue;
+    const file = raw.replace(/\\/g, '/');
+    const parts = file.split('/');
+    if (parts.length === 0) continue;
+    const top = parts[0];
+    if ((top === 'apps' || top === 'packages') && parts.length >= 2) {
+      out.add(`${top}/${parts[1]}`);
+    } else {
+      out.add(top);
+    }
+  }
+  return [...out].sort();
+}
+
+/**
+ * Filter `paths` to only those that are safe to splice into a mapper prompt.
+ * Any path that is absolute, contains traversal, or includes shell
+ * metacharacters is dropped.
+ */
+function sanitizePaths(paths) {
+  if (!Array.isArray(paths)) return [];
+  const out = [];
+  for (const p of paths) {
+    if (typeof p !== 'string') continue;
+    if (p.startsWith('/')) continue;
+    if (!SAFE_PATH_RE.test(p)) continue;
+    out.push(p);
+  }
+  return out;
+}
+
+// ─── Frontmatter helpers ─────────────────────────────────────────────────────
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+
+function parseFrontmatter(content) {
+  if (typeof content !== 'string') return { data: {}, body: '' };
+  const m = content.match(FRONTMATTER_RE);
+  if (!m) return { data: {}, body: content };
+  const data = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = line.match(/^([A-Za-z0-9_][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (!kv) continue;
+    data[kv[1]] = kv[2];
+  }
+  return { data, body: content.slice(m[0].length) };
+}
+
+function serializeFrontmatter(data, body) {
+  const keys = Object.keys(data);
+  if (keys.length === 0) return body;
+  const lines = ['---'];
+  for (const k of keys) lines.push(`${k}: ${data[k]}`);
+  lines.push('---');
+  return lines.join('\n') + '\n' + body;
+}
+
+/**
+ * Read `last_mapped_commit` from the frontmatter of a `.planning/codebase/*.md`
+ * file. Returns null if the file does not exist or has no frontmatter.
+ */
+function readMappedCommit(filePath) {
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+  const { data } = parseFrontmatter(content);
+  const sha = data.last_mapped_commit;
+  return typeof sha === 'string' && sha.length > 0 ? sha : null;
+}
+
+/**
+ * Upsert `last_mapped_commit` and `last_mapped_at` into the frontmatter of
+ * the given file, preserving any other frontmatter keys and the body.
+ */
+function writeMappedCommit(filePath, commitSha, isoDate) {
+  // Symmetric with readMappedCommit (which returns null on missing files):
+  // tolerate a missing target by creating a minimal frontmatter-only file
+  // rather than throwing ENOENT. This matters when a mapper produces a new
+  // doc and the caller stamps it before any prior content existed.
+  let content = '';
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  const { data, body } = parseFrontmatter(content);
+  data.last_mapped_commit = commitSha;
+  if (isoDate) data.last_mapped_at = isoDate;
+  fs.writeFileSync(filePath, serializeFrontmatter(data, body));
+}
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  DRIFT_CATEGORIES,
+  classifyFile,
+  detectDrift,
+  chooseAffectedPaths,
+  sanitizePaths,
+  readMappedCommit,
+  writeMappedCommit,
+  // Exposed for the CLI layer to reuse the same parser.
+  parseFrontmatter,
+};

get-shit-done/bin/lib/gap-checker.cjs

@@ -0,0 +1,183 @@
+'use strict';
+
+/**
+ * Post-planning gap analysis (#2493).
+ *
+ * Reads REQUIREMENTS.md (planning-root) and CONTEXT.md (per-phase) and compares
+ * each REQ-ID and D-ID against the concatenated text of all PLAN.md files in
+ * the phase directory. Emits a unified `Source | Item | Status` report.
+ *
+ * Gated on workflow.post_planning_gaps (default true). When false, returns
+ * { enabled: false } and does not scan.
+ *
+ * Coverage detection uses word-boundary regex matching to avoid false positives
+ * (REQ-1 must not match REQ-10).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { planningPaths, planningDir, escapeRegex, output, error } = require('./core.cjs');
+const { parseDecisions } = require('./decisions.cjs');
+
+/**
+ * Parse REQ-IDs from REQUIREMENTS.md content.
+ *
+ * Supports both checkbox (`- [ ] **REQ-NN** ...`) and traceability table
+ * (`| REQ-NN | ... |`) formats.
+ */
+function parseRequirements(reqMd) {
+  if (!reqMd || typeof reqMd !== 'string') return [];
+  const out = [];
+  const seen = new Set();
+
+  const checkboxRe = /^\s*-\s*\[[x ]\]\s*\*\*(REQ-[A-Za-z0-9_-]+)\*\*\s*(.*)$/gm;
+  let cm = checkboxRe.exec(reqMd);
+  while (cm !== null) {
+    const id = cm[1];
+    if (!seen.has(id)) {
+      seen.add(id);
+      out.push({ id, text: (cm[2] || '').trim() });
+    }
+    cm = checkboxRe.exec(reqMd);
+  }
+
+  const tableRe = /\|\s*(REQ-[A-Za-z0-9_-]+)\s*\|/g;
+  let tm = tableRe.exec(reqMd);
+  while (tm !== null) {
+    const id = tm[1];
+    if (!seen.has(id)) {
+      seen.add(id);
+      out.push({ id, text: '' });
+    }
+    tm = tableRe.exec(reqMd);
+  }
+
+  return out;
+}
+
+function detectCoverage(items, planText) {
+  return items.map(it => {
+    const re = new RegExp('\\b' + escapeRegex(it.id) + '\\b');
+    return {
+      source: it.source,
+      item: it.id,
+      status: re.test(planText) ? 'Covered' : 'Not covered',
+    };
+  });
+}
+
+function naturalKey(s) {
+  return String(s).replace(/(\d+)/g, (_, n) => n.padStart(8, '0'));
+}
+
+function sortRows(rows) {
+  const sourceOrder = { 'REQUIREMENTS.md': 0, 'CONTEXT.md': 1 };
+  return rows.slice().sort((a, b) => {
+    const so = (sourceOrder[a.source] ?? 99) - (sourceOrder[b.source] ?? 99);
+    if (so !== 0) return so;
+    return naturalKey(a.item).localeCompare(naturalKey(b.item));
+  });
+}
+
+function formatGapTable(rows) {
+  if (rows.length === 0) {
+    return '## Post-Planning Gap Analysis\n\nNo requirements or decisions to check.\n';
+  }
+  const header = '| Source | Item | Status |\n|--------|------|--------|';
+  const body = rows.map(r => {
+    const tick = r.status === 'Covered' ? '\u2713 Covered' : '\u2717 Not covered';
+    return `| ${r.source} | ${r.item} | ${tick} |`;
+  }).join('\n');
+  return `## Post-Planning Gap Analysis\n\n${header}\n${body}\n`;
+}
+
+function readGate(cwd) {
+  const cfgPath = path.join(planningDir(cwd), 'config.json');
+  try {
+    const raw = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
+    if (raw && raw.workflow && typeof raw.workflow.post_planning_gaps === 'boolean') {
+      return raw.workflow.post_planning_gaps;
+    }
+  } catch { /* fall through */ }
+  return true;
+}
+
+function runGapAnalysis(cwd, phaseDir) {
+  if (!readGate(cwd)) {
+    return {
+      enabled: false,
+      rows: [],
+      table: '',
+      summary: 'workflow.post_planning_gaps disabled — skipping post-planning gap analysis',
+      counts: { total: 0, covered: 0, uncovered: 0 },
+    };
+  }
+
+  const absPhaseDir = path.isAbsolute(phaseDir) ? phaseDir : path.join(cwd, phaseDir);
+
+  const reqPath = planningPaths(cwd).requirements;
+  const reqMd = fs.existsSync(reqPath) ? fs.readFileSync(reqPath, 'utf-8') : '';
+  const reqItems = parseRequirements(reqMd).map(r => ({ ...r, source: 'REQUIREMENTS.md' }));
+
+  const ctxPath = path.join(absPhaseDir, 'CONTEXT.md');
+  const ctxMd = fs.existsSync(ctxPath) ? fs.readFileSync(ctxPath, 'utf-8') : '';
+  const dItems = parseDecisions(ctxMd).map(d => ({ ...d, source: 'CONTEXT.md' }));
+
+  const items = [...reqItems, ...dItems];
+
+  let planText = '';
+  try {
+    if (fs.existsSync(absPhaseDir)) {
+      const files = fs.readdirSync(absPhaseDir).filter(f => /-PLAN\.md$/.test(f));
+      planText = files.map(f => {
+        try { return fs.readFileSync(path.join(absPhaseDir, f), 'utf-8'); }
+        catch { return ''; }
+      }).join('\n');
+    }
+  } catch { /* unreadable */ }
+
+  if (items.length === 0) {
+    return {
+      enabled: true,
+      rows: [],
+      table: '## Post-Planning Gap Analysis\n\nNo requirements or decisions to check.\n',
+      summary: 'no requirements or decisions to check',
+      counts: { total: 0, covered: 0, uncovered: 0 },
+    };
+  }
+
+  const rows = sortRows(detectCoverage(items, planText));
+  const uncovered = rows.filter(r => r.status === 'Not covered').length;
+  const covered = rows.length - uncovered;
+
+  const summary = uncovered === 0
+    ? `\u2713 All ${rows.length} items covered by plans`
+    : `\u26A0 ${uncovered} of ${rows.length} items not covered by any plan`;
+
+  return {
+    enabled: true,
+    rows,
+    table: formatGapTable(rows) + '\n' + summary + '\n',
+    summary,
+    counts: { total: rows.length, covered, uncovered },
+  };
+}
+
+function cmdGapAnalysis(cwd, args, raw) {
+  const idx = args.indexOf('--phase-dir');
+  if (idx === -1 || !args[idx + 1]) {
+    error('Usage: gap-analysis --phase-dir <path-to-phase-directory>');
+  }
+  const phaseDir = args[idx + 1];
+  const result = runGapAnalysis(cwd, phaseDir);
+  output(result, raw, result.table || result.summary);
+}
+
+module.exports = {
+  parseRequirements,
+  detectCoverage,
+  formatGapTable,
+  sortRows,
+  runGapAnalysis,
+  cmdGapAnalysis,
+};

get-shit-done/bin/lib/init.cjs

@@ -458,8 +458,11 @@ function cmdInitNewMilestone(cwd, raw) {
 
   try {
     if (fs.existsSync(phasesDir)) {
+      // Bug #2445: filter phase dirs to current milestone only so stale dirs
+      // from a prior milestone that were not archived don't inflate the count.
+      const isDirInMilestone = getMilestonePhaseFilter(cwd);
       phaseDirCount = fs.readdirSync(phasesDir, { withFileTypes: true })
-        .filter(entry => entry.isDirectory())
+        .filter(entry => entry.isDirectory() && isDirInMilestone(entry.name))
         .length;
     }
   } catch {}
@@ -824,20 +827,70 @@ function cmdInitMilestoneOp(cwd, raw) {
   let phaseCount = 0;
   let completedPhases = 0;
   const phasesDir = path.join(planningDir(cwd), 'phases');
+
+  // Bug #2633 — ROADMAP.md (current milestone section) is the authority for
+  // phase counts, NOT the on-disk `.planning/phases/` directory. After
+  // `phases clear` between milestones, on-disk dirs will be a subset of the
+  // roadmap until each phase is materialized; reading from disk causes
+  // `all_phases_complete: true` to fire prematurely.
+  let roadmapPhaseNumbers = [];
+  try {
+    const roadmapPath = path.join(planningDir(cwd), 'ROADMAP.md');
+    const roadmapRaw = fs.readFileSync(roadmapPath, 'utf-8');
+    const currentSection = extractCurrentMilestone(roadmapRaw, cwd);
+    const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:/gi;
+    let m;
+    while ((m = phasePattern.exec(currentSection)) !== null) {
+      roadmapPhaseNumbers.push(m[1]);
+    }
+  } catch { /* intentionally empty */ }
+
+  // Canonicalize a phase token by stripping leading zeros from the integer
+  // head while preserving any [A-Z]? suffix and dotted segments. So "03" →
+  // "3", "03A" → "3A", "03.1" → "3.1", "3A" → "3A". Disk dirs that pad
+  // ("03-alpha") then match roadmap tokens ("Phase 3") without ever
+  // collapsing distinct tokens like "3" / "3A" / "3.1" into the same bucket.
+  const canonicalizePhase = (tok) => {
+    const m = tok.match(/^(\d+)([A-Z]?(?:\.\d+)*)$/);
+    return m ? String(parseInt(m[1], 10)) + m[2] : tok;
+  };
+  const diskPhaseDirs = new Map();
   try {
     const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
-    const dirs = entries.filter(e => e.isDirectory()).map(e => e.name);
-    phaseCount = dirs.length;
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const m = e.name.match(/^(\d+[A-Z]?(?:\.\d+)*)/);
+      if (!m) continue;
+      diskPhaseDirs.set(canonicalizePhase(m[1]), e.name);
+    }
+  } catch { /* intentionally empty */ }
 
-    // Count phases with summaries (completed)
-    for (const dir of dirs) {
+  if (roadmapPhaseNumbers.length > 0) {
+    phaseCount = roadmapPhaseNumbers.length;
+    for (const num of roadmapPhaseNumbers) {
+      const dirName = diskPhaseDirs.get(canonicalizePhase(num));
+      if (!dirName) continue;
       try {
-        const phaseFiles = fs.readdirSync(path.join(phasesDir, dir));
+        const phaseFiles = fs.readdirSync(path.join(phasesDir, dirName));
         const hasSummary = phaseFiles.some(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
         if (hasSummary) completedPhases++;
       } catch { /* intentionally empty */ }
     }
-  } catch { /* intentionally empty */ }
+  } else {
+    // Fallback: no parseable ROADMAP — preserve legacy on-disk behavior.
+    try {
+      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      const dirs = entries.filter(e => e.isDirectory()).map(e => e.name);
+      phaseCount = dirs.length;
+      for (const dir of dirs) {
+        try {
+          const phaseFiles = fs.readdirSync(path.join(phasesDir, dir));
+          const hasSummary = phaseFiles.some(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
+          if (hasSummary) completedPhases++;
+        } catch { /* intentionally empty */ }
+      }
+    } catch { /* intentionally empty */ }
+  }
 
   // Check archive
   const archiveDir = path.join(planningRoot(cwd), 'archive');
@@ -1227,6 +1280,7 @@ function cmdInitProgress(cwd, raw) {
   // Build set of phases defined in ROADMAP for the current milestone
   const roadmapPhaseNums = new Set();
   const roadmapPhaseNames = new Map();
+  const roadmapCheckboxStates = new Map();
   try {
     const roadmapContent = extractCurrentMilestone(
       fs.readFileSync(path.join(planningDir(cwd), 'ROADMAP.md'), 'utf-8'), cwd
@@ -1237,6 +1291,13 @@ function cmdInitProgress(cwd, raw) {
       roadmapPhaseNums.add(hm[1]);
       roadmapPhaseNames.set(hm[1], hm[2].replace(/\(INSERTED\)/i, '').trim());
     }
+    // #2646: parse `- [x] Phase N` checkbox states so ROADMAP-only phases
+    // inherit completion from the ROADMAP when no phase directory exists.
+    const cbPattern = /-\s*\[(x| )\]\s*.*Phase\s+(\d+[A-Z]?(?:\.\d+)*)[:\s]/gi;
+    let cbm;
+    while ((cbm = cbPattern.exec(roadmapContent)) !== null) {
+      roadmapCheckboxStates.set(cbm[2], cbm[1].toLowerCase() === 'x');
+    }
   } catch { /* intentionally empty */ }
 
   const isDirInMilestone = getMilestonePhaseFilter(cwd);
@@ -1292,21 +1353,27 @@ function cmdInitProgress(cwd, raw) {
     }
   } catch { /* intentionally empty */ }
 
-  // Add phases defined in ROADMAP but not yet scaffolded to disk
+  // Add phases defined in ROADMAP but not yet scaffolded to disk. When the
+  // ROADMAP has a `- [x] Phase N` checkbox, honor it as 'complete' so
+  // completed_count and status reflect the ROADMAP source of truth (#2646).
   for (const [num, name] of roadmapPhaseNames) {
     const stripped = num.replace(/^0+/, '') || '0';
     if (!seenPhaseNums.has(stripped)) {
+      const checkboxComplete =
+        roadmapCheckboxStates.get(num) === true ||
+        roadmapCheckboxStates.get(stripped) === true;
+      const status = checkboxComplete ? 'complete' : 'not_started';
       const phaseInfo = {
         number: num,
         name: name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, ''),
         directory: null,
-        status: 'not_started',
+        status,
         plan_count: 0,
         summary_count: 0,
         has_research: false,
       };
       phases.push(phaseInfo);
-      if (!nextPhase && !currentPhase) {
+      if (!nextPhase && !currentPhase && status !== 'complete') {
         nextPhase = phaseInfo;
       }
     }

get-shit-done/bin/lib/phase.cjs

@@ -625,7 +625,7 @@ function renameIntegerPhases(phasesDir, removedInt) {
       const m = dir.match(/^(\d+)([A-Z])?(?:\.(\d+))?-(.+)$/i);
       if (!m) return null;
       const dirInt = parseInt(m[1], 10);
-      return dirInt > removedInt ? { dir, oldInt: dirInt, letter: m[2] ? m[2].toUpperCase() : '', decimal: m[3] ? parseInt(m[3], 10) : null, slug: m[4] } : null;
+      return (dirInt > removedInt && dirInt < 999) ? { dir, oldInt: dirInt, letter: m[2] ? m[2].toUpperCase() : '', decimal: m[3] ? parseInt(m[3], 10) : null, slug: m[4] } : null;
     })
     .filter(Boolean)
     .sort((a, b) => a.oldInt !== b.oldInt ? b.oldInt - a.oldInt : (b.decimal || 0) - (a.decimal || 0));
@@ -673,7 +673,7 @@ function updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, rem
         const oldPad = oldStr.padStart(2, '0'), newPad = newStr.padStart(2, '0');
         content = content.replace(new RegExp(`(#{2,4}\\s*Phase\\s+)${oldStr}(\\s*:)`, 'gi'), `$1${newStr}$2`);
         content = content.replace(new RegExp(`(Phase\\s+)${oldStr}([:\\s])`, 'g'), `$1${newStr}$2`);
-        content = content.replace(new RegExp(`${oldPad}-(\\d{2})`, 'g'), `${newPad}-$1`);
+        content = content.replace(new RegExp(`(?<![0-9-])${oldPad}-(\\d{2})(?![0-9-])`, 'g'), `${newPad}-$1`);
         content = content.replace(new RegExp(`(\\|\\s*)${oldStr}\\.\\s`, 'g'), `$1${newStr}. `);
         content = content.replace(new RegExp(`(Depends on:\\*\\*\\s*Phase\\s+)${oldStr}\\b`, 'gi'), `$1${newStr}`);
       }
@@ -870,9 +870,10 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
         const sectionText = phaseSectionMatch ? phaseSectionMatch[1] : '';
         const reqMatch = sectionText.match(/\*\*Requirements:\*\*\s*([^\n]+)/i);
 
+        let reqContent = fs.readFileSync(reqPath, 'utf-8');
+
         if (reqMatch) {
           const reqIds = reqMatch[1].replace(/[\[\]]/g, '').split(/[,\s]+/).map(r => r.trim()).filter(Boolean);
-          let reqContent = fs.readFileSync(reqPath, 'utf-8');
 
           for (const reqId of reqIds) {
             const reqEscaped = escapeRegex(reqId);
@@ -887,10 +888,40 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
               '$1 Complete $2'
             );
           }
-
-          atomicWriteFileSync(reqPath, reqContent);
-          requirementsUpdated = true;
         }
+
+        // Scan body for all **REQ-ID** patterns, warn about any missing from the Traceability table.
+        // Always runs regardless of whether the roadmap has a Requirements: line.
+        const bodyReqIds = [];
+        const bodyReqPattern = /\*\*([A-Z][A-Z0-9]*-\d+)\*\*/g;
+        let bodyMatch;
+        while ((bodyMatch = bodyReqPattern.exec(reqContent)) !== null) {
+          const id = bodyMatch[1];
+          if (!bodyReqIds.includes(id)) bodyReqIds.push(id);
+        }
+
+        // Collect REQ-IDs present in the Traceability section only, to avoid
+        // picking up IDs from other tables in the document.
+        const traceabilityHeadingMatch = reqContent.match(/^#{1,6}\s+Traceability\b/im);
+        const traceabilitySection = traceabilityHeadingMatch
+          ? reqContent.slice(traceabilityHeadingMatch.index)
+          : '';
+        const tableReqIds = new Set();
+        const tableRowPattern = /^\|\s*([A-Z][A-Z0-9]*-\d+)\s*\|/gm;
+        let tableMatch;
+        while ((tableMatch = tableRowPattern.exec(traceabilitySection)) !== null) {
+          tableReqIds.add(tableMatch[1]);
+        }
+
+        const unregistered = bodyReqIds.filter(id => !tableReqIds.has(id));
+        if (unregistered.length > 0) {
+          warnings.push(
+            `REQUIREMENTS.md: ${unregistered.length} REQ-ID(s) found in body but missing from Traceability table: ${unregistered.join(', ')} — add them manually to keep traceability in sync`
+          );
+        }
+
+        atomicWriteFileSync(reqPath, reqContent);
+        requirementsUpdated = true;
       }
     });
   }

get-shit-done/bin/lib/profile-output.cjs

@@ -285,7 +285,7 @@ function generateProjectSection(cwd) {
   const projectPath = path.join(cwd, '.planning', 'PROJECT.md');
   const content = safeReadFile(projectPath);
   if (!content) {
-    return { content: CLAUDE_MD_FALLBACKS.project, source: 'PROJECT.md', hasFallback: true };
+    return { content: CLAUDE_MD_FALLBACKS.project, source: 'PROJECT.md', linkPath: null, hasFallback: true };
   }
   const parts = [];
   const h1Match = content.match(/^# (.+)$/m);
@@ -306,9 +306,9 @@ function generateProjectSection(cwd) {
     if (body) parts.push(`### Constraints\n\n${body}`);
   }
   if (parts.length === 0) {
-    return { content: CLAUDE_MD_FALLBACKS.project, source: 'PROJECT.md', hasFallback: true };
+    return { content: CLAUDE_MD_FALLBACKS.project, source: 'PROJECT.md', linkPath: null, hasFallback: true };
   }
-  return { content: parts.join('\n\n'), source: 'PROJECT.md', hasFallback: false };
+  return { content: parts.join('\n\n'), source: 'PROJECT.md', linkPath: '.planning/PROJECT.md', hasFallback: false };
 }
 
 function generateStackSection(cwd) {
@@ -316,12 +316,14 @@ function generateStackSection(cwd) {
   const researchPath = path.join(cwd, '.planning', 'research', 'STACK.md');
   let content = safeReadFile(codebasePath);
   let source = 'codebase/STACK.md';
+  let linkPath = '.planning/codebase/STACK.md';
   if (!content) {
     content = safeReadFile(researchPath);
     source = 'research/STACK.md';
+    linkPath = '.planning/research/STACK.md';
   }
   if (!content) {
-    return { content: CLAUDE_MD_FALLBACKS.stack, source: 'STACK.md', hasFallback: true };
+    return { content: CLAUDE_MD_FALLBACKS.stack, source: 'STACK.md', linkPath: null, hasFallback: true };
   }
   const lines = content.split('\n');
   const summaryLines = [];
@@ -336,14 +338,14 @@ function generateStackSection(cwd) {
     if (line.startsWith('- ') || line.startsWith('* ')) summaryLines.push(line);
   }
   const summary = summaryLines.length > 0 ? summaryLines.join('\n') : content.trim();
-  return { content: summary, source, hasFallback: false };
+  return { content: summary, source, linkPath, hasFallback: false };
 }
 
 function generateConventionsSection(cwd) {
   const conventionsPath = path.join(cwd, '.planning', 'codebase', 'CONVENTIONS.md');
   const content = safeReadFile(conventionsPath);
   if (!content) {
-    return { content: CLAUDE_MD_FALLBACKS.conventions, source: 'CONVENTIONS.md', hasFallback: true };
+    return { content: CLAUDE_MD_FALLBACKS.conventions, source: 'CONVENTIONS.md', linkPath: null, hasFallback: true };
   }
   const lines = content.split('\n');
   const summaryLines = [];
@@ -352,14 +354,14 @@ function generateConventionsSection(cwd) {
     if (line.startsWith('- ') || line.startsWith('* ') || line.startsWith('|')) summaryLines.push(line);
   }
   const summary = summaryLines.length > 0 ? summaryLines.join('\n') : content.trim();
-  return { content: summary, source: 'CONVENTIONS.md', hasFallback: false };
+  return { content: summary, source: 'CONVENTIONS.md', linkPath: '.planning/codebase/CONVENTIONS.md', hasFallback: false };
 }
 
 function generateArchitectureSection(cwd) {
   const architecturePath = path.join(cwd, '.planning', 'codebase', 'ARCHITECTURE.md');
   const content = safeReadFile(architecturePath);
   if (!content) {
-    return { content: CLAUDE_MD_FALLBACKS.architecture, source: 'ARCHITECTURE.md', hasFallback: true };
+    return { content: CLAUDE_MD_FALLBACKS.architecture, source: 'ARCHITECTURE.md', linkPath: null, hasFallback: true };
   }
   const lines = content.split('\n');
   const summaryLines = [];
@@ -368,13 +370,14 @@ function generateArchitectureSection(cwd) {
     if (line.startsWith('- ') || line.startsWith('* ') || line.startsWith('|') || line.startsWith('```')) summaryLines.push(line);
   }
   const summary = summaryLines.length > 0 ? summaryLines.join('\n') : content.trim();
-  return { content: summary, source: 'ARCHITECTURE.md', hasFallback: false };
+  return { content: summary, source: 'ARCHITECTURE.md', linkPath: '.planning/codebase/ARCHITECTURE.md', hasFallback: false };
 }
 
 function generateWorkflowSection() {
   return {
     content: CLAUDE_MD_WORKFLOW_ENFORCEMENT,
     source: 'GSD defaults',
+    linkPath: null,
     hasFallback: false,
   };
 }
@@ -948,19 +951,35 @@ function cmdGenerateClaudeMd(cwd, options, raw) {
     }
   }
 
+  let assemblyConfig = {};
+  let configClaudeMdPath = './CLAUDE.md';
+  try {
+    const config = loadConfig(cwd);
+    if (config.claude_md_path) configClaudeMdPath = config.claude_md_path;
+    if (config.claude_md_assembly) assemblyConfig = config.claude_md_assembly;
+  } catch { /* use default */ }
+
   let outputPath = options.output;
   if (!outputPath) {
-    // Read claude_md_path from config, default to ./CLAUDE.md
-    let configClaudeMdPath = './CLAUDE.md';
-    try {
-      const config = loadConfig(cwd);
-      if (config.claude_md_path) configClaudeMdPath = config.claude_md_path;
-    } catch { /* use default */ }
     outputPath = path.isAbsolute(configClaudeMdPath) ? configClaudeMdPath : path.join(cwd, configClaudeMdPath);
   } else if (!path.isAbsolute(outputPath)) {
     outputPath = path.join(cwd, outputPath);
   }
 
+  const globalAssemblyMode = assemblyConfig.mode || 'embed';
+  const blockModes = assemblyConfig.blocks || {};
+
+  // Return the assembled content for a section, respecting link vs embed mode.
+  // "link" mode writes `@<linkPath>` when the generator has a real source file.
+  // Falls back to "embed" for sections without a linkable source (workflow, fallbacks).
+  function buildSectionContent(name, gen, heading) {
+    const effectiveMode = blockModes[name] || globalAssemblyMode;
+    if (effectiveMode === 'link' && gen.linkPath && !gen.hasFallback) {
+      return buildSection(name, gen.source, `${heading}\n\n@${gen.linkPath}`);
+    }
+    return buildSection(name, gen.source, `${heading}\n\n${gen.content}`);
+  }
+
   let existingContent = safeReadFile(outputPath);
   let action;
 
@@ -969,8 +988,7 @@ function cmdGenerateClaudeMd(cwd, options, raw) {
     for (const name of MANAGED_SECTIONS) {
       const gen = generated[name];
       const heading = sectionHeadings[name];
-      const body = `${heading}\n\n${gen.content}`;
-      sections.push(buildSection(name, gen.source, body));
+      sections.push(buildSectionContent(name, gen, heading));
     }
     sections.push('');
     sections.push(CLAUDE_MD_PROFILE_PLACEHOLDER);
@@ -985,13 +1003,15 @@ function cmdGenerateClaudeMd(cwd, options, raw) {
     for (const name of MANAGED_SECTIONS) {
       const gen = generated[name];
       const heading = sectionHeadings[name];
-      const body = `${heading}\n\n${gen.content}`;
-      const fullSection = buildSection(name, gen.source, body);
+      const fullSection = buildSectionContent(name, gen, heading);
       const hasMarkers = fileContent.indexOf(`<!-- GSD:${name}-start`) !== -1;
 
       if (hasMarkers) {
         if (options.auto) {
-          const expectedBody = `${heading}\n\n${gen.content}`;
+          const effectiveMode = blockModes[name] || globalAssemblyMode;
+          const expectedBody = (effectiveMode === 'link' && gen.linkPath && !gen.hasFallback)
+            ? `${heading}\n\n@${gen.linkPath}`
+            : `${heading}\n\n${gen.content}`;
           if (detectManualEdit(fileContent, name, expectedBody)) {
             sectionsSkipped.push(name);
             const genIdx = sectionsGenerated.indexOf(name);

get-shit-done/bin/lib/roadmap.cjs

@@ -353,8 +353,171 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
   }, raw, `${summaryCount}/${planCount} ${status}`);
 }
 
+/**
+ * Annotate the ROADMAP.md plan list for a phase with wave dependency notes
+ * and a cross-cutting constraints subsection derived from PLAN frontmatter.
+ *
+ * Wave dependency notes: "Wave 2 — blocked on Wave 1 completion" inserted as
+ * bold headers before each wave group in the plan checklist.
+ *
+ * Cross-cutting constraints: must_haves.truths strings that appear in 2+ plans
+ * are surfaced in a "Cross-cutting constraints" subsection below the plan list.
+ *
+ * The operation is idempotent: if wave headers already exist in the section
+ * the function returns without modifying the file.
+ */
+function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
+  if (!phaseNum) {
+    error('phase number required for roadmap annotate-dependencies');
+  }
+
+  const roadmapPath = planningPaths(cwd).roadmap;
+  if (!fs.existsSync(roadmapPath)) {
+    output({ updated: false, reason: 'ROADMAP.md not found' }, raw, 'no roadmap');
+    return;
+  }
+
+  const phaseInfo = findPhaseInternal(cwd, phaseNum);
+  if (!phaseInfo || phaseInfo.plans.length === 0) {
+    output({ updated: false, reason: 'no plans found for phase', phase: phaseNum }, raw, 'no plans');
+    return;
+  }
+
+  const { extractFrontmatter, parseMustHavesBlock } = require('./frontmatter.cjs');
+
+  // Read each PLAN.md and extract wave + must_haves.truths
+  const planData = [];
+  for (const planFile of phaseInfo.plans) {
+    const planPath = path.join(path.resolve(cwd, phaseInfo.directory), planFile);
+    try {
+      const content = fs.readFileSync(planPath, 'utf-8');
+      const fm = extractFrontmatter(content);
+      const wave = parseInt(fm.wave, 10) || 1;
+      const planId = planFile.replace(/-PLAN\.md$/i, '').replace(/PLAN\.md$/i, '');
+      const truths = parseMustHavesBlock(content, 'truths') || [];
+      planData.push({ planFile, planId, wave, truths });
+    } catch { /* skip unreadable plans */ }
+  }
+
+  if (planData.length === 0) {
+    output({ updated: false, reason: 'could not read plan frontmatter' }, raw, 'no frontmatter');
+    return;
+  }
+
+  // Group plans by wave (sorted)
+  const waveGroups = new Map();
+  for (const p of planData) {
+    if (!waveGroups.has(p.wave)) waveGroups.set(p.wave, []);
+    waveGroups.get(p.wave).push(p);
+  }
+  const waves = [...waveGroups.keys()].sort((a, b) => a - b);
+
+  // Find cross-cutting truths: appear in 2+ plans (de-duplicated, case-insensitive)
+  const truthCounts = new Map();
+  for (const { truths } of planData) {
+    const seen = new Set();
+    for (const t of truths) {
+      const key = t.trim().toLowerCase();
+      if (!key || seen.has(key)) continue;
+      seen.add(key);
+      truthCounts.set(key, (truthCounts.get(key) || { count: 0, text: t.trim() }));
+      truthCounts.get(key).count++;
+    }
+  }
+  const crossCuttingTruths = [...truthCounts.values()]
+    .filter(v => v.count >= 2)
+    .map(v => v.text);
+
+  // Patch ROADMAP.md
+  let updated = false;
+  withPlanningLock(cwd, () => {
+    let content = fs.readFileSync(roadmapPath, 'utf-8');
+
+    // Find the phase section
+    const phaseEscaped = escapeRegex(phaseNum);
+    const phaseHeaderPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEscaped}:[^\\n]*)`, 'i');
+    const phaseMatch = content.match(phaseHeaderPattern);
+    if (!phaseMatch) return;
+
+    const phaseStart = phaseMatch.index;
+    const restAfterHeader = content.slice(phaseStart);
+    const nextPhaseOffset = restAfterHeader.slice(1).search(/\n#{2,4}\s+Phase\s+\d/i);
+    const phaseEnd = nextPhaseOffset >= 0 ? phaseStart + 1 + nextPhaseOffset : content.length;
+    const phaseSection = content.slice(phaseStart, phaseEnd);
+
+    // Idempotency: skip if annotation markers already present
+    if (
+      /\*\*Wave\s+\d+/i.test(phaseSection) ||
+      /\*\*Cross-cutting constraints:\*\*/i.test(phaseSection)
+    ) return;
+
+    // Find the Plans: section within the phase section
+    const plansBlockMatch = phaseSection.match(/(Plans:\s*\n)((?:\s*-\s*\[[ x]\][^\n]*\n?)*)/i);
+    if (!plansBlockMatch) return;
+
+    const plansHeader = plansBlockMatch[1];
+    const existingList = plansBlockMatch[2];
+    const listLines = existingList.split('\n').filter(l => /^\s*-\s*\[/.test(l));
+
+    if (listLines.length === 0) return;
+
+    // Build wave-annotated plan list
+    const linesByWave = new Map();
+    for (const line of listLines) {
+      // Match plan ID from line: "- [ ] 01-01-PLAN.md — ..." or "- [ ] 01-01: ..."
+      const idMatch = line.match(/\[\s*[x ]\s*\]\s*([\w-]+?)(?:-PLAN\.md|\.md|:|\s—)/i);
+      const planId = idMatch ? idMatch[1] : null;
+      const planEntry = planId ? planData.find(p => p.planId === planId) : null;
+      const wave = planEntry ? planEntry.wave : 1;
+      if (!linesByWave.has(wave)) linesByWave.set(wave, []);
+      linesByWave.get(wave).push(line);
+    }
+
+    const annotatedLines = [];
+    const sortedWaves = [...linesByWave.keys()].sort((a, b) => a - b);
+    for (let i = 0; i < sortedWaves.length; i++) {
+      const w = sortedWaves[i];
+      const waveLines = linesByWave.get(w);
+      if (sortedWaves.length > 1) {
+        const dep = i > 0 ? ` *(blocked on Wave ${sortedWaves[i - 1]} completion)*` : '';
+        annotatedLines.push(`**Wave ${w}**${dep}`);
+      }
+      annotatedLines.push(...waveLines);
+      if (i < sortedWaves.length - 1) annotatedLines.push('');
+    }
+
+    // Append cross-cutting constraints subsection if any found
+    if (crossCuttingTruths.length > 0) {
+      annotatedLines.push('');
+      annotatedLines.push('**Cross-cutting constraints:**');
+      for (const t of crossCuttingTruths) {
+        annotatedLines.push(`- ${t}`);
+      }
+    }
+
+    const newListBlock = annotatedLines.join('\n') + '\n';
+    const newPhaseSection = phaseSection.replace(
+      plansBlockMatch[0],
+      plansHeader + newListBlock
+    );
+
+    const nextContent = content.slice(0, phaseStart) + newPhaseSection + content.slice(phaseEnd);
+    if (nextContent === content) return;
+    atomicWriteFileSync(roadmapPath, nextContent);
+    updated = true;
+  });
+
+  output({
+    updated,
+    phase: phaseNum,
+    waves: waves.length,
+    cross_cutting_constraints: crossCuttingTruths.length,
+  }, raw, updated ? `annotated ${waves.length} wave(s), ${crossCuttingTruths.length} constraint(s)` : 'skipped (already annotated or no plan list)');
+}
+
 module.exports = {
   cmdRoadmapGetPhase,
   cmdRoadmapAnalyze,
   cmdRoadmapUpdatePlanProgress,
+  cmdRoadmapAnnotateDependencies,
 };

get-shit-done/bin/lib/secrets.cjs

@@ -0,0 +1,33 @@
+'use strict';
+
+/**
+ * Secrets handling — masking convention for API keys and other
+ * credentials managed via /gsd-settings-integrations.
+ *
+ * Convention: strings 8+ chars long render as `****<last-4>`; shorter
+ * strings render as `****` with no tail (to avoid leaking a meaningful
+ * fraction of a short secret). null/empty renders as `(unset)`.
+ *
+ * Keys considered sensitive are listed in SECRET_CONFIG_KEYS and matched
+ * at the exact key-path level. The list is intentionally narrow — these
+ * are the fields documented as secrets in docs/CONFIGURATION.md.
+ */
+
+const SECRET_CONFIG_KEYS = new Set([
+  'brave_search',
+  'firecrawl',
+  'exa_search',
+]);
+
+function isSecretKey(keyPath) {
+  return SECRET_CONFIG_KEYS.has(keyPath);
+}
+
+function maskSecret(value) {
+  if (value === null || value === undefined || value === '') return '(unset)';
+  const s = String(value);
+  if (s.length < 8) return '****';
+  return '****' + s.slice(-4);
+}
+
+module.exports = { SECRET_CONFIG_KEYS, isSecretKey, maskSecret };

get-shit-done/bin/lib/security.cjs

@@ -245,14 +245,15 @@ function sanitizeForPrompt(text) {
   // Neutralize XML/HTML tags that mimic system boundaries
   // Replace < > with full-width equivalents to prevent tag interpretation
   // Note: <instructions> is excluded — GSD uses it as legitimate prompt structure
-  sanitized = sanitized.replace(/<(\/?)(?:system|assistant|human)>/gi,
+  // Matches system|assistant|human|user with optional whitespace before the closing >
+  sanitized = sanitized.replace(/<(\/?)\s*(?:system|assistant|human|user)\s*>/gi,
     (_, slash) => `＜${slash || ''}system-text＞`);
 
-  // Neutralize [SYSTEM] / [INST] / [/INST] markers
+  // Neutralize [SYSTEM] / [INST] / [/INST] markers — both opening and closing variants
   sanitized = sanitized.replace(/\[(\/?)(SYSTEM|INST)\]/gi, (_, slash, tag) => `[${slash}${tag.toUpperCase()}-TEXT]`);
 
-  // Neutralize <<SYS>> markers
-  sanitized = sanitized.replace(/<<\s*SYS\s*>>/gi, '«SYS-TEXT»');
+  // Neutralize <<SYS>> and <</SYS>> markers (Llama-style delimiters)
+  sanitized = sanitized.replace(/<<\/?\s*SYS\s*>>/gi, '«SYS-TEXT»');
 
   return sanitized;
 }

get-shit-done/bin/lib/state.cjs

@@ -29,12 +29,13 @@ process.on('exit', () => {
 
 // Shared helper: extract a field value from STATE.md content.
 // Supports both **Field:** bold and plain Field: format.
+// Horizontal whitespace only after ':' so YAML keys like `progress:` do not match as `Progress:` (parity with sdk/helpers stateExtractField).
 function stateExtractField(content, fieldName) {
   const escaped = escapeRegex(fieldName);
-  const boldPattern = new RegExp(`\\*\\*${escaped}:\\*\\*\\s*(.+)`, 'i');
+  const boldPattern = new RegExp(`\\*\\*${escaped}:\\*\\*[ \\t]*(.+)`, 'i');
   const boldMatch = content.match(boldPattern);
   if (boldMatch) return boldMatch[1].trim();
-  const plainPattern = new RegExp(`^${escaped}:\\s*(.+)`, 'im');
+  const plainPattern = new RegExp(`^${escaped}:[ \\t]*(.+)`, 'im');
   const plainMatch = content.match(plainPattern);
   return plainMatch ? plainMatch[1].trim() : null;
 }
@@ -720,7 +721,13 @@ function buildStateFrontmatter(bodyContent, cwd) {
   const status = stateExtractField(bodyContent, 'Status');
   const progressRaw = stateExtractField(bodyContent, 'Progress');
   const lastActivity = stateExtractField(bodyContent, 'Last Activity');
-  const stoppedAt = stateExtractField(bodyContent, 'Stopped At') || stateExtractField(bodyContent, 'Stopped at');
+  // Bug #2444: scope Stopped At extraction to the ## Session section so that
+  // historical "Stopped at:" prose elsewhere in the body (e.g. in a
+  // Session Continuity Archive section) never overwrites the current value.
+  // Fall back to full-body search only when no ## Session section exists.
+  const sessionSectionMatch = bodyContent.match(/##\s*Session\s*\n([\s\S]*?)(?=\n##|$)/i);
+  const sessionBodyScope = sessionSectionMatch ? sessionSectionMatch[1] : bodyContent;
+  const stoppedAt = stateExtractField(sessionBodyScope, 'Stopped At') || stateExtractField(sessionBodyScope, 'Stopped at');
   const pausedAt = stateExtractField(bodyContent, 'Paused At');
 
   let milestone = null;
@@ -747,9 +754,33 @@ function buildStateFrontmatter(bodyContent, cwd) {
         let cached = _diskScanCache.get(cwd);
         if (!cached) {
           const isDirInMilestone = getMilestonePhaseFilter(cwd);
-          const phaseDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
+          const allMatchingDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
             .filter(e => e.isDirectory()).map(e => e.name)
             .filter(isDirInMilestone);
+
+          // Bug #2445: when stale phase dirs from a prior milestone remain in
+          // .planning/phases/ alongside new dirs with the same phase number,
+          // de-duplicate by normalized phase number keeping the most recently
+          // modified dir. This prevents double-counting (e.g. two "Phase 1" dirs).
+          const seenPhaseNums = new Map(); // normalizedNum -> dirName
+          for (const dir of allMatchingDirs) {
+            const m = dir.match(/^0*(\d+[A-Za-z]?(?:\.\d+)*)/);
+            const key = m ? m[1].toLowerCase() : dir;
+            if (!seenPhaseNums.has(key)) {
+              seenPhaseNums.set(key, dir);
+            } else {
+              // Keep the dir that is newer on disk (more likely current milestone)
+              try {
+                const existing = path.join(phasesDir, seenPhaseNums.get(key));
+                const candidate = path.join(phasesDir, dir);
+                if (fs.statSync(candidate).mtimeMs > fs.statSync(existing).mtimeMs) {
+                  seenPhaseNums.set(key, dir);
+                }
+              } catch { /* keep existing on stat error */ }
+            }
+          }
+          const phaseDirs = [...seenPhaseNums.values()];
+
           let diskTotalPlans = 0;
           let diskTotalSummaries = 0;
           let diskCompletedPhases = 0;
@@ -1222,6 +1253,70 @@ function cmdStatePlannedPhase(cwd, phaseNumber, planCount, raw) {
   output({ updated, phase: phaseNumber, plan_count: planCount }, raw, updated.length > 0 ? 'true' : 'false');
 }
 
+/**
+ * Bug #2630: reset STATE.md for a new milestone cycle.
+ * Stomps frontmatter milestone/milestone_name/status/progress AND rewrites
+ * the Current Position body. Preserves Accumulated Context.
+ * Symmetric with the SDK `stateMilestoneSwitch` handler.
+ */
+function cmdStateMilestoneSwitch(cwd, version, name, raw) {
+  if (!version || !String(version).trim()) {
+    output({ error: 'milestone required (--milestone <vX.Y>)' }, raw);
+    return;
+  }
+  const resolvedName = (name && String(name).trim()) || 'milestone';
+  const statePath = planningPaths(cwd).state;
+  const today = new Date().toISOString().split('T')[0];
+
+  const lockPath = acquireStateLock(statePath);
+  try {
+    const content = fs.existsSync(statePath) ? fs.readFileSync(statePath, 'utf-8') : '';
+    const existingFm = extractFrontmatter(content);
+    const body = stripFrontmatter(content);
+
+    const positionPattern = /(##\s*Current Position\s*\n)([\s\S]*?)(?=\n##|$)/i;
+    const resetPositionBody =
+      `\nPhase: Not started (defining requirements)\n` +
+      `Plan: —\n` +
+      `Status: Defining requirements\n` +
+      `Last activity: ${today} — Milestone ${version} started\n\n`;
+    let newBody;
+    if (positionPattern.test(body)) {
+      newBody = body.replace(positionPattern, (_m, header) => `${header}${resetPositionBody}`);
+    } else {
+      const preface = body.trim().length > 0 ? body : '# Project State\n';
+      newBody = `${preface.trimEnd()}\n\n## Current Position\n${resetPositionBody}`;
+    }
+
+    const fm = {
+      gsd_state_version: existingFm.gsd_state_version || '1.0',
+      milestone: version,
+      milestone_name: resolvedName,
+      status: 'planning',
+      last_updated: new Date().toISOString(),
+      last_activity: today,
+      progress: {
+        total_phases: 0,
+        completed_phases: 0,
+        total_plans: 0,
+        completed_plans: 0,
+        percent: 0,
+      },
+    };
+
+    const yamlStr = reconstructFrontmatter(fm);
+    const assembled = `---\n${yamlStr}\n---\n\n${newBody.replace(/^\n+/, '')}`;
+    atomicWriteFileSync(statePath, normalizeMd(assembled), 'utf-8');
+    output(
+      { switched: true, version, name: resolvedName, status: 'planning' },
+      raw,
+      'true',
+    );
+  } finally {
+    releaseStateLock(lockPath);
+  }
+}
+
 /**
  * Gate 1: Validate STATE.md against filesystem.
  * Returns { valid, warnings, drift } JSON.
@@ -1613,6 +1708,7 @@ module.exports = {
   cmdStateValidate,
   cmdStateSync,
   cmdStatePrune,
+  cmdStateMilestoneSwitch,
   cmdSignalWaiting,
   cmdSignalResume,
 };

get-shit-done/bin/lib/uat.cjs

@@ -225,6 +225,11 @@ function parseVerificationItems(content, status) {
         const numberedMatch = line.match(/^(\d+)\.\s+(.+)/);
 
         if (tableMatch) {
+          // Skip rows that already have a passing result (PASS, pass, resolved, etc.)
+          const rowRemainder = line.slice(tableMatch.index + tableMatch[0].length);
+          const cellValues = rowRemainder.split('|').map(c => c.trim());
+          const hasPassResult = cellValues.some(c => /^pass$/i.test(c) || /^resolved$/i.test(c));
+          if (hasPassResult) continue;
           items.push({
             test: parseInt(tableMatch[1], 10),
             name: tableMatch[2].trim(),

get-shit-done/bin/lib/verify.cjs

@@ -591,28 +591,57 @@ function cmdValidateHealth(cwd, options, raw) {
   } else {
     const stateContent = fs.readFileSync(statePath, 'utf-8');
     // Extract phase references from STATE.md
-    const phaseRefs = [...stateContent.matchAll(/[Pp]hase\s+(\d+(?:\.\d+)*)/g)].map(m => m[1]);
-    // Get disk phases
-    const diskPhases = new Set();
+    const phaseRefs = [...stateContent.matchAll(/[Pp]hase\s+(\d+[A-Z]?(?:\.\d+)*)/g)].map(m => m[1]);
+    // Bug #2633 — ROADMAP.md is the authority for which phases are valid.
+    // STATE.md may legitimately reference current-milestone future phases
+    // (not yet materialized on disk) and shipped-milestone history phases
+    // (archived / cleared off disk). Matching only against on-disk dirs
+    // produces false W002 warnings in both cases.
+    const validPhases = new Set();
     try {
       const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
       for (const e of entries) {
         if (e.isDirectory()) {
-          const m = e.name.match(/^(\d+(?:\.\d+)*)/);
-          if (m) diskPhases.add(m[1]);
+          const m = e.name.match(/^(\d+[A-Z]?(?:\.\d+)*)/);
+          if (m) validPhases.add(m[1]);
         }
       }
     } catch { /* intentionally empty */ }
+    // Union in every phase declared anywhere in ROADMAP.md (current + shipped + backlog).
+    try {
+      if (fs.existsSync(roadmapPath)) {
+        const roadmapRaw = fs.readFileSync(roadmapPath, 'utf-8');
+        const all = [...roadmapRaw.matchAll(/#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)/gi)];
+        for (const m of all) validPhases.add(m[1]);
+      }
+    } catch { /* intentionally empty */ }
+    // Compare canonical full phase tokens. Also accept a leading-zero variant
+    // on the integer prefix only (e.g. "03" matching "3", "03.1" matching
+    // "3.1") so historic STATE.md formatting still validates. Suffix tokens
+    // like "3A" must match exactly — never collapsed to "3".
+    const normalizedValid = new Set();
+    for (const p of validPhases) {
+      normalizedValid.add(p);
+      const dotIdx = p.indexOf('.');
+      const head = dotIdx === -1 ? p : p.slice(0, dotIdx);
+      const tail = dotIdx === -1 ? '' : p.slice(dotIdx);
+      if (/^\d+$/.test(head)) {
+        normalizedValid.add(head.padStart(2, '0') + tail);
+      }
+    }
     // Check for invalid references
     for (const ref of phaseRefs) {
-      const normalizedRef = String(parseInt(ref, 10)).padStart(2, '0');
-      if (!diskPhases.has(ref) && !diskPhases.has(normalizedRef) && !diskPhases.has(String(parseInt(ref, 10)))) {
-        // Only warn if phases dir has any content (not just an empty project)
-        if (diskPhases.size > 0) {
+      const dotIdx = ref.indexOf('.');
+      const head = dotIdx === -1 ? ref : ref.slice(0, dotIdx);
+      const tail = dotIdx === -1 ? '' : ref.slice(dotIdx);
+      const padded = /^\d+$/.test(head) ? head.padStart(2, '0') + tail : ref;
+      if (!normalizedValid.has(ref) && !normalizedValid.has(padded)) {
+        // Only warn if we know any valid phases (not just an empty project)
+        if (normalizedValid.size > 0) {
           addIssue(
             'warning',
             'W002',
-            `STATE.md references phase ${ref}, but only phases ${[...diskPhases].sort().join(', ')} exist`,
+            `STATE.md references phase ${ref}, but only phases ${[...validPhases].sort().join(', ')} are declared`,
             'Review STATE.md manually before changing it; /gsd-health --repair will not overwrite an existing STATE.md for phase mismatches'
           );
         }
@@ -871,6 +900,54 @@ function cmdValidateHealth(cwd, options, raw) {
     }
   } catch { /* git worktree not available or not a git repo — skip silently */ }
 
+  // ─── Check 12: MILESTONES.md / archive snapshot drift (#2446) ─────────────
+  const milestonesPath = path.join(planBase, 'MILESTONES.md');
+  const milestonesArchiveDir = path.join(planBase, 'milestones');
+  const missingFromRegistry = [];
+  try {
+    if (fs.existsSync(milestonesArchiveDir)) {
+      const archiveFiles = fs.readdirSync(milestonesArchiveDir);
+      const archivedVersions = archiveFiles
+        .map(f => f.match(/^(v\d+\.\d+(?:\.\d+)?)-ROADMAP\.md$/))
+        .filter(Boolean)
+        .map(m => m[1]);
+
+      if (archivedVersions.length > 0) {
+        const registryContent = fs.existsSync(milestonesPath)
+          ? fs.readFileSync(milestonesPath, 'utf-8')
+          : '';
+        for (const ver of archivedVersions) {
+          if (!registryContent.includes(`## ${ver}`)) {
+            missingFromRegistry.push(ver);
+          }
+        }
+        if (missingFromRegistry.length > 0) {
+          addIssue('warning', 'W018',
+            `MILESTONES.md missing ${missingFromRegistry.length} archived milestone(s): ${missingFromRegistry.join(', ')}`,
+            'Run /gsd-health --backfill to synthesize missing entries from archive snapshots',
+            true);
+          repairs.push('backfillMilestones');
+        }
+      }
+    }
+  } catch { /* intentionally empty — milestone sync check is advisory */ }
+
+  // ─── Check 13: Unrecognized .planning/ root files (W019) ──────────────────
+  try {
+    const { isCanonicalPlanningFile } = require('./artifacts.cjs');
+    const entries = fs.readdirSync(planBase, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      if (!entry.name.endsWith('.md')) continue;
+      if (!isCanonicalPlanningFile(entry.name)) {
+        addIssue('warning', 'W019',
+          `Unrecognized .planning/ file: ${entry.name} — not a canonical GSD artifact`,
+          'Move to .planning/milestones/ archive subdir or delete if stale. See templates/README.md for the canonical artifact list.',
+          false);
+      }
+    }
+  } catch { /* artifact check is advisory — skip on error */ }
+
   // ─── Perform repairs if requested ─────────────────────────────────────────
   const repairActions = [];
   if (options.repair && repairs.length > 0) {
@@ -960,6 +1037,39 @@ function cmdValidateHealth(cwd, options, raw) {
             }
             break;
           }
+          case 'backfillMilestones': {
+            if (!options.backfill && !options.repair) break;
+            const today = new Date().toISOString().split('T')[0];
+            let backfilled = 0;
+            for (const ver of missingFromRegistry) {
+              try {
+                const snapshotPath = path.join(milestonesArchiveDir, `${ver}-ROADMAP.md`);
+                const snapshot = fs.existsSync(snapshotPath) ? fs.readFileSync(snapshotPath, 'utf-8') : null;
+                // Build minimal entry from snapshot title or version
+                const titleMatch = snapshot && snapshot.match(/^#\s+(.+)$/m);
+                const milestoneName = titleMatch ? titleMatch[1].replace(/^Milestone\s+/i, '').replace(/^v[\d.]+\s*/, '').trim() : ver;
+                const entry = `## ${ver}${milestoneName && milestoneName !== ver ? ` ${milestoneName}` : ''} (Backfilled: ${today})\n\n**Note:** Synthesized from archive snapshot by \`/gsd-health --backfill\`. Original completion date unknown.\n\n---\n\n`;
+                const milestonesContent = fs.existsSync(milestonesPath)
+                  ? fs.readFileSync(milestonesPath, 'utf-8')
+                  : '';
+                if (!milestonesContent.trim()) {
+                  fs.writeFileSync(milestonesPath, `# Milestones\n\n${entry}`, 'utf-8');
+                } else {
+                  const headerMatch = milestonesContent.match(/^(#{1,3}\s+[^\n]*\n\n?)/);
+                  if (headerMatch) {
+                    const header = headerMatch[1];
+                    const rest = milestonesContent.slice(header.length);
+                    fs.writeFileSync(milestonesPath, header + entry + rest, 'utf-8');
+                  } else {
+                    fs.writeFileSync(milestonesPath, entry + milestonesContent, 'utf-8');
+                  }
+                }
+                backfilled++;
+              } catch { /* intentionally empty — partial backfill is acceptable */ }
+            }
+            repairActions.push({ action: repair, success: true, detail: `Backfilled ${backfilled} milestone(s) into MILESTONES.md` });
+            break;
+          }
         }
       } catch (err) {
         repairActions.push({ action: repair, success: false, error: err.message });
@@ -980,14 +1090,16 @@ function cmdValidateHealth(cwd, options, raw) {
   const repairableCount = errors.filter(e => e.repairable).length +
                          warnings.filter(w => w.repairable).length;
 
-  output({
+  const result = {
     status,
     errors,
     warnings,
     info,
     repairable_count: repairableCount,
     repairs_performed: repairActions.length > 0 ? repairActions : undefined,
-  }, raw);
+  };
+  output(result, raw);
+  return result;
 }
 
 /**
@@ -1086,6 +1198,141 @@ function cmdVerifySchemaDrift(cwd, phaseArg, skipFlag, raw) {
   }, raw);
 }
 
+// ─── Codebase Drift Detection (#2003) ────────────────────────────────────────
+
+/**
+ * Detect structural drift between the committed tree and
+ * `.planning/codebase/STRUCTURE.md`. Non-blocking: any failure returns a
+ * `{ skipped: true }` JSON result with a reason; the command never exits
+ * non-zero so `execute-phase`'s drift gate cannot fail the phase.
+ */
+function cmdVerifyCodebaseDrift(cwd, raw) {
+  const drift = require('./drift.cjs');
+
+  const emit = (payload) => output(payload, raw);
+
+  try {
+    const codebaseDir = path.join(planningDir(cwd), 'codebase');
+    const structurePath = path.join(codebaseDir, 'STRUCTURE.md');
+    if (!fs.existsSync(structurePath)) {
+      emit({
+        skipped: true,
+        reason: 'no-structure-md',
+        action_required: false,
+        directive: 'none',
+        elements: [],
+      });
+      return;
+    }
+
+    let structureMd;
+    try {
+      structureMd = fs.readFileSync(structurePath, 'utf-8');
+    } catch (err) {
+      emit({
+        skipped: true,
+        reason: 'cannot-read-structure-md: ' + err.message,
+        action_required: false,
+        directive: 'none',
+        elements: [],
+      });
+      return;
+    }
+
+    const lastMapped = drift.readMappedCommit(structurePath);
+
+    // Verify we're inside a git repo and resolve the diff range.
+    const revProbe = execGit(cwd, ['rev-parse', 'HEAD']);
+    if (revProbe.exitCode !== 0) {
+      emit({
+        skipped: true,
+        reason: 'not-a-git-repo',
+        action_required: false,
+        directive: 'none',
+        elements: [],
+      });
+      return;
+    }
+
+    // Empty-tree SHA is a stable fallback when no mapping commit is recorded.
+    const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+    let base = lastMapped;
+    if (!base) {
+      base = EMPTY_TREE;
+    } else {
+      // Verify the commit is reachable; if not, fall back to EMPTY_TREE.
+      const verify = execGit(cwd, ['cat-file', '-t', base]);
+      if (verify.exitCode !== 0) base = EMPTY_TREE;
+    }
+
+    const diff = execGit(cwd, ['diff', '--name-status', base, 'HEAD']);
+    if (diff.exitCode !== 0) {
+      emit({
+        skipped: true,
+        reason: 'git-diff-failed',
+        action_required: false,
+        directive: 'none',
+        elements: [],
+      });
+      return;
+    }
+
+    const added = [];
+    const modified = [];
+    const deleted = [];
+    for (const line of diff.stdout.split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      const m = line.match(/^([A-Z])\d*\t(.+?)(?:\t(.+))?$/);
+      if (!m) continue;
+      const status = m[1];
+      // For renames (R), use the new path (m[3] if present, else m[2]).
+      const file = m[3] || m[2];
+      if (status === 'A' || status === 'R' || status === 'C') added.push(file);
+      else if (status === 'M') modified.push(file);
+      else if (status === 'D') deleted.push(file);
+    }
+
+    // Threshold and action read from config, with defaults.
+    const config = loadConfig(cwd);
+    const threshold = Number.isInteger(config?.workflow?.drift_threshold) && config.workflow.drift_threshold >= 1
+      ? config.workflow.drift_threshold
+      : 3;
+    const action = config?.workflow?.drift_action === 'auto-remap' ? 'auto-remap' : 'warn';
+
+    const result = drift.detectDrift({
+      addedFiles: added,
+      modifiedFiles: modified,
+      deletedFiles: deleted,
+      structureMd,
+      threshold,
+      action,
+    });
+
+    emit({
+      skipped: !!result.skipped,
+      reason: result.reason || null,
+      action_required: !!result.actionRequired,
+      directive: result.directive,
+      spawn_mapper: !!result.spawnMapper,
+      affected_paths: result.affectedPaths || [],
+      elements: result.elements || [],
+      threshold,
+      action,
+      last_mapped_commit: lastMapped,
+      message: result.message || '',
+    });
+  } catch (err) {
+    // Non-blocking: never bubble up an exception.
+    emit({
+      skipped: true,
+      reason: 'exception: ' + (err && err.message ? err.message : String(err)),
+      action_required: false,
+      directive: 'none',
+      elements: [],
+    });
+  }
+}
+
 module.exports = {
   cmdVerifySummary,
   cmdVerifyPlanStructure,
@@ -1098,4 +1345,5 @@ module.exports = {
   cmdValidateHealth,
   cmdValidateAgents,
   cmdVerifySchemaDrift,
+  cmdVerifyCodebaseDrift,
 };

get-shit-done/references/context-budget.md

@@ -12,7 +12,7 @@ Every workflow that spawns agents or reads significant content must follow these
 
 1. **Never** read agent definition files (`agents/*.md`) -- `subagent_type` auto-loads them
 2. **Never** inline large files into subagent prompts -- tell agents to read files from disk instead
-3. **Read depth scales with context window** -- check `context_window_tokens` in `.planning/config.json`:
+3. **Read depth scales with context window** -- check `context_window` in `.planning/config.json`:
    - At < 500000 tokens (default 200k): read only frontmatter, status fields, or summaries. Never read full SUMMARY.md, VERIFICATION.md, or RESEARCH.md bodies.
    - At >= 500000 tokens (1M model): MAY read full subagent output bodies when the content is needed for inline presentation or decision-making. Still avoid unnecessary reads.
 4. **Delegate** heavy work to subagents -- the orchestrator routes, it doesn't execute
@@ -25,7 +25,7 @@ Every workflow that spawns agents or reads significant content must follow these
 | < 500k (200k model) | Frontmatter only | Frontmatter only | Frontmatter only | Current phase only |
 | >= 500k (1M model) | Full body permitted | Full body permitted | Full body permitted | Current phase only |
 
-**How to check:** Read `.planning/config.json` and inspect `context_window_tokens`. If the field is absent, treat as 200k (conservative default).
+**How to check:** Read `.planning/config.json` and inspect `context_window`. If the field is absent, treat as 200k (conservative default).
 
 ## Context Degradation Tiers
 

get-shit-done/references/planner-chunked.md

@@ -0,0 +1,49 @@
+# Chunked Mode Return Formats
+
+Used when `plan-phase` spawns `gsd-planner` with `CHUNKED_MODE=true` (triggered by `--chunked`
+flag or `workflow.plan_chunked: true` config). Splits the single long-lived planner Task into
+shorter-lived Tasks to bound the blast radius of Windows stdio hangs.
+
+## Modes
+
+### outline-only
+
+Write **only** `{PHASE_DIR}/{PADDED_PHASE}-PLAN-OUTLINE.md`. Do not write any PLAN.md files.
+Return:
+
+```markdown
+## OUTLINE COMPLETE
+
+**Phase:** {phase-name}
+**Plans:** {N} plan(s) in {M} wave(s)
+
+| Plan ID | Objective | Wave | Depends On | Requirements |
+|---------|-----------|------|-----------|-------------|
+| {padded_phase}-01 | [brief objective] | 1 | none | REQ-001, REQ-002 |
+| {padded_phase}-02 | [brief objective] | 1 | none | REQ-003 |
+```
+
+The orchestrator reads this table, then spawns one single-plan Task per row.
+
+### single-plan
+
+Write **exactly one** `{PHASE_DIR}/{plan_id}-PLAN.md`. Do not write any other plan files.
+Return:
+
+```markdown
+## PLAN COMPLETE
+
+**Plan:** {plan-id}
+**Objective:** {brief}
+**File:** {PHASE_DIR}/{plan-id}-PLAN.md
+**Tasks:** {N}
+```
+
+The orchestrator verifies the file exists on disk after each return, commits it, then moves
+to the next plan entry from the outline.
+
+## Resume Behaviour
+
+If the orchestrator detects that `PLAN-OUTLINE.md` already exists (from a prior interrupted
+run), it skips the outline-only Task and goes directly to single-plan Tasks, skipping any
+`{plan_id}-PLAN.md` files that already exist on disk.

get-shit-done/references/planning-config.md

@@ -54,7 +54,7 @@ Configuration options for `.planning/` directory behavior.
 - User must add `.planning/` to `.gitignore`
 - Useful for: OSS contributions, client projects, keeping planning private
 
-**Using gsd-tools.cjs (preferred):**
+**Using `gsd-sdk query` (preferred):**
 
 ```bash
 # Commit with automatic commit_docs + gitignore checks:
@@ -268,6 +268,7 @@ Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research":
 | `workflow.security_enforcement` | boolean | `true` | `true`, `false` | Enable threat-model-anchored security verification via `/gsd-secure-phase`. When `false`, security checks are skipped entirely |
 | `workflow.security_asvs_level` | number | `1` | `1`, `2`, `3` | OWASP ASVS verification level. Level 1 = opportunistic, Level 2 = standard, Level 3 = comprehensive |
 | `workflow.security_block_on` | string | `"high"` | `"high"`, `"medium"`, `"low"` | Minimum severity that blocks phase advancement |
+| `workflow.post_planning_gaps` | boolean | `true` | `true`, `false` | Post-planning gap report (#2493). After plans are generated, scans REQUIREMENTS.md and CONTEXT.md `<decisions>` against all PLAN.md files and emits a unified `Source \| Item \| Status` table. Non-blocking. Set to `false` to skip Step 13e of plan-phase. _Alias:_ `post_planning_gaps` is the flat-key form used in `CONFIG_DEFAULTS`; `workflow.post_planning_gaps` is the canonical namespaced form. |
 
 ### Git Fields
 

get-shit-done/references/scout-codebase.md

@@ -0,0 +1,51 @@
+# Codebase scout — map selection table
+
+> Lazy-loaded reference for the `scout_codebase` step in
+> `workflows/discuss-phase.md` (extracted via #2551 progressive-disclosure
+> refactor). Read this only when prior `.planning/codebase/*.md` maps exist
+> and the workflow needs to pick which 2–3 to load.
+
+## Phase-type → recommended maps
+
+Read 2–3 maps based on inferred phase type. Do NOT read all seven —
+that inflates context without improving discussion quality.
+
+| Phase type (infer from title + ROADMAP entry) | Read these maps |
+|---|---|
+| UI / frontend / styling / design | CONVENTIONS.md, STRUCTURE.md, STACK.md |
+| Backend / API / service / data model | STACK.md, ARCHITECTURE.md, INTEGRATIONS.md |
+| Integration / third-party / provider | STACK.md, INTEGRATIONS.md, ARCHITECTURE.md |
+| Infrastructure / DevOps / CI / deploy | STACK.md, ARCHITECTURE.md, INTEGRATIONS.md |
+| Testing / QA / coverage | TESTING.md, CONVENTIONS.md, STRUCTURE.md |
+| Documentation / content | CONVENTIONS.md, STRUCTURE.md |
+| Mixed / unclear | STACK.md, ARCHITECTURE.md, CONVENTIONS.md |
+
+Read CONCERNS.md only if the phase explicitly addresses known concerns or
+security issues.
+
+## Single-read rule
+
+Read each map file in a **single** Read call. Do not read the same file at
+two different offsets — split reads break prompt-cache reuse and cost more
+than a single full read.
+
+## No-maps fallback
+
+If `.planning/codebase/*.md` does not exist:
+1. Extract key terms from the phase goal (e.g., "feed" → "post", "card",
+   "list"; "auth" → "login", "session", "token")
+2. `grep -rlE "{term1}|{term2}" src/ app/ --include="*.ts" ...` (use `-E`
+   for extended regex so the `|` alternation works on both GNU grep and BSD
+   grep / macOS), and `ls` the conventional component/hook/util dirs
+3. Read the 3–5 most relevant files
+
+## Output (internal `<codebase_context>`)
+
+From the scan, identify:
+- **Reusable assets** — components, hooks, utilities usable in this phase
+- **Established patterns** — state management, styling, data fetching
+- **Integration points** — routes, nav, providers where new code connects
+- **Creative options** — approaches the architecture enables or constrains
+
+Used in `analyze_phase` and `present_gray_areas`. NOT written to a file —
+session-only.

get-shit-done/references/universal-anti-patterns.md

@@ -8,13 +8,13 @@ Rules that apply to ALL workflows and agents. Individual workflows may have addi
 
 1. **Never** read agent definition files (`agents/*.md`) -- `subagent_type` auto-loads them. Reading agent definitions into the orchestrator wastes context for content automatically injected into subagent sessions.
 2. **Never** inline large files into subagent prompts -- tell agents to read files from disk instead. Agents have their own context windows.
-3. **Read depth scales with context window** -- check `context_window_tokens` in `.planning/config.json`. At < 500000: read only frontmatter, status fields, or summaries. At >= 500000 (1M model): full body reads permitted when content is needed for inline decisions. See `references/context-budget.md` for the complete table.
+3. **Read depth scales with context window** -- check `context_window` in `.planning/config.json`. At < 500000: read only frontmatter, status fields, or summaries. At >= 500000 (1M model): full body reads permitted when content is needed for inline decisions. See `references/context-budget.md` for the complete table.
 4. **Delegate** heavy work to subagents -- the orchestrator routes, it does not build, analyze, research, investigate, or verify.
 5. **Proactive pause warning**: If you have already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider checkpointing progress."
 
 ## File Reading Rules
 
-6. **SUMMARY.md read depth scales with context window** -- at context_window_tokens < 500000: read frontmatter only from prior phase SUMMARYs. At >= 500000: full body reads permitted for direct-dependency phases. Transitive dependencies (2+ phases back) remain frontmatter-only regardless.
+6. **SUMMARY.md read depth scales with context window** -- at context_window < 500000: read frontmatter only from prior phase SUMMARYs. At >= 500000: full body reads permitted for direct-dependency phases. Transitive dependencies (2+ phases back) remain frontmatter-only regardless.
 7. **Never** read full PLAN.md files from other phases -- only current phase plans.
 8. **Never** read `.planning/logs/` files -- only the health workflow reads these.
 9. **Do not** re-read full file contents when frontmatter is sufficient -- frontmatter contains status, key_files, commits, and provides fields. Exception: at >= 500000, re-reading full body is acceptable when semantic content is needed.
@@ -34,7 +34,7 @@ Reference: `references/questioning.md` for the full anti-pattern list.
 
 ## State Management Anti-Patterns
 
-15. **No direct Write/Edit to STATE.md or ROADMAP.md for mutations.** Always use `gsd-tools.cjs` CLI commands (`state update`, `state advance-plan`, `roadmap update-status`) for mutations. Direct Write tool usage bypasses safe update logic and is unsafe in multi-session environments. Exception: first-time creation of STATE.md from template is allowed.
+15. **No direct Write/Edit to STATE.md or ROADMAP.md for mutations.** Always use `gsd-sdk query` for registered state/roadmap handlers (e.g. `state.update`, `state.advance-plan`, `roadmap.update-plan-progress`), or legacy `node …/gsd-tools.cjs` for CLI-only commands. Direct Write tool usage bypasses safe update logic and is unsafe in multi-session environments. Exception: first-time creation of STATE.md from template is allowed.
 
 ## Behavioral Rules
 
@@ -53,7 +53,7 @@ Reference: `references/questioning.md` for the full anti-pattern list.
 ## GSD-Specific Rules
 
 24. **Do not** check for `mode === 'auto'` or `mode === 'autonomous'` -- GSD uses `yolo` config flag. Check `yolo: true` for autonomous mode, absence or `false` for interactive mode.
-25. **Always use `gsd-tools.cjs`** (not `gsd-tools.js` or any other variant) -- GSD uses CommonJS for Node.js CLI compatibility.
+25. **Prefer `gsd-sdk query`** for orchestration when a handler exists; when shelling out to the legacy CLI, use **`gsd-tools.cjs`** (not `gsd-tools.js` or any other filename) — GSD ships the programmatic API as CommonJS for Node.js CLI compatibility.
 26. **Plan files MUST follow `{padded_phase}-{NN}-PLAN.md` pattern** (e.g., `01-01-PLAN.md`). Never use `PLAN-01.md`, `plan-01.md`, or any other variation -- gsd-tools detection depends on this exact pattern.
 27. **Do not start executing the next plan before writing the SUMMARY.md for the current plan** -- downstream plans may reference it via `@` includes.
 

get-shit-done/templates/README.md

@@ -0,0 +1,76 @@
+# GSD Canonical Artifact Registry
+
+This directory contains the template files for every artifact that GSD workflows officially produce. The table below is the authoritative index: **if a `.planning/` root file is not listed here, `gsd-health` will flag it as W019** (unrecognized artifact).
+
+Agents should query this file before treating a `.planning/` file as authoritative. If the file name does not appear below, it is not a canonical GSD artifact.
+
+---
+
+## `.planning/` Root Artifacts
+
+These files live directly at `.planning/` — not inside phase subdirectories.
+
+| File | Template | Produced by | Purpose |
+|------|----------|-------------|---------|
+| `PROJECT.md` | `project.md` | `/gsd-new-project` | Project identity, goals, requirements summary |
+| `ROADMAP.md` | `roadmap.md` | `/gsd-new-milestone`, `/gsd-new-project` | Phase plan with milestones and progress tracking |
+| `STATE.md` | `state.md` | `/gsd-new-project`, `/gsd-health --repair` | Current session state, active phase, last activity |
+| `REQUIREMENTS.md` | `requirements.md` | `/gsd-new-milestone` | Functional requirements with traceability |
+| `MILESTONES.md` | `milestone.md` | `/gsd-complete-milestone` | Log of completed milestones with accomplishments |
+| `BACKLOG.md` | *(inline)* | `/gsd-add-backlog` | Pending ideas and deferred work |
+| `LEARNINGS.md` | *(inline)* | `/gsd-extract-learnings`, `/gsd-execute-phase` | Phase retrospective learnings for future plans |
+| `THREADS.md` | *(inline)* | `/gsd-thread` | Persistent discussion threads |
+| `config.json` | `config.json` | `/gsd-new-project`, `/gsd-health --repair` | Project-specific GSD configuration |
+| `CLAUDE.md` | `claude-md.md` | `/gsd-profile` | Auto-assembled Claude Code context file |
+
+### Version-stamped artifacts (pattern: `vX.Y-*.md`)
+
+| Pattern | Produced by | Purpose |
+|---------|-------------|---------|
+| `vX.Y-MILESTONE-AUDIT.md` | `/gsd-audit-milestone` | Milestone audit report before archiving |
+
+These files are archived to `.planning/milestones/` by `/gsd-complete-milestone`. Finding them at the `.planning/` root after completion indicates the archive step was skipped.
+
+---
+
+## Phase Subdirectory Artifacts (`.planning/phases/NN-name/`)
+
+These files live inside a phase directory. They are NOT checked by W019 (which only inspects the `.planning/` root).
+
+| File Pattern | Template | Produced by | Purpose |
+|-------------|----------|-------------|---------|
+| `NN-MM-PLAN.md` | `phase-prompt.md` | `/gsd-plan-phase` | Executable implementation plan |
+| `NN-MM-SUMMARY.md` | `summary.md` | `/gsd-execute-phase` | Post-execution summary with learnings |
+| `NN-CONTEXT.md` | `context.md` | `/gsd-discuss-phase` | Scoped discussion decisions for the phase |
+| `NN-RESEARCH.md` | `research.md` | `/gsd-research-phase`, `/gsd-plan-phase` | Technical research for the phase |
+| `NN-VALIDATION.md` | `VALIDATION.md` | `/gsd-research-phase` (Nyquist) | Validation architecture (Nyquist method) |
+| `NN-UAT.md` | `UAT.md` | `/gsd-validate-phase` | User acceptance test results |
+| `NN-PATTERNS.md` | *(inline)* | `/gsd-plan-phase` (pattern mapper) | Analog file mapping for the phase |
+| `NN-UI-SPEC.md` | `UI-SPEC.md` | `/gsd-ui-phase` | UI design contract |
+| `NN-SECURITY.md` | `SECURITY.md` | `/gsd-secure-phase` | Security threat model |
+| `NN-AI-SPEC.md` | `AI-SPEC.md` | `/gsd-ai-integration-phase` | AI integration spec with eval strategy |
+| `NN-DEBUG.md` | `DEBUG.md` | `/gsd-debug` | Debug session log |
+| `NN-REVIEWS.md` | *(inline)* | `/gsd-review` | Cross-AI review feedback |
+
+---
+
+## Milestone Archive (`.planning/milestones/`)
+
+Files archived by `/gsd-complete-milestone`. These are never checked by W019.
+
+| File Pattern | Source |
+|-------------|--------|
+| `vX.Y-ROADMAP.md` | Snapshot of ROADMAP.md at milestone close |
+| `vX.Y-REQUIREMENTS.md` | Snapshot of REQUIREMENTS.md at milestone close |
+| `vX.Y-MILESTONE-AUDIT.md` | Moved from `.planning/` root |
+| `vX.Y-phases/` | Archived phase directories (if `--archive-phases` used) |
+
+---
+
+## Adding a New Canonical Artifact
+
+When a new workflow produces a `.planning/` root file:
+
+1. Add the file name to `CANONICAL_EXACT` in `get-shit-done/bin/lib/artifacts.cjs`
+2. Add a row to the **`.planning/` Root Artifacts** table above
+3. Add the template to `get-shit-done/templates/` if one exists

get-shit-done/workflows/audit-fix.md

@@ -103,7 +103,25 @@ Task(
 
 **b. Run tests:**
 ```bash
-npm test 2>&1 | tail -20
+AUDIT_TEST_CMD=$(gsd-sdk query config-get workflow.test_command --default "" 2>/dev/null || true)
+if [ -z "$AUDIT_TEST_CMD" ]; then
+  if [ -f "Makefile" ] && grep -q "^test:" Makefile; then
+    AUDIT_TEST_CMD="make test"
+  elif [ -f "Justfile" ] || [ -f "justfile" ]; then
+    AUDIT_TEST_CMD="just test"
+  elif [ -f "package.json" ]; then
+    AUDIT_TEST_CMD="npm test"
+  elif [ -f "Cargo.toml" ]; then
+    AUDIT_TEST_CMD="cargo test"
+  elif [ -f "go.mod" ]; then
+    AUDIT_TEST_CMD="go test ./..."
+  elif [ -f "pyproject.toml" ] || [ -f "requirements.txt" ]; then
+    AUDIT_TEST_CMD="python -m pytest -x -q --tb=short"
+  else
+    AUDIT_TEST_CMD="true"
+  fi
+fi
+eval "$AUDIT_TEST_CMD" 2>&1 | tail -20
 ```
 
 **c. If tests pass** — commit atomically:

get-shit-done/workflows/audit-milestone.md

@@ -18,7 +18,7 @@ Valid GSD subagent types (use exact names — do not fall back to 'general-purpo
 ```bash
 INIT=$(gsd-sdk query init.milestone-op)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-AGENT_SKILLS_CHECKER=$(gsd-sdk query agent-skills gsd-integration-checker 2>/dev/null)
+AGENT_SKILLS_CHECKER=$(gsd-sdk query agent-skills gsd-integration-checker)
 ```
 
 Extract from init JSON: `milestone_version`, `milestone_name`, `phase_count`, `completed_phases`, `commit_docs`.

get-shit-done/workflows/complete-milestone.md

@@ -40,10 +40,8 @@ When a milestone completes:
 <step name="pre_close_artifact_audit">
 Before proceeding with milestone close, run the comprehensive open artifact audit.
 
-`audit-open` is not registered on `gsd-sdk query` yet; use the installed CJS CLI:
-
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" audit-open 2>/dev/null
+gsd-sdk query audit-open
 ```
 
 If the output contains open items (any section with count > 0):
@@ -59,7 +57,7 @@ These items are open. Choose an action:
 ```
 
 If user chooses [A] (Acknowledge):
-1. Re-run `audit-open --json` to get structured data
+1. Re-run `gsd-sdk query audit-open --json` to get structured data
 2. Write acknowledged items to STATE.md under `## Deferred Items` section:
    ```markdown
    ## Deferred Items
@@ -78,7 +76,7 @@ If user chooses [A] (Acknowledge):
 
 If output shows all clear (no open items): print `All artifact types clear.` and proceed.
 
-SECURITY: Audit JSON output is structured data from `audit-open` (gsd-tools.cjs) — validated and sanitized at source. When writing to STATE.md, item slugs and descriptions are sanitized via `sanitizeForDisplay()` before inclusion. Never inject raw user-supplied content into STATE.md without sanitization.
+SECURITY: Audit JSON output is structured data from the `audit-open` query handler (same JSON contract as legacy `gsd-tools.cjs audit-open`) — validated and sanitized at source. When writing to STATE.md, item slugs and descriptions are sanitized via `sanitizeForDisplay()` before inclusion. Never inject raw user-supplied content into STATE.md without sanitization.
 </step>
 
 <step name="verify_readiness">

get-shit-done/workflows/diagnose-issues.md

@@ -87,7 +87,7 @@ This runs in parallel - all gaps investigated simultaneously.
 **Load agent skills:**
 
 ```bash
-AGENT_SKILLS_DEBUGGER=$(gsd-sdk query agent-skills gsd-debugger 2>/dev/null)
+AGENT_SKILLS_DEBUGGER=$(gsd-sdk query agent-skills gsd-debugger)
 EXPECTED_BASE=$(git rev-parse HEAD)
 ```
 

get-shit-done/workflows/discuss-phase-assumptions.md

@@ -66,7 +66,7 @@ Phase number from argument (required).
 ```bash
 INIT=$(gsd-sdk query init.phase-op "${PHASE}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-AGENT_SKILLS_ANALYZER=$(gsd-sdk query agent-skills gsd-assumptions-analyzer 2>/dev/null)
+AGENT_SKILLS_ANALYZER=$(gsd-sdk query agent-skills gsd-assumptions-analyzer)
 ```
 
 Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`,
@@ -619,24 +619,23 @@ Check for auto-advance trigger:
 2. Sync chain flag:
    ```bash
    if [[ ! "$ARGUMENTS" =~ --auto ]]; then
-     gsd-sdk query config-set workflow._auto_chain_active false 2>/dev/null
+     gsd-sdk query config-set workflow._auto_chain_active false || true
    fi
    ```
-3. Read chain flag and user preference:
+3. Read consolidated auto-mode (`active` = chain flag OR user preference):
    ```bash
-   AUTO_CHAIN=$(gsd-sdk query config-get workflow._auto_chain_active 2>/dev/null || echo "false")
-   AUTO_CFG=$(gsd-sdk query config-get workflow.auto_advance 2>/dev/null || echo "false")
+   AUTO_MODE=$(gsd-sdk query check auto-mode --pick active 2>/dev/null || echo "false")
    ```
 
-**If `--auto` flag present AND `AUTO_CHAIN` is not true:**
+**If `--auto` flag present AND `AUTO_MODE` is not true:**
 ```bash
 gsd-sdk query config-set workflow._auto_chain_active true
 ```
 
-**If `--auto` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true:**
+**If `--auto` flag present OR `AUTO_MODE` is true:**
 
 Display banner:
-```
+```text
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  GSD ► AUTO-ADVANCING TO PLAN
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

get-shit-done/workflows/discuss-phase/modes/advisor.md

@@ -0,0 +1,173 @@
+# Advisor mode — research-backed comparison tables
+
+> **Lazy-loaded and gated.** The parent `workflows/discuss-phase.md` Reads
+> this file ONLY when `ADVISOR_MODE` is true (i.e., when
+> `$HOME/.claude/get-shit-done/USER-PROFILE.md` exists). Skip the Read
+> entirely when no profile is present — that's the inverse of the
+> `--advisor` flag from #2174 (don't pay the cost when unused).
+
+## Activation
+
+```bash
+PROFILE_PATH="$HOME/.claude/get-shit-done/USER-PROFILE.md"
+if [ -f "$PROFILE_PATH" ]; then
+  ADVISOR_MODE=true
+else
+  ADVISOR_MODE=false
+fi
+```
+
+If `ADVISOR_MODE` is false, do **not** Read this file — proceed with the
+standard `default.md` discussion flow.
+
+## Calibration tier
+
+Resolve `vendor_philosophy` calibration tier:
+1. **Priority 1:** Read `config.json` > `preferences.vendor_philosophy`
+   (project-level override)
+2. **Priority 2:** Read USER-PROFILE.md `Vendor Choices/Philosophy` rating
+   (global)
+3. **Priority 3:** Default to `"standard"` if neither has a value or value
+   is `UNSCORED`
+
+Map to calibration tier:
+- `conservative` OR `thorough-evaluator` → `full_maturity`
+- `opinionated` → `minimal_decisive`
+- `pragmatic-fast` OR any other value OR empty → `standard`
+
+Resolve advisor model:
+```bash
+ADVISOR_MODEL=$(gsd-sdk query resolve-model gsd-advisor-researcher --raw)
+```
+
+## Non-technical owner detection
+
+Read USER-PROFILE.md and check for product-owner signals:
+
+```bash
+PROFILE_CONTENT=$(cat "$HOME/.claude/get-shit-done/USER-PROFILE.md" 2>/dev/null || true)
+```
+
+Set `NON_TECHNICAL_OWNER = true` if ANY of the following are present:
+- `learning_style: guided`
+- The word `jargon` appears in a `frustration_triggers` section
+- `explanation_depth: practical-detailed` (without a technical modifier)
+- `explanation_depth: high-level`
+
+**Tie-breaker / precedence (when signals conflict):**
+1. An explicit `technical_background: true` (or any `explanation_depth` value
+   tagged with a technical modifier such as `practical-detailed:technical`)
+   **overrides** all inferred non-technical signals — set
+   `NON_TECHNICAL_OWNER = false`.
+2. Otherwise, ANY single matching signal is sufficient to set
+   `NON_TECHNICAL_OWNER = true` (signals are OR-aggregated, not weighted).
+3. Contradictory `explanation_depth` values: the most recent entry wins.
+
+Log the resolved value and the matched/overriding signal so the user can
+audit why a given framing was used.
+
+When `NON_TECHNICAL_OWNER` is true, reframe gray area labels and
+descriptions in product-outcome language before presenting them. Preserve
+the same underlying decision — only change the framing:
+
+- Technical implementation term → outcome the user will experience
+  - "Token architecture" → "Color system: which approach prevents the dark theme from flashing white on open"
+  - "CSS variable strategy" → "Theme colors: how your brand colors stay consistent in both light and dark mode"
+  - "Component API surface area" → "How the building blocks connect: how tightly coupled should these parts be"
+  - "Caching strategy: SWR vs React Query" → "Loading speed: should screens show saved data right away or wait for fresh data"
+
+This reframing applies to:
+1. Gray area labels and descriptions in `present_gray_areas`
+2. Advisor research rationale rewrites in the synthesis step below
+
+## advisor_research step
+
+After the user selects gray areas in `present_gray_areas`, spawn parallel
+research agents.
+
+1. Display brief status: `Researching {N} areas...`
+
+2. For EACH user-selected gray area, spawn a `Task()` in parallel:
+
+   ```
+   Task(
+     prompt="First, read @~/.claude/agents/gsd-advisor-researcher.md for your role and instructions.
+
+     <gray_area>{area_name}: {area_description from gray area identification}</gray_area>
+     <phase_context>{phase_goal and description from ROADMAP.md}</phase_context>
+     <project_context>{project name and brief description from PROJECT.md}</project_context>
+     <calibration_tier>{resolved calibration tier: full_maturity | standard | minimal_decisive}</calibration_tier>
+
+     Research this gray area and return a structured comparison table with rationale.
+     ${AGENT_SKILLS_ADVISOR}",
+     subagent_type="general-purpose",
+     model="{ADVISOR_MODEL}",
+     description="Research: {area_name}"
+   )
+   ```
+
+   All `Task()` calls spawn simultaneously — do NOT wait for one before
+   starting the next.
+
+3. After ALL agents return, **synthesize results** before presenting:
+
+   For each agent's return:
+   a. Parse the markdown comparison table and rationale paragraph
+   b. Verify all 5 columns present (Option | Pros | Cons | Complexity | Recommendation) — fill any missing columns rather than showing broken table
+   c. Verify option count matches calibration tier:
+      - `full_maturity`: 3-5 options acceptable
+      - `standard`: 2-4 options acceptable
+      - `minimal_decisive`: 1-2 options acceptable
+      If agent returned too many, trim least viable. If too few, accept as-is.
+   d. Rewrite rationale paragraph to weave in project context and ongoing discussion context that the agent did not have access to
+   e. If agent returned only 1 option, convert from table format to direct recommendation: "Standard approach for {area}: {option}. {rationale}"
+   f. **If `NON_TECHNICAL_OWNER` is true:** apply a plain language rewrite to the rationale paragraph. Replace implementation-level terms with outcome descriptions the user can reason about without technical context. The Recommendation column value and the table structure remain intact. Do not remove detail; translate it. Example: "SWR uses stale-while-revalidate to serve cached responses immediately" → "This approach shows you something right away, then quietly updates in the background — users see data instantly."
+
+4. Store synthesized tables for use in `discuss_areas` (table-first flow).
+
+## discuss_areas (advisor table-first flow)
+
+For each selected area:
+
+1. **Present the synthesized comparison table + rationale paragraph** (from
+   `advisor_research`)
+
+2. **Use AskUserQuestion** (or text-mode equivalent if `--text` overlay):
+   - header: `{area_name}`
+   - question: `Which approach for {area_name}?`
+   - options: extract from the table's Option column (AskUserQuestion adds
+     "Other" automatically)
+
+3. **Record the user's selection:**
+   - If user picks from table options → record as locked decision for that
+     area
+   - If user picks "Other" → receive their input, reflect it back for
+     confirmation, record
+
+4. **Thinking partner (conditional):** same rule as default mode — if
+   `features.thinking_partner` is enabled and tradeoff signals are
+   detected, offer a 3-5 bullet analysis before locking in.
+
+5. **After recording pick, decide whether follow-up questions are needed:**
+   - If the pick has ambiguity that would affect downstream planning →
+     ask 1-2 targeted follow-up questions using AskUserQuestion
+   - If the pick is clear and self-contained → move to next area
+   - Do NOT ask the standard 4 questions — the table already provided the
+     context
+
+6. **After all areas processed:**
+   - header: "Done"
+   - question: "That covers [list areas]. Ready to create context?"
+   - options: "Create context" / "Revisit an area"
+
+## Scope creep handling (advisor mode)
+
+If user mentions something outside the phase domain:
+```
+"[Feature] sounds like a new capability — that belongs in its own phase.
+I'll note it as a deferred idea.
+
+Back to [current area]: [return to current question]"
+```
+
+Track deferred ideas internally.

get-shit-done/workflows/discuss-phase/modes/all.md

@@ -0,0 +1,28 @@
+# --all mode — auto-select ALL gray areas, discuss interactively
+
+> **Lazy-loaded.** Read this file from `workflows/discuss-phase.md` when
+> `--all` is present in `$ARGUMENTS`. Behavior overlays the default mode.
+
+## Effect
+
+- In `present_gray_areas`: auto-select ALL gray areas without asking the user
+  (skips the AskUserQuestion area-selection step).
+- Discussion for each area proceeds **fully interactively** — the user drives
+  every question for every area (use the default-mode `discuss_areas` flow).
+- Does NOT auto-advance to plan-phase afterward — use `--chain` or `--auto`
+  if you want auto-advance.
+- Log: `[--all] Auto-selected all gray areas: [list area names].`
+
+## Why this mode exists
+
+This is the "discuss everything" shortcut: skip the selection friction, keep
+full interactive control over each individual question.
+
+## Combination rules
+
+- `--all --auto`: `--auto` wins for the discussion phase too (Claude picks
+  recommended answers); `--all`'s contribution is just area auto-selection.
+- `--all --chain`: areas auto-selected, discussion interactive, then
+  auto-advance to plan/execute (chain semantics).
+- `--all --batch` / `--all --text` / `--all --analyze`: layered overlays
+  apply during discussion as documented in their respective files.

get-shit-done/workflows/discuss-phase/modes/analyze.md

@@ -0,0 +1,44 @@
+# --analyze mode — trade-off tables before each question
+
+> **Lazy-loaded overlay.** Read this file from `workflows/discuss-phase.md`
+> when `--analyze` is present in `$ARGUMENTS`. Combinable with default,
+> `--all`, `--chain`, `--text`, `--batch`.
+
+## Effect
+
+Before presenting each question (or question group, in batch mode), provide
+a brief **trade-off analysis** for the decision:
+- 2-3 options with pros/cons based on codebase context and common patterns
+- A recommended approach with reasoning
+- Known pitfalls or constraints from prior phases
+
+## Example
+
+```markdown
+**Trade-off analysis: Authentication strategy**
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| Session cookies | Simple, httpOnly prevents XSS | Requires CSRF protection, sticky sessions |
+| JWT (stateless) | Scalable, no server state | Token size, revocation complexity |
+| OAuth 2.0 + PKCE | Industry standard for SPAs | More setup, redirect flow UX |
+
+💡 Recommended: OAuth 2.0 + PKCE — your app has social login in requirements (REQ-04) and this aligns with the existing NextAuth setup in `src/lib/auth.ts`.
+
+How should users authenticate?
+```
+
+This gives the user context to make informed decisions without extra
+prompting.
+
+When `--analyze` is absent, present questions directly as before (no
+trade-off table).
+
+## Sourcing the analysis
+
+- Pros/cons should reflect the codebase context loaded in `scout_codebase`
+  and any prior decisions surfaced in `load_prior_context`.
+- The recommendation must explicitly tie to project context (e.g.,
+  existing libraries, prior phase decisions, documented requirements).
+- If a related ADR or spec is referenced in CONTEXT.md `<canonical_refs>`,
+  cite it in the recommendation.

get-shit-done/workflows/discuss-phase/modes/auto.md

@@ -0,0 +1,56 @@
+# --auto mode — fully autonomous discuss-phase
+
+> **Lazy-loaded.** Read this file from `workflows/discuss-phase.md` when
+> `--auto` is present in `$ARGUMENTS`. After the discussion completes, the
+> parent's `auto_advance` step also reads `modes/chain.md` to drive the
+> auto-advance to plan-phase.
+
+## Effect across steps
+
+- **`check_existing`**: if CONTEXT.md exists, auto-select "Update it" — load
+  existing context and continue to `analyze_phase` (matches the parent step's
+  documented `--auto` branch). If no context exists, continue without
+  prompting. For interrupted checkpoints, auto-select "Resume". For existing
+  plans, auto-select "Continue and replan after". Log every decision so the
+  user can audit.
+- **`cross_reference_todos`**: fold all todos with relevance score >= 0.4
+  automatically. Log the selection.
+- **`present_gray_areas`**: auto-select ALL gray areas. Log:
+  `[--auto] Selected all gray areas: [list area names].`
+- **`discuss_areas`**: for each discussion question, choose the recommended
+  option (first option, or the one explicitly marked "recommended") **without
+  using AskUserQuestion**. Skip interactive prompts entirely. Log each
+  auto-selected choice inline so the user can review decisions in the
+  context file:
+  ```
+  [auto] [Area] — Q: "[question text]" → Selected: "[chosen option]" (recommended default)
+  ```
+- After all areas are auto-resolved, skip the "Explore more gray areas"
+  prompt and proceed directly to `write_context`.
+- After `write_context`, **auto-advance** to plan-phase via `modes/chain.md`.
+
+## CRITICAL — Auto-mode pass cap
+
+In `--auto` mode, the discuss step MUST complete in a **single pass**. After
+writing CONTEXT.md once, you are DONE — proceed immediately to
+`write_context` and then auto_advance. Do NOT re-read your own CONTEXT.md to
+find "gaps", "undefined types", or "missing decisions" and run additional
+passes. This creates a self-feeding loop where each pass generates references
+that the next pass treats as gaps, consuming unbounded time and resources.
+
+Check the pass cap from config:
+```bash
+MAX_PASSES=$(gsd-sdk query config-get workflow.max_discuss_passes 2>/dev/null || echo "3")
+```
+
+If you have already written and committed CONTEXT.md, the discuss step is
+complete. Move on.
+
+## Combination rules
+
+- `--auto --text` / `--auto --batch`: text/batch overlays are no-ops in
+  auto mode (no user prompts to render).
+- `--auto --analyze`: trade-off tables can still be logged for the audit
+  trail; selection still uses the recommended option.
+- `--auto --power`: `--power` wins (power mode generates files for offline
+  answering — incompatible with autonomous selection).

get-shit-done/workflows/discuss-phase/modes/batch.md

@@ -0,0 +1,52 @@
+# --batch mode — grouped question batches
+
+> **Lazy-loaded overlay.** Read this file from `workflows/discuss-phase.md`
+> when `--batch` is present in `$ARGUMENTS`. Combinable with default,
+> `--all`, `--chain`, `--text`, `--analyze`.
+
+## Argument parsing
+
+Parse optional `--batch` from `$ARGUMENTS`:
+- Accept `--batch`, `--batch=N`, or `--batch N`
+- Default to **4 questions per batch** when no number is provided
+- Clamp explicit sizes to **2–5** so a batch stays answerable
+- If `--batch` is absent, keep the existing one-question-at-a-time flow
+  (default mode).
+
+## Effect on discuss_areas
+
+`--batch` mode: ask **2–5 numbered questions in one plain-text turn** per
+area, instead of the default 4 single-question AskUserQuestion turns.
+
+- Group closely related questions for the current area into a single
+  message
+- Keep each question concrete and answerable in one reply
+- When options are helpful, include short inline choices per question
+  rather than a separate AskUserQuestion for every item
+- After the user replies, reflect back the captured decisions, note any
+  unanswered items, and ask only the minimum follow-up needed before
+  moving on
+- Preserve adaptiveness between batches: use the full set of answers to
+  decide the next batch or whether the area is sufficiently clear
+
+## Philosophy
+
+Stay adaptive, but let the user choose the pacing.
+- Default mode: 4 single-question turns, then check whether to continue
+- `--batch` mode: 1 grouped turn with 2–5 numbered questions, then check
+  whether to continue
+
+Each answer set should reveal the next question or next batch.
+
+## Example batch
+
+```
+Authentication — please answer 1–4:
+
+1. Which auth strategy?  (a) Session cookies  (b) JWT  (c) OAuth 2.0 + PKCE
+2. Where do tokens live?  (a) httpOnly cookie  (b) localStorage  (c) memory only
+3. Session lifetime?       (a) 1h  (b) 24h  (c) 30d  (d) configurable
+4. Account recovery?       (a) email reset  (b) magic link  (c) both
+
+Reply with your choices (e.g. "1c, 2a, 3b, 4c") or describe in your own words.
+```

get-shit-done/workflows/discuss-phase/modes/chain.md

@@ -0,0 +1,97 @@
+# --chain mode — interactive discuss, then auto-advance
+
+> **Lazy-loaded.** Read this file from `workflows/discuss-phase.md` when
+> `--chain` is present in `$ARGUMENTS`, or when the parent's `auto_advance`
+> step needs to dispatch to plan-phase under `--auto`.
+
+## Effect
+
+- Discussion is **fully interactive** — questions, gray-area selection, and
+  follow-ups behave exactly the same as default mode.
+- After discussion completes, **auto-advance to plan-phase → execute-phase**
+  (same downstream behavior as `--auto`).
+- This is the middle ground: the user controls the discuss decisions, then
+  plan and execute run autonomously.
+
+## auto_advance step (executed by the parent file)
+
+1. Parse `--auto` and `--chain` flags from `$ARGUMENTS`. **Note:** `--all`
+   is NOT an auto-advance trigger — it only affects area selection. A
+   session with `--all` but without `--auto` or `--chain` returns to manual
+   next-steps after discussion completes.
+
+2. **Sync chain flag with intent** — if user invoked manually (no `--auto`
+   and no `--chain`), clear the ephemeral chain flag from any previous
+   interrupted `--auto` chain. This does NOT touch `workflow.auto_advance`
+   (the user's persistent settings preference):
+   ```bash
+   if [[ ! "$ARGUMENTS" =~ --auto ]] && [[ ! "$ARGUMENTS" =~ --chain ]]; then
+     gsd-sdk query config-set workflow._auto_chain_active false || true
+   fi
+   ```
+
+3. Read consolidated auto-mode (`active` = chain flag OR user preference):
+   ```bash
+   AUTO_MODE=$(gsd-sdk query check auto-mode --pick active 2>/dev/null || echo "false")
+   ```
+
+4. **If `--auto` or `--chain` flag present AND `AUTO_MODE` is not true:**
+   Persist chain flag to config (handles direct usage without new-project):
+   ```bash
+   gsd-sdk query config-set workflow._auto_chain_active true
+   ```
+
+5. **If `--auto` flag present OR `--chain` flag present OR `AUTO_MODE` is
+   true:** display banner and launch plan-phase.
+
+   Banner:
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    GSD ► AUTO-ADVANCING TO PLAN
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   Context captured. Launching plan-phase...
+   ```
+
+   Launch plan-phase using the Skill tool to avoid nested Task sessions
+   (which cause runtime freezes due to deep agent nesting — see #686):
+   ```
+   Skill(skill="gsd-plan-phase", args="${PHASE} --auto ${GSD_WS}")
+   ```
+
+   This keeps the auto-advance chain flat — discuss, plan, and execute all
+   run at the same nesting level rather than spawning increasingly deep
+   Task agents.
+
+6. **Handle plan-phase return:**
+
+   - **PHASE COMPLETE** → Full chain succeeded. Display:
+     ```
+     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+      GSD ► PHASE ${PHASE} COMPLETE
+     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+     Auto-advance pipeline finished: discuss → plan → execute
+
+     /clear then:
+
+     Next: /gsd-discuss-phase ${NEXT_PHASE} ${WAS_CHAIN ? "--chain" : "--auto"} ${GSD_WS}
+     ```
+   - **PLANNING COMPLETE** → Planning done, execution didn't complete:
+     ```
+     Auto-advance partial: Planning complete, execution did not finish.
+     Continue: /gsd-execute-phase ${PHASE} ${GSD_WS}
+     ```
+   - **PLANNING INCONCLUSIVE / CHECKPOINT** → Stop chain:
+     ```
+     Auto-advance stopped: Planning needs input.
+     Continue: /gsd-plan-phase ${PHASE} ${GSD_WS}
+     ```
+   - **GAPS FOUND** → Stop chain:
+     ```
+     Auto-advance stopped: Gaps found during execution.
+     Continue: /gsd-plan-phase ${PHASE} --gaps ${GSD_WS}
+     ```
+
+7. **If none of `--auto`, `--chain`, nor config enabled:** route to
+   `confirm_creation` step (existing behavior — show manual next steps).

get-shit-done/workflows/discuss-phase/modes/default.md

@@ -0,0 +1,141 @@
+# Default mode — interactive discuss-phase
+
+> **Lazy-loaded.** Read this file from `workflows/discuss-phase.md` when no
+> mode flag is present (the baseline interactive flow). When `--text`,
+> `--batch`, or `--analyze` is also present, layer the corresponding overlay
+> file from this directory on top of the rules below.
+
+This document defines `discuss_areas` for the default flow. The shared steps
+that come before (`initialize`, `check_blocking_antipatterns`, `check_spec`,
+`check_existing`, `load_prior_context`, `cross_reference_todos`,
+`scout_codebase`, `analyze_phase`, `present_gray_areas`) live in the parent
+file and run for every mode.
+
+## discuss_areas (default, interactive)
+
+For each selected area, conduct a focused discussion loop.
+
+**Research-before-questions mode:** Check if `workflow.research_before_questions` is enabled in config (from init context or `.planning/config.json`). When enabled, before presenting questions for each area:
+1. Do a brief web search for best practices related to the area topic
+2. Summarize the top findings in 2-3 bullet points
+3. Present the research alongside the question so the user can make a more informed decision
+
+Example with research enabled:
+```text
+Let's talk about [Authentication Strategy].
+
+📊 Best practices research:
+• OAuth 2.0 + PKCE is the current standard for SPAs (replaces implicit flow)
+• Session tokens with httpOnly cookies preferred over localStorage for XSS protection
+• Consider passkey/WebAuthn support — adoption is accelerating in 2025-2026
+
+With that context: How should users authenticate?
+```
+
+When disabled (default), skip the research and present questions directly as before.
+
+**Philosophy:** stay adaptive. Default flow is 4 single-question turns, then
+check whether to continue. Each answer should reveal the next question.
+
+**For each area:**
+
+1. **Announce the area:**
+   ```text
+   Let's talk about [Area].
+   ```
+
+2. **Ask 4 questions using AskUserQuestion:**
+   - header: "[Area]" (max 12 chars — abbreviate if needed)
+   - question: Specific decision for this area
+   - options: 2-3 concrete choices (AskUserQuestion adds "Other" automatically), with the recommended choice highlighted and brief explanation why
+   - **Annotate options with code context** when relevant:
+     ```text
+     "How should posts be displayed?"
+     - Cards (reuses existing Card component — consistent with Messages)
+     - List (simpler, would be a new pattern)
+     - Timeline (needs new Timeline component — none exists yet)
+     ```
+   - Include "You decide" as an option when reasonable — captures Claude discretion
+   - **Context7 for library choices:** When a gray area involves library selection (e.g., "magic links" → query next-auth docs) or API approach decisions, use `mcp__context7__*` tools to fetch current documentation and inform the options. Don't use Context7 for every question — only when library-specific knowledge improves the options.
+
+3. **After the current set of questions, check:**
+   - header: "[Area]" (max 12 chars)
+   - question: "More questions about [area], or move to next? (Remaining: [list other unvisited areas])"
+   - options: "More questions" / "Next area"
+
+   When building the question text, list the remaining unvisited areas so the user knows what's ahead. For example: "More questions about Layout, or move to next? (Remaining: Loading behavior, Content ordering)"
+
+   If "More questions" → ask another 4 single questions, then check again
+   If "Next area" → proceed to next selected area
+   If "Other" (free text) → interpret intent: continuation phrases ("chat more", "keep going", "yes", "more") map to "More questions"; advancement phrases ("done", "move on", "next", "skip") map to "Next area". If ambiguous, ask: "Continue with more questions about [area], or move to the next area?"
+
+4. **After all initially-selected areas complete:**
+   - Summarize what was captured from the discussion so far
+   - AskUserQuestion:
+     - header: "Done"
+     - question: "We've discussed [list areas]. Which gray areas remain unclear?"
+     - options: "Explore more gray areas" / "I'm ready for context"
+   - If "Explore more gray areas":
+     - Identify 2-4 additional gray areas based on what was learned
+     - Return to present_gray_areas logic with these new areas
+     - Loop: discuss new areas, then prompt again
+   - If "I'm ready for context": Proceed to write_context
+
+**Canonical ref accumulation during discussion:**
+When the user references a doc, spec, or ADR during any answer — e.g., "read adr-014", "check the MCP spec", "per browse-spec.md" — immediately:
+1. Read the referenced doc (or confirm it exists)
+2. Add it to the canonical refs accumulator with full relative path
+3. Use what you learned from the doc to inform subsequent questions
+
+These user-referenced docs are often MORE important than ROADMAP.md refs because they represent docs the user specifically wants downstream agents to follow. Never drop them.
+
+**Question design:**
+- Options should be concrete, not abstract ("Cards" not "Option A")
+- Each answer should inform the next question or next batch
+- If user picks "Other" to provide freeform input (e.g., "let me describe it", "something else", or an open-ended reply), ask your follow-up as plain text — NOT another AskUserQuestion. Wait for them to type at the normal prompt, then reflect their input back and confirm before resuming AskUserQuestion or the next numbered batch.
+
+**Thinking partner (conditional):**
+If `features.thinking_partner` is enabled in config, check the user's answer for tradeoff signals
+(see `references/thinking-partner.md` for signal list). If tradeoff detected:
+
+```text
+I notice competing priorities here — {option_A} optimizes for {goal_A} while {option_B} optimizes for {goal_B}.
+
+Want me to think through the tradeoffs before we lock this in?
+[Yes, analyze] / [No, decision made]
+```
+
+If yes: provide 3-5 bullet analysis (what each optimizes/sacrifices, alignment with PROJECT.md goals, recommendation). Then return to normal flow.
+
+**Scope creep handling:**
+If user mentions something outside the phase domain:
+```text
+"[Feature] sounds like a new capability — that belongs in its own phase.
+I'll note it as a deferred idea.
+
+Back to [current area]: [return to current question]"
+```
+
+Track deferred ideas internally.
+
+**Incremental checkpoint — save after each area completes:**
+
+After each area is resolved (user says "Next area"), immediately write a checkpoint file with all decisions captured so far. This prevents data loss if the session is interrupted mid-discussion.
+
+**Checkpoint file:** `${phase_dir}/${padded_phase}-DISCUSS-CHECKPOINT.json`
+
+Schema: read `workflows/discuss-phase/templates/checkpoint.json` for the
+canonical structure — copy it and substitute the live values.
+
+**On session resume:** Handled in the parent's `check_existing` step. After
+`write_context` completes successfully, the parent's `git_commit` step
+deletes the checkpoint.
+
+**Track discussion log data internally:**
+For each question asked, accumulate:
+- Area name
+- All options presented (label + description)
+- Which option the user selected (or their free-text response)
+- Any follow-up notes or clarifications the user provided
+
+This data is used to generate DISCUSSION-LOG.md in the parent's `git_commit` step.

get-shit-done/workflows/discuss-phase/modes/power.md

@@ -0,0 +1,44 @@
+# --power mode — bulk question generation, async answering
+
+> **Lazy-loaded.** Read this file from `workflows/discuss-phase.md` when
+> `--power` is present in `$ARGUMENTS`. The full step-by-step instructions
+> live in the existing `discuss-phase-power.md` workflow file (kept stable
+> at its original path so installed `@`-references continue to resolve).
+
+## Dispatch
+
+```
+Read @~/.claude/get-shit-done/workflows/discuss-phase-power.md
+```
+
+Execute it end-to-end. Do not continue with the standard interactive steps.
+
+## Summary of flow
+
+The power user mode generates ALL questions upfront into machine-readable
+and human-friendly files, then waits for the user to answer at their own
+pace before processing all answers in a single pass.
+
+1. Run the same phase analysis (gray area identification) as standard mode
+2. Write all questions to
+   `{phase_dir}/{padded_phase}-QUESTIONS.json` and
+   `{phase_dir}/{padded_phase}-QUESTIONS.html`
+3. Notify user with file paths and wait for a "refresh" or "finalize"
+   command
+4. On "refresh": read the JSON, process answered questions, update stats
+   and HTML
+5. On "finalize": read all answers from JSON, generate CONTEXT.md in the
+   standard format
+
+## When to use
+
+Large phases with many gray areas, or when users prefer to answer
+questions offline / asynchronously rather than interactively in the chat
+session.
+
+## Combination rules
+
+- `--power --auto`: power wins. Power mode is incompatible with
+  autonomous selection — its purpose is offline answering.
+- `--power --chain`: after the power-mode finalize step writes
+  CONTEXT.md, the chain auto-advance still applies (Read `chain.md`).

get-shit-done/workflows/discuss-phase/modes/text.md

@@ -0,0 +1,55 @@
+# --text mode — plain-text overlay (no AskUserQuestion)
+
+> **Lazy-loaded overlay.** Read this file from `workflows/discuss-phase.md`
+> when `--text` is present in `$ARGUMENTS`, OR when
+> `workflow.text_mode: true` is set in config (e.g., per-project default).
+
+## Effect
+
+When text mode is active, **do not use AskUserQuestion at all**. Instead,
+present every question as a plain-text numbered list and ask the user to
+type their choice number. Free-text input maps to the "Other" branch of
+the equivalent AskUserQuestion call.
+
+This is required for Claude Code remote sessions (`/rc` mode) where the
+Claude App cannot forward TUI menu selections back to the host.
+
+## Activation
+
+- Per-session: pass `--text` flag to any command (e.g.,
+  `/gsd-discuss-phase --text`)
+- Per-project: `gsd-sdk query config-set workflow.text_mode true`
+
+Text mode applies to ALL workflows in the session, not just discuss-phase.
+
+## Question rendering
+
+Replace this:
+```text
+AskUserQuestion(
+  header="Layout",
+  question="How should posts be displayed?",
+  options=["Cards", "List", "Timeline"]
+)
+```
+
+With this:
+```text
+Layout — How should posts be displayed?
+  1. Cards
+  2. List
+  3. Timeline
+  4. Other (type freeform)
+
+Reply with a number, or describe your preference.
+```
+
+Wait for the user's reply at the normal prompt. Parse:
+- Numeric reply → mapped to that option
+- Free text → treated as "Other" — reflect it back, confirm, then proceed
+
+## Empty-answer handling
+
+The same answer-validation rules from the parent file apply: empty
+responses trigger one retry, then a clarifying question. Do not proceed
+with empty input.

get-shit-done/workflows/discuss-phase/templates/checkpoint.json

@@ -0,0 +1,18 @@
+{
+  "phase": "{PHASE_NUM}",
+  "phase_name": "{phase_name}",
+  "timestamp": "{ISO timestamp}",
+  "areas_completed": ["Area 1", "Area 2"],
+  "areas_remaining": ["Area 3", "Area 4"],
+  "decisions": {
+    "Area 1": [
+      {"question": "...", "answer": "...", "options_presented": ["..."]},
+      {"question": "...", "answer": "...", "options_presented": ["..."]}
+    ],
+    "Area 2": [
+      {"question": "...", "answer": "...", "options_presented": ["..."]}
+    ]
+  },
+  "deferred_ideas": ["..."],
+  "canonical_refs": ["..."]
+}

get-shit-done/workflows/discuss-phase/templates/context.md

@@ -0,0 +1,136 @@
+# CONTEXT.md template — for discuss-phase write_context step
+
+> **Lazy-loaded.** Read this file only inside the `write_context` step of
+> `workflows/discuss-phase.md`, immediately before writing
+> `${phase_dir}/${padded_phase}-CONTEXT.md`. Do not put a reference to this
+> file in `<required_reading>` — that defeats the progressive-disclosure
+> savings introduced by issue #2551.
+
+## Variable substitutions
+
+The caller substitutes:
+- `[X]` → phase number
+- `[Name]` → phase name
+- `[date]` → ISO date when context was gathered
+- `${padded_phase}` → zero-padded phase number (e.g., `07`, `15`)
+- `{N}` → counts (requirements, etc.)
+
+## Conditional sections
+
+- **`<spec_lock>`** — include only when `spec_loaded = true` (a `*-SPEC.md`
+  was found by `check_spec`). Otherwise omit the entire `<spec_lock>` block.
+- **Folded Todos / Reviewed Todos** — include subsections only when the
+  `cross_reference_todos` step folded or reviewed at least one todo.
+
+## Template body
+
+```markdown
+# Phase [X]: [Name] - Context
+
+**Gathered:** [date]
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+[Clear statement of what this phase delivers — the scope anchor]
+
+</domain>
+
+[If spec_loaded = true, insert this section:]
+<spec_lock>
+## Requirements (locked via SPEC.md)
+
+**{N} requirements are locked.** See `{padded_phase}-SPEC.md` for full requirements, boundaries, and acceptance criteria.
+
+Downstream agents MUST read `{padded_phase}-SPEC.md` before planning or implementing. Requirements are not duplicated here.
+
+**In scope (from SPEC.md):** [copy the "In scope" bullet list from SPEC.md Boundaries]
+**Out of scope (from SPEC.md):** [copy the "Out of scope" bullet list from SPEC.md Boundaries]
+
+</spec_lock>
+
+<decisions>
+## Implementation Decisions
+
+### [Category 1 that was discussed]
+- **D-01:** [Decision or preference captured]
+- **D-02:** [Another decision if applicable]
+
+### [Category 2 that was discussed]
+- **D-03:** [Decision or preference captured]
+
+### Claude's Discretion
+[Areas where user said "you decide" — note that Claude has flexibility here]
+
+### Folded Todos
+[If any todos were folded into scope from the cross_reference_todos step, list them here.
+Each entry should include the todo title, original problem, and how it fits this phase's scope.
+If no todos were folded: omit this subsection entirely.]
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+[MANDATORY section. Write the FULL accumulated canonical refs list here.
+Sources: ROADMAP.md refs + REQUIREMENTS.md refs + user-referenced docs during
+discussion + any docs discovered during codebase scout. Group by topic area.
+Every entry needs a full relative path — not just a name.]
+
+### [Topic area 1]
+- `path/to/adr-or-spec.md` — [What it decides/defines that's relevant]
+- `path/to/doc.md` §N — [Specific section reference]
+
+### [Topic area 2]
+- `path/to/feature-doc.md` — [What this doc defines]
+
+[If no external specs: "No external specs — requirements fully captured in decisions above"]
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- [Component/hook/utility]: [How it could be used in this phase]
+
+### Established Patterns
+- [Pattern]: [How it constrains/enables this phase]
+
+### Integration Points
+- [Where new code connects to existing system]
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+[Any particular references, examples, or "I want it like X" moments from discussion]
+
+[If none: "No specific requirements — open to standard approaches"]
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+[Ideas that came up but belong in other phases. Don't lose them.]
+
+### Reviewed Todos (not folded)
+[If any todos were reviewed in cross_reference_todos but not folded into scope,
+list them here so future phases know they were considered.
+Each entry: todo title + reason it was deferred (out of scope, belongs in Phase Y, etc.)
+If no reviewed-but-deferred todos: omit this subsection entirely.]
+
+[If none: "None — discussion stayed within phase scope"]
+
+</deferred>
+
+---
+
+*Phase: [X]-[Name]*
+*Context gathered: [date]*
+```

get-shit-done/workflows/discuss-phase/templates/discussion-log.md

@@ -0,0 +1,50 @@
+# DISCUSSION-LOG.md template — for discuss-phase git_commit step
+
+> **Lazy-loaded.** Read this file only inside the `git_commit` step of
+> `workflows/discuss-phase.md`, immediately before writing
+> `${phase_dir}/${padded_phase}-DISCUSSION-LOG.md`.
+
+## Purpose
+
+Audit trail for human review (compliance, learning, retrospectives). NOT
+consumed by downstream agents — those read CONTEXT.md only.
+
+## Template body
+
+```markdown
+# Phase [X]: [Name] - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** [ISO date]
+**Phase:** [phase number]-[phase name]
+**Areas discussed:** [comma-separated list]
+
+---
+
+[For each gray area discussed:]
+
+## [Area Name]
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| [Option 1] | [Description from AskUserQuestion] | |
+| [Option 2] | [Description] | ✓ |
+| [Option 3] | [Description] | |
+
+**User's choice:** [Selected option or free-text response]
+**Notes:** [Any clarifications, follow-up context, or rationale the user provided]
+
+---
+
+[Repeat for each area]
+
+## Claude's Discretion
+
+[List areas where user said "you decide" or deferred to Claude]
+
+## Deferred Ideas
+
+[Ideas mentioned during discussion that were noted for future phases]
+```

get-shit-done/workflows/docs-update.md

@@ -16,7 +16,7 @@ Load docs-update context:
 ```bash
 INIT=$(gsd-sdk query docs-init)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-AGENT_SKILLS=$(gsd-sdk query agent-skills gsd-doc-writer 2>/dev/null)
+AGENT_SKILLS=$(gsd-sdk query agent-skills gsd-doc-writer)
 ```
 
 Extract from init JSON:

get-shit-done/workflows/execute-phase.md

@@ -69,11 +69,13 @@ Load all context in one call:
 ```bash
 INIT=$(gsd-sdk query init.execute-phase "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-AGENT_SKILLS=$(gsd-sdk query agent-skills gsd-executor 2>/dev/null)
+AGENT_SKILLS=$(gsd-sdk query agent-skills gsd-executor)
 ```
 
 Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `phase_req_ids`, `response_language`.
 
+**Model resolution:** If `executor_model` is `"inherit"`, omit the `model=` parameter from all `Task()` calls — do NOT pass `model="inherit"` to Task. Omitting the `model=` parameter causes Claude Code to inherit the current orchestrator model automatically. Only set `model=` when `executor_model` is an explicit model name (e.g., `"claude-sonnet-4-6"`, `"claude-opus-4-7"`).
+
 **If `response_language` is set:** Include `response_language: {value}` in all spawned subagent prompts so any user-facing output stays in the configured language.
 
 Read worktree config:
@@ -128,7 +130,7 @@ inline path for each plan.
 ```bash
 # REQUIRED: prevents stale auto-chain from previous --auto runs
 if [[ ! "$ARGUMENTS" =~ --auto ]]; then
-  gsd-sdk query config-set workflow._auto_chain_active false 2>/dev/null
+  gsd-sdk query config-set workflow._auto_chain_active false || true
 fi
 ```
 </step>
@@ -334,6 +336,26 @@ CROSS_AI_TIMEOUT=$(gsd-sdk query config-get workflow.cross_ai_timeout 2>/dev/nul
 <step name="execute_waves">
 Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`, sequential if `false`.
 
+**Stream-idle-timeout prevention — checkpoint heartbeats (#2410):**
+
+Multi-plan phases can accumulate enough subagent context that the Claude API
+SSE layer terminates with `Stream idle timeout - partial response received`
+between a large tool_result and the next assistant turn (seen on Claude Code
++ Opus 4.7 at ~200K+ cache_read). To keep the stream warm, emit short
+assistant-text heartbeats — **no tool call, just a literal line** — at every
+wave and plan boundary. Each heartbeat MUST start with `[checkpoint]` so
+tooling and `/gsd-manager`'s background-completion handler can grep partial
+transcripts. `{P}/{Q}` is the phase-wide completed/total plans counter and
+increases monotonically across waves. `{status}` is `complete` (success),
+`failed` (executor error), or `checkpoint` (human-gate returned).
+
+```
+[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} starting, {wave_plan_count} plan(s), {P}/{Q} plans done
+[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} starting ({P}/{Q} plans done)
+[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} {status} ({P}/{Q} plans done)
+[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} complete, {P}/{Q} plans done ({wave_success}/{wave_plan_count} ok)
+```
+
 **For each wave:**
 
 1. **Intra-wave files_modified overlap check (BEFORE spawning):**
@@ -372,7 +394,15 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
 
 2. **Describe what's being built (BEFORE spawning):**
 
-   Read each plan's `<objective>`. Extract what's being built and why.
+   **First, emit the wave-start checkpoint heartbeat as a literal assistant-text
+   line — no tool call (#2410). Do NOT skip this even for single-plan waves; it
+   is required before any further reasoning or spawning:**
+
+   ```
+   [checkpoint] phase {PHASE_NUMBER} wave {N}/{M} starting, {wave_plan_count} plan(s), {P}/{Q} plans done
+   ```
+
+   Then read each plan's `<objective>`. Extract what's being built and why.
 
    ```
    ---
@@ -390,6 +420,13 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
 
 3. **Spawn executor agents:**
 
+   **Emit a plan-start heartbeat (literal line, no tool call) immediately before
+   each `Task()` dispatch (#2410):**
+
+   ```
+   [checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} starting ({P}/{Q} plans done)
+   ```
+
    Pass paths only — executors read files themselves with their fresh context window.
    For 200k models, this keeps orchestrator context lean (~10-15%).
    For 1M+ models (Opus 4.6, Sonnet 4.6), richer context can be passed directly.
@@ -421,7 +458,10 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
    Task(
      subagent_type="gsd-executor",
      description="Execute plan {plan_number} of phase {phase_number}",
-     model="{executor_model}",
+     # Only include model= when executor_model is an explicit model name.
+     # When executor_model is "inherit", omit this parameter entirely so
+     # Claude Code inherits the orchestrator model automatically.
+     model="{executor_model}",  # omit this line when executor_model == "inherit"
      isolation="worktree",
      prompt="
        <objective>
@@ -547,6 +587,16 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
 
 4. **Wait for all agents in wave to complete.**
 
+   **Plan-complete heartbeat (#2410):** as each executor returns (or is verified
+   via spot-check below), emit one line — `complete` advances `{P}`, `failed`
+   and `checkpoint` do not but still warm the stream:
+
+   ```
+   [checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} complete ({P}/{Q} plans done)
+   [checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} failed ({P}/{Q} plans done)
+   [checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} checkpoint ({P}/{Q} plans done)
+   ```
+
    **Completion signal fallback (Copilot and runtimes where Task() may not return):**
 
    If a spawned agent does not return a completion signal but appears to have finished
@@ -623,6 +673,21 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
          break
        }
 
+       # Post-merge deletion audit: detect bulk file deletions in merge commit (#2384)
+       # --diff-filter=D HEAD~1 HEAD shows files deleted by the merge commit itself.
+       # Exclude .planning/ — orchestrator-owned deletions there are expected (resurrections
+       # are handled below). Require ALLOW_BULK_DELETE=1 to bypass for intentional large refactors.
+       MERGE_DEL_COUNT=$(git diff --diff-filter=D --name-only HEAD~1 HEAD 2>/dev/null | grep -vc '^\.planning/' || true)
+       if [ "$MERGE_DEL_COUNT" -gt 5 ] && [ "${ALLOW_BULK_DELETE:-0}" != "1" ]; then
+         MERGE_DELETIONS=$(git diff --diff-filter=D --name-only HEAD~1 HEAD 2>/dev/null | grep -v '^\.planning/' || true)
+         echo "⚠ BLOCKED: Merge of $WT_BRANCH deleted $MERGE_DEL_COUNT files outside .planning/ — reverting to protect repository integrity (#2384)"
+         echo "$MERGE_DELETIONS"
+         echo "  If these deletions are intentional, re-run with ALLOW_BULK_DELETE=1"
+         git reset --hard HEAD~1 2>/dev/null || true
+         rm -f "$STATE_BACKUP" "$ROADMAP_BACKUP"
+         continue
+       fi
+
        # Restore orchestrator-owned files (main always wins)
        if [ -s "$STATE_BACKUP" ]; then
          cp "$STATE_BACKUP" .planning/STATE.md
@@ -634,10 +699,15 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
 
        # Detect files deleted on main but re-added by worktree merge
        # (e.g., archived phase directories that were intentionally removed)
+       # A "resurrected" file must have a deletion event in main's ancestry —
+       # brand-new files (e.g. SUMMARY.md just created by the executor) have no
+       # such history and must NOT be removed (#2501).
        DELETED_FILES=$(git diff --diff-filter=A --name-only HEAD~1 -- .planning/ 2>/dev/null || true)
        for RESURRECTED in $DELETED_FILES; do
-         # Check if this file was NOT in main's pre-merge tree
-         if ! echo "$PRE_MERGE_FILES" | grep -qxF "$RESURRECTED"; then
+         # Only delete if this file was previously tracked on main and then
+         # deliberately removed (has a deletion event in git history).
+         WAS_DELETED=$(git log --follow --diff-filter=D --name-only --format="" HEAD~1 -- "$RESURRECTED" 2>/dev/null | grep -c . || true)
+         if [ "${WAS_DELETED:-0}" -gt 0 ]; then
            git rm -f "$RESURRECTED" 2>/dev/null || true
          fi
        done
@@ -665,7 +735,19 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
        fi
 
        # Remove the worktree
-       git worktree remove "$WT" --force 2>/dev/null || true
+       if ! git worktree remove "$WT" --force; then
+         WT_NAME=$(basename "$WT")
+         if [ -f ".git/worktrees/${WT_NAME}/locked" ]; then
+           echo "⚠ Worktree $WT is locked — attempting to unlock and retry"
+           git worktree unlock "$WT" 2>/dev/null || true
+           if ! git worktree remove "$WT" --force; then
+             echo "⚠ Residual worktree at $WT — manual cleanup required after session exits:"
+             echo "    git worktree unlock \"$WT\" && git worktree remove \"$WT\" --force && git branch -D \"$WT_BRANCH\""
+           fi
+         else
+           echo "⚠ Residual worktree at $WT (remove failed) — investigate manually"
+         fi
+       fi
 
        # Delete the temporary branch
        git branch -D "$WT_BRANCH" 2>/dev/null || true
@@ -688,22 +770,29 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
    merging their work creates failures.
 
    ```bash
+   # Resolve test command: project config > Makefile > language sniff
+   TEST_CMD=$(gsd-sdk query config-get workflow.test_command --default "" 2>/dev/null || true)
+   if [ -z "$TEST_CMD" ]; then
+     if [ -f "Makefile" ] && grep -q "^test:" Makefile; then
+       TEST_CMD="make test"
+     elif [ -f "Justfile" ] || [ -f "justfile" ]; then
+       TEST_CMD="just test"
+     elif [ -f "package.json" ]; then
+       TEST_CMD="npm test"
+     elif [ -f "Cargo.toml" ]; then
+       TEST_CMD="cargo test"
+     elif [ -f "go.mod" ]; then
+       TEST_CMD="go test ./..."
+     elif [ -f "pyproject.toml" ] || [ -f "requirements.txt" ]; then
+       TEST_CMD="python -m pytest -x -q --tb=short 2>&1 || uv run python -m pytest -x -q --tb=short"
+     else
+       TEST_CMD="true"
+       echo "⚠ No test runner detected — skipping post-merge test gate"
+     fi
+   fi
    # Detect test runner and run quick smoke test (timeout: 5 minutes)
    TEST_EXIT=0
-   timeout 300 bash -c '
-   if [ -f "package.json" ]; then
-     npm test 2>&1
-   elif [ -f "Cargo.toml" ]; then
-     cargo test 2>&1
-   elif [ -f "go.mod" ]; then
-     go test ./... 2>&1
-   elif [ -f "pyproject.toml" ] || [ -f "requirements.txt" ]; then
-     python -m pytest -x -q --tb=short 2>&1 || uv run python -m pytest -x -q --tb=short 2>&1
-   else
-     echo "⚠ No test runner detected — skipping post-merge test gate"
-     exit 0
-   fi
-   '
+   timeout 300 bash -c "$TEST_CMD" 2>&1
    TEST_EXIT=$?
    if [ "${TEST_EXIT}" -eq 0 ]; then
      echo "✓ Post-merge test gate passed — no cross-plan conflicts"
@@ -786,6 +875,15 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
 
 6. **Report completion — spot-check claims first:**
 
+   **Wave-close heartbeat (#2410):** after spot-checks finish (pass or fail),
+   before the `## Wave {N} Complete` summary, emit as a literal line:
+
+   ```
+   [checkpoint] phase {PHASE_NUMBER} wave {N}/{M} complete, {P}/{Q} plans done ({wave_success}/{wave_plan_count} ok)
+   ```
+
+
+
    For each SUMMARY.md:
    - Verify first 2 files from `key-files.created` exist on disk
    - Check `git log --oneline --all --grep="{phase}-{plan}"` returns ≥1 commit
@@ -846,13 +944,12 @@ Plans with `autonomous: false` require user interaction.
 
 **Auto-mode checkpoint handling:**
 
-Read auto-advance config (chain flag + user preference):
+Read auto-advance config (chain flag OR user preference — same boolean as `check.auto-mode`):
 ```bash
-AUTO_CHAIN=$(gsd-sdk query config-get workflow._auto_chain_active 2>/dev/null || echo "false")
-AUTO_CFG=$(gsd-sdk query config-get workflow.auto_advance 2>/dev/null || echo "false")
+AUTO_MODE=$(gsd-sdk query check auto-mode --pick active 2>/dev/null || echo "false")
 ```
 
-When executor returns a checkpoint AND (`AUTO_CHAIN` is `"true"` OR `AUTO_CFG` is `"true"`):
+When executor returns a checkpoint AND `AUTO_MODE` is `true`:
 - **human-verify** → Auto-spawn continuation agent with `{user_response}` = `"approved"`. Log `⚡ Auto-approved checkpoint`.
 - **decision** → Auto-spawn continuation agent with `{user_response}` = first option from checkpoint details. Log `⚡ Auto-selected: [option]`.
 - **human-action** → Present to user (existing behavior below). Auth gates cannot be automated.
@@ -1111,16 +1208,27 @@ Collect all unique test file paths into `REGRESSION_FILES`.
 **Step 3: Run regression tests (if any found)**
 
 ```bash
-# Detect test runner and run prior phase tests
-if [ -f "package.json" ]; then
-  npm test 2>&1
-elif [ -f "Cargo.toml" ]; then
-  cargo test 2>&1
-elif [ -f "go.mod" ]; then
-  go test ./... 2>&1
-elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
-  python -m pytest ${REGRESSION_FILES} -q --tb=short 2>&1
+# Resolve test command: project config > Makefile > language sniff
+REG_TEST_CMD=$(gsd-sdk query config-get workflow.test_command --default "" 2>/dev/null || true)
+if [ -z "$REG_TEST_CMD" ]; then
+  if [ -f "Makefile" ] && grep -q "^test:" Makefile; then
+    REG_TEST_CMD="make test"
+  elif [ -f "Justfile" ] || [ -f "justfile" ]; then
+    REG_TEST_CMD="just test"
+  elif [ -f "package.json" ]; then
+    REG_TEST_CMD="npm test"
+  elif [ -f "Cargo.toml" ]; then
+    REG_TEST_CMD="cargo test"
+  elif [ -f "go.mod" ]; then
+    REG_TEST_CMD="go test ./..."
+  elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
+    REG_TEST_CMD="python -m pytest ${REGRESSION_FILES} -q --tb=short"
+  else
+    REG_TEST_CMD="true"
+  fi
 fi
+# Detect test runner and run prior phase tests
+eval "$REG_TEST_CMD" 2>&1
 ```
 
 **Step 4: Report results**
@@ -1216,11 +1324,22 @@ If `TEXT_MODE` is true, present as a plain-text numbered list. Otherwise use Ask
 **If user selects option 3:** Stop execution. Report partial completion.
 </step>
 
+<step name="codebase_drift_gate">
+Post-execution structural drift detection (#2003). Non-blocking by contract:
+any internal error here MUST fall through to `verify_phase_goal`. The phase
+is never failed by this gate.
+
+Load and follow the full step spec from
+`get-shit-done/workflows/execute-phase/steps/codebase-drift-gate.md` —
+covers the SDK call, JSON contract, `warn` vs `auto-remap` branches, mapper
+spawn template, and the two `workflow.drift_*` config keys.
+</step>
+
 <step name="verify_phase_goal">
 Verify phase achieved its GOAL, not just completed tasks.
 
 ```bash
-VERIFIER_SKILLS=$(gsd-sdk query agent-skills gsd-verifier 2>/dev/null)
+VERIFIER_SKILLS=$(gsd-sdk query agent-skills gsd-verifier)
 ```
 
 ```
@@ -1402,6 +1521,38 @@ gsd-sdk query learnings.copy 2>/dev/null || echo "⚠ Learnings copy failed —
 Copy failure must NOT block phase completion.
 </step>
 
+<step name="close_phase_todos">
+**Auto-close pending todos tagged for this phase (#2433).**
+
+This step runs AFTER `update_roadmap` marks the phase complete. It moves any pending todos that carry `resolves_phase: <current-phase-number>` to the completed directory.
+
+```bash
+PHASE_NUM="${PHASE_NUMBER}"
+PENDING_DIR=".planning/todos/pending"
+COMPLETED_DIR=".planning/todos/completed"
+mkdir -p "$COMPLETED_DIR"
+
+CLOSED=()
+for TODO_FILE in "$PENDING_DIR"/*.md; do
+  [ -f "$TODO_FILE" ] || continue
+  # Extract resolves_phase from YAML frontmatter (first --- block only)
+  RP=$(awk '/^---/{c++;next} c==1 && /^resolves_phase:/{print $2;exit} c==2{exit}' "$TODO_FILE" 2>/dev/null || true)
+  if [ "$RP" = "$PHASE_NUM" ] || [ "$RP" = "\"$PHASE_NUM\"" ]; then
+    mv "$TODO_FILE" "$COMPLETED_DIR/"
+    CLOSED+=("$(basename "$TODO_FILE")")
+  fi
+done
+
+if [ ${#CLOSED[@]} -gt 0 ]; then
+  gsd-sdk query commit "docs(phase-${PHASE_NUMBER}): auto-close ${#CLOSED[@]} todo(s) resolved by this phase" .planning/todos/completed/ .planning/STATE.md || true
+  echo "◆ Closed ${#CLOSED[@]} todo(s) resolved by Phase ${PHASE_NUMBER}:"
+  for f in "${CLOSED[@]}"; do echo "  ✓ $f"; done
+fi
+```
+
+**If no todos have `resolves_phase: <this-phase>`:** Skip silently — this step is always additive and never blocks phase completion.
+</step>
+
 <step name="update_project_md">
 **Evolve PROJECT.md to reflect phase completion (prevents planning document drift — #956):**
 
@@ -1454,13 +1605,12 @@ STOP. Do not proceed to auto-advance or transition.
 **Auto-advance detection:**
 
 1. Parse `--auto` flag from $ARGUMENTS
-2. Read both the chain flag and user preference (chain flag already synced in init step):
+2. Read consolidated auto-mode (`active` = chain flag OR user preference; chain flag already synced in init step):
    ```bash
-   AUTO_CHAIN=$(gsd-sdk query config-get workflow._auto_chain_active 2>/dev/null || echo "false")
-   AUTO_CFG=$(gsd-sdk query config-get workflow.auto_advance 2>/dev/null || echo "false")
+   AUTO_MODE=$(gsd-sdk query check auto-mode --pick active 2>/dev/null || echo "false")
    ```
 
-**If `--auto` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true (AND verification passed with no gaps):**
+**If `--auto` flag present OR `AUTO_MODE` is true (AND verification passed with no gaps):**
 
 ```
 ╔══════════════════════════════════════════╗
@@ -1473,7 +1623,7 @@ Execute the transition workflow inline (do NOT use Task — orchestrator context
 
 Read and follow `~/.claude/get-shit-done/workflows/transition.md`, passing through the `--auto` flag so it propagates to the next phase invocation.
 
-**If none of `--auto`, `AUTO_CHAIN`, or `AUTO_CFG` is true:**
+**If neither `--auto` nor `AUTO_MODE` is true:**
 
 **STOP. Do not auto-advance. Do not execute transition. Do not plan next phase. Present options to the user and wait.**
 

get-shit-done/workflows/execute-phase/steps/codebase-drift-gate.md

@@ -0,0 +1,79 @@
+# Step: codebase_drift_gate
+
+Post-execution structural drift detection (#2003). Runs after the last wave
+commits, before verification. **Non-blocking by contract:** any internal
+error here MUST fall through and continue to `verify_phase_goal`. The phase
+is never failed by this gate.
+
+```bash
+DRIFT=$(gsd-sdk query verify.codebase-drift 2>/dev/null || echo '{"skipped":true,"reason":"sdk-failed"}')
+```
+
+Parse JSON for: `skipped`, `reason`, `action_required`, `directive`,
+`spawn_mapper`, `affected_paths`, `elements`, `threshold`, `action`,
+`last_mapped_commit`, `message`.
+
+**If `skipped` is true (no STRUCTURE.md, missing git, or any internal error):**
+Log one line — `Codebase drift check skipped: {reason}` — and continue to
+`verify_phase_goal`. Do NOT prompt the user. Do NOT block.
+
+**If `action_required` is false:** Continue silently to `verify_phase_goal`.
+
+**If `action_required` is true AND `directive` is `warn`:**
+Print the `message` field verbatim. The format is:
+
+```text
+Codebase drift detected: {N} structural element(s) since last mapping.
+
+New directories:
+  - {path}
+New barrel exports:
+  - {path}
+New migrations:
+  - {path}
+New route modules:
+  - {path}
+
+Run /gsd-map-codebase --paths {affected_paths} to refresh planning context.
+```
+
+Then continue to `verify_phase_goal`. Do NOT block. Do NOT spawn anything.
+
+**If `action_required` is true AND `directive` is `auto-remap`:**
+
+First load the mapper agent's skill bundle (the executor's `AGENT_SKILLS`
+from step `init_context` is for `gsd-executor`, not the mapper):
+
+```bash
+AGENT_SKILLS_MAPPER=$(gsd-sdk query agent-skills gsd-codebase-mapper)
+```
+
+Then spawn `gsd-codebase-mapper` agents with the `--paths` hint:
+
+```text
+Task(
+  subagent_type="gsd-codebase-mapper",
+  description="Incremental codebase remap (drift)",
+  prompt="Focus: arch
+Today's date: {date}
+--paths {affected_paths joined by comma}
+
+Refresh STRUCTURE.md and ARCHITECTURE.md scoped to the listed paths only.
+Stamp last_mapped_commit in each document's frontmatter.
+${AGENT_SKILLS_MAPPER}"
+)
+```
+
+If the spawn fails or the agent reports an error: log `Codebase drift
+auto-remap failed: {reason}` and continue to `verify_phase_goal`. The phase
+is NOT failed by a remap failure.
+
+If the remap succeeds: log `Codebase drift auto-remap completed for paths:
+{affected_paths}` and continue to `verify_phase_goal`.
+
+The two relevant config keys (continue on error / failure if either is invalid):
+- `workflow.drift_threshold` (integer, default 3) — minimum drift elements before action
+- `workflow.drift_action` — `warn` (default) or `auto-remap`
+
+This step is fully non-blocking — it never fails the phase, and any
+exception path returns control to `verify_phase_goal`.

get-shit-done/workflows/execute-plan.md

@@ -402,15 +402,19 @@ If SUMMARY "Issues Encountered" ≠ "None": yolo → log and continue. Interacti
 </step>
 
 <step name="update_roadmap">
-**Skip this step if running in parallel mode** (the orchestrator handles ROADMAP.md
-updates centrally after merging worktrees).
+Run this step only when NOT executing inside a git worktree (i.e.
+`use_worktrees: false`, the bug #2661 reproducer). In worktree mode each
+worktree has its own ROADMAP.md, so per-plan writes here would diverge
+across siblings; the orchestrator owns the post-merge sync centrally
+(see execute-phase.md §5.7, single-writer contract from #1486 / dcb50396).
 
 ```bash
-# Auto-detect parallel mode: .git is a file in worktrees, a directory in main repo
+# Auto-detect worktree mode: .git is a file in worktrees, a directory in main repo.
+# This mirrors the use_worktrees config flag for the executing handler.
 IS_WORKTREE=$([ -f .git ] && echo "true" || echo "false")
 
-# Skip in parallel mode — orchestrator handles ROADMAP.md centrally
 if [ "$IS_WORKTREE" != "true" ]; then
+  # use_worktrees: false → this handler is the sole post-plan sync point (#2661)
   gsd-sdk query roadmap.update-plan-progress "${PHASE}"
 fi
 ```

get-shit-done/workflows/extract_learnings.md

@@ -135,6 +135,12 @@ missing_artifacts:
 ---
 ```
 
+Individual items may carry an optional `graduated:` annotation (added by `graduation.md` when a cluster is promoted):
+```markdown
+**Graduated:** {target-file}:{ISO_DATE}
+```
+This annotation is appended after the item's existing fields and prevents the item from being re-surfaced in future graduation scans. Do not add this field during extraction — it is written only by the graduation workflow.
+
 The body follows this structure:
 ```markdown
 # Phase {PHASE_NUMBER} Learnings: {PHASE_NAME}

get-shit-done/workflows/graduation.md

@@ -0,0 +1,195 @@
+# graduation.md — LEARNINGS.md Cross-Phase Graduation Helper
+
+**Invoked by:** `transition.md` step `graduation_scan`. Never invoked directly by users.
+
+This workflow clusters recurring items across the last N phases' LEARNINGS.md files and surfaces promotion candidates to the developer via HITL. No item is promoted without explicit developer approval.
+
+---
+
+## Configuration
+
+Read from project config (`config.json`):
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `features.graduation` | `true` | Master on/off switch. `false` skips silently. |
+| `features.graduation_window` | `5` | How many prior phases to scan |
+| `features.graduation_threshold` | `3` | Minimum cluster size to surface |
+
+---
+
+## Step 1: Guard Checks
+
+```bash
+GRADUATION_ENABLED=$(gsd-sdk query config-get features.graduation 2>/dev/null || echo "true")
+GRADUATION_WINDOW=$(gsd-sdk query config-get features.graduation_window 2>/dev/null || echo "5")
+GRADUATION_THRESHOLD=$(gsd-sdk query config-get features.graduation_threshold 2>/dev/null || echo "3")
+```
+
+**Skip silently (print nothing) if:**
+- `features.graduation` is `false`
+- Fewer than `graduation_threshold` completed prior phases exist (not enough data)
+
+**Skip silently (print nothing) if total items across all LEARNINGS.md files in the window is fewer than 5.**
+
+---
+
+## Step 2: Collect LEARNINGS.md Files
+
+Find LEARNINGS.md files from the last N completed phases (excluding the phase currently completing):
+
+```bash
+find .planning/phases -name "*-LEARNINGS.md" | sort | tail -n "$GRADUATION_WINDOW"
+```
+
+For each file found:
+1. Parse the four category sections: `## Decisions`, `## Lessons`, `## Patterns`, `## Surprises`
+2. Extract each `### Item Title` + body as a single item record: `{ category, title, body, source_phase, source_file }`
+3. **Skip items that already contain `**Graduated:**`** — they have been promoted and must not re-surface
+
+---
+
+## Step 3: Cluster by Lexical Similarity
+
+For each category independently, cluster items using Jaccard similarity on tokenized title+body:
+
+**Tokenization:** lowercase, strip punctuation, split on whitespace, remove stop words (a, an, the, is, was, in, on, at, to, for, of, and, or, but, with, from, that, this, by, as).
+
+**Jaccard similarity:** `|A ∩ B| / |A ∪ B|` where A and B are token sets. Two items are in the same cluster if similarity ≥ 0.25.
+
+**Clustering algorithm:** single-pass greedy — process items in phase order; add to the first cluster whose centroid (union of all cluster tokens) has similarity ≥ 0.25 with the new item; otherwise start a new cluster.
+
+**Cluster size filter:** only surface clusters with distinct source phases ≥ `graduation_threshold` (not just total items — same item repeated in one phase still counts as 1 distinct phase).
+
+---
+
+## Step 4: Check graduation_backlog in STATE.md
+
+Read `.planning/STATE.md` `graduation_backlog` section (if present). Format:
+
+```yaml
+graduation_backlog:
+  - cluster_id: "{sha256-of-cluster-title}"
+    status: "dismissed"   # or "deferred"
+    deferred_until: "phase-N"  # only for deferred entries
+    cluster_title: "{representative title}"
+```
+
+**Skip any cluster whose `cluster_id` matches a `dismissed` entry.**
+
+**Skip any cluster whose `cluster_id` matches a `deferred` entry where `deferred_until` phase has not yet completed.**
+
+---
+
+## Step 5: Surface Promotion Candidates
+
+For each qualifying cluster, determine the suggested target file:
+
+| Category | Suggested Target |
+|----------|-----------------|
+| `decisions` | `PROJECT.md` — append under `## Validated Decisions` (create section if absent) |
+| `patterns` | `PATTERNS.md` — append under the appropriate category section (create file if absent) |
+| `lessons` | `PROJECT.md` — append under `## Invariants` (create section if absent) |
+| `surprises` | Flag for human review — if genuinely surprising 3+ times, something structural is wrong |
+
+Print the graduation report:
+
+```text
+📚 Graduation scan across phases {M}–{N}:
+
+  HIGH RECURRENCE ({K}/{WINDOW} phases)
+  ├─ Cluster: "{representative title}"
+  ├─ Category: {category}
+  ├─ Sources: {list of NN-LEARNINGS filenames}
+  └─ Suggested target: {target file} § {section}
+
+  [repeat for each qualifying cluster, ordered HIGH→LOW recurrence]
+
+For each cluster above, choose an action:
+  P = Promote now   D = Defer (re-surface next transition)   X = Dismiss (never re-surface)   A = Defer all remaining
+```
+
+---
+
+## Step 6: HITL — Process Each Cluster
+
+For each cluster (in order from Step 5), ask the developer:
+
+```text
+Cluster: "{title}" [{category}, {K} phases] → {target}
+Action [P/D/X/A]:
+```
+
+Use `AskUserQuestion` (or equivalent HITL primitive for the current runtime). If `TEXT_MODE` is true, display the cluster question as plain text and accept typed input. Accept single-character input: `P`, `D`, `X`, `A` (case-insensitive).
+
+**On `P` (Promote now):**
+
+1. Read the target file (or create it with a standard header if absent)
+2. Append the cluster entry under the suggested section:
+   ```markdown
+   ### {Cluster representative title}
+   {Merged body — combine unique sentences across cluster items}
+
+   **Sources:** Phase {A}, Phase {B}, Phase {C}
+   **Promoted:** {ISO_DATE}
+   ```
+3. For each source LEARNINGS.md item in the cluster, append `**Graduated:** {target-file}:{ISO_DATE}` after its last existing field
+4. Commit both the target file and all annotated LEARNINGS.md files in a single atomic commit:
+   `docs(learnings): graduate "{cluster title}" to {target-file}`
+
+**On `D` (Defer):**
+
+Write to `.planning/STATE.md` under `graduation_backlog`:
+```yaml
+- cluster_id: "{sha256}"
+  status: "deferred"
+  deferred_until: "phase-{NEXT_PHASE_NUMBER}"
+  cluster_title: "{title}"
+```
+
+**On `X` (Dismiss):**
+
+Write to `.planning/STATE.md` under `graduation_backlog`:
+```yaml
+- cluster_id: "{sha256}"
+  status: "dismissed"
+  cluster_title: "{title}"
+```
+
+**On `A` (Defer all):**
+
+Defer the current cluster (same as `D`) and skip all remaining clusters for this run, deferring each to the next transition. Print:
+```text
+[graduation: deferred all remaining clusters to next transition]
+```
+Then proceed directly to Step 7.
+
+---
+
+## Step 7: Completion Report
+
+After processing all clusters, print:
+
+```text
+Graduation complete: {promoted} promoted, {deferred} deferred, {dismissed} dismissed.
+```
+
+If no clusters qualified (all filtered by backlog or threshold), print:
+```text
+[graduation: no qualifying clusters in phases {M}–{N}]
+```
+
+---
+
+## First-Run Behaviour
+
+On the first transition after upgrading to a version that includes this workflow, all extant LEARNINGS.md files may produce a large batch of candidates at once. A `[Defer all]` shorthand is available: if the developer enters `A` at any cluster prompt, all remaining clusters for this run are deferred to the next transition.
+
+---
+
+## No-Op Conditions (silent skip)
+
+- `features.graduation = false`
+- Fewer than `graduation_threshold` prior phases with LEARNINGS.md
+- Total items < 5 across the window
+- All qualifying clusters are in `graduation_backlog` as dismissed

get-shit-done/workflows/health.md

@@ -11,13 +11,17 @@ Read all files referenced by the invoking prompt's execution_context before star
 <step name="parse_args">
 **Parse arguments:**
 
-Check if `--repair` flag is present in the command arguments.
+Check if `--repair` or `--backfill` flags are present in the command arguments.
 
 ```
 REPAIR_FLAG=""
+BACKFILL_FLAG=""
 if arguments contain "--repair"; then
   REPAIR_FLAG="--repair"
 fi
+if arguments contain "--backfill"; then
+  BACKFILL_FLAG="--backfill"
+fi
 ```
 </step>
 
@@ -25,7 +29,7 @@ fi
 **Run health validation:**
 
 ```bash
-gsd-sdk query validate.health $REPAIR_FLAG
+gsd-sdk query validate.health $REPAIR_FLAG $BACKFILL_FLAG
 ```
 
 Parse JSON output:
@@ -138,6 +142,8 @@ Report final status.
 | W007 | warning | Phase on disk but not in ROADMAP | No |
 | W008 | warning | config.json: workflow.nyquist_validation absent (defaults to enabled but agents may skip) | Yes |
 | W009 | warning | Phase has Validation Architecture in RESEARCH.md but no VALIDATION.md | No |
+| W018 | warning | MILESTONES.md missing entry for archived milestone snapshot | Yes (`--backfill`) |
+| W019 | warning | Unrecognized .planning/ root file — not a canonical GSD artifact | No |
 | I001 | info | Plan without SUMMARY (may be in progress) | No |
 
 </error_codes>
@@ -150,6 +156,7 @@ Report final status.
 | resetConfig | Delete + recreate config.json | Loses custom settings |
 | regenerateState | Create STATE.md from ROADMAP structure when it is missing | Loses session history |
 | addNyquistKey | Add workflow.nyquist_validation: true to config.json | None — matches existing default |
+| backfillMilestones | Synthesize missing MILESTONES.md entries from `.planning/milestones/vX.Y-ROADMAP.md` snapshots | None — additive only; triggered by `--backfill` flag |
 
 **Not repairable (too risky):**
 - PROJECT.md, ROADMAP.md content