docguard-cli 0.28.0 → 0.30.0

package/cli/scanners/agent-readability.mjs

@@ -0,0 +1,202 @@
+/**
+ * Agent Readability scanner — how well do this repo's docs serve an AI agent?
+ *
+ * Human readability (Flesch, passive voice — doc-quality.mjs) asks "can a
+ * person read this prose?". This scanner asks the 2026 question: "can an AI
+ * consumer FIND, QUOTE, and TRUST this documentation?" — token budgets,
+ * section addressability, machine-parseable structure, metadata markers, and
+ * unbroken pointers. Deterministic, zero-LLM, zero npm dependencies.
+ *
+ * DISPLAY-ONLY consumer contract: assessAgentReadability feeds a score display
+ * block (like ALCOA+) and must never feed the gating CDD grade — CI thresholds
+ * read that.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+
+/** chars/4 — the standard rough token estimate; consistency matters more than precision. */
+const estTokens = (s) => Math.ceil(s.length / 4);
+
+const GRADES = [[90, 'A'], [75, 'B'], [60, 'C'], [40, 'D']];
+function toGrade(score) {
+  for (const [min, g] of GRADES) if (score >= min) return g;
+  return 'F';
+}
+
+function readIfExists(path) {
+  try { return existsSync(path) ? readFileSync(path, 'utf-8') : null; } catch { return null; }
+}
+
+function canonicalDocs(projectDir) {
+  const dir = resolve(projectDir, 'docs-canonical');
+  if (!existsSync(dir)) return [];
+  try {
+    return readdirSync(dir)
+      .filter(f => f.toLowerCase().endsWith('.md'))
+      .sort()
+      .map(f => ({ name: `docs-canonical/${f}`, content: readIfExists(resolve(dir, f)) }))
+      .filter(d => d.content !== null);
+  } catch { return []; }
+}
+
+/**
+ * Split a markdown body into sections at H2/H3 headings.
+ * Returns [{heading, body}] — body excludes the heading line itself.
+ */
+function splitSections(content) {
+  const lines = content.split('\n');
+  const sections = [];
+  let current = null;
+  let inFence = false;
+  for (const line of lines) {
+    if (/^\s*```/.test(line)) inFence = !inFence;
+    const h = !inFence && line.match(/^#{2,3}\s+(.+)$/);
+    if (h) {
+      if (current) sections.push(current);
+      current = { heading: h[1].trim(), body: '' };
+    } else if (current) {
+      current.body += line + '\n';
+    }
+  }
+  if (current) sections.push(current);
+  return sections;
+}
+
+/** Fraction of non-blank lines that are structured (table/list/fence/heading/marker). */
+function structuredFraction(content) {
+  let structured = 0, total = 0, inFence = false;
+  for (const line of content.split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    total++;
+    if (/^```/.test(t)) { inFence = !inFence; structured++; continue; }
+    if (inFence) { structured++; continue; }
+    if (/^(\||[-*+]\s|\d+\.\s|#{1,6}\s|>|<!--)/.test(t)) structured++;
+  }
+  return total === 0 ? 0 : structured / total;
+}
+
+/**
+ * Assess agent readability for a project.
+ * @returns {{ metrics: Array<{key,label,score,detail,fix}>, score: number, grade: string }}
+ */
+export function assessAgentReadability(projectDir, config = {}) {
+  const metrics = [];
+  const agentsMd = readIfExists(resolve(projectDir, 'AGENTS.md'));
+  const claudeMd = readIfExists(resolve(projectDir, 'CLAUDE.md'));
+  const agentEntry = agentsMd ?? claudeMd;
+  const docs = canonicalDocs(projectDir);
+
+  // 1. agent-entry — without an entry file, an agent starts blind.
+  metrics.push({
+    key: 'agent-entry',
+    label: 'Agent entry file',
+    score: agentEntry ? 100 : 0,
+    detail: agentsMd ? 'AGENTS.md present' : claudeMd ? 'CLAUDE.md present (no AGENTS.md)' : 'no AGENTS.md or CLAUDE.md',
+    fix: agentEntry ? null : 'Create AGENTS.md (docguard init scaffolds it) — agents need an entry point',
+  });
+
+  // 2. token-budget — an entry file beyond the skim budget gets skimmed, not read.
+  if (agentEntry) {
+    const tokens = estTokens(agentEntry);
+    let score, fix = null;
+    if (tokens <= 2000) score = 100;
+    else if (tokens <= 4000) score = 75;
+    else if (tokens <= 8000) { score = 40; fix = 'Trim the agent entry file below ~4k tokens — link out to detail docs instead of inlining'; }
+    else { score = 10; fix = 'Agent entry file blows the context skim budget — split into linked canonical docs'; }
+    metrics.push({
+      key: 'token-budget',
+      label: 'Entry-file token budget',
+      score,
+      detail: `~${tokens} est. tokens (ideal ≤2000, acceptable ≤4000)`,
+      fix,
+    });
+  }
+
+  // 3. addressability — can a section be quoted alone, and do anchors resolve uniquely?
+  if (docs.length > 0) {
+    let quotable = 0, totalSections = 0, dupDocs = [];
+    for (const d of docs) {
+      const sections = splitSections(d.content);
+      totalSections += sections.length;
+      quotable += sections.filter(s => estTokens(s.body) <= 120).length;
+      const seen = new Set();
+      for (const s of sections) {
+        const slug = s.heading.toLowerCase();
+        if (seen.has(slug)) { dupDocs.push(`${d.name} ("${s.heading}")`); break; }
+        seen.add(slug);
+      }
+    }
+    const frac = totalSections === 0 ? 0 : quotable / totalSections;
+    let score = Math.round(frac * 100);
+    if (dupDocs.length > 0) score = Math.max(0, score - 30);
+    metrics.push({
+      key: 'addressability',
+      label: 'Section addressability',
+      score,
+      detail: `${quotable}/${totalSections} H2/H3 sections quotable alone (≤120 tok)${dupDocs.length ? `; duplicate headings: ${dupDocs[0]}${dupDocs.length > 1 ? ` +${dupDocs.length - 1}` : ''}` : ''}`,
+      fix: score >= 60 ? null : dupDocs.length ? 'Make headings unique within each doc — duplicates break anchor links' : 'Split long sections — an agent should be able to quote one section without dragging the whole doc',
+    });
+  }
+
+  // 4. structure-density — tables/lists/fences parse; prose walls don't.
+  if (docs.length > 0) {
+    const fracs = docs.map(d => structuredFraction(d.content));
+    const avg = fracs.reduce((a, b) => a + b, 0) / fracs.length;
+    const score = Math.min(100, Math.round((avg / 0.3) * 100));
+    metrics.push({
+      key: 'structure-density',
+      label: 'Structured-content density',
+      score,
+      detail: `${Math.round(avg * 100)}% of canonical-doc lines are structured (target ≥30%)`,
+      fix: score >= 60 ? null : 'Convert prose walls to tables/lists — structured content is machine-parseable',
+    });
+  }
+
+  // 5. marker-presence — machine-readable metadata density.
+  if (docs.length > 0) {
+    const marked = docs.filter(d => /docguard:(last-reviewed|section|generated)/.test(d.content)).length;
+    metrics.push({
+      key: 'marker-presence',
+      label: 'Machine markers',
+      score: Math.round((marked / docs.length) * 100),
+      detail: `${marked}/${docs.length} canonical docs carry docguard markers (last-reviewed / section / generated)`,
+      fix: marked === docs.length ? null : 'Add <!-- docguard:last-reviewed YYYY-MM-DD --> to unmarked docs — agents use it to judge trust',
+    });
+  }
+
+  // 6. llms-txt — the AI-consumer index standard.
+  const hasLlms = existsSync(resolve(projectDir, 'llms.txt'));
+  metrics.push({
+    key: 'llms-txt',
+    label: 'llms.txt index',
+    score: hasLlms ? 100 : 0,
+    detail: hasLlms ? 'llms.txt present at root' : 'no llms.txt at root',
+    fix: hasLlms ? null : 'Run docguard llms — generates the llms.txt AI index from your canonical docs',
+  });
+
+  // 7. self-containedness — broken relative pointers strand an agent mid-task.
+  // The entry file lives at the project root, so links resolve against it.
+  if (agentEntry) {
+    const links = [...agentEntry.matchAll(/\]\(([^)#]+\.md)(?:#[^)]*)?\)/g)]
+      .map(m => m[1])
+      .filter(l => !/^[a-z]+:\/\//i.test(l));
+    if (links.length > 0) {
+      const broken = links.filter(l => !existsSync(resolve(projectDir, l)));
+      metrics.push({
+        key: 'self-containedness',
+        label: 'Entry-file link integrity',
+        score: Math.round(((links.length - broken.length) / links.length) * 100),
+        detail: broken.length === 0
+          ? `${links.length}/${links.length} relative doc links resolve`
+          : `${broken.length}/${links.length} relative links broken (first: ${broken[0]})`,
+        fix: broken.length === 0 ? null : 'Fix the broken links — a dead pointer strands an agent mid-task',
+      });
+    }
+  }
+
+  const score = metrics.length === 0 ? 0
+    : Math.round(metrics.reduce((sum, m) => sum + m.score, 0) / metrics.length);
+  return { metrics, score, grade: toGrade(score) };
+}

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 };
+}

package/cli/scanners/semantic-claims.mjs

@@ -28,7 +28,13 @@ import { resolve, join } from 'node:path';
 const NUMBER_PATTERNS = [
   { kind: 'duration', re: /\b(\d+(?:\.\d+)?)\s*(milliseconds?|ms|seconds?|secs?|minutes?|mins?|hours?|hrs?|days?|weeks?|months?|years?)\b/gi },
   { kind: 'rate',     re: /\b(\d+)\s*(?:\/|\bper\b|\breq(?:uests?)?\s*\/?)\s*(s|sec|seconds?|min|minutes?|hours?|h)\b/gi },
-  { kind: 'count',    re: /\b(\d+)\s*\+?\s*(GSIs?|LSIs?|indexes|indices|roles?|permissions?|scopes?|tables?|queues?|topics?|buckets?|endpoints?|routes?|validators?|columns?|fields?|shards?|partitions?|replicas?|retries|workers?|threads?|connections?)\b/gi },
+  // Field report #6: the noun list IS the precision mechanism — a number is only
+  // a claim when it sits next to a recognized "registered-unit" noun. The gap that
+  // shipped a wrong "16 extractors" past every check was simply that "extractors"
+  // (and its domain-collection siblings) weren't in this list. Added the common
+  // pluggable-architecture nouns. Deliberately NOT added: generic prose nouns that
+  // collide with running-text numbers (steps, items, checks, modules, services).
+  { kind: 'count',    re: /\b(\d+)\s*\+?\s*(GSIs?|LSIs?|indexes|indices|roles?|permissions?|scopes?|tables?|queues?|topics?|buckets?|endpoints?|routes?|validators?|columns?|fields?|shards?|partitions?|replicas?|retries|workers?|threads?|connections?|extractors?|plugins?|detectors?|scanners?|analyzers?|collectors?|commands?|subcommands?|rules?|hooks?|providers?|adapters?|handlers?|middlewares?|transformers?|processors?|generators?|parsers?|exporters?|importers?|integrations?|formatters?|linters?|agents?|skills?)\b/gi },
 ];
 
 // A list of 2+ UPPER_SNAKE tokens separated by / , | or "or" — an enum claim,