@nerviq/cli 0.9.1 → 0.9.3

package/README.md

@@ -1,52 +1,137 @@
-# claudex-setup → Nerviq
+# Nerviq
 
-> **This project has been renamed and expanded to [Nerviq](https://github.com/nerviq/nerviq).**
+> The intelligent nervous system for AI coding agents — audit, align, and amplify every platform on every project.
 
-## What changed
+[![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)
 
-`claudex-setup` started as a Claude Code audit tool (85 checks, single platform).
+---
 
-**Nerviq** is the next generation — the intelligent nervous system for **all** AI coding agents:
+### ⚠️ Beta — Currently Claude Code only
 
-- **8 platforms**: Claude Code, Codex, Gemini CLI, GitHub Copilot, Cursor, Windsurf, Aider, OpenCode
-- **639 checks** across all platforms
-- **Harmony**: detect drift between agents on the same project
-- **Synergy**: make agents amplify each other (1+1+1 > 3)
-- **135 modules**, 172 exports
+Nerviq is in **beta**. The current release fully supports **Claude Code** (90 checks, audit, setup, governance, benchmark).
 
-## Install the new version
+**Coming soon:**
+- Codex (OpenAI)
+- Gemini CLI (Google)
+- GitHub Copilot
+- Cursor
+- Windsurf
+- Aider
+- OpenCode
+- **Harmony** — cross-platform drift detection
+- **Synergy** — multi-agent amplification
+
+---
+
+## 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.
 
-```bash
-npm i -g @nerviq/cli
 ```
+  nerviq audit
+  ═══════════════════════════════════════
+  Detected: React, TypeScript, Docker
+
+  ████████████████░░░░ 78/100
+
+  ✅ CLAUDE.md with architecture diagram
+  ✅ Hooks (PreToolUse + PostToolUse)
+  ✅ Custom skills (3 skills)
+  ✅ MCP servers configured
 
-## Usage
+  ⚡ 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/
+
+  Next: nerviq setup
+```
+
+## Quick Start
 
 ```bash
-nerviq audit                        # Audit Claude Code (default)
-nerviq audit --platform codex       # Audit Codex setup
-nerviq audit --platform gemini      # Audit Gemini CLI setup
-nerviq audit --platform copilot     # Audit GitHub Copilot setup
-nerviq audit --platform cursor      # Audit Cursor setup
-nerviq audit --platform windsurf    # Audit Windsurf setup
-nerviq audit --platform aider       # Audit Aider setup
-nerviq audit --platform opencode    # Audit OpenCode setup
-
-nerviq harmony-audit                # Cross-platform harmony score
-nerviq synergy-report               # Synergy amplification report
+npx @nerviq/cli audit              # Score your project (10 seconds)
+npx @nerviq/cli audit --lite       # Quick top-3 scan
+npx @nerviq/cli setup              # Generate starter-safe baseline
+npx @nerviq/cli augment            # Improvement plan, no writes
+npx @nerviq/cli governance         # Permission profiles + policy packs
+npx @nerviq/cli benchmark          # Before/after in isolated copy
 ```
 
+No install required. Zero dependencies.
+
+## 90 Checks Across 14 Categories
+
+| Category | Checks | Examples |
+|----------|--------|---------|
+| Memory & Context | 9 | CLAUDE.md, architecture, @path imports, CLAUDE.local.md |
+| Quality | 8 | verification loops, test/lint/build commands |
+| Security | 7 | permissions, deny rules, secrets detection |
+| Automation | 8 | hooks (30+ event types), notification, subagent tracking |
+| Workflow | 9 | skills, subagents, rules, commands, snapshots |
+| Git & Hygiene | 14 | .gitignore, env protection, README, changelog |
+| Tools & MCP | 4 | .mcp.json, Context7, multi-server |
+| Prompting | 6 | XML tags, constraints, examples, role definition |
+| DevOps | 5 | Docker, CI, Terraform |
+| Design | 2 | frontend anti-slop, Tailwind |
+| Performance | 3 | compaction, context management, effort level |
+| Features | 2 | channels, worktrees |
+| Quality Deep | 9 | freshness, contradictions, deprecated patterns |
+
+## All Commands
+
+| Command | What it does |
+|---------|-------------|
+| `nerviq audit` | Score 0-100 against 90 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) |
+| `nerviq suggest-only` | Structured report for sharing |
+| `nerviq plan` | Export proposal bundles with previews |
+| `nerviq apply` | Apply proposals with rollback |
+| `nerviq governance` | Permission profiles, hooks, policy packs |
+| `nerviq benchmark` | Before/after in isolated temp copy |
+| `nerviq deep-review` | AI-powered config review (opt-in) |
+| `nerviq interactive` | Step-by-step guided wizard |
+| `nerviq watch` | Live monitoring with score delta |
+| `nerviq history` | Score history from snapshots |
+| `nerviq compare` | Compare latest vs previous |
+| `nerviq trend` | Export trend report |
+| `nerviq feedback` | Record recommendation outcomes |
+| `nerviq badge` | shields.io badge for README |
+| `nerviq scan dir1 dir2` | Compare multiple repos |
+
+## Options
+
+| Flag | Effect |
+|------|--------|
+| `--threshold N` | Exit 1 if score < N (for CI) |
+| `--json` | Machine-readable JSON output |
+| `--out FILE` | Write output to file |
+| `--snapshot` | Save audit snapshot for trending |
+| `--lite` | Compact top-3 quick scan |
+| `--dry-run` | Preview apply without writing |
+| `--auto` | Apply without prompts |
+| `--verbose` | Show all recommendations |
+| `--format sarif` | SARIF output for code scanning |
+
+## Privacy
+
+- **Zero dependencies** — nothing to audit
+- **Runs locally** — audit, setup, plan, apply, governance, benchmark all run on your machine
+- **Deep review is opt-in** — only `deep-review` sends selected config for AI analysis
+- **AGPL-3.0 Licensed** — open source
+
 ## Links
 
 - **npm**: [@nerviq/cli](https://www.npmjs.com/package/@nerviq/cli)
 - **GitHub**: [github.com/nerviq/nerviq](https://github.com/nerviq/nerviq)
 - **Website**: [nerviq.net](https://nerviq.net)
 
-## Legacy
-
-The original `claudex-setup` package on npm is deprecated. All future development happens at [@nerviq/cli](https://www.npmjs.com/package/@nerviq/cli).
+## Previously claudex-setup
 
-If you were using `claudex-setup`, simply switch:
+Nerviq was previously published as `claudex-setup`. If you were using it:
 
 ```bash
 # Old
@@ -56,4 +141,4 @@ npx claudex-setup
 npx @nerviq/cli audit
 ```
 
-All features from claudex-setup are preserved and expanded in Nerviq.
+All features are preserved and expanded.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerviq/cli",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "The intelligent nervous system for AI coding agents — audit, align, and amplify every platform on every project.",
   "main": "src/index.js",
   "bin": {

package/src/aider/techniques.js

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

package/src/copilot/techniques.js

@@ -1,11 +1,12 @@
 /**
  * Copilot techniques module — CHECK CATALOG
  *
- * 82 checks across 16 categories:
+ * 86 checks across 17 categories:
  *   v0.1 (38): A. Instructions(8), B. Config(6), C. Trust & Safety(9), D. MCP(5), E. Cloud Agent(5), F. Organization(5)
  *   v0.5 (54): G. Prompt Files(4), H. Agents & Skills(4), I. VS Code IDE(4), J. CLI(4)
  *   v1.0 (70): K. Cross-Surface(5), L. Enterprise(5), M. Quality Deep(6)
- *   CP-08 (82): N. Advisory(4), O. Pack(4), P. Repeat(3), Q. Freshness(3)
+ *   CP-08 (82): N. Advisory(4), O. Pack(4), P. Repeat(3)
+ *   v1.1 (87): Q. Experiment-Verified CLI Fixes (CLI ingests AGENTS.md/CLAUDE.md, mcpServers key, VS Code settings not CLI-relevant, org policy MCP blocks, BYOK MCP caveat)
  *
  * Each check: { id, name, check(ctx), impact, rating, category, fix, template, file(), line() }
  */
@@ -313,18 +314,19 @@ const COPILOT_TECHNIQUES = {
 
   copilotVscodeSettingsExists: {
     id: 'CP-B01',
-    name: '.vscode/settings.json has Copilot agent settings',
+    name: '.vscode/settings.json has Copilot agent settings (VS Code-only)',
     check: (ctx) => {
       const data = vscodeSettingsData(ctx);
       if (!data) return false;
       // Check for any Copilot or chat-related key
+      // NOTE: These settings affect VS Code only. Copilot CLI ignores them.
       const raw = vscodeSettingsRaw(ctx);
       return /github\.copilot|chat\./.test(raw);
     },
     impact: 'medium',
     rating: 4,
     category: 'config',
-    fix: 'Add Copilot agent settings to .vscode/settings.json.',
+    fix: 'Add Copilot agent settings to .vscode/settings.json. NOTE: These are VS Code-only — Copilot CLI has its own configuration surface.',
     template: 'copilot-vscode-settings',
     file: () => '.vscode/settings.json',
     line: () => 1,
@@ -491,19 +493,20 @@ const COPILOT_TECHNIQUES = {
 
   copilotTerminalSandboxEnabled: {
     id: 'CP-C03',
-    name: 'Terminal sandbox enabled (VS Code agent)',
+    name: 'Terminal sandbox enabled (VS Code-only — does NOT affect CLI)',
     check: (ctx) => {
       const data = vscodeSettingsData(ctx);
       if (!data) return false;
       const raw = vscodeSettingsRaw(ctx);
       // Check for chat.tools.terminal.sandbox.enabled = true
+      // NOTE: This setting is VS Code-specific. Copilot CLI ignores it entirely.
       if (raw.includes('terminal.sandbox') && raw.includes('true')) return true;
       return getCopilotSetting(ctx, 'chat.tools.terminal.sandbox.enabled') === true;
     },
     impact: 'high',
     rating: 5,
     category: 'trust',
-    fix: 'Add "chat.tools.terminal.sandbox.enabled": true to .vscode/settings.json.',
+    fix: 'Add "chat.tools.terminal.sandbox.enabled": true to .vscode/settings.json. NOTE: This is VS Code-only — Copilot CLI uses its own permission flags, not VS Code settings.',
     template: 'copilot-vscode-settings',
     file: () => '.vscode/settings.json',
     line: (ctx) => {
@@ -533,12 +536,14 @@ const COPILOT_TECHNIQUES = {
 
   copilotAutoApprovalSpecific: {
     id: 'CP-C05',
-    name: 'Auto-approval rules are specific (not wildcard)',
+    name: 'Auto-approval rules are specific (VS Code-only — CLI uses permission flags)',
     check: (ctx) => {
       const data = vscodeSettingsData(ctx);
       if (!data) return null;
       const raw = vscodeSettingsRaw(ctx);
       // Check for auto-approval patterns
+      // NOTE: autoApproval.terminalCommands is VS Code-specific.
+      // Copilot CLI uses its own --permission flags, not this setting.
       const autoApproval = getCopilotSetting(ctx, 'chat.agent.autoApproval.terminalCommands');
       if (!autoApproval || !Array.isArray(autoApproval)) return null;
       // Fail if any wildcard patterns
@@ -547,7 +552,7 @@ const COPILOT_TECHNIQUES = {
     impact: 'high',
     rating: 5,
     category: 'trust',
-    fix: 'Replace wildcard auto-approval patterns with specific command patterns (e.g., "npm test", "npm run lint").',
+    fix: 'Replace wildcard auto-approval patterns with specific command patterns (e.g., "npm test", "npm run lint"). NOTE: This setting only affects VS Code — Copilot CLI approval is controlled by CLI permission flags.',
     template: null,
     file: () => '.vscode/settings.json',
     line: (ctx) => {
@@ -1051,11 +1056,13 @@ const COPILOT_TECHNIQUES = {
 
   copilotAgentsMdEnabled: {
     id: 'CP-H01',
-    name: 'If AGENTS.md exists, verify it is enabled in VS Code settings',
+    name: 'If AGENTS.md exists, verify it is enabled in VS Code (CLI reads it automatically)',
     check: (ctx) => {
       const agentsMd = ctx.fileContent('AGENTS.md');
       if (!agentsMd) return null; // N/A
-      // AGENTS.md support needs explicit enabling
+      // AGENTS.md support needs explicit enabling in VS Code
+      // WARNING: Copilot CLI reads AGENTS.md (and CLAUDE.md) automatically without any setting!
+      // Use --no-custom-instructions in CLI to prevent this
       const data = vscodeSettingsData(ctx);
       if (!data) return false;
       const raw = vscodeSettingsRaw(ctx);
@@ -1064,7 +1071,7 @@ const COPILOT_TECHNIQUES = {
     impact: 'critical',
     rating: 5,
     category: 'skills-agents',
-    fix: 'Enable AGENTS.md support in VS Code settings. It is off by default and silently ignored.',
+    fix: 'Enable AGENTS.md in VS Code settings (off by default). WARNING: Copilot CLI reads AGENTS.md and CLAUDE.md automatically — use --no-custom-instructions to prevent cross-platform instruction leakage.',
     template: 'copilot-vscode-settings',
     file: () => '.vscode/settings.json',
     line: (ctx) => {
@@ -1815,6 +1822,110 @@ const COPILOT_TECHNIQUES = {
     file: () => null,
     line: () => null,
   },
+
+  // =============================================
+  // Q. Experiment-Verified CLI Fixes (5 checks) — CP-Q01..CP-Q05
+  // Added from runtime experiment findings (2026-04-05)
+  // =============================================
+
+  copilotCliIngestsNonCopilotFiles: {
+    id: 'CP-Q01',
+    name: 'Aware that Copilot CLI ingests AGENTS.md and CLAUDE.md',
+    check: (ctx) => {
+      const agentsMd = ctx.fileContent('AGENTS.md');
+      const claudeMd = ctx.fileContent('CLAUDE.md');
+      if (!agentsMd && !claudeMd) return null; // No cross-platform files
+      const instr = copilotInstructions(ctx) || '';
+      // If non-Copilot instruction files exist, check that instructions acknowledge this
+      return /copilot cli|--no-custom-instructions|cross.platform|AGENTS\.md|CLAUDE\.md/i.test(instr);
+    },
+    impact: 'high',
+    rating: 4,
+    category: 'quality-deep',
+    fix: 'WARNING: Copilot CLI ingests AGENTS.md and CLAUDE.md alongside copilot-instructions.md. Document this or use --no-custom-instructions for clean runs.',
+    template: null,
+    file: () => '.github/copilot-instructions.md',
+    line: () => null,
+  },
+
+  copilotCliMcpUsesServerKey: {
+    id: 'CP-Q02',
+    name: 'CLI MCP config uses mcpServers key (not servers)',
+    check: (ctx) => {
+      const mcpData = mcpJsonData(ctx);
+      if (!mcpData) return null;
+      // CLI expects mcpServers, not servers
+      if (mcpData.servers && !mcpData.mcpServers) return false;
+      return true;
+    },
+    impact: 'high',
+    rating: 4,
+    category: 'ci-automation',
+    fix: 'Copilot CLI MCP config expects the "mcpServers" key. "servers" alone may not work in CLI context.',
+    template: null,
+    file: () => '.vscode/mcp.json',
+    line: () => 1,
+  },
+
+  copilotVscodeSettingsNotCliRelevant: {
+    id: 'CP-Q03',
+    name: 'VS Code-specific settings not assumed to affect CLI',
+    check: (ctx) => {
+      const instr = copilotInstructions(ctx) || '';
+      if (!instr) return null;
+      // If instructions reference VS Code settings as if they affect CLI, flag it
+      const mentionsCli = /copilot cli|gh copilot/i.test(instr);
+      const mentionsVscodeForCli = /chat\.tools.*cli|terminal\.sandbox.*cli|autoApproval.*cli/i.test(instr);
+      if (mentionsCli && mentionsVscodeForCli) return false;
+      return true;
+    },
+    impact: 'medium',
+    rating: 3,
+    category: 'quality-deep',
+    fix: 'VS Code settings (sandbox, autoApproval, instructionsFilesLocations) do not affect Copilot CLI. Document CLI-specific configuration separately.',
+    template: null,
+    file: () => '.github/copilot-instructions.md',
+    line: () => null,
+  },
+
+  copilotOrgPolicyBlocksMcp: {
+    id: 'CP-Q04',
+    name: 'Org policy MCP restrictions documented if applicable',
+    check: (ctx) => {
+      const instr = copilotInstructions(ctx) || '';
+      const mcpData = mcpJsonData(ctx);
+      if (!mcpData) return null;
+      const servers = mcpData.servers || mcpData.mcpServers || {};
+      if (Object.keys(servers).length === 0) return null;
+      // If MCP servers are configured, check that org policy restrictions are documented
+      return /org.policy|policy.block|third.party.*mcp|mcp.*restrict|Access denied/i.test(instr);
+    },
+    impact: 'medium',
+    rating: 3,
+    category: 'quality-deep',
+    fix: 'Document that org policies can block third-party MCP servers even in local CLI sessions. Error: "Access denied by policy settings".',
+    template: null,
+    file: () => '.github/copilot-instructions.md',
+    line: () => null,
+  },
+
+  copilotByokMcpCaveat: {
+    id: 'CP-Q05',
+    name: 'BYOK mode MCP limitations documented',
+    check: (ctx) => {
+      const instr = copilotInstructions(ctx) || '';
+      // Only relevant if BYOK is mentioned
+      if (!/byok|bring your own key|openai.*key|COPILOT_.*KEY/i.test(instr)) return null;
+      return /byok.*mcp|mcp.*byok|oauth.*broken|built.in.*github.*mcp/i.test(instr);
+    },
+    impact: 'medium',
+    rating: 3,
+    category: 'quality-deep',
+    fix: 'Document that BYOK mode breaks built-in GitHub MCP server (OAuth auth unavailable). Third-party MCP may also be restricted by org policy.',
+    template: null,
+    file: () => '.github/copilot-instructions.md',
+    line: () => null,
+  },
 };
 
 module.exports = {