docguard-cli 0.29.0 → 0.30.0

package/README.md

@@ -132,6 +132,19 @@ docguard diagnose
 
 > **Note:** The Python package is a thin wrapper that delegates to `npx`. Node.js 18+ is required on the system.
 
+### More ways to integrate
+
+- **pre-commit** — changed-only guard on every commit:
+  ```yaml
+  repos:
+    - repo: https://github.com/raccioly/docguard
+      rev: v0.29.0
+      hooks: [{ id: docguard-guard }]   # docguard-guard-full for pre-push
+  ```
+- **MCP** (Claude, Cursor, any MCP client) — `claude mcp add docguard -- npx -y docguard-cli mcp`; 5 read-only tools (guard, score, explain, verify-claims, diagnose). Registry manifest ships in-repo (`server.json`, Smithery-ready).
+- **GitLab CI** — component staged at [`templates/ci/gitlab-component.yml`](templates/ci/gitlab-component.yml) (guard/score/ci job with a SARIF artifact).
+- **Homebrew** — `brew install raccioly/tap/docguard` (formula in [`packaging/homebrew/`](packaging/homebrew/)).
+
 ### Core Workflow
 
 ```bash
@@ -253,10 +266,11 @@ DocGuard ships **18 commands** (the "Daily 5" + 13 situational tools, including
 | `fix` | Generate AI fix instructions for specific docs (`--doc <name> --format prompt`) |
 | `fix --write` | Apply deterministic fixes (no AI — version bumps, counts, anchors, sections) |
 | `fix --history` | Audit log of every mechanical fix applied (from `.docguard/fixed.json`) |
-| `generate` | Reverse-engineer docs from existing codebase (`--plan` for AI scan) |
+| `generate` | Reverse-engineer docs from existing codebase (`--plan` for AI scan) — includes auto-generated Mermaid ER diagrams from your detected schemas (Prisma/Drizzle/TypeORM/Sequelize/Django/Rails) in DATA-MODEL.md |
 | `agent` | One-shot agent task graph — ordered, pre-filled code-truth, per-task verify (`--format json`) |
 | `explain <warning\|CODE>` | Paste any warning — or a finding code like `SEC001` — to get the validator's docstring, fix path, and how to suppress |
 | `verify --semantic` | Extract documented numbers/limits/enums (retention days, rate limits, GSI/role counts, status enums) as a task list for an agent to check against code — the semantic-drift class regex/AST can't see |
+| `verify --instructions` | Audit AGENTS.md/CLAUDE.md themselves for drift: duplicate rules, never-vs-always contradictions, stale file pointers, unknown commands — plus clustered rule pairs as agent judgment tasks |
 | `feedback` | Report likely false positives back to DocGuard — local-first record + a 1-click prefilled, redacted GitHub issue (zero typing) |
 | `mcp` | MCP server over stdio — exposes guard/score/explain/verify/diagnose as native tools for Claude, Cursor, and any MCP client. Setup: `claude mcp add docguard -- npx docguard-cli mcp` |
 | `memory` | Per-domain accuracy headline (endpoints / entities / env / tech) |
@@ -264,6 +278,7 @@ DocGuard ships **18 commands** (the "Daily 5" + 13 situational tools, including
 | `memory --pack` | Write `.docguard/context-pack.md` — compact, code-truth-stamped session-start context for AI agents |
 | `score --diff` | Drill into which checks pulled each category down |
 | `trace` / `trace --reverse <file>` | Requirements traceability — forward AND reverse |
+| `trace --features` | Per-feature spec-adherence scores (requirement coverage, task completion, task evidence, artifacts) — worst-first with fix hints |
 | `upgrade [--apply] [--pr]` | Check + migrate `.docguard.json` schema; `--pr` opens a PR |
 | `watch` | Live mode: re-run guard on file changes |
 

package/cli/commands/trace.mjs

@@ -7,8 +7,9 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { resolve, join, extname, basename, relative } from 'node:path';
+import { resolve, join, extname, basename, relative, dirname } from 'node:path';
 import { c } from '../shared.mjs';
+import { detectSpecKit } from '../scanners/speckit.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
@@ -134,6 +135,11 @@ export function runTrace(projectDir, config, flags) {
     return runTraceReverse(projectDir, config, flags);
   }
 
+  // Per-feature spec-kit adherence scoring when --features is set.
+  if (flags.features) {
+    return runTraceFeatures(projectDir, config, flags);
+  }
+
   // v0.16-P1: same headless-mode pattern as guard/score. Reported by Python
   // user — trace --format json was leaking ANSI escapes before the body.
   const isJson = flags.format === 'json';
@@ -366,6 +372,363 @@ function scanDir(rootDir, dir, files) {
   }
 }
 
+// ── Per-feature spec adherence (trace --features) ───────────────────────────
+//
+// Scores each detected spec-kit feature's implementation adherence
+// individually (inspired by spec-kit-retrospective), instead of only the
+// repo-wide scores that `docguard score` produces. Deterministic signals only —
+// no LLM judgment:
+//
+//   reqCoverage          40%  FR-/SC- IDs in spec.md referenced by any test file
+//   taskCompletion       25%  checked/total `- [x]` tasks in tasks.md
+//   taskEvidence         20%  checked tasks whose line names an existing file
+//   artifactCompleteness 15%  spec.md (40%) + plan.md (30%) + tasks.md (30%)
+//
+// A signal that cannot be measured (no tasks.md, no requirement IDs, no
+// checked task names a parseable path) is NEUTRAL: excluded from the weighted
+// sum and its weight redistributed across the measurable signals. This mirrors
+// the traceability validator's "no requirement IDs → silently pass" stance —
+// absence of a convention is not evidence of low adherence (missing artifacts
+// are already priced in by artifactCompleteness).
+
+const FEATURE_SIGNAL_WEIGHTS = {
+  reqCoverage: 0.40,
+  taskCompletion: 0.25,
+  taskEvidence: 0.20,
+  artifactCompleteness: 0.15,
+};
+
+// Grade bands mirrored from cli/scanners/agent-readability.mjs GRADES.
+// Display-only — never feeds the gating CDD grade that CI thresholds read.
+const FEATURE_GRADES = [[90, 'A'], [75, 'B'], [60, 'C'], [40, 'D']];
+
+function featureGrade(score) {
+  for (const [min, g] of FEATURE_GRADES) if (score >= min) return g;
+  return 'F';
+}
+
+// Spec-kit requirement IDs scored per feature. Subset of the traceability
+// validator's DEFAULT_REQ_PATTERNS (cli/validators/traceability.mjs) — the two
+// ID families spec-kit's spec-template.md mandates.
+const FEATURE_REQ_RE = /\b(?:FR|SC)-\d{2,4}\b/g;
+
+// Path-token heuristic mirrored from cli/scanners/semantic-claims.mjs
+// CITED_CODE_RE: a backticked or bare path-like token with a code extension.
+const TASK_PATH_RE = /`?([\w./-]+\.(?:ts|tsx|js|mjs|cjs|jsx|py|go|rs|java|kt|rb|php|sql|yaml|yml|json))`?/g;
+
+// 20-char bar mirrored from cli/commands/score.mjs renderBar (not exported
+// there; score.mjs is display-conventions-only for this feature).
+function featureBar(score) {
+  const filled = Math.round(score / 5);
+  const empty = 20 - filled;
+  const color = score >= 80 ? c.green : score >= 60 ? c.yellow : c.red;
+  return `${color}${'█'.repeat(filled)}${c.dim}${'░'.repeat(empty)}${c.reset}`;
+}
+
+/**
+ * Collect every FR-/SC- ID referenced anywhere in a test file, once for the
+ * whole project. Test-file discovery mirrors the traceability validator's
+ * scanTestFilesForReferences(): TEST_PATTERNS ∪ __tests__/ ∪ tests?/ dirs, and
+ * any occurrence of the ID in file content counts (not just @req lines).
+ */
+function collectTestReferencedIds(projectDir) {
+  const projectFiles = [];
+  scanDir(projectDir, projectDir, projectFiles);
+  const testFiles = projectFiles.filter(f =>
+    TEST_PATTERNS.some(p => p.test(f)) || /__tests__\//.test(f) || /tests?\//.test(f)
+  );
+
+  const ids = new Set();
+  for (const rel of testFiles) {
+    let content;
+    try { content = readFileSync(resolve(projectDir, rel), 'utf-8'); } catch { continue; }
+    FEATURE_REQ_RE.lastIndex = 0;
+    let m;
+    while ((m = FEATURE_REQ_RE.exec(content)) !== null) ids.add(m[0]);
+  }
+  return ids;
+}
+
+/**
+ * Compute the four adherence signals for one detected spec-kit feature.
+ * Each signal: { applicable, value (0..1 | null), ...n/m detail fields }.
+ */
+function computeFeatureSignals(projectDir, feature, testRefIds) {
+  // ── artifactCompleteness — always measurable ──
+  const artifactValue = (feature.hasSpec ? 0.4 : 0)
+    + (feature.hasPlan ? 0.3 : 0)
+    + (feature.hasTasks ? 0.3 : 0);
+
+  // ── taskCompletion + taskEvidence — parse tasks.md checklist lines ──
+  let totalTasks = 0, checkedTasks = 0, evidenced = 0, considered = 0;
+  if (feature.hasTasks && feature.tasksPath) {
+    let content = null;
+    try { content = readFileSync(feature.tasksPath, 'utf-8'); } catch { /* unreadable → no tasks */ }
+    if (content !== null) {
+      for (const line of content.split('\n')) {
+        const box = /^\s*[-*]\s*\[([ xX])\]/.exec(line);
+        if (!box) continue;
+        totalTasks++;
+        if (box[1] === ' ') continue;
+        checkedTasks++;
+        // Evidence: any named path on the line that exists in the project.
+        // Checked tasks with no parseable path are neutral (skip denominator).
+        TASK_PATH_RE.lastIndex = 0;
+        let tok, sawToken = false, exists = false;
+        while ((tok = TASK_PATH_RE.exec(line)) !== null) {
+          sawToken = true;
+          if (existsSync(resolve(projectDir, tok[1].replace(/^\.\//, '')))) { exists = true; break; }
+        }
+        if (sawToken) { considered++; if (exists) evidenced++; }
+      }
+    }
+  }
+
+  // ── reqCoverage — spec.md IDs that appear in ANY test file ──
+  const specIds = [];
+  if (feature.hasSpec && feature.specPath) {
+    try {
+      const spec = readFileSync(feature.specPath, 'utf-8');
+      const seen = new Set();
+      FEATURE_REQ_RE.lastIndex = 0;
+      let m;
+      while ((m = FEATURE_REQ_RE.exec(spec)) !== null) {
+        if (!seen.has(m[0])) { seen.add(m[0]); specIds.push(m[0]); }
+      }
+    } catch { /* unreadable spec → no IDs */ }
+  }
+  const covered = specIds.filter(id => testRefIds.has(id));
+  const uncovered = specIds.filter(id => !testRefIds.has(id));
+
+  return {
+    reqCoverage: {
+      applicable: specIds.length > 0,
+      value: specIds.length > 0 ? covered.length / specIds.length : null,
+      covered: covered.length,
+      total: specIds.length,
+      uncovered,
+    },
+    taskCompletion: {
+      applicable: totalTasks > 0,
+      value: totalTasks > 0 ? checkedTasks / totalTasks : null,
+      checked: checkedTasks,
+      total: totalTasks,
+    },
+    taskEvidence: {
+      applicable: considered > 0,
+      value: considered > 0 ? evidenced / considered : null,
+      evidenced,
+      considered,
+    },
+    artifactCompleteness: {
+      applicable: true,
+      value: artifactValue,
+      spec: feature.hasSpec,
+      plan: feature.hasPlan,
+      tasks: feature.hasTasks,
+    },
+  };
+}
+
+/** Weighted 0–100 score over the applicable signals (weights renormalized). */
+function scoreFromSignals(signals) {
+  let weighted = 0, weightTotal = 0;
+  for (const [key, weight] of Object.entries(FEATURE_SIGNAL_WEIGHTS)) {
+    const s = signals[key];
+    if (!s.applicable) continue;
+    weighted += weight * s.value;
+    weightTotal += weight;
+  }
+  return weightTotal > 0 ? Math.round((weighted / weightTotal) * 100) : 0;
+}
+
+/**
+ * The lowest-valued applicable signal. Iteration order is descending weight,
+ * and replacement is strict-less-than, so ties resolve to the highest-impact
+ * signal — the one worth fixing first.
+ */
+function weakestSignal(signals) {
+  let worstKey = null;
+  for (const key of Object.keys(FEATURE_SIGNAL_WEIGHTS)) {
+    const s = signals[key];
+    if (!s.applicable) continue;
+    if (worstKey === null || s.value < signals[worstKey].value) worstKey = key;
+  }
+  return worstKey;
+}
+
+function fixHintFor(key, s, feature) {
+  switch (key) {
+    case 'reqCoverage':
+      return `Cover the untested spec IDs (e.g. ${s.uncovered[0]}) — reference them from tests via @req annotations`;
+    case 'taskCompletion':
+      return `Complete (or prune) the ${s.total - s.checked} unchecked task(s) in tasks.md`;
+    case 'taskEvidence':
+      return `${s.considered - s.evidenced} checked task(s) name files that don't exist — fix stale paths or uncheck them`;
+    case 'artifactCompleteness': {
+      const missing = [
+        feature.hasSpec ? null : 'spec.md',
+        feature.hasPlan ? null : 'plan.md',
+        feature.hasTasks ? null : 'tasks.md',
+      ].filter(Boolean);
+      return `Add ${missing.join(', ')} to complete the artifact set`;
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * `docguard trace --features` — per-feature spec-kit adherence report.
+ * Reuses detectSpecKit() for feature discovery (no re-implementation).
+ */
+export function runTraceFeatures(projectDir, config, flags) {
+  const isJson = flags.format === 'json';
+  if (!isJson) {
+    console.log(`${c.bold}🎯 DocGuard Trace (features) — ${config.projectName}${c.reset}`);
+    console.log(`${c.dim}   Scoring per-feature spec adherence (spec-kit)...${c.reset}\n`);
+  }
+
+  const speckit = detectSpecKit(projectDir);
+  if (!speckit.detected || speckit.specs.length === 0) {
+    // Same empty-state contract as trace --reverse: JSON stays parseable with
+    // an `error` field; text gets an actionable pointer.
+    if (isJson) {
+      console.log(JSON.stringify({
+        features: [],
+        summary: { features: 0, avgScore: null, worst: null },
+        error: 'no spec-kit features detected',
+        timestamp: new Date().toISOString(),
+      }, null, 2));
+    } else {
+      console.log(`  ${c.yellow}No spec-kit features detected.${c.reset}`);
+      console.log(`  ${c.dim}Feature scoring needs .specify/specs/** or specs/** (spec.md/plan.md/tasks.md). Run \`specify init\` to start.${c.reset}`);
+    }
+    return;
+  }
+
+  const testRefIds = collectTestReferencedIds(projectDir);
+
+  const features = speckit.specs.map(f => {
+    const signals = computeFeatureSignals(projectDir, f, testRefIds);
+    const score = scoreFromSignals(signals);
+    const weakest = weakestSignal(signals);
+    const needsFix = weakest !== null && signals[weakest].value < 1;
+    return {
+      name: f.name,
+      dir: relative(projectDir, dirname(f.specPath || f.planPath || f.tasksPath)),
+      score,
+      grade: featureGrade(score),
+      signals,
+      weakest,
+      fixHint: needsFix ? fixHintFor(weakest, signals[weakest], f) : null,
+    };
+  });
+
+  // Worst-first — act on the weakest feature. Name tie-break for determinism.
+  features.sort((a, b) => a.score - b.score || a.name.localeCompare(b.name));
+
+  const avgScore = Math.round(features.reduce((sum, f) => sum + f.score, 0) / features.length);
+  const summary = {
+    features: features.length,
+    avgScore,
+    worst: { name: features[0].name, score: features[0].score },
+  };
+
+  if (isJson) {
+    outputFeaturesJSON(features, summary);
+  } else {
+    outputFeaturesText(features, summary);
+  }
+}
+
+function pctOrNull(signal) {
+  return signal.applicable ? Math.round(signal.value * 100) : null;
+}
+
+function outputFeaturesJSON(features, summary) {
+  console.log(JSON.stringify({
+    features: features.map(f => ({
+      name: f.name,
+      dir: f.dir,
+      score: f.score,
+      grade: f.grade,
+      signals: {
+        reqCoverage: {
+          pct: pctOrNull(f.signals.reqCoverage),
+          covered: f.signals.reqCoverage.covered,
+          total: f.signals.reqCoverage.total,
+          uncovered: f.signals.reqCoverage.uncovered,
+        },
+        taskCompletion: {
+          pct: pctOrNull(f.signals.taskCompletion),
+          checked: f.signals.taskCompletion.checked,
+          total: f.signals.taskCompletion.total,
+        },
+        taskEvidence: {
+          pct: pctOrNull(f.signals.taskEvidence),
+          evidenced: f.signals.taskEvidence.evidenced,
+          considered: f.signals.taskEvidence.considered,
+        },
+        artifactCompleteness: {
+          pct: pctOrNull(f.signals.artifactCompleteness),
+          spec: f.signals.artifactCompleteness.spec,
+          plan: f.signals.artifactCompleteness.plan,
+          tasks: f.signals.artifactCompleteness.tasks,
+        },
+      },
+      weakest: f.weakest,
+      fixHint: f.fixHint,
+    })),
+    summary,
+    timestamp: new Date().toISOString(),
+  }, null, 2));
+}
+
+function outputFeaturesText(features, summary) {
+  console.log(`  ${c.bold}Feature Adherence${c.reset} ${c.dim}(worst first)${c.reset}\n`);
+
+  for (const f of features) {
+    const gradeColor = f.score >= 80 ? c.green : f.score >= 60 ? c.yellow : c.red;
+    console.log(`  📦 ${c.bold}${f.name}${c.reset} — ${gradeColor}${f.score}/100 (${f.grade})${c.reset} ${featureBar(f.score)}`);
+    console.log(`     ${c.dim}${f.dir}${c.reset}`);
+
+    const sig = f.signals;
+    const line = (label, weightPct, s, detail) => {
+      const pct = s.applicable ? `${Math.round(s.value * 100)}%`.padEnd(4) : 'n/a ';
+      const color = !s.applicable ? c.dim : s.value >= 0.8 ? c.green : s.value >= 0.5 ? c.yellow : c.red;
+      console.log(`     ${color}${pct}${c.reset} ${label.padEnd(22)} ${c.dim}${detail} · weight ${weightPct}%${c.reset}`);
+    };
+
+    line('Requirement coverage', 40, sig.reqCoverage,
+      sig.reqCoverage.applicable
+        ? `${sig.reqCoverage.covered}/${sig.reqCoverage.total} spec IDs referenced by tests`
+        : 'no FR-/SC- IDs in spec.md');
+    line('Task completion', 25, sig.taskCompletion,
+      sig.taskCompletion.applicable
+        ? `${sig.taskCompletion.checked}/${sig.taskCompletion.total} tasks checked`
+        : 'no tasks.md checklist');
+    line('Task evidence', 20, sig.taskEvidence,
+      sig.taskEvidence.applicable
+        ? `${sig.taskEvidence.evidenced}/${sig.taskEvidence.considered} checked tasks name existing files`
+        : 'no checked task names a file path');
+    line('Artifacts', 15, sig.artifactCompleteness,
+      `${[sig.artifactCompleteness.spec, sig.artifactCompleteness.plan, sig.artifactCompleteness.tasks].filter(Boolean).length}/3 ` +
+      `(spec ${sig.artifactCompleteness.spec ? '✓' : '✗'} · plan ${sig.artifactCompleteness.plan ? '✓' : '✗'} · tasks ${sig.artifactCompleteness.tasks ? '✓' : '✗'})`);
+
+    if (f.fixHint) {
+      console.log(`     ${c.yellow}⚠ Fix first:${c.reset} ${f.fixHint}`);
+    } else {
+      console.log(`     ${c.green}✓ No weak signal — all applicable signals at 100%${c.reset}`);
+    }
+    console.log('');
+  }
+
+  console.log(`  ${c.bold}─────────────────────────────────────${c.reset}`);
+  console.log(`  ${summary.features} feature(s) · avg ${summary.avgScore}/100 · worst: ${c.red}${summary.worst.name} (${summary.worst.score}/100)${c.reset}`);
+  console.log(`\n  ${c.dim}Signals are deterministic (checklist, ID-to-test references, file existence) — adherence of intent, not correctness.${c.reset}\n`);
+}
+
 function findRelatedTests(projectFiles, sourcePatterns) {
   // Find test files that might cover the source patterns
   const testFiles = projectFiles.filter(f => TEST_PATTERNS.some(p => p.test(f)));

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',