@paths.design/caws-cli 7.0.1 → 7.0.3

package/dist/budget-derivation.js

@@ -196,10 +196,11 @@ async function deriveBudget(spec, projectRoot = process.cwd(), options = {}) {
             '   This may be a path resolution or caching issue\n'
         );
       } else {
-        console.warn(
-          '⚠️  Policy file not found: .caws/policy.yaml\n' +
-            '   Using default policy. Run "caws init" to create policy.yaml'
-        );
+        // Policy.yaml is optional - defaults work fine, so don't warn unnecessarily
+        // Only show info message if user explicitly wants to see it
+        if (options.showPolicyInfo !== false) {
+          // Silent by default - policy.yaml is optional
+        }
       }
     }
 

package/dist/commands/diagnose.js

@@ -240,41 +240,44 @@ async function checkTestFiles() {
  * @returns {Promise<Object>} Check result
  */
 async function checkCAWSTools() {
-  const toolsPath = 'apps/tools/caws';
+  // Check new location first, then legacy location for backward compatibility
+  const toolsPath = '.caws/tools';
+  const legacyToolsPath = 'apps/tools/caws';
 
-  if (!(await fs.pathExists(toolsPath))) {
+  if (!(await fs.pathExists(toolsPath)) && !(await fs.pathExists(legacyToolsPath))) {
     return {
-      passed: false,
-      severity: 'low',
-      message: 'CAWS tools directory not found',
-      fix: 'Scaffold tools: caws scaffold',
+      passed: true,
+      severity: 'info',
+      message: 'CAWS tools directory not found (optional - use CLI commands instead)',
+      fix: 'Core functionality available via: caws validate, caws quality-gates, caws provenance',
       autoFixable: false,
     };
   }
 
-  // Check for essential tools
-  const essentialTools = ['validate.js', 'gates.js', 'provenance.js'];
-  let missingTools = [];
+  // Tools directory exists - check for specialized tools (not core CLI duplicates)
+  const specializedTools = ['flake-detector.ts', 'spec-test-mapper.ts', 'perf-budgets.ts'];
+  const foundTools = [];
 
-  for (const tool of essentialTools) {
-    if (!(await fs.pathExists(path.join(toolsPath, tool)))) {
-      missingTools.push(tool);
+  for (const tool of specializedTools) {
+    if (await fs.pathExists(path.join(toolsPath, tool))) {
+      foundTools.push(tool);
     }
   }
 
-  if (missingTools.length > 0) {
+  if (foundTools.length === 0) {
     return {
-      passed: false,
-      severity: 'medium',
-      message: `Missing ${missingTools.length} essential tools`,
-      fix: 'Re-scaffold tools: caws scaffold --force',
+      passed: true,
+      severity: 'info',
+      message: 'No specialized tools found (optional - use CLI commands for core functionality)',
+      fix: 'Core functionality available via: caws validate, caws quality-gates, caws provenance',
       autoFixable: false,
     };
   }
 
   return {
     passed: true,
-    message: 'All essential CAWS tools present',
+    message: `Found ${foundTools.length} specialized tool(s): ${foundTools.join(', ')}`,
+    note: 'Core functionality (validate, quality-gates, provenance) available via CLI commands',
   };
 }
 
@@ -481,9 +484,12 @@ async function diagnoseCommand(options = {}) {
 
     if (issueCount === 0) {
       console.log(chalk.blue('📚 Next steps:'));
-      console.log(chalk.blue('   • Run: caws status to view project health'));
+      console.log(chalk.blue('   • Run: caws status --visual to view project health'));
       console.log(chalk.blue('   • Run: caws validate to check working spec'));
-      console.log(chalk.blue('   • Run: node apps/tools/caws/gates.js for quality gates'));
+      console.log(chalk.blue('   • Optional: Create .caws/policy.yaml for custom budgets'));
+      console.log(
+        chalk.blue('   • Start implementing: caws iterate --current-state "Ready to begin"')
+      );
     }
   } catch (error) {
     console.error(chalk.red('\n❌ Error running diagnosis:'), error.message);

package/dist/commands/init.js

@@ -17,6 +17,7 @@ const { generateWorkingSpec } = require('../generators/working-spec');
 const { finalizeProject } = require('../utils/finalization');
 const { scaffoldCursorHooks } = require('../scaffold/cursor-hooks');
 const { scaffoldIDEIntegrations } = require('../scaffold/index');
+const { updateGitignore } = require('../utils/gitignore-updater');
 
 /**
  * Initialize a new project with CAWS
@@ -361,6 +362,18 @@ async function initProject(projectName, options) {
       await fs.writeFile(path.join('.caws', 'working-spec.yaml'), specContent);
       console.log(chalk.green('✅ Created .caws/working-spec.yaml'));
 
+      // Optionally create policy.yaml (optional - defaults work fine)
+      const policyPath = path.join('.caws', 'policy.yaml');
+      if (!fs.existsSync(policyPath)) {
+        const { PolicyManager } = require('../policy/PolicyManager');
+        const policyManager = new PolicyManager();
+        const defaultPolicy = policyManager.getDefaultPolicy();
+        const yaml = require('js-yaml');
+        const policyContent = yaml.dump(defaultPolicy, { indent: 2 });
+        await fs.writeFile(policyPath, policyContent);
+        console.log(chalk.green('✅ Created .caws/policy.yaml (optional - defaults work fine)'));
+      }
+
       // Generate additional files if requested
       if (answers.generateExamples) {
         console.log(chalk.blue('📝 Generating example files...'));
@@ -409,6 +422,17 @@ Happy coding! 🎯
       console.log(chalk.blue('🎨 Setting up IDE integrations...'));
       await scaffoldIDEIntegrations(process.cwd(), { force: false });
 
+      // Update .gitignore to exclude CAWS local runtime files
+      console.log(chalk.blue('📝 Updating .gitignore...'));
+      const gitignoreUpdated = await updateGitignore(process.cwd());
+      if (gitignoreUpdated) {
+        console.log(chalk.green('✅ Updated .gitignore to exclude CAWS local runtime files'));
+        console.log(
+          chalk.gray('   Tracked: Specs, policy, waivers, provenance, plans (shared with team)')
+        );
+        console.log(chalk.gray('   Ignored: Agent runtime, temp files, logs (local-only)'));
+      }
+
       // Finalize project
       await finalizeProject(projectName, options, answers);
     } else {
@@ -456,7 +480,7 @@ Happy coding! 🎯
         experimentalSandbox: '',
         aiConfidence: 0.8,
         uncertaintyAreas: '',
-        complexityFactors: ''
+        complexityFactors: '',
       };
 
       const specContent = generateWorkingSpec(defaultAnswers);
@@ -464,6 +488,18 @@ Happy coding! 🎯
       await fs.writeFile(path.join('.caws', 'working-spec.yaml'), specContent);
       console.log(chalk.green('✅ Created .caws/working-spec.yaml'));
 
+      // Optionally create policy.yaml (optional - defaults work fine)
+      const policyPath = path.join('.caws', 'policy.yaml');
+      if (!fs.existsSync(policyPath)) {
+        const { PolicyManager } = require('../policy/PolicyManager');
+        const policyManager = new PolicyManager();
+        const defaultPolicy = policyManager.getDefaultPolicy();
+        const yaml = require('js-yaml');
+        const policyContent = yaml.dump(defaultPolicy, { indent: 2 });
+        await fs.writeFile(policyPath, policyContent);
+        console.log(chalk.green('✅ Created .caws/policy.yaml (optional - defaults work fine)'));
+      }
+
       // Setup Cursor hooks by default in non-interactive mode
       console.log(chalk.blue('🎯 Setting up Cursor hooks...'));
       await scaffoldCursorHooks(process.cwd());
@@ -472,6 +508,17 @@ Happy coding! 🎯
       console.log(chalk.blue('🎨 Setting up IDE integrations...'));
       await scaffoldIDEIntegrations(process.cwd(), { force: false });
 
+      // Update .gitignore to exclude CAWS local runtime files
+      console.log(chalk.blue('📝 Updating .gitignore...'));
+      const gitignoreUpdated = await updateGitignore(process.cwd());
+      if (gitignoreUpdated) {
+        console.log(chalk.green('✅ Updated .gitignore to exclude CAWS local runtime files'));
+        console.log(
+          chalk.gray('   Tracked: Specs, policy, waivers, provenance, plans (shared with team)')
+        );
+        console.log(chalk.gray('   Ignored: Agent runtime, temp files, logs (local-only)'));
+      }
+
       // Finalize project
       await finalizeProject(projectName, options, defaultAnswers);
     }
@@ -481,17 +528,37 @@ Happy coding! 🎯
     console.log(chalk.blue('\nNext steps:'));
     console.log('1. Review .caws/working-spec.yaml');
     console.log('2. Customize the specification for your needs');
-    console.log('3. Run "caws validate" to check your setup');
+
+    // Show contract requirements if Tier 1 or 2
+    // Use answers if available (interactive mode), otherwise default to 2
+    const riskTier = answers?.riskTier || 2;
+    if (riskTier === 1 || riskTier === 2) {
+      console.log(chalk.yellow('\n⚠️  Important: Contract Requirements'));
+      console.log(`   Tier ${riskTier} changes require at least one contract.`);
+      console.log('   For infrastructure/setup work, add a minimal contract:');
+      console.log(chalk.gray('   contracts:'));
+      console.log(chalk.gray('     - type: "project_setup"'));
+      console.log(chalk.gray('       path: ".caws/working-spec.yaml"'));
+      console.log(chalk.gray('       description: "Project-level CAWS configuration"'));
+      console.log('   Or use "chore" mode for maintenance work (mode: chore)');
+    }
+
+    console.log('\n📋 Recommended Setup Workflow:');
+    console.log('   1. Review .caws/working-spec.yaml');
+    console.log('   2. Run: caws scaffold (adds tools and templates)');
+    console.log('   3. Run: caws validate (verify setup)');
+    console.log('   4. Run: caws diagnose (check health)');
+    console.log('   5. Optional: Create .caws/policy.yaml for custom budgets');
     if (answers?.useCursorHooks || options.interactive === false) {
-      console.log('4. Restart Cursor IDE to activate quality gates');
+      console.log('   6. Restart Cursor IDE to activate quality gates');
     }
-    console.log('5. Start implementing your features!');
+    console.log('\n💡 Quick start: caws scaffold && caws validate && caws diagnose');
   } catch (error) {
     console.error(chalk.red('❌ Error during initialization:'), error.message);
     if (error.stack) {
       console.error(chalk.gray(error.stack));
     }
-    
+
     // Cleanup on error (only for new directory creation)
     if (projectName && projectName !== '.' && fs.existsSync(projectName)) {
       try {

package/dist/commands/specs.js

@@ -202,7 +202,46 @@ async function createSpec(id, options = {}) {
   const filePath = path.join(SPECS_DIR, fileName);
 
   // Write spec file
-  await fs.writeFile(filePath, yaml.dump(specContent, { indent: 2 }));
+  const yamlContent = yaml.dump(specContent, { indent: 2 });
+  await fs.writeFile(filePath, yamlContent);
+
+  // Validate written file (YAML syntax and structure)
+  try {
+    const writtenContent = await fs.readFile(filePath, 'utf8');
+    const parsed = yaml.load(writtenContent);
+
+    // Validate YAML syntax was preserved
+    if (!parsed || typeof parsed !== 'object') {
+      await fs.remove(filePath);
+      throw new Error('Failed to parse written spec file - invalid YAML structure');
+    }
+
+    // Validate spec structure using CAWS validation
+    const { validateWorkingSpec } = require('../validation/spec-validation');
+    const validation = validateWorkingSpec(parsed);
+
+    if (!validation.valid) {
+      await fs.remove(filePath);
+      const errorMessages = validation.errors
+        .map((e) => `${e.instancePath}: ${e.message}`)
+        .join('; ');
+      throw new Error(`Spec validation failed: ${errorMessages}`);
+    }
+  } catch (error) {
+    // Clean up invalid file if it exists
+    if (await fs.pathExists(filePath)) {
+      await fs.remove(filePath);
+    }
+
+    // Re-throw with helpful message
+    if (error.message.includes('YAMLException') || error.message.includes('yaml')) {
+      throw new Error(
+        `Failed to create valid spec: YAML syntax error. ${error.message}\n` +
+          '💡 Consider using the interactive mode: caws specs create <id> --interactive'
+      );
+    }
+    throw error;
+  }
 
   // Update registry
   const registry = await loadSpecsRegistry();

package/dist/commands/status.js

@@ -182,10 +182,10 @@ async function loadWaiverStatus() {
  */
 async function checkQualityGates() {
   // For now, return a placeholder
-  // In full implementation, this would run actual gate checks
+  // Quality gates are available via CLI or MCP
   return {
     checked: false,
-    message: 'Run: node apps/tools/caws/gates.js for full gate status',
+    message: 'Run: caws quality-gates or use MCP tool caws_quality_gates_run for full gate status',
   };
 }
 

package/dist/commands/templates.js

@@ -7,6 +7,7 @@
 const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
+const { findPackageRoot } = require('../utils/detection');
 
 /**
  * Built-in template definitions
@@ -64,11 +65,20 @@ const BUILTIN_TEMPLATES = {
 
 /**
  * Get template directory path
+ * Works in both development and global install scenarios
  * @returns {string|null} Template directory path or null
  */
 function getTemplateDir() {
+  // Find package root using shared utility
+  const packageRoot = findPackageRoot(__dirname);
+  
   const possiblePaths = [
+    // First: Try templates relative to package root (works in dev and global install)
+    path.join(packageRoot, 'templates'),
+    // Fallback: Try relative to current file location (for development)
     path.join(__dirname, '../../templates'),
+    path.join(__dirname, '../templates'),
+    // Legacy fallbacks
     path.join(process.cwd(), 'packages/caws-cli/templates'),
     path.join(process.cwd(), 'templates'),
   ];

package/dist/commands/tool.js

@@ -23,9 +23,8 @@ async function initializeToolSystem() {
   if (toolLoader) return toolLoader;
 
   try {
-    toolLoader = new ToolLoader({
-      toolsDir: path.join(process.cwd(), 'apps/tools/caws'),
-    });
+    // ToolLoader now checks .caws/tools first, then falls back to legacy location
+    toolLoader = new ToolLoader();
 
     toolValidator = new ToolValidator();
 

package/dist/commands/validate.js

@@ -194,6 +194,18 @@ async function validateCommand(specFile, options = {}) {
           if (error.suggestion) {
             console.log(`      ${chalk.blue('💡 ' + error.suggestion)}`);
           }
+          if (error.example) {
+            console.log(`      ${chalk.gray('Example:')}`);
+            if (error.example.contracts) {
+              error.example.contracts.forEach((contract) => {
+                console.log(`        ${chalk.gray('- type: ' + contract.type)}`);
+                console.log(`          ${chalk.gray('path: ' + contract.path)}`);
+                if (contract.description) {
+                  console.log(`          ${chalk.gray('description: ' + contract.description)}`);
+                }
+              });
+            }
+          }
         });
 
         // Show warnings

package/dist/config/index.js

@@ -49,15 +49,19 @@ function initializeGlobalSetup() {
 function loadProvenanceTools() {
   if (provenanceTools) return provenanceTools; // Already loaded
 
-  // Try multiple possible locations for provenance tools
+  // Provenance tools are now handled by CLI command (caws provenance)
+  // Legacy tool loading removed - use CLI instead
+  // Try multiple possible locations for provenance tools (legacy support)
   const possiblePaths = [
-    // 1. Bundled templates in CLI package (for global installs)
-    path.join(__dirname, '../../templates/apps/tools/caws/provenance.js'),
-    // 2. Local project templates
+    // 1. New location (if someone manually adds it)
+    path.join(process.cwd(), '.caws/tools/provenance.js'),
+    // 2. Legacy location (for backward compatibility)
     path.join(process.cwd(), 'apps/tools/caws/provenance.js'),
-    // 3. Template package in monorepo
+    // 3. Bundled templates in CLI package (legacy)
+    path.join(__dirname, '../../templates/.caws/tools/provenance.js'),
+    // 4. Template package in monorepo (legacy)
     path.join(__dirname, '../../../caws-template/apps/tools/caws/provenance.js'),
-    // 4. Detected setup template directory
+    // 5. Detected setup template directory
     null, // Will be set from setup if available
   ];
 
@@ -65,7 +69,7 @@ function loadProvenanceTools() {
   try {
     const setup = cawsSetup || initializeGlobalSetup();
     if (setup?.hasTemplateDir && setup?.templateDir) {
-      possiblePaths[3] = path.join(setup.templateDir, 'apps/tools/caws/provenance.js');
+      possiblePaths[4] = path.join(setup.templateDir, '.caws/tools/provenance.js');
     }
   } catch (setupError) {
     // Continue without detected setup
@@ -97,8 +101,13 @@ function initializeLanguageSupport() {
   if (languageSupport) return languageSupport;
 
   try {
-    // Try multiple possible locations for language support
+    // Language support tools removed - use CLI instead
+    // Try multiple possible locations for language support (legacy support)
     const possiblePaths = [
+      // New location (if someone manually adds it)
+      path.join(process.cwd(), '.caws/tools/language-support.js'),
+      // Legacy locations
+      path.join(process.cwd(), 'apps/tools/caws/language-support.js'),
       path.join(__dirname, '../../../caws-template/apps/tools/caws/language-support.js'),
       path.join(__dirname, '../../../../caws-template/apps/tools/caws/language-support.js'),
       path.join(process.cwd(), 'packages/caws-template/apps/tools/caws/language-support.js'),

package/dist/generators/working-spec.js

@@ -42,16 +42,28 @@ function generateWorkingSpec(answers) {
         .split(',')
         .map((s) => s.trim())
         .filter((s) => s),
-      out: (answers.scopeOut || 'node_modules/, dist/')
+      out: (answers.scopeOut || 'node_modules/, dist/, build/')
         .split(',')
         .map((s) => s.trim())
-        .filter((s) => s),
+        .filter((s) => s)
+        // Remove glob patterns - scope.out should only contain directory paths
+        .filter((s) => !s.includes('*') && !s.includes('?'))
+        // Ensure paths end with / for directories or are explicit file paths
+        .map((s) => {
+          // If it's a directory pattern without trailing slash, add it
+          if (!s.includes('.') && !s.endsWith('/')) {
+            return s + '/';
+          }
+          return s;
+        }),
     },
     invariants: (answers.projectInvariants || 'System maintains data consistency')
       .split('\n')
       .map((i) => i.trim())
       .filter((i) => i),
-    acceptance: (answers.acceptanceCriteria || 'Given current state, when action occurs, then expected result')
+    acceptance: (
+      answers.acceptanceCriteria || 'Given current state, when action occurs, then expected result'
+    )
       .split('\n')
       .filter((a) => a.trim())
       .map((criteria, index) => {
@@ -97,12 +109,33 @@ function generateWorkingSpec(answers) {
         .map((s) => s.trim())
         .filter((s) => s),
     },
-    contracts: [
-      {
-        type: answers.contractType || '',
-        path: answers.contractPath || '',
-      },
-    ],
+    contracts: (() => {
+      // If contract type/path provided, use it
+      if (answers.contractType && answers.contractPath) {
+        return [
+          {
+            type: answers.contractType,
+            path: answers.contractPath,
+          },
+        ];
+      }
+
+      // For Tier 1 & 2, provide minimal project_setup contract if none specified
+      const riskTier = answers.riskTier || 2;
+      if (riskTier === 1 || riskTier === 2) {
+        return [
+          {
+            type: 'project_setup',
+            path: '.caws/working-spec.yaml',
+            description:
+              'Project-level CAWS configuration. Feature-specific contracts will be added as features are developed.',
+          },
+        ];
+      }
+
+      // Tier 3 doesn't require contracts
+      return [];
+    })(),
     observability: {
       logs: (answers.observabilityLogs || '')
         .split(',')

package/dist/index.js

@@ -138,7 +138,7 @@ program
   .option('--json', 'Output machine-readable JSON to stdout', false)
   .option(
     '--gates <gates>',
-    'Run only specific gates (comma-separated: naming,code_freeze,duplication,god_objects,documentation)',
+    'Run only specific gates (comma-separated: naming,code_freeze,duplication,god_objects,hidden-todo,documentation,placeholders)',
     ''
   )
   .option('--fix', 'Attempt automatic fixes (experimental)', false)
@@ -168,7 +168,9 @@ VALID GATES:
   code_freeze      Enforce code freeze compliance
   duplication      Detect functional duplication
   god_objects      Prevent oversized files
+  hidden-todo      Detect hidden incomplete implementations
   documentation    Check documentation quality
+  placeholders     Placeholder governance (explicit degradations)
 
 EXAMPLES:
   # Run all gates in development mode

package/dist/scaffold/cursor-hooks.js

@@ -9,7 +9,7 @@ const path = require('path');
 const chalk = require('chalk');
 
 // Import detection utilities
-const { detectCAWSSetup } = require('../utils/detection');
+const { detectCAWSSetup, findPackageRoot } = require('../utils/detection');
 
 /**
  * Scaffold Cursor hooks for a CAWS project
@@ -28,9 +28,17 @@ async function scaffoldCursorHooks(projectDir, levels = ['safety', 'quality', 's
 
     // Determine template directory - prefer bundled templates
     const setup = detectCAWSSetup(projectDir);
-    const bundledTemplateDir = path.join(__dirname, '../../templates');
+    
+    // Find package root using shared utility
+    const packageRoot = findPackageRoot(__dirname);
+    
+    // Try templates relative to package root first (works in both dev and global install)
+    const bundledTemplateDir = path.join(packageRoot, 'templates');
+    const fallbackTemplateDir = path.join(__dirname, '../../templates');
     const templateDir = fs.existsSync(bundledTemplateDir)
       ? bundledTemplateDir
+      : fs.existsSync(fallbackTemplateDir)
+      ? fallbackTemplateDir
       : setup.templateDir || path.resolve(__dirname, '../templates');
 
     const cursorTemplateDir = path.join(templateDir, '.cursor');