docs: fix malformed bold/code spans in CHANGELOG.md

Convert all `**text`** patterns (backtick before bold markers) to the correct **`text`** form (bold wrapping a code span) throughout the CHANGELOG.md sections introduced by this PR. Fixes 61 instances across narrative text and list items in the [Unreleased] and [1.36.0] sections. Resolves trek-e CHANGES_REQUESTED review (2026-04-20). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
fix(workflows): read AUTO_CHAIN via config-get when check auto-mode unavailable
2026-04-25 17:25:23 +02:00 · 2026-04-19 23:43:26 -04:00 · 2026-04-18 18:37:07 -04:00 · 2026-04-18 17:40:52 -04:00
27 changed files with 1002 additions and 540 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
--- a/docs/ARCHITECTURE.md
+++ b/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
@@ -129,6 +134,7 @@ Orchestration logic that commands reference. Contains the step-by-step process i
 ### 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 +147,7 @@ Specialized agent definitions with frontmatter specifying:
 Shared knowledge documents that workflows and agents `@-reference` (35 total):

 **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 +163,7 @@ Shared knowledge documents that workflows and agents `@-reference` (35 total):
 - `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 +198,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
@@ -204,43 +212,47 @@ Markdown templates for all planning artifacts. Used by `gsd-tools.cjs template f

 Runtime hooks that integrate with the host AI agent:

-| Hook | Event | Purpose |
-|------|-------|---------|
-| `gsd-statusline.js` | `statusLine` | Displays model, task, directory, and context usage bar |
-| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | Injects agent-facing context warnings at 35%/25% remaining |
-| `gsd-check-update.js` | `SessionStart` | Background check for new GSD versions |
-| `gsd-prompt-guard.js` | `PreToolUse` | Scans `.planning/` writes for prompt injection patterns (advisory) |
-| `gsd-workflow-guard.js` | `PreToolUse` | Detects file edits outside GSD workflow context (advisory, opt-in via `hooks.workflow_guard`) |
-| `gsd-read-guard.js` | `PreToolUse` | Advisory guard preventing Edit/Write on files not yet read in the session |
-| `gsd-session-state.sh` | `PostToolUse` | Session state tracking for shell-based runtimes |
-| `gsd-validate-commit.sh` | `PostToolUse` | Commit validation for conventional commit enforcement |
-| `gsd-phase-boundary.sh` | `PostToolUse` | Phase boundary detection for workflow transitions |
+
+| Hook                     | Event                       | Purpose                                                                                       |
+| ------------------------ | --------------------------- | --------------------------------------------------------------------------------------------- |
+| `gsd-statusline.js`      | `statusLine`                | Displays model, task, directory, and context usage bar                                        |
+| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | Injects agent-facing context warnings at 35%/25% remaining                                    |
+| `gsd-check-update.js`    | `SessionStart`              | Background check for new GSD versions                                                         |
+| `gsd-prompt-guard.js`    | `PreToolUse`                | Scans `.planning/` writes for prompt injection patterns (advisory)                            |
+| `gsd-workflow-guard.js`  | `PreToolUse`                | Detects file edits outside GSD workflow context (advisory, opt-in via `hooks.workflow_guard`) |
+| `gsd-read-guard.js`      | `PreToolUse`                | Advisory guard preventing Edit/Write on files not yet read in the session                     |
+| `gsd-session-state.sh`   | `PostToolUse`               | Session state tracking for shell-based runtimes                                               |
+| `gsd-validate-commit.sh` | `PostToolUse`               | Commit validation for conventional commit enforcement                                         |
+| `gsd-phase-boundary.sh`  | `PostToolUse`               | Phase boundary detection for workflow transitions                                             |
+

 ### CLI Tools (`get-shit-done/bin/`)

 Node.js CLI utility (`gsd-tools.cjs`) with 19 domain modules:

-| Module | Responsibility |
-|--------|---------------|
-| `core.cjs` | Error handling, output formatting, shared utilities |
-| `state.cjs` | STATE.md parsing, updating, progression, metrics |
-| `phase.cjs` | Phase directory operations, decimal numbering, plan indexing |
-| `roadmap.cjs` | ROADMAP.md parsing, phase extraction, plan progress |
-| `config.cjs` | config.json read/write, section initialization |
-| `verify.cjs` | Plan structure, phase completeness, reference, commit validation |
-| `template.cjs` | Template selection and filling with variable substitution |
-| `frontmatter.cjs` | YAML frontmatter CRUD operations |
-| `init.cjs` | Compound context loading for each workflow type |
-| `milestone.cjs` | Milestone archival, requirements marking |
-| `commands.cjs` | Misc commands (slug, timestamp, todos, scaffolding, stats) |
-| `model-profiles.cjs` | Model profile resolution table |
-| `security.cjs` | Path traversal prevention, prompt injection detection, safe JSON parsing, shell argument validation |
-| `uat.cjs` | UAT file parsing, verification debt tracking, audit-uat support |
-| `docs.cjs` | Docs-update workflow init, Markdown scanning, monorepo detection |
-| `workstream.cjs` | Workstream CRUD, migration, session-scoped active pointer |
-| `schema-detect.cjs` | Schema-drift detection for ORM patterns (Prisma, Drizzle, etc.) |
-| `profile-pipeline.cjs` | User behavioral profiling data pipeline, session file scanning |
-| `profile-output.cjs` | Profile rendering, USER-PROFILE.md and dev-preferences.md generation |
+
+| Module                 | Responsibility                                                                                      |
+| ---------------------- | --------------------------------------------------------------------------------------------------- |
+| `core.cjs`             | Error handling, output formatting, shared utilities                                                 |
+| `state.cjs`            | STATE.md parsing, updating, progression, metrics                                                    |
+| `phase.cjs`            | Phase directory operations, decimal numbering, plan indexing                                        |
+| `roadmap.cjs`          | ROADMAP.md parsing, phase extraction, plan progress                                                 |
+| `config.cjs`           | config.json read/write, section initialization                                                      |
+| `verify.cjs`           | Plan structure, phase completeness, reference, commit validation                                    |
+| `template.cjs`         | Template selection and filling with variable substitution                                           |
+| `frontmatter.cjs`      | YAML frontmatter CRUD operations                                                                    |
+| `init.cjs`             | Compound context loading for each workflow type                                                     |
+| `milestone.cjs`        | Milestone archival, requirements marking                                                            |
+| `commands.cjs`         | Misc commands (slug, timestamp, todos, scaffolding, stats)                                          |
+| `model-profiles.cjs`   | Model profile resolution table                                                                      |
+| `security.cjs`         | Path traversal prevention, prompt injection detection, safe JSON parsing, shell argument validation |
+| `uat.cjs`              | UAT file parsing, verification debt tracking, audit-uat support                                     |
+| `docs.cjs`             | Docs-update workflow init, Markdown scanning, monorepo detection                                    |
+| `workstream.cjs`       | Workstream CRUD, migration, session-scoped active pointer                                           |
+| `schema-detect.cjs`    | Schema-drift detection for ORM patterns (Prisma, Drizzle, etc.)                                     |
+| `profile-pipeline.cjs` | User behavioral profiling data pipeline, session file scanning                                      |
+| `profile-output.cjs`   | Profile rendering, USER-PROFILE.md and dev-preferences.md generation                                |
+

 ---

@@ -251,10 +263,10 @@ Node.js CLI utility (`gsd-tools.cjs`) with 19 domain modules:
 ```
 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)
@@ -265,25 +277,27 @@ 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)
 ```

 ### Agent Spawn Categories

-| Category | Agents | Parallelism |
-|----------|--------|-------------|
-| **Researchers** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4 parallel (stack, features, architecture, pitfalls); advisor spawns during discuss-phase |
-| **Synthesizers** | gsd-research-synthesizer | Sequential (after researchers complete) |
-| **Planners** | gsd-planner, gsd-roadmapper | Sequential |
-| **Checkers** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | Sequential (verification loop, max 3 iterations) |
-| **Executors** | gsd-executor | Parallel within waves, sequential across waves |
-| **Verifiers** | gsd-verifier | Sequential (after all executors complete) |
-| **Mappers** | gsd-codebase-mapper | 4 parallel (tech, arch, quality, concerns) |
-| **Debuggers** | gsd-debugger | Sequential (interactive) |
-| **Auditors** | gsd-ui-auditor, gsd-security-auditor | Sequential |
-| **Doc Writers** | gsd-doc-writer, gsd-doc-verifier | Sequential (writer then verifier) |
-| **Profilers** | gsd-user-profiler | Sequential |
-| **Analyzers** | gsd-assumptions-analyzer | Sequential (during discuss-phase) |
+
+| Category         | Agents                                                                                  | Parallelism                                                                               |
+| ---------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| **Researchers**  | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4 parallel (stack, features, architecture, pitfalls); advisor spawns during discuss-phase |
+| **Synthesizers** | gsd-research-synthesizer                                                                | Sequential (after researchers complete)                                                   |
+| **Planners**     | gsd-planner, gsd-roadmapper                                                             | Sequential                                                                                |
+| **Checkers**     | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor          | Sequential (verification loop, max 3 iterations)                                          |
+| **Executors**    | gsd-executor                                                                            | Parallel within waves, sequential across waves                                            |
+| **Verifiers**    | gsd-verifier                                                                            | Sequential (after all executors complete)                                                 |
+| **Mappers**      | gsd-codebase-mapper                                                                     | 4 parallel (tech, arch, quality, concerns)                                                |
+| **Debuggers**    | gsd-debugger                                                                            | Sequential (interactive)                                                                  |
+| **Auditors**     | gsd-ui-auditor, gsd-security-auditor                                                    | Sequential                                                                                |
+| **Doc Writers**  | gsd-doc-writer, gsd-doc-verifier                                                        | Sequential (writer then verifier)                                                         |
+| **Profilers**    | gsd-user-profiler                                                                       | Sequential                                                                                |
+| **Analyzers**    | gsd-assumptions-analyzer                                                                | Sequential (during discuss-phase)                                                         |
+

 ### Wave Execution Model

@@ -299,6 +313,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)
@@ -311,14 +326,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.

 ---
@@ -426,6 +440,7 @@ UI-SPEC.md (per phase) ───────────────────
 ```

 Equivalent paths for other runtimes:
+
 - **OpenCode:** `~/.config/opencode/` or `~/.opencode/`
 - **Kilo:** `~/.config/kilo/` or `~/.kilo/`
 - **Gemini CLI:** `~/.gemini/`
@@ -495,16 +510,16 @@ The installer (`bin/install.js`, ~3,000 lines) handles:
 2. **Location selection** — Global (`--global`) or local (`--local`)
 3. **File deployment** — Copies commands, workflows, references, templates, agents, hooks
 4. **Runtime adaptation** — Transforms file content per runtime:
-   - Claude Code: Uses as-is
-   - OpenCode: Converts commands/agents to OpenCode-compatible flat command + subagent format
-   - Kilo: Reuses the OpenCode conversion pipeline with Kilo config paths
-   - Codex: Generates TOML config + skills from commands
-   - Copilot: Maps tool names (Read→read, Bash→execute, etc.)
-   - Gemini: Adjusts hook event names (`AfterTool` instead of `PostToolUse`)
-   - Antigravity: Skills-first with Google model equivalents
-   - Trae: Skills-first install to `~/.trae` / `./.trae` with no `settings.json` or hook integration
-   - Cline: Writes `.clinerules` for rule-based integration
-   - Augment Code: Skills-first with full skill conversion and config management
+  - Claude Code: Uses as-is
+  - OpenCode: Converts commands/agents to OpenCode-compatible flat command + subagent format
+  - Kilo: Reuses the OpenCode conversion pipeline with Kilo config paths
+  - Codex: Generates TOML config + skills from commands
+  - Copilot: Maps tool names (Read→read, Bash→execute, etc.)
+  - Gemini: Adjusts hook event names (`AfterTool` instead of `PostToolUse`)
+  - Antigravity: Skills-first with Google model equivalents
+  - Trae: Skills-first install to `~/.trae` / `./.trae` with no `settings.json` or hook integration
+  - Cline: Writes `.clinerules` for rule-based integration
+  - Augment Code: Skills-first with full skill conversion and config management
 5. **Path normalization** — Replaces `~/.claude/` paths with runtime-specific paths
 6. **Settings integration** — Registers hooks in runtime's `settings.json`
 7. **Patch backup** — Since v1.17, backs up locally modified files to `gsd-local-patches/` for `/gsd-reapply-patches`
@@ -541,11 +556,13 @@ Runtime Engine (Claude Code / Gemini CLI)

 ### Context Monitor Thresholds

-| Remaining Context | Level | Agent Behavior |
-|-------------------|-------|----------------|
-| > 35% | Normal | No warning injected |
-| ≤ 35% | WARNING | "Avoid starting new complex work" |
-| ≤ 25% | CRITICAL | "Context nearly exhausted, inform user" |
+
+| Remaining Context | Level    | Agent Behavior                          |
+| ----------------- | -------- | --------------------------------------- |
+| > 35%             | Normal   | No warning injected                     |
+| ≤ 35%             | WARNING  | "Avoid starting new complex work"       |
+| ≤ 25%             | CRITICAL | "Context nearly exhausted, inform user" |
+

 Debounce: 5 tool uses between repeated warnings. Severity escalation (WARNING→CRITICAL) bypasses debounce.

@@ -560,12 +577,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
@@ -577,18 +596,20 @@ Debounce: 5 tool uses between repeated warnings. Severity escalation (WARNING→

 GSD supports multiple AI coding runtimes through a unified command/workflow architecture:

-| Runtime | Command Format | Agent System | Config Location |
-|---------|---------------|--------------|-----------------|
-| Claude Code | `/gsd-command` | Task spawning | `~/.claude/` |
-| OpenCode | `/gsd-command` | Subagent mode | `~/.config/opencode/` |
-| Kilo | `/gsd-command` | Subagent mode | `~/.config/kilo/` |
-| Gemini CLI | `/gsd-command` | Task spawning | `~/.gemini/` |
-| Codex | `$gsd-command` | Skills | `~/.codex/` |
-| Copilot | `/gsd-command` | Agent delegation | `~/.github/` |
-| Antigravity | Skills | Skills | `~/.gemini/antigravity/` |
-| Trae | Skills | Skills | `~/.trae/` |
-| Cline | Rules | Rules | `.clinerules` |
-| Augment Code | Skills | Skills | Augment config |
+
+| Runtime      | Command Format | Agent System     | Config Location          |
+| ------------ | -------------- | ---------------- | ------------------------ |
+| Claude Code  | `/gsd-command` | Task spawning    | `~/.claude/`             |
+| OpenCode     | `/gsd-command` | Subagent mode    | `~/.config/opencode/`    |
+| Kilo         | `/gsd-command` | Subagent mode    | `~/.config/kilo/`        |
+| Gemini CLI   | `/gsd-command` | Task spawning    | `~/.gemini/`             |
+| Codex        | `$gsd-command` | Skills           | `~/.codex/`              |
+| Copilot      | `/gsd-command` | Agent delegation | `~/.github/`             |
+| Antigravity  | Skills         | Skills           | `~/.gemini/antigravity/` |
+| Trae         | Skills         | Skills           | `~/.trae/`               |
+| Cline        | Rules          | Rules            | `.clinerules`            |
+| Augment Code | Skills         | Skills           | Augment config           |
+

 ### Abstraction Points

@@ -598,4 +619,4 @@ GSD supports multiple AI coding runtimes through a unified command/workflow arch
 4. **Path conventions** — Each runtime stores config in different directories
 5. **Model references** — `inherit` profile lets GSD defer to runtime's model selection

-The installer handles all translation at install time. Workflows and agents are written in Claude Code's native format and transformed during deployment.
+The installer handles all translation at install time. Workflows and agents are written in Claude Code's native format and transformed during deployment.
--- a/docs/CLI-TOOLS.md
+++ b/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:** 15 domain modules in `get-shit-done/bin/lib/`
+|                    |                                                                                                                                                                                                        |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Shipped path**   | `get-shit-done/bin/gsd-tools.cjs`                                                                                                                                                                      |
+| **Implementation** | 15 domain modules under `get-shit-done/bin/lib/`                                                                                                                                                       |
+| **Status**         | Maintained for parity tests and CJS-only entrypoints; `gsd-sdk query` / SDK registry are the supported path for new orchestration (see [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md)). |
+
+
+**Usage (CJS):**

-**Usage:**
 ```bash
 node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
 ```

-**Global Flags:**
-| Flag | Description |
-|------|-------------|
-| `--raw` | Machine-readable output (JSON or plain text, no formatting) |
-| `--cwd <path>` | Override working directory (for sandboxed subagents) |
-| `--ws <name>` | Target a specific workstream context (SDK only) |
+**Global flags (CJS):**
+
+
+| Flag           | Description                                                                  |
+| -------------- | ---------------------------------------------------------------------------- |
+| `--raw`        | Machine-readable output (JSON or plain text, no formatting)                  |
+| `--cwd <path>` | Override working directory (for sandboxed subagents)                         |
+| `--ws <name>`  | Workstream context (also honored when the SDK spawns this binary; see below) |
+
+
+---
+
+## SDK and programmatic access
+
+Use this when authoring workflows, not when you only need the command list below.
+
+**1. CLI — `gsd-sdk query <argv…>`**
+
+- Resolves argv with the same **longest-prefix** rules as the typed registry (`resolveQueryArgv` in `sdk/src/query/registry.ts`). Unregistered commands **fail fast** — use `node …/gsd-tools.cjs` only for handlers not in the registry.
+- Full matrix (CJS command → registry key, CLI-only tools, aliases, golden tiers): [sdk/src/query/QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md).
+
+**2. TypeScript — `@gsd-build/sdk` (`GSDTools`, `createRegistry`)**
+
+- `GSDTools` (used by `PhaseRunner`, `InitRunner`, and `GSD.createTools()`) always shells out to `gsd-tools.cjs` via `execFile` — there is no in-process registry path on this class. For typed, in-process dispatch use `createRegistry()` from `sdk/src/query/index.ts`, or invoke `gsd-sdk query` (see [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md)).
+- Conventions: mutation event wiring, `GSDError` vs `{ data: { error } }`, locks, and stubs — [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md).
+
+**CJS → SDK examples (same project directory):**
+
+
+| Legacy CJS                               | Preferred `gsd-sdk query` (examples) |
+| ---------------------------------------- | ------------------------------------ |
+| `node gsd-tools.cjs init phase-op 12`    | `gsd-sdk query init phase-op 12`     |
+| `node gsd-tools.cjs phase-plan-index 12` | `gsd-sdk query phase-plan-index 12`  |
+| `node gsd-tools.cjs state json`          | `gsd-sdk query state json`           |
+| `node gsd-tools.cjs roadmap analyze`     | `gsd-sdk query roadmap analyze`      |
+
+
+**SDK state reads:** `gsd-sdk query state json` / `state.json` and `gsd-sdk query state load` / `state.load` currently share one native handler (rebuilt STATE.md frontmatter — CJS `cmdStateJson`). The legacy CJS `state load` payload (`config`, `state_raw`, existence flags) is still **CLI-only** via `node …/gsd-tools.cjs state load` until a separate registry handler exists. Full routing and golden rules: [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md).
+
+**CLI-only (not in registry):** e.g. **graphify**, **from-gsd2** / **gsd2-import** — call `gsd-tools.cjs` until registered.
+
+**Mutation events (SDK):** `QUERY_MUTATION_COMMANDS` in `sdk/src/query/index.ts` lists commands that may emit structured events after a successful dispatch. Exceptions called out in QUERY-HANDLERS: `state validate` (read-only), `skill-manifest` (writes only with `--write`), `intel update` (stub).
+
+**Golden parity:** Policy and CJS↔SDK test categories are documented under **Golden parity** in [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md).

 ---

@@ -360,7 +402,7 @@ node gsd-tools.cjs audit-uat
 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]
@@ -370,20 +412,31 @@ node gsd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]

 ## Module Architecture

-| Module | File | Exports |
-|--------|------|---------|
-| Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`, shared utilities |
-| State | `lib/state.cjs` | All `state` subcommands, `state-snapshot` |
-| Phase | `lib/phase.cjs` | Phase CRUD, `find-phase`, `phase-plan-index`, `phases list` |
-| 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 |
-| Template | `lib/template.cjs` | Template selection and variable filling |
-| Frontmatter | `lib/frontmatter.cjs` | YAML frontmatter CRUD |
-| Init | `lib/init.cjs` | Compound context loading for all workflows |
-| Milestone | `lib/milestone.cjs` | Milestone archival, requirements marking |
-| Commands | `lib/commands.cjs` | Misc: slug, timestamp, todos, scaffold, stats, websearch |
-| Model Profiles | `lib/model-profiles.cjs` | Profile resolution table |
-| UAT | `lib/uat.cjs` | Cross-phase UAT/verification audit |
-| Profile Output | `lib/profile-output.cjs` | Developer profile formatting |
-| Profile Pipeline | `lib/profile-pipeline.cjs` | Session analysis pipeline |
+
+| Module           | File                       | Exports                                                     |
+| ---------------- | -------------------------- | ----------------------------------------------------------- |
+| Core             | `lib/core.cjs`             | `error()`, `output()`, `parseArgs()`, shared utilities      |
+| State            | `lib/state.cjs`            | All `state` subcommands, `state-snapshot`                   |
+| Phase            | `lib/phase.cjs`            | Phase CRUD, `find-phase`, `phase-plan-index`, `phases list` |
+| 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                    |
+| Template         | `lib/template.cjs`         | Template selection and variable filling                     |
+| Frontmatter      | `lib/frontmatter.cjs`      | YAML frontmatter CRUD                                       |
+| Init             | `lib/init.cjs`             | Compound context loading for all workflows                  |
+| Milestone        | `lib/milestone.cjs`        | Milestone archival, requirements marking                    |
+| Commands         | `lib/commands.cjs`         | Misc: slug, timestamp, todos, scaffold, stats, websearch    |
+| Model Profiles   | `lib/model-profiles.cjs`   | Profile resolution table                                    |
+| UAT              | `lib/uat.cjs`              | Cross-phase UAT/verification audit                          |
+| Profile Output   | `lib/profile-output.cjs`   | Developer profile formatting                                |
+| Profile Pipeline | `lib/profile-pipeline.cjs` | Session analysis pipeline                                   |
+
+
+---
+
+## 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
+
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -234,7 +234,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>
@@ -251,7 +251,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"]'
 ```

 ---
@@ -270,10 +270,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.
--- a/docs/README.md
+++ b/docs/README.md
@@ -6,17 +6,19 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md)

 ## Documentation Index

-| Document | Audience | Description |
-|----------|----------|-------------|
-| [Architecture](ARCHITECTURE.md) | Contributors, advanced users | System architecture, agent model, data flow, and internal design |
-| [Feature Reference](FEATURES.md) | All users | Complete feature and function documentation with requirements |
-| [Command Reference](COMMANDS.md) | All users | Every command with syntax, flags, options, and examples |
-| [Configuration Reference](CONFIGURATION.md) | All users | Full config schema, workflow toggles, model profiles, git branching |
-| [CLI Tools Reference](CLI-TOOLS.md) | Contributors, agent authors | `gsd-tools.cjs` programmatic API for workflows and agents |
-| [Agent Reference](AGENTS.md) | Contributors, advanced users | All 18 specialized agents — roles, tools, spawn patterns |
-| [User Guide](USER-GUIDE.md) | All users | Workflow walkthroughs, troubleshooting, and recovery |
-| [Context Monitor](context-monitor.md) | All users | Context window monitoring hook architecture |
-| [Discuss Mode](workflow-discuss-mode.md) | All users | Assumptions vs interview mode for discuss-phase |
+
+| Document                                    | Audience                     | Description                                                         |
+| ------------------------------------------- | ---------------------------- | ------------------------------------------------------------------- |
+| [Architecture](ARCHITECTURE.md)             | Contributors, advanced users | System architecture, agent model, data flow, and internal design    |
+| [Feature Reference](FEATURES.md)            | All users                    | Complete feature and function documentation with requirements       |
+| [Command Reference](COMMANDS.md)            | All users                    | Every command with syntax, flags, options, and examples             |
+| [Configuration Reference](CONFIGURATION.md) | All users                    | Full config schema, workflow toggles, model profiles, git branching |
+| [CLI Tools Reference](CLI-TOOLS.md)         | Contributors, agent authors  | CJS `gsd-tools.cjs` surface + `gsd-sdk query` / **SDK** guidance    |
+| [Agent Reference](AGENTS.md)                | Contributors, advanced users | All 18 specialized agents — roles, tools, spawn patterns            |
+| [User Guide](USER-GUIDE.md)                 | All users                    | Workflow walkthroughs, troubleshooting, and recovery                |
+| [Context Monitor](context-monitor.md)       | All users                    | Context window monitoring hook architecture                         |
+| [Discuss Mode](workflow-discuss-mode.md)    | All users                    | Assumptions vs interview mode for discuss-phase                     |
+

 ## Quick Links

@@ -26,4 +28,4 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md)
 - **All commands at a glance:** [Command Reference](COMMANDS.md)
 - **Configuring GSD:** [Configuration Reference](CONFIGURATION.md)
 - **How the system works internally:** [Architecture](ARCHITECTURE.md)
- **Contributing or extending:** [CLI Tools Reference](CLI-TOOLS.md) + [Agent Reference](AGENTS.md)
+- **Contributing or extending:** [CLI Tools Reference](CLI-TOOLS.md) + [Agent Reference](AGENTS.md)
--- a/docs/USER-GUIDE.md
+++ b/docs/USER-GUIDE.md
@@ -166,12 +166,14 @@ By default, `/gsd-discuss-phase` asks open-ended questions about your implementa
 **Enable:** Set `workflow.discuss_mode` to `'assumptions'` via `/gsd-settings`.

 **How it works:**
+
 1. Reads PROJECT.md, codebase mapping, and existing conventions
 2. Generates a structured list of assumptions (tech choices, patterns, file locations)
 3. Presents assumptions for you to confirm, correct, or expand
 4. Writes CONTEXT.md from confirmed assumptions

 **When to use:**
+
 - Experienced developers who already know their codebase well
 - Rapid iteration where open-ended questions slow you down
 - Projects where patterns are well-established and predictable
@@ -190,16 +192,19 @@ AI-generated frontends are visually inconsistent not because Claude Code is bad

 ### Commands

-| Command | Description |
-|---------|-------------|
-| `/gsd-ui-phase [N]` | Generate UI-SPEC.md design contract for a frontend phase |
-| `/gsd-ui-review [N]` | Retroactive 6-pillar visual audit of implemented UI |
+
+| Command              | Description                                              |
+| -------------------- | -------------------------------------------------------- |
+| `/gsd-ui-phase [N]`  | Generate UI-SPEC.md design contract for a frontend phase |
+| `/gsd-ui-review [N]` | Retroactive 6-pillar visual audit of implemented UI      |
+

 ### Workflow: `/gsd-ui-phase`

 **When to run:** After `/gsd-discuss-phase`, before `/gsd-plan-phase` — for phases with frontend/UI work.

 **Flow:**
+
 1. Reads CONTEXT.md, RESEARCH.md, REQUIREMENTS.md for existing decisions
 2. Detects design system state (shadcn components.json, Tailwind config, existing tokens)
 3. shadcn initialization gate — offers to initialize if React/Next.js/Vite project has none
@@ -217,6 +222,7 @@ AI-generated frontends are visually inconsistent not because Claude Code is bad
 **Standalone:** Works on any project, not just GSD-managed ones. If no UI-SPEC.md exists, audits against abstract 6-pillar standards.

 **6 Pillars (scored 1-4 each):**
+
 1. Copywriting — CTA labels, empty states, error states
 2. Visuals — focal points, visual hierarchy, icon accessibility
 3. Color — accent usage discipline, 60/30/10 compliance
@@ -228,10 +234,12 @@ AI-generated frontends are visually inconsistent not because Claude Code is bad

 ### Configuration

-| Setting | Default | Description |
-|---------|---------|-------------|
-| `workflow.ui_phase` | `true` | Generate UI design contracts for frontend phases |
-| `workflow.ui_safety_gate` | `true` | plan-phase prompts to run /gsd-ui-phase for frontend phases |
+
+| Setting                   | Default | Description                                                 |
+| ------------------------- | ------- | ----------------------------------------------------------- |
+| `workflow.ui_phase`       | `true`  | Generate UI design contracts for frontend phases            |
+| `workflow.ui_safety_gate` | `true`  | plan-phase prompts to run /gsd-ui-phase for frontend phases |
+

 Both follow the absent=enabled pattern. Disable via `/gsd-settings`.

@@ -249,6 +257,7 @@ The preset string becomes a first-class GSD planning artifact, reproducible acro
 ### Registry Safety Gate

 Third-party shadcn registries can inject arbitrary code. The safety gate requires:
+
 - `npx shadcn view {component}` — inspect before installing
 - `npx shadcn diff {component}` — compare against official

@@ -366,12 +375,14 @@ Workstreams let you work on multiple milestone areas concurrently without state

 ### Commands

-| Command | Purpose |
-|---------|---------|
-| `/gsd-workstreams create <name>` | Create a new workstream with isolated planning state |
-| `/gsd-workstreams switch <name>` | Switch active context to a different workstream |
-| `/gsd-workstreams list` | Show all workstreams and which is active |
-| `/gsd-workstreams complete <name>` | Mark a workstream as done and archive its state |
+
+| Command                            | Purpose                                              |
+| ---------------------------------- | ---------------------------------------------------- |
+| `/gsd-workstreams create <name>`   | Create a new workstream with isolated planning state |
+| `/gsd-workstreams switch <name>`   | Switch active context to a different workstream      |
+| `/gsd-workstreams list`            | Show all workstreams and which is active             |
+| `/gsd-workstreams complete <name>` | Mark a workstream as done and archive its state      |
+

 ### How It Works

@@ -394,6 +405,7 @@ All user-supplied file paths (`--text-file`, `--prd`) are validated to resolve w
 The `security.cjs` module scans for known injection patterns (role overrides, instruction bypasses, system tag injections) in user-supplied text before it enters planning artifacts.

 **Runtime Hooks:**
+
 - `gsd-prompt-guard.js` — Scans Write/Edit calls to `.planning/` for injection patterns (always active, advisory-only)
 - `gsd-workflow-guard.js` — Warns on file edits outside GSD workflow context (opt-in via `hooks.workflow_guard`)

@@ -526,86 +538,98 @@ For a focused assessment without full `/gsd-map-codebase` overhead:

 ### Core Workflow

-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| `/gsd-new-project` | Full project init: questions, research, requirements, roadmap | Start of a new project |
-| `/gsd-new-project --auto @idea.md` | Automated init from document | Have a PRD or idea doc ready |
-| `/gsd-discuss-phase [N]` | Capture implementation decisions | Before planning, to shape how it gets built |
-| `/gsd-ui-phase [N]` | Generate UI design contract | After discuss-phase, before plan-phase (frontend phases) |
-| `/gsd-plan-phase [N]` | Research + plan + verify | Before executing a phase |
-| `/gsd-execute-phase <N>` | Execute all plans in parallel waves | After planning is complete |
-| `/gsd-verify-work [N]` | Manual UAT with auto-diagnosis | After execution completes |
-| `/gsd-ship [N]` | Create PR from verified work | After verification passes |
-| `/gsd-fast <text>` | Inline trivial tasks — skips planning entirely | Typo fixes, config changes, small refactors |
-| `/gsd-next` | Auto-detect state and run next step | Anytime — "what should I do next?" |
-| `/gsd-ui-review [N]` | Retroactive 6-pillar visual audit | After execution or verify-work (frontend projects) |
-| `/gsd-audit-milestone` | Verify milestone met its definition of done | Before completing milestone |
-| `/gsd-complete-milestone` | Archive milestone, tag release | All phases verified |
-| `/gsd-new-milestone [name]` | Start next version cycle | After completing a milestone |
+
+| Command                            | Purpose                                                       | When to Use                                              |
+| ---------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------- |
+| `/gsd-new-project`                 | Full project init: questions, research, requirements, roadmap | Start of a new project                                   |
+| `/gsd-new-project --auto @idea.md` | Automated init from document                                  | Have a PRD or idea doc ready                             |
+| `/gsd-discuss-phase [N]`           | Capture implementation decisions                              | Before planning, to shape how it gets built              |
+| `/gsd-ui-phase [N]`                | Generate UI design contract                                   | After discuss-phase, before plan-phase (frontend phases) |
+| `/gsd-plan-phase [N]`              | Research + plan + verify                                      | Before executing a phase                                 |
+| `/gsd-execute-phase <N>`           | Execute all plans in parallel waves                           | After planning is complete                               |
+| `/gsd-verify-work [N]`             | Manual UAT with auto-diagnosis                                | After execution completes                                |
+| `/gsd-ship [N]`                    | Create PR from verified work                                  | After verification passes                                |
+| `/gsd-fast <text>`                 | Inline trivial tasks — skips planning entirely                | Typo fixes, config changes, small refactors              |
+| `/gsd-next`                        | Auto-detect state and run next step                           | Anytime — "what should I do next?"                       |
+| `/gsd-ui-review [N]`               | Retroactive 6-pillar visual audit                             | After execution or verify-work (frontend projects)       |
+| `/gsd-audit-milestone`             | Verify milestone met its definition of done                   | Before completing milestone                              |
+| `/gsd-complete-milestone`          | Archive milestone, tag release                                | All phases verified                                      |
+| `/gsd-new-milestone [name]`        | Start next version cycle                                      | After completing a milestone                             |
+

 ### Navigation

-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| `/gsd-progress` | Show status and next steps | Anytime -- "where am I?" |
-| `/gsd-resume-work` | Restore full context from last session | Starting a new session |
-| `/gsd-pause-work` | Save structured handoff (HANDOFF.json + continue-here.md) | Stopping mid-phase |
-| `/gsd-session-report` | Generate session summary with work and outcomes | End of session, stakeholder sharing |
-| `/gsd-help` | Show all commands | Quick reference |
-| `/gsd-update` | Update GSD with changelog preview | Check for new versions |
-| `/gsd-join-discord` | Open Discord community invite | Questions or community |
+
+| Command               | Purpose                                                   | When to Use                         |
+| --------------------- | --------------------------------------------------------- | ----------------------------------- |
+| `/gsd-progress`       | Show status and next steps                                | Anytime -- "where am I?"            |
+| `/gsd-resume-work`    | Restore full context from last session                    | Starting a new session              |
+| `/gsd-pause-work`     | Save structured handoff (HANDOFF.json + continue-here.md) | Stopping mid-phase                  |
+| `/gsd-session-report` | Generate session summary with work and outcomes           | End of session, stakeholder sharing |
+| `/gsd-help`           | Show all commands                                         | Quick reference                     |
+| `/gsd-update`         | Update GSD with changelog preview                         | Check for new versions              |
+| `/gsd-join-discord`   | Open Discord community invite                             | Questions or community              |
+

 ### Phase Management

-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| `/gsd-add-phase` | Append new phase to roadmap | Scope grows after initial planning |
-| `/gsd-insert-phase [N]` | Insert urgent work (decimal numbering) | Urgent fix mid-milestone |
-| `/gsd-remove-phase [N]` | Remove future phase and renumber | Descoping a feature |
-| `/gsd-list-phase-assumptions [N]` | Preview Claude's intended approach | Before planning, to validate direction |
-| `/gsd-analyze-dependencies` | Detect phase dependencies for ROADMAP.md | Before `/gsd-manager` when phases have empty `Depends on` |
-| `/gsd-plan-milestone-gaps` | Create phases for audit gaps | After audit finds missing items |
-| `/gsd-research-phase [N]` | Deep ecosystem research only | Complex or unfamiliar domain |
+
+| Command                           | Purpose                                  | When to Use                                               |
+| --------------------------------- | ---------------------------------------- | --------------------------------------------------------- |
+| `/gsd-add-phase`                  | Append new phase to roadmap              | Scope grows after initial planning                        |
+| `/gsd-insert-phase [N]`           | Insert urgent work (decimal numbering)   | Urgent fix mid-milestone                                  |
+| `/gsd-remove-phase [N]`           | Remove future phase and renumber         | Descoping a feature                                       |
+| `/gsd-list-phase-assumptions [N]` | Preview Claude's intended approach       | Before planning, to validate direction                    |
+| `/gsd-analyze-dependencies`       | Detect phase dependencies for ROADMAP.md | Before `/gsd-manager` when phases have empty `Depends on` |
+| `/gsd-plan-milestone-gaps`        | Create phases for audit gaps             | After audit finds missing items                           |
+| `/gsd-research-phase [N]`         | Deep ecosystem research only             | Complex or unfamiliar domain                              |
+

 ### Brownfield & Utilities

-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| `/gsd-map-codebase` | Analyze existing codebase (4 parallel agents) | Before `/gsd-new-project` on existing code |
-| `/gsd-scan [--focus area]` | Rapid single-focus codebase scan (1 agent) | Quick assessment of a specific area |
-| `/gsd-intel [query\|status\|diff\|refresh]` | Query codebase intelligence index | Look up APIs, deps, or architecture decisions |
-| `/gsd-explore [topic]` | Socratic ideation — think through an idea before committing | Exploring unfamiliar solution space |
-| `/gsd-quick` | Ad-hoc task with GSD guarantees | Bug fixes, small features, config changes |
-| `/gsd-autonomous` | Run remaining phases autonomously (`--from N`, `--to N`) | Hands-free multi-phase execution |
-| `/gsd-undo --last N\|--phase NN\|--plan NN-MM` | Safe git revert using phase manifest | Roll back a bad execution |
-| `/gsd-import --from <file>` | Ingest external plan with conflict detection | Import plans from teammates or other tools |
-| `/gsd-debug [desc]` | Systematic debugging with persistent state (`--diagnose` for no-fix mode) | When something breaks |
-| `/gsd-forensics` | Diagnostic report for workflow failures | When state, artifacts, or git history seem corrupted |
-| `/gsd-add-todo [desc]` | Capture an idea for later | Think of something during a session |
-| `/gsd-check-todos` | List pending todos | Review captured ideas |
-| `/gsd-settings` | Configure workflow toggles and model profile | Change model, toggle agents |
-| `/gsd-set-profile <profile>` | Quick profile switch | Change cost/quality tradeoff |
-| `/gsd-reapply-patches` | Restore local modifications after update | After `/gsd-update` if you had local edits |
+
+| Command                                      | Purpose                                                                   | When to Use                                          |
+| -------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `/gsd-map-codebase`                          | Analyze existing codebase (4 parallel agents)                             | Before `/gsd-new-project` on existing code           |
+| `/gsd-scan [--focus area]`                   | Rapid single-focus codebase scan (1 agent)                                | Quick assessment of a specific area                  |
+| `/gsd-intel [query|status|diff|refresh]`     | Query codebase intelligence index                                         | Look up APIs, deps, or architecture decisions        |
+| `/gsd-explore [topic]`                       | Socratic ideation — think through an idea before committing               | Exploring unfamiliar solution space                  |
+| `/gsd-quick`                                 | Ad-hoc task with GSD guarantees                                           | Bug fixes, small features, config changes            |
+| `/gsd-autonomous`                            | Run remaining phases autonomously (`--from N`, `--to N`)                  | Hands-free multi-phase execution                     |
+| `/gsd-undo --last N \| --phase NN \| --plan NN-MM` | Safe git revert using phase manifest                                      | Roll back a bad execution                            |
+| `/gsd-import --from <file>`                  | Ingest external plan with conflict detection                              | Import plans from teammates or other tools           |
+| `/gsd-debug [desc]`                          | Systematic debugging with persistent state (`--diagnose` for no-fix mode) | When something breaks                                |
+| `/gsd-forensics`                             | Diagnostic report for workflow failures                                   | When state, artifacts, or git history seem corrupted |
+| `/gsd-add-todo [desc]`                       | Capture an idea for later                                                 | Think of something during a session                  |
+| `/gsd-check-todos`                           | List pending todos                                                        | Review captured ideas                                |
+| `/gsd-settings`                              | Configure workflow toggles and model profile                              | Change model, toggle agents                          |
+| `/gsd-set-profile <profile>`                 | Quick profile switch                                                      | Change cost/quality tradeoff                         |
+| `/gsd-reapply-patches`                       | Restore local modifications after update                                  | After `/gsd-update` if you had local edits           |
+

 ### Code Quality & Review

-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| `/gsd-review --phase N` | Cross-AI peer review from external CLIs | Before executing, to validate plans |
-| `/gsd-code-review <N>` | Review source files changed in a phase for bugs and security issues | After execution, before verification |
-| `/gsd-code-review-fix <N>` | Auto-fix issues found by `/gsd-code-review` | After code review produces REVIEW.md |
-| `/gsd-audit-fix` | Autonomous audit-to-fix pipeline with classification and atomic commits | After UAT surfaces fixable issues |
-| `/gsd-pr-branch` | Clean PR branch filtering `.planning/` commits | Before creating PR with planning-free diff |
-| `/gsd-audit-uat` | Audit verification debt across all phases | Before milestone completion |
+
+| Command                    | Purpose                                                                 | When to Use                                |
+| -------------------------- | ----------------------------------------------------------------------- | ------------------------------------------ |
+| `/gsd-review --phase N`    | Cross-AI peer review from external CLIs                                 | Before executing, to validate plans        |
+| `/gsd-code-review <N>`     | Review source files changed in a phase for bugs and security issues     | After execution, before verification       |
+| `/gsd-code-review-fix <N>` | Auto-fix issues found by `/gsd-code-review`                             | After code review produces REVIEW.md       |
+| `/gsd-audit-fix`           | Autonomous audit-to-fix pipeline with classification and atomic commits | After UAT surfaces fixable issues          |
+| `/gsd-pr-branch`           | Clean PR branch filtering `.planning/` commits                          | Before creating PR with planning-free diff |
+| `/gsd-audit-uat`           | Audit verification debt across all phases                               | Before milestone completion                |
+

 ### Backlog & Threads

-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| `/gsd-add-backlog <desc>` | Add idea to backlog parking lot (999.x) | Ideas not ready for active planning |
-| `/gsd-review-backlog` | Promote/keep/remove backlog items | Before new milestone, to prioritize |
-| `/gsd-plant-seed <idea>` | Forward-looking idea with trigger conditions | Ideas that should surface at a future milestone |
-| `/gsd-thread [name]` | Persistent context threads | Cross-session work outside the phase structure |
+
+| Command                   | Purpose                                      | When to Use                                     |
+| ------------------------- | -------------------------------------------- | ----------------------------------------------- |
+| `/gsd-add-backlog <desc>` | Add idea to backlog parking lot (999.x)      | Ideas not ready for active planning             |
+| `/gsd-review-backlog`     | Promote/keep/remove backlog items            | Before new milestone, to prioritize             |
+| `/gsd-plant-seed <idea>`  | Forward-looking idea with trigger conditions | Ideas that should surface at a future milestone |
+| `/gsd-thread [name]`      | Persistent context threads                   | Cross-session work outside the phase structure  |
+

 ---

@@ -651,61 +675,73 @@ GSD stores project settings in `.planning/config.json`. Configure during `/gsd-n

 ### Core Settings

-| Setting | Options | Default | What it Controls |
-|---------|---------|---------|------------------|
-| `mode` | `interactive`, `yolo` | `interactive` | `yolo` auto-approves decisions; `interactive` confirms at each step |
-| `granularity` | `coarse`, `standard`, `fine` | `standard` | Phase granularity: how finely scope is sliced (3-5, 5-8, or 8-12 phases) |
-| `model_profile` | `quality`, `balanced`, `budget`, `inherit` | `balanced` | Model tier for each agent (see table below) |
+
+| Setting         | Options                                    | Default       | What it Controls                                                         |
+| --------------- | ------------------------------------------ | ------------- | ------------------------------------------------------------------------ |
+| `mode`          | `interactive`, `yolo`                      | `interactive` | `yolo` auto-approves decisions; `interactive` confirms at each step      |
+| `granularity`   | `coarse`, `standard`, `fine`               | `standard`    | Phase granularity: how finely scope is sliced (3-5, 5-8, or 8-12 phases) |
+| `model_profile` | `quality`, `balanced`, `budget`, `inherit` | `balanced`    | Model tier for each agent (see table below)                              |
+

 ### Planning Settings

-| Setting | Options | Default | What it Controls |
-|---------|---------|---------|------------------|
-| `planning.commit_docs` | `true`, `false` | `true` | Whether `.planning/` files are committed to git |
+
+| Setting                      | Options         | Default | What it Controls                                            |
+| ---------------------------- | --------------- | ------- | ----------------------------------------------------------- |
+| `planning.commit_docs`       | `true`, `false` | `true`  | Whether `.planning/` files are committed to git             |
 | `planning.search_gitignored` | `true`, `false` | `false` | Add `--no-ignore` to broad searches to include `.planning/` |

+
 > **Note:** If `.planning/` is in `.gitignore`, `commit_docs` is automatically `false` regardless of the config value.

 ### Workflow Toggles

-| Setting | Options | Default | What it Controls |
-|---------|---------|---------|------------------|
-| `workflow.research` | `true`, `false` | `true` | Domain investigation before planning |
-| `workflow.plan_check` | `true`, `false` | `true` | Plan verification loop (up to 3 iterations) |
-| `workflow.verifier` | `true`, `false` | `true` | Post-execution verification against phase goals |
-| `workflow.nyquist_validation` | `true`, `false` | `true` | Validation architecture research during plan-phase; 8th plan-check dimension |
-| `workflow.ui_phase` | `true`, `false` | `true` | Generate UI design contracts for frontend phases |
-| `workflow.ui_safety_gate` | `true`, `false` | `true` | plan-phase prompts to run /gsd-ui-phase for frontend phases |
-| `workflow.research_before_questions` | `true`, `false` | `false` | Run research before discussion questions instead of after |
-| `workflow.discuss_mode` | `standard`, `assumptions` | `standard` | Discussion style: open-ended questions vs. codebase-driven assumptions |
-| `workflow.skip_discuss` | `true`, `false` | `false` | Skip discuss-phase entirely in autonomous mode; writes minimal CONTEXT.md from ROADMAP phase goal |
-| `response_language` | language code | (none) | Agent response language for cross-phase consistency (e.g., `"pt"`, `"ko"`, `"ja"`) |
+
+| Setting                              | Options                   | Default    | What it Controls                                                                                  |
+| ------------------------------------ | ------------------------- | ---------- | ------------------------------------------------------------------------------------------------- |
+| `workflow.research`                  | `true`, `false`           | `true`     | Domain investigation before planning                                                              |
+| `workflow.plan_check`                | `true`, `false`           | `true`     | Plan verification loop (up to 3 iterations)                                                       |
+| `workflow.verifier`                  | `true`, `false`           | `true`     | Post-execution verification against phase goals                                                   |
+| `workflow.nyquist_validation`        | `true`, `false`           | `true`     | Validation architecture research during plan-phase; 8th plan-check dimension                      |
+| `workflow.ui_phase`                  | `true`, `false`           | `true`     | Generate UI design contracts for frontend phases                                                  |
+| `workflow.ui_safety_gate`            | `true`, `false`           | `true`     | plan-phase prompts to run /gsd-ui-phase for frontend phases                                       |
+| `workflow.research_before_questions` | `true`, `false`           | `false`    | Run research before discussion questions instead of after                                         |
+| `workflow.discuss_mode`              | `standard`, `assumptions` | `standard` | Discussion style: open-ended questions vs. codebase-driven assumptions                            |
+| `workflow.skip_discuss`              | `true`, `false`           | `false`    | Skip discuss-phase entirely in autonomous mode; writes minimal CONTEXT.md from ROADMAP phase goal |
+| `response_language`                  | language code             | (none)     | Agent response language for cross-phase consistency (e.g., `"pt"`, `"ko"`, `"ja"`)                |
+

 ### Hook Settings

-| Setting | Options | Default | What it Controls |
-|---------|---------|---------|------------------|
-| `hooks.context_warnings` | `true`, `false` | `true` | Context window usage warnings |
-| `hooks.workflow_guard` | `true`, `false` | `false` | Warn on file edits outside GSD workflow context |
+
+| Setting                  | Options         | Default | What it Controls                                |
+| ------------------------ | --------------- | ------- | ----------------------------------------------- |
+| `hooks.context_warnings` | `true`, `false` | `true`  | Context window usage warnings                   |
+| `hooks.workflow_guard`   | `true`, `false` | `false` | Warn on file edits outside GSD workflow context |
+

 Disable workflow toggles to speed up phases in familiar domains or when conserving tokens.

 ### Git Branching

-| Setting | Options | Default | What it Controls |
-|---------|---------|---------|------------------|
-| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | When and how branches are created |
-| `git.phase_branch_template` | Template string | `gsd/phase-{phase}-{slug}` | Branch name for phase strategy |
-| `git.milestone_branch_template` | Template string | `gsd/{milestone}-{slug}` | Branch name for milestone strategy |
-| `git.quick_branch_template` | Template string or `null` | `null` | Optional branch name for `/gsd-quick` tasks |
+
+| Setting                         | Options                      | Default                    | What it Controls                            |
+| ------------------------------- | ---------------------------- | -------------------------- | ------------------------------------------- |
+| `git.branching_strategy`        | `none`, `phase`, `milestone` | `none`                     | When and how branches are created           |
+| `git.phase_branch_template`     | Template string              | `gsd/phase-{phase}-{slug}` | Branch name for phase strategy              |
+| `git.milestone_branch_template` | Template string              | `gsd/{milestone}-{slug}`   | Branch name for milestone strategy          |
+| `git.quick_branch_template`     | Template string or `null`    | `null`                     | Optional branch name for `/gsd-quick` tasks |
+

 **Branching strategies explained:**

-| Strategy | Creates Branch | Scope | Best For |
-|----------|---------------|-------|----------|
-| `none` | Never | N/A | Solo development, simple projects |
-| `phase` | At each `execute-phase` | One phase per branch | Code review per phase, granular rollback |
-| `milestone` | At first `execute-phase` | All phases share one branch | Release branches, PR per version |
+
+| Strategy    | Creates Branch           | Scope                       | Best For                                 |
+| ----------- | ------------------------ | --------------------------- | ---------------------------------------- |
+| `none`      | Never                    | N/A                         | Solo development, simple projects        |
+| `phase`     | At each `execute-phase`  | One phase per branch        | Code review per phase, granular rollback |
+| `milestone` | At first `execute-phase` | All phases share one branch | Release branches, PR per version         |
+

 **Template variables:** `{phase}` = zero-padded number (e.g., "03"), `{slug}` = lowercase hyphenated name, `{milestone}` = version (e.g., "v1.0"), `{num}` / `{quick}` = quick task ID (e.g., "260317-abc").

@@ -719,21 +755,24 @@ Example quick-task branching:

 ### Model Profiles (Per-Agent Breakdown)

-| Agent | `quality` | `balanced` | `budget` | `inherit` |
-|-------|-----------|------------|----------|-----------|
-| gsd-planner | Opus | Opus | Sonnet | Inherit |
-| gsd-roadmapper | Opus | Sonnet | Sonnet | Inherit |
-| gsd-executor | Opus | Sonnet | Sonnet | Inherit |
-| gsd-phase-researcher | Opus | Sonnet | Haiku | Inherit |
-| gsd-project-researcher | Opus | Sonnet | Haiku | Inherit |
-| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Inherit |
-| gsd-debugger | Opus | Sonnet | Sonnet | Inherit |
-| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Inherit |
-| gsd-verifier | Sonnet | Sonnet | Haiku | Inherit |
-| gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit |
-| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit |
+
+| Agent                    | `quality` | `balanced` | `budget` | `inherit` |
+| ------------------------ | --------- | ---------- | -------- | --------- |
+| gsd-planner              | Opus      | Opus       | Sonnet   | Inherit   |
+| gsd-roadmapper           | Opus      | Sonnet     | Sonnet   | Inherit   |
+| gsd-executor             | Opus      | Sonnet     | Sonnet   | Inherit   |
+| gsd-phase-researcher     | Opus      | Sonnet     | Haiku    | Inherit   |
+| gsd-project-researcher   | Opus      | Sonnet     | Haiku    | Inherit   |
+| gsd-research-synthesizer | Sonnet    | Sonnet     | Haiku    | Inherit   |
+| gsd-debugger             | Opus      | Sonnet     | Sonnet   | Inherit   |
+| gsd-codebase-mapper      | Sonnet    | Haiku      | Haiku    | Inherit   |
+| gsd-verifier             | Sonnet    | Sonnet     | Haiku    | Inherit   |
+| gsd-plan-checker         | Sonnet    | Sonnet     | Haiku    | Inherit   |
+| gsd-integration-checker  | Sonnet    | Sonnet     | Haiku    | Inherit   |
+

 **Profile philosophy:**
+
 - **quality** -- Opus for all decision-making agents, Sonnet for read-only verification. Use when quota is available and the work is critical.
 - **balanced** -- Opus only for planning (where architecture decisions happen), Sonnet for everything else. The default for good reason.
 - **budget** -- Sonnet for anything that writes code, Haiku for research and verification. Use for high-volume work or less critical phases.
@@ -805,11 +844,13 @@ claude --dangerously-skip-permissions

 ### Speed vs Quality Presets

-| Scenario | Mode | Granularity | Profile | Research | Plan Check | Verifier |
-|----------|------|-------|---------|----------|------------|----------|
-| Prototyping | `yolo` | `coarse` | `budget` | off | off | off |
-| Normal dev | `interactive` | `standard` | `balanced` | on | on | on |
-| Production | `interactive` | `fine` | `quality` | on | on | on |
+
+| Scenario    | Mode          | Granularity | Profile    | Research | Plan Check | Verifier |
+| ----------- | ------------- | ----------- | ---------- | -------- | ---------- | -------- |
+| Prototyping | `yolo`        | `coarse`    | `budget`   | off      | off        | off      |
+| Normal dev  | `interactive` | `standard`  | `balanced` | on       | on         | on       |
+| Production  | `interactive` | `fine`      | `quality`  | on       | on         | on       |
+

 **Skipping discuss-phase in autonomous mode:** When running in `yolo` mode with well-established preferences already captured in PROJECT.md, set `workflow.skip_discuss: true` via `/gsd-settings`. This bypasses the discuss-phase entirely and writes a minimal CONTEXT.md derived from the ROADMAP phase goal. Useful when your PROJECT.md and conventions are comprehensive enough that discussion adds no new information.

@@ -844,6 +885,7 @@ cd ~/gsd-workspaces/feature-b
 ```

 Each workspace gets:
+
 - Its own `.planning/` directory (fully independent from source repos)
 - Git worktrees (default) or clones of specified repos
 - A `WORKSPACE.md` manifest tracking member repos
@@ -854,9 +896,9 @@ Each workspace gets:

 ### Programmatic CLI (`gsd-sdk query` vs `gsd-tools.cjs`)

-For automation and copy-paste from docs, prefer **`gsd-sdk query`** with a registered subcommand (see [CLI-TOOLS.md](CLI-TOOLS.md) and [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md)). The legacy **`node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs`** CLI remains supported for dual-mode operation.
+For automation and copy-paste from docs, prefer **`gsd-sdk query`** with a registered subcommand (see [CLI-TOOLS.md — SDK and programmatic access](CLI-TOOLS.md#sdk-and-programmatic-access) and [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md)). The legacy `node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs` CLI remains supported for dual-mode operation.

-**Not yet on `gsd-sdk query` (use CJS):** `state validate`, `state sync`, `audit-open`, `graphify`, `from-gsd2`, and any subcommand not listed in the registry.
+**CLI-only (not in the query registry):** **graphify**, **from-gsd2** / **gsd2-import** — call `gsd-tools.cjs` (see [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md)). **Two different `state` JSON shapes in the legacy CLI:** `state json` (frontmatter rebuild) vs `state load` (`config` + `state_raw` + flags). **`gsd-sdk query` today:** both `state.json` and `state.load` resolve to the frontmatter-rebuild handler — use `node …/gsd-tools.cjs state load` when you need the CJS `state load` shape. See [CLI-TOOLS.md](CLI-TOOLS.md#sdk-and-programmatic-access) and QUERY-HANDLERS.

 ### STATE.md Out of Sync

@@ -989,6 +1031,7 @@ If `npx get-shit-done-cc` fails due to npm outages or network restrictions, see
 When a workflow fails in a way that isn't obvious -- plans reference nonexistent files, execution produces unexpected results, or state seems corrupted -- run `/gsd-forensics` to generate a diagnostic report.

 **What it checks:**
+
 - Git history anomalies (orphaned commits, unexpected branch state, rebase artifacts)
 - Artifact integrity (missing or malformed planning files, broken cross-references)
 - State inconsistencies (ROADMAP status vs. actual file presence, config drift)
@@ -1123,22 +1166,24 @@ If the installer crashes with `EPERM: operation not permitted, scandir` on Windo

 ## Recovery Quick Reference

-| Problem | Solution |
-|---------|----------|
-| Lost context / new session | `/gsd-resume-work` or `/gsd-progress` |
-| Phase went wrong | `git revert` the phase commits, then re-plan |
-| Need to change scope | `/gsd-add-phase`, `/gsd-insert-phase`, or `/gsd-remove-phase` |
-| Milestone audit found gaps | `/gsd-plan-milestone-gaps` |
-| Something broke | `/gsd-debug "description"` (add `--diagnose` for analysis without fixes) |
-| STATE.md out of sync | `state validate` then `state sync` |
-| Workflow state seems corrupted | `/gsd-forensics` |
-| Quick targeted fix | `/gsd-quick` |
-| Plan doesn't match your vision | `/gsd-discuss-phase [N]` then re-plan |
-| Costs running high | `/gsd-set-profile budget` and `/gsd-settings` to toggle agents off |
-| Update broke local changes | `/gsd-reapply-patches` |
-| Want session summary for stakeholder | `/gsd-session-report` |
-| Don't know what step is next | `/gsd-next` |
-| Parallel execution build errors | Update GSD or set `parallelization.enabled: false` |
+
+| Problem                              | Solution                                                                 |
+| ------------------------------------ | ------------------------------------------------------------------------ |
+| Lost context / new session           | `/gsd-resume-work` or `/gsd-progress`                                    |
+| Phase went wrong                     | `git revert` the phase commits, then re-plan                             |
+| Need to change scope                 | `/gsd-add-phase`, `/gsd-insert-phase`, or `/gsd-remove-phase`            |
+| Milestone audit found gaps           | `/gsd-plan-milestone-gaps`                                               |
+| Something broke                      | `/gsd-debug "description"` (add `--diagnose` for analysis without fixes) |
+| STATE.md out of sync                 | `state validate` then `state sync`                                       |
+| Workflow state seems corrupted       | `/gsd-forensics`                                                         |
+| Quick targeted fix                   | `/gsd-quick`                                                             |
+| Plan doesn't match your vision       | `/gsd-discuss-phase [N]` then re-plan                                    |
+| Costs running high                   | `/gsd-set-profile budget` and `/gsd-settings` to toggle agents off       |
+| Update broke local changes           | `/gsd-reapply-patches`                                                   |
+| Want session summary for stakeholder | `/gsd-session-report`                                                    |
+| Don't know what step is next         | `/gsd-next`                                                              |
+| Parallel execution build errors      | Update GSD or set `parallelization.enabled: false`                       |
+

 ---

@@ -1182,3 +1227,4 @@ For reference, here is what GSD creates in your project:
      XX-UI-REVIEW.md     # Visual audit scores (from /gsd-ui-review)
  ui-reviews/             # Screenshots from /gsd-ui-review (gitignored)
 ```
+
--- a/docs/gsd-sdk-query-migration-blurb.md
+++ b/docs/gsd-sdk-query-migration-blurb.md
@@ -4,7 +4,7 @@ Copy-paste friendly for Discord and GitHub comments.

 ---

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

 **What users can expect**

--- a/docs/ja-JP/README.md
+++ b/docs/ja-JP/README.md
@@ -10,7 +10,7 @@ Get Shit Done（GSD）フレームワークの包括的なドキュメントで
 | [機能リファレンス](FEATURES.md) | 全ユーザー | 全機能の詳細ドキュメントと要件 |
 | [コマンドリファレンス](COMMANDS.md) | 全ユーザー | 全コマンドの構文、フラグ、オプション、使用例 |
 | [設定リファレンス](CONFIGURATION.md) | 全ユーザー | 設定スキーマ、ワークフロートグル、モデルプロファイル、Git ブランチ |
-| [CLI ツールリファレンス](CLI-TOOLS.md) | コントリビューター、エージェント作成者 | `gsd-tools.cjs` のプログラマティック API（ワークフローおよびエージェント向け） |
+| [CLI ツールリファレンス](CLI-TOOLS.md) | コントリビューター、エージェント作成者 | CJS `gsd-tools.cjs` と **`gsd-sdk query` / SDK** のガイド |
 | [エージェントリファレンス](AGENTS.md) | コントリビューター、上級ユーザー | 全18種の専門エージェント — 役割、ツール、スポーンパターン |
 | [ユーザーガイド](USER-GUIDE.md) | 全ユーザー | ワークフローのウォークスルー、トラブルシューティング、リカバリー |
 | [コンテキストモニター](context-monitor.md) | 全ユーザー | コンテキストウィンドウ監視フックのアーキテクチャ |
--- a/docs/ko-KR/README.md
+++ b/docs/ko-KR/README.md
@@ -12,7 +12,7 @@ Get Shit Done (GSD) 프레임워크의 종합 문서입니다. GSD는 AI 코딩
 | [Feature Reference](FEATURES.md) | 전체 사용자 | 요구사항이 포함된 전체 기능 및 함수 문서 |
 | [Command Reference](COMMANDS.md) | 전체 사용자 | 모든 명령어의 구문, 플래그, 옵션 및 예제 |
 | [Configuration Reference](CONFIGURATION.md) | 전체 사용자 | 전체 설정 스키마, 워크플로우 토글, 모델 프로필, git 브랜칭 |
-| [CLI Tools Reference](CLI-TOOLS.md) | 기여자, 에이전트 작성자 | 워크플로우 및 에이전트를 위한 `gsd-tools.cjs` 프로그래매틱 API |
+| [CLI Tools Reference](CLI-TOOLS.md) | 기여자, 에이전트 작성자 | CJS `gsd-tools.cjs` + **`gsd-sdk query`/SDK** 안내 |
 | [Agent Reference](AGENTS.md) | 기여자, 고급 사용자 | 18개 전문 에이전트의 역할, 도구, 스폰 패턴 |
 | [User Guide](USER-GUIDE.md) | 전체 사용자 | 워크플로우 안내, 문제 해결, 복구 방법 |
 | [Context Monitor](context-monitor.md) | 전체 사용자 | 컨텍스트 윈도우 모니터링 훅 아키텍처 |
--- a/docs/pt-BR/CLI-TOOLS.md
+++ b/docs/pt-BR/CLI-TOOLS.md
@@ -1,7 +1,7 @@
 # Referência de Ferramentas CLI

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

 ---

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

 为紧急插入计算下一个小数阶段编号。

-## 使用 gsd-tools
+## 使用 gsd-sdk query

 ```bash
 # 获取阶段 6 之后的下一个小数阶段
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phase next-decimal 6
+gsd-sdk query phase.next-decimal 6
 ```

 输出：
@@ -32,14 +32,13 @@ node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phase next-decimal 6
 ## 提取值

 ```bash
-DECIMAL_INFO=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phase next-decimal "${AFTER_PHASE}")
-DECIMAL_PHASE=$(printf '%s\n' "$DECIMAL_INFO" | jq -r '.next')
-BASE_PHASE=$(printf '%s\n' "$DECIMAL_INFO" | jq -r '.base_phase')
+DECIMAL_PHASE=$(gsd-sdk query phase.next-decimal "${AFTER_PHASE}" --pick next)
+BASE_PHASE=$(gsd-sdk query phase.next-decimal "${AFTER_PHASE}" --pick base_phase)
 ```

 或使用 --raw 标志：
 ```bash
-DECIMAL_PHASE=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phase next-decimal "${AFTER_PHASE}" --raw)
+DECIMAL_PHASE=$(gsd-sdk query phase.next-decimal "${AFTER_PHASE}" --raw)
 # 返回: 06.1
 ```

@@ -57,9 +56,9 @@ DECIMAL_PHASE=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phase next-
 小数阶段目录使用完整的小数编号：

 ```bash
-SLUG=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" generate-slug "$DESCRIPTION" --raw)
+SLUG=$(gsd-sdk query generate-slug "$DESCRIPTION" --raw)
 PHASE_DIR=".planning/phases/${DECIMAL_PHASE}-${SLUG}"
 mkdir -p "$PHASE_DIR"
 ```

-示例：`.planning/phases/06.1-fix-critical-auth-bug/`
+示例：`.planning/phases/06.1-fix-critical-auth-bug/`
--- a/docs/zh-CN/references/git-integration.md
+++ b/docs/zh-CN/references/git-integration.md
@@ -51,7 +51,7 @@ Phases:
 提交内容：

 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: initialize [project-name] ([N] phases)" --files .planning/
+gsd-sdk query commit "docs: initialize [project-name] ([N] phases)" .planning/
 ```

 </format>
@@ -129,7 +129,7 @@ SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
 提交内容：

 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
+gsd-sdk query commit "docs({phase}-{plan}): complete [plan-name] plan" .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
 ```

 **注意：** 代码文件不包含 - 已按任务提交。
@@ -149,7 +149,7 @@ Current: [task name]
 提交内容：

 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
+gsd-sdk query commit "wip: [phase-name] paused at task [X]/[Y]" .planning/
 ```

 </format>
--- a/docs/zh-CN/references/git-planning-commit.md
+++ b/docs/zh-CN/references/git-planning-commit.md
@@ -1,13 +1,15 @@
 # Git 规划提交

-使用 gsd-tools CLI 提交规划工件，它会自动检查 `commit_docs` 配置和 gitignore 状态。
+通过 `gsd-sdk query commit` 提交规划工件，它会自动检查 `commit_docs` 配置和 gitignore 状态（与旧版 `gsd-tools.cjs commit` 行为相同）。

 ## 通过 CLI 提交

-始终使用 `gsd-tools.cjs commit` 处理 `.planning/` 文件 — 它会自动处理 `commit_docs` 和 gitignore 检查：
+先传提交说明，再传文件路径（位置参数）。`commit` 不要使用 `--files`（该标志仅用于 `commit-to-subrepo`）。
+
+对 `.planning/` 文件始终使用此方式 —— 它会自动处理 `commit_docs` 与 gitignore 检查：

 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
+gsd-sdk query commit "docs({scope}): {description}" .planning/STATE.md .planning/ROADMAP.md
 ```

 如果 `commit_docs` 为 `false` 或 `.planning/` 被 gitignore，CLI 会返回 `skipped`（带原因）。无需手动条件检查。
@@ -17,7 +19,7 @@ node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs({scope}): {des
 将 `.planning/` 文件变更合并到上次提交：

 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "" --files .planning/codebase/*.md --amend
+gsd-sdk query commit "" .planning/codebase/*.md --amend
 ```

 ## 提交消息模式
@@ -35,4 +37,4 @@ node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "" --files .planning

 - config 中 `commit_docs: false`
 - `.planning/` 被 gitignore
- 无变更可提交（用 `git status --porcelain .planning/` 检查）
+- 无变更可提交（用 `git status --porcelain .planning/` 检查）
--- a/docs/zh-CN/references/planning-config.md
+++ b/docs/zh-CN/references/planning-config.md
@@ -36,19 +36,19 @@
 - 用户必须将 `.planning/` 添加到 `.gitignore`
 - 适用于：OSS 贡献、客户项目、保持规划私有

-**使用 gsd-tools.cjs（推荐）：**
+**使用 `gsd-sdk query`（推荐）：**

 ```bash
 # 提交时自动检查 commit_docs + gitignore：
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: update state" --files .planning/STATE.md
+gsd-sdk query commit "docs: update state" .planning/STATE.md

 # 通过 state load 加载配置（返回 JSON）：
-INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state load)
+INIT=$(gsd-sdk query state.load)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # commit_docs 在 JSON 输出中可用

 # 或使用包含 commit_docs 的 init 命令：
-INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init execute-phase "1")
+INIT=$(gsd-sdk query init.execute-phase "1")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # commit_docs 包含在所有 init 命令输出中
 ```
@@ -58,7 +58,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 **通过 CLI 提交（自动处理检查）：**

 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: update state" --files .planning/STATE.md
+gsd-sdk query commit "docs: update state" .planning/STATE.md
 ```

 CLI 在内部检查 `commit_docs` 配置和 gitignore 状态 —— 无需手动条件判断。
@@ -146,14 +146,14 @@ CLI 在内部检查 `commit_docs` 配置和 gitignore 状态 —— 无需手动

 使用 `init execute-phase` 返回所有配置为 JSON：
 ```bash
-INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init execute-phase "1")
+INIT=$(gsd-sdk query init.execute-phase "1")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # JSON 输出包含：branching_strategy, phase_branch_template, milestone_branch_template
 ```

 或使用 `state load` 获取配置值：
 ```bash
-INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state load)
+INIT=$(gsd-sdk query state.load)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # 从 JSON 解析 branching_strategy, phase_branch_template, milestone_branch_template
 ```
--- a/get-shit-done/references/planning-config.md
+++ b/get-shit-done/references/planning-config.md
@@ -54,7 +54,7 @@ Configuration options for `.planning/` directory behavior.
 - User must add `.planning/` to `.gitignore`
 - Useful for: OSS contributions, client projects, keeping planning private

-**Using gsd-tools.cjs (preferred):**
+**Using `gsd-sdk query` (preferred):**

 ```bash
 # Commit with automatic commit_docs + gitignore checks:
--- a/get-shit-done/references/universal-anti-patterns.md
+++ b/get-shit-done/references/universal-anti-patterns.md
@@ -34,7 +34,7 @@ Reference: `references/questioning.md` for the full anti-pattern list.

 ## State Management Anti-Patterns

-15. **No direct Write/Edit to STATE.md or ROADMAP.md for mutations.** Always use `gsd-tools.cjs` CLI commands (`state update`, `state advance-plan`, `roadmap update-status`) for mutations. Direct Write tool usage bypasses safe update logic and is unsafe in multi-session environments. Exception: first-time creation of STATE.md from template is allowed.
+15. **No direct Write/Edit to STATE.md or ROADMAP.md for mutations.** Always use `gsd-sdk query` for registered state/roadmap handlers (e.g. `state.update`, `state.advance-plan`, `roadmap.update-plan-progress`), or legacy `node …/gsd-tools.cjs` for CLI-only commands. Direct Write tool usage bypasses safe update logic and is unsafe in multi-session environments. Exception: first-time creation of STATE.md from template is allowed.

 ## Behavioral Rules

@@ -53,7 +53,7 @@ Reference: `references/questioning.md` for the full anti-pattern list.
 ## GSD-Specific Rules

 24. **Do not** check for `mode === 'auto'` or `mode === 'autonomous'` -- GSD uses `yolo` config flag. Check `yolo: true` for autonomous mode, absence or `false` for interactive mode.
-25. **Always use `gsd-tools.cjs`** (not `gsd-tools.js` or any other variant) -- GSD uses CommonJS for Node.js CLI compatibility.
+25. **Prefer `gsd-sdk query`** for orchestration when a handler exists; when shelling out to the legacy CLI, use **`gsd-tools.cjs`** (not `gsd-tools.js` or any other filename) — GSD ships the programmatic API as CommonJS for Node.js CLI compatibility.
 26. **Plan files MUST follow `{padded_phase}-{NN}-PLAN.md` pattern** (e.g., `01-01-PLAN.md`). Never use `PLAN-01.md`, `plan-01.md`, or any other variation -- gsd-tools detection depends on this exact pattern.
 27. **Do not start executing the next plan before writing the SUMMARY.md for the current plan** -- downstream plans may reference it via `@` includes.

--- a/get-shit-done/workflows/complete-milestone.md
+++ b/get-shit-done/workflows/complete-milestone.md
@@ -40,10 +40,8 @@ When a milestone completes:
 <step name="pre_close_artifact_audit">
 Before proceeding with milestone close, run the comprehensive open artifact audit.

-`audit-open` is not registered on `gsd-sdk query` yet; use the installed CJS CLI:
-
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" audit-open 2>/dev/null
+gsd-sdk query audit-open 2>/dev/null
 ```

 If the output contains open items (any section with count > 0):
@@ -59,7 +57,7 @@ These items are open. Choose an action:
 ```

 If user chooses [A] (Acknowledge):
-1. Re-run `audit-open --json` to get structured data
+1. Re-run `gsd-sdk query audit-open --json` to get structured data
 2. Write acknowledged items to STATE.md under `## Deferred Items` section:
   ```markdown
   ## Deferred Items
@@ -78,7 +76,7 @@ If user chooses [A] (Acknowledge):

 If output shows all clear (no open items): print `All artifact types clear.` and proceed.

-SECURITY: Audit JSON output is structured data from `audit-open` (gsd-tools.cjs) — validated and sanitized at source. When writing to STATE.md, item slugs and descriptions are sanitized via `sanitizeForDisplay()` before inclusion. Never inject raw user-supplied content into STATE.md without sanitization.
+SECURITY: Audit JSON output is structured data from the `audit-open` query handler (same JSON contract as legacy `gsd-tools.cjs audit-open`) — validated and sanitized at source. When writing to STATE.md, item slugs and descriptions are sanitized via `sanitizeForDisplay()` before inclusion. Never inject raw user-supplied content into STATE.md without sanitization.
 </step>

 <step name="verify_readiness">
--- a/get-shit-done/workflows/discuss-phase-assumptions.md
+++ b/get-shit-done/workflows/discuss-phase-assumptions.md
@@ -622,21 +622,20 @@ Check for auto-advance trigger:
     gsd-sdk query config-set workflow._auto_chain_active false 2>/dev/null
   fi
   ```
-3. Read chain flag and user preference:
+3. Read consolidated auto-mode (`active` = chain flag OR user preference):
   ```bash
-   AUTO_CHAIN=$(gsd-sdk query config-get workflow._auto_chain_active 2>/dev/null || echo "false")
-   AUTO_CFG=$(gsd-sdk query config-get workflow.auto_advance 2>/dev/null || echo "false")
+   AUTO_MODE=$(gsd-sdk query check auto-mode --pick active 2>/dev/null || echo "false")
   ```

-**If `--auto` flag present AND `AUTO_CHAIN` is not true:**
+**If `--auto` flag present AND `AUTO_MODE` is not true:**
 ```bash
 gsd-sdk query config-set workflow._auto_chain_active true
 ```

-**If `--auto` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true:**
+**If `--auto` flag present OR `AUTO_MODE` is true:**

 Display banner:
-```
+```text
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GSD ► AUTO-ADVANCING TO PLAN
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
--- a/get-shit-done/workflows/discuss-phase.md
+++ b/get-shit-done/workflows/discuss-phase.md
@@ -1223,18 +1223,17 @@ Check for auto-advance trigger:
     gsd-sdk query config-set workflow._auto_chain_active false 2>/dev/null
   fi
   ```
-3. Read both the chain flag and user preference:
+3. Read consolidated auto-mode (`active` = chain flag OR user preference):
   ```bash
-   AUTO_CHAIN=$(gsd-sdk query config-get workflow._auto_chain_active 2>/dev/null || echo "false")
-   AUTO_CFG=$(gsd-sdk query config-get workflow.auto_advance 2>/dev/null || echo "false")
+   AUTO_MODE=$(gsd-sdk query check auto-mode --pick active 2>/dev/null || echo "false")
   ```

-**If `--auto` or `--chain` flag present AND `AUTO_CHAIN` is not true:** Persist chain flag to config (handles direct usage without new-project):
+**If `--auto` or `--chain` flag present AND `AUTO_MODE` is not true:** Persist chain flag to config (handles direct usage without new-project):
 ```bash
 gsd-sdk query config-set workflow._auto_chain_active true
 ```

-**If `--auto` flag present OR `--chain` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true:**
+**If `--auto` flag present OR `--chain` flag present OR `AUTO_MODE` is true:**

 Display banner:
 ```
--- a/get-shit-done/workflows/execute-phase.md
+++ b/get-shit-done/workflows/execute-phase.md
@@ -846,13 +846,12 @@ Plans with `autonomous: false` require user interaction.

 **Auto-mode checkpoint handling:**

-Read auto-advance config (chain flag + user preference):
+Read auto-advance config (chain flag OR user preference — same boolean as `check.auto-mode`):
 ```bash
-AUTO_CHAIN=$(gsd-sdk query config-get workflow._auto_chain_active 2>/dev/null || echo "false")
-AUTO_CFG=$(gsd-sdk query config-get workflow.auto_advance 2>/dev/null || echo "false")
+AUTO_MODE=$(gsd-sdk query check auto-mode --pick active 2>/dev/null || echo "false")
 ```

-When executor returns a checkpoint AND (`AUTO_CHAIN` is `"true"` OR `AUTO_CFG` is `"true"`):
+When executor returns a checkpoint AND `AUTO_MODE` is `true`:
 - **human-verify** → Auto-spawn continuation agent with `{user_response}` = `"approved"`. Log `⚡ Auto-approved checkpoint`.
 - **decision** → Auto-spawn continuation agent with `{user_response}` = first option from checkpoint details. Log `⚡ Auto-selected: [option]`.
 - **human-action** → Present to user (existing behavior below). Auth gates cannot be automated.
@@ -1454,13 +1453,12 @@ STOP. Do not proceed to auto-advance or transition.
 **Auto-advance detection:**

 1. Parse `--auto` flag from $ARGUMENTS
-2. Read both the chain flag and user preference (chain flag already synced in init step):
+2. Read consolidated auto-mode (`active` = chain flag OR user preference; chain flag already synced in init step):
   ```bash
-   AUTO_CHAIN=$(gsd-sdk query config-get workflow._auto_chain_active 2>/dev/null || echo "false")
-   AUTO_CFG=$(gsd-sdk query config-get workflow.auto_advance 2>/dev/null || echo "false")
+   AUTO_MODE=$(gsd-sdk query check auto-mode --pick active 2>/dev/null || echo "false")
   ```

-**If `--auto` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true (AND verification passed with no gaps):**
+**If `--auto` flag present OR `AUTO_MODE` is true (AND verification passed with no gaps):**

 ```
 ╔══════════════════════════════════════════╗
@@ -1473,7 +1471,7 @@ Execute the transition workflow inline (do NOT use Task — orchestrator context

 Read and follow `~/.claude/get-shit-done/workflows/transition.md`, passing through the `--auto` flag so it propagates to the next phase invocation.

-**If none of `--auto`, `AUTO_CHAIN`, or `AUTO_CFG` is true:**
+**If neither `--auto` nor `AUTO_MODE` is true:**

 **STOP. Do not auto-advance. Do not execute transition. Do not plan next phase. Present options to the user and wait.**

--- a/get-shit-done/workflows/plan-phase.md
+++ b/get-shit-done/workflows/plan-phase.md
@@ -471,9 +471,11 @@ UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)

 **If UI-SPEC.md missing AND `UI_GATE_CFG` is `true`:**

-Read auto-chain state:
+Read ephemeral chain flag (same field as `check.auto-mode` → `auto_chain_active`). Prefer native `check auto-mode` when registered; otherwise read the persisted flag via `config-get` (see `workflow._auto_chain_active` in `sdk/src/query/config-mutation.ts`):
 ```bash
-AUTO_CHAIN=$(gsd-sdk query config-get workflow._auto_chain_active 2>/dev/null || echo "false")
+AUTO_CHAIN=$(gsd-sdk query check auto-mode --pick auto_chain_active 2>/dev/null \
+  || gsd-sdk query config-get workflow._auto_chain_active 2>/dev/null \
+  || echo "false")
 ```

 **If `AUTO_CHAIN` is `true` (running inside a `--chain` or `--auto` pipeline):**
--- a/get-shit-done/workflows/settings.md
+++ b/get-shit-done/workflows/settings.md
@@ -13,13 +13,21 @@ Ensure config exists and load current state:

 ```bash
 gsd-sdk query config-ensure-section
-GSD_CONFIG_PATH=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-path)
 INIT=$(gsd-sdk query state.load)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# `state.load` returns STATE frontmatter JSON from the SDK — it does not include `config_path`. Orchestrators may set `GSD_CONFIG_PATH` from init phase-op JSON; otherwise resolve the same path gsd-tools uses for flat vs active workstream (#2282).
+if [[ -z "${GSD_CONFIG_PATH:-}" ]]; then
+  if [[ -f .planning/active-workstream ]]; then
+    WS=$(tr -d '\n\r' < .planning/active-workstream)
+    GSD_CONFIG_PATH=".planning/workstreams/${WS}/config.json"
+  else
+    GSD_CONFIG_PATH=".planning/config.json"
+  fi
+fi
 ```

-Creates config.json (at the workstream-aware path) with defaults if missing and loads current config values.
-Store `$GSD_CONFIG_PATH` — all subsequent reads and writes use this path, not the hardcoded `.planning/config.json`, so active-workstream installs write to the correct location (#2282).
+Creates `config.json` (at the resolved path) with defaults if missing. `INIT` still holds `state.load` output for any step that needs STATE fields.
+Store `$GSD_CONFIG_PATH` — all subsequent reads and writes use this path, not a hardcoded `.planning/config.json`, so active-workstream installs target the correct file (#2282).
 </step>

 <step name="read_current">
--- a/get-shit-done/workflows/sketch.md
+++ b/get-shit-done/workflows/sketch.md
@@ -53,9 +53,7 @@ COMMIT_DOCS=$(gsd-sdk query config-get commit_docs 2>/dev/null || echo "true")

 **Otherwise:**

-**Text mode:** If TEXT_MODE is enabled (set in the banner step), replace AskUserQuestion calls with plain-text numbered lists — emit the options and ask the user to type the number of their choice.
-
-Before sketching anything, explore the design intent through conversation. Ask one question at a time — using AskUserQuestion in normal mode, or a plain-text numbered list if TEXT_MODE is active — with a paragraph of context and reasoning for each.
+Before sketching anything, explore the design intent through conversation. Ask one question at a time using AskUserQuestion, with a paragraph of context and reasoning for each.

 **Questions to cover (adapt to what the user has already shared):**

--- a/get-shit-done/workflows/update.md
+++ b/get-shit-done/workflows/update.md
@@ -388,8 +388,9 @@ installer does not know about and will delete during the wipe.
 **Do not use bash path-stripping (`${filepath#$RUNTIME_DIR/}`) or `node -e require()`
 inline** — those patterns fail when `$RUNTIME_DIR` is unset and the stripped
 relative path may not match manifest key format, which causes CUSTOM_COUNT=0
-even when custom files exist (bug #1997). Use `gsd-tools detect-custom-files`
-instead, which resolves paths reliably with Node.js `path.relative()`.
+even when custom files exist (bug #1997). Use `gsd-sdk query detect-custom-files`
+when `gsd-sdk` is on `PATH`, or the bundled `gsd-tools.cjs detect-custom-files`
+otherwise — both resolve paths reliably with Node.js `path.relative()`.

 First, resolve the config directory (`RUNTIME_DIR`) from the install scope
 detected in `get_installed_version`:
@@ -410,17 +411,20 @@ fi
 If `RUNTIME_DIR` is empty or does not exist, skip this step (no config dir to
 inspect).

-Otherwise, resolve the path to `gsd-tools.cjs` and run:
+Otherwise run `detect-custom-files` (prefer SDK when available):

 ```bash
 GSD_TOOLS="$RUNTIME_DIR/get-shit-done/bin/gsd-tools.cjs"
-if [ -f "$GSD_TOOLS" ] && [ -n "$RUNTIME_DIR" ]; then
+CUSTOM_JSON=''
+if [ -n "$RUNTIME_DIR" ] && command -v gsd-sdk >/dev/null 2>&1; then
+  CUSTOM_JSON=$(gsd-sdk query detect-custom-files --config-dir "$RUNTIME_DIR" 2>/dev/null)
+elif [ -f "$GSD_TOOLS" ] && [ -n "$RUNTIME_DIR" ]; then
  CUSTOM_JSON=$(node "$GSD_TOOLS" detect-custom-files --config-dir "$RUNTIME_DIR" 2>/dev/null)
-  CUSTOM_COUNT=$(echo "$CUSTOM_JSON" | node -e "process.stdin.resume();let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{console.log(JSON.parse(d).custom_count);}catch{console.log(0);}})" 2>/dev/null || echo "0")
-else
-  CUSTOM_COUNT=0
+fi
+if [ -z "$CUSTOM_JSON" ]; then
  CUSTOM_JSON='{"custom_files":[],"custom_count":0}'
 fi
+CUSTOM_COUNT=$(echo "$CUSTOM_JSON" | node -e "process.stdin.resume();let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{console.log(JSON.parse(d).custom_count);}catch{console.log(0);}})" 2>/dev/null || echo "0")
 ```

 **If `CUSTOM_COUNT` > 0:**
--- a/get-shit-done/workflows/verify-work.md
+++ b/get-shit-done/workflows/verify-work.md
@@ -464,7 +464,7 @@ Run phase artifact scan to surface any open items before marking phase verified:
 `audit-open` is CJS-only until registered on `gsd-sdk query`:

 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" audit-open --json 2>/dev/null
+gsd-sdk query audit-open --json 2>/dev/null
 ```

 Parse the JSON output. For the CURRENT PHASE ONLY, surface:
--- a/tests/read-guard.test.cjs
+++ b/tests/read-guard.test.cjs
@@ -28,7 +28,7 @@ const HOOK_PATH = path.join(__dirname, '..', 'hooks', 'gsd-read-guard.js');
 */
 function runHook(payload, envOverrides = {}) {
  const input = JSON.stringify(payload);
-  // Sanitize Claude Code env vars so positive-path tests work inside Claude Code sessions
+  // Sanitize CLAUDE_SESSION_ID so positive-path tests work inside Claude Code sessions
  const env = { ...process.env, CLAUDE_SESSION_ID: '', CLAUDECODE: '', ...envOverrides };
  try {
    const stdout = execFileSync(process.execPath, [HOOK_PATH], {