ci(drift): enforce alias freshness checks in CI and contributor flow (#2910)

Merging alias-drift guardrails and local hook hardening.

.githooks/pre-commit

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

.githooks/pre-push

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

.github/workflows/canary.yml

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

.github/workflows/install-smoke.yml

@@ -1,10 +1,13 @@
 name: Install Smoke
 
-# Exercises the real install path: `npm pack` → `npm install -g <tarball>`
+# Exercises the real install paths:
-# → run `bin/install.js` → assert `gsd-sdk` is on PATH.
+#   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
+# The tarball path is the canonical ship path. The unpacked path reproduces the
-# `bin/install.js` as a string and never executes it.
+# 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
+          # `--claude --local` is the non-interactive code path. Don't swallow
-          # install.js main block: when both a runtime and location are set,
+          # non-zero exit — if the installer fails, that IS the CI failure, and
-          # installAllRuntimes runs with isInteractive=false, no prompts).
+          # its own error message is more useful than the downstream "shim
-          # We tolerate non-zero here because the authoritative assertion is
+          # regression" assertion masking the real cause.
-          # the next step: gsd-sdk must land on PATH. Some runtime targets
+          if ! get-shit-done-cc --claude --local; then
-          # may exit before the SDK step for unrelated reasons on CI.
+            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.)."
-          get-shit-done-cc --claude --local || true
+            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
+      - name: Build SDK dist for tarball
-        run: cd sdk && npm ci && npm run build
+        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
+      - name: Build SDK dist for tarball
-        run: cd sdk && npm ci && npm run build
+        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/require-issue-link.yml

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

.github/workflows/test.yml

@@ -16,6 +16,21 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  # Static lint: no source-grep tests in the test suite.
+  # Runs once (not per matrix node version) since it is a file-content check.
+  lint-tests:
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - name: Set up Node.js
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f  # v6.3.0
+        with:
+          node-version: 24
+      - name: Lint — no source-grep tests
+        shell: bash
+        run: node scripts/lint-no-source-grep.cjs
+
   test:
     runs-on: ${{ matrix.os }}
     timeout-minutes: 10
@@ -35,6 +50,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 +85,21 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Build SDK dist (required by installer)
+        run: npm run build:sdk
+
+      # Seam contract gate: keep manifest -> generated aliases -> registry/CJS adapters aligned.
+      # Run once per workflow on the primary Linux node to avoid redundant matrix cost.
+      - name: SDK seam coverage tests
+        if: matrix.os == 'ubuntu-latest' && matrix.node-version == 24
+        shell: bash
+        run: cd sdk && npx vitest run src/query/command-seam-coverage.test.ts
+
+      - name: SDK generated alias artifact drift check
+        if: matrix.os == 'ubuntu-latest' && matrix.node-version == 24
+        shell: bash
+        run: node sdk/scripts/check-command-aliases-fresh.mjs
+
       - name: Run tests with coverage
         shell: bash
         run: npm run test:coverage

CONTRIBUTING.md

@@ -229,6 +229,73 @@ const content = `
 `;
 ```
 
+### Prohibited: Source-Grep Tests
+
+**Never read source-code `.cjs` files with `readFileSync` to assert that strings exist within them.** This is source-grep theater: it proves a literal is present in a file, not that the feature works at runtime.
+
+```javascript
+// BAD — source-grep theater
+const configSrc = fs.readFileSync(
+  path.join(GSD_ROOT, 'bin', 'lib', 'config-schema.cjs'), 'utf-8'
+);
+assert.ok(
+  configSrc.includes("'workflow.plan_bounce'"),
+  'VALID_CONFIG_KEYS should contain workflow.plan_bounce'
+);
+```
+
+This test passes even if `workflow.plan_bounce` is present but misspelled in the schema, removed from the validation path, or moved to a different file under a different name. It survives every behavioral regression and fails only on trivial renames.
+
+The correct pattern for config key tests — use the CLI:
+
+```javascript
+// GOOD — behavioral test via the CLI
+test('config-set accepts workflow.plan_bounce', (t) => {
+  const tmpDir = createTempProject();
+  t.after(() => cleanup(tmpDir));
+
+  const result = runGsdTools('config-set workflow.plan_bounce true', tmpDir);
+  assert.ok(result.success, `config-set should accept workflow.plan_bounce: ${result.error}`);
+
+  const configPath = path.join(tmpDir, '.planning', 'config.json');
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  assert.strictEqual(config.workflow?.plan_bounce, true, 'value must be persisted');
+});
+```
+
+This single test covers key registration in `VALID_CONFIG_KEYS`, the key's namespace resolution in `KNOWN_TOP_LEVEL`, and value persistence — all behaviors that the source-grep test could not touch.
+
+**Why this pattern broke at scale:** Commit `990c3e64` in this repo updated 5 source-grep tests in one pass when `VALID_CONFIG_KEYS` moved between files. Zero of those tests were testing behavior. If they had been behavioral tests, the migration would have been invisible.
+
+**CI enforcement:** A linter (`scripts/lint-no-source-grep.cjs`, run as `npm run lint:tests`) detects violations. Any test file that calls `readFileSync` on a `.cjs` path in a source directory without the exemption annotation below will fail the `lint-tests` CI job.
+
+### Exception: `allow-test-rule: <reason>`
+
+Some tests legitimately read source files. There are six recognized categories:
+
+| Reason | When to use |
+|--------|-------------|
+| `source-text-is-the-product` | Agent `.md`, workflow `.md`, command `.md` files — their text IS what the runtime loads. Testing text content tests the deployed contract. |
+| `architectural-invariant` | Implementation must use a specific primitive (e.g., `Atomics.wait`, atomic file writes) that cannot be tested by observing outputs. |
+| `structural-regression-guard` | A specific code pattern must (or must not) exist to prevent a class of bug (e.g., regex global-state misuse). Behavioral tests cannot distinguish which pattern was used. |
+| `docs-parity` | A reference doc must stay in sync with source-defined constants (e.g., `CONFIG_DEFAULTS`). The source is the canonical list; there is no runtime API to enumerate it. |
+| `integration-test-input` | A source file is used as a real fixture input to a transformation function under test — the file is not inspected for strings but passed as data. |
+| `structural-implementation-guard` | A feature's interception or wiring point is not reachable end-to-end via `runGsdTools`. Used temporarily until a behavioral path exists. |
+
+Annotate with a standalone `//` comment before the file's opening block comment:
+
+```javascript
+// allow-test-rule: architectural-invariant
+// state.cjs locking must use Atomics.wait(), not a spin-loop. Behavioral tests
+// cannot observe which sleep primitive was chosen — only source inspection can.
+
+/**
+ * Regression tests for locking bugs #1909...
+ */
+```
+
+The annotation **must** be a standalone `// allow-test-rule:` line, not inside a `/** */` block comment — the CI linter scans for the pattern `// allow-test-rule:`.
+
 ### Node.js Version Compatibility
 
 **Node 22 is the minimum supported version.** Node 24 is the primary CI target. All tests must pass on both.
@@ -278,6 +345,83 @@ node --test tests/core.test.cjs
 npm run test:coverage
 ```
 
+### Pre-PR Seam Checks (Manifest/Alias Routing)
+
+If you touched any of the command-manifest or generated alias files, run:
+
+```bash
+npm run check:alias-drift
+```
+
+This verifies generated alias artifacts are in sync with manifest source-of-truth.
+
+Optional local pre-commit hook entry (Git-native):
+
+```bash
+# one-time setup
+mkdir -p .githooks
+cat > .githooks/pre-commit <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+
+if git diff --cached --name-only | grep -Eq "^sdk/src/query/command-manifest\.|^sdk/src/query/command-aliases\.generated\.ts$|^get-shit-done/bin/lib/command-aliases\.generated\.cjs$|^sdk/scripts/gen-command-aliases\.ts$"; then
+  npm run check:alias-drift
+fi
+EOF
+chmod +x .githooks/pre-commit
+git config core.hooksPath .githooks
+```
+
+Optional local pre-push hook to block a private author-email pattern:
+
+```bash
+# set locally in your shell profile (example)
+export GSD_BLOCKED_AUTHOR_REGEX='@example-corp\\.com$'
+
+cat > .githooks/pre-push <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+
+zero_sha='0000000000000000000000000000000000000000'
+blocked_regex="${GSD_BLOCKED_AUTHOR_REGEX:-}"
+[[ -z "$blocked_regex" ]] && exit 0
+violations=()
+
+while read -r local_ref local_sha remote_ref remote_sha; do
+  [[ "$local_sha" == "$zero_sha" ]] && continue
+  if [[ "$remote_sha" == "$zero_sha" ]]; then
+    commits=$(git rev-list "$local_sha" --not --remotes)
+  else
+    commits=$(git rev-list "$remote_sha..$local_sha")
+  fi
+  while read -r commit; do
+    [[ -z "$commit" ]] && continue
+    email=$(git show -s --format='%ae' "$commit" | tr '[:upper:]' '[:lower:]')
+    if printf '%s' "$email" | grep -Eq "$blocked_regex"; then
+      violations+=("$commit <$email>")
+    fi
+  done <<< "$commits"
+done
+
+if [[ ${#violations[@]} -gt 0 ]]; then
+  echo "Push blocked: commit author email matched local blocked regex ($blocked_regex)." >&2
+  printf '  - %s\n' "${violations[@]}" >&2
+  exit 1
+fi
+EOF
+chmod +x .githooks/pre-push
+```
+
+### CI Test Quality Checks
+
+The following checks run on every PR in addition to the test suite:
+
+| Job | What it checks | How to pass |
+|-----|----------------|-------------|
+| `lint-tests` | No source-grep tests (see above) | Replace with `runGsdTools()` behavioral tests, or add `// allow-test-rule: <reason>` |
+
+Run locally before pushing: `npm run lint:tests`
+
 ### Test Requirements by Contribution Type
 
 The required tests differ depending on what you are contributing:
@@ -314,6 +458,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

README.md

@@ -41,7 +41,7 @@ npx get-shit-done-cc@latest
 
 **Trusted by engineers at Amazon, Google, Shopify, and Webflow.**
 
-[Why I Built This](#why-i-built-this) · [How It Works](#how-it-works) · [Commands](#commands) · [Why It Works](#why-it-works) · [User Guide](docs/USER-GUIDE.md)
+[Why I Built This](#why-i-built-this) · [How It Works](#how-it-works) · [Commands](#commands) · [Why It Works](#why-it-works) · [User Guide](docs/USER-GUIDE.md) · [Walkthrough](docs/USER-GUIDE.md#end-to-end-walkthrough)
 
 </div>
 
@@ -197,6 +197,57 @@ The GSD SDK CLI (`gsd-sdk`) is installed automatically (required by `/gsd-*` com
 
 </details>
 
+<details>
+<summary><strong>Minimal Install (local LLMs and token-billed APIs)</strong></summary>
+
+GSD ships 86 skills and 33 subagents. Every runtime (Claude Code, OpenCode, etc.) eagerly enumerates skill descriptions and subagent descriptions into the system prompt on **every turn** — about **~12k tokens** of fixed overhead before you've typed anything. Frontier models with large context (Sonnet 4.6, Opus 4.7 — 200K to 1M ctx) absorb that without a noticeable hit. **Local LLMs with 32K–128K context, and any model where you're paying per token, will feel it.**
+
+Pass `--minimal` (alias `--core-only`) to install only the **main GSD loop**:
+
+```bash
+npx get-shit-done-cc --claude --global --minimal
+# or any other runtime — works the same
+npx get-shit-done-cc --opencode --global --minimal
+```
+
+What you get:
+
+| Surface | Default install | `--minimal` install |
+|---|---|---|
+| Skills | 86 (`new-project`, `discuss-phase`, `plan-phase`, `execute-phase`, …82 more) | **6** (`new-project`, `discuss-phase`, `plan-phase`, `execute-phase`, `help`, `update`) |
+| Subagents | 33 `gsd-*` agents | **0** |
+| Cold-start system-prompt overhead | ~12k tokens | **~700 tokens** (≥94% reduction) |
+| Manifest mode field | `"full"` | `"minimal"` |
+
+The 6 core skills are exactly the ones you need to drive a project from zero: `new-project` to bootstrap, then the `discuss → plan → execute` loop, plus `help` for discovery and `update` to upgrade later.
+
+**This is a hard floor, not a ceiling.** Each `/gsd-*` command you start using and each subagent it dispatches loads its body content into the conversation for that turn — that's normal token use, not eager overhead. But:
+
+> [!IMPORTANT]
+> **The savings disappear the moment you re-install without `--minimal`.** Running `npx get-shit-done-cc@latest` (or `gsd update` from inside a session) without the flag puts the full 86-skill / 33-agent surface back on disk, and every subsequent session pays the full ~12k-token floor again. If you want to stay minimal, **always pass `--minimal` when updating**:
+>
+> ```bash
+> npx get-shit-done-cc@latest --claude --global --minimal
+> ```
+>
+> Need a specific skill that isn't in the core set (e.g., `gsd-autonomous`, `gsd-ship`, `gsd-debug`)? You have two options:
+> 1. **Permanent expand:** re-install without `--minimal` to get the full surface (and the full token floor).
+> 2. **One-shot:** run the slash command's underlying logic by reading the source from `commands/gsd/<name>.md` in the GSD package and executing it manually — no install change needed.
+>
+> Tip: `cat ~/.claude/get-shit-done/.gsd-manifest.json | jq .mode` (or `gsd-file-manifest.json` depending on layout) confirms which mode you're in.
+
+When to use `--minimal`:
+- Local model with 32K–128K context (Qwen3, Llama, Mistral, etc.)
+- Token-metered API where every turn matters
+- Throwaway directory or non-GSD project where you want `/gsd-new-project` available without paying for the rest
+- CI runners or ephemeral containers where install footprint matters
+
+When **not** to use `--minimal`:
+- Active GSD project where you regularly invoke the broader command set (`autonomous`, `ship`, `code-review`, `debug`, etc.) — re-installing each time is friction without payoff.
+- Frontier models with 200K–1M context — the savings are noise.
+
+</details>
+
 <details>
 <summary><strong>Development Installation</strong></summary>
 
@@ -263,6 +314,8 @@ If you prefer not to use that flag, add this to your project's `.claude/settings
 
 ## How It Works
 
+> **New to GSD?** See the [end-to-end walkthrough](docs/USER-GUIDE.md#end-to-end-walkthrough) in the User Guide — it shows a complete project from `/gsd-new-project` through `/gsd-verify-work` with concrete example outputs.
+
 > **Already have code?** Run `/gsd-map-codebase` first. It spawns parallel agents to analyze your stack, architecture, conventions, and concerns. Then `/gsd-new-project` knows your codebase — questions focus on what you're adding, and planning automatically loads your patterns.
 
 ### 1. Initialize Project

agents/gsd-code-fixer.md

@@ -209,6 +209,96 @@ If a finding references multiple files (in Fix section or Issue section):
 
 <execution_flow>
 
+<step name="setup_worktree">
+**Isolation: create a dedicated git worktree BEFORE touching any files.**
+
+This agent runs as a background process that makes commits. Operating on the main working tree would race the foreground session (shared index, HEAD, and on-disk files). Instead, every instance runs in its own isolated worktree.
+
+The cleanup tail (commit fixes -> remove worktree -> drop recovery sentinel) MUST be **transactional**: either all of (worktree, branch advance, sentinel) end in a clean state, or — if the process is interrupted (system restart, OOM kill) between the last commit and `git worktree remove` — a discoverable recovery sentinel is left behind so a future run, `/gsd-resume-work`, or `/gsd-progress` can complete the cleanup. The bug fixed by #2839 was that the cleanup tail was non-transactional and silently left orphan worktrees + unmerged branches with no resume marker.
+
+```bash
+# Derive worktree path from padded_phase (parsed from config in next step,
+# but the shell snippet below is illustrative — adapt once config is parsed).
+# In practice: parse padded_phase from config first, then run:
+branch=$(git branch --show-current)
+test -n "$branch" || { echo "Detached HEAD is not supported for review-fix (#2686)"; exit 1; }
+
+# Recovery-sentinel handling (#2839):
+# Path is ${phase_dir}/.review-fix-recovery-pending.json. If it already exists,
+# a previous run was interrupted between fix commits and `git worktree remove`.
+# The pre-existing sentinel records the orphan worktree_path, branch, and
+# padded_phase so this run can complete recovery before starting fresh.
+sentinel="${phase_dir}/.review-fix-recovery-pending.json"
+if [ -f "$sentinel" ]; then
+  echo "Detected pre-existing recovery sentinel from a prior interrupted run: $sentinel"
+  prior_wt=$(node -e '
+    const fs = require("fs");
+    try {
+      const parsed = JSON.parse(fs.readFileSync(process.argv[1], "utf-8"));
+      process.stdout.write(parsed.worktree_path || "");
+    } catch (err) {
+      process.stderr.write(`Warning: malformed recovery sentinel ${process.argv[1]}: ${err.message}\n`);
+      process.stdout.write("");
+    }
+  ' "$sentinel")
+  if [ -n "$prior_wt" ] && git worktree list --porcelain | grep -q "^worktree $prior_wt$"; then
+    echo "Removing orphan worktree from prior run: $prior_wt"
+    git worktree remove "$prior_wt" --force || true
+  fi
+  rm -f "$sentinel"
+fi
+
+wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")
+git worktree add "$wt" "$branch"
+
+# Write the recovery sentinel ONLY AFTER `git worktree add` succeeds.
+# Writing it before would leave a sentinel pointing at a worktree that does
+# not exist if `git worktree add` itself failed.
+node -e '
+  const fs = require("fs");
+  const [sentinelPath, worktree_path, branch, padded_phase] = process.argv.slice(1);
+  fs.writeFileSync(sentinelPath, JSON.stringify({
+    worktree_path,
+    branch,
+    padded_phase,
+    started_at: new Date().toISOString()
+  }, null, 2));
+' "$sentinel" "$wt" "$branch" "$padded_phase"
+
+cd "$wt"
+```
+
+Concrete steps:
+1. Parse `padded_phase` and `phase_dir` from the `<config>` block (needed for the path and for the sentinel location).
+2. Resolve the current branch: `branch=$(git branch --show-current)`. If empty (detached HEAD), print an error and exit — detached-HEAD state is not supported; commits made in a detached-HEAD worktree would not advance the branch.
+3. **Recovery check (#2839):** If `${phase_dir}/.review-fix-recovery-pending.json` already exists, a prior run was interrupted. Parse the JSON, attempt to remove the orphan worktree it points at (best-effort, with `--force`), then delete the stale sentinel before continuing. This makes a re-run of `/gsd-code-review-fix` self-healing.
+4. Create a unique worktree path: `wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")`. The `mktemp` suffix ensures concurrent runs for the same phase do not collide.
+5. Run `git worktree add "$wt" "$branch"` — this attaches the worktree to the current branch so commits advance it.
+6. **Write the recovery sentinel** at `${phase_dir}/.review-fix-recovery-pending.json` containing `{worktree_path, branch, padded_phase, started_at}`. Doing this AFTER `git worktree add` ensures the sentinel only ever points at a real worktree.
+7. All subsequent file reads, edits, and commits happen inside `$wt`.
+
+**If `git worktree add` fails**, surface the error and exit — do not force-remove the path, as another concurrent run may be holding it. Do not write the sentinel (the worktree does not exist).
+
+**Cleanup tail (transactional, ALWAYS — even on failure):** After writing REVIEW-FIX.md and before returning to the orchestrator, run the two-step cleanup in this exact order:
+
+```bash
+# Step 1: drop the worktree FIRST. If this succeeds and the process is then
+# killed, the next run finds a sentinel pointing at a worktree that no longer
+# exists — the recovery branch handles this gracefully (best-effort remove +
+# sentinel delete). If we reversed the order (sentinel removed first, then
+# worktree remove), an interruption between the two steps would leave NO
+# sentinel and an orphan worktree — exactly the bug from #2839.
+git worktree remove "$wt" --force
+
+# Step 2: drop the recovery sentinel ONLY after `git worktree remove` returns
+# successfully. This atomic-ish ordering is what makes the cleanup tail
+# transactional from the orchestrator's perspective.
+rm -f "$sentinel"
+```
+
+This cleanup is unconditional — register it mentally as a finally-block obligation. If the agent exits early (config error, no findings, etc.), still run the two-step cleanup tail (`git worktree remove "$wt" --force` followed by `rm -f "$sentinel"`) before exit. The sentinel must NEVER be removed before `git worktree remove` succeeds.
+</step>
+
 <step name="load_context">
 **1. Read mandatory files:** Load all files from `<required_reading>` block if present.
 
@@ -312,6 +402,7 @@ Use `gsd-sdk query commit` with conventional format (message first, then every s
 ```bash
 gsd-sdk query commit \
   "fix({padded_phase}): {finding_id} {short_description}" \
+  --files \
   {all_modified_files}
 ```
 
@@ -321,7 +412,7 @@ Examples:
 
 **Multiple files:** List ALL modified files after the message (space-separated):
 ```bash
-gsd-sdk query commit "fix(02): CR-01 ..." \
+gsd-sdk query commit "fix(02): CR-01 ..." --files \
   src/api/auth.ts src/types/user.ts tests/auth.test.ts
 ```
 
@@ -437,6 +528,10 @@ _Iteration: {N}_
 
 <critical_rules>
 
+**ALWAYS run inside the isolated worktree** — set up via `branch=$(git branch --show-current)` + `wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")` + `git worktree add "$wt" "$branch"` at the very start (see `setup_worktree` step). Using `mktemp` ensures concurrent runs do not collide. Attaching to `$branch` (not `HEAD`) ensures commits advance the branch. Every file read, edit, and commit must happen inside `$wt`. Run `git worktree remove "$wt" --force` unconditionally when done (treat it as a finally block). If `git worktree add` fails, exit with an error rather than force-removing a path another run may hold. This prevents racing the foreground session on the shared main working tree (#2686).
+
+**ALWAYS run the transactional cleanup tail in order** (#2839): `git worktree remove "$wt" --force` MUST happen BEFORE `rm -f "$sentinel"` (the recovery sentinel at `${phase_dir}/.review-fix-recovery-pending.json`). The sentinel is written AFTER `git worktree add` succeeds and removed only AFTER `git worktree remove` returns successfully. This ordering is what makes the cleanup tail transactional — an interruption between commits and `git worktree remove` leaves the sentinel behind so a future run, `/gsd-resume-work`, or `/gsd-progress` can detect and complete the recovery. Reversing the order recreates the orphan-worktree bug.
+
 **ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
 
 **DO read the actual source file** before applying any fix — never blindly apply REVIEW.md suggestions without understanding current code state.

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">
@@ -326,10 +339,42 @@ Ready for orchestrator summary.
 ## ARCHITECTURE.md Template (arch focus)
 
 ```markdown
+<!-- refreshed: [YYYY-MM-DD] -->
 # Architecture
 
 **Analysis Date:** [YYYY-MM-DD]
 
+## System Overview
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│                      [Top Layer Name]                        │
+├──────────────────┬──────────────────┬───────────────────────┤
+│   [Component A]  │   [Component B]  │    [Component C]      │
+│  `[path/to/a]`   │  `[path/to/b]`   │   `[path/to/c]`       │
+└────────┬─────────┴────────┬─────────┴──────────┬────────────┘
+         │                  │                     │
+         ▼                  ▼                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    [Middle Layer Name]                       │
+│         `[path/to/layer]`                                    │
+└─────────────────────────────────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────────────────────────────────────┐
+│  [Store / Output / External]                                 │
+│  `[path/to/store]`                                           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Component Responsibilities
+
+| Component | Responsibility | File |
+|-----------|----------------|------|
+| [Name] | [What it owns] | `[path]` |
+| [Name] | [What it owns] | `[path]` |
+| [Name] | [What it owns] | `[path]` |
+
 ## Pattern Overview
 
 **Overall:** [Pattern name]
@@ -350,7 +395,13 @@ Ready for orchestrator summary.
 
 ## Data Flow
 
-**[Flow Name]:**
+### Primary Request Path
+
+1. [Step 1 — entry point] (`[file:line]`)
+2. [Step 2 — processing] (`[file:line]`)
+3. [Step 3 — output/response] (`[file:line]`)
+
+### [Secondary Flow Name]
 
 1. [Step 1]
 2. [Step 2]
@@ -373,6 +424,27 @@ Ready for orchestrator summary.
 - Triggers: [What invokes it]
 - Responsibilities: [What it does]
 
+## Architectural Constraints
+
+- **Threading:** [Threading model — e.g., single-threaded event loop, worker threads used for X]
+- **Global state:** [Any module-level singletons or shared mutable state — list files]
+- **Circular imports:** [Known circular dependency chains, if any]
+- **[Other constraint]:** [Description]
+
+## Anti-Patterns
+
+### [Anti-Pattern Name]
+
+**What happens:** [The incorrect pattern observed in this codebase]
+**Why it's wrong:** [The problem it causes here]
+**Do this instead:** [The correct pattern with file reference]
+
+### [Anti-Pattern Name]
+
+**What happens:** [The incorrect pattern observed in this codebase]
+**Why it's wrong:** [The problem it causes here]
+**Do this instead:** [The correct pattern with file reference]
+
 ## Error Handling
 
 **Strategy:** [Approach]

agents/gsd-debugger.md

@@ -1168,7 +1168,7 @@ Root cause: {root_cause}"
 
 Then commit planning docs via CLI (respects `commit_docs` config automatically):
 ```bash
-gsd-sdk query commit "docs: resolve debug {slug}" .planning/debug/resolved/{slug}.md
+gsd-sdk query commit "docs: resolve debug {slug}" --files .planning/debug/resolved/{slug}.md
 ```
 
 **Append to knowledge base:**
@@ -1199,7 +1199,7 @@ Then append the entry:
 
 Commit the knowledge base update alongside the resolved session:
 ```bash
-gsd-sdk query commit "docs: update debug knowledge base with {slug}" .planning/debug/knowledge-base.md
+gsd-sdk query commit "docs: update debug knowledge base with {slug}" --files .planning/debug/knowledge-base.md
 ```
 
 Report completion and offer next steps.

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.
@@ -562,7 +563,7 @@ gsd-sdk query state.add-blocker "Blocker description"
 
 <final_commit>
 ```bash
-gsd-sdk query commit "docs({phase}-{plan}): complete [plan-name] plan" \
+gsd-sdk query commit "docs({phase}-{plan}): complete [plan-name] plan" --files \
   .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md .planning/REQUIREMENTS.md
 ```
 

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)
 
@@ -755,7 +755,7 @@ Write to: `$PHASE_DIR/$PADDED_PHASE-RESEARCH.md`
 ## Step 7: Commit Research (optional)
 
 ```bash
-gsd-sdk query commit "docs($PHASE): research phase domain" "$PHASE_DIR/$PADDED_PHASE-RESEARCH.md"
+gsd-sdk query commit "docs($PHASE): research phase domain" --files "$PHASE_DIR/$PADDED_PHASE-RESEARCH.md"
 ```
 
 ## Step 8: Return Structured Result
@@ -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
+node ./node_modules/@gsd-build/sdk/dist/cli.js query phase.list-plans "$phase_number"
-# Read research for Nyquist validation data
+# Research / brief artifacts (deterministic listing)
-cat "$phase_dir"/*-RESEARCH.md 2>/dev/null
+node ./node_modules/@gsd-build/sdk/dist/cli.js query phase.list-artifacts "$phase_number" --type research
-gsd-sdk query roadmap.get-phase "$phase_number"
+node ./node_modules/@gsd-build/sdk/dist/cli.js 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-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
+node ./node_modules/@gsd-build/sdk/dist/cli.js query plan.task-structure "$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 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>
@@ -1133,7 +1136,7 @@ Plans:
 
 <step name="git_commit">
 ```bash
-gsd-sdk query commit "docs($PHASE): create phase plan" \
+gsd-sdk query commit "docs($PHASE): create phase plan" --files \
   .planning/phases/$PHASE-*/$PHASE-*-PLAN.md .planning/ROADMAP.md
 ```
 </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-research-synthesizer.md

@@ -139,7 +139,7 @@ Write to `.planning/research/SUMMARY.md`
 The 4 parallel researcher agents write files but do NOT commit. You commit everything together.
 
 ```bash
-gsd-sdk query commit "docs: complete project research" .planning/research/
+gsd-sdk query commit "docs: complete project research" --files .planning/research/
 ```
 
 ## Step 8: Return Summary

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:
+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`.
-- `cat .planning/ROADMAP.md`
-- `cat .planning/STATE.md`
 
 {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-ui-researcher.md

@@ -292,7 +292,7 @@ Fill all sections. Write to `$PHASE_DIR/$PADDED_PHASE-UI-SPEC.md`.
 ## Step 6: Commit (optional)
 
 ```bash
-gsd-sdk query commit "docs($PHASE): UI design contract" "$PHASE_DIR/$PADDED_PHASE-UI-SPEC.md"
+gsd-sdk query commit "docs($PHASE): UI design contract" --files "$PHASE_DIR/$PADDED_PHASE-UI-SPEC.md"
 ```
 
 ## Step 7: Return Structured Result

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,37 @@
+#!/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`)
+ * 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.
+ *
+ * NOTE (#2775): `npx get-shit-done-cc` does NOT link this shim — npx only
+ * exposes the package's primary bin (`get-shit-done-cc`). For npx-based usage,
+ * the installer (`bin/install.js#installSdkIfNeeded`) self-symlinks `gsd-sdk`
+ * into `~/.local/bin` when needed and verifies PATH callability before
+ * reporting `✓ GSD SDK ready`.
+ *
+ * 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/add-backlog.md

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

commands/gsd/add-phase.md

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

commands/gsd/add-todo.md

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

commands/gsd/ai-integration-phase.md

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

commands/gsd/analyze-dependencies.md

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

commands/gsd/capture.md

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

commands/gsd/check-todos.md

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

commands/gsd/code-review-fix.md

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

commands/gsd/code-review.md

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

commands/gsd/config.md

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

commands/gsd/discuss-phase.md

@@ -1,6 +1,6 @@
 ---
 name: gsd:discuss-phase
-description: Gather phase context through adaptive questioning before planning. Use --all to skip area selection and discuss all gray areas interactively. Use --auto to skip interactive questions (Claude picks recommended defaults). Use --chain for interactive discuss followed by automatic plan+execute. Use --power for bulk question generation into a file-based UI (answer at your own pace).
+description: Gather phase context through adaptive questioning before planning.
 argument-hint: "<phase> [--all] [--auto] [--chain] [--batch] [--analyze] [--text] [--power]"
 allowed-tools:
   - Read
@@ -29,10 +29,8 @@ Extract implementation decisions that downstream agents need — researcher and
 </objective>
 
 <execution_context>
-@~/.claude/get-shit-done/workflows/discuss-phase.md
+Workflow files are loaded on-demand in the <process> section below — not upfront.
-@~/.claude/get-shit-done/workflows/discuss-phase-assumptions.md
+Do not pre-load any workflow files before reading the mode routing instructions.
-@~/.claude/get-shit-done/workflows/discuss-phase-power.md
-@~/.claude/get-shit-done/templates/context.md
 </execution_context>
 
 <runtime_note>
@@ -51,11 +49,15 @@ Context files are resolved in-workflow using `init phase-op` and roadmap/state t
 DISCUSS_MODE=$(gsd-sdk query config-get workflow.discuss_mode 2>/dev/null || echo "discuss")
 ```
 
-If `DISCUSS_MODE` is `"assumptions"`: Read and execute @~/.claude/get-shit-done/workflows/discuss-phase-assumptions.md end-to-end.
+If `DISCUSS_MODE` is `"assumptions"`:
+Read and execute `~/.claude/get-shit-done/workflows/discuss-phase-assumptions.md` end-to-end.
 
-If `DISCUSS_MODE` is `"discuss"` (or unset, or any other value): Read and execute @~/.claude/get-shit-done/workflows/discuss-phase.md end-to-end.
+If `DISCUSS_MODE` is `"discuss"` (or unset, or any other value):
+Read and execute `~/.claude/get-shit-done/workflows/discuss-phase.md` end-to-end.
 
-**MANDATORY:** The execution_context files listed above ARE the instructions. Read the workflow file BEFORE taking any action. The objective and success_criteria sections in this command file are summaries — the workflow file contains the complete step-by-step process with all required behaviors, config checks, and interaction patterns. Do not improvise from the summary.
+**MANDATORY:** Read the appropriate workflow file BEFORE taking any action. The objective and success_criteria sections in this command file are summaries — the workflow file contains the complete step-by-step process with all required behaviors, config checks, and interaction patterns. Do not improvise from the summary.
+
+**Lazy loading:** `templates/context.md` is loaded inside the `write_context` step of the active workflow. `discuss-phase-power.md` is loaded inside `discuss-phase.md` when `--power` is detected. Do not load either here.
 </process>
 
 <success_criteria>

commands/gsd/do.md

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

commands/gsd/eval-review.md

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

commands/gsd/forensics.md

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

commands/gsd/from-gsd2.md

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

commands/gsd/graphify.md

@@ -153,7 +153,7 @@ gsd-tools path: $HOME/.claude/get-shit-done/bin/gsd-tools.cjs
 1. **Invoke graphify:**
    Run from the project root:
    ```
-   graphify . --update
+   graphify update .
    ```
    This builds the knowledge graph with SHA256 incremental caching.
    Timeout: up to 5 minutes (or as configured via graphify.build_timeout).

commands/gsd/health.md

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

commands/gsd/inbox.md

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

commands/gsd/ingest-docs.md

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

commands/gsd/insert-phase.md

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

commands/gsd/intel.md

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

commands/gsd/join-discord.md

@@ -1,19 +0,0 @@
----
-name: gsd:join-discord
-description: Join the GSD Discord community
-allowed-tools: []
----
-
-<objective>
-Display the Discord invite link for the GSD community server.
-</objective>
-
-<output>
-# Join the GSD Discord
-
-Connect with other GSD users, get help, share what you're building, and stay updated.
-
-**Invite link:** https://discord.gg/mYgfVNfA2r
-
-Click the link or paste it into your browser to join.
-</output>

commands/gsd/list-phase-assumptions.md

@@ -1,46 +0,0 @@
----
-name: gsd:list-phase-assumptions
-description: Surface Claude's assumptions about a phase approach before planning
-argument-hint: "[phase]"
-allowed-tools:
-  - Read
-  - Bash
-  - Grep
-  - Glob
----
-
-<objective>
-Analyze a phase and present Claude's assumptions about technical approach, implementation order, scope boundaries, risk areas, and dependencies.
-
-Purpose: Help users see what Claude thinks BEFORE planning begins - enabling course correction early when assumptions are wrong.
-Output: Conversational output only (no file creation) - ends with "What do you think?" prompt
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/list-phase-assumptions.md
-</execution_context>
-
-<context>
-Phase number: $ARGUMENTS (required)
-
-Project state and roadmap are loaded in-workflow using targeted reads.
-</context>
-
-<process>
-1. Validate phase number argument (error if missing or invalid)
-2. Check if phase exists in roadmap
-3. Follow list-phase-assumptions.md workflow:
-   - Analyze roadmap description
-   - Surface assumptions about: technical approach, implementation order, scope, risks, dependencies
-   - Present assumptions clearly
-   - Prompt "What do you think?"
-4. Gather feedback and offer next steps
-</process>
-
-<success_criteria>
-
-- Phase validated against roadmap
-- Assumptions surfaced across five areas
-- User prompted for feedback
-- User knows next steps (discuss context, plan phase, or correct assumptions)
-  </success_criteria>

commands/gsd/list-workspaces.md

@@ -1,19 +0,0 @@
----
-name: gsd:list-workspaces
-description: List active GSD workspaces and their status
-allowed-tools:
-  - Bash
-  - Read
----
-<objective>
-Scan `~/gsd-workspaces/` for workspace directories containing `WORKSPACE.md` manifests. Display a summary table with name, path, repo count, strategy, and GSD project status.
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/list-workspaces.md
-@~/.claude/get-shit-done/references/ui-brand.md
-</execution_context>
-
-<process>
-Execute the list-workspaces workflow from @~/.claude/get-shit-done/workflows/list-workspaces.md end-to-end.
-</process>

commands/gsd/map-codebase.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:map-codebase
 description: Analyze codebase with parallel mapper agents to produce .planning/codebase/ documents
-argument-hint: "[optional: specific area to map, e.g., 'api' or 'auth']"
+argument-hint: "[--fast [--focus tech|arch|quality|concerns]] [--query <term>|status|diff|refresh] [area]"
 allowed-tools:
   - Read
   - Bash
@@ -23,8 +23,19 @@ Output: .planning/codebase/ folder with 7 structured documents about the codebas
 @~/.claude/get-shit-done/workflows/map-codebase.md
 </execution_context>
 
+<flags>
+- **--fast**: Lightweight scan mode — spawns one mapper agent instead of four. Accepts an optional `--focus` value: `tech`, `arch`, `quality`, `concerns`, or `tech+arch` (default). Faster and lower-context than the full map.
+- **--query**: Codebase intelligence query mode. Sub-commands: `query <term>`, `status`, `diff`, `refresh`. Requires intel to be enabled in config (`intel.enabled: true`). Runs inline for query/status/diff; spawns an agent for refresh.
+- **(no flag)**: Full parallel map — spawns 4 mapper agents to produce all 7 codebase documents.
+</flags>
+
 <context>
-Focus area: $ARGUMENTS (optional - if provided, tells agents to focus on specific subsystem)
+Arguments: $ARGUMENTS
+
+Parse the first token of $ARGUMENTS:
+- If it is `--fast`: strip the flag, run the scan workflow (passing remaining args including optional --focus).
+- If it is `--query`: strip the flag, run the intel workflow (passing remaining args as the subcommand).
+- Otherwise: pass all of $ARGUMENTS as focus area to the map-codebase workflow.
 
 **Load project state if exists:**
 Check for .planning/STATE.md - loads context if project already initialized

commands/gsd/new-workspace.md

@@ -1,44 +0,0 @@
----
-name: gsd:new-workspace
-description: Create an isolated workspace with repo copies and independent .planning/
-argument-hint: "--name <name> [--repos repo1,repo2] [--path /target] [--strategy worktree|clone] [--branch name] [--auto]"
-allowed-tools:
-  - Read
-  - Bash
-  - Write
-  - AskUserQuestion
----
-<context>
-**Flags:**
-- `--name` (required) — Workspace name
-- `--repos` — Comma-separated repo paths or names. If omitted, interactive selection from child git repos in cwd
-- `--path` — Target directory. Defaults to `~/gsd-workspaces/<name>`
-- `--strategy` — `worktree` (default, lightweight) or `clone` (fully independent)
-- `--branch` — Branch to checkout. Defaults to `workspace/<name>`
-- `--auto` — Skip interactive questions, use defaults
-</context>
-
-<objective>
-Create a physical workspace directory containing copies of specified git repos (as worktrees or clones) with an independent `.planning/` directory for isolated GSD sessions.
-
-**Use cases:**
-- Multi-repo orchestration: work on a subset of repos in parallel with isolated GSD state
-- Feature branch isolation: create a worktree of the current repo with its own `.planning/`
-
-**Creates:**
-- `<path>/WORKSPACE.md` — workspace manifest
-- `<path>/.planning/` — independent planning directory
-- `<path>/<repo>/` — git worktree or clone for each specified repo
-
-**After this command:** `cd` into the workspace and run `/gsd-new-project` to initialize GSD.
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/new-workspace.md
-@~/.claude/get-shit-done/references/ui-brand.md
-</execution_context>
-
-<process>
-Execute the new-workspace workflow from @~/.claude/get-shit-done/workflows/new-workspace.md end-to-end.
-Preserve all workflow gates (validation, approvals, commits, routing).
-</process>

commands/gsd/next.md

@@ -1,28 +0,0 @@
----
-name: gsd:next
-description: Automatically advance to the next logical step in the GSD workflow
-allowed-tools:
-  - Read
-  - Bash
-  - Grep
-  - Glob
-  - SlashCommand
----
-<objective>
-Detect the current project state and automatically invoke the next logical GSD workflow step.
-No arguments needed — reads STATE.md, ROADMAP.md, and phase directories to determine what comes next.
-
-Designed for rapid multi-project workflows where remembering which phase/step you're on is overhead.
-
-Supports `--force` flag to bypass safety gates (checkpoint, error state, verification failures, and prior-phase completeness scan).
-
-Before routing to the next step, scans all prior phases for incomplete work: plans that ran without producing summaries, verification failures without overrides, and phases where discussion happened but planning never ran. When incomplete work is found, shows a structured report and offers three options: defer the gaps to the backlog and continue, stop and resolve manually, or force advance without recording. When prior phases are clean, routes silently with no interruption.
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/next.md
-</execution_context>
-
-<process>
-Execute the next workflow from @~/.claude/get-shit-done/workflows/next.md end-to-end.
-</process>

commands/gsd/note.md

@@ -1,34 +0,0 @@
----
-name: gsd:note
-description: Zero-friction idea capture. Append, list, or promote notes to todos.
-argument-hint: "<text> | list | promote <N> [--global]"
-allowed-tools:
-  - Read
-  - Write
-  - Glob
-  - Grep
----
-<objective>
-Zero-friction idea capture — one Write call, one confirmation line.
-
-Three subcommands:
-- **append** (default): Save a timestamped note file. No questions, no formatting.
-- **list**: Show all notes from project and global scopes.
-- **promote**: Convert a note into a structured todo.
-
-Runs inline — no Task, no AskUserQuestion, no Bash.
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/note.md
-@~/.claude/get-shit-done/references/ui-brand.md
-</execution_context>
-
-<context>
-$ARGUMENTS
-</context>
-
-<process>
-Execute the note workflow from @~/.claude/get-shit-done/workflows/note.md end-to-end.
-Capture the note, list notes, or promote to todo — depending on arguments.
-</process>

commands/gsd/ns-context.md

@@ -0,0 +1,22 @@
+---
+name: gsd-context
+description: "codebase intelligence | map graphify docs learnings"
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Skill
+---
+
+Route to the appropriate codebase-intelligence skill based on the user's intent.
+`gsd-scan` and `gsd-intel` were folded into `gsd-map-codebase` flags by #2790.
+
+| User wants | Invoke |
+|---|---|
+| Map the full codebase structure | gsd-map-codebase |
+| Quick lightweight codebase scan | gsd-map-codebase --fast |
+| Query mapped intelligence files | gsd-map-codebase --query |
+| Generate a knowledge graph | gsd-graphify |
+| Update project documentation | gsd-docs-update |
+| Extract learnings from a completed phase | gsd-extract-learnings |
+
+Invoke the matched skill directly using the Skill tool.

commands/gsd/ns-ideate.md

@@ -0,0 +1,23 @@
+---
+name: gsd-ideate
+description: "exploration capture | explore sketch spike spec capture"
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Skill
+---
+
+Route to the appropriate exploration / capture skill based on the user's intent.
+`gsd-note`, `gsd-add-todo`, `gsd-add-backlog`, and `gsd-plant-seed` were folded
+into `gsd-capture` (with `--note`, default, `--backlog`, `--seed` modes) by
+#2790. The capture target lists pending todos via `--list`.
+
+| User wants | Invoke |
+|---|---|
+| Explore an idea or opportunity | gsd-explore |
+| Sketch out a rough design or plan | gsd-sketch |
+| Time-boxed technical spike | gsd-spike |
+| Write a spec for a phase | gsd-spec-phase |
+| Capture a thought (todo / note / backlog / seed) | gsd-capture |
+
+Invoke the matched skill directly using the Skill tool.

commands/gsd/ns-manage.md

@@ -0,0 +1,28 @@
+---
+name: gsd-manage
+description: "config workspace | workstreams thread update ship inbox"
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Skill
+---
+
+Route to the appropriate management skill based on the user's intent.
+`gsd-config` (settings + advanced + integrations + profile) and `gsd-workspace`
+(new + list + remove) are post-#2790 consolidated entries.
+
+| User wants | Invoke |
+|---|---|
+| Configure GSD settings (basic / advanced / integrations / profile) | gsd-config |
+| Manage workspaces (create / list / remove) | gsd-workspace |
+| Manage parallel workstreams | gsd-workstreams |
+| Continue work in a fresh context thread | gsd-thread |
+| Pause current work | gsd-pause-work |
+| Resume paused work | gsd-resume-work |
+| Update the GSD installation | gsd-update |
+| Ship completed work | gsd-ship |
+| Process inbox items | gsd-inbox |
+| Create a clean PR branch | gsd-pr-branch |
+| Undo the last GSD action | gsd-undo |
+
+Invoke the matched skill directly using the Skill tool.

commands/gsd/ns-project.md

@@ -0,0 +1,22 @@
+---
+name: gsd-project
+description: "project lifecycle | milestones audits summary"
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Skill
+---
+
+Route to the appropriate project / milestone skill based on the user's intent.
+`gsd-plan-milestone-gaps` was deleted by #2790 — gap planning now happens
+inline as part of `gsd-audit-milestone`'s output.
+
+| User wants | Invoke |
+|---|---|
+| Start a new project | gsd-new-project |
+| Create a new milestone | gsd-new-milestone |
+| Complete the current milestone | gsd-complete-milestone |
+| Audit a milestone for issues | gsd-audit-milestone |
+| Summarize milestone status | gsd-milestone-summary |
+
+Invoke the matched skill directly using the Skill tool.

commands/gsd/ns-review.md

@@ -0,0 +1,25 @@
+---
+name: gsd-review
+description: "quality gates | code review debug audit security eval ui"
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Skill
+---
+
+Route to the appropriate quality / review skill based on the user's intent.
+`gsd-code-review-fix` was absorbed by `gsd-code-review --fix` in #2790.
+
+| User wants | Invoke |
+|---|---|
+| Review code for quality and correctness | gsd-code-review |
+| Auto-fix code review findings | gsd-code-review --fix |
+| Audit UAT / acceptance testing | gsd-audit-uat |
+| Security review of a phase | gsd-secure-phase |
+| Evaluate AI response quality | gsd-eval-review |
+| Review UI for design and accessibility | gsd-ui-review |
+| Validate phase outputs | gsd-validate-phase |
+| Debug a failing feature or error | gsd-debug |
+| Forensic investigation of a broken system | gsd-forensics |
+
+Invoke the matched skill directly using the Skill tool.

commands/gsd/ns-workflow.md

@@ -0,0 +1,27 @@
+---
+name: gsd-workflow
+description: "workflow | discuss plan execute verify phase progress"
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Skill
+---
+
+Route to the appropriate phase-pipeline skill based on the user's intent.
+Sub-skill names below are post-#2790 consolidated targets — `gsd-phase`
+absorbs the former add/insert/remove/edit-phase commands and `gsd-progress`
+absorbs the former next/do commands.
+
+| User wants | Invoke |
+|---|---|
+| Gather context before planning | gsd-discuss-phase |
+| Clarify what a phase delivers | gsd-spec-phase |
+| Create a PLAN.md | gsd-plan-phase |
+| Execute plans in a phase | gsd-execute-phase |
+| Verify built features through UAT | gsd-verify-work |
+| Add / insert / remove / edit a phase | gsd-phase |
+| Advance to the next logical step | gsd-progress |
+| Offload planning to the ultraplan cloud | gsd-ultraplan-phase |
+| Cross-AI plan review convergence loop | gsd-plan-review-convergence |
+
+Invoke the matched skill directly using the Skill tool.

commands/gsd/phase.md

@@ -0,0 +1,56 @@
+---
+name: gsd:phase
+description: CRUD for phases in ROADMAP.md — add, insert, remove, or edit phases
+argument-hint: "[--insert | --remove | --edit] <phase-name-or-number>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+---
+
+<objective>
+Manage phases in ROADMAP.md with a single consolidated command.
+
+Mode routing:
+- **default** (no flag): Add a new integer phase to the end of the current milestone → add-phase workflow
+- **--insert**: Insert urgent work as a decimal phase (e.g., 72.1) between existing phases → insert-phase workflow
+- **--remove**: Remove a future phase and renumber subsequent phases → remove-phase workflow
+- **--edit**: Edit any field of an existing phase in place → edit-phase workflow
+</objective>
+
+<routing>
+
+| Flag | Action | Workflow |
+|------|--------|----------|
+| (none) | Add new integer phase at end of milestone | add-phase |
+| --insert | Insert decimal phase (e.g., 72.1) after specified phase | insert-phase |
+| --remove | Remove future phase, renumber subsequent | remove-phase |
+| --edit | Edit fields of existing phase in place | edit-phase |
+
+</routing>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/add-phase.md
+@~/.claude/get-shit-done/workflows/insert-phase.md
+@~/.claude/get-shit-done/workflows/remove-phase.md
+@~/.claude/get-shit-done/workflows/edit-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+
+Parse the first token of $ARGUMENTS:
+- If it is `--insert`: strip the flag, pass remainder (format: <after-phase-number> <description>) to insert-phase workflow
+- If it is `--remove`: strip the flag, pass remainder (phase number) to remove-phase workflow
+- If it is `--edit`: strip the flag, pass remainder (phase-number [--force]) to edit-phase workflow
+- Otherwise: pass all of $ARGUMENTS (phase description) to add-phase workflow
+
+Roadmap and state are resolved in-workflow via `init phase-op` and targeted reads.
+</context>
+
+<process>
+1. Parse the leading flag (if any) from $ARGUMENTS.
+2. Load and execute the appropriate workflow end-to-end based on the routing table above.
+3. Preserve all validation gates from the target workflow.
+</process>

commands/gsd/plan-milestone-gaps.md

@@ -1,34 +0,0 @@
----
-name: gsd:plan-milestone-gaps
-description: Create phases to close all gaps identified by milestone audit
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-<objective>
-Create all phases necessary to close gaps identified by `/gsd-audit-milestone`.
-
-Reads MILESTONE-AUDIT.md, groups gaps into logical phases, creates phase entries in ROADMAP.md, and offers to plan each phase.
-
-One command creates all fix phases — no manual `/gsd-add-phase` per gap.
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/plan-milestone-gaps.md
-</execution_context>
-
-<context>
-**Audit results:**
-Glob: .planning/v*-MILESTONE-AUDIT.md (use most recent)
-
-Original intent and current planning state are loaded on demand inside the workflow.
-</context>
-
-<process>
-Execute the plan-milestone-gaps workflow from @~/.claude/get-shit-done/workflows/plan-milestone-gaps.md end-to-end.
-Preserve all workflow gates (audit loading, prioritization, phase grouping, user confirmation, roadmap updates).
-</process>

commands/gsd/plan-phase.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:plan-phase
 description: Create detailed phase plan (PLAN.md) with verification loop
-argument-hint: "[phase] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify] [--prd <file>] [--reviews] [--text] [--tdd]"
+argument-hint: "[phase] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify] [--prd <file>] [--reviews] [--text] [--tdd] [--mvp]"
 agent: gsd-planner
 allowed-tools:
   - Read
@@ -42,6 +42,7 @@ Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omit
 - `--prd <file>` — Use a PRD/acceptance criteria file instead of discuss-phase. Parses requirements into CONTEXT.md automatically. Skips discuss-phase entirely.
 - `--reviews` — Replan incorporating cross-AI review feedback from REVIEWS.md (produced by `/gsd-review`)
 - `--text` — Use plain-text numbered lists instead of TUI menus (required for `/rc` remote sessions)
+- `--mvp` — Vertical MVP mode. Planner organizes tasks as feature slices (UI→API→DB) instead of horizontal layers. On Phase 1 of a new project, also emits `SKELETON.md` (Walking Skeleton). Can be persisted on a phase via `**Mode:** mvp` in ROADMAP.md.
 
 Normalize phase input in step 2 before any directory lookups.
 </context>

commands/gsd/plan-review-convergence.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:plan-review-convergence
-description: "Cross-AI plan convergence loop — replan with review feedback until no HIGH concerns remain (max 3 cycles)"
+description: "Cross-AI plan convergence loop — replan with review feedback until no HIGH concerns remain."
-argument-hint: "<phase> [--codex] [--gemini] [--claude] [--opencode] [--text] [--ws <name>] [--all] [--max-cycles N]"
+argument-hint: "<phase> [--codex] [--gemini] [--claude] [--opencode] [--ollama] [--lm-studio] [--llama-cpp] [--text] [--ws <name>] [--all] [--max-cycles N]"
 allowed-tools:
   - Read
   - Write
@@ -42,8 +42,14 @@ Phase number: extracted from $ARGUMENTS (required)
 - `--gemini` — Use Gemini CLI as reviewer
 - `--claude` — Use Claude CLI as reviewer (separate session)
 - `--opencode` — Use OpenCode as reviewer
-- `--all` — Use all available CLIs
+- `--ollama` — Use local Ollama server as reviewer (OpenAI-compatible, default host `http://localhost:11434`; configure model via `review.models.ollama`)
+- `--lm-studio` — Use local LM Studio server as reviewer (OpenAI-compatible, default host `http://localhost:1234`; configure model via `review.models.lm_studio`)
+- `--llama-cpp` — Use local llama.cpp server as reviewer (OpenAI-compatible, default host `http://localhost:8080`; configure model via `review.models.llama_cpp`)
+- `--all` — Use all available CLIs and running local model servers
 - `--max-cycles N` — Maximum replan→review cycles (default: 3)
+
+**Feature gate:** This command requires `workflow.plan_review_convergence=true`. Enable with:
+`gsd config-set workflow.plan_review_convergence true`
 </context>
 
 <process>

commands/gsd/plant-seed.md

@@ -1,28 +0,0 @@
----
-name: gsd:plant-seed
-description: Capture a forward-looking idea with trigger conditions — surfaces automatically at the right milestone
-argument-hint: "[idea summary]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - AskUserQuestion
----
-
-<objective>
-Capture an idea that's too big for now but should surface automatically when the right
-milestone arrives. Seeds solve context rot: instead of a one-liner in Deferred that nobody
-reads, a seed preserves the full WHY, WHEN to surface, and breadcrumbs to details.
-
-Creates: .planning/seeds/SEED-NNN-slug.md
-Consumed by: /gsd-new-milestone (scans seeds and presents matches)
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/plant-seed.md
-</execution_context>
-
-<process>
-Execute the plant-seed workflow from @~/.claude/get-shit-done/workflows/plant-seed.md end-to-end.
-</process>

commands/gsd/progress.md

@@ -1,25 +1,44 @@
 ---
 name: gsd:progress
-description: Check project progress, show context, and route to next action (execute or plan). Use --forensic to append a 6-check integrity audit after the standard report.
+description: Check progress, advance workflow, or dispatch freeform intent — the unified GSD situational command
-argument-hint: "[--forensic]"
+argument-hint: "[--forensic | --next | --do \"task description\"]"
 allowed-tools:
   - Read
   - Bash
   - Grep
   - Glob
   - SlashCommand
+  - AskUserQuestion
 ---
 <objective>
-Check project progress, summarize recent work and what's ahead, then intelligently route to the next action - either executing an existing plan or creating the next one.
+Check project progress, summarize recent work and what's ahead, then intelligently route to the next action.
 
-Provides situational awareness before continuing work.
+Three modes:
+- **default**: Show progress report + intelligently route to the next action (execute or plan). Provides situational awareness before continuing work.
+- **--next**: Automatically advance to the next logical step without manual route selection. Reads STATE.md, ROADMAP.md, and phase directories. Supports `--force` to bypass safety gates.
+- **--do "task description"**: Analyze freeform natural language and dispatch to the most appropriate GSD command. Never does the work itself — matches intent, confirms, hands off.
+- **--forensic**: Append a 6-check integrity audit after the standard progress report.
 </objective>
 
+<flags>
+- **--next**: Detect current project state and automatically invoke the next logical GSD workflow step. Scans all prior phases for incomplete work before routing. `--next --force` bypasses safety gates.
+- **--do "..."**: Smart dispatcher — match freeform intent to the best GSD command using routing rules, confirm the match, then hand off.
+- **--forensic**: Run 6-check integrity audit after the standard progress report.
+- **(no flag)**: Standard progress check + intelligent routing (Routes A through F).
+</flags>
+
 <execution_context>
 @~/.claude/get-shit-done/workflows/progress.md
+@~/.claude/get-shit-done/workflows/next.md
+@~/.claude/get-shit-done/workflows/do.md
+@~/.claude/get-shit-done/references/ui-brand.md
 </execution_context>
 
 <process>
-Execute the progress workflow from @~/.claude/get-shit-done/workflows/progress.md end-to-end.
+Parse the first token of $ARGUMENTS:
-Preserve all routing logic (Routes A through F) and edge case handling.
+- If it is `--next`: strip the flag, execute the next workflow (passing remaining args e.g. --force).
+- If it is `--do`: strip the flag, pass remainder as freeform intent to the do workflow.
+- Otherwise: execute the progress workflow end-to-end (pass --forensic through if present).
+
+Preserve all routing logic from the target workflow.
 </process>

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/remove-phase.md

@@ -1,31 +0,0 @@
----
-name: gsd:remove-phase
-description: Remove a future phase from roadmap and renumber subsequent phases
-argument-hint: <phase-number>
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
----
-<objective>
-Remove an unstarted future phase from the roadmap and renumber all subsequent phases to maintain a clean, linear sequence.
-
-Purpose: Clean removal of work you've decided not to do, without polluting context with cancelled/deferred markers.
-Output: Phase deleted, all subsequent phases renumbered, git commit as historical record.
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/remove-phase.md
-</execution_context>
-
-<context>
-Phase: $ARGUMENTS
-
-Roadmap and state are resolved in-workflow via `init phase-op` and targeted reads.
-</context>
-
-<process>
-Execute the remove-phase workflow from @~/.claude/get-shit-done/workflows/remove-phase.md end-to-end.
-Preserve all validation gates (future phase check, work check), renumbering logic, and commit.
-</process>

commands/gsd/remove-workspace.md

@@ -1,26 +0,0 @@
----
-name: gsd:remove-workspace
-description: Remove a GSD workspace and clean up worktrees
-argument-hint: "<workspace-name>"
-allowed-tools:
-  - Bash
-  - Read
-  - AskUserQuestion
----
-<context>
-**Arguments:**
-- `<workspace-name>` (required) — Name of the workspace to remove
-</context>
-
-<objective>
-Remove a workspace directory after confirmation. For worktree strategy, runs `git worktree remove` for each member repo first. Refuses if any repo has uncommitted changes.
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/remove-workspace.md
-@~/.claude/get-shit-done/references/ui-brand.md
-</execution_context>
-
-<process>
-Execute the remove-workspace workflow from @~/.claude/get-shit-done/workflows/remove-workspace.md end-to-end.
-</process>

commands/gsd/research-phase.md

@@ -1,195 +0,0 @@
----
-name: gsd:research-phase
-description: Research how to implement a phase (standalone - usually use /gsd-plan-phase instead)
-argument-hint: "[phase]"
-allowed-tools:
-  - Read
-  - Bash
-  - Task
----
-
-<objective>
-Research how to implement a phase. Spawns gsd-phase-researcher agent with phase context.
-
-**Note:** This is a standalone research command. For most workflows, use `/gsd-plan-phase` which integrates research automatically.
-
-**Use this command when:**
-- You want to research without planning yet
-- You want to re-research after planning is complete
-- You need to investigate before deciding if a phase is feasible
-
-**Orchestrator role:** Parse phase, validate against roadmap, check existing research, gather context, spawn researcher agent, present results.
-
-**Why subagent:** Research burns context fast (WebSearch, Context7 queries, source verification). Fresh 200k context for investigation. Main context stays lean for user interaction.
-</objective>
-
-<available_agent_types>
-Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
-- gsd-phase-researcher — Researches technical approaches for a phase
-</available_agent_types>
-
-<context>
-Phase number: $ARGUMENTS (required)
-
-Normalize phase input in step 1 before any directory lookups.
-</context>
-
-<process>
-
-## 0. Initialize Context
-
-```bash
-INIT=$(gsd-sdk query init.phase-op "$ARGUMENTS")
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-```
-
-Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `phase_found`, `commit_docs`, `has_research`, `state_path`, `requirements_path`, `context_path`, `research_path`.
-
-Resolve researcher model:
-```bash
-RESEARCHER_MODEL=$(gsd-sdk query resolve-model gsd-phase-researcher --raw)
-```
-
-## 1. Validate Phase
-
-```bash
-PHASE_INFO=$(gsd-sdk query roadmap.get-phase "${phase_number}")
-```
-
-**If `found` is false:** Error and exit. **If `found` is true:** Extract `phase_number`, `phase_name`, `goal` from JSON.
-
-## 2. Check Existing Research
-
-```bash
-ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null
-```
-
-**If exists:** Offer: 1) Update research, 2) View existing, 3) Skip. Wait for response.
-
-**If doesn't exist:** Continue.
-
-## 3. Gather Phase Context
-
-Use paths from INIT (do not inline file contents in orchestrator context):
-- `requirements_path`
-- `context_path`
-- `state_path`
-
-Present summary with phase description and what files the researcher will load.
-
-## 4. Spawn gsd-phase-researcher Agent
-
-Research modes: ecosystem (default), feasibility, implementation, comparison.
-
-```markdown
-<research_type>
-Phase Research — investigating HOW to implement a specific phase well.
-</research_type>
-
-<key_insight>
-The question is NOT "which library should I use?"
-
-The question is: "What do I not know that I don't know?"
-
-For this phase, discover:
-- What's the established architecture pattern?
-- What libraries form the standard stack?
-- What problems do people commonly hit?
-- What's SOTA vs what Claude's training thinks is SOTA?
-- What should NOT be hand-rolled?
-</key_insight>
-
-<objective>
-Research implementation approach for Phase {phase_number}: {phase_name}
-Mode: ecosystem
-</objective>
-
-<files_to_read>
-- {requirements_path} (Requirements)
-- {context_path} (Phase context from discuss-phase, if exists)
-- {state_path} (Prior project decisions and blockers)
-</files_to_read>
-
-<additional_context>
-**Phase description:** {phase_description}
-</additional_context>
-
-<downstream_consumer>
-Your RESEARCH.md will be loaded by `/gsd-plan-phase` which uses specific sections:
-- `## Standard Stack` → Plans use these libraries
-- `## Architecture Patterns` → Task structure follows these
-- `## Don't Hand-Roll` → Tasks NEVER build custom solutions for listed problems
-- `## Common Pitfalls` → Verification steps check for these
-- `## Code Examples` → Task actions reference these patterns
-
-Be prescriptive, not exploratory. "Use X" not "Consider X or Y."
-</downstream_consumer>
-
-<quality_gate>
-Before declaring complete, verify:
-- [ ] All domains investigated (not just some)
-- [ ] Negative claims verified with official docs
-- [ ] Multiple sources for critical claims
-- [ ] Confidence levels assigned honestly
-- [ ] Section names match what plan-phase expects
-</quality_gate>
-
-<output>
-Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
-</output>
-```
-
-```
-Task(
-  prompt=filled_prompt,
-  subagent_type="gsd-phase-researcher",
-  model="{researcher_model}",
-  description="Research Phase {phase}"
-)
-```
-
-## 5. Handle Agent Return
-
-**`## RESEARCH COMPLETE`:** Display summary, offer: Plan phase, Dig deeper, Review full, Done.
-
-**`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation.
-
-**`## RESEARCH INCONCLUSIVE`:** Show what was attempted, offer: Add context, Try different mode, Manual.
-
-## 6. Spawn Continuation Agent
-
-```markdown
-<objective>
-Continue research for Phase {phase_number}: {phase_name}
-</objective>
-
-<prior_state>
-<files_to_read>
-- .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md (Existing research)
-</files_to_read>
-</prior_state>
-
-<checkpoint_response>
-**Type:** {checkpoint_type}
-**Response:** {user_response}
-</checkpoint_response>
-```
-
-```
-Task(
-  prompt=continuation_prompt,
-  subagent_type="gsd-phase-researcher",
-  model="{researcher_model}",
-  description="Continue research Phase {phase}"
-)
-```
-
-</process>
-
-<success_criteria>
-- [ ] Phase validated against roadmap
-- [ ] Existing research checked
-- [ ] gsd-phase-researcher spawned with context
-- [ ] Checkpoints handled correctly
-- [ ] User knows next steps
-</success_criteria>

commands/gsd/review-backlog.md

@@ -47,7 +47,7 @@ milestone sequence or remove stale entries.
 
 6. **Commit changes:**
    ```bash
-   gsd-sdk query commit "docs: review backlog — promoted N, removed M" .planning/ROADMAP.md
+   gsd-sdk query commit "docs: review backlog — promoted N, removed M" --files .planning/ROADMAP.md
    ```
 
 7. **Report summary:**

commands/gsd/scan.md

@@ -1,26 +0,0 @@
----
-name: gsd:scan
-description: Rapid codebase assessment — lightweight alternative to /gsd-map-codebase
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Grep
-  - Glob
-  - Agent
-  - AskUserQuestion
----
-<objective>
-Run a focused codebase scan for a single area, producing targeted documents in `.planning/codebase/`.
-Accepts an optional `--focus` flag: `tech`, `arch`, `quality`, `concerns`, or `tech+arch` (default).
-
-Lightweight alternative to `/gsd-map-codebase` — spawns one mapper agent instead of four parallel ones.
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/scan.md
-</execution_context>
-
-<process>
-Execute the scan workflow from @~/.claude/get-shit-done/workflows/scan.md end-to-end.
-</process>

commands/gsd/session-report.md

@@ -1,19 +0,0 @@
----
-name: gsd:session-report
-description: Generate a session report with token usage estimates, work summary, and outcomes
-allowed-tools:
-  - Read
-  - Bash
-  - Write
----
-<objective>
-Generate a structured SESSION_REPORT.md document capturing session outcomes, work performed, and estimated resource usage. Provides a shareable artifact for post-session review.
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/session-report.md
-</execution_context>
-
-<process>
-Execute the session-report workflow from @~/.claude/get-shit-done/workflows/session-report.md end-to-end.
-</process>

commands/gsd/set-profile.md

@@ -1,12 +0,0 @@
----
-name: gsd:set-profile
-description: Switch model profile for GSD agents (quality/balanced/budget/inherit)
-argument-hint: <profile (quality|balanced|budget|inherit)>
-model: haiku
-allowed-tools:
-  - Bash
----
-
-Show the following output to the user verbatim, with no extra commentary:
-
-!`if ! command -v gsd-sdk >/dev/null 2>&1; then printf '⚠ gsd-sdk not found in PATH — /gsd-set-profile requires it.\n\nInstall the GSD SDK:\n  npm install -g @gsd-build/sdk\n\nOr update GSD to get the latest packages:\n  /gsd-update\n'; exit 1; fi; gsd-sdk query config-set-model-profile $ARGUMENTS --raw`

commands/gsd/sketch-wrap-up.md

@@ -1,31 +0,0 @@
----
-name: gsd:sketch-wrap-up
-description: Package sketch design findings into a persistent project skill for future build conversations
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Grep
-  - Glob
-  - AskUserQuestion
----
-<objective>
-Curate sketch design findings and package them into a persistent project skill that Claude
-auto-loads when building the real UI. Also writes a summary to `.planning/sketches/` for
-project history. Output skill goes to `./.claude/skills/sketch-findings-[project]/` (project-local).
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/sketch-wrap-up.md
-@~/.claude/get-shit-done/references/ui-brand.md
-</execution_context>
-
-<runtime_note>
-**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`.
-</runtime_note>
-
-<process>
-Execute the sketch-wrap-up workflow from @~/.claude/get-shit-done/workflows/sketch-wrap-up.md end-to-end.
-Preserve all curation gates (per-sketch review, grouping approval, CLAUDE.md routing line).
-</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
+description: Sketch UI/design ideas with throwaway HTML mockups, or propose what to sketch next (frontier mode)
-argument-hint: "<design idea to explore> [--quick]"
+argument-hint: "[design idea to explore] [--quick] [--text] [--wrap-up] 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>
@@ -37,9 +46,10 @@ Design idea: $ARGUMENTS
 
 **Available flags:**
 - `--quick` — Skip mood/direction intake, jump straight to decomposition and building. Use when the design direction is already clear.
+- `--wrap-up` — Package sketch design findings into a persistent project skill for future build conversations. Runs the sketch-wrap-up workflow.
 </context>
 
 <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/spec-phase.md

@@ -1,6 +1,6 @@
 ---
 name: gsd:spec-phase
-description: Socratic spec refinement — clarify WHAT a phase delivers with ambiguity scoring before discuss-phase. Produces a SPEC.md with falsifiable requirements locked before implementation decisions begin.
+description: Clarify WHAT a phase delivers with ambiguity scoring; produces a SPEC.md before discuss-phase.
 argument-hint: "<phase> [--auto] [--text]"
 allowed-tools:
   - Read

commands/gsd/spike-wrap-up.md

@@ -1,31 +0,0 @@
----
-name: gsd:spike-wrap-up
-description: Package spike findings into a persistent project skill for future build conversations
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Grep
-  - Glob
-  - AskUserQuestion
----
-<objective>
-Curate spike experiment findings and package them into a persistent project skill that Claude
-auto-loads in future build conversations. Also writes a summary to `.planning/spikes/` for
-project history. Output skill goes to `./.claude/skills/spike-findings-[project]/` (project-local).
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/spike-wrap-up.md
-@~/.claude/get-shit-done/references/ui-brand.md
-</execution_context>
-
-<runtime_note>
-**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`.
-</runtime_note>
-
-<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).
-</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
+description: Spike an idea through experiential exploration, or propose what to spike next (frontier mode)
-argument-hint: "<idea to validate> [--quick]"
+argument-hint: "[idea to validate] [--quick] [--text] [--wrap-up] 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
+Spike an idea through experiential exploration — build focused experiments to feel the pieces
-specific question with observable evidence. Spikes live in `.planning/spikes/` and integrate
+of a future app, validate feasibility, and produce verified knowledge for the real build.
-with GSD commit patterns, state tracking, and handoff workflows.
+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,11 @@ 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).
+- `--wrap-up` — Package spike findings into a persistent project skill for future build conversations. Runs the spike-wrap-up workflow.
 </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/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
@@ -83,7 +83,7 @@ When SUBCMD=close and SLUG is set (already sanitized):
 
 3. Commit:
    ```bash
-   gsd-sdk query commit "docs: resolve thread — {SLUG}" ".planning/threads/{SLUG}.md"
+   gsd-sdk query commit "docs: resolve thread — {SLUG}" --files ".planning/threads/{SLUG}.md"
    ```
 
 4. Print:
@@ -191,7 +191,7 @@ updated: {today ISO date}
 
 5. Commit:
    ```bash
-   gsd-sdk query commit "docs: create thread — ${ARGUMENTS}" ".planning/threads/${SLUG}.md"
+   gsd-sdk query commit "docs: create thread — ${ARGUMENTS}" --files ".planning/threads/${SLUG}.md"
    ```
 
 6. Report:

commands/gsd/ultraplan-phase.md

@@ -1,6 +1,6 @@
 ---
 name: gsd:ultraplan-phase
-description: "[BETA] Offload plan phase to Claude Code's ultraplan cloud — drafts remotely while terminal stays free, review in browser with inline comments, import back via /gsd-import. Claude Code only."
+description: "[BETA] Offload plan phase to Claude Code's ultraplan cloud; review in browser and import back."
 argument-hint: "[phase-number]"
 allowed-tools:
   - Read

commands/gsd/update.md

@@ -1,8 +1,14 @@
 ---
 name: gsd:update
 description: Update GSD to latest version with changelog display
+argument-hint: "[--sync | --reapply]"
 allowed-tools:
+  - Read
+  - Write
+  - Edit
   - Bash
+  - Glob
+  - Grep
   - AskUserQuestion
 ---
 
@@ -22,10 +28,19 @@ Routes to the update workflow which handles:
 @~/.claude/get-shit-done/workflows/update.md
 </execution_context>
 
-<process>
+<flags>
-**Follow the update workflow** from `@~/.claude/get-shit-done/workflows/update.md`.
+- **--sync**: Sync managed GSD skills across runtime roots so multi-runtime users stay aligned after an update. Runs the sync-skills workflow (--from, --to, --dry-run, --apply flags supported).
+- **--reapply**: Reapply local modifications after a GSD update. Uses three-way comparison (pristine baseline, user-modified backup, newly installed version) to merge user customizations back. Runs the reapply-patches workflow.
+- **(no flag)**: Standard update — check for new version, show changelog, install.
+</flags>
 
-The workflow handles all logic including:
+<process>
+Parse the first token of $ARGUMENTS:
+- If it is `--sync`: strip the flag, execute the sync-skills workflow (passing remaining args for --from/--to/--dry-run/--apply).
+- If it is `--reapply`: strip the flag, execute the reapply-patches workflow.
+- Otherwise: **Follow the update workflow** from `@~/.claude/get-shit-done/workflows/update.md`.
+
+The update workflow handles all logic including:
 1. Installed version detection (local/global)
 2. Latest version checking via npm
 3. Version comparison
@@ -35,3 +50,8 @@ The workflow handles all logic including:
 7. Update execution
 8. Cache clearing
 </process>
+
+<execution_context_extended>
+@~/.claude/get-shit-done/workflows/sync-skills.md
+@~/.claude/get-shit-done/workflows/reapply-patches.md
+</execution_context_extended>

commands/gsd/workspace.md

@@ -0,0 +1,52 @@
+---
+name: gsd:workspace
+description: Manage GSD workspaces — create, list, or remove isolated workspace environments
+argument-hint: "[--new | --list | --remove] [name]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Manage GSD workspaces with a single consolidated command.
+
+Mode routing:
+- **--new**: Create an isolated workspace with repo copies and independent .planning/ → new-workspace workflow
+- **--list**: List active GSD workspaces and their status → list-workspaces workflow
+- **--remove**: Remove a GSD workspace and clean up worktrees → remove-workspace workflow
+</objective>
+
+<routing>
+
+| Flag | Action | Workflow |
+|------|--------|----------|
+| --new | Create workspace with worktree/clone strategy | new-workspace |
+| --list | Scan ~/gsd-workspaces/, show summary table | list-workspaces |
+| --remove | Confirm and remove workspace directory | remove-workspace |
+
+</routing>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/new-workspace.md
+@~/.claude/get-shit-done/workflows/list-workspaces.md
+@~/.claude/get-shit-done/workflows/remove-workspace.md
+@~/.claude/get-shit-done/references/ui-brand.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+
+Parse the first token of $ARGUMENTS:
+- If it is `--new`: strip the flag, pass remainder (--name, --repos, --path, --strategy, --branch, --auto flags) to new-workspace workflow
+- If it is `--list`: execute list-workspaces workflow (no argument needed)
+- If it is `--remove`: strip the flag, pass remainder (workspace-name) to remove-workspace workflow
+- Otherwise (no flag): show usage — one of --new, --list, or --remove is required
+</context>
+
+<process>
+1. Parse the leading flag from $ARGUMENTS.
+2. Load and execute the appropriate workflow end-to-end based on the routing table above.
+3. Preserve all workflow gates from the target workflow (validation, approvals, commits, routing).
+</process>

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
@@ -222,29 +257,32 @@ See [`docs/INVENTORY.md`](INVENTORY.md#hooks-11-shipped) for the authoritative 1
 
 ### CLI Tools (`get-shit-done/bin/`)
 
-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):
+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-33-shipped) for the authoritative roster):
+
+
+| Module                 | Responsibility                                                                                      |
+| ---------------------- | --------------------------------------------------------------------------------------------------- |
+| `core.cjs`             | Error handling, output formatting, shared utilities; compatibility re-exports for planning helpers |
+| `planning-workspace.cjs` | Planning seam (`planningDir`, `planningPaths`, active workstream routing, `.planning/.lock`)      |
+| `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 +293,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 +307,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 |
+
-|----------|--------|-------------|
+| 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) |
+| **Researchers**  | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4 parallel (stack, features, architecture, pitfalls); advisor spawns during discuss-phase |
-| **Planners** | gsd-planner, gsd-roadmapper | Sequential |
+| **Synthesizers** | gsd-research-synthesizer                                                                | Sequential (after researchers complete)                                                   |
-| **Checkers** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | Sequential (verification loop, max 3 iterations) |
+| **Planners**     | gsd-planner, gsd-roadmapper                                                             | Sequential                                                                                |
-| **Executors** | gsd-executor | Parallel within waves, sequential across waves |
+| **Checkers**     | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor          | Sequential (verification loop, max 3 iterations)                                          |
-| **Verifiers** | gsd-verifier | Sequential (after all executors complete) |
+| **Executors**    | gsd-executor                                                                            | Parallel within waves, sequential across waves                                            |
-| **Mappers** | gsd-codebase-mapper | 4 parallel (tech, arch, quality, concerns) |
+| **Verifiers**    | gsd-verifier                                                                            | Sequential (after all executors complete)                                                 |
-| **Debuggers** | gsd-debugger | Sequential (interactive) |
+| **Mappers**      | gsd-codebase-mapper                                                                     | 4 parallel (tech, arch, quality, concerns)                                                |
-| **Auditors** | gsd-ui-auditor, gsd-security-auditor | Sequential |
+| **Debuggers**    | gsd-debugger                                                                            | Sequential (interactive)                                                                  |
-| **Doc Writers** | gsd-doc-writer, gsd-doc-verifier | Sequential (writer then verifier) |
+| **Auditors**     | gsd-ui-auditor, gsd-security-auditor                                                    | Sequential                                                                                |
-| **Profilers** | gsd-user-profiler | Sequential |
+| **Doc Writers**  | gsd-doc-writer, gsd-doc-verifier                                                        | Sequential (writer then verifier)                                                         |
-| **Analyzers** | gsd-assumptions-analyzer | Sequential (during discuss-phase) |
+| **Profilers**    | gsd-user-profiler                                                                       | Sequential                                                                                |
+| **Analyzers**    | gsd-assumptions-analyzer                                                                | Sequential (during discuss-phase)                                                         |
+
 
 ### Wave Execution Model
 
@@ -305,6 +345,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 +358,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 +412,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 +425,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 +473,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 +498,8 @@ Equivalent paths for other runtimes:
 │   ├── ARCHITECTURE.md
 │   └── PITFALLS.md
 ├── codebase/               # Brownfield mapping (from /gsd-map-codebase)
-│   ├── STACK.md
+│   ├── STACK.md            # YAML frontmatter carries `last_mapped_commit`
-│   ├── ARCHITECTURE.md
+│   ├── ARCHITECTURE.md     # for the post-execute drift gate (#2003)
 │   ├── CONVENTIONS.md
 │   ├── CONCERNS.md
 │   ├── STRUCTURE.md
@@ -489,6 +533,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 +567,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
+  - Claude Code: Uses as-is
-   - OpenCode: Converts commands/agents to OpenCode-compatible flat command + subagent format
+  - OpenCode: Converts commands/agents to OpenCode-compatible flat command + subagent format
-   - Kilo: Reuses the OpenCode conversion pipeline with Kilo config paths
+  - Kilo: Reuses the OpenCode conversion pipeline with Kilo config paths
-   - Codex: Generates TOML config + skills from commands
+  - Codex: Generates TOML config + skills from commands
-   - Copilot: Maps tool names (Read→read, Bash→execute, etc.)
+  - Copilot: Maps tool names (Read→read, Bash→execute, etc.)
-   - Gemini: Adjusts hook event names (`AfterTool` instead of `PostToolUse`)
+  - Gemini: Adjusts hook event names (`AfterTool` instead of `PostToolUse`)
-   - Antigravity: Skills-first with Google model equivalents
+  - Antigravity: Skills-first with Google model equivalents
-   - Trae: Skills-first install to `~/.trae` / `./.trae` with no `settings.json` or hook integration
+  - Trae: Skills-first install to `~/.trae` / `./.trae` with no `settings.json` or hook integration
-   - Cline: Writes `.clinerules` for rule-based integration
+  - Cline: Writes `.clinerules` for rule-based integration
-   - Augment Code: Skills-first with full skill conversion and config management
+  - 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 +613,13 @@ Runtime Engine (Claude Code / Gemini CLI)
 
 ### Context Monitor Thresholds
 
-| Remaining Context | Level | Agent Behavior |
+
-|-------------------|-------|----------------|
+| Remaining Context | Level    | Agent Behavior                          |
-| > 35% | Normal | No warning injected |
+| ----------------- | -------- | --------------------------------------- |
-| ≤ 35% | WARNING | "Avoid starting new complex work" |
+| > 35%             | Normal   | No warning injected                     |
-| ≤ 25% | CRITICAL | "Context nearly exhausted, inform user" |
+| ≤ 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 +634,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 +653,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 |
+
-|---------|---------------|--------------|-----------------|
+| Runtime      | Command Format | Agent System     | Config Location          |
-| Claude Code | `/gsd-command` | Task spawning | `~/.claude/` |
+| ------------ | -------------- | ---------------- | ------------------------ |
-| OpenCode | `/gsd-command` | Subagent mode | `~/.config/opencode/` |
+| Claude Code  | `/gsd-command` | Task spawning    | `~/.claude/`             |
-| Kilo | `/gsd-command` | Subagent mode | `~/.config/kilo/` |
+| OpenCode     | `/gsd-command` | Subagent mode    | `~/.config/opencode/`    |
-| Gemini CLI | `/gsd-command` | Task spawning | `~/.gemini/` |
+| Kilo         | `/gsd-command` | Subagent mode    | `~/.config/kilo/`        |
-| Codex | `$gsd-command` | Skills | `~/.codex/` |
+| Gemini CLI   | `/gsd-command` | Task spawning    | `~/.gemini/`             |
-| Copilot | `/gsd-command` | Agent delegation | `~/.github/` |
+| Codex        | `$gsd-command` | Skills           | `~/.codex/`              |
-| Antigravity | Skills | Skills | `~/.gemini/antigravity/` |
+| Copilot      | `/gsd-command` | Agent delegation | `~/.github/`             |
-| Trae | Skills | Skills | `~/.trae/` |
+| Antigravity  | Skills         | Skills           | `~/.gemini/antigravity/` |
-| Cline | Rules | Rules | `.clinerules` |
+| Trae         | Skills         | Skills           | `~/.trae/`               |
-| Augment Code | Skills | Skills | Augment config |
+| Cline        | Rules          | Rules            | `.clinerules`            |
+| Augment Code | Skills         | Skills           | Augment config           |
+
 
 ### Abstraction Points
 

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:**
+**Global flags (CJS):**
-| Flag | Description |
+
-|------|-------------|
+
-| `--raw` | Machine-readable output (JSON or plain text, no formatting) |
+| Flag           | Description                                                                  |
-| `--cwd <path>` | Override working directory (for sandboxed subagents) |
+| -------------- | ---------------------------------------------------------------------------- |
-| `--ws <name>` | Target a specific workstream context (SDK only) |
+| `--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]
@@ -410,9 +452,10 @@ User-facing entry point: `/gsd-graphify` (see [Command Reference](COMMANDS.md#gs
 
 | Module | File | Exports |
 |--------|------|---------|
-| Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`, shared utilities |
+| Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`, shared utilities, compatibility re-exports |
 | State | `lib/state.cjs` | All `state` subcommands, `state-snapshot` |
 | Phase | `lib/phase.cjs` | Phase CRUD, `find-phase`, `phase-plan-index`, `phases list` |
+| Planning Workspace | `lib/planning-workspace.cjs` | Planning seam: `planningDir`, `planningPaths`, active workstream routing, `.planning/.lock` |
 | Roadmap | `lib/roadmap.cjs` | Roadmap parsing, phase extraction, progress updates |
 | Config | `lib/config.cjs` | Config read/write, section initialization |
 | Verify | `lib/verify.cjs` | All verification and validation commands |
@@ -430,3 +473,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

@@ -32,14 +32,17 @@ Initialize a new project with deep context gathering.
 
 ---
 
-### `/gsd-new-workspace`
+### `/gsd-workspace`
 
-Create an isolated workspace with repo copies and independent `.planning/` directory.
+Manage GSD workspaces — create, list, or remove isolated workspace environments with repo copies and independent `.planning/` directories.
 
 | Flag | Description |
 |------|-------------|
-| `--name <name>` | Workspace name (required) |
+| `--new` | Create a new workspace (use with `--name`, `--repos`, etc.) |
-| `--repos repo1,repo2` | Comma-separated repo paths or names |
+| `--list` | List active GSD workspaces and their status |
+| `--remove <name>` | Remove a workspace and clean up git worktrees |
+| `--name <name>` | Workspace name (used with `--new`) |
+| `--repos repo1,repo2` | Comma-separated repo paths or names (used with `--new`) |
 | `--path /target` | Target directory (default: `~/gsd-workspaces/<name>`) |
 | `--strategy worktree\|clone` | Copy strategy (default: `worktree`) |
 | `--branch <name>` | Branch to checkout (default: `workspace/<name>`) |
@@ -52,45 +55,17 @@ Create an isolated workspace with repo copies and independent `.planning/` direc
 **Produces:** `WORKSPACE.md`, `.planning/`, repo copies (worktrees or clones)
 
 ```bash
-/gsd-new-workspace --name feature-b --repos hr-ui,ZeymoAPI
+/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI
-/gsd-new-workspace --name feature-b --repos . --strategy worktree  # Same-repo isolation
+/gsd-workspace --new --name feature-b --repos . --strategy worktree  # Same-repo isolation
-/gsd-new-workspace --name spike --repos api,web --strategy clone   # Full clones
+/gsd-workspace --list
-```
+/gsd-workspace --remove feature-b
-
----
-
-### `/gsd-list-workspaces`
-
-List active GSD workspaces and their status.
-
-**Scans:** `~/gsd-workspaces/` for `WORKSPACE.md` manifests
-**Shows:** Name, repo count, strategy, GSD project status
-
-```bash
-/gsd-list-workspaces
-```
-
----
-
-### `/gsd-remove-workspace`
-
-Remove a workspace and clean up git worktrees.
-
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `<name>` | Yes | Workspace name to remove |
-
-**Safety:** Refuses removal if any repo has uncommitted changes. Requires name confirmation.
-
-```bash
-/gsd-remove-workspace feature-b
 ```
 
 ---
 
 ### `/gsd-discuss-phase`
 
-Capture implementation decisions before planning.
+Gather phase context through adaptive questioning before planning.
 
 | Argument | Required | Description |
 |----------|----------|-------------|
@@ -171,7 +146,7 @@ Research, plan, and verify a phase.
 
 ### `/gsd-plan-review-convergence`
 
-Cross-AI plan convergence loop. Runs `plan-phase → review → replan → re-review` cycles until no HIGH concerns remain (max 3 cycles by default). Spawns isolated agents for planning and review; orchestrator handles loop control, HIGH-concern counting, stall detection, and escalation.
+Cross-AI plan convergence loop — replan with review feedback until no HIGH concerns remain. Runs `plan-phase → review → replan → re-review` cycles (max 3 cycles by default). Spawns isolated agents for planning and review; orchestrator handles loop control, HIGH-concern counting, stall detection, and escalation.
 
 | Argument / Flag | Required | Description |
 |-----------------|----------|-------------|
@@ -192,7 +167,7 @@ Cross-AI plan convergence loop. Runs `plan-phase → review → replan → re-re
 
 ### `/gsd-ultraplan-phase`
 
-**[BETA — Claude Code only.]** Offload plan-phase work to Claude Code's ultraplan cloud. The plan drafts remotely so the terminal stays free; review inline comments in a browser, then import the finalized plan back into `.planning/` via `/gsd-import`.
+**[BETA]** Offload plan phase to Claude Code's ultraplan cloud; review in browser and import back. The plan drafts remotely so the terminal stays free; review inline comments in a browser, then import the finalized plan back into `.planning/` via `/gsd-import`.
 
 | Flag | Required | Description |
 |------|----------|-------------|
@@ -247,43 +222,6 @@ User acceptance testing with auto-diagnosis.
 
 ---
 
-### `/gsd-next`
-
-Automatically advance to the next logical workflow step. Reads project state and runs the appropriate command.
-
-**Prerequisites:** `.planning/` directory exists
-**Behavior:**
-- No project → suggests `/gsd-new-project`
-- Phase needs discussion → runs `/gsd-discuss-phase`
-- Phase needs planning → runs `/gsd-plan-phase`
-- Phase needs execution → runs `/gsd-execute-phase`
-- Phase needs verification → runs `/gsd-verify-work`
-- All phases complete → suggests `/gsd-complete-milestone`
-
-```bash
-/gsd-next                           # Auto-detect and run next step
-```
-
----
-
-### `/gsd-session-report`
-
-Generate a session report with work summary, outcomes, and estimated resource usage.
-
-**Prerequisites:** Active project with recent work
-**Produces:** `.planning/reports/SESSION_REPORT.md`
-
-```bash
-/gsd-session-report                 # Generate post-session summary
-```
-
-**Report includes:**
-- Work performed (commits, plans executed, phases progressed)
-- Outcomes and deliverables
-- Blockers and decisions made
-- Estimated token/cost usage
-- Next steps recommendation
-
 ---
 
 ### `/gsd-ship`
@@ -417,90 +355,31 @@ Start next version cycle.
 
 ## Phase Management Commands
 
-### `/gsd-add-phase`
+### `/gsd-phase`
 
-Append new phase to roadmap.
+CRUD for phases in ROADMAP.md — add, insert, remove, or edit phases with a single consolidated command.
 
-```bash
+| Flag | Description |
-/gsd-add-phase                      # Interactive — describe the phase
+|------|-------------|
-```
+| (none) | Append a new integer phase to the end of the current milestone |
-
+| `--insert <N>` | Insert urgent work as a decimal phase (e.g., 3.1) after phase N |
-### `/gsd-insert-phase`
+| `--remove <N>` | Remove a future phase and renumber subsequent phases |
-
+| `--edit <N>` | Edit any field of an existing phase in place |
-Insert urgent work between phases using decimal numbering.
+| `--force` | Allow editing in-progress or completed phases (used with `--edit`) |
-
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `N` | No | Insert after this phase number |
-
-```bash
-/gsd-insert-phase 3                 # Insert between phase 3 and 4 → creates 3.1
-```
-
-### `/gsd-remove-phase`
-
-Remove future phase and renumber subsequent phases.
-
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `N` | No | Phase number to remove |
-
-```bash
-/gsd-remove-phase 7                 # Remove phase 7, renumber 8→7, 9→8, etc.
-```
-
-### `/gsd-list-phase-assumptions`
-
-Preview Claude's intended approach before planning.
-
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `N` | No | Phase number |
-
-```bash
-/gsd-list-phase-assumptions 2       # See assumptions for phase 2
-```
-
-### `/gsd-analyze-dependencies`
-
-Analyze phase dependencies and suggest `Depends on` entries for ROADMAP.md before running `/gsd-manager`.
 
 **Prerequisites:** `.planning/ROADMAP.md` exists
-**Produces:** Dependency suggestion table; optionally updates `Depends on` fields in ROADMAP.md with confirmation
+**Produces:** Updated ROADMAP.md
-
-**Run this before `/gsd-manager`** when phases have empty `Depends on` fields and you want to avoid merge conflicts from unordered parallel execution.
 
 ```bash
-/gsd-analyze-dependencies           # Analyze all phases and suggest dependencies
+/gsd-phase "Add authentication system"          # Append new phase with description
+/gsd-phase --insert 3 "Fix auth race condition" # Insert between phase 3 and 4 → creates 3.1
+/gsd-phase --remove 7               # Remove phase 7, renumber 8→7, 9→8, etc.
+/gsd-phase --edit 5                 # Edit any field of phase 5
+/gsd-phase --edit 5 --force         # Edit phase 5 even if in-progress or completed
 ```
 
-**Detection methods:**
-- File overlap — phases touching the same files/domains must be ordered
-- Semantic dependencies — a phase that consumes an API or schema built by another phase
-- Data flow — a phase that reads output produced by another phase
-
 ---
 
-### `/gsd-plan-milestone-gaps`
-
-Create phases to close gaps from milestone audit.
-
-```bash
-/gsd-plan-milestone-gaps             # Creates phases for each audit gap
-```
-
-### `/gsd-research-phase`
-
-Deep ecosystem research only (standalone — usually use `/gsd-plan-phase` instead).
-
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `N` | No | Phase number |
-
-```bash
-/gsd-research-phase 4               # Research phase 4 domain
-```
-
 ### `/gsd-validate-phase`
 
 Retroactively audit and fill Nyquist validation gaps.
@@ -519,14 +398,26 @@ Retroactively audit and fill Nyquist validation gaps.
 
 ### `/gsd-progress`
 
-Show status and next steps.
+Show status, next steps, and automatically advance to the next logical workflow step. Reads project state and determines the appropriate action.
 
 | Flag | Description |
 |------|-------------|
+| `--next` | Automatically advance to the next logical workflow step without manual route selection |
+| `--do "task description"` | Analyze freeform intent and dispatch to the most appropriate GSD command |
 | `--forensic` | Append a 6-check integrity audit after the standard report (STATE consistency, orphaned handoffs, deferred scope drift, memory-flagged pending work, blocking todos, uncommitted code) |
 
+**Auto-routing behavior (absorbed from `/gsd-next`):**
+- No project → suggests `/gsd-new-project`
+- Phase needs discussion → runs `/gsd-discuss-phase`
+- Phase needs planning → runs `/gsd-plan-phase`
+- Phase needs execution → runs `/gsd-execute-phase`
+- Phase needs verification → runs `/gsd-verify-work`
+- All phases complete → suggests `/gsd-complete-milestone`
+
 ```bash
-/gsd-progress                       # "Where am I? What's next?"
+/gsd-progress                       # "Where am I? What's next?" with auto-routing
+/gsd-progress --next                # Advance to next step automatically
+/gsd-progress --do "fix the auth bug"  # Dispatch freeform intent to best GSD command
 /gsd-progress --forensic            # Standard report + integrity audit
 ```
 
@@ -562,6 +453,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:
@@ -645,7 +554,7 @@ Ingest an external plan file into the GSD planning system with conflict detectio
 
 ### `/gsd-ingest-docs`
 
-Scan a repo containing mixed ADRs, PRDs, SPECs, and DOCs and bootstrap or merge the full `.planning/` setup from them in a single pass. Parallel classification (`gsd-doc-classifier`) plus synthesis with precedence rules and cycle detection (`gsd-doc-synthesizer`). Produces a three-bucket conflicts report (`INGEST-CONFLICTS.md`: auto-resolved, competing-variants, unresolved-blockers) and hard-blocks on LOCKED-vs-LOCKED ADR contradictions.
+Bootstrap or merge a .planning/ setup from existing ADRs, PRDs, SPECs, and docs in a repo. Runs parallel classification (`gsd-doc-classifier`) plus synthesis with precedence rules and cycle detection (`gsd-doc-synthesizer`). Produces a three-bucket conflicts report (`INGEST-CONFLICTS.md`: auto-resolved, competing-variants, unresolved-blockers) and hard-blocks on LOCKED-vs-LOCKED ADR contradictions.
 
 | Argument / Flag | Required | Description |
 |-----------------|----------|-------------|
@@ -664,31 +573,6 @@ Scan a repo containing mixed ADRs, PRDs, SPECs, and DOCs and bootstrap or merge
 
 ---
 
-### `/gsd-from-gsd2`
-
-Reverse migration from GSD-2 format (`.gsd/` with Milestone→Slice→Task hierarchy) back to v1 `.planning/` format.
-
-| Flag | Required | Description |
-|------|----------|-------------|
-| `--dry-run` | No | Preview what would be migrated without writing anything |
-| `--force` | No | Overwrite existing `.planning/` directory |
-| `--path <dir>` | No | Specify GSD-2 root directory (defaults to current directory) |
-
-**Flattening:** Milestone→Slice hierarchy is flattened to sequential phase numbers (M001/S01→phase 01, M001/S02→phase 02, M002/S01→phase 03, etc.).
-
-**Produces:** `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, and sequential phase directories in `.planning/`.
-
-**Safety:** Guards against overwriting an existing `.planning/` directory without `--force`.
-
-```bash
-/gsd-from-gsd2                          # Migrate .gsd/ in current directory
-/gsd-from-gsd2 --dry-run                # Preview migration without writing
-/gsd-from-gsd2 --force                  # Overwrite existing .planning/
-/gsd-from-gsd2 --path /path/to/gsd2-project  # Specify GSD-2 root
-```
-
----
-
 ### `/gsd-quick`
 
 Execute ad-hoc task with GSD guarantees.
@@ -735,34 +619,6 @@ Run all remaining phases autonomously.
 /gsd-autonomous --from 3 --to 5     # Run phases 3 through 5
 ```
 
-### `/gsd-do`
-
-Route freeform text to the right GSD command.
-
-```bash
-/gsd-do                             # Then describe what you want
-```
-
-### `/gsd-note`
-
-Zero-friction idea capture — append, list, or promote notes to todos.
-
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `text` | No | Note text to capture (default: append mode) |
-| `list` | No | List all notes from project and global scopes |
-| `promote N` | No | Convert note N into a structured todo |
-
-| Flag | Description |
-|------|-------------|
-| `--global` | Use global scope for note operations |
-
-```bash
-/gsd-note "Consider caching strategy for API responses"
-/gsd-note list
-/gsd-note promote 3
-```
-
 ### `/gsd-debug`
 
 Systematic debugging with persistent state.
@@ -791,26 +647,6 @@ Systematic debugging with persistent state.
 /gsd-debug continue form-submit-500
 ```
 
-### `/gsd-add-todo`
-
-Capture idea or task for later.
-
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `description` | No | Todo description |
-
-```bash
-/gsd-add-todo "Consider adding dark mode support"
-```
-
-### `/gsd-check-todos`
-
-List pending todos and select one to work on.
-
-```bash
-/gsd-check-todos
-```
-
 ### `/gsd-add-tests`
 
 Generate tests for a completed phase.
@@ -884,26 +720,16 @@ Run 2–5 focused feasibility experiments before committing to an implementation
 |----------|----------|-------------|
 | `idea` | No | The technical question or approach to investigate |
 | `--quick` | No | Skip intake conversation; use `idea` text directly |
+| `--wrap-up` | No | Package completed spike findings into a reusable project-local skill |
 
 **Produces:** `.planning/spikes/NNN-experiment-name/` with code, results, and README; `.planning/spikes/MANIFEST.md`
+**`--wrap-up` produces:** `.claude/skills/spike-findings-[project]/` skill file
 
 ```bash
 /gsd-spike                              # Interactive intake
 /gsd-spike "can we stream LLM tokens through SSE"
 /gsd-spike --quick websocket-vs-polling
-```
+/gsd-spike --wrap-up                    # Package findings into a reusable skill
-
----
-
-### `/gsd-spike-wrap-up`
-
-Package completed spike findings into a reusable project-local skill so future sessions can reference the conclusions.
-
-**Prerequisites:** `.planning/spikes/` exists with at least one completed spike
-**Produces:** `.claude/skills/spike-findings-[project]/` skill file
-
-```bash
-/gsd-spike-wrap-up
 ```
 
 ---
@@ -917,27 +743,17 @@ Explore design directions through throwaway HTML mockups before committing to im
 | `idea` | No | The UI design question or direction to explore |
 | `--quick` | No | Skip mood intake; use `idea` text directly |
 | `--text` | No | Text-mode fallback — replace interactive prompts with numbered lists (for non-Claude runtimes) |
+| `--wrap-up` | No | Package winning sketch decisions into a reusable project-local skill |
 
 **Produces:** `.planning/sketches/NNN-descriptive-name/index.html` (2–3 interactive variants), `README.md`, shared `themes/default.css`; `.planning/sketches/MANIFEST.md`
+**`--wrap-up` produces:** `.claude/skills/sketch-findings-[project]/` skill file
 
 ```bash
 /gsd-sketch                             # Interactive mood intake
 /gsd-sketch "dashboard layout"
 /gsd-sketch --quick "sidebar navigation"
 /gsd-sketch --text "onboarding flow"    # Non-Claude runtime
-```
+/gsd-sketch --wrap-up                   # Package winning sketch into a skill
-
----
-
-### `/gsd-sketch-wrap-up`
-
-Package winning sketch decisions into a reusable project-local skill so future sessions inherit the visual direction.
-
-**Prerequisites:** `.planning/sketches/` exists with at least one completed sketch (winner marked)
-**Produces:** `.claude/skills/sketch-findings-[project]/` skill file
-
-```bash
-/gsd-sketch-wrap-up
 ```
 
 ---
@@ -946,7 +762,7 @@ Package winning sketch decisions into a reusable project-local skill so future s
 
 ### `/gsd-forensics`
 
-Post-mortem investigation of failed or stuck GSD workflows.
+Post-mortem investigation for failed GSD workflows — diagnoses what went wrong.
 
 | Argument | Required | Description |
 |----------|----------|-------------|
@@ -1037,80 +853,81 @@ 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-set-profile`
+### `/gsd-config`
 
-Quick profile switch.
+Configure GSD settings interactively — workflow toggles, advanced knobs, integrations, and model profile — with a single consolidated command.
 
-| Argument | Required | Description |
+| Flag | Description |
-|----------|----------|-------------|
+|------|-------------|
-| `profile` | **Yes** | `quality`, `balanced`, `budget`, or `inherit` |
+| (none) | Common-case toggles: model, research, plan_check, verifier, branching |
+| `--advanced` | Power-user knobs: planning tuning, timeouts, branch templates, cross-AI execution, runtime/output |
+| `--integrations` | Third-party API keys, code-review CLI routing, agent-skill injection |
+| `--profile <name>` | Quick profile switch: `quality`, `balanced`, `budget`, or `inherit` |
+
+**`--advanced` sections:**
+
+| 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` |
+
+All answers merge via `gsd-sdk query config-set`, preserving unrelated keys. API keys are masked (`****<last-4>`) in all output.
 
 ```bash
-/gsd-set-profile budget             # Switch to budget profile
+/gsd-config                         # Common-case interactive config
-/gsd-set-profile quality            # Switch to quality profile
+/gsd-config --advanced              # Power-user knobs (six-section prompt)
+/gsd-config --integrations          # API keys, review CLI routing, agent skills
+/gsd-config --profile budget        # Switch to budget profile
+/gsd-config --profile quality       # Switch to quality profile
 ```
 
+See [CONFIGURATION.md](CONFIGURATION.md) for the full schema and defaults.
+
 ---
 
 ## Brownfield Commands
 
 ### `/gsd-map-codebase`
 
-Analyze existing codebase with parallel mapper agents.
+Analyze existing codebase with parallel mapper agents. Use `--fast` for a quick single-agent scan, or `--query` to search existing intel.
 
 | Argument | Required | Description |
 |----------|----------|-------------|
 | `area` | No | Scope mapping to a specific area |
-
+| `--fast` | No | Rapid single-focus assessment — spawns one mapper agent instead of four parallel ones (lightweight alternative) |
-```bash
+| `--query <term>` | No | Search queryable codebase intel files in `.planning/intel/` (requires `intel.enabled: true`) |
-/gsd-map-codebase                   # Full codebase analysis
-/gsd-map-codebase auth              # Focus on auth area
-```
-
----
-
-### `/gsd-scan`
-
-Rapid single-focus codebase assessment — lightweight alternative to `/gsd-map-codebase` that spawns one mapper agent instead of four parallel ones.
 
 | Flag | Description |
 |------|-------------|
-| `--focus tech\|arch\|quality\|concerns\|tech+arch` | Focus area (default: `tech+arch`) |
+| `--focus tech\|arch\|quality\|concerns\|tech+arch` | Focus area for `--fast` mode (default: `tech+arch`) |
 
-**Produces:** Targeted document(s) in `.planning/codebase/`
+**Produces:** `.planning/codebase/` analysis documents (full mode); targeted document(s) in `.planning/codebase/` (`--fast`); intel query results (`--query`)
 
 ```bash
-/gsd-scan                           # Quick tech + arch overview
+/gsd-map-codebase                   # Full codebase analysis (4 parallel agents)
-/gsd-scan --focus quality           # Quality and code health only
+/gsd-map-codebase auth              # Focus on auth area
-/gsd-scan --focus concerns          # Surface concerns and risk areas
+/gsd-map-codebase --fast            # Quick tech + arch overview (1 agent)
-```
+/gsd-map-codebase --fast --focus quality  # Quality and code health only
-
+/gsd-map-codebase --query authentication  # Search intel for a term
----
-
-### `/gsd-intel`
-
-Query, inspect, or refresh queryable codebase intelligence files stored in `.planning/intel/`. Requires `intel.enabled: true` in `config.json`.
-
-| Argument | Description |
-|----------|-------------|
-| `query <term>` | Search intel files for a term |
-| `status` | Show intel file freshness (FRESH/STALE) |
-| `diff` | Show changes since last snapshot |
-| `refresh` | Rebuild all intel files from codebase analysis |
-
-**Produces:** `.planning/intel/` JSON files (stack, api-map, dependency-graph, file-roles, arch-decisions)
-
-```bash
-/gsd-intel status                   # Check freshness of intel files
-/gsd-intel query authentication     # Search intel for a term
-/gsd-intel diff                     # What changed since last snapshot
-/gsd-intel refresh                  # Rebuild intel index
 ```
 
 ### `/gsd-graphify`
@@ -1141,7 +958,7 @@ Build, query, and inspect the project knowledge graph stored in `.planning/graph
 
 ### `/gsd-ai-integration-phase`
 
-AI framework selection wizard for integrating AI/LLM capabilities into a project phase. Presents an interactive decision matrix, surfaces domain-specific failure modes and eval criteria, and produces `AI-SPEC.md` with a framework recommendation, implementation guidance, and evaluation strategy.
+Generate an AI-SPEC.md design contract for phases that involve building AI systems. Presents an interactive decision matrix, surfaces domain-specific failure modes and eval criteria, and produces `AI-SPEC.md` with a framework recommendation, implementation guidance, and evaluation strategy.
 
 **Produces:** `{phase}-AI-SPEC.md` in the phase directory
 
@@ -1156,7 +973,7 @@ AI framework selection wizard for integrating AI/LLM capabilities into a project
 
 ### `/gsd-eval-review`
 
-Retroactive audit of an implemented AI phase's evaluation coverage. Checks implementation against the `AI-SPEC.md` evaluation plan produced by `/gsd-ai-integration-phase`. Scores each eval dimension as COVERED/PARTIAL/MISSING.
+Audit an executed AI phase's evaluation coverage and produce an EVAL-REVIEW.md remediation plan. Checks implementation against the `AI-SPEC.md` evaluation plan produced by `/gsd-ai-integration-phase`. Scores each eval dimension as COVERED/PARTIAL/MISSING.
 
 **Prerequisites:** Phase has been executed and has an `AI-SPEC.md`
 **Produces:** `{phase}-EVAL-REVIEW.md` with findings, gaps, and remediation guidance
@@ -1172,18 +989,17 @@ Retroactive audit of an implemented AI phase's evaluation coverage. Checks imple
 
 ### `/gsd-update`
 
-Update GSD with changelog preview.
+Update GSD with changelog preview, and optionally sync skills or reapply local patches.
+
+| Flag | Description |
+|------|-------------|
+| `--sync` | Sync skills from the GSD registry after updating |
+| `--reapply` | Restore local modifications (patches) after updating |
 
 ```bash
 /gsd-update                         # Check for updates and install
-```
+/gsd-update --sync                  # Update and sync skills
-
+/gsd-update --reapply               # Update and reapply local patches
-### `/gsd-reapply-patches`
-
-Restore local modifications after a GSD update.
-
-```bash
-/gsd-reapply-patches                # Merge back local changes
 ```
 
 ---
@@ -1192,44 +1008,28 @@ Restore local modifications after a GSD update.
 
 ### `/gsd-code-review`
 
-Review source files changed during a phase for bugs, security vulnerabilities, and code quality problems.
+Review source files changed during a phase for bugs, security vulnerabilities, and code quality problems. Use `--fix` to auto-fix findings after review.
 
 | Argument | Required | Description |
 |----------|----------|-------------|
 | `N` | **Yes** | Phase number whose changes to review (e.g., `2` or `02`) |
 | `--depth=quick\|standard\|deep` | No | Review depth level (overrides `workflow.code_review_depth` config). `quick`: pattern-matching only (~2 min). `standard`: per-file analysis with language-specific checks (~5–15 min, default). `deep`: cross-file analysis including import graphs and call chains (~15–30 min) |
 | `--files file1,file2,...` | No | Explicit comma-separated file list; skips SUMMARY/git scoping entirely |
+| `--fix` | No | Auto-fix issues after review — reads REVIEW.md, spawns fixer agent, commits each fix atomically |
+| `--fix --all` | No | Include Info findings in fix scope (default: Critical + Warning only) |
+| `--fix --auto` | No | Fix + re-review iteration loop, capped at 3 iterations |
 
 **Prerequisites:** Phase has been executed and has SUMMARY.md or git history
-**Produces:** `{phase}-REVIEW.md` in phase directory with severity-classified findings
+**Produces:** `{phase}-REVIEW.md` with severity-classified findings; `{phase}-REVIEW-FIX.md` when `--fix` is used
-**Spawns:** `gsd-code-reviewer` agent
+**Spawns:** `gsd-code-reviewer` agent; `gsd-code-fixer` agent (with `--fix`)
 
 ```bash
 /gsd-code-review 3                          # Standard review for phase 3
 /gsd-code-review 2 --depth=deep             # Deep cross-file review
 /gsd-code-review 4 --files src/auth.ts,src/token.ts  # Explicit file list
-```
+/gsd-code-review 3 --fix                    # Review then fix Critical + Warning findings
-
+/gsd-code-review 3 --fix --all             # Review then fix all findings including Info
----
+/gsd-code-review 3 --fix --auto            # Review, fix, and re-review until clean (max 3 iterations)
-
-### `/gsd-code-review-fix`
-
-Auto-fix issues found by `/gsd-code-review`. Reads `REVIEW.md`, spawns a fixer agent, commits each fix atomically, and produces a `REVIEW-FIX.md` summary.
-
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `N` | **Yes** | Phase number whose REVIEW.md to fix |
-| `--all` | No | Include Info findings in fix scope (default: Critical + Warning only) |
-| `--auto` | No | Enable fix + re-review iteration loop, capped at 3 iterations |
-
-**Prerequisites:** Phase has a `{phase}-REVIEW.md` file (run `/gsd-code-review` first)
-**Produces:** `{phase}-REVIEW-FIX.md` with applied fixes summary
-**Spawns:** `gsd-code-fixer` agent
-
-```bash
-/gsd-code-review-fix 3                      # Fix Critical + Warning findings for phase 3
-/gsd-code-review-fix 3 --all               # Include Info findings
-/gsd-code-review-fix 3 --auto              # Fix and re-review until clean (max 3 iterations)
 ```
 
 ---
@@ -1321,19 +1121,6 @@ Create a clean PR branch by filtering out `.planning/` commits.
 
 ---
 
-### `/gsd-audit-uat`
-
-Cross-phase audit of all outstanding UAT and verification items.
-
-**Prerequisites:** At least one phase has been executed with UAT or verification
-**Produces:** Categorized audit report with human test plan
-
-```bash
-/gsd-audit-uat
-```
-
----
-
 ### `/gsd-secure-phase`
 
 Retroactively verify threat mitigations for a completed phase.
@@ -1380,21 +1167,34 @@ Each doc writer explores the codebase directly — no hallucinated paths or stal
 
 ---
 
-## Backlog & Thread Commands
+## Task Capture & Backlog Commands
 
-### `/gsd-add-backlog`
+### `/gsd-capture`
 
-Add an idea to the backlog parking lot using 999.x numbering.
+Capture ideas, tasks, notes, and seeds to their appropriate destination. Default mode adds a structured todo; flags route to specialized capture workflows.
 
-| Argument | Required | Description |
+| Flag | Description |
-|----------|----------|-------------|
+|------|-------------|
-| `description` | **Yes** | Backlog item description |
+| (none) | Capture as a structured todo for later work |
+| `--note [text]` | Zero-friction note — append, list (`--note list`), or promote (`--note promote N`) |
+| `--backlog <description>` | Add to the backlog parking lot using 999.x numbering |
+| `--seed [idea summary]` | Capture a forward-looking idea with trigger conditions |
+| `--list` | List pending todos and select one to work on |
+| `--global` | Use global scope (for note operations) |
 
-**999.x numbering** keeps backlog items outside the active phase sequence. Phase directories are created immediately so `/gsd-discuss-phase` and `/gsd-plan-phase` work on them.
+**Backlog:** 999.x numbering keeps items outside the active phase sequence; phase directories are created immediately so `/gsd-discuss-phase` and `/gsd-plan-phase` work on them.
+**Seeds:** Preserve full WHY, WHEN to surface, and breadcrumbs — consumed by `/gsd-new-milestone`.
+
+**Produces:** `.planning/todos/` (default), note files (--note), ROADMAP.md backlog section (--backlog), `.planning/seeds/SEED-NNN-slug.md` (--seed)
 
 ```bash
-/gsd-add-backlog "GraphQL API layer"
+/gsd-capture "Consider adding dark mode support"   # Add todo
-/gsd-add-backlog "Mobile responsive redesign"
+/gsd-capture --note "Caching strategy idea"        # Quick note
+/gsd-capture --note list                           # List all notes
+/gsd-capture --note promote 3                      # Promote note 3 to todo
+/gsd-capture --backlog "GraphQL API layer"         # Add to backlog
+/gsd-capture --seed "Add real-time collaboration when WebSocket infra is in place"
+/gsd-capture --list                                # Browse and act on todos
 ```
 
 ---
@@ -1411,25 +1211,6 @@ Review and promote backlog items to active milestone.
 
 ---
 
-### `/gsd-plant-seed`
-
-Capture a forward-looking idea with trigger conditions — surfaces automatically at the right milestone.
-
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `idea summary` | No | Seed description (prompted if omitted) |
-
-Seeds solve context rot: instead of a one-liner in Deferred that nobody reads, a seed preserves the full WHY, WHEN to surface, and breadcrumbs to details.
-
-**Produces:** `.planning/seeds/SEED-NNN-slug.md`
-**Consumed by:** `/gsd-new-milestone` (scans seeds and presents matches)
-
-```bash
-/gsd-plant-seed "Add real-time collaboration when WebSocket infra is in place"
-```
-
----
-
 ### `/gsd-thread`
 
 Manage persistent context threads for cross-session work.
@@ -1528,10 +1309,22 @@ Enable with:
 
 ---
 
-### `/gsd-join-discord`
+### Community Invite
 
-Open Discord community invite.
+To join the GSD Discord community, visit the link in the GSD README or run `/gsd-help` and follow the Discord link shown there.
+
+---
+
+## Contributing: Skill Description Standards
+
+Skill descriptions (the `description:` field in each `commands/gsd/*.md` frontmatter) are
+injected into every session's system prompt. To keep per-session overhead low, descriptions
+must be ≤ 100 chars and must not duplicate flag documentation already in `argument-hint:`.
+
+A lint gate enforces the budget:
 
 ```bash
-/gsd-join-discord
+npm run lint:descriptions
 ```
+
+The check is also run as part of `npm test` via `tests/enh-2789-description-budget.test.cjs`.

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,17 @@ 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,
+    "build_command": null,
+    "test_command": null
   },
   "hooks": {
     "context_warnings": true,
@@ -108,11 +114,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 +134,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 +182,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 +196,9 @@ 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_review_convergence` | boolean | `false` | Enable the `/gsd-plan-review-convergence` command. Disabled by default — the command exits with an enable instruction when this key is `false`. The command automates the manual plan→review→replan loop: it spawns configured reviewers (Codex, Gemini, Claude, OpenCode, Ollama, LM Studio, llama.cpp), counts unresolved HIGH concerns via the CYCLE_SUMMARY contract, replans with `--reviews` feedback, and repeats until converged or max cycles reached. Enable with `gsd config-set workflow.plan_review_convergence true`. Added in v1.39 |
+| `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 +209,10 @@ 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 |
+| `workflow.build_command` | string | (none) | Shell command to build the project in the post-merge build gate (Step A of step 5.6 in execute-phase). When unset, the gate auto-detects: Xcode (`.xcodeproj` present) → `xcodebuild build`, `Makefile` with `build:` target → `make build`, Justfile → `just build`, `Cargo.toml` → `cargo build`, `go.mod` → `go build ./...`, Python → `python -m py_compile`, `package.json` with `build` script → `npm run build`. Runs with a 5-minute timeout; failure increments `WAVE_FAILURE_COUNT`. Added in v1.39 |
+| `workflow.test_command` | string | (none) | Shell command to run the project's test suite in the post-merge test gate (Step B of step 5.6 in execute-phase) and the regression gate. When unset, the gate auto-detects: Xcode (`.xcodeproj` present) → `xcodebuild test`, `Makefile` with `test:` target → `make test`, Justfile → `just test`, `package.json` → `npm test`, `Cargo.toml` → `cargo test`, `go.mod` → `go test ./...`, Python → `python -m pytest`. Runs with a 5-minute timeout; failure increments `WAVE_FAILURE_COUNT`. Added in v1.39 |
 
 ### Recommended Presets
 
@@ -178,6 +232,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 +255,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 +313,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 +330,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 +358,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 +460,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 +470,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.
@@ -414,6 +536,12 @@ Configure per-CLI model selection for `/gsd-review`. When set, overrides the CLI
 | `review.models.opencode` | string | (CLI default) | Model used when `--opencode` reviewer is invoked |
 | `review.models.qwen` | string | (CLI default) | Model used when `--qwen` reviewer is invoked |
 | `review.models.cursor` | string | (CLI default) | Model used when `--cursor` reviewer is invoked |
+| `review.models.ollama` | string | (server default) | Model name passed to Ollama when `--ollama` reviewer is invoked. If unset, the first available model reported by the server is used (e.g. `llama3`). Set to a specific tag: `gsd config-set review.models.ollama codellama` |
+| `review.models.lm_studio` | string | (server default) | Model name passed to LM Studio when `--lm-studio` reviewer is invoked. If unset, the first available model reported by the server is used. |
+| `review.models.llama_cpp` | string | (server default) | Model name passed to llama.cpp when `--llama-cpp` reviewer is invoked. If unset, the first model reported by `/v1/models` is used. |
+| `review.ollama_host` | string | `http://localhost:11434` | Base URL of the Ollama server. Override when running Ollama on a non-default port or remote host: `gsd config-set review.ollama_host http://192.168.1.10:11434` |
+| `review.lm_studio_host` | string | `http://localhost:1234` | Base URL of the LM Studio local server. Override when using a non-default port. |
+| `review.llama_cpp_host` | string | `http://localhost:8080` | Base URL of the llama.cpp server (`llama-server`). Override when using a non-default port. |
 
 ### Example
 
@@ -503,6 +631,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 +679,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
@@ -1752,6 +1791,7 @@ Test suite that scans all agent, workflow, and command files for embedded inject
 - REQ-CTXRED-01: System MUST truncate oversized markdown artifacts to fit within context budgets
 - REQ-CTXRED-02: System MUST order prompts for cache-friendly assembly (stable prefixes first)
 - REQ-CTXRED-03: Reduction MUST preserve essential information (headings, requirements, task structure)
+- REQ-CTXRED-04: Skill `description:` fields MUST be ≤ 100 chars; enforced by `npm run lint:descriptions` (see `scripts/lint-descriptions.cjs` and `tests/enh-2789-description-budget.test.cjs`)
 
 **Process:**
 1. **Measure** — Calculate total prompt size for the workflow

docs/INVENTORY-MANIFEST.json

@@ -1,5 +1,5 @@
 {
-  "generated": "2026-04-20",
+  "generated": "2026-04-30",
   "families": {
     "agents": [
       "gsd-advisor-researcher",
@@ -37,78 +37,60 @@
       "gsd-verifier"
     ],
     "commands": [
-      "/gsd-add-backlog",
-      "/gsd-add-phase",
       "/gsd-add-tests",
-      "/gsd-add-todo",
       "/gsd-ai-integration-phase",
-      "/gsd-analyze-dependencies",
       "/gsd-audit-fix",
       "/gsd-audit-milestone",
       "/gsd-audit-uat",
       "/gsd-autonomous",
-      "/gsd-check-todos",
+      "/gsd-capture",
       "/gsd-cleanup",
       "/gsd-code-review",
-      "/gsd-code-review-fix",
       "/gsd-complete-milestone",
+      "/gsd-config",
       "/gsd-debug",
       "/gsd-discuss-phase",
-      "/gsd-do",
       "/gsd-docs-update",
       "/gsd-eval-review",
       "/gsd-execute-phase",
       "/gsd-explore",
-      "/gsd-extract_learnings",
+      "/gsd-extract-learnings",
       "/gsd-fast",
       "/gsd-forensics",
-      "/gsd-from-gsd2",
       "/gsd-graphify",
       "/gsd-health",
       "/gsd-help",
       "/gsd-import",
       "/gsd-inbox",
       "/gsd-ingest-docs",
-      "/gsd-insert-phase",
-      "/gsd-intel",
-      "/gsd-join-discord",
-      "/gsd-list-phase-assumptions",
-      "/gsd-list-workspaces",
       "/gsd-manager",
       "/gsd-map-codebase",
       "/gsd-milestone-summary",
       "/gsd-new-milestone",
       "/gsd-new-project",
-      "/gsd-new-workspace",
+      "/gsd-ns-context",
-      "/gsd-next",
+      "/gsd-ns-ideate",
-      "/gsd-note",
+      "/gsd-ns-manage",
+      "/gsd-ns-project",
+      "/gsd-ns-review",
+      "/gsd-ns-workflow",
       "/gsd-pause-work",
-      "/gsd-plan-milestone-gaps",
+      "/gsd-phase",
       "/gsd-plan-phase",
       "/gsd-plan-review-convergence",
-      "/gsd-plant-seed",
       "/gsd-pr-branch",
       "/gsd-profile-user",
       "/gsd-progress",
       "/gsd-quick",
-      "/gsd-reapply-patches",
-      "/gsd-remove-phase",
-      "/gsd-remove-workspace",
-      "/gsd-research-phase",
       "/gsd-resume-work",
       "/gsd-review",
       "/gsd-review-backlog",
-      "/gsd-scan",
       "/gsd-secure-phase",
-      "/gsd-session-report",
-      "/gsd-set-profile",
       "/gsd-settings",
       "/gsd-ship",
       "/gsd-sketch",
-      "/gsd-sketch-wrap-up",
       "/gsd-spec-phase",
       "/gsd-spike",
-      "/gsd-spike-wrap-up",
       "/gsd-stats",
       "/gsd-thread",
       "/gsd-ui-phase",
@@ -118,6 +100,7 @@
       "/gsd-update",
       "/gsd-validate-phase",
       "/gsd-verify-work",
+      "/gsd-workspace",
       "/gsd-workstreams"
     ],
     "workflows": [
@@ -142,6 +125,7 @@
       "discuss-phase.md",
       "do.md",
       "docs-update.md",
+      "edit-phase.md",
       "eval-review.md",
       "execute-phase.md",
       "execute-plan.md",
@@ -149,6 +133,7 @@
       "extract_learnings.md",
       "fast.md",
       "forensics.md",
+      "graduation.md",
       "health.md",
       "help.md",
       "import.md",
@@ -175,6 +160,7 @@
       "profile-user.md",
       "progress.md",
       "quick.md",
+      "reapply-patches.md",
       "remove-phase.md",
       "remove-workspace.md",
       "research-phase.md",
@@ -183,6 +169,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 +179,7 @@
       "spike-wrap-up.md",
       "spike.md",
       "stats.md",
+      "sync-skills.md",
       "transition.md",
       "ui-phase.md",
       "ui-review.md",
@@ -226,6 +215,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 +224,7 @@
       "project-skills-discovery.md",
       "questioning.md",
       "revision-loop.md",
+      "scout-codebase.md",
       "sketch-interactivity.md",
       "sketch-theme-system.md",
       "sketch-tooling.md",
@@ -253,29 +244,45 @@
       "workstream-flag.md"
     ],
     "cli_modules": [
+      "artifacts.cjs",
       "audit.cjs",
+      "command-aliases.generated.cjs",
       "commands.cjs",
       "config-schema.cjs",
       "config.cjs",
+      "context-utilization.cjs",
       "core.cjs",
+      "decisions.cjs",
       "docs.cjs",
+      "drift.cjs",
       "frontmatter.cjs",
+      "gap-checker.cjs",
       "graphify.cjs",
       "gsd2-import.cjs",
+      "init-command-router.cjs",
       "init.cjs",
+      "install-profiles.cjs",
       "intel.cjs",
       "learnings.cjs",
       "milestone.cjs",
       "model-profiles.cjs",
+      "phase-command-router.cjs",
       "phase.cjs",
+      "phases-command-router.cjs",
+      "planning-workspace.cjs",
       "profile-output.cjs",
       "profile-pipeline.cjs",
+      "roadmap-command-router.cjs",
       "roadmap.cjs",
       "schema-detect.cjs",
+      "secrets.cjs",
       "security.cjs",
+      "state-command-router.cjs",
       "state.cjs",
       "template.cjs",
       "uat.cjs",
+      "validate-command-router.cjs",
+      "verify-command-router.cjs",
       "verify.cjs",
       "workstream.cjs"
     ],

docs/INVENTORY.md

@@ -54,18 +54,29 @@ Full roster at `agents/gsd-*.md`. The "Primary doc" column flags whether [`docs/
 
 ---
 
-## Commands (82 shipped)
+## Commands (65 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.
 
+### Namespace Meta-Skills
+
+These six routers are descriptor-only entries that the model picks first; the body of each contains a routing table that points at the correct concrete sub-skill. They exist to keep the eager skill-listing token cost low while the full surface remains reachable. See [#2792](https://github.com/gsd-build/get-shit-done/issues/2792) for the rationale; the routing tables target the post-[#2790](https://github.com/gsd-build/get-shit-done/issues/2790) consolidated surface.
+
+| Command | Role | Source |
+|---------|------|--------|
+| `/gsd-ns-workflow` | Phase pipeline router — discuss / plan / execute / verify / phase / progress. | [commands/gsd/ns-workflow.md](../commands/gsd/ns-workflow.md) |
+| `/gsd-ns-project` | Project lifecycle router — milestones, audits, summary. | [commands/gsd/ns-project.md](../commands/gsd/ns-project.md) |
+| `/gsd-ns-review` | Quality-gate router — code review, debug, audit, security, eval, ui. | [commands/gsd/ns-review.md](../commands/gsd/ns-review.md) |
+| `/gsd-ns-context` | Codebase-intelligence router — map, graphify, docs, learnings. | [commands/gsd/ns-context.md](../commands/gsd/ns-context.md) |
+| `/gsd-ns-manage` | Management router — config, workspace, workstreams, thread, update, ship, inbox. | [commands/gsd/ns-manage.md](../commands/gsd/ns-manage.md) |
+| `/gsd-ns-ideate` | Exploration & capture router — explore, sketch, spike, spec, capture. | [commands/gsd/ns-ideate.md](../commands/gsd/ns-ideate.md) |
+
 ### Core Workflow
 
 | Command | Role | Source |
 |---------|------|--------|
 | `/gsd-new-project` | Initialize a new project with deep context gathering and PROJECT.md. | [commands/gsd/new-project.md](../commands/gsd/new-project.md) |
-| `/gsd-new-workspace` | Create an isolated workspace with repo copies and independent `.planning/`. | [commands/gsd/new-workspace.md](../commands/gsd/new-workspace.md) |
+| `/gsd-workspace` | Manage GSD workspaces — create (`--new`), list (`--list`), or remove (`--remove`) isolated workspace environments. | [commands/gsd/workspace.md](../commands/gsd/workspace.md) |
-| `/gsd-list-workspaces` | List active GSD workspaces and their status. | [commands/gsd/list-workspaces.md](../commands/gsd/list-workspaces.md) |
-| `/gsd-remove-workspace` | Remove a GSD workspace and clean up worktrees. | [commands/gsd/remove-workspace.md](../commands/gsd/remove-workspace.md) |
 | `/gsd-discuss-phase` | Gather phase context through adaptive questioning before planning. | [commands/gsd/discuss-phase.md](../commands/gsd/discuss-phase.md) |
 | `/gsd-spec-phase` | Socratic spec refinement producing a SPEC.md with falsifiable requirements. | [commands/gsd/spec-phase.md](../commands/gsd/spec-phase.md) |
 | `/gsd-ui-phase` | Generate UI design contract (UI-SPEC.md) for frontend phases. | [commands/gsd/ui-phase.md](../commands/gsd/ui-phase.md) |
@@ -73,36 +84,28 @@ Full roster at `commands/gsd/*.md`. The groupings below mirror `docs/COMMANDS.md
 | `/gsd-plan-phase` | Create detailed phase plan (PLAN.md) with verification loop. | [commands/gsd/plan-phase.md](../commands/gsd/plan-phase.md) |
 | `/gsd-plan-review-convergence` | Cross-AI plan convergence loop — replan with review feedback until no HIGH concerns remain (max 3 cycles). | [commands/gsd/plan-review-convergence.md](../commands/gsd/plan-review-convergence.md) |
 | `/gsd-ultraplan-phase` | [BETA] Offload plan phase to Claude Code's ultraplan cloud — drafts remotely, review in browser, import back via `/gsd-import`. Claude Code only. | [commands/gsd/ultraplan-phase.md](../commands/gsd/ultraplan-phase.md) |
-| `/gsd-spike` | Rapidly spike an idea with throwaway experiments to validate feasibility before planning. | [commands/gsd/spike.md](../commands/gsd/spike.md) |
+| `/gsd-spike` | Rapidly spike an idea with throwaway experiments; use `--wrap-up` to package findings as a persistent skill. | [commands/gsd/spike.md](../commands/gsd/spike.md) |
-| `/gsd-sketch` | Rapidly sketch UI/design ideas using throwaway HTML mockups with multi-variant exploration. | [commands/gsd/sketch.md](../commands/gsd/sketch.md) |
+| `/gsd-sketch` | Rapidly sketch UI/design ideas using throwaway HTML mockups; use `--wrap-up` to package findings. | [commands/gsd/sketch.md](../commands/gsd/sketch.md) |
-| `/gsd-research-phase` | Research how to implement a phase (standalone). | [commands/gsd/research-phase.md](../commands/gsd/research-phase.md) |
 | `/gsd-execute-phase` | Execute all plans in a phase with wave-based parallelization. | [commands/gsd/execute-phase.md](../commands/gsd/execute-phase.md) |
 | `/gsd-verify-work` | Validate built features through conversational UAT with auto-diagnosis. | [commands/gsd/verify-work.md](../commands/gsd/verify-work.md) |
 | `/gsd-ship` | Create PR, run review, and prepare for merge after verification. | [commands/gsd/ship.md](../commands/gsd/ship.md) |
-| `/gsd-next` | Automatically advance to the next logical step in the GSD workflow. | [commands/gsd/next.md](../commands/gsd/next.md) |
 | `/gsd-fast` | Execute a trivial task inline — no subagents, no planning overhead. | [commands/gsd/fast.md](../commands/gsd/fast.md) |
 | `/gsd-quick` | Execute a quick task with GSD guarantees (atomic commits, state tracking) but skip optional agents. | [commands/gsd/quick.md](../commands/gsd/quick.md) |
 | `/gsd-ui-review` | Retroactive 6-pillar visual audit of implemented frontend code. | [commands/gsd/ui-review.md](../commands/gsd/ui-review.md) |
-| `/gsd-code-review` | Review source files changed during a phase for bugs, security, and code-quality problems. | [commands/gsd/code-review.md](../commands/gsd/code-review.md) |
+| `/gsd-code-review` | Review source files changed during a phase for bugs, security, and code-quality problems; use `--fix` to auto-apply findings. | [commands/gsd/code-review.md](../commands/gsd/code-review.md) |
-| `/gsd-code-review-fix` | Auto-fix issues found by `/gsd-code-review`, committing each fix atomically. | [commands/gsd/code-review-fix.md](../commands/gsd/code-review-fix.md) |
 | `/gsd-eval-review` | Retroactively audit an executed AI phase's evaluation coverage; produces EVAL-REVIEW.md. | [commands/gsd/eval-review.md](../commands/gsd/eval-review.md) |
 
 ### Phase & Milestone Management
 
 | Command | Role | Source |
 |---------|------|--------|
-| `/gsd-add-phase` | Add phase to end of current milestone in roadmap. | [commands/gsd/add-phase.md](../commands/gsd/add-phase.md) |
+| `/gsd-phase` | CRUD for phases — add (default), insert (`--insert`), remove (`--remove`), or edit (`--edit`) phases in ROADMAP.md. | [commands/gsd/phase.md](../commands/gsd/phase.md) |
-| `/gsd-insert-phase` | Insert urgent work as decimal phase (e.g., 72.1) between existing phases. | [commands/gsd/insert-phase.md](../commands/gsd/insert-phase.md) |
-| `/gsd-remove-phase` | Remove a future phase from roadmap and renumber subsequent phases. | [commands/gsd/remove-phase.md](../commands/gsd/remove-phase.md) |
 | `/gsd-add-tests` | Generate tests for a completed phase based on UAT criteria and implementation. | [commands/gsd/add-tests.md](../commands/gsd/add-tests.md) |
-| `/gsd-list-phase-assumptions` | Surface Claude's assumptions about a phase approach before planning. | [commands/gsd/list-phase-assumptions.md](../commands/gsd/list-phase-assumptions.md) |
-| `/gsd-analyze-dependencies` | Analyze phase dependencies and suggest `Depends on` entries for ROADMAP.md. | [commands/gsd/analyze-dependencies.md](../commands/gsd/analyze-dependencies.md) |
 | `/gsd-validate-phase` | Retroactively audit and fill Nyquist validation gaps for a completed phase. | [commands/gsd/validate-phase.md](../commands/gsd/validate-phase.md) |
 | `/gsd-secure-phase` | Retroactively verify threat mitigations for a completed phase. | [commands/gsd/secure-phase.md](../commands/gsd/secure-phase.md) |
 | `/gsd-audit-milestone` | Audit milestone completion against original intent before archiving. | [commands/gsd/audit-milestone.md](../commands/gsd/audit-milestone.md) |
 | `/gsd-audit-uat` | Cross-phase audit of all outstanding UAT and verification items. | [commands/gsd/audit-uat.md](../commands/gsd/audit-uat.md) |
 | `/gsd-audit-fix` | Autonomous audit-to-fix pipeline — find issues, classify, fix, test, commit. | [commands/gsd/audit-fix.md](../commands/gsd/audit-fix.md) |
-| `/gsd-plan-milestone-gaps` | Create phases to close all gaps identified by milestone audit. | [commands/gsd/plan-milestone-gaps.md](../commands/gsd/plan-milestone-gaps.md) |
 | `/gsd-complete-milestone` | Archive completed milestone and prepare for next version. | [commands/gsd/complete-milestone.md](../commands/gsd/complete-milestone.md) |
 | `/gsd-new-milestone` | Start a new milestone cycle — update PROJECT.md and route to requirements. | [commands/gsd/new-milestone.md](../commands/gsd/new-milestone.md) |
 | `/gsd-milestone-summary` | Generate a comprehensive project summary from milestone artifacts. | [commands/gsd/milestone-summary.md](../commands/gsd/milestone-summary.md) |
@@ -116,30 +119,22 @@ Full roster at `commands/gsd/*.md`. The groupings below mirror `docs/COMMANDS.md
 
 | Command | Role | Source |
 |---------|------|--------|
-| `/gsd-progress` | Check project progress, show context, and route to next action. | [commands/gsd/progress.md](../commands/gsd/progress.md) |
+| `/gsd-progress` | Check project progress, show context, and route to next action; use `--next` to advance automatically or `--do` to run a freeform task. | [commands/gsd/progress.md](../commands/gsd/progress.md) |
+| `/gsd-capture` | Capture ideas, tasks, notes, and seeds — todo (default), `--note`, `--backlog`, `--seed`, or `--list` pending todos. | [commands/gsd/capture.md](../commands/gsd/capture.md) |
 | `/gsd-stats` | Display project statistics — phases, plans, requirements, git metrics, timeline. | [commands/gsd/stats.md](../commands/gsd/stats.md) |
-| `/gsd-session-report` | Generate a session report with token usage estimates, work summary, outcomes. | [commands/gsd/session-report.md](../commands/gsd/session-report.md) |
 | `/gsd-pause-work` | Create context handoff when pausing work mid-phase. | [commands/gsd/pause-work.md](../commands/gsd/pause-work.md) |
 | `/gsd-resume-work` | Resume work from previous session with full context restoration. | [commands/gsd/resume-work.md](../commands/gsd/resume-work.md) |
 | `/gsd-explore` | Socratic ideation and idea routing — think through ideas before committing. | [commands/gsd/explore.md](../commands/gsd/explore.md) |
-| `/gsd-do` | Route freeform text to the right GSD command automatically. | [commands/gsd/do.md](../commands/gsd/do.md) |
-| `/gsd-note` | Zero-friction idea capture — append, list, or promote notes to todos. | [commands/gsd/note.md](../commands/gsd/note.md) |
-| `/gsd-add-todo` | Capture idea or task as todo from current conversation context. | [commands/gsd/add-todo.md](../commands/gsd/add-todo.md) |
-| `/gsd-check-todos` | List pending todos and select one to work on. | [commands/gsd/check-todos.md](../commands/gsd/check-todos.md) |
-| `/gsd-add-backlog` | Add an idea to the backlog parking lot (999.x numbering). | [commands/gsd/add-backlog.md](../commands/gsd/add-backlog.md) |
 | `/gsd-review-backlog` | Review and promote backlog items to active milestone. | [commands/gsd/review-backlog.md](../commands/gsd/review-backlog.md) |
-| `/gsd-plant-seed` | Capture a forward-looking idea with trigger conditions. | [commands/gsd/plant-seed.md](../commands/gsd/plant-seed.md) |
 | `/gsd-thread` | Manage persistent context threads for cross-session work. | [commands/gsd/thread.md](../commands/gsd/thread.md) |
 
 ### Codebase Intelligence
 
 | Command | Role | Source |
 |---------|------|--------|
-| `/gsd-map-codebase` | Analyze codebase with parallel mapper agents; produces `.planning/codebase/` documents. | [commands/gsd/map-codebase.md](../commands/gsd/map-codebase.md) |
+| `/gsd-map-codebase` | Analyze codebase with parallel mapper agents; use `--fast` for lightweight scan or `--query` for intel queries. | [commands/gsd/map-codebase.md](../commands/gsd/map-codebase.md) |
-| `/gsd-scan` | Rapid codebase assessment — lightweight alternative to `/gsd-map-codebase`. | [commands/gsd/scan.md](../commands/gsd/scan.md) |
-| `/gsd-intel` | Query, inspect, or refresh codebase intelligence files in `.planning/intel/`. | [commands/gsd/intel.md](../commands/gsd/intel.md) |
 | `/gsd-graphify` | Build, query, and inspect the project knowledge graph in `.planning/graphs/`. | [commands/gsd/graphify.md](../commands/gsd/graphify.md) |
-| `/gsd-extract-learnings` | Extract decisions, lessons, patterns, and surprises from completed phase artifacts. | [commands/gsd/extract_learnings.md](../commands/gsd/extract_learnings.md) |
+| `/gsd-extract-learnings` | Extract decisions, lessons, patterns, and surprises from completed phase artifacts. | [commands/gsd/extract-learnings.md](../commands/gsd/extract-learnings.md) |
 
 ### Review, Debug & Recovery
 
@@ -150,7 +145,6 @@ Full roster at `commands/gsd/*.md`. The groupings below mirror `docs/COMMANDS.md
 | `/gsd-forensics` | Post-mortem investigation for failed GSD workflows — analyzes git, artifacts, state. | [commands/gsd/forensics.md](../commands/gsd/forensics.md) |
 | `/gsd-health` | Diagnose planning directory health and optionally repair issues. | [commands/gsd/health.md](../commands/gsd/health.md) |
 | `/gsd-import` | Ingest external plans with conflict detection against project decisions. | [commands/gsd/import.md](../commands/gsd/import.md) |
-| `/gsd-from-gsd2` | Import a GSD-2 (`.gsd/`) project back to GSD v1 (`.planning/`) format. | [commands/gsd/from-gsd2.md](../commands/gsd/from-gsd2.md) |
 | `/gsd-inbox` | Triage and review all open GitHub issues and PRs against project templates. | [commands/gsd/inbox.md](../commands/gsd/inbox.md) |
 
 ### Docs, Profile & Utilities
@@ -159,20 +153,16 @@ Full roster at `commands/gsd/*.md`. The groupings below mirror `docs/COMMANDS.md
 |---------|------|--------|
 | `/gsd-docs-update` | Generate or update project documentation verified against the codebase. | [commands/gsd/docs-update.md](../commands/gsd/docs-update.md) |
 | `/gsd-ingest-docs` | Scan a repo for mixed ADRs/PRDs/SPECs/DOCs and bootstrap or merge the full `.planning/` setup with classification, synthesis, and conflicts report. | [commands/gsd/ingest-docs.md](../commands/gsd/ingest-docs.md) |
-| `/gsd-spike-wrap-up` | Package spike findings into a persistent project skill for future build conversations. | [commands/gsd/spike-wrap-up.md](../commands/gsd/spike-wrap-up.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-set-profile` | Switch model profile for GSD agents (quality/balanced/budget/inherit). | [commands/gsd/set-profile.md](../commands/gsd/set-profile.md) |
+| `/gsd-config` | Configure GSD settings — workflow toggles (default), advanced knobs (`--advanced`), integrations (`--integrations`), or model profile (`--profile`). | [commands/gsd/config.md](../commands/gsd/config.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-update` | Update GSD to latest version with changelog display. | [commands/gsd/update.md](../commands/gsd/update.md) |
+| `/gsd-update` | Update GSD to latest version; use `--sync` to sync skills across runtimes or `--reapply` to reapply local patches. | [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) |
-| `/gsd-join-discord` | Join the GSD Discord community. | [commands/gsd/join-discord.md](../commands/gsd/join-discord.md) |
 
 ---
 
-## Workflows (79 shipped)
+## Workflows (85 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.
 
@@ -180,14 +170,14 @@ Full roster at `get-shit-done/workflows/*.md`. Workflows are thin orchestrators
 |----------|------|------------|
 | `add-phase.md` | Add a new integer phase to the end of the current milestone in the roadmap. | `/gsd-add-phase` |
 | `add-tests.md` | Generate unit and E2E tests for a completed phase based on its artifacts. | `/gsd-add-tests` |
-| `add-todo.md` | Capture an idea or task that surfaces during a session as a structured todo. | `/gsd-add-todo`, `/gsd-add-backlog` |
+| `add-todo.md` | Capture an idea or task that surfaces during a session as a structured todo. | `/gsd-capture` (default), `/gsd-capture --backlog` |
 | `ai-integration-phase.md` | Orchestrate framework selection → AI research → domain research → eval planning into AI-SPEC.md. | `/gsd-ai-integration-phase` |
 | `analyze-dependencies.md` | Analyze ROADMAP.md phases for file overlap and semantic dependencies; suggest `Depends on` edges. | `/gsd-analyze-dependencies` |
 | `audit-fix.md` | Autonomous audit-to-fix pipeline — run audit, parse, classify, fix, test, commit. | `/gsd-audit-fix` |
 | `audit-milestone.md` | Verify milestone met its definition of done by aggregating phase verifications. | `/gsd-audit-milestone` |
 | `audit-uat.md` | Cross-phase audit of UAT and verification files; produces prioritized outstanding-items list. | `/gsd-audit-uat` |
 | `autonomous.md` | Drive milestone phases autonomously — all remaining, a range, or a single phase. | `/gsd-autonomous` |
-| `check-todos.md` | List pending todos, allow selection, load context, and route to the appropriate action. | `/gsd-check-todos` |
+| `check-todos.md` | List pending todos, allow selection, load context, and route to the appropriate action. | `/gsd-capture --list` |
 | `cleanup.md` | Archive accumulated phase directories from completed milestones. | `/gsd-cleanup` |
 | `code-review-fix.md` | Auto-fix issues from REVIEW.md via gsd-code-fixer with per-fix atomic commits. | `/gsd-code-review-fix` |
 | `code-review.md` | Review phase source changes via gsd-code-reviewer; produces REVIEW.md. | `/gsd-code-review` |
@@ -197,8 +187,9 @@ Full roster at `get-shit-done/workflows/*.md`. Workflows are thin orchestrators
 | `discuss-phase-assumptions.md` | Assumptions-mode discuss — extract implementation decisions via codebase-first analysis. | `/gsd-discuss-phase` (when `discuss_mode=assumptions`) |
 | `discuss-phase-power.md` | Power-user discuss — pre-generate all questions into a JSON state file + HTML UI. | `/gsd-discuss-phase --power` |
 | `discuss-phase.md` | Extract implementation decisions through iterative gray-area discussion. | `/gsd-discuss-phase` |
-| `do.md` | Route freeform text from the user to the best matching GSD command. | `/gsd-do` |
+| `do.md` | Route freeform text from the user to the best matching GSD command. | `/gsd-progress --do` |
 | `docs-update.md` | Generate, update, and verify canonical and hand-written project documentation. | `/gsd-docs-update` |
+| `edit-phase.md` | Edit any field of an existing phase in ROADMAP.md in place, preserving number and position. | `/gsd-phase --edit` |
 | `eval-review.md` | Retroactive audit of an implemented AI phase's evaluation coverage. | `/gsd-eval-review` |
 | `execute-phase.md` | Execute all plans in a phase using wave-based parallel execution. | `/gsd-execute-phase` |
 | `execute-plan.md` | Execute a phase prompt (PLAN.md) and create the outcome summary (SUMMARY.md). | `execute-phase.md` (per-plan subagent) |
@@ -206,6 +197,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` |
@@ -220,18 +212,19 @@ Full roster at `get-shit-done/workflows/*.md`. Workflows are thin orchestrators
 | `new-milestone.md` | Start a new milestone cycle — load project context, gather goals, update PROJECT.md/STATE.md. | `/gsd-new-milestone` |
 | `new-project.md` | Unified new-project flow — questioning, research (optional), requirements, roadmap. | `/gsd-new-project` |
 | `new-workspace.md` | Create an isolated workspace with repo worktrees/clones and an independent `.planning/`. | `/gsd-new-workspace` |
-| `next.md` | Detect current project state and automatically advance to the next logical step. | `/gsd-next` |
+| `next.md` | Detect current project state and automatically advance to the next logical step. | `/gsd-progress --next` |
 | `node-repair.md` | Autonomous repair operator for failed task verification; invoked by `execute-plan`. | `execute-plan.md` (recovery) |
-| `note.md` | Zero-friction idea capture — one Write call, one confirmation line. | `/gsd-note` |
+| `note.md` | Zero-friction idea capture — one Write call, one confirmation line. | `/gsd-capture --note` |
 | `pause-work.md` | Create structured `.planning/HANDOFF.json` and `.continue-here.md` handoff files. | `/gsd-pause-work` |
 | `plan-milestone-gaps.md` | Create all phases necessary to close gaps identified by `/gsd-audit-milestone`. | `/gsd-plan-milestone-gaps` |
 | `plan-phase.md` | Create executable PLAN.md files with integrated research and verification loop. | `/gsd-plan-phase`, `/gsd-quick` |
 | `plan-review-convergence.md` | Cross-AI plan convergence loop — replan with review feedback until no HIGH concerns remain. | `/gsd-plan-review-convergence` |
-| `plant-seed.md` | Capture a forward-looking idea as a structured seed file with trigger conditions. | `/gsd-plant-seed` |
+| `plant-seed.md` | Capture a forward-looking idea as a structured seed file with trigger conditions. | `/gsd-capture --seed` |
 | `pr-branch.md` | Create a clean branch for pull requests by filtering `.planning/` commits. | `/gsd-pr-branch` |
 | `profile-user.md` | Orchestrate the full developer profiling flow — consent, session scan, profile generation. | `/gsd-profile-user` |
 | `progress.md` | Progress rendering — project context, position, and next-action routing. | `/gsd-progress` |
 | `quick.md` | Quick-task execution with GSD guarantees (atomic commits, state tracking). | `/gsd-quick` |
+| `reapply-patches.md` | Reapply local modifications after a GSD update. | `/gsd-reapply-patches` |
 | `remove-phase.md` | Remove a future phase from the roadmap and renumber subsequent phases. | `/gsd-remove-phase` |
 | `remove-workspace.md` | Remove a GSD workspace and clean up worktrees. | `/gsd-remove-workspace` |
 | `research-phase.md` | Standalone phase research workflow (usually invoked via `plan-phase`). | `/gsd-research-phase` |
@@ -241,6 +234,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,7 +243,8 @@ 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` |
-| `transition.md` | Phase-boundary transition workflow — workstream checks, state advancement. | `execute-phase.md`, `/gsd-next` |
+| `sync-skills.md` | Cross-runtime GSD skill sync — diff and apply `gsd-*` skill directories across runtime roots. | `/gsd-update --sync` |
+| `transition.md` | Phase-boundary transition workflow — workstream checks, state advancement. | `execute-phase.md`, `/gsd-progress --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` |
 | `ultraplan-phase.md` | [BETA] Offload planning to Claude Code's ultraplan cloud; drafts remotely and imports back via `/gsd-import`. | `/gsd-ultraplan-phase` |
@@ -262,7 +258,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 +292,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,44 +338,61 @@ 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 (41 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 |
+| `command-aliases.generated.cjs` | Generated CJS alias/subcommand metadata for manifest-backed family routers |
 | `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 |
+| `context-utilization.cjs` | Pure classifier for `gsd-health --context` — turns (tokensUsed, contextWindow) into a `{ percent, state }` triage result against the 60%/70% fracture-point thresholds (#2792) |
+| `core.cjs` | Error handling, output formatting, shared utilities, runtime fallbacks; compatibility re-exports for planning-workspace helpers |
+| `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-command-router.cjs` | Thin CJS subcommand router adapter for `gsd-tools init` |
 | `init.cjs` | Compound context loading for each workflow type |
+| `install-profiles.cjs` | Install profile allowlist + skill staging for `--minimal` install (#2762); single source of truth for which `gsd-*` skills/agents land in runtime config dirs |
 | `intel.cjs` | Codebase intel store backing `/gsd-intel` and `gsd-intel-updater` |
 | `learnings.cjs` | Cross-phase learnings extraction for `/gsd-extract-learnings` |
 | `milestone.cjs` | Milestone archival, requirements marking |
 | `model-profiles.cjs` | Model profile resolution table (authoritative profile data) |
+| `phase-command-router.cjs` | Thin CJS subcommand router adapter for `gsd-tools phase` |
 | `phase.cjs` | Phase directory operations, decimal numbering, plan indexing |
+| `phases-command-router.cjs` | Thin CJS subcommand router adapter for `gsd-tools phases` |
+| `planning-workspace.cjs` | Planning path/workstream seam (`planningDir`, `planningPaths`, active-workstream routing, `.planning/.lock` orchestration) |
 | `profile-output.cjs` | Profile rendering, USER-PROFILE.md and dev-preferences.md generation |
 | `profile-pipeline.cjs` | User behavioral profiling data pipeline, session file scanning |
+| `roadmap-command-router.cjs` | Thin CJS subcommand router adapter for `gsd-tools roadmap` |
 | `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-command-router.cjs` | Thin CJS subcommand router adapter for `gsd-tools state` |
 | `state.cjs` | STATE.md parsing, updating, progression, metrics |
 | `template.cjs` | Template selection and filling with variable substitution |
 | `uat.cjs` | UAT file parsing, verification debt tracking, audit-uat support |
+| `validate-command-router.cjs` | Thin CJS subcommand router adapter for `gsd-tools validate` |
+| `verify-command-router.cjs` | Thin CJS subcommand router adapter for `gsd-tools verify` |
 | `verify.cjs` | Plan structure, phase completeness, reference, commit validation |
 | `workstream.cjs` | Workstream CRUD, migration, session-scoped active pointer |
 

docs/RELEASE-v1.39.0-rc.4.md

@@ -0,0 +1,84 @@
+# v1.39.0-rc.4 Release Notes
+
+Pre-release candidate. Published to npm under the `next` tag.
+
+```
+npx get-shit-done-cc@next
+```
+
+---
+
+## What's in this release
+
+### Added
+
+**`--minimal` install flag** (alias `--core-only`) (#2762)
+
+Writes only the six core skills needed to run the main workflow loop:
+`new-project`, `discuss-phase`, `plan-phase`, `execute-phase`, `help`, `update`.
+No `gsd-*` subagents are installed.
+
+| Mode | Cold-start system-prompt overhead |
+|------|-----------------------------------|
+| full (default) | ~12k tokens |
+| minimal | ~700 tokens |
+
+Useful for local LLMs with 32K–128K context windows. Sonnet 4.6 / Opus 4.7 users
+don't need it — the full surface is the right default for cloud models.
+
+The install manifest records `mode: "minimal" | "full"`. Run `gsd update` without
+`--minimal` at any time to expand to the full skill set.
+
+---
+
+### Fixed
+
+**Codex install no longer corrupts `~/.codex/config.toml`** (#2760)
+
+Four users confirmed the same breakage: the previous installer left
+`~/.codex/config.toml` in a state that Codex rejected on launch, with manual file
+cleanup as the only workaround.
+
+The installer now:
+
+- Strips legacy `[agents]` (single-bracket) and `[[agents]]` (sequence) blocks
+  unconditionally — both are invalid in the current Codex TOML schema, regardless of
+  whether a GSD marker is present.
+- Emits the GSD-managed hook in the shape the user's config already uses:
+  `[[hooks.<Event>]]` namespaced AoT if any existing hook uses that form, otherwise
+  top-level `[[hooks]]`.
+- Migrates any legacy `[hooks.<Event>]` (map format) to `[[hooks.<Event>]]` (array
+  format) during write.
+- Writes atomically via a temp file + `renameSync` — no partial writes.
+- Validates the post-write bytes with a strict TOML parser that rejects duplicate
+  keys, repeated table headers, trailing bytes after values, and unsupported value
+  types.
+- On any pre-write or write-time failure, restores the pre-install snapshot and aborts
+  with a clear error instead of warn-and-continue.
+
+---
+
+## Installing the pre-release
+
+```bash
+# npm
+npm install -g get-shit-done-cc@next
+
+# npx (one-shot)
+npx get-shit-done-cc@next
+```
+
+To pin to this exact RC:
+
+```bash
+npm install -g get-shit-done-cc@1.39.0-rc.4
+```
+
+---
+
+## What's next
+
+- Run `rc` again on the release branch to publish rc.5 if further fixes land before
+  finalization.
+- Run `finalize` on the release workflow to promote `1.39.0` to `latest` when the RC
+  is stable.

docs/RELEASE-v1.39.0-rc.5.md

@@ -0,0 +1,99 @@
+# v1.39.0-rc.5 Release Notes
+
+Pre-release candidate. Published to npm under the `next` tag.
+
+```bash
+npx get-shit-done-cc@next
+```
+
+---
+
+## What's in this release
+
+All fixes from rc.4, plus:
+
+### Fixed
+
+**Codex hooks migrator correctness hardening** (#2809)
+
+Five edge-cases in the `[[hooks.<Event>]]` → `[[hooks.<Event>.hooks]]` two-level nested
+schema migration path, discovered across five rounds of code review:
+
+| Finding | Fix |
+|---------|-----|
+| `parseHooksBody` used a bare regex (`/^([\w.]+)\s*=/`) that silently dropped hyphenated keys such as `status-message` and any quoted TOML key | Replaced with `parseTomlKey()`, the existing full TOML key parser |
+| `buildNestedBlock` unconditionally emitted `[[hooks.TYPE.hooks]]` even when no handler fields were present, producing an entry with `type = "command"` but no `command` | Added guard: matcher-only / handler-field-free sections emit only the event-entry block |
+| `legacyMapSections` filter used `section.path.startsWith('hooks.')` without checking the segment count, so three-segment tables like `[hooks.SessionStart.hooks]` were misclassified as event entries and re-emitted as bogus nested events | Now uses `section.segments.length === 2` (same fix previously applied to `staleNamespacedAotSections`) |
+| No regression test for quoted event names containing dots — `[[hooks."before.tool"]]` has a 2-segment path but 3 dot-parts, and a `split('.')` check would misclassify it | Regression test added; quoted-dot names are correctly treated as a single two-segment namespace |
+| Handler command path assertion in install tests used a regex (`/gsd-check-update\.js/`) rather than the exact absolute path | Strengthened to `assert.strictEqual` with `path.join(codexHome, 'hooks', 'gsd-check-update.js')` |
+
+---
+
+## What was in rc.4
+
+### Added
+
+**`--minimal` install flag** (alias `--core-only`) (#2762)
+
+Writes only the six core skills needed to run the main workflow loop:
+`new-project`, `discuss-phase`, `plan-phase`, `execute-phase`, `help`, `update`.
+No `gsd-*` subagents are installed.
+
+| Mode | Cold-start system-prompt overhead |
+|------|-----------------------------------|
+| full (default) | ~12k tokens |
+| minimal | ~700 tokens |
+
+Useful for local LLMs with 32K–128K context windows. Sonnet 4.6 / Opus 4.7 users
+don't need it — the full surface is the right default for cloud models.
+
+The install manifest records `mode: "minimal" | "full"`. Run `gsd update` without
+`--minimal` at any time to expand to the full skill set.
+
+### Fixed (rc.4)
+
+**Codex install no longer corrupts `~/.codex/config.toml`** (#2760)
+
+The installer now:
+
+- Strips legacy `[agents]` (single-bracket) and `[[agents]]` (sequence) blocks
+  unconditionally — both are invalid in the current Codex TOML schema, regardless of
+  whether a GSD marker is present.
+- Emits the GSD-managed hook in the shape the user's config already uses:
+  `[[hooks.<Event>]]` namespaced AoT if any existing hook uses that form, otherwise
+  top-level `[[hooks]]`.
+- Migrates any legacy `[hooks.<Event>]` (map format) to `[[hooks.<Event>]]` (array
+  format) during write.
+- Writes atomically via a temp file + `renameSync` — no partial writes.
+- Validates the post-write bytes with a strict TOML parser that rejects duplicate
+  keys, repeated table headers, trailing bytes after values, and unsupported value
+  types.
+- On any pre-write or write-time failure, restores the pre-install snapshot and aborts
+  with a clear error instead of warn-and-continue.
+
+---
+
+## Installing the pre-release
+
+```bash
+# npm
+npm install -g get-shit-done-cc@next
+
+# npx (one-shot)
+npx get-shit-done-cc@next
+```
+
+To pin to this exact RC:
+
+```bash
+npm install -g get-shit-done-cc@1.39.0-rc.5
+```
+
+---
+
+## What's next
+
+- Run `rc` again on the release branch to publish rc.6 if further fixes land before
+  finalization.
+- Run `finalize` on the release workflow to promote `1.39.0` to `latest` when the RC
+  is stable.