@nerviq/cli 1.4.1 → 1.5.1

package/README.md

@@ -1,28 +1,27 @@
 # Nerviq
 
-> The intelligent nervous system for AI coding agents — audit, align, and amplify every platform on every project.
+> Standardize and govern your AI coding agent setup — score, fix, and align across 8 platforms.
 
 [![npm version](https://img.shields.io/npm/v/@nerviq/cli)](https://www.npmjs.com/package/@nerviq/cli)
 [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)
-[![Checks: 2039](https://img.shields.io/badge/checks-2039-brightgreen)](https://github.com/nerviq/nerviq)
-[![Nerviq Certified Gold](https://img.shields.io/badge/Nerviq-Nerviq%20Certified%20Gold-gold)](https://nerviq.net)
+[![Checks: 2431](https://img.shields.io/badge/checks-2431-brightgreen)](https://github.com/nerviq/nerviq)
 
 ---
 
 ### 8 Platforms Supported
 
-Nerviq v1.0 ships with full audit, setup, governance, and benchmark support for **8 AI coding platforms**:
+Nerviq audits, sets up, and governs AI coding agent configurations for **8 platforms**:
 
 | Platform | Checks | Status |
 |----------|--------|--------|
-| Claude Code | 309 | Full |
-| Codex (OpenAI) | 225 | Full |
-| Gemini CLI (Google) | 219 | Full |
-| GitHub Copilot | 218 | Full |
-| Cursor | 267 | Full |
-| Windsurf | 265 | Full |
-| Aider | 249 | Full |
-| OpenCode | 251 | Full |
+| Claude Code | 393 | Full |
+| Codex (OpenAI) | 272 | Full |
+| Gemini CLI (Google) | 300 | Full |
+| GitHub Copilot | 299 | Full |
+| Cursor | 301 | Full |
+| Windsurf | 297 | Full |
+| Aider | 283 | Full |
+| OpenCode | 286 | Full |
 
 ### 10 Stack-Specific Languages
 
@@ -78,7 +77,15 @@ npx @nerviq/cli benchmark          # Before/after in isolated copy
 
 No install required. Zero dependencies.
 
-## 2,039 Checks Across 96 Categories
+## Get Started by Role
+
+| You are a... | Start here | Then |
+|--------------|------------|------|
+| **Solo developer** | `nerviq audit` → `nerviq augment` | `nerviq benchmark` |
+| **Team lead / DevEx** | `nerviq governance` → `nerviq audit --json` | CI threshold + `nerviq watch` |
+| **Enterprise / Platform** | `nerviq harmony-audit` → `nerviq harmony-drift` | Policy packs + `nerviq certify` |
+
+## 2,431 Checks Across 96 Categories
 
 | Category Group | Checks | Examples |
 |----------------|--------|---------|
@@ -217,7 +224,7 @@ Levels:
 
 | Command | What it does |
 |---------|-------------|
-| `nerviq audit` | Score 0-100 against 2,039 checks |
+| `nerviq audit` | Score 0-100 against 2,431 checks |
 | `nerviq audit --lite` | Quick top-3 scan |
 | `nerviq setup` | Generate starter-safe CLAUDE.md + hooks + commands |
 | `nerviq augment` | Repo-aware improvement plan (no writes) |
@@ -270,7 +277,7 @@ Nerviq is built on the CLAUDEX knowledge engine — the largest verified catalog
 
 - **448+ research documents** covering all 8 platforms
 - **332+ experiments** with tested, rated results
-- **2,039 checks** across 8 platforms and 10 languages, each with `sourceUrl` and `confidence` level (0.0-1.0)
+- **2,431 checks** across 8 platforms and 10 languages, each with `sourceUrl` and `confidence` level (0.0-1.0)
 - Every check is traceable to primary documentation or verified experiment
 - 90-day freshness cycle: stale findings are re-verified or pruned
 
@@ -287,6 +294,14 @@ Nerviq is built on the CLAUDEX knowledge engine — the largest verified catalog
 - **GitHub**: [github.com/nerviq/nerviq](https://github.com/nerviq/nerviq)
 - **Website**: [nerviq.net](https://nerviq.net)
 
+## What Nerviq Is — and Isn't
+
+**Strongest at:** Agent configuration, workflow governance, repo policy hygiene, cross-platform alignment, and setup standardization.
+
+**Not a replacement for:** Deep architectural review of business logic, runtime performance profiling, or security penetration testing. Nerviq focuses on how your AI coding agents are configured and governed — not on what your application code does.
+
+**Confidence levels:** Every check includes a `confidence` score (0.0–1.0) and a `sourceUrl` linking to primary documentation. Checks marked `heuristic` are pattern-based and may produce false positives on non-standard project structures.
+
 ## Previously claudex-setup
 
 Nerviq was previously published as `claudex-setup`. If you were using it:

package/bin/cli.js

@@ -11,6 +11,8 @@ const { collectFeedback } = require('../src/feedback');
 const { startServer } = require('../src/server');
 const { auditWorkspaces } = require('../src/workspace');
 const { scanOrg } = require('../src/org');
+const { detectAntiPatterns, printAntiPatterns, printAntiPatternCatalog } = require('../src/anti-patterns');
+const { VERIFICATION_DATES, getVerificationDate, getVerificationStats } = require('../src/verification-metadata');
 const { version } = require('../package.json');
 
 const args = process.argv.slice(2);
@@ -24,7 +26,7 @@ const COMMAND_ALIASES = {
   gov: 'governance',
   outcome: 'feedback',
 };
-const KNOWN_COMMANDS = ['audit', 'org', 'setup', 'augment', 'suggest-only', 'plan', 'apply', 'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'badge', 'insights', 'history', 'compare', 'trend', 'scan', 'feedback', 'doctor', 'convert', 'migrate', 'catalog', 'certify', 'serve', 'harmony-audit', 'harmony-sync', 'harmony-drift', 'harmony-advise', 'harmony-watch', 'harmony-governance', 'harmony-add', 'synergy-report', 'help', 'version'];
+const KNOWN_COMMANDS = ['audit', 'org', 'setup', 'augment', 'suggest-only', 'plan', 'apply', 'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'badge', 'insights', 'history', 'compare', 'trend', 'scan', 'feedback', 'doctor', 'convert', 'migrate', 'catalog', 'certify', 'serve', 'harmony-audit', 'harmony-sync', 'harmony-drift', 'harmony-advise', 'harmony-watch', 'harmony-governance', 'harmony-add', 'synergy-report', 'anti-patterns', 'rules-export', 'freshness', 'help', 'version'];
 
 function levenshtein(a, b) {
   const matrix = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
@@ -85,11 +87,12 @@ function parseArgs(rawArgs) {
   let migrateFrom = null;
   let migrateTo = null;
   let checkVersion = null;
+  let external = null;
 
   for (let i = 0; i < rawArgs.length; i++) {
     const arg = rawArgs[i];
 
-    if (arg === '--threshold' || arg === '--out' || arg === '--plan' || arg === '--only' || arg === '--profile' || arg === '--mcp-pack' || arg === '--require' || arg === '--key' || arg === '--status' || arg === '--effect' || arg === '--notes' || arg === '--source' || arg === '--score-delta' || arg === '--platform' || arg === '--format' || arg === '--from' || arg === '--to' || arg === '--port' || arg === '--workspace' || arg === '--check-version' || arg === '--webhook') {
+    if (arg === '--threshold' || arg === '--out' || arg === '--plan' || arg === '--only' || arg === '--profile' || arg === '--mcp-pack' || arg === '--require' || arg === '--key' || arg === '--status' || arg === '--effect' || arg === '--notes' || arg === '--source' || arg === '--score-delta' || arg === '--platform' || arg === '--format' || arg === '--from' || arg === '--to' || arg === '--port' || arg === '--workspace' || arg === '--check-version' || arg === '--webhook' || arg === '--external') {
       const value = rawArgs[i + 1];
       if (!value || value.startsWith('--')) {
         throw new Error(`${arg} requires a value`);
@@ -115,10 +118,16 @@ function parseArgs(rawArgs) {
       if (arg === '--workspace') workspace = value.trim();
       if (arg === '--check-version') checkVersion = value.trim();
       if (arg === '--webhook') webhookUrl = value.trim();
+      if (arg === '--external') external = value.trim();
       i++;
       continue;
     }
 
+    if (arg.startsWith('--external=')) {
+      external = arg.split('=').slice(1).join('=').trim();
+      continue;
+    }
+
     if (arg.startsWith('--require=')) {
       requireChecks = arg.split('=').slice(1).join('=').split(',').map(item => item.trim()).filter(Boolean);
       continue;
@@ -224,7 +233,7 @@ function parseArgs(rawArgs) {
 
   const normalizedCommand = COMMAND_ALIASES[command] || command;
 
-  return { flags, command, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks, requireChecks, feedbackKey, feedbackStatus, feedbackEffect, feedbackNotes, feedbackSource, feedbackScoreDelta, platform, format, port, workspace, extraArgs, convertFrom, convertTo, migrateFrom, migrateTo, checkVersion, webhookUrl };
+  return { flags, command, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks, requireChecks, feedbackKey, feedbackStatus, feedbackEffect, feedbackNotes, feedbackSource, feedbackScoreDelta, platform, format, port, workspace, extraArgs, convertFrom, convertTo, migrateFrom, migrateTo, checkVersion, webhookUrl, external };
 }
 
 function printWorkspaceSummary(summary, options) {
@@ -289,6 +298,8 @@ const HELP = `
     nerviq org scan dir1 dir2     Aggregate multiple repos into one score table
     nerviq catalog                Full check catalog (all 8 platforms)
     nerviq catalog --json         Export full check catalog as JSON
+    nerviq anti-patterns          Detect anti-patterns in current project
+    nerviq anti-patterns --all    Show full anti-pattern catalog
 
   SETUP
     nerviq setup                  Generate starter-safe baseline config files
@@ -308,6 +319,8 @@ const HELP = `
     nerviq governance             Permission profiles + hooks + policy packs
     nerviq governance --json      Machine-readable governance summary
     nerviq benchmark              Before/after score in isolated temp copy
+    nerviq benchmark --external /path  Benchmark an external repo
+    nerviq freshness              Show verification freshness for all checks
     nerviq certify                Generate certification badge for your project
 
   CROSS-PLATFORM
@@ -333,6 +346,8 @@ const HELP = `
     nerviq deep-review            AI-powered config review (opt-in, uses API key)
     nerviq serve --port 3000      Start local Nerviq REST API server
     nerviq badge                  Generate shields.io badge markdown
+    nerviq rules-export           Export recommendation rules as JSON
+    nerviq rules-export --out F   Save rules to file
 
   OPTIONS
     --platform NAME   Platform: claude (default), codex, cursor, copilot, gemini, windsurf, aider, opencode
@@ -346,6 +361,7 @@ const HELP = `
     --check-version V Pin catalog to a specific version (warn on mismatch)
     --format NAME     Output format: json | sarif | otel
     --webhook URL     Send audit results to a webhook (Slack/Discord/generic JSON)
+    --external PATH   Benchmark an external repo instead of cwd
     --port N          Port for \`serve\` (default: 3000)
     --workspace GLOBS Audit workspaces separately (e.g. packages/* or apps/web,apps/api)
     --snapshot        Save snapshot artifact under .claude/nerviq/snapshots/
@@ -427,6 +443,7 @@ async function main() {
     port: parsed.port !== null ? Number(parsed.port) : null,
     workspace: parsed.workspace || null,
     webhookUrl: parsed.webhookUrl || null,
+    external: parsed.external || null,
     dir: process.cwd()
   };
 
@@ -507,7 +524,8 @@ async function main() {
       'history', 'compare', 'trend', 'feedback', 'catalog', 'certify', 'serve', 'help', 'version',
       // Harmony + Synergy (cross-platform)
       'harmony-audit', 'harmony-sync', 'harmony-drift', 'harmony-advise',
-      'harmony-watch', 'harmony-governance', 'harmony-add', 'synergy-report',
+      'harmony-watch', 'harmony-governance', 'harmony-add', 'synergy-report', 'anti-patterns', 'rules-export',
+      'freshness',
     ]);
 
     if (options.platform === 'codex') {
@@ -987,6 +1005,70 @@ async function main() {
         process.exit(1);
       }
       process.exit(0);
+    } else if (normalizedCommand === 'anti-patterns') {
+      const showAll = flags.includes('--all');
+      if (showAll) {
+        printAntiPatternCatalog(options);
+      } else {
+        const { ProjectContext } = require('../src/context');
+        const ctx = new ProjectContext(options.dir);
+        const detected = detectAntiPatterns(ctx);
+        printAntiPatterns(detected, options);
+      }
+      process.exit(0);
+    } else if (normalizedCommand === 'rules-export') {
+      const { generateRecommendationRules } = require('../src/recommendation-rules');
+      const rules = generateRecommendationRules();
+      const output = JSON.stringify(rules, null, 2);
+      if (options.out) {
+        require('fs').writeFileSync(options.out, output, 'utf8');
+        if (!options.json) {
+          console.log(`\n  Rules exported to ${options.out} (${rules.totalRules} rules)\n`);
+        } else {
+          console.log(output);
+        }
+      } else {
+        console.log(output);
+      }
+      process.exit(0);
+    } else if (normalizedCommand === 'freshness') {
+      const { TECHNIQUES } = require('../src/techniques');
+      const stats = getVerificationStats();
+      const allKeys = Object.keys(TECHNIQUES);
+      const verifiedKeys = Object.keys(VERIFICATION_DATES);
+      const neverVerified = allKeys.filter(k => !VERIFICATION_DATES[k]);
+
+      if (options.json) {
+        console.log(JSON.stringify({
+          totalChecks: allKeys.length,
+          verifiedChecks: verifiedKeys.length,
+          neverVerifiedCount: neverVerified.length,
+          newestVerification: stats.newest,
+          oldestVerification: stats.oldest,
+          neverVerified,
+        }, null, 2));
+      } else {
+        console.log('');
+        console.log('  nerviq freshness');
+        console.log('  ═══════════════════════════════════════');
+        console.log(`  Total checks:            ${allKeys.length}`);
+        console.log(`  With verification date:  ${verifiedKeys.length}`);
+        console.log(`  Never verified:          ${neverVerified.length}`);
+        console.log(`  Newest verification:     ${stats.newest}`);
+        console.log(`  Oldest verification:     ${stats.oldest}`);
+        console.log('');
+        if (neverVerified.length > 0 && options.verbose) {
+          console.log('  Never verified:');
+          for (const key of neverVerified) {
+            console.log(`    - ${key}`);
+          }
+          console.log('');
+        } else if (neverVerified.length > 0) {
+          console.log(`  Use --verbose to list all ${neverVerified.length} never-verified checks.`);
+          console.log('');
+        }
+      }
+      process.exit(0);
     } else if (normalizedCommand === 'synergy-report') {
       // Placeholder — synergy report is referenced but may not be implemented yet
       console.log('\n  Synergy report: coming soon.\n');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nerviq/cli",
-  "version": "1.4.1",
-  "description": "The intelligent nervous system for AI coding agents — 2,039 checks across 8 platforms, 10 languages, and 62 domain packs. Audit, align, and amplify.",
+  "version": "1.5.1",
+  "description": "The intelligent nervous system for AI coding agents — 2,431 checks across 8 platforms, 10 languages, and 62 domain packs. Audit, align, and amplify.",
   "main": "src/index.js",
   "bin": {
     "nerviq": "bin/cli.js",

package/src/analyze.js

@@ -296,15 +296,16 @@ const STRENGTH_REASONS = {
 
 function toStrengths(results) {
   return results
-    .filter(r => r.passed === true)
+    .filter(r => r.passed === true && (r.impact === 'critical' || r.impact === 'high' || r.impact === 'medium'))
     .sort((a, b) => {
       const order = { critical: 3, high: 2, medium: 1, low: 0 };
       return (order[b.impact] || 0) - (order[a.impact] || 0);
     })
-    .slice(0, 8)
+    .slice(0, 10)
     .map(r => ({
       key: r.key,
       name: r.name,
+      impact: r.impact,
       category: r.category,
       why: STRENGTH_REASONS[r.key] || `Already configured and working: ${r.name}.`,
     }));
@@ -604,12 +605,10 @@ function printAnalysis(report, options = {}) {
   console.log('');
 
   if (report.strengthsPreserved.length > 0) {
-    console.log(c('  Strengths Preserved', 'green'));
+    console.log(c(`  ${'\u2705'} Strengths Preserved (don't change these)`, 'green'));
     for (const item of report.strengthsPreserved) {
-      console.log(`  ${c('✓', 'green')} ${item.name}`);
-      if (item.why) {
-        console.log(c(`    ${item.why}`, 'dim'));
-      }
+      const impactLabel = item.impact ? ` (${item.impact})` : '';
+      console.log(`     ${c('\u2022', 'green')} ${item.name}${c(impactLabel, 'dim')}`);
     }
     console.log('');
   }
@@ -730,10 +729,11 @@ function exportMarkdown(report) {
   lines.push('');
 
   if (report.strengthsPreserved.length > 0) {
-    lines.push('## Strengths Preserved');
+    lines.push('## Strengths Preserved (don\'t change these)');
     lines.push('');
     for (const item of report.strengthsPreserved) {
-      lines.push(`- **${item.name}** — ${item.why || 'Already configured.'}`);
+      const impactLabel = item.impact ? ` (${item.impact})` : '';
+      lines.push(`- **${item.name}**${impactLabel} — ${item.why || 'Already configured.'}`);
     }
     lines.push('');
   }

package/src/anti-patterns.js

@@ -0,0 +1,468 @@
+/**
+ * Anti-Pattern Catalog — things NOT to do when configuring AI coding agents.
+ * Provides a static catalog and a runtime detector that checks a project context.
+ */
+
+const path = require('path');
+
+const ANTI_PATTERNS = [
+  {
+    id: 'AP001',
+    name: 'bypassPermissions as default',
+    severity: 'critical',
+    description: 'Setting defaultMode to bypassPermissions removes all safety guardrails.',
+    platforms: ['claude'],
+    fix: 'Use "default" or "safe-write" mode. Add specific allow rules for trusted operations.',
+    detect: (ctx) => {
+      const settings = ctx.jsonFile('.claude/settings.json') || ctx.jsonFile('.claude/settings.local.json');
+      return settings && settings.permissions && settings.permissions.defaultMode === 'bypassPermissions';
+    },
+  },
+  {
+    id: 'AP002',
+    name: 'No deny rules configured',
+    severity: 'high',
+    description: 'Without deny rules, the agent can execute any operation it decides to, including destructive ones.',
+    platforms: ['claude'],
+    fix: 'Add deny rules in settings.json for dangerous operations like rm -rf, git reset --hard, and reading .env files.',
+    detect: (ctx) => {
+      const settings = ctx.jsonFile('.claude/settings.json') || ctx.jsonFile('.claude/settings.local.json');
+      if (!settings || !settings.permissions) return true;
+      return !Array.isArray(settings.permissions.deny) || settings.permissions.deny.length === 0;
+    },
+  },
+  {
+    id: 'AP003',
+    name: 'Secrets in CLAUDE.md',
+    severity: 'critical',
+    description: 'API keys, tokens, or passwords hardcoded in CLAUDE.md are visible to every session and may leak in outputs.',
+    platforms: ['claude', 'codex', 'cursor', 'windsurf', 'copilot', 'gemini', 'aider', 'opencode'],
+    fix: 'Move secrets to .env files and reference them via environment variables. Add .env to .gitignore.',
+    detect: (ctx) => {
+      const content = ctx.fileContent('CLAUDE.md') || ctx.fileContent('.claude/CLAUDE.md') || '';
+      const patterns = [
+        /(?:api[_-]?key|api[_-]?secret|token|password|secret[_-]?key)\s*[:=]\s*['"]?[A-Za-z0-9_\-]{16,}/i,
+        /sk-[A-Za-z0-9]{20,}/,
+        /ghp_[A-Za-z0-9]{36,}/,
+        /AKIA[A-Z0-9]{16}/,
+      ];
+      return patterns.some(p => p.test(content));
+    },
+  },
+  {
+    id: 'AP004',
+    name: 'Empty CLAUDE.md',
+    severity: 'medium',
+    description: 'An empty or near-empty instruction file provides no guidance, making the agent guess at project conventions.',
+    platforms: ['claude'],
+    fix: 'Add project description, architecture overview, verification commands, and coding conventions to CLAUDE.md.',
+    detect: (ctx) => {
+      const content = ctx.fileContent('CLAUDE.md') || ctx.fileContent('.claude/CLAUDE.md') || '';
+      return content.trim().length > 0 && content.trim().length < 50;
+    },
+  },
+  {
+    id: 'AP005',
+    name: 'Too many MCP servers (>10)',
+    severity: 'medium',
+    description: 'More than 10 MCP servers increases startup latency, context overhead, and potential for tool conflicts.',
+    platforms: ['claude'],
+    fix: 'Limit MCP servers to essential ones. Remove rarely-used servers and consolidate overlapping functionality.',
+    detect: (ctx) => {
+      const settings = ctx.jsonFile('.claude/settings.json') || ctx.jsonFile('.claude/settings.local.json');
+      if (!settings || !settings.mcpServers) return false;
+      return Object.keys(settings.mcpServers).length > 10;
+    },
+  },
+  {
+    id: 'AP006',
+    name: 'Overly broad allow rules',
+    severity: 'high',
+    description: 'Allow rules like "Bash(*)" or "Write(**)" grant blanket permission, defeating the purpose of permission controls.',
+    platforms: ['claude'],
+    fix: 'Scope allow rules to specific commands and paths. Use "Bash(npm test)" instead of "Bash(*)".',
+    detect: (ctx) => {
+      const settings = ctx.jsonFile('.claude/settings.json') || ctx.jsonFile('.claude/settings.local.json');
+      if (!settings || !settings.permissions) return false;
+      const allow = settings.permissions.allow || [];
+      const broadPatterns = ['Bash(*)', 'Write(**)', 'Edit(**)', 'Read(**)', 'Bash(**)', 'Write(*)', 'Edit(*)', 'Read(*)'];
+      return allow.some(rule => broadPatterns.includes(rule));
+    },
+  },
+  {
+    id: 'AP007',
+    name: 'No verification commands',
+    severity: 'medium',
+    description: 'Without test, lint, or build commands in CLAUDE.md, the agent cannot self-verify its changes.',
+    platforms: ['claude', 'codex', 'cursor', 'windsurf', 'copilot', 'gemini', 'aider', 'opencode'],
+    fix: 'Add ## Verification Commands section with test, lint, and build commands to your instruction file.',
+    detect: (ctx) => {
+      const content = ctx.fileContent('CLAUDE.md') || ctx.fileContent('.claude/CLAUDE.md') || '';
+      if (!content) return false;
+      const hasVerification = /\b(test|lint|build|check|verify)\b/i.test(content) &&
+        /\b(npm |yarn |pnpm |pytest|cargo |go |make )/i.test(content);
+      return !hasVerification;
+    },
+  },
+  {
+    id: 'AP008',
+    name: 'Ignoring .gitignore for sensitive files',
+    severity: 'high',
+    description: 'Not gitignoring .env, credentials, and key files means they can be committed and pushed to remote repos.',
+    platforms: ['claude', 'codex', 'cursor', 'windsurf', 'copilot', 'gemini', 'aider', 'opencode'],
+    fix: 'Add .env, .env.*, credentials.json, *.pem, and *.key to .gitignore.',
+    detect: (ctx) => {
+      const gitignore = ctx.fileContent('.gitignore') || '';
+      return !gitignore.includes('.env');
+    },
+  },
+  {
+    id: 'AP009',
+    name: 'No hooks configured',
+    severity: 'medium',
+    description: 'Without hooks, there is no automated enforcement — all safety depends on instructions alone (80% compliance vs 100%).',
+    platforms: ['claude'],
+    fix: 'Add at least a protect-secrets PreToolUse hook and a post-edit lint hook in settings.json.',
+    detect: (ctx) => {
+      const settings = ctx.jsonFile('.claude/settings.json') || ctx.jsonFile('.claude/settings.local.json');
+      if (!settings || !settings.hooks) return true;
+      const hookEntries = Object.values(settings.hooks).flat();
+      return hookEntries.length === 0;
+    },
+  },
+  {
+    id: 'AP010',
+    name: 'Duplicated instructions across platforms',
+    severity: 'medium',
+    description: 'Copy-pasting the same instructions into CLAUDE.md, .cursorrules, and AGENTS.md creates drift when one is updated.',
+    platforms: ['claude', 'codex', 'cursor', 'windsurf', 'copilot', 'gemini', 'aider', 'opencode'],
+    fix: 'Create a shared source of truth (e.g., docs/ai-instructions.md) and reference it from each platform config.',
+    detect: (ctx) => {
+      const claudeMd = ctx.fileContent('CLAUDE.md') || '';
+      const cursorrules = ctx.fileContent('.cursorrules') || '';
+      const agentsMd = ctx.fileContent('AGENTS.md') || '';
+      if (!claudeMd || claudeMd.length < 100) return false;
+      const files = [cursorrules, agentsMd].filter(f => f.length > 100);
+      if (files.length === 0) return false;
+      // Simple heuristic: check if any significant chunk (100+ chars) appears in both
+      const chunk = claudeMd.slice(0, 200).trim();
+      return files.some(f => f.includes(chunk));
+    },
+  },
+  {
+    id: 'AP011',
+    name: 'Conflicting trust postures across platforms',
+    severity: 'high',
+    description: 'One platform in bypassPermissions while another is read-only creates inconsistent security boundaries.',
+    platforms: ['claude', 'codex'],
+    fix: 'Align permission profiles across platforms. Use Harmony audit to detect and resolve trust drift.',
+    detect: (ctx) => {
+      const claudeSettings = ctx.jsonFile('.claude/settings.json') || ctx.jsonFile('.claude/settings.local.json');
+      const codexConfig = ctx.fileContent('.codex/config.toml') || '';
+      if (!claudeSettings || !codexConfig) return false;
+      const claudeMode = claudeSettings.permissions && claudeSettings.permissions.defaultMode;
+      const isBypass = claudeMode === 'bypassPermissions';
+      const codexHasAutoApprove = /approval_policy\s*=\s*["']auto-edit["']/i.test(codexConfig);
+      // Conflict: one is very permissive while the other is restrictive, or vice versa
+      return (isBypass && !codexHasAutoApprove) || (!isBypass && codexHasAutoApprove);
+    },
+  },
+  {
+    id: 'AP012',
+    name: 'No error handling in hooks',
+    severity: 'medium',
+    description: 'Hook scripts without error handling can silently fail, giving a false sense of security.',
+    platforms: ['claude'],
+    fix: 'Add "set -e" to shell hooks and wrap commands in try/catch for JS hooks. Log failures to a known location.',
+    detect: (ctx) => {
+      if (!ctx.hasDir('.claude/hooks')) return false;
+      const hookFiles = ctx.dirFiles('.claude/hooks');
+      for (const file of hookFiles) {
+        const content = ctx.fileContent(`.claude/hooks/${file}`) || '';
+        if (file.endsWith('.sh') && content.length > 0 && !content.includes('set -e')) {
+          return true;
+        }
+      }
+      return false;
+    },
+  },
+  {
+    id: 'AP013',
+    name: 'Hardcoded paths in CLAUDE.md',
+    severity: 'medium',
+    description: 'Absolute paths like /Users/alice/project or C:\\Users break when other developers clone the repo.',
+    platforms: ['claude', 'codex', 'cursor', 'windsurf', 'copilot', 'gemini', 'aider', 'opencode'],
+    fix: 'Use relative paths or environment variables. Replace absolute paths with project-relative references.',
+    detect: (ctx) => {
+      const content = ctx.fileContent('CLAUDE.md') || ctx.fileContent('.claude/CLAUDE.md') || '';
+      if (!content) return false;
+      return /(?:\/Users\/[a-zA-Z]|\/home\/[a-zA-Z]|C:\\Users\\[a-zA-Z])/.test(content);
+    },
+  },
+  {
+    id: 'AP014',
+    name: 'No test command defined',
+    severity: 'medium',
+    description: 'Without a test command, the agent cannot verify its changes work before presenting them for review.',
+    platforms: ['claude', 'codex', 'cursor', 'windsurf', 'copilot', 'gemini', 'aider', 'opencode'],
+    fix: 'Add a test command in your instruction file, e.g., "Test: npm test" or "Test: pytest".',
+    detect: (ctx) => {
+      const content = ctx.fileContent('CLAUDE.md') || ctx.fileContent('.claude/CLAUDE.md') || '';
+      const pkg = ctx.jsonFile('package.json');
+      const hasTestInMd = /(?:test|testing)\s*(?:command)?[:\s]+[`"']*(?:npm|yarn|pnpm|pytest|cargo|go|make)\s/i.test(content);
+      const hasTestScript = pkg && pkg.scripts && pkg.scripts.test;
+      return !hasTestInMd && !hasTestScript;
+    },
+  },
+  {
+    id: 'AP015',
+    name: 'All permissions allowed',
+    severity: 'high',
+    description: 'Allowing all tool permissions without any deny rules gives the agent unrestricted system access.',
+    platforms: ['claude'],
+    fix: 'Define deny rules for destructive operations. At minimum deny rm -rf, git reset --hard, and .env reads.',
+    detect: (ctx) => {
+      const settings = ctx.jsonFile('.claude/settings.json') || ctx.jsonFile('.claude/settings.local.json');
+      if (!settings || !settings.permissions) return false;
+      const allow = settings.permissions.allow || [];
+      const deny = settings.permissions.deny || [];
+      return allow.length > 5 && deny.length === 0;
+    },
+  },
+  {
+    id: 'AP016',
+    name: 'Missing architecture diagram',
+    severity: 'low',
+    description: 'Without an architecture diagram, the agent has to infer project structure from file exploration, wasting tokens.',
+    platforms: ['claude', 'codex', 'cursor', 'windsurf', 'copilot', 'gemini', 'aider', 'opencode'],
+    fix: 'Add a Mermaid diagram in CLAUDE.md showing the main components and data flow.',
+    detect: (ctx) => {
+      const content = ctx.fileContent('CLAUDE.md') || ctx.fileContent('.claude/CLAUDE.md') || '';
+      if (!content) return false;
+      return !content.includes('mermaid') && !content.includes('```') && content.length > 200;
+    },
+  },
+  {
+    id: 'AP017',
+    name: 'Using deprecated features',
+    severity: 'medium',
+    description: 'Relying on deprecated features risks breakage when they are removed in future versions.',
+    platforms: ['claude'],
+    fix: 'Check the platform changelog for deprecated features and migrate to recommended alternatives.',
+    detect: (ctx) => {
+      const content = ctx.fileContent('CLAUDE.md') || ctx.fileContent('.claude/CLAUDE.md') || '';
+      const settings = ctx.jsonFile('.claude/settings.json') || ctx.jsonFile('.claude/settings.local.json');
+      // Check for known deprecated patterns
+      const deprecatedPatterns = [
+        /allowedTools/i,
+        /blockedTools/i,
+      ];
+      const hasDeprecatedInMd = deprecatedPatterns.some(p => p.test(content));
+      const hasDeprecatedInSettings = settings && deprecatedPatterns.some(p => p.test(JSON.stringify(settings)));
+      return hasDeprecatedInMd || hasDeprecatedInSettings;
+    },
+  },
+  {
+    id: 'AP018',
+    name: 'No rules files',
+    severity: 'low',
+    description: 'Without .claude/rules/ files, all instructions live in one place, making it harder to scope guidance by file type.',
+    platforms: ['claude'],
+    fix: 'Create .claude/rules/ with scoped rules for different areas (e.g., tests.md, api.md, frontend.md).',
+    detect: (ctx) => {
+      return !ctx.hasDir('.claude/rules') || (ctx.dirFiles('.claude/rules') || []).length === 0;
+    },
+  },
+  {
+    id: 'AP019',
+    name: 'Overly long CLAUDE.md (>500 lines)',
+    severity: 'medium',
+    description: 'Instruction files over 500 lines consume excessive context tokens and reduce adherence to individual rules.',
+    platforms: ['claude'],
+    fix: 'Split into CLAUDE.md (core) + .claude/rules/ (scoped). Use @import for focused modules.',
+    detect: (ctx) => {
+      const content = ctx.fileContent('CLAUDE.md') || ctx.fileContent('.claude/CLAUDE.md') || '';
+      if (!content) return false;
+      const lineCount = content.split('\n').length;
+      return lineCount > 500;
+    },
+  },
+  {
+    id: 'AP020',
+    name: 'No security review command',
+    severity: 'medium',
+    description: 'Without a security review command, OWASP Top 10 vulnerabilities go undetected during agent-assisted development.',
+    platforms: ['claude', 'codex', 'cursor', 'windsurf', 'copilot', 'gemini', 'aider', 'opencode'],
+    fix: 'Add a /security-review command or include security scanning in your CI pipeline.',
+    detect: (ctx) => {
+      const content = ctx.fileContent('CLAUDE.md') || ctx.fileContent('.claude/CLAUDE.md') || '';
+      const hasSecurityReview = /security[- ]?review/i.test(content);
+      const hasSecurityCommand = ctx.hasDir('.claude/commands') &&
+        (ctx.dirFiles('.claude/commands') || []).some(f => /security/i.test(f));
+      return !hasSecurityReview && !hasSecurityCommand;
+    },
+  },
+  {
+    id: 'AP021',
+    name: 'Inline secrets in hook scripts',
+    severity: 'critical',
+    description: 'Hardcoded API keys or tokens in hook scripts are executed every session and easily leaked.',
+    platforms: ['claude'],
+    fix: 'Use environment variables in hooks. Reference secrets via $ENV_VAR instead of hardcoding values.',
+    detect: (ctx) => {
+      if (!ctx.hasDir('.claude/hooks')) return false;
+      const hookFiles = ctx.dirFiles('.claude/hooks');
+      const secretPatterns = [
+        /(?:api[_-]?key|token|password|secret)\s*=\s*['"][A-Za-z0-9_\-]{16,}['"]/i,
+        /sk-[A-Za-z0-9]{20,}/,
+        /ghp_[A-Za-z0-9]{36,}/,
+        /AKIA[A-Z0-9]{16}/,
+      ];
+      for (const file of hookFiles) {
+        const content = ctx.fileContent(`.claude/hooks/${file}`) || '';
+        if (secretPatterns.some(p => p.test(content))) {
+          return true;
+        }
+      }
+      return false;
+    },
+  },
+  {
+    id: 'AP022',
+    name: 'Missing .env protection in .gitignore',
+    severity: 'high',
+    description: 'Without .env in .gitignore, environment files with secrets can be accidentally committed and pushed.',
+    platforms: ['claude', 'codex', 'cursor', 'windsurf', 'copilot', 'gemini', 'aider', 'opencode'],
+    fix: 'Add .env, .env.*, and .env.local to .gitignore. Verify with "git check-ignore .env".',
+    detect: (ctx) => {
+      const gitignore = ctx.fileContent('.gitignore') || '';
+      if (!gitignore) return true;
+      return !gitignore.includes('.env');
+    },
+  },
+];
+
+/**
+ * Return the full anti-pattern catalog.
+ * @returns {Array<Object>} All registered anti-patterns.
+ */
+function getAntiPatterns() {
+  return ANTI_PATTERNS.map(({ detect, ...rest }) => rest);
+}
+
+/**
+ * Detect anti-patterns present in a project context.
+ * @param {Object} ctx - A ProjectContext instance (from src/context.js).
+ * @returns {Array<Object>} Detected anti-patterns with id, name, severity, description, and fix.
+ */
+function detectAntiPatterns(ctx) {
+  const detected = [];
+  for (const pattern of ANTI_PATTERNS) {
+    try {
+      if (pattern.detect(ctx)) {
+        const { detect, ...rest } = pattern;
+        detected.push(rest);
+      }
+    } catch (_err) {
+      // Skip patterns that fail to detect (missing files, etc.)
+    }
+  }
+  return detected;
+}
+
+/**
+ * Print detected anti-patterns to the console.
+ * @param {Array<Object>} patterns - Detected anti-patterns.
+ * @param {Object} [options] - Display options.
+ * @param {boolean} [options.json] - Output as JSON.
+ */
+function printAntiPatterns(patterns, options = {}) {
+  if (options.json) {
+    console.log(JSON.stringify(patterns, null, 2));
+    return;
+  }
+
+  const SEVERITY_COLORS = {
+    critical: '\x1b[31m',
+    high: '\x1b[33m',
+    medium: '\x1b[36m',
+    low: '\x1b[2m',
+  };
+  const RESET = '\x1b[0m';
+  const BOLD = '\x1b[1m';
+  const DIM = '\x1b[2m';
+
+  console.log('');
+  console.log(`${BOLD}  nerviq anti-patterns${RESET}`);
+  console.log(`${DIM}  ${'═'.repeat(39)}${RESET}`);
+
+  if (patterns.length === 0) {
+    console.log(`  ${'\\x1b[32m'}No anti-patterns detected. Good job!${RESET}`);
+    console.log('');
+    return;
+  }
+
+  console.log(`  ${patterns.length} anti-pattern${patterns.length === 1 ? '' : 's'} detected`);
+  console.log('');
+
+  // Sort by severity: critical > high > medium > low
+  const severityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+  const sorted = [...patterns].sort((a, b) => (severityOrder[a.severity] || 9) - (severityOrder[b.severity] || 9));
+
+  for (const p of sorted) {
+    const color = SEVERITY_COLORS[p.severity] || '';
+    console.log(`  ${color}[${p.severity}]${RESET} ${p.name} (${p.id})`);
+    console.log(`${DIM}    ${p.description}${RESET}`);
+    console.log(`${DIM}    Fix: ${p.fix}${RESET}`);
+    console.log('');
+  }
+}
+
+/**
+ * Print the full anti-pattern catalog.
+ * @param {Object} [options] - Display options.
+ * @param {boolean} [options.json] - Output as JSON.
+ */
+function printAntiPatternCatalog(options = {}) {
+  const all = getAntiPatterns();
+  if (options.json) {
+    console.log(JSON.stringify(all, null, 2));
+    return;
+  }
+
+  const SEVERITY_COLORS = {
+    critical: '\x1b[31m',
+    high: '\x1b[33m',
+    medium: '\x1b[36m',
+    low: '\x1b[2m',
+  };
+  const RESET = '\x1b[0m';
+  const BOLD = '\x1b[1m';
+  const DIM = '\x1b[2m';
+
+  console.log('');
+  console.log(`${BOLD}  nerviq anti-pattern catalog${RESET}`);
+  console.log(`${DIM}  ${'═'.repeat(39)}${RESET}`);
+  console.log(`  ${all.length} anti-patterns registered`);
+  console.log('');
+
+  const severityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+  const sorted = [...all].sort((a, b) => (severityOrder[a.severity] || 9) - (severityOrder[b.severity] || 9));
+
+  for (const p of sorted) {
+    const color = SEVERITY_COLORS[p.severity] || '';
+    console.log(`  ${color}[${p.severity}]${RESET} ${p.name} (${p.id})`);
+    console.log(`${DIM}    ${p.description}${RESET}`);
+    console.log(`${DIM}    Platforms: ${p.platforms.join(', ')}${RESET}`);
+    console.log(`${DIM}    Fix: ${p.fix}${RESET}`);
+    console.log('');
+  }
+}
+
+module.exports = {
+  ANTI_PATTERNS,
+  getAntiPatterns,
+  detectAntiPatterns,
+  printAntiPatterns,
+  printAntiPatternCatalog,
+};

package/src/benchmark.js

@@ -247,18 +247,23 @@ function renderBenchmarkMarkdown(report) {
  * Run a before/after benchmark on an isolated copy of the project.
  * @param {Object} options - Benchmark options.
  * @param {string} options.dir - Project directory to benchmark.
+ * @param {string} [options.external] - External repo path to benchmark instead of cwd.
  * @param {string} [options.profile] - Permission profile to use during setup.
  * @param {string[]} [options.mcpPacks] - MCP pack keys to include in setup.
  * @returns {Promise<Object>} Benchmark report with before/after scores, delta, and workflow evidence.
  */
 async function runBenchmark(options) {
   const platform = options.platform || 'claude';
-  const before = await audit({ dir: options.dir, silent: true, platform });
+  const sourceDir = options.external || options.dir;
+  if (options.external && !fs.existsSync(options.external)) {
+    throw new Error(`External repo path not found: ${options.external}`);
+  }
+  const before = await audit({ dir: sourceDir, silent: true, platform });
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'claudex-benchmark-'));
   const sandboxDir = path.join(tempRoot, 'repo');
 
   try {
-    copyProject(options.dir, sandboxDir);
+    copyProject(sourceDir, sandboxDir);
     const applyResult = await setup({
       dir: sandboxDir,
       auto: true,
@@ -278,7 +283,7 @@ async function runBenchmark(options) {
       schemaVersion: 1,
       generatedBy: `nerviq@${version}`,
       createdAt: new Date().toISOString(),
-      directory: options.dir,
+      directory: sourceDir,
       platform,
       methodology: [
         'Run a baseline audit on the source repo.',

package/src/governance.js

@@ -60,6 +60,7 @@ const HOOK_REGISTRY = [
     filesTouched: [],
     sideEffects: ['Stops the action and returns a block decision when a secret path is targeted.'],
     risk: 'low',
+    riskLevel: 'high',
     dryRunExample: 'Attempt to read `.env` and confirm the hook blocks the request.',
     rollbackPath: 'Remove the PreToolUse registration from settings.json.',
   },
@@ -72,6 +73,7 @@ const HOOK_REGISTRY = [
     filesTouched: ['Working tree files targeted by eslint/ruff fixes'],
     sideEffects: ['May auto-fix formatting or lint issues.', 'Can modify the same files that were just edited.'],
     risk: 'medium',
+    riskLevel: 'medium',
     dryRunExample: 'Edit a JS or Python file and inspect whether eslint or ruff would run.',
     rollbackPath: 'Remove the PostToolUse hook entry or delete the script.',
   },
@@ -84,6 +86,7 @@ const HOOK_REGISTRY = [
     filesTouched: ['.claude/logs/file-changes.log'],
     sideEffects: ['Creates the logs directory on first use.', 'Adds a timestamped audit line per file change.'],
     risk: 'low',
+    riskLevel: 'low',
     dryRunExample: 'Edit one file and verify the log entry is appended.',
     rollbackPath: 'Remove the PostToolUse hook entry and delete the log file if desired.',
   },
@@ -96,6 +99,7 @@ const HOOK_REGISTRY = [
     filesTouched: [],
     sideEffects: ['Returns a systemMessage warning if duplicates are found.'],
     risk: 'low',
+    riskLevel: 'low',
     dryRunExample: 'Edit a catalog file and verify duplicate check runs without blocking.',
     rollbackPath: 'Remove the PostToolUse hook entry from settings.',
   },
@@ -108,6 +112,7 @@ const HOOK_REGISTRY = [
     filesTouched: ['tools/failure-log.txt'],
     sideEffects: ['Logs alerts to failure log.', 'Returns a systemMessage warning if patterns detected.'],
     risk: 'low',
+    riskLevel: 'low',
     dryRunExample: 'Run a WebFetch and verify output is scanned for injection patterns.',
     rollbackPath: 'Remove the PostToolUse hook entry from settings.',
   },
@@ -120,6 +125,7 @@ const HOOK_REGISTRY = [
     filesTouched: [],
     sideEffects: ['Returns a systemMessage warning if drift is detected.'],
     risk: 'low',
+    riskLevel: 'low',
     dryRunExample: 'Edit a product-facing file and verify drift check runs.',
     rollbackPath: 'Remove the PostToolUse hook entry from settings.',
   },
@@ -132,11 +138,48 @@ const HOOK_REGISTRY = [
     filesTouched: ['tools/change-log.txt', 'tools/failure-log.txt'],
     sideEffects: ['Archives logs over 500KB.', 'Returns a systemMessage with workspace info.'],
     risk: 'low',
+    riskLevel: 'low',
     dryRunExample: 'Start a new session and verify log rotation runs.',
     rollbackPath: 'Remove the SessionStart hook entry from settings.',
   },
 ];
 
+/**
+ * Classify the risk level of a hook based on its event type and characteristics.
+ * - high: PreToolUse hooks that can block operations (exit 2)
+ * - medium: PostToolUse hooks that modify files or warn (exit 1 or write-only)
+ * - low: Informational hooks (PostToolUse notification/logging, SessionStart)
+ * @param {Object} hook - A hook entry from HOOK_REGISTRY or a custom hook.
+ * @returns {string} Risk level: 'high', 'medium', or 'low'.
+ */
+function classifyHookRiskLevel(hook) {
+  // PreToolUse hooks can block operations (exit code 2 blocks the tool call)
+  if (hook.triggerPoint === 'PreToolUse') {
+    return 'high';
+  }
+
+  // SessionStart hooks are informational — they run once at session init
+  if (hook.triggerPoint === 'SessionStart') {
+    return 'low';
+  }
+
+  // PostToolUse hooks that touch files are medium risk (they can modify working tree)
+  if (hook.triggerPoint === 'PostToolUse') {
+    if (Array.isArray(hook.filesTouched) && hook.filesTouched.length > 0) {
+      // Hooks that only write to log files are low risk
+      const onlyLogs = hook.filesTouched.every(f =>
+        /\blog|\.log\b/i.test(f) || f.includes('logs/')
+      );
+      if (onlyLogs) return 'low';
+      return 'medium';
+    }
+    return 'low';
+  }
+
+  // Default: unknown trigger points get medium risk
+  return 'medium';
+}
+
 const POLICY_PACKS = [
   {
     key: 'baseline-engineering',
@@ -377,7 +420,9 @@ function printGovernanceSummary(summary, options = {}) {
   console.log('  Hook Registry');
   for (const hook of summary.hookRegistry) {
     const riskColor = hook.risk === 'low' ? '\x1b[32m' : hook.risk === 'medium' ? '\x1b[33m' : '\x1b[31m';
-    console.log(`  - ${hook.file} ${riskColor}[${hook.risk} risk]\x1b[0m`);
+    const rl = hook.riskLevel || classifyHookRiskLevel(hook);
+    const rlColor = rl === 'low' ? '\x1b[32m' : rl === 'medium' ? '\x1b[33m' : '\x1b[31m';
+    console.log(`  - ${hook.file} ${riskColor}[${hook.risk} risk]\x1b[0m ${rlColor}[${rl} riskLevel]\x1b[0m`);
     console.log(`    ${hook.triggerPoint}${hook.matcher ? ` ${hook.matcher}` : ''} -> ${hook.purpose}`);
   }
   console.log('');
@@ -448,7 +493,8 @@ function renderGovernanceMarkdown(summary) {
 
   lines.push('', '## Hook Registry');
   for (const hook of summary.hookRegistry) {
-    lines.push(`- **${hook.key}** \`${hook.triggerPoint}${hook.matcher ? ` ${hook.matcher}` : ''}\` | risk: \`${hook.risk}\``);
+    const rl = hook.riskLevel || classifyHookRiskLevel(hook);
+    lines.push(`- **${hook.key}** \`${hook.triggerPoint}${hook.matcher ? ` ${hook.matcher}` : ''}\` | risk: \`${hook.risk}\` | riskLevel: \`${rl}\``);
     lines.push(`  - File: ${hook.file}`);
     lines.push(`  - Purpose: ${hook.purpose}`);
     lines.push(`  - Dry run: ${hook.dryRunExample}`);
@@ -520,4 +566,5 @@ module.exports = {
   getGovernanceSummary,
   printGovernanceSummary,
   renderGovernanceMarkdown,
+  classifyHookRiskLevel,
 };

package/src/recommendation-rules.js

@@ -0,0 +1,84 @@
+/**
+ * Recommendation Rules Export
+ *
+ * Reads all TECHNIQUES, groups by category, and generates
+ * a structured JSON-serializable recommendation rules object.
+ */
+
+const { TECHNIQUES } = require('./techniques');
+const { version } = require('../package.json');
+
+const IMPACT_ORDER = { critical: 4, high: 3, medium: 2, low: 1 };
+
+function impactLabel(avg) {
+  if (avg >= 3.5) return 'critical';
+  if (avg >= 2.5) return 'high';
+  if (avg >= 1.5) return 'medium';
+  return 'low';
+}
+
+function generateRecommendationRules(options) {
+  const opts = options || {};
+  const entries = Object.entries(TECHNIQUES);
+
+  // Group by category
+  const grouped = {};
+  for (const [key, t] of entries) {
+    const cat = t.category;
+    if (!grouped[cat]) grouped[cat] = [];
+    grouped[cat].push({ key, ...t });
+  }
+
+  // Build categories summary
+  const categories = {};
+  for (const [cat, checks] of Object.entries(grouped)) {
+    const weights = checks.map(c => IMPACT_ORDER[c.impact] || 0);
+    const avgWeight = weights.reduce((a, b) => a + b, 0) / weights.length;
+
+    // Top 5 by impact weight (descending), then by rating (descending)
+    const sorted = [...checks].sort((a, b) => {
+      const impactDiff = (IMPACT_ORDER[b.impact] || 0) - (IMPACT_ORDER[a.impact] || 0);
+      if (impactDiff !== 0) return impactDiff;
+      return (b.rating || 0) - (a.rating || 0);
+    });
+
+    const topChecks = sorted.slice(0, 5).map(c => ({
+      key: c.key,
+      name: c.name,
+      impact: c.impact,
+      fix: c.fix,
+    }));
+
+    categories[cat] = {
+      checkCount: checks.length,
+      averageImpact: impactLabel(avgWeight),
+      topChecks,
+    };
+  }
+
+  const byRepoType = {
+    frontend: ['security', 'design', 'performance-budget', 'accessibility'],
+    backend: ['security', 'api-versioning', 'caching', 'rate-limiting', 'observability'],
+    fullstack: ['security', 'quality', 'automation', 'observability'],
+    mobile: ['flutter', 'swift', 'kotlin', 'security'],
+    infrastructure: ['devops', 'supply-chain', 'monitoring'],
+    library: ['docs-quality', 'quality', 'git'],
+  };
+
+  const byMaturity = {
+    'new-project': { focus: ['hygiene', 'security', 'quality'], skipCategories: ['quality-deep', 'enterprise'] },
+    growing: { focus: ['automation', 'workflow', 'observability'], skipCategories: [] },
+    mature: { focus: ['quality-deep', 'performance-budget', 'governance'], skipCategories: [] },
+  };
+
+  return {
+    generatedAt: new Date().toISOString(),
+    version,
+    totalRules: entries.length,
+    categories,
+    byRepoType,
+    byMaturity,
+  };
+}
+
+module.exports = { generateRecommendationRules };

package/src/verification-metadata.js

@@ -0,0 +1,145 @@
+/**
+ * Last-verified dates for technique checks.
+ * Updated when checks are re-tested against live platforms.
+ */
+const VERIFICATION_DATES = {
+  // Core checks (verified 2026-04-06 via self-audit on nerviq repo)
+  claudeMd: '2026-04-06',
+  mermaidArchitecture: '2026-04-06',
+  pathRules: '2026-04-06',
+  importSyntax: '2026-04-06',
+  underlines200: '2026-04-06',
+  verificationLoop: '2026-04-06',
+  testCommand: '2026-04-06',
+  lintCommand: '2026-04-06',
+  buildCommand: '2026-04-06',
+  gitIgnoreClaudeTracked: '2026-04-06',
+  gitIgnoreEnv: '2026-04-06',
+  gitIgnoreNodeModules: '2026-04-06',
+  noSecretsInClaude: '2026-04-06',
+  customCommands: '2026-04-06',
+  multipleCommands: '2026-04-06',
+  deployCommand: '2026-04-06',
+  reviewCommand: '2026-04-06',
+  skills: '2026-04-06',
+  multipleSkills: '2026-04-06',
+  agents: '2026-04-06',
+  multipleAgents: '2026-04-06',
+  multipleRules: '2026-04-06',
+  settingsPermissions: '2026-04-06',
+  permissionDeny: '2026-04-06',
+  noBypassPermissions: '2026-04-06',
+  secretsProtection: '2026-04-06',
+  securityReview: '2026-04-06',
+  hooks: '2026-04-06',
+  hooksInSettings: '2026-04-06',
+  preToolUseHook: '2026-04-06',
+  postToolUseHook: '2026-04-06',
+  sessionStartHook: '2026-04-06',
+  ciPipeline: '2026-04-06',
+  readme: '2026-04-06',
+  changelog: '2026-04-06',
+  contributing: '2026-04-06',
+  license: '2026-04-06',
+  editorconfig: '2026-04-06',
+  nvmrc: '2026-04-06',
+  compactionAwareness: '2026-04-06',
+  contextManagement: '2026-04-06',
+  mcpServers: '2026-04-06',
+  context7Mcp: '2026-04-06',
+  xmlTags: '2026-04-06',
+  fewShotExamples: '2026-04-06',
+  roleDefinition: '2026-04-06',
+  constraintBlocks: '2026-04-06',
+  claudeMdFreshness: '2026-04-06',
+  claudeMdNoContradictions: '2026-04-06',
+  hooksAreSpecific: '2026-04-06',
+  commandsUseArguments: '2026-04-06',
+  agentsHaveMaxTurns: '2026-04-06',
+  securityReviewInWorkflow: '2026-04-06',
+  testCoverage: '2026-04-06',
+  agentHasAllowedTools: '2026-04-06',
+  sandboxAwareness: '2026-04-06',
+  denyRulesDepth: '2026-04-06',
+  hasSnapshotHistory: '2026-04-06',
+  negativeInstructions: '2026-04-06',
+  outputStyleGuidance: '2026-04-06',
+  githubActionsOrCI: '2026-04-06',
+  projectDescriptionInClaudeMd: '2026-04-06',
+  directoryStructureInClaudeMd: '2026-04-06',
+  multipleHookTypes: '2026-04-06',
+  gitIgnoreClaudeLocal: '2026-04-06',
+  envExampleExists: '2026-04-06',
+  packageJsonHasScripts: '2026-04-06',
+  noDeprecatedPatterns: '2026-04-06',
+  claudeMdQuality: '2026-04-06',
+  mcpJsonProject: '2026-04-06',
+  rulesDirectory: '2026-04-06',
+  gitignoreClaudeLocal: '2026-04-06',
+  pyprojectTomlExists: '2026-04-06',
+  pythonSecurityScanner: '2026-04-06',
+  pythonAsyncPatterns: '2026-04-06',
+  pythonEnvExample: '2026-04-06',
+  pythonAPISchema: '2026-04-06',
+  pythonMonorepo: '2026-04-06',
+  pythonDataValidation: '2026-04-06',
+  mcpBudgetHealthy: '2026-04-06',
+  hookExitCodesDefined: '2026-04-06',
+  consistencyPassAtK: '2026-04-06',
+  sseEndpoint: '2026-04-06',
+  realtimeAuth: '2026-04-06',
+  healthEndpoint: '2026-04-06',
+  privacyPolicy: '2026-04-06',
+  piiHandling: '2026-04-06',
+  gdprCompliance: '2026-04-06',
+  dataEncryption: '2026-04-06',
+  errorReporting: '2026-04-06',
+  sbomExists: '2026-04-06',
+  dependencyPinning: '2026-04-06',
+  provenanceAttestation: '2026-04-06',
+  lockfileIntegrity: '2026-04-06',
+  apiVersionHeader: '2026-04-06',
+  deprecationNotices: '2026-04-06',
+  apiChangelog: '2026-04-06',
+  backwardCompat: '2026-04-06',
+  cdnConfigured: '2026-04-06',
+  cacheHeaders: '2026-04-06',
+  rateLimitHeaders: '2026-04-06',
+  featureFlagTests: '2026-04-06',
+  contributingGuide: '2026-04-06',
+  licenseDeclared: '2026-04-06',
+  testingStrategyFrameworkDetected: '2026-04-06',
+  testingStrategyCoverageConfigExists: '2026-04-06',
+  testingStrategySnapshotTestsMentioned: '2026-04-06',
+  testingStrategyTestCommandDocumented: '2026-04-06',
+  testingStrategyCiRunsTests: '2026-04-06',
+  codeQualityLinterConfigured: '2026-04-06',
+  codeQualityFormatterConfigured: '2026-04-06',
+  codeQualityComplexityAwareness: '2026-04-06',
+  codeQualityConsistentNamingDocumented: '2026-04-06',
+  codeQualityCodeReviewProcessMentioned: '2026-04-06',
+  dependencyManagementLockfilePresent: '2026-04-06',
+  dependencyManagementOutdatedDepsAwareness: '2026-04-06',
+  dependencyManagementLicenseCompliance: '2026-04-06',
+  dependencyManagementNpmAuditConfigured: '2026-04-06',
+  dependencyManagementAutoUpdatePolicy: '2026-04-06',
+  costOptimizationTokenUsageAwareness: '2026-04-06',
+  costOptimizationModelSelectionGuidance: '2026-04-06',
+  costOptimizationCachingGuidance: '2026-04-06',
+  costOptimizationBudgetGuardrails: '2026-04-06',
+};
+
+function getVerificationDate(checkKey) {
+  return VERIFICATION_DATES[checkKey] || null;
+}
+
+function getVerificationStats() {
+  const total = Object.keys(VERIFICATION_DATES).length;
+  const dates = Object.values(VERIFICATION_DATES);
+  const sorted = [...dates].sort();
+  const newest = sorted[sorted.length - 1];
+  const oldest = sorted[0];
+  return { total, newest, oldest };
+}
+
+module.exports = { VERIFICATION_DATES, getVerificationDate, getVerificationStats };