docguard-cli 0.30.0 → 0.31.0

package/README.md

@@ -13,6 +13,8 @@
 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org)
 [![Runtime deps](https://img.shields.io/badge/runtime_deps-1_(pinned)-green)](package.json)
 [![Spec Kit Extension](https://img.shields.io/badge/Spec_Kit-Extension-blueviolet)](https://github.com/github/spec-kit)
+[![Glama](https://glama.ai/mcp/servers/raccioly/docguard/badges/score.svg)](https://glama.ai/mcp/servers/raccioly/docguard)
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-0a7ea4)](https://registry.modelcontextprotocol.io/)
 
 ---
 
@@ -74,7 +76,7 @@ graph TD
     Commands --> setup["setup wizard"]
     Commands --> other["diff · init · fix · trace · impact · sync<br/>explain · memory · upgrade · agents · hooks · badge · ci · watch"]
 
-    guard --> Validators["Validators (24)"]
+    guard --> Validators["Validators (27)"]
     generate --> Scanners["Scanners (4)<br/>routes · schemas · doc-tools · speckit"]
     score --> Scoring["Weighted Scoring<br/>8 categories"]
     diagnose --> Validators
@@ -252,7 +254,7 @@ DocGuard ships **18 commands** (the "Daily 5" + 13 situational tools, including
 | Command | What It Does |
 |:--------|:-------------|
 | `init`  | Bootstrap a project (`--wizard` for interactive · `--with <name>` for scaffolders) |
-| `guard` | Validate against canonical docs — 24 validators |
+| `guard` | Validate against canonical docs — 27 validators |
 | `diff`  | Show gaps between docs and code (`--since <ref>` for impact mode) |
 | `sync`  | Refresh code-truth doc sections — keeps memory always up to date |
 | `score` | CDD maturity score (0-100; `--diff` for delta between refs) |
@@ -358,7 +360,7 @@ $ npx docguard-cli generate
 
 ## 🔍 Validators
 
-DocGuard runs **24 automated validators** on every `guard` check. Every one is **language-aware** as of v0.16 — patterns for Python (`test_*.py`), Rust (`tests/*.rs`), Go (`*_test.go`), Java (`*Test.java`), Ruby (`*_spec.rb`), PHP, and JS/TS all match.
+DocGuard runs **27 automated validators** on every `guard` check. Every one is **language-aware** as of v0.16 — patterns for Python (`test_*.py`), Rust (`tests/*.rs`), Go (`*_test.go`), Java (`*Test.java`), Ruby (`*_spec.rb`), PHP, and JS/TS all match.
 
 | # | Validator | What It Checks | Default |
 |:--|:----------|:--------------|:--------|
@@ -385,7 +387,10 @@ DocGuard runs **24 automated validators** on every `guard` check. Every one is *
 | 21 | **Generated-Staleness** | `source=code` sections match scanner output; `status: draft` doc age | ✅ On |
 | 22 | **Canonical-Sync** | DocGuard's own README count claims match code-truth (DocGuard repo only — N/A elsewhere) | ✅ On |
 | 23 | **Metrics-Consistency** | Hardcoded numbers match actual counts | ✅ On |
-| 24 | **Surface-Sync** | Item-level enumerable drift — names in doc tables/lists (commands, validators, etc.) match code-truth (opt-in via `surfaceSync.surfaces`; N/A unless configured) | ✅ On |
+| 24 | **Surface-Sync** | Item-level enumerable drift — names in doc tables/lists (commands, checks, etc.) match code-truth (opt-in via `surfaceSync.surfaces`; N/A unless configured) | ✅ On |
+| 25 | **Diff-Suspicion** | Change-driven: a doc/agent-instruction file that references code changed since the ref AND shares removed domain symbols is flagged for review (arXiv 2010.01625, F1 74.7) | ✅ On |
+| 26 | **Reference-Existence** | Two-revision check: a backticked code symbol present when the doc was last updated but gone at HEAD is flagged as outdated (arXiv 2212.01479) | ✅ On |
+| 27 | **API-Doc-Smells** | Bloated (≥300 words) / Lazy (≤6 prose words) API documentation units, keyed on signature-headed sections (F1 0.90/0.95) | ✅ On |
 
 **Per-validator controls** (in `.docguard.json`):
 ```json
@@ -454,7 +459,7 @@ DocGuard provides AI agent slash commands for integrated workflows. Installed au
 | Command | What It Does |
 |:--------|:-------------|
 | `/docguard.init` | Initialize Canonical-Driven Development in a new or existing project |
-| `/docguard.guard` | Run quality validation — check all 24 validators |
+| `/docguard.guard` | Run quality validation — check all 27 validators |
 | `/docguard.review` | Analyze doc quality and suggest improvements |
 | `/docguard.fix` | Generate targeted fix prompts for specific issues |
 | `/docguard.update` | Update canonical docs after code changes — detect drift and sync documentation |
@@ -613,7 +618,7 @@ Two ready-to-use templates ship with the Spec Kit extension and as standalone fi
 Recent highlights across the v0.16 → v0.19 line:
 
 - **`docguard explain <validator>`** — `docguard explain freshness` prints purpose, rules, common
-  failures, and fix recipes for any of the 24 validators. No need to dig into source.
+  failures, and fix recipes for any of the 27 validators. No need to dig into source.
 - **`docguard memory --diff`** — surface what changed in your canonical docs between two refs
   (`HEAD~10..HEAD` by default). Great for code review and changelog drafting.
 - **`docguard score --diff`** — see exactly which validators moved the score up or down between

package/cli/commands/explain.mjs

@@ -178,6 +178,37 @@ const EXPLAINERS = {
     example: '`cli/commands/demo.mjs` exists and `| `demo` | Zero-install preview |` appears in README.md\'s commands table',
     standard: 'CDD principle: documented surfaces match implemented surfaces',
   },
+  diffSuspicion: {
+    title: 'Diff-Suspicion — docs describing code that just changed (DSP001)',
+    what: 'Change-driven. For each code file changed since the ref (`config.changedSinceRef`, else HEAD~1), flags a canonical doc or agent-instruction file that BOTH references the file (path/`module`) AND shares domain tokens that were removed/replaced in the diff. Deterministic diff-overlap rule (arXiv 2010.01625, F1 74.7); confidence:low.',
+    why:  'A doc that talks about a symbol the code just deleted is the highest-signal, lowest-cost drift class — and it is exactly what whole-repo scans miss but a diff makes obvious.',
+    triggers: [
+      ['describes X, which just had … removed/changed', 'Re-read the doc against the current file; the removed symbols may now be wrong. Suppress the pairing if it is a false positive.'],
+    ],
+    example: 'AUTH.md references `src/auth.ts` and `validateToken` was renamed away in the last commit',
+    standard: 'Just-in-time comment-code inconsistency detection (AAAI 2021)',
+  },
+  referenceExistence: {
+    title: 'Reference-Existence — doc names a code symbol that no longer exists (REF001)',
+    what: 'Two-revision check. A compound code identifier backticked in a doc that existed in the source when the doc was last updated but has ZERO whole-word matches at HEAD is flagged as outdated. Deterministic (arXiv 2212.01479); confidence:low.',
+    why:  'References go stale silently for years; the two-revision gate distinguishes "renamed away" from "never existed", keeping false positives near zero.',
+    triggers: [
+      ['references `X`, which existed … but has ZERO matches at HEAD', 'Update or remove the reference. Suppress with `<!-- docguard:ignore REF001 -->` if it is a still-relevant user-facing name.'],
+    ],
+    example: 'API-REFERENCE.md backticks `getUserById` which was deleted three commits ago',
+    standard: 'Outdated code-element reference detection (EMSE 2022)',
+  },
+  apiDocSmells: {
+    title: 'API-Doc-Smells — Bloated / Lazy API documentation (APS001/APS002)',
+    what: 'Length signals on doc units whose heading is a code signature (HTTP endpoint / function / backticked symbol). Lazy = ≤6 prose words (documented in name only); Bloated = ≥300 words for one unit. Deterministic (F1 0.90/0.95); confidence:low. OFF by default — enable with `validators.apiDocSmells: true`.',
+    why:  'An endpoint documented in name only, or buried in 400 words, both fail the reader — and both are detectable without understanding the prose.',
+    triggers: [
+      ['documented in name only', 'Describe what it does, its params, return, and errors — not just the signature.'],
+      ['is N words for one unit — Bloated', 'Trim to the essential contract; move examples/edge-cases elsewhere.'],
+    ],
+    example: '`#### GET /api/health` with an empty body → Lazy',
+    standard: 'API documentation smell taxonomy',
+  },
   crossReference: {
     title: 'Cross-Reference — internal markdown links resolve',
     what: 'Scans canonical docs for `[text](./OTHER.md#anchor)` and `#anchor` links. Verifies the target file exists and the anchor matches a heading.',
@@ -351,6 +382,9 @@ const DISPLAY_NAMES = {
   surfaceSync: 'Surface-Sync',
   canonicalSync: 'Canonical-Sync',
   metricsConsistency: 'Metrics-Consistency',
+  diffSuspicion: 'Diff-Suspicion',
+  referenceExistence: 'Reference-Existence',
+  apiDocSmells: 'API-Doc-Smells',
 };
 
 /** Collapse a key / display name to a comparable form: lowercase, alnum only. */

package/cli/commands/guard.mjs

@@ -147,6 +147,10 @@ import { validateSchemaSync } from '../validators/schema-sync.mjs';
 import { validateSpecKitIntegration } from '../validators/spec-kit.mjs';
 import { validateCanonicalSync } from '../validators/canonical-sync.mjs';
 import { validateSurfaceSync } from '../validators/surface-sync.mjs';
+// v0.31.0 change-driven + smell detectors
+import { validateDiffSuspicion } from '../validators/diff-suspicion.mjs';
+import { validateReferenceExistence } from '../validators/reference-existence.mjs';
+import { validateApiDocSmells } from '../validators/api-doc-smells.mjs';
 
 /**
  * Internal guard — returns structured data, no console output, no process.exit.
@@ -313,6 +317,10 @@ export function runGuardInternal(projectDir, config) {
     { key: 'crossReference', name: 'Cross-Reference', fn: () => validateCrossReferences(projectDir, config) },
     { key: 'generatedStaleness', name: 'Generated-Staleness', fn: () => validateGeneratedStaleness(projectDir, config) },
     { key: 'surfaceSync', name: 'Surface-Sync', fn: () => validateSurfaceSync(projectDir, config) },
+    // v0.31.0 — change-driven + smell detectors (all confidence:low / soft).
+    { key: 'diffSuspicion', name: 'Diff-Suspicion', fn: () => validateDiffSuspicion(projectDir, config) },
+    { key: 'referenceExistence', name: 'Reference-Existence', fn: () => validateReferenceExistence(projectDir, config) },
+    { key: 'apiDocSmells', name: 'API-Doc-Smells', fn: () => validateApiDocSmells(projectDir, config) },
     // Metrics-Consistency runs post-loop (needs guard results)
   ];
 

package/cli/commands/impact.mjs

@@ -15,10 +15,21 @@
  * JSON mode emits a structured `{ changedFiles, affectedDocs }` payload
  * for CI integrations and PR-comment bots.
  *
+ * v0.31.0 — blast radius (feat 1):
+ *   - Agent-instruction files (AGENTS.md/CLAUDE.md/GEMINI.md) are indexed
+ *     alongside canonical docs, so a changed code file they reference is
+ *     surfaced too (agent instructions drift when the code they describe moves).
+ *   - Doc→doc graph: when a DOC changes, the docs that reference it — INCLUDING
+ *     agent-instruction files — are flagged as suspect ("blast radius"). This is
+ *     the unclaimed slice: a change in ARCHITECTURE.md marks the AGENTS.md that
+ *     points at it for review.
+ *
  * @req SC-S11-001 — impact reports per-file → doc mappings
  * @req SC-S11-002 — files with no doc references are listed as "no impact"
  * @req SC-S11-003 — --format json emits parseable structured output
  * @req SC-S11-004 — non-code files (.md, .json, etc.) are skipped from impact analysis
+ * @req SC-S11-007 — agent-instruction files participate in impact analysis
+ * @req SC-S11-008 — a changed doc flags the docs that reference it (blast radius)
  */
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
@@ -33,10 +44,28 @@ import { changedFilesSince, isGitRepo } from '../shared-git.mjs';
  */
 const CODE_EXTENSIONS = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|swift)$/;
 
+// Root agent-instruction files — documentation that names code and other docs.
+const AGENT_FILES = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'];
+
 function escapeRegex(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+/**
+ * Doc→doc references: which indexed docs reference `changedDocPath` (by its
+ * basename — the form used in prose "see ARCHITECTURE.md" and markdown links
+ * `](ARCHITECTURE.md)`). Skips self. This is the blast-radius edge set.
+ */
+function docsReferencing(changedDocPath, index) {
+  const cbase = basename(changedDocPath);
+  const dependents = [];
+  for (const [docName, lines] of index) {
+    if (docName === cbase || docName === changedDocPath) continue; // not self
+    if (lines.some(l => l.includes(cbase))) dependents.push(docName);
+  }
+  return dependents;
+}
+
 /**
  * Find canonical doc references for a single file. Reuses the same three
  * match strategies as trace --reverse for consistency: direct path,
@@ -81,9 +110,11 @@ export function runImpact(projectDir, _config, flags) {
   // impact" in the same sense; they ARE the docs (or config).
   const codeChanged = changed.filter(f => CODE_EXTENSIONS.test(f));
 
-  // Index canonical docs once
+  // Index canonical docs once, PLUS root agent-instruction files (they name
+  // code and other docs, so they belong in both code→doc and doc→doc analysis).
   const docsDir = resolve(projectDir, 'docs-canonical');
   const docsIndex = new Map(); // docName → lines[]
+  const agentDocs = new Set(); // which indexed docs are agent-instruction files
   if (existsSync(docsDir)) {
     try {
       for (const f of readdirSync(docsDir)) {
@@ -95,6 +126,11 @@ export function runImpact(projectDir, _config, flags) {
       }
     } catch { /* skip if dir unreadable */ }
   }
+  for (const a of AGENT_FILES) {
+    const p = resolve(projectDir, a);
+    if (!existsSync(p)) continue;
+    try { docsIndex.set(a, readFileSync(p, 'utf-8').split('\n')); agentDocs.add(a); } catch { /* skip */ }
+  }
 
   // Compute per-file references
   const fileImpact = []; // { file, references: [{doc, line, kind}] }
@@ -113,15 +149,38 @@ export function runImpact(projectDir, _config, flags) {
   const affectedDocs = Array.from(docMap.entries()).map(([doc, files]) => ({
     doc,
     files: Array.from(files),
+    isAgentFile: agentDocs.has(doc),
   }));
 
+  // ── Doc→doc blast radius: a changed DOC flags the docs that reference it ──
+  // (including agent-instruction files that point at it). Only meaningful edges
+  // are emitted (changed doc with ≥1 dependent).
+  //
+  // A source must be an INDEXED canonical/agent doc — not any changed `.md`.
+  // Otherwise a CHANGELOG.md / README.md / .wolf/*.md change flags every doc
+  // that merely mentions it in passing (dogfooding false positives).
+  const indexBasenames = new Set(docsIndex.keys());
+  const changedDocs = changed.filter(f => f.endsWith('.md') && indexBasenames.has(basename(f)));
+  const blastRadius = [];
+  for (const cd of changedDocs) {
+    const dependents = docsReferencing(cd, docsIndex);
+    if (dependents.length > 0) {
+      blastRadius.push({
+        changedDoc: cd,
+        dependents: dependents.map(d => ({ doc: d, isAgentFile: agentDocs.has(d) })),
+      });
+    }
+  }
+
   // ── JSON output ──
   if (isJson) {
     console.log(JSON.stringify({
       since,
       changedFiles: codeChanged,
-      ignoredFiles: changed.filter(f => !CODE_EXTENSIONS.test(f)),
+      changedDocs,
+      ignoredFiles: changed.filter(f => !CODE_EXTENSIONS.test(f) && !f.endsWith('.md')),
       affectedDocs,
+      blastRadius,
       timestamp: new Date().toISOString(),
     }, null, 2));
     return;
@@ -134,8 +193,28 @@ export function runImpact(projectDir, _config, flags) {
     console.log(`  ${c.green}✅ No file changes since ${since}.${c.reset}`);
     return;
   }
+
+  // Doc→doc blast radius — shown whether or not code changed (a doc-only change
+  // can still ripple to the docs / agent files that reference it).
+  const printBlast = () => {
+    if (blastRadius.length === 0) return;
+    console.log(`\n  ${c.bold}🌐 Doc blast radius${c.reset} ${c.dim}(${changedDocs.length} doc(s) changed)${c.reset}`);
+    for (const { changedDoc, dependents } of blastRadius) {
+      console.log(`  ${c.cyan}${changedDoc}${c.reset} ${c.dim}changed → review ${dependents.length} dependent doc(s):${c.reset}`);
+      for (const dep of dependents.slice(0, 8)) {
+        const tag = dep.isAgentFile ? ` ${c.yellow}[agent-instruction]${c.reset}` : '';
+        console.log(`     ${c.dim}↳${c.reset} ${dep.doc}${tag}`);
+      }
+      if (dependents.length > 8) console.log(`     ${c.dim}... ${dependents.length - 8} more${c.reset}`);
+    }
+  };
+
   if (codeChanged.length === 0) {
-    console.log(`  ${c.dim}No code files changed (${changed.length} non-code files: ${changed.slice(0, 3).join(', ')}${changed.length > 3 ? '…' : ''}).${c.reset}`);
+    console.log(`  ${c.dim}No code files changed (${changedDocs.length} doc(s) + ${changed.length - changedDocs.length} other non-code file(s)).${c.reset}`);
+    if (blastRadius.length === 0 && changedDocs.length > 0) {
+      console.log(`  ${c.green}✅ No other docs reference the changed doc(s).${c.reset}`);
+    }
+    printBlast();
     return;
   }
 
@@ -146,16 +225,16 @@ export function runImpact(projectDir, _config, flags) {
     console.log(`  ${c.dim}This often means the changed code is undocumented. Consider:${c.reset}`);
     console.log(`  ${c.dim}  - Running ${c.cyan}docguard generate --plan${c.dim} to add doc skeletons${c.reset}`);
     console.log(`  ${c.dim}  - Reviewing whether the change belongs in an existing doc${c.reset}`);
-    return;
-  }
-
-  console.log(`  ${c.green}${affectedDocs.length}${c.reset} canonical doc(s) reference the changed files:\n`);
-  for (const { doc, files } of affectedDocs) {
-    console.log(`  ${c.cyan}${doc}${c.reset} ${c.dim}(${files.length} file${files.length > 1 ? 's' : ''})${c.reset}`);
-    for (const f of files.slice(0, 5)) {
-      console.log(`     ${c.dim}via${c.reset} ${f}`);
+  } else {
+    console.log(`  ${c.green}${affectedDocs.length}${c.reset} canonical doc(s) reference the changed files:\n`);
+    for (const { doc, files, isAgentFile } of affectedDocs) {
+      const tag = isAgentFile ? ` ${c.yellow}[agent-instruction]${c.reset}` : '';
+      console.log(`  ${c.cyan}${doc}${c.reset}${tag} ${c.dim}(${files.length} file${files.length > 1 ? 's' : ''})${c.reset}`);
+      for (const f of files.slice(0, 5)) {
+        console.log(`     ${c.dim}via${c.reset} ${f}`);
+      }
+      if (files.length > 5) console.log(`     ${c.dim}... ${files.length - 5} more${c.reset}`);
     }
-    if (files.length > 5) console.log(`     ${c.dim}... ${files.length - 5} more${c.reset}`);
   }
 
   // List code files with NO doc references — these may need new docs
@@ -166,4 +245,6 @@ export function runImpact(projectDir, _config, flags) {
     if (orphaned.length > 5) console.log(`     ${c.dim}... ${orphaned.length - 5} more${c.reset}`);
     console.log(`  ${c.dim}These may be undocumented — review whether they belong in an existing doc.${c.reset}`);
   }
+
+  printBlast();
 }

package/cli/commands/mcp.mjs

@@ -53,25 +53,40 @@ const PROJECT_DIR_PROP = {
   },
 };
 
+// Every DocGuard MCP tool is READ-ONLY: it inspects local project files and
+// never writes, mutates, or reaches the network. These MCP tool hints let
+// clients (and directory scanners like Glama) surface that safety to users.
+const READONLY_ANNOTATIONS = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+};
+
 const TOOLS = [
   {
     name: 'docguard_guard',
+    title: 'Guard docs against code',
     description: 'Run every enabled DocGuard validator against the project\'s canonical docs. Returns the full guard JSON contract: status (PASS/WARN/FAIL), structured findings with stable codes and suggestions, nextStep, doc coverage map, semantic-claim count, and per-validator results.',
     inputSchema: {
       type: 'object',
       properties: { ...PROJECT_DIR_PROP },
     },
+    annotations: READONLY_ANNOTATIONS,
   },
   {
     name: 'docguard_score',
+    title: 'CDD maturity score',
     description: 'Compute the project\'s CDD maturity score (0-100) with letter grade and per-category breakdown.',
     inputSchema: {
       type: 'object',
       properties: { ...PROJECT_DIR_PROP },
     },
+    annotations: READONLY_ANNOTATIONS,
   },
   {
     name: 'docguard_explain',
+    title: 'Explain a finding code',
     description: 'Explain a stable DocGuard finding code (e.g. STR001, ENV003): what it means, which validator emits it, and the inline suppression to use if it\'s a confirmed false positive.',
     inputSchema: {
       type: 'object',
@@ -83,22 +98,27 @@ const TOOLS = [
       },
       required: ['code'],
     },
+    annotations: READONLY_ANNOTATIONS,
   },
   {
     name: 'docguard_verify_claims',
+    title: 'Extract claims to verify',
     description: 'Extract the semantic claims in the project\'s canonical docs — documented numbers, limits, and enums — as a verification task list. Deterministic discovery, LLM judgment — the caller verifies each claim against the code.',
     inputSchema: {
       type: 'object',
       properties: { ...PROJECT_DIR_PROP },
     },
+    annotations: READONLY_ANNOTATIONS,
   },
   {
     name: 'docguard_diagnose',
+    title: 'Diagnose what to fix',
     description: 'Run guard and return only what needs fixing: failing/warning validators with their messages, structured findings, and suggested next actions — shaped for an agent to act on.',
     inputSchema: {
       type: 'object',
       properties: { ...PROJECT_DIR_PROP },
     },
+    annotations: READONLY_ANNOTATIONS,
   },
 ];
 

package/cli/commands/score.mjs

@@ -5,7 +5,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import { c, docHasSection } from '../shared.mjs';
 import { validateSecurity } from '../validators/security.mjs';
 import { runGuardInternal } from './guard.mjs';
@@ -1039,11 +1039,16 @@ function estimateDocTax(projectDir, config, scores) {
   // Estimate code churn (commits in last 30 days)
   let recentCommits = 0;
   try {
-    const output = execSync('git log --oneline --since="30 days ago" 2>/dev/null | wc -l', {
+    // execFileSync (argv array) + count in JS — avoids the shell `| wc -l` pipe,
+    // which isn't portable to Windows (no `wc`) and needs a shell at all. Same
+    // pattern freshness.mjs already uses for commit counting.
+    const output = execFileSync('git', ['log', '--oneline', '--since=30 days ago'], {
       cwd: projectDir,
       encoding: 'utf-8',
-    }).trim();
-    recentCommits = parseInt(output, 10) || 0;
+      stdio: ['pipe', 'pipe', 'ignore'],
+      maxBuffer: 1024 * 1024 * 5,
+    });
+    recentCommits = output.trim() ? output.trim().split('\n').length : 0;
   } catch {
     recentCommits = 10; // Default assumption
   }

package/cli/commands/setup.mjs

@@ -21,7 +21,6 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from
 import { resolve, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
-import { execSync } from 'node:child_process';
 import { c, CURRENT_SCHEMA_VERSION } from '../shared.mjs';
 import { ensureSkills, detectAgentMode, isSpecKitInitialized, getDetectedAgent } from '../ensure-skills.mjs';
 
@@ -70,18 +69,6 @@ function detectProjectType(dir) {
   return 'unknown';
 }
 
-// ── CLI Detection ───────────────────────────────────────────────────────
-
-function isCliAvailable(name) {
-  try {
-    const cmd = process.platform === 'win32' ? `where ${name}` : `which ${name}`;
-    execSync(`${cmd} 2>/dev/null`, { encoding: 'utf-8', timeout: 3000 });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 function detectAgentDirs(projectDir) {
   const agentDirs = [
     { name: 'GitHub Copilot', dir: '.github', commandsPath: '.github/commands' },

package/cli/commands/verify.mjs

@@ -22,10 +22,50 @@
  *   docguard verify [--semantic | --instructions] [--format json]
  */
 
+import { basename } from 'node:path';
 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';
+import { isGitRepo, getDiffText } from '../shared-git.mjs';
+import { parseUnifiedDiff, activityLabeledDiff } from '../shared-diff.mjs';
+
+const CHANGE_CODE_EXT = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|swift|scala|dart)$/;
+
+/**
+ * Structured change context for staged agent tasks (feat 6). When `--since` is
+ * given, decompose the code diff into activity-labeled spans (ordered
+ * replace/delete/add) — the CARL-CCI representation shown to beat raw-text
+ * diffs (arXiv 2512.19883). The agent judging a claim then sees WHAT changed,
+ * not just the claim. Returns null when there's no ref / git / diff.
+ *
+ * Bounded: caps files and per-activity lines so the JSON stays agent-sized.
+ */
+function buildChangeContext(projectDir, since, { maxFiles = 40, maxLines = 6 } = {}) {
+  if (!since || !isGitRepo(projectDir)) return null;
+  const files = parseUnifiedDiff(getDiffText(projectDir, since))
+    .filter(f => f.newPath && CHANGE_CODE_EXT.test(f.newPath) && f.status !== 'deleted');
+  if (files.length === 0) return null;
+  const clip = (arr) => arr.slice(0, maxLines).map(s => s.length > 200 ? s.slice(0, 200) + '…' : s);
+  const activities = files.slice(0, maxFiles).map(f => ({
+    file: f.newPath,
+    activities: activityLabeledDiff(f).map(a => ({
+      type: a.type,
+      ...(a.del ? { del: clip(a.del) } : {}),
+      ...(a.add ? { add: clip(a.add) } : {}),
+    })),
+  }));
+  return { since, changedFiles: files.map(f => f.newPath), activities };
+}
+
+// Best-effort: is this semantic-verify task about code that just changed?
+function taskTouchesChange(task, changedSet, changedBasenames) {
+  const cite = task.citedCode || '';
+  if (!cite) return false;
+  if (changedSet.has(cite)) return true;
+  const b = basename(cite);
+  return changedBasenames.has(b) || [...changedSet].some(p => cite.includes(p) || p.includes(cite));
+}
 
 export function runVerify(projectDir, config, flags) {
   if (flags.instructions) {
@@ -37,13 +77,27 @@ export function runVerify(projectDir, config, flags) {
   const claims = extractSemanticClaims(projectDir, config);
   const tasks = buildSemanticVerifyTasks(claims);
 
+  // Change-aware staging (feat 6): if --since given, attach the structured diff
+  // and flag which claims are about just-changed code (verify those first).
+  const changeContext = buildChangeContext(projectDir, flags.since);
+  if (changeContext) {
+    const changedSet = new Set(changeContext.changedFiles);
+    const changedBasenames = new Set(changeContext.changedFiles.map(f => basename(f)));
+    for (const t of tasks) t.aboutChangedCode = taskTouchesChange(t, changedSet, changedBasenames);
+    // Prioritize changed-code claims first.
+    tasks.sort((a, b) => (b.aboutChangedCode ? 1 : 0) - (a.aboutChangedCode ? 1 : 0));
+  }
+
   if (isJson) {
     console.log(JSON.stringify({
       command: 'verify --semantic',
       project: config.projectName,
       claimCount: tasks.length,
       // How to act on this: each task is a claim to confirm against the code.
-      howToVerify: 'For each task, read the cited code (or grep for the constant/config), compare it to the documented value, and report any mismatch with both values. DocGuard cannot judge these — they require reading the code.',
+      howToVerify: changeContext
+        ? 'Claims flagged aboutChangedCode are about code that changed since the ref — verify those FIRST using changeContext.activities (the ordered replace/delete/add spans show exactly what changed). For each task, read the cited code, compare to the documented value, report mismatches with both values.'
+        : 'For each task, read the cited code (or grep for the constant/config), compare it to the documented value, and report any mismatch with both values. DocGuard cannot judge these — they require reading the code.',
+      ...(changeContext ? { changeContext } : {}),
       tasks,
     }, null, 2));
     return;
@@ -66,6 +120,10 @@ export function runVerify(projectDir, config, flags) {
   }
 
   console.log(`  ${c.yellow}${tasks.length} claim(s) to verify against the code:${c.reset}\n`);
+  if (changeContext) {
+    const nChanged = tasks.filter(t => t.aboutChangedCode).length;
+    console.log(`  ${c.cyan}⚡ ${nChanged} claim(s) are about code changed since ${flags.since}${c.reset} ${c.dim}— verify these first (structured diff in --format json).${c.reset}\n`);
+  }
   for (const [doc, ts] of byDoc) {
     console.log(`  ${c.bold}${doc}${c.reset}`);
     for (const t of ts) {
@@ -89,6 +147,9 @@ function runInstructionAudit(projectDir, config, flags) {
   const { rules, deterministic, tasks } = auditInstructions(projectDir, config);
   const { duplicates, negations, stalePointers, staleCommands } = deterministic;
   const findingCount = duplicates.length + negations.length + stalePointers.length + staleCommands.length;
+  // Structured change context helps the agent judge whether a rule about code
+  // has been invalidated by a recent change (feat 6).
+  const changeContext = buildChangeContext(projectDir, flags.since);
 
   if (isJson) {
     console.log(JSON.stringify({
@@ -100,6 +161,7 @@ function runInstructionAudit(projectDir, config, flags) {
       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.',
+      ...(changeContext ? { changeContext } : {}),
       tasks,
     }, null, 2));
     return;

package/cli/config.mjs

@@ -77,6 +77,13 @@ export function loadConfig(projectDir) {
       security: false,
       environment: true,
       freshness: true,
+      // v0.31.0 — all three default ON. Soft (confidence:low, never break CI),
+      // precise (zero false positives across the 6-repo corpus), and quiet when
+      // not applicable (no diff / no API-reference doc). api-doc-smells is
+      // low-yield but zero-FP, so on-by-default beats a self-counting split.
+      diffSuspicion: true,
+      referenceExistence: true,
+      apiDocSmells: true,
     },
   };
 

package/cli/findings.mjs

@@ -600,6 +600,32 @@ export const CODES = {
     help: 'Over 30% of sentences are conditional (if/unless/when…). Split conditionals into separate, unconditional requirements.',
     suppress: null,
   },
+
+  // ── v0.31.0 change-driven + IR detectors (all confidence:'low' / soft) ──
+  DSP001: {
+    validator: 'diff-suspicion',
+    title: 'Doc describes code that just changed',
+    help: 'A canonical doc (or agent-instruction file) references a code file AND shares wording with symbols removed/changed in that file since the compared revision. Deterministic diff-overlap rule (arXiv 2010.01625, F1 74.7). Low-confidence by design — re-read the doc against the current code; suppress the pairing if it is a false positive.',
+    suppress: null,
+  },
+  REF001: {
+    validator: 'reference-existence',
+    title: 'Doc references a code symbol that no longer exists',
+    help: 'A code-element reference in the doc matched source when the doc was last updated, but matches ZERO source instances at HEAD (two-revision check, arXiv 2212.01479). Excludes the two documented false-positive modes (removed-but-config-relevant flags, and symbols whose literal string was deleted while logic remains). Verify and update the reference.',
+    suppress: '<!-- docguard:ignore REF001 — still relevant, e.g. user-facing flag -->',
+  },
+  APS001: {
+    validator: 'api-doc-smells',
+    title: 'Bloated API documentation',
+    help: 'An API doc unit is excessively long / over-structured relative to the surface it documents (smell taxonomy, arXiv API-doc-smells; deterministic Bloated detector F1 0.90). Trim to the essential contract.',
+    suppress: '<!-- docguard:quality api-smell off — your reason -->',
+  },
+  APS002: {
+    validator: 'api-doc-smells',
+    title: 'Lazy API documentation',
+    help: 'An API doc unit is vague/generic or barely exceeds the signature it documents (deterministic Lazy detector F1 0.95). Document parameters, return, and errors concretely.',
+    suppress: '<!-- docguard:quality api-smell off — your reason -->',
+  },
 };
 
 /**