@nerviq/cli 1.14.0 → 1.16.0

package/README.md

@@ -217,7 +217,7 @@ All successful operational responses are wrapped in a JSON envelope:
 {
   "data": {},
   "meta": {
-    "version": "1.14.0",
+    "version": "1.16.0",
     "timestamp": "2026-04-11T12:00:00.000Z"
   }
 }

package/bin/cli.js

@@ -8,6 +8,7 @@ const { getGovernanceSummary, printGovernanceSummary, ensureWritableProfile, ren
 const { runBenchmark, printBenchmark, writeBenchmarkReport } = require('../src/benchmark');
 const { writeSnapshotArtifact, writeRollbackArtifact, recordRecommendationOutcome, formatRecommendationOutcomeSummary, getRecommendationOutcomeSummary } = require('../src/activity');
 const { collectFeedback } = require('../src/feedback');
+const { collectAnonymousEvent } = require('../src/telemetry');
 const { recordPattern, getPriorityAdjustment, formatUsageSummary } = require('../src/usage-patterns');
 const { startServer } = require('../src/server');
 const { auditWorkspaces } = require('../src/workspace');
@@ -104,6 +105,7 @@ function parseArgs(rawArgs) {
   let format = null;
   let port = null;
   let workspace = null;
+  let targetDir = null;
   let webhookUrl = null;
   let webhookHeaders = [];
   let webhookRetries = null;
@@ -134,7 +136,7 @@ function parseArgs(rawArgs) {
   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' || arg === '--webhook-header' || arg === '--webhook-retries' || arg === '--external' || arg === '--team-profile' || arg === '--lang' || arg === '--tag' || arg === '--milestone' || arg === '--campaign' || arg === '--diff-base' || arg === '--diff-head' || arg === '--drift-mode' || arg === '--owner' || arg === '--reason' || arg === '--expires' || arg === '--scope' || arg === '--class') {
+    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 === '--dir' || arg === '--format' || arg === '--from' || arg === '--to' || arg === '--port' || arg === '--workspace' || arg === '--check-version' || arg === '--webhook' || arg === '--webhook-header' || arg === '--webhook-retries' || arg === '--external' || arg === '--team-profile' || arg === '--lang' || arg === '--tag' || arg === '--milestone' || arg === '--campaign' || arg === '--diff-base' || arg === '--diff-head' || arg === '--drift-mode' || arg === '--owner' || arg === '--reason' || arg === '--expires' || arg === '--scope' || arg === '--class') {
       const value = rawArgs[i + 1];
       if (!value || value.startsWith('--')) {
         throw new Error(`${arg} requires a value`);
@@ -153,6 +155,7 @@ function parseArgs(rawArgs) {
       if (arg === '--source') feedbackSource = value.trim();
       if (arg === '--score-delta') feedbackScoreDelta = value.trim();
       if (arg === '--platform') { platform = value.trim().toLowerCase(); platformExplicit = true; }
+      if (arg === '--dir') targetDir = require('path').resolve(value.trim());
       if (arg === '--format') format = value.trim().toLowerCase();
       if (arg === '--from') { convertFrom = value.trim(); migrateFrom = value.trim(); }
       if (arg === '--to') { convertTo = value.trim(); migrateTo = value.trim(); }
@@ -337,6 +340,11 @@ function parseArgs(rawArgs) {
       continue;
     }
 
+    if (arg.startsWith('--dir=')) {
+      targetDir = require('path').resolve(arg.split('=').slice(1).join('=').trim());
+      continue;
+    }
+
     if (arg.startsWith('--format=')) {
       format = arg.split('=').slice(1).join('=').trim().toLowerCase();
       continue;
@@ -388,7 +396,7 @@ function parseArgs(rawArgs) {
 
   const normalizedCommand = COMMAND_ALIASES[command] || command;
 
-  return { flags, command, commandExplicit, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks, requireChecks, feedbackKey, feedbackStatus, feedbackEffect, feedbackNotes, feedbackSource, feedbackScoreDelta, platform, platformExplicit, format, port, workspace, extraArgs, convertFrom, convertTo, migrateFrom, migrateTo, checkVersion, webhookUrl, webhookHeaders, webhookRetries, external, repos, teamProfile, lang, snapshotTags, snapshotMilestone, campaigns, diffBase, diffHead, driftMode, exceptionOwner, exceptionReason, exceptionExpires, exceptionScope, exceptionClass };
+  return { flags, command, commandExplicit, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks, requireChecks, feedbackKey, feedbackStatus, feedbackEffect, feedbackNotes, feedbackSource, feedbackScoreDelta, platform, platformExplicit, format, port, workspace, targetDir, extraArgs, convertFrom, convertTo, migrateFrom, migrateTo, checkVersion, webhookUrl, webhookHeaders, webhookRetries, external, repos, teamProfile, lang, snapshotTags, snapshotMilestone, campaigns, diffBase, diffHead, driftMode, exceptionOwner, exceptionReason, exceptionExpires, exceptionScope, exceptionClass };
 }
 
 function printWorkspaceSummary(summary, options) {
@@ -560,7 +568,8 @@ const HELP = `
   New here? Run: nerviq --beginner
 
   DISCOVER
-    nerviq audit                  Quick scan: score + top 3 gaps (default)
+    nerviq audit                  Quick scan: score + top 3 gaps (Harmony-first when 2+ platforms detected)
+    nerviq audit --no-harmony-first   Skip the cross-platform Harmony header
     nerviq audit --full           Full audit with all checks, weakest areas, badge
     nerviq audit --platform X     Audit specific platform (claude|codex|cursor|copilot|gemini|windsurf|aider|opencode)
     nerviq audit --json           Machine-readable JSON output (for CI)
@@ -663,6 +672,7 @@ const HELP = `
 
   OPTIONS
     --platform NAME   Platform: claude (default), codex, cursor, copilot, gemini, windsurf, aider, opencode
+    --dir PATH        Target directory to audit (default: current directory)
     --threshold N     Exit code 1 if score < N  (CI gate)
     --require A,B     Exit code 1 if named checks fail
     --out FILE        Write output to file (JSON or markdown)
@@ -694,6 +704,7 @@ const HELP = `
     --verbose         Full audit + medium-priority recommendations
     --show-deprecated Show deprecated checks (excluded from scoring)
     --json            Output as JSON
+    --agent-mode      Non-interactive JSON output for AI agents (setup/audit)
     --auto            Apply all generated files without prompting
     --beginner        Show only the 5 starter commands for first-time users
     --key NAME        Feedback: recommendation key (e.g. permissionDeny)
@@ -735,8 +746,9 @@ const HELP = `
     npx nerviq feedback --key permissionDeny --status accepted --effect positive
 
   EXIT CODES
-    0  Success
-    1  Error, unknown command, or score below --threshold
+    0  Success (score meets threshold, or no threshold set)
+    1  Threshold not met (score below --threshold)
+    2  Runtime error (unknown command, missing files, crash)
 `;
 
 const BEGINNER_HELP = `
@@ -770,7 +782,7 @@ async function main() {
     parsed = parseArgs(args);
   } catch (err) {
     console.error(`\n  Error: ${err.message}\n`);
-    process.exit(1);
+    process.exit(2);
   }
 
   const { flags, command, commandExplicit, normalizedCommand } = parsed;
@@ -807,6 +819,7 @@ async function main() {
     fix: flags.includes('--fix'),
     badge: flags.includes('--badge'),
     quiet: flags.includes('--quiet'),
+    agentMode: flags.includes('--agent-mode'),
     autoSync: flags.includes('--auto-sync'),
     dryRun: flags.includes('--dry-run'),
     configOnly: flags.includes('--config-only'),
@@ -834,6 +847,7 @@ async function main() {
     historyView: flags.includes('--history'),
     compareView: flags.includes('--compare'),
     diffOnly: flags.includes('--diff-only'),
+    noHarmonyFirst: flags.includes('--no-harmony-first'),
     diffBase: parsed.diffBase || null,
     diffHead: parsed.diffHead || null,
     driftMode: parsed.driftMode || null,
@@ -842,32 +856,32 @@ async function main() {
     exceptionExpires: parsed.exceptionExpires || null,
     exceptionScope: parsed.exceptionScope || null,
     exceptionClass: parsed.exceptionClass || null,
-    dir: process.cwd()
+    dir: parsed.targetDir || process.cwd()
   };
 
   if (options.snapshotTags.length > 0 && !options.snapshot) {
     console.error('\n  Error: --tag requires --snapshot.\n');
-    process.exit(1);
+    process.exit(2);
   }
 
   if (options.snapshotMilestone && !options.snapshot) {
     console.error('\n  Error: --milestone requires --snapshot.\n');
-    process.exit(1);
+    process.exit(2);
   }
 
   if (options.snapshotMilestone && !SNAPSHOT_MILESTONES.includes(options.snapshotMilestone)) {
     console.error(`\n  Error: Unsupported milestone '${options.snapshotMilestone}'. Use one of: ${SNAPSHOT_MILESTONES.join(', ')}.\n`);
-    process.exit(1);
+    process.exit(2);
   }
 
   if (options.diffOnly && options.snapshot) {
     console.error('\n  Error: --diff-only cannot be combined with --snapshot because diff-only scores are not comparable to full audit snapshots.\n');
-    process.exit(1);
+    process.exit(2);
   }
 
   if (options.driftMode && !['ci', 'pr', 'watch'].includes(options.driftMode)) {
     console.error(`\n  Error: Unsupported drift mode '${options.driftMode}'. Use ci, pr, or watch.\n`);
-    process.exit(1);
+    process.exit(2);
   }
 
   if (parsed.checkVersion) {
@@ -967,7 +981,7 @@ async function main() {
       console.error('  Fix: Run nerviq --help to see all available commands.');
     }
     console.error('  Docs: https://github.com/nerviq/nerviq#readme\n');
-    process.exit(1);
+    process.exit(2);
   }
 
   if (!require('fs').existsSync(options.dir)) {
@@ -975,7 +989,7 @@ async function main() {
     console.error('  Why: The current working directory does not exist or is not accessible.');
     console.error('  Fix: cd into your project directory first, then run nerviq.');
     console.error('  Docs: https://github.com/nerviq/nerviq#getting-started\n');
-    process.exit(1);
+    process.exit(2);
   }
 
   if (['setup', 'apply', 'benchmark'].includes(normalizedCommand)) {
@@ -1002,7 +1016,7 @@ async function main() {
       if (!FULL_COMMAND_SET.has(normalizedCommand)) {
         console.error(`\n  Error: '${normalizedCommand}' is not supported for --platform codex.`);
         console.error('  Available: ' + [...FULL_COMMAND_SET].filter(c => c !== 'help' && c !== 'version').join(', ') + '.');
-        process.exit(1);
+        process.exit(2);
       }
     }
 
@@ -1010,7 +1024,7 @@ async function main() {
       if (!FULL_COMMAND_SET.has(normalizedCommand)) {
         console.error(`\n  Error: '${normalizedCommand}' is not supported for --platform gemini.`);
         console.error('  Available: ' + [...FULL_COMMAND_SET].filter(c => c !== 'help' && c !== 'version').join(', ') + '.');
-        process.exit(1);
+        process.exit(2);
       }
     }
 
@@ -1018,7 +1032,7 @@ async function main() {
       if (!FULL_COMMAND_SET.has(normalizedCommand)) {
         console.error(`\n  Error: '${normalizedCommand}' is not supported for --platform copilot.`);
         console.error('  Available: ' + [...FULL_COMMAND_SET].filter(c => c !== 'help' && c !== 'version').join(', ') + '.');
-        process.exit(1);
+        process.exit(2);
       }
     }
 
@@ -1026,7 +1040,7 @@ async function main() {
       if (!FULL_COMMAND_SET.has(normalizedCommand)) {
         console.error(`\n  Error: '${normalizedCommand}' is not supported for --platform cursor.`);
         console.error('  Available: ' + [...FULL_COMMAND_SET].filter(c => c !== 'help' && c !== 'version').join(', ') + '.');
-        process.exit(1);
+        process.exit(2);
       }
     }
 
@@ -1035,7 +1049,7 @@ async function main() {
         if (!FULL_COMMAND_SET.has(normalizedCommand)) {
           console.error(`\n  Error: '${normalizedCommand}' is not supported for --platform ${plat}.`);
           console.error('  Available: ' + [...FULL_COMMAND_SET].filter(c => c !== 'help' && c !== 'version').join(', ') + '.');
-          process.exit(1);
+          process.exit(2);
         }
       }
     }
@@ -1045,7 +1059,7 @@ async function main() {
       if (scanDirs.length === 0) {
         console.error('\n  Error: scan requires at least one directory argument.');
         console.error('  Usage: npx nerviq scan dir1 dir2 dir3\n');
-        process.exit(1);
+        process.exit(2);
       }
       const summary = await scanOrg(scanDirs, options);
       printScanDetail(summary, options);
@@ -1073,7 +1087,7 @@ async function main() {
         console.error('\n  Error: org requires `scan` or `policy`.');
         console.error('  Usage: npx nerviq org scan dir1 dir2 dir3');
         console.error('         npx nerviq org policy [dir]\n');
-        process.exit(1);
+        process.exit(2);
       }
       const summary = await scanOrg(scanDirs, options);
       if (options.json) {
@@ -1617,6 +1631,7 @@ async function main() {
       return;
     } else if (normalizedCommand === 'harmony-audit') {
       const { runHarmonyAudit } = require('../src/harmony/cli');
+      collectAnonymousEvent('harmony-audit', { dir: options.dir });
       await runHarmonyAudit(options);
       process.exit(0);
     } else if (normalizedCommand === 'harmony-sync') {
@@ -2448,7 +2463,29 @@ async function main() {
       await runInit(options.dir, flags);
       process.exit(0);
     } else if (normalizedCommand === 'setup') {
-      await setup(options);
+      collectAnonymousEvent('setup', { platform: options.platform, dir: options.dir });
+      const setupResult = await setup({ ...options, silent: options.agentMode || options.json });
+      if (options.agentMode) {
+        // Agent-mode: structured JSON output with next steps
+        const postAudit = await audit({ dir: options.dir, silent: true, platform: options.platform });
+        const agentOutput = {
+          status: setupResult.created > 0 ? 'files_created' : 'already_configured',
+          created: setupResult.created,
+          skipped: setupResult.skipped,
+          written_files: setupResult.writtenFiles,
+          preserved_files: setupResult.preservedFiles,
+          detected_stacks: setupResult.stacks.map(s => s.key),
+          rollback_id: setupResult.rollbackId,
+          post_setup_score: postAudit.score,
+          next_commands: [
+            'npx @nerviq/cli audit --json',
+            setupResult.created > 0 ? `npx @nerviq/cli augment --platform ${options.platform}` : null,
+            postAudit.score < 70 ? 'npx @nerviq/cli plan' : null,
+          ].filter(Boolean),
+        };
+        console.log(JSON.stringify(agentOutput, null, 2));
+        process.exit(0);
+      }
       if (options.snapshot) {
         const postSetupResult = await audit({ dir: options.dir, silent: true, platform: options.platform });
         const snapshot = writeSnapshotArtifact(options.dir, 'audit', postSetupResult, {
@@ -2469,8 +2506,32 @@ async function main() {
         }
         process.exit(0);
       }
+      // MOAT-01: Harmony-first default — when 2+ platforms and platform not explicit
+      let harmonyFirstResult = null;
+      if (!options.platformExplicit && !options.noHarmonyFirst && !options.diffOnly && !options.driftMode && !options.workspace) {
+        const detected = detectPlatforms(options.dir) || [];
+        if (detected.length >= 2) {
+          try {
+            const { harmonyAudit } = require('../src/harmony/audit');
+            harmonyFirstResult = await harmonyAudit({ dir: options.dir, silent: true });
+            if (!options.json && harmonyFirstResult) {
+              const hs = harmonyFirstResult.harmonyScore;
+              const driftCount = (harmonyFirstResult.drift && harmonyFirstResult.drift.drifts) ? harmonyFirstResult.drift.drifts.length : 0;
+              const platformLabels = (harmonyFirstResult.activePlatforms || []).map(p => p.label || p.platform).join(' + ');
+              const color = hs >= 70 ? '\x1b[32m' : hs >= 40 ? '\x1b[33m' : '\x1b[31m';
+              const issueWord = driftCount === 1 ? 'issue' : 'issues';
+              console.log('');
+              console.log(`\x1b[1m  Harmony Score: ${color}${hs}/100\x1b[0m — ${driftCount} drift ${issueWord} across ${detected.length} platforms (${platformLabels})`);
+              console.log('\x1b[2m  Run `nerviq harmony-audit` for the full cross-platform report. Use --no-harmony-first to hide.\x1b[0m');
+            }
+          } catch {
+            harmonyFirstResult = null;
+          }
+        }
+      }
+
       let result;
-      const renderAuditJsonLocally = options.json && Boolean(options.driftMode);
+      const renderAuditJsonLocally = options.json && (Boolean(options.driftMode) || Boolean(harmonyFirstResult));
       if (options.diffOnly) {
         const { getChangedFiles, buildDiffOnlyAuditView, printDiffOnlyAudit } = require('../src/diff-only');
         const fullResult = await audit({ ...options, silent: true });
@@ -2485,6 +2546,14 @@ async function main() {
           : await audit(options);
       }
 
+      // ── Telemetry (opt-in, local only) ──
+      collectAnonymousEvent('audit', {
+        platform: result.platform || options.platform,
+        score: result.score,
+        checkCount: Array.isArray(result.results) ? result.results.length : null,
+        dir: options.dir,
+      });
+
       if (options.driftMode) {
         const { buildContinuousStatus, formatContinuousStatus } = require('../src/continuous-ops');
         let campaigns = [];
@@ -2537,9 +2606,17 @@ async function main() {
           }
         }
       } else if (renderAuditJsonLocally) {
+        const harmonyEnvelope = harmonyFirstResult ? {
+          harmony: {
+            score: harmonyFirstResult.harmonyScore,
+            driftCount: (harmonyFirstResult.drift && harmonyFirstResult.drift.drifts) ? harmonyFirstResult.drift.drifts.length : 0,
+            platforms: (harmonyFirstResult.activePlatforms || []).map(p => p.platform),
+          },
+        } : {};
         console.log(JSON.stringify({
           version,
           timestamp: new Date().toISOString(),
+          ...harmonyEnvelope,
           ...result,
         }, null, 2));
       } else {
@@ -2664,7 +2741,7 @@ async function main() {
   } catch (err) {
     console.error(`\n  Error: ${err.message}`);
     console.error('  Fix: Run `npx nerviq doctor` to diagnose common issues, or check https://github.com/nerviq/nerviq#troubleshooting');
-    process.exit(1);
+    process.exit(2);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerviq/cli",
-  "version": "1.14.0",
+  "version": "1.16.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/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;
   }
 
   /**