@nerviq/cli 1.20.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.20.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerviq/cli",
-  "version": "1.20.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": {
@@ -19,6 +19,7 @@
     "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/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,