@paths.design/caws-cli 7.0.2 → 8.0.0

package/dist/tool-loader.js

@@ -19,8 +19,13 @@ const { safeAsync } = require('./error-handler');
 class ToolLoader extends EventEmitter {
   constructor(options = {}) {
     super();
+    // Check new location first, fall back to legacy location
+    const newToolsDir = path.join(process.cwd(), '.caws/tools');
+    const legacyToolsDir = path.join(process.cwd(), 'apps/tools/caws');
+    const defaultToolsDir = fs.existsSync(newToolsDir) ? newToolsDir : legacyToolsDir;
+
     this.options = {
-      toolsDir: options.toolsDir || path.join(process.cwd(), 'apps/tools/caws'),
+      toolsDir: options.toolsDir || defaultToolsDir,
       cacheEnabled: options.cacheEnabled !== false,
       timeout: options.timeout || 10000,
       maxTools: options.maxTools || 50,

package/dist/tool-validator.js

@@ -15,9 +15,15 @@ const crypto = require('crypto');
  */
 class ToolValidator {
   constructor(options = {}) {
+    // Check new location first, fall back to legacy location
+    const newAllowlistPath = path.join(process.cwd(), '.caws/tools-allow.json');
+    const legacyAllowlistPath = path.join(process.cwd(), 'apps/tools/caws/tools-allow.json');
+    const defaultAllowlistPath = fs.existsSync(newAllowlistPath)
+      ? newAllowlistPath
+      : legacyAllowlistPath;
+
     this.options = {
-      allowlistPath:
-        options.allowlistPath || path.join(process.cwd(), 'apps/tools/caws/tools-allow.json'),
+      allowlistPath: options.allowlistPath || defaultAllowlistPath,
       strictMode: options.strictMode !== false,
       maxFileSize: options.maxFileSize || 1024 * 1024, // 1MB
       ...options,

package/dist/utils/detection.js

@@ -73,9 +73,10 @@ function detectCAWSSetup(cwd = process.cwd()) {
   const specFiles = files.filter((f) => f.endsWith('-spec.yaml'));
   const hasMultipleSpecs = specFiles.length > 1;
 
-  // Check for tools directory (enhanced setup)
-  const toolsDir = path.join(cwd, 'apps/tools/caws');
-  const hasTools = fs.existsSync(toolsDir);
+  // Check for tools directory (enhanced setup) - check new location first
+  const toolsDir = path.join(cwd, '.caws/tools');
+  const legacyToolsDir = path.join(cwd, 'apps/tools/caws');
+  const hasTools = fs.existsSync(toolsDir) || fs.existsSync(legacyToolsDir);
 
   // Determine setup type
   let setupType = 'basic';

package/dist/utils/git-lock.js

@@ -0,0 +1,119 @@
+/**
+ * @fileoverview Git Lock Detection Utilities
+ * Functions for detecting and handling git locks
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * Check for git lock files
+ * @param {string} projectRoot - Project root directory
+ * @returns {Object} Lock status information
+ */
+function checkGitLock(projectRoot) {
+  const lockFile = path.join(projectRoot, '.git', 'index.lock');
+  const headLockFile = path.join(projectRoot, '.git', 'HEAD.lock');
+
+  const result = {
+    locked: false,
+    stale: false,
+    lockFiles: [],
+    message: null,
+    suggestion: null,
+  };
+
+  // Check index.lock
+  if (fs.existsSync(lockFile)) {
+    const lockAge = Date.now() - fs.statSync(lockFile).mtimeMs;
+    const lockAgeMinutes = Math.floor(lockAge / 60000);
+
+    result.locked = true;
+    result.lockFiles.push({
+      path: '.git/index.lock',
+      age: lockAgeMinutes,
+      stale: lockAgeMinutes > 5,
+    });
+
+    if (lockAgeMinutes > 5) {
+      // Stale lock (older than 5 minutes)
+      result.stale = true;
+      result.message = `Stale git lock detected (${lockAgeMinutes} minutes old). This may indicate a crashed git process.`;
+      result.suggestion = 'Remove stale lock: rm .git/index.lock';
+    } else {
+      // Active lock
+      result.message =
+        'Git lock detected. Another git process may be running.';
+      result.suggestion =
+        'Wait for the other process to complete, or check for running git/editor processes';
+    }
+  }
+
+  // Check HEAD.lock
+  if (fs.existsSync(headLockFile)) {
+    const lockAge = Date.now() - fs.statSync(headLockFile).mtimeMs;
+    const lockAgeMinutes = Math.floor(lockAge / 60000);
+
+    result.locked = true;
+    result.lockFiles.push({
+      path: '.git/HEAD.lock',
+      age: lockAgeMinutes,
+      stale: lockAgeMinutes > 5,
+    });
+
+    if (lockAgeMinutes > 5) {
+      result.stale = true;
+      if (!result.message) {
+        result.message = `Stale git lock detected (${lockAgeMinutes} minutes old).`;
+        result.suggestion = 'Remove stale lock: rm .git/HEAD.lock';
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Format git lock error message
+ * @param {Object} lockStatus - Lock status from checkGitLock
+ * @returns {string} Formatted error message
+ */
+function formatGitLockError(lockStatus) {
+  if (!lockStatus.locked) {
+    return null;
+  }
+
+  let message = '⚠️  Git lock detected\n';
+  message += `   ${lockStatus.message}\n`;
+
+  if (lockStatus.lockFiles.length > 0) {
+    message += '\n   Lock files:\n';
+    for (const lockFile of lockStatus.lockFiles) {
+      message += `   - ${lockFile.path} (${lockFile.age} minutes old)`;
+      if (lockFile.stale) {
+        message += ' [STALE]';
+      }
+      message += '\n';
+    }
+  }
+
+  if (lockStatus.suggestion) {
+    message += `\n   💡 ${lockStatus.suggestion}\n`;
+  }
+
+  if (lockStatus.stale) {
+    message +=
+      '\n   ⚠️  Warning: Removing stale locks may cause data loss if another process is actually running.\n';
+    message += '   Check for running git/editor processes before removing locks.\n';
+  }
+
+  return message;
+}
+
+module.exports = {
+  checkGitLock,
+  formatGitLockError,
+};
+
+

package/dist/utils/gitignore-updater.js

@@ -0,0 +1,148 @@
+/**
+ * @fileoverview Gitignore Updater Utility
+ * Updates .gitignore to properly handle CAWS runtime files vs source files
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+/**
+ * CAWS .gitignore entries
+ *
+ * Strategy: Track shared/collaborative files, ignore local-only runtime data
+ *
+ * TRACKED (shared with team):
+ * - .caws/working-spec.yaml (main spec)
+ * - .caws/specs/*.yaml (feature specs)
+ * - .caws/policy.yaml (team policy)
+ * - .caws/waivers/*.yaml (project-wide waivers)
+ * - .caws/provenance/ (audit trails for compliance)
+ * - .caws/changes/ (change tracking for team visibility)
+ * - .caws/archive/ (archived changes for history)
+ * - .caws/plans/*.md (implementation plans)
+ *
+ * IGNORED (local-only):
+ * - .agent/ (agent runtime tracking, local to each developer)
+ * - Temporary files (*.tmp, *.bak)
+ * - Logs (caws.log, debug logs)
+ * - Local overrides (caws.local.*)
+ */
+const CAWS_GITIGNORE_ENTRIES = `
+# CAWS Local Runtime Data (developer-specific, should not be tracked)
+# ====================================================================
+# Note: Specs, policy, waivers, provenance, and plans ARE tracked for team collaboration
+# Only local agent tracking, generated tools, and temporary files are ignored
+
+# Agent runtime tracking (local to each developer)
+.agent/
+
+# CAWS tools (now in .caws/tools/)
+.caws/tools/
+# Legacy location (for backward compatibility)
+apps/tools/caws/
+
+# Temporary CAWS files
+**/*.caws.tmp
+**/*.working-spec.bak
+.caws/*.tmp
+.caws/*.bak
+
+# CAWS logs (local debugging)
+caws-debug.log*
+**/caws.log
+.caws/*.log
+
+# Local development overrides (developer-specific)
+caws.local.*
+.caws/local.*
+`;
+
+/**
+ * Update .gitignore to include CAWS runtime file exclusions
+ * @param {string} projectRoot - Project root directory
+ * @param {Object} options - Options
+ * @param {boolean} options.force - Force update even if entries exist
+ * @returns {Promise<boolean>} Whether .gitignore was updated
+ */
+async function updateGitignore(projectRoot, options = {}) {
+  const { force = false } = options;
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+
+  try {
+    // Read existing .gitignore or create empty
+    let existingContent = '';
+    if (await fs.pathExists(gitignorePath)) {
+      existingContent = await fs.readFile(gitignorePath, 'utf8');
+    }
+
+    // Check if CAWS entries already exist (check for either old or new header)
+    const hasCawsEntries =
+      existingContent.includes('# CAWS Local Runtime Data') ||
+      existingContent.includes('# CAWS Runtime Data');
+
+    if (hasCawsEntries && !force) {
+      // Already has CAWS entries, skip
+      return false;
+    }
+
+    // If old entries exist, replace them with new ones
+    if (existingContent.includes('# CAWS Runtime Data') && force) {
+      // Remove old CAWS entries (between "# CAWS Runtime Data" and next major section)
+      const lines = existingContent.split('\n');
+      const startIndex = lines.findIndex((line) => line.includes('# CAWS Runtime Data'));
+      if (startIndex !== -1) {
+        // Find the end of CAWS section (next major section starting with #)
+        let endIndex = startIndex + 1;
+        while (
+          endIndex < lines.length &&
+          (lines[endIndex].trim() === '' ||
+            lines[endIndex].startsWith('#') ||
+            lines[endIndex].startsWith('.caws/') ||
+            lines[endIndex].startsWith('.agent/') ||
+            lines[endIndex].includes('caws') ||
+            lines[endIndex].includes('CAWS'))
+        ) {
+          endIndex++;
+        }
+        // Remove old section and insert new one
+        const before = lines.slice(0, startIndex).join('\n');
+        const after = lines.slice(endIndex).join('\n');
+        existingContent = [before, after].filter(Boolean).join('\n');
+      }
+    }
+
+    // Append CAWS entries
+    const updatedContent = existingContent.trim() + '\n' + CAWS_GITIGNORE_ENTRIES.trim() + '\n';
+
+    await fs.writeFile(gitignorePath, updatedContent, 'utf8');
+
+    return true;
+  } catch (error) {
+    console.warn(chalk.yellow(`⚠️  Could not update .gitignore: ${error.message}`));
+    return false;
+  }
+}
+
+/**
+ * Verify .gitignore has proper CAWS entries
+ * @param {string} projectRoot - Project root directory
+ * @returns {Promise<boolean>} Whether .gitignore has CAWS entries
+ */
+async function verifyGitignore(projectRoot) {
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+
+  if (!(await fs.pathExists(gitignorePath))) {
+    return false;
+  }
+
+  const content = await fs.readFile(gitignorePath, 'utf8');
+  return content.includes('# CAWS Local Runtime Data') || content.includes('# CAWS Runtime Data');
+}
+
+module.exports = {
+  updateGitignore,
+  verifyGitignore,
+  CAWS_GITIGNORE_ENTRIES,
+};

package/dist/utils/project-analysis.js

@@ -111,9 +111,7 @@ function detectsPublishing(cwd = process.cwd()) {
   // Check package.json for npm publishing
   if (files.includes('package.json')) {
     try {
-      const packageJson = JSON.parse(
-        fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')
-      );
+      const packageJson = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
 
       // Indicators of publishing:
       // - Has publishConfig
@@ -123,9 +121,7 @@ function detectsPublishing(cwd = process.cwd()) {
       const hasPublishConfig = packageJson.publishConfig;
       const hasPublishScript =
         packageJson.scripts &&
-        Object.keys(packageJson.scripts).some((key) =>
-          key.toLowerCase().includes('publish')
-        );
+        Object.keys(packageJson.scripts).some((key) => key.toLowerCase().includes('publish'));
       const hasScopedName = packageJson.name && packageJson.name.startsWith('@');
       const hasRepository = packageJson.repository;
 
@@ -140,16 +136,13 @@ function detectsPublishing(cwd = process.cwd()) {
   // Check pyproject.toml for PyPI publishing
   if (files.includes('pyproject.toml')) {
     try {
-      const pyprojectContent = fs.readFileSync(
-        path.join(cwd, 'pyproject.toml'),
-        'utf8'
-      );
+      const pyprojectContent = fs.readFileSync(path.join(cwd, 'pyproject.toml'), 'utf8');
 
       // Check for build system and project metadata (indicates publishable package)
       const hasBuildSystem = pyprojectContent.includes('[build-system]');
       const hasProjectMetadata = pyprojectContent.includes('[project]');
-      const hasToolPublish = pyprojectContent.includes('[tool.publish]') ||
-                            pyprojectContent.includes('[tool.twine]');
+      const hasToolPublish =
+        pyprojectContent.includes('[tool.publish]') || pyprojectContent.includes('[tool.twine]');
 
       if ((hasBuildSystem && hasProjectMetadata) || hasToolPublish) {
         return true;
@@ -177,10 +170,7 @@ function detectsPublishing(cwd = process.cwd()) {
       const workflowFiles = fs.readdirSync(workflowsPath);
       for (const workflowFile of workflowFiles) {
         if (workflowFile.endsWith('.yml') || workflowFile.endsWith('.yaml')) {
-          const workflowContent = fs.readFileSync(
-            path.join(workflowsPath, workflowFile),
-            'utf8'
-          );
+          const workflowContent = fs.readFileSync(path.join(workflowsPath, workflowFile), 'utf8');
           // Check for common publishing actions/commands
           if (
             workflowContent.includes('npm publish') ||
@@ -201,8 +191,178 @@ function detectsPublishing(cwd = process.cwd()) {
   return false;
 }
 
+/**
+ * Detect primary programming language(s) used in project
+ * @param {string} cwd - Current working directory
+ * @returns {Object} Language detection result with primary language and indicators
+ */
+function detectProjectLanguage(cwd = process.cwd()) {
+  const files = fs.readdirSync(cwd);
+  const indicators = {
+    javascript: false,
+    typescript: false,
+    python: false,
+    rust: false,
+    go: false,
+    java: false,
+    csharp: false,
+    php: false,
+  };
+
+  // JavaScript/TypeScript indicators
+  if (files.includes('package.json')) {
+    indicators.javascript = true;
+    try {
+      const packageJson = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+      const allDeps = {
+        ...(packageJson.dependencies || {}),
+        ...(packageJson.devDependencies || {}),
+      };
+      if ('typescript' in allDeps || files.includes('tsconfig.json')) {
+        indicators.typescript = true;
+        indicators.javascript = false; // TypeScript supersedes JavaScript
+      }
+    } catch (e) {
+      // Ignore parse errors
+    }
+  }
+
+  // Python indicators
+  if (
+    files.includes('requirements.txt') ||
+    files.includes('pyproject.toml') ||
+    files.includes('setup.py') ||
+    files.includes('Pipfile') ||
+    files.includes('poetry.lock') ||
+    files.some((f) => f.endsWith('.py'))
+  ) {
+    indicators.python = true;
+  }
+
+  // Rust indicators
+  if (files.includes('Cargo.toml') || files.some((f) => f.endsWith('.rs'))) {
+    indicators.rust = true;
+  }
+
+  // Go indicators
+  if (
+    files.includes('go.mod') ||
+    files.includes('go.sum') ||
+    files.some((f) => f.endsWith('.go'))
+  ) {
+    indicators.go = true;
+  }
+
+  // Java indicators
+  if (
+    files.includes('pom.xml') ||
+    files.includes('build.gradle') ||
+    files.some((f) => f.endsWith('.java'))
+  ) {
+    indicators.java = true;
+  }
+
+  // C# indicators
+  if (
+    files.some((f) => f.endsWith('.csproj')) ||
+    files.some((f) => f.endsWith('.sln')) ||
+    files.some((f) => f.endsWith('.cs'))
+  ) {
+    indicators.csharp = true;
+  }
+
+  // PHP indicators
+  if (
+    files.includes('composer.json') ||
+    files.includes('composer.lock') ||
+    files.some((f) => f.endsWith('.php'))
+  ) {
+    indicators.php = true;
+  }
+
+  // Determine primary language (priority order)
+  let primaryLanguage = 'unknown';
+  if (indicators.typescript) {
+    primaryLanguage = 'typescript';
+  } else if (indicators.javascript) {
+    primaryLanguage = 'javascript';
+  } else if (indicators.python) {
+    primaryLanguage = 'python';
+  } else if (indicators.rust) {
+    primaryLanguage = 'rust';
+  } else if (indicators.go) {
+    primaryLanguage = 'go';
+  } else if (indicators.java) {
+    primaryLanguage = 'java';
+  } else if (indicators.csharp) {
+    primaryLanguage = 'csharp';
+  } else if (indicators.php) {
+    primaryLanguage = 'php';
+  }
+
+  return {
+    primary: primaryLanguage,
+    indicators,
+    hasNodeJs: indicators.javascript || indicators.typescript,
+    hasPython: indicators.python,
+  };
+}
+
+/**
+ * Get language-agnostic suggestion for TODO analyzer installation
+ * Focuses on runtime availability (Node.js/npx) rather than project language
+ * @param {string} cwd - Current working directory
+ * @returns {string} Installation suggestion message
+ */
+function getTodoAnalyzerSuggestion(cwd = process.cwd()) {
+  // Check runtime availability (language-agnostic)
+  let hasNodeJs = false;
+  let hasNpx = false;
+  try {
+    const { execSync } = require('child_process');
+    execSync('command -v node', { encoding: 'utf8', stdio: 'ignore' });
+    hasNodeJs = true;
+    execSync('command -v npx', { encoding: 'utf8', stdio: 'ignore' });
+    hasNpx = true;
+  } catch (e) {
+    // Node.js/npx not available
+  }
+
+  const suggestions = [];
+
+  if (hasNpx) {
+    // npx available - works for any language, no installation needed
+    suggestions.push(
+      '   • Use npx (no installation required): npx --yes @paths.design/quality-gates'
+    );
+    suggestions.push('   • Install package: npm install --save-dev @paths.design/quality-gates');
+  } else if (hasNodeJs) {
+    // Node.js available but npx not found (unusual)
+    suggestions.push('   • Install package: npm install --save-dev @paths.design/quality-gates');
+    suggestions.push(
+      '   • Install npx: npm install -g npx (then use: npx --yes @paths.design/quality-gates)'
+    );
+  } else {
+    // Node.js not available - suggest installation
+    suggestions.push(
+      '   • Install Node.js: https://nodejs.org/ (then use: npx --yes @paths.design/quality-gates)'
+    );
+    suggestions.push('   • Use CAWS MCP server: caws quality-gates (via MCP)');
+  }
+
+  // Check for project-specific scripts (language-agnostic - if they exist, suggest them)
+  const pythonScript = path.join(cwd, 'scripts', 'v3', 'analysis', 'todo_analyzer.py');
+  if (fs.existsSync(pythonScript)) {
+    suggestions.push(`   • Use project script: python3 ${pythonScript}`);
+  }
+
+  return suggestions.join('\n');
+}
+
 module.exports = {
   detectProjectType,
   shouldInitInCurrentDirectory,
   detectsPublishing,
+  detectProjectLanguage,
+  getTodoAnalyzerSuggestion,
 };

package/dist/utils/quality-gates.js

@@ -11,6 +11,7 @@ const fs = require('fs');
 const path = require('path');
 const yaml = require('js-yaml');
 const { execSync } = require('child_process');
+const { getTodoAnalyzerSuggestion } = require('./project-analysis');
 
 /**
  * Quality Gate Configuration
@@ -196,18 +197,58 @@ function checkHiddenTodos(stagedFiles) {
   console.log(`📁 Found ${supportedFiles.length} staged files to analyze for TODOs`);
 
   try {
-    // Check if TODO analyzer exists
-    const analyzerPath = path.join(process.cwd(), 'scripts/v3/analysis/todo_analyzer.py');
-    if (!fs.existsSync(analyzerPath)) {
+    // Find TODO analyzer .mjs file (preferred - no Python dependency)
+    const possiblePaths = [
+      // Published npm package (priority)
+      path.join(
+        process.cwd(),
+        'node_modules',
+        '@paths.design',
+        'quality-gates',
+        'todo-analyzer.mjs'
+      ),
+      // Legacy monorepo local copy
+      path.join(process.cwd(), 'node_modules', '@caws', 'quality-gates', 'todo-analyzer.mjs'),
+      // Monorepo structure (development)
+      path.join(process.cwd(), 'packages', 'quality-gates', 'todo-analyzer.mjs'),
+      // Local copy in scripts directory (if scaffolded)
+      path.join(process.cwd(), 'scripts', 'todo-analyzer.mjs'),
+      // Legacy Python analyzer (deprecated)
+      path.join(process.cwd(), 'scripts', 'v3', 'analysis', 'todo_analyzer.py'),
+    ];
+
+    let analyzerPath = null;
+    let usePython = false;
+
+    for (const testPath of possiblePaths) {
+      if (fs.existsSync(testPath)) {
+        analyzerPath = testPath;
+        usePython = testPath.endsWith('.py');
+        break;
+      }
+    }
+
+    if (!analyzerPath) {
       console.warn('⚠️  TODO analyzer not found - skipping TODO analysis');
+      const suggestion = getTodoAnalyzerSuggestion(process.cwd());
+      console.warn('💡 Available options for TODO analysis:');
+      console.warn(suggestion);
       return { todos: [], blocking: 0, total: 0 };
     }
 
+    if (usePython) {
+      console.warn('⚠️  Using legacy Python TODO analyzer (deprecated)');
+      const suggestion = getTodoAnalyzerSuggestion(process.cwd());
+      console.warn('💡 Consider upgrading to Node.js version:');
+      console.warn(suggestion);
+    }
+
     // Run the TODO analyzer with staged files
-    const result = execSync(
-      `python3 ${analyzerPath} --staged-only --min-confidence ${CONFIG.todoConfidenceThreshold}`,
-      { encoding: 'utf8', cwd: process.cwd() }
-    );
+    const command = usePython
+      ? `python3 ${analyzerPath} --staged-only --min-confidence ${CONFIG.todoConfidenceThreshold}`
+      : `node ${analyzerPath} --staged-only --ci-mode --min-confidence ${CONFIG.todoConfidenceThreshold}`;
+
+    const result = execSync(command, { encoding: 'utf8', cwd: process.cwd() });
 
     // Parse the output to extract TODO count
     const lines = result.split('\n');

package/dist/utils/spec-resolver.js

@@ -108,7 +108,14 @@ async function resolveSpec(options = {}) {
       const specPath = path.join(SPECS_DIR, registry.specs[id].path);
       try {
         const content = await fs.readFile(specPath, 'utf8');
-        const spec = yaml.load(content);
+        let spec;
+        try {
+          spec = yaml.load(content);
+        } catch (yamlError) {
+          console.log(chalk.yellow(`   - ${id} (YAML syntax error: ${yamlError.message})`));
+          specsInfo.push({ id, type: 'unknown', status: 'unknown', title: 'YAML error' });
+          continue;
+        }
         const status = spec.status || 'draft';
         const type = spec.type || 'feature';
         const statusColor =
@@ -122,7 +129,7 @@ async function resolveSpec(options = {}) {
         );
         specsInfo.push({ id, type, status, title: spec.title || 'Untitled' });
       } catch (error) {
-        console.log(chalk.yellow(`   - ${id} (error loading details)`));
+        console.log(chalk.yellow(`   - ${id} (error loading details: ${error.message})`));
         specsInfo.push({ id, type: 'unknown', status: 'unknown', title: 'Error loading' });
       }
     }
@@ -363,7 +370,20 @@ async function checkScopeConflicts(specIds) {
 
     try {
       const content = await fs.readFile(specPath, 'utf8');
-      const spec = yaml.load(content);
+      let spec;
+      try {
+        spec = yaml.load(content);
+      } catch (yamlError) {
+        const relativePath = path.relative(process.cwd(), specPath);
+        throw new Error(
+          `Invalid YAML syntax in ${relativePath}: ${yamlError.message}\n` +
+            (yamlError.mark
+              ? `   Line ${yamlError.mark.line + 1}, Column ${yamlError.mark.column + 1}\n`
+              : '') +
+            (yamlError.mark?.snippet ? `   ${yamlError.mark.snippet}\n` : '') +
+            `💡 Fix YAML syntax errors or use 'caws specs create <id>' for proper structure`
+        );
+      }
 
       specScopes.push({
         id,
@@ -492,6 +512,10 @@ async function suggestMigration() {
 function suggestFeatureBreakdown(legacySpec) {
   const features = [];
 
+  if (!legacySpec) {
+    return features;
+  }
+
   if (legacySpec.acceptance && legacySpec.acceptance.length > 0) {
     // Group acceptance criteria by logical features
     const criteriaByFeature = {};