get-shit-done-cc 1.22.2 → 1.22.4

package/README.md

@@ -516,7 +516,7 @@ You're never locked in. The system adapts.
 | `/gsd:add-todo [desc]` | Capture idea for later |
 | `/gsd:check-todos` | List pending todos |
 | `/gsd:debug [desc]` | Systematic debugging with persistent state |
-| `/gsd:quick [--full]` | Execute ad-hoc task with GSD guarantees (`--full` adds plan-checking and verification) |
+| `/gsd:quick [--full] [--discuss]` | Execute ad-hoc task with GSD guarantees (`--full` adds plan-checking and verification, `--discuss` gathers context first) |
 | `/gsd:health [--repair]` | Validate `.planning/` directory integrity, auto-repair with `--repair` |
 
 <sup>¹ Contributed by reddit user OracleGreyBeard</sup>
@@ -532,7 +532,7 @@ GSD stores project settings in `.planning/config.json`. Configure during `/gsd:n
 | Setting | Options | Default | What it controls |
 |---------|---------|---------|------------------|
 | `mode` | `yolo`, `interactive` | `interactive` | Auto-approve vs confirm at each step |
-| `depth` | `quick`, `standard`, `comprehensive` | `standard` | Planning thoroughness (phases × plans) |
+| `granularity` | `coarse`, `standard`, `fine` | `standard` | Phase granularity — how finely scope is sliced (phases × plans) |
 
 ### Model Profiles
 

package/agents/gsd-debugger.md

@@ -1038,6 +1038,7 @@ mv .planning/debug/{slug}.md .planning/debug/resolved/
 
 ```bash
 INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state load)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # commit_docs is in the JSON output
 ```
 

package/agents/gsd-executor.md

@@ -46,6 +46,7 @@ Load execution context:
 
 ```bash
 INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init execute-phase "${PHASE}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Extract from init JSON: `executor_model`, `commit_docs`, `phase_dir`, `plans`, `incomplete_plans`.

package/agents/gsd-nyquist-auditor.md

@@ -0,0 +1,178 @@
+---
+name: gsd-nyquist-auditor
+description: Fills Nyquist validation gaps by generating tests and verifying coverage for phase requirements
+tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+color: "#8B5CF6"
+skills:
+  - gsd-nyquist-auditor-workflow
+---
+
+<role>
+GSD Nyquist auditor. Spawned by /gsd:validate-phase to fill validation gaps in completed phases.
+
+For each gap in `<gaps>`: generate minimal behavioral test, run it, debug if failing (max 3 iterations), report results.
+
+**Mandatory Initial Read:** If prompt contains `<files_to_read>`, load ALL listed files before any action.
+
+**Implementation files are READ-ONLY.** Only create/modify: test files, fixtures, VALIDATION.md. Implementation bugs → ESCALATE. Never fix implementation.
+</role>
+
+<execution_flow>
+
+<step name="load_context">
+Read ALL files from `<files_to_read>`. Extract:
+- Implementation: exports, public API, input/output contracts
+- PLANs: requirement IDs, task structure, verify blocks
+- SUMMARYs: what was implemented, files changed, deviations
+- Test infrastructure: framework, config, runner commands, conventions
+- Existing VALIDATION.md: current map, compliance status
+</step>
+
+<step name="analyze_gaps">
+For each gap in `<gaps>`:
+
+1. Read related implementation files
+2. Identify observable behavior the requirement demands
+3. Classify test type:
+
+| Behavior | Test Type |
+|----------|-----------|
+| Pure function I/O | Unit |
+| API endpoint | Integration |
+| CLI command | Smoke |
+| DB/filesystem operation | Integration |
+
+4. Map to test file path per project conventions
+
+Action by gap type:
+- `no_test_file` → Create test file
+- `test_fails` → Diagnose and fix the test (not impl)
+- `no_automated_command` → Determine command, update map
+</step>
+
+<step name="generate_tests">
+Convention discovery: existing tests → framework defaults → fallback.
+
+| Framework | File Pattern | Runner | Assert Style |
+|-----------|-------------|--------|--------------|
+| pytest | `test_{name}.py` | `pytest {file} -v` | `assert result == expected` |
+| jest | `{name}.test.ts` | `npx jest {file}` | `expect(result).toBe(expected)` |
+| vitest | `{name}.test.ts` | `npx vitest run {file}` | `expect(result).toBe(expected)` |
+| go test | `{name}_test.go` | `go test -v -run {Name}` | `if got != want { t.Errorf(...) }` |
+
+Per gap: Write test file. One focused test per requirement behavior. Arrange/Act/Assert. Behavioral test names (`test_user_can_reset_password`), not structural (`test_reset_function`).
+</step>
+
+<step name="run_and_verify">
+Execute each test. If passes: record success, next gap. If fails: enter debug loop.
+
+Run every test. Never mark untested tests as passing.
+</step>
+
+<step name="debug_loop">
+Max 3 iterations per failing test.
+
+| Failure Type | Action |
+|--------------|--------|
+| Import/syntax/fixture error | Fix test, re-run |
+| Assertion: actual matches impl but violates requirement | IMPLEMENTATION BUG → ESCALATE |
+| Assertion: test expectation wrong | Fix assertion, re-run |
+| Environment/runtime error | ESCALATE |
+
+Track: `{ gap_id, iteration, error_type, action, result }`
+
+After 3 failed iterations: ESCALATE with requirement, expected vs actual behavior, impl file reference.
+</step>
+
+<step name="report">
+Resolved gaps: `{ task_id, requirement, test_type, automated_command, file_path, status: "green" }`
+Escalated gaps: `{ task_id, requirement, reason, debug_iterations, last_error }`
+
+Return one of three formats below.
+</step>
+
+</execution_flow>
+
+<structured_returns>
+
+## GAPS FILLED
+
+```markdown
+## GAPS FILLED
+
+**Phase:** {N} — {name}
+**Resolved:** {count}/{count}
+
+### Tests Created
+| # | File | Type | Command |
+|---|------|------|---------|
+| 1 | {path} | {unit/integration/smoke} | `{cmd}` |
+
+### Verification Map Updates
+| Task ID | Requirement | Command | Status |
+|---------|-------------|---------|--------|
+| {id} | {req} | `{cmd}` | green |
+
+### Files for Commit
+{test file paths}
+```
+
+## PARTIAL
+
+```markdown
+## PARTIAL
+
+**Phase:** {N} — {name}
+**Resolved:** {M}/{total} | **Escalated:** {K}/{total}
+
+### Resolved
+| Task ID | Requirement | File | Command | Status |
+|---------|-------------|------|---------|--------|
+| {id} | {req} | {file} | `{cmd}` | green |
+
+### Escalated
+| Task ID | Requirement | Reason | Iterations |
+|---------|-------------|--------|------------|
+| {id} | {req} | {reason} | {N}/3 |
+
+### Files for Commit
+{test file paths for resolved gaps}
+```
+
+## ESCALATE
+
+```markdown
+## ESCALATE
+
+**Phase:** {N} — {name}
+**Resolved:** 0/{total}
+
+### Details
+| Task ID | Requirement | Reason | Iterations |
+|---------|-------------|--------|------------|
+| {id} | {req} | {reason} | {N}/3 |
+
+### Recommendations
+- **{req}:** {manual test instructions or implementation fix needed}
+```
+
+</structured_returns>
+
+<success_criteria>
+- [ ] All `<files_to_read>` loaded before any action
+- [ ] Each gap analyzed with correct test type
+- [ ] Tests follow project conventions
+- [ ] Tests verify behavior, not structure
+- [ ] Every test executed — none marked passing without running
+- [ ] Implementation files never modified
+- [ ] Max 3 debug iterations per gap
+- [ ] Implementation bugs escalated, not fixed
+- [ ] Structured return provided (GAPS FILLED / PARTIAL / ESCALATE)
+- [ ] Test files listed for commit
+</success_criteria>

package/agents/gsd-phase-researcher.md

@@ -306,7 +306,7 @@ Verified patterns from official sources:
 
 ## Validation Architecture
 
-> Skip this section entirely if workflow.nyquist_validation is false in .planning/config.json
+> Skip this section entirely if workflow.nyquist_validation is explicitly set to false in .planning/config.json. If the key is absent, treat as enabled.
 
 ### Test Framework
 | Property | Value |
@@ -368,11 +368,12 @@ Orchestrator provides: phase number/name, description/goal, requirements, constr
 Load phase context using init command:
 ```bash
 INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Extract from init JSON: `phase_dir`, `padded_phase`, `phase_number`, `commit_docs`.
 
-Also read `.planning/config.json` — if `workflow.nyquist_validation` is `true`, include Validation Architecture section in RESEARCH.md. If `false`, skip it.
+Also read `.planning/config.json` — include Validation Architecture section in RESEARCH.md unless `workflow.nyquist_validation` is explicitly `false`. If the key is absent or `true`, include the section.
 
 Then read CONTEXT.md if exists:
 ```bash
@@ -408,7 +409,7 @@ For each domain: Context7 first → Official docs → WebSearch → Cross-verify
 
 ## Step 4: Validation Architecture Research (if nyquist_validation enabled)
 
-**Skip if** workflow.nyquist_validation is false.
+**Skip if** workflow.nyquist_validation is explicitly set to false. If absent, treat as enabled.
 
 ### Detect Test Infrastructure
 Scan for: test config files (pytest.ini, jest.config.*, vitest.config.*), test directories (test/, tests/, __tests__/), test files (*.test.*, *.spec.*), package.json test scripts.

package/agents/gsd-plan-checker.md

@@ -316,7 +316,20 @@ issue:
 
 ## Dimension 8: Nyquist Compliance
 
-Skip if: `workflow.nyquist_validation` is false, phase has no RESEARCH.md, or RESEARCH.md has no "Validation Architecture" section. Output: "Dimension 8: SKIPPED (nyquist_validation disabled or not applicable)"
+Skip if: `workflow.nyquist_validation` is explicitly set to `false` in config.json (absent key = enabled), phase has no RESEARCH.md, or RESEARCH.md has no "Validation Architecture" section. Output: "Dimension 8: SKIPPED (nyquist_validation disabled or not applicable)"
+
+### Check 8e — VALIDATION.md Existence (Gate)
+
+Before running checks 8a-8d, verify VALIDATION.md exists:
+
+```bash
+ls "${PHASE_DIR}"/*-VALIDATION.md 2>/dev/null
+```
+
+**If missing:** **BLOCKING FAIL** — "VALIDATION.md not found for phase {N}. Re-run `/gsd:plan-phase {N} --research` to regenerate."
+Skip checks 8a-8d entirely. Report Dimension 8 as FAIL with this single issue.
+
+**If exists:** Proceed to checks 8a-8d.
 
 ### Check 8a — Automated Verify Presence
 
@@ -368,6 +381,7 @@ If FAIL: return to planner with specific fixes. Same revision loop as other dime
 Load phase operation context:
 ```bash
 INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Extract from init JSON: `phase_dir`, `phase_number`, `has_plans`, `plan_count`.

package/agents/gsd-planner.md

@@ -371,15 +371,15 @@ Plans should complete within ~50% context (not 80%). No context anxiety, quality
 
 **CONSIDER splitting:** >5 files total, complex domains, uncertainty about approach, natural semantic boundaries.
 
-## Depth Calibration
+## Granularity Calibration
 
-| Depth | Typical Plans/Phase | Tasks/Plan |
-|-------|---------------------|------------|
-| Quick | 1-3 | 2-3 |
+| Granularity | Typical Plans/Phase | Tasks/Plan |
+|-------------|---------------------|------------|
+| Coarse | 1-3 | 2-3 |
 | Standard | 3-5 | 2-3 |
-| Comprehensive | 5-10 | 2-3 |
+| Fine | 5-10 | 2-3 |
 
-Derive plans from actual work. Depth determines compression tolerance, not a target. Don't pad small work to hit a number. Don't compress complex work to look efficient.
+Derive plans from actual work. Granularity determines compression tolerance, not a target. Don't pad small work to hit a number. Don't compress complex work to look efficient.
 
 ## Context Per Task Estimates
 
@@ -973,6 +973,7 @@ Load planning context:
 
 ```bash
 INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init plan-phase "${PHASE}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Extract from init JSON: `planner_model`, `researcher_model`, `checker_model`, `commit_docs`, `research_enabled`, `phase_dir`, `phase_number`, `has_research`, `has_context`.
@@ -1135,7 +1136,7 @@ Apply goal-backward methodology (see goal_backward section):
 </step>
 
 <step name="estimate_scope">
-Verify each plan fits context budget: 2-3 tasks, ~50% target. Split if necessary. Check depth setting.
+Verify each plan fits context budget: 2-3 tasks, ~50% target. Split if necessary. Check granularity setting.
 </step>
 
 <step name="confirm_breakdown">

package/agents/gsd-roadmapper.md

@@ -200,17 +200,17 @@ Track coverage as you go.
 - New milestone: Start at 1
 - Continuing milestone: Check existing phases, start at last + 1
 
-## Depth Calibration
+## Granularity Calibration
 
-Read depth from config.json. Depth controls compression tolerance.
+Read granularity from config.json. Granularity controls compression tolerance.
 
-| Depth | Typical Phases | What It Means |
-|-------|----------------|---------------|
-| Quick | 3-5 | Combine aggressively, critical path only |
+| Granularity | Typical Phases | What It Means |
+|-------------|----------------|---------------|
+| Coarse | 3-5 | Combine aggressively, critical path only |
 | Standard | 5-8 | Balanced grouping |
-| Comprehensive | 8-12 | Let natural boundaries stand |
+| Fine | 8-12 | Let natural boundaries stand |
 
-**Key:** Derive phases from work, then apply depth as compression guidance. Don't pad small projects or compress complex ones.
+**Key:** Derive phases from work, then apply granularity as compression guidance. Don't pad small projects or compress complex ones.
 
 ## Good Phase Patterns
 
@@ -357,7 +357,7 @@ When presenting to user for approval:
 ## ROADMAP DRAFT
 
 **Phases:** [N]
-**Depth:** [from config]
+**Granularity:** [from config]
 **Coverage:** [X]/[Y] requirements mapped
 
 ### Phase Structure
@@ -401,7 +401,7 @@ Orchestrator provides:
 - PROJECT.md content (core value, constraints)
 - REQUIREMENTS.md content (v1 requirements with REQ-IDs)
 - research/SUMMARY.md content (if exists - phase suggestions)
-- config.json (depth setting)
+- config.json (granularity setting)
 
 Parse and confirm understanding before proceeding.
 
@@ -437,7 +437,7 @@ Apply phase identification methodology:
 1. Group requirements by natural delivery boundaries
 2. Identify dependencies between groups
 3. Create phases that complete coherent capabilities
-4. Check depth setting for compression guidance
+4. Check granularity setting for compression guidance
 
 ## Step 5: Derive Success Criteria
 
@@ -502,7 +502,7 @@ When files are written and returning to orchestrator:
 ### Summary
 
 **Phases:** {N}
-**Depth:** {from config}
+**Granularity:** {from config}
 **Coverage:** {X}/{X} requirements mapped ✓
 
 | Phase | Goal | Requirements |
@@ -628,7 +628,7 @@ Roadmap is complete when:
 - [ ] All v1 requirements extracted with IDs
 - [ ] Research context loaded (if exists)
 - [ ] Phases derived from requirements (not imposed)
-- [ ] Depth calibration applied
+- [ ] Granularity calibration applied
 - [ ] Dependencies between phases identified
 - [ ] Success criteria derived for each phase (2-5 observable behaviors)
 - [ ] Success criteria cross-checked against requirements (gaps resolved)

package/bin/install.js

@@ -58,6 +58,21 @@ if (hasAll) {
   if (hasCodex) selectedRuntimes.push('codex');
 }
 
+/**
+ * Convert a pathPrefix (which uses absolute paths for global installs) to a
+ * $HOME-relative form for replacing $HOME/.claude/ references in bash code blocks.
+ * Preserves $HOME as a shell variable so paths remain portable across machines.
+ */
+function toHomePrefix(pathPrefix) {
+  const home = os.homedir().replace(/\\/g, '/');
+  const normalized = pathPrefix.replace(/\\/g, '/');
+  if (normalized.startsWith(home)) {
+    return '$HOME' + normalized.slice(home.length);
+  }
+  // For relative paths or paths not under $HOME, return as-is
+  return normalized;
+}
+
 // Helper to get directory name for a runtime (used for local/project installs)
 function getDirName(runtime) {
   if (runtime === 'opencode') return '.opencode';
@@ -700,8 +715,14 @@ function installCodexConfig(targetDir, agentsSrc) {
   const agentEntries = fs.readdirSync(agentsSrc).filter(f => f.startsWith('gsd-') && f.endsWith('.md'));
   const agents = [];
 
+  // Compute the Codex pathPrefix for replacing .claude paths
+  const codexPathPrefix = `${targetDir.replace(/\\/g, '/')}/`;
+
   for (const file of agentEntries) {
-    const content = fs.readFileSync(path.join(agentsSrc, file), 'utf8');
+    let content = fs.readFileSync(path.join(agentsSrc, file), 'utf8');
+    // Replace .claude paths before generating TOML (source files use ~/.claude and $HOME/.claude)
+    content = content.replace(/~\/\.claude\//g, codexPathPrefix);
+    content = content.replace(/\$HOME\/\.claude\//g, toHomePrefix(codexPathPrefix));
     const { frontmatter } = extractFrontmatterAndBody(content);
     const name = extractFrontmatterField(frontmatter, 'name') || file.replace('.md', '');
     const description = extractFrontmatterField(frontmatter, 'description') || '';
@@ -823,8 +844,9 @@ function convertClaudeToOpencodeFrontmatter(content) {
   convertedContent = convertedContent.replace(/\bTodoWrite\b/g, 'todowrite');
   // Replace /gsd:command with /gsd-command for opencode (flat command structure)
   convertedContent = convertedContent.replace(/\/gsd:/g, '/gsd-');
-  // Replace ~/.claude with ~/.config/opencode (OpenCode's correct config location)
+  // Replace ~/.claude and $HOME/.claude with OpenCode's config location
   convertedContent = convertedContent.replace(/~\/\.claude\b/g, '~/.config/opencode');
+  convertedContent = convertedContent.replace(/\$HOME\/\.claude\b/g, '$HOME/.config/opencode');
   // Replace general-purpose subagent type with OpenCode's equivalent "general"
   convertedContent = convertedContent.replace(/subagent_type="general-purpose"/g, 'subagent_type="general"');
 
@@ -1006,9 +1028,11 @@ function copyFlattenedCommands(srcDir, destDir, prefix, pathPrefix, runtime) {
 
       let content = fs.readFileSync(srcPath, 'utf8');
       const globalClaudeRegex = /~\/\.claude\//g;
+      const globalClaudeHomeRegex = /\$HOME\/\.claude\//g;
       const localClaudeRegex = /\.\/\.claude\//g;
       const opencodeDirRegex = /~\/\.opencode\//g;
       content = content.replace(globalClaudeRegex, pathPrefix);
+      content = content.replace(globalClaudeHomeRegex, toHomePrefix(pathPrefix));
       content = content.replace(localClaudeRegex, `./${getDirName(runtime)}/`);
       content = content.replace(opencodeDirRegex, pathPrefix);
       content = processAttribution(content, getCommitAttribution(runtime));
@@ -1065,9 +1089,11 @@ function copyCommandsAsCodexSkills(srcDir, skillsDir, prefix, pathPrefix, runtim
 
       let content = fs.readFileSync(srcPath, 'utf8');
       const globalClaudeRegex = /~\/\.claude\//g;
+      const globalClaudeHomeRegex = /\$HOME\/\.claude\//g;
       const localClaudeRegex = /\.\/\.claude\//g;
       const codexDirRegex = /~\/\.codex\//g;
       content = content.replace(globalClaudeRegex, pathPrefix);
+      content = content.replace(globalClaudeHomeRegex, toHomePrefix(pathPrefix));
       content = content.replace(localClaudeRegex, `./${getDirName(runtime)}/`);
       content = content.replace(codexDirRegex, pathPrefix);
       content = processAttribution(content, getCommitAttribution(runtime));
@@ -1108,11 +1134,13 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand
     if (entry.isDirectory()) {
       copyWithPathReplacement(srcPath, destPath, pathPrefix, runtime, isCommand);
     } else if (entry.name.endsWith('.md')) {
-      // Replace ~/.claude/ and ./.claude/ with runtime-appropriate paths
+      // Replace ~/.claude/ and $HOME/.claude/ and ./.claude/ with runtime-appropriate paths
       let content = fs.readFileSync(srcPath, 'utf8');
       const globalClaudeRegex = /~\/\.claude\//g;
+      const globalClaudeHomeRegex = /\$HOME\/\.claude\//g;
       const localClaudeRegex = /\.\/\.claude\//g;
       content = content.replace(globalClaudeRegex, pathPrefix);
+      content = content.replace(globalClaudeHomeRegex, toHomePrefix(pathPrefix));
       content = content.replace(localClaudeRegex, `./${dirName}/`);
       content = processAttribution(content, getCommitAttribution(runtime));
 
@@ -1953,9 +1981,11 @@ function install(isGlobal, runtime = 'claude') {
     for (const entry of agentEntries) {
       if (entry.isFile() && entry.name.endsWith('.md')) {
         let content = fs.readFileSync(path.join(agentsSrc, entry.name), 'utf8');
-        // Always replace ~/.claude/ as it is the source of truth in the repo
+        // Replace ~/.claude/ and $HOME/.claude/ as they are the source of truth in the repo
         const dirRegex = /~\/\.claude\//g;
+        const homeDirRegex = /\$HOME\/\.claude\//g;
         content = content.replace(dirRegex, pathPrefix);
+        content = content.replace(homeDirRegex, toHomePrefix(pathPrefix));
         content = processAttribution(content, getCommitAttribution(runtime));
         // Convert frontmatter for runtime compatibility
         if (isOpencode) {
@@ -2046,6 +2076,39 @@ function install(isGlobal, runtime = 'claude') {
   // Report any backed-up local patches
   reportLocalPatches(targetDir, runtime);
 
+  // Verify no leaked .claude paths in non-Claude runtimes
+  if (runtime !== 'claude') {
+    const leakedPaths = [];
+    function scanForLeakedPaths(dir) {
+      if (!fs.existsSync(dir)) return;
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          scanForLeakedPaths(fullPath);
+        } else if ((entry.name.endsWith('.md') || entry.name.endsWith('.toml')) && entry.name !== 'CHANGELOG.md') {
+          const content = fs.readFileSync(fullPath, 'utf8');
+          const matches = content.match(/(?:~|\$HOME)\/\.claude\b/g);
+          if (matches) {
+            leakedPaths.push({ file: fullPath.replace(targetDir + '/', ''), count: matches.length });
+          }
+        }
+      }
+    }
+    scanForLeakedPaths(targetDir);
+    if (leakedPaths.length > 0) {
+      const totalLeaks = leakedPaths.reduce((sum, l) => sum + l.count, 0);
+      console.warn(`\n  ${yellow}⚠${reset}  Found ${totalLeaks} unreplaced .claude path reference(s) in ${leakedPaths.length} file(s):`);
+      for (const leak of leakedPaths.slice(0, 5)) {
+        console.warn(`     ${dim}${leak.file}${reset} (${leak.count})`);
+      }
+      if (leakedPaths.length > 5) {
+        console.warn(`     ${dim}... and ${leakedPaths.length - 5} more file(s)${reset}`);
+      }
+      console.warn(`  ${dim}These paths may not resolve correctly for ${runtimeLabel}.${reset}`);
+    }
+  }
+
   if (isCodex) {
     // Generate Codex config.toml and per-agent .toml files
     const agentCount = installCodexConfig(targetDir, agentsSrc);

package/commands/gsd/debug.md

@@ -32,6 +32,7 @@ ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
 
 ```bash
 INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state load)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Extract `commit_docs` from init JSON. Resolve debugger model:

package/commands/gsd/quick.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:quick
 description: Execute a quick task with GSD guarantees (atomic commits, state tracking) but skip optional agents
-argument-hint: "[--full]"
+argument-hint: "[--full] [--discuss]"
 allowed-tools:
   - Read
   - Write
@@ -20,9 +20,13 @@ Quick mode is the same system with a shorter path:
 - Quick tasks live in `.planning/quick/` separate from planned phases
 - Updates STATE.md "Quick Tasks Completed" table (NOT ROADMAP.md)
 
-**Default:** Skips research, plan-checker, verifier. Use when you know exactly what to do.
+**Default:** Skips research, discussion, plan-checker, verifier. Use when you know exactly what to do.
+
+**`--discuss` flag:** Lightweight discussion phase before planning. Surfaces assumptions, clarifies gray areas, captures decisions in CONTEXT.md. Use when the task has ambiguity worth resolving upfront.
 
 **`--full` flag:** Enables plan-checking (max 2 iterations) and post-execution verification. Use when you want quality guarantees without full milestone ceremony.
+
+Flags are composable: `--discuss --full` gives discussion + plan-checking + verification.
 </objective>
 
 <execution_context>

package/commands/gsd/research-phase.md

@@ -35,6 +35,7 @@ Normalize phase input in step 1 before any directory lookups.
 
 ```bash
 INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "$ARGUMENTS")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `phase_found`, `commit_docs`, `has_research`, `state_path`, `requirements_path`, `context_path`, `research_path`.

package/commands/gsd/validate-phase.md

@@ -0,0 +1,35 @@
+---
+name: gsd:validate-phase
+description: Retroactively audit and fill Nyquist validation gaps for a completed phase
+argument-hint: "[phase number]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Audit Nyquist validation coverage for a completed phase. Three states:
+- (A) VALIDATION.md exists — audit and fill gaps
+- (B) No VALIDATION.md, SUMMARY.md exists — reconstruct from artifacts
+- (C) Phase not executed — exit with guidance
+
+Output: updated VALIDATION.md + generated test files.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/validate-phase.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS — optional, defaults to last completed phase.
+</context>
+
+<process>
+Execute @~/.claude/get-shit-done/workflows/validate-phase.md.
+Preserve all workflow gates.
+</process>

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

@@ -37,6 +37,13 @@ function cmdConfigEnsureSection(cwd, raw) {
   try {
     if (fs.existsSync(globalDefaultsPath)) {
       userDefaults = JSON.parse(fs.readFileSync(globalDefaultsPath, 'utf-8'));
+      // Migrate deprecated "depth" key to "granularity"
+      if ('depth' in userDefaults && !('granularity' in userDefaults)) {
+        const depthToGranularity = { quick: 'coarse', standard: 'standard', comprehensive: 'fine' };
+        userDefaults.granularity = depthToGranularity[userDefaults.depth] || userDefaults.depth;
+        delete userDefaults.depth;
+        try { fs.writeFileSync(globalDefaultsPath, JSON.stringify(userDefaults, null, 2), 'utf-8'); } catch {}
+      }
     }
   } catch (err) {
     // Ignore malformed global defaults, fall back to hardcoded
@@ -54,7 +61,7 @@ function cmdConfigEnsureSection(cwd, raw) {
       research: true,
       plan_check: true,
       verifier: true,
-      nyquist_validation: false,
+      nyquist_validation: true,
     },
     parallelization: true,
     brave_search: hasBraveSearch,

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

@@ -27,6 +27,7 @@ const MODEL_PROFILES = {
   'gsd-verifier':             { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
   'gsd-plan-checker':         { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
   'gsd-integration-checker':  { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-nyquist-auditor':      { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
 };
 
 // ─── Output helpers ───────────────────────────────────────────────────────────
@@ -76,7 +77,7 @@ function loadConfig(cwd) {
     research: true,
     plan_checker: true,
     verifier: true,
-    nyquist_validation: false,
+    nyquist_validation: true,
     parallelization: true,
     brave_search: false,
   };
@@ -85,6 +86,14 @@ function loadConfig(cwd) {
     const raw = fs.readFileSync(configPath, 'utf-8');
     const parsed = JSON.parse(raw);
 
+    // Migrate deprecated "depth" key to "granularity" with value mapping
+    if ('depth' in parsed && !('granularity' in parsed)) {
+      const depthToGranularity = { quick: 'coarse', standard: 'standard', comprehensive: 'fine' };
+      parsed.granularity = depthToGranularity[parsed.depth] || parsed.depth;
+      delete parsed.depth;
+      try { fs.writeFileSync(configPath, JSON.stringify(parsed, null, 2), 'utf-8'); } catch {}
+    }
+
     const get = (key, nested) => {
       if (parsed[key] !== undefined) return parsed[key];
       if (nested && parsed[nested.section] && parsed[nested.section][nested.field] !== undefined) {