docguard-cli 0.36.1 → 0.37.0

package/cli/validators/traceability.mjs

@@ -15,12 +15,23 @@
 
 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 { TRACE_MAP, isTraceableSource } from '../shared-trace-patterns.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';
-import { parseJsTs, walk } from '../scanners/js-ast.mjs';
+import {
+  isTestSource,
+  resolveRequirementReferences as resolveRequirementReferencesShared,
+  scanTestFilesForReferences as scanTestFilesForReferencesShared,
+} from '../scanners/requirement-evidence.mjs';
+import {
+  DEFAULT_REQ_PATTERNS,
+  collectRequirementIdsFromContent,
+  requirementPatterns,
+} from '../shared-requirements.mjs';
+import { readRetirementManifest } from '../scanners/document-lifecycle.mjs';
+import { parseSpecId } from '../scanners/spec-registry.mjs';
 
 /**
  * Optional graphify interop (github.com/Graphify-Labs/graphify, MIT).
@@ -72,13 +83,6 @@ 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.
@@ -101,29 +105,6 @@ const IGNORE_DIRS = new Set([
 ]);
 
 
-// ──── Default requirement ID patterns ────
-// Users can override via config.traceability.requirementPattern
-// Includes spec-kit standard IDs: FR-xxx, SC-xxx, T-xxx
-const DEFAULT_REQ_PATTERNS = [
-  /\b(REQ)-(\d{2,4})\b/g,
-  /\b(FR)-(\d{2,4})\b/g,
-  /\b(NFR)-(\d{2,4})\b/g,
-  /\b(US)-(\d{2,4})\b/g,
-  /\b(STORY)-(\d{2,4})\b/g,
-  /\b(AC)-(\d{2,4})\b/g,
-  /\b(UC)-(\d{2,4})\b/g,
-  /\b(SYS)-(\d{2,4})\b/g,
-  /\b(ARCH)-(\d{2,4})\b/g,
-  /\b(MOD)-(\d{2,4})\b/g,
-  /\b(SC)-(\d{2,4})\b/g,     // Spec Kit: Success Criteria
-  // Spec Kit task IDs (T001, T002). Unlike the hyphenated IDs above, a bare
-  // `T350` over-matches prose (timeouts, model names, status codes), forcing
-  // spurious "untraced requirement" warnings. Anchor to the two contexts where
-  // a real task ID actually appears: a markdown checklist marker (`- [ ] T001`,
-  // the spec-kit tasks.md format) or a test annotation (`@req T001`/`@task`).
-  /(?<=\[[ xX]\]\s|@(?:req|task|covers)\s)(T)(\d{3,4})\b/g,
-];
-
 /**
  * Validate traceability — ensures canonical docs have corresponding source artifacts,
  * and requirement IDs trace through to test files.
@@ -287,16 +268,22 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
   let total = 0;
 
   // Get requirement patterns (user-configurable or defaults)
-  const customPattern = config.traceability?.requirementPattern;
-  const patterns = customPattern
-    ? [new RegExp(customPattern, 'g')]
-    : DEFAULT_REQ_PATTERNS;
+  const patterns = requirementPatterns(config);
 
   // ── Step 1: Collect requirement IDs from documentation ──
   const reqIds = collectRequirementIds(projectDir, config, patterns);
+  const retiredReqIds = loadRetiredRequirementIds(projectDir);
 
   // ── Step 2: Scan test files for requirement ID references ──
   const testRefs = scanTestFilesForReferences(projectDir, projectFiles, patterns);
+  const resolvedRefs = resolveRequirementReferences(reqIds, testRefs, retiredReqIds);
+  const definitionCounts = new Map();
+  for (const def of reqIds.values()) definitionCounts.set(def.id, (definitionCounts.get(def.id) || 0) + 1);
+  const retiredDefinitionCounts = new Map();
+  for (const key of retiredReqIds) {
+    const id = key.slice(key.lastIndexOf('#') + 1);
+    retiredDefinitionCounts.set(id, (retiredDefinitionCounts.get(id) || 0) + 1);
+  }
 
   // ── Step 3: Report traceability results ──
 
@@ -308,14 +295,15 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
   let testCorpus = null;
 
   // Check each documented requirement has at least one test reference
-  for (const [reqId, location] of reqIds) {
+  for (const [key, location] of reqIds) {
+    const reqId = location.id;
     total++;
-    if (testRefs.has(reqId)) {
+    if (resolvedRefs.has(key)) {
       passed++;
     } else {
       // Try to recover a likely-but-unannotated test via TF-IDF cosine.
       let softHint = '';
-      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.`;
+      let softText = `Review existing tests for this requirement. If a test verifies it, add an @req ${key} 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) {
@@ -324,14 +312,14 @@ 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 = `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.`;
+          softText = `Review ${top.id} as a candidate (${pct}% text similarity, not coverage evidence). Add @req ${key} 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 recognized test annotation or label; behavioral coverage is unknown.${softHint}`,
+        message: `Requirement ${reqId} (${location.file}:${location.line}) has no recognized test annotation or label; behavioral coverage is unknown.${definitionCounts.get(reqId) > 1 ? ` This ID occurs in multiple documents; use ${key} to disambiguate test references.` : ""}${softHint}`,
         location: `${location.file}:${location.line}`,
         suggestion: { kind: 'review', text: softText },
       }));
@@ -340,15 +328,18 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
 
   // Check for orphaned test refs (tests referencing non-existent requirements)
   for (const [reqId, refs] of testRefs) {
-    if (!reqIds.has(reqId)) {
+    const orphan = refs.find(ref => ref.scope
+      ? resolveRequirementReferences(reqIds, new Map([[reqId, [ref]]]), retiredReqIds).size === 0
+      : !definitionCounts.has(reqId) && !retiredDefinitionCounts.has(reqId));
+    if (orphan) {
       total++;
       findings.push(mkFinding({
         code: 'TRC005',
         validator: 'traceability',
         severity: 'warn',
-        message: `Test references ${reqId} (${refs[0].file}:${refs[0].line}) but no requirement ` +
+        message: `Test references ${orphan.scope ? `${orphan.scope}#` : ""}${reqId} (${orphan.file}:${orphan.line}) but no requirement ` +
           `with this ID exists in documentation. Remove the reference or add the requirement to docs`,
-        location: `${refs[0].file}:${refs[0].line}`,
+        location: `${orphan.file}:${orphan.line}`,
         suggestion: { kind: 'review', text: 'Remove the stale reference, or add the requirement to the documentation' },
       }));
     }
@@ -357,176 +348,59 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
   return { findings, passed, total };
 }
 
-function collectRequirementIds(projectDir, config, patterns) {
+/**
+ * Retired requirement identities remain known without restoring obsolete prose
+ * to active context. Invalid manifests supply no evidence; Document-Lifecycle
+ * reports their integrity failure separately.
+ */
+function loadRetiredRequirementIds(projectDir) {
+  const manifest = readRetirementManifest(projectDir);
+  if (!manifest.ok) return new Set();
+  const ids = new Set();
+  for (const entry of manifest.entries) {
+    if (!Array.isArray(entry.requirementIds)) continue;
+    const path = entry.path.replaceAll('\\', '/').replace(/^\.\//, '');
+    for (const id of entry.requirementIds) {
+      if (typeof id === 'string' && id.length <= 128 && /^[^\s#\0]+$/.test(id)) {
+        ids.add(`${path}#${id}`);
+      }
+    }
+  }
+  return ids;
+}
+
+export function collectRequirementIds(projectDir, config, patterns = DEFAULT_REQ_PATTERNS) {
   const reqIds = new Map(); // reqId → { file, line }
   const docSearchPaths = getRequirementDocPaths(projectDir, config);
 
   for (const docPath of docSearchPaths) {
     if (!existsSync(docPath)) continue;
 
+    const docName = relative(projectDir, docPath).replaceAll("\\", "/");
     const content = readFileSync(docPath, 'utf-8');
-
-    // Fast early-return: skip expensive string split if no requirement patterns exist
-    const hasMatch = patterns.some(p => { p.lastIndex = 0; return p.test(content); });
-    if (!hasMatch) continue;
-
-    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) {
-        pattern.lastIndex = 0;
-        let match;
-        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)) {
-            reqIds.set(reqId, { file: docName, line: i + 1, text: line.trim() });
-          }
-        }
-      }
+    const specId = parseSpecId(content);
+    for (const [key, definition] of collectRequirementIdsFromContent(content, docName, patterns)) {
+      if (!reqIds.has(key)) reqIds.set(key, { ...definition, specId });
     }
   }
 
   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;
+/** Resolve positive test links without sharing evidence between document scopes. */
+export function resolveRequirementReferences(definitions, references, retiredDefinitions = new Set()) {
+  return resolveRequirementReferencesShared(definitions, references, retiredDefinitions);
 }
 
-function scanTestFilesForReferences(projectDir, projectFiles, patterns) {
-  const testFiles = projectFiles.filter(isTestSource);
-
-  const testRefs = new Map(); // reqId → [{ file, line }]
-
-  for (const relPath of testFiles) {
-    const fullPath = resolve(projectDir, relPath);
-    if (!existsSync(fullPath)) continue;
-
-    let content;
-    try { content = readFileSync(fullPath, 'utf-8'); } catch { continue; }
-
-    // Fast early-return: skip expensive string split if no requirement patterns exist
-    const hasMatch = patterns.some(p => { p.lastIndex = 0; return p.test(content); });
-    if (!hasMatch) continue;
-
-    for (const declaration of testDeclarations(content, relPath)) {
-      for (const pattern of patterns) {
-        pattern.lastIndex = 0;
-        let match;
-        while ((match = pattern.exec(declaration.text)) !== null) {
-          if (!match[0]) { pattern.lastIndex++; continue; }
-          const reqId = match[0];
-          if (!testRefs.has(reqId)) testRefs.set(reqId, []);
-          const line = declaration.line + (declaration.text.slice(0, match.index).match(/\n/g) || []).length;
-          testRefs.get(reqId).push({ file: relPath, line });
-        }
-      }
-    }
-  }
-
-  return testRefs;
+/**
+ * Read explicit requirement annotations and test labels from eligible test sources.
+ * Shared by validation and feature scoring; fixture data is not linkage evidence.
+ * Callers supply project-relative candidate paths and global requirement regexes.
+ * No files are written and no findings or suppression policy are consulted.
+ * @returns {Map<string, Array<{file: string, line: number}>>} ID to declaration locations
+ */
+export function scanTestFilesForReferences(projectDir, projectFiles, patterns) {
+  return scanTestFilesForReferencesShared(projectDir, projectFiles, patterns);
 }
 
 /**

package/docs/ai-integration.md

@@ -107,6 +107,7 @@ and degrade gracefully on fork tokens and shallow clones.
 | `llms.txt` | `docguard llms` | Link index of the canonical docs ([llms.txt standard](https://llmstxt.org)) |
 | `llms-full.txt` | `docguard llms --full` | Full doc bodies inlined — one fetch, per-doc 400-line cap |
 | `.docguard/context-pack.md` | `docguard memory --pack` | Compact session-start context: guard status, scanner-derived surface counts, doc index with review dates, your AGENTS.md rules verbatim, known drift. Everything derived from code — regenerable, hallucination-free |
+| `.docguard-specs.json` | `docguard specs --check` / `--write` | Committed spec lifecycle index: reviewed status and lineage plus deterministic artifact, task, and requirement-scoped test evidence. Requirement prose stays in each authoritative spec. |
 
 Load the context pack at agent session start; regenerate any time — it is
 never hand-edited.
@@ -134,15 +135,18 @@ is the canonical source.
 ## The agent workflow
 
 ```
-diagnose → fix (research + write) → guard → verify --semantic → done
+specs preflight → diagnose → fix (research + write) → guard → verify --semantic → done
 ```
 
-1. **`docguard diagnose`** — one command that identifies everything, with
+1. **`docguard specs preflight`** — before specification, load the current intent
+   briefing. After a draft exists, rerun with `--path <spec.md>` and stop planning
+   on deterministic blockers. Review semantic overlap manually.
+2. **`docguard diagnose`** — one command that identifies everything, with
    AI-ready fix prompts (add `--format json` for structure).
-2. **`docguard fix --doc <name>`** — emits research steps + expected structure
+3. **`docguard fix --doc <name>`** — emits research steps + expected structure
    for one doc. Execute the research, write real content, no placeholders.
-3. **`docguard guard`** — verify. Loop until PASS.
-4. **`docguard verify --semantic`** — extract every checkable documented claim
+4. **`docguard guard`** — verify. Loop until PASS.
+5. **`docguard verify --semantic`** — extract every checkable documented claim
    (counts, limits, enums) with the nearest cited code path. **You** compare
    each value against the code: a green guard asserts structure, not the truth
    of documented numbers. This is the highest-value step an agent can run.
@@ -165,6 +169,15 @@ integrity. Each failing metric names its fix.
 
 ## Best practices for AI agents
 
+- Read `.docguard-specs.json` before opening prior planning documents. Follow
+  only entries whose reviewed context is `current`; tombstones preserve identity
+  and recovery without putting retired prose back into normal context.
+- Require `specId#requirementId` references for lifecycle evidence. A bare local
+  ID or a checked task cannot establish completion across a multi-spec project.
+- Run `docguard specs preflight` before drafting and
+  `docguard specs preflight --path <spec.md>` before planning. Treat deterministic
+  blockers as gates and similarity as review-only context.
+
 1. **MCP first** — native tools beat parsing CLI output.
 2. **Trust the codes** — every finding has a stable code; `explain` it before
    acting, suppress at the site with it, report false positives via `feedback`.

package/docs/commands.md

@@ -147,6 +147,51 @@ npx docguard-cli audit
 
 ---
 
+## Specification Lifecycle Commands
+
+### `docguard specs`
+
+**Maintain the committed spec lifecycle registry.** The registry keeps reviewed
+approval, delivery, context, lineage, and canonical-document scope separate from
+deterministically observed artifacts, task counts, and requirement-scoped test
+evidence.
+
+```bash
+npx docguard-cli specs --check                 # CI: registry must match the repository
+npx docguard-cli specs --write                 # Refresh observations; preserve reviewed fields
+npx docguard-cli specs preflight               # Brief prior intent before specification
+npx docguard-cli specs preflight --path specs/007-feature/spec.md
+```
+
+Every active spec needs a stable project-scoped metadata identity such as
+`Spec ID: acme.billing-export` near the top of the authoritative spec. Completion evidence uses
+`specId#requirementId`; bare `FR-001` references remain navigation hints because
+the same local ID commonly appears in several specs.
+
+The generated-spec preflight blocks missing or duplicate identity, stale
+registry state, unsafe paths, and broken lifecycle lineage. Text similarity is
+low-confidence review context and never blocks by itself. A future
+`specs complete` transaction will verify exact-revision implementation evidence,
+canonical outcomes, and context regeneration before marking a spec verified.
+
+### `docguard retire`
+
+**Remove reviewed stale documents from active AI context while preserving exact
+recovery metadata in Git.** Planning and checking are read-only; writing requires
+explicit paths and a reason.
+
+```bash
+npx docguard-cli retire --plan
+npx docguard-cli retire --check --format json
+npx docguard-cli retire --write --path docs/old-plan.md --reason "Superseded by current architecture"
+```
+
+Retirement fails closed for dirty, untracked, required, symlinked, private, or
+out-of-project content. Generic retirement also refuses active registered specs;
+their lifecycle must move through the dedicated `specs` control plane.
+
+---
+
 ## AI Integration Commands
 
 ### `docguard fix`

package/docs/configuration.md

@@ -198,3 +198,18 @@ These statuses skip currentness assertions; they do not hide structural or other
 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.
+
+### Evidence boundaries in documentation and schema scans
+
+Documentation-coverage filename checks search supported Markdown in conventional and explicitly configured homes, mapped role files, and supported extension metadata. Configured homes extend the defaults. Excluded files, private paths and symlinks cannot satisfy a documentation reference. This search does not establish absence of an explanation in external sites, RST, or unsupported formats.
+
+A parsed direct file-read/write call supplies stronger path evidence than a path construction or existence check. Ambiguous paths remain low-confidence review signals; a directory name alone does not establish a configuration file. The bounded detector does not resolve arbitrary import aliases or dynamic paths. Schema synchronization applies source exclusions and deduplicates overlapping roots by source file, preserving models in distinct files even when names match.
+
+Feature requirement scoring recognizes eligible test annotations and labels using the validator parser. An arbitrary fixture string is not linkage evidence, and a recognized link is not proof of behavioral coverage. Duplicate requirement IDs across separate specifications remain a known scoping limitation.
+
+
+### Requirement identity across documents
+
+Requirement definitions are identified by repository-relative document path plus ID. A bare test annotation such as `@req FR-001` earns linkage credit only when that ID is defined in one document. When features reuse an ID, qualify the declaration: `@req specs/payments/spec.md#FR-001`. The same spelling works in a test label. Use forward slashes; an optional leading `./` is accepted. Qualifiers are exact repository-relative paths, not paths relative to the test file.
+
+Validation and `trace --features` share definition parsing and reference resolution. A qualified reference credits only its target document. Ambiguous bare references credit neither feature and produce a review finding for each unresolved definition. A wrong qualifier is an orphan reference and never falls back to a bare match. Repeated mentions within one document do not create additional identities. Linkage remains evidence of a declaration, not proof of behavioral correctness; lifecycle and arbitrary verification-link semantics are separate concerns.

package/docs/quickstart.md

@@ -68,7 +68,7 @@ diagnose  →  AI reads prompts  →  AI fixes docs  →  guard verifies
 ## Verify
 
 ```bash
-npx docguard-cli guard        # Pass/fail check (27 validators)
+npx docguard-cli guard        # Pass/fail check (29 validators)
 npx docguard-cli score        # 0-100 maturity score
 ```
 

package/extensions/spec-kit-docguard/README.md

@@ -9,7 +9,7 @@ Enterprise-grade Canonical-Driven Development (CDD) enforcement and **AI-readabl
 - **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.
 - **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)
+- **5 AI Skills** — docguard-fix, docguard-guard, docguard-review, docguard-score, docguard-sync (enterprise-grade behavior protocols, not just step-lists)
 - **Workflow Chaining** — YAML handoffs enable guard → sync → fix → review → score flows
 - **Spec Kit Hooks** — Quality gate integrations at implement, tasks, and review phases
 - **Minimal Dependencies** — one pinned, optional-load parser (`@babel/parser`); Node.js built-ins otherwise
@@ -51,10 +51,12 @@ docguard score
 | `speckit.docguard.score` | `docguard.score` | CDD maturity score with ROI improvement roadmap |
 | `speckit.docguard.diagnose` | — | Diagnose issues + generate multi-perspective AI prompts |
 | `speckit.docguard.generate` | — | Reverse-engineer canonical docs from codebase |
+| `speckit.docguard.brief` | — | Load current spec intent before specification |
+| `speckit.docguard.preflight` | — | Gate the generated spec before task generation |
 
 ## AI Skills
 
-DocGuard provides 4 enterprise-grade AI behavior protocols modeled after Spec Kit's skill architecture:
+DocGuard provides 5 enterprise-grade AI behavior protocols modeled after Spec Kit's skill architecture:
 
 | Skill | Lines | What It Does |
 |-------|:-----:|-------------|
@@ -62,6 +64,7 @@ DocGuard provides 4 enterprise-grade AI behavior protocols modeled after Spec Ki
 | `docguard-fix` | 195 | 7-step research workflow with per-document codebase research, 3-iteration validation loops |
 | `docguard-review` | 170 | Semantic cross-document analysis with 6 analysis passes and quality scoring matrix |
 | `docguard-score` | 165 | CDD maturity assessment with ROI-based improvement roadmap and grade progression |
+| `docguard-sync` | — | Refresh code-truth sections while preserving human prose and routing it for review |
 
 Skills differ from commands in a critical way: **commands tell agents what to run** (step-lists), while **skills tell agents how to think, validate, and iterate** (behavior protocols).
 
@@ -73,14 +76,21 @@ DocGuard integrates into the spec-kit workflow through hooks:
 
 ```yaml
 hooks:
-  after_implement:   # Optional — quality gate after /speckit.implement
+  before_specify:    # Mandatory — read current spec intent first
+    command: speckit.docguard.brief
+  after_implement:   # Mandatory — quality gate after /speckit.implement
     command: speckit.docguard.guard
-  before_tasks:      # Optional — review docs before task generation
-    command: speckit.docguard.review
+  before_tasks:      # Mandatory — gate the generated spec
+    command: speckit.docguard.preflight
   after_tasks:       # Optional — show score after tasks
     command: speckit.docguard.score
 ```
 
+The hooks call the deterministic CLI contract. The pre-specification hook emits
+a current-intent briefing; the pre-task hook checks the actual generated spec.
+Spec Kit dispatches the hooks through its agent workflow, while
+`docguard specs --check` remains the CI enforcement surface.
+
 ### Workflow Chaining
 
 All commands support YAML handoffs for seamless workflow chaining:

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

@@ -0,0 +1,34 @@
+---
+description: "Load current spec intent and lifecycle before creating a new specification"
+allowed-tools: Bash, Read
+---
+
+# DocGuard Spec Briefing
+
+Read the committed spec lifecycle registry before creating a new specification.
+This command is a deterministic history gate. It does not decide whether two
+features are semantically equivalent.
+
+## Execution
+
+1. Run the read-only briefing:
+
+```bash
+npx --yes docguard-cli@latest specs preflight --format json
+```
+
+2. If the result is `BLOCKED`, stop specification work. Report every blocker and
+   refresh or repair the registry before continuing. A missing registry is valid
+   only when the project has no prior specs.
+
+3. If the result is `BRIEFING`, read each current spec named in `briefing` before
+   drafting the new behavior. Treat approval, delivery, task counts, and test
+   evidence as separate signals. None of them alone proves that behavior exists.
+
+4. Carry relevant immutable spec IDs and explicit lineage into the draft. Do not
+   copy prior requirement prose into the registry or infer completion from a
+   checkbox.
+
+## User Input
+
+$ARGUMENTS

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

@@ -0,0 +1,52 @@
+---
+description: "Gate a generated specification against registry integrity and prior intent"
+allowed-tools: Bash, Read, Edit
+---
+
+# DocGuard Generated-Spec Preflight
+
+Run after the specification exists and before planning or task generation. The
+generated draft is the reviewable artifact that DocGuard can gate.
+
+## User Input
+
+$ARGUMENTS
+
+## Execution
+
+1. Resolve the current feature's `spec.md`. Use an explicit path from the user
+   when supplied. Otherwise use the current Spec Kit feature directory; its
+   prerequisite script reports `FEATURE_DIR` in JSON. Use the platform-specific
+   script under `.specify/scripts/` and append `/spec.md`.
+
+2. Confirm the draft declares a stable metadata field near the top:
+
+```markdown
+**Spec ID**: `organization.feature-name`
+```
+
+   Add a project-scoped lowercase ID when it is missing. Never reuse an ID from
+   the briefing, even when an old spec has moved to Git history.
+
+3. Run the read-only generated-spec gate:
+
+```bash
+npx --yes docguard-cli@latest specs preflight --path <feature-spec.md> --format json
+```
+
+4. If the result is `BLOCKED`, stop before task generation. Fix duplicate or
+   missing identity, broken lineage, unsafe paths, or stale registry state, then
+   rerun the same command.
+
+5. Review `overlaps` manually. Similarity has low confidence and never blocks by
+   itself. Record a reviewed `extends`, `duplicates`, `conflictsWith`,
+   `supersedes`, or `supersededBy` relation only when the underlying intent
+   supports it.
+
+6. Continue only when the deterministic status is `READY`. Refresh the registry
+   after the draft is accepted so CI observes its current digest and requirement
+   identities:
+
+```bash
+npx --yes docguard-cli@latest specs --write
+```