@nerviq/cli 1.5.3 → 1.6.1

package/README.md

@@ -310,6 +310,7 @@ Every write command supports `--snapshot` for automatic backup before changes.
 - **npm**: [@nerviq/cli](https://www.npmjs.com/package/@nerviq/cli)
 - **GitHub**: [github.com/nerviq/nerviq](https://github.com/nerviq/nerviq)
 - **Website**: [nerviq.net](https://nerviq.net)
+- **Discord**: [Join the community](https://discord.gg/nerviq)
 
 ## What Nerviq Is — and Isn't
 

package/bin/cli.js

@@ -26,7 +26,7 @@ const COMMAND_ALIASES = {
   gov: 'governance',
   outcome: 'feedback',
 };
-const KNOWN_COMMANDS = ['audit', 'org', 'setup', 'augment', 'suggest-only', 'plan', 'apply', 'fix', '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'];
+const KNOWN_COMMANDS = ['audit', 'org', 'setup', 'augment', 'suggest-only', 'plan', 'apply', 'fix', 'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'badge', 'insights', 'history', 'compare', 'trend', 'scan', 'feedback', 'doctor', 'convert', 'migrate', 'catalog', 'certify', 'serve', 'check-health', '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));
@@ -305,6 +305,7 @@ const HELP = `
     nerviq setup                  Generate starter-safe baseline config files
     nerviq setup --auto           Apply all generated files without prompts
     nerviq interactive            Step-by-step guided wizard
+    nerviq check-health           Detect regressions + platform format changes between snapshots
     nerviq doctor                 Self-diagnostics: Node, deps, freshness, platform detection
 
   FIX
@@ -1041,6 +1042,16 @@ async function main() {
         console.log(output);
       }
       process.exit(0);
+    } else if (normalizedCommand === 'check-health') {
+      const { checkHealth, formatCheckHealth } = require('../src/activity');
+      const report = checkHealth(options.dir);
+      if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+      } else {
+        console.log('');
+        console.log(formatCheckHealth(report));
+      }
+      process.exit(0);
     } else if (normalizedCommand === 'freshness') {
       const { TECHNIQUES } = require('../src/techniques');
       const stats = getVerificationStats();

package/package.json

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

package/src/activity.js

@@ -533,6 +533,170 @@ function formatRecommendationOutcomeSummary(dir) {
   return lines.join('\n');
 }
 
+/**
+ * Load the full payload of a snapshot by its index entry.
+ * @param {string} dir - Project root directory.
+ * @param {Object} indexEntry - Snapshot index entry with relativePath.
+ * @returns {Object|null} Full snapshot envelope, or null if unreadable.
+ */
+function loadSnapshotPayload(dir, indexEntry) {
+  if (!indexEntry || !indexEntry.relativePath) return null;
+  const filePath = path.join(dir, indexEntry.relativePath);
+  try {
+    const envelope = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return envelope.payload || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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.
+ *
+ * @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);
+  if (history.length < 2) return null;
+
+  const currentPayload = loadSnapshotPayload(dir, history[0]);
+  const previousPayload = loadSnapshotPayload(dir, history[1]);
+  if (!currentPayload || !previousPayload) return null;
+
+  const currentResults = currentPayload.results || [];
+  const previousResults = previousPayload.results || [];
+
+  // Build maps: key → passed (true/false/null)
+  const prevMap = {};
+  for (const r of previousResults) {
+    if (r.key) prevMap[r.key] = r.passed;
+  }
+  const currMap = {};
+  for (const r of currentResults) {
+    if (r.key) currMap[r.key] = r.passed;
+  }
+
+  const regressions = []; // was passing → now failing
+  const improvements = []; // was failing → now passing
+  const newChecks = []; // not in previous
+  const removedChecks = []; // not in current
+
+  for (const r of currentResults) {
+    if (!r.key) continue;
+    const prev = prevMap[r.key];
+    const curr = r.passed;
+    if (prev === undefined) {
+      if (curr !== null) newChecks.push({ key: r.key, name: r.name, impact: r.impact, passed: curr });
+      continue;
+    }
+    if (prev === true && curr === false) {
+      regressions.push({ key: r.key, name: r.name, impact: r.impact, category: r.category });
+    } else if (prev === false && curr === true) {
+      improvements.push({ key: r.key, name: r.name, impact: r.impact, category: r.category });
+    }
+  }
+
+  for (const r of previousResults) {
+    if (r.key && currMap[r.key] === undefined) {
+      removedChecks.push({ key: r.key, name: r.name });
+    }
+  }
+
+  // Detect potential platform format changes:
+  // If 3+ checks in the same category regressed, flag it
+  const regressionsByCategory = {};
+  for (const r of regressions) {
+    if (!regressionsByCategory[r.category]) regressionsByCategory[r.category] = [];
+    regressionsByCategory[r.category].push(r);
+  }
+  const platformAlerts = [];
+  for (const [cat, items] of Object.entries(regressionsByCategory)) {
+    if (items.length >= 3) {
+      platformAlerts.push({
+        category: cat,
+        regressionCount: items.length,
+        message: `${items.length} checks in '${cat}' regressed — possible platform format change`,
+        checks: items.map(i => i.key),
+      });
+    }
+  }
+
+  return {
+    currentDate: history[0].createdAt,
+    previousDate: history[1].createdAt,
+    scoreDelta: (currentPayload.score || 0) - (previousPayload.score || 0),
+    regressions,
+    improvements,
+    newChecks,
+    removedChecks,
+    platformAlerts,
+    summary: {
+      regressionsCount: regressions.length,
+      improvementsCount: improvements.length,
+      newChecksCount: newChecks.length,
+      removedChecksCount: removedChecks.length,
+      alertsCount: platformAlerts.length,
+    },
+  };
+}
+
+/**
+ * Format check-health report for CLI display.
+ */
+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 sign = scoreDelta >= 0 ? '+' : '';
+
+  lines.push(`  Check Health Report`);
+  lines.push(`  ─────────────────────────────────────`);
+  lines.push(`  Period: ${healthReport.previousDate?.split('T')[0]} → ${healthReport.currentDate?.split('T')[0]}`);
+  lines.push(`  Score delta: ${sign}${scoreDelta}`);
+  lines.push('');
+
+  if (platformAlerts.length > 0) {
+    lines.push(`  ⚠️  PLATFORM ALERTS (${platformAlerts.length})`);
+    for (const alert of platformAlerts) {
+      lines.push(`     ${alert.message}`);
+      lines.push(`     Checks: ${alert.checks.join(', ')}`);
+    }
+    lines.push('');
+  }
+
+  if (regressions.length > 0) {
+    lines.push(`  🔴 Regressions (${regressions.length} checks now failing)`);
+    for (const r of regressions) {
+      lines.push(`     ${r.name} [${r.impact}]`);
+    }
+    lines.push('');
+  }
+
+  if (improvements.length > 0) {
+    lines.push(`  ✅ Improvements (${improvements.length} checks now passing)`);
+    for (const r of improvements) {
+      lines.push(`     ${r.name}`);
+    }
+    lines.push('');
+  }
+
+  if (newChecks.length > 0) {
+    lines.push(`  🆕 New checks (${newChecks.length})`);
+    lines.push('');
+  }
+
+  if (regressions.length === 0 && platformAlerts.length === 0) {
+    lines.push(`  ✅ All checks stable. No regressions detected.`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
 module.exports = {
   getUserId,
   ensureArtifactDirs,
@@ -550,4 +714,7 @@ module.exports = {
   getRecommendationOutcomeSummary,
   getRecommendationAdjustment,
   formatRecommendationOutcomeSummary,
+  checkHealth,
+  formatCheckHealth,
+  loadSnapshotPayload,
 };

package/src/audit.js

@@ -3,7 +3,7 @@
  */
 
 const path = require('path');
-const { TECHNIQUES: CLAUDE_TECHNIQUES, STACKS } = 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');
@@ -907,9 +907,9 @@ function printLiteAudit(result, dir) {
     return;
   }
 
-  // Urgency summary line
-  const criticalCount = (result.results || []).filter(r => !r.passed && r.impact === 'critical').length;
-  const highCount = (result.results || []).filter(r => !r.passed && r.impact === 'high').length;
+  // Urgency summary line (only count actual failures, not skipped/null)
+  const criticalCount = (result.results || []).filter(r => r.passed === false && r.impact === 'critical').length;
+  const highCount = (result.results || []).filter(r => r.passed === false && r.impact === 'high').length;
   const mediumCount = result.failed - criticalCount - highCount;
   const urgencyParts = [];
   if (criticalCount > 0) urgencyParts.push(colorize(`🔴 ${criticalCount} critical`, 'red'));
@@ -964,8 +964,40 @@ async function audit(options) {
     ? mergePluginChecks(spec.techniques, plugins)
     : spec.techniques;
 
+  // Pre-compute which stack categories are active for this project
+  const activeStackCategories = new Set();
+  for (const [category, detector] of Object.entries(STACK_CATEGORY_DETECTORS)) {
+    if (detector(ctx)) activeStackCategories.add(category);
+  }
+
+  // Generic quality categories that are NOT about AI agent configuration.
+  // These are only included with --verbose or --full --verbose (deep quality mode).
+  const GENERIC_QUALITY_CATEGORIES = new Set([
+    'observability', 'accessibility', 'i18n', 'privacy', 'error-tracking',
+    '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',
+  ]);
+  const includeGenericQuality = options.verbose;
+
   // Run all technique checks
   for (const [key, technique] of Object.entries(techniques)) {
+    // Skip entire stack category if the stack is not detected at a core location
+    // Skip generic quality categories unless --verbose is set
+    const cat = technique.category;
+    if ((!includeGenericQuality && GENERIC_QUALITY_CATEGORIES.has(cat)) ||
+        (STACK_CATEGORY_DETECTORS[cat] && !activeStackCategories.has(cat))) {
+      results.push({
+        key,
+        ...technique,
+        file: null,
+        line: null,
+        passed: null, // not applicable
+      });
+      continue;
+    }
+
     const passed = technique.check(ctx);
     const file = typeof technique.file === 'function' ? (technique.file(ctx) ?? null) : (technique.file ?? null);
     const line = typeof technique.line === 'function' ? (technique.line(ctx) ?? null) : (technique.line ?? null);

package/src/harmony/cli.js

@@ -28,66 +28,21 @@ function resolveDir(options) {
 
 /**
  * Collect audit results from all detectable platforms.
- * This is a lightweight aggregation - each platform module is loaded lazily.
+ * Runs audit() for each platform in sequence (audit is async).
  */
-function collectPlatformAudits(dir) {
+async function collectPlatformAudits(dir) {
+  const { audit } = require('../audit');
+  const platforms = ['claude', 'codex', 'gemini', 'copilot', 'cursor', 'windsurf', 'aider', 'opencode'];
   const results = [];
 
-  // Try Claude audit
-  try {
-    const { audit } = require('../audit');
-    const result = audit({ dir, silent: true, platform: 'claude' });
-    if (result) results.push({ platform: 'claude', ...result });
-  } catch (_e) { /* platform not available */ }
-
-  // Try Codex audit
-  try {
-    const { audit } = require('../audit');
-    const result = audit({ dir, silent: true, platform: 'codex' });
-    if (result) results.push({ platform: 'codex', ...result });
-  } catch (_e) { /* platform not available */ }
-
-  // Try Gemini audit
-  try {
-    const { audit } = require('../audit');
-    const result = audit({ dir, silent: true, platform: 'gemini' });
-    if (result) results.push({ platform: 'gemini', ...result });
-  } catch (_e) { /* platform not available */ }
-
-  // Try Copilot audit
-  try {
-    const { audit } = require('../audit');
-    const result = audit({ dir, silent: true, platform: 'copilot' });
-    if (result) results.push({ platform: 'copilot', ...result });
-  } catch (_e) { /* platform not available */ }
-
-  // Try Cursor audit
-  try {
-    const { audit } = require('../audit');
-    const result = audit({ dir, silent: true, platform: 'cursor' });
-    if (result) results.push({ platform: 'cursor', ...result });
-  } catch (_e) { /* platform not available */ }
-
-  // Try Windsurf audit
-  try {
-    const { audit } = require('../audit');
-    const result = audit({ dir, silent: true, platform: 'windsurf' });
-    if (result) results.push({ platform: 'windsurf', ...result });
-  } catch (_e) { /* platform not available */ }
-
-  // Try Aider audit
-  try {
-    const { audit } = require('../audit');
-    const result = audit({ dir, silent: true, platform: 'aider' });
-    if (result) results.push({ platform: 'aider', ...result });
-  } catch (_e) { /* platform not available */ }
-
-  // Try OpenCode audit
-  try {
-    const { audit } = require('../audit');
-    const result = audit({ dir, silent: true, platform: 'opencode' });
-    if (result) results.push({ platform: 'opencode', ...result });
-  } catch (_e) { /* platform not available */ }
+  for (const platform of platforms) {
+    try {
+      const result = await audit({ dir, silent: true, platform });
+      if (result && typeof result.score === 'number') {
+        results.push({ platform, ...result });
+      }
+    } catch (_e) { /* platform not available */ }
+  }
 
   return results;
 }
@@ -99,7 +54,7 @@ function collectPlatformAudits(dir) {
  */
 async function runHarmonyAudit(options) {
   const dir = resolveDir(options);
-  const platformAudits = collectPlatformAudits(dir);
+  const platformAudits = await collectPlatformAudits(dir);
 
   if (options.json) {
     console.log(JSON.stringify({ dir, platforms: platformAudits }, null, 2));
@@ -147,7 +102,7 @@ async function runHarmonyAudit(options) {
  */
 async function runHarmonySync(options) {
   const dir = resolveDir(options);
-  const platformAudits = collectPlatformAudits(dir);
+  const platformAudits = await collectPlatformAudits(dir);
 
   // Load or build canonical model from memory
   const state = loadHarmonyState(dir);
@@ -234,7 +189,7 @@ async function runHarmonyDrift(options) {
  */
 async function runHarmonyAdvise(options) {
   const dir = resolveDir(options);
-  const platformAudits = collectPlatformAudits(dir);
+  const platformAudits = await collectPlatformAudits(dir);
   const state = loadHarmonyState(dir);
   const canonicalModel = state.canon || null;
 
@@ -309,7 +264,7 @@ async function runHarmonyWatch(options) {
       // Logged by watch module itself
     },
     runAudit: options.noAudit ? null : async (auditDir) => {
-      const audits = collectPlatformAudits(auditDir);
+      const audits = await collectPlatformAudits(auditDir);
       const result = {};
       for (const audit of audits) {
         result[audit.platform] = audit;
@@ -326,7 +281,7 @@ async function runHarmonyWatch(options) {
  */
 async function runHarmonyGovernance(options) {
   const dir = resolveDir(options);
-  const platformAudits = collectPlatformAudits(dir);
+  const platformAudits = await collectPlatformAudits(dir);
   const state = loadHarmonyState(dir);
   const canonicalModel = state.canon || null;
 

package/src/techniques.js

@@ -95,6 +95,26 @@ function hasProjectFile(ctx, pattern) {
   return findProjectFiles(ctx, pattern).length > 0;
 }
 
+/**
+ * Check if a stack-indicator file exists at a "core" location (root, src/, lib/, app/, packages/)
+ * rather than inside examples/, docs/, test/, vendor/, or deeply nested paths.
+ * This prevents false stack detection from example/demo code.
+ */
+const EXCLUDED_STACK_DIRS = /^(examples?|docs?|test|tests|fixtures?|samples?|demo|vendor|third[_-]?party|\.github)\//i;
+
+function hasCoreProjectFile(ctx, pattern) {
+  return findProjectFiles(ctx, pattern).some(file => !EXCLUDED_STACK_DIRS.test(file));
+}
+
+function hasCoreRootFile(ctx, pattern) {
+  // Only match files at project root (no / in path) or one level deep (src/X, lib/X, app/X)
+  return findProjectFiles(ctx, pattern).some(file => {
+    if (EXCLUDED_STACK_DIRS.test(file)) return false;
+    const depth = (file.match(/\//g) || []).length;
+    return depth <= 1;
+  });
+}
+
 function readProjectFiles(ctx, pattern, limit = 60) {
   return findProjectFiles(ctx, pattern)
     .slice(0, limit)
@@ -105,40 +125,42 @@ function readProjectFiles(ctx, pattern, limit = 60) {
 
 function isPythonProject(ctx) {
   if (ctx.__nerviqIsPython !== undefined) return ctx.__nerviqIsPython;
+  // Require a Python config file (pyproject.toml, requirements.txt, setup.py) at a core location.
+  // Stray .py files in examples/ or docs/ don't make it a Python project.
   ctx.__nerviqIsPython =
-    hasProjectFile(ctx, /(^|\/)(pyproject\.toml|requirements[^/]*\.txt|setup\.py)$/i) ||
-    hasProjectFile(ctx, /\.py$/i);
+    hasCoreRootFile(ctx, /(^|\/)(pyproject\.toml|setup\.py|Pipfile)$/i) ||
+    hasCoreRootFile(ctx, /(^|\/)requirements\.txt$/i);
   return ctx.__nerviqIsPython;
 }
 
 function isGoProject(ctx) {
   if (ctx.__nerviqIsGo !== undefined) return ctx.__nerviqIsGo;
-  ctx.__nerviqIsGo = hasProjectFile(ctx, /(^|\/)go\.mod$/i);
+  ctx.__nerviqIsGo = hasCoreRootFile(ctx, /(^|\/)go\.mod$/i);
   return ctx.__nerviqIsGo;
 }
 
 function isRustProject(ctx) {
   if (ctx.__nerviqIsRust !== undefined) return ctx.__nerviqIsRust;
-  ctx.__nerviqIsRust = hasProjectFile(ctx, /(^|\/)Cargo\.toml$/i);
+  ctx.__nerviqIsRust = hasCoreRootFile(ctx, /(^|\/)Cargo\.toml$/i);
   return ctx.__nerviqIsRust;
 }
 
 function isJavaProject(ctx) {
   if (ctx.__nerviqIsJava !== undefined) return ctx.__nerviqIsJava;
-  ctx.__nerviqIsJava = hasProjectFile(ctx, /(^|\/)(pom\.xml|build\.gradle|build\.gradle\.kts)$/i);
+  ctx.__nerviqIsJava = hasCoreRootFile(ctx, /(^|\/)(pom\.xml|build\.gradle|build\.gradle\.kts)$/i);
   return ctx.__nerviqIsJava;
 }
 
 function isFlutterProject(ctx) {
   if (ctx.__nerviqIsFlutter !== undefined) return ctx.__nerviqIsFlutter;
-  ctx.__nerviqIsFlutter = hasProjectFile(ctx, /(^|\/)pubspec\.yaml$/i);
+  ctx.__nerviqIsFlutter = hasCoreRootFile(ctx, /(^|\/)pubspec\.yaml$/i);
   return ctx.__nerviqIsFlutter;
 }
 
 function isSwiftProject(ctx) {
   if (ctx.__nerviqIsSwift !== undefined) return ctx.__nerviqIsSwift;
-  ctx.__nerviqIsSwift = hasProjectFile(ctx, /(^|\/)Package\.swift$/i) ||
-    hasProjectFile(ctx, /\.xcodeproj/i);
+  ctx.__nerviqIsSwift = hasCoreRootFile(ctx, /(^|\/)Package\.swift$/i) ||
+    hasCoreProjectFile(ctx, /\.xcodeproj/i);
   return ctx.__nerviqIsSwift;
 }
 
@@ -149,6 +171,41 @@ function isKotlinProject(ctx) {
   return ctx.__nerviqIsKotlin;
 }
 
+function isRubyProject(ctx) {
+  if (ctx.__nerviqIsRuby !== undefined) return ctx.__nerviqIsRuby;
+  ctx.__nerviqIsRuby = hasCoreRootFile(ctx, /(^|\/)Gemfile$/i);
+  return ctx.__nerviqIsRuby;
+}
+
+function isPhpProject(ctx) {
+  if (ctx.__nerviqIsPhp !== undefined) return ctx.__nerviqIsPhp;
+  ctx.__nerviqIsPhp = hasCoreRootFile(ctx, /(^|\/)composer\.json$/i);
+  return ctx.__nerviqIsPhp;
+}
+
+function isDotnetProject(ctx) {
+  if (ctx.__nerviqIsDotnet !== undefined) return ctx.__nerviqIsDotnet;
+  ctx.__nerviqIsDotnet = hasCoreProjectFile(ctx, /(^|\/)(.*\.csproj|.*\.sln|global\.json)$/i);
+  return ctx.__nerviqIsDotnet;
+}
+
+/**
+ * Map category names to their project detection function.
+ * Used by the audit to skip entire categories when the stack isn't detected.
+ */
+const STACK_CATEGORY_DETECTORS = {
+  python: isPythonProject,
+  go: isGoProject,
+  rust: isRustProject,
+  java: isJavaProject,
+  flutter: isFlutterProject,
+  swift: isSwiftProject,
+  kotlin: isKotlinProject,
+  ruby: isRubyProject,
+  php: isPhpProject,
+  dotnet: isDotnetProject,
+};
+
 function getPythonFiles(ctx) {
   if (ctx.__nerviqPythonFiles) return ctx.__nerviqPythonFiles;
   ctx.__nerviqPythonFiles = findProjectFiles(ctx, /\.py$/i);
@@ -5434,4 +5491,4 @@ const STACKS = {
 
 attachSourceUrls('claude', TECHNIQUES);
 
-module.exports = { TECHNIQUES, STACKS, containsEmbeddedSecret };
+module.exports = { TECHNIQUES, STACKS, STACK_CATEGORY_DETECTORS, containsEmbeddedSecret };