@sienklogic/plan-build-run 2.21.0 → 2.21.2

package/plugins/pbr/scripts/lib/ci-fix-loop.js

@@ -0,0 +1,228 @@
+'use strict';
+
+/**
+ * lib/ci-fix-loop.js -- Self-healing CI fix loop for Plan-Build-Run.
+ *
+ * Parses Jest and ESLint output, auto-fixes lint errors via `eslint --fix`,
+ * and iterates up to N times to achieve a passing CI run.
+ *
+ * Exports:
+ *   parseJestOutput(stdout)    -- Extract pass/fail info from Jest output
+ *   parseLintOutput(stdout)    -- Extract errors from ESLint output
+ *   autoFixLint(cwd)           -- Run eslint --fix on project directories
+ *   runCiFixLoop(options)      -- Iterative test+fix loop
+ */
+
+const { execSync } = require('child_process');
+
+/**
+ * Parse Jest's default output format.
+ *
+ * Looks for:
+ *   - "FAIL path/to/test.js" lines to extract failed suite paths
+ *   - "Test Suites: N failed, M passed, T total" summary line
+ *
+ * @param {string} stdout - Combined stdout+stderr from `npm test`
+ * @returns {{ passed: boolean, failedSuites: string[], summary: string }}
+ */
+function parseJestOutput(stdout) {
+  if (!stdout || typeof stdout !== 'string') {
+    return { passed: false, failedSuites: [], summary: '' };
+  }
+
+  const lines = stdout.split('\n');
+
+  // Extract failed suite paths from "FAIL path/to/test.js" lines
+  const failedSuites = [];
+  for (const line of lines) {
+    const failMatch = line.match(/^\s*FAIL\s+(.+?)(?:\s|$)/);
+    if (failMatch) {
+      failedSuites.push(failMatch[1].trim());
+    }
+  }
+
+  // Extract the summary line
+  let summary = '';
+  for (const line of lines) {
+    if (/Test Suites:\s/.test(line)) {
+      summary = line.trim();
+      break;
+    }
+  }
+
+  // Determine pass/fail: passed if summary exists with no failures, or no FAIL lines
+  let passed = false;
+  if (summary) {
+    // "Test Suites: 0 failed" or no "failed" keyword means pass
+    const failedMatch = summary.match(/(\d+)\s+failed/);
+    passed = !failedMatch || parseInt(failedMatch[1], 10) === 0;
+  } else if (failedSuites.length === 0 && lines.some(l => /PASS\s/.test(l))) {
+    // No summary line but has PASS lines and no FAIL lines
+    passed = true;
+  }
+
+  return { passed, failedSuites, summary };
+}
+
+/**
+ * Parse ESLint's default (stylish) output format.
+ *
+ * Format:
+ *   /path/to/file.js
+ *     line:col  error  message  rule-name
+ *     line:col  warning  message  rule-name
+ *
+ *   N problems (X errors, Y warnings)
+ *
+ * @param {string} stdout - Output from `npm run lint` or `npx eslint`
+ * @returns {{ errorCount: number, files: string[], errors: Array<{file: string, line: number, col: number, message: string, rule: string}> }}
+ */
+function parseLintOutput(stdout) {
+  if (!stdout || typeof stdout !== 'string') {
+    return { errorCount: 0, files: [], errors: [] };
+  }
+
+  const lines = stdout.split('\n');
+  const errors = [];
+  const filesSet = new Set();
+  let currentFile = '';
+
+  for (const line of lines) {
+    // File header: a line that looks like a path (starts with / or drive letter, no leading spaces)
+    const fileMatch = line.match(/^([A-Za-z]:[\\/]|\/)[^\s].*\.[a-zA-Z]+$/);
+    if (fileMatch) {
+      currentFile = line.trim();
+      continue;
+    }
+
+    // Error/warning line: "  line:col  error  message  rule-name"
+    const errorMatch = line.match(/^\s+(\d+):(\d+)\s+(error|warning)\s+(.+?)\s{2,}(\S+)\s*$/);
+    if (errorMatch && currentFile) {
+      const severity = errorMatch[3];
+      if (severity === 'error') {
+        filesSet.add(currentFile);
+        errors.push({
+          file: currentFile,
+          line: parseInt(errorMatch[1], 10),
+          col: parseInt(errorMatch[2], 10),
+          message: errorMatch[4].trim(),
+          rule: errorMatch[5].trim()
+        });
+      }
+    }
+  }
+
+  return {
+    errorCount: errors.length,
+    files: Array.from(filesSet),
+    errors
+  };
+}
+
+/**
+ * Run `npx eslint --fix` on standard project directories.
+ *
+ * @param {string} cwd - Project root directory
+ * @returns {{ fixed: boolean, output: string }}
+ */
+function autoFixLint(cwd) {
+  try {
+    const output = execSync(
+      'npx eslint --fix hooks/ plugins/pbr/scripts/ tests/ --ext .js,.cjs',
+      { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+    return { fixed: true, output: output || '' };
+  } catch (err) {
+    // eslint --fix exits non-zero if unfixable errors remain
+    const output = (err.stdout || '') + (err.stderr || '');
+    return { fixed: true, output };
+  }
+}
+
+/**
+ * Iterative CI fix loop: test -> lint -> fix -> re-test.
+ *
+ * @param {object} options
+ * @param {string} options.cwd - Project root directory
+ * @param {number} [options.maxIterations=3] - Max fix iterations
+ * @param {boolean} [options.dryRun=false] - If true, skip actual fix commands
+ * @returns {{ success: boolean, iterations: number, actions: string[], testResult: object, lintResult: object }}
+ */
+function runCiFixLoop(options = {}) {
+  const {
+    cwd = process.cwd(),
+    maxIterations = 3,
+    dryRun = false
+  } = options;
+
+  const actions = [];
+  let testResult = { passed: false, failedSuites: [], summary: '' };
+  let lintResult = { errorCount: 0, files: [], errors: [] };
+
+  for (let i = 1; i <= maxIterations; i++) {
+    // Step a: Run tests
+    actions.push(`iteration ${i}: running tests`);
+    let testOutput = '';
+    try {
+      testOutput = execSync('npm test', {
+        cwd,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 120000
+      });
+    } catch (err) {
+      testOutput = (err.stdout || '') + (err.stderr || '');
+    }
+
+    testResult = parseJestOutput(testOutput);
+
+    // Step b: If all tests pass, return success
+    if (testResult.passed) {
+      actions.push(`iteration ${i}: all tests passed`);
+      return { success: true, iterations: i, actions, testResult, lintResult };
+    }
+
+    // Step c: Run lint
+    actions.push(`iteration ${i}: running lint`);
+    let lintOutput = '';
+    try {
+      lintOutput = execSync('npm run lint', {
+        cwd,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 60000
+      });
+    } catch (err) {
+      lintOutput = (err.stdout || '') + (err.stderr || '');
+    }
+
+    lintResult = parseLintOutput(lintOutput);
+
+    // Step d: If lint errors found, run autofix
+    if (lintResult.errorCount > 0) {
+      if (dryRun) {
+        actions.push(`iteration ${i}: would fix ${lintResult.errorCount} lint errors (dry-run)`);
+      } else {
+        actions.push(`iteration ${i}: fixing ${lintResult.errorCount} lint errors`);
+        autoFixLint(cwd);
+      }
+      // Continue loop to re-run tests
+      continue;
+    }
+
+    // Step e: No lint errors but tests still fail — not a lint issue
+    actions.push(`iteration ${i}: no lint errors, test failures are not lint-related`);
+    return { success: false, iterations: i, actions, testResult, lintResult };
+  }
+
+  // Exhausted iterations
+  actions.push(`exhausted ${maxIterations} iterations`);
+  return { success: false, iterations: maxIterations, actions, testResult, lintResult };
+}
+
+module.exports = {
+  parseJestOutput,
+  parseLintOutput,
+  autoFixLint,
+  runCiFixLoop
+};

package/plugins/pbr/scripts/lib/commands.js

@@ -0,0 +1,483 @@
+/* global fetch */
+/**
+ * Commands — Standalone utility commands
+ */
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { safeReadFile, loadConfig, isGitIgnored, execGit, normalizePhaseName, comparePhaseNum, getArchivedPhaseDirs, generateSlugInternal, getMilestoneInfo, resolveModelInternal, MODEL_PROFILES, toPosixPath, output, error, findPhaseInternal } = require('./core');
+const { extractFrontmatter } = require('./frontmatter');
+
+function cmdGenerateSlug(text, raw) {
+  if (!text) {
+    error('text required for slug generation');
+  }
+
+  const slug = text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+  const result = { slug };
+  output(result, raw, slug);
+}
+
+function cmdCurrentTimestamp(format, raw) {
+  const now = new Date();
+  let result;
+
+  switch (format) {
+    case 'date':
+      result = now.toISOString().split('T')[0];
+      break;
+    case 'filename':
+      result = now.toISOString().replace(/:/g, '-').replace(/\..+/, '');
+      break;
+    case 'full':
+    default:
+      result = now.toISOString();
+      break;
+  }
+
+  output({ timestamp: result }, raw, result);
+}
+
+function cmdVerifyPathExists(cwd, targetPath, raw) {
+  if (!targetPath) {
+    error('path required for verification');
+  }
+
+  const fullPath = path.isAbsolute(targetPath) ? targetPath : path.join(cwd, targetPath);
+
+  try {
+    const stats = fs.statSync(fullPath);
+    const type = stats.isDirectory() ? 'directory' : stats.isFile() ? 'file' : 'other';
+    const result = { exists: true, type };
+    output(result, raw, 'true');
+  } catch {
+    const result = { exists: false, type: null };
+    output(result, raw, 'false');
+  }
+}
+
+function cmdHistoryDigest(cwd, raw) {
+  const phasesDir = path.join(cwd, '.planning', 'phases');
+  const digest = { phases: {}, decisions: [], tech_stack: new Set() };
+
+  // Collect all phase directories: archived + current
+  const allPhaseDirs = [];
+
+  // Add archived phases first (oldest milestones first)
+  const archived = getArchivedPhaseDirs(cwd);
+  for (const a of archived) {
+    allPhaseDirs.push({ name: a.name, fullPath: a.fullPath, milestone: a.milestone });
+  }
+
+  // Add current phases
+  if (fs.existsSync(phasesDir)) {
+    try {
+      const currentDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
+        .filter(e => e.isDirectory())
+        .map(e => e.name)
+        .sort();
+      for (const dir of currentDirs) {
+        allPhaseDirs.push({ name: dir, fullPath: path.join(phasesDir, dir), milestone: null });
+      }
+    } catch { /* intentionally silent: phases directory may not exist */ }
+  }
+
+  if (allPhaseDirs.length === 0) {
+    digest.tech_stack = [];
+    output(digest, raw);
+    return;
+  }
+
+  try {
+    for (const { name: dir, fullPath: dirPath } of allPhaseDirs) {
+      const summaries = fs.readdirSync(dirPath).filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
+
+      for (const summary of summaries) {
+        try {
+          const content = fs.readFileSync(path.join(dirPath, summary), 'utf-8');
+          const fm = extractFrontmatter(content);
+
+          const phaseNum = fm.phase || dir.split('-')[0];
+
+          if (!digest.phases[phaseNum]) {
+            digest.phases[phaseNum] = {
+              name: fm.name || dir.split('-').slice(1).join(' ') || 'Unknown',
+              provides: new Set(),
+              affects: new Set(),
+              patterns: new Set(),
+            };
+          }
+
+          // Merge provides
+          if (fm['dependency-graph'] && fm['dependency-graph'].provides) {
+            fm['dependency-graph'].provides.forEach(p => digest.phases[phaseNum].provides.add(p));
+          } else if (fm.provides) {
+            fm.provides.forEach(p => digest.phases[phaseNum].provides.add(p));
+          }
+
+          // Merge affects
+          if (fm['dependency-graph'] && fm['dependency-graph'].affects) {
+            fm['dependency-graph'].affects.forEach(a => digest.phases[phaseNum].affects.add(a));
+          }
+
+          // Merge patterns
+          if (fm['patterns-established']) {
+            fm['patterns-established'].forEach(p => digest.phases[phaseNum].patterns.add(p));
+          }
+
+          // Merge decisions
+          if (fm['key-decisions']) {
+            fm['key-decisions'].forEach(d => {
+              digest.decisions.push({ phase: phaseNum, decision: d });
+            });
+          }
+
+          // Merge tech stack
+          if (fm['tech-stack'] && fm['tech-stack'].added) {
+            fm['tech-stack'].added.forEach(t => digest.tech_stack.add(typeof t === 'string' ? t : t.name));
+          }
+
+        } catch (e) {
+          // Skip malformed summaries
+        }
+      }
+    }
+
+    // Convert Sets to Arrays for JSON output
+    Object.keys(digest.phases).forEach(p => {
+      digest.phases[p].provides = [...digest.phases[p].provides];
+      digest.phases[p].affects = [...digest.phases[p].affects];
+      digest.phases[p].patterns = [...digest.phases[p].patterns];
+    });
+    digest.tech_stack = [...digest.tech_stack];
+
+    output(digest, raw);
+  } catch (e) {
+    error('Failed to generate history digest: ' + e.message);
+  }
+}
+
+function cmdResolveModel(cwd, agentType, raw) {
+  if (!agentType) {
+    error('agent-type required');
+  }
+
+  const config = loadConfig(cwd);
+  const profile = config.model_profile || 'balanced';
+  const model = resolveModelInternal(cwd, agentType);
+
+  const agentModels = MODEL_PROFILES[agentType];
+  const result = agentModels
+    ? { model, profile }
+    : { model, profile, unknown_agent: true };
+  output(result, raw, model);
+}
+
+function cmdCommit(cwd, message, files, raw, amend) {
+  if (!message && !amend) {
+    error('commit message required');
+  }
+
+  const config = loadConfig(cwd);
+
+  // Check commit_docs config
+  if (!config.commit_docs) {
+    const result = { committed: false, hash: null, reason: 'skipped_commit_docs_false' };
+    output(result, raw, 'skipped');
+    return;
+  }
+
+  // Check if .planning is gitignored
+  if (isGitIgnored(cwd, '.planning')) {
+    const result = { committed: false, hash: null, reason: 'skipped_gitignored' };
+    output(result, raw, 'skipped');
+    return;
+  }
+
+  // Stage files
+  const filesToStage = files && files.length > 0 ? files : ['.planning/'];
+  for (const file of filesToStage) {
+    execGit(cwd, ['add', file]);
+  }
+
+  // Commit
+  const commitArgs = amend ? ['commit', '--amend', '--no-edit'] : ['commit', '-m', message];
+  const commitResult = execGit(cwd, commitArgs);
+  if (commitResult.exitCode !== 0) {
+    if (commitResult.stdout.includes('nothing to commit') || commitResult.stderr.includes('nothing to commit')) {
+      const result = { committed: false, hash: null, reason: 'nothing_to_commit' };
+      output(result, raw, 'nothing');
+      return;
+    }
+    const result = { committed: false, hash: null, reason: 'nothing_to_commit', error: commitResult.stderr };
+    output(result, raw, 'nothing');
+    return;
+  }
+
+  // Get short hash
+  const hashResult = execGit(cwd, ['rev-parse', '--short', 'HEAD']);
+  const hash = hashResult.exitCode === 0 ? hashResult.stdout : null;
+  const result = { committed: true, hash, reason: 'committed' };
+  output(result, raw, hash || 'committed');
+}
+
+function cmdSummaryExtract(cwd, summaryPath, fields, raw) {
+  if (!summaryPath) {
+    error('summary-path required for summary-extract');
+  }
+
+  const fullPath = path.join(cwd, summaryPath);
+
+  if (!fs.existsSync(fullPath)) {
+    output({ error: 'File not found', path: summaryPath }, raw);
+    return;
+  }
+
+  const content = fs.readFileSync(fullPath, 'utf-8');
+  const fm = extractFrontmatter(content);
+
+  // Parse key-decisions into structured format
+  const parseDecisions = (decisionsList) => {
+    if (!decisionsList || !Array.isArray(decisionsList)) return [];
+    return decisionsList.map(d => {
+      const colonIdx = d.indexOf(':');
+      if (colonIdx > 0) {
+        return {
+          summary: d.substring(0, colonIdx).trim(),
+          rationale: d.substring(colonIdx + 1).trim(),
+        };
+      }
+      return { summary: d, rationale: null };
+    });
+  };
+
+  // Build full result
+  const fullResult = {
+    path: summaryPath,
+    one_liner: fm['one-liner'] || null,
+    key_files: fm['key-files'] || [],
+    tech_added: (fm['tech-stack'] && fm['tech-stack'].added) || [],
+    patterns: fm['patterns-established'] || [],
+    decisions: parseDecisions(fm['key-decisions']),
+    requirements_completed: fm['requirements-completed'] || [],
+  };
+
+  // If fields specified, filter to only those fields
+  if (fields && fields.length > 0) {
+    const filtered = { path: summaryPath };
+    for (const field of fields) {
+      if (fullResult[field] !== undefined) {
+        filtered[field] = fullResult[field];
+      }
+    }
+    output(filtered, raw);
+    return;
+  }
+
+  output(fullResult, raw);
+}
+
+async function cmdWebsearch(query, options, raw) {
+  const apiKey = process.env.BRAVE_API_KEY;
+
+  if (!apiKey) {
+    // No key = silent skip, agent falls back to built-in WebSearch
+    output({ available: false, reason: 'BRAVE_API_KEY not set' }, raw, '');
+    return;
+  }
+
+  if (!query) {
+    output({ available: false, error: 'Query required' }, raw, '');
+    return;
+  }
+
+  const params = new URLSearchParams({
+    q: query,
+    count: String(options.limit || 10),
+    country: 'us',
+    search_lang: 'en',
+    text_decorations: 'false'
+  });
+
+  if (options.freshness) {
+    params.set('freshness', options.freshness);
+  }
+
+  try {
+    const response = await fetch(
+      `https://api.search.brave.com/res/v1/web/search?${params}`,
+      {
+        headers: {
+          'Accept': 'application/json',
+          'X-Subscription-Token': apiKey
+        }
+      }
+    );
+
+    if (!response.ok) {
+      output({ available: false, error: `API error: ${response.status}` }, raw, '');
+      return;
+    }
+
+    const data = await response.json();
+
+    const results = (data.web?.results || []).map(r => ({
+      title: r.title,
+      url: r.url,
+      description: r.description,
+      age: r.age || null
+    }));
+
+    output({
+      available: true,
+      query,
+      count: results.length,
+      results
+    }, raw, results.map(r => `${r.title}\n${r.url}\n${r.description}`).join('\n\n'));
+  } catch (err) {
+    output({ available: false, error: err.message }, raw, '');
+  }
+}
+
+function cmdProgressRender(cwd, format, raw) {
+  const phasesDir = path.join(cwd, '.planning', 'phases');
+  const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md');
+  const milestone = getMilestoneInfo(cwd);
+
+  const phases = [];
+  let totalPlans = 0;
+  let totalSummaries = 0;
+
+  try {
+    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort((a, b) => comparePhaseNum(a, b));
+
+    for (const dir of dirs) {
+      const dm = dir.match(/^(\d+(?:\.\d+)*)-?(.*)/);
+      const phaseNum = dm ? dm[1] : dir;
+      const phaseName = dm && dm[2] ? dm[2].replace(/-/g, ' ') : '';
+      const phaseFiles = fs.readdirSync(path.join(phasesDir, dir));
+      const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').length;
+      const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').length;
+
+      totalPlans += plans;
+      totalSummaries += summaries;
+
+      let status;
+      if (plans === 0) status = 'Pending';
+      else if (summaries >= plans) status = 'Complete';
+      else if (summaries > 0) status = 'In Progress';
+      else status = 'Planned';
+
+      phases.push({ number: phaseNum, name: phaseName, plans, summaries, status });
+    }
+  } catch { /* intentionally silent: phase directory may not exist or be unreadable */ }
+
+  const percent = totalPlans > 0 ? Math.min(100, Math.round((totalSummaries / totalPlans) * 100)) : 0;
+
+  if (format === 'table') {
+    // Render markdown table
+    const barWidth = 10;
+    const filled = Math.round((percent / 100) * barWidth);
+    const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(barWidth - filled);
+    let out = `# ${milestone.version} ${milestone.name}\n\n`;
+    out += `**Progress:** [${bar}] ${totalSummaries}/${totalPlans} plans (${percent}%)\n\n`;
+    out += `| Phase | Name | Plans | Status |\n`;
+    out += `|-------|------|-------|--------|\n`;
+    for (const p of phases) {
+      out += `| ${p.number} | ${p.name} | ${p.summaries}/${p.plans} | ${p.status} |\n`;
+    }
+    output({ rendered: out }, raw, out);
+  } else if (format === 'bar') {
+    const barWidth = 20;
+    const filled = Math.round((percent / 100) * barWidth);
+    const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(barWidth - filled);
+    const text = `[${bar}] ${totalSummaries}/${totalPlans} plans (${percent}%)`;
+    output({ bar: text, percent, completed: totalSummaries, total: totalPlans }, raw, text);
+  } else {
+    // JSON format
+    output({
+      milestone_version: milestone.version,
+      milestone_name: milestone.name,
+      phases,
+      total_plans: totalPlans,
+      total_summaries: totalSummaries,
+      percent,
+    }, raw);
+  }
+}
+
+function cmdScaffold(cwd, type, options, raw) {
+  const { phase, name } = options;
+  const padded = phase ? normalizePhaseName(phase) : '00';
+  const today = new Date().toISOString().split('T')[0];
+
+  // Find phase directory
+  const phaseInfo = phase ? findPhaseInternal(cwd, phase) : null;
+  const phaseDir = phaseInfo ? path.join(cwd, phaseInfo.directory) : null;
+
+  if (phase && !phaseDir && type !== 'phase-dir') {
+    error(`Phase ${phase} directory not found`);
+  }
+
+  let filePath, content;
+
+  switch (type) {
+    case 'context': {
+      filePath = path.join(phaseDir, `${padded}-CONTEXT.md`);
+      content = `---\nphase: "${padded}"\nname: "${name || phaseInfo?.phase_name || 'Unnamed'}"\ncreated: ${today}\n---\n\n# Phase ${phase}: ${name || phaseInfo?.phase_name || 'Unnamed'} — Context\n\n## Decisions\n\n_Decisions will be captured during /pbr:discuss-phase ${phase}_\n\n## Discretion Areas\n\n_Areas where the executor can use judgment_\n\n## Deferred Ideas\n\n_Ideas to consider later_\n`;
+      break;
+    }
+    case 'uat': {
+      filePath = path.join(phaseDir, `${padded}-UAT.md`);
+      content = `---\nphase: "${padded}"\nname: "${name || phaseInfo?.phase_name || 'Unnamed'}"\ncreated: ${today}\nstatus: pending\n---\n\n# Phase ${phase}: ${name || phaseInfo?.phase_name || 'Unnamed'} — User Acceptance Testing\n\n## Test Results\n\n| # | Test | Status | Notes |\n|---|------|--------|-------|\n\n## Summary\n\n_Pending UAT_\n`;
+      break;
+    }
+    case 'verification': {
+      filePath = path.join(phaseDir, `${padded}-VERIFICATION.md`);
+      content = `---\nphase: "${padded}"\nname: "${name || phaseInfo?.phase_name || 'Unnamed'}"\ncreated: ${today}\nstatus: pending\n---\n\n# Phase ${phase}: ${name || phaseInfo?.phase_name || 'Unnamed'} — Verification\n\n## Goal-Backward Verification\n\n**Phase Goal:** [From ROADMAP.md]\n\n## Checks\n\n| # | Requirement | Status | Evidence |\n|---|------------|--------|----------|\n\n## Result\n\n_Pending verification_\n`;
+      break;
+    }
+    case 'phase-dir': {
+      if (!phase || !name) {
+        error('phase and name required for phase-dir scaffold');
+      }
+      const slug = generateSlugInternal(name);
+      const dirName = `${padded}-${slug}`;
+      const phasesParent = path.join(cwd, '.planning', 'phases');
+      fs.mkdirSync(phasesParent, { recursive: true });
+      const dirPath = path.join(phasesParent, dirName);
+      fs.mkdirSync(dirPath, { recursive: true });
+      output({ created: true, directory: `.planning/phases/${dirName}`, path: dirPath }, raw, dirPath);
+      return;
+    }
+    default:
+      error(`Unknown scaffold type: ${type}. Available: context, uat, verification, phase-dir`);
+  }
+
+  if (fs.existsSync(filePath)) {
+    output({ created: false, reason: 'already_exists', path: filePath }, raw, 'exists');
+    return;
+  }
+
+  fs.writeFileSync(filePath, content, 'utf-8');
+  const relPath = toPosixPath(path.relative(cwd, filePath));
+  output({ created: true, path: relPath }, raw, relPath);
+}
+
+module.exports = {
+  cmdGenerateSlug,
+  cmdCurrentTimestamp,
+  cmdVerifyPathExists,
+  cmdHistoryDigest,
+  cmdResolveModel,
+  cmdCommit,
+  cmdSummaryExtract,
+  cmdWebsearch,
+  cmdProgressRender,
+  cmdScaffold,
+};