docguard-cli 0.35.0 → 0.36.0

package/cli/validators/todo-tracking.mjs

@@ -19,6 +19,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, extname } from 'node:path';
 import { shouldIgnore, walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
+import { parseJsTs, walk } from '../scanners/js-ast.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
@@ -62,7 +63,7 @@ function commentPortion(line) {
 
 // Test skip patterns for common test frameworks
 const SKIP_PATTERNS = [
-  /\btest\.skip\s*\(/,
+  /\btest\.(?:skip|fixme)\s*\(/,
   /\bit\.skip\s*\(/,
   /\bdescribe\.skip\s*\(/,
   /\bxit\s*\(/,
@@ -73,8 +74,61 @@ const SKIP_PATTERNS = [
   /\bit\.todo\s*\(/,
 ];
 
-// Skip explanation patterns (comments that justify the skip)
-const SKIP_REASON_PATTERN = /\/\/\s*(REASON|SKIP|TODO|FIXME|NOTE|WHY)\s*:/i;
+// Reasons must contain text and belong to this call, not a neighboring test.
+const SKIP_REASON_PATTERN = /(?:REASON|SKIP|TODO|FIXME|NOTE|WHY)\s*:\s*\S/i;
+
+function hasAdjacentReason(content, call, comments) {
+  return comments.some(comment => {
+    if (!SKIP_REASON_PATTERN.test(comment.value)) return false;
+    if (comment.end <= call.start) {
+      // A trailing comment belongs to the preceding statement.
+      const lineStart = content.lastIndexOf('\n', comment.start - 1) + 1;
+      if (!/^\s*$/.test(content.slice(lineStart, comment.start))) return false;
+      const gap = content.slice(comment.end, call.start);
+      return call.loc.start.line - comment.loc.end.line <= 3 && /^\s*$/.test(gap);
+    }
+    if (comment.start >= call.end && comment.loc.start.line === call.loc.end.line) {
+      return /^[\s;]*$/.test(content.slice(call.end, comment.start));
+    }
+    return false;
+  });
+}
+
+function skippedCalls(content, filename) {
+  const { ast, ok } = parseJsTs(content, filename);
+  if (!ok || ast.errors?.length) return null;
+  const calls = [];
+  walk(ast, node => {
+    if (node.type !== 'CallExpression') return;
+    const callee = content.slice(node.callee.start, node.callee.end).replace(/\s/g, '');
+    if (!/^(?:(?:test(?:\.describe)?|it|describe)\.(?:skip|todo)|test\.fixme|xit|xdescribe|xtest)$/.test(callee)) return;
+    const [condition, reason] = node.arguments;
+    // Playwright's conditional overload takes a reason in argument two.
+    // A title followed by a callback is a declaration, not an explanation.
+    const explicitReason = /^(?:test\.skip|test\.fixme)$/.test(callee) &&
+      condition && condition.type !== 'StringLiteral' && condition.type !== 'TemplateLiteral' &&
+      (reason?.type === 'StringLiteral' && reason.value.trim().length > 0 ||
+        reason?.type === 'TemplateLiteral' && reason.expressions.length === 0 &&
+        reason.quasis.some(part => (part.value.cooked ?? part.value.raw).trim().length > 0));
+    calls.push({ line: node.loc.start.line, hasReason: Boolean(explicitReason) ||
+      hasAdjacentReason(content, node, ast.comments || []) });
+  });
+  return calls;
+}
+
+// Parser failure/unavailability cannot turn an unexplained skip into a pass.
+function fallbackSkippedCalls(content) {
+  const lines = content.split('\n');
+  const calls = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (!SKIP_PATTERNS.some(p => p.test(lines[i]))) continue;
+    // Only a directly preceding comment is unambiguous without a parser.
+    const previous = lines[i - 1] || '';
+    calls.push({ line: i + 1, hasReason: /^\s*\/\//.test(previous) &&
+      SKIP_REASON_PATTERN.test(previous) });
+  }
+  return calls;
+}
 
 /**
  * Main validator — checks for untracked TODOs and unexplained test skips.
@@ -139,29 +193,8 @@ function checkSkippedTests(projectDir, config) {
     const hasSkip = SKIP_PATTERNS.some(p => p.test(content));
     if (!hasSkip) continue;
 
-    const lines = content.split('\n');
-
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i];
-
-      // Check if this line has a test skip pattern
-      const isSkipped = SKIP_PATTERNS.some(p => p.test(line));
-      if (!isSkipped) continue;
-
-      // Check surrounding lines (3 above, 1 below, and inline) for explanation
-      // Developers commonly place block comments above the skip call
-      const surroundingLines = [];
-      for (let j = Math.max(0, i - 3); j <= Math.min(lines.length - 1, i + 1); j++) {
-        surroundingLines.push(lines[j]);
-      }
-
-      // Also check for block comment pattern: /* REASON: ... */ or /** ... REASON: ... */
-      const blockCommentPattern = /\/\*[\s\S]*?(REASON|SKIP|TODO|FIXME|NOTE|WHY)\s*:/i;
-
-      const hasReason =
-        surroundingLines.some(l => SKIP_REASON_PATTERN.test(l)) ||
-        blockCommentPattern.test(surroundingLines.join('\n'));
-
+    const calls = skippedCalls(content, relPath) ?? fallbackSkippedCalls(content);
+    for (const { line, hasReason } of calls) {
       if (hasReason) {
         skippedWithReason++;
       } else {
@@ -170,9 +203,9 @@ function checkSkippedTests(projectDir, config) {
           code: 'TDO001',
           validator: 'todoTracking',
           severity: 'warn',
-          message: `Skipped test without explanation at ${relPath}:${i + 1}. ` +
+          message: `Skipped test without explanation at ${relPath}:${line}. ` +
             `Add a // REASON: comment explaining why the test is skipped`,
-          location: `${relPath}:${i + 1}`,
+          location: `${relPath}:${line}`,
           suggestion: {
             kind: 'fix',
             text: 'Add a // REASON: comment on or up to 3 lines above the skip explaining why',

package/cli/validators/traceability.mjs

@@ -6,7 +6,7 @@
  *   2. Requirement Traceability (V-Model): Requirement IDs in docs trace to tests
  *
  * Requirement traceability is opt-in by convention — if no requirement IDs are
- * found (REQ-001, FR-001, etc.), the check silently passes. Once you add IDs,
+ * defined or explicitly annotated (REQ-001, FR-001, etc.), the check silently passes. Once you add IDs,
  * DocGuard automatically enforces traceability.
  *
  * Inspired by ISO/IEC/IEEE 29119, IEEE 1016, and V-Model methodology.
@@ -20,6 +20,7 @@ import { walkFiles as sharedWalkFiles, listCanonicalDocs } from '../shared-ignor
 import { mkFinding, resultFromFindings } from '../findings.mjs';
 import { tokenize } from '../shared-diff.mjs';
 import { rankBySimilarity } from '../shared-ir.mjs';
+import { parseJsTs, walk } from '../scanners/js-ast.mjs';
 
 /**
  * Optional graphify interop (github.com/Graphify-Labs/graphify, MIT).
@@ -71,13 +72,18 @@ function loadGraphifyDocLinks(projectDir) {
   }
 }
 
+// A test directory also contains fixtures and configuration. Only source files
+// are eligible for annotations or candidate-test similarity hints.
+function isTestSource(file) {
+  return /\.(?:[cm]?[jt]sx?|py|go|rs|java|kt|rb|php|sh)$/.test(file)
+    && (TEST_PATTERNS.some(pattern => pattern.test(file)) || /(?:^|\/)(?:__tests__|tests?)\//.test(file));
+}
+
 // IR soft-link recovery (feat 5): tokenize test files once so an untraced
 // requirement can be matched to the test that most likely already covers it
 // (TF-IDF cosine, VSM). Capped so a huge test suite can't blow up guard.
 function buildTestCorpus(projectDir, projectFiles, { maxFiles = 250, maxTokens = 400 } = {}) {
-  const testFiles = projectFiles.filter(f =>
-    TEST_PATTERNS.some(p => p.test(f)) || /__tests__\//.test(f) || /tests?\//.test(f)
-  ).slice(0, maxFiles);
+  const testFiles = projectFiles.filter(isTestSource).slice(0, maxFiles);
   const corpus = [];
   for (const relPath of testFiles) {
     try {
@@ -134,7 +140,7 @@ export function validateTraceability(projectDir, config) {
   let total = 0;
 
   const docsDir = resolve(projectDir, 'docs-canonical');
-  if (!existsSync(docsDir)) {
+  if (!existsSync(docsDir) && getRequirementDocPaths(projectDir, config).length === 0) {
     // No docs-canonical dir at all — structure validator handles this
     return resultFromFindings([], { passed: 0, total: 0 });
   }
@@ -166,9 +172,14 @@ export function validateTraceability(projectDir, config) {
     // Skip docs not in the user's required list
     if (!requiredDocs.has(docName)) continue;
 
-    total++;
-    const docPath = resolve(docsDir, docName);
+    const configuredPath = (config.requiredFiles?.canonical || []).find(file => basename(file) === docName);
+    const docPath = configuredPath && (configuredPath.includes('/') || existsSync(resolve(projectDir, configuredPath)))
+      ? resolve(projectDir, configuredPath) : resolve(docsDir, docName);
     const docExists = existsSync(docPath);
+    // Discovering feature specs must not activate missing-canonical findings
+    // for a repository without a canonical home. Structure owns that absence.
+    if (!existsSync(docsDir) && !docExists) continue;
+    total++;
 
     if (!docExists) {
       findings.push(mkFinding({
@@ -176,7 +187,7 @@ export function validateTraceability(projectDir, config) {
         validator: 'traceability',
         severity: 'warn',
         message: `${docName} — required but missing, no traceability possible`,
-        location: `docs-canonical/${docName}`,
+        location: relative(projectDir, docPath),
         suggestion: { kind: 'fix', text: 'Create the required doc from the professional template', command: 'docguard init' },
       }));
       continue;
@@ -220,7 +231,7 @@ export function validateTraceability(projectDir, config) {
         validator: 'traceability',
         severity: 'warn',
         message: `${docName} — exists but no matching source code found (unlinked doc)`,
-        location: `docs-canonical/${docName}`,
+        location: relative(projectDir, docPath),
         suggestion: {
           kind: 'fix',
           text: 'Link a source file explicitly with a header annotation if the code lives in a non-standard location',
@@ -237,7 +248,7 @@ export function validateTraceability(projectDir, config) {
   // 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)) {
+  for (const doc of listCanonicalDocs(projectDir, { config })) {
     const docFile = basename(doc.rel);
     if (!requiredDocs.has(docFile) && TRACE_MAP[docFile]) {
       findings.push(mkFinding({
@@ -266,7 +277,7 @@ export function validateTraceability(projectDir, config) {
  * Scan docs for requirement IDs and verify they appear in test files.
  *
  * Behavior:
- *   - If no requirement IDs found anywhere → silently passes (0 checks)
+ *   - If no definitions or test declarations exist → silently passes (0 checks)
  *   - If IDs found → validates each has a matching test reference
  *   - Reports untraced requirements and orphaned test refs
  */
@@ -284,11 +295,6 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
   // ── Step 1: Collect requirement IDs from documentation ──
   const reqIds = collectRequirementIds(projectDir, config, patterns);
 
-  // If no requirement IDs found, silently pass — this project doesn't use them
-  if (reqIds.size === 0) {
-    return { findings, passed, total };
-  }
-
   // ── Step 2: Scan test files for requirement ID references ──
   const testRefs = scanTestFilesForReferences(projectDir, projectFiles, patterns);
 
@@ -309,7 +315,7 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
     } else {
       // Try to recover a likely-but-unannotated test via TF-IDF cosine.
       let softHint = '';
-      let softText = `Add an @req ${reqId} comment to the test that verifies this requirement`;
+      let softText = `Review existing tests for this requirement. If a test verifies it, add an @req ${reqId} annotation or requirement ID test label; write a test only if behavioral coverage is actually missing.`;
       const queryText = location.text && location.text.length > reqId.length ? location.text : reqId;
       if (testCorpus === null) testCorpus = buildTestCorpus(projectDir, projectFiles);
       if (testCorpus.length > 0) {
@@ -318,16 +324,16 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
         if (top && top.score >= softThreshold) {
           const pct = (top.score * 100).toFixed(0);
           softHint = ` — IR soft-match: ${top.id} (${pct}% similar) may already cover it`;
-          softText = `${top.id} looks like it already tests this (${pct}% similar) — add @req ${reqId} there, or if unrelated, write the missing test`;
+          softText = `Review ${top.id} as a candidate (${pct}% text similarity, not coverage evidence). Add @req ${reqId} only if it verifies the requirement; otherwise inspect other tests before deciding a new test is needed.`;
         }
       }
       findings.push(mkFinding({
         code: 'TRC004',
         validator: 'traceability',
         severity: 'warn',
-        message: `Requirement ${reqId} (${location.file}:${location.line}) has no test coverage.${softHint || ' Add @req ' + reqId + ' comment to the test that verifies this requirement'}`,
+        message: `Requirement ${reqId} (${location.file}:${location.line}) has no recognized test annotation or label; behavioral coverage is unknown.${softHint}`,
         location: `${location.file}:${location.line}`,
-        suggestion: { kind: 'fix', text: softText },
+        suggestion: { kind: 'review', text: softText },
       }));
     }
   }
@@ -367,16 +373,53 @@ function collectRequirementIds(projectDir, config, patterns) {
     const lines = content.split('\n');
     const docName = relative(projectDir, docPath);
 
+    let fence = null;
+    let exampleLevel = null;
+    let inComment = false;
     for (let i = 0; i < lines.length; i++) {
+      let line = lines[i];
+      if (/^(?: {4}|\t)/.test(line) && !fence && !inComment) continue;
+      const marker = line.match(/^\s{0,3}(`{3,}|~{3,})/);
+      if (fence) {
+        if (marker && marker[1][0] === fence[0] && marker[1].length >= fence.length
+          && line.slice(marker[0].length).trim() === '') fence = null;
+        continue;
+      }
+      if (marker) { fence = marker[1]; continue; }
+      // Comments and fenced examples cannot define requirements. Preserve
+      // physical line numbers instead of scanning a compacted document.
+      line = line.replace(/<!--[\s\S]*?-->/g, '');
+      if (inComment) {
+        const close = line.indexOf('-->');
+        if (close < 0) continue;
+        line = line.slice(close + 3);
+        inComment = false;
+      }
+      const open = line.indexOf('<!--');
+      if (open >= 0) { line = line.slice(0, open); inComment = true; }
+      const heading = line.match(/^\s{0,3}(#{1,6})\s+(.*)/);
+      if (heading) {
+        if (exampleLevel !== null && heading[1].length <= exampleLevel) exampleLevel = null;
+        if (exampleLevel === null && /^(?:(?:requirement|task)[ -]+)?(?:examples?|ID[ -]+(?:formats?|syntax|examples?)|(?:formats?|syntax)[ -]+(?:of[ -]+)?IDs?)\b/i.test(heading[2])) {
+          exampleLevel = heading[1].length;
+        }
+      }
+      if (exampleLevel !== null) continue;
       for (const pattern of patterns) {
-        // Reset regex lastIndex for each line
         pattern.lastIndex = 0;
         let match;
-        while ((match = pattern.exec(lines[i])) !== null) {
-          const reqId = match[0]; // e.g., "REQ-001"
+        while ((match = pattern.exec(line)) !== null) {
+          // Definitions lead a line, heading, list item or first table cell.
+          // Later prose references must not satisfy a missing requirement ID.
+          const prefix = line.slice(0, match.index);
+          if (!/^\s{0,3}(?:#{1,6}\s+|[-*+]\s+(?:\[[ xX]\]\s+)?|\d+[.)]\s+|\|\s*)?[\s*`_]*$/.test(prefix)) {
+            if (!match[0].length) pattern.lastIndex++;
+            continue;
+          }
+          const reqId = match[0];
+          if (!reqId.length) { pattern.lastIndex++; continue; }
           if (!reqIds.has(reqId)) {
-            // capture the line text (the requirement description) for IR soft-match
-            reqIds.set(reqId, { file: docName, line: i + 1, text: lines[i].trim() });
+            reqIds.set(reqId, { file: docName, line: i + 1, text: line.trim() });
           }
         }
       }
@@ -386,12 +429,74 @@ function collectRequirementIds(projectDir, config, patterns) {
   return reqIds;
 }
 
+// A mention in fixture data is not a coverage declaration. Keep the same ID
+// patterns, but apply them only to annotations and test labels. In particular,
+// prose discussing an annotation ("never annotates @req ...") is not one.
+function testDeclarations(content, filename) {
+  const declarations = [];
+  const comment = (text, line) => {
+    for (const [offset, raw] of text.split('\n').entries()) {
+      const body = raw.replace(/^\s*\*?\s*/, '');
+      if (/^(?:@(?:req|task|covers)\s|Testing\s)/i.test(body)) {
+        declarations.push({ text: body, line: line + offset });
+      }
+    }
+  };
+  const labelName = /^(?:test|it|describe|context|specify|Run|DisplayName)$/;
+  const ext = extname(filename);
+  if (/^\.(?:[cm]?[jt]s|[jt]sx)$/.test(ext)) {
+    const { ast, ok } = parseJsTs(content, filename);
+    if (ok) {
+      for (const c of ast.comments || []) comment(c.value, c.loc.start.line);
+      const isLabelCall = (callee) => {
+        if (callee?.type === 'Identifier') return labelName.test(callee.name);
+        if (callee?.type !== 'MemberExpression' || callee.computed) return false;
+        return labelName.test(callee.property.name)
+          || (/^(?:only|skip|todo|concurrent|serial)$/.test(callee.property.name)
+            && isLabelCall(callee.object));
+      };
+      walk(ast.program, node => {
+        if (node.type !== 'CallExpression' || !isLabelCall(node.callee)) return;
+        const label = node.arguments[0];
+        if (label?.type === 'StringLiteral'
+          || (label?.type === 'TemplateLiteral' && label.expressions.length === 0)) {
+          // Scan source spelling to retain physical lines and custom patterns.
+          declarations.push({ text: content.slice(label.start + 1, label.end - 1), line: label.loc.start.line });
+        }
+      });
+      return declarations.sort((a, b) => a.line - b.line);
+    }
+  }
+
+  // Other languages, and JS/TS without the optional parser: lex comments and
+  // strings together so comment-like text inside a fixture stays opaque.
+  // This is deliberately a best-effort tier, like the multilingual scanners.
+  const tokens = /\/\*[\s\S]*?(?:\*\/|$)|\/\/[^\n]*|\#[^\n]*|"""[\s\S]*?(?:"""|$)|'''[\s\S]*?(?:'''|$)|"(?:\\[\s\S]|[^"\\])*"|'(?:\\[\s\S]|[^'\\])*'|`(?:\\[\s\S]|[^`\\])*`/g;
+  const hashComments = /\.(?:py|rb|php|sh)$/.test(ext);
+  let end = 0;
+  let line = 1;
+  let code = '';
+  for (const token of content.matchAll(tokens)) {
+    const gap = content.slice(end, token.index);
+    line += (gap.match(/\n/g) || []).length;
+    code += gap;
+    const text = token[0];
+    if (text.startsWith('//') || text.startsWith('/*') || (hashComments && text.startsWith('#'))) {
+      comment(text.replace(/^(?:\/\/|\/\*|#)/, ''), line);
+    } else if (/^["'`]/.test(text)
+      && /\b(?:test|it|describe|context|specify|Run|DisplayName)(?:\.(?:only|skip|todo|concurrent|serial))*\s*\(?\s*$/.test(code)) {
+      declarations.push({ text: text.slice(1, -1), line });
+    }
+    line += (text.match(/\n/g) || []).length;
+    // Strings must break a possible label prefix; comments are whitespace.
+    code = text.startsWith('/') || text.startsWith('#') ? code + ' ' : ';';
+    end = token.index + text.length;
+  }
+  return declarations;
+}
+
 function scanTestFilesForReferences(projectDir, projectFiles, patterns) {
-  const testFiles = projectFiles.filter(f =>
-    TEST_PATTERNS.some(p => p.test(f)) ||   // multilingual: JS/TS, Python, Go, Rust, Java/Kotlin, Ruby, PHP
-    /__tests__\//.test(f) ||
-    /tests?\//.test(f)
-  );
+  const testFiles = projectFiles.filter(isTestSource);
 
   const testRefs = new Map(); // reqId → [{ file, line }]
 
@@ -406,16 +511,16 @@ function scanTestFilesForReferences(projectDir, projectFiles, patterns) {
     const hasMatch = patterns.some(p => { p.lastIndex = 0; return p.test(content); });
     if (!hasMatch) continue;
 
-    const lines = content.split('\n');
-
-    for (let i = 0; i < lines.length; i++) {
+    for (const declaration of testDeclarations(content, relPath)) {
       for (const pattern of patterns) {
         pattern.lastIndex = 0;
         let match;
-        while ((match = pattern.exec(lines[i])) !== null) {
+        while ((match = pattern.exec(declaration.text)) !== null) {
+          if (!match[0]) { pattern.lastIndex++; continue; }
           const reqId = match[0];
           if (!testRefs.has(reqId)) testRefs.set(reqId, []);
-          testRefs.get(reqId).push({ file: relPath, line: i + 1 });
+          const line = declaration.line + (declaration.text.slice(0, match.index).match(/\n/g) || []).length;
+          testRefs.get(reqId).push({ file: relPath, line });
         }
       }
     }
@@ -434,7 +539,7 @@ function getRequirementDocPaths(projectDir, config) {
   // 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);
+  for (const doc of listCanonicalDocs(projectDir, { config })) paths.push(doc.abs);
 
   // Root-level docs
   const rootDocs = ['REQUIREMENTS.md', 'spec.md', 'README.md'];
@@ -444,10 +549,19 @@ function getRequirementDocPaths(projectDir, config) {
   }
 
   // User-configured requirement docs
-  const configDocs = config.traceability?.requirementDocs || [];
+  const configDocs = [...(config.requiredFiles?.canonical || []), ...(config.traceability?.requirementDocs || [])];
   for (const doc of configDocs) {
     const p = resolve(projectDir, doc);
-    if (existsSync(p) && !paths.includes(p)) paths.push(p);
+    const rel = relative(projectDir, p);
+    if (rel === '..' || rel.startsWith('../') || rel.split(/[\\/]/).includes('.local')) continue;
+    try {
+      if (statSync(p).isFile() && !paths.includes(p)) paths.push(p);
+      else if (statSync(p).isDirectory()) {
+        for (const entry of listCanonicalDocs(projectDir, { dirName: doc, config: {} })) {
+          if (!paths.includes(entry.abs)) paths.push(entry.abs);
+        }
+      }
+    } catch { /* Structural validators own missing or unreadable doc paths. */ }
   }
 
   // Spec Kit artifacts: .specify/specs/*/spec.md (v3+) and specs/*/spec.md (legacy)

package/docs/configuration.md

@@ -157,3 +157,44 @@ DocGuard auto-detects your project type from `package.json`:
 | `library` | ✗ | ✗ | ✗ | ✗ |
 | `webapp` | ✓ | ✓ | ✓ | ✓ |
 | `api` | ✓ | ✓ | ✗ | ✓ |
+
+## Existing documentation layouts
+
+Use explicit document roles to validate Markdown files in an existing layout. A mapping replaces the default path for that role, makes the mapped file required, and enrolls it in the canonical inventory. Missing files and content defects remain findings. No project names or framework-specific paths are required.
+
+```json
+{
+  "docs": {
+    "roles": {
+      "architecture": "docs/design.md",
+      "dataModel": "specs/data-model.md",
+      "environment": "operations/setup.md",
+      "apiReference": "reference/http.md"
+    }
+  }
+}
+```
+
+Supported roles are architecture, dataModel, security, testSpec, environment, apiReference, and requirements. Paths must name Markdown files within the project; private directories, parent traversal, absolute paths, and symlink destinations are rejected. Several roles may reference one document. Each role's content checks still apply; a mapping is not a correctness attestation. Default roles remain unchanged unless explicitly mapped.
+
+This first version supports validation, scoring, and read-only planning. Legacy automatic document generation, sync writes, and repair writes refuse custom mappings before scaffolding or modifying files. This protects existing documents while writer behavior is extended and reviewed. Read-only plans identify mapped destinations; a human or agent can review the proposed work against the existing document structure.
+
+The docs.dirs setting extends document inventory and explicitly opts additional directories into freshness review. Inventory membership does not mean every detector checks every file. Semantic extraction covers canonical Markdown, explicitly mapped Markdown roles, README, and AGENTS within its safety and size limits; other prose remains unverified.
+
+## Review signals and historical material
+
+Freshness findings describe repository-history review signals with low confidence. They do not establish semantic drift or instruct automatic rewriting. After reviewing the relevant intent and implementation, record a review date or propose the appropriate code/document change.
+
+Use an explicit historical, superseded, or deprecated status when a document records past decisions rather than current instructions:
+
+```markdown
+<!-- docguard:status historical -->
+```
+
+These statuses skip currentness assertions; they do not hide structural or other applicable findings. A filename containing ADR does not automatically exempt an active decision. Existing explicit validator/section exemptions continue to require reasons.
+
+## Understanding check coverage
+
+Guard JSON includes checkCoverage and an applicability record per validator. States distinguish checked, partial, disabled, not-applicable, missing-prerequisite, unsupported, no-matches, and error. A passing gate means the selected policy passed; it does not mean unsupported languages or unmatched inputs were examined. CI and reports preserve this disclosure. Python import-graph analysis remains unsupported; mixed Python/JS projects disclose partial architecture coverage.
+
+Wrangler configuration supplies evidence for Worker classification. Supported typed Worker bindings participate in environment extraction without executing configuration or application code. Dynamic names, alias/dataflow tracking, and unsupported forms remain outside this bounded analysis. The existing optional Babel parser resolves lexical bindings; the fallback covers ordinary tested scopes and has lower syntax coverage.

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

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.35.0"
+  version: "0.36.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"
@@ -76,8 +76,7 @@ provides:
 hooks:
   after_implement:
     command: "speckit.docguard.guard"
-    optional: true
-    prompt: "Run DocGuard validation after implementation?"
+    optional: false
     description: "Quality gate — ensures docs stay in sync with code"
 
   before_tasks:

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.35.0
+  version: 0.36.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.35.0 -->
+<!-- docguard:version: 0.36.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.35.0
+  version: 0.36.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.35.0 -->
+<!-- docguard:version: 0.36.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.35.0
+  version: 0.36.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.35.0 -->
+<!-- docguard:version: 0.36.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.35.0
+  version: 0.36.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.35.0 -->
+<!-- docguard:version: 0.36.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.35.0
+  version: 0.36.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.35.0 -->
+<!-- docguard:version: 0.36.0 -->
 
 # DocGuard Sync Skill
 

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

@@ -17,8 +17,7 @@ hooks:
       command: speckit.docguard.guard
       description: "Validate documentation passes CDD standards after implementation"
       enabled: true
-      optional: true
-      prompt: "Run DocGuard guard to verify documentation quality after implementation changes?"
+      optional: false
 
   # Run DocGuard review before /speckit.tasks to catch doc drift early
   before_tasks: