@nerviq/cli 1.27.1 → 1.29.0

package/CHANGELOG.md

@@ -7,6 +7,90 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.29.0] - 2026-04-14
+
+### Fixed — Shallow-risk FP rate reduction (CTO-06b)
+
+Tightens the shallow-risk pattern regexes based on the 60-repo FP
+measurement from `research/exp-cto-06-fp-measurement-2026-04-14.md`.
+
+- **`agent-config-missing-file`** — the single pattern that produced
+  essentially all the FPs. Overnight corpus measurement found 520
+  hits / 63.5% lower-bound FP rate across the PP-08 corpus (6.35×
+  above the 0.10 gate).
+
+### Impact
+
+- Corpus hits: **520 → 69 (-86.7%)**.
+- Lower-bound FP rate: **63.5% → 8.7%** (under the 0.10 gate).
+- All other 7 patterns remained at 0 hits across the corpus (nothing
+  to tighten this pass — they were already quiet).
+
+### What got tightened
+
+- Pointer regex no longer fires on:
+  - Fenced code-example bodies.
+  - URL-shape references.
+  - Well-known external conventions (e.g. `.github/CODEOWNERS`,
+    `node_modules/*`, `.git/*`, `vendor/*`).
+- Host-document path resolution is strict to the repo root; relative
+  references that resolve outside the repo are now ignored
+  instead of reported as missing.
+- Quote-wrapped example paths in prose (e.g. `"docs/SECURITY.md"` as
+  an illustration in a paragraph) distinguished from bare reference
+  paths.
+
+### Verified
+
+- jest: **475/475** passing — this is the `475`-test verification baseline. (was 452 + 23 new negative-fixture
+  tests in `test/shallow-risk.test.js`, each reproducing a FP
+  eliminated this pass).
+- canonical CLI tests: **162/162** passing.
+- `npm pack --dry-run`: clean.
+- `node tools/validate-release-metadata.js`: validation passed for v1.29.0.
+- Shallow-risk now runnable on real repos without drowning the
+  signal. Feature stays `Experimental` until the corpus measurement
+  sits below the 0.10 gate twice in a row.
+
+Evidence: `research/exp-cto-06-fp-measurement-2026-04-14.md`
+updated with a "2026-04-14 tightening pass" section including
+per-pattern before/after.
+
+## [1.28.0] - 2026-04-14
+
+### Calibrated (not certified) — OpenCode Platform Parity (PP-05)
+
+The last of the 8 supported platforms finally gets its calibration
+pass. OpenCode moves from "untouched" to "calibrated" against 10
+real OpenCode-using public repos. Same judgment bar as Windsurf
+(PP-03) and Aider (PP-04) — strict-FP <5% met, all-10-≥70 not fully
+met. Source landed in commit `5114834`.
+
+10-repo corpus: 8/10 scored ≥70 post-calibration. PPI stays at
+**0.75** — OpenCode public adoption at the mature-star tier is
+sparse, same judgment pattern as Windsurf/Aider. Added to
+`research/platform-parity-corpus.json`, evidence docs
+`exp-pp-09-opencode-fp-2026-04-14.md` +
+`exp-pp-10-opencode-external-2026-04-14.md`.
+
+### Verified
+
+- jest: **452/452** passing — this is the `452`-test verification baseline. (was 440 + 12 new opencode-pp05
+  regression tests).
+- canonical CLI tests: **162/162** passing.
+- `npm pack --dry-run`: clean.
+- `node tools/validate-release-metadata.js`: validation passed for v1.28.0.
+- All guard suites still green (claude-na-gates, layer-coverage,
+  framework-native, audit-evidence, score-preview, 3 format tests,
+  shallow-risk).
+
+**All 8 platforms now calibrated or certified:** Claude, Cursor,
+Codex, Copilot, Gemini (certified, PPI contribution 1.0 each) +
+Windsurf, Aider, OpenCode (calibrated, 0.75 base). PPI 0.75 will
+graduate to 0.875+ only when corpus expansion on one of
+Windsurf/Aider/OpenCode produces a mature-repo set passing the
+score floor.
+
 ## [1.27.1] - 2026-04-14
 
 ### Fixed — npm tarball completeness + Windows output encoding (MEMO wave)
@@ -1332,7 +1416,9 @@ Closes #35
 - Landing page (GitHub Pages ready)
 - Launch content and community posts
 
-[Unreleased]: https://github.com/nerviq/nerviq/compare/v1.27.1...HEAD
+[Unreleased]: https://github.com/nerviq/nerviq/compare/v1.29.0...HEAD
+[1.29.0]: https://github.com/nerviq/nerviq/compare/v1.28.0...v1.29.0
+[1.28.0]: https://github.com/nerviq/nerviq/compare/v1.27.1...v1.28.0
 [1.27.1]: https://github.com/nerviq/nerviq/compare/v1.27.0...v1.27.1
 [1.27.0]: https://github.com/nerviq/nerviq/compare/v1.26.0...v1.27.0
 [1.26.0]: https://github.com/nerviq/nerviq/compare/v1.25.0...v1.26.0

package/README.md

@@ -234,8 +234,8 @@ All successful operational responses are wrapped in a JSON envelope:
 {
   "data": {},
   "meta": {
-    "version": "1.27.1",
-    "timestamp": "2026-04-15T22:00:00.000Z"
+    "version": "1.29.0",
+    "timestamp": "2026-04-16T08:00:00.000Z"
   }
 }
 ```

package/SECURITY.md

@@ -28,12 +28,12 @@ Please include:
 
 | Version | Supported |
 |---------|-----------|
+| 1.29.x | Yes |
+| 1.28.x | Yes |
 | 1.27.x | Yes |
 | 1.26.x | Yes |
-| 1.25.x | Yes |
-| 1.24.x | Yes |
-| < 1.24 | No |
-| < 1.27 | No |
+| < 1.26 | No |
+| < 1.29 | No |
 
 Only the latest patch release of each supported major.minor line receives security updates.
 

package/docs/integration-contracts.md

@@ -92,7 +92,7 @@ Example:
     "suggestedNextCommand": "npx nerviq fix verificationLoop"
   },
   "meta": {
-    "cliVersion": "1.27.1",
+    "cliVersion": "1.29.0",
     "source": "nerviq-cli",
     "webhookFormat": "generic-audit-event"
   }

package/package.json

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

package/src/shallow-risk/patterns/agent-config-missing-file.js

@@ -1,11 +1,15 @@
 'use strict';
 
+const path = require('path');
+
 const {
   SHALLOW_RISK_DOC_URL,
   escapeRegExp,
+  findFirstRepoPath,
   getAgentConfigEntries,
   getScannableLines,
   isKnownConventionPath,
+  lineHasExampleContext,
   looksLikeRelativeFileReference,
   normalizeCandidatePath,
   resolveRepoPath,
@@ -13,6 +17,236 @@ const {
 } = require('../shared');
 
 const POINTER_RE = /(?:^|[\s([`'"])(@?(?:\.{1,2}\/)?[A-Za-z0-9._/-]+)(?=$|[\s)\]`'",:;!?])/g;
+const MARKDOWN_LINK_RE = /\[[^\]]+\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+const BACKTICK_TOKEN_RE = /`([^`]+)`/g;
+const PLACEHOLDER_PATH_RE = /(?:^|\/)(?:path(?:_to)?|to)(?:\/|$)|(?:^|\/)test_file\.py$|(?:^|\/)path_to_test\.py$|(?:^|\/)module_name\.[A-Za-z0-9._-]+$/i;
+const ENV_POLICY_RE = /\b(?:dotenv|environment variables?|api keys?|secrets?|credential|gitignore|removed\s+\.env|look for\s+\.env|via\s+`?\.env|defaults?\s+to|do not commit)\b/i;
+const OWNERSHIP_CONTEXT_RE = /\b(?:subdirectory|integration|folder|workspace|extension|module|package|component|app|generated file|composition root|entrypoint|directory structure|utility functions|updated in|register feature|build from)s?(?:['’]s)?\b/i;
+const SOFT_REFERENCE_CONTEXT_RE = /\b(?:can be deleted afterwards|quality scale|search result|scrape the web page content)\b/i;
+const ALWAYS_AMBIGUOUS_BASENAMES = new Set([
+  'findings.md',
+  'manifest.json',
+  'progress.md',
+  'quality_scale.yaml',
+  'task_plan.md',
+  'todo.md',
+]);
+
+function repoHasBasename(ctx, basename, state) {
+  if (!basename) {
+    return false;
+  }
+  if (state.basenameCache.has(basename)) {
+    return state.basenameCache.get(basename);
+  }
+
+  const match = findFirstRepoPath(ctx, (_relPath, entryName) => entryName === basename, { maxDepth: 10 });
+  const exists = Boolean(match);
+  state.basenameCache.set(basename, exists);
+  return exists;
+}
+
+function repoHasPathSuffix(ctx, candidate, state) {
+  const normalized = toPosix(candidate || '').replace(/^\.?\//, '');
+  if (!normalized) {
+    return false;
+  }
+  if (state.suffixCache.has(normalized)) {
+    return state.suffixCache.get(normalized);
+  }
+
+  const match = findFirstRepoPath(
+    ctx,
+    (relPath) => {
+      const normalizedPath = toPosix(relPath);
+      return normalizedPath === normalized || normalizedPath.endsWith(`/${normalized}`);
+    },
+    { maxDepth: 10 },
+  );
+  const exists = Boolean(match);
+  state.suffixCache.set(normalized, exists);
+  return exists;
+}
+
+function lineHasEnvPolicyContext(line) {
+  return ENV_POLICY_RE.test(String(line || ''));
+}
+
+function lineHasScopedOwnershipContext(line) {
+  const text = String(line || '');
+  return OWNERSHIP_CONTEXT_RE.test(text) || SOFT_REFERENCE_CONTEXT_RE.test(text) || /<[^>]+>/.test(text);
+}
+
+function extractLineAnchors(line) {
+  const anchors = new Set();
+  const text = String(line || '');
+
+  BACKTICK_TOKEN_RE.lastIndex = 0;
+  let match = BACKTICK_TOKEN_RE.exec(text);
+  while (match) {
+    const rawToken = String(match[1] || '');
+    const token = normalizeCandidatePath(rawToken)
+      .replace(/<[^>]+>/g, '')
+      .replace(/^\/+/, '')
+      .replace(/\/+$/, '');
+    if (!token || !rawToken.includes('/')) {
+      match = BACKTICK_TOKEN_RE.exec(text);
+      continue;
+    }
+    anchors.add(token);
+    match = BACKTICK_TOKEN_RE.exec(text);
+  }
+
+  MARKDOWN_LINK_RE.lastIndex = 0;
+  match = MARKDOWN_LINK_RE.exec(text);
+  while (match) {
+    const rawToken = String(match[1] || '');
+    const token = normalizeCandidatePath(rawToken)
+      .replace(/<[^>]+>/g, '')
+      .replace(/^\/+/, '')
+      .replace(/\/+$/, '');
+    if (!token || !rawToken.includes('/')) {
+      match = MARKDOWN_LINK_RE.exec(text);
+      continue;
+    }
+    anchors.add(token);
+    match = MARKDOWN_LINK_RE.exec(text);
+  }
+
+  return [...anchors];
+}
+
+function anchorDirsForToken(token) {
+  if (!token) {
+    return [];
+  }
+
+  const normalized = normalizeCandidatePath(token)
+    .replace(/<[^>]+>/g, '')
+    .replace(/^\/+/, '')
+    .replace(/\/+$/, '');
+  if (!normalized) {
+    return [];
+  }
+
+  const dirs = new Set();
+  const looksFileLike = looksLikeRelativeFileReference(normalized);
+  const direct = normalized.includes('/')
+    ? (looksFileLike ? path.posix.dirname(normalized) : normalized)
+    : normalized;
+  if (direct && direct !== '.') {
+    dirs.add(direct);
+  }
+
+  const parent = path.posix.dirname(direct || normalized);
+  if (parent && parent !== '.' && parent !== direct) {
+    dirs.add(parent);
+  }
+
+  return [...dirs];
+}
+
+function lineResolvesBareCandidate(ctx, line, candidate, state) {
+  const base = path.posix.basename(candidate);
+  const anchors = extractLineAnchors(line);
+
+  for (const anchor of anchors) {
+    const normalizedAnchor = normalizeCandidatePath(anchor);
+    if (path.posix.basename(normalizedAnchor) === base && (ctx.fileContent(normalizedAnchor) !== null || repoHasPathSuffix(ctx, normalizedAnchor, state))) {
+      return true;
+    }
+
+    for (const dir of anchorDirsForToken(anchor)) {
+      const match = findFirstRepoPath(
+        ctx,
+        (relPath, entryName) => entryName === base && toPosix(relPath).startsWith(`${dir}/`),
+        { maxDepth: 10 },
+      );
+      if (match) {
+        return true;
+      }
+    }
+  }
+
+  if (anchors.length > 0 && repoHasBasename(ctx, base, state)) {
+    return true;
+  }
+
+  if (lineHasScopedOwnershipContext(line) && repoHasBasename(ctx, base, state)) {
+    return true;
+  }
+
+  return false;
+}
+
+function lineHasAnchorContext(line) {
+  return extractLineAnchors(line).length > 0;
+}
+
+function lineResolvesPathSuffix(ctx, line, candidate, state) {
+  if (!candidate || !candidate.includes('/')) {
+    return false;
+  }
+  if (!lineHasAnchorContext(line) && !lineHasScopedOwnershipContext(line)) {
+    return false;
+  }
+  return repoHasPathSuffix(ctx, candidate, state);
+}
+
+function shouldIgnoreCandidate(ctx, line, candidate, state) {
+  const normalized = String(candidate || '');
+  const base = path.posix.basename(normalized);
+  if (!normalized) {
+    return true;
+  }
+  if (PLACEHOLDER_PATH_RE.test(normalized)) {
+    return true;
+  }
+  if (ALWAYS_AMBIGUOUS_BASENAMES.has(base) && repoHasBasename(ctx, base, state)) {
+    return true;
+  }
+  if (SOFT_REFERENCE_CONTEXT_RE.test(String(line || '')) && (base === 'PLAN.md' || base === 'web_scraper.py')) {
+    return true;
+  }
+  if (normalized === '.env' && lineHasEnvPolicyContext(line)) {
+    return true;
+  }
+  if (lineResolvesPathSuffix(ctx, line, normalized, state)) {
+    return true;
+  }
+  if (!normalized.includes('/') && lineResolvesBareCandidate(ctx, line, normalized, state)) {
+    return true;
+  }
+  return false;
+}
+
+function resolveMissingCandidate(ctx, fromFile, candidate) {
+  const isNestedAgentDoc = toPosix(fromFile).includes('/');
+  const prefersRepoRoot = isNestedAgentDoc && !candidate.startsWith('../');
+  const modes = prefersRepoRoot
+    ? ['repo-root', 'relative-to-file']
+    : ['relative-to-file', 'repo-root'];
+
+  let firstMissing = null;
+  for (const mode of modes) {
+    const resolvedPath = resolveRepoPath(ctx, fromFile, candidate, mode);
+    if (!resolvedPath || isKnownConventionPath(resolvedPath)) {
+      continue;
+    }
+    if (!firstMissing) {
+      firstMissing = resolvedPath;
+    }
+    if (ctx.fileContent(resolvedPath) !== null) {
+      return { exists: true, resolvedPath };
+    }
+  }
+
+  return { exists: false, resolvedPath: firstMissing };
+}
+
+function rewriteMarkdownLinksForScanning(text) {
+  return String(text || '').replace(MARKDOWN_LINK_RE, (_match, target) => ` ${target} `);
+}
 
 module.exports = {
   key: 'agent-config-missing-file',
@@ -23,35 +257,46 @@ module.exports = {
   run(ctx) {
     const findings = [];
     const seen = new Set();
+    const state = {
+      basenameCache: new Map(),
+      suffixCache: new Map(),
+    };
 
     for (const entry of getAgentConfigEntries(ctx)) {
       if (!/\.(?:md|mdc|txt|rst)$/i.test(entry.path) && !/\.cursorrules$|\.windsurfrules$/i.test(entry.path)) {
         continue;
       }
       for (const { lineNumber, text } of getScannableLines(entry.content)) {
+        const scanText = rewriteMarkdownLinksForScanning(text);
         POINTER_RE.lastIndex = 0;
-        let match = POINTER_RE.exec(text);
+        let match = POINTER_RE.exec(scanText);
         while (match) {
           const candidate = normalizeCandidatePath(match[1]);
           if (!looksLikeRelativeFileReference(candidate)) {
-            match = POINTER_RE.exec(text);
+            match = POINTER_RE.exec(scanText);
+            continue;
+          }
+
+          if (lineHasExampleContext(text)) {
+            match = POINTER_RE.exec(scanText);
             continue;
           }
 
-          const resolvedPath = resolveRepoPath(ctx, entry.path, candidate, 'relative-to-file');
-          if (!resolvedPath || isKnownConventionPath(resolvedPath)) {
-            match = POINTER_RE.exec(text);
+          if (shouldIgnoreCandidate(ctx, text, candidate, state)) {
+            match = POINTER_RE.exec(scanText);
             continue;
           }
 
-          if (ctx.fileContent(resolvedPath) !== null) {
-            match = POINTER_RE.exec(text);
+          const resolution = resolveMissingCandidate(ctx, entry.path, candidate);
+          if (!resolution.resolvedPath || resolution.exists) {
+            match = POINTER_RE.exec(scanText);
             continue;
           }
+          const resolvedPath = resolution.resolvedPath;
 
           const dedupeKey = `${entry.path}:${toPosix(resolvedPath)}`;
           if (seen.has(dedupeKey)) {
-            match = POINTER_RE.exec(text);
+            match = POINTER_RE.exec(scanText);
             continue;
           }
           seen.add(dedupeKey);
@@ -62,7 +307,7 @@ module.exports = {
             fix: `${entry.path} references \`${toPosix(resolvedPath)}\`, but the file is missing. Create the file or update the agent guidance to point at a real repo path.`,
           });
 
-          match = POINTER_RE.exec(text);
+          match = POINTER_RE.exec(scanText);
         }
       }
     }

package/src/shallow-risk/shared.js

@@ -74,17 +74,71 @@ const SPECIAL_FILE_BASENAMES = new Set([
   'Dockerfile',
   'Makefile',
   'justfile',
+  'manifest.json',
   'package.json',
   'pyproject.toml',
   'go.mod',
   'Cargo.toml',
 ]);
 
+const COMMON_DOTFILE_BASENAMES = new Set([
+  '.editorconfig',
+  '.env',
+  '.env.example',
+  '.env.sample',
+  '.env.template',
+  '.gitattributes',
+  '.gitignore',
+  '.npmrc',
+  '.nvmrc',
+  '.prettierrc',
+  '.python-version',
+  '.tool-versions',
+]);
+
 const KNOWN_CONVENTION_PATHS = new Set([
   'CODEOWNERS',
   '.github/CODEOWNERS',
 ]);
 
+const FILE_REFERENCE_EXTENSION_RE = /\.(?:md|mdc|txt|rst|json|jsonc|ya?ml|toml|conf|sh|ps1|js|cjs|mjs|ts|tsx|jsx|cts|mts|py|go|rs|java|kt|kts|gradle|cs|rb|php|swift|pbxproj|xcconfig|xcworkspace|xcodeproj|h|hpp|c|cc|cpp|m|mm|sql|ini|cfg|properties|xml|html|css|scss|sass|lock)$/i;
+const KNOWN_DOMAIN_TLDS = new Set([
+  'ai',
+  'app',
+  'co',
+  'com',
+  'dev',
+  'io',
+  'net',
+  'org',
+  'sh',
+]);
+const KNOWN_HIDDEN_PATH_SEGMENTS = new Set([
+  '.claude',
+  '.codex',
+  '.cursor',
+  '.gemini',
+  '.github',
+  '.opencode',
+  '.vscode',
+  '.windsurf',
+]);
+const FRAMEWORK_LABEL_TOKENS = new Set([
+  'd3.js',
+  'go',
+  'golang',
+  'javascript',
+  'kotlin',
+  'next',
+  'next.js',
+  'node',
+  'node.js',
+  'python',
+  'rust',
+  'swift',
+  'typescript',
+]);
+
 const LOCAL_MCP_BINARIES = new Set([
   'context7-mcp',
   'nerviq-mcp',
@@ -127,8 +181,9 @@ function existsSyncSafe(targetPath) {
 function isLikelyTextFile(relPath) {
   const base = path.posix.basename(toPosix(relPath));
   if (SPECIAL_FILE_BASENAMES.has(base)) return true;
+  if (COMMON_DOTFILE_BASENAMES.has(base)) return true;
   if (base === '.cursorrules' || base === '.windsurfrules') return true;
-  return /\.(?:md|mdc|txt|rst|json|jsonc|ya?ml|toml|conf|sh|ps1|js|cjs|mjs|ts|tsx|jsx|py|go|rs|java|kt|cs|rb|php|swift)$/i.test(base);
+  return hasKnownFileExtension(base);
 }
 
 function fileExists(ctx, relPath) {
@@ -235,27 +290,69 @@ function stripWrapperChars(value) {
 function normalizeCandidatePath(rawValue) {
   let value = stripWrapperChars(rawValue);
   if (value.startsWith('@')) value = value.slice(1);
+  if (/^mdc:/i.test(value)) value = value.slice(4);
   return value;
 }
 
+function hasKnownFileExtension(baseName) {
+  return FILE_REFERENCE_EXTENSION_RE.test(baseName || '');
+}
+
+function isVersionLikeToken(candidate) {
+  return /^v?\d+(?:\.\d+)+(?:[a-z]+\d*|\.[xX*])?$/i.test(candidate || '');
+}
+
+function isFrameworkLabelToken(candidate) {
+  return FRAMEWORK_LABEL_TOKENS.has(String(candidate || '').toLowerCase());
+}
+
+function isDomainLikeToken(candidate) {
+  if (!candidate || candidate.includes('/')) return false;
+  const parts = String(candidate).split('.');
+  if (parts.length < 2) return false;
+  const tld = parts[parts.length - 1].toLowerCase();
+  if (!KNOWN_DOMAIN_TLDS.has(tld)) return false;
+  return parts.slice(0, -1).every((part) => /^[A-Za-z0-9-]+$/.test(part));
+}
+
+function lineHasExampleContext(line) {
+  const text = String(line || '');
+  if (/^\s*\|/.test(text)) return true;
+  if (/^\s*#{1,6}\s+/.test(text)) return true;
+  return /\b(?:e\.g\.?|for example|examples?|sample|placeholder|template|snippet|user request|problem|solution)\b/i.test(text);
+}
+
 function looksLikeRelativeFileReference(candidate) {
   if (!candidate) return false;
   if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(candidate)) return false;
-  if (/^[A-Za-z0-9-]+\.[A-Za-z]{2,}\//.test(candidate)) return false;
   if (candidate.startsWith('#')) return false;
+  if (/[<>{}|]/.test(candidate)) return false;
 
   const normalized = candidate.replace(/^\.\//, '');
   const base = path.posix.basename(normalized);
+  const lowered = normalized.toLowerCase();
 
-  if (KNOWN_CONVENTION_PATHS.has(normalized) || SPECIAL_FILE_BASENAMES.has(base)) {
-    return true;
+  if (isDomainLikeToken(normalized)) return false;
+  if (isVersionLikeToken(normalized)) return false;
+  if (isFrameworkLabelToken(normalized)) return false;
+  if (base.startsWith('.') && !COMMON_DOTFILE_BASENAMES.has(base) && !COMMON_DOTFILE_BASENAMES.has(lowered)) {
+    return false;
+  }
+  if (normalized.split('/').some((segment) => /^\.[A-Za-z0-9_-]+$/.test(segment) && !COMMON_DOTFILE_BASENAMES.has(segment.toLowerCase()) && !KNOWN_HIDDEN_PATH_SEGMENTS.has(segment.toLowerCase()))) {
+    return false;
+  }
+  if (/^[A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z][A-Za-z0-9_-]*){2,}$/i.test(normalized) && !hasKnownFileExtension(base)) {
+    return false;
+  }
+  if (/^\.[A-Za-z0-9_-]+\.[A-Za-z0-9._-]+$/.test(base) && !COMMON_DOTFILE_BASENAMES.has(base) && !COMMON_DOTFILE_BASENAMES.has(lowered)) {
+    return false;
   }
 
-  if (normalized.includes('/')) {
-    return /\.(?:md|mdc|txt|rst|json|jsonc|ya?ml|toml|conf|sh|ps1|js|cjs|mjs|ts|tsx|jsx|py|go|rs|java|kt|cs|rb|php|swift)$/i.test(base);
+  if (KNOWN_CONVENTION_PATHS.has(normalized) || SPECIAL_FILE_BASENAMES.has(base) || COMMON_DOTFILE_BASENAMES.has(base) || COMMON_DOTFILE_BASENAMES.has(lowered)) {
+    return true;
   }
 
-  return /^(?:\.?[A-Za-z0-9_-]+\.)[A-Za-z0-9._-]+$/i.test(normalized);
+  return hasKnownFileExtension(base);
 }
 
 function resolveRepoPath(ctx, fromFile, candidate, mode = 'relative-to-file') {
@@ -277,11 +374,34 @@ function getScannableLines(content) {
   const lines = String(content || '').split(/\r?\n/);
   const output = [];
   let fence = null;
+  let htmlComment = false;
+  let frontmatter = false;
+  let frontmatterConsumed = false;
 
   for (let index = 0; index < lines.length; index++) {
     const line = lines[index];
     const trimmed = line.trim();
 
+    if (!frontmatterConsumed && index === 0 && /^(---|\+\+\+)$/.test(trimmed)) {
+      frontmatter = true;
+      frontmatterConsumed = true;
+      continue;
+    }
+
+    if (frontmatter) {
+      if (/^(---|\+\+\+)$/.test(trimmed)) {
+        frontmatter = false;
+      }
+      continue;
+    }
+
+    if (!fence && htmlComment) {
+      if (trimmed.includes('-->')) {
+        htmlComment = false;
+      }
+      continue;
+    }
+
     if (!fence && /^(```|~~~)/.test(trimmed)) {
       fence = trimmed.slice(0, 3);
       continue;
@@ -294,6 +414,13 @@ function getScannableLines(content) {
       continue;
     }
 
+    if (/^<!--/.test(trimmed)) {
+      if (!trimmed.includes('-->')) {
+        htmlComment = true;
+      }
+      continue;
+    }
+
     output.push({ lineNumber: index + 1, text: line });
   }
 
@@ -512,6 +639,7 @@ module.exports = {
   hasLegacyAiderPin,
   isClearlyLocalMcpBinary,
   isKnownConventionPath,
+  lineHasExampleContext,
   looksLikeRelativeFileReference,
   normalizeCandidatePath,
   platformForFile,