docguard-cli 0.33.1 → 0.34.0

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, readdirSync } from 'node:fs';
+import { existsSync, writeFileSync, mkdirSync, chmodSync, readFileSync, unlinkSync } 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
@@ -57,6 +57,7 @@ function spliceManagedBlock(existing, newBody) {
 import { resolve, relative, basename } from 'node:path';
 import { c } from '../shared.mjs';
 import { getHooksDir } from '../shared-git.mjs';
+import { listCanonicalDocs } from '../shared-ignore.mjs';
 
 const HOOKS = {
   'pre-commit': {
@@ -488,14 +489,11 @@ function docsReferencingFile(projectDir, base) {
       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 */ }
-  }
+  // Recursive — a nested doc mentioning the edited file must still trigger
+  // the post-commit nudge. `name` stays the bare basename to match this
+  // function's pre-existing flat-tree display (the nudge message lists
+  // "ARCHITECTURE.md, SECURITY.md", not full nested paths).
+  for (const doc of listCanonicalDocs(projectDir)) check(basename(doc.rel), doc.abs);
   for (const a of NUDGE_AGENT_FILES) {
     const p = resolve(projectDir, a);
     if (existsSync(p)) check(a, p);

package/cli/commands/impact.mjs

@@ -40,13 +40,14 @@
  * @req SC-S11-009 — docs referencing an importer of a changed file are flagged as indirect
  */
 
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { resolve, basename } from 'node:path';
 import { execFileSync } from 'node:child_process';
 
 import { c } from '../shared.mjs';
 import { changedFilesSince, isGitRepo } from '../shared-git.mjs';
 import { buildImportGraph } from '../validators/architecture.mjs';
+import { listCanonicalDocs } from '../shared-ignore.mjs';
 
 /**
  * File extensions we consider "code" for the purposes of impact analysis.
@@ -254,19 +255,18 @@ export function runImpact(projectDir, config, flags) {
 
   // 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 docsIndex = new Map(); // docName (basename) → lines[]
   const agentDocs = new Set(); // which indexed docs are agent-instruction files
-  if (existsSync(docsDir)) {
+  // Recursive — a nested canonical doc must be indexed too. Keyed by basename
+  // (not full path) to match this file's existing basename-based lookups
+  // (`docsIndex.has(basename(f))`, `indexBasenames`); a doc in a subfolder
+  // with a name clashing an already-indexed doc will overwrite it in the Map,
+  // same pre-existing behavior as a canonical doc clashing an agent doc name.
+  for (const doc of listCanonicalDocs(projectDir)) {
     try {
-      for (const f of readdirSync(docsDir)) {
-        if (!f.endsWith('.md')) continue;
-        try {
-          const content = readFileSync(resolve(docsDir, f), 'utf-8');
-          docsIndex.set(f, content.split('\n'));
-        } catch { /* skip unreadable */ }
-      }
-    } catch { /* skip if dir unreadable */ }
+      const content = readFileSync(doc.abs, 'utf-8');
+      docsIndex.set(basename(doc.rel), content.split('\n'));
+    } catch { /* skip unreadable */ }
   }
   for (const a of AGENT_FILES) {
     const p = resolve(projectDir, a);

package/cli/commands/init.mjs

@@ -11,6 +11,7 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
+import { listCanonicalDocs } from '../shared-ignore.mjs';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
 import { execSync } from 'node:child_process';
@@ -135,13 +136,9 @@ function shouldRunGenerate(projectDir, flags) {
   if (flags.fix)             return false; // --fix = deterministic create-missing-from-templates (headless)
 
   // If canonical docs already exist, this is a re-init, not a first-run.
-  const canonicalDir = resolve(projectDir, 'docs-canonical');
-  if (existsSync(canonicalDir)) {
-    try {
-      const entries = readdirSync(canonicalDir).filter(f => f.endsWith('.md'));
-      if (entries.length > 0) return false;
-    } catch { /* fall through */ }
-  }
+  // Recursive — a project whose only canonical docs are nested must still be
+  // detected as already-initialized, or the wizard re-triggers on every run.
+  if (listCanonicalDocs(projectDir).length > 0) return false;
 
   // Existing-code signals: any of cli/, src/, lib/, app/ as a directory.
   const codeDirs = ['cli', 'src', 'lib', 'app'];

package/cli/commands/llms.mjs

@@ -15,9 +15,10 @@
  *   - `docguard guard` validates llms.txt exists and is current
  */
 
-import { existsSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { resolve, join, basename } from 'node:path';
 import { c } from '../shared.mjs';
+import { listCanonicalDocs } from '../shared-ignore.mjs';
 
 // ──── Doc descriptions for llms.txt ────
 const DOC_DESCRIPTIONS = {
@@ -58,18 +59,12 @@ export function generateLlmsTxt(projectDir, config) {
   }
   lines.push('');
 
-  // ── Canonical Docs ──
-  const docsDir = resolve(projectDir, 'docs-canonical');
+  // ── Canonical Docs ── (recursive — a nested doc still belongs in llms.txt)
   const existingDocs = [];
-
-  if (existsSync(docsDir)) {
-    try {
-      const entries = readdirSync(docsDir).filter(f => f.endsWith('.md')).sort();
-      for (const entry of entries) {
-        const desc = DOC_DESCRIPTIONS[entry] || `${entry.replace('.md', '')} documentation`;
-        existingDocs.push({ path: `docs-canonical/${entry}`, name: entry, desc });
-      }
-    } catch { /* ignore */ }
+  for (const doc of listCanonicalDocs(projectDir)) {
+    const entry = basename(doc.rel);
+    const desc = DOC_DESCRIPTIONS[entry] || `${entry.replace('.md', '')} documentation`;
+    existingDocs.push({ path: doc.rel, name: entry, desc });
   }
 
   if (existingDocs.length > 0) {
@@ -160,13 +155,8 @@ export function generateLlmsFullTxt(projectDir, config) {
 
   // Same doc discovery as the index form: canonical docs + present optional docs.
   const docPaths = [];
-  const docsDir = resolve(projectDir, 'docs-canonical');
-  if (existsSync(docsDir)) {
-    try {
-      for (const entry of readdirSync(docsDir).filter(f => f.endsWith('.md')).sort()) {
-        docPaths.push({ path: `docs-canonical/${entry}`, desc: DOC_DESCRIPTIONS[entry] || null });
-      }
-    } catch { /* ignore */ }
+  for (const doc of listCanonicalDocs(projectDir)) {
+    docPaths.push({ path: doc.rel, desc: DOC_DESCRIPTIONS[basename(doc.rel)] || null });
   }
   for (const [file, desc] of Object.entries(OPTIONAL_DOCS)) {
     if (existsSync(resolve(projectDir, file))) docPaths.push({ path: file, desc });

package/cli/commands/memory.mjs

@@ -21,9 +21,10 @@
  * Zero NPM dependencies. Pure orchestration of existing diff helpers.
  */
 
-import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { c } from '../shared.mjs';
+import { listCanonicalDocs } from '../shared-ignore.mjs';
 import { diffRoutes, diffEntities, diffEnvVars, diffTechStack } from './diff.mjs';
 import { buildMemoryPlan } from '../scanners/memory-plan.mjs';
 import { runGuardInternal } from './guard.mjs';
@@ -97,19 +98,17 @@ function runMemoryPack(projectDir, config, flags) {
   lines.push(`- Tests: ${plan.surface.tests.totalFiles} files, ${plan.surface.tests.totalCases} cases`);
   lines.push('');
 
-  const docsDir = resolve(projectDir, 'docs-canonical');
-  if (existsSync(docsDir)) {
+  const canonicalDocs = listCanonicalDocs(projectDir);
+  if (canonicalDocs.length > 0) {
     lines.push('## Canonical docs');
     lines.push('');
-    let entries = [];
-    try { entries = readdirSync(docsDir).filter(f => f.endsWith('.md')).sort(); } catch { /* ignore */ }
-    for (const doc of entries) {
+    for (const doc of canonicalDocs) {
       let reviewed = '';
       try {
-        const m = readFileSync(resolve(docsDir, doc), 'utf-8').match(/docguard:last-reviewed\s+(\d{4}-\d{2}-\d{2})/);
+        const m = readFileSync(doc.abs, 'utf-8').match(/docguard:last-reviewed\s+(\d{4}-\d{2}-\d{2})/);
         if (m) reviewed = ` (last-reviewed ${m[1]})`;
       } catch { /* ignore */ }
-      lines.push(`- docs-canonical/${doc}${reviewed}`);
+      lines.push(`- ${doc.rel}${reviewed}`);
     }
     lines.push('');
   }

package/cli/commands/score.mjs

@@ -12,6 +12,7 @@ import { runGuardInternal } from './guard.mjs';
 import { extractSemanticClaims } from '../scanners/semantic-claims.mjs';
 import { assessAgentReadability } from '../scanners/agent-readability.mjs';
 import { loadHistory, sparkline } from '../writers/history.mjs';
+import { listCanonicalDocs } from '../shared-ignore.mjs';
 
 /**
  * Detect whether the project configures a test runner (the "Check 3" of the
@@ -424,16 +425,16 @@ export function computeAlcoaCompliance(projectDir, config, scores) {
   // 1. Attributable — Can we trace who wrote/reviewed docs?
   const hasGit = existsSync(resolve(projectDir, '.git'));
   const docsDir = resolve(projectDir, 'docs-canonical');
+  // Recursive — a nested canonical tree is still the canonical tree. A flat
+  // read scored ALCOA against an empty doc set on those projects.
+  const canonicalDocs = listCanonicalDocs(projectDir);
   let hasReviewedMeta = false;
-  if (existsSync(docsDir)) {
+  for (const doc of canonicalDocs) {
     try {
-      const docs = readdirSync(docsDir).filter(f => f.endsWith('.md'));
-      for (const doc of docs) {
-        const content = readFileSync(join(docsDir, doc), 'utf-8');
-        if (content.includes('docguard:last-reviewed') || content.includes('last-reviewed')) {
-          hasReviewedMeta = true;
-          break;
-        }
+      const content = readFileSync(doc.abs, 'utf-8');
+      if (content.includes('docguard:last-reviewed') || content.includes('last-reviewed')) {
+        hasReviewedMeta = true;
+        break;
       }
     } catch { /* ignore */ }
   }
@@ -457,16 +458,13 @@ export function computeAlcoaCompliance(projectDir, config, scores) {
 
   // 3. Contemporaneous — Are docs kept current?
   let freshnessMet = true;
-  if (existsSync(docsDir)) {
+  for (const doc of canonicalDocs) {
     try {
-      const docs = readdirSync(docsDir).filter(f => f.endsWith('.md'));
-      for (const doc of docs) {
-        const stat_ = statSync(join(docsDir, doc));
-        const daysSinceModified = (Date.now() - stat_.mtimeMs) / (1000 * 60 * 60 * 24);
-        if (daysSinceModified > 30) {
-          freshnessMet = false;
-          break;
-        }
+      const stat_ = statSync(doc.abs);
+      const daysSinceModified = (Date.now() - stat_.mtimeMs) / (1000 * 60 * 60 * 24);
+      if (daysSinceModified > 30) {
+        freshnessMet = false;
+        break;
       }
     } catch { /* ignore */ }
   }
@@ -1079,13 +1077,8 @@ function getSuggestion(category, score, details) {
  */
 function estimateDocTax(projectDir, config, scores) {
   // Count tracked docs
-  const canonicalDir = resolve(projectDir, 'docs-canonical');
-  let docCount = 0;
-  if (existsSync(canonicalDir)) {
-    try {
-      docCount = readdirSync(canonicalDir).filter(f => f.endsWith('.md')).length;
-    } catch { /* ignore */ }
-  }
+  // Recursive — nested canonical docs cost maintenance too, so they count.
+  let docCount = listCanonicalDocs(projectDir).length;
   // Add root tracking files
   if (existsSync(resolve(projectDir, 'CHANGELOG.md'))) docCount++;
   if (existsSync(resolve(projectDir, 'DRIFT-LOG.md'))) docCount++;

package/cli/commands/trace.mjs

@@ -10,6 +10,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname, basename, relative, dirname } from 'node:path';
 import { c } from '../shared.mjs';
 import { detectSpecKit } from '../scanners/speckit.mjs';
+import { listCanonicalDocs } from '../shared-ignore.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
@@ -74,11 +75,11 @@ export function runTraceReverse(projectDir, config, flags) {
   const stem = base.replace(/\.[^.]+$/, '');
 
   const matches = []; // { doc, line, content, kind }
-  for (const f of readdirSync(docsDir)) {
-    if (!f.endsWith('.md')) continue;
-    const docPath = resolve(docsDir, f);
+  // Recursive — a nested doc mentioning this file must still be found, or
+  // `trace --reverse` falsely reports "no canonical doc references this".
+  for (const doc of listCanonicalDocs(projectDir)) {
     let content;
-    try { content = readFileSync(docPath, 'utf-8'); } catch { continue; }
+    try { content = readFileSync(doc.abs, 'utf-8'); } catch { continue; }
     const lines = content.split('\n');
     for (let i = 0; i < lines.length; i++) {
       const line = lines[i];
@@ -87,7 +88,7 @@ export function runTraceReverse(projectDir, config, flags) {
       else if (line.includes(base)) kind = 'basename';
       else if (new RegExp(`\`${escapeRegex(stem)}\``).test(line)) kind = 'module';
       if (kind) {
-        matches.push({ doc: f, line: i + 1, content: line.trim(), kind });
+        matches.push({ doc: doc.rel, line: i + 1, content: line.trim(), kind });
       }
     }
   }
@@ -155,13 +156,11 @@ export function runTrace(projectDir, config, flags) {
   );
 
   // ── 2. Inventory canonical docs ──
+  // NOTE: currently unused downstream (outputText ignores its 3rd param) —
+  // kept for API stability and future use. Recursive so it isn't ANOTHER
+  // silent flat-read landmine if something starts consuming it.
   const docsDir = resolve(projectDir, 'docs-canonical');
-  const canonicalDocs = [];
-  if (existsSync(docsDir)) {
-    for (const f of readdirSync(docsDir)) {
-      if (f.endsWith('.md')) canonicalDocs.push(f);
-    }
-  }
+  const canonicalDocs = listCanonicalDocs(projectDir).map(d => d.rel);
 
   // ── 3. Scan project files ──
   const projectFiles = [];

package/cli/scanners/agent-readability.mjs

@@ -12,9 +12,10 @@
  * read that.
  */
 
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
 import { loadIgnorePatterns } from '../shared.mjs';
+import { listCanonicalDocs } from '../shared-ignore.mjs';
 
 /** chars/4 — the standard rough token estimate; consistency matters more than precision. */
 const estTokens = (s) => Math.ceil(s.length / 4);
@@ -30,19 +31,14 @@ function readIfExists(path) {
 }
 
 function canonicalDocs(projectDir) {
-  const dir = resolve(projectDir, 'docs-canonical');
-  if (!existsSync(dir)) return [];
   // Honor .docguardignore — an excluded doc (e.g. a historical audit) must
   // not drag down the readability metrics either (same rule as the
   // semantic-claim extractor, bug-212).
   const isIgnored = loadIgnorePatterns(projectDir);
-  try {
-    return readdirSync(dir)
-      .filter(f => f.toLowerCase().endsWith('.md') && !isIgnored(`docs-canonical/${f}`))
-      .sort()
-      .map(f => ({ name: `docs-canonical/${f}`, content: readIfExists(resolve(dir, f)) }))
-      .filter(d => d.content !== null);
-  } catch { return []; }
+  // Recursive: docs in subfolders are canonical docs and are scored as such.
+  return listCanonicalDocs(projectDir, { isIgnored })
+    .map(d => ({ name: d.rel, content: readIfExists(d.abs) }))
+    .filter(d => d.content !== null);
 }
 
 /**

package/cli/scanners/semantic-claims.mjs

@@ -21,9 +21,10 @@
  * Zero npm dependencies — pure Node.js built-ins.
  */
 
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { resolve, join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { loadIgnorePatterns } from '../shared.mjs';
+import { listCanonicalDocs } from '../shared-ignore.mjs';
 
 // Numbers are only claims when adjacent to a recognized unit.
 const NUMBER_PATTERNS = [
@@ -55,17 +56,10 @@ function claimSourceDocs(projectDir) {
   // "unverified claims" pool either — it inflated the count and buried the
   // claims that ARE actionable (bug-212).
   const isIgnored = loadIgnorePatterns(projectDir);
-  const docs = [];
-  const canonical = resolve(projectDir, 'docs-canonical');
-  if (existsSync(canonical)) {
-    try {
-      for (const f of readdirSync(canonical)) {
-        if (f.toLowerCase().endsWith('.md') && !isIgnored(`docs-canonical/${f}`)) {
-          docs.push(`docs-canonical/${f}`);
-        }
-      }
-    } catch { /* ignore */ }
-  }
+  // Recursive — nested canonical docs make claims too. The ignore predicate is
+  // applied per-doc inside the helper against the full relative path, so a
+  // pattern like `docs-canonical/99-archive/**` still excludes a subtree.
+  const docs = listCanonicalDocs(projectDir, { isIgnored }).map(d => d.rel);
   for (const root of ['README.md', 'AGENTS.md']) {
     if (existsSync(resolve(projectDir, root)) && !isIgnored(root)) docs.push(root);
   }

package/cli/shared-ignore.mjs

@@ -350,6 +350,59 @@ export function walkFiles(dir, callback, opts = {}) {
   return complete;
 }
 
+/**
+ * Enumerate the project's canonical docs — RECURSIVELY.
+ *
+ * Five call sites used to do this by hand with a flat
+ * `readdirSync('docs-canonical').filter(f => f.endsWith('.md'))`. That works
+ * only for a flat tree; a project that groups its canonical docs in subfolders
+ * (`docs-canonical/01-architecture/MODULE-MAP.md` — a common convention once a
+ * repo has more than a handful) was invisible to ALL of them. The failure was
+ * silent and pointed the wrong way: docs-sync flagged every service as
+ * undocumented while the docs sat right there, `docguard:validator … n/a`
+ * markers in nested docs were ignored, and readability/freshness scored an
+ * empty set. This is the single shared implementation — same rule as
+ * `walkFiles`: exactly one correct way to enumerate, so the answers can't drift.
+ *
+ * Contract:
+ *   - Recursive; delegates traversal to `walkFiles`, so `ignoreDirs` and the
+ *     skip-dot-directories rule apply. A dot-FILE ending in `.md` is kept, to
+ *     preserve the flat behavior these call sites had.
+ *   - `.md` matching is case-INSENSITIVE. Three of the five original call sites
+ *     lowercased and two did not; one tool must not hold two opinions about
+ *     what a canonical doc is. The inclusive reading wins.
+ *   - Sorted by relative path, so output is deterministic across platforms.
+ *   - NEVER throws. An unreadable subtree yields the files that were readable.
+ *
+ * @param {string} projectDir - Project root (absolute)
+ * @param {{dirName?: string, isIgnored?: ((relPath: string) => boolean) | null}} [opts]
+ *   `isIgnored` — optional `.docguardignore` predicate from the caller (see
+ *   `loadIgnorePatterns` in shared.mjs). Passed in rather than imported so this
+ *   module stays a leaf with no local imports.
+ * @returns {Array<{abs: string, rel: string}>} `rel` is project-relative POSIX
+ */
+export function listCanonicalDocs(projectDir, opts = {}) {
+  const { dirName = 'docs-canonical', isIgnored = null } = opts;
+  const root = resolvePath(projectDir, dirName);
+  if (!existsSync(root)) return [];
+
+  const isMarkdown = (name) => name.toLowerCase().endsWith('.md');
+  const out = [];
+  walkFiles(root, (abs) => {
+    if (!isMarkdown(abs)) return;
+    const rel = relPosix(projectDir, abs);
+    if (isIgnored && isIgnored(rel)) return;
+    out.push({ abs, rel });
+  }, {
+    // Keep dot-FILES that are markdown (old flat behavior included them);
+    // dot-DIRECTORIES still get skipped, since the predicate only matches `.md`.
+    keepDot: isMarkdown,
+  });
+
+  out.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+  return out;
+}
+
 /**
  * Count files under `projectDir` matching an anchored glob (project-relative).
  * The code-truth side of `config.collections` (metrics-consistency).

package/cli/validator-markers.mjs

@@ -20,8 +20,9 @@
  * Zero NPM dependencies — pure Node.js built-ins.
  */
 
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { resolve, join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { listCanonicalDocs } from './shared-ignore.mjs';
 
 // `<!-- docguard:validator <key> n/a [— reason] -->`
 // Separator before the reason may be —, :, or one-or-more hyphens. Reason
@@ -30,15 +31,10 @@ const MARKER_RE = /<!--\s*docguard:validator\s+([A-Za-z0-9_-]+)\s+n\/a\b\s*(?:[
 
 /** Files where a validator marker is honored — the docs humans actually read. */
 function markerSourceFiles(projectDir) {
-  const files = [];
-  const canonicalDir = resolve(projectDir, 'docs-canonical');
-  if (existsSync(canonicalDir)) {
-    try {
-      for (const f of readdirSync(canonicalDir)) {
-        if (f.toLowerCase().endsWith('.md')) files.push(join(canonicalDir, f));
-      }
-    } catch { /* ignore */ }
-  }
+  // Recursive: a marker declared in docs-canonical/01-architecture/FOO.md must
+  // be honored too — a flat read silently dropped the suppression and the
+  // validator ran anyway, which reads as "DocGuard ignored my n/a".
+  const files = listCanonicalDocs(projectDir).map(d => d.abs);
   for (const root of ['AGENTS.md', 'README.md', 'CLAUDE.md']) {
     const p = resolve(projectDir, root);
     if (existsSync(p)) files.push(p);

package/cli/validators/api-doc-smells.mjs

@@ -20,9 +20,10 @@
  * All findings confidence:'low' / soft — a nudge to right-size the doc.
  */
 
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
+import { listCanonicalDocs } from '../shared-ignore.mjs';
 
 const HEADING = /^(#{1,6})\s+(.*)$/;
 // A heading that documents an API/code unit — NOT a prose section heading.
@@ -94,18 +95,20 @@ export function validateApiDocSmells(projectDir, config = {}) {
   const lazyMax = Number.isInteger(cfg.lazyMaxWords) ? cfg.lazyMaxWords : 6;
   const bloatedMin = Number.isInteger(cfg.bloatedMinWords) ? cfg.bloatedMinWords : 300;
 
-  const docsDir = resolve(projectDir, 'docs-canonical');
-  if (!existsSync(docsDir)) {
+  const docFiles = listCanonicalDocs(projectDir); // recursive
+  if (docFiles.length === 0) {
     return resultFromFindings([], { passed: 0, total: 0, applicable: false });
   }
-  let docFiles = [];
-  try { docFiles = readdirSync(docsDir).filter(f => f.endsWith('.md')); } catch { /* skip */ }
 
   const findings = [];
   let unitCount = 0;
-  for (const f of docFiles) {
+  for (const doc of docFiles) {
     let content;
-    try { content = readFileSync(resolve(docsDir, f), 'utf-8'); } catch { continue; }
+    try { content = readFileSync(doc.abs, 'utf-8'); } catch { continue; }
+    // `f` stays the bare basename — matches this validator's pre-existing
+    // flat-tree message/location format exactly (both were already bare
+    // filenames, not project-relative paths, before this fix).
+    const f = basename(doc.rel);
     const units = extractUnits(content);
     for (const u of units) {
       unitCount++;

package/cli/validators/cross-reference.mjs

@@ -33,11 +33,11 @@
  * @req SC-K7-004 — code-fenced examples don't trigger false positives
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { resolve, join, dirname, basename, relative } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, dirname, basename, relative } from 'node:path';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
 import { resolveDocDirs } from '../shared.mjs';
-import { walkFiles } from '../shared-ignore.mjs';
+import { walkFiles, listCanonicalDocs } from '../shared-ignore.mjs';
 
 /**
  * Slugify a heading the way GitHub's markdown anchors work.
@@ -323,18 +323,7 @@ function resolveTarget(sourcePath, targetRel, projectDir) {
  * validators — `docs-canonical/`, root tracking files, and AGENTS.md.
  */
 function collectCanonicalDocs(projectDir) {
-  const docs = [];
-  const cdir = resolve(projectDir, 'docs-canonical');
-  if (existsSync(cdir)) {
-    try {
-      for (const f of readdirSync(cdir)) {
-        if (f.endsWith('.md')) {
-          const p = join(cdir, f);
-          if (statSync(p).isFile()) docs.push(p);
-        }
-      }
-    } catch {}
-  }
+  const docs = listCanonicalDocs(projectDir).map(d => d.abs); // recursive
   // Standard root-level docs that are commonly cross-referenced. We index
   // them so links like [CONTRIBUTING.md](CONTRIBUTING.md#some-section) can
   // resolve. The list is conservative — adding everything would pull in

package/cli/validators/diff-suspicion.mjs

@@ -18,11 +18,12 @@
  * or no code change carries removed tokens, so it stays silent off-CI.
  */
 
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { resolve, basename } from 'node:path';
 import { isGitRepo, getDiffText } from '../shared-git.mjs';
 import { parseUnifiedDiff, removedTokens, tokenize, tokenOverlap } from '../shared-diff.mjs';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
+import { listCanonicalDocs } from '../shared-ignore.mjs';
 
 const CODE_EXTENSIONS = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|swift|scala|dart)$/;
 
@@ -64,14 +65,9 @@ function indexDocs(projectDir) {
       docs.set(name, { lines: content.split('\n'), tokens: tokenize(content) });
     } catch { /* skip unreadable */ }
   };
-  const docsDir = resolve(projectDir, 'docs-canonical');
-  if (existsSync(docsDir)) {
-    try {
-      for (const f of readdirSync(docsDir)) {
-        if (f.endsWith('.md')) add(f, resolve(docsDir, f));
-      }
-    } catch { /* skip */ }
-  }
+  // Recursive. Keyed by bare basename — matches this validator's pre-existing
+  // flat-tree DSP001 message format ("ARCHITECTURE.md describes...").
+  for (const doc of listCanonicalDocs(projectDir)) add(basename(doc.rel), doc.abs);
   // Agent-instruction files are documentation too — they routinely name code.
   for (const agent of ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']) {
     const p = resolve(projectDir, agent);

package/cli/validators/doc-quality.mjs

@@ -20,9 +20,10 @@
  * built-ins reading files only.
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { resolve, join, extname, relative } from 'node:path';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { resolve, join, extname, relative, basename } from 'node:path';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
+import { listCanonicalDocs } from '../shared-ignore.mjs';
 
 // ──── Metric Thresholds ────
 // These define "good" vs "warning" boundaries for each metric.
@@ -446,24 +447,12 @@ function getGradeLabel(grade) {
  * Collect all markdown files in docs-canonical/ directory.
  */
 function getCanonicalDocs(projectDir) {
-  const docsDir = resolve(projectDir, 'docs-canonical');
-  const docs = [];
-
-  if (!existsSync(docsDir)) return docs;
-
-  try {
-    const entries = readdirSync(docsDir);
-    for (const entry of entries) {
-      if (extname(entry).toLowerCase() === '.md') {
-        docs.push({
-          name: entry,
-          path: join(docsDir, entry),
-        });
-      }
-    }
-  } catch {
-    // Directory read failed silently
-  }
+  // Recursive. `name` stays the bare basename (not the full nested path) to
+  // match this function's pre-existing flat-tree display format exactly —
+  // messages read "ARCHITECTURE.md: ..." not "docs-canonical/x/ARCHITECTURE.md: ...".
+  // Same collision tradeoff as elsewhere: two nested docs sharing a basename
+  // are indistinguishable by name (pre-existing risk, not new).
+  const docs = listCanonicalDocs(projectDir).map(d => ({ name: basename(d.rel), path: d.abs }));
 
   // Also check README.md at project root
   const readmePath = resolve(projectDir, 'README.md');

package/cli/validators/docs-coverage.mjs

@@ -21,7 +21,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, basename, extname } from 'node:path';
 import { resolveSourceRoots } from '../shared-source.mjs';
-import { shouldIgnore, walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
+import { shouldIgnore, walkFiles as sharedWalkFiles, listCanonicalDocs } from '../shared-ignore.mjs';
 import { detectIaC, hasInfrastructureHeading, buildIaCWarning } from '../scanners/iac.mjs';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
 
@@ -508,14 +508,7 @@ function collectDocContent(projectDir) {
     if (existsSync(p)) docPaths.push(p);
   }
 
-  const canonDir = resolve(projectDir, 'docs-canonical');
-  if (existsSync(canonDir)) {
-    try {
-      for (const entry of readdirSync(canonDir)) {
-        if (entry.endsWith('.md')) docPaths.push(resolve(canonDir, entry));
-      }
-    } catch { /* skip */ }
-  }
+  for (const doc of listCanonicalDocs(projectDir)) docPaths.push(doc.abs); // recursive
 
   const extDir = resolve(projectDir, 'extensions');
   if (existsSync(extDir)) {

package/cli/validators/docs-sync.mjs

@@ -10,7 +10,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname, basename } from 'node:path';
 import { resolveSourceRoots } from '../shared-source.mjs';
-import { relPosix, walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
+import { relPosix, walkFiles as sharedWalkFiles, listCanonicalDocs } from '../shared-ignore.mjs';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 const IGNORE_DIRS = new Set([
@@ -71,15 +71,13 @@ export function validateDocsSync(projectDir, config) {
   let passed = 0;
   let total = 0;
 
-  // Load all canonical doc content for checking
-  const canonicalDir = resolve(projectDir, 'docs-canonical');
+  // Load all canonical doc content for checking. Recursive — docs grouped in
+  // subfolders (docs-canonical/01-architecture/…) count as canonical too; a
+  // flat read made every service they documented look undocumented.
   let canonicalContent = '';
-  if (existsSync(canonicalDir)) {
+  for (const doc of listCanonicalDocs(projectDir)) {
     try {
-      const files = readdirSync(canonicalDir).filter(f => f.endsWith('.md'));
-      for (const f of files) {
-        canonicalContent += readFileSync(resolve(canonicalDir, f), 'utf-8') + '\n';
-      }
+      canonicalContent += readFileSync(doc.abs, 'utf-8') + '\n';
     } catch {
       // Skip if can't read
     }

package/cli/validators/generated-staleness.mjs

@@ -29,6 +29,7 @@ import { resolve, basename, join } from 'node:path';
 import { buildMemoryPlan } from '../scanners/memory-plan.mjs';
 import { getSection } from '../writers/sections.mjs';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
+import { listCanonicalDocs } from '../shared-ignore.mjs';
 
 /**
  * v0.18-P1 fast-path: cheap pre-flight to detect whether ANY canonical doc
@@ -41,34 +42,36 @@ import { mkFinding, resultFromFindings } from '../findings.mjs';
  */
 function _quickScan(projectDir) {
   const out = { hasMarkers: false, hasDrafts: false };
-  const candidateDirs = [
-    resolve(projectDir, 'docs-canonical'),
-    projectDir, // for README.md, AGENTS.md, etc.
-  ];
+  // Recursive for docs-canonical/ — a marker in a nested doc must still be
+  // found, or this pre-flight false-negatives and skips the ENTIRE validator
+  // (buildMemoryPlan never even runs), silently disabling drift detection.
+  // projectDir itself stays a SHALLOW, non-recursive scan by design — it's
+  // here only to catch root-level README.md/AGENTS.md, not to walk the repo.
+  const candidateFiles = listCanonicalDocs(projectDir).map(d => d.abs);
+  try {
+    for (const entry of readdirSync(projectDir)) {
+      if (entry.endsWith('.md')) candidateFiles.push(join(projectDir, entry));
+    }
+  } catch { /* ignore */ }
+
   // We only need a single match in any file to know the validator has work.
   // Short-circuit aggressively: stop the moment we find either signal.
-  for (const dir of candidateDirs) {
-    if (!existsSync(dir)) continue;
-    let entries;
-    try { entries = readdirSync(dir); } catch { continue; }
-    for (const entry of entries) {
-      if (!entry.endsWith('.md')) continue;
-      // Skip very large files quickly — for canonical docs, > 200 KB is unusual
-      // and almost certainly not the marker-heavy file we're looking for.
-      let stat;
-      try { stat = statSync(join(dir, entry)); } catch { continue; }
-      if (!stat.isFile()) continue;
-      if (stat.size > 200_000) continue;
-      let content;
-      try { content = readFileSync(join(dir, entry), 'utf-8'); } catch { continue; }
-      if (!out.hasMarkers && /<!--\s*docguard:section\s+[^>]*source=code/i.test(content)) {
-        out.hasMarkers = true;
-      }
-      if (!out.hasDrafts && /(?:^---\s*\n[\s\S]*?\bstatus:\s*draft\b[\s\S]*?\n---|<!--\s*status:\s*draft\s*-->)/im.test(content)) {
-        out.hasDrafts = true;
-      }
-      if (out.hasMarkers && out.hasDrafts) return out;
+  for (const full of candidateFiles) {
+    // Skip very large files quickly — for canonical docs, > 200 KB is unusual
+    // and almost certainly not the marker-heavy file we're looking for.
+    let stat;
+    try { stat = statSync(full); } catch { continue; }
+    if (!stat.isFile()) continue;
+    if (stat.size > 200_000) continue;
+    let content;
+    try { content = readFileSync(full, 'utf-8'); } catch { continue; }
+    if (!out.hasMarkers && /<!--\s*docguard:section\s+[^>]*source=code/i.test(content)) {
+      out.hasMarkers = true;
+    }
+    if (!out.hasDrafts && /(?:^---\s*\n[\s\S]*?\bstatus:\s*draft\b[\s\S]*?\n---|<!--\s*status:\s*draft\s*-->)/im.test(content)) {
+      out.hasDrafts = true;
     }
+    if (out.hasMarkers && out.hasDrafts) return out;
   }
   return out;
 }

package/cli/validators/reference-existence.mjs

@@ -41,7 +41,7 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { resolve, extname, relative, basename } from 'node:path';
 import { isGitRepo, lastCommitHash, symbolExistsAtRev } from '../shared-git.mjs';
-import { walkFiles, isNonProductPath } from '../shared-ignore.mjs';
+import { walkFiles, isNonProductPath, listCanonicalDocs } from '../shared-ignore.mjs';
 import { readScannable } from '../shared-source.mjs';
 import { resolveDocDirs } from '../shared.mjs';
 import { mkFinding, resultFromFindings, lineSuppresses } from '../findings.mjs';
@@ -170,12 +170,9 @@ function indexDocs(projectDir) {
       docs.push({ name, path: full, refs: extractRefs(content) });
     } catch { /* skip */ }
   };
-  const docsDir = resolve(projectDir, 'docs-canonical');
-  if (existsSync(docsDir)) {
-    try {
-      for (const f of readdirSync(docsDir)) if (f.endsWith('.md')) push(f, resolve(docsDir, f));
-    } catch { /* skip */ }
-  }
+  // Recursive. `name` stays the bare basename — matches this validator's
+  // pre-existing flat-tree message/location format exactly.
+  for (const doc of listCanonicalDocs(projectDir)) push(basename(doc.rel), doc.abs);
   for (const agent of ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']) {
     const p = resolve(projectDir, agent);
     if (existsSync(p)) push(agent, p);

package/cli/validators/traceability.mjs

@@ -16,7 +16,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, basename, extname } from 'node:path';
 import { TRACE_MAP, TEST_PATTERNS, isTraceableSource } from '../shared-trace-patterns.mjs';
-import { walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
+import { walkFiles as sharedWalkFiles, listCanonicalDocs } from '../shared-ignore.mjs';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
 import { tokenize } from '../shared-diff.mjs';
 import { rankBySimilarity } from '../shared-ir.mjs';
@@ -231,21 +231,25 @@ export function validateTraceability(projectDir, config) {
   }
 
   // ── Detect orphaned files (exist but not required) ──
-  try {
-    const existingDocs = readdirSync(docsDir).filter(f => f.endsWith('.md'));
-    for (const docFile of existingDocs) {
-      if (!requiredDocs.has(docFile) && TRACE_MAP[docFile]) {
-        findings.push(mkFinding({
-          code: 'TRC003',
-          validator: 'traceability',
-          severity: 'warn',
-          message: `${docFile} — file exists in docs-canonical/ but is not in your requiredFiles config. Consider deleting it or adding it to .docguard.json requiredFiles.canonical`,
-          location: `docs-canonical/${docFile}`,
-          suggestion: { kind: 'review', text: 'Delete the doc, or add it to requiredFiles.canonical in .docguard.json so it gets validated' },
-        }));
-      }
+  // Recursive — a nested stray doc must be visible too. TRACE_MAP/requiredDocs
+  // matching stays keyed by bare basename (TRACE_MAP's own keys are
+  // conventional top-level names); `location` uses the real path so the
+  // finding points at the actual file instead of a fabricated flat one — for
+  // a flat tree `doc.rel` already equals the old `docs-canonical/${docFile}`
+  // template exactly, so this is a no-op on the flat case.
+  for (const doc of listCanonicalDocs(projectDir)) {
+    const docFile = basename(doc.rel);
+    if (!requiredDocs.has(docFile) && TRACE_MAP[docFile]) {
+      findings.push(mkFinding({
+        code: 'TRC003',
+        validator: 'traceability',
+        severity: 'warn',
+        message: `${docFile} — file exists in docs-canonical/ but is not in your requiredFiles config. Consider deleting it or adding it to .docguard.json requiredFiles.canonical`,
+        location: doc.rel,
+        suggestion: { kind: 'review', text: 'Delete the doc, or add it to requiredFiles.canonical in .docguard.json so it gets validated' },
+      }));
     }
-  } catch { /* ignore */ }
+  }
 
   // ── Part 2: Requirement ID Traceability (V-Model) ──
   const reqResult = validateRequirementTraceability(projectDir, config, projectFiles);
@@ -427,17 +431,10 @@ function scanTestFilesForReferences(projectDir, projectFiles, patterns) {
 function getRequirementDocPaths(projectDir, config) {
   const paths = [];
 
-  // docs-canonical/ directory
-  const docsDir = resolve(projectDir, 'docs-canonical');
-  if (existsSync(docsDir)) {
-    try {
-      for (const f of readdirSync(docsDir)) {
-        if (extname(f).toLowerCase() === '.md') {
-          paths.push(join(docsDir, f));
-        }
-      }
-    } catch { /* ignore */ }
-  }
+  // docs-canonical/ directory — recursive. Consumer re-derives the display
+  // path via relative(projectDir, docPath), so nested docs already report
+  // their real path with no further change needed there.
+  for (const doc of listCanonicalDocs(projectDir)) paths.push(doc.abs);
 
   // Root-level docs
   const rootDocs = ['REQUIREMENTS.md', 'spec.md', 'README.md'];

package/extensions/spec-kit-docguard/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.33.1"
+  version: "0.34.0"
   description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with automated validators, 4 AI behavior skills, spec-kit skill chaining, and workflow hooks. One pinned runtime dependency (@babel/parser); pure Node.js otherwise."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"

package/extensions/spec-kit-docguard/skills/docguard-fix/SKILL.md

@@ -6,10 +6,10 @@ description: AI-driven documentation repair with structured research workflow, t
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.33.1
+  version: 0.34.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.33.1 -->
+<!-- docguard:version: 0.34.0 -->
 
 # DocGuard Fix Skill
 

package/extensions/spec-kit-docguard/skills/docguard-guard/SKILL.md

@@ -7,10 +7,10 @@ description: Run DocGuard guard validation against Canonical-Driven Development
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.33.1
+  version: 0.34.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.33.1 -->
+<!-- docguard:version: 0.34.0 -->
 
 # DocGuard Guard Skill
 

package/extensions/spec-kit-docguard/skills/docguard-review/SKILL.md

@@ -6,10 +6,10 @@ description: Cross-document consistency analysis and quality assessment. Perform
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.33.1
+  version: 0.34.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.33.1 -->
+<!-- docguard:version: 0.34.0 -->
 
 # DocGuard Review Skill
 

package/extensions/spec-kit-docguard/skills/docguard-score/SKILL.md

@@ -6,10 +6,10 @@ description: CDD maturity assessment with category-aware improvement roadmap. Ru
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.33.1
+  version: 0.34.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.33.1 -->
+<!-- docguard:version: 0.34.0 -->
 
 # DocGuard Score Skill
 

package/extensions/spec-kit-docguard/skills/docguard-sync/SKILL.md

@@ -4,10 +4,10 @@ description: Keep canonical documentation ALWAYS UP TO DATE. Refreshes code-trut
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.33.1
+  version: 0.34.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.33.1 -->
+<!-- docguard:version: 0.34.0 -->
 
 # DocGuard Sync Skill
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.33.1",
+  "version": "0.34.0",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {