@nerviq/cli 0.9.6 → 1.0.1

package/README.md

@@ -4,23 +4,24 @@
 
 [![npm version](https://img.shields.io/npm/v/@nerviq/cli)](https://www.npmjs.com/package/@nerviq/cli)
 [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)
+[![Checks: 673](https://img.shields.io/badge/checks-673-brightgreen)](https://github.com/nerviq/nerviq)
 
 ---
 
-### ⚠️ Beta — Currently Claude Code only
+### 8 Platforms Supported
 
-Nerviq is in **beta**. The current release fully supports **Claude Code** (90 checks, audit, setup, governance, benchmark).
+Nerviq v1.0 ships with full audit, setup, governance, and benchmark support for **8 AI coding platforms**:
 
-**Coming soon:**
-- Codex (OpenAI)
-- Gemini CLI (Google)
-- GitHub Copilot
-- Cursor
-- Windsurf
-- Aider
-- OpenCode
-- **Harmony** — cross-platform drift detection
-- **Synergy** — multi-agent amplification
+| Platform | Checks | Status |
+|----------|--------|--------|
+| Claude Code | 90 | Full |
+| Codex (OpenAI) | 83 | Full |
+| Gemini CLI (Google) | 83 | Full |
+| GitHub Copilot | 83 | Full |
+| Cursor | 83 | Full |
+| Windsurf | 83 | Full |
+| Aider | 85 | Full |
+| OpenCode | 83 | Full |
 
 ---
 
@@ -61,7 +62,7 @@ npx @nerviq/cli benchmark          # Before/after in isolated copy
 
 No install required. Zero dependencies.
 
-## 90 Checks Across 14 Categories
+## 673 Checks Across 14 Categories
 
 | Category | Checks | Examples |
 |----------|--------|---------|
@@ -79,11 +80,126 @@ No install required. Zero dependencies.
 | Features | 2 | channels, worktrees |
 | Quality Deep | 9 | freshness, contradictions, deprecated patterns |
 
+## Harmony — Cross-Platform Alignment
+
+Harmony detects drift between your AI coding platforms and keeps them in sync.
+
+```bash
+npx @nerviq/cli harmony-audit      # Cross-platform DX audit (0-100 harmony score)
+npx @nerviq/cli harmony-sync       # Sync shared config across platforms
+npx @nerviq/cli harmony-drift      # Detect drift between platform configs
+npx @nerviq/cli harmony-advise     # Cross-platform improvement advice
+npx @nerviq/cli harmony-watch      # Live monitoring for config drift
+npx @nerviq/cli harmony-governance # Unified governance across platforms
+```
+
+## Synergy — Multi-Agent Amplification
+
+Synergy analyzes how your platforms work together and finds amplification opportunities.
+
+```bash
+npx @nerviq/cli synergy-report     # Multi-agent synergy analysis
+```
+
+Synergy evaluates compound audit results, discovers compensation patterns (where one platform covers another's gaps), and ranks recommendations by cross-platform impact.
+
+## SDK — `@nerviq/sdk`
+
+Programmatic access to all Nerviq capabilities:
+
+```js
+const { audit, harmonyAudit, synergyReport, detectPlatforms } = require('@nerviq/sdk');
+
+const result = await audit('.', 'claude');
+console.log(`Score: ${result.score}/100`);
+
+const platforms = detectPlatforms('.');
+console.log(`Active platforms: ${platforms.join(', ')}`);
+
+const harmony = await harmonyAudit('.');
+console.log(`Harmony score: ${harmony.harmonyScore}/100`);
+```
+
+## MCP Server — `nerviq serve`
+
+Nerviq ships with a built-in MCP-compatible HTTP server for integration with AI agents:
+
+```bash
+npx @nerviq/cli serve --port 3000
+```
+
+Endpoints:
+- `GET /api/health` — Server health check
+- `GET /api/catalog` — Full check catalog
+- `POST /api/audit` — Run audit on a directory
+- `GET /api/harmony` — Cross-platform harmony data
+
+## Plugin System — `nerviq.config.js`
+
+Extend Nerviq with custom checks via a config file in your project root:
+
+```js
+// nerviq.config.js
+module.exports = {
+  plugins: [
+    {
+      name: 'my-company-checks',
+      checks: {
+        internalDocs: {
+          id: 'internalDocs',
+          name: 'Internal docs present',
+          check: (dir) => require('fs').existsSync(`${dir}/docs/internal.md`),
+          impact: 'medium',
+          category: 'Quality',
+          fix: 'Add docs/internal.md with team-specific guidelines',
+        },
+      },
+    },
+  ],
+};
+```
+
+See [docs/plugins.md](docs/plugins.md) for full plugin API reference.
+
+## GitHub Action
+
+Add Nerviq to your CI pipeline:
+
+```yaml
+# .github/workflows/nerviq.yml
+name: Nerviq Audit
+on: [push, pull_request]
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: nerviq/nerviq@v1
+        with:
+          threshold: 60
+```
+
+The action outputs `score`, `passed`, and `total` for use in downstream steps. Fails the workflow if the score is below the configured threshold.
+
+## Certification
+
+Earn a Nerviq certification badge for your project:
+
+```bash
+npx @nerviq/cli certify            # Run certification and display badge
+```
+
+Levels:
+- **Gold** — Harmony score >= 80, all platforms >= 70
+- **Silver** — Harmony score >= 60, all platforms >= 50
+- **Bronze** — Any platform >= 40
+
 ## All Commands
 
 | Command | What it does |
 |---------|-------------|
-| `nerviq audit` | Score 0-100 against 90 checks |
+| `nerviq audit` | Score 0-100 against 673 checks |
 | `nerviq audit --lite` | Quick top-3 scan |
 | `nerviq setup` | Generate starter-safe CLAUDE.md + hooks + commands |
 | `nerviq augment` | Repo-aware improvement plan (no writes) |
@@ -100,7 +216,20 @@ No install required. Zero dependencies.
 | `nerviq trend` | Export trend report |
 | `nerviq feedback` | Record recommendation outcomes |
 | `nerviq badge` | shields.io badge for README |
+| `nerviq certify` | Certification level + badge |
 | `nerviq scan dir1 dir2` | Compare multiple repos |
+| `nerviq harmony-audit` | Cross-platform DX audit |
+| `nerviq harmony-sync` | Sync config across platforms |
+| `nerviq harmony-drift` | Detect platform drift |
+| `nerviq harmony-advise` | Cross-platform advice |
+| `nerviq harmony-watch` | Live drift monitoring |
+| `nerviq harmony-governance` | Unified platform governance |
+| `nerviq synergy-report` | Multi-agent synergy analysis |
+| `nerviq catalog` | Show check catalog for all 8 platforms |
+| `nerviq doctor` | Self-diagnostics |
+| `nerviq convert` | Convert config between platforms |
+| `nerviq migrate` | Migrate platform config versions |
+| `nerviq serve` | Start local MCP-compatible HTTP API |
 
 ## Options
 
@@ -115,6 +244,17 @@ No install required. Zero dependencies.
 | `--auto` | Apply without prompts |
 | `--verbose` | Show all recommendations |
 | `--format sarif` | SARIF output for code scanning |
+| `--platform NAME` | Target platform (claude, codex, gemini, copilot, cursor, windsurf, aider, opencode) |
+
+## Backed by Research
+
+Nerviq is built on the CLAUDEX knowledge engine — the largest verified catalog of AI coding agent techniques:
+
+- **315 research documents** covering all 8 platforms
+- **100+ experiments** with tested, rated results
+- **673 checks** each with `sourceUrl` and `confidence` level (0.0-1.0)
+- Every check is traceable to primary documentation or verified experiment
+- 90-day freshness cycle: stale findings are re-verified or pruned
 
 ## Privacy
 

package/bin/cli.js

@@ -22,7 +22,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', 'doctor', 'convert', 'migrate', 'catalog', 'serve', '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', 'catalog', 'certify', 'serve', 'help', 'version'];
 
 function levenshtein(a, b) {
   const matrix = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
@@ -211,109 +211,99 @@ function parseArgs(rawArgs) {
 
 const HELP = `
   nerviq v${version}
-  Score your repo's Claude Code setup. Fix gaps safely. Benchmark the impact.
-
-  Start here (read-only, nothing changes):
-    npx nerviq                  Audit your project (10 seconds)
-    npx nerviq --lite           Quick scan: top 3 gaps + next command
-    npx nerviq --platform codex Audit your Codex repo setup
-    npx nerviq --platform codex augment      Codex-aware advisory pass, no writes
-    npx nerviq --platform codex suggest-only Structured Codex report, no writes
-    npx nerviq augment          Repo-aware analysis, no writes
-    npx nerviq suggest-only     Structured report, no writes
-
-  Plan and apply (when you're ready to change things):
-    npx nerviq plan             Export proposal bundles with previews
-    npx nerviq apply            Apply proposals selectively with rollback
-    npx nerviq setup            Generate starter-safe baseline
-    npx nerviq setup --auto     Apply all generated files without prompts
-
-  Track progress over time:
-    npx nerviq history          Show score history from saved snapshots
-    npx nerviq compare          Compare latest vs previous snapshot
-    npx nerviq trend --out r.md Export trend report as markdown
-
-  Multi-repo:
-    npx nerviq scan dir1 dir2   Compare multiple repos side-by-side
-
-  Advanced:
-    npx nerviq governance       Permission profiles, hooks, policy packs
-    npx nerviq benchmark        Before/after in isolated temp copy
-    npx nerviq deep-review      AI-powered config review (opt-in, uses API)
-    npx nerviq interactive      Step-by-step guided wizard
-    npx nerviq watch            Live monitoring on config changes with cross-platform watch fallback
-    npx nerviq serve --port 3000 Start the local Nerviq HTTP API
-    npx nerviq badge            Generate shields.io badge markdown
-    npx nerviq feedback         Record recommendation outcomes or show local outcome summary
-
-  Catalog:
-    npx nerviq catalog          Show check catalog summary for all 8 platforms
-    npx nerviq catalog --json   Full catalog as JSON
-    npx nerviq catalog --out catalog.json  Write catalog to file
-
-  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)
-    --out FILE      Write JSON or markdown output to a file
-    --plan FILE     Load a previously exported plan file
-    --only A,B      Limit plan/apply to selected proposal ids or technique keys
-    --profile NAME  Choose permission profile (read-only, suggest-only, safe-write, power-user, internal-research)
-    --mcp-pack A,B  Merge named MCP packs into generated settings (e.g. context7-docs,next-devtools)
-    --key NAME      Recommendation key for feedback logging (e.g. permissionDeny)
-    --status VALUE  Feedback status: accepted, rejected, deferred
-    --effect VALUE  Feedback effect: positive, neutral, negative
-    --notes TEXT    Short notes to store with a feedback event
-    --source NAME   Source label for feedback event (default: manual-cli)
-    --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)
-    --port N        Port for \`serve\` (default: 3000)
-    --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
-    --verbose       Show all recommendations (not just critical/high)
-    --json          Output as JSON (for CI pipelines)
-    --auto          Apply all generated setup files without prompting
-    --insights      Enable anonymous usage insights (off by default)
-    --help          Show this help
-    --version       Show version
-
-  Examples:
+  The intelligent nervous system for AI coding agents.
+  Audit, align, and amplify every platform on every project.
+
+  DISCOVER
+    nerviq audit                  Score your project (0-100)
+    nerviq audit --platform X     Audit specific platform (claude|codex|cursor|copilot|gemini|windsurf|aider|opencode)
+    nerviq audit --lite           Quick scan: top 3 gaps + next command
+    nerviq audit --json           Machine-readable JSON output (for CI)
+    nerviq scan dir1 dir2         Compare multiple repos side-by-side
+    nerviq catalog                Full check catalog (all 8 platforms)
+    nerviq catalog --json         Export full check catalog as JSON
+
+  SETUP
+    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 doctor                 Self-diagnostics: Node, deps, freshness, platform detection
+
+  IMPROVE
+    nerviq augment                Improvement plan (no writes)
+    nerviq suggest-only           Structured report for sharing (no writes)
+    nerviq plan                   Export proposal bundles with diffs
+    nerviq plan --out plan.json   Save plan to file
+    nerviq apply                  Apply proposals selectively with rollback
+    nerviq apply --dry-run        Preview changes without writing
+
+  GOVERN
+    nerviq governance             Permission profiles + hooks + policy packs
+    nerviq governance --json      Machine-readable governance summary
+    nerviq benchmark              Before/after score in isolated temp copy
+    nerviq certify                Generate certification badge for your project
+
+  CROSS-PLATFORM
+    nerviq harmony-audit          Drift detection across all active platforms
+    nerviq synergy-report         Multi-agent amplification opportunities
+    nerviq convert --from X --to Y   Convert configs between platforms
+    nerviq migrate --platform X   Platform version migration helper
+    nerviq migrate --platform cursor --from v2 --to v3
+
+  MONITOR
+    nerviq watch                  Live config monitoring (re-audits on file change)
+    nerviq history                Score history from saved snapshots
+    nerviq compare                Latest vs previous snapshot diff
+    nerviq trend                  Score trend over time
+    nerviq trend --out report.md  Export trend report as markdown
+    nerviq feedback               Record recommendation outcomes
+
+  ADVANCED
+    nerviq deep-review            AI-powered config review (opt-in, uses API key)
+    nerviq serve --port 3000      Start local Nerviq REST API server
+    nerviq badge                  Generate shields.io badge markdown
+
+  OPTIONS
+    --platform NAME   Platform: claude (default), codex, cursor, copilot, gemini, windsurf, aider, opencode
+    --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)
+    --plan FILE       Load previously exported plan file
+    --only A,B        Limit plan/apply to selected proposal IDs
+    --profile NAME    Permission profile: read-only | suggest-only | safe-write | power-user
+    --mcp-pack A,B    Merge MCP packs into setup (e.g. context7-docs,next-devtools)
+    --format NAME     Output format: json | sarif
+    --port N          Port for \`serve\` (default: 3000)
+    --snapshot        Save snapshot artifact under .claude/nerviq/snapshots/
+    --lite            Short top-3 scan with one clear next step
+    --dry-run         Preview changes without writing files
+    --verbose         Show all checks (not just critical/high)
+    --json            Output as JSON
+    --auto            Apply all generated files without prompting
+    --key NAME        Feedback: recommendation key (e.g. permissionDeny)
+    --status VALUE    Feedback: accepted | rejected | deferred
+    --effect VALUE    Feedback: positive | neutral | negative
+    --score-delta N   Feedback: observed score delta
+    --help            Show this help
+    --version         Show version
+
+  EXAMPLES
     npx nerviq
     npx nerviq --lite
-    npx nerviq --platform codex
+    npx nerviq --platform cursor
     npx nerviq --platform codex augment
-    npx nerviq --platform codex suggest-only --json
-    npx nerviq --platform codex setup
-    npx nerviq --platform codex plan --out codex-plan.json
-    npx nerviq --platform codex --format sarif
-    npx nerviq --snapshot
-    npx nerviq augment
-    npx nerviq augment --snapshot
-    npx nerviq suggest-only --json
-    npx nerviq governance --snapshot
-    npx nerviq plan --out claudex-plan.json
-    npx nerviq plan --profile safe-write
+    npx nerviq scan ./app ./api ./infra
+    npx nerviq harmony-audit
+    npx nerviq convert --from claude --to codex
+    npx nerviq migrate --platform cursor --from v2 --to v3
     npx nerviq setup --mcp-pack context7-docs
-    npx nerviq apply --plan claudex-plan.json --only hooks,commands
-    npx nerviq apply --mcp-pack context7-docs,next-devtools --only hooks
-    npx nerviq apply --profile power-user --only claude-md,hooks
-    npx nerviq governance --json
-    npx nerviq benchmark --out benchmark.md
-    npx nerviq feedback
-    npx nerviq feedback --key permissionDeny --status accepted --effect positive --score-delta 12
-    npx nerviq serve --port 3000
-    npx nerviq --json --threshold 60
-    npx nerviq setup --auto
-    npx nerviq interactive
-
-  Exit codes:
+    npx nerviq apply --plan plan.json --only hooks,commands
+    npx nerviq serve --port 4000
+    npx nerviq --json --threshold 70
+    npx nerviq catalog --json --out catalog.json
+    npx nerviq feedback --key permissionDeny --status accepted --effect positive
+
+  EXIT CODES
     0  Success
     1  Error, unknown command, or score below --threshold
 `;
@@ -413,7 +403,7 @@ async function main() {
     const FULL_COMMAND_SET = new Set([
       'audit', 'scan', 'badge', 'augment', 'suggest-only', 'setup', 'plan', 'apply',
       'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'insights',
-      'history', 'compare', 'trend', 'feedback', 'catalog', 'serve', 'help', 'version',
+      'history', 'compare', 'trend', 'feedback', 'catalog', 'certify', 'serve', 'help', 'version',
       // Harmony + Synergy (cross-platform)
       'harmony-audit', 'harmony-sync', 'harmony-drift', 'harmony-advise',
       'harmony-watch', 'harmony-governance', 'synergy-report',
@@ -768,6 +758,34 @@ async function main() {
         }
       }
       process.exit(0);
+    } else if (normalizedCommand === 'certify') {
+      const { certifyProject, generateCertBadge } = require('../src/certification');
+      const certResult = await certifyProject(options.dir);
+      if (options.json) {
+        console.log(JSON.stringify(certResult, null, 2));
+      } else {
+        console.log('');
+        console.log('\x1b[1m  nerviq certification\x1b[0m');
+        console.log('\x1b[2m  ═══════════════════════════════════════\x1b[0m');
+        console.log('');
+        console.log(`  Level: \x1b[1m${certResult.level}\x1b[0m`);
+        console.log(`  Harmony Score: ${certResult.harmonyScore}/100`);
+        console.log('');
+        if (Object.keys(certResult.platformScores).length > 0) {
+          console.log('  Platform Scores:');
+          for (const [plat, score] of Object.entries(certResult.platformScores)) {
+            const scoreColor = score >= 70 ? '\x1b[32m' : score >= 40 ? '\x1b[33m' : '\x1b[31m';
+            console.log(`    ${plat.padEnd(12)} ${scoreColor}${score}/100\x1b[0m`);
+          }
+          console.log('');
+        }
+        console.log('  Badge:');
+        console.log(`  ${certResult.badge}`);
+        console.log('');
+        console.log('  Add the badge to your README.md');
+        console.log('');
+      }
+      process.exit(0);
     } else if (normalizedCommand === 'serve') {
       const server = await startServer({
         port: options.port == null ? 3000 : options.port,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nerviq/cli",
-  "version": "0.9.6",
-  "description": "The intelligent nervous system for AI coding agents — audit, align, and amplify every platform on every project.",
+  "version": "1.0.1",
+  "description": "The intelligent nervous system for AI coding agents — 673 checks across 8 platforms. Audit, align, and amplify.",
   "main": "src/index.js",
   "bin": {
     "nerviq": "bin/cli.js",
@@ -9,10 +9,8 @@
   },
   "files": [
     "bin",
-    "content",
     "src",
-    "README.md",
-    "CHANGELOG.md"
+    "README.md"
   ],
   "scripts": {
     "start": "node bin/cli.js",
@@ -20,7 +18,7 @@
     "test": "node test/run.js",
     "test:jest": "jest",
     "test:coverage": "jest --coverage",
-    "test:all": "node test/run.js && node test/check-matrix.js && node test/codex-check-matrix.js && node test/golden-matrix.js && node test/codex-golden-matrix.js && node test/gemini-check-matrix.js && node test/gemini-golden-matrix.js && node test/copilot-check-matrix.js && node test/copilot-golden-matrix.js && node test/cursor-check-matrix.js && node test/cursor-golden-matrix.js && node test/security-tests.js && jest",
+    "test:all": "npm test && npx jest && node test/check-matrix.js && node test/codex-check-matrix.js && node test/gemini-check-matrix.js && node test/copilot-check-matrix.js && node test/cursor-check-matrix.js && node test/golden-matrix.js && node test/codex-golden-matrix.js && node test/gemini-golden-matrix.js && node test/copilot-golden-matrix.js && node test/cursor-golden-matrix.js",
     "benchmark:perf": "node tools/benchmark.js",
     "catalog": "node -e \"const {generateCatalog}=require('./src/catalog');console.log(JSON.stringify(generateCatalog(),null,2))\""
   },

package/src/audit.js

@@ -25,6 +25,7 @@ const { OpenCodeProjectContext } = require('./opencode/context');
 const { getBadgeMarkdown } = require('./badge');
 const { sendInsights, getLocalInsights } = require('./insights');
 const { getRecommendationOutcomeSummary, getRecommendationAdjustment } = require('./activity');
+const { getFeedbackSummary } = require('./feedback');
 const { formatSarif } = require('./formatters/sarif');
 const { loadPlugins, mergePluginChecks } = require('./plugins');
 
@@ -441,24 +442,48 @@ function getQuickWins(failed, options = {}) {
     .slice(0, 3);
 }
 
-function getRecommendationPriorityScore(item, outcomeSummaryByKey = {}) {
+/**
+ * Compute a multiplier based on FP (helpful/not-helpful) feedback for a check key.
+ * - >50% "not helpful" feedback: lower priority by 30% (multiplier 0.7)
+ * - >80% "helpful" feedback: boost priority by 20% (multiplier 1.2)
+ * - Otherwise: no change (multiplier 1.0)
+ * @param {Object} fpFeedbackByKey - Keyed feedback summary from getFeedbackSummary().byKey
+ * @param {string} key - The check key to look up
+ * @returns {number} Multiplier to apply to priority score
+ */
+function getFpFeedbackMultiplier(fpFeedbackByKey, key) {
+  if (!fpFeedbackByKey) return 1.0;
+  const bucket = fpFeedbackByKey[key];
+  if (!bucket || bucket.total === 0) return 1.0;
+
+  const unhelpfulRate = bucket.unhelpful / bucket.total;
+  const helpfulRate = bucket.helpful / bucket.total;
+
+  if (unhelpfulRate > 0.5) return 0.7;
+  if (helpfulRate > 0.8) return 1.2;
+  return 1.0;
+}
+
+function getRecommendationPriorityScore(item, outcomeSummaryByKey = {}, fpFeedbackByKey = null) {
   const impactScore = (IMPACT_ORDER[item.impact] ?? 0) * 100;
   const feedbackAdjustment = getRecommendationAdjustment(outcomeSummaryByKey, item.key);
   const brevityPenalty = Math.min((item.fix || '').length, 240) / 20;
-  return impactScore + (feedbackAdjustment * 10) - brevityPenalty;
+  const raw = impactScore + (feedbackAdjustment * 10) - brevityPenalty;
+  return raw * getFpFeedbackMultiplier(fpFeedbackByKey, item.key);
 }
 
 function buildTopNextActions(failed, limit = 5, outcomeSummaryByKey = {}, options = {}) {
   const pool = getPrioritizedFailed(failed);
+  const fpByKey = options.fpFeedbackByKey || null;
 
   return [...pool]
     .sort((a, b) => {
       const scoreB = options.platform === 'codex'
         ? codexPriorityScore(b, outcomeSummaryByKey)
-        : getRecommendationPriorityScore(b, outcomeSummaryByKey);
+        : getRecommendationPriorityScore(b, outcomeSummaryByKey, fpByKey);
       const scoreA = options.platform === 'codex'
         ? codexPriorityScore(a, outcomeSummaryByKey)
-        : getRecommendationPriorityScore(a, outcomeSummaryByKey);
+        : getRecommendationPriorityScore(a, outcomeSummaryByKey, fpByKey);
       return scoreB - scoreA;
     })
     .slice(0, limit)
@@ -479,7 +504,7 @@ function buildTopNextActions(failed, limit = 5, outcomeSummaryByKey = {}, option
       const evidenceClass = options.platform === 'codex' ? codexEvidenceClass(fullItem) : (feedback ? 'measured' : 'estimated');
       const priorityScore = options.platform === 'codex'
         ? codexPriorityScore(fullItem, outcomeSummaryByKey)
-        : Math.max(0, Math.min(100, Math.round(getRecommendationPriorityScore(fullItem, outcomeSummaryByKey) / 3)));
+        : Math.max(0, Math.min(100, Math.round(getRecommendationPriorityScore(fullItem, outcomeSummaryByKey, fpByKey) / 3)));
 
       signals.push(`evidence:${evidenceClass}`);
       if (options.platform === 'codex' && CODEX_HARD_FAIL_KEYS.has(key)) {
@@ -728,6 +753,7 @@ async function audit(options) {
   const stacks = ctx.detectStacks(STACKS);
   const results = [];
   const outcomeSummary = getRecommendationOutcomeSummary(options.dir);
+  const fpFeedback = getFeedbackSummary(options.dir);
 
   // Load and merge plugin checks
   const plugins = loadPlugins(options.dir);
@@ -795,7 +821,7 @@ async function audit(options) {
   const organicEarned = organicPassed.reduce((sum, r) => sum + (WEIGHTS[r.impact] || 5), 0);
   const organicScore = maxScore > 0 ? Math.round((organicEarned / maxScore) * 100) : 0;
   const quickWins = getQuickWins(failed, { platform: spec.platform });
-  const topNextActions = buildTopNextActions(failed, 5, outcomeSummary.byKey, { platform: spec.platform });
+  const topNextActions = buildTopNextActions(failed, 5, outcomeSummary.byKey, { platform: spec.platform, fpFeedbackByKey: fpFeedback.byKey });
   const categoryScores = computeCategoryScores(applicable, passed);
   const platformScopeNote = getPlatformScopeNote(spec, ctx);
   const platformCaveats = getPlatformCaveats(spec, ctx);
@@ -1008,4 +1034,4 @@ async function audit(options) {
   return result;
 }
 
-module.exports = { audit, buildTopNextActions };
+module.exports = { audit, buildTopNextActions, getFpFeedbackMultiplier, getRecommendationPriorityScore };