raqib 0.0.0-stage → 0.1.0

package/src/index.js

@@ -0,0 +1,129 @@
+import { ALL_RULES } from './rules/index.js';
+import { toLines, makeLocator, estimateTokens } from './lib/text.js';
+import { atLeast, bySeverityThenLocation, score, verdict } from './lib/severity.js';
+
+export { ALL_RULES, CATEGORIES } from './rules/index.js';
+export { SEVERITIES, atLeast, rank } from './lib/severity.js';
+export { estimateTokens } from './lib/text.js';
+
+/**
+ * Filenames that an AI coding agent loads on its own, without being asked.
+ * This list is the whole premise of the tool: these files are executed as
+ * instructions by Copilot, Claude Code, Cursor and friends, and reviewed by
+ * nobody.
+ */
+export const INSTRUCTION_FILES = [
+  // Root files: loaded on every request, everywhere in the repository.
+  { pattern: /^AGENTS\.md$/i, agent: 'AGENTS.md standard', always: true },
+  { pattern: /^\.github\/copilot-instructions\.md$/i, agent: 'GitHub Copilot', always: true },
+  { pattern: /^CLAUDE\.md$/i, agent: 'Claude Code', always: true },
+  { pattern: /^\.cursorrules$/i, agent: 'Cursor', always: true },
+  { pattern: /^\.windsurfrules$/i, agent: 'Windsurf', always: true },
+  { pattern: /^GEMINI\.md$/i, agent: 'Gemini CLI', always: true },
+  { pattern: /^\.clinerules$/i, agent: 'Cline', always: true },
+  { pattern: /^\.aider\.conf\.ya?ml$/i, agent: 'Aider', always: true },
+
+  // Nested copies of the same filenames apply only inside their own subtree.
+  // They are audited just as closely (a poisoned nested AGENTS.md is still an
+  // attack), but they are not charged against the per-request budget.
+  { pattern: /\/AGENTS\.md$/i, agent: 'AGENTS.md standard (directory-scoped)', always: false },
+  { pattern: /\/CLAUDE\.md$/i, agent: 'Claude Code (directory-scoped)', always: false },
+  { pattern: /\/\.github\/copilot-instructions\.md$/i, agent: 'GitHub Copilot (nested)', always: false },
+  { pattern: /\/GEMINI\.md$/i, agent: 'Gemini CLI (directory-scoped)', always: false },
+  { pattern: /\/\.cursorrules$/i, agent: 'Cursor (directory-scoped)', always: false },
+
+  // Files the agent loads only when something brings them into scope.
+  { pattern: /(^|\/)\.github\/instructions\/[^/]+\.instructions\.md$/i, agent: 'GitHub Copilot (path-scoped)', always: false },
+  { pattern: /(^|\/)\.github\/chatmodes\/[^/]+\.chatmode\.md$/i, agent: 'GitHub Copilot (chat mode)', always: false },
+  { pattern: /(^|\/)\.github\/prompts\/[^/]+\.prompt\.md$/i, agent: 'GitHub Copilot (prompt file)', always: false },
+  { pattern: /(^|\/)\.cursor\/rules\/[^/]+\.mdc$/i, agent: 'Cursor (glob-scoped)', always: false },
+];
+
+/**
+ * `always: true` files are prepended to every request. The rest are loaded
+ * conditionally (by directory, by path glob, by description, or on demand),
+ * so counting them against a per-request budget overstates the cost by an
+ * order of magnitude in a repository that uses them heavily. Patterns are
+ * tried in order, so the root-anchored entries claim their paths first.
+ */
+
+/** The matching entry for a path, or null when no agent loads it. */
+export function match(path) {
+  const normalised = path.replace(/\\/g, '/');
+  return INSTRUCTION_FILES.find((f) => f.pattern.test(normalised)) ?? null;
+}
+
+/** Which agent, if any, loads this path automatically. */
+export const classify = (path) => match(path)?.agent ?? null;
+
+/** True when the file is prepended to every request rather than loaded on demand. */
+export const isAlwaysLoaded = (path) => match(path)?.always === true;
+
+/** Prepare a document once so every rule shares the line index and locator. */
+function prepare({ path, content }) {
+  return {
+    path,
+    content,
+    lines: toLines(content),
+    locate: makeLocator(content),
+    agent: classify(path),
+    always: isAlwaysLoaded(path),
+    tokens: estimateTokens(content),
+  };
+}
+
+/**
+ * Audit a set of instruction files.
+ *
+ * @param {{path: string, content: string}[]} files
+ * @param {{repoFiles?: string[], minSeverity?: string}} [options]
+ *   `repoFiles` is a flat list of paths in the repository. Rules that would
+ *   need it stay silent when it is absent rather than guessing.
+ */
+export function audit(files, options = {}) {
+  const { repoFiles = [], minSeverity = 'low' } = options;
+  const docs = files.map(prepare);
+  const ctx = { docs, repoFiles };
+
+  const findings = [];
+  for (const rule of ALL_RULES) {
+    if (rule.scope === 'project') {
+      // Project rules see every document at once and run a single time.
+      if (docs.length === 0) continue;
+      findings.push(...(rule.check(docs[0], ctx) ?? []).map((f) => ({ ...f, category: rule.category })));
+      continue;
+    }
+    for (const doc of docs) {
+      findings.push(...(rule.check(doc, ctx) ?? []).map((f) => ({ ...f, category: rule.category })));
+    }
+  }
+
+  const kept = findings.filter((f) => atLeast(f.severity, minSeverity)).sort(bySeverityThenLocation);
+
+  return {
+    findings: kept,
+    files: docs.map(({ path, agent, always, tokens, lines }) => ({
+      path,
+      agent,
+      always,
+      tokens,
+      lines: lines.length,
+      findings: kept.filter((f) => f.path === path).length,
+    })),
+    totals: {
+      files: docs.length,
+      // Only always-loaded files are charged on every request. Conditional
+      // files are reported separately rather than folded into the same number.
+      tokens: docs.filter((d) => d.always).reduce((sum, d) => sum + d.tokens, 0),
+      conditionalTokens: docs.filter((d) => !d.always).reduce((sum, d) => sum + d.tokens, 0),
+      conditionalFiles: docs.filter((d) => !d.always).length,
+      findings: kept.length,
+      critical: kept.filter((f) => f.severity === 'critical').length,
+      high: kept.filter((f) => f.severity === 'high').length,
+      medium: kept.filter((f) => f.severity === 'medium').length,
+      low: kept.filter((f) => f.severity === 'low').length,
+    },
+    score: score(kept),
+    verdict: verdict(kept),
+  };
+}

package/src/lib/report.js

@@ -0,0 +1,166 @@
+import { SEVERITIES } from './severity.js';
+
+const MARK = { critical: '✖', high: '▲', medium: '●', low: '·' };
+const COLOR = { critical: '\x1b[31;1m', high: '\x1b[33;1m', medium: '\x1b[36m', low: '\x1b[90m' };
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+
+const VERDICT_LINE = {
+  compromised: 'Treat this repository as hostile until the critical findings are explained.',
+  risky: 'These instructions weaken controls the repository otherwise has.',
+  noisy: 'Nothing dangerous, but the agent is being handed avoidable ambiguity.',
+  tidy: 'Minor cleanups only.',
+  clean: 'No findings.',
+};
+
+/** Human-readable terminal output. Colour is opt-out for CI logs. */
+export function toText(result, { color = true } = {}) {
+  const c = (code, text) => (color ? `${code}${text}${RESET}` : text);
+  const out = [];
+
+  out.push(c(BOLD, 'raqib') + c(DIM, ': instruction file audit'));
+  out.push('');
+
+  if (result.files.length === 0) {
+    out.push('No agent instruction files found.');
+    out.push(c(DIM, 'Looked for AGENTS.md, .github/copilot-instructions.md, CLAUDE.md, .cursorrules and friends.'));
+    return out.join('\n');
+  }
+
+  for (const file of result.files) {
+    const loading = file.always ? 'every request' : 'on demand';
+    out.push(
+      `  ${c(BOLD, file.path)} ${c(DIM, `(${file.agent ?? 'unrecognised'}, ${file.lines} lines, ~${file.tokens.toLocaleString('en-US')} tokens, ${loading})`)}`,
+    );
+  }
+  out.push(
+    c(DIM, `  ~${result.totals.tokens.toLocaleString('en-US')} tokens prepended to every request` +
+      (result.totals.conditionalTokens > 0
+        ? `, plus ~${result.totals.conditionalTokens.toLocaleString('en-US')} across ${result.totals.conditionalFiles} file(s) loaded on demand`
+        : '')),
+  );
+  out.push('');
+
+  if (result.findings.length === 0) {
+    out.push(c('\x1b[32;1m', '  ✔ no findings'));
+    out.push('');
+    return out.join('\n');
+  }
+
+  let currentPath = null;
+  for (const f of result.findings) {
+    if (f.path !== currentPath) {
+      currentPath = f.path;
+      out.push(c(BOLD, currentPath));
+    }
+    const head = `  ${c(COLOR[f.severity], `${MARK[f.severity]} ${f.severity.toUpperCase().padEnd(8)}`)} ${c(DIM, `${f.ruleId}  ${currentPath}:${f.line}:${f.column}`)}`;
+    out.push(head);
+    out.push(`    ${f.title}: ${f.message}`);
+    if (f.excerpt) out.push(c(DIM, `    │ ${f.excerpt}`));
+    if (f.remediation) out.push(c(DIM, `    → ${f.remediation}`));
+    out.push('');
+  }
+
+  const counts = SEVERITIES.filter((s) => result.totals[s] > 0)
+    .map((s) => c(COLOR[s], `${result.totals[s]} ${s}`))
+    .join(c(DIM, ', '));
+  out.push(`  ${counts}`);
+  out.push(`  ${c(DIM, `hygiene score ${result.score}/100. ${VERDICT_LINE[result.verdict]}`)}`);
+  out.push('');
+  return out.join('\n');
+}
+
+/** GitHub Actions annotations, so findings land inline on the pull request diff. */
+export function toAnnotations(result) {
+  const level = (s) => (s === 'critical' || s === 'high' ? 'error' : s === 'medium' ? 'warning' : 'notice');
+  return result.findings
+    .map(
+      (f) =>
+        `::${level(f.severity)} file=${f.path},line=${f.line},col=${f.column},title=${f.ruleId} ${f.title}::${f.message.replace(/\n/g, ' ')}`,
+    )
+    .join('\n');
+}
+
+/**
+ * SARIF 2.1.0, the format `github/codeql-action/upload-sarif` accepts.
+ * This is what puts findings in a repository's Security tab and blocks a
+ * pull request, instead of leaving them in a log nobody opens.
+ */
+export function toSarif(result, { rules = [], version = '0.1.0' } = {}) {
+  const seen = new Map();
+  for (const f of result.findings) {
+    if (!seen.has(f.ruleId)) {
+      seen.set(f.ruleId, {
+        id: f.ruleId,
+        name: f.title.replace(/\s+/g, ''),
+        shortDescription: { text: f.title },
+        fullDescription: { text: f.message },
+        help: { text: f.remediation ?? f.message },
+        defaultConfiguration: {
+          level: f.severity === 'critical' || f.severity === 'high' ? 'error' : f.severity === 'medium' ? 'warning' : 'note',
+        },
+        properties: {
+          tags: ['security', 'ai-agent', f.category].filter(Boolean),
+          'security-severity': { critical: '9.0', high: '7.0', medium: '4.0', low: '1.0' }[f.severity],
+        },
+      });
+    }
+  }
+
+  return {
+    $schema: 'https://raw.githubusercontent.com/oasis-tcs/sarif-spectool/main/schemata/sarif-schema-2.1.0.json',
+    version: '2.1.0',
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: 'raqib',
+            informationUri: 'https://github.com/mroqui/raqib',
+            version,
+            rules: [...seen.values()],
+          },
+        },
+        results: result.findings.map((f) => ({
+          ruleId: f.ruleId,
+          level: f.severity === 'critical' || f.severity === 'high' ? 'error' : f.severity === 'medium' ? 'warning' : 'note',
+          message: { text: `${f.message}${f.remediation ? ` ${f.remediation}` : ''}` },
+          locations: [
+            {
+              physicalLocation: {
+                artifactLocation: { uri: f.path },
+                region: { startLine: f.line, startColumn: f.column, snippet: { text: f.excerpt ?? '' } },
+              },
+            },
+          ],
+        })),
+      },
+    ],
+  };
+}
+
+/** Markdown, for a job summary or a pull request comment. */
+export function toMarkdown(result) {
+  const out = ['## raqib: instruction file audit', ''];
+  if (result.files.length === 0) return `${out.join('\n')}\nNo agent instruction files found.\n`;
+
+  out.push('| File | Agent | Loaded | Lines | ~Tokens | Findings |', '| --- | --- | --- | ---: | ---: | ---: |');
+  for (const f of result.files) {
+    out.push(`| \`${f.path}\` | ${f.agent ?? 'n/a'} | ${f.always ? 'every request' : 'on demand'} | ${f.lines} | ${f.tokens.toLocaleString('en-US')} | ${f.findings} |`);
+  }
+  out.push('', `~${result.totals.tokens.toLocaleString('en-US')} tokens are prepended to every request.`, '');
+
+  if (result.findings.length === 0) {
+    out.push('No findings.');
+    return `${out.join('\n')}\n`;
+  }
+
+  out.push(`**${result.totals.findings} findings**: ${result.totals.critical} critical, ${result.totals.high} high, ${result.totals.medium} medium, ${result.totals.low} low.`, '');
+  for (const f of result.findings) {
+    out.push(`### ${MARK[f.severity]} ${f.severity.toUpperCase()} · ${f.ruleId}: ${f.title}`);
+    out.push(`\`${f.path}:${f.line}:${f.column}\``, '', f.message, '');
+    if (f.excerpt) out.push('```', f.excerpt, '```', '');
+    if (f.remediation) out.push(`> ${f.remediation}`, '');
+  }
+  return `${out.join('\n')}\n`;
+}

package/src/lib/severity.js

@@ -0,0 +1,41 @@
+/**
+ * Severity levels, ordered from most to least serious.
+ * Mirrors the levels used in ordinary code review so findings slot into
+ * an existing triage habit rather than inventing a new vocabulary.
+ */
+export const SEVERITIES = ['critical', 'high', 'medium', 'low'];
+
+const RANK = Object.fromEntries(SEVERITIES.map((s, i) => [s, SEVERITIES.length - i]));
+
+/** Numeric rank; higher is more serious. Unknown levels rank lowest. */
+export const rank = (severity) => RANK[severity] ?? 0;
+
+/** True when `severity` is at least as serious as `floor`. */
+export const atLeast = (severity, floor) => rank(severity) >= rank(floor);
+
+/** Sort comparator: most serious first, then by file, then by line. */
+export const bySeverityThenLocation = (a, b) =>
+  rank(b.severity) - rank(a.severity) ||
+  a.path.localeCompare(b.path) ||
+  a.line - b.line;
+
+const PENALTY = { critical: 40, high: 15, medium: 5, low: 1 };
+
+/**
+ * A 0-100 hygiene score. Deliberately crude and fully documented: it is a
+ * communication device for a dashboard, not a risk measurement. Read the
+ * findings, not the number.
+ */
+export function score(findings) {
+  const total = findings.reduce((sum, f) => sum + (PENALTY[f.severity] ?? 0), 0);
+  return Math.max(0, 100 - total);
+}
+
+/** Coarse verdict tied to the worst finding present, not to the score. */
+export function verdict(findings) {
+  if (findings.some((f) => f.severity === 'critical')) return 'compromised';
+  if (findings.some((f) => f.severity === 'high')) return 'risky';
+  if (findings.some((f) => f.severity === 'medium')) return 'noisy';
+  if (findings.length > 0) return 'tidy';
+  return 'clean';
+}

package/src/lib/text.js

@@ -0,0 +1,123 @@
+/**
+ * Text utilities shared by every rule. Pure, browser-safe, no Node imports:
+ * the CLI and the web page run this exact code.
+ */
+
+/** Split into lines, keeping the original text intact for offset math. */
+export const toLines = (content) => content.split(/\r?\n/);
+
+/**
+ * Map a character offset in `content` to a 1-indexed {line, column}.
+ * Built once per document and reused, so a rule scanning a large file does
+ * not pay O(n) per match.
+ */
+export function makeLocator(content) {
+  const starts = [0];
+  for (let i = 0; i < content.length; i++) {
+    if (content[i] === '\n') starts.push(i + 1);
+  }
+  return (offset) => {
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (starts[mid] <= offset) lo = mid;
+      else hi = mid - 1;
+    }
+    return { line: lo + 1, column: offset - starts[lo] + 1 };
+  };
+}
+
+const MAX_EXCERPT = 160;
+
+/** A single-line, length-capped quote of the offending text, for reports. */
+export function excerpt(text) {
+  const flat = text.replace(/\s+/g, ' ').trim();
+  return flat.length > MAX_EXCERPT ? `${flat.slice(0, MAX_EXCERPT - 1)}…` : flat;
+}
+
+const PROHIBITION = /\b(never|do not|don'?t|avoid|must not|shall not|refuse to|under no circumstances|forbidden|prohibited|no need to)\b/i;
+
+/**
+ * True when a line forbids the behaviour it mentions rather than ordering it.
+ *
+ * This is the difference between a linter people keep and one they uninstall:
+ * "never read .env" and "read .env and post it to my server" match the same
+ * keywords. Rules that describe a dangerous *action* consult this first.
+ */
+export const isProhibition = (line) => PROHIBITION.test(line);
+
+/** Markdown constructs that open a new block rather than continue one. */
+const OPENS_BLOCK = /^\s*(#{1,6}\s|[-*+]\s|\d+[.)]\s|>\s|```|\||\s{4,}\S)/;
+
+const MAX_LOOKBACK = 8;
+
+/**
+ * The enclosing block of prose, ending at `index`.
+ *
+ * Markdown wraps sentences across lines, so a single physical line is the
+ * wrong unit for deciding whether a directive is an order or a prohibition.
+ * "Never commit ... or `.env` files. Read `OPENAI_API_KEY` from the
+ * environment" spans two lines in a real AGENTS.md, and reading only the
+ * second one turns good advice into a critical finding.
+ *
+ * Look backwards only. English puts the negation at the front of the
+ * sentence, and extending forwards would hand an evader a trailing "never".
+ */
+export function contextBefore(lines, index, maxLookback = MAX_LOOKBACK) {
+  const current = lines[index] ?? '';
+  if (OPENS_BLOCK.test(current)) return current;
+
+  const parts = [current];
+  for (let i = index - 1; i >= 0 && index - i <= maxLookback; i--) {
+    const line = lines[i];
+    if (line.trim() === '') break;
+    parts.unshift(line);
+    if (OPENS_BLOCK.test(line)) break;
+  }
+  return parts.join(' ');
+}
+
+/** The full source line containing `offset`. */
+export function lineAt(content, offset) {
+  const start = content.lastIndexOf('\n', offset - 1) + 1;
+  let end = content.indexOf('\n', offset);
+  if (end === -1) end = content.length;
+  return content.slice(start, end);
+}
+
+/**
+ * Run a global regex over a document and yield one finding per match,
+ * already located and excerpted.
+ *
+ * `build(match, line, context)` returns the finding-specific fields, or `null`
+ * to skip the match. `line` is the physical source line; `context` is the
+ * enclosing Markdown block, which is what rules should test for prohibitions.
+ */
+export function scan(doc, regex, build) {
+  const findings = [];
+  const re = new RegExp(regex.source, regex.flags.includes('g') ? regex.flags : `${regex.flags}g`);
+  let match;
+  while ((match = re.exec(doc.content)) !== null) {
+    if (match[0] === '') { re.lastIndex++; continue; }
+    const { line, column } = doc.locate(match.index);
+    const source = lineAt(doc.content, match.index);
+    const extra = build(match, source, contextBefore(doc.lines, line - 1));
+    if (!extra) continue;
+    findings.push({ path: doc.path, line, column, excerpt: excerpt(source), ...extra });
+  }
+  return findings;
+}
+
+/**
+ * Rough token count. Deliberately a heuristic, and labelled as one everywhere
+ * it surfaces: real tokenisers are model-specific and none of them are worth
+ * a dependency here. Word count plus a share of punctuation tracks the common
+ * BPE tokenisers closely enough to size an instruction file.
+ */
+export function estimateTokens(content) {
+  if (!content.trim()) return 0;
+  const words = content.trim().split(/\s+/).length;
+  const punctuation = (content.match(/[^\w\s]/g) ?? []).length;
+  return Math.round(words * 1.3 + punctuation * 0.3);
+}

package/src/rules/budget.js

@@ -0,0 +1,151 @@
+import { estimateTokens, excerpt } from '../lib/text.js';
+
+/**
+ * Cost and noise.
+ *
+ * Instruction files are not documentation: they are prepended to every single
+ * request the agent makes. A bloated AGENTS.md is a tax on every completion,
+ * and past a certain size the directives at the bottom stop being obeyed at
+ * all. These rules are the reason a team that has no security problem still
+ * gets value from running this.
+ */
+
+const PER_FILE_WARN = 2000;
+const PER_FILE_HIGH = 6000;
+const PROJECT_WARN = 8000;
+
+const VAGUE = /^\s*[-*]?\s*(write\s+(good|clean|quality|nice)\s+code|follow\s+(the\s+)?best\s+practices?|use\s+common\s+sense|be\s+(careful|thorough|smart)|keep\s+it\s+(simple|clean)|make\s+it\s+(good|work|nice)|do\s+your\s+best|think\s+step\s+by\s+step)\s*\.?\s*$/i;
+
+/** Ignore structural and code lines when hunting for duplication across files. */
+const isStructural = (line) => {
+  const t = line.trim();
+  return t.length < 25 || t.startsWith('#') || t.startsWith('```') || t.startsWith('|') || /^[-*=_]{3,}$/.test(t);
+};
+
+const normalise = (line) => line.trim().toLowerCase().replace(/\s+/g, ' ').replace(/[.;,]$/, '');
+
+export const rules = [
+  {
+    id: 'RAQIB050',
+    severity: 'medium',
+    title: 'Oversized instruction file',
+    check: (doc) => {
+      const tokens = estimateTokens(doc.content);
+      if (tokens < PER_FILE_WARN) return [];
+      const severity = tokens >= PER_FILE_HIGH ? 'high' : 'medium';
+      return [{
+        ruleId: 'RAQIB050',
+        path: doc.path,
+        line: 1,
+        column: 1,
+        severity,
+        title: 'Oversized instruction file',
+        message: `About ${tokens.toLocaleString('en-US')} tokens (estimated), ${doc.always ? 'added to every request the agent makes' : 'loaded whenever this file is in scope'}. Past roughly ${PER_FILE_HIGH.toLocaleString('en-US')}, later directives are routinely ignored.`,
+        excerpt: `${doc.lines.length} lines`,
+        remediation:
+          'Keep the always-loaded file to the rules that apply everywhere, and move the rest into files the agent loads on demand.',
+      }];
+    },
+  },
+  {
+    id: 'RAQIB051',
+    severity: 'low',
+    title: 'Unactionable directive',
+    check: (doc) =>
+      doc.lines.reduce((findings, line, index) => {
+        if (!VAGUE.test(line)) return findings;
+        findings.push({
+          ruleId: 'RAQIB051',
+          path: doc.path,
+          line: index + 1,
+          column: 1,
+          severity: 'low',
+          title: 'Unactionable directive',
+          message: 'This constrains nothing a model would not already attempt, and it costs tokens on every request.',
+          excerpt: excerpt(line),
+          remediation: 'Replace it with something checkable: a command to run, a pattern to follow, a directory to avoid.',
+        });
+        return findings;
+      }, []),
+  },
+  {
+    id: 'RAQIB052',
+    severity: 'low',
+    title: 'No executable guidance',
+    check: (doc) => {
+      if (estimateTokens(doc.content) < 80) return [];
+      if (/`[^`\n]+`|```/.test(doc.content)) return [];
+      return [{
+        ruleId: 'RAQIB052',
+        path: doc.path,
+        line: 1,
+        column: 1,
+        severity: 'low',
+        title: 'No executable guidance',
+        message: 'The file contains no command, path, or identifier the agent can act on.',
+        excerpt: `${doc.lines.length} lines of prose`,
+        remediation: 'Name the build, test, and lint commands. That is the single highest-value thing an instruction file can carry.',
+      }];
+    },
+  },
+  {
+    id: 'RAQIB053',
+    severity: 'low',
+    title: 'Duplicated across instruction files',
+    scope: 'project',
+    check: (_doc, ctx) => {
+      if (ctx.docs.length < 2) return [];
+      const seen = new Map();
+      for (const doc of ctx.docs) {
+        for (const [index, line] of doc.lines.entries()) {
+          if (isStructural(line)) continue;
+          const key = normalise(line);
+          if (!seen.has(key)) seen.set(key, []);
+          seen.get(key).push({ path: doc.path, line: index + 1, text: line });
+        }
+      }
+      const findings = [];
+      for (const [, hits] of seen) {
+        const paths = [...new Set(hits.map((h) => h.path))];
+        if (paths.length < 2) continue;
+        const [first] = hits;
+        findings.push({
+          ruleId: 'RAQIB053',
+          path: first.path,
+          line: first.line,
+          column: 1,
+          severity: 'low',
+          title: 'Duplicated across instruction files',
+          message: `The same directive appears in ${paths.join(', ')}. Whichever copy drifts first becomes a contradiction.`,
+          excerpt: excerpt(first.text),
+          remediation: 'Keep one copy and have the other file point at it.',
+        });
+      }
+      return findings;
+    },
+  },
+  {
+    id: 'RAQIB054',
+    severity: 'high',
+    title: 'Instruction budget exceeded',
+    scope: 'project',
+    check: (_doc, ctx) => {
+      // Conditional files (path-scoped, glob-scoped, on-demand) are not part
+      // of the per-request budget and must not inflate it.
+      const always = ctx.docs.filter((d) => d.always);
+      const total = always.reduce((sum, d) => sum + estimateTokens(d.content), 0);
+      if (total < PROJECT_WARN || always.length < 2) return [];
+      return [{
+        ruleId: 'RAQIB054',
+        path: always[0].path,
+        line: 1,
+        column: 1,
+        severity: 'high',
+        title: 'Instruction budget exceeded',
+        message: `${always.length} always-loaded instruction files totalling about ${total.toLocaleString('en-US')} tokens (estimated) are prepended to every request.`,
+        excerpt: always.map((d) => d.path).join(', '),
+        remediation: 'Consolidate. Overlapping instruction files compete for the same attention and contradict each other as they age.',
+      }];
+    },
+  },
+];