@nerviq/cli 1.16.0 → 1.17.1

package/README.md

@@ -42,28 +42,34 @@ Nerviq audits, sets up, and governs AI coding agent configurations for **8 platf
 
 ## What Nerviq Does
 
-Nerviq scores your AI coding agent setup from 0 to 100, finds what's missing, and fixes it — with rollback for every change.
+Most repos use **more than one** AI coding agent — Claude and Cursor, Copilot and Codex, Gemini and Windsurf. Their configs drift silently. Nerviq is the neutral control plane that detects that drift, scores it, and helps align it.
+
+When your repo has 2+ platforms configured, `nerviq audit` leads with the Harmony Score — cross-platform alignment — before any single-platform results. Single-platform repos still get a normal per-platform audit.
 
 ```
-  nerviq audit
-  ═══════════════════════════════════════
-  Detected: React, TypeScript, Docker
+  $ nerviq audit
+  Detected: Next.js + TypeScript + Claude + Cursor
+
+  Harmony Score: 78/100 — 3 drift issues across 2 platforms (Claude Code + Cursor)
+  Run `nerviq harmony-audit` for the full cross-platform report.
 
-  ████████████████░░░░ 78/100
+  Platform: Claude Code
+    CLAUDE.md .............. 23/25 checks passed
+    .claude/settings.json .. 6/9 checks passed
 
-  ✅ CLAUDE.md with architecture diagram
-  ✅ Hooks (PreToolUse + PostToolUse)
-  ✅ Custom skills (3 skills)
-  ✅ MCP servers configured
+  Platform: Cursor
+    .cursor/rules/ ......... 14/16 checks passed
+    .cursorrules ........... 4/7 checks passed
 
-  ⚡ Top 3 Next Actions
-     1. Add verification commands to CLAUDE.md
-     2. Configure deny rules for dangerous operations
-     3. Add path-specific rules in .claude/rules/
+  Drift: trust-mode mismatch (Claude relaxed / Cursor strict)
+         MCP coverage gap — 3 servers in Claude, 1 in Cursor
+         format-on-save hook missing from Cursor
 
-  Next: nerviq setup
+  3 suggestions → `nerviq harmony-sync` to align.
 ```
 
+Single-platform repos still work the same way — the Harmony Score only appears when 2+ platforms are detected. Use `--no-harmony-first` to suppress it even on multi-platform repos.
+
 ## Quick Start
 
 ```bash
@@ -217,8 +223,8 @@ All successful operational responses are wrapped in a JSON envelope:
 {
   "data": {},
   "meta": {
-    "version": "1.16.0",
-    "timestamp": "2026-04-11T12:00:00.000Z"
+    "version": "1.17.1",
+    "timestamp": "2026-04-12T12:00:00.000Z"
   }
 }
 ```

package/package.json

@@ -1,60 +1,60 @@
-{
-  "name": "@nerviq/cli",
-  "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": {
-    "nerviq": "bin/cli.js",
-    "@nerviq/cli": "bin/cli.js",
-    "nerviq-mcp": "src/mcp-server.js"
-  },
-  "files": [
-    "bin",
-    "src",
-    "README.md"
-  ],
-  "scripts": {
-    "start": "node bin/cli.js",
-    "build": "npm pack --dry-run",
-    "test": "node test/run.js",
-    "verify:release-metadata": "node tools/validate-release-metadata.js",
-    "test:jest": "jest",
-    "test:coverage": "jest --coverage",
-    "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/windsurf-check-matrix.js && node test/aider-check-matrix.js && node test/opencode-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 && node test/windsurf-golden-matrix.js && node test/aider-golden-matrix.js && node test/opencode-golden-matrix.js",
-    "benchmark:perf": "node tools/benchmark.js",
-    "catalog": "node -e \"const {generateCatalog}=require('./src/catalog');console.log(JSON.stringify(generateCatalog(),null,2))\""
-  },
-  "keywords": [
-    "nerviq",
-    "ai-agents",
-    "agent-governance",
-    "agent-config",
-    "harmony",
-    "synergy",
-    "audit",
-    "claude",
-    "codex",
-    "gemini",
-    "copilot",
-    "cursor",
-    "windsurf",
-    "aider",
-    "developer-tools",
-    "cli",
-    "mcp",
-    "multi-agent"
-  ],
-  "author": "Nerviq <hello@nerviq.net>",
-  "license": "AGPL-3.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/nerviq/nerviq.git"
-  },
-  "homepage": "https://nerviq.net",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "devDependencies": {
-    "jest": "^30.3.0"
-  }
-}
+{
+  "name": "@nerviq/cli",
+  "version": "1.17.1",
+  "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": {
+    "nerviq": "bin/cli.js",
+    "@nerviq/cli": "bin/cli.js",
+    "nerviq-mcp": "src/mcp-server.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/cli.js",
+    "build": "npm pack --dry-run",
+    "test": "node test/run.js",
+    "verify:release-metadata": "node tools/validate-release-metadata.js",
+    "test:jest": "jest",
+    "test:coverage": "jest --coverage",
+    "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/windsurf-check-matrix.js && node test/aider-check-matrix.js && node test/opencode-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 && node test/windsurf-golden-matrix.js && node test/aider-golden-matrix.js && node test/opencode-golden-matrix.js",
+    "benchmark:perf": "node tools/benchmark.js",
+    "catalog": "node -e \"const {generateCatalog}=require('./src/catalog');console.log(JSON.stringify(generateCatalog(),null,2))\""
+  },
+  "keywords": [
+    "nerviq",
+    "ai-agents",
+    "agent-governance",
+    "agent-config",
+    "harmony",
+    "synergy",
+    "audit",
+    "claude",
+    "codex",
+    "gemini",
+    "copilot",
+    "cursor",
+    "windsurf",
+    "aider",
+    "developer-tools",
+    "cli",
+    "mcp",
+    "multi-agent"
+  ],
+  "author": "Nerviq <hello@nerviq.net>",
+  "license": "AGPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nerviq/nerviq.git"
+  },
+  "homepage": "https://nerviq.net",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "jest": "^30.3.0"
+  }
+}

package/src/audit.js

@@ -514,6 +514,42 @@ async function audit(options) {
   const recommendedDomainPacks = spec.platform === 'codex'
     ? detectCodexDomainPacks(ctx, stacks, getCodexDomainPackSignals(ctx))
     : [];
+
+  // FB-05: framework-aware fix rewriting — don't recommend `npm test` on a
+  // Python/Go/Rust-only repo. Only rewrites when Node/JS stacks are absent.
+  const stackKeys = new Set(stacks.map(s => s.key));
+  const hasNodeStack = stackKeys.has('node') || stackKeys.has('react') || stackKeys.has('vue') ||
+    stackKeys.has('nextjs') || stackKeys.has('angular') || stackKeys.has('svelte') ||
+    stackKeys.has('nestjs') || stackKeys.has('remix') || stackKeys.has('astro') ||
+    stackKeys.has('typescript') || stackKeys.has('deno') || stackKeys.has('bun');
+  if (!hasNodeStack) {
+    let preferredTest = null;
+    let preferredInstall = null;
+    if (stackKeys.has('python') || stackKeys.has('django') || stackKeys.has('fastapi')) {
+      preferredTest = 'pytest'; preferredInstall = 'pip install -r requirements.txt';
+    } else if (stackKeys.has('go')) {
+      preferredTest = 'go test ./...'; preferredInstall = 'go mod download';
+    } else if (stackKeys.has('rust')) {
+      preferredTest = 'cargo test'; preferredInstall = 'cargo fetch';
+    } else if (stackKeys.has('ruby')) {
+      preferredTest = 'bundle exec rspec'; preferredInstall = 'bundle install';
+    } else if (stackKeys.has('java') || stackKeys.has('kotlin')) {
+      preferredTest = './gradlew test'; preferredInstall = './gradlew build';
+    } else if (stackKeys.has('elixir')) {
+      preferredTest = 'mix test'; preferredInstall = 'mix deps.get';
+    } else if (stackKeys.has('dotnet')) {
+      preferredTest = 'dotnet test'; preferredInstall = 'dotnet restore';
+    }
+    if (preferredTest) {
+      for (const r of results) {
+        if (typeof r.fix !== 'string') continue;
+        if (/\bnpm\s+test\b/i.test(r.fix)) r.fix = r.fix.replace(/`npm\s+test`/gi, '`' + preferredTest + '`').replace(/\bnpm\s+test\b/gi, preferredTest);
+        if (/\bnpm\s+ci\b/i.test(r.fix) && preferredInstall) r.fix = r.fix.replace(/`npm\s+ci`/gi, '`' + preferredInstall + '`').replace(/\bnpm\s+ci\b/gi, preferredInstall);
+        if (/\bnpm\s+install\b/i.test(r.fix) && preferredInstall) r.fix = r.fix.replace(/`npm\s+install`/gi, '`' + preferredInstall + '`').replace(/\bnpm\s+install\b/gi, preferredInstall);
+      }
+    }
+  }
+
   const result = {
     platform: spec.platform,
     platformLabel: spec.platformLabel,

package/src/codex/techniques.js

@@ -1,9 +1,9 @@
 const os = require('os');
-const path = require('path');
-const { EMBEDDED_SECRET_PATTERNS, containsEmbeddedSecret } = require('../secret-patterns');
-const { attachSourceUrls } = require('../source-urls');
-const { buildSupplementalChecks } = require('../supplemental-checks');
-const { resolveProjectStateReadPath } = require('../state-paths');
+const path = require('path');
+const { EMBEDDED_SECRET_PATTERNS, containsEmbeddedSecret } = require('../secret-patterns');
+const { attachSourceUrls } = require('../source-urls');
+const { buildSupplementalChecks } = require('../supplemental-checks');
+const { resolveProjectStateReadPath } = require('../state-paths');
 
 const CODEX_SUPPLEMENTAL_SOURCE_URLS = {
   'testing-strategy': 'https://developers.openai.com/codex/cli',
@@ -157,7 +157,14 @@ function hasCommandMention(content, category) {
 }
 
 function agentsHasArchitecture(content) {
-  return /```mermaid|flowchart\b|graph\s+(TD|LR|RL|BT)\b|##\s+Architecture\b|##\s+Project Map\b|##\s+Structure\b/i.test(content);
+  // Explicit architecture/structure markers
+  if (/```mermaid|flowchart\b|graph\s+(TD|LR|RL|BT)\b/i.test(content)) return true;
+  // Heading variants seen in real repos (openai-agents-python, etc.)
+  if (/^#{1,4}\s+(Architecture|Project Map|Structure|Project Structure( Guide)?|Repo Structure( & Important Files)?|Repository Layout|Codebase (Guide|Map|Overview|Structure)|Repo Map|Key Directories|Module Map|Directory Layout|Folder Structure|Package Structure)\b/im.test(content)) return true;
+  // Enumerated file/directory maps (3+ backtick-wrapped paths in a row)
+  const pathList = content.match(/^[-*]?\s*`[^`]+\/`?/gm);
+  if (pathList && pathList.length >= 3) return true;
+  return false;
 }
 
 function findFillerLine(content) {
@@ -345,7 +352,31 @@ function projectMcpServers(ctx) {
   return config.data.mcp_servers;
 }
 
+function isSdkOrLibraryRepo(ctx) {
+  const pkg = ctx.fileContent('package.json');
+  if (pkg) {
+    try {
+      const parsed = JSON.parse(pkg);
+      // Library if it declares a main/exports/module entry AND no start script that runs a server
+      const hasEntry = parsed.main || parsed.exports || parsed.module;
+      const scripts = parsed.scripts || {};
+      const hasServerStart = /(node|uvicorn|gunicorn).*(server|app|index\.js)/i.test(JSON.stringify(scripts));
+      if (hasEntry && !hasServerStart) return true;
+    } catch { /* fall through */ }
+  }
+  const pyproject = ctx.fileContent('pyproject.toml') || '';
+  if (/\[project\][^\[]*\b(packages|py_modules)\s*=/i.test(pyproject) && !ctx.hasDir('app') && !ctx.hasDir('server')) return true;
+  // README signals
+  const readme = ctx.fileContent('README.md') || '';
+  if (/\b(npm install|pip install|pnpm add|yarn add)\b.*\b(this|the)? ?(package|library|sdk)/i.test(readme)) return true;
+  if (/^# .*\bSDK\b/im.test(readme)) return true;
+  return false;
+}
+
 function repoNeedsExternalTools(ctx) {
+  // SDK/library repos document integrations but don't need project-scoped MCP.
+  if (isSdkOrLibraryRepo(ctx)) return false;
+
   const deps = ctx.projectDependencies ? Object.keys(ctx.projectDependencies()) : [];
   const depSet = new Set(deps);
   const files = new Set(ctx.files || []);
@@ -639,12 +670,27 @@ function skillArtifacts(ctx) {
   }));
 }
 
+function extractFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  if (!match) return null;
+  const fm = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const m = line.match(/^([a-zA-Z_-]+)\s*:\s*(.+)$/);
+    if (m) fm[m[1].trim()] = m[2].trim().replace(/^["']|["']$/g, '');
+  }
+  return fm;
+}
+
 function extractSkillTitle(content) {
+  const fm = extractFrontmatter(content);
+  if (fm && fm.name) return fm.name;
   const match = content.match(/^#\s+(.+)$/m);
   return match ? match[1].trim() : '';
 }
 
 function extractSkillDescription(content) {
+  const fm = extractFrontmatter(content);
+  if (fm && fm.description) return fm.description;
   const lines = content.split(/\r?\n/);
   const meaningful = [];
   let seenHeading = false;
@@ -1116,8 +1162,16 @@ function requirementsTomlIssue(ctx) {
 
 function sharedOrManagedMachineSignals(ctx) {
   const docs = docsBundle(ctx);
-  return Boolean(ctx.fileContent('requirements.toml')) ||
-    /\bshared\b|\bmanaged\b|\badmin[- ]enforced\b|\bmulti-user\b|\benterprise\b|\bkiosk\b|\bvdi\b/i.test(docs);
+  if (ctx.fileContent('requirements.toml')) return true;
+  // Explicit workstation/admin context only — not generic "shared" or "managed" words.
+  // Must match specific managed-device or multi-user terminology.
+  if (/\bmanaged[- ](device|laptop|workstation|host)\b/i.test(docs)) return true;
+  if (/\bshared[- ](workstation|host|laptop|machine|computer)\b/i.test(docs)) return true;
+  if (/\bmulti-user[- ](host|machine|workstation)\b/i.test(docs)) return true;
+  if (/\b(kiosk|vdi|virtual desktop)\b/i.test(docs)) return true;
+  if (/\benterprise[- ](managed|deployment|workstation)\b/i.test(docs)) return true;
+  if (/\badmin[- ]enforced\b/i.test(docs)) return true;
+  return false;
 }
 
 function authCredentialsStoreIssue(ctx) {
@@ -3049,17 +3103,30 @@ const CODEX_TECHNIQUES = {
     id: 'CX-N03',
     name: 'Pack recommendations are grounded in detected signals',
     check: (ctx) => {
-      // This check validates that the project has enough signals for meaningful pack recommendation
+      // Ecosystem-neutral grounding: any primary manifest counts.
       const agents = agentsContent(ctx);
       const config = ctx.configContent ? (ctx.configContent() || '') : (ctx.fileContent('.codex/config.toml') || '');
-      const hasPkg = Boolean(ctx.jsonFile('package.json'));
+      const manifestFiles = [
+        'package.json', 'pyproject.toml', 'Cargo.toml', 'go.mod',
+        'Gemfile', 'composer.json', 'pom.xml', 'build.gradle',
+        'flake.nix', 'shard.yml', 'mix.exs', 'rebar.config',
+        'Makefile', 'CMakeLists.txt', 'Package.swift', 'pubspec.yaml',
+      ];
+      const hasManifest = manifestFiles.some(f => ctx.files.includes(f));
+      // Dotfiles/config-only repos: they don't ship code, so pack recommendations
+      // aren't meaningful — N/A is the correct answer.
+      const dotfilesSignals = ['.zshrc', '.bashrc', '.vimrc', '.tmux.conf', '.gitconfig', 'install.sh', 'bootstrap.sh'];
+      const looksLikeDotfiles = dotfilesSignals.filter(f => ctx.files.includes(f)).length >= 2;
+      if (looksLikeDotfiles) return null;
+      // If no signals at all, N/A rather than fail
+      if (!agents && !config && !hasManifest) return null;
       // At least 2 signal sources for grounded recommendation
-      return [Boolean(agents), Boolean(config), hasPkg].filter(Boolean).length >= 2;
+      return [Boolean(agents), Boolean(config), hasManifest].filter(Boolean).length >= 2;
     },
     impact: 'medium',
     rating: 3,
     category: 'pack-posture',
-    fix: 'Add package.json and AGENTS.md so pack recommendations can be grounded in real project signals.',
+    fix: 'Add AGENTS.md and ensure a primary manifest (package.json, pyproject.toml, Cargo.toml, go.mod, etc.) is present so pack recommendations can be grounded in real project signals.',
     template: 'codex-agents-md',
     file: () => 'AGENTS.md',
     line: () => 1,
@@ -3098,15 +3165,15 @@ const CODEX_TECHNIQUES = {
   // CP-08: New checks (O. Repeat-Usage Hygiene)
   // =============================================
 
-  codexSnapshotRetention: {
-    id: 'CX-O01',
-    name: 'At least one prior audit snapshot exists for repeat-usage',
-    check: (ctx) => {
-      try {
-        const indexPath = resolveProjectStateReadPath(ctx.dir, 'snapshots', 'index.json');
-        const fs = require('fs');
-        if (!fs.existsSync(indexPath)) return null; // No snapshots yet, not a failure
-        const entries = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+  codexSnapshotRetention: {
+    id: 'CX-O01',
+    name: 'At least one prior audit snapshot exists for repeat-usage',
+    check: (ctx) => {
+      try {
+        const indexPath = resolveProjectStateReadPath(ctx.dir, 'snapshots', 'index.json');
+        const fs = require('fs');
+        if (!fs.existsSync(indexPath)) return null; // No snapshots yet, not a failure
+        const entries = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
         return Array.isArray(entries) && entries.length > 0;
       } catch {
         return null;
@@ -3121,15 +3188,15 @@ const CODEX_TECHNIQUES = {
     line: () => null,
   },
 
-  codexFeedbackLoopHealth: {
-    id: 'CX-O02',
-    name: 'Feedback loop is functional when feedback has been submitted',
-    check: (ctx) => {
-      try {
-        const indexPath = resolveProjectStateReadPath(ctx.dir, 'outcomes', 'index.json');
-        const fs = require('fs');
-        if (!fs.existsSync(indexPath)) return null; // No feedback yet, not a failure
-        const entries = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+  codexFeedbackLoopHealth: {
+    id: 'CX-O02',
+    name: 'Feedback loop is functional when feedback has been submitted',
+    check: (ctx) => {
+      try {
+        const indexPath = resolveProjectStateReadPath(ctx.dir, 'outcomes', 'index.json');
+        const fs = require('fs');
+        if (!fs.existsSync(indexPath)) return null; // No feedback yet, not a failure
+        const entries = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
         return Array.isArray(entries) && entries.length > 0;
       } catch {
         return null;
@@ -3144,15 +3211,15 @@ const CODEX_TECHNIQUES = {
     line: () => null,
   },
 
-  codexTrendDataAvailability: {
-    id: 'CX-O03',
-    name: 'Trend data is computable (2+ snapshots with compatible schemas)',
-    check: (ctx) => {
-      try {
-        const indexPath = resolveProjectStateReadPath(ctx.dir, 'snapshots', 'index.json');
-        const fs = require('fs');
-        if (!fs.existsSync(indexPath)) return null;
-        const entries = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+  codexTrendDataAvailability: {
+    id: 'CX-O03',
+    name: 'Trend data is computable (2+ snapshots with compatible schemas)',
+    check: (ctx) => {
+      try {
+        const indexPath = resolveProjectStateReadPath(ctx.dir, 'snapshots', 'index.json');
+        const fs = require('fs');
+        if (!fs.existsSync(indexPath)) return null;
+        const entries = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
         const audits = (Array.isArray(entries) ? entries : []).filter(e => e.snapshotKind === 'audit');
         return audits.length >= 2;
       } catch {
@@ -3342,8 +3409,25 @@ const CODEX_TECHNIQUES = {
 
   codexPythonFormatterConfigured: {
     id: 'CX-PY08',
-    name: 'Formatter configured (black / isort / ruff format)',
-    check: (ctx) => { const hasPy = ctx.files.some(f => /pyproject\.toml$|requirements\.txt$|setup\.py$|manage\.py$/.test(f)); if (!hasPy) return null; const pp = ctx.fileContent('pyproject.toml') || ''; return /\[tool\.black|\[tool\.isort|\[tool\.ruff\.format/i.test(pp); },
+    name: 'Formatter configured (black / isort / ruff / yapf)',
+    check: (ctx) => {
+      const hasPy = ctx.files.some(f => /pyproject\.toml$|requirements\.txt$|setup\.py$|manage\.py$/.test(f));
+      if (!hasPy) return null;
+      const pp = ctx.fileContent('pyproject.toml') || '';
+      // Explicit formatter sections
+      if (/\[tool\.black|\[tool\.isort|\[tool\.ruff\.format|\[tool\.yapf|\[tool\.autopep8/i.test(pp)) return true;
+      // Ruff config implies formatting capability in modern setups (ruff 0.3+)
+      if (/\[tool\.ruff(\.lint)?\]/i.test(pp)) return true;
+      // Standalone config files
+      if (ctx.files.some(f => /^(ruff\.toml|\.ruff\.toml|\.isort\.cfg|\.yapfrc|setup\.cfg)$/i.test(f))) {
+        const setupCfg = ctx.fileContent('setup.cfg') || '';
+        if (/\[isort\]|\[yapf\]|\[flake8\]/i.test(setupCfg)) return true;
+        if (f => /ruff|yapf|isort/i.test(f)) return true;
+      }
+      // Dev dependency signal
+      if (/\b(black|isort|ruff|yapf|autopep8)\b/i.test(pp)) return true;
+      return false;
+    },
     impact: 'medium',
     category: 'python',
     fix: 'Configure black, isort, or ruff format in pyproject.toml.',
@@ -3365,7 +3449,24 @@ const CODEX_TECHNIQUES = {
   codexPythonFastapiEntryDocumented: {
     id: 'CX-PY10',
     name: 'FastAPI entry point documented if FastAPI project',
-    check: (ctx) => { const hasPy = ctx.files.some(f => /pyproject\.toml$|requirements\.txt$|setup\.py$|manage\.py$/.test(f)); if (!hasPy) return null; const deps = (ctx.fileContent('pyproject.toml') || '') + (ctx.fileContent('requirements.txt') || ''); if (!/fastapi/i.test(deps)) return null; const docs = (ctx.claudeMdContent ? ctx.claudeMdContent() : ctx.fileContent('CLAUDE.md')) || ctx.fileContent('README.md') || ''; return /fastapi|uvicorn|app\.py|main\.py/i.test(docs); },
+    check: (ctx) => {
+      const hasPy = ctx.files.some(f => /pyproject\.toml$|requirements\.txt$|setup\.py$|manage\.py$/.test(f));
+      if (!hasPy) return null;
+      const pp = ctx.fileContent('pyproject.toml') || '';
+      const reqs = ctx.fileContent('requirements.txt') || '';
+      // FastAPI only in dev/optional/example deps → N/A (SDK with example server)
+      const inMain = /^\s*fastapi\b/im.test(reqs) ||
+                     /\[project\.dependencies\][\s\S]*?fastapi/i.test(pp) ||
+                     /\[tool\.poetry\.dependencies\][\s\S]*?fastapi/i.test(pp) ||
+                     /^\s*dependencies\s*=\s*\[[^\]]*"fastapi/im.test(pp);
+      if (!inMain) return null;
+      const docs = [
+        ctx.claudeMdContent ? ctx.claudeMdContent() : ctx.fileContent('CLAUDE.md'),
+        ctx.fileContent('README.md'),
+        ctx.fileContent('AGENTS.md'),
+      ].filter(Boolean).join('\n');
+      return /fastapi|uvicorn|app\.py|main\.py/i.test(docs);
+    },
     impact: 'high',
     category: 'python',
     fix: 'Document FastAPI entry point and how to run the development server.',
@@ -3376,7 +3477,18 @@ const CODEX_TECHNIQUES = {
   codexPythonMigrationsDocumented: {
     id: 'CX-PY11',
     name: 'Database migrations mentioned (alembic / Django migrations)',
-    check: (ctx) => { const hasPy = ctx.files.some(f => /pyproject\.toml$|requirements\.txt$|setup\.py$|manage\.py$/.test(f)); if (!hasPy) return null; const docs = (ctx.claudeMdContent ? ctx.claudeMdContent() : ctx.fileContent('CLAUDE.md')) || ctx.fileContent('README.md') || ''; return /alembic|migrate|makemigrations|django.{0,10}migration/i.test(docs) || ctx.files.some(f => /alembic[.]ini$|alembic[/]/.test(f)); },
+    check: (ctx) => {
+      const hasPy = ctx.files.some(f => /pyproject\.toml$|requirements\.txt$|setup\.py$|manage\.py$/.test(f));
+      if (!hasPy) return null;
+      // SDK/library repos don't need migration docs
+      if (isSdkOrLibraryRepo(ctx)) return null;
+      // Only applicable when repo actually uses a database
+      const deps = (ctx.fileContent('pyproject.toml') || '') + (ctx.fileContent('requirements.txt') || '');
+      const hasDb = /sqlalchemy|django|peewee|tortoise|asyncpg|psycopg|pymongo|pymysql|alembic/i.test(deps);
+      if (!hasDb) return null;
+      const docs = (ctx.claudeMdContent ? ctx.claudeMdContent() : ctx.fileContent('CLAUDE.md')) || ctx.fileContent('README.md') || '';
+      return /alembic|migrate|makemigrations|django.{0,10}migration/i.test(docs) || ctx.files.some(f => /alembic[.]ini$|alembic[/]/.test(f));
+    },
     impact: 'medium',
     category: 'python',
     fix: 'Document database migration workflow (alembic or Django migrations).',
@@ -3464,7 +3576,31 @@ const CODEX_TECHNIQUES = {
   codexPythonPackageStructure: {
     id: 'CX-PY19',
     name: 'Python package has proper structure (src/ layout or __init__.py)',
-    check: (ctx) => { const hasPy = ctx.files.some(f => /pyproject\.toml$|requirements\.txt$|setup\.py$|manage\.py$/.test(f)); if (!hasPy) return null; return ctx.files.some(f => /src[/].*[/]__init__\.py$|^[^/]+[/]__init__\.py$/.test(f)); },
+    check: (ctx) => {
+      const hasPy = ctx.files.some(f => /pyproject\.toml$|requirements\.txt$|setup\.py$|manage\.py$/.test(f));
+      if (!hasPy) return null;
+      const fs = require('fs');
+      const path = require('path');
+      // ctx.files only lists root — probe common package layouts directly
+      try {
+        // src/ layout: look for any src/*/__init__.py
+        const srcDir = path.join(ctx.dir, 'src');
+        if (fs.existsSync(srcDir) && fs.statSync(srcDir).isDirectory()) {
+          const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+          for (const e of entries) {
+            if (e.isDirectory() && fs.existsSync(path.join(srcDir, e.name, '__init__.py'))) return true;
+          }
+        }
+        // Flat layout: <package>/__init__.py at root
+        const rootEntries = fs.readdirSync(ctx.dir, { withFileTypes: true });
+        for (const e of rootEntries) {
+          if (e.isDirectory() && !e.name.startsWith('.') && e.name !== 'tests' && e.name !== 'docs') {
+            if (fs.existsSync(path.join(ctx.dir, e.name, '__init__.py'))) return true;
+          }
+        }
+      } catch { /* fall through */ }
+      return false;
+    },
     impact: 'medium',
     category: 'python',
     fix: 'Use src/ layout or ensure packages have __init__.py files.',

package/src/cursor/context.js

@@ -36,16 +36,36 @@ class CursorProjectContext extends ProjectContext {
    * NOTE: Subdirectories inside .cursor/rules/ are silently ignored by Cursor.
    */
   cursorRules() {
-    const dir = path.join(this.dir, '.cursor', 'rules');
-    const files = listFiles(dir, f => f.endsWith('.mdc'));
+    const fs = require('fs');
+    const rulesPath = path.join(this.dir, '.cursor', 'rules');
+    let dir = rulesPath;
+    let basePath = '.cursor/rules';
+
+    // File-redirect pattern: .cursor/rules is a file pointing to another path
+    // (e.g., cal.com uses agents/rules/ with .cursor/rules as a text pointer).
+    try {
+      const stat = fs.statSync(rulesPath);
+      if (stat.isFile()) {
+        const redirect = fs.readFileSync(rulesPath, 'utf8').trim();
+        if (redirect && redirect.length < 500) {
+          const resolved = path.resolve(path.dirname(rulesPath), redirect);
+          if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+            dir = resolved;
+            basePath = path.relative(this.dir, resolved).replace(/\\/g, '/');
+          }
+        }
+      }
+    } catch { /* .cursor/rules may not exist — fall through to empty list */ }
+
+    const files = listFiles(dir, f => f.endsWith('.mdc') || f.endsWith('.md'));
     return files.map(f => {
-      const relPath = `.cursor/rules/${f}`;
+      const relPath = `${basePath}/${f}`;
       const content = this.fileContent(relPath);
       if (!content) return null;
       const parsed = parseMdc(content);
       const ruleType = detectRuleType(parsed.frontmatter);
       return {
-        name: f.replace('.mdc', ''),
+        name: f.replace(/\.(mdc|md)$/, ''),
         path: relPath,
         frontmatter: parsed.frontmatter,
         body: parsed.body,

package/src/cursor/techniques.js

@@ -14,12 +14,12 @@
 const os = require('os');
 const path = require('path');
 const { CursorProjectContext } = require('./context');
-const { EMBEDDED_SECRET_PATTERNS, containsEmbeddedSecret } = require('../secret-patterns');
-const { attachSourceUrls } = require('../source-urls');
-const { buildStackChecks } = require('../stack-checks');
-const { isApiProject, isDatabaseProject, isAuthProject, isMonitoringRelevant } = require('../supplemental-checks');
-const { hasCostBudgetOrUsageTracking } = require('../cost-tracking');
-const { validateMdcFrontmatter, validateMcpEnvVars } = require('./config-parser');
+const { EMBEDDED_SECRET_PATTERNS, containsEmbeddedSecret } = require('../secret-patterns');
+const { attachSourceUrls } = require('../source-urls');
+const { buildStackChecks } = require('../stack-checks');
+const { isApiProject, isDatabaseProject, isAuthProject, isMonitoringRelevant } = require('../supplemental-checks');
+const { hasCostBudgetOrUsageTracking } = require('../cost-tracking');
+const { validateMdcFrontmatter, validateMcpEnvVars } = require('./config-parser');
 
 // ─── Shared helpers ─────────────────────────────────────────────────────────
 
@@ -180,6 +180,10 @@ const CURSOR_TECHNIQUES = {
     name: 'No .cursorrules without migration warning',
     check: (ctx) => {
       const hasLegacy = ctx.hasLegacyRules ? ctx.hasLegacyRules() : Boolean(ctx.fileContent('.cursorrules'));
+      const hasNewRules = ctx.cursorRules ? ctx.cursorRules().length > 0 : false;
+      const hasMcp = Boolean(ctx.fileContent('.cursor/mcp.json'));
+      // N/A when repo has no Cursor configuration at all — don't reward absence
+      if (!hasLegacy && !hasNewRules && !hasMcp) return null;
       return !hasLegacy;
     },
     impact: 'critical',
@@ -507,17 +511,21 @@ const CURSOR_TECHNIQUES = {
 
   cursorPrivacyMode: {
     id: 'CU-C01',
-    name: 'Privacy Mode enabled (or explicitly documented as off)',
+    name: 'Privacy Mode documented in rules/docs',
     check: (ctx) => {
-      // Cannot detect Privacy Mode from files (stored in SQLite state.vscdb)
-      // Check if rules/docs document the privacy mode status
+      // Privacy Mode is an IDE setting stored in SQLite state.vscdb — not auditable
+      // from repo files. This check validates that the repo documents its stance.
+      const hasNewRules = ctx.cursorRules ? ctx.cursorRules().length > 0 : false;
+      const hasLegacy = ctx.hasLegacyRules ? ctx.hasLegacyRules() : Boolean(ctx.fileContent('.cursorrules'));
+      // N/A when no rules exist to check against
+      if (!hasNewRules && !hasLegacy) return null;
       const docs = docsBundle(ctx);
       return /privacy mode|zero.?retention|data retention|privacy.*enabled/i.test(docs);
     },
-    impact: 'critical',
-    rating: 5,
+    impact: 'low',
+    rating: 3,
     category: 'trust',
-    fix: 'Privacy Mode is OFF by default — code is sent to all third-party providers (OpenAI, Anthropic, etc.) unless explicitly enabled. Enable in Cursor Settings → Privacy → Privacy Mode, or document the deliberate decision to keep it off.',
+    fix: 'Privacy Mode is OFF by default in Cursor — code is sent to providers unless enabled. Document your stance in a rules file so contributors know whether Privacy Mode is expected on/off. Enable in Cursor Settings → Privacy → Privacy Mode.',
     template: null,
     file: () => '.cursor/rules/',
     line: () => null,
@@ -1323,12 +1331,32 @@ const CURSOR_TECHNIQUES = {
     check: (ctx) => {
       const docs = docsBundle(ctx);
       if (!docs.trim()) return null;
-      return /bugbot|bug.?bot|automated.*pr.*review/i.test(docs);
+      // BugBot is an optional Cursor enterprise feature requiring separate installation.
+      // Return N/A unless there is actual evidence the repo uses or intends to use BugBot.
+      const files = new Set(ctx.files || []);
+      const hasBugbotConfigFile = ['bugbot.yml', 'bugbot.yaml', '.bugbot.yml', '.bugbot.yaml'].some(f => files.has(f));
+      let hasBugbotWorkflow = false;
+      try {
+        const fs = require('fs');
+        const path = require('path');
+        const wfDir = path.join(ctx.dir, '.github', 'workflows');
+        if (fs.existsSync(wfDir)) {
+          const wfFiles = fs.readdirSync(wfDir).filter(f => /\.ya?ml$/i.test(f));
+          for (const f of wfFiles) {
+            const content = fs.readFileSync(path.join(wfDir, f), 'utf8');
+            if (/bugbot|bug.?bot/i.test(content)) { hasBugbotWorkflow = true; break; }
+          }
+        }
+      } catch { /* no workflows dir */ }
+      const mentionedInDocs = /bugbot|bug.?bot|automated.*pr.*review/i.test(docs);
+      // N/A when no signal at all that this repo uses/wants BugBot
+      if (!hasBugbotConfigFile && !hasBugbotWorkflow && !mentionedInDocs) return null;
+      return hasBugbotConfigFile || hasBugbotWorkflow || mentionedInDocs;
     },
-    impact: 'medium',
+    impact: 'low',
     rating: 3,
     category: 'bugbot',
-    fix: 'Enable BugBot for automated PR code review on critical repos.',
+    fix: 'If you use BugBot for automated PR code review, document it in your rules or add the BugBot workflow. Otherwise ignore this check.',
     template: null,
     file: () => '.cursor/rules/',
     line: () => null,
@@ -2212,17 +2240,17 @@ const CURSOR_TECHNIQUES = {
     fix: 'Enable prompt caching in MCP configuration or document caching strategy for repeated prompts.',
     template: null, file: () => '.cursor/mcp.json', line: () => null,
   },
-  cursorCostBudgetDefined: {
-    id: 'CU-T48', name: 'AI cost budget or per-run usage tracking documented',
-    check: (ctx) => {
-      const docs = docsBundle(ctx) + (ctx.fileContent('CLAUDE.md') || '');
-      if (!docs.trim() && !hasCostBudgetOrUsageTracking('', ctx)) return null;
-      return hasCostBudgetOrUsageTracking(docs, ctx);
-    },
-    impact: 'low', rating: 2, category: 'cost-optimization',
-    fix: 'Document AI cost guardrails or per-run usage tracking in README.md or Cursor rules so spend is observable, not guessed.',
-    template: null, file: () => 'README.md', line: () => null,
-  },
+  cursorCostBudgetDefined: {
+    id: 'CU-T48', name: 'AI cost budget or per-run usage tracking documented',
+    check: (ctx) => {
+      const docs = docsBundle(ctx) + (ctx.fileContent('CLAUDE.md') || '');
+      if (!docs.trim() && !hasCostBudgetOrUsageTracking('', ctx)) return null;
+      return hasCostBudgetOrUsageTracking(docs, ctx);
+    },
+    impact: 'low', rating: 2, category: 'cost-optimization',
+    fix: 'Document AI cost guardrails or per-run usage tracking in README.md or Cursor rules so spend is observable, not guessed.',
+    template: null, file: () => 'README.md', line: () => null,
+  },
 
   // ============================================================
   // === PYTHON STACK CHECKS (category: 'python') ===============