create-qa-architect 5.3.1 → 5.4.3

package/lib/project-maturity.js

@@ -157,6 +157,9 @@ class ProjectMaturityDetector {
       hasTests: this.hasTests(),
       hasDependencies: this.hasDependencies(),
       hasCssFiles: this.hasCssFiles(),
+      hasShellScripts: this.hasShellScripts(),
+      shellScriptCount: this.countShellScripts(),
+      isShellProject: this.isShellProject(),
       packageJsonExists: this.packageJsonExists(),
     }
   }
@@ -266,7 +269,7 @@ class ProjectMaturityDetector {
       const deps = packageJson.dependencies || {}
       const devDeps = packageJson.devDependencies || {}
       return Object.keys(deps).length > 0 || Object.keys(devDeps).length > 0
-    } catch {
+    } catch (_error) {
       return false
     }
   }
@@ -287,6 +290,36 @@ class ProjectMaturityDetector {
     )
   }
 
+  /**
+   * Check if project has shell scripts
+   * @returns {boolean} True if shell scripts exist
+   */
+  hasShellScripts() {
+    return this.countShellScripts() > 0
+  }
+
+  /**
+   * Count shell script files
+   * @returns {number} Number of shell script files
+   */
+  countShellScripts() {
+    const extensions = ['.sh', '.bash']
+
+    return this.countFilesRecursive(this.projectPath, {
+      extensions,
+      excludeDirs: EXCLUDE_DIRECTORIES.PROJECT_MATURITY,
+      maxDepth: 4,
+    })
+  }
+
+  /**
+   * Check if this is primarily a shell script project
+   * @returns {boolean} True if shell project (has .sh files, no package.json)
+   */
+  isShellProject() {
+    return this.hasShellScripts() && !this.packageJsonExists()
+  }
+
   /**
    * Check if package.json exists
    * @returns {boolean} True if package.json exists
@@ -405,9 +438,17 @@ class ProjectMaturityDetector {
         }
       }
     } catch (error) {
-      // Silently ignore permission errors
-      if (this.verbose) {
-        console.warn(`Warning: Could not read directory ${dir}:`, error.message)
+      // Always log permission errors (affects maturity detection accuracy)
+      if (error.code === 'EACCES') {
+        console.warn(`⚠️  Permission denied: ${dir} (excluded from analysis)`)
+      } else if (error.code !== 'ENOENT') {
+        console.warn(
+          `⚠️  Could not read ${dir}: ${error.message} (${error.code})`
+        )
+      }
+
+      if (this.verbose && error.stack) {
+        console.warn(`   Stack: ${error.stack}`)
       }
     }
 
@@ -435,7 +476,7 @@ class ProjectMaturityDetector {
 
   /**
    * Generate GitHub Actions outputs for maturity detection
-   * @returns {{maturity: string, sourceCount: number, testCount: number, hasDeps: boolean, hasDocs: boolean, hasCss: boolean, requiredChecks: string, optionalChecks: string, disabledChecks: string}} GitHub Actions output format
+   * @returns {{maturity: string, sourceCount: number, testCount: number, hasDeps: boolean, hasDocs: boolean, hasCss: boolean, hasShell: boolean, shellCount: number, isShellProject: boolean, requiredChecks: string, optionalChecks: string, disabledChecks: string}} GitHub Actions output format
    */
   generateGitHubActionsOutput() {
     const maturity = this.detect()
@@ -449,6 +490,9 @@ class ProjectMaturityDetector {
       hasDeps: stats.hasDependencies,
       hasDocs: stats.hasDocumentation,
       hasCss: stats.hasCssFiles,
+      hasShell: stats.hasShellScripts,
+      shellCount: stats.shellScriptCount,
+      isShellProject: stats.isShellProject,
       requiredChecks: checks.required.join(','),
       optionalChecks: checks.optional.join(','),
       disabledChecks: checks.disabled.join(','),
@@ -472,7 +516,12 @@ class ProjectMaturityDetector {
     console.log(`  • Test files: ${stats.testFiles}`)
     console.log(`  • Documentation: ${stats.hasDocumentation ? 'Yes' : 'No'}`)
     console.log(`  • Dependencies: ${stats.hasDependencies ? 'Yes' : 'No'}`)
-    console.log(`  • CSS files: ${stats.hasCssFiles ? 'Yes' : 'No'}\n`)
+    console.log(`  • CSS files: ${stats.hasCssFiles ? 'Yes' : 'No'}`)
+    console.log(`  • Shell scripts: ${stats.shellScriptCount}`)
+    if (stats.isShellProject) {
+      console.log(`  • Project type: Shell script project`)
+    }
+    console.log()
 
     console.log('Quality Checks:')
     console.log(`  ✅ Required: ${level.checks.required.join(', ')}`)
@@ -504,6 +553,9 @@ if (require.main === module) {
     console.log(`has-deps=${output.hasDeps}`)
     console.log(`has-docs=${output.hasDocs}`)
     console.log(`has-css=${output.hasCss}`)
+    console.log(`has-shell=${output.hasShell}`)
+    console.log(`shell-count=${output.shellCount}`)
+    console.log(`is-shell-project=${output.isShellProject}`)
     console.log(`required-checks=${output.requiredChecks}`)
     console.log(`optional-checks=${output.optionalChecks}`)
     console.log(`disabled-checks=${output.disabledChecks}`)

package/lib/smart-strategy-generator.js

@@ -170,9 +170,19 @@ function readPackageJson(projectPath) {
   } catch (error) {
     // DR22 fix: Provide specific error messages for different failure types
     if (error instanceof SyntaxError) {
-      console.error(`❌ package.json has invalid JSON syntax: ${error.message}`)
+      const errorId = 'PKG_JSON_INVALID_SYNTAX'
+      console.error(`❌ [${errorId}] package.json has invalid JSON syntax:`)
       console.error(`   File: ${pkgPath}`)
-      console.error('   Please fix JSON syntax errors before continuing')
+      console.error(`   Error: ${error.message}`)
+      console.error(`\n   Recovery steps:`)
+      console.error(`   1. Validate JSON: cat ${pkgPath} | jq .`)
+      console.error(
+        `   2. Common issues: trailing commas, missing quotes, unclosed brackets`
+      )
+      console.error(`   3. Use a JSON validator: https://jsonlint.com`)
+      console.error(
+        `\n   ⚠️  Smart Test Strategy will use generic fallback until this is fixed\n`
+      )
     } else if (error.code === 'EACCES') {
       console.error(`❌ Permission denied reading package.json: ${pkgPath}`)
       console.error('   Check file permissions and try again')
@@ -235,7 +245,14 @@ function generateSmartStrategy(options = {}) {
   )
 
   if (!fs.existsSync(templatePath)) {
-    throw new Error(`Smart strategy template not found at ${templatePath}`)
+    throw new Error(
+      `Smart strategy template not found at ${templatePath}\n` +
+        `This indicates a package installation issue.\n\n` +
+        `Troubleshooting steps:\n` +
+        `1. Reinstall the package: npm install -g create-qa-architect@latest\n` +
+        `2. Check file permissions: ls -la ${path.dirname(templatePath)}\n` +
+        `3. Report issue if problem persists: https://github.com/vibebuildlab/qa-architect/issues/new`
+    )
   }
 
   let template = fs.readFileSync(templatePath, 'utf8')

package/lib/telemetry.js

@@ -75,7 +75,7 @@ function loadTelemetryData() {
       const data = fs.readFileSync(file, 'utf8')
       return JSON.parse(data)
     }
-  } catch {
+  } catch (_error) {
     // If corrupted, start fresh
     console.warn('⚠️  Telemetry data corrupted, starting fresh')
   }

package/lib/ui-helpers.js

@@ -58,7 +58,7 @@ function showProgress(message) {
     const oraImport = require('ora')
     const ora = /** @type {any} */ (oraImport.default || oraImport)
     return ora(message).start()
-  } catch {
+  } catch (_error) {
     // Fallback if ora not installed (graceful degradation)
     console.log(formatMessage('working', message))
     return {

package/lib/validation/config-security.js

@@ -37,11 +37,19 @@ class ConfigSecurityScanner {
     // checksumMap dependency injection - FOR TESTING ONLY
     // WARNING: Do not use in production CLI - this bypasses security verification!
     if (options.checksumMap) {
-      if (process.env.NODE_ENV === 'production') {
+      // Security fix: Block checksumMap override in production
+      // Only allow in explicit test/development mode
+      const isTestMode = process.env.NODE_ENV === 'test'
+      const isDeveloperMode = process.env.QAA_DEVELOPER === 'true'
+      const isProduction = process.env.NODE_ENV === 'production'
+
+      if (isProduction || (!isTestMode && !isDeveloperMode)) {
         throw new Error(
-          'checksumMap override not allowed in production environment'
+          'checksumMap override not allowed in production. ' +
+            'Only permitted when NODE_ENV=test or QAA_DEVELOPER=true'
         )
       }
+
       if (!options.quiet) {
         console.warn(
           '⚠️ WARNING: Using custom checksum map - FOR TESTING ONLY!'
@@ -118,23 +126,14 @@ class ConfigSecurityScanner {
         )
       }
 
-      // Check if fallback to unpinned gitleaks is explicitly allowed
-      if (this.options.allowLatestGitleaks) {
-        console.warn(
-          '🚨 WARNING: Using npx gitleaks (supply chain risk - downloads latest version)'
-        )
-        console.warn(
-          '📌 Consider: brew install gitleaks (macOS) or choco install gitleaks (Windows)'
-        )
-        return 'npx gitleaks'
-      }
-
-      // Security-first: fail hard instead of silent fallback
+      // Security-first: fail hard instead of any fallback
+      // SECURITY: Removed npx gitleaks fallback to prevent command injection
       throw new Error(
         `Cannot resolve secure gitleaks binary. Options:\n` +
           `1. Install globally: brew install gitleaks (macOS) or choco install gitleaks (Windows)\n` +
           `2. Set GITLEAKS_PATH to your preferred binary\n` +
-          `3. Use --allow-latest-gitleaks flag (NOT RECOMMENDED - supply chain risk)`
+          `Note: --allow-latest-gitleaks flag is deprecated and no longer supported.\n` +
+          `npx gitleaks has been intentionally removed due to supply chain security risk.`
       )
     }
   }
@@ -404,11 +403,16 @@ class ConfigSecurityScanner {
             spinner.succeed('npm audit completed')
           }
         } catch {
-          spinner.warn(`Could not parse ${packageManager} audit output`)
-          console.warn(`Could not parse ${packageManager} audit output`)
+          spinner.fail(`Could not parse ${packageManager} audit output`)
+          this.issues.push(
+            `${packageManager} audit: Unable to parse audit output. Run '${packageManager} audit --json' manually to inspect vulnerabilities.`
+          )
         }
       } else {
-        spinner.succeed('npm audit completed')
+        spinner.fail('npm audit returned an error with no output')
+        this.issues.push(
+          `${packageManager} audit: Failed with no output. Run '${packageManager} audit --json' manually to inspect vulnerabilities.`
+        )
       }
     }
   }

package/lib/validation/index.js

@@ -4,6 +4,27 @@ const { ConfigSecurityScanner } = require('./config-security')
 const { DocumentationValidator } = require('./documentation')
 const { WorkflowValidator } = require('./workflow-validation')
 
+/**
+ * Validation check configuration
+ */
+const VALIDATION_CHECKS = [
+  {
+    name: 'configSecurity',
+    label: 'Configuration security',
+    method: 'runConfigSecurity',
+  },
+  {
+    name: 'documentation',
+    label: 'Documentation validation',
+    method: 'runDocumentationValidation',
+  },
+  {
+    name: 'workflows',
+    label: 'Workflow validation',
+    method: 'runWorkflowValidation',
+  },
+]
+
 /**
  * Enhanced Validation Runner
  * Coordinates all validation checks
@@ -43,63 +64,31 @@ class ValidationRunner {
   async runComprehensiveCheck() {
     console.log('🔍 Running comprehensive validation...\n')
 
-    const results = {
-      configSecurity: null,
-      documentation: null,
-      workflows: null,
-      overall: { passed: true, issues: [] },
-    }
-
-    try {
-      console.log('⏳ [1/3] Running configuration security scan...')
-      results.configSecurity = await this.runConfigSecurity()
-      console.log('✅ [1/3] Configuration security complete')
-    } catch (error) {
-      console.log('❌ [1/3] Configuration security failed')
-      results.configSecurity = { passed: false, error: error.message }
-      results.overall.passed = false
-      results.overall.issues.push(`Configuration Security: ${error.message}`)
-    }
+    const results = this._initResults()
+    const total = VALIDATION_CHECKS.length
 
-    console.log('') // Add spacing between checks
-
-    try {
-      console.log('⏳ [2/3] Running documentation validation...')
-      results.documentation = await this.runDocumentationValidation()
-      console.log('✅ [2/3] Documentation validation complete')
-    } catch (error) {
-      console.log('❌ [2/3] Documentation validation failed')
-      results.documentation = { passed: false, error: error.message }
-      results.overall.passed = false
-      results.overall.issues.push(`Documentation: ${error.message}`)
-    }
+    for (let i = 0; i < VALIDATION_CHECKS.length; i++) {
+      const check = VALIDATION_CHECKS[i]
+      const stepNum = i + 1
 
-    console.log('') // Add spacing between checks
-
-    try {
-      console.log('⏳ [3/3] Running workflow validation...')
-      results.workflows = await this.runWorkflowValidation()
-      console.log('✅ [3/3] Workflow validation complete')
-    } catch (error) {
-      console.log('❌ [3/3] Workflow validation failed')
-      results.workflows = { passed: false, error: error.message }
-      results.overall.passed = false
-      results.overall.issues.push(`Workflows: ${error.message}`)
-    }
+      console.log(
+        `⏳ [${stepNum}/${total}] Running ${check.label.toLowerCase()}...`
+      )
 
-    console.log('') // Add spacing
+      try {
+        results[check.name] = await this[check.method]()
+        console.log(`✅ [${stepNum}/${total}] ${check.label} complete`)
+      } catch (error) {
+        console.log(`❌ [${stepNum}/${total}] ${check.label} failed`)
+        results[check.name] = { passed: false, error: error.message }
+        results.overall.passed = false
+        results.overall.issues.push(`${check.label}: ${error.message}`)
+      }
 
-    if (results.overall.passed) {
-      console.log('✅ All validation checks passed!')
-    } else {
-      // Detect test scenario and use appropriate prefix
-      const isTest = process.argv.join(' ').includes('test')
-      const prefix = isTest ? '📋 TEST SCENARIO:' : '❌'
-      console.error(`${prefix} Validation failed with issues:`)
-      results.overall.issues.forEach(issue => console.error(`   - ${issue}`))
-      throw new Error('Comprehensive validation failed')
+      console.log('')
     }
 
+    this._reportResults(results)
     return results
   }
 
@@ -110,71 +99,53 @@ class ValidationRunner {
   async runComprehensiveCheckParallel() {
     console.log('🔍 Running comprehensive validation (parallel)...\n')
 
-    const results = {
-      configSecurity: null,
-      documentation: null,
-      workflows: null,
-      overall: { passed: true, issues: [] },
-    }
+    const results = this._initResults()
 
-    // Run all validations in parallel
-    const validationPromises = [
-      this.runConfigSecurity()
+    const validationPromises = VALIDATION_CHECKS.map(check =>
+      this[check.method]()
         .then(result => {
-          results.configSecurity = result
-          console.log('✅ Configuration security complete')
+          results[check.name] = result
+          console.log(`✅ ${check.label} complete`)
         })
         .catch(error => {
-          console.log('❌ Configuration security failed')
-          results.configSecurity = { passed: false, error: error.message }
+          console.log(`❌ ${check.label} failed`)
+          results[check.name] = { passed: false, error: error.message }
           results.overall.passed = false
-          results.overall.issues.push(
-            `Configuration Security: ${error.message}`
-          )
-        }),
-
-      this.runDocumentationValidation()
-        .then(result => {
-          results.documentation = result
-          console.log('✅ Documentation validation complete')
+          results.overall.issues.push(`${check.label}: ${error.message}`)
         })
-        .catch(error => {
-          console.log('❌ Documentation validation failed')
-          results.documentation = { passed: false, error: error.message }
-          results.overall.passed = false
-          results.overall.issues.push(`Documentation: ${error.message}`)
-        }),
+    )
 
-      this.runWorkflowValidation()
-        .then(result => {
-          results.workflows = result
-          console.log('✅ Workflow validation complete')
-        })
-        .catch(error => {
-          console.log('❌ Workflow validation failed')
-          results.workflows = { passed: false, error: error.message }
-          results.overall.passed = false
-          results.overall.issues.push(`Workflows: ${error.message}`)
-        }),
-    ]
-
-    // Wait for all validations to complete
     await Promise.all(validationPromises)
+    console.log('')
+
+    this._reportResults(results)
+    return results
+  }
 
-    console.log('') // Add spacing
+  /**
+   * Initialize results object
+   */
+  _initResults() {
+    const results = { overall: { passed: true, issues: [] } }
+    VALIDATION_CHECKS.forEach(check => {
+      results[check.name] = null
+    })
+    return results
+  }
 
+  /**
+   * Report validation results
+   */
+  _reportResults(results) {
     if (results.overall.passed) {
       console.log('✅ All validation checks passed!')
     } else {
-      // Detect test scenario and use appropriate prefix
       const isTest = process.argv.join(' ').includes('test')
       const prefix = isTest ? '📋 TEST SCENARIO:' : '❌'
       console.error(`${prefix} Validation failed with issues:`)
       results.overall.issues.forEach(issue => console.error(`   - ${issue}`))
       throw new Error('Comprehensive validation failed')
     }
-
-    return results
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-qa-architect",
-  "version": "5.3.1",
+  "version": "5.4.3",
   "description": "QA Architect - Bootstrap quality automation for JavaScript/TypeScript and Python projects with GitHub Actions, pre-commit hooks, linting, formatting, and smart test strategy",
   "main": "setup.js",
   "bin": {
@@ -20,8 +20,8 @@
     "validate:comprehensive": "node setup.js --comprehensive --no-markdownlint",
     "validate:all": "npm run validate:comprehensive && npm run security:audit",
     "validate:pre-push": "npm run test:patterns --if-present && npm run lint && npm run format:check && npm run test:commands --if-present && npm test --if-present",
-    "test": "export QAA_DEVELOPER=true && node tests/setup.test.js && node tests/integration.test.js && node tests/error-paths.test.js && node tests/error-messages.test.js && node tests/cache-manager.test.js && node tests/parallel-validation.test.js && node tests/python-integration.test.js && node tests/interactive.test.js && node tests/monorepo.test.js && node tests/template-loader.test.js && node tests/critical-fixes.test.js && node tests/interactive-routing-fix.test.js && node tests/telemetry.test.js && node tests/error-reporter.test.js && node tests/premium-dependency-monitoring.test.js && node tests/multi-language-dependency-monitoring.test.js && node tests/cli-deps-integration.test.js && node tests/real-world-packages.test.js && node tests/validation-factory.test.js && node tests/setup-error-coverage.test.js && node tests/python-detection-sensitivity.test.js && node tests/python-parser-fixes.test.js && node tests/licensing.test.js && node tests/security-licensing.test.js && node tests/real-purchase-flow.test.js && node tests/base-validator.test.js && node tests/dependency-monitoring-basic.test.js && node tests/workflow-validation.test.js && node tests/setup-critical-paths.test.js && node tests/project-maturity.test.js && node tests/project-maturity-cli.test.js && node tests/package-manager-detection.test.js && node tests/check-docs.test.js && node tests/validate-command-patterns.test.js && node tests/gitleaks-binary-resolution.test.js && node tests/gitleaks-production-checksums.test.js && node tests/gitleaks-checksum-verification.test.js && node tests/gitleaks-real-binary-test.js && node tests/tier-enforcement.test.js",
-    "test:unit": "export QAA_DEVELOPER=true && node tests/setup.test.js && node tests/error-paths.test.js && node tests/error-messages.test.js && node tests/cache-manager.test.js && node tests/template-loader.test.js && node tests/telemetry.test.js && node tests/error-reporter.test.js && node tests/validation-factory.test.js && node tests/setup-error-coverage.test.js && node tests/licensing.test.js && node tests/security-licensing.test.js && node tests/base-validator.test.js && node tests/dependency-monitoring-basic.test.js && node tests/workflow-validation.test.js && node tests/setup-critical-paths.test.js && node tests/project-maturity.test.js && node tests/package-manager-detection.test.js && node tests/check-docs.test.js && node tests/validate-command-patterns.test.js && node tests/gitleaks-binary-resolution.test.js && node tests/gitleaks-production-checksums.test.js && node tests/gitleaks-checksum-verification.test.js",
+    "test": "export QAA_DEVELOPER=true && node tests/result-types.test.js && node tests/setup.test.js && node tests/integration.test.js && node tests/error-paths.test.js && node tests/error-messages.test.js && node tests/cache-manager.test.js && node tests/parallel-validation.test.js && node tests/python-integration.test.js && node tests/interactive.test.js && node tests/monorepo.test.js && node tests/template-loader.test.js && node tests/critical-fixes.test.js && node tests/interactive-routing-fix.test.js && node tests/telemetry.test.js && node tests/error-reporter.test.js && node tests/premium-dependency-monitoring.test.js && node tests/multi-language-dependency-monitoring.test.js && node tests/cli-deps-integration.test.js && node tests/deps-edge-cases.test.js && node tests/real-world-packages.test.js && node tests/validation-factory.test.js && node tests/setup-error-coverage.test.js && node tests/python-detection-sensitivity.test.js && node tests/python-parser-fixes.test.js && node tests/licensing.test.js && node tests/security-licensing.test.js && node tests/real-purchase-flow.test.js && node tests/base-validator.test.js && node tests/dependency-monitoring-basic.test.js && node tests/workflow-validation.test.js && node tests/workflow-tiers.test.js && node tests/analyze-ci.test.js && node tests/analyze-ci-integration.test.js && node tests/setup-critical-paths.test.js && node tests/project-maturity.test.js && node tests/project-maturity-cli.test.js && node tests/package-manager-detection.test.js && node tests/check-docs.test.js && node tests/validate-command-patterns.test.js && node tests/gitleaks-binary-resolution.test.js && node tests/gitleaks-production-checksums.test.js && node tests/gitleaks-checksum-verification.test.js && node tests/gitleaks-real-binary-test.js && node tests/tier-enforcement.test.js",
+    "test:unit": "export QAA_DEVELOPER=true && node tests/result-types.test.js && node tests/setup.test.js && node tests/error-paths.test.js && node tests/error-messages.test.js && node tests/cache-manager.test.js && node tests/template-loader.test.js && node tests/telemetry.test.js && node tests/error-reporter.test.js && node tests/validation-factory.test.js && node tests/setup-error-coverage.test.js && node tests/licensing.test.js && node tests/security-licensing.test.js && node tests/base-validator.test.js && node tests/dependency-monitoring-basic.test.js && node tests/workflow-validation.test.js && node tests/workflow-tiers.test.js && node tests/analyze-ci.test.js && node tests/setup-critical-paths.test.js && node tests/project-maturity.test.js && node tests/package-manager-detection.test.js && node tests/check-docs.test.js && node tests/validate-command-patterns.test.js && node tests/gitleaks-binary-resolution.test.js && node tests/gitleaks-production-checksums.test.js && node tests/gitleaks-checksum-verification.test.js",
     "test:fast": "npm run test:unit",
     "test:medium": "npm run test:fast && npm run test:patterns && npm run test:commands",
     "test:slow": "export QAA_DEVELOPER=true && node tests/python-integration.test.js && node tests/interactive.test.js && node tests/monorepo.test.js && node tests/critical-fixes.test.js && node tests/interactive-routing-fix.test.js && node tests/premium-dependency-monitoring.test.js && node tests/multi-language-dependency-monitoring.test.js && node tests/cli-deps-integration.test.js && node tests/real-world-packages.test.js && node tests/python-detection-sensitivity.test.js && node tests/python-parser-fixes.test.js && node tests/real-purchase-flow.test.js && node tests/project-maturity-cli.test.js && node tests/gitleaks-real-binary-test.js && npm run test:e2e",

package/scripts/validate-claude-md.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+'use strict'
+
+/**
+ * Validates CLAUDE.md consistency with package.json
+ * Checks that package name and version are correctly referenced
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+function validateClaudeMd() {
+  console.log('🔍 Validating CLAUDE.md...\n')
+
+  // Read package.json
+  const packagePath = path.join(__dirname, '..', 'package.json')
+  if (!fs.existsSync(packagePath)) {
+    console.error('❌ package.json not found')
+    process.exit(1)
+  }
+
+  const pkg = JSON.parse(fs.readFileSync(packagePath, 'utf8'))
+  const packageName = pkg.name
+  const packageVersion = pkg.version
+
+  // Read CLAUDE.md
+  const claudeMdPath = path.join(__dirname, '..', 'CLAUDE.md')
+  if (!fs.existsSync(claudeMdPath)) {
+    console.error('❌ CLAUDE.md not found')
+    process.exit(1)
+  }
+
+  const claudeMd = fs.readFileSync(claudeMdPath, 'utf8')
+
+  let errors = 0
+
+  // Check for package name reference
+  if (!claudeMd.includes(packageName)) {
+    console.error(
+      `❌ CLAUDE.md does not reference package name: ${packageName}`
+    )
+    errors++
+  } else {
+    console.log(`✅ Package name referenced: ${packageName}`)
+  }
+
+  // Check for version reference (optional - just warn)
+  if (!claudeMd.includes(packageVersion)) {
+    console.warn(
+      `⚠️  CLAUDE.md does not reference current version: ${packageVersion}`
+    )
+    console.warn('   This is not a critical error, but consider updating.')
+  } else {
+    console.log(`✅ Version referenced: ${packageVersion}`)
+  }
+
+  // Basic content checks
+  const requiredSections = ['Project Overview', 'Commands', 'Architecture']
+
+  requiredSections.forEach(section => {
+    if (!claudeMd.includes(section)) {
+      console.error(`❌ Missing required section: ${section}`)
+      errors++
+    } else {
+      console.log(`✅ Section found: ${section}`)
+    }
+  })
+
+  console.log()
+
+  if (errors > 0) {
+    console.error(`❌ CLAUDE.md validation failed with ${errors} error(s)`)
+    process.exit(1)
+  } else {
+    console.log('✅ CLAUDE.md validation passed!')
+    process.exit(0)
+  }
+}
+
+validateClaudeMd()