docguard-cli 0.36.2 → 0.37.1

package/cli/validators/spec-registry.mjs

@@ -0,0 +1,47 @@
+import { mkFinding, resultFromFindings } from '../findings.mjs';
+import { projectSpecRegistry, SPEC_REGISTRY_PATH } from '../scanners/spec-registry.mjs';
+
+export function validateSpecRegistry(projectDir, config = {}) {
+  const projection = projectSpecRegistry(projectDir, config);
+  if (projection.detected === 0 && !projection.exists) {
+    return resultFromFindings([], { passed: 0, total: 0, applicable: false });
+  }
+  const findings = projection.issues.map(issue => mkFinding({
+    code: issue.code,
+    validator: 'specRegistry',
+    severity: 'warn',
+    confidence: 'high',
+    message: issue.message,
+    location: issue.path,
+    suggestion: {
+      kind: 'review',
+      text: issue.code === 'SPR002'
+        ? 'Assign a unique immutable Spec ID in the authoritative spec metadata.'
+        : 'Resolve the lifecycle or registry integrity conflict, then refresh the registry.',
+      command: 'docguard specs --write',
+    },
+  }));
+  if (!projection.current && projection.issues.length === 0) {
+    findings.push(mkFinding({
+      code: 'SPR001',
+      validator: 'specRegistry',
+      severity: 'warn',
+      confidence: 'high',
+      message: projection.exists
+        ? `${SPEC_REGISTRY_PATH} does not match the current deterministic spec evidence projection.`
+        : `${SPEC_REGISTRY_PATH} is missing while active specifications exist.`,
+      location: SPEC_REGISTRY_PATH,
+      suggestion: {
+        kind: 'fix',
+        text: 'Refresh derived evidence without changing reviewed lifecycle fields.',
+        command: 'docguard specs --write',
+      },
+    }));
+  }
+  const checks = Math.max(1, projection.registry.specs.length + projection.registry.tombstones.length);
+  return resultFromFindings(findings, {
+    passed: Math.max(0, checks - findings.length),
+    total: checks,
+    applicable: true,
+  });
+}

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,19 +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);
+  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 ──
 
@@ -344,7 +328,9 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
 
   // Check for orphaned test refs (tests referencing non-existent requirements)
   for (const [reqId, refs] of testRefs) {
-    const orphan = refs.find(ref => ref.scope ? !reqIds.has(`${ref.scope}#${reqId}`) : !definitionCounts.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({
@@ -362,6 +348,27 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
   return { findings, passed, total };
 }
 
+/**
+ * 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);
@@ -369,66 +376,11 @@ export function collectRequirementIds(projectDir, config, patterns = DEFAULT_REQ
   for (const docPath of docSearchPaths) {
     if (!existsSync(docPath)) continue;
 
-    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).replaceAll("\\", "/");
-
-    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; }
-          const key = `${docName}#${reqId}`;
-          if (!reqIds.has(key)) {
-            reqIds.set(key, { id: reqId, file: docName, line: i + 1, text: line.trim() });
-          }
-        }
-      }
+    const content = readFileSync(docPath, 'utf-8');
+    const specId = parseSpecId(content);
+    for (const [key, definition] of collectRequirementIdsFromContent(content, docName, patterns)) {
+      if (!reqIds.has(key)) reqIds.set(key, { ...definition, specId });
     }
   }
 
@@ -436,89 +388,8 @@ export function collectRequirementIds(projectDir, config, patterns = DEFAULT_REQ
 }
 
 /** Resolve positive test links without sharing evidence between document scopes. */
-export function resolveRequirementReferences(definitions, references) {
-  const byId = new Map();
-  for (const [key, definition] of definitions) {
-    if (!byId.has(definition.id)) byId.set(definition.id, []);
-    byId.get(definition.id).push(key);
-  }
-  const resolved = new Map();
-  for (const [id, refs] of references) {
-    const candidates = byId.get(id) || [];
-    for (const ref of refs) {
-      const key = ref.scope ? `${ref.scope}#${id}` : candidates.length === 1 ? candidates[0] : null;
-      if (!key || !definitions.has(key)) continue;
-      if (!resolved.has(key)) resolved.set(key, []);
-      resolved.get(key).push(ref);
-    }
-  }
-  return resolved;
-}
-
-// 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;
+export function resolveRequirementReferences(definitions, references, retiredDefinitions = new Set()) {
+  return resolveRequirementReferencesShared(definitions, references, retiredDefinitions);
 }
 
 /**
@@ -529,42 +400,7 @@ function testDeclarations(content, filename) {
  * @returns {Map<string, Array<{file: string, line: number}>>} ID to declaration locations
  */
 export 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;
-          // A document qualifier is repository-relative and exact; never fall
-          // back to a bare ID when a supplied qualifier fails to resolve.
-          const prefix = declaration.text.slice(0, match.index);
-          const qualifier = prefix.match(/([^\s`"'<>()[\]{}]+)#$/);
-          const scope = qualifier ? qualifier[1].replaceAll('\\', '/').replace(/^\.\//, '') : null;
-          testRefs.get(reqId).push({ file: relPath, line, scope });
-        }
-      }
-    }
-  }
-
-  return testRefs;
+  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/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
+```