docguard-cli 0.35.0 → 0.36.1

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/README.md

@@ -1,13 +1,13 @@
 # DocGuard — CDD Enforcement Extension for Spec Kit
 
-Enterprise-grade Canonical-Driven Development (CDD) enforcement and **AI-readable project memory** for [Spec Kit](https://github.com/github/spec-kit). DocGuard builds a complete, language-aware documentation memory of any codebase (`generate --plan`), keeps it always up to date as code changes (`sync`), and verifies it (`guard`) — with deterministic mechanical fixes (`fix --write`) where it can and grounded agent prompts where prose is needed.
+Enterprise-grade Canonical-Driven Development (CDD) enforcement and **AI-readable project memory** for [Spec Kit](https://github.com/github/spec-kit). DocGuard builds source-derived documentation context for supported code (`generate --plan`), refreshes generated sections as code changes (`sync`), and checks configured rules (`guard`) — with deterministic mechanical fixes (`fix --write`) where it can and grounded agent prompts where prose is needed.
 
 ## Features
 
-- **24 Validators** — Structure, Security, Doc Quality, Test-Spec, Drift-Comments, API-Surface, Freshness, Cross-Reference, and 13 more
-- **Language-agnostic** — JS/TS, Python, Rust, Go, Java/Kotlin, Ruby, PHP, C#. Polyglot/monorepo-aware.
+- **Configurable validators** — Structure, Security, Doc Quality, Test-Spec, Drift-Comments, API-Surface, Freshness, Cross-Reference, and more; use `docguard --help` for the current surface
+- **Language-specific extraction** — Supported checks cover several languages and monorepos. Coverage varies by detector; unsupported inputs remain unverified.
 - **AI-powered Generate** — `generate --plan` builds the code-truth skeleton in `<!-- docguard:section -->` markers and emits a structured agent task manifest; the AI writes the prose.
-- **Always up to date** — `sync` surgically refreshes code-truth doc sections in place, **preserves human prose**, flags prose for agent review.
+- **Refresh and review** — `sync` surgically refreshes code-truth doc sections in place, **preserves human prose**, flags prose for agent review.
 - **Mechanical `fix --write`** — deterministic, no-LLM: remove stale documented endpoints, refresh stale "N validators" counts, replace stale version refs, insert missing `## [Unreleased]`.
 - **5 AI Skills** — docguard-fix, docguard-guard, docguard-sync, docguard-review, docguard-score (enterprise-grade behavior protocols, not just step-lists)
 - **Workflow Chaining** — YAML handoffs enable guard → sync → fix → review → score flows
@@ -20,7 +20,7 @@ Enterprise-grade Canonical-Driven Development (CDD) enforcement and **AI-readabl
 npm install -g docguard-cli
 ```
 
-Or use via npx:
+Spec Kit orchestration scripts require a local `node_modules/docguard-cli` installation or `docguard` on PATH; they do not implicitly download a CLI. Direct CLI use via npx remains available:
 ```bash
 npx docguard-cli guard
 ```
@@ -45,7 +45,7 @@ docguard score
 
 | Command | Alias | Purpose |
 |---------|-------|---------|
-| `speckit.docguard.guard` | `docguard.guard` | Run 19-validator quality gate with severity triage |
+| `speckit.docguard.guard` | `docguard.guard` | Run configurable quality gate with severity triage |
 | `speckit.docguard.fix` | `docguard.fix` | AI-driven documentation repair with codebase research |
 | `speckit.docguard.review` | `docguard.review` | Cross-document semantic consistency analysis (read-only) |
 | `speckit.docguard.score` | `docguard.score` | CDD maturity score with ROI improvement roadmap |

package/extensions/spec-kit-docguard/commands/sync.md

@@ -1,5 +1,5 @@
 ---
-description: Keep canonical docs always up to date — refresh code-truth sections in place, preserve human prose
+description: Refresh canonical code-truth sections and flag prose for review — refresh code-truth sections in place, preserve human prose
 allowed-tools: Bash, Read, Edit
 ---
 

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.1"
   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"
@@ -27,7 +27,7 @@ provides:
   commands:
     - name: "speckit.docguard.guard"
       file: "commands/guard.md"
-      description: "Run 19-validator quality gate with severity triage and remediation plan"
+      description: "Run configurable quality gate with severity triage and remediation plan"
 
     - name: "speckit.docguard.fix"
       file: "commands/generate.md"
@@ -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/scripts/bash/common.sh

@@ -23,25 +23,17 @@ find_docguard_root() {
 
 find_docguard_cli() {
     local root="${1:-$(pwd)}"
-    
-    # Check for local dev mode first
-    if [ -f "$root/cli/docguard.mjs" ]; then
-        echo "node $root/cli/docguard.mjs"
-        return 0
-    fi
-    
-    # Check for global install
-    if command -v docguard-cli >/dev/null 2>&1; then
-        echo "docguard-cli"
-        return 0
-    fi
-    
-    # Fall back to npx
-    if command -v npx >/dev/null 2>&1; then
-        echo "npx docguard-cli"
+    local entry
+    for entry in "$root/cli/docguard.mjs" "$root/node_modules/docguard-cli/cli/docguard.mjs"; do
+        if [ -f "$entry" ] && command -v node >/dev/null 2>&1; then
+            printf '%q %q\n' "$(command -v node)" "$entry"
+            return 0
+        fi
+    done
+    if command -v docguard >/dev/null 2>&1; then
+        printf '%q\n' "$(command -v docguard)"
         return 0
     fi
-    
     return 1
 }
 

package/extensions/spec-kit-docguard/scripts/bash/docguard-check-docs.sh

@@ -104,17 +104,24 @@ if $JSON_MODE; then
     # Optionally include score and guard
     EXTRAS=""
     if $VERBOSE; then
-        SCORE_OUTPUT=$(eval $CLI_CMD score --format json 2>/dev/null || echo "")
-        GUARD_OUTPUT=$(eval $CLI_CMD guard 2>&1 || true)
-        
-        # Extract score
-        SCORE=$(echo "$SCORE_OUTPUT" | grep -o '"total":[0-9]*' | head -1 | sed 's/"total"://' || echo "0")
-        
-        # Extract guard pass/total from output like "156/160 passed"
-        GUARD_PASS=$(echo "$GUARD_OUTPUT" | grep -o '[0-9]*/[0-9]* passed' | sed 's|/.*||' || echo "0")
-        GUARD_TOTAL=$(echo "$GUARD_OUTPUT" | grep -o '[0-9]*/[0-9]* passed' | sed 's|.*/||; s| .*||' || echo "0")
-        
-        EXTRAS=",\"score\":$SCORE,\"guardPass\":$GUARD_PASS,\"guardTotal\":$GUARD_TOTAL"
+        SCORE_OUTPUT=$(eval "$CLI_CMD score --format json")
+        SCORE=$(printf '%s' "$SCORE_OUTPUT" | node -e '
+          const d=JSON.parse(require("fs").readFileSync(0,"utf8"));
+          if(!Number.isFinite(d.score) || d.score<0 || d.score>100) throw Error("Invalid DocGuard score");
+          process.stdout.write(String(d.score));
+        ')
+        GUARD_STATUS=0
+        GUARD_OUTPUT=$(eval "$CLI_CMD guard --format json") || GUARD_STATUS=$?
+        EXTRAS=$(printf '%s' "$GUARD_OUTPUT" | node -e '
+          const d=JSON.parse(require("fs").readFileSync(0,"utf8"));
+          const exit=Number(process.argv[2]);
+          const expected={PASS:0,WARN:2,FAIL:1};
+          if(!Object.hasOwn(expected,d.status) || expected[d.status]!==exit ||
+             !Number.isInteger(d.passed) || !Number.isInteger(d.total) ||
+             d.passed<0 || d.total<d.passed) throw Error("Invalid DocGuard guard report");
+          const fields={score:Number(process.argv[1]),guardPass:d.passed,guardTotal:d.total,guardStatus:d.status};
+          process.stdout.write(","+JSON.stringify(fields).slice(1,-1));
+        ' "$SCORE" "$GUARD_STATUS")
     fi
     
     # Check for spec-kit