docguard-cli 0.29.0 → 0.30.1

package/cli/commands/verify.mjs

@@ -1,22 +1,38 @@
 /**
- * Verify Command — `docguard verify --semantic` (LLM field report #5).
+ * Verify Command — `docguard verify` (LLM field reports #5, #11).
  *
- * Surfaces the semantic claims in the canonical docs (documented numbers, limits,
- * and enums) as a structured verification task list for the agent to check
- * against the code. DocGuard does the deterministic discovery; the LLM does the
- * judgment — the same division of labour as `docguard agent`.
+ * Two modes, same division of labour (DocGuard does the deterministic
+ * discovery; the LLM does the judgment — like `docguard agent`):
+ *
+ *   --semantic (default)  Surface the semantic claims in the canonical docs
+ *                         (documented numbers, limits, enums) as a verification
+ *                         task list for the agent to check against the code.
+ *
+ *   --instructions        Audit the agent instruction files themselves
+ *                         (AGENTS.md, CLAUDE.md) for drift: duplicate rules,
+ *                         direct never/always contradictions, stale file
+ *                         pointers, and unknown docguard commands are found
+ *                         deterministically; topically-clustered rule pairs
+ *                         become agent tasks ("do these contradict in
+ *                         practice?"). Inspired by spec-kit's MemoryLint.
  *
  * Read-only. JSON is the machine artifact (the agent-executable task list);
  * text is the human summary.
  *
- *   docguard verify [--semantic] [--format json]
+ *   docguard verify [--semantic | --instructions] [--format json]
  */
 
 import { c } from '../shared.mjs';
 import { detectAgentMode } from '../ensure-skills.mjs';
 import { extractSemanticClaims, buildSemanticVerifyTasks } from '../scanners/semantic-claims.mjs';
+import { auditInstructions } from '../scanners/instruction-audit.mjs';
 
 export function runVerify(projectDir, config, flags) {
+  if (flags.instructions) {
+    runInstructionAudit(projectDir, config, flags);
+    return;
+  }
+
   const isJson = flags.format === 'json';
   const claims = extractSemanticClaims(projectDir, config);
   const tasks = buildSemanticVerifyTasks(claims);
@@ -65,3 +81,74 @@ export function runVerify(projectDir, config, flags) {
   console.log(`  ${c.dim}This is the highest-value bug class and DocGuard can't judge it — an agent must.${c.reset}`);
   console.log(`  ${c.dim}Get the machine task list: ${c.cyan}${cmd}${c.dim}, then read each cited file and confirm the value.${c.reset}\n`);
 }
+
+// ── verify --instructions: agent-instruction drift/conflict audit ───────────
+
+function runInstructionAudit(projectDir, config, flags) {
+  const isJson = flags.format === 'json';
+  const { rules, deterministic, tasks } = auditInstructions(projectDir, config);
+  const { duplicates, negations, stalePointers, staleCommands } = deterministic;
+  const findingCount = duplicates.length + negations.length + stalePointers.length + staleCommands.length;
+
+  if (isJson) {
+    console.log(JSON.stringify({
+      command: 'verify --instructions',
+      project: config.projectName,
+      ruleCount: rules.length,
+      findingCount,
+      findings: deterministic,
+      taskCount: tasks.length,
+      // How to act on this: findings are proven; tasks need judgment.
+      howToVerify: 'The findings are deterministic — fix them directly (delete the duplicate copy, resolve the negation in favour of one rule, repoint or remove stale paths/commands). For each task, read both rules in context and judge whether they contradict in practice; if so, report which should win, why, and which file to edit. DocGuard cannot judge the tasks — they require understanding intent.',
+      tasks,
+    }, null, 2));
+    return;
+  }
+
+  console.log(`${c.bold}🔬 DocGuard Verify — instruction audit${c.reset}`);
+  console.log(`${c.dim}   ${config.projectName} · duplicate / contradictory / stale rules in AGENTS.md + CLAUDE.md${c.reset}\n`);
+
+  if (rules.length === 0) {
+    console.log(`  ${c.green}✅ No instruction rules found (no AGENTS.md/CLAUDE.md, or nothing imperative in them).${c.reset}\n`);
+    return;
+  }
+
+  console.log(`  ${c.dim}${rules.length} rule(s) extracted from ${[...new Set(rules.map(r => r.file))].join(' + ')}${c.reset}\n`);
+
+  if (findingCount === 0) {
+    console.log(`  ${c.green}✅ No duplicate, directly-contradictory, or stale rules found.${c.reset}\n`);
+  } else {
+    console.log(`  ${c.yellow}${findingCount} deterministic finding(s):${c.reset}\n`);
+    for (const d of duplicates) {
+      const where = d.rules.map(r => `${r.file}:${r.line}`).join(` ${c.dim}≡${c.reset} `);
+      console.log(`    ${c.yellow}⚠${c.reset} duplicate rule — ${where}: ${c.dim}"${d.rules[0].text}"${c.reset}`);
+    }
+    for (const n of negations) {
+      console.log(`    ${c.yellow}⚠${c.reset} negation conflict — ${n.a.file}:${n.a.line} ${c.dim}⇄${c.reset} ${n.b.file}:${n.b.line}: ${c.dim}"${n.a.text}" vs "${n.b.text}"${c.reset}`);
+    }
+    for (const s of stalePointers) {
+      console.log(`    ${c.yellow}⚠${c.reset} stale pointer — ${s.file}:${s.line}: ${c.cyan}${s.path}${c.reset} does not exist`);
+    }
+    for (const s of staleCommands) {
+      console.log(`    ${c.yellow}⚠${c.reset} stale command — ${s.file}:${s.line}: ${c.cyan}docguard ${s.command}${c.reset} is not a docguard command`);
+    }
+    console.log('');
+  }
+
+  if (tasks.length > 0) {
+    console.log(`  ${c.yellow}${tasks.length} rule pair(s) for the agent to judge:${c.reset}\n`);
+    for (const t of tasks) {
+      console.log(`  ${c.bold}${t.a.file}:${t.a.line} ↔ ${t.b.file}:${t.b.line}${c.reset} ${c.dim}(shared: ${t.sharedTerms.join(', ')})${c.reset}`);
+      console.log(`    ${c.yellow}A${c.reset} ${c.dim}${t.a.section ? `[${t.a.section}] ` : ''}${c.reset}"${t.a.text}"`);
+      console.log(`    ${c.yellow}B${c.reset} ${c.dim}${t.b.section ? `[${t.b.section}] ` : ''}${c.reset}"${t.b.text}"`);
+      console.log('');
+    }
+
+    const mode = detectAgentMode(projectDir);
+    const cmd = mode === 'llm' ? '/docguard.verify' : 'docguard verify --instructions --format json';
+    console.log(`  ${c.dim}Whether clustered rules contradict in practice is judgment DocGuard can't make — an agent must.${c.reset}`);
+    console.log(`  ${c.dim}Get the machine task list: ${c.cyan}${cmd}${c.dim}, then judge each pair and report which rule should win.${c.reset}\n`);
+  } else if (findingCount === 0) {
+    console.log(`  ${c.dim}(Looks for duplicate/negated rules, dead file pointers, unknown docguard commands, and topically-clustered rule pairs.)${c.reset}\n`);
+  }
+}

package/cli/docguard.mjs

@@ -93,7 +93,7 @@ ${c.bold}Tools (situational, but day-to-day useful)${c.reset}
   ${c.green}feedback${c.reset}   Report likely false positives back to DocGuard (local-first + 1-click prefilled issue)
   ${c.green}mcp${c.reset}        MCP server over stdio — guard/score/explain/verify/diagnose as agent tools
   ${c.green}memory${c.reset}     Show what DocGuard remembers (${c.cyan}--diff${c.reset} drills into drift)
-  ${c.green}trace${c.reset}      Requirements traceability matrix (${c.cyan}--reverse${c.reset} for code→doc map)
+  ${c.green}trace${c.reset}      Requirements traceability matrix (${c.cyan}--reverse${c.reset} for code→doc map, ${c.cyan}--features${c.reset} for per-feature adherence)
   ${c.green}upgrade${c.reset}    Migrate ${c.cyan}.docguard.json${c.reset} schema + CLI (${c.cyan}--apply --pr${c.reset} for team-wide PR)
   ${c.green}watch${c.reset}      Live mode: re-run guard on file changes
 
@@ -258,7 +258,7 @@ const COMMAND_HELP = {
   },
   trace: {
     summary: 'Requirements traceability matrix.',
-    usage: 'docguard trace [--reverse]',
+    usage: 'docguard trace [--reverse] [--features]',
     flags: [['--reverse', 'Code→doc map instead of doc→code']],
     examples: ['docguard trace', 'docguard trace --reverse'],
   },
@@ -294,9 +294,10 @@ const COMMAND_HELP = {
   },
   verify: {
     summary: 'Extract the semantic claims in your canonical docs — documented numbers, limits, and enums (retention days, rate limits, GSI/role counts, status enums) — as a verification task list the agent checks against the code. This is the highest-value bug class (a doc value that drifted from code) and the one regex/AST cannot judge. DocGuard finds the claims; the LLM confirms them.',
-    usage: 'docguard verify [--semantic] [--format json]',
+    usage: 'docguard verify [--semantic|--instructions] [--format json]',
     flags: [
       ['--semantic', 'Extract documented numbers/limits/enums to verify against code (the current — and default — mode)'],
+      ['--instructions', 'Audit AGENTS.md/CLAUDE.md for duplicate, contradictory, and stale-pointer rules (deterministic findings + agent conflict tasks)'],
       ['--format json', 'Machine-readable task list (the agent-executable artifact)'],
     ],
     examples: ['docguard verify --semantic', 'docguard verify --semantic --format json'],
@@ -377,6 +378,10 @@ async function main() {
       // v0.28 (field report #5): `docguard verify --semantic` extracts
       // documented numbers/enums/limits for the agent to check against code.
       flags.semantic = true;
+    } else if (args[i] === '--instructions') {
+      // v0.30: `docguard verify --instructions` audits AGENTS.md/CLAUDE.md for
+      // duplicate/contradictory/stale rules (MemoryLint-inspired).
+      flags.instructions = true;
     } else if (args[i] === '--full') {
       // v0.29: `docguard llms --full` emits llms-full.txt (inline doc bodies,
       // the Mintlify-popularized companion to the llms.txt index).
@@ -409,6 +414,9 @@ async function main() {
       flags.changedOnly = true;
     } else if (args[i] === '--reverse') {
       flags.reverse = true;
+    } else if (args[i] === '--features') {
+      // v0.30: `docguard trace --features` — per-feature spec-adherence report.
+      flags.features = true;
     } else if (args[i] === '--history') {
       flags.history = true;
     } else if (args[i] === '--force-redo') {

package/cli/findings.mjs

@@ -474,6 +474,18 @@ export const CODES = {
     help: 'constitution.md exists but there is no AGENTS.md. AI agents look to AGENTS.md for project rules — create one (e.g. via `docguard init`) and reference the constitution from it.',
     suppress: null,
   },
+  SPK008: {
+    validator: 'specKit',
+    title: 'Phantom completion — checked task with no implementation evidence',
+    help: 'A tasks.md task marked [x] names a deliverable path that does not exist, and no evidence tier confirms the work landed: no matching basename anywhere in the repo (moved file), no named code symbol in source, no plan.md/spec.md tie to an existing artifact, no task-ID annotation in source, and no task-ID in the git log. A checked task with no artifact corrupts agent memory — later sessions trust the checkbox and skip the work. Uncheck the task or land the implementation. Flagged low-confidence — report a false positive if the deliverable was renamed beyond recognition. Opt out with `"specKit": { "phantomCheck": false }` in .docguard.json.',
+    suppress: null,
+  },
+  SPK009: {
+    validator: 'specKit',
+    title: 'Additional phantom completions elided',
+    help: 'Guard reports at most 10 phantom-completion findings (SPK008) per run to avoid noise; this line counts the remainder. Fix or uncheck the reported tasks and re-run guard to surface more, or set `"specKit": { "phantomCheck": false }` in .docguard.json to disable the check.',
+    suppress: null,
+  },
   XRF001: {
     validator: 'crossReference',
     title: 'Broken doc link',

package/cli/scanners/instruction-audit.mjs

@@ -0,0 +1,320 @@
+/**
+ * Instruction Audit scanner — drift/conflict audit WITHIN agent instruction
+ * files (AGENTS.md, CLAUDE.md). Inspired by spec-kit's MemoryLint.
+ *
+ * Agent instruction files rot in a specific way: rules get duplicated across
+ * AGENTS.md and CLAUDE.md, then one copy is edited and the other isn't — an
+ * agent reading both now holds two contradictory orders and silently picks
+ * one. Rules also point at files that were renamed away, and at docguard
+ * subcommands that no longer exist. None of the doc↔code validators see this
+ * class: the drift is doc↔doc, inside the instruction layer itself.
+ *
+ * DocGuard's split applies (sibling of semantic-claims.mjs):
+ *   - DETERMINISTIC: extract the rules, then flag what string logic can prove
+ *     — exact-normalized duplicates, direct never/always negation pairs,
+ *     pointers to nonexistent files, references to unknown docguard commands.
+ *   - LLM JUDGMENT: rule pairs in the same topical cluster (≥2 shared
+ *     significant stems) become tasks for the agent running
+ *     `docguard verify --instructions` — "do these contradict in practice?".
+ *     Cross-file pairs are prioritized: AGENTS-vs-CLAUDE divergence is the
+ *     classic drift.
+ *
+ * Precision over recall: a line is only a rule when it carries an
+ * imperative/modal signal (must/never/always/…); a pointer is only checked
+ * when it lexes as a relative file path; a docguard command is only checked
+ * inside backticks (prose like "docguard should never…" is not an
+ * invocation). Files generated by `docguard agents --sync` (they carry the
+ * docguard:agents-sync marker) are skipped — auditing a generated mirror
+ * against its source would flag every rule as a duplicate.
+ *
+ * Zero npm dependencies — pure Node.js built-ins.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const INSTRUCTION_FILES = ['AGENTS.md', 'CLAUDE.md'];
+const GENERATED_MARKER = 'docguard:agents-sync';
+
+/** A line/sentence is only a rule when it carries an imperative/modal signal. */
+const SIGNAL_RE = /\b(must|never|always|do not|don't|should|require[sd]?|forbid|only)\b/i;
+
+const MAX_RULES = 400;
+const MAX_TASKS = 40;
+
+// ── Normalization ───────────────────────────────────────────────────────────
+
+/** lowercase, drop apostrophes (don't → dont), all other punctuation → space. */
+function normalizeRule(text) {
+  return text
+    .toLowerCase()
+    .replace(/['’]/g, '')
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+// Negation tokens (counted for parity) vs the full polarity set (stripped for
+// comparison). "do not" must precede "not"/"do" in the alternation so it
+// matches as one token.
+const NEG_RE = /\b(never|dont|do not|not)\b/g;
+const POLARITY_RE = /\b(never|dont|do not|not|always|must|do|should|shall)\b/g;
+
+const negationCount = (norm) => (norm.match(NEG_RE) || []).length;
+const stripPolarity = (norm) => norm.replace(POLARITY_RE, ' ').replace(/\s+/g, ' ').trim();
+
+// ── Rule extraction (deterministic) ─────────────────────────────────────────
+
+/**
+ * Parse AGENTS.md + CLAUDE.md into rules: list items or paragraph sentences
+ * carrying an imperative/modal signal. Skips fenced code, tables, HTML
+ * comments, and files generated by `docguard agents --sync`.
+ * @returns {Array<{ file, line, section, text }>}
+ */
+export function extractInstructionRules(projectDir) {
+  const rules = [];
+  for (const file of INSTRUCTION_FILES) {
+    let content;
+    try { content = readFileSync(resolve(projectDir, file), 'utf-8'); } catch { continue; }
+    if (content.includes(GENERATED_MARKER)) continue; // generated mirror of AGENTS.md — audit the source, not the copy
+
+    const lines = content.split('\n');
+    let section = '';
+    let inFence = false;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (/^\s*```/.test(line)) { inFence = !inFence; continue; }
+      if (inFence) continue; // rules in code samples are examples, not orders
+      const h = line.match(/^(#{2,3})\s+(.+)$/);
+      if (h) { section = h[2].trim(); continue; }
+      const t = line.trim();
+      if (!t || t.startsWith('#') || t.startsWith('<!--') || t.startsWith('|')) continue;
+
+      // A list item is one candidate rule; a paragraph line splits into sentences.
+      const li = t.match(/^(?:[-*+]|\d+[.)])\s+(.*)$/);
+      const candidates = li ? [li[1]] : t.replace(/^>\s*/, '').split(/(?<=[.!?])\s+/);
+      for (const cand of candidates) {
+        const text = cand.trim();
+        if (text.length < 8 || !SIGNAL_RE.test(text)) continue;
+        rules.push({ file, line: i + 1, section, text: text.slice(0, 200) });
+        if (rules.length >= MAX_RULES) return rules;
+      }
+    }
+  }
+  return rules;
+}
+
+// ── Deterministic findings ──────────────────────────────────────────────────
+
+const PATH_EXTS = 'md|mjs|cjs|js|ts|tsx|jsx|json|ya?ml|py|sh|toml|txt|rs|go|css|html';
+// Backticked token: no spaces, lexes as a relative path with a known extension.
+const PATH_LIKE_RE = new RegExp(`^[\\w.-][\\w./-]*\\.(?:${PATH_EXTS})$`, 'i');
+// Bare (unbackticked) token: requires a directory separator for precision.
+const BARE_PATH_RE = new RegExp(`(?:^|[\\s("'])([\\w.-]+\\/[\\w./-]+\\.(?:${PATH_EXTS}))\\b`, 'gi');
+const BACKTICK_RE = /`([^`]+)`/g;
+const DOCGUARD_CMD_RE = /\bdocguard\s+([a-z][a-z0-9-]*)\b/g;
+
+/** File-path candidates referenced by a rule (anchors/line refs stripped). */
+function pathCandidates(text) {
+  const found = new Set();
+  BACKTICK_RE.lastIndex = 0;
+  let m;
+  while ((m = BACKTICK_RE.exec(text)) !== null) {
+    const tok = m[1].replace(/[#:].*$/, '').trim();
+    if (!tok.includes(' ') && PATH_LIKE_RE.test(tok)) found.add(tok);
+  }
+  BARE_PATH_RE.lastIndex = 0;
+  while ((m = BARE_PATH_RE.exec(text)) !== null) found.add(m[1].replace(/[#:].*$/, ''));
+  return [...found];
+}
+
+/**
+ * Known docguard subcommands: cli/commands/*.mjs basenames + permanent
+ * aliases. Read from disk at runtime so the list can't drift from the code.
+ * Returns null when unreadable — the caller then SKIPS the check (a wrong
+ * "unknown command" is worse than a missed one).
+ */
+function knownDocguardCommands() {
+  try {
+    const names = readdirSync(join(__dirname, '..', 'commands'))
+      .filter(f => f.endsWith('.mjs'))
+      .map(f => f.slice(0, -'.mjs'.length));
+    return new Set([...names, 'audit', 'dx']);
+  } catch { return null; }
+}
+
+/**
+ * The findings string logic can prove — no LLM involved.
+ * @returns {{ duplicates, negations, stalePointers, staleCommands }}
+ */
+export function findDeterministicFindings(rules, projectDir) {
+  // duplicates: exact-normalized matches, within or across files.
+  const byNorm = new Map();
+  for (const r of rules) {
+    const norm = normalizeRule(r.text);
+    if (!norm) continue;
+    if (!byNorm.has(norm)) byNorm.set(norm, []);
+    byNorm.get(norm).push(r);
+  }
+  const duplicates = [...byNorm.entries()]
+    .filter(([, rs]) => rs.length >= 2)
+    .map(([normalized, rs]) => ({ normalized, rules: rs }));
+
+  // direct-negation pairs: identical after stripping polarity tokens, with
+  // opposite negation-count parity ("never use tabs" vs "always use tabs").
+  const negations = [];
+  const byStripped = new Map();
+  for (const r of rules) {
+    const norm = normalizeRule(r.text);
+    const stripped = stripPolarity(norm);
+    if (stripped.split(' ').length < 2) continue; // "never" vs "always" alone proves nothing
+    if (!byStripped.has(stripped)) byStripped.set(stripped, []);
+    byStripped.get(stripped).push({ r, norm, parity: negationCount(norm) % 2 });
+  }
+  for (const [stripped, group] of byStripped) {
+    if (group.length < 2) continue;
+    for (let i = 0; i < group.length; i++) {
+      for (let j = i + 1; j < group.length; j++) {
+        const A = group[i], B = group[j];
+        if (A.parity === B.parity || A.norm === B.norm) continue; // same polarity → duplicate territory, not a conflict
+        negations.push({ a: A.r, b: B.r, common: stripped });
+      }
+    }
+  }
+
+  // stale pointers: referenced file paths that don't exist in the repo.
+  const stalePointers = [];
+  const seenPtr = new Set();
+  for (const r of rules) {
+    for (const p of pathCandidates(r.text)) {
+      const key = `${r.file}:${r.line}:${p}`;
+      if (seenPtr.has(key)) continue;
+      seenPtr.add(key);
+      if (!existsSync(resolve(projectDir, p))) {
+        stalePointers.push({ file: r.file, line: r.line, section: r.section, text: r.text, path: p });
+      }
+    }
+  }
+
+  // stale commands: `docguard <cmd>` (backticked — an invocation, not prose)
+  // where <cmd> is not a known command.
+  const staleCommands = [];
+  const known = knownDocguardCommands();
+  if (known) {
+    const seenCmd = new Set();
+    for (const r of rules) {
+      BACKTICK_RE.lastIndex = 0;
+      let span;
+      while ((span = BACKTICK_RE.exec(r.text)) !== null) {
+        DOCGUARD_CMD_RE.lastIndex = 0;
+        let m;
+        while ((m = DOCGUARD_CMD_RE.exec(span[1])) !== null) {
+          const command = m[1];
+          const key = `${r.file}:${r.line}:${command}`;
+          if (known.has(command) || seenCmd.has(key)) continue;
+          seenCmd.add(key);
+          staleCommands.push({ file: r.file, line: r.line, section: r.section, text: r.text, command });
+        }
+      }
+    }
+  }
+
+  return { duplicates, negations, stalePointers, staleCommands };
+}
+
+// ── LLM tasks (topical-cluster pairs) ───────────────────────────────────────
+
+// Function words + polarity/signal tokens. Content verbs (use, run, commit,
+// write, read…) stay significant — "never use tabs" / "always use spaces"
+// should cluster on use+indentation, not be filtered to nothing.
+const STOPWORDS = new Set([
+  'the', 'a', 'an', 'to', 'of', 'in', 'for', 'and', 'or', 'with', 'without',
+  'on', 'at', 'by', 'from', 'as', 'is', 'are', 'be', 'been', 'being', 'it',
+  'its', 'this', 'that', 'these', 'those', 'you', 'your', 'we', 'our', 'all',
+  'any', 'each', 'every', 'when', 'where', 'while', 'if', 'then', 'than',
+  'so', 'but', 'not', 'no', 'never', 'always', 'must', 'should', 'shall',
+  'do', 'dont', 'does', 'did', 'done', 'can', 'cannot', 'cant', 'may',
+  'might', 'will', 'would', 'could', 'only', 'before', 'after', 'into',
+  'over', 'under', 'via', 'per', 'also', 'ever', 'instead', 'rather',
+  'avoid', 'ensure', 'require', 'requires', 'required', 'forbid', 'forbidden',
+  'e', 'g', 'i', 'etc', 'please',
+]);
+
+/** Cheap suffix stemmer — consistency matters, not linguistics. */
+function stem(w) {
+  let s = w;
+  if (s.length > 5 && s.endsWith('ing')) s = s.slice(0, -3);
+  else if (s.length > 4 && (s.endsWith('ed') || s.endsWith('es'))) s = s.slice(0, -2);
+  else if (s.length > 3 && s.endsWith('s')) s = s.slice(0, -1);
+  if (s.length > 3 && s[s.length - 1] === s[s.length - 2]) s = s.slice(0, -1); // committ → commit
+  return s;
+}
+
+function significantStems(norm) {
+  const stems = new Set();
+  for (const w of norm.split(' ')) {
+    if (w.length < 3 || STOPWORDS.has(w) || /^\d+$/.test(w)) continue;
+    stems.add(stem(w));
+  }
+  return stems;
+}
+
+/**
+ * Rule pairs in the same topical cluster (≥2 shared significant stems) become
+ * agent judgment tasks. Pairs already proven by the deterministic pass (exact
+ * duplicates, direct negations) are excluded — no LLM needed there. Cross-file
+ * pairs first (AGENTS-vs-CLAUDE divergence is the classic drift), capped.
+ */
+export function buildInstructionAuditTasks(rules) {
+  const enriched = rules.map(r => {
+    const norm = normalizeRule(r.text);
+    return { r, norm, stripped: stripPolarity(norm), parity: negationCount(norm) % 2, stems: significantStems(norm) };
+  });
+
+  const pairs = [];
+  for (let i = 0; i < enriched.length; i++) {
+    for (let j = i + 1; j < enriched.length; j++) {
+      const A = enriched[i], B = enriched[j];
+      if (A.norm === B.norm) continue; // exact duplicate — deterministic finding
+      if (A.stripped === B.stripped && A.parity !== B.parity) continue; // direct negation — deterministic finding
+      const shared = [...A.stems].filter(s => B.stems.has(s));
+      if (shared.length < 2) continue;
+      pairs.push({ a: A.r, b: B.r, shared, crossFile: A.r.file !== B.r.file });
+    }
+  }
+
+  pairs.sort((p, q) =>
+    (q.crossFile - p.crossFile) ||
+    (q.shared.length - p.shared.length) ||
+    (p.a.line - q.a.line) || (p.b.line - q.b.line));
+
+  return pairs.slice(0, MAX_TASKS).map((p, i) => {
+    const at = (r) => `${r.file}:${r.line}${r.section ? ` (section "${r.section}")` : ''}`;
+    return {
+      id: `verify.instructions.${i + 1}`,
+      a: p.a,
+      b: p.b,
+      sharedTerms: p.shared,
+      crossFile: p.crossFile,
+      instruction: `Judge whether these two agent-instruction rules contradict in practice. Rule A — ${at(p.a)}: "${p.a.text}". Rule B — ${at(p.b)}: "${p.b.text}". They share the terms: ${p.shared.join(', ')}. If they conflict, report which rule should win, why, and which file to edit; if one merely duplicates the other, say which copy to delete; if they complement each other, say so.`,
+      confidence: 'requires-human',
+    };
+  });
+}
+
+// ── Entry point ─────────────────────────────────────────────────────────────
+
+/**
+ * Full instruction audit: extract rules, prove what string logic can prove,
+ * and stage the semantic-conflict judgments for the agent.
+ * @returns {{ rules, deterministic: {duplicates,negations,stalePointers,staleCommands}, tasks }}
+ */
+export function auditInstructions(projectDir, config = {}) {
+  const rules = extractInstructionRules(projectDir);
+  const deterministic = findDeterministicFindings(rules, projectDir);
+  const tasks = buildInstructionAuditTasks(rules);
+  return { rules, deterministic, tasks };
+}