@paths.design/caws-cli 8.0.1 → 8.2.0

package/dist/templates/docs/README.md

@@ -4,11 +4,11 @@
 This project is built with the **Coding Agent Workflow System (CAWS)** - an engineering-grade framework that ensures quality, reliability, and maintainability in AI-assisted development.
 
 ## Key Features
-- 🔒 **Quality Gates**: Automated validation of scope, budget, and standards
-- 🧪 **Comprehensive Testing**: Unit, contract, integration, and mutation testing
-- 📊 **Observability**: Structured logging, metrics, and tracing
-- 🔄 **Rollback Ready**: Feature flags and migration support
-- 📦 **Provenance Tracking**: SBOM and SLSA attestation generation
+- **Quality Gates**: Automated validation of scope, budget, and standards
+- **Comprehensive Testing**: Unit, contract, integration, and mutation testing
+- **Observability**: Structured logging, metrics, and tracing
+- **Rollback Ready**: Feature flags and migration support
+- **Provenance Tracking**: SBOM and SLSA attestation generation
 
 ## Getting Started
 

package/dist/test-analysis.d.ts

@@ -55,7 +55,8 @@ export class WaiverPatternLearner {
      */
     loadWaivers(): any[];
     /**
-     * Load historical working specs (mock implementation)
+     * Load historical working specs from git history
+     * Retrieves past versions of spec files to analyze patterns
      */
     loadHistoricalSpecs(): any[];
     /**
@@ -101,10 +102,36 @@ export class WaiverPatternLearner {
 export class ProjectSimilarityMatcher {
     constructor(projectRoot?: string);
     projectRoot: string;
+    patternLearner: WaiverPatternLearner;
     /**
      * Find projects similar to the current spec
+     * Uses real historical specs from git history when available
      */
     findSimilarProjects(currentSpec: any): {
+        project: any;
+        similarity_score: number;
+        budget_accuracy: number;
+        waiver_count: any;
+        details: {
+            id: any;
+            title: any;
+            risk_tier: any;
+            mode: any;
+            tech_stack: any;
+            feature_type: any;
+            actual_budget: {
+                files: any;
+                loc: any;
+            };
+            allocated_budget: {
+                files: any;
+                loc: any;
+            };
+            waivers: any;
+            _source: any;
+            _date: any;
+        };
+    }[] | {
         project: string;
         similarity_score: number;
         budget_accuracy: number;
@@ -127,6 +154,28 @@ export class ProjectSimilarityMatcher {
             waivers: string[];
         };
     }[];
+    /**
+     * Convert a spec object to project format for similarity comparison
+     */
+    specToProject(spec: any): {
+        id: any;
+        title: any;
+        risk_tier: any;
+        mode: any;
+        tech_stack: any;
+        feature_type: any;
+        actual_budget: {
+            files: any;
+            loc: any;
+        };
+        allocated_budget: {
+            files: any;
+            loc: any;
+        };
+        waivers: any;
+        _source: any;
+        _date: any;
+    };
     /**
      * Calculate similarity score between two specs/projects
      */

package/dist/test-analysis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-analysis.d.ts","sourceRoot":"","sources":["../src/test-analysis.js"],"names":[],"mappings":"AAiZA;;GAEG;AACH,qFAsBC;AAhaD;;;GAGG;AACH;IACE,kCAEC;IADC,oBAA8B;IAGhC;;OAEG;IACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAgCC;IAED;;OAEG;IACH,qBAsBC;IAED;;OAEG;IACH,6BAIC;IAED;;OAEG;IACH;;;;;;;;;;;;;;;MA6CC;IAED;;OAEG;IACH;;;;QAaC;IAED;;OAEG;IACH;;;;QAeC;CACF;AAED;;;GAGG;AACH;IACE,kCAEC;IADC,oBAA8B;IAGhC;;OAEG;IACH;;;;;;;;;;;;;;;;;;;;;;QAkEC;IAED;;OAEG;IACH,oDA6BC;CACF;AAED;;GAEG;AACH;IACE,kCAIC;IAHC,oBAA8B;IAC9B,qCAA2D;IAC3D,4CAAkE;IAGpE;;OAEG;IACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MA8DC;IAED;;OAEG;IACH,4EAsBC;CACF"}
+{"version":3,"file":"test-analysis.d.ts","sourceRoot":"","sources":["../src/test-analysis.js"],"names":[],"mappings":"AAklBA;;GAEG;AACH,qFAsBC;AAjmBD;;;GAGG;AACH;IACE,kCAEC;IADC,oBAA8B;IAGhC;;OAEG;IACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAgCC;IAED;;OAEG;IACH,qBAsBC;IAED;;;OAGG;IACH,6BA4GC;IAED;;OAEG;IACH;;;;;;;;;;;;;;;MA6CC;IAED;;OAEG;IACH;;;;QAaC;IAED;;OAEG;IACH;;;;QAeC;CACF;AAED;;;GAGG;AACH;IACE,kCAGC;IAFC,oBAA8B;IAC9B,qCAA2D;IAG7D;;;OAGG;IACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAyFC;IAED;;OAEG;IACH;;;;;;;;;;;;;;;;;;MA0DC;IAED;;OAEG;IACH,oDA6BC;CACF;AAED;;GAEG;AACH;IACE,kCAIC;IAHC,oBAA8B;IAC9B,qCAA2D;IAC3D,4CAAkE;IAGpE;;OAEG;IACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MA8DC;IAED;;OAEG;IACH,4EAsBC;CACF"}

package/dist/test-analysis.js

@@ -82,12 +82,117 @@ class WaiverPatternLearner {
   }
 
   /**
-   * Load historical working specs (mock implementation)
+   * Load historical working specs from git history
+   * Retrieves past versions of spec files to analyze patterns
    */
   loadHistoricalSpecs() {
-    // In a real implementation, this would load from git history or a local cache
-    // For v0.1, we'll use mock data based on waivers
-    return [];
+    const { execSync } = require('child_process');
+    const specs = [];
+
+    try {
+      // Get list of commits that modified spec files
+      const specPaths = [
+        '.caws/working-spec.yaml',
+        '.caws/specs/*.yaml',
+      ];
+
+      for (const specPattern of specPaths) {
+        try {
+          // Get commits that touched spec files
+          const logOutput = execSync(
+            `git log --pretty=format:"%H" --follow -- "${specPattern}" 2>/dev/null | head -20`,
+            { cwd: this.projectRoot, encoding: 'utf8' }
+          ).trim();
+
+          if (!logOutput) continue;
+
+          const commits = logOutput.split('\n').filter(Boolean);
+
+          for (const commitHash of commits) {
+            try {
+              // Get the list of files matching the pattern at that commit
+              const filesOutput = execSync(
+                `git ls-tree -r --name-only ${commitHash} -- "${specPattern}" 2>/dev/null`,
+                { cwd: this.projectRoot, encoding: 'utf8' }
+              ).trim();
+
+              if (!filesOutput) continue;
+
+              const files = filesOutput.split('\n').filter(Boolean);
+
+              for (const filePath of files) {
+                try {
+                  // Get the spec content at that commit
+                  const specContent = execSync(
+                    `git show ${commitHash}:"${filePath}" 2>/dev/null`,
+                    { cwd: this.projectRoot, encoding: 'utf8' }
+                  );
+
+                  const spec = yaml.load(specContent);
+                  if (spec && spec.id) {
+                    // Get commit date for context
+                    const commitDate = execSync(
+                      `git show -s --format=%ci ${commitHash}`,
+                      { cwd: this.projectRoot, encoding: 'utf8' }
+                    ).trim();
+
+                    specs.push({
+                      ...spec,
+                      _commit: commitHash.substring(0, 7),
+                      _date: commitDate,
+                      _file: filePath,
+                    });
+                  }
+                } catch {
+                  // Skip files that can't be loaded
+                }
+              }
+            } catch {
+              // Skip commits with issues
+            }
+          }
+        } catch {
+          // Pattern didn't match any files
+        }
+      }
+
+      // Also check archived specs in .caws/archive/
+      const archiveDir = path.join(this.projectRoot, '.caws', 'archive');
+      if (fs.existsSync(archiveDir)) {
+        const archiveFiles = fs.readdirSync(archiveDir)
+          .filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
+
+        for (const file of archiveFiles) {
+          try {
+            const archivePath = path.join(archiveDir, file);
+            const spec = yaml.load(fs.readFileSync(archivePath, 'utf8'));
+            if (spec && spec.id) {
+              specs.push({
+                ...spec,
+                _source: 'archive',
+                _file: file,
+              });
+            }
+          } catch {
+            // Skip invalid archive files
+          }
+        }
+      }
+
+      // Deduplicate by spec ID, keeping the most recent version
+      const uniqueSpecs = new Map();
+      for (const spec of specs) {
+        const existing = uniqueSpecs.get(spec.id);
+        if (!existing || (spec._date && (!existing._date || spec._date > existing._date))) {
+          uniqueSpecs.set(spec.id, spec);
+        }
+      }
+
+      return Array.from(uniqueSpecs.values());
+    } catch (error) {
+      console.warn(`Failed to load historical specs: ${error.message}`);
+      return [];
+    }
   }
 
   /**
@@ -186,16 +291,41 @@ class WaiverPatternLearner {
 class ProjectSimilarityMatcher {
   constructor(projectRoot = process.cwd()) {
     this.projectRoot = projectRoot;
+    this.patternLearner = new WaiverPatternLearner(projectRoot);
   }
 
   /**
    * Find projects similar to the current spec
+   * Uses real historical specs from git history when available
    */
   findSimilarProjects(currentSpec) {
-    // For v0.1, we'll use mock historical data based on waiver patterns
-    // In a real implementation, this would load from git history or local cache
+    // Load real historical specs first
+    const historicalSpecs = this.patternLearner.loadHistoricalSpecs();
+
+    // Convert historical specs to project format with budget data
+    const historicalProjects = historicalSpecs
+      .filter(spec => spec.id !== currentSpec.id) // Exclude current spec
+      .map(spec => this.specToProject(spec));
+
+    // If we have real historical data, use it
+    if (historicalProjects.length > 0) {
+      return historicalProjects
+        .map((project) => ({
+          project: project.id,
+          similarity_score: this.calculateSimilarity(currentSpec, project),
+          budget_accuracy: project.allocated_budget.files > 0
+            ? project.actual_budget.files / project.allocated_budget.files
+            : 1.0,
+          waiver_count: project.waivers?.length || 0,
+          details: project,
+        }))
+        .filter((p) => p.similarity_score > 0.3)
+        .sort((a, b) => b.similarity_score - a.similarity_score)
+        .slice(0, 5);
+    }
 
-    const mockHistoricalProjects = [
+    // Fallback to demo data if no historical specs found
+    const demoProjects = [
       {
         id: 'PROJ-0123',
         title: 'API Enhancement',
@@ -231,9 +361,9 @@ class ProjectSimilarityMatcher {
       },
     ];
 
-    // Add a mock project similar to ARCH-0001 for demonstration
+    // Add a demo project similar to ARCH-0001 for demonstration
     if (currentSpec.id === 'ARCH-0001') {
-      mockHistoricalProjects.push({
+      demoProjects.push({
         id: 'ARCH-0002',
         title: 'Policy System Refactor',
         risk_tier: 1,
@@ -246,7 +376,7 @@ class ProjectSimilarityMatcher {
       });
     }
 
-    return mockHistoricalProjects
+    return demoProjects
       .map((project) => ({
         project: project.id,
         similarity_score: this.calculateSimilarity(currentSpec, project),
@@ -259,6 +389,69 @@ class ProjectSimilarityMatcher {
       .slice(0, 5); // Top 5 matches
   }
 
+  /**
+   * Convert a spec object to project format for similarity comparison
+   */
+  specToProject(spec) {
+    // Extract budget info from spec
+    const budget = spec.budget || spec.scope?.budget || {};
+    const allocatedFiles = budget.max_files || budget.files || 50;
+    const allocatedLoc = budget.max_loc || budget.loc || 5000;
+
+    // If spec has actual metrics, use them; otherwise estimate from allocated
+    const actualFiles = spec.metrics?.files_changed || spec.actual_files || allocatedFiles;
+    const actualLoc = spec.metrics?.lines_changed || spec.actual_loc || allocatedLoc;
+
+    // Extract tech stack from spec metadata
+    let techStack = spec.tech_stack || spec.metadata?.tech_stack || 'unknown';
+    if (!techStack || techStack === 'unknown') {
+      // Try to infer from title or description
+      const text = `${spec.title || ''} ${spec.description || ''}`.toLowerCase();
+      if (text.includes('react') || text.includes('ui') || text.includes('component')) {
+        techStack = 'react';
+      } else if (text.includes('api') || text.includes('node') || text.includes('server')) {
+        techStack = 'node';
+      } else if (text.includes('python') || text.includes('django') || text.includes('flask')) {
+        techStack = 'python';
+      }
+    }
+
+    // Extract feature type
+    let featureType = spec.feature_type || spec.type || 'general';
+    if (featureType === 'general') {
+      const text = `${spec.title || ''} ${spec.description || ''}`.toLowerCase();
+      if (text.includes('api') || text.includes('endpoint')) {
+        featureType = 'api';
+      } else if (text.includes('ui') || text.includes('component') || text.includes('view')) {
+        featureType = 'ui';
+      } else if (text.includes('data') || text.includes('migration') || text.includes('database')) {
+        featureType = 'data';
+      } else if (text.includes('refactor') || text.includes('architecture')) {
+        featureType = 'architecture';
+      }
+    }
+
+    return {
+      id: spec.id,
+      title: spec.title || spec.name || spec.id,
+      risk_tier: spec.risk_tier || spec.tier || 2,
+      mode: spec.mode || 'feature',
+      tech_stack: techStack,
+      feature_type: featureType,
+      actual_budget: {
+        files: actualFiles,
+        loc: actualLoc,
+      },
+      allocated_budget: {
+        files: allocatedFiles,
+        loc: allocatedLoc,
+      },
+      waivers: spec.waivers || [],
+      _source: spec._source,
+      _date: spec._date,
+    };
+  }
+
   /**
    * Calculate similarity score between two specs/projects
    */

package/dist/utils/error-categories.d.ts

@@ -0,0 +1,52 @@
+export namespace ERROR_CATEGORIES {
+    let VALIDATION: string;
+    let PERMISSION: string;
+    let FILESYSTEM: string;
+    let NETWORK: string;
+    let CONFIGURATION: string;
+    let USER_INPUT: string;
+    let DEPENDENCY: string;
+    let UNKNOWN: string;
+}
+export namespace ERROR_CODES {
+    import EACCES = ERROR_CATEGORIES.PERMISSION;
+    export { EACCES };
+    import EPERM = ERROR_CATEGORIES.PERMISSION;
+    export { EPERM };
+    import ENOENT = ERROR_CATEGORIES.FILESYSTEM;
+    export { ENOENT };
+    import ENOTFOUND = ERROR_CATEGORIES.NETWORK;
+    export { ENOTFOUND };
+    import ECONNREFUSED = ERROR_CATEGORIES.NETWORK;
+    export { ECONNREFUSED };
+    import ETIMEDOUT = ERROR_CATEGORIES.NETWORK;
+    export { ETIMEDOUT };
+    import ENOSPC = ERROR_CATEGORIES.FILESYSTEM;
+    export { ENOSPC };
+    import EEXIST = ERROR_CATEGORIES.FILESYSTEM;
+    export { EEXIST };
+    import EISDIR = ERROR_CATEGORIES.FILESYSTEM;
+    export { EISDIR };
+    import ENOTDIR = ERROR_CATEGORIES.FILESYSTEM;
+    export { ENOTDIR };
+}
+/**
+ * Get error category from error object or message
+ * @param {Error|string} error - Error object or message
+ * @returns {string} Error category
+ */
+export function getErrorCategory(error: Error | string): string;
+/**
+ * Get user-friendly error message based on category
+ * @param {string} category - Error category
+ * @param {string} originalMessage - Original error message
+ * @returns {string} User-friendly message
+ */
+export function getFriendlyMessage(category: string, originalMessage: string): string;
+/**
+ * Get recovery suggestions based on error category
+ * @param {string} category - Error category
+ * @returns {Array<string>} Array of recovery suggestions
+ */
+export function getCategorySuggestions(category: string): Array<string>;
+//# sourceMappingURL=error-categories.d.ts.map

package/dist/utils/error-categories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-categories.d.ts","sourceRoot":"","sources":["../../src/utils/error-categories.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA;;;;GAIG;AACH,wCAHW,KAAK,GAAC,MAAM,GACV,MAAM,CA8ElB;AAED;;;;;GAKG;AACH,6CAJW,MAAM,mBACN,MAAM,GACJ,MAAM,CAmBlB;AAED;;;;GAIG;AACH,iDAHW,MAAM,GACJ,KAAK,CAAC,MAAM,CAAC,CAsDzB"}

package/dist/utils/error-categories.js

@@ -0,0 +1,210 @@
+/**
+ * @fileoverview Centralized Error Categories
+ * Shared error categorization for consistent error handling across CAWS packages
+ * @author @darianrosebrook
+ */
+
+/**
+ * Error categories for better user experience
+ */
+const ERROR_CATEGORIES = {
+  VALIDATION: 'validation',
+  PERMISSION: 'permission',
+  FILESYSTEM: 'filesystem',
+  NETWORK: 'network',
+  CONFIGURATION: 'configuration',
+  USER_INPUT: 'user_input',
+  DEPENDENCY: 'dependency',
+  UNKNOWN: 'unknown',
+};
+
+/**
+ * Error code mappings for common system errors
+ */
+const ERROR_CODES = {
+  EACCES: ERROR_CATEGORIES.PERMISSION,
+  EPERM: ERROR_CATEGORIES.PERMISSION,
+  ENOENT: ERROR_CATEGORIES.FILESYSTEM,
+  ENOTFOUND: ERROR_CATEGORIES.NETWORK,
+  ECONNREFUSED: ERROR_CATEGORIES.NETWORK,
+  ETIMEDOUT: ERROR_CATEGORIES.NETWORK,
+  ENOSPC: ERROR_CATEGORIES.FILESYSTEM,
+  EEXIST: ERROR_CATEGORIES.FILESYSTEM,
+  EISDIR: ERROR_CATEGORIES.FILESYSTEM,
+  ENOTDIR: ERROR_CATEGORIES.FILESYSTEM,
+};
+
+/**
+ * Get error category from error object or message
+ * @param {Error|string} error - Error object or message
+ * @returns {string} Error category
+ */
+function getErrorCategory(error) {
+  const errorMessage = typeof error === 'string' ? error : (error?.message || '');
+  const errorCode = typeof error === 'object' && error?.code ? error.code : null;
+
+  // Check error codes first
+  if (errorCode && ERROR_CODES[errorCode]) {
+    return ERROR_CODES[errorCode];
+  }
+
+  // Check message patterns
+  const lowerMessage = errorMessage.toLowerCase();
+
+  if (
+    lowerMessage.includes('validation') ||
+    lowerMessage.includes('invalid') ||
+    lowerMessage.includes('required') ||
+    lowerMessage.includes('malformed') ||
+    lowerMessage.includes('syntax')
+  ) {
+    return ERROR_CATEGORIES.VALIDATION;
+  }
+
+  if (
+    lowerMessage.includes('permission') ||
+    lowerMessage.includes('access') ||
+    lowerMessage.includes('denied') ||
+    lowerMessage.includes('forbidden')
+  ) {
+    return ERROR_CATEGORIES.PERMISSION;
+  }
+
+  if (
+    lowerMessage.includes('file') ||
+    lowerMessage.includes('directory') ||
+    lowerMessage.includes('path') ||
+    lowerMessage.includes('not found') ||
+    lowerMessage.includes('does not exist') ||
+    lowerMessage.includes('enoent')
+  ) {
+    return ERROR_CATEGORIES.FILESYSTEM;
+  }
+
+  if (
+    lowerMessage.includes('network') ||
+    lowerMessage.includes('connection') ||
+    lowerMessage.includes('timeout')
+  ) {
+    return ERROR_CATEGORIES.NETWORK;
+  }
+
+  if (
+    lowerMessage.includes('config') ||
+    lowerMessage.includes('setting') ||
+    lowerMessage.includes('option') ||
+    lowerMessage.includes('missing') ||
+    lowerMessage.includes('empty')
+  ) {
+    return ERROR_CATEGORIES.CONFIGURATION;
+  }
+
+  if (
+    lowerMessage.includes('input') ||
+    lowerMessage.includes('prompt') ||
+    lowerMessage.includes('answer')
+  ) {
+    return ERROR_CATEGORIES.USER_INPUT;
+  }
+
+  if (
+    lowerMessage.includes('dependency') ||
+    lowerMessage.includes('module not found')
+  ) {
+    return ERROR_CATEGORIES.DEPENDENCY;
+  }
+
+  return ERROR_CATEGORIES.UNKNOWN;
+}
+
+/**
+ * Get user-friendly error message based on category
+ * @param {string} category - Error category
+ * @param {string} originalMessage - Original error message
+ * @returns {string} User-friendly message
+ */
+function getFriendlyMessage(category, originalMessage) {
+  const messages = {
+    [ERROR_CATEGORIES.PERMISSION]:
+      'Permission denied. Check file permissions or run with elevated privileges.',
+    [ERROR_CATEGORIES.FILESYSTEM]:
+      'File system error. Check if the file/directory exists and is accessible.',
+    [ERROR_CATEGORIES.NETWORK]: 'Network error. Check your connection and try again.',
+    [ERROR_CATEGORIES.VALIDATION]:
+      'Data validation failed. Check your input format and requirements.',
+    [ERROR_CATEGORIES.CONFIGURATION]:
+      'Configuration error. Check your settings and required fields.',
+    [ERROR_CATEGORIES.USER_INPUT]: 'Invalid user input. Check the command syntax and parameters.',
+    [ERROR_CATEGORIES.DEPENDENCY]: 'Missing dependency. Install required packages.',
+    [ERROR_CATEGORIES.UNKNOWN]: 'An unexpected error occurred.',
+  };
+
+  return messages[category] || originalMessage;
+}
+
+/**
+ * Get recovery suggestions based on error category
+ * @param {string} category - Error category
+ * @returns {Array<string>} Array of recovery suggestions
+ */
+function getCategorySuggestions(category) {
+  const suggestions = {
+    [ERROR_CATEGORIES.PERMISSION]: [
+      'Try running with sudo/admin privileges',
+      'Check file/directory permissions with chmod/chown',
+      'Verify user has write access to the target directory',
+    ],
+    [ERROR_CATEGORIES.FILESYSTEM]: [
+      'Verify the file/directory path is correct',
+      'Check if the file is not corrupted',
+      'Ensure sufficient disk space is available',
+      'Check if the file is not being used by another process',
+    ],
+    [ERROR_CATEGORIES.NETWORK]: [
+      'Check your internet connection',
+      'Verify network configuration and firewall settings',
+      'Try again in a few moments',
+      'Check if the remote service is available',
+    ],
+    [ERROR_CATEGORIES.VALIDATION]: [
+      'Review the input format and requirements',
+      'Check for typos in file paths or values',
+      'Validate against the schema documentation',
+      'Use the --help flag to see correct syntax',
+    ],
+    [ERROR_CATEGORIES.CONFIGURATION]: [
+      'Check that all required configuration files exist',
+      'Verify configuration values are in the correct format',
+      'Review the setup documentation',
+      'Ensure environment variables are set correctly',
+    ],
+    [ERROR_CATEGORIES.USER_INPUT]: [
+      'Check the command syntax with --help',
+      'Verify all required arguments are provided',
+      'Ensure arguments are in the correct order',
+      'Check for typos in command names or options',
+    ],
+    [ERROR_CATEGORIES.DEPENDENCY]: [
+      'Install missing dependencies with npm install',
+      'Check if all peer dependencies are installed',
+      'Verify Node.js version compatibility',
+      'Clear npm cache and try again',
+    ],
+    [ERROR_CATEGORIES.UNKNOWN]: [
+      'Check the logs for more detailed information',
+      'Try restarting the process',
+      'Verify system resources (memory, disk space)',
+      'Report the issue with full error details',
+    ],
+  };
+
+  return suggestions[category] || suggestions[ERROR_CATEGORIES.UNKNOWN];
+}
+
+module.exports = {
+  ERROR_CATEGORIES,
+  ERROR_CODES,
+  getErrorCategory,
+  getFriendlyMessage,
+  getCategorySuggestions,
+};

package/dist/utils/gitignore-updater.d.ts

@@ -35,5 +35,5 @@ export function verifyGitignore(projectRoot: string): Promise<boolean>;
  * - Logs (caws.log, debug logs)
  * - Local overrides (caws.local.*)
  */
-export const CAWS_GITIGNORE_ENTRIES: "\n# CAWS Local Runtime Data (developer-specific, should not be tracked)\n# ====================================================================\n# Note: Specs, policy, waivers, provenance, and plans ARE tracked for team collaboration\n# Only local agent tracking, generated tools, and temporary files are ignored\n\n# Agent runtime tracking (local to each developer)\n.agent/\n\n# CAWS tools (now in .caws/tools/)\n.caws/tools/\n# Legacy location (for backward compatibility)\napps/tools/caws/\n\n# Temporary CAWS files\n**/*.caws.tmp\n**/*.working-spec.bak\n.caws/*.tmp\n.caws/*.bak\n\n# CAWS logs (local debugging)\ncaws-debug.log*\n**/caws.log\n.caws/*.log\n\n# Local development overrides (developer-specific)\ncaws.local.*\n.caws/local.*\n";
+export const CAWS_GITIGNORE_ENTRIES: "\n# CAWS Local Runtime Data (developer-specific, should not be tracked)\n# ====================================================================\n# Note: Specs, policy, waivers, provenance, and plans ARE tracked for team collaboration\n# Only local agent tracking, generated tools, and temporary files are ignored\n\n# Agent runtime tracking (local to each developer)\n.agent/\n\n# CAWS tools (now in .caws/tools/)\n.caws/tools/\n# Legacy location (for backward compatibility)\napps/tools/caws/\n\n# Temporary CAWS files\n**/*.caws.tmp\n**/*.working-spec.bak\n.caws/*.tmp\n.caws/*.bak\n\n# CAWS logs (local debugging)\ncaws-debug.log*\n**/caws.log\n.caws/*.log\n\n# Local development overrides (developer-specific)\ncaws.local.*\n.caws/local.*\n\n# CAWS Worktrees (local, should not be tracked)\n.caws/worktrees/\n.caws/worktrees.json\n";
 //# sourceMappingURL=gitignore-updater.d.ts.map

package/dist/utils/gitignore-updater.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gitignore-updater.d.ts","sourceRoot":"","sources":["../../src/utils/gitignore-updater.js"],"names":[],"mappings":"AA6DA;;;;;;GAMG;AACH,6CALW,MAAM,YAEd;IAAyB,KAAK,EAAtB,OAAO;CACf,GAAU,OAAO,CAAC,OAAO,CAAC,CA2D5B;AAED;;;;GAIG;AACH,6CAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAW5B;AAnID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,gxBA4BE"}
+{"version":3,"file":"gitignore-updater.d.ts","sourceRoot":"","sources":["../../src/utils/gitignore-updater.js"],"names":[],"mappings":"AAiEA;;;;;;GAMG;AACH,6CALW,MAAM,YAEd;IAAyB,KAAK,EAAtB,OAAO;CACf,GAAU,OAAO,CAAC,OAAO,CAAC,CA2D5B;AAED;;;;GAIG;AACH,6CAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAW5B;AAvID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,22BAgCE"}

package/dist/utils/gitignore-updater.js

@@ -57,6 +57,10 @@ caws-debug.log*
 # Local development overrides (developer-specific)
 caws.local.*
 .caws/local.*
+
+# CAWS Worktrees (local, should not be tracked)
+.caws/worktrees/
+.caws/worktrees.json
 `;
 
 /**