@nerviq/cli 0.9.2 → 0.9.4

package/bin/cli.js

@@ -7,6 +7,7 @@ const { buildProposalBundle, printProposalBundle, writePlanFile, applyProposalBu
 const { getGovernanceSummary, printGovernanceSummary, ensureWritableProfile, renderGovernanceMarkdown } = require('../src/governance');
 const { runBenchmark, printBenchmark, writeBenchmarkReport } = require('../src/benchmark');
 const { writeSnapshotArtifact, recordRecommendationOutcome, formatRecommendationOutcomeSummary, getRecommendationOutcomeSummary } = require('../src/activity');
+const { collectFeedback } = require('../src/feedback');
 const { version } = require('../package.json');
 
 const args = process.argv.slice(2);
@@ -20,7 +21,7 @@ const COMMAND_ALIASES = {
   gov: 'governance',
   outcome: 'feedback',
 };
-const KNOWN_COMMANDS = ['audit', 'setup', 'augment', 'suggest-only', 'plan', 'apply', 'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'badge', 'insights', 'history', 'compare', 'trend', 'scan', 'feedback', 'help', 'version'];
+const KNOWN_COMMANDS = ['audit', 'setup', 'augment', 'suggest-only', 'plan', 'apply', 'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'badge', 'insights', 'history', 'compare', 'trend', 'scan', 'feedback', 'doctor', 'convert', 'migrate', 'help', 'version'];
 
 function levenshtein(a, b) {
   const matrix = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
@@ -73,11 +74,15 @@ function parseArgs(rawArgs) {
   let format = null;
   let commandSet = false;
   let extraArgs = [];
+  let convertFrom = null;
+  let convertTo = null;
+  let migrateFrom = null;
+  let migrateTo = null;
 
   for (let i = 0; i < rawArgs.length; i++) {
     const arg = rawArgs[i];
 
-    if (arg === '--threshold' || arg === '--out' || arg === '--plan' || arg === '--only' || arg === '--profile' || arg === '--mcp-pack' || arg === '--require' || arg === '--key' || arg === '--status' || arg === '--effect' || arg === '--notes' || arg === '--source' || arg === '--score-delta' || arg === '--platform' || arg === '--format') {
+    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') {
       const value = rawArgs[i + 1];
       if (!value || value.startsWith('--')) {
         throw new Error(`${arg} requires a value`);
@@ -97,6 +102,8 @@ function parseArgs(rawArgs) {
       if (arg === '--score-delta') feedbackScoreDelta = value.trim();
       if (arg === '--platform') platform = value.trim().toLowerCase();
       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(); }
       i++;
       continue;
     }
@@ -191,7 +198,7 @@ function parseArgs(rawArgs) {
 
   const normalizedCommand = COMMAND_ALIASES[command] || command;
 
-  return { flags, command, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks, requireChecks, feedbackKey, feedbackStatus, feedbackEffect, feedbackNotes, feedbackSource, feedbackScoreDelta, platform, format, extraArgs };
+  return { flags, command, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks, requireChecks, feedbackKey, feedbackStatus, feedbackEffect, feedbackNotes, feedbackSource, feedbackScoreDelta, platform, format, extraArgs, convertFrom, convertTo, migrateFrom, migrateTo };
 }
 
 const HELP = `
@@ -230,6 +237,11 @@ const HELP = `
     npx nerviq badge            Generate shields.io badge markdown
     npx nerviq feedback         Record recommendation outcomes or show local outcome summary
 
+  Utilities:
+    npx nerviq doctor           Self-diagnostics: Node version, deps, freshness gates, platform detection
+    npx nerviq convert --from claude --to codex   Convert config between platforms
+    npx nerviq migrate --platform cursor --from v2 --to v3   Migrate platform config to newer version
+
   Options:
     --threshold N   Exit with code 1 if score is below N (useful for CI)
     --require A,B   Exit with code 1 if named checks fail (e.g. --require secretsProtection,permissionDeny)
@@ -246,6 +258,7 @@ const HELP = `
     --score-delta N Optional observed score delta tied to the outcome
     --platform NAME Choose platform surface (claude default, codex advisory/build preview)
     --format NAME   Output format for audit results (json, sarif)
+    --feedback      After audit output, prompt "Was this helpful? (y/n)" for each displayed top action and save answers locally
     --snapshot      Save a normalized snapshot artifact under .claude/nerviq/snapshots/
     --lite          Show a short top-3 quick scan with one clear next command
     --dry-run       Preview apply without writing files
@@ -316,6 +329,7 @@ async function main() {
     auto: flags.includes('--auto'),
     lite: flags.includes('--lite'),
     snapshot: flags.includes('--snapshot'),
+    feedback: flags.includes('--feedback'),
     dryRun: flags.includes('--dry-run'),
     threshold: parsed.threshold !== null ? Number(parsed.threshold) : null,
     out: parsed.out,
@@ -699,6 +713,34 @@ async function main() {
     } else if (normalizedCommand === 'watch') {
       const { watch } = require('../src/watch');
       await watch(options);
+    } else if (normalizedCommand === 'doctor') {
+      const { runDoctor } = require('../src/doctor');
+      const output = await runDoctor({ dir: options.dir, json: options.json, verbose: options.verbose });
+      console.log(output);
+      process.exit(0);
+    } else if (normalizedCommand === 'convert') {
+      const { runConvert } = require('../src/convert');
+      const output = await runConvert({
+        dir: options.dir,
+        from: parsed.convertFrom,
+        to: parsed.convertTo,
+        dryRun: options.dryRun,
+        json: options.json,
+      });
+      console.log(output);
+      process.exit(0);
+    } else if (normalizedCommand === 'migrate') {
+      const { runMigrate } = require('../src/migrate');
+      const output = await runMigrate({
+        dir: options.dir,
+        platform: options.platform || parsed.platform || 'claude',
+        from: parsed.migrateFrom,
+        to: parsed.migrateTo,
+        dryRun: options.dryRun,
+        json: options.json,
+      });
+      console.log(output);
+      process.exit(0);
     } else if (normalizedCommand === 'setup') {
       await setup(options);
       if (options.snapshot) {
@@ -712,6 +754,25 @@ async function main() {
       }
     } else {
       const result = await audit(options);
+      if (options.feedback && !options.json && options.format === null) {
+        const feedbackTargets = options.lite
+          ? (result.liteSummary?.topNextActions || [])
+          : (result.topNextActions || []);
+        const feedbackResult = await collectFeedback(options.dir, {
+          findings: feedbackTargets,
+          platform: result.platform,
+          sourceCommand: normalizedCommand,
+          score: result.score,
+        });
+        if (feedbackResult.mode === 'skipped-noninteractive') {
+          console.log('  Feedback prompt skipped: interactive terminal required.');
+          console.log('');
+        } else if (feedbackResult.saved > 0) {
+          console.log(`  Feedback saved: ${feedbackResult.relativeDir}`);
+          console.log(`  Helpful: ${feedbackResult.helpful} | Not helpful: ${feedbackResult.unhelpful}`);
+          console.log('');
+        }
+      }
       const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, 'audit', result, {
         sourceCommand: normalizedCommand,
       }) : null;

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@nerviq/cli",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "The intelligent nervous system for AI coding agents — audit, align, and amplify every platform on every project.",
   "main": "src/index.js",
   "bin": {
-    "nerviq": "bin/cli.js"
+    "nerviq": "bin/cli.js",
+    "nerviq-mcp": "src/mcp-server.js"
   },
   "files": [
     "bin",

package/src/aider/techniques.js

@@ -1,22 +1,26 @@
 /**
- * Aider Technique Database — 68 checks (AD-A01 through AD-P03)
+ * Aider Technique Database — 71 checks (AD-A01 through AD-P06)
  *
  * Aider is fundamentally different from IDE platforms:
  * - Git-first CLI tool: git is the ONLY safety mechanism
  * - No hooks, no MCP, no skills, no agents
  * - Config: .aider.conf.yml (YAML), .aider.model.settings.yml, .env
  * - 3 model roles: main (coding), editor (applying), weak (commit messages)
- * - Architect mode (2-model workflow)
- * - Convention files must be explicitly passed (no auto-discovery)
+ * - Architect mode (2-model workflow, ~1.73x cost vs standard)
+ * - Convention files must be EXPLICITLY passed AND referenced in prompts (no auto-discovery)
  * - 4-level config precedence: env vars > CLI args > .aider.conf.yml > defaults
+ * - Key gotcha: default auto-commit bypasses pre-commit hooks (use --git-commit-verify)
+ * - Key gotcha: exit code 0 returned even on auth failure in headless mode
+ * - Key gotcha: Playwright auto-scrapes URLs in messages (unexpected side effect)
  *
- * Categories: Config(8), Git Safety(8), Model Config(8), Conventions(6),
- *   Architecture(4), Security(6), CI(4), Quality(6) + M/N/O/P expansion (18)
+ * Categories: Config(8), Git Safety(10), Model Config(8), Conventions(6),
+ *   Architecture(4), Security(6), CI(4), Quality(6) + M/N/O/P expansion (19)
  *
  * Check ID prefix: AD-
  */
 
 const { containsEmbeddedSecret } = require('../secret-patterns');
+const { attachSourceUrls } = require('../source-urls');
 
 const FILLER_PATTERNS = [
   /\bbe helpful\b/i,
@@ -421,7 +425,7 @@ const AIDER_TECHNIQUES = {
     impact: 'high',
     rating: 4,
     category: 'model-config',
-    fix: 'Set `architect: true` to use a 2-model workflow (architect plans, editor applies).',
+    fix: 'Set `architect: true` to use a 2-model workflow (architect plans, editor applies). NOTE: architect mode costs ~1.73x standard mode per edit ($0.00026 vs $0.00015 measured in live experiment). auto_accept_architect is on by default — no confirmation between steps.',
     template: 'aider-conf-yml',
     file: () => '.aider.conf.yml',
     line: (ctx) => firstLineMatching(configContent(ctx), /architect\s*:/i),
@@ -540,7 +544,7 @@ const AIDER_TECHNIQUES = {
     impact: 'high',
     rating: 4,
     category: 'conventions',
-    fix: 'Add `read: [CONVENTIONS.md]` to .aider.conf.yml — Aider has NO auto-discovery.',
+    fix: 'Add `read: [CONVENTIONS.md]` to .aider.conf.yml — Aider has NO auto-discovery. Additionally, convention files are only followed when EXPLICITLY referenced in the prompt itself (confirmed by live experiment with gpt-4o-mini). Just loading them via --read is not enough; your prompts must say "follow the conventions in CONVENTIONS.md".',
     template: 'aider-conf-yml',
     file: () => '.aider.conf.yml',
     line: (ctx) => firstLineMatching(configContent(ctx), /read\s*:/i),
@@ -867,15 +871,64 @@ const AIDER_TECHNIQUES = {
         Boolean(ctx.fileContent('.husky/pre-commit')) ||
         Boolean(ctx.fileContent('.lefthook.yml'));
     },
-    impact: 'medium',
-    rating: 3,
+    impact: 'high',
+    rating: 4,
     category: 'ci',
-    fix: 'Add pre-commit hooks (pre-commit, husky, lefthook) to validate Aider changes.',
+    fix: 'Add pre-commit hooks (pre-commit, husky, lefthook). IMPORTANT: Aider default auto-commit BYPASSES pre-commit hooks (confirmed by live experiment). If hooks are critical, pass --git-commit-verify to Aider to restore hook enforcement.',
     template: null,
     file: () => null,
     line: () => null,
   },
 
+  aiderGitCommitVerify: {
+    id: 'AD-G05',
+    name: '--git-commit-verify recommended when pre-commit hooks exist',
+    check: (ctx) => {
+      // Only relevant if pre-commit hooks exist
+      const hasHooks = Boolean(ctx.fileContent('.pre-commit-config.yaml')) ||
+        Boolean(ctx.fileContent('.husky/pre-commit')) ||
+        Boolean(ctx.fileContent('.lefthook.yml'));
+      if (!hasHooks) return null;
+      const config = configContent(ctx);
+      if (!config) return false;
+      // Check if git-commit-verify is set in config or documented in conventions
+      return /git-commit-verify/i.test(config) ||
+        /git-commit-verify/i.test(conventionContent(ctx));
+    },
+    impact: 'high',
+    rating: 4,
+    category: 'ci',
+    fix: 'When pre-commit hooks exist, add --git-commit-verify to Aider invocations. Default Aider auto-commits SKIP pre-commit hooks entirely (experimentally confirmed). Without this flag, hooks that enforce security or quality checks are silently bypassed.',
+    template: 'aider-conf-yml',
+    file: () => '.aider.conf.yml',
+    line: (ctx) => firstLineMatching(configContent(ctx), /git-commit-verify/i),
+  },
+
+  aiderCiExitCodeUnreliable: {
+    id: 'AD-G06',
+    name: 'CI scripts handle exit code 0 on auth failure (unreliable exit code)',
+    check: (ctx) => {
+      const workflows = ctx.workflowFiles ? ctx.workflowFiles() : [];
+      if (workflows.length === 0) return null;
+      // Check if any workflow mentions aider and has output checking
+      for (const wf of workflows) {
+        const content = ctx.fileContent(wf) || '';
+        if (/aider/i.test(content)) {
+          // Good if it checks output, not just exit code
+          return /grep|check.*output|--json|error.*detect/i.test(content);
+        }
+      }
+      return null;
+    },
+    impact: 'high',
+    rating: 4,
+    category: 'ci',
+    fix: 'Aider returns exit code 0 even on auth failure (experimentally confirmed). CI scripts that use Aider MUST NOT rely solely on exit codes to detect failure. Check Aider output for error strings or use output parsing to detect real failures.',
+    template: null,
+    file: () => '.github/workflows/',
+    line: () => null,
+  },
+
   // =========================================================================
   // H — Quality (6 checks: AD-H01 .. AD-H06)
   // =========================================================================
@@ -1128,6 +1181,25 @@ const AIDER_TECHNIQUES = {
     line: (ctx) => firstLineMatching(configContent(ctx), /voice-language\s*:/i),
   },
 
+  aiderPlaywrightUrlScraping: {
+    id: 'AD-N05',
+    name: 'Playwright URL auto-scraping side effect is expected',
+    check: (ctx) => {
+      const conventions = conventionContent(ctx);
+      const config = configContent(ctx);
+      // Check if team is aware of the Playwright auto-scraping behavior
+      return /playwright|url.*scrap|scrape.*url|auto.*fetch|web.*fetch/i.test(conventions) ||
+        /playwright|url.*scrap/i.test(config);
+    },
+    impact: 'medium',
+    rating: 3,
+    category: 'workflow-patterns',
+    fix: 'Aider automatically scrapes URLs found in messages using Playwright (experimentally confirmed side effect). This causes unexpected network requests and delays. Document this in conventions, and avoid putting real URLs in messages unless scraping is intentional.',
+    template: 'aider-conventions',
+    file: () => 'CONVENTIONS.md',
+    line: () => null,
+  },
+
   // =========================================================================
   // O — Editor Integration (4 checks: AD-O01 .. AD-O04)
   // =========================================================================
@@ -1294,7 +1366,7 @@ const AIDER_TECHNIQUES = {
     impact: 'medium',
     rating: 3,
     category: 'release-readiness',
-    fix: 'Enable prompt caching or configure separate weak/editor models for cost optimization.',
+    fix: 'Enable prompt caching or configure separate weak/editor models for cost optimization. Cost reference (measured): standard edit ~$0.00015, architect mode edit ~$0.00026 (~1.73x). Set cache-prompts: true for repeated context, and weak-model for commit messages to reduce costs.',
     template: 'aider-conf-yml',
     file: () => '.aider.conf.yml',
     line: (ctx) => firstLineMatching(configContent(ctx), /cache-prompts\s*:|weak-model\s*:|editor-model\s*:/i),
@@ -1318,6 +1390,8 @@ const AIDER_TECHNIQUES = {
   },
 };
 
+attachSourceUrls('aider', AIDER_TECHNIQUES);
+
 module.exports = {
   AIDER_TECHNIQUES,
 };

package/src/audit.js

@@ -461,7 +461,7 @@ function buildTopNextActions(failed, limit = 5, outcomeSummaryByKey = {}, option
       return scoreB - scoreA;
     })
     .slice(0, limit)
-    .map(({ key, id, name, impact, fix, category }) => {
+    .map(({ key, id, name, impact, fix, category, sourceUrl }) => {
       const feedback = outcomeSummaryByKey[key] || null;
       const rankingAdjustment = getRecommendationAdjustment(outcomeSummaryByKey, key);
       const signals = [
@@ -491,6 +491,7 @@ function buildTopNextActions(failed, limit = 5, outcomeSummaryByKey = {}, option
       name,
       impact,
       category,
+      sourceUrl,
       module: CATEGORY_MODULES[category] || category,
       fix,
       priorityScore,
@@ -810,7 +811,7 @@ async function audit(options) {
     stacks,
     results,
     categoryScores,
-    quickWins: quickWins.map(({ key, name, impact, fix, category }) => ({ key, name, impact, category, fix })),
+    quickWins: quickWins.map(({ key, name, impact, fix, category, sourceUrl }) => ({ key, name, impact, category, fix, sourceUrl })),
     topNextActions,
     recommendationOutcomes: {
       totalEntries: outcomeSummary.totalEntries,

package/src/codex/techniques.js

@@ -1,6 +1,7 @@
 const os = require('os');
 const path = require('path');
 const { EMBEDDED_SECRET_PATTERNS, containsEmbeddedSecret } = require('../secret-patterns');
+const { attachSourceUrls } = require('../source-urls');
 
 const DEFAULT_PROJECT_DOC_MAX_BYTES = 32768;
 const SUPPORTED_HOOK_EVENTS = new Set(['SessionStart', 'PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'Stop']);
@@ -3249,6 +3250,8 @@ const CODEX_TECHNIQUES = {
   },
 };
 
+attachSourceUrls('codex', CODEX_TECHNIQUES);
+
 module.exports = {
   CODEX_TECHNIQUES,
 };