@nerviq/cli 1.8.1 → 1.8.3

package/bin/cli.js

@@ -6,8 +6,9 @@ const { analyzeProject, printAnalysis, exportMarkdown } = require('../src/analyz
 const { buildProposalBundle, printProposalBundle, writePlanFile, applyProposalBundle, printApplyResult } = require('../src/plans');
 const { getGovernanceSummary, printGovernanceSummary, ensureWritableProfile, renderGovernanceMarkdown } = require('../src/governance');
 const { runBenchmark, printBenchmark, writeBenchmarkReport } = require('../src/benchmark');
-const { writeSnapshotArtifact, recordRecommendationOutcome, formatRecommendationOutcomeSummary, getRecommendationOutcomeSummary } = require('../src/activity');
+const { writeSnapshotArtifact, writeRollbackArtifact, recordRecommendationOutcome, formatRecommendationOutcomeSummary, getRecommendationOutcomeSummary } = require('../src/activity');
 const { collectFeedback } = require('../src/feedback');
+const { recordPattern, getPriorityAdjustment, formatUsageSummary } = require('../src/usage-patterns');
 const { startServer } = require('../src/server');
 const { auditWorkspaces } = require('../src/workspace');
 const { scanOrg } = require('../src/org');
@@ -328,6 +329,7 @@ const HELP = `
   FIX
     nerviq fix                    Show fixable checks and manual-fix guidance
     nerviq fix <key>              Auto-fix a specific check (with score impact)
+    nerviq fix <key> --prompt     Show AI agent prompt for a check (no auto-fix)
     nerviq fix --all-critical     Fix all critical issues at once
     nerviq fix --dry-run          Preview fixes without writing
     nerviq fix --auto             Apply fixes without confirmation prompt
@@ -745,6 +747,17 @@ async function main() {
       });
       return; // keep process alive for http
     } else if (normalizedCommand === 'feedback') {
+      if (flags.includes('--patterns')) {
+        if (options.json) {
+          const { getUsageSummary } = require('../src/usage-patterns');
+          console.log(JSON.stringify(getUsageSummary(options.dir), null, 2));
+        } else {
+          console.log('');
+          console.log(formatUsageSummary(options.dir));
+          console.log('');
+        }
+        process.exit(0);
+      }
       if (parsed.feedbackKey) {
         if (!parsed.feedbackStatus) {
           console.error('\n  Error: feedback logging requires --status when --key is provided.\n');
@@ -1284,9 +1297,10 @@ async function main() {
       console.log(output);
       process.exit(0);
     } else if (normalizedCommand === 'fix') {
-      // nerviq fix [key] [--all-critical] [--dry-run] [--auto]
+      // nerviq fix [key] [--all-critical] [--dry-run] [--auto] [--prompt]
       const fixKey = parsed.extraArgs[0] || null;
       const allCritical = flags.includes('--all-critical');
+      const promptOnly = flags.includes('--prompt');
       const autoApply = options.auto || options.dryRun;
 
       // Step 1: Run silent audit to find failed checks (only actual failures, not skipped/null)
@@ -1300,6 +1314,7 @@ async function main() {
 
       // Step 2: Determine which checks to fix
       const { TECHNIQUES } = require('../src/techniques');
+      const { FIX_PROMPTS, formatFixPrompt } = require('../src/fix-prompts');
       const fs = require('fs');
       const pathMod = require('path');
 
@@ -1348,6 +1363,18 @@ async function main() {
           }
           process.exit(1);
         }
+        // --prompt flag: show AI prompt and exit without attempting fix
+        if (promptOnly) {
+          const prompt = FIX_PROMPTS[fixKey];
+          if (prompt) {
+            console.log(formatFixPrompt(fixKey, prompt));
+          } else {
+            const failedCheck = failedResults.find(r => r.key === fixKey);
+            console.log(`\n  No AI prompt available for '${fixKey}'.`);
+            console.log(`  Manual fix: ${failedCheck ? failedCheck.fix : 'See nerviq audit --full.'}\n`);
+          }
+          process.exit(0);
+        }
         targetKeys = [fixKey];
       } else if (allCritical) {
         targetKeys = failedResults.filter(r => r.impact === 'critical').map(r => r.key);
@@ -1371,15 +1398,30 @@ async function main() {
           console.log('');
         }
         if (nonFixable.length > 0) {
-          console.log(`  Manual fix needed (${nonFixable.length}):`);
-          for (const r of nonFixable.slice(0, 5)) {
-            const tier = r.impact === 'critical' ? '🔴' : r.impact === 'high' ? '🟡' : '🔵';
-            console.log(`    ${tier} ${r.key}: ${r.fix}`);
+          const withPrompt = nonFixable.filter(r => FIX_PROMPTS[r.key]);
+          const withoutPrompt = nonFixable.filter(r => !FIX_PROMPTS[r.key]);
+          if (withPrompt.length > 0) {
+            console.log(`  AI prompt available (${withPrompt.length}):`);
+            for (const r of withPrompt.slice(0, 5)) {
+              const tier = r.impact === 'critical' ? '🔴' : r.impact === 'high' ? '🟡' : '🔵';
+              console.log(`    ${tier} nerviq fix ${r.key} --prompt`);
+            }
+            if (withPrompt.length > 5) {
+              console.log(`    ... and ${withPrompt.length - 5} more`);
+            }
+            console.log('');
           }
-          if (nonFixable.length > 5) {
-            console.log(`    ... and ${nonFixable.length - 5} more (use --full to see all)`);
+          if (withoutPrompt.length > 0) {
+            console.log(`  Manual fix needed (${withoutPrompt.length}):`);
+            for (const r of withoutPrompt.slice(0, 5)) {
+              const tier = r.impact === 'critical' ? '🔴' : r.impact === 'high' ? '🟡' : '🔵';
+              console.log(`    ${tier} ${r.key}: ${r.fix}`);
+            }
+            if (withoutPrompt.length > 5) {
+              console.log(`    ... and ${withoutPrompt.length - 5} more (use --full to see all)`);
+            }
+            console.log('');
           }
-          console.log('');
         }
         if (fixable.length > 0) {
           console.log(`  Quick actions:`);
@@ -1448,55 +1490,175 @@ async function main() {
         });
         rl.close();
         if (answer && answer.trim().toLowerCase() === 'n') {
+          for (const key of targetKeys) {
+            recordPattern(options.dir, key, 'rejected');
+          }
           console.log('\n  Aborted.\n');
           process.exit(0);
         }
       }
 
-      // Step 3: For each target, either use template, inline fix, or show manual instructions
+      // Step 3: Create rollback snapshot before applying fixes
+      const isBatch = allCritical && targetKeys.length > 1;
+      let rollbackId = null;
+      const allCreatedFiles = [];
+      const fixResults = []; // { key, name, status, delta }
+
+      if (!options.dryRun && targetKeys.length > 0) {
+        // Snapshot existing files for rollback
+        const snapshotFiles = {};
+        for (const key of targetKeys) {
+          const technique = TECHNIQUES[key];
+          if (technique && technique.template && technique.template.path) {
+            const tplPath = pathMod.join(options.dir, technique.template.path);
+            if (fs.existsSync(tplPath)) {
+              snapshotFiles[technique.template.path] = fs.readFileSync(tplPath, 'utf8');
+            }
+          }
+        }
+        const rollbackArtifact = writeRollbackArtifact(options.dir, {
+          sourcePlan: 'fix-batch',
+          preSnapshot: snapshotFiles,
+          createdFiles: [],
+          patchedFiles: Object.keys(snapshotFiles),
+          rollbackInstructions: ['Use nerviq rollback to undo these fixes'],
+        });
+        rollbackId = rollbackArtifact.id;
+      }
+
+      // Step 3b: Apply fixes sequentially with progress
       let fixed = 0;
       let manual = 0;
+      let runningScore = preScore;
 
-      for (const key of targetKeys) {
+      for (let i = 0; i < targetKeys.length; i++) {
+        const key = targetKeys[i];
         const technique = TECHNIQUES[key];
         const failedCheck = failedResults.find(r => r.key === key);
+        const progress = isBatch ? `${i + 1}/${targetKeys.length}: ` : '';
 
         if (technique && technique.template) {
           if (options.dryRun) {
-            console.log(`\n  [dry-run] Would fix: ${failedCheck.name} (${key})`);
+            console.log(`  [dry-run] Would fix: ${progress}${failedCheck.name} (${key})`);
+            fixResults.push({ key, name: failedCheck.name, status: 'dry-run', delta: 0 });
             fixed++;
           } else {
-            // Use setup with only this key
-            await setup({ ...options, only: [key], silent: true });
-            console.log(`  ✅ Fixed: ${failedCheck.name}`);
-            fixed++;
+            try {
+              if (isBatch) console.log(`  Fixing ${progress}${key}...`);
+              const setupResult = await setup({ ...options, only: [key], silent: true });
+              if (setupResult && setupResult.writtenFiles) {
+                allCreatedFiles.push(...setupResult.writtenFiles);
+              }
+              const midResult = await audit({ dir: options.dir, silent: true, platform: options.platform });
+              const delta = midResult.score - runningScore;
+              fixResults.push({ key, name: failedCheck.name, status: 'fixed', delta });
+              runningScore = midResult.score;
+              if (!isBatch) console.log(`  ✅ Fixed: ${failedCheck.name}`);
+              fixed++;
+            } catch (err) {
+              fixResults.push({ key, name: failedCheck.name, status: 'failed', delta: 0 });
+              if (isBatch) {
+                console.log(`  ❌ Failed: ${key} — ${err.message}`);
+                console.log(`  Stopping batch. ${fixed} fixes applied so far.`);
+                console.log(`  Rollback: nerviq rollback --id ${rollbackId}`);
+                break;
+              } else {
+                console.log(`  ❌ Failed: ${failedCheck.name} — ${err.message}`);
+              }
+            }
           }
         } else if (INLINE_FIXERS[key]) {
           if (options.dryRun) {
-            console.log(`  [dry-run] Would fix: ${failedCheck.name} (${key})`);
+            console.log(`  [dry-run] Would fix: ${progress}${failedCheck.name} (${key})`);
+            fixResults.push({ key, name: failedCheck.name, status: 'dry-run', delta: 0 });
             fixed++;
           } else {
-            const didFix = INLINE_FIXERS[key](options.dir);
-            if (didFix) {
-              console.log(`  ✅ Fixed: ${failedCheck.name}`);
-              fixed++;
-            } else {
-              console.log(`  ⏭️  Already fixed: ${failedCheck.name}`);
+            try {
+              if (isBatch) console.log(`  Fixing ${progress}${key}...`);
+              const didFix = INLINE_FIXERS[key](options.dir);
+              if (didFix) {
+                const midResult = await audit({ dir: options.dir, silent: true, platform: options.platform });
+                const delta = midResult.score - runningScore;
+                fixResults.push({ key, name: failedCheck.name, status: 'fixed', delta });
+                runningScore = midResult.score;
+                if (!isBatch) console.log(`  ✅ Fixed: ${failedCheck.name}`);
+                fixed++;
+              } else {
+                fixResults.push({ key, name: failedCheck.name, status: 'skipped', delta: 0 });
+                if (!isBatch) console.log(`  ⏭️  Already fixed: ${failedCheck.name}`);
+              }
+            } catch (err) {
+              fixResults.push({ key, name: failedCheck.name, status: 'failed', delta: 0 });
+              if (isBatch) {
+                console.log(`  ❌ Failed: ${key} — ${err.message}`);
+                console.log(`  Stopping batch. ${fixed} fixes applied so far.`);
+                console.log(`  Rollback: nerviq rollback --id ${rollbackId}`);
+                break;
+              }
             }
           }
         } else {
-          console.log(`  📋 ${failedCheck.name} (manual fix needed)`);
-          console.log(`     ${failedCheck.fix}`);
+          if (!isBatch) {
+            const aiPrompt = FIX_PROMPTS[key];
+            if (aiPrompt) {
+              console.log(formatFixPrompt(key, aiPrompt));
+            } else {
+              console.log(`  📋 ${failedCheck.name} (manual fix needed)`);
+              console.log(`     ${failedCheck.fix}`);
+            }
+          }
+          fixResults.push({ key, name: failedCheck.name, status: 'skipped', delta: 0 });
           manual++;
         }
       }
 
-      // Step 4: Show score impact
-      if (fixed > 0 && !options.dryRun) {
+      // Record accepted patterns for successfully fixed checks
+      if (!options.dryRun) {
+        for (const key of targetKeys) {
+          const fr = fixResults.find(r => r.key === key);
+          recordPattern(options.dir, key, fr && fr.status === 'fixed' ? 'accepted' : 'rejected');
+        }
+      }
+
+      // Update rollback artifact with actual created files
+      if (!options.dryRun && rollbackId && allCreatedFiles.length > 0) {
+        const { ensureArtifactDirs } = require('../src/activity');
+        const { rollbackDir } = ensureArtifactDirs(options.dir);
+        const rbFiles = fs.readdirSync(rollbackDir).filter(f => f.includes(rollbackId));
+        if (rbFiles.length > 0) {
+          const rbPath = pathMod.join(rollbackDir, rbFiles[0]);
+          try {
+            const rbData = JSON.parse(fs.readFileSync(rbPath, 'utf8'));
+            rbData.createdFiles = allCreatedFiles;
+            fs.writeFileSync(rbPath, JSON.stringify(rbData, null, 2), 'utf8');
+          } catch { /* best effort */ }
+        }
+      }
+
+      // Step 4: Show batch summary or simple score impact
+      if (isBatch && fixResults.length > 0) {
+        console.log('');
+        console.log('  Batch fix complete:');
+        for (let i = 0; i < fixResults.length; i++) {
+          const r = fixResults[i];
+          const icon = r.status === 'fixed' ? '✅' : r.status === 'failed' ? '❌' : '⚠ ';
+          const deltaStr = r.status === 'fixed' ? ` (+${r.delta})` : r.status === 'skipped' ? ' (skipped — no auto-fix)' : r.status === 'failed' ? ' (failed)' : ' (dry-run)';
+          console.log(`  ${icon} ${i + 1}. ${r.key.padEnd(20)}${deltaStr}`);
+        }
+        const totalDelta = runningScore - preScore;
+        console.log('');
+        console.log(`  Score: ${preScore} → ${runningScore} (${totalDelta >= 0 ? '+' : ''}${totalDelta})`);
+        if (rollbackId && !options.dryRun) {
+          console.log(`  Rollback available: nerviq rollback --id ${rollbackId}`);
+        }
+      } else if (fixed > 0 && !options.dryRun) {
         const postResult = await audit({ dir: options.dir, silent: true, platform: options.platform });
         const delta = postResult.score - preScore;
         console.log('');
         console.log(`  Score: ${preScore} → ${postResult.score} (${delta >= 0 ? '+' : ''}${delta})`);
+        if (rollbackId) {
+          console.log(`  Rollback available: nerviq rollback --id ${rollbackId}`);
+        }
       }
 
       console.log(`\n  ${fixed} fixed, ${manual} need manual action.\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerviq/cli",
-  "version": "1.8.1",
+  "version": "1.8.3",
   "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": {

package/src/activity.js

@@ -557,12 +557,13 @@ function loadSnapshotPayload(dir, indexEntry) {
  * Analyze check health by comparing the two most recent audit snapshots.
  * Detects checks that regressed (passed → failed), improved (failed → passed),
  * and flags sudden drops that may indicate platform format changes.
+ * When more than 2 snapshots exist, also computes per-check pass rates.
  *
  * @param {string} dir - Project root directory.
  * @returns {Object|null} Health report, or null if fewer than 2 audit snapshots exist.
  */
 function checkHealth(dir) {
-  const history = getHistory(dir, 2);
+  const history = getHistory(dir, 20);
   if (history.length < 2) return null;
 
   const currentPayload = loadSnapshotPayload(dir, history[0]);
@@ -627,15 +628,20 @@ function checkHealth(dir) {
     }
   }
 
+  // Per-check pass rates across all snapshots
+  const passRates = computePassRates(dir, history);
+
   return {
     currentDate: history[0].createdAt,
     previousDate: history[1].createdAt,
+    snapshotsAnalyzed: history.length,
     scoreDelta: (currentPayload.score || 0) - (previousPayload.score || 0),
     regressions,
     improvements,
     newChecks,
     removedChecks,
     platformAlerts,
+    passRates,
     summary: {
       regressionsCount: regressions.length,
       improvementsCount: improvements.length,
@@ -646,6 +652,66 @@ function checkHealth(dir) {
   };
 }
 
+/**
+ * Compute per-check pass rates across all snapshots.
+ * Returns { declining, consistentlyFailing, consistentlyPassing, overallHealth }.
+ */
+function computePassRates(dir, history) {
+  // key → { passes, total, recentResults: [bool...] (newest first) }
+  const stats = {};
+  for (const entry of history) {
+    const payload = loadSnapshotPayload(dir, entry);
+    if (!payload || !payload.results) continue;
+    for (const r of payload.results) {
+      if (!r.key || r.passed === null || r.passed === undefined) continue;
+      if (!stats[r.key]) stats[r.key] = { name: r.name, passes: 0, total: 0, recentResults: [] };
+      stats[r.key].total++;
+      if (r.passed) stats[r.key].passes++;
+      stats[r.key].recentResults.push(!!r.passed);
+    }
+  }
+
+  const declining = [];
+  const consistentlyFailing = [];
+  let consistentlyPassingCount = 0;
+  let totalChecks = 0;
+  let totalPasses = 0;
+  let totalAppearances = 0;
+
+  for (const [key, s] of Object.entries(stats)) {
+    const rate = s.total > 0 ? s.passes / s.total : 0;
+    totalChecks++;
+    totalPasses += s.passes;
+    totalAppearances += s.total;
+
+    if (s.total >= 2 && rate === 0) {
+      consistentlyFailing.push({ key, name: s.name, runs: s.total });
+    } else if (rate === 1) {
+      consistentlyPassingCount++;
+    } else if (s.total >= 2) {
+      // Check if declining: earlier results passed, recent ones failed
+      const half = Math.ceil(s.recentResults.length / 2);
+      const recentHalf = s.recentResults.slice(0, half);
+      const olderHalf = s.recentResults.slice(half);
+      const recentRate = recentHalf.filter(Boolean).length / recentHalf.length;
+      const olderRate = olderHalf.length > 0 ? olderHalf.filter(Boolean).length / olderHalf.length : recentRate;
+      if (olderRate > recentRate) {
+        const failStreak = s.recentResults.findIndex(v => v === true);
+        declining.push({
+          key, name: s.name,
+          oldRate: Math.round(olderRate * 100),
+          newRate: Math.round(recentRate * 100),
+          failingRuns: failStreak === -1 ? s.recentResults.length : failStreak,
+        });
+      }
+    }
+  }
+
+  const overallHealth = totalAppearances > 0 ? Math.round((totalPasses / totalAppearances) * 100) : 100;
+
+  return { declining, consistentlyFailing, consistentlyPassingCount, overallHealth };
+}
+
 /**
  * Format check-health report for CLI display.
  */
@@ -653,11 +719,12 @@ function formatCheckHealth(healthReport) {
   if (!healthReport) return 'Need at least 2 audit snapshots. Run `nerviq audit --snapshot` twice.';
 
   const lines = [];
-  const { scoreDelta, regressions, improvements, platformAlerts, newChecks, summary } = healthReport;
+  const { scoreDelta, regressions, improvements, platformAlerts, newChecks, passRates } = healthReport;
   const sign = scoreDelta >= 0 ? '+' : '';
 
   lines.push(`  Check Health Report`);
-  lines.push(`  ─────────────────────────────────────`);
+  lines.push(`  ═══════════════════════════════════════`);
+  lines.push(`  Snapshots analyzed: ${healthReport.snapshotsAnalyzed}`);
   lines.push(`  Period: ${healthReport.previousDate?.split('T')[0]} → ${healthReport.currentDate?.split('T')[0]}`);
   lines.push(`  Score delta: ${sign}${scoreDelta}`);
   lines.push('');
@@ -671,6 +738,23 @@ function formatCheckHealth(healthReport) {
     lines.push('');
   }
 
+  if (passRates && passRates.declining.length > 0) {
+    lines.push(`  Checks with declining pass rate:`);
+    for (const d of passRates.declining) {
+      const detail = d.failingRuns > 0 ? `(failing in last ${d.failingRuns} runs)` : '';
+      lines.push(`  ⚠ ${d.key.padEnd(22)} ${d.oldRate}% → ${d.newRate}%  ${detail}`);
+    }
+    lines.push('');
+  }
+
+  if (passRates && passRates.consistentlyFailing.length > 0) {
+    lines.push(`  Consistently failing (0% pass rate):`);
+    for (const f of passRates.consistentlyFailing) {
+      lines.push(`  ✗ ${f.key.padEnd(22)} 0/${f.runs} runs`);
+    }
+    lines.push('');
+  }
+
   if (regressions.length > 0) {
     lines.push(`  🔴 Regressions (${regressions.length} checks now failing)`);
     for (const r of regressions) {
@@ -692,11 +776,21 @@ function formatCheckHealth(healthReport) {
     lines.push('');
   }
 
+  if (passRates && passRates.consistentlyPassingCount > 0) {
+    lines.push(`  Consistently passing (100%):`);
+    lines.push(`  ✓ ${passRates.consistentlyPassingCount} checks at 100% pass rate`);
+    lines.push('');
+  }
+
   if (regressions.length === 0 && platformAlerts.length === 0) {
     lines.push(`  ✅ All checks stable. No regressions detected.`);
     lines.push('');
   }
 
+  if (passRates) {
+    lines.push(`  Overall health: ${passRates.overallHealth}%`);
+  }
+
   return lines.join('\n');
 }
 

package/src/audit.js

@@ -953,9 +953,13 @@ function printLiteAudit(result, dir) {
 
   console.log(colorize('  Top 3 things to fix right now:', 'magenta'));
   console.log('');
+  let usagePatterns;
+  try { usagePatterns = require('./usage-patterns'); } catch { usagePatterns = null; }
   result.liteSummary.topNextActions.forEach((item, index) => {
     const tier = item.impact === 'critical' ? '🔴' : item.impact === 'high' ? '🟡' : '🔵';
-    console.log(`  ${index + 1}. ${tier} ${colorize(item.name, 'bold')}`);
+    const suppressed = usagePatterns && usagePatterns.getPriorityAdjustment(dir, item.key) === 'suppress';
+    const suffix = suppressed ? colorize(' (suppressed)', 'dim') : '';
+    console.log(`  ${index + 1}. ${tier} ${colorize(item.name, 'bold')}${suffix}`);
     console.log(colorize(`     ${item.fix}`, 'dim'));
   });
   console.log('');

package/src/fix-prompts.js

@@ -0,0 +1,122 @@
+/**
+ * AI-generated fix prompts for checks without template auto-fixes.
+ * Each key maps to a check key from techniques.js.
+ * These prompts are designed to be copy-pasted into an AI coding agent.
+ */
+
+const FIX_PROMPTS = {
+  importSyntax:
+    'Refactor CLAUDE.md to use @path imports for modularity. Split large sections into separate files (e.g. @docs/coding-style.md, @docs/architecture.md) and reference them with @path syntax. Also consider using .claude/rules/ for path-specific rules.',
+
+  underlines200:
+    'Refactor CLAUDE.md to be under 200 lines. Move detailed sections into separate files using @import or .claude/rules/ for path-specific rules. Keep only essential project overview, build commands, and key conventions in the main file.',
+
+  verificationLoop:
+    'Add a verification section to CLAUDE.md with commands Claude should run after making changes. Include test, lint, and build commands. Example:\n\n## Verification\nAfter every change, run:\n- `npm test` to verify tests pass\n- `npm run lint` to check code style\n- `npm run build` to verify compilation',
+
+  testCommand:
+    'Add an explicit test command to CLAUDE.md. Example: "Run `npm test` before committing." or "Run `pytest` to verify changes." Place it in a ## Commands or ## Verification section.',
+
+  lintCommand:
+    'Add a lint command to CLAUDE.md so the AI agent auto-checks code style. Example: "Run `npm run lint` or `eslint .` before committing." Place it in a ## Commands section.',
+
+  buildCommand:
+    'Add a build command to CLAUDE.md so the AI agent can verify compilation. Example: "Run `npm run build` or `tsc` to verify the project compiles." Place it in a ## Commands section.',
+
+  settingsPermissions:
+    'Create or update .claude/settings.json with permission configuration. Add "permissions": { "allow": ["Read", "Write src/**"], "deny": ["Write .env", "Write **/secrets/**"] } to control which tools and paths the AI agent can access.',
+
+  permissionDeny:
+    'Add deny rules to .claude/settings.json under permissions.deny to block dangerous operations. Example entries: "rm -rf /", "DROP TABLE", "Write .env", "Write **/*.pem", "Write **/secrets/**".',
+
+  noBypassPermissions:
+    'Remove bypassPermissions from your .claude/settings.json defaultMode. Instead, use explicit allow rules in permissions.allow to grant only the access needed.',
+
+  secretsProtection:
+    'Add permissions.deny rules in .claude/settings.json to block reading sensitive files. Add entries like: ".env", ".env.*", "**/.env", "**/*.pem", "**/secrets/**" to the deny array.',
+
+  securityReview:
+    'Add a /security-review command or mention security review in CLAUDE.md. Create .claude/commands/security-review.md with: "Review the codebase for OWASP Top 10 vulnerabilities. Check for: SQL injection, XSS, CSRF, insecure dependencies, hardcoded secrets, and misconfigured permissions."',
+
+  preToolUseHook:
+    'Add a PreToolUse hook in .claude/settings.json to validate tool calls before execution. Example: add a hook that blocks writes to protected files or validates file paths. See hooks documentation for the event schema.',
+
+  postToolUseHook:
+    'Add a PostToolUse hook in .claude/settings.json for automated actions after tool calls. Example: auto-run linting after file writes, or validate output format after code generation.',
+
+  sessionStartHook:
+    'Add a SessionStart hook in .claude/settings.json for initialization tasks. Example: load project state, rotate logs, or display a welcome message with project status at the start of each session.',
+
+  deployCommand:
+    'Create .claude/commands/deploy.md with deployment instructions. Include: pre-deploy checks (tests, lint, build), deployment steps for your platform (Vercel, AWS, etc.), and post-deploy verification.',
+
+  reviewCommand:
+    'Create .claude/commands/review.md with code review instructions. Include: check for security issues, verify test coverage, review naming conventions, check for code duplication, and validate error handling.',
+
+  compactionAwareness:
+    'Add compaction guidance to CLAUDE.md. Add a line like: "Run /compact when context gets heavy or before large operations." This helps the AI agent manage its context window effectively.',
+
+  contextManagement:
+    'Add context management tips to CLAUDE.md. Include: "Use /compact proactively at 70% capacity. Prefer targeted file reads over broad searches. Keep conversation focused on one task at a time."',
+
+  mcpServers:
+    'Create .mcp.json at the project root to configure MCP servers. Example:\n{\n  "mcpServers": {\n    "memory": { "command": "npx", "args": ["-y", "@anthropic/mcp-memory"] }\n  }\n}\nUse `claude mcp add <name>` to add servers interactively.',
+
+  context7Mcp:
+    'Add the Context7 MCP server for real-time documentation lookup. Add to .mcp.json:\n"context7": { "command": "npx", "args": ["-y", "@anthropic/context7-mcp"] }\nThis provides always-up-to-date library documentation.',
+
+  xmlTags:
+    'Add XML-tagged sections to CLAUDE.md for structured rules. Wrap critical rules in tags like <constraints>, <validation>, or <rules>. Example:\n<constraints>\n- Never modify package-lock.json manually\n- Always run tests before committing\n</constraints>',
+
+  fewShotExamples:
+    'Add code examples to CLAUDE.md showing preferred patterns. Include 2-3 examples of your coding style: naming conventions, error handling patterns, file structure. Use fenced code blocks with the appropriate language tag.',
+
+  roleDefinition:
+    'Add a role definition to the top of CLAUDE.md. Example: "You are a senior backend engineer working on a Node.js microservices platform. Prioritize type safety, comprehensive error handling, and test coverage."',
+
+  constraintBlocks:
+    'Add XML constraint blocks to CLAUDE.md for critical rules. Wrap must-follow rules in <constraints> tags for ~40% better adherence. Example:\n<constraints>\n- Never delete database migrations\n- Always use parameterized queries\n- Run the full test suite before committing\n</constraints>',
+
+  readme:
+    'Create a README.md with: project name and description, installation/setup instructions, usage examples, configuration options, and contribution guidelines.',
+
+  changelog:
+    'Create a CHANGELOG.md following Keep a Changelog format. Include sections: Added, Changed, Deprecated, Removed, Fixed, Security. Start with your current version.',
+
+  contributing:
+    'Create a CONTRIBUTING.md with: how to set up the dev environment, coding standards and style guide, pull request process, issue reporting guidelines, and code of conduct reference.',
+
+  editorconfig:
+    'Create a .editorconfig file at the project root with consistent formatting rules:\n[*]\nindent_style = space\nindent_size = 2\nend_of_line = lf\ncharset = utf-8\ntrim_trailing_whitespace = true\ninsert_final_newline = true',
+
+  ciPipeline:
+    'Add a CI pipeline for automated testing. For GitHub Actions, create .github/workflows/ci.yml with steps: checkout, setup Node/Python, install dependencies, run lint, run tests, run build.',
+
+  dockerfile:
+    'Create a Dockerfile for the project. Use a multi-stage build: stage 1 installs dependencies and builds, stage 2 copies only production artifacts. Use a slim base image and set a non-root user.',
+
+  noSecretsInClaude:
+    'Remove any API keys, tokens, or secrets from CLAUDE.md. Replace them with environment variable references (e.g. $API_KEY or process.env.API_KEY). Store actual values in .env files that are gitignored.',
+};
+
+/**
+ * Format a fix prompt for display in the terminal.
+ */
+function formatFixPrompt(key, prompt) {
+  const divider = '\u2500'.repeat(38);
+  const lines = [
+    '',
+    `  No auto-fix for '${key}'. Here's a prompt for your AI agent:`,
+    '',
+    `  ${divider}`,
+  ];
+  for (const line of prompt.split('\n')) {
+    lines.push(`  ${line}`);
+  }
+  lines.push(`  ${divider}`);
+  lines.push('');
+  lines.push('  Copy and paste this into Claude Code, Cursor, or your preferred AI agent.');
+  return lines.join('\n');
+}
+
+module.exports = { FIX_PROMPTS, formatFixPrompt };

package/src/usage-patterns.js

@@ -0,0 +1,99 @@
+const fs = require('fs');
+const path = require('path');
+const { ensureProjectStateDir, resolveProjectStateReadPath } = require('./state-paths');
+
+const PATTERNS_FILE = 'patterns.json';
+const SUPPRESS_THRESHOLD = 3;
+
+function patternsPath(dir, writable) {
+  if (writable) {
+    const feedbackDir = ensureProjectStateDir(dir, 'feedback');
+    return path.join(feedbackDir, PATTERNS_FILE);
+  }
+  const feedbackDir = resolveProjectStateReadPath(dir, 'feedback');
+  return path.join(feedbackDir, PATTERNS_FILE);
+}
+
+function loadPatterns(dir) {
+  const filePath = patternsPath(dir, false);
+  if (!fs.existsSync(filePath)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function savePatterns(dir, patterns) {
+  const filePath = patternsPath(dir, true);
+  fs.writeFileSync(filePath, JSON.stringify(patterns, null, 2), 'utf8');
+}
+
+function recordPattern(dir, checkKey, action) {
+  if (!['accepted', 'rejected', 'skipped'].includes(action)) return;
+  const patterns = loadPatterns(dir);
+  if (!patterns[checkKey]) {
+    patterns[checkKey] = { accepted: 0, rejected: 0, skipped: 0, lastAction: null, lastDate: null };
+  }
+  patterns[checkKey][action] += 1;
+  patterns[checkKey].lastAction = action;
+  patterns[checkKey].lastDate = new Date().toISOString();
+  savePatterns(dir, patterns);
+}
+
+function getPriorityAdjustment(dir, checkKey) {
+  const patterns = loadPatterns(dir);
+  const entry = patterns[checkKey];
+  if (!entry) return null;
+  const total = entry.accepted + entry.rejected;
+  if (total < 2) return null;
+  if (entry.accepted > 0 && entry.rejected === 0) return 'boost';
+  if (entry.rejected >= SUPPRESS_THRESHOLD && entry.accepted === 0) return 'suppress';
+  return null;
+}
+
+function getUsageSummary(dir) {
+  const patterns = loadPatterns(dir);
+  const keys = Object.keys(patterns);
+  const totalEvents = keys.reduce((sum, k) => {
+    const e = patterns[k];
+    return sum + e.accepted + e.rejected + e.skipped;
+  }, 0);
+
+  const withRates = keys
+    .filter(k => (patterns[k].accepted + patterns[k].rejected) > 0)
+    .map(k => {
+      const e = patterns[k];
+      const total = e.accepted + e.rejected;
+      return { key: k, accepted: e.accepted, rejected: e.rejected, total, rate: total > 0 ? e.accepted / total : 0 };
+    });
+
+  withRates.sort((a, b) => b.rate - a.rate || b.total - a.total);
+  const topAccepted = withRates.filter(e => e.rate > 0).slice(0, 5);
+  const topRejected = withRates.filter(e => e.rate < 1).sort((a, b) => a.rate - b.rate || b.total - a.total).slice(0, 5);
+
+  return { totalEvents, topAccepted, topRejected, patterns };
+}
+
+function formatUsageSummary(dir) {
+  const summary = getUsageSummary(dir);
+  if (summary.totalEvents === 0) return '  No usage patterns recorded yet.\n  Patterns are tracked when you run nerviq fix.';
+
+  const lines = [`  Usage Patterns (${summary.totalEvents} events recorded):`];
+  if (summary.topAccepted.length > 0) {
+    lines.push('', '  Most accepted:');
+    summary.topAccepted.forEach((e, i) => {
+      lines.push(`  ${i + 1}. ${e.key.padEnd(20)} ${e.accepted}/${e.total} (${Math.round(e.rate * 100)}%)`);
+    });
+  }
+  if (summary.topRejected.length > 0) {
+    lines.push('', '  Most rejected:');
+    summary.topRejected.forEach((e, i) => {
+      const hint = e.rate === 0 && e.total >= SUPPRESS_THRESHOLD ? ' -- consider suppressing' : '';
+      lines.push(`  ${i + 1}. ${e.key.padEnd(20)} ${e.accepted}/${e.total} (${Math.round(e.rate * 100)}%)${hint}`);
+    });
+  }
+  return lines.join('\n');
+}
+
+module.exports = { loadPatterns, recordPattern, getPriorityAdjustment, getUsageSummary, formatUsageSummary };