@nerviq/cli 1.15.0 → 1.17.0

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.15.0",
-    "timestamp": "2026-04-11T12:00:00.000Z"
+    "version": "1.17.0",
+    "timestamp": "2026-04-12T12:00:00.000Z"
   }
 }
 ```

package/bin/cli.js

@@ -568,7 +568,8 @@ const HELP = `
   New here? Run: nerviq --beginner
 
   DISCOVER
-    nerviq audit                  Quick scan: score + top 3 gaps (default)
+    nerviq audit                  Quick scan: score + top 3 gaps (Harmony-first when 2+ platforms detected)
+    nerviq audit --no-harmony-first   Skip the cross-platform Harmony header
     nerviq audit --full           Full audit with all checks, weakest areas, badge
     nerviq audit --platform X     Audit specific platform (claude|codex|cursor|copilot|gemini|windsurf|aider|opencode)
     nerviq audit --json           Machine-readable JSON output (for CI)
@@ -846,6 +847,7 @@ async function main() {
     historyView: flags.includes('--history'),
     compareView: flags.includes('--compare'),
     diffOnly: flags.includes('--diff-only'),
+    noHarmonyFirst: flags.includes('--no-harmony-first'),
     diffBase: parsed.diffBase || null,
     diffHead: parsed.diffHead || null,
     driftMode: parsed.driftMode || null,
@@ -2504,8 +2506,32 @@ async function main() {
         }
         process.exit(0);
       }
+      // MOAT-01: Harmony-first default — when 2+ platforms and platform not explicit
+      let harmonyFirstResult = null;
+      if (!options.platformExplicit && !options.noHarmonyFirst && !options.diffOnly && !options.driftMode && !options.workspace) {
+        const detected = detectPlatforms(options.dir) || [];
+        if (detected.length >= 2) {
+          try {
+            const { harmonyAudit } = require('../src/harmony/audit');
+            harmonyFirstResult = await harmonyAudit({ dir: options.dir, silent: true });
+            if (!options.json && harmonyFirstResult) {
+              const hs = harmonyFirstResult.harmonyScore;
+              const driftCount = (harmonyFirstResult.drift && harmonyFirstResult.drift.drifts) ? harmonyFirstResult.drift.drifts.length : 0;
+              const platformLabels = (harmonyFirstResult.activePlatforms || []).map(p => p.label || p.platform).join(' + ');
+              const color = hs >= 70 ? '\x1b[32m' : hs >= 40 ? '\x1b[33m' : '\x1b[31m';
+              const issueWord = driftCount === 1 ? 'issue' : 'issues';
+              console.log('');
+              console.log(`\x1b[1m  Harmony Score: ${color}${hs}/100\x1b[0m — ${driftCount} drift ${issueWord} across ${detected.length} platforms (${platformLabels})`);
+              console.log('\x1b[2m  Run `nerviq harmony-audit` for the full cross-platform report. Use --no-harmony-first to hide.\x1b[0m');
+            }
+          } catch {
+            harmonyFirstResult = null;
+          }
+        }
+      }
+
       let result;
-      const renderAuditJsonLocally = options.json && Boolean(options.driftMode);
+      const renderAuditJsonLocally = options.json && (Boolean(options.driftMode) || Boolean(harmonyFirstResult));
       if (options.diffOnly) {
         const { getChangedFiles, buildDiffOnlyAuditView, printDiffOnlyAudit } = require('../src/diff-only');
         const fullResult = await audit({ ...options, silent: true });
@@ -2580,9 +2606,17 @@ async function main() {
           }
         }
       } else if (renderAuditJsonLocally) {
+        const harmonyEnvelope = harmonyFirstResult ? {
+          harmony: {
+            score: harmonyFirstResult.harmonyScore,
+            driftCount: (harmonyFirstResult.drift && harmonyFirstResult.drift.drifts) ? harmonyFirstResult.drift.drifts.length : 0,
+            platforms: (harmonyFirstResult.activePlatforms || []).map(p => p.platform),
+          },
+        } : {};
         console.log(JSON.stringify({
           version,
           timestamp: new Date().toISOString(),
+          ...harmonyEnvelope,
           ...result,
         }, null, 2));
       } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerviq/cli",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "description": "The intelligent nervous system for AI coding agents — 2,441 checks (8 platforms × ~300 governance rules), 10 languages, 62 domain packs. Audit, align, and amplify.",
   "main": "src/index.js",
   "bin": {

package/src/audit.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,25 @@ 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));
+      // 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 +3160,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 +3183,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 +3206,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 +3404,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 +3444,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 +3472,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 +3571,12 @@ 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;
+      // Path-separator agnostic: match both forward and back slashes (Windows compat)
+      return ctx.files.some(f => /(^|[/\\])src[/\\].*[/\\]__init__\.py$|^[^/\\]+[/\\]__init__\.py$/.test(f));
+    },
     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,
@@ -2212,17 +2220,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') ===============