@nerviq/cli 1.13.0 → 1.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerviq/cli",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "description": "The intelligent nervous system for AI coding agents — 2,441 checks (8 platforms × ~300 governance rules), 10 languages, 62 domain packs. Audit, align, and amplify.",
   "main": "src/index.js",
   "bin": {

package/src/audit/recommendations.js

@@ -379,6 +379,7 @@ function buildTopNextActions(failed, limit = 5, outcomeSummaryByKey = {}, option
         sourceUrl,
         module: CATEGORY_MODULES[category] || category,
         fix,
+        remediation_command: getRemediationCommand(key, category, options.platform),
         priorityScore,
         why: ACTION_RATIONALES[key] || fix,
         risk: riskFromImpact(impact),
@@ -399,6 +400,51 @@ function buildTopNextActions(failed, limit = 5, outcomeSummaryByKey = {}, option
     });
 }
 
+/**
+ * Map check keys/categories to a shell command an agent can run to fix the issue.
+ * Returns null when no automated fix is available.
+ */
+function getRemediationCommand(key, category, platform) {
+  const plat = platform || 'claude';
+
+  // Key-specific remediation commands
+  const KEY_COMMANDS = {
+    claudeMd: 'npx @nerviq/cli setup',
+    agentsMd: 'npx @nerviq/cli setup --platform codex',
+    geminiMd: 'npx @nerviq/cli setup --platform gemini',
+    copilotInstructions: 'npx @nerviq/cli setup --platform copilot',
+    cursorRules: 'npx @nerviq/cli setup --platform cursor',
+    windsurfRules: 'npx @nerviq/cli setup --platform windsurf',
+    aiderConfig: 'npx @nerviq/cli setup --platform aider',
+    opencodeConfig: 'npx @nerviq/cli setup --platform opencode',
+    settingsPermissions: 'npx @nerviq/cli plan --only permissions',
+    permissionDeny: 'npx @nerviq/cli plan --only permissions',
+    noBypassPermissions: 'npx @nerviq/cli plan --only permissions',
+    secretsProtection: 'npx @nerviq/cli plan --only permissions',
+    verificationLoop: `npx @nerviq/cli augment --platform ${plat}`,
+    lintCommand: `npx @nerviq/cli augment --platform ${plat}`,
+    testCommand: `npx @nerviq/cli augment --platform ${plat}`,
+    buildCommand: `npx @nerviq/cli augment --platform ${plat}`,
+    hookExists: 'npx @nerviq/cli plan --only hooks',
+    preCommitHook: 'npx @nerviq/cli plan --only hooks',
+    commandsExist: 'npx @nerviq/cli plan --only commands',
+    mcpServers: 'npx @nerviq/cli plan --mcp-pack context7',
+  };
+
+  if (KEY_COMMANDS[key]) return KEY_COMMANDS[key];
+
+  // Category-level fallback
+  const CATEGORY_COMMANDS = {
+    memory: `npx @nerviq/cli setup --platform ${plat}`,
+    security: `npx @nerviq/cli plan --only permissions --platform ${plat}`,
+    automation: `npx @nerviq/cli plan --only hooks --platform ${plat}`,
+    workflow: `npx @nerviq/cli plan --only commands --platform ${plat}`,
+    tools: `npx @nerviq/cli plan --mcp-pack context7 --platform ${plat}`,
+  };
+
+  return CATEGORY_COMMANDS[category] || `npx @nerviq/cli augment --platform ${plat}`;
+}
+
 function getNextScoreMilestone(score) {
   return SCORE_MILESTONES.find((milestone) => score < milestone) || null;
 }

package/src/audit.js

@@ -2,7 +2,7 @@
  * Audit engine - evaluates project against NERVIQ technique database.
  */
 
-const { TECHNIQUES: CLAUDE_TECHNIQUES, STACKS, STACK_CATEGORY_DETECTORS } = require('./techniques');
+const { TECHNIQUES: CLAUDE_TECHNIQUES, STACKS, STACK_CATEGORY_DETECTORS } = require('./techniques');
 const { ProjectContext } = require('./context');
 const { CODEX_TECHNIQUES } = require('./codex/techniques');
 const { detectCodexDomainPacks } = require('./codex/domain-packs');
@@ -23,28 +23,28 @@ const { AiderProjectContext } = require('./aider/context');
 const { OPENCODE_TECHNIQUES } = require('./opencode/techniques');
 const { OpenCodeProjectContext } = require('./opencode/context');
 const { getBadgeMarkdown } = require('./badge');
-const { sendInsights, getLocalInsights } = require('./insights');
-const { getRecommendationOutcomeSummary } = require('./activity');
-const { getFeedbackSummary } = require('./feedback');
-const { formatSarif } = require('./formatters/sarif');
-const { formatOtelMetrics } = require('./formatters/otel');
-const { collectAuditTerminology, formatTerminologyLines } = require('./terminology');
-const { loadPlugins, mergePluginChecks } = require('./plugins');
-const { detectDeprecationWarnings } = require('./deprecation');
-const { buildWorkspaceHint, formatCount, guardSkippedInstructionFiles, inspectInstructionFiles } = require('./audit/instruction-files');
-const {
-  WEIGHTS,
-  buildScoreCoaching,
-  buildTopNextActions,
-  confidenceLabel,
-  computeCategoryScores,
-  getFpFeedbackMultiplier,
-  getQuickWins,
-  getRecommendationPriorityScore,
-  inferSuggestedNextCommand,
-} = require('./audit/recommendations');
-const { version: packageVersion } = require('../package.json');
-const { t } = require('./i18n');
+const { sendInsights, getLocalInsights } = require('./insights');
+const { getRecommendationOutcomeSummary } = require('./activity');
+const { getFeedbackSummary } = require('./feedback');
+const { formatSarif } = require('./formatters/sarif');
+const { formatOtelMetrics } = require('./formatters/otel');
+const { collectAuditTerminology, formatTerminologyLines } = require('./terminology');
+const { loadPlugins, mergePluginChecks } = require('./plugins');
+const { detectDeprecationWarnings } = require('./deprecation');
+const { buildWorkspaceHint, formatCount, guardSkippedInstructionFiles, inspectInstructionFiles } = require('./audit/instruction-files');
+const {
+  WEIGHTS,
+  buildScoreCoaching,
+  buildTopNextActions,
+  confidenceLabel,
+  computeCategoryScores,
+  getFpFeedbackMultiplier,
+  getQuickWins,
+  getRecommendationPriorityScore,
+  inferSuggestedNextCommand,
+} = require('./audit/recommendations');
+const { version: packageVersion } = require('../package.json');
+const { t } = require('./i18n');
 
 const COLORS = {
   reset: '\x1b[0m',
@@ -68,10 +68,10 @@ function progressBar(score, max = 100, width = 20) {
   return colorize('█'.repeat(filled), color) + colorize('░'.repeat(empty), 'dim');
 }
 
-function formatLocation(file, line) {
-  if (!file) return null;
-  return line ? `${file}:${line}` : file;
-}
+function formatLocation(file, line) {
+  if (!file) return null;
+  return line ? `${file}:${line}` : file;
+}
 
 function getAuditSpec(platform = 'claude') {
   if (platform === 'codex') {
@@ -153,7 +153,7 @@ function getAuditSpec(platform = 'claude') {
   };
 }
 
-function getPlatformScopeNote(spec, ctx) {
+function getPlatformScopeNote(spec, ctx) {
   if (spec.platform !== 'codex') {
     return null;
   }
@@ -242,7 +242,7 @@ function printLiteAudit(result, dir) {
     console.log(colorize(`  Found: ${result.detectedConfigFiles.join(', ')}`, 'dim'));
   }
   console.log('');
-  console.log(`  ${t('audit.score', { score: colorize(`${result.score}/100`, 'bold'), passed: result.passed, total: result.passed + result.failed })}`);
+  console.log(`  ${t('audit.score', { score: colorize(`${result.score}/100`, 'bold'), passed: result.passed, total: result.passed + result.failed })}`);
 
   // Score explanation line (lite mode only)
   const _critCount = (result.results || []).filter(r => r.passed === false && r.impact === 'critical').length;
@@ -265,14 +265,14 @@ function printLiteAudit(result, dir) {
     scoreExplanation = t('audit.basic', { category: weakestCategory });
   } else {
     scoreExplanation = t('audit.early');
-  }
-  console.log(colorize(`  ${scoreExplanation}`, 'dim'));
-  if (result.scoreCoaching) {
-    console.log(colorize(`  Milestone: ${result.scoreCoaching.summary}`, 'magenta'));
-  }
-  console.log(colorize('  Score type: live repo audit (current files only, not snapshot history or benchmark projection).', 'dim'));
-
-  if (result.platformScopeNote) {
+  }
+  console.log(colorize(`  ${scoreExplanation}`, 'dim'));
+  if (result.scoreCoaching) {
+    console.log(colorize(`  Milestone: ${result.scoreCoaching.summary}`, 'magenta'));
+  }
+  console.log(colorize('  Score type: live repo audit (current files only, not snapshot history or benchmark projection).', 'dim'));
+
+  if (result.platformScopeNote) {
     console.log(colorize(`  Scope: ${result.platformScopeNote.message}`, 'dim'));
   }
   if (result.workspaceHint && result.workspaceHint.workspaces.length > 0) {
@@ -284,11 +284,11 @@ function printLiteAudit(result, dir) {
       console.log(colorize(`     - ${item.title}: ${item.message}`, 'dim'));
     });
   }
-  if (result.largeInstructionFiles && result.largeInstructionFiles.length > 0) {
-    result.largeInstructionFiles.slice(0, 2).forEach((item) => {
-      console.log(colorize(`  Large file: ${item.file} (~${formatCount(item.tokenCount)} tokens)`, 'yellow'));
-    });
-  }
+  if (result.largeInstructionFiles && result.largeInstructionFiles.length > 0) {
+    result.largeInstructionFiles.slice(0, 2).forEach((item) => {
+      console.log(colorize(`  Large file: ${item.file} (~${formatCount(item.tokenCount)} tokens)`, 'yellow'));
+    });
+  }
   console.log('');
 
   if (result.failed === 0) {
@@ -320,23 +320,23 @@ function printLiteAudit(result, dir) {
   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' ? '🟡' : '🔵';
-    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('');
-  const liteTerminology = formatTerminologyLines(collectAuditTerminology(result));
-  if (liteTerminology.length > 0) {
-    liteTerminology.forEach((line) => {
-      const color = line.startsWith('  Terms used here:') ? 'blue' : 'dim';
-      console.log(colorize(line, color));
-    });
-    console.log('');
-  }
-  console.log(`  Ready? Run: ${colorize(result.suggestedNextCommand, 'bold')}`);
+  result.liteSummary.topNextActions.forEach((item, index) => {
+    const tier = item.impact === 'critical' ? '🔴' : item.impact === 'high' ? '🟡' : '🔵';
+    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('');
+  const liteTerminology = formatTerminologyLines(collectAuditTerminology(result));
+  if (liteTerminology.length > 0) {
+    liteTerminology.forEach((line) => {
+      const color = line.startsWith('  Terms used here:') ? 'blue' : 'dim';
+      console.log(colorize(line, color));
+    });
+    console.log('');
+  }
+  console.log(`  Ready? Run: ${colorize(result.suggestedNextCommand, 'bold')}`);
   if (result.platform === 'codex') {
     console.log(colorize('  Note: Codex now supports no-write advisory flows via augment and suggest-only before setup/apply.', 'dim'));
   }
@@ -387,7 +387,7 @@ async function audit(options) {
     'supply-chain', 'api-versioning', 'caching', 'rate-limiting', 'feature-flags',
     'docs-quality', 'monorepo', 'performance-budget', 'realtime', 'graphql',
     'testing-strategy', 'code-quality', 'api-design', 'database', 'authentication',
-    'monitoring', 'dependency-management', 'cost-optimization',
+    'monitoring', 'dependency-management', 'cost-optimization', 'devops',
   ]);
   const includeGenericQuality = options.verbose;
 
@@ -425,12 +425,12 @@ async function audit(options) {
       key: 'largeInstructionFile',
       id: null,
       name: 'Large instruction file warning',
-      category: 'performance',
-      impact: 'medium',
-      rating: null,
-      fix: 'Split oversized instruction files so they stay under ~12,000 tokens, and keep any single instruction file below ~240,000 tokens.',
-      sourceUrl: null,
-      confidence: 'high',
+      category: 'performance',
+      impact: 'medium',
+      rating: null,
+      fix: 'Split oversized instruction files so they stay under ~12,000 tokens, and keep any single instruction file below ~240,000 tokens.',
+      sourceUrl: null,
+      confidence: 'high',
       file: largeInstructionFiles[0].file,
       line: null,
       passed: null,
@@ -498,13 +498,13 @@ async function audit(options) {
     ...largeInstructionFiles.map((item) => ({
       kind: 'large-instruction-file',
       severity: item.severity,
-      message: item.message,
-      file: item.file,
-      lineCount: item.lineCount,
-      byteCount: item.byteCount,
-      tokenCount: item.tokenCount,
-      skipped: item.skipped,
-    })),
+      message: item.message,
+      file: item.file,
+      lineCount: item.lineCount,
+      byteCount: item.byteCount,
+      tokenCount: item.tokenCount,
+      skipped: item.skipped,
+    })),
     ...deprecationWarnings.map((item) => ({
       kind: 'deprecated-feature',
       severity: 'warning',
@@ -514,7 +514,7 @@ async function audit(options) {
   const recommendedDomainPacks = spec.platform === 'codex'
     ? detectCodexDomainPacks(ctx, stacks, getCodexDomainPackSignals(ctx))
     : [];
-  const result = {
+  const result = {
     platform: spec.platform,
     platformLabel: spec.platformLabel,
     platformVersion: spec.platformVersion,
@@ -537,18 +537,18 @@ async function audit(options) {
       deprecatedReason: r.deprecatedReason || null,
       sunsetDate: r.sunsetDate || null,
     })),
-    categoryScores,
-    scoreCoaching: buildScoreCoaching({
-      score,
-      earnedPoints: earnedScore,
-      maxPoints: maxScore,
-      failed,
-      outcomeSummaryByKey: outcomeSummary.byKey,
-      platform: spec.platform,
-      fpFeedbackByKey: fpFeedback.byKey,
-    }),
-    quickWins: quickWins.map(({ key, name, impact, fix, category, sourceUrl }) => ({ key, name, impact, category, fix, sourceUrl })),
-    topNextActions,
+    categoryScores,
+    scoreCoaching: buildScoreCoaching({
+      score,
+      earnedPoints: earnedScore,
+      maxPoints: maxScore,
+      failed,
+      outcomeSummaryByKey: outcomeSummary.byKey,
+      platform: spec.platform,
+      fpFeedbackByKey: fpFeedback.byKey,
+    }),
+    quickWins: quickWins.map(({ key, name, impact, fix, category, sourceUrl }) => ({ key, name, impact, category, fix, sourceUrl })),
+    topNextActions,
     recommendationOutcomes: {
       totalEntries: outcomeSummary.totalEntries,
       keysTracked: outcomeSummary.keys,
@@ -578,12 +578,12 @@ async function audit(options) {
   result.detectedConfigFiles = configFiles;
 
   result.suggestedNextCommand = inferSuggestedNextCommand(result);
-  result.liteSummary = {
-    topNextActions: topNextActions.slice(0, 3),
-    nextCommand: result.suggestedNextCommand,
-    platformCaveats: platformCaveats.slice(0, 2),
-    scoreCoaching: result.scoreCoaching,
-  };
+  result.liteSummary = {
+    topNextActions: topNextActions.slice(0, 3),
+    nextCommand: result.suggestedNextCommand,
+    platformCaveats: platformCaveats.slice(0, 2),
+    scoreCoaching: result.scoreCoaching,
+  };
 
   // Silent mode: skip all output, just return result
   if (silent) {
@@ -642,13 +642,13 @@ async function audit(options) {
     console.log('');
   }
 
-  if (largeInstructionFiles.length > 0) {
-    console.log(colorize('  Large instruction files', 'yellow'));
-    for (const item of largeInstructionFiles) {
-      const sizeKb = Number.isFinite(item.byteCount) ? Math.round(item.byteCount / 1024) : '?';
-      console.log(colorize(`     ${item.file} (~${formatCount(item.tokenCount)} tokens, ${item.lineCount || '?'} lines, ${sizeKb}KB)`, 'bold'));
-      console.log(colorize(`     → ${item.message}`, 'dim'));
-    }
+  if (largeInstructionFiles.length > 0) {
+    console.log(colorize('  Large instruction files', 'yellow'));
+    for (const item of largeInstructionFiles) {
+      const sizeKb = Number.isFinite(item.byteCount) ? Math.round(item.byteCount / 1024) : '?';
+      console.log(colorize(`     ${item.file} (~${formatCount(item.tokenCount)} tokens, ${item.lineCount || '?'} lines, ${sizeKb}KB)`, 'bold'));
+      console.log(colorize(`     → ${item.message}`, 'dim'));
+    }
     console.log('');
   }
 
@@ -678,18 +678,18 @@ async function audit(options) {
   console.log('');
 
   // Score
-  console.log(`  ${progressBar(score)} ${colorize(`${score}/100`, 'bold')}`);
-  if (isScaffolded && scaffoldedPassed.length > 0) {
-    console.log(colorize(`  Organic: ${organicScore}/100 (without nerviq generated files)`, 'dim'));
-  }
-  if (result.scoreCoaching) {
-    const fastestPath = result.scoreCoaching.recommendedNames.slice(0, 3).join(', ');
-    console.log(colorize(`  Milestone: ${result.scoreCoaching.summary}`, 'magenta'));
-    if (fastestPath) {
-      console.log(colorize(`  Fastest path: ${fastestPath}`, 'dim'));
-    }
-  }
-  console.log('');
+  console.log(`  ${progressBar(score)} ${colorize(`${score}/100`, 'bold')}`);
+  if (isScaffolded && scaffoldedPassed.length > 0) {
+    console.log(colorize(`  Organic: ${organicScore}/100 (without nerviq generated files)`, 'dim'));
+  }
+  if (result.scoreCoaching) {
+    const fastestPath = result.scoreCoaching.recommendedNames.slice(0, 3).join(', ');
+    console.log(colorize(`  Milestone: ${result.scoreCoaching.summary}`, 'magenta'));
+    if (fastestPath) {
+      console.log(colorize(`  Fastest path: ${fastestPath}`, 'dim'));
+    }
+  }
+  console.log('');
 
   // Passed
   if (passed.length > 0) {
@@ -755,8 +755,8 @@ async function audit(options) {
   }
 
   // Top next actions
-  if (topNextActions.length > 0) {
-    console.log(colorize('  ⚡ Top 5 Next Actions', 'magenta'));
+  if (topNextActions.length > 0) {
+    console.log(colorize('  ⚡ Top 5 Next Actions', 'magenta'));
     for (let i = 0; i < topNextActions.length; i++) {
       const item = topNextActions[i];
       console.log(`     ${i + 1}. ${colorize(item.name, 'bold')}`);
@@ -772,20 +772,20 @@ async function audit(options) {
         console.log(colorize(`        Feedback: accepted ${item.feedback.accepted}, rejected ${item.feedback.rejected}, positive ${item.feedback.positive}, negative ${item.feedback.negative}${avgDelta}`, 'dim'));
       }
       console.log(colorize(`        Fix: ${item.fix}`, 'dim'));
-    }
-    console.log('');
-  }
-
-  const terminology = formatTerminologyLines(collectAuditTerminology(result));
-  if (terminology.length > 0) {
-    terminology.forEach((line) => {
-      const color = line.startsWith('  Terms used here:') ? 'blue' : 'dim';
-      console.log(colorize(line, color));
-    });
-    console.log('');
-  }
-
-  // Summary
+    }
+    console.log('');
+  }
+
+  const terminology = formatTerminologyLines(collectAuditTerminology(result));
+  if (terminology.length > 0) {
+    terminology.forEach((line) => {
+      const color = line.startsWith('  Terms used here:') ? 'blue' : 'dim';
+      console.log(colorize(line, color));
+    });
+    console.log('');
+  }
+
+  // Summary
   console.log(colorize('  ─────────────────────────────────────', 'dim'));
   const deprecatedNote = deprecated.length > 0 ? colorize(`, ${deprecated.length} deprecated`, 'dim') : '';
   console.log(`  ${colorize(`${passed.length}/${applicable.length}`, 'bold')} checks passing${skipped.length > 0 ? colorize(` (${skipped.length} not applicable${deprecatedNote})`, 'dim') : (deprecatedNote ? colorize(` (${deprecatedNote})`, 'dim') : '')}`);

package/src/context.js

@@ -74,10 +74,32 @@ class ProjectContext {
 
   /**
    * Return the contents of the project's CLAUDE.md (root or .claude/ location).
+   * If CLAUDE.md contains only a reference to another file (e.g., "AGENTS.md"),
+   * follows that reference and returns the referenced file's content appended.
    * @returns {string|null} File content or null if not found.
    */
   claudeMdContent() {
-    return this.fileContent('CLAUDE.md') || this.fileContent('.claude/CLAUDE.md');
+    const raw = this.fileContent('CLAUDE.md') || this.fileContent('.claude/CLAUDE.md');
+    if (!raw) return null;
+
+    // If the file is very short and looks like a file reference, follow it.
+    // Pattern: a single line that is just a filename (e.g., "AGENTS.md" or "docs/CODING.md")
+    const trimmed = raw.trim();
+    if (trimmed.length < 200 && /^[a-zA-Z0-9_./-]+\.(md|txt|rst)$/m.test(trimmed)) {
+      const lines = trimmed.split(/\r?\n/).map(l => l.trim()).filter(Boolean);
+      let combined = raw;
+      for (const line of lines) {
+        if (/^[a-zA-Z0-9_./-]+\.(md|txt|rst)$/.test(line)) {
+          const referenced = this.fileContent(line);
+          if (referenced) {
+            combined += '\n' + referenced;
+          }
+        }
+      }
+      return combined;
+    }
+
+    return raw;
   }
 
   /**