gsd-opencode 1.30.0 → 1.33.1

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

@@ -0,0 +1,267 @@
+/**
+ * Docs — Commands for the docs-update workflow
+ *
+ * Provides `cmdDocsInit` which returns project signals, existing doc inventory
+ * with GSD marker detection, doc tooling detection, monorepo awareness, and
+ * model resolution. Used by Phase 2 to route doc generation appropriately.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, loadConfig, resolveModelInternal, pathExistsInternal, toPosixPath, checkAgentsInstalled } = require('./core.cjs');
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const GSD_MARKER = '<!-- generated-by: gsd-doc-writer -->';
+
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.planning', '.OpenCode', '__pycache__',
+  'target', 'dist', 'build', '.next', '.nuxt', 'coverage',
+  '.vscode', '.idea',
+]);
+
+// ─── Private helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Check whether a file begins with the GSD doc writer marker.
+ * Reads the first 500 bytes only — avoids loading large files.
+ *
+ * @param {string} filePath - Absolute path to the file
+ * @returns {boolean}
+ */
+function hasGsdMarker(filePath) {
+  try {
+    const buf = Buffer.alloc(500);
+    const fd = fs.openSync(filePath, 'r');
+    const bytesRead = fs.readSync(fd, buf, 0, 500, 0);
+    fs.closeSync(fd);
+    return buf.slice(0, bytesRead).toString('utf-8').includes(GSD_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Recursively scan the project root (immediate .md files) and docs/ directory
+ * (up to 4 levels deep) for Markdown files, excluding dirs in SKIP_DIRS.
+ *
+ * @param {string} cwd - Project root
+ * @returns {Array<{path: string, has_gsd_marker: boolean}>}
+ */
+function scanExistingDocs(cwd) {
+  const MAX_DEPTH = 4;
+  const results = [];
+
+  /**
+   * Recursively walk a directory for .md files up to MAX_DEPTH levels.
+   * @param {string} dir - Directory to scan
+   * @param {number} depth - Current depth (1-based)
+   */
+  function walkDir(dir, depth) {
+    if (depth > MAX_DEPTH) return;
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        const abs = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walkDir(abs, depth + 1);
+        } else if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+          const rel = toPosixPath(path.relative(cwd, abs));
+          results.push({ path: rel, has_gsd_marker: hasGsdMarker(abs) });
+        }
+      }
+    } catch { /* directory may not exist — best-effort */ }
+  }
+
+  // Scan root-level .md files (non-recursive)
+  try {
+    const entries = fs.readdirSync(cwd, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+        const abs = path.join(cwd, entry.name);
+        const rel = toPosixPath(path.relative(cwd, abs));
+        results.push({ path: rel, has_gsd_marker: hasGsdMarker(abs) });
+      }
+    }
+  } catch { /* best-effort */ }
+
+  // Recursively scan docs/ directory
+  const docsDir = path.join(cwd, 'docs');
+  walkDir(docsDir, 1);
+
+  // Fallback: if docs/ does not exist, try documentation/ or doc/
+  try {
+    fs.statSync(docsDir);
+  } catch {
+    const alternatives = ['documentation', 'doc'];
+    for (const alt of alternatives) {
+      const altDir = path.join(cwd, alt);
+      try {
+        const stat = fs.statSync(altDir);
+        if (stat.isDirectory()) {
+          walkDir(altDir, 1);
+          break;
+        }
+      } catch { /* not present */ }
+    }
+  }
+
+  return results.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * Detect project type signals from the filesystem and package.json.
+ * All checks are best-effort and never throw.
+ *
+ * @param {string} cwd - Project root
+ * @returns {Object} Boolean signal fields
+ */
+function detectProjectType(cwd) {
+  const exists = (rel) => {
+    try { return pathExistsInternal(cwd, rel); } catch { return false; }
+  };
+
+  // has_cli_bin: package.json has a `bin` field
+  let has_cli_bin = false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
+    has_cli_bin = !!(pkg.bin && (typeof pkg.bin === 'string' || Object.keys(pkg.bin).length > 0));
+  } catch { /* no package.json or invalid JSON */ }
+
+  // is_monorepo: pnpm-workspace.yaml, lerna.json, or package.json workspaces
+  let is_monorepo = exists('pnpm-workspace.yaml') || exists('lerna.json');
+  if (!is_monorepo) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
+      is_monorepo = Array.isArray(pkg.workspaces) && pkg.workspaces.length > 0;
+    } catch { /* ignore */ }
+  }
+
+  // has_tests: common test directories or test frameworks in devDependencies
+  let has_tests = exists('test') || exists('tests') || exists('__tests__') || exists('spec');
+  if (!has_tests) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
+      const devDeps = Object.keys(pkg.devDependencies || {});
+      has_tests = devDeps.some(d => ['vitest', 'jest', 'mocha', 'jasmine', 'ava'].includes(d));
+    } catch { /* ignore */ }
+  }
+
+  // has_deploy_config: various deployment config files
+  const deployFiles = [
+    'Dockerfile', 'docker-compose.yml', 'docker-compose.yaml',
+    'fly.toml', 'render.yaml', 'vercel.json', 'netlify.toml', 'railway.json',
+    '.github/workflows/deploy.yml', '.github/workflows/deploy.yaml',
+  ];
+  const has_deploy_config = deployFiles.some(f => exists(f));
+
+  return {
+    has_package_json: exists('package.json'),
+    has_api_routes: (
+      exists('src/app/api') || exists('routes') || exists('src/routes') ||
+      exists('api') || exists('server')
+    ),
+    has_cli_bin,
+    is_open_source: exists('LICENSE') || exists('LICENSE.md'),
+    has_deploy_config,
+    is_monorepo,
+    has_tests,
+  };
+}
+
+/**
+ * Detect known documentation tooling in the project.
+ *
+ * @param {string} cwd - Project root
+ * @returns {Object} Boolean detection fields
+ */
+function detectDocTooling(cwd) {
+  const exists = (rel) => {
+    try { return pathExistsInternal(cwd, rel); } catch { return false; }
+  };
+
+  return {
+    docusaurus: exists('docusaurus.config.js') || exists('docusaurus.config.ts'),
+    vitepress: (
+      exists('.vitepress/config.js') ||
+      exists('.vitepress/config.ts') ||
+      exists('.vitepress/config.mts')
+    ),
+    mkdocs: exists('mkdocs.yml'),
+    storybook: exists('.storybook'),
+  };
+}
+
+/**
+ * Extract monorepo workspace globs from pnpm-workspace.yaml, package.json
+ * workspaces, or lerna.json.
+ *
+ * @param {string} cwd - Project root
+ * @returns {string[]} Array of workspace glob patterns, or [] if not a monorepo
+ */
+function detectMonorepoWorkspaces(cwd) {
+  // pnpm-workspace.yaml
+  try {
+    const content = fs.readFileSync(path.join(cwd, 'pnpm-workspace.yaml'), 'utf-8');
+    const lines = content.split('\n');
+    const workspaces = [];
+    for (const line of lines) {
+      const m = line.match(/^\s*-\s+['"]?(.+?)['"]?\s*$/);
+      if (m) workspaces.push(m[1].trim());
+    }
+    if (workspaces.length > 0) return workspaces;
+  } catch { /* not present */ }
+
+  // package.json workspaces
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
+    if (Array.isArray(pkg.workspaces) && pkg.workspaces.length > 0) {
+      return pkg.workspaces;
+    }
+  } catch { /* not present or invalid */ }
+
+  // lerna.json
+  try {
+    const lerna = JSON.parse(fs.readFileSync(path.join(cwd, 'lerna.json'), 'utf-8'));
+    if (Array.isArray(lerna.packages) && lerna.packages.length > 0) {
+      return lerna.packages;
+    }
+  } catch { /* not present or invalid */ }
+
+  return [];
+}
+
+// ─── Public commands ──────────────────────────────────────────────────────────
+
+/**
+ * Return JSON context for the docs-update workflow: project signals, existing
+ * doc inventory, doc tooling detection, monorepo workspaces, and model
+ * resolution. Follows the cmdInitMapCodebase pattern.
+ *
+ * @example
+ * node gsd-tools.cjs docs-init --raw
+ *
+ * @param {string} cwd - Project root directory
+ * @param {boolean} raw - Pass raw JSON flag through to output()
+ */
+function cmdDocsInit(cwd, raw) {
+  const config = loadConfig(cwd);
+  const result = {
+    doc_writer_model: resolveModelInternal(cwd, 'gsd-doc-writer'),
+    commit_docs: config.commit_docs,
+    existing_docs: scanExistingDocs(cwd),
+    project_type: detectProjectType(cwd),
+    doc_tooling: detectDocTooling(cwd),
+    monorepo_workspaces: detectMonorepoWorkspaces(cwd),
+    planning_exists: pathExistsInternal(cwd, '.planning'),
+  };
+  // Inject project_root and agent installation status (mirrors withProjectRoot in init.cjs)
+  result.project_root = cwd;
+  const agentStatus = checkAgentsInstalled();
+  result.agents_installed = agentStatus.agents_installed;
+  result.missing_agents = agentStatus.missing_agents;
+  output(result, raw);
+}
+
+module.exports = { cmdDocsInit };

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

@@ -8,6 +8,38 @@ const { safeReadFile, normalizeMd, output, error } = require('./core.cjs');
 
 // ─── Parsing engine ───────────────────────────────────────────────────────────
 
+/**
+ * Split a YAML inline array body on commas, respecting quoted strings.
+ * e.g. '"a, b", c' → ['a, b', 'c']
+ */
+function splitInlineArray(body) {
+  const items = [];
+  let current = '';
+  let inQuote = null; // null | '"' | "'"
+
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i];
+    if (inQuote) {
+      if (ch === inQuote) {
+        inQuote = null;
+      } else {
+        current += ch;
+      }
+    } else if (ch === '"' || ch === "'") {
+      inQuote = ch;
+    } else if (ch === ',') {
+      const trimmed = current.trim();
+      if (trimmed) items.push(trimmed);
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  const trimmed = current.trim();
+  if (trimmed) items.push(trimmed);
+  return items;
+}
+
 function extractFrontmatter(content) {
   const frontmatter = {};
   // Find ALL frontmatter blocks at the start of the file.
@@ -53,8 +85,8 @@ function extractFrontmatter(content) {
         // Push new context for potential nested content
         stack.push({ obj: current.obj[key], key: null, indent });
       } else if (value.startsWith('[') && value.endsWith(']')) {
-        // Inline array: key: [a, b, c]
-        current.obj[key] = value.slice(1, -1).split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+        // Inline array: key: [a, b, c] — quote-aware split (REG-04 fix)
+        current.obj[key] = splitInlineArray(value.slice(1, -1));
         current.key = null;
       } else {
         // Simple key: value
@@ -252,6 +284,19 @@ function parseMustHavesBlock(content, blockName) {
   }
   if (current) items.push(current);
 
+  // Warn when must_haves block exists but parsed as empty -- likely YAML formatting issue.
+  // This is a critical diagnostic: empty must_haves causes verification to silently degrade
+  // to Option C (LLM-derived truths) instead of checking documented contracts.
+  if (items.length === 0 && blockLines.length > 0) {
+    const nonEmptyLines = blockLines.filter(l => l.trim() !== '').length;
+    if (nonEmptyLines > 0) {
+      process.stderr.write(
+        `[gsd-tools] WARNING: must_haves.${blockName} block has ${nonEmptyLines} content lines but parsed 0 items. ` +
+        `Possible YAML formatting issue — verification will fall back to LLM-derived truths.\n`
+      );
+    }
+  }
+
   return items;
 }
 

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

@@ -5,7 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const { loadConfig, resolveModelInternal, findPhaseInternal, getRoadmapPhaseInternal, pathExistsInternal, generateSlugInternal, getMilestoneInfo, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, normalizePhaseName, planningPaths, planningDir, planningRoot, toPosixPath, output, error, checkAgentsInstalled } = require('./core.cjs');
+const { loadConfig, resolveModelInternal, findPhaseInternal, getRoadmapPhaseInternal, pathExistsInternal, generateSlugInternal, getMilestoneInfo, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, normalizePhaseName, planningPaths, planningDir, planningRoot, toPosixPath, output, error, checkAgentsInstalled, phaseTokenMatches } = require('./core.cjs');
 
 function getLatestCompletedMilestone(cwd) {
   const milestonesPath = path.join(planningRoot(cwd), 'MILESTONES.md');
@@ -37,10 +37,17 @@ function withProjectRoot(cwd, result) {
   const agentStatus = checkAgentsInstalled();
   result.agents_installed = agentStatus.agents_installed;
   result.missing_agents = agentStatus.missing_agents;
+  // Inject response_language into all init outputs (#1399).
+  // Workflows propagate this to subagent prompts so user-facing questions
+  // stay in the configured language across phase boundaries.
+  const config = loadConfig(cwd);
+  if (config.response_language) {
+    result.response_language = config.response_language;
+  }
   return result;
 }
 
-function cmdInitExecutePhase(cwd, phase, raw) {
+function cmdInitExecutePhase(cwd, phase, raw, options = {}) {
   if (!phase) {
     error('phase required for init execute-phase');
   }
@@ -108,6 +115,7 @@ function cmdInitExecutePhase(cwd, phase, raw) {
     // Branch name (pre-computed)
     branch_name: config.branching_strategy === 'phase' && phaseInfo
       ? config.phase_branch_template
+          .replace('{project}', config.project_code || '')
           .replace('{phase}', phaseInfo.phase_number)
           .replace('{slug}', phaseInfo.phase_slug || 'phase')
       : config.branching_strategy === 'milestone'
@@ -131,10 +139,38 @@ function cmdInitExecutePhase(cwd, phase, raw) {
     config_path: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'config.json'))),
   };
 
+  // Optional --validate: run state validation and include warnings (#1627)
+  if (options.validate) {
+    try {
+      const { cmdStateValidate } = require('./state.cjs');
+      // Capture validate output by temporarily redirecting
+      const statePath = path.join(planningDir(cwd), 'STATE.md');
+      if (fs.existsSync(statePath)) {
+        const stateContent = fs.readFileSync(statePath, 'utf-8');
+        const { stateExtractField } = require('./state.cjs');
+        const status = stateExtractField(stateContent, 'Status') || '';
+        result.state_validation_ran = true;
+        // Simple inline validation — check for obvious drift
+        const warnings = [];
+        const phasesPath = planningPaths(cwd).phases;
+        if (phaseInfo && phaseInfo.directory && fs.existsSync(path.join(cwd, phaseInfo.directory))) {
+          const files = fs.readdirSync(path.join(cwd, phaseInfo.directory));
+          const diskPlans = files.filter(f => f.match(/-PLAN\.md$/i)).length;
+          const totalPlansRaw = stateExtractField(stateContent, 'Total Plans in Phase');
+          const totalPlansInPhase = totalPlansRaw ? parseInt(totalPlansRaw, 10) : null;
+          if (totalPlansInPhase !== null && diskPlans !== totalPlansInPhase) {
+            warnings.push(`Plan count mismatch: STATE.md says ${totalPlansInPhase}, disk has ${diskPlans}`);
+          }
+        }
+        result.state_warnings = warnings;
+      }
+    } catch { /* intentionally empty */ }
+  }
+
   output(withProjectRoot(cwd, result), raw);
 }
 
-function cmdInitPlanPhase(cwd, phase, raw) {
+function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
   if (!phase) {
     error('phase required for init plan-phase');
   }
@@ -235,6 +271,25 @@ function cmdInitPlanPhase(cwd, phase, raw) {
     } catch { /* intentionally empty */ }
   }
 
+  // Optional --validate: run state validation and include warnings (#1627)
+  if (options.validate) {
+    try {
+      const statePath = path.join(planningDir(cwd), 'STATE.md');
+      if (fs.existsSync(statePath)) {
+        const { stateExtractField } = require('./state.cjs');
+        const stateContent = fs.readFileSync(statePath, 'utf-8');
+        const warnings = [];
+        result.state_validation_ran = true;
+        const totalPlansRaw = stateExtractField(stateContent, 'Total Plans in Phase');
+        const totalPlansInPhase = totalPlansRaw ? parseInt(totalPlansRaw, 10) : null;
+        if (totalPlansInPhase !== null && phaseInfo && totalPlansInPhase !== (phaseInfo.plans?.length || 0)) {
+          warnings.push(`Plan count mismatch: STATE.md says ${totalPlansInPhase}, disk has ${phaseInfo.plans?.length || 0}`);
+        }
+        result.state_warnings = warnings;
+      }
+    } catch { /* intentionally empty */ }
+  }
+
   output(withProjectRoot(cwd, result), raw);
 }
 
@@ -275,7 +330,7 @@ function cmdInitNewProject(cwd, raw) {
       '.ex', '.exs',           // Elixir
       '.clj',                  // Clojure
     ]);
-    const skipDirs = new Set(['node_modules', '.git', '.planning', '.OpenCode', '__pycache__', 'target', 'dist', 'build']);
+    const skipDirs = new Set(['node_modules', '.git', '.planning', '.OpenCode', '.codex', '__pycache__', 'target', 'dist', 'build']);
     function findCodeFiles(dir, depth) {
       if (depth > 3) return false;
       let entries;
@@ -779,6 +834,7 @@ function cmdInitMapCodebase(cwd, raw) {
     commit_docs: config.commit_docs,
     search_gitignored: config.search_gitignored,
     parallelization: config.parallelization,
+    subagent_timeout: config.subagent_timeout,
 
     // Paths
     codebase_dir: '.planning/codebase',
@@ -846,7 +902,7 @@ function cmdInitManager(cwd, raw) {
     try {
       const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
       const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).filter(isDirInMilestone);
-      const dirMatch = dirs.find(d => d.startsWith(normalized + '-') || d === normalized);
+      const dirMatch = dirs.find(d => phaseTokenMatches(d, normalized));
 
       if (dirMatch) {
         const fullDir = path.join(phasesDir, dirMatch);
@@ -954,9 +1010,11 @@ function cmdInitManager(cwd, raw) {
   } catch { /* intentionally empty */ }
 
   // Compute recommended actions (execute > plan > discuss)
+  // Skip BACKLOG phases (999.x numbering) — they are parked ideas, not active work
   const recommendedActions = [];
   for (const phase of phases) {
     if (phase.disk_status === 'complete') continue;
+    if (/^999(?:\.|$)/.test(phase.number)) continue;
 
     if (phase.disk_status === 'planned' && phase.deps_satisfied) {
       recommendedActions.push({
@@ -1024,6 +1082,27 @@ function cmdInitManager(cwd, raw) {
   });
 
   const completedCount = phases.filter(p => p.disk_status === 'complete').length;
+
+  // read manager flags from config (passthrough flags for each step)
+  // Validate: flags must be CLI-safe (only --flags, alphanumeric, hyphens, spaces)
+  const sanitizeFlags = (raw) => {
+    const val = typeof raw === 'string' ? raw : '';
+    if (!val) return '';
+    // Allow only --flag patterns with alphanumeric/hyphen values separated by spaces
+    const tokens = val.split(/\s+/).filter(Boolean);
+    const safe = tokens.every(t => /^--[a-zA-Z0-9][-a-zA-Z0-9]*$/.test(t) || /^[a-zA-Z0-9][-a-zA-Z0-9_.]*$/.test(t));
+    if (!safe) {
+      process.stderr.write(`gsd-tools: warning: manager.flags contains invalid tokens, ignoring: ${val}\n`);
+      return '';
+    }
+    return val;
+  };
+  const managerFlags = {
+    discuss: sanitizeFlags(config.manager && config.manager.flags && config.manager.flags.discuss),
+    plan: sanitizeFlags(config.manager && config.manager.flags && config.manager.flags.plan),
+    execute: sanitizeFlags(config.manager && config.manager.flags && config.manager.flags.execute),
+  };
+
   const result = {
     milestone_version: milestone.version,
     milestone_name: milestone.name,
@@ -1037,6 +1116,7 @@ function cmdInitManager(cwd, raw) {
     project_exists: pathExistsInternal(cwd, '.planning/PROJECT.md'),
     roadmap_exists: true,
     state_exists: true,
+    manager_flags: managerFlags,
   };
 
   output(withProjectRoot(cwd, result), raw);

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

@@ -246,7 +246,28 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
   output(result, raw);
 }
 
+function cmdPhasesClear(cwd, raw) {
+  const phasesDir = planningPaths(cwd).phases;
+  let cleared = 0;
+
+  if (fs.existsSync(phasesDir)) {
+    try {
+      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        fs.rmSync(path.join(phasesDir, entry.name), { recursive: true, force: true });
+        cleared++;
+      }
+    } catch (e) {
+      error('Failed to clear phases directory: ' + e.message);
+    }
+  }
+
+  output({ cleared }, raw, `${cleared} phase director${cleared === 1 ? 'y' : 'ies'} cleared`);
+}
+
 module.exports = {
   cmdRequirementsMarkComplete,
   cmdMilestoneComplete,
+  cmdPhasesClear,
 };

package/get-shit-done/bin/lib/model-profiles.cjs

@@ -22,6 +22,8 @@ const MODEL_PROFILES = {
   'gsd-ui-researcher': { quality: 'opus', balanced: 'sonnet', budget: 'haiku' },
   'gsd-ui-checker': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
   'gsd-ui-auditor': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-doc-writer': { quality: 'opus', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-doc-verifier': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
 };
 const VALID_PROFILES = Object.keys(MODEL_PROFILES['gsd-planner']);