docguard-cli 0.27.0 → 0.29.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/semantic-claims.mjs

@@ -0,0 +1,160 @@
+/**
+ * Semantic claim extractor (LLM field report #5).
+ *
+ * The highest-value class of doc bug is SEMANTIC: a documented number/enum/limit
+ * that no longer matches the code — DLP retention "30 days" vs code 730, a status
+ * enum "PENDING/IDLE" vs "WAITING", "100/min" vs "500 req/s", "29+ roles" vs 44,
+ * "4 GSIs" vs 6. Regex/AST can't judge these (the doc value and the code value
+ * are both just numbers), so they slip through every deterministic validator.
+ *
+ * DocGuard is zero-dependency and does NOT call an LLM itself. So this is an
+ * EXTRACTOR: it surfaces the verifiable claims — value, unit, doc:line, section,
+ * and the nearest cited code path — as a structured task list. The agent running
+ * `docguard verify --semantic` does the actual comparison against the code. This
+ * mirrors the `docguard agent` task-graph: deterministic discovery, LLM judgment.
+ *
+ * Precision over recall: a number is only a claim when it carries a recognized
+ * unit (days/ms/req-s/GSIs/roles/…); an enum only when it's a list of 2+
+ * UPPER_SNAKE tokens in a status/state/enum context. Bare version strings, dates,
+ * and prose numbers are ignored.
+ *
+ * Zero npm dependencies — pure Node.js built-ins.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+// Numbers are only claims when adjacent to a recognized unit.
+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 },
+  // 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,
+// but only when the line or its heading reads like a status/state/enum context.
+const ENUM_LIST_RE = /\b[A-Z][A-Z0-9_]{2,}(?:\s*(?:\/|,|\||\bor\b)\s*[A-Z][A-Z0-9_]{2,}){1,}\b/g;
+const ENUM_CONTEXT_RE = /\b(status|state|enum|values?|one of|phase|stage|transitions?)\b/i;
+
+// A code path mentioned in or near the claim — the agent's starting point.
+const CITED_CODE_RE = /`?([\w./-]+\.(?:ts|tsx|js|mjs|cjs|jsx|py|go|rs|java|kt|rb|php|sql|yaml|yml|json))`?(?::(\d+))?/;
+
+const MAX_CLAIMS = 80;
+
+/** Canonical docs + the root docs where limits/counts commonly live. */
+function claimSourceDocs(projectDir) {
+  const docs = [];
+  const canonical = resolve(projectDir, 'docs-canonical');
+  if (existsSync(canonical)) {
+    try {
+      for (const f of readdirSync(canonical)) {
+        if (f.toLowerCase().endsWith('.md')) docs.push(`docs-canonical/${f}`);
+      }
+    } catch { /* ignore */ }
+  }
+  for (const root of ['README.md', 'AGENTS.md']) {
+    if (existsSync(resolve(projectDir, root))) docs.push(root);
+  }
+  return docs;
+}
+
+/** True if a line is inside a fenced code block (toggled by the caller). */
+function findCitedCode(lines, idx) {
+  // Search the claim line first, then the immediately adjacent lines. A tight
+  // window avoids cross-attributing a path from an unrelated nearby claim (e.g.
+  // a rate limit grabbing the retention doc's cited file three lines up).
+  for (let d = 0; d <= 1; d++) {
+    for (const j of d === 0 ? [idx] : [idx - d, idx + d]) {
+      if (j < 0 || j >= lines.length) continue;
+      const m = CITED_CODE_RE.exec(lines[j]);
+      if (m) return m[2] ? `${m[1]}:${m[2]}` : m[1];
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract semantic claims from a project's canonical docs.
+ * @returns {Array<{ doc, line, section, kind, subkind, value, unit, text, citedCode }>}
+ */
+export function extractSemanticClaims(projectDir, config = {}) {
+  const claims = [];
+  const seen = new Set();
+
+  for (const doc of claimSourceDocs(projectDir)) {
+    let content;
+    try { content = readFileSync(resolve(projectDir, doc), 'utf-8'); } catch { continue; }
+    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; // numbers in code samples are examples, not claims
+      const h = line.match(/^#{1,6}\s+(.*)$/);
+      if (h) { section = h[1].trim(); continue; }
+
+      const lineNo = i + 1;
+      const push = (claim) => {
+        const key = `${doc}:${lineNo}:${claim.kind}:${claim.value}:${claim.unit || ''}`;
+        if (seen.has(key)) return;
+        seen.add(key);
+        claims.push({ doc, line: lineNo, section, citedCode: findCitedCode(lines, i), text: line.trim().slice(0, 200), ...claim });
+      };
+
+      for (const { kind, re } of NUMBER_PATTERNS) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(line)) !== null) {
+          push({ kind: 'number', subkind: kind, value: m[1], unit: m[2].toLowerCase() });
+        }
+      }
+
+      if (ENUM_CONTEXT_RE.test(line) || ENUM_CONTEXT_RE.test(section)) {
+        ENUM_LIST_RE.lastIndex = 0;
+        let m;
+        while ((m = ENUM_LIST_RE.exec(line)) !== null) {
+          // Skip all-caps acronym runs joined by slash that are really one token.
+          const values = m[0].split(/\s*(?:\/|,|\||\bor\b)\s*/).filter(Boolean);
+          if (values.length >= 2) push({ kind: 'enum', subkind: 'enum-list', value: values.join('/'), unit: null });
+        }
+      }
+
+      if (claims.length >= MAX_CLAIMS) return claims;
+    }
+  }
+  return claims;
+}
+
+/**
+ * Turn extracted claims into agent-executable verification tasks (one per claim).
+ * Pure — reused by the command and any task-graph consumer.
+ */
+export function buildSemanticVerifyTasks(claims) {
+  return claims.map((c, i) => {
+    const where = c.citedCode ? ` Start at the cited code: ${c.citedCode}.` : ' No code path is cited nearby — grep the codebase for the relevant constant/config.';
+    const what = c.kind === 'enum'
+      ? `the enum/status set "${c.value}"`
+      : `the ${c.subkind} value ${c.value}${c.unit ? ` ${c.unit}` : ''}`;
+    return {
+      id: `verify.semantic.${i + 1}`,
+      doc: c.doc,
+      line: c.line,
+      section: c.section,
+      kind: c.kind,
+      value: c.value,
+      unit: c.unit,
+      citedCode: c.citedCode,
+      claim: c.text,
+      instruction: `Verify ${what} documented in ${c.doc}:${c.line}${c.section ? ` (section "${c.section}")` : ''} against the code.${where} If the code disagrees, the doc (or the code) is wrong — report the mismatch with both values.`,
+      confidence: 'requires-human',
+    };
+  });
+}

package/cli/scanners/speckit.mjs

@@ -23,7 +23,8 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync, copyFileSync, writeFileSync } from 'node:fs';
-import { resolve, join } from 'node:path';
+import { resolve, join, relative } from 'node:path';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 // ──── Spec Kit Mandatory Sections ────
 // Based on spec-kit's spec-template.md, plan-template.md, tasks-template.md
@@ -385,95 +386,164 @@ export function generateFromSpecKit(projectDir, config, flags) {
  *   - Checks constitution → AGENTS.md mapping
  *
  * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
+ *
+ * v0.29: migrated to structured findings (SPK001–SPK007). Messages are
+ * byte-identical to the legacy strings — resultFromFindings derives the
+ * errors/warnings arrays from the same findings, so counts, exit codes, and
+ * existing tests are unaffected; guard just renders richer output.
  */
 export function validateSpecKitIntegration(projectDir, config) {
-  const results = { errors: [], warnings: [], passed: 0, total: 0 };
+  const findings = [];
+  let passed = 0;
+  let total = 0;
 
   const speckit = detectSpecKit(projectDir);
 
   // If no Spec Kit detected, suggest it
   if (!speckit.detected) {
-    results.total++;
-    results.warnings.push(
-      'No Spec Kit artifacts detected. Consider `specify init` for spec-driven development (github.com/github/spec-kit)'
-    );
-    return results;
+    total++;
+    findings.push(mkFinding({
+      code: 'SPK001',
+      validator: 'specKit',
+      severity: 'warn',
+      message: 'No Spec Kit artifacts detected. Consider `specify init` for spec-driven development (github.com/github/spec-kit)',
+      location: null,
+      suggestion: { kind: 'review', text: 'Adopt spec-driven development by initializing Spec Kit', command: 'specify init' },
+    }));
+    return resultFromFindings(findings, { passed, total });
   }
 
   // ── Check 1: .specify/ directory exists ──
-  results.total++;
+  total++;
   if (speckit.specifyDir) {
-    results.passed++;
+    passed++;
   } else {
-    results.warnings.push(
-      'Spec Kit artifacts found but .specify/ directory missing. Run `specify init` to create standard structure'
-    );
+    findings.push(mkFinding({
+      code: 'SPK002',
+      validator: 'specKit',
+      severity: 'warn',
+      message: 'Spec Kit artifacts found but .specify/ directory missing. Run `specify init` to create standard structure',
+      location: '.specify',
+      suggestion: { kind: 'fix', text: 'Create the standard Spec Kit structure', command: 'specify init' },
+    }));
   }
 
   // ── Check 2: Validate each spec's quality ──
   for (const spec of speckit.specs) {
     // 2a: spec.md quality
     if (spec.hasSpec && spec.specPath) {
-      results.total++;
+      total++;
+      const loc = relative(projectDir, spec.specPath);
       try {
         const issues = validateSpecQuality(spec.specPath);
         if (issues.length === 0) {
-          results.passed++;
+          passed++;
         } else {
           for (const issue of issues) {
-            results.warnings.push(`specs/${spec.name}/spec.md: ${issue}`);
+            findings.push(mkFinding({
+              code: 'SPK003',
+              validator: 'specKit',
+              severity: 'warn',
+              message: `specs/${spec.name}/spec.md: ${issue}`,
+              location: loc,
+              suggestion: { kind: 'fix', text: 'Bring the spec up to the spec-kit spec-template.md shape (sections, FR-/SC- IDs)' },
+            }));
           }
         }
       } catch {
-        results.warnings.push(`specs/${spec.name}/spec.md: Could not read file`);
+        findings.push(mkFinding({
+          code: 'SPK006',
+          validator: 'specKit',
+          severity: 'warn',
+          message: `specs/${spec.name}/spec.md: Could not read file`,
+          location: loc,
+          suggestion: { kind: 'review', text: 'Check the file exists and is readable (permissions/encoding)' },
+        }));
       }
     }
 
     // 2b: plan.md quality
     if (spec.hasPlan && spec.planPath) {
-      results.total++;
+      total++;
+      const loc = relative(projectDir, spec.planPath);
       try {
         const issues = validatePlanQuality(spec.planPath);
         if (issues.length === 0) {
-          results.passed++;
+          passed++;
         } else {
           for (const issue of issues) {
-            results.warnings.push(`specs/${spec.name}/plan.md: ${issue}`);
+            findings.push(mkFinding({
+              code: 'SPK004',
+              validator: 'specKit',
+              severity: 'warn',
+              message: `specs/${spec.name}/plan.md: ${issue}`,
+              location: loc,
+              suggestion: { kind: 'fix', text: 'Add the missing section per spec-kit plan-template.md' },
+            }));
           }
         }
       } catch {
-        results.warnings.push(`specs/${spec.name}/plan.md: Could not read file`);
+        findings.push(mkFinding({
+          code: 'SPK006',
+          validator: 'specKit',
+          severity: 'warn',
+          message: `specs/${spec.name}/plan.md: Could not read file`,
+          location: loc,
+          suggestion: { kind: 'review', text: 'Check the file exists and is readable (permissions/encoding)' },
+        }));
       }
     }
 
     // 2c: tasks.md quality
     if (spec.hasTasks && spec.tasksPath) {
-      results.total++;
+      total++;
+      const loc = relative(projectDir, spec.tasksPath);
       try {
         const issues = validateTasksQuality(spec.tasksPath);
         if (issues.length === 0) {
-          results.passed++;
+          passed++;
         } else {
           for (const issue of issues) {
-            results.warnings.push(`specs/${spec.name}/tasks.md: ${issue}`);
+            findings.push(mkFinding({
+              code: 'SPK005',
+              validator: 'specKit',
+              severity: 'warn',
+              message: `specs/${spec.name}/tasks.md: ${issue}`,
+              location: loc,
+              suggestion: { kind: 'fix', text: 'Add a phased breakdown with T-IDs per spec-kit tasks-template.md' },
+            }));
           }
         }
       } catch {
-        results.warnings.push(`specs/${spec.name}/tasks.md: Could not read file`);
+        findings.push(mkFinding({
+          code: 'SPK006',
+          validator: 'specKit',
+          severity: 'warn',
+          message: `specs/${spec.name}/tasks.md: Could not read file`,
+          location: loc,
+          suggestion: { kind: 'review', text: 'Check the file exists and is readable (permissions/encoding)' },
+        }));
       }
     }
   }
 
   // ── Check 3: Constitution → AGENTS.md mapping ──
   if (speckit.constitution) {
-    results.total++;
+    total++;
     const agentsPath = resolve(projectDir, 'AGENTS.md');
     if (existsSync(agentsPath)) {
-      results.passed++;
+      passed++;
     } else {
-      results.warnings.push('constitution.md exists but no AGENTS.md found. Create one for AI agent rules');
+      findings.push(mkFinding({
+        code: 'SPK007',
+        validator: 'specKit',
+        severity: 'warn',
+        message: 'constitution.md exists but no AGENTS.md found. Create one for AI agent rules',
+        location: 'AGENTS.md',
+        suggestion: { kind: 'fix', text: 'Create an AGENTS.md that references the constitution', command: 'docguard init' },
+      }));
     }
   }
 
-  return results;
+  return resultFromFindings(findings, { passed, total });
 }