claudex-setup 1.6.0 → 1.8.0

package/src/setup.js

@@ -1,6 +1,6 @@
 /**
  * Setup engine - applies recommended Claude Code configuration to a project.
- * v0.3.0 - Smart CLAUDE.md generation with project analysis.
+ * v1.8.0 - Starter-safe setup engine with reusable planning primitives.
  */
 
 const fs = require('fs');
@@ -8,6 +8,7 @@ const path = require('path');
 const { TECHNIQUES, STACKS } = require('./techniques');
 const { ProjectContext } = require('./context');
 const { audit } = require('./audit');
+const { buildSettingsForProfile } = require('./governance');
 
 // ============================================================
 // Helper: detect project scripts from package.json
@@ -248,9 +249,9 @@ function detectDependencies(ctx) {
 // Helper: detect main directories
 // ============================================================
 function detectMainDirs(ctx) {
-  const candidates = ['src', 'lib', 'app', 'pages', 'components', 'api', 'routes', 'utils', 'helpers', 'services', 'models', 'controllers', 'views', 'public', 'assets', 'config', 'tests', 'test', '__tests__', 'spec', 'scripts', 'prisma', 'db', 'middleware', 'hooks'];
+  const candidates = ['src', 'lib', 'app', 'pages', 'components', 'api', 'routes', 'utils', 'helpers', 'services', 'models', 'controllers', 'views', 'public', 'assets', 'config', 'tests', 'test', '__tests__', 'spec', 'scripts', 'prisma', 'db', 'middleware', 'hooks', 'agents', 'chains', 'workers', 'jobs', 'dags', 'macros', 'migrations'];
   // Also check inside src/ for nested structure (common in Next.js, React)
-  const srcNested = ['src/components', 'src/app', 'src/pages', 'src/api', 'src/lib', 'src/hooks', 'src/utils', 'src/services', 'src/models', 'src/middleware', 'src/app/api', 'app/api'];
+  const srcNested = ['src/components', 'src/app', 'src/pages', 'src/api', 'src/lib', 'src/hooks', 'src/utils', 'src/services', 'src/models', 'src/middleware', 'src/app/api', 'app/api', 'src/agents', 'src/chains', 'src/workers', 'src/jobs', 'models/staging', 'models/marts'];
   const found = [];
   const seenNames = new Set();
 
@@ -267,6 +268,55 @@ function detectMainDirs(ctx) {
   return found;
 }
 
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function extractTomlSection(content, sectionName) {
+  const pattern = new RegExp(`\\[${escapeRegex(sectionName)}\\]([\\s\\S]*?)(?:\\n\\s*\\[|$)`);
+  const match = content.match(pattern);
+  return match ? match[1] : null;
+}
+
+function extractTomlValue(sectionContent, key) {
+  if (!sectionContent) return null;
+  const pattern = new RegExp(`^\\s*${escapeRegex(key)}\\s*=\\s*["']([^"']+)["']`, 'm');
+  const match = sectionContent.match(pattern);
+  return match ? match[1].trim() : null;
+}
+
+function detectProjectMetadata(ctx) {
+  const pkg = ctx.jsonFile('package.json');
+  if (pkg && (pkg.name || pkg.description)) {
+    return {
+      name: pkg.name || path.basename(ctx.dir),
+      description: pkg.description || '',
+    };
+  }
+
+  const pyproject = ctx.fileContent('pyproject.toml') || '';
+  if (pyproject) {
+    const projectSection = extractTomlSection(pyproject, 'project');
+    const poetrySection = extractTomlSection(pyproject, 'tool.poetry');
+    const name = extractTomlValue(projectSection, 'name') ||
+      extractTomlValue(poetrySection, 'name');
+    const description = extractTomlValue(projectSection, 'description') ||
+      extractTomlValue(poetrySection, 'description');
+
+    if (name || description) {
+      return {
+        name: name || path.basename(ctx.dir),
+        description: description || '',
+      };
+    }
+  }
+
+  return {
+    name: path.basename(ctx.dir),
+    description: '',
+  };
+}
+
 // ============================================================
 // Helper: generate Mermaid diagram from directory structure
 // ============================================================
@@ -295,6 +345,11 @@ function generateMermaid(dirs, stacks) {
   const hasSrcComponents = dirNames.includes('src/components') || dirNames.includes('components');
   const hasSrcHooks = dirNames.includes('src/hooks') || dirNames.includes('hooks');
   const hasSrcLib = dirNames.includes('src/lib') || dirNames.includes('lib');
+  const hasSrcNode = dirNames.includes('src');
+  const hasAgents = dirNames.includes('src/agents') || dirNames.includes('agents');
+  const hasChains = dirNames.includes('src/chains') || dirNames.includes('chains');
+  const hasWorkers = dirNames.includes('src/workers') || dirNames.includes('workers') || dirNames.includes('jobs');
+  const hasPipelines = dirNames.includes('dags') || dirNames.includes('macros');
 
   // Smart entry point based on framework
   const isNextJs = stackKeys.includes('nextjs');
@@ -312,6 +367,7 @@ function generateMermaid(dirs, stacks) {
   }
 
   const root = ids['Next.js'] || ids['Django'] || ids['FastAPI'] || ids['Entry Point'];
+  const pickNodeId = (...labels) => labels.map(label => ids[label]).find(Boolean) || root;
 
   // Detect layers
   if (hasAppRouter || hasPages) {
@@ -340,9 +396,9 @@ function generateMermaid(dirs, stacks) {
 
   if (hasSrcLib) {
     nodes.push(addNode('lib/', 'default'));
-    const parent = ids['API Routes'] || ids['Hooks'] || ids['Components'] || root;
+    const parent = pickNodeId('API Routes', 'Hooks', 'Components');
     edges.push(`    ${parent} --> ${ids['lib/']}`);
-  } else if (dirNames.includes('src') && !hasAppRouter && !hasPages) {
+  } else if (hasSrcNode && !hasAppRouter && !hasPages) {
     nodes.push(addNode('src/', 'default'));
     edges.push(`    ${root} --> ${ids['src/']}`);
   }
@@ -350,19 +406,19 @@ function generateMermaid(dirs, stacks) {
   if (dirNames.includes('api') || dirNames.includes('routes') || dirNames.includes('controllers')) {
     const label = dirNames.includes('api') ? 'API Layer' : 'Routes';
     nodes.push(addNode(label, 'default'));
-    const parent = ids['src/'] || ids['Entry Point'];
+    const parent = pickNodeId('src/', 'App Router', 'Pages');
     edges.push(`    ${parent} --> ${ids[label]}`);
   }
 
   if (dirNames.includes('services')) {
     nodes.push(addNode('Services', 'default'));
-    const parent = ids['API Layer'] || ids['Routes'] || ids['src/'] || ids['Entry Point'];
+    const parent = pickNodeId('API Layer', 'Routes', 'src/', 'App Router', 'Pages');
     edges.push(`    ${parent} --> ${ids['Services']}`);
   }
 
   if (dirNames.includes('models') || dirNames.includes('prisma') || dirNames.includes('db')) {
     nodes.push(addNode('Data Layer', 'default'));
-    const parent = ids['Services'] || ids['API Layer'] || ids['Routes'] || ids['src/'] || ids['Entry Point'];
+    const parent = pickNodeId('Services', 'API Layer', 'Routes', 'src/', 'App Router', 'Pages');
     edges.push(`    ${parent} --> ${ids['Data Layer']}`);
     nodes.push(addNode('Database', 'db'));
     edges.push(`    ${ids['Data Layer']} --> ${ids['Database']}`);
@@ -370,19 +426,43 @@ function generateMermaid(dirs, stacks) {
 
   if (dirNames.includes('utils') || dirNames.includes('helpers')) {
     nodes.push(addNode('Utils', 'default'));
-    const parent = ids['src/'] || ids['Services'] || ids['Entry Point'];
+    const parent = pickNodeId('src/', 'Services', 'lib/', 'Components');
     edges.push(`    ${parent} --> ${ids['Utils']}`);
   }
 
   if (dirNames.includes('middleware')) {
     nodes.push(addNode('Middleware', 'default'));
-    const parent = ids['API Layer'] || ids['Routes'] || ids['Entry Point'];
+    const parent = pickNodeId('API Layer', 'Routes', 'App Router', 'Pages');
     edges.push(`    ${parent} --> ${ids['Middleware']}`);
   }
 
+  if (hasChains) {
+    nodes.push(addNode('Chains', 'default'));
+    const parent = pickNodeId('Services', 'src/', 'lib/', 'API Layer');
+    edges.push(`    ${parent} --> ${ids['Chains']}`);
+  }
+
+  if (hasAgents) {
+    nodes.push(addNode('Agents', 'default'));
+    const parent = pickNodeId('Chains', 'Services', 'src/', 'lib/');
+    edges.push(`    ${parent} --> ${ids['Agents']}`);
+  }
+
+  if (hasWorkers) {
+    nodes.push(addNode('Workers', 'default'));
+    const parent = pickNodeId('Services', 'API Layer', 'src/');
+    edges.push(`    ${parent} --> ${ids['Workers']}`);
+  }
+
+  if (hasPipelines) {
+    nodes.push(addNode('Pipelines', 'default'));
+    const parent = pickNodeId('Services', 'Data Layer', 'src/');
+    edges.push(`    ${parent} --> ${ids['Pipelines']}`);
+  }
+
   if (dirNames.includes('tests') || dirNames.includes('test') || dirNames.includes('__tests__') || dirNames.includes('spec')) {
     nodes.push(addNode('Tests', 'round'));
-    const parent = ids['src/'] || ids['Entry Point'];
+    const parent = pickNodeId('src/', 'App Router', 'Pages', 'Services', 'Components');
     edges.push(`    ${ids['Tests']} -.-> ${parent}`);
   }
 
@@ -416,13 +496,9 @@ function getFrameworkInstructions(stacks) {
 - Use next/image for images, next/link for navigation
 - API routes go in app/api/ (App Router) or pages/api/ (Pages Router)
 - Use loading.tsx, error.tsx, and not-found.tsx for route-level UX
-
-### Next.js App Router
-- Default to Server Components. Add 'use client' only when needed (hooks, events, browser APIs)
-- Use Server Actions for mutations. Validate with Zod, call revalidatePath after writes
-- Route handlers in app/api/ export named functions: GET, POST, PUT, DELETE
-- Use loading.tsx, error.tsx, not-found.tsx for route-level UI states
-- Middleware in middleware.ts for auth checks, redirects, headers`);
+- If app/ exists, use Server Actions for mutations, validate with Zod, and call revalidatePath after writes
+- Route handlers in app/api/ should export named functions: GET, POST, PUT, DELETE
+- Middleware in middleware.ts should handle auth checks, redirects, and headers`);
   } else if (stackKeys.includes('react')) {
     sections.push(`### React
 - Use functional components with hooks exclusively
@@ -655,10 +731,10 @@ ${depGuidelines.join('\n')}
     }
     verificationSteps.push(`${verificationSteps.length + 1}. Changes match the requested scope (no gold-plating)`);
 
-    // --- Read package.json for project name/description ---
-    const pkg = ctx.jsonFile('package.json');
-    const projectName = (pkg && pkg.name) ? pkg.name : path.basename(ctx.dir);
-    const projectDesc = (pkg && pkg.description) ? ` — ${pkg.description}` : '';
+    // --- Read project metadata from package.json or pyproject.toml ---
+    const projectMeta = detectProjectMetadata(ctx);
+    const projectName = projectMeta.name;
+    const projectDesc = projectMeta.description ? ` — ${projectMeta.description}` : '';
 
     // --- Assemble the final CLAUDE.md ---
     return `# ${projectName}${projectDesc}
@@ -674,11 +750,10 @@ ${stackSection}${tsSection}${depSection}
 ${buildSection}
 \`\`\`
 
-## Code Style
-- Follow existing patterns in the codebase
-- Write tests for new features
-- Keep functions small and focused (< 50 lines)
-- Use descriptive variable names; avoid abbreviations
+## Working Notes
+- You are a careful engineer working inside this repository. Preserve its existing architecture and naming patterns unless the task requires a change
+- Prefer extending existing modules over creating parallel abstractions
+- Keep changes scoped to the requested task and verify them before marking work complete
 
 <constraints>
 - Never commit secrets, API keys, or .env files
@@ -700,12 +775,6 @@ ${verificationSteps.join('\n')}
 - If a session gets too long, start fresh with /clear
 - Use subagents for research tasks to keep main context clean
 
-## Workflow
-- Verify changes with tests before committing
-- Use descriptive commit messages (why, not what)
-- Create focused PRs — one concern per PR
-- Document non-obvious decisions in code comments
-
 ---
 *Generated by [claudex-setup](https://github.com/DnaFin/claudex-setup) v${require('../package.json').version} on ${new Date().toISOString().split('T')[0]}. Customize this file for your project — a hand-crafted CLAUDE.md will always be better than a generated one.*
 `;
@@ -758,6 +827,19 @@ mkdir -p "$LOG_DIR"
 TIMESTAMP=$(date +"%Y-%m-%d %H:%M:%S")
 echo "[$TIMESTAMP] $TOOL_NAME: $FILE_PATH" >> "$LOG_FILE"
 
+exit 0
+`,
+    'session-start.sh': `#!/bin/bash
+# SessionStart hook - prepares logs and records session entry
+
+LOG_DIR=".claude/logs"
+LOG_FILE="$LOG_DIR/sessions.log"
+
+mkdir -p "$LOG_DIR"
+
+TIMESTAMP=$(date +"%Y-%m-%d %H:%M:%S")
+echo "[$TIMESTAMP] session started" >> "$LOG_FILE"
+
 exit 0
 `,
   }),
@@ -809,6 +891,15 @@ exit 0
 1. Run \`git diff\` to see all changes
 2. Check for: bugs, security issues, missing tests, code style
 3. Provide actionable feedback
+`;
+
+    cmds['security-review.md'] = `Run a focused security review using Claude Code's built-in security workflow.
+
+## Steps:
+1. Review auth, permissions, secrets handling, and data access paths
+2. Run \`/security-review\` for OWASP-focused analysis
+3. Check for unsafe shell commands, token leakage, and risky file access
+4. Report findings ordered by severity with concrete fixes
 `;
 
     // Deploy - stack-specific
@@ -912,6 +1003,17 @@ Fix the GitHub issue: $ARGUMENTS
 3. Implement the fix
 4. Write tests
 5. Create a descriptive commit
+`,
+    'release-check/SKILL.md': `---
+name: release-check
+description: Prepare a release candidate and verify publish readiness
+---
+Prepare a release candidate for: $ARGUMENTS
+
+1. Read CHANGELOG.md and package.json version
+2. Run the test suite and packaging checks
+3. Verify docs, tags, and release notes are aligned
+4. Flag anything that would make the release unsafe or misleading
 `,
   }),
 
@@ -959,6 +1061,12 @@ Fix the GitHub issue: $ARGUMENTS
 - Never skip or disable tests without a tracking issue
 - Mock external dependencies, not internal logic
 - Include both happy path and edge case tests
+`;
+    rules['repository.md'] = `When changing release, packaging, or workflow files:
+- Keep package.json, CHANGELOG.md, README.md, and docs in sync
+- Prefer tagged release references over floating branch references in public docs
+- Preserve backward compatibility in CLI flags where practical
+- Any automation that writes files must document rollback expectations
 `;
     return rules;
   },
@@ -969,12 +1077,26 @@ name: security-reviewer
 description: Reviews code for security vulnerabilities
 tools: [Read, Grep, Glob]
 model: sonnet
+maxTurns: 50
 ---
 Review code for security issues:
 - Injection vulnerabilities (SQL, XSS, command injection)
 - Authentication and authorization flaws
 - Secrets or credentials in code
 - Insecure data handling
+`,
+    'release-manager.md': `---
+name: release-manager
+description: Checks release readiness and packaging consistency
+tools: [Read, Grep, Glob]
+model: sonnet
+maxTurns: 50
+---
+Review release readiness:
+- version alignment across package.json, changelog, and docs
+- publish safety and packaging scope
+- missing rollback or migration notes
+- documentation drift that would confuse adopters
 `,
   }),
 
@@ -992,15 +1114,24 @@ graph TD
 async function setup(options) {
   const ctx = new ProjectContext(options.dir);
   const stacks = ctx.detectStacks(STACKS);
+  const silent = options.silent === true;
+  const writtenFiles = [];
+  const preservedFiles = [];
+
+  function log(message = '') {
+    if (!silent) {
+      console.log(message);
+    }
+  }
 
-  console.log('');
-  console.log('\x1b[1m  claudex-setup\x1b[0m');
-  console.log('\x1b[2m  ═══════════════════════════════════════\x1b[0m');
+  log('');
+  log('\x1b[1m  claudex-setup\x1b[0m');
+  log('\x1b[2m  ═══════════════════════════════════════\x1b[0m');
 
   if (stacks.length > 0) {
-    console.log(`\x1b[36m  Detected: ${stacks.map(s => s.label).join(', ')}\x1b[0m`);
+    log(`\x1b[36m  Detected: ${stacks.map(s => s.label).join(', ')}\x1b[0m`);
   }
-  console.log('');
+  log('');
 
   let created = 0;
   let skipped = 0;
@@ -1038,10 +1169,12 @@ async function setup(options) {
 
       if (!fs.existsSync(fullPath)) {
         fs.writeFileSync(fullPath, result, 'utf8');
-        console.log(`  \x1b[32m✅\x1b[0m Created ${filePath}`);
+        writtenFiles.push(filePath);
+        log(`  \x1b[32m✅\x1b[0m Created ${filePath}`);
         created++;
       } else {
-        console.log(`  \x1b[2m⏭️  Skipped ${filePath} (already exists — your version is kept)\x1b[0m`);
+        preservedFiles.push(filePath);
+        log(`  \x1b[2m⏭️  Skipped ${filePath} (already exists — your version is kept)\x1b[0m`);
         skipped++;
       }
     } else if (typeof result === 'object') {
@@ -1068,9 +1201,11 @@ async function setup(options) {
         }
         if (!fs.existsSync(filePath)) {
           fs.writeFileSync(filePath, content, 'utf8');
-          console.log(`  \x1b[32m✅\x1b[0m Created ${path.relative(options.dir, filePath)}`);
+          writtenFiles.push(path.relative(options.dir, filePath));
+          log(`  \x1b[32m✅\x1b[0m Created ${path.relative(options.dir, filePath)}`);
           created++;
         } else {
+          preservedFiles.push(path.relative(options.dir, filePath));
           skipped++;
         }
       }
@@ -1083,50 +1218,41 @@ async function setup(options) {
   if (fs.existsSync(hooksDir) && !fs.existsSync(settingsPath)) {
     const hookFiles = fs.readdirSync(hooksDir).filter(f => f.endsWith('.sh'));
     if (hookFiles.length > 0) {
-      const settings = {
-        hooks: {
-          PostToolUse: [{
-            matcher: "Write|Edit",
-            hooks: hookFiles.filter(f => f !== 'protect-secrets.sh').map(f => ({
-              type: "command",
-              command: `bash .claude/hooks/${f}`,
-              timeout: 10
-            }))
-          }]
-        }
-      };
-      // Add protect-secrets as PreToolUse if it exists
-      if (hookFiles.includes('protect-secrets.sh')) {
-        settings.hooks.PreToolUse = [{
-          matcher: "Read|Write|Edit",
-          hooks: [{
-            type: "command",
-            command: "bash .claude/hooks/protect-secrets.sh",
-            timeout: 5
-          }]
-        }];
-      }
+      const settings = buildSettingsForProfile({
+        profileKey: options.profile || 'safe-write',
+        hookFiles,
+        mcpPackKeys: options.mcpPacks || [],
+      });
       fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
-      console.log(`  \x1b[32m✅\x1b[0m Created .claude/settings.json (hooks registered)`);
+      writtenFiles.push('.claude/settings.json');
+      log(`  \x1b[32m✅\x1b[0m Created .claude/settings.json (hooks registered)`);
       created++;
     }
   }
 
-  console.log('');
+  log('');
   if (created === 0 && skipped > 0) {
-    console.log('  \x1b[32m✅\x1b[0m Your project is already well configured!');
-    console.log(`  \x1b[2m  ${skipped} files already exist and were preserved.\x1b[0m`);
-    console.log('  \x1b[2m  We never overwrite your existing config — your setup is kept.\x1b[0m');
+    log('  \x1b[32m✅\x1b[0m Your project is already well configured!');
+    log(`  \x1b[2m  ${skipped} files already exist and were preserved.\x1b[0m`);
+    log('  \x1b[2m  We never overwrite your existing config — your setup is kept.\x1b[0m');
   } else if (created > 0) {
-    console.log(`  \x1b[1m${created} files created.\x1b[0m`);
+    log(`  \x1b[1m${created} files created.\x1b[0m`);
     if (skipped > 0) {
-      console.log(`  \x1b[2m${skipped} existing files preserved (not overwritten).\x1b[0m`);
+      log(`  \x1b[2m${skipped} existing files preserved (not overwritten).\x1b[0m`);
     }
   }
 
-  console.log('');
-  console.log('  Run \x1b[1mnpx claudex-setup audit\x1b[0m to check your score.');
-  console.log('');
+  log('');
+  log('  Run \x1b[1mnpx claudex-setup audit\x1b[0m to check your score.');
+  log('');
+
+  return {
+    created,
+    skipped,
+    writtenFiles,
+    preservedFiles,
+    stacks,
+  };
 }
 
-module.exports = { setup };
+module.exports = { setup, TEMPLATES };

package/src/techniques.js

@@ -4,6 +4,12 @@
  * Each technique includes: what to check, how to fix, impact level.
  */
 
+function hasFrontendSignals(ctx) {
+  const pkg = ctx.fileContent('package.json') || '';
+  return /react|vue|angular|next|svelte|tailwind|vite|astro/i.test(pkg) ||
+    ctx.files.some(f => /tailwind\.config|vite\.config|next\.config|svelte\.config|nuxt\.config|pages\/|components\/|app\//i.test(f));
+}
+
 const TECHNIQUES = {
   // ============================================================
   // === MEMORY & CONTEXT (category: 'memory') ==================
@@ -142,8 +148,13 @@ const TECHNIQUES = {
     name: '.claude/ tracked in git',
     check: (ctx) => {
       if (!ctx.fileContent('.gitignore')) return true; // no gitignore = ok
-      const content = ctx.fileContent('.gitignore');
-      return !content.includes('.claude/') || content.includes('!.claude/');
+      const lines = ctx.fileContent('.gitignore')
+        .split(/\r?\n/)
+        .map(line => line.trim())
+        .filter(line => line && !line.startsWith('#'));
+      const ignoresClaudeDir = lines.some(line => /^(\/|\*\*\/)?\.claude\/?$/.test(line));
+      const unignoresClaudeDir = lines.some(line => /^!(\/)?\.claude(\/|\*\*)?$/.test(line));
+      return !ignoresClaudeDir || unignoresClaudeDir;
     },
     impact: 'high',
     rating: 4,
@@ -170,6 +181,10 @@ const TECHNIQUES = {
     id: 91701,
     name: '.gitignore blocks node_modules',
     check: (ctx) => {
+      const hasNodeSignals = ctx.files.includes('package.json') ||
+        ctx.files.includes('tsconfig.json') ||
+        ctx.files.some(f => /package-lock\.json|pnpm-lock\.yaml|yarn\.lock|next\.config|vite\.config/i.test(f));
+      if (!hasNodeSignals) return null;
       const gitignore = ctx.fileContent('.gitignore') || '';
       return gitignore.includes('node_modules');
     },
@@ -314,7 +329,7 @@ const TECHNIQUES = {
     name: 'Permission configuration',
     check: (ctx) => {
       const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
-      return settings && settings.permissions;
+      return !!(settings && settings.permissions);
     },
     impact: 'medium',
     rating: 4,
@@ -467,6 +482,7 @@ const TECHNIQUES = {
     id: 1025,
     name: 'Frontend design skill for anti-AI-slop',
     check: (ctx) => {
+      if (!hasFrontendSignals(ctx)) return null;
       const md = ctx.fileContent('CLAUDE.md') || '';
       return md.includes('frontend_aesthetics') || md.includes('anti-AI-slop') || md.includes('frontend-design');
     },
@@ -481,6 +497,7 @@ const TECHNIQUES = {
     id: 102501,
     name: 'Tailwind CSS configured',
     check: (ctx) => {
+      if (!hasFrontendSignals(ctx)) return null;
       const pkg = ctx.fileContent('package.json') || '';
       return pkg.includes('tailwind') ||
         ctx.files.some(f => /tailwind\.config/.test(f));
@@ -603,9 +620,13 @@ const TECHNIQUES = {
     id: 5002,
     name: 'Node version pinned',
     check: (ctx) => {
+      const hasNodeSignals = ctx.files.includes('package.json') ||
+        ctx.files.includes('tsconfig.json') ||
+        ctx.files.some(f => /package-lock\.json|pnpm-lock\.yaml|yarn\.lock|next\.config|vite\.config/i.test(f));
+      if (!hasNodeSignals) return null;
       if (ctx.files.includes('.nvmrc') || ctx.files.includes('.node-version')) return true;
       const pkg = ctx.jsonFile('package.json');
-      return pkg && pkg.engines && pkg.engines.node;
+      return !!(pkg && pkg.engines && pkg.engines.node);
     },
     impact: 'low',
     rating: 3,
@@ -655,7 +676,7 @@ const TECHNIQUES = {
     name: 'MCP servers configured',
     check: (ctx) => {
       const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
-      return settings && settings.mcpServers && Object.keys(settings.mcpServers).length > 0;
+      return !!(settings && settings.mcpServers && Object.keys(settings.mcpServers).length > 0);
     },
     impact: 'medium',
     rating: 3,
@@ -669,7 +690,7 @@ const TECHNIQUES = {
     name: '2+ MCP servers for rich tooling',
     check: (ctx) => {
       const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
-      return settings && settings.mcpServers && Object.keys(settings.mcpServers).length >= 2;
+      return !!(settings && settings.mcpServers && Object.keys(settings.mcpServers).length >= 2);
     },
     impact: 'medium',
     rating: 4,