get-shit-done-cc 1.37.1 → 1.38.1

package/README.md

@@ -89,14 +89,11 @@ People who want to describe what they want and have it built correctly — witho
 
 Built-in quality gates catch real problems: schema drift detection flags ORM changes missing migrations, security enforcement anchors verification to threat models, and scope reduction detection prevents the planner from silently dropping your requirements.
 
-### v1.36.0 Highlights
+### v1.37.0 Highlights
 
-- **Knowledge graph integration** — `/gsd-graphify` brings knowledge graphs to planning agents for richer context connections
-- **SDK typed query foundation** — Registry-based `gsd-sdk query` command with classified errors and handlers for state, roadmap, phase lifecycle, and config
-- **TDD pipeline mode** — Opt-in test-driven development workflow with `--tdd` flag
-- **Context-window-aware prompt thinning** — Automatic prompt size reduction for sub-200K models
-- **Project skills awareness** — 9 GSD agents now discover and use project-scoped skills
-- **30+ bug fixes** — Worktree safety, state management, installer paths, and health check optimizations
+- **Spiking & sketching** — `/gsd-spike` runs 2–5 focused experiments with Given/When/Then verdicts; `/gsd-sketch` produces 2–3 interactive HTML mockup variants per design question — both store artifacts in `.planning/` and pair with wrap-up commands to package findings into project-local skills
+- **Agent size-budget enforcement** — Tiered line-count limits (XL: 1 600, Large: 1 000, Default: 500) keep agent prompts lean; violations surface in CI
+- **Shared boilerplate extraction** — Mandatory-initial-read and project-skills-discovery logic extracted to reference files, reducing duplication across a dozen agents
 
 ---
 
@@ -196,7 +193,7 @@ npx get-shit-done-cc --all --global      # Install to all directories
 
 Use `--global` (`-g`) or `--local` (`-l`) to skip the location prompt.
 Use `--claude`, `--opencode`, `--gemini`, `--kilo`, `--codex`, `--copilot`, `--cursor`, `--windsurf`, `--antigravity`, `--augment`, `--trae`, `--qwen`, `--codebuddy`, `--cline`, or `--all` to skip the runtime prompt.
-Use `--sdk` to also install the GSD SDK CLI (`gsd-sdk`) for headless autonomous execution.
+The GSD SDK CLI (`gsd-sdk`) is installed automatically (required by `/gsd-*` commands). Pass `--no-sdk` to skip the SDK install, or `--sdk` to force a reinstall.
 
 </details>
 
@@ -627,6 +624,7 @@ You're never locked in. The system adapts.
 | Command | What it does |
 |---------|--------------|
 | `/gsd-map-codebase [area]` | Analyze existing codebase before new-project |
+| `/gsd-ingest-docs [dir]` | Scan a repo of mixed ADRs, PRDs, SPECs, and DOCs and bootstrap or merge the full `.planning/` setup in one pass — parallel classification, synthesis with precedence rules, and a three-bucket conflicts report |
 
 ### Phase Management
 

package/agents/gsd-doc-classifier.md

@@ -0,0 +1,168 @@
+---
+name: gsd-doc-classifier
+description: Classifies a single planning document as ADR, PRD, SPEC, DOC, or UNKNOWN. Extracts title, scope summary, and cross-references. Spawned in parallel by /gsd-ingest-docs. Writes a JSON classification file and returns a one-line confirmation.
+tools: Read, Write, Grep, Glob
+color: yellow
+# hooks:
+#   PostToolUse:
+#     - matcher: "Write|Edit"
+#       hooks:
+#         - type: command
+#           command: "true"
+---
+
+<role>
+You are a GSD doc classifier. You read ONE document and write a structured classification to `.planning/intel/classifications/`. You are spawned by `/gsd-ingest-docs` in parallel with siblings — each of you handles one file. Your output is consumed by `gsd-doc-synthesizer`.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<required_reading>` block, use the `Read` tool to load every file listed there before doing anything else. That is your primary context.
+</role>
+
+<why_this_matters>
+Your classification drives extraction. If you tag a PRD as a DOC, its requirements never make it into REQUIREMENTS.md. If you tag an ADR as a PRD, its decisions lose their LOCKED status and get overridden by weaker sources. Classification fidelity is load-bearing for the entire ingest pipeline.
+</why_this_matters>
+
+<taxonomy>
+
+**ADR** (Architecture Decision Record)
+- One architectural or technical decision, locked once made
+- Hallmarks: `Status: Accepted|Proposed|Superseded`, numbered filename (`0001-`, `ADR-001-`), sections like `Context / Decision / Consequences`
+- Content: trade-off analysis ending in one chosen path
+- Produces: **locked decisions** (highest precedence by default)
+
+**PRD** (Product Requirements Document)
+- What the product/feature should do, from a user/business perspective
+- Hallmarks: user stories, acceptance criteria, success metrics, goals/non-goals, "as a user..." language
+- Content: requirements + scope, not implementation
+- Produces: **requirements** (mid precedence)
+
+**SPEC** (Technical Specification)
+- How something is built — APIs, schemas, contracts, non-functional requirements
+- Hallmarks: endpoint tables, request/response schemas, SLOs, protocol definitions, data models
+- Content: implementation contracts the system must honor
+- Produces: **technical constraints** (above PRD, below ADR)
+
+**DOC** (General Documentation)
+- Supporting context: guides, tutorials, design rationales, onboarding, runbooks
+- Hallmarks: prose-heavy, tutorial structure, explanations without a decision or requirement
+- Produces: **context only** (lowest precedence)
+
+**UNKNOWN**
+- Cannot be confidently placed in any of the above
+- Record observed signals and let the synthesizer or user decide
+
+</taxonomy>
+
+<process>
+
+<step name="parse_input">
+The prompt gives you:
+- `FILEPATH` — the document to classify (absolute path)
+- `OUTPUT_DIR` — where to write your JSON output (e.g., `.planning/intel/classifications/`)
+- `MANIFEST_TYPE` (optional) — if present, the manifest declared this file's type; treat as authoritative, skip heuristic+LLM classification
+- `MANIFEST_PRECEDENCE` (optional) — override precedence if declared
+</step>
+
+<step name="heuristic_classification">
+Before reading the file, apply fast filename/path heuristics:
+
+- Path matches `**/adr/**` or filename `ADR-*.md` or `0001-*.md`…`9999-*.md` → strong ADR signal
+- Path matches `**/prd/**` or filename `PRD-*.md` → strong PRD signal
+- Path matches `**/spec/**`, `**/specs/**`, `**/rfc/**` or filename `SPEC-*.md`/`RFC-*.md` → strong SPEC signal
+- Everything else → unclear, proceed to content analysis
+
+If `MANIFEST_TYPE` is provided, skip to `extract_metadata` with that type.
+</step>
+
+<step name="read_and_analyze">
+Read the file. Parse its frontmatter (if YAML) and scan the first 50 lines + any table-of-contents.
+
+**Frontmatter signals (authoritative if present):**
+- `type: adr|prd|spec|doc` → use directly
+- `status: Accepted|Proposed|Superseded|Draft` → ADR signal
+- `decision:` field → ADR
+- `requirements:` or `user_stories:` → PRD
+
+**Content signals:**
+- Contains `## Decision` + `## Consequences` sections → ADR
+- Contains `## User Stories` or `As a [user], I want` paragraphs → PRD
+- Contains endpoint/schema tables, OpenAPI snippets, protocol fields → SPEC
+- None of the above, prose only → DOC
+
+**Ambiguity rule:** If two types compete at roughly equal strength, pick the one with the highest-precedence signal (ADR > SPEC > PRD > DOC). Record the ambiguity in `notes`.
+
+**Confidence:**
+- `high` — frontmatter or filename convention + matching content signals
+- `medium` — content signals only, one dominant
+- `low` — signals conflict or are thin → classify as best guess but flag the low confidence
+
+If signals are too thin to choose, output `UNKNOWN` with `low` confidence and list observed signals in `notes`.
+</step>
+
+<step name="extract_metadata">
+Regardless of type, extract:
+
+- **title** — the document's H1, or the filename if no H1
+- **summary** — one sentence (≤ 30 words) describing the doc's subject
+- **scope** — list of concrete nouns the doc is about (systems, components, features)
+- **cross_refs** — list of other doc paths referenced by this doc (markdown links, filename mentions). Include both relative and absolute paths as-written.
+- **locked_markers** — for ADRs only: does status read `Accepted` (locked) vs `Proposed`/`Draft` (not locked)? Set `locked: true|false`.
+</step>
+
+<step name="write_output">
+Write to `{OUTPUT_DIR}/{slug}.json` where `slug` is the filename without extension (replace non-alphanumerics with `-`).
+
+JSON schema:
+
+```json
+{
+  "source_path": "{FILEPATH}",
+  "type": "ADR|PRD|SPEC|DOC|UNKNOWN",
+  "confidence": "high|medium|low",
+  "manifest_override": false,
+  "title": "...",
+  "summary": "...",
+  "scope": ["...", "..."],
+  "cross_refs": ["path/to/other.md", "..."],
+  "locked": true,
+  "precedence": null,
+  "notes": "Only populated when confidence is low or ambiguity was resolved"
+}
+```
+
+Field rules:
+- `manifest_override: true` only when `MANIFEST_TYPE` was provided
+- `locked`: always `false` unless type is `ADR` with `Accepted` status
+- `precedence`: `null` unless `MANIFEST_PRECEDENCE` was provided (then store the integer)
+- `notes`: omit or empty string when confidence is `high`
+
+**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
+</step>
+
+<step name="return_confirmation">
+Return one line to the orchestrator. No JSON, no document contents.
+
+```
+Classified: {filename} → {TYPE} ({confidence}){, LOCKED if true}
+```
+</step>
+
+</process>
+
+<anti_patterns>
+Do NOT:
+- Read the doc's transitive references — only classify what you were assigned
+- Invent classification types beyond the five defined
+- Output anything other than the one-line confirmation to the orchestrator
+- Downgrade confidence silently — when unsure, output `UNKNOWN` with signals in `notes`
+- Classify a `Proposed` or `Draft` ADR as `locked: true` — only `Accepted` counts as locked
+- Use markdown tables or prose in your JSON output — stick to the schema
+</anti_patterns>
+
+<success_criteria>
+- [ ] Exactly one JSON file written to OUTPUT_DIR
+- [ ] Schema matches the template above, all required fields present
+- [ ] Confidence level reflects the actual signal strength
+- [ ] `locked` is true only for Accepted ADRs
+- [ ] Confirmation line returned to orchestrator (≤ 1 line)
+</success_criteria>

package/agents/gsd-doc-synthesizer.md

@@ -0,0 +1,204 @@
+---
+name: gsd-doc-synthesizer
+description: Synthesizes classified planning docs into a single consolidated context. Applies precedence rules, detects cross-ref cycles, enforces LOCKED-vs-LOCKED hard-blocks, and writes INGEST-CONFLICTS.md with three buckets (auto-resolved, competing-variants, unresolved-blockers). Spawned by /gsd-ingest-docs.
+tools: Read, Write, Grep, Glob, Bash
+color: orange
+# hooks:
+#   PostToolUse:
+#     - matcher: "Write|Edit"
+#       hooks:
+#         - type: command
+#           command: "true"
+---
+
+<role>
+You are a GSD doc synthesizer. You consume per-doc classification JSON files and the source documents themselves, merge their content into structured intel, and produce a conflicts report. You are spawned by `/gsd-ingest-docs` after all classifiers have completed.
+
+You do NOT prompt the user. You do NOT write PROJECT.md, REQUIREMENTS.md, or ROADMAP.md — those are produced downstream by `gsd-roadmapper` using your output. Your job is synthesis + conflict surfacing.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<required_reading>` block, load every file listed there first — especially `references/doc-conflict-engine.md` which defines your conflict report format.
+</role>
+
+<why_this_matters>
+You are the precedence-enforcing layer. Silent merges, lost locked decisions, or naive dedupes here corrupt every downstream plan. When in doubt, surface the conflict rather than pick.
+</why_this_matters>
+
+<inputs>
+The prompt provides:
+- `CLASSIFICATIONS_DIR` — directory containing per-doc `*.json` files produced by `gsd-doc-classifier`
+- `INTEL_DIR` — where to write synthesized intel (typically `.planning/intel/`)
+- `CONFLICTS_PATH` — where to write `INGEST-CONFLICTS.md` (typically `.planning/INGEST-CONFLICTS.md`)
+- `MODE` — `new` or `merge`
+- `EXISTING_CONTEXT` (merge mode only) — list of paths to existing `.planning/` files to check against (ROADMAP.md, PROJECT.md, REQUIREMENTS.md, CONTEXT.md files)
+- `PRECEDENCE` — ordered list, default `["ADR", "SPEC", "PRD", "DOC"]`; may be overridden per-doc via the classification's `precedence` field
+</inputs>
+
+<precedence_rules>
+
+**Default ordering:** `ADR > SPEC > PRD > DOC`. Higher-precedence sources win when content contradicts.
+
+**Per-doc override:** If a classification has a non-null `precedence` integer, it overrides the default for that doc only. Lower integer = higher precedence.
+
+**LOCKED decisions:**
+- An ADR with `locked: true` produces decisions that cannot be auto-overridden by any source, including another LOCKED ADR.
+- **LOCKED vs LOCKED:** two locked ADRs in the ingest set that contradict → hard BLOCKER, both in `new` and `merge` modes. Never auto-resolve.
+- **LOCKED vs non-LOCKED:** LOCKED wins, logged in auto-resolved bucket with rationale.
+- **Merge mode, LOCKED in ingest vs existing locked decision in CONTEXT.md:** hard BLOCKER.
+
+**Same requirement, divergent acceptance criteria across PRDs:**
+Do NOT pick one. Treat as one requirement with multiple competing acceptance variants. Write all variants to the `competing-variants` bucket for user resolution.
+
+</precedence_rules>
+
+<process>
+
+<step name="load_classifications">
+Read every `*.json` in `CLASSIFICATIONS_DIR`. Build an in-memory index keyed by `source_path`. Count by type.
+
+If any classification is `UNKNOWN` with `low` confidence, note it — these will surface as unresolved-blockers (user must type-tag via manifest and re-run).
+</step>
+
+<step name="cycle_detection">
+Build a directed graph from `cross_refs`. Run cycle detection (DFS with three-color marking).
+
+If cycles exist:
+- Record each cycle as an unresolved-blocker entry
+- Do NOT proceed with synthesis on the cyclic set — synthesis loops produce garbage
+- Docs outside the cycle may still be synthesized
+
+**Cap:** Max traversal depth 50. If the ref graph exceeds this, abort with a BLOCKER entry directing user to shrink input via `--manifest`.
+</step>
+
+<step name="extract_per_type">
+For each classified doc, read the source and extract per-type content. Write per-type intel files to `INTEL_DIR`:
+
+- **ADRs** → `INTEL_DIR/decisions.md`
+  - One entry per ADR: title, source path, status (locked/proposed), decision statement, scope
+  - Preserve every decision separately; synthesis happens in the next step
+
+- **PRDs** → `INTEL_DIR/requirements.md`
+  - One entry per requirement: ID (derive `REQ-{slug}`), source PRD path, description, acceptance criteria, scope
+  - One PRD usually yields multiple requirements
+
+- **SPECs** → `INTEL_DIR/constraints.md`
+  - One entry per constraint: title, source path, type (api-contract | schema | nfr | protocol), content block
+
+- **DOCs** → `INTEL_DIR/context.md`
+  - Running notes keyed by topic; appended verbatim with source attribution
+
+Every entry must have `source: {path}` so downstream consumers can trace provenance.
+</step>
+
+<step name="detect_conflicts">
+Walk the extracted intel to find conflicts. Apply precedence rules to classify each into a bucket.
+
+**Conflict detection passes:**
+
+1. **LOCKED-vs-LOCKED ADR contradiction** — two ADRs with `locked: true` whose decision statements contradict on the same scope → `unresolved-blockers`
+2. **ADR-vs-existing locked CONTEXT.md (merge mode only)** — any ingest decision contradicts a decision in an existing `<decisions>` block marked locked → `unresolved-blockers`
+3. **PRD requirement overlap with different acceptance** — two PRDs define requirements on the same scope with non-identical acceptance criteria → `competing-variants`; preserve all variants
+4. **SPEC contradicts higher-precedence ADR** — SPEC asserts a technical decision contradicting a higher-precedence ADR decision → `auto-resolved` with ADR as winner, rationale logged
+5. **Lower-precedence contradicts higher** (non-locked) — `auto-resolved` with higher-precedence source winning
+6. **UNKNOWN-confidence-low docs** — `unresolved-blockers` (user must re-tag)
+7. **Cycle-detection blockers** (from previous step) — `unresolved-blockers`
+
+Apply the `doc-conflict-engine` severity semantics:
+- `unresolved-blockers` maps to [BLOCKER] — gate the workflow
+- `competing-variants` maps to [WARNING] — user must pick before routing
+- `auto-resolved` maps to [INFO] — recorded for transparency
+</step>
+
+<step name="write_conflicts_report">
+Write `CONFLICTS_PATH` using the format from `references/doc-conflict-engine.md`. Three buckets, plain text, no tables.
+
+Structure:
+
+```
+## Conflict Detection Report
+
+### BLOCKERS ({N})
+
+[BLOCKER] LOCKED ADR contradiction
+  Found: docs/adr/0004-db.md declares "Postgres" (Accepted)
+  Expected: docs/adr/0011-db.md declares "DynamoDB" (Accepted) — same scope "primary datastore"
+  → Resolve by marking one ADR Superseded, or set precedence in --manifest
+
+### WARNINGS ({N})
+
+[WARNING] Competing acceptance variants for REQ-user-auth
+  Found: docs/prd/auth-v1.md requires "email+password", docs/prd/auth-v2.md requires "SSO only"
+  Impact: Synthesis cannot pick without losing intent
+  → Choose one variant or split into two requirements before routing
+
+### INFO ({N})
+
+[INFO] Auto-resolved: ADR > SPEC on cache layer
+  Note: docs/adr/0007-cache.md (Accepted) chose Redis; docs/specs/cache-api.md assumed Memcached — ADR wins, SPEC updated to Redis in synthesized intel
+```
+
+Every entry requires `source:` references for every claim.
+</step>
+
+<step name="write_synthesis_summary">
+Write `INTEL_DIR/SYNTHESIS.md` — a human-readable summary of what was synthesized:
+
+- Doc counts by type
+- Decisions locked (count + source paths)
+- Requirements extracted (count, with IDs)
+- Constraints (count + type breakdown)
+- Context topics (count)
+- Conflicts: N blockers, N competing-variants, N auto-resolved
+- Pointer to `CONFLICTS_PATH` for detail
+- Pointer to per-type intel files
+
+This is the single entry point `gsd-roadmapper` reads.
+
+**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
+</step>
+
+<step name="return_confirmation">
+Return ≤ 10 lines to the orchestrator:
+
+```
+## Synthesis Complete
+
+Docs synthesized: {N} ({breakdown})
+Decisions locked: {N}
+Requirements: {N}
+Conflicts: {N} blockers, {N} variants, {N} auto-resolved
+
+Intel: {INTEL_DIR}/
+Report: {CONFLICTS_PATH}
+
+{If blockers > 0: "STATUS: BLOCKED — review report before routing"}
+{If variants > 0: "STATUS: AWAITING USER — competing variants need resolution"}
+{Else: "STATUS: READY — safe to route"}
+```
+
+Do NOT dump intel contents. The orchestrator reads the files directly.
+</step>
+
+</process>
+
+<anti_patterns>
+Do NOT:
+- Pick a winner between two LOCKED ADRs — always BLOCK
+- Merge competing PRD acceptance criteria into a single "combined" criterion — preserve all variants
+- Write PROJECT.md, REQUIREMENTS.md, ROADMAP.md, or STATE.md — those are the roadmapper's job
+- Skip cycle detection — synthesis loops produce garbage output
+- Use markdown tables in the conflicts report — violates the doc-conflict-engine contract
+- Auto-resolve by filename order, timestamp, or arbitrary tiebreaker — precedence rules only
+- Silently drop `UNKNOWN`-confidence-low docs — they must surface as blockers
+</anti_patterns>
+
+<success_criteria>
+- [ ] All classifications in CLASSIFICATIONS_DIR consumed
+- [ ] Cycle detection run on cross-ref graph
+- [ ] Per-type intel files written to INTEL_DIR
+- [ ] INGEST-CONFLICTS.md written with three buckets, format per `doc-conflict-engine.md`
+- [ ] SYNTHESIS.md written as entry point for downstream consumers
+- [ ] LOCKED-vs-LOCKED contradictions surface as BLOCKERs, never auto-resolved
+- [ ] Competing acceptance variants preserved, never merged
+- [ ] Confirmation returned (≤ 10 lines)
+</success_criteria>

package/bin/install.js

@@ -10,6 +10,8 @@ const crypto = require('crypto');
 const cyan = '\x1b[36m';
 const green = '\x1b[32m';
 const yellow = '\x1b[33m';
+const red = '\x1b[31m';
+const bold = '\x1b[1m';
 const dim = '\x1b[2m';
 const reset = '\x1b[0m';
 
@@ -77,6 +79,13 @@ const hasBoth = args.includes('--both'); // Legacy flag, keeps working
 const hasAll = args.includes('--all');
 const hasUninstall = args.includes('--uninstall') || args.includes('-u');
 const hasPortableHooks = args.includes('--portable-hooks') || process.env.GSD_PORTABLE_HOOKS === '1';
+const hasSdk = args.includes('--sdk');
+const hasNoSdk = args.includes('--no-sdk');
+
+if (hasSdk && hasNoSdk) {
+  console.error(`  ${yellow}Cannot specify both --sdk and --no-sdk${reset}`);
+  process.exit(1);
+}
 
 // Runtime selection - can be set by flags or interactive prompt
 let selectedRuntimes = [];
@@ -5818,6 +5827,7 @@ function install(isGlobal, runtime = 'claude') {
             let content = fs.readFileSync(srcFile, 'utf8');
             content = content.replace(/'\.claude'/g, configDirReplacement);
             content = content.replace(/\/\.claude\//g, `/${getDirName(runtime)}/`);
+            content = content.replace(/\.claude\//g, `${getDirName(runtime)}/`);
             if (isQwen) {
               content = content.replace(/CLAUDE\.md/g, 'QWEN.md');
               content = content.replace(/\bClaude Code\b/g, 'Qwen Code');
@@ -5943,6 +5953,7 @@ function install(isGlobal, runtime = 'claude') {
           let content = fs.readFileSync(srcFile, 'utf8');
           content = content.replace(/'\.claude'/g, configDirReplacement);
           content = content.replace(/\/\.claude\//g, `/${getDirName(runtime)}/`);
+          content = content.replace(/\.claude\//g, `${getDirName(runtime)}/`);
           content = content.replace(/\{\{GSD_VERSION\}\}/g, pkg.version);
           fs.writeFileSync(destFile, content);
           try { fs.chmodSync(destFile, 0o755); } catch (e) { /* Windows */ }
@@ -6626,6 +6637,179 @@ function promptLocation(runtimes) {
   });
 }
 
+/**
+ * Build `@gsd-build/sdk` from the in-repo `sdk/` source tree and install the
+ * resulting `gsd-sdk` binary globally so workflow commands that shell out to
+ * `gsd-sdk query …` succeed.
+ *
+ * We build from source rather than `npm install -g @gsd-build/sdk` because the
+ * npm-published package lags the source tree and shipping a stale SDK breaks
+ * every /gsd-* command that depends on newer query handlers.
+ *
+ * Skip if --no-sdk. Skip if already on PATH (unless --sdk was explicit).
+ * Failures are FATAL — we exit non-zero so install does not complete with a
+ * silently broken SDK (issue #2439). Set GSD_ALLOW_OFF_PATH=1 to downgrade the
+ * post-install PATH verification to a warning (exit code 2) for users with an
+ * intentionally restricted PATH who will wire things up manually.
+ */
+
+/**
+ * Resolve `gsd-sdk` on PATH. Uses `command -v` via `sh -c` on POSIX (portable
+ * across sh/bash/zsh) and `where` on Windows. Returns trimmed path or null.
+ */
+function resolveGsdSdk() {
+  const { spawnSync } = require('child_process');
+  if (process.platform === 'win32') {
+    const r = spawnSync('where', ['gsd-sdk'], { encoding: 'utf-8' });
+    if (r.status === 0 && r.stdout && r.stdout.trim()) {
+      return r.stdout.trim().split('\n')[0].trim();
+    }
+    return null;
+  }
+  const r = spawnSync('sh', ['-c', 'command -v gsd-sdk'], { encoding: 'utf-8' });
+  if (r.status === 0 && r.stdout && r.stdout.trim()) {
+    return r.stdout.trim();
+  }
+  return null;
+}
+
+/**
+ * Best-effort detection of the user's shell rc file for PATH remediation hints.
+ */
+function detectShellRc() {
+  const path = require('path');
+  const shell = process.env.SHELL || '';
+  const home = process.env.HOME || '~';
+  if (/\/zsh$/.test(shell)) return { shell: 'zsh', rc: path.join(home, '.zshrc') };
+  if (/\/bash$/.test(shell)) return { shell: 'bash', rc: path.join(home, '.bashrc') };
+  if (/\/fish$/.test(shell)) return { shell: 'fish', rc: path.join(home, '.config', 'fish', 'config.fish') };
+  return { shell: 'sh', rc: path.join(home, '.profile') };
+}
+
+/**
+ * Emit a red fatal banner and exit. Prints actionable PATH remediation when
+ * the global install succeeded but the bin dir is not on PATH.
+ *
+ * If exitCode is 2, this is the "off-PATH" case and GSD_ALLOW_OFF_PATH respect
+ * is applied by the caller; we only print.
+ */
+function emitSdkFatal(reason, { globalBin, exitCode }) {
+  const { shell, rc } = detectShellRc();
+  const bar = '━'.repeat(72);
+  const redBold = `${red}${bold}`;
+
+  console.error('');
+  console.error(`${redBold}${bar}${reset}`);
+  console.error(`${redBold}  ✗ GSD SDK install failed — /gsd-* commands will not work${reset}`);
+  console.error(`${redBold}${bar}${reset}`);
+  console.error(`  ${red}Reason:${reset} ${reason}`);
+
+  if (globalBin) {
+    console.error('');
+    console.error(`  ${yellow}gsd-sdk was installed to:${reset}`);
+    console.error(`    ${cyan}${globalBin}${reset}`);
+    console.error('');
+    console.error(`  ${yellow}Your shell's PATH does not include this directory.${reset}`);
+    console.error(`  Add it by running:`);
+    if (shell === 'fish') {
+      console.error(`    ${cyan}fish_add_path "${globalBin}"${reset}`);
+      console.error(`    (or append to ${rc})`);
+    } else {
+      console.error(`    ${cyan}echo 'export PATH="${globalBin}:$PATH"' >> ${rc}${reset}`);
+      console.error(`    ${cyan}source ${rc}${reset}`);
+    }
+    console.error('');
+    console.error(`  Then verify: ${cyan}command -v gsd-sdk${reset}`);
+    if (exitCode === 2) {
+      console.error('');
+      console.error(`  ${dim}(GSD_ALLOW_OFF_PATH=1 set → exit ${exitCode} instead of hard failure)${reset}`);
+    }
+  } else {
+    console.error('');
+    console.error(`  Build manually to retry:`);
+    console.error(`    ${cyan}cd <install-dir>/sdk && npm install && npm run build && npm install -g .${reset}`);
+  }
+
+  console.error(`${redBold}${bar}${reset}`);
+  console.error('');
+  process.exit(exitCode);
+}
+
+function installSdkIfNeeded() {
+  if (hasNoSdk) {
+    console.log(`\n  ${dim}Skipping GSD SDK install (--no-sdk)${reset}`);
+    return;
+  }
+
+  const { spawnSync } = require('child_process');
+  const path = require('path');
+  const fs = require('fs');
+
+  if (!hasSdk) {
+    const resolved = resolveGsdSdk();
+    if (resolved) {
+      console.log(`  ${green}✓${reset} GSD SDK already installed (gsd-sdk on PATH at ${resolved})`);
+      return;
+    }
+  }
+
+  // Locate the in-repo sdk/ directory relative to this installer file.
+  // For global npm installs this resolves inside the published package dir;
+  // for git-based installs (npx github:..., local clone) it resolves to the
+  // repo's sdk/ tree. Both contain the source tree because root package.json
+  // includes "sdk" in its `files` array.
+  const sdkDir = path.resolve(__dirname, '..', 'sdk');
+  const sdkPackageJson = path.join(sdkDir, 'package.json');
+
+  if (!fs.existsSync(sdkPackageJson)) {
+    emitSdkFatal(`SDK source tree not found at ${sdkDir}.`, { globalBin: null, exitCode: 1 });
+  }
+
+  console.log(`\n  ${cyan}Building GSD SDK from source (${sdkDir})…${reset}`);
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+  // 1. Install sdk build-time dependencies (tsc, etc.)
+  const installResult = spawnSync(npmCmd, ['install'], { cwd: sdkDir, stdio: 'inherit' });
+  if (installResult.status !== 0) {
+    emitSdkFatal('Failed to `npm install` in sdk/.', { globalBin: null, exitCode: 1 });
+  }
+
+  // 2. Compile TypeScript → sdk/dist/
+  const buildResult = spawnSync(npmCmd, ['run', 'build'], { cwd: sdkDir, stdio: 'inherit' });
+  if (buildResult.status !== 0) {
+    emitSdkFatal('Failed to `npm run build` in sdk/.', { globalBin: null, exitCode: 1 });
+  }
+
+  // 3. Install the built package globally so `gsd-sdk` lands on PATH.
+  const globalResult = spawnSync(npmCmd, ['install', '-g', '.'], { cwd: sdkDir, stdio: 'inherit' });
+  if (globalResult.status !== 0) {
+    emitSdkFatal('Failed to `npm install -g .` from sdk/.', { globalBin: null, exitCode: 1 });
+  }
+
+  // 4. Verify gsd-sdk is actually resolvable on PATH. npm's global bin dir is
+  //    not always on the current shell's PATH (Homebrew prefixes, nvm setups,
+  //    unconfigured npm prefix), so a zero exit status from `npm install -g`
+  //    alone is not proof of a working binary (issue #2439 root cause).
+  const resolved = resolveGsdSdk();
+  if (resolved) {
+    console.log(`  ${green}✓${reset} Built and installed GSD SDK from source (gsd-sdk resolved at ${resolved})`);
+    return;
+  }
+
+  // Off-PATH: resolve npm global bin dir for actionable remediation.
+  const prefixResult = spawnSync(npmCmd, ['config', 'get', 'prefix'], { encoding: 'utf-8' });
+  const prefix = prefixResult.status === 0 ? (prefixResult.stdout || '').trim() : null;
+  const globalBin = prefix
+    ? (process.platform === 'win32' ? prefix : path.join(prefix, 'bin'))
+    : null;
+
+  const allowOffPath = process.env.GSD_ALLOW_OFF_PATH === '1';
+  emitSdkFatal(
+    'Built and installed GSD SDK, but `gsd-sdk` is not on your PATH.',
+    { globalBin, exitCode: allowOffPath ? 2 : 1 },
+  );
+}
+
 /**
  * Install GSD for all selected runtimes
  */
@@ -6641,7 +6825,15 @@ function installAllRuntimes(runtimes, isGlobal, isInteractive) {
   const primaryStatuslineResult = results.find(r => statuslineRuntimes.includes(r.runtime));
 
   const finalize = (shouldInstallStatusline) => {
-    // Handle SDK installation before printing final summaries
+    // Build @gsd-build/sdk from the in-repo sdk/ source and install it globally
+    // so `gsd-sdk` lands on PATH. Every /gsd-* command shells out to
+    // `gsd-sdk query …`; without this, commands fail with "command not found:
+    // gsd-sdk". The npm-published @gsd-build/sdk is kept intentionally frozen
+    // at an older version; we always build from source so users get the SDK
+    // that matches the installed GSD version.
+    // Runs by default; skip with --no-sdk. Idempotent when already present.
+    installSdkIfNeeded();
+
     const printSummaries = () => {
       for (const result of results) {
         const useStatusline = statuslineRuntimes.includes(result.runtime) && shouldInstallStatusline;

package/commands/gsd/import.md

@@ -25,6 +25,7 @@ Future: `--prd` mode for PRD extraction is planned for a follow-up PR.
 @~/.claude/get-shit-done/workflows/import.md
 @~/.claude/get-shit-done/references/ui-brand.md
 @~/.claude/get-shit-done/references/gate-prompts.md
+@~/.claude/get-shit-done/references/doc-conflict-engine.md
 </execution_context>
 
 <context>