get-shit-done-cc 1.22.2 → 1.22.3

package/README.md

@@ -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-nyquist-auditor.md

@@ -0,0 +1,176 @@
+---
+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"
+---
+
+<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 |
@@ -372,7 +372,7 @@ INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHA
 
 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 +408,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
 

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
 
@@ -1135,7 +1135,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/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) {

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

@@ -617,6 +617,18 @@ function cmdValidateHealth(cwd, options, raw) {
     }
   }
 
+  // ─── Check 5b: Nyquist validation key presence ──────────────────────────
+  if (fs.existsSync(configPath)) {
+    try {
+      const configRaw = fs.readFileSync(configPath, 'utf-8');
+      const configParsed = JSON.parse(configRaw);
+      if (configParsed.workflow && configParsed.workflow.nyquist_validation === undefined) {
+        addIssue('warning', 'W008', 'config.json: workflow.nyquist_validation absent (defaults to enabled but agents may skip)', 'Run /gsd:health --repair to add key', true);
+        if (!repairs.includes('addNyquistKey')) repairs.push('addNyquistKey');
+      }
+    } catch {}
+  }
+
   // ─── Check 6: Phase directory naming (NN-name format) ─────────────────────
   try {
     const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
@@ -646,6 +658,24 @@ function cmdValidateHealth(cwd, options, raw) {
     }
   } catch {}
 
+  // ─── Check 7b: Nyquist VALIDATION.md consistency ────────────────────────
+  try {
+    const phaseEntries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    for (const e of phaseEntries) {
+      if (!e.isDirectory()) continue;
+      const phaseFiles = fs.readdirSync(path.join(phasesDir, e.name));
+      const hasResearch = phaseFiles.some(f => f.endsWith('-RESEARCH.md'));
+      const hasValidation = phaseFiles.some(f => f.endsWith('-VALIDATION.md'));
+      if (hasResearch && !hasValidation) {
+        const researchFile = phaseFiles.find(f => f.endsWith('-RESEARCH.md'));
+        const researchContent = fs.readFileSync(path.join(phasesDir, e.name, researchFile), 'utf-8');
+        if (researchContent.includes('## Validation Architecture')) {
+          addIssue('warning', 'W009', `Phase ${e.name}: has Validation Architecture in RESEARCH.md but no VALIDATION.md`, 'Re-run /gsd:plan-phase with --research to regenerate');
+        }
+      }
+    }
+  } catch {}
+
   // ─── Check 8: Run existing consistency checks ─────────────────────────────
   // Inline subset of cmdValidateConsistency
   if (fs.existsSync(roadmapPath)) {
@@ -730,6 +760,23 @@ function cmdValidateHealth(cwd, options, raw) {
             repairActions.push({ action: repair, success: true, path: 'STATE.md' });
             break;
           }
+          case 'addNyquistKey': {
+            if (fs.existsSync(configPath)) {
+              try {
+                const configRaw = fs.readFileSync(configPath, 'utf-8');
+                const configParsed = JSON.parse(configRaw);
+                if (!configParsed.workflow) configParsed.workflow = {};
+                if (configParsed.workflow.nyquist_validation === undefined) {
+                  configParsed.workflow.nyquist_validation = true;
+                  fs.writeFileSync(configPath, JSON.stringify(configParsed, null, 2), 'utf-8');
+                }
+                repairActions.push({ action: repair, success: true, path: 'config.json' });
+              } catch (err) {
+                repairActions.push({ action: repair, success: false, error: err.message });
+              }
+            }
+            break;
+          }
         }
       } catch (err) {
         repairActions.push({ action: repair, success: false, error: err.message });

package/get-shit-done/references/model-profiles.md

@@ -17,6 +17,7 @@ Model profiles control which Claude model each GSD agent uses. This allows balan
 | gsd-verifier | sonnet | sonnet | haiku |
 | gsd-plan-checker | sonnet | sonnet | haiku |
 | gsd-integration-checker | sonnet | sonnet | haiku |
+| gsd-nyquist-auditor | sonnet | sonnet | haiku |
 
 ## Profile Philosophy
 

package/get-shit-done/templates/config.json

@@ -1,12 +1,12 @@
 {
   "mode": "interactive",
-  "depth": "standard",
+  "granularity": "standard",
   "workflow": {
     "research": true,
     "plan_check": true,
     "verifier": true,
     "auto_advance": false,
-    "nyquist_validation": false
+    "nyquist_validation": true
   },
   "planning": {
     "commit_docs": true,

package/get-shit-done/templates/roadmap.md

@@ -105,7 +105,7 @@ Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 
 <guidelines>
 **Initial planning (v1.0):**
-- Phase count depends on depth setting (quick: 3-5, standard: 5-8, comprehensive: 8-12)
+- Phase count depends on granularity setting (coarse: 3-5, standard: 5-8, fine: 8-12)
 - Each phase delivers something coherent
 - Phases can have 1+ plans (split if >3 tasks or multiple subsystems)
 - Plans use naming: {phase}-{plan}-PLAN.md (e.g., 01-02-PLAN.md)

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

@@ -127,6 +127,30 @@ For each REQ-ID, determine status using all three sources:
 
 **Orphan detection:** Requirements present in REQUIREMENTS.md traceability table but absent from ALL phase VERIFICATION.md files MUST be flagged as orphaned. Orphaned requirements are treated as `unsatisfied` — they were assigned but never verified by any phase.
 
+## 5.5. Nyquist Compliance Discovery
+
+Skip if `workflow.nyquist_validation` is explicitly `false` (absent = enabled).
+
+```bash
+NYQUIST_CONFIG=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config get workflow.nyquist_validation --raw 2>/dev/null)
+```
+
+If `false`: skip entirely.
+
+For each phase directory, check `*-VALIDATION.md`. If exists, parse frontmatter (`nyquist_compliant`, `wave_0_complete`).
+
+Classify per phase:
+
+| Status | Condition |
+|--------|-----------|
+| COMPLIANT | `nyquist_compliant: true` and all tasks green |
+| PARTIAL | VALIDATION.md exists, `nyquist_compliant: false` or red/pending |
+| MISSING | No VALIDATION.md |
+
+Add to audit YAML: `nyquist: { compliant_phases, partial_phases, missing_phases, overall }`
+
+Discovery only — never auto-calls `/gsd:validate-phase`.
+
 ## 6. Aggregate into v{version}-MILESTONE-AUDIT.md
 
 Create `.planning/v{version}-v{version}-MILESTONE-AUDIT.md` with:
@@ -227,6 +251,14 @@ All requirements covered. Cross-phase integration verified. E2E flows complete.
 {For each flow gap:}
 - **{flow name}:** breaks at {step}
 
+### Nyquist Coverage
+
+| Phase | VALIDATION.md | Compliant | Action |
+|-------|---------------|-----------|--------|
+| {phase} | exists/missing | true/false/partial | `/gsd:validate-phase {N}` |
+
+Phases needing validation: run `/gsd:validate-phase {N}` for each flagged phase.
+
 ───────────────────────────────────────────────────────────────
 
 ## ▶ Next Up
@@ -293,5 +325,7 @@ All requirements met. No critical blockers. Accumulated tech debt needs review.
 - [ ] Integration checker spawned with milestone requirement IDs
 - [ ] v{version}-MILESTONE-AUDIT.md created with structured requirement gap objects
 - [ ] FAIL gate enforced — any unsatisfied requirement forces gaps_found status
+- [ ] Nyquist compliance scanned for all milestone phases (if enabled)
+- [ ] Missing VALIDATION.md phases flagged with validate-phase suggestion
 - [ ] Results presented with actionable next steps
 </success_criteria>

package/get-shit-done/workflows/health.md

@@ -136,6 +136,8 @@ Report final status.
 | W005 | warning | Phase directory naming mismatch | No |
 | W006 | warning | Phase in ROADMAP but no directory | No |
 | W007 | warning | Phase on disk but not in ROADMAP | No |
+| W008 | warning | config.json: workflow.nyquist_validation absent (defaults to enabled but agents may skip) | Yes |
+| W009 | warning | Phase has Validation Architecture in RESEARCH.md but no VALIDATION.md | No |
 | I001 | info | Plan without SUMMARY (may be in progress) | No |
 
 </error_codes>
@@ -147,6 +149,7 @@ Report final status.
 | createConfig | Create config.json with defaults | None |
 | resetConfig | Delete + recreate config.json | Loses custom settings |
 | regenerateState | Create STATE.md from ROADMAP structure | Loses session history |
+| addNyquistKey | Add workflow.nyquist_validation: true to config.json | None — matches existing default |
 
 **Not repairable (too risky):**
 - PROJECT.md, ROADMAP.md content

package/get-shit-done/workflows/new-project.md

@@ -14,7 +14,7 @@ Check if `--auto` flag is present in $ARGUMENTS.
 **If auto mode:**
 - Skip brownfield mapping offer (assume greenfield)
 - Skip deep questioning (extract context from provided document)
-- Config: YOLO mode is implicit (skip that question), but ask depth/git/agents FIRST (Step 2a)
+- Config: YOLO mode is implicit (skip that question), but ask granularity/git/agents FIRST (Step 2a)
 - After config: run Steps 6-9 automatically with smart defaults:
   - Research: Always yes
   - Requirements: Include all table stakes + features from provided document
@@ -90,13 +90,13 @@ YOLO mode is implicit (auto = YOLO). Ask remaining config questions:
 ```
 AskUserQuestion([
   {
-    header: "Depth",
-    question: "How thorough should planning be?",
+    header: "Granularity",
+    question: "How finely should scope be sliced into phases?",
     multiSelect: false,
     options: [
-      { label: "Quick (Recommended)", description: "Ship fast (3-5 phases, 1-3 plans each)" },
-      { label: "Standard", description: "Balanced scope and speed (5-8 phases, 3-5 plans each)" },
-      { label: "Comprehensive", description: "Thorough coverage (8-12 phases, 5-10 plans each)" }
+      { label: "Coarse (Recommended)", description: "Fewer, broader phases (3-5 phases, 1-3 plans each)" },
+      { label: "Standard", description: "Balanced phase size (5-8 phases, 3-5 plans each)" },
+      { label: "Fine", description: "Many focused phases (8-12 phases, 5-10 plans each)" }
     ]
   },
   {
@@ -169,7 +169,7 @@ Create `.planning/config.json` with mode set to "yolo":
 ```json
 {
   "mode": "yolo",
-  "depth": "[selected]",
+  "granularity": "[selected]",
   "parallelization": true|false,
   "commit_docs": true|false,
   "model_profile": "quality|balanced|budget",
@@ -177,6 +177,7 @@ Create `.planning/config.json` with mode set to "yolo":
     "research": true|false,
     "plan_check": true|false,
     "verifier": true|false,
+    "nyquist_validation": depth !== "quick",
     "auto_advance": true
   }
 }
@@ -379,13 +380,13 @@ questions: [
     ]
   },
   {
-    header: "Depth",
-    question: "How thorough should planning be?",
+    header: "Granularity",
+    question: "How finely should scope be sliced into phases?",
     multiSelect: false,
     options: [
-      { label: "Quick", description: "Ship fast (3-5 phases, 1-3 plans each)" },
-      { label: "Standard", description: "Balanced scope and speed (5-8 phases, 3-5 plans each)" },
-      { label: "Comprehensive", description: "Thorough coverage (8-12 phases, 5-10 plans each)" }
+      { label: "Coarse", description: "Fewer, broader phases (3-5 phases, 1-3 plans each)" },
+      { label: "Standard", description: "Balanced phase size (5-8 phases, 3-5 plans each)" },
+      { label: "Fine", description: "Many focused phases (8-12 phases, 5-10 plans each)" }
     ]
   },
   {
@@ -468,14 +469,15 @@ Create `.planning/config.json` with all settings:
 ```json
 {
   "mode": "yolo|interactive",
-  "depth": "quick|standard|comprehensive",
+  "granularity": "coarse|standard|fine",
   "parallelization": true|false,
   "commit_docs": true|false,
   "model_profile": "quality|balanced|budget",
   "workflow": {
     "research": true|false,
     "plan_check": true|false,
-    "verifier": true|false
+    "verifier": true|false,
+    "nyquist_validation": depth !== "quick"
   }
 }
 ```
@@ -903,7 +905,7 @@ Task(prompt="
 - .planning/PROJECT.md (Project context)
 - .planning/REQUIREMENTS.md (v1 Requirements)
 - .planning/research/SUMMARY.md (Research findings - if exists)
-- .planning/config.json (Depth and mode settings)
+- .planning/config.json (Granularity and mode settings)
 </files_to_read>
 
 </planning_context>
@@ -1090,7 +1092,7 @@ Exit skill and invoke SlashCommand("/gsd:discuss-phase 1 --auto")
 - [ ] Brownfield detection completed
 - [ ] Deep questioning completed (threads followed, not rushed)
 - [ ] PROJECT.md captures full context → **committed**
-- [ ] config.json has workflow mode, depth, parallelization → **committed**
+- [ ] config.json has workflow mode, granularity, parallelization → **committed**
 - [ ] Research completed (if selected) — 4 parallel agents spawned → **committed**
 - [ ] Requirements gathered (from research or conversation)
 - [ ] User scoped each category (v1/v2/out of scope)

package/get-shit-done/workflows/plan-phase.md

@@ -219,30 +219,26 @@ Task(
 - **`## RESEARCH COMPLETE`:** Display confirmation, continue to step 6
 - **`## RESEARCH BLOCKED`:** Display blocker, offer: 1) Provide context, 2) Skip research, 3) Abort
 
-## 5.5. Create Validation Strategy (if Nyquist enabled)
+## 5.5. Create Validation Strategy
 
-**Skip if:** `nyquist_validation_enabled` is false from INIT JSON.
-
-After researcher completes, check if RESEARCH.md contains a Validation Architecture section:
+MANDATORY unless `nyquist_validation_enabled` is false.
 
 ```bash
 grep -l "## Validation Architecture" "${PHASE_DIR}"/*-RESEARCH.md 2>/dev/null
 ```
 
 **If found:**
-1. Read validation template from `~/.claude/get-shit-done/templates/VALIDATION.md`
-2. Write to `${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md`
-3. Fill frontmatter: replace `{N}` with phase number, `{phase-slug}` with phase slug, `{date}` with current date
-4. If `commit_docs` is true:
+1. Read template: `~/.claude/get-shit-done/templates/VALIDATION.md`
+2. Write to `${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md` (use Write tool)
+3. Fill frontmatter: `{N}` → phase number, `{phase-slug}` → slug, `{date}` → current date
+4. Verify:
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit-docs "docs(phase-${PHASE}): add validation strategy"
+test -f "${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md" && echo "VALIDATION_CREATED=true" || echo "VALIDATION_CREATED=false"
 ```
+5. If `VALIDATION_CREATED=false`: STOP — do not proceed to Step 6
+6. If `commit_docs`: `commit-docs "docs(phase-${PHASE}): add validation strategy"`
 
-**If not found (and nyquist enabled):** Display warning:
-```
-⚠ Nyquist validation enabled but researcher did not produce a Validation Architecture section.
-  Continuing without validation strategy. Plans may fail Dimension 8 check.
-```
+**If not found:** Warn and continue — plans may fail Dimension 8.
 
 ## 6. Check Existing Plans
 
@@ -266,6 +262,21 @@ UAT_PATH=$(printf '%s\n' "$INIT" | jq -r '.uat_path // empty')
 CONTEXT_PATH=$(printf '%s\n' "$INIT" | jq -r '.context_path // empty')
 ```
 
+## 7.5. Verify Nyquist Artifacts
+
+Skip if `nyquist_validation_enabled` is false.
+
+```bash
+VALIDATION_EXISTS=$(ls "${PHASE_DIR}"/*-VALIDATION.md 2>/dev/null | head -1)
+```
+
+If missing and Nyquist enabled — ask user:
+1. Re-run: `/gsd:plan-phase {PHASE} --research`
+2. Disable Nyquist in config
+3. Continue anyway (plans fail Dimension 8)
+
+Proceed to Step 8 only if user selects 2 or 3.
+
 ## 8. Spawn gsd-planner Agent
 
 Display banner:

package/get-shit-done/workflows/settings.md

@@ -28,7 +28,7 @@ Parse current values (default to `true` if not present):
 - `workflow.research` — spawn researcher during plan-phase
 - `workflow.plan_check` — spawn plan checker during plan-phase
 - `workflow.verifier` — spawn verifier during execute-phase
-- `workflow.nyquist_validation` — validation architecture research during plan-phase
+- `workflow.nyquist_validation` — validation architecture research during plan-phase (default: true if absent)
 - `model_profile` — which model each agent uses (default: `balanced`)
 - `git.branching_strategy` — branching approach (default: `"none"`)
 </step>
@@ -157,7 +157,7 @@ Write `~/.gsd/defaults.json` with:
 ```json
 {
   "mode": <current>,
-  "depth": <current>,
+  "granularity": <current>,
   "model_profile": <current>,
   "commit_docs": <current>,
   "parallelization": <current>,

package/get-shit-done/workflows/validate-phase.md

@@ -0,0 +1,166 @@
+<purpose>
+Audit Nyquist validation gaps for a completed phase. Generate missing tests. Update VALIDATION.md.
+</purpose>
+
+<required_reading>
+@~/.claude/get-shit-done/references/ui-brand.md
+</required_reading>
+
+<process>
+
+## 0. Initialize
+
+```bash
+INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}")
+```
+
+Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`.
+
+```bash
+AUDITOR_MODEL=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-nyquist-auditor --raw)
+NYQUIST_CFG=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config get workflow.nyquist_validation --raw)
+```
+
+If `NYQUIST_CFG` is `false`: exit with "Nyquist validation is disabled. Enable via /gsd:settings."
+
+Display banner: `GSD > VALIDATE PHASE {N}: {name}`
+
+## 1. Detect Input State
+
+```bash
+VALIDATION_FILE=$(ls "${PHASE_DIR}"/*-VALIDATION.md 2>/dev/null | head -1)
+SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)
+```
+
+- **State A** (`VALIDATION_FILE` non-empty): Audit existing
+- **State B** (`VALIDATION_FILE` empty, `SUMMARY_FILES` non-empty): Reconstruct from artifacts
+- **State C** (`SUMMARY_FILES` empty): Exit — "Phase {N} not executed. Run /gsd:execute-phase {N} first."
+
+## 2. Discovery
+
+### 2a. Read Phase Artifacts
+
+Read all PLAN and SUMMARY files. Extract: task lists, requirement IDs, key-files changed, verify blocks.
+
+### 2b. Build Requirement-to-Task Map
+
+Per task: `{ task_id, plan_id, wave, requirement_ids, has_automated_command }`
+
+### 2c. Detect Test Infrastructure
+
+State A: Parse from existing VALIDATION.md Test Infrastructure table.
+State B: Filesystem scan:
+
+```bash
+find . -name "pytest.ini" -o -name "jest.config.*" -o -name "vitest.config.*" -o -name "pyproject.toml" 2>/dev/null | head -10
+find . \( -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" \) -not -path "*/node_modules/*" 2>/dev/null | head -40
+```
+
+### 2d. Cross-Reference
+
+Match each requirement to existing tests by filename, imports, test descriptions. Record: requirement → test_file → status.
+
+## 3. Gap Analysis
+
+Classify each requirement:
+
+| Status | Criteria |
+|--------|----------|
+| COVERED | Test exists, targets behavior, runs green |
+| PARTIAL | Test exists, failing or incomplete |
+| MISSING | No test found |
+
+Build: `{ task_id, requirement, gap_type, suggested_test_path, suggested_command }`
+
+No gaps → skip to Step 6, set `nyquist_compliant: true`.
+
+## 4. Present Gap Plan
+
+Call AskUserQuestion with gap table and options:
+1. "Fix all gaps" → Step 5
+2. "Skip — mark manual-only" → add to Manual-Only, Step 6
+3. "Cancel" → exit
+
+## 5. Spawn gsd-nyquist-auditor
+
+```
+Task(
+  prompt="Read ~/.claude/agents/gsd-nyquist-auditor.md for instructions.\n\n" +
+    "<files_to_read>{PLAN, SUMMARY, impl files, VALIDATION.md}</files_to_read>" +
+    "<gaps>{gap list}</gaps>" +
+    "<test_infrastructure>{framework, config, commands}</test_infrastructure>" +
+    "<constraints>Never modify impl files. Max 3 debug iterations. Escalate impl bugs.</constraints>",
+  subagent_type="gsd-nyquist-auditor",
+  model="{AUDITOR_MODEL}",
+  description="Fill validation gaps for Phase {N}"
+)
+```
+
+Handle return:
+- `## GAPS FILLED` → record tests + map updates, Step 6
+- `## PARTIAL` → record resolved, move escalated to manual-only, Step 6
+- `## ESCALATE` → move all to manual-only, Step 6
+
+## 6. Generate/Update VALIDATION.md
+
+**State B (create):**
+1. Read template from `~/.claude/get-shit-done/templates/VALIDATION.md`
+2. Fill: frontmatter, Test Infrastructure, Per-Task Map, Manual-Only, Sign-Off
+3. Write to `${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md`
+
+**State A (update):**
+1. Update Per-Task Map statuses, add escalated to Manual-Only, update frontmatter
+2. Append audit trail:
+
+```markdown
+## Validation Audit {date}
+| Metric | Count |
+|--------|-------|
+| Gaps found | {N} |
+| Resolved | {M} |
+| Escalated | {K} |
+```
+
+## 7. Commit
+
+```bash
+git add {test_files}
+git commit -m "test(phase-${PHASE}): add Nyquist validation tests"
+
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit-docs "docs(phase-${PHASE}): add/update validation strategy"
+```
+
+## 8. Results + Routing
+
+**Compliant:**
+```
+GSD > PHASE {N} IS NYQUIST-COMPLIANT
+All requirements have automated verification.
+▶ Next: /gsd:audit-milestone
+```
+
+**Partial:**
+```
+GSD > PHASE {N} VALIDATED (PARTIAL)
+{M} automated, {K} manual-only.
+▶ Retry: /gsd:validate-phase {N}
+```
+
+Display `/clear` reminder.
+
+</process>
+
+<success_criteria>
+- [ ] Nyquist config checked (exit if disabled)
+- [ ] Input state detected (A/B/C)
+- [ ] State C exits cleanly
+- [ ] PLAN/SUMMARY files read, requirement map built
+- [ ] Test infrastructure detected
+- [ ] Gaps classified (COVERED/PARTIAL/MISSING)
+- [ ] User gate with gap table
+- [ ] Auditor spawned with complete context
+- [ ] All three return formats handled
+- [ ] VALIDATION.md created or updated
+- [ ] Test files committed separately
+- [ ] Results with routing presented
+</success_criteria>

package/get-shit-done/workflows/verify-work.md

@@ -108,6 +108,19 @@ Examples:
   → Expected: "Clicking Reply opens inline composer below comment. Submitting shows reply nested under parent with visual indentation."
 
 Skip internal/non-observable items (refactors, type changes, etc.).
+
+**Cold-start smoke test injection:**
+
+After extracting tests from SUMMARYs, scan the SUMMARY files for modified/created file paths. If ANY path matches these patterns:
+
+`server.ts`, `server.js`, `app.ts`, `app.js`, `index.ts`, `index.js`, `main.ts`, `main.js`, `database/*`, `db/*`, `seed/*`, `seeds/*`, `migrations/*`, `startup*`, `docker-compose*`, `Dockerfile*`
+
+Then **prepend** this test to the test list:
+
+- name: "Cold Start Smoke Test"
+- expected: "Kill any running server/service. Clear ephemeral state (temp DBs, caches, lock files). Start the application from scratch. Server boots without errors, any seed/migration completes, and a primary query (health check, homepage load, or basic API call) returns live data."
+
+This catches bugs that only manifest on fresh start — race conditions in startup sequences, silent seed failures, missing environment setup — which pass against warm state but break in production.
 </step>
 
 <step name="create_uat_file">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "get-shit-done-cc",
-  "version": "1.22.2",
+  "version": "1.22.3",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code, OpenCode, Gemini and Codex by TÂCHES.",
   "bin": {
     "get-shit-done-cc": "bin/install.js"