gsd-opencode 1.20.3 → 1.22.0

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

@@ -6,6 +6,7 @@ const fs = require('fs');
 const path = require('path');
 const { safeReadFile, normalizePhaseName, execGit, findPhaseInternal, getMilestoneInfo, output, error } = require('./core.cjs');
 const { extractFrontmatter, parseMustHavesBlock } = require('./frontmatter.cjs');
+const { writeStateMd } = require('./state.cjs');
 
 function cmdVerifySummary(cwd, summaryPath, checkFileCount, raw) {
   if (!summaryPath) {
@@ -410,7 +411,7 @@ function cmdValidateConsistency(cwd, raw) {
 
   // Extract phases from ROADMAP
   const roadmapPhases = new Set();
-  const phasePattern = /#{2,4}\s*Phase\s+(\d+(?:\.\d+)?)\s*:/gi;
+  const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:/gi;
   let m;
   while ((m = phasePattern.exec(roadmapContent)) !== null) {
     roadmapPhases.add(m[1]);
@@ -422,7 +423,7 @@ function cmdValidateConsistency(cwd, raw) {
     const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
     const dirs = entries.filter(e => e.isDirectory()).map(e => e.name);
     for (const dir of dirs) {
-      const dm = dir.match(/^(\d+(?:\.\d+)?)/);
+      const dm = dir.match(/^(\d+[A-Z]?(?:\.\d+)*)/i);
       if (dm) diskPhases.add(dm[1]);
     }
   } catch {}
@@ -572,14 +573,14 @@ function cmdValidateHealth(cwd, options, raw) {
   } else {
     const stateContent = fs.readFileSync(statePath, 'utf-8');
     // Extract phase references from STATE.md
-    const phaseRefs = [...stateContent.matchAll(/[Pp]hase\s+(\d+(?:\.\d+)?)/g)].map(m => m[1]);
+    const phaseRefs = [...stateContent.matchAll(/[Pp]hase\s+(\d+(?:\.\d+)*)/g)].map(m => m[1]);
     // Get disk phases
     const diskPhases = new Set();
     try {
       const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
       for (const e of entries) {
         if (e.isDirectory()) {
-          const m = e.name.match(/^(\d+(?:\.\d+)?)/);
+          const m = e.name.match(/^(\d+(?:\.\d+)*)/);
           if (m) diskPhases.add(m[1]);
         }
       }
@@ -616,11 +617,23 @@ 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 });
     for (const e of entries) {
-      if (e.isDirectory() && !e.name.match(/^\d{2}(?:\.\d+)?-[\w-]+$/)) {
+      if (e.isDirectory() && !e.name.match(/^\d{2}(?:\.\d+)*-[\w-]+$/)) {
         addIssue('warning', 'W005', `Phase directory "${e.name}" doesn't follow NN-name format`, 'Rename to match pattern (e.g., 01-setup)');
       }
     }
@@ -645,12 +658,30 @@ 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)) {
     const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
     const roadmapPhases = new Set();
-    const phasePattern = /#{2,4}\s*Phase\s+(\d+(?:\.\d+)?)\s*:/gi;
+    const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:/gi;
     let m;
     while ((m = phasePattern.exec(roadmapContent)) !== null) {
       roadmapPhases.add(m[1]);
@@ -661,7 +692,7 @@ function cmdValidateHealth(cwd, options, raw) {
       const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
       for (const e of entries) {
         if (e.isDirectory()) {
-          const dm = e.name.match(/^(\d+(?:\.\d+)?)/);
+          const dm = e.name.match(/^(\d+[A-Z]?(?:\.\d+)*)/i);
           if (dm) diskPhases.add(dm[1]);
         }
       }
@@ -725,10 +756,27 @@ function cmdValidateHealth(cwd, options, raw) {
             stateContent += `**Status:** Resuming\n\n`;
             stateContent += `## Session Log\n\n`;
             stateContent += `- ${new Date().toISOString().split('T')[0]}: STATE.md regenerated by /gsd-health --repair\n`;
-            fs.writeFileSync(statePath, stateContent, 'utf-8');
+            writeStateMd(statePath, stateContent, cwd);
             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/bin/test/allow-read-config.test.cjs

@@ -0,0 +1,262 @@
+/**
+ * allow-read-config.test.cjs — Tests for allow-read-config command
+ *
+ * Tests the allow-read-config command functionality:
+ * - Permission creation
+ * - Idempotency (detecting existing permission)
+ * - Dry-run mode
+ * - Backup creation
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const CLI_PATH = path.join(__dirname, '../gsd-oc-commands/allow-read-config.cjs');
+const TOOLS_PATH = path.join(__dirname, '../gsd-oc-tools.cjs');
+
+/**
+ * Create a temporary test directory
+ */
+function createTestDir() {
+  const testDir = path.join(os.tmpdir(), `gsd-oc-test-${Date.now()}`);
+  fs.mkdirSync(testDir, { recursive: true });
+  return testDir;
+}
+
+/**
+ * Clean up test directory
+ */
+function cleanupTestDir(testDir) {
+  if (fs.existsSync(testDir)) {
+    fs.rmSync(testDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Run CLI command and parse JSON output
+ */
+function runCLI(testDir, args) {
+  const cmd = `node ${TOOLS_PATH} allow-read-config ${args.join(' ')}`;
+  const output = execSync(cmd, { cwd: testDir, encoding: 'utf8' });
+  return JSON.parse(output);
+}
+
+/**
+ * Test: Create new opencode.json with permission
+ */
+function testCreatePermission() {
+  console.log('Test: Create new opencode.json with permission...');
+  
+  const testDir = createTestDir();
+  
+  try {
+    const result = runCLI(testDir, []);
+    
+    if (!result.success) {
+      throw new Error(`Expected success, got: ${JSON.stringify(result)}`);
+    }
+    
+    if (result.data.action !== 'add_permission') {
+      throw new Error(`Expected action 'add_permission', got: ${result.data.action}`);
+    }
+    
+    if (result.data.created !== true) {
+      throw new Error(`Expected created=true, got: ${result.data.created}`);
+    }
+    
+    // Verify opencode.json was created
+    const opencodePath = path.join(testDir, 'opencode.json');
+    if (!fs.existsSync(opencodePath)) {
+      throw new Error('opencode.json was not created');
+    }
+    
+    const content = JSON.parse(fs.readFileSync(opencodePath, 'utf8'));
+    if (!content.permission?.external_directory) {
+      throw new Error('Permission not added to opencode.json');
+    }
+    
+    console.log('✓ PASS: Create permission\n');
+    return true;
+  } catch (err) {
+    console.error('✗ FAIL:', err.message, '\n');
+    return false;
+  } finally {
+    cleanupTestDir(testDir);
+  }
+}
+
+/**
+ * Test: Idempotency - detect existing permission
+ */
+function testIdempotency() {
+  console.log('Test: Idempotency (detect existing permission)...');
+  
+  const testDir = createTestDir();
+  
+  try {
+    // First call - create permission
+    runCLI(testDir, []);
+    
+    // Second call - should detect existing
+    const result = runCLI(testDir, []);
+    
+    if (!result.success) {
+      throw new Error(`Expected success, got: ${JSON.stringify(result)}`);
+    }
+    
+    if (result.data.action !== 'permission_exists') {
+      throw new Error(`Expected action 'permission_exists', got: ${result.data.action}`);
+    }
+    
+    console.log('✓ PASS: Idempotency\n');
+    return true;
+  } catch (err) {
+    console.error('✗ FAIL:', err.message, '\n');
+    return false;
+  } finally {
+    cleanupTestDir(testDir);
+  }
+}
+
+/**
+ * Test: Dry-run mode
+ */
+function testDryRun() {
+  console.log('Test: Dry-run mode...');
+  
+  const testDir = createTestDir();
+  
+  try {
+    const result = runCLI(testDir, ['--dry-run']);
+    
+    if (!result.success) {
+      throw new Error(`Expected success, got: ${JSON.stringify(result)}`);
+    }
+    
+    if (result.data.dryRun !== true) {
+      throw new Error(`Expected dryRun=true, got: ${result.data.dryRun}`);
+    }
+    
+    // Verify opencode.json was NOT created
+    const opencodePath = path.join(testDir, 'opencode.json');
+    if (fs.existsSync(opencodePath)) {
+      throw new Error('opencode.json should not be created in dry-run mode');
+    }
+    
+    console.log('✓ PASS: Dry-run mode\n');
+    return true;
+  } catch (err) {
+    console.error('✗ FAIL:', err.message, '\n');
+    return false;
+  } finally {
+    cleanupTestDir(testDir);
+  }
+}
+
+/**
+ * Test: Backup creation on update
+ */
+function testBackupCreation() {
+  console.log('Test: Backup creation on update...');
+  
+  const testDir = createTestDir();
+  
+  try {
+    // Create initial opencode.json
+    const opencodePath = path.join(testDir, 'opencode.json');
+    const initialContent = {
+      "$schema": "https://opencode.ai/config.json",
+      "model": "test/model"
+    };
+    fs.writeFileSync(opencodePath, JSON.stringify(initialContent, null, 2) + '\n');
+    
+    // Run allow-read-config
+    const result = runCLI(testDir, []);
+    
+    if (!result.success) {
+      throw new Error(`Expected success, got: ${JSON.stringify(result)}`);
+    }
+    
+    if (!result.data.backup) {
+      throw new Error('Expected backup path, got none');
+    }
+    
+    if (!fs.existsSync(result.data.backup)) {
+      throw new Error(`Backup file does not exist: ${result.data.backup}`);
+    }
+    
+    // Verify backup content matches original
+    const backupContent = JSON.parse(fs.readFileSync(result.data.backup, 'utf8'));
+    if (JSON.stringify(backupContent) !== JSON.stringify(initialContent)) {
+      throw new Error('Backup content does not match original');
+    }
+    
+    console.log('✓ PASS: Backup creation\n');
+    return true;
+  } catch (err) {
+    console.error('✗ FAIL:', err.message, '\n');
+    return false;
+  } finally {
+    cleanupTestDir(testDir);
+  }
+}
+
+/**
+ * Test: Verbose output
+ */
+function testVerbose() {
+  console.log('Test: Verbose output...');
+  
+  const testDir = createTestDir();
+  
+  try {
+    const cmd = `node ${TOOLS_PATH} allow-read-config --verbose`;
+    const output = execSync(cmd, { cwd: testDir, encoding: 'utf8', stdio: 'pipe' });
+    
+    // Verbose output should contain log messages to stderr
+    // We just verify it doesn't crash
+    console.log('✓ PASS: Verbose output\n');
+    return true;
+  } catch (err) {
+    console.error('✗ FAIL:', err.message, '\n');
+    return false;
+  } finally {
+    cleanupTestDir(testDir);
+  }
+}
+
+/**
+ * Run all tests
+ */
+function runTests() {
+  console.log('Running allow-read-config tests...\n');
+  console.log('=' .repeat(50));
+  console.log();
+  
+  const results = [
+    testCreatePermission(),
+    testIdempotency(),
+    testDryRun(),
+    testBackupCreation(),
+    testVerbose()
+  ];
+  
+  const passed = results.filter(r => r).length;
+  const total = results.length;
+  
+  console.log('=' .repeat(50));
+  console.log(`Results: ${passed}/${total} tests passed`);
+  
+  if (passed === total) {
+    console.log('✓ All tests passed!\n');
+    process.exit(0);
+  } else {
+    console.error(`✗ ${total - passed} test(s) failed\n`);
+    process.exit(1);
+  }
+}
+
+// Run tests
+runTests();

package/get-shit-done/references/checkpoints.md

@@ -8,7 +8,7 @@ Plans execute autonomously. Checkpoints formalize interaction points where human
 2. **OpenCode sets up the verification environment** - Start dev servers, seed databases, configure env vars
 3. **User only does what requires human judgment** - Visual checks, UX evaluation, "does this feel right?"
 4. **Secrets come from user, automation comes from OpenCode** - Ask for API keys, then OpenCode uses them via CLI
-5. **Auto-mode bypasses verification/decision checkpoints** — When `workflow.auto_advance` is true in config: human-verify auto-approves, decision auto-selects first option, human-action still stops (auth gates cannot be automated)
+5. **Auto-mode bypasses verification/decision checkpoints** — When `workflow._auto_chain_active` or `workflow.auto_advance` is true in config: human-verify auto-approves, decision auto-selects first option, human-action still stops (auth gates cannot be automated)
 </overview>
 
 <checkpoint_types>

package/get-shit-done/references/decimal-phase-calculation.md

@@ -6,7 +6,7 @@ Calculate the next decimal phase number for urgent insertions.
 
 ```bash
 # Get next decimal phase after phase 6
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs phase next-decimal 6
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" phase next-decimal 6
 ```
 
 Output:
@@ -32,14 +32,14 @@ With existing decimals:
 ## Extract Values
 
 ```bash
-DECIMAL_INFO=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs phase next-decimal "${AFTER_PHASE}")
-DECIMAL_PHASE=$(echo "$DECIMAL_INFO" | jq -r '.next')
-BASE_PHASE=$(echo "$DECIMAL_INFO" | jq -r '.base_phase')
+DECIMAL_INFO=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" phase next-decimal "${AFTER_PHASE}")
+DECIMAL_PHASE=$(printf '%s\n' "$DECIMAL_INFO" | jq -r '.next')
+BASE_PHASE=$(printf '%s\n' "$DECIMAL_INFO" | jq -r '.base_phase')
 ```
 
 Or with --raw flag:
 ```bash
-DECIMAL_PHASE=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs phase next-decimal "${AFTER_PHASE}" --raw)
+DECIMAL_PHASE=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" phase next-decimal "${AFTER_PHASE}" --raw)
 # Returns just: 06.1
 ```
 
@@ -57,7 +57,7 @@ DECIMAL_PHASE=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs phase ne
 Decimal phase directories use the full decimal number:
 
 ```bash
-SLUG=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs generate-slug "$DESCRIPTION" --raw)
+SLUG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" generate-slug "$DESCRIPTION" --raw)
 PHASE_DIR=".planning/phases/${DECIMAL_PHASE}-${SLUG}"
 mkdir -p "$PHASE_DIR"
 ```

package/get-shit-done/references/git-integration.md

@@ -51,7 +51,7 @@ Phases:
 What to commit:
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "docs: initialize [project-name] ([N] phases)" --files .planning/
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: initialize [project-name] ([N] phases)" --files .planning/
 ```
 
 </format>
@@ -129,7 +129,7 @@ SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
 What to commit:
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
 ```
 
 **Note:** Code files NOT included - already committed per-task.
@@ -149,7 +149,7 @@ Current: [task name]
 What to commit:
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
 ```
 
 </format>

package/get-shit-done/references/git-planning-commit.md

@@ -7,7 +7,7 @@ Commit planning artifacts using the gsd-tools CLI, which automatically checks `c
 Always use `gsd-tools.cjs commit` for `.planning/` files — it handles `commit_docs` and gitignore checks automatically:
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
 ```
 
 The CLI will return `skipped` (with reason) if `commit_docs` is `false` or `.planning/` is gitignored. No manual conditional checks needed.
@@ -17,7 +17,7 @@ The CLI will return `skipped` (with reason) if `commit_docs` is `false` or `.pla
 To fold `.planning/` file changes into the previous commit:
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "" --files .planning/codebase/*.md --amend
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "" --files .planning/codebase/*.md --amend
 ```
 
 ## Commit Message Patterns

package/get-shit-done/references/model-profile-resolution.md

@@ -12,7 +12,7 @@ Default: `simple` if not set or config missing.
 
 ## Lookup Table
 
-@~/.config/opencode/get-shit-done/references/model-profiles.md
+@$HOME/.config/opencode/get-shit-done/references/model-profiles.md
 
 Look up the agent in the table for the resolved profile. Pass the model parameter to task calls:
 

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

@@ -17,6 +17,7 @@ Model profiles control which OpenCode model each GSD agent uses. This allows bal
 | 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/references/phase-argument-parsing.md

@@ -14,7 +14,7 @@ From `$ARGUMENTS`:
 The `find-phase` command handles normalization and validation in one step:
 
 ```bash
-PHASE_INFO=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs find-phase "${PHASE}")
+PHASE_INFO=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" find-phase "${PHASE}")
 ```
 
 Returns JSON with:
@@ -45,8 +45,8 @@ fi
 Use `roadmap get-phase` to validate phase exists:
 
 ```bash
-PHASE_CHECK=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs roadmap get-phase "${PHASE}")
-if [ "$(echo "$PHASE_CHECK" | jq -r '.found')" = "false" ]; then
+PHASE_CHECK=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${PHASE}")
+if [ "$(printf '%s\n' "$PHASE_CHECK" | jq -r '.found')" = "false" ]; then
   echo "ERROR: Phase ${PHASE} not found in roadmap"
   exit 1
 fi
@@ -57,5 +57,5 @@ fi
 Use `find-phase` for directory lookup:
 
 ```bash
-PHASE_DIR=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs find-phase "${PHASE}" --raw)
+PHASE_DIR=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" find-phase "${PHASE}" --raw)
 ```

package/get-shit-done/references/planning-config.md

@@ -40,14 +40,16 @@ Configuration options for `.planning/` directory behavior.
 
 ```bash
 # Commit with automatic commit_docs + gitignore checks:
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "docs: update state" --files .planning/STATE.md
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: update state" --files .planning/STATE.md
 
 # Load config via state load (returns JSON):
-INIT=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs state load)
+INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state load)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # commit_docs is available in the JSON output
 
 # Or use init commands which include commit_docs:
-INIT=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs init execute-phase "1")
+INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init execute-phase "1")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # commit_docs is included in all init command outputs
 ```
 
@@ -56,7 +58,7 @@ INIT=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs init execute-phas
 **Commit via CLI (handles checks automatically):**
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "docs: update state" --files .planning/STATE.md
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: update state" --files .planning/STATE.md
 ```
 
 The CLI checks `commit_docs` config and gitignore status internally — no manual conditionals needed.
@@ -144,13 +146,15 @@ To use uncommitted mode:
 
 Use `init execute-phase` which returns all config as JSON:
 ```bash
-INIT=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs init execute-phase "1")
+INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init execute-phase "1")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # JSON output includes: branching_strategy, phase_branch_template, milestone_branch_template
 ```
 
 Or use `state load` for the config values:
 ```bash
-INIT=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs state load)
+INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state load)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # Parse branching_strategy, phase_branch_template, milestone_branch_template from JSON
 ```
 

package/get-shit-done/references/questioning.md

@@ -100,6 +100,23 @@ Users who want a slightly modified version of an option can select "Other" and r
 
 </using_askuserquestion>
 
+<freeform_rule>
+
+**When the user wants to explain freely, STOP using question.**
+
+If a user selects "Other" and their response signals they want to describe something in their own words (e.g., "let me describe it", "I'll explain", "something else", or any open-ended reply that isn't choosing/modifying an existing option), you MUST:
+
+1. **Ask your follow-up as plain text** — NOT via question
+2. **Wait for them to type at the normal prompt**
+3. **Resume question** only after processing their freeform response
+
+The same applies if YOU include a freeform-indicating option (like "Let me explain" or "Describe in detail") and the user selects it.
+
+**Wrong:** User says "let me describe it" → question("What feature?", ["Feature A", "Feature B", "Describe in detail"])
+**Right:** User says "let me describe it" → "Go ahead — what are you thinking?"
+
+</freeform_rule>
+
 <context_checklist>
 
 Use this as a **background checklist**, not a conversation structure. Check these mentally as you go. If gaps remain, weave questions naturally.

package/get-shit-done/references/verification-patterns.md

@@ -600,7 +600,7 @@ Some things can't be verified programmatically. Flag these for human testing:
 
 For automation-first checkpoint patterns, server lifecycle management, CLI installation handling, and error recovery protocols, see:
 
-**@~/.config/opencode/get-shit-done/references/checkpoints.md** → `<automation_reference>` section
+**@$HOME/.config/opencode/get-shit-done/references/checkpoints.md** → `<automation_reference>` section
 
 Key principles:
 - OpenCode sets up verification environment BEFORE presenting checkpoints

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

@@ -8,7 +8,7 @@ Template for `.planning/debug/[slug].md` — active debug session tracking.
 
 ```markdown
 ---
-status: gathering | investigating | fixing | verifying | resolved
+status: gathering | investigating | fixing | verifying | awaiting_human_verify | resolved
 trigger: "[verbatim user input]"
 created: [ISO timestamp]
 updated: [ISO timestamp]
@@ -127,9 +127,14 @@ files_changed: []
 - Update Resolution.verification with results
 - If verification fails: status → "investigating", try again
 
+**After self-verification passes:**
+- status -> "awaiting_human_verify"
+- Request explicit user confirmation in a checkpoint
+- Do NOT move file to resolved yet
+
 **On resolution:**
 - status → "resolved"
-- Move file to .planning/debug/resolved/
+- Move file to .planning/debug/resolved/ (only after user confirms fix)
 
 </lifecycle>