docguard-cli 0.30.1 → 0.32.0

package/README.md

@@ -62,7 +62,7 @@ DocGuard enforces **Canonical-Driven Development (CDD)** — a methodology where
 
 DocGuard is an official [GitHub Spec Kit](https://github.com/github/spec-kit) community extension. It validates the artifacts that Spec Kit creates, ensuring your specs stay high-quality throughout the development lifecycle.
 
-📖 **[Philosophy](PHILOSOPHY.md)** · 📋 **[CDD Standard](STANDARD.md)** · ⚖️ **[Comparisons](COMPARISONS.md)** · 🗺️ **[Roadmap](ROADMAP.md)**
+📖 **[Philosophy](PHILOSOPHY.md)** · 📋 **[CDD Standard](STANDARD.md)** · ⚖️ **[Comparisons](COMPARISONS.md)** · 🔬 **[Validation](VALIDATION.md)** · 🗺️ **[Roadmap](ROADMAP.md)**
 
 ### Architecture
 
@@ -76,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
@@ -254,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) |
@@ -274,7 +274,7 @@ DocGuard ships **18 commands** (the "Daily 5" + 13 situational tools, including
 | `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` |
+| `mcp` | MCP server — exposes guard/score/explain/verify/diagnose as native tools for Claude, Cursor, and any MCP client. Stdio: `claude mcp add docguard -- npx docguard-cli mcp`. Team-shared HTTP: `docguard mcp --transport http --port 8585` (loopback by default; non-loopback binds require `--api-key`) |
 | `memory` | Per-domain accuracy headline (endpoints / entities / env / tech) |
 | `memory --diff` | Drill into which specific claims don't match code |
 | `memory --pack` | Write `.docguard/context-pack.md` — compact, code-truth-stamped session-start context for AI agents |
@@ -325,6 +325,9 @@ Run them solo (`docguard init --with hooks`) or stacked (`docguard init --with a
 | `--apply` | Actually run the migration | upgrade |
 | `--pr` | Open a PR with the migration | upgrade |
 | `--reverse <file>` | Reverse traceability (code → docs) | trace |
+| `--no-indirect` | Skip the reverse-import-graph analysis (docs about modules that import a changed file) | impact, diff --since |
+| `--prs` | Open-PR doc-conflict analysis — two PRs impacting the same canonical doc = merge-order risk (needs the `gh` CLI) | impact |
+| `--transport http` `--port` `--host` `--api-key` `--path` | Serve MCP over Streamable HTTP instead of stdio (team-shared server; loopback-only unless an api-key is set) | mcp |
 | `--history` | Show fix audit log | fix |
 
 ### Example Output
@@ -360,7 +363,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 |
 |:--|:----------|:--------------|:--------|
@@ -383,11 +386,14 @@ DocGuard runs **24 automated validators** on every `guard` check. Every one is *
 | 17 | **TODO-Tracking** | Untracked TODOs/FIXMEs and skipped tests (skips test files by default) | ✅ On |
 | 18 | **Schema-Sync** | Database models documented in DATA-MODEL.md | ✅ On |
 | 19 | **Spec-Kit** | Spec quality validation (FR-IDs, mandatory sections, phased tasks) | ✅ On |
-| 20 | **Cross-Reference** | Internal markdown links + anchors resolve (with "did you mean?" hints) | ✅ On |
+| 20 | **Cross-Reference** | Internal markdown links + anchors resolve (with "did you mean?" hints); Obsidian wikilinks validated when the repo uses them as file links (`.obsidian` present or a target resolves) | ✅ On |
 | 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
@@ -447,6 +453,19 @@ DocGuard works with **every major AI coding agent**. All canonical docs are plai
 | Google Gemini CLI | ✅ | `docguard agents --agent gemini` |
 | Kiro (AWS) | ✅ | — |
 
+### Always-on nudge hook (Claude Code)
+
+```bash
+docguard hooks --claude            # install   (remove: docguard hooks --claude --remove)
+```
+
+Registers a `PostToolUse` hook in the project's `.claude/settings.json`. After the
+agent edits a canonical doc it is nudged to run `docguard guard --changed-only`;
+after it edits a code file the docs reference, it is nudged toward `docguard impact`.
+Merge-safe (only DocGuard's own entry is ever added/removed), throttled to one nudge
+per file per 30 minutes, and the hook runtime can never break a session (errors are
+silent by contract). Explicit opt-in — `init` never installs it for you.
+
 ---
 
 ## ⚡ Slash Commands
@@ -456,7 +475,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 |
@@ -615,7 +634,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/hooks.mjs

@@ -3,7 +3,7 @@
  * Creates git hooks that run guard/score before commits.
  */
 
-import { existsSync, writeFileSync, mkdirSync, chmodSync, readFileSync, unlinkSync } from 'node:fs';
+import { existsSync, writeFileSync, mkdirSync, chmodSync, readFileSync, unlinkSync, readdirSync } from 'node:fs';
 
 // v0.16-P3: managed-block markers. Letting users extend the hook with their
 // own commands (data-file guards, lint checks, etc.) without us clobbering
@@ -54,7 +54,7 @@ function spliceManagedBlock(existing, newBody) {
   const bodyNoShebang = newBody.replace(/^#!.*\n/, '');
   return `${before}${BEGIN_MARKER}\n${bodyNoShebang.replace(/\n+$/, '')}\n${END_MARKER}${after}`;
 }
-import { resolve } from 'node:path';
+import { resolve, relative, basename } from 'node:path';
 import { c } from '../shared.mjs';
 import { getHooksDir } from '../shared-git.mjs';
 
@@ -217,6 +217,15 @@ export function runHooks(projectDir, config, flags) {
   console.log(`${c.bold}🪝 DocGuard Hooks — ${config.projectName}${c.reset}`);
   console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
 
+  // ── Claude Code agent nudge: `docguard hooks --claude` ──
+  // Separate path from git hooks: it edits .claude/settings.json, needs no
+  // git repo, and is explicitly opt-in (writing agent config unasked is a
+  // trust break — same class as the ensureSkills READ_ONLY_COMMANDS rule).
+  if (flags.claude) {
+    installClaudeNudge(projectDir, { remove: !!flags.remove });
+    return;
+  }
+
   // Resolve the real hooks dir via git — NOT `<projectDir>/.git/hooks`, which
   // is wrong inside a linked worktree (where `.git` is a file, not a dir) and
   // ignores a custom core.hooksPath.
@@ -337,3 +346,159 @@ export function runHooks(projectDir, config, flags) {
 
   console.log('');
 }
+
+// ── Claude Code agent nudge ─────────────────────────────────────────────────
+//
+// `docguard hooks --claude` registers a PostToolUse hook in the PROJECT's
+// .claude/settings.json. After the agent edits a canonical doc (or a code
+// file the docs reference), the hook nudges it toward the right DocGuard
+// command — the graphify "query-first hook" distribution pattern, pointed at
+// doc integrity instead of graph queries.
+//
+// Trust rules:
+//   - Explicit opt-in only (never installed by ensureSkills/init).
+//   - Merge-safe: parses the existing settings.json and adds/removes ONLY the
+//     entry whose command contains the NUDGE_HOOK_COMMAND marker. A file that
+//     doesn't parse is never touched.
+//   - The runtime (`docguard nudge-hook`) is throttled and can never break an
+//     agent session: any internal error exits 0 with no output.
+
+const NUDGE_HOOK_COMMAND = 'docguard nudge-hook';
+const NUDGE_THROTTLE_MS = 30 * 60 * 1000; // one nudge per file per 30 min
+const NUDGE_STATE_PATH = '.docguard/nudge-state.json';
+const NUDGE_CODE_EXT = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|swift)$/;
+const NUDGE_AGENT_FILES = new Set(['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']);
+
+function isOurNudgeGroup(group) {
+  return Array.isArray(group?.hooks) &&
+    group.hooks.some(h => typeof h?.command === 'string' && h.command.includes(NUDGE_HOOK_COMMAND));
+}
+
+export function installClaudeNudge(projectDir, { remove = false } = {}) {
+  const settingsDir = resolve(projectDir, '.claude');
+  const settingsPath = resolve(settingsDir, 'settings.json');
+
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    } catch {
+      console.log(`  ${c.red}❌ .claude/settings.json exists but is not valid JSON — refusing to touch it.${c.reset}`);
+      console.log(`  ${c.dim}Fix the file, then re-run docguard hooks --claude.${c.reset}\n`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  const groups = Array.isArray(settings.hooks?.PostToolUse) ? settings.hooks.PostToolUse : [];
+  const present = groups.some(isOurNudgeGroup);
+
+  if (remove) {
+    if (!present) {
+      console.log(`  ${c.dim}⏭️  No DocGuard nudge hook found in .claude/settings.json — nothing to remove.${c.reset}\n`);
+      return;
+    }
+    settings.hooks.PostToolUse = groups.filter(g => !isOurNudgeGroup(g));
+    if (settings.hooks.PostToolUse.length === 0) delete settings.hooks.PostToolUse;
+    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    console.log(`  ${c.yellow}🗑️  Removed the DocGuard nudge hook from .claude/settings.json${c.reset} ${c.dim}(everything else preserved)${c.reset}\n`);
+    return;
+  }
+
+  if (present) {
+    console.log(`  ${c.green}✅ DocGuard nudge hook already installed${c.reset} ${c.dim}(.claude/settings.json — idempotent)${c.reset}\n`);
+    return;
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.PostToolUse)) settings.hooks.PostToolUse = [];
+  settings.hooks.PostToolUse.push({
+    matcher: 'Edit|Write|MultiEdit',
+    hooks: [{ type: 'command', command: NUDGE_HOOK_COMMAND }],
+  });
+
+  if (!existsSync(settingsDir)) mkdirSync(settingsDir, { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  console.log(`  ${c.green}✅ Installed the DocGuard nudge hook${c.reset} → .claude/settings.json (PostToolUse)`);
+  console.log(`  ${c.dim}After an agent edits a canonical doc (or code the docs reference), it is${c.reset}`);
+  console.log(`  ${c.dim}nudged toward docguard guard --changed-only / docguard impact.${c.reset}`);
+  console.log(`  ${c.dim}Throttled: one nudge per file per 30 minutes. Remove: docguard hooks --claude --remove${c.reset}\n`);
+}
+
+/**
+ * Runtime for the PostToolUse hook (`docguard nudge-hook`). Reads the Claude
+ * Code hook payload from stdin, classifies the edited file, and emits a
+ * `{"decision":"block","reason":…}` nudge on stdout when — and only when —
+ * DocGuard has something specific to say. stdout is the machine channel:
+ * nothing else may be printed. Errors NEVER propagate (exit 0, silent) — a
+ * broken nudge must not degrade the agent session.
+ */
+export function runNudgeHook(projectDir) {
+  try {
+    const payload = JSON.parse(readFileSync(0, 'utf-8'));
+    const toolInput = payload.tool_input || payload.toolInput || {};
+    const filePath = toolInput.file_path || toolInput.filePath;
+    if (!filePath) return;
+
+    const rel = relative(projectDir, resolve(projectDir, filePath)).replace(/\\/g, '/');
+    if (!rel || rel.startsWith('..')) return;
+
+    let reason = null;
+    const base = basename(rel);
+    const isCanonicalDoc =
+      (rel.startsWith('docs-canonical/') && rel.endsWith('.md')) ||
+      (NUDGE_AGENT_FILES.has(base) && !rel.includes('/'));
+
+    if (isCanonicalDoc) {
+      reason = `DocGuard: you edited ${rel} — a canonical/agent doc that gates this repo. ` +
+        `Before finishing, run \`docguard guard --changed-only\` to confirm links, anchors, and count claims still hold.`;
+    } else if (NUDGE_CODE_EXT.test(rel)) {
+      const referencingDocs = docsReferencingFile(projectDir, base);
+      if (referencingDocs.length > 0) {
+        reason = `DocGuard: ${referencingDocs.slice(0, 3).join(', ')} reference${referencingDocs.length === 1 ? 's' : ''} ` +
+          `\`${base}\` — after your edits, run \`docguard impact\` to see which doc sections to re-read or update.`;
+      }
+    }
+    if (!reason) return;
+
+    // Throttle per file — iterative edits must not spam the agent.
+    const statePath = resolve(projectDir, NUDGE_STATE_PATH);
+    let state = {};
+    try { state = JSON.parse(readFileSync(statePath, 'utf-8')); } catch { /* first run */ }
+    const now = Date.now();
+    if (state[rel] && now - state[rel] < NUDGE_THROTTLE_MS) return;
+    state[rel] = now;
+    try {
+      mkdirSync(resolve(projectDir, '.docguard'), { recursive: true });
+      writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+    } catch { /* state is best-effort; still nudge */ }
+
+    process.stdout.write(JSON.stringify({ decision: 'block', reason }) + '\n');
+  } catch {
+    // Silent by contract.
+  }
+}
+
+/** Which canonical/agent docs mention this basename? Cheap line scan. */
+function docsReferencingFile(projectDir, base) {
+  const docs = [];
+  const check = (name, full) => {
+    try {
+      if (readFileSync(full, 'utf-8').includes(base)) docs.push(name);
+    } catch { /* unreadable */ }
+  };
+  const dir = resolve(projectDir, 'docs-canonical');
+  if (existsSync(dir)) {
+    try {
+      for (const f of readdirSync(dir)) {
+        if (f.endsWith('.md')) check(f, resolve(dir, f));
+      }
+    } catch { /* unreadable dir */ }
+  }
+  for (const a of NUDGE_AGENT_FILES) {
+    const p = resolve(projectDir, a);
+    if (existsSync(p)) check(a, p);
+  }
+  return docs;
+}