@paths.design/caws-cli 7.0.1 → 7.0.2

package/dist/commands/diagnose.js

@@ -481,9 +481,10 @@ 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

@@ -481,11 +481,31 @@ 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) {

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/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/generators/working-spec.js

@@ -97,12 +97,32 @@ 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');

package/dist/scaffold/git-hooks.js

@@ -364,12 +364,71 @@ fi
 # Run full validation suite
 if command -v caws >/dev/null 2>&1; then
   echo "📋 Running comprehensive CAWS validation..."
-  if caws validate --quiet; then
+  
+  # Run validation and capture output
+  VALIDATION_OUTPUT=$(caws validate 2>&1)
+  VALIDATION_EXIT=$?
+  
+  if [ $VALIDATION_EXIT -eq 0 ]; then
     echo "✅ CAWS validation passed"
   else
     echo "❌ CAWS validation failed"
-    echo "💡 Fix issues locally, then push again"
-    echo "💡 You can commit fixes with: git commit --no-verify"
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "Validation Errors:"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "$VALIDATION_OUTPUT" | grep -E "(❌|error|Error|Missing|required)" || echo "$VALIDATION_OUTPUT"
+    echo ""
+    
+    # Check for contract-related errors
+    if echo "$VALIDATION_OUTPUT" | grep -qi "contract"; then
+      echo "💡 Contract Requirements:"
+      echo "   • Tier 1 & 2 changes require at least one contract"
+      echo "   • For infrastructure/setup work, use 'chore' mode or add a minimal contract:"
+      echo ""
+      echo "   Example minimal contract (.caws/working-spec.yaml):"
+      echo "   contracts:"
+      echo "     - type: 'project_setup'"
+      echo "       path: '.caws/working-spec.yaml'"
+      echo "       description: 'Project-level CAWS configuration'"
+      echo ""
+      echo "   Or change mode to 'chore' for maintenance work:"
+      echo "   mode: chore"
+      echo ""
+    fi
+    
+    # Check for active waivers
+    echo "🔍 Checking for active waivers..."
+    if command -v caws >/dev/null 2>&1 && caws waivers list --status=active --format=count 2>/dev/null | grep -q "[1-9]"; then
+      ACTIVE_WAIVERS=$(caws waivers list --status=active 2>/dev/null)
+      echo "⚠️  Active waivers found:"
+      echo "$ACTIVE_WAIVERS" | head -5
+      echo ""
+      echo "💡 Note: Waivers may not cover all validation failures"
+      echo "   Review waiver coverage: caws waivers list --status=active"
+    else
+      echo "   No active waivers found"
+      echo ""
+      echo "💡 If this is infrastructure/setup work, you can create a waiver:"
+      echo "   caws waivers create \\"
+      echo "     --title='Initial CAWS setup' \\"
+      echo "     --reason=infrastructure_limitation \\"
+      echo "     --gates=contracts \\"
+      echo "     --expires-at='2024-12-31T23:59:59Z' \\"
+      echo "     --approved-by='@your-team' \\"
+      echo "     --impact-level=low \\"
+      echo "     --mitigation-plan='Contracts will be added as features are developed'"
+    fi
+    
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "Next Steps:"
+    echo "   1. Review errors above"
+    echo "   2. Fix issues in .caws/working-spec.yaml"
+    echo "   3. Run: caws validate (to verify fixes)"
+    echo "   4. Commit fixes: git commit --no-verify (allowed)"
+    echo "   5. Push again: git push"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
     exit 1
   fi
 fi

package/dist/scaffold/index.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');
 const { detectsPublishing } = require('../utils/project-analysis');
 
 // Import git hooks scaffolding
@@ -23,8 +23,33 @@ const CLI_VERSION = require('../../package.json').version;
  * @param {string} targetDir - Target directory for scaffolding
  * @param {Object} options - Scaffold options
  */
+/**
+ * Find the template directory using robust path resolution
+ * Works in both development and global install scenarios
+ * @returns {string|null} Template directory path or null
+ */
+function findTemplateDir() {
+  // 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 possiblePaths = [
+    path.join(packageRoot, 'templates'),
+    path.resolve(__dirname, '../../templates'), // Dev fallback
+    path.resolve(__dirname, '../templates'), // Legacy fallback
+  ];
+  
+  for (const testPath of possiblePaths) {
+    if (fs.existsSync(testPath)) {
+      return testPath;
+    }
+  }
+  
+  return null;
+}
+
 async function scaffoldIDEIntegrations(targetDir, options) {
-  const templateDir = path.join(__dirname, '../../templates');
+  const templateDir = findTemplateDir() || path.join(__dirname, '../../templates');
 
   console.log(chalk.cyan('🎨 Setting up IDE integrations...'));
 
@@ -192,19 +217,24 @@ async function scaffoldProject(options) {
       setup.templateDir = cawsSetup.templateDir;
       setup.hasTemplateDir = true;
     } else if (!setup.templateDir) {
-      // Try to find template directory using absolute paths that work in CI
+      // Try to find template directory using robust path resolution
       const possiblePaths = [
-        // 1. Bundled templates in CLI package (for global installs) - CHECK THIS FIRST!
+        // 1. Use the helper function to find templates (works in dev and global install)
+        findTemplateDir(),
+        // 2. Bundled templates relative to package root
+        path.join(findPackageRoot(__dirname), 'templates'),
+        // 3. Legacy fallback paths
         path.join(__dirname, '../../templates'),
-        // 2. CI paths
+        path.join(__dirname, '../templates'),
+        // 4. CI paths
         '/home/runner/work/coding-agent-working-standard/coding-agent-working-standard/packages/caws-template',
         '/workspace/packages/caws-template',
         '/caws/packages/caws-template',
-        // 3. Monorepo relative paths
+        // 5. Monorepo relative paths
         path.resolve(process.cwd(), '../../../packages/caws-template'),
         path.resolve(process.cwd(), '../../packages/caws-template'),
         path.resolve(process.cwd(), '../packages/caws-template'),
-      ];
+      ].filter(Boolean); // Remove null values
 
       for (const testPath of possiblePaths) {
         if (fs.existsSync(testPath)) {
@@ -567,10 +597,22 @@ async function scaffoldProject(options) {
             console.warn(chalk.yellow(`⚠️  Failed to add ${enhancement.name}:`), copyError.message);
           }
         } else {
-          // If source doesn't exist in template, create the directory structure
+          // If source doesn't exist in template, check if it should be a file or directory
           try {
-            await fs.ensureDir(destPath);
-            console.log(chalk.green(`✅ Created ${enhancement.description}`));
+            // Check if the enhancement name looks like a file (has extension)
+            const hasExtension = path.extname(enhancement.name).length > 0;
+            
+            if (hasExtension) {
+              // Create an empty file for file-like enhancements
+              await fs.ensureDir(path.dirname(destPath));
+              await fs.writeFile(destPath, '');
+              console.log(chalk.yellow(`⚠️  Created empty ${enhancement.description} (template not found)`));
+              console.log(chalk.gray(`   Template expected at: ${sourcePath}`));
+            } else {
+              // Create directory for directory-like enhancements
+              await fs.ensureDir(destPath);
+              console.log(chalk.green(`✅ Created ${enhancement.description}`));
+            }
             addedCount++;
             addedFiles.push(enhancement.name);
           } catch (createError) {
@@ -629,19 +671,19 @@ async function scaffoldProject(options) {
         console.log('3. Push to trigger automated publishing');
         console.log('4. Your existing CAWS tools remain unchanged');
       } else {
-        console.log('2. Customize your working spec in .caws/working-spec.yaml');
-        console.log('3. Run validation: caws validate --suggestions');
+        console.log('2. Run: caws validate (verify setup)');
+        console.log('3. Run: caws diagnose (check project health)');
+        console.log('4. Customize .caws/working-spec.yaml for your project');
+        console.log('5. Optional: Create .caws/policy.yaml for tier-specific budgets');
         if (!qualityGatesAdded && !options.minimal) {
           console.log(
-            chalk.gray('4. Note: Quality gates scripts skipped (git hooks use CAWS CLI by default)')
+            chalk.gray('6. Note: Quality gates scripts skipped (git hooks use CAWS CLI by default)')
           );
           console.log(
             chalk.gray(
               '   Add --with-quality-gates flag if you want local scripts without global CLI'
             )
           );
-        } else {
-          console.log('4. Your existing CAWS tools remain unchanged');
         }
       }
     }

package/dist/utils/detection.js

@@ -8,6 +8,25 @@ const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
 
+/**
+ * Find the package root directory by looking for package.json
+ * Works in both development (src/) and production (dist/) scenarios
+ * @param {string} startDir - Directory to start searching from (defaults to __dirname)
+ * @returns {string} Package root directory path
+ */
+function findPackageRoot(startDir = __dirname) {
+  let packageRoot = startDir;
+  for (let i = 0; i < 5; i++) {
+    const packageJsonPath = path.join(packageRoot, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+      return packageRoot;
+    }
+    packageRoot = path.dirname(packageRoot);
+  }
+  // Fallback to startDir if package.json not found
+  return startDir;
+}
+
 /**
  * Detect CAWS setup in a directory
  * @param {string} cwd - Current working directory
@@ -93,10 +112,17 @@ function detectCAWSSetup(cwd = process.cwd()) {
 
   // Check for template directory - try multiple possible locations
   let templateDir = null;
+
+  // Find package root using shared utility
+  const packageRoot = findPackageRoot(__dirname);
+
   const possibleTemplatePaths = [
-    // FIRST: Try bundled templates (for npm-installed CLI)
-    { path: path.resolve(__dirname, '../templates'), source: 'bundled with CLI' },
-    { path: path.resolve(__dirname, 'templates'), source: 'bundled with CLI (fallback)' },
+    // FIRST: Try bundled templates relative to package root (works in dev and global install)
+    { path: path.join(packageRoot, 'templates'), source: 'bundled with CLI (package root)' },
+    // Fallback: Try relative to current file location (for development)
+    { path: path.resolve(__dirname, '../../templates'), source: 'bundled with CLI (dev fallback)' },
+    { path: path.resolve(__dirname, '../templates'), source: 'bundled with CLI (legacy fallback)' },
+    { path: path.resolve(__dirname, 'templates'), source: 'bundled with CLI (legacy fallback 2)' },
     // Try relative to current working directory (for monorepo setups)
     { path: path.resolve(cwd, '../caws-template'), source: 'monorepo parent directory' },
     { path: path.resolve(cwd, '../../caws-template'), source: 'monorepo grandparent' },
@@ -171,4 +197,5 @@ function detectCAWSSetup(cwd = process.cwd()) {
 
 module.exports = {
   detectCAWSSetup,
+  findPackageRoot,
 };

package/dist/validation/spec-validation.js

@@ -325,11 +325,35 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
     // Tier-specific validations
     if (spec.risk_tier === 1 || spec.risk_tier === 2) {
       if (!spec.contracts || spec.contracts.length === 0) {
+        const isChoreMode = spec.mode === 'chore';
+        const suggestion = isChoreMode
+          ? 'For infrastructure/setup work, add a minimal project_setup contract or create a waiver'
+          : 'Add API contracts (OpenAPI, GraphQL, etc.) or change mode to "chore" for maintenance work';
+        
         errors.push({
           instancePath: '/contracts',
-          message: 'Contracts required for Tier 1 and 2 changes',
-          suggestion: 'Specify API contracts (OpenAPI, GraphQL, etc.)',
+          message: `Contracts required for Tier ${spec.risk_tier} changes`,
+          suggestion: suggestion,
           canAutoFix: false,
+          example: isChoreMode
+            ? {
+                contracts: [
+                  {
+                    type: 'project_setup',
+                    path: '.caws/working-spec.yaml',
+                    description: 'Project-level CAWS configuration. Feature-specific contracts will be added as features are developed.',
+                  },
+                ],
+              }
+            : {
+                contracts: [
+                  {
+                    type: 'openapi',
+                    path: 'docs/api/feature.yaml',
+                    version: '1.0.0',
+                  },
+                ],
+              },
         });
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paths.design/caws-cli",
-  "version": "7.0.1",
+  "version": "7.0.2",
   "description": "CAWS CLI - Coding Agent Workflow System command line tools",
   "main": "dist/index.js",
   "bin": {