@nerviq/cli 1.19.0 → 1.20.1

package/README.md

@@ -223,8 +223,8 @@ All successful operational responses are wrapped in a JSON envelope:
 {
   "data": {},
   "meta": {
-    "version": "1.19.0",
-    "timestamp": "2026-04-13T12:00:00.000Z"
+    "version": "1.20.1",
+    "timestamp": "2026-04-14T12:00:00.000Z"
   }
 }
 ```

package/bin/cli.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 // macOS pipe-flush guard: when stdout is a pipe, Node defaults to
 // non-blocking writes. `console.log(...) + process.exit(N)` then drops
 // the trailing write (empty stdout on macOS Node 18, truncation at the
@@ -2536,6 +2537,7 @@ async function main() {
     }
   } catch (err) {
     console.error(`\n  Error: ${err.message}`);
+    if (process.env.NERVIQ_DEBUG) console.error(err.stack);
     console.error('  Fix: Run `npx nerviq doctor` to diagnose common issues, or check https://github.com/nerviq/nerviq#troubleshooting');
     process.exit(2);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerviq/cli",
-  "version": "1.19.0",
+  "version": "1.20.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": {
@@ -18,6 +18,8 @@
     "build": "npm pack --dry-run",
     "test": "node test/run.js",
     "verify:release-metadata": "node tools/validate-release-metadata.js",
+    "prepublish:check": "node tools/pre-publish.js",
+    "prepublishOnly": "node tools/pre-publish.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",

package/src/aider/context.js

@@ -39,7 +39,8 @@ function detectAiderVersion() {
 
 class AiderProjectContext extends ProjectContext {
   configContent() {
-    return this.fileContent('.aider.conf.yml');
+    // Aider accepts both .yml and .yaml extensions for the project config
+    return this.fileContent('.aider.conf.yml') || this.fileContent('.aider.conf.yaml');
   }
 
   modelSettingsContent() {

package/src/context.js

@@ -83,14 +83,20 @@ class ProjectContext {
     if (!raw) return null;
 
     // If the file is very short and looks like a file reference, follow it.
-    // Pattern: a single line that is just a filename (e.g., "AGENTS.md" or "docs/CODING.md")
+    // Recognised pointer shapes on each line:
+    //   AGENTS.md
+    //   docs/CODING.md
+    //   @AGENTS.md            (Claude Code @import syntax)
+    //   @./docs/CODING.md     (Claude Code @import with relative prefix)
     const trimmed = raw.trim();
-    if (trimmed.length < 200 && /^[a-zA-Z0-9_./-]+\.(md|txt|rst)$/m.test(trimmed)) {
+    const pointerLine = /^@?\.?\/?[a-zA-Z0-9_./-]+\.(md|txt|rst)$/;
+    if (trimmed.length < 200 && pointerLine.test(trimmed.split(/\r?\n/)[0].trim())) {
       const lines = trimmed.split(/\r?\n/).map(l => l.trim()).filter(Boolean);
       let combined = raw;
       for (const line of lines) {
-        if (/^[a-zA-Z0-9_./-]+\.(md|txt|rst)$/.test(line)) {
-          const referenced = this.fileContent(line);
+        if (pointerLine.test(line)) {
+          const ref = line.replace(/^@/, '').replace(/^\.\//, '');
+          const referenced = this.fileContent(ref);
           if (referenced) {
             combined += '\n' + referenced;
           }

package/src/gemini/context.js

@@ -54,18 +54,87 @@ class GeminiProjectContext extends ProjectContext {
 
   geminiMdContent() {
     const direct = this.fileContent('GEMINI.md');
-    if (direct) return direct;
+    if (direct) return this._expandGeminiMdImports(direct);
 
-    // Fallback: use context.fileName from settings if configured
+    // Fallback: use context.fileName from settings if configured.
+    // Per Gemini CLI spec, context.fileName may be a string or an array of strings.
     const contextFileName = this.configValue('context.fileName');
-    if (contextFileName) {
-      const content = this.fileContent(contextFileName);
-      if (content) return content;
+    const candidates = Array.isArray(contextFileName)
+      ? contextFileName.filter(n => typeof n === 'string' && n.length > 0)
+      : (typeof contextFileName === 'string' && contextFileName ? [contextFileName] : []);
+    for (const name of candidates) {
+      const content = this.fileContent(name);
+      if (content) return this._expandGeminiMdImports(content);
+    }
+
+    // Further fallback: recognise common alternate instruction surfaces
+    // (AGENTS.md, CLAUDE.md) and Gemini Code Assist styleguides
+    // (.gemini/styleguide.md) even when not explicitly declared in settings,
+    // mirroring how real Gemini-using repos document guidance.
+    for (const alt of ['AGENTS.md', 'CLAUDE.md', '.gemini/styleguide.md']) {
+      const content = this.fileContent(alt);
+      if (content) return this._expandGeminiMdImports(content);
     }
 
     return null;
   }
 
+  /**
+   * Expand Gemini CLI-style imports inside an instructions file. Gemini CLI
+   * supports `@path/to/file.md` imports and treats GEMINI.md files that are
+   * a single pointer line as an alias for the referenced file. For audit
+   * purposes we concatenate the referenced bodies so substance/architecture/
+   * command checks see the effective instructions bundle.
+   */
+  _expandGeminiMdImports(content, depth = 0) {
+    if (!content || depth > 3) return content || '';
+    let out = content;
+    const importRe = /@([^\s@]+\.(?:md|markdown|MD))/g;
+    const seen = new Set();
+    let m;
+    while ((m = importRe.exec(content)) !== null) {
+      const ref = m[1].replace(/^\.\//, '');
+      if (seen.has(ref)) continue;
+      seen.add(ref);
+      const body = this.fileContent(ref);
+      if (body) out += '\n\n' + this._expandGeminiMdImports(body, depth + 1);
+    }
+    // "Pointer" GEMINI.md: the whole file is a single relative path to another
+    // markdown doc (no @ prefix). Observed in google/dotprompt.
+    const trimmed = content.trim();
+    if (/^[\w./-]+\.(md|markdown)$/.test(trimmed) && !trimmed.includes('\n')) {
+      const body = this.fileContent(trimmed);
+      if (body) out += '\n\n' + this._expandGeminiMdImports(body, depth + 1);
+    }
+    return out;
+  }
+
+  /**
+   * Returns true when the repo exposes any Gemini-recognisable instruction
+   * surface — GEMINI.md (directly or via context.fileName override), an
+   * imported pointer, AGENTS.md, or CLAUDE.md. Used to gate checks that
+   * would otherwise hard-fail on repos that use alternative conventions.
+   */
+  hasAnyInstructionsSurface() {
+    return Boolean(this.geminiMdContent());
+  }
+
+  /**
+   * Returns true when the repo exposes any evidence of Gemini CLI usage.
+   * This is deliberately narrower than `isGeminiRepo`: it also counts
+   * `.idx/airules.md` (Project IDX) and Gemini-specific settings keys.
+   */
+  hasGeminiCliSurface() {
+    if (this.fileContent('.gemini/settings.json')) return true;
+    if (this.fileContent('GEMINI.md')) return true;
+    const extDirs = this.extensionDirs ? this.extensionDirs() : [];
+    if (extDirs.length > 0) return true;
+    const cmdFiles = this.commandFiles ? this.commandFiles() : [];
+    if (cmdFiles.length > 0) return true;
+    if (this.fileContent('.idx/airules.md')) return true;
+    return false;
+  }
+
   globalGeminiMdContent() {
     const homeDir = os.homedir();
     const globalPath = path.join(homeDir, '.gemini', 'GEMINI.md');

package/src/gemini/techniques.js

@@ -93,10 +93,37 @@ function settingsData(ctx) {
   return result && result.ok ? result.data : null;
 }
 
+/**
+ * True when .gemini/settings.json is effectively an MCP-only config — i.e.
+ * it configures external tool servers but does not attempt to tune CLI
+ * behaviour (model, sandbox, approval, theme, history, etc.). Checks that
+ * assert on CLI-behaviour keys should be N/A on such configs.
+ */
+function isMcpOnlySettings(data) {
+  if (!data || typeof data !== 'object') return false;
+  const keys = Object.keys(data).filter(k => k !== '$schema' && k !== 'ide' && k !== 'context');
+  if (keys.length === 0) return true;
+  const behaviourKeys = new Set(['model', 'sandbox', 'safety', 'theme', 'approval', 'approvalMode', 'history', 'session', 'telemetry', 'hooks', 'tools', 'skills', 'commands', 'extensions', 'security']);
+  return keys.every(k => k === 'mcpServers' || !behaviourKeys.has(k));
+}
+
 function docsBundle(ctx) {
   const gmd = geminiMd(ctx) || '';
   const readme = ctx.fileContent('README.md') || '';
-  return `${gmd}\n${readme}`;
+  const agents = ctx.fileContent('AGENTS.md') || '';
+  const claudeMd = ctx.fileContent('CLAUDE.md') || '';
+  const contributing = ctx.fileContent('CONTRIBUTING.md') || '';
+  const architecture = ctx.fileContent('ARCHITECTURE.md') || '';
+  const development = ctx.fileContent('DEVELOPMENT.md') || ctx.fileContent('docs/development.md') || '';
+  return [gmd, readme, agents, claudeMd, contributing, architecture, development].join('\n');
+}
+
+// Broader bundle for stack-specific docs discovery (mirrors the Copilot
+// PP-01 stackDocsBundle approach): consults common developer docs in
+// addition to the instruction surfaces so stack checks don't hard-fail
+// when conventions live in CONTRIBUTING/DEVELOPMENT instead of GEMINI.md.
+function stackDocsBundle(ctx) {
+  return docsBundle(ctx);
 }
 
 function expectedVerificationCategories(ctx) {
@@ -262,11 +289,18 @@ const GEMINI_TECHNIQUES = {
 
   geminiMdArchitecture: {
     id: 'GM-A04',
-    name: 'GEMINI.md has architecture section or Mermaid diagram',
+    name: 'Instructions have architecture section or Mermaid diagram',
     check: (ctx) => {
       const content = geminiMd(ctx);
       if (!content) return null;
-      return hasArchitecture(content);
+      if (hasArchitecture(content)) return true;
+      // Credit an ARCHITECTURE.md at repo root, or architecture content
+      // surfaced in README.md — both are legitimate ways Gemini will pick
+      // up repo shape, especially when GEMINI.md is a pointer/import.
+      const arch = ctx.fileContent('ARCHITECTURE.md') || ctx.fileContent('docs/architecture.md');
+      if (arch) return true;
+      const readme = ctx.fileContent('README.md') || '';
+      return hasArchitecture(readme);
     },
     impact: 'medium',
     rating: 4,
@@ -352,7 +386,15 @@ const GEMINI_TECHNIQUES = {
   geminiSettingsExists: {
     id: 'GM-B01',
     name: '.gemini/settings.json exists',
-    check: (ctx) => Boolean(ctx.fileContent('.gemini/settings.json')),
+    check: (ctx) => {
+      if (ctx.fileContent('.gemini/settings.json')) return true;
+      // N/A when the repo uses only the GEMINI.md-instruction convention
+      // without any .gemini/ configuration directory. settings.json is
+      // opt-in for CLI tuning; instruction-only repos should not fail.
+      const hasGeminiDir = ctx.hasDir && ctx.hasDir('.gemini');
+      if (!hasGeminiDir) return null;
+      return false;
+    },
     impact: 'high',
     rating: 5,
     category: 'config',
@@ -397,6 +439,7 @@ const GEMINI_TECHNIQUES = {
     check: (ctx) => {
       const data = settingsData(ctx);
       if (!data) return null;
+      if (isMcpOnlySettings(data)) return null;
       if (!data.model) return false;
       // v0.36.0: model field MUST be an object { name: "..." }, not a string
       // String format causes exit code 41: "Expected object, received string"
@@ -419,8 +462,9 @@ const GEMINI_TECHNIQUES = {
     check: (ctx) => {
       const data = settingsData(ctx);
       if (!data) return null;
-      // At least sandbox or safety setting should be explicit
-      return Boolean(data.sandbox || data.safety || data.theme);
+      if (isMcpOnlySettings(data)) return null;
+      // At least one CLI-behaviour setting should be explicit.
+      return Boolean(data.sandbox || data.safety || data.theme || data.approval || data.approvalMode);
     },
     impact: 'medium',
     rating: 4,
@@ -479,13 +523,17 @@ const GEMINI_TECHNIQUES = {
 
   geminiEnvApiKey: {
     id: 'GM-B07',
-    name: '.env exists with required API keys (GEMINI_API_KEY or Google auth)',
+    name: 'API key / auth documented (env file, README, or GEMINI.md)',
     check: (ctx) => {
       const envContent = ctx.fileContent('.env') || '';
-      const envExample = ctx.fileContent('.env.example') || ctx.fileContent('.env.template') || '';
-      const combined = `${envContent}\n${envExample}`;
-      // Check for Gemini API key or Google auth
-      return /\bGEMINI_API_KEY\b|\bGOOGLE_API_KEY\b|\bGOOGLE_APPLICATION_CREDENTIALS\b|\bgcloud\b/i.test(combined) || Boolean(envContent);
+      const envExample = ctx.fileContent('.env.example') || ctx.fileContent('.env.template') || ctx.fileContent('.env.sample') || '';
+      const docs = docsBundle(ctx);
+      const combined = `${envContent}\n${envExample}\n${docs}`;
+      if (!combined.trim()) return null;
+      // Credit env files OR documentation that mentions any Gemini/Google auth mechanism,
+      // including `gemini auth`, ADC / application default credentials, Vertex AI, or a
+      // direct mention of the standard env var names.
+      return /\bGEMINI_API_KEY\b|\bGOOGLE_API_KEY\b|\bGOOGLE_APPLICATION_CREDENTIALS\b|\bgcloud\b|\bapplication[- ]default credentials?\b|\bADC\b|\bvertex[- ]?ai\b|\bgemini auth\b|\bservice account\b/i.test(combined);
     },
     impact: 'high',
     rating: 4,
@@ -542,6 +590,7 @@ const GEMINI_TECHNIQUES = {
     check: (ctx) => {
       const data = settingsData(ctx);
       if (!data) return null;
+      if (isMcpOnlySettings(data)) return null;
       return Boolean(data.sandbox && (data.sandbox.mode || typeof data.sandbox === 'string'));
     },
     impact: 'high',
@@ -1017,6 +1066,7 @@ const GEMINI_TECHNIQUES = {
     check: (ctx) => {
       const data = settingsData(ctx);
       if (!data) return null;
+      if (isMcpOnlySettings(data)) return null;
       const sandbox = data.sandbox;
       if (!sandbox) return false;
       const mode = typeof sandbox === 'string' ? sandbox : sandbox.mode;
@@ -1633,8 +1683,9 @@ const GEMINI_TECHNIQUES = {
     id: 'GM-J01',
     name: 'Rate limit/quota awareness documented',
     check: (ctx) => {
-      const gmd = geminiMd(ctx) || '';
-      return /\brate limit\b|\bquota\b|\brequests? per\b|\bcost\b|\btoken\b.*\blimit\b/i.test(gmd);
+      const docs = docsBundle(ctx);
+      if (!docs.trim()) return null;
+      return /\brate[- ]?limit\b|\bquota\b|\brequests? per\b|\bcost\b|\btoken\b.*\blimit\b|\bthrottl|\b429\b/i.test(docs);
     },
     impact: 'medium',
     rating: 3,
@@ -1677,6 +1728,7 @@ const GEMINI_TECHNIQUES = {
     check: (ctx) => {
       const data = settingsData(ctx);
       if (!data) return null;
+      if (isMcpOnlySettings(data)) return null;
       // Check if session/history settings are explicit
       return data.history !== undefined || data.session !== undefined || data.telemetry !== undefined;
     },
@@ -1836,11 +1888,11 @@ const GEMINI_TECHNIQUES = {
 
   geminiTokenUsageAwareness: {
     id: 'GM-K05',
-    name: 'Token usage awareness in GEMINI.md',
+    name: 'Token usage awareness documented',
     check: (ctx) => {
-      const gmd = geminiMd(ctx) || '';
-      if (!gmd) return null;
-      return /\btoken\b|\bcontext window\b|\bcontext length\b|\b1M\b|\btruncat/i.test(gmd);
+      const docs = docsBundle(ctx);
+      if (!docs.trim()) return null;
+      return /\btoken\b|\bcontext window\b|\bcontext length\b|\b1M\b|\btruncat/i.test(docs);
     },
     impact: 'low',
     rating: 2,
@@ -1863,7 +1915,12 @@ const GEMINI_TECHNIQUES = {
     name: 'Custom commands exist in .gemini/commands/',
     check: (ctx) => {
       const commandFiles = ctx.commandFiles ? ctx.commandFiles() : [];
-      return commandFiles.length > 0;
+      if (commandFiles.length > 0) return true;
+      // Custom commands are opt-in — only fire when the repo already has
+      // a .gemini/commands/ directory (implying the user intends to use
+      // commands but hasn't populated it).
+      const hasCommandsDir = ctx.hasDir && ctx.hasDir('.gemini/commands');
+      return hasCommandsDir ? false : null;
     },
     impact: 'medium',
     rating: 3,
@@ -2109,7 +2166,22 @@ const GEMINI_TECHNIQUES = {
   },
   geminiPropagationCompleteness: {
     id: 'GM-P03', name: 'No dangling surface references',
-    check: (ctx) => { const g = ctx.geminiMdContent(); if (!g) return null; const issues = []; if (/\bhooks?\b/i.test(g)) { const s = ctx.settingsJson(); if (!s || (!s.hooks && !s.BeforeTool && !s.AfterTool)) issues.push('hooks'); } if (/\bskills?\b/i.test(g) && !(ctx.hasDir ? ctx.hasDir('.gemini/skills') : false)) issues.push('skills'); if (/\bextensions?\b/i.test(g) && !(ctx.hasDir ? ctx.hasDir('.gemini/extensions') : false)) issues.push('extensions'); return issues.length === 0; },
+    check: (ctx) => {
+      const g = ctx.geminiMdContent();
+      if (!g) return null;
+      const issues = [];
+      // Require specific Gemini-CLI vocabulary before asserting a dangling
+      // reference. "skills" is too generic a word (appears in unrelated
+      // product copy); require `.gemini/skills` path or `gemini skills`
+      // phrasing. Same for hooks/extensions.
+      if (/\.gemini\/hooks\b|\bgemini hooks?\b|\bhooksConfig\b|\bBeforeTool\b|\bAfterTool\b/i.test(g)) {
+        const s = ctx.settingsJson();
+        if (!s || !s.ok || (!s.data || (!s.data.hooks && !s.data.BeforeTool && !s.data.AfterTool))) issues.push('hooks');
+      }
+      if (/\.gemini\/skills\b|\bgemini skills?\b/i.test(g) && !(ctx.hasDir ? ctx.hasDir('.gemini/skills') : false)) issues.push('skills');
+      if (/\.gemini\/extensions\b|\bgemini extensions?\b/i.test(g) && !(ctx.hasDir ? ctx.hasDir('.gemini/extensions') : false)) issues.push('extensions');
+      return issues.length === 0;
+    },
     impact: 'high', rating: 4, category: 'release-freshness',
     fix: 'Ensure all surfaces mentioned in GEMINI.md have corresponding definition files.',
     template: 'gemini-md', file: () => 'GEMINI.md', line: () => 1,

package/src/windsurf/context.js

@@ -36,26 +36,59 @@ class WindsurfProjectContext extends ProjectContext {
    * Windsurf uses Markdown + YAML frontmatter (NOT MDC like Cursor).
    * 4 activation modes: Always, Auto, Agent-Requested, Manual.
    * 10K char limit per rule file.
+   *
+   * PP-03: also recognises the `.windsurfrules/` *directory* convention
+   * (observed in rudrankriyam/Ichi) where the rule files sit in
+   * `.windsurfrules/*.md` or `*.mdc` instead of `.windsurf/rules/`.
    */
   windsurfRules() {
-    const dir = path.join(this.dir, '.windsurf', 'rules');
-    const files = listFiles(dir, f => f.endsWith('.md'));
-    return files.map(f => {
+    const collected = [];
+
+    // Primary: .windsurf/rules/*.md
+    const primaryDir = path.join(this.dir, '.windsurf', 'rules');
+    const primaryFiles = listFiles(primaryDir, f => f.endsWith('.md'));
+    for (const f of primaryFiles) {
       const relPath = `.windsurf/rules/${f}`;
       const content = this.fileContent(relPath);
-      if (!content) return null;
+      if (!content) continue;
       const parsed = parseWindsurfRule(content);
       const ruleType = detectRuleType(parsed.frontmatter);
-      return {
+      collected.push({
         name: f.replace('.md', ''),
         path: relPath,
         frontmatter: parsed.frontmatter,
         body: parsed.body,
         ruleType,
-        charCount: (content || '').length,
-        overLimit: (content || '').length > 10000,
-      };
-    }).filter(Boolean);
+        charCount: content.length,
+        overLimit: content.length > 10000,
+      });
+    }
+
+    // PP-03: fallback — `.windsurfrules/` as a directory.
+    const altDir = path.join(this.dir, '.windsurfrules');
+    try {
+      if (fs.statSync(altDir).isDirectory()) {
+        const altFiles = listFiles(altDir, f => f.endsWith('.md') || f.endsWith('.mdc'));
+        for (const f of altFiles) {
+          const relPath = `.windsurfrules/${f}`;
+          const content = this.fileContent(relPath);
+          if (!content) continue;
+          const parsed = parseWindsurfRule(content);
+          const ruleType = detectRuleType(parsed.frontmatter);
+          collected.push({
+            name: f.replace(/\.(md|mdc)$/, ''),
+            path: relPath,
+            frontmatter: parsed.frontmatter,
+            body: parsed.body,
+            ruleType,
+            charCount: content.length,
+            overLimit: content.length > 10000,
+          });
+        }
+      }
+    } catch { /* not a directory */ }
+
+    return collected;
   }
 
   /**
@@ -81,15 +114,92 @@ class WindsurfProjectContext extends ProjectContext {
 
   /**
    * .windsurfrules content (deprecated).
+   *
+   * PP-03: handles three real-world shapes:
+   *  1. Classic file with rule text.
+   *  2. Pointer file — a single short line referencing another markdown
+   *     file (e.g. `.ai/instructions.md`, `.llmrules`,
+   *     `.ai/tech-stack.md`). Observed in ShareX/XerahS,
+   *     Brawl345/Image-Reverse-Search-WebExtension, wepublish/wepublish.
+   *  3. Directory convention — `.windsurfrules/` is itself a directory
+   *     of rule files. Observed in rudrankriyam/Ichi. In that case this
+   *     method returns the concatenated body of all contained rule files
+   *     so consumer checks (architecture / verification / etc.) see the
+   *     effective instruction bundle.
    */
   legacyWindsurfrules() {
-    return this.fileContent('.windsurfrules');
+    // Directory form first — `.windsurfrules/` as a directory.
+    const altDir = path.join(this.dir, '.windsurfrules');
+    try {
+      if (fs.statSync(altDir).isDirectory()) {
+        const files = listFiles(altDir, f => f.endsWith('.md') || f.endsWith('.mdc'));
+        const bodies = files
+          .map(f => this.fileContent(`.windsurfrules/${f}`) || '')
+          .filter(Boolean);
+        return bodies.length > 0 ? bodies.join('\n') : '';
+      }
+    } catch { /* not a directory */ }
+
+    const raw = this.fileContent('.windsurfrules');
+    if (!raw) return null;
+
+    // Pointer form — one short line that looks like a relative path.
+    const trimmed = raw.trim();
+    if (trimmed.length < 200) {
+      const lines = trimmed.split(/\r?\n/).map(l => l.trim()).filter(Boolean);
+      if (lines.length <= 3 && lines.every(l => /^[a-zA-Z0-9_./-]+(\.(md|mdc|txt|rst))?$/.test(l))) {
+        let combined = raw;
+        for (const line of lines) {
+          const referenced = this.fileContent(line);
+          if (referenced) combined += '\n' + referenced;
+        }
+        return combined;
+      }
+    }
+    return raw;
   }
 
   hasLegacyRules() {
     return Boolean(this.legacyWindsurfrules());
   }
 
+  /**
+   * PP-03: True only when `.windsurfrules` exists as a regular file
+   * containing legacy rule text (not a pointer and not a directory).
+   * Used by checks that warn about the deprecated single-file format.
+   */
+  hasRawLegacyWindsurfrules() {
+    const altDir = path.join(this.dir, '.windsurfrules');
+    try {
+      if (fs.statSync(altDir).isDirectory()) return false;
+    } catch { /* not a dir */ }
+    const raw = this.fileContent('.windsurfrules');
+    if (!raw) return false;
+    const trimmed = raw.trim();
+    if (trimmed.length < 200) {
+      const lines = trimmed.split(/\r?\n/).map(l => l.trim()).filter(Boolean);
+      if (lines.length <= 3 && lines.every(l => /^[a-zA-Z0-9_./-]+(\.(md|mdc|txt|rst))?$/.test(l))) {
+        // It's a pointer — not a raw legacy file.
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * PP-03: surface detection helper — any instruction surface that
+   * Cascade/Windsurf can pick up.
+   */
+  hasAnyInstructionsSurface() {
+    return (
+      this.windsurfRules().length > 0 ||
+      Boolean(this.legacyWindsurfrules()) ||
+      Boolean(this.fileContent('AGENTS.md')) ||
+      Boolean(this.fileContent('CLAUDE.md')) ||
+      Boolean(this.fileContent('.ai/instructions.md'))
+    );
+  }
+
   // ─── MCP config (.windsurf/mcp.json) ──────────────────────────────────
 
   /**

package/src/windsurf/techniques.js

@@ -160,10 +160,23 @@ function isValidWindsurfFrontmatter(frontmatter) {
 }
 
 function docsBundle(ctx) {
+  // PP-03: broadened to include the surfaces real Windsurf-using repos
+  // actually use for instructions (AGENTS.md, CLAUDE.md, CONTRIBUTING.md,
+  // ARCHITECTURE.md, DEVELOPMENT.md) plus the `.ai/` convention observed
+  // in ShareX/XerahS and wepublish/wepublish. This mirrors the Gemini
+  // PP-02 broadening and ensures docs-quality checks do not FP on repos
+  // that keep guidance outside `.windsurf/rules/` alone.
   const rules = allRulesContent(ctx) || '';
   const readme = ctx.fileContent('README.md') || '';
   const legacy = ctx.legacyWindsurfrules ? (ctx.legacyWindsurfrules() || '') : '';
-  return `${rules}\n${readme}\n${legacy}`;
+  const agents = ctx.fileContent('AGENTS.md') || '';
+  const claudeMd = ctx.fileContent('CLAUDE.md') || ctx.fileContent('.claude/CLAUDE.md') || '';
+  const contributing = ctx.fileContent('CONTRIBUTING.md') || '';
+  const architecture = ctx.fileContent('ARCHITECTURE.md') || '';
+  const development = ctx.fileContent('DEVELOPMENT.md') || ctx.fileContent('DEVELOPING.md') || '';
+  const aiInstructions = ctx.fileContent('.ai/instructions.md') || ctx.fileContent('.ai/tech-stack.md') || '';
+  const windsurfMd = ctx.fileContent('WINDSURF.md') || ctx.fileContent('windsurf_rules.md') || '';
+  return `${rules}\n${readme}\n${legacy}\n${agents}\n${claudeMd}\n${contributing}\n${architecture}\n${development}\n${aiInstructions}\n${windsurfMd}`;
 }
 
 function expectedVerificationCategories(ctx) {
@@ -257,8 +270,14 @@ const WINDSURF_TECHNIQUES = {
     id: 'WS-A01',
     name: '.windsurf/rules/ directory exists with .md files',
     check: (ctx) => {
+      // PP-03: `windsurfRules()` now also enumerates the
+      // `.windsurfrules/` directory form. In addition, pointer-style
+      // `.windsurfrules` (one-liner referencing e.g. `.ai/instructions.md`)
+      // counts because it resolves to a real instruction body.
       const rules = ctx.windsurfRules ? ctx.windsurfRules() : [];
-      return rules.length > 0;
+      if (rules.length > 0) return true;
+      const legacy = ctx.legacyWindsurfrules ? ctx.legacyWindsurfrules() : null;
+      return Boolean(legacy && legacy.trim().length > 0);
     },
     impact: 'critical',
     rating: 5,
@@ -273,8 +292,13 @@ const WINDSURF_TECHNIQUES = {
     id: 'WS-A02',
     name: 'No .windsurfrules without migration to .windsurf/rules/',
     check: (ctx) => {
-      const hasLegacy = ctx.hasLegacyRules ? ctx.hasLegacyRules() : Boolean(ctx.fileContent('.windsurfrules'));
-      return !hasLegacy;
+      // PP-03: only raw legacy single-file `.windsurfrules` (non-pointer,
+      // non-directory) counts as the deprecated form. Pointer files
+      // delegating to a modern instruction surface (e.g.
+      // `.ai/instructions.md`) and the `.windsurfrules/` directory
+      // convention are both acceptable modern patterns.
+      const raw = ctx.hasRawLegacyWindsurfrules ? ctx.hasRawLegacyWindsurfrules() : false;
+      return !raw;
     },
     impact: 'critical',
     rating: 5,
@@ -306,9 +330,12 @@ const WINDSURF_TECHNIQUES = {
     id: 'WS-A04',
     name: 'Rules have valid YAML frontmatter',
     check: (ctx) => {
+      // PP-03: absent frontmatter is acceptable — Windsurf defaults such
+      // rules to `always_on`. Only flag when frontmatter *is* present
+      // and malformed, or when the declared trigger/field is invalid.
       const rules = ctx.windsurfRules ? ctx.windsurfRules() : [];
       if (rules.length === 0) return null;
-      return rules.every((rule) => isValidWindsurfFrontmatter(rule.frontmatter));
+      return rules.every((rule) => rule.frontmatter == null || isValidWindsurfFrontmatter(rule.frontmatter));
     },
     impact: 'high',
     rating: 4,
@@ -462,8 +489,13 @@ const WINDSURF_TECHNIQUES = {
     id: 'WS-B03',
     name: 'Workflow slash commands exist in .windsurf/workflows/',
     check: (ctx) => {
+      // PP-03: workflows are opt-in. N/A when the repo has no
+      // `.windsurf/workflows/` directory at all — firing a fail on every
+      // Windsurf repo without workflows produced systematic bias.
       const files = ctx.workflowFiles ? ctx.workflowFiles() : [];
-      return files.length > 0;
+      if (files.length > 0) return true;
+      if (!ctx.hasDir || !ctx.hasDir('.windsurf/workflows')) return null;
+      return false;
     },
     impact: 'medium',
     rating: 3,
@@ -498,8 +530,15 @@ const WINDSURF_TECHNIQUES = {
     id: 'WS-B05',
     name: 'Memories configured for persistent context',
     check: (ctx) => {
+      // PP-03: memories are workspace-local and strictly opt-in. The
+      // technique docs themselves warn not to rely on them (see
+      // windsurfMemoryScopeDocumented). Firing a fail on every repo that
+      // doesn't ship a `.windsurf/memories/` directory produced a 10/10
+      // FP rate. N/A when the repo doesn't opt in.
       const memories = ctx.memoryFiles ? ctx.memoryFiles() : [];
-      return memories.length > 0;
+      if (memories.length > 0) return true;
+      if (!ctx.hasDir || !ctx.hasDir('.windsurf/memories')) return null;
+      return false;
     },
     impact: 'medium',
     rating: 3,
@@ -740,10 +779,18 @@ const WINDSURF_TECHNIQUES = {
     id: 'WS-D01',
     name: 'Rules properly reach Cascade (not just .windsurfrules)',
     check: (ctx) => {
+      // PP-03: `windsurfRules()` now includes `.windsurfrules/`
+      // directory form. Pointer-style legacy `.windsurfrules` that
+      // points at a modern instruction file (`.ai/instructions.md`,
+      // AGENTS.md, etc.) is also acceptable since the referenced body
+      // is what Cascade actually receives.
       const rules = ctx.windsurfRules ? ctx.windsurfRules() : [];
       const hasLegacy = ctx.hasLegacyRules ? ctx.hasLegacyRules() : false;
       if (rules.length === 0 && !hasLegacy) return null;
-      return rules.length > 0;
+      if (rules.length > 0) return true;
+      // Raw legacy single-file is a genuine miss; pointer/dir is fine.
+      const raw = ctx.hasRawLegacyWindsurfrules ? ctx.hasRawLegacyWindsurfrules() : false;
+      return !raw;
     },
     impact: 'critical',
     rating: 5,
@@ -758,9 +805,15 @@ const WINDSURF_TECHNIQUES = {
     id: 'WS-D02',
     name: 'Cascade multi-file editing awareness documented',
     check: (ctx) => {
+      // PP-03: this is a Cascade-specific awareness advisory. It should
+      // only fire when the repo has actual `.windsurf/rules/` content
+      // that could reasonably cover Cascade guidance. Pointer-only
+      // `.windsurfrules` repos and repos with just a README keep this
+      // check N/A — the README is not the right place for Cascade
+      // multi-file editing notes.
       const rules = allRulesContent(ctx);
       if (!rules.trim()) return null;
-      return /multi.?file|cross.?file|cascade.*edit|multiple.*file/i.test(rules);
+      return /multi.?file|cross.?file|cascade.*edit|multiple.*file/i.test(docsBundle(ctx));
     },
     impact: 'medium',
     rating: 3,
@@ -775,9 +828,11 @@ const WINDSURF_TECHNIQUES = {
     id: 'WS-D03',
     name: 'Steps automation awareness documented',
     check: (ctx) => {
+      // PP-03: Cascade-specific advisory; N/A when no
+      // `.windsurf/rules/` content exists.
       const rules = allRulesContent(ctx);
       if (!rules.trim()) return null;
-      return /steps|automation|step.?by.?step|cascade.*step/i.test(rules);
+      return /steps|automation|step.?by.?step|cascade.*step/i.test(docsBundle(ctx));
     },
     impact: 'medium',
     rating: 3,
@@ -792,9 +847,12 @@ const WINDSURF_TECHNIQUES = {
     id: 'WS-D04',
     name: 'Agent session length awareness',
     check: (ctx) => {
+      // PP-03: Cascade-specific advisory; N/A when no
+      // `.windsurf/rules/` content exists (advisory belongs in rules,
+      // not in README).
       const rules = allRulesContent(ctx);
       if (!rules.trim()) return null;
-      return /session.*length|session.*limit|context.*drift|long.*session/i.test(rules);
+      return /session.*length|session.*limit|context.*drift|long.*session/i.test(docsBundle(ctx));
     },
     impact: 'low',
     rating: 2,
@@ -809,9 +867,13 @@ const WINDSURF_TECHNIQUES = {
     id: 'WS-D05',
     name: 'Cascade skills configured for project needs',
     check: (ctx) => {
+      // PP-03: the `.windsurf/skills/` directory is itself a valid
+      // signal (observed in snyk/snyk-intellij-plugin). Otherwise
+      // N/A unless the repo has `.windsurf/rules/` content.
+      if (ctx.hasDir && ctx.hasDir('.windsurf/skills')) return true;
       const rules = allRulesContent(ctx);
       if (!rules.trim()) return null;
-      return /skill|capability|tool.*use|cascade.*skill/i.test(rules);
+      return /\bskill\b|\bcapability\b|tool.*use|cascade.*skill/i.test(docsBundle(ctx));
     },
     impact: 'medium',
     rating: 3,
@@ -925,11 +987,21 @@ const WINDSURF_TECHNIQUES = {
     id: 'WS-F01',
     name: 'Rules include build/test/lint commands',
     check: (ctx) => {
-      const content = coreRulesContent(ctx) || allRulesContent(ctx);
-      if (!content.trim()) return null;
+      // PP-03: verification commands often live in README / AGENTS /
+      // CONTRIBUTING. Fall back to the full docsBundle if the core
+      // rules don't mention them, so we don't FP on repos that keep
+      // commands in a standard README section.
+      const core = coreRulesContent(ctx) || allRulesContent(ctx);
       const expected = expectedVerificationCategories(ctx);
-      if (expected.length === 0) return /\bverify\b|\btest\b|\blint\b|\bbuild\b/i.test(content);
-      return expected.every(cat => hasCommandMention(content, cat));
+      if (expected.length === 0) {
+        const combined = core || docsBundle(ctx);
+        if (!combined.trim()) return null;
+        return /\bverify\b|\btest\b|\blint\b|\bbuild\b/i.test(combined);
+      }
+      if (expected.every(cat => hasCommandMention(core, cat))) return true;
+      const docs = docsBundle(ctx);
+      if (!docs.trim()) return null;
+      return expected.every(cat => hasCommandMention(docs, cat));
     },
     impact: 'high',
     rating: 5,
@@ -944,9 +1016,13 @@ const WINDSURF_TECHNIQUES = {
     id: 'WS-F02',
     name: 'Rules include architecture section or Mermaid diagram',
     check: (ctx) => {
-      const content = allRulesContent(ctx);
-      if (!content.trim()) return null;
-      return hasArchitecture(content);
+      // PP-03: architecture content commonly lives in ARCHITECTURE.md
+      // or a README section, not duplicated inside rules. Widen to
+      // docsBundle. N/A only when the repo has no instruction surface
+      // whatsoever (not even a README).
+      const bundle = docsBundle(ctx);
+      if (!bundle.trim()) return null;
+      return hasArchitecture(bundle);
     },
     impact: 'medium',
     rating: 4,
@@ -997,12 +1073,17 @@ const WINDSURF_TECHNIQUES = {
     id: 'WS-F05',
     name: 'Rules reference project-specific patterns (not generic)',
     check: (ctx) => {
-      const content = allRulesContent(ctx);
+      // PP-03: widen to docsBundle and add stack-agnostic project
+      // directory markers (internal/, pkg/, cmd/, crates/, modules/,
+      // packages/, tests/, docs/, examples/). The previous JS-heavy
+      // regex produced FPs on Rust/Go/Java/Swift/Kotlin repos whose
+      // project layouts never mention src/app/api etc.
+      const content = docsBundle(ctx);
       if (!content.trim()) return null;
       const pkg = ctx.jsonFile ? ctx.jsonFile('package.json') : null;
       const projectName = (pkg && pkg.name) || path.basename(ctx.dir);
       const hasSpecific = content.includes(projectName) ||
-        /src\/|app\/|api\/|routes\/|services\/|components\/|lib\/|cmd\//i.test(content);
+        /\b(src|app|api|routes|services|components|lib|cmd|internal|pkg|crates|modules|packages|tests?|docs|examples|scripts)\//i.test(content);
       return hasSpecific;
     },
     impact: 'medium',
@@ -1471,7 +1552,11 @@ const WINDSURF_TECHNIQUES = {
     id: 'WS-L01',
     name: 'Rules mention modern Windsurf features (Steps, Memories, Workflows)',
     check: (ctx) => {
-      const content = allRulesContent(ctx);
+      // PP-03: widen to docsBundle; also credit `.windsurf/workflows` or
+      // `.windsurf/skills` directories as structural evidence that the
+      // repo has adopted modern Windsurf features.
+      if (ctx.hasDir && (ctx.hasDir('.windsurf/workflows') || ctx.hasDir('.windsurf/skills'))) return true;
+      const content = docsBundle(ctx);
       if (!content.trim()) return null;
       return /steps|memories|workflow|cascade|skill|slash command/i.test(content);
     },
@@ -1488,9 +1573,12 @@ const WINDSURF_TECHNIQUES = {
     id: 'WS-L02',
     name: 'No deprecated patterns (.windsurfrules for agent)',
     check: (ctx) => {
-      const legacy = ctx.legacyWindsurfrules ? ctx.legacyWindsurfrules() : null;
-      if (!legacy) return null;
-      return false; // Legacy exists = deprecated pattern
+      // PP-03: only the raw single-file legacy form is deprecated.
+      // Pointer-style `.windsurfrules` and the `.windsurfrules/`
+      // directory convention are not.
+      const raw = ctx.hasRawLegacyWindsurfrules ? ctx.hasRawLegacyWindsurfrules() : false;
+      if (!raw) return null;
+      return false;
     },
     impact: 'high',
     rating: 4,
@@ -1556,7 +1644,11 @@ const WINDSURF_TECHNIQUES = {
     id: 'WS-L06',
     name: 'Rules guide Cascade context usage (@-mentions, file refs)',
     check: (ctx) => {
-      const content = allRulesContent(ctx);
+      // PP-03: Cascade-specific deep-quality advisory; N/A when no
+      // `.windsurf/rules/` content exists.
+      const rules = allRulesContent(ctx);
+      if (!rules.trim()) return null;
+      const content = docsBundle(ctx);
       if (!content.trim()) return null;
       return /@|file.*reference|context.*include|codebase|index/i.test(content);
     },
@@ -1573,9 +1665,11 @@ const WINDSURF_TECHNIQUES = {
     id: 'WS-L07',
     name: 'Session drift awareness documented',
     check: (ctx) => {
-      const content = allRulesContent(ctx);
-      if (!content.trim()) return null;
-      return /session.*drift|context.*window|long.*session|session.*length|refresh.*context/i.test(content);
+      // PP-03: Cascade-specific deep-quality advisory; N/A when no
+      // `.windsurf/rules/` content exists.
+      const rules = allRulesContent(ctx);
+      if (!rules.trim()) return null;
+      return /session.*drift|context.*window|long.*session|session.*length|refresh.*context/i.test(docsBundle(ctx));
     },
     impact: 'low',
     rating: 2,
@@ -1650,9 +1744,13 @@ const WINDSURF_TECHNIQUES = {
     id: 'WS-M04',
     name: 'Windows/WSL usage includes a Windsurf stability caveat',
     check: (ctx) => {
+      // PP-03: relevance was keyed off `os.platform()`, which is the
+      // *host* running the audit (always Windows in our environment),
+      // causing a systematic 10/10 fail on every target repo. This
+      // check should only fire when the *target repo* itself documents
+      // Windows/WSL use — otherwise the advisory is not applicable.
       const docs = docsBundle(ctx);
-      const relevant = os.platform() === 'win32' || /\bwsl\b|\bwindows\b/i.test(docs);
-      if (!relevant) return null;
+      if (!/\bwsl\b|\bnative windows\b|\bwindows subsystem\b/i.test(docs)) return null;
       return /\bwsl\b.{0,40}\b(crash|unstable|avoid|native windows)\b|\bnative windows\b|\bavoid wsl\b/i.test(docs);
     },
     impact: 'medium',
@@ -1672,8 +1770,23 @@ const WINDSURF_TECHNIQUES = {
     id: 'WS-N01',
     name: 'Domain pack detection returns relevant results',
     check: (ctx) => {
+      // PP-03: expand stack markers so we also recognise Kotlin/Java
+      // (build.gradle, build.gradle.kts, pom.xml), Swift
+      // (Package.swift, *.xcodeproj), .NET (*.csproj / *.sln), Ruby
+      // (Gemfile), PHP (composer.json), requirements.txt and
+      // Pipfile/poetry. Without these the check FP'd on every
+      // non-JS/Go/Rust/Python repo.
       const pkg = ctx.jsonFile ? ctx.jsonFile('package.json') : null;
-      return Boolean(pkg || ctx.fileContent('go.mod') || ctx.fileContent('Cargo.toml') || ctx.fileContent('pyproject.toml'));
+      if (pkg) return true;
+      const simple = [
+        'go.mod', 'Cargo.toml', 'pyproject.toml', 'requirements.txt',
+        'Pipfile', 'poetry.lock', 'Gemfile', 'composer.json', 'pom.xml',
+        'build.gradle', 'build.gradle.kts', 'Package.swift', 'mix.exs',
+      ];
+      if (simple.some(f => ctx.fileContent(f))) return true;
+      const files = ctx.files || [];
+      if (files.some(f => /\.(csproj|sln|fsproj|vbproj|xcodeproj|xcworkspace)\/?$/i.test(f))) return true;
+      return false;
     },
     impact: 'low',
     rating: 2,
@@ -1688,9 +1801,18 @@ const WINDSURF_TECHNIQUES = {
     id: 'WS-N02',
     name: 'MCP packs recommended based on project signals',
     check: (ctx) => {
+      // PP-03: only relevant when the repo actually opts in to MCP
+      // (either documents it or ships a project-local `.windsurf/mcp.json`).
+      // Previously fired on every repo without global MCP config, which
+      // is 10/10 FP against real Windsurf repos that don't use MCP.
       const mcp = mcpJsonData(ctx);
       const servers = mcp && mcp.mcpServers ? mcp.mcpServers : {};
-      return Object.keys(servers).length > 0;
+      if (Object.keys(servers).length > 0) return true;
+      const projectMcp = ctx.mcpConfig ? ctx.mcpConfig() : null;
+      if (projectMcp && projectMcp.ok) return true;
+      const docs = docsBundle(ctx);
+      if (!/\bmcp\b/i.test(docs)) return null;
+      return false;
     },
     impact: 'low',
     rating: 2,