docguard-cli 0.8.2 → 0.9.0

package/README.md

@@ -223,13 +223,13 @@ $ npx docguard-cli guard
 
 ---
 
-## 14 Validators
+## 19 Validators
 
 | # | Validator | What It Checks | Default |
 |---|-----------|---------------|---------| 
 | 1 | **Structure** | Required CDD files exist | ✅ On |
 | 2 | **Doc Sections** | Canonical docs have required sections | ✅ On |
-| 3 | **Docs-Sync** | Routes/services referenced in docs | ✅ On |
+| 3 | **Docs-Sync** | Routes/services referenced in docs + OpenAPI cross-check | ✅ On |
 | 4 | **Drift** | `// DRIFT:` comments logged in DRIFT-LOG.md | ✅ On |
 | 5 | **Changelog** | CHANGELOG.md has [Unreleased] section | ✅ On |
 | 6 | **Test-Spec** | Tests exist per TEST-SPEC.md rules | ✅ On |
@@ -237,16 +237,19 @@ $ npx docguard-cli guard
 | 8 | **Security** | No hardcoded secrets in source code | ✅ On |
 | 9 | **Architecture** | Imports follow layer boundaries | ✅ On |
 | 10 | **Freshness** | Docs not stale relative to code changes | ✅ On |
-| 11 | **Traceability** | Canonical docs linked to source code | ✅ On |
+| 11 | **Traceability** | Canonical docs linked to source + V-Model requirement IDs | ✅ On |
 | 12 | **Docs-Diff** | Code artifacts match documented entities | ✅ On |
 | 13 | **Metadata-Sync** | Version refs consistent across docs | ✅ On |
 | 14 | **Docs-Coverage** | Code features referenced in documentation | ✅ On |
 | 15 | **Metrics-Consistency** | Hardcoded numbers match actual counts | ✅ On |
-| 16 | **Docs-Sync** | Source files have matching doc entries | ✅ On |
+| 16 | **Doc-Quality** | Writing quality (readability, passive voice, atomicity) | ✅ On |
+| 17 | **TODO-Tracking** | Untracked TODOs/FIXMEs and skipped tests | ✅ On |
+| 18 | **Schema-Sync** | Database models documented in DATA-MODEL.md | ✅ On |
+| 19 | **Spec-Kit** | GitHub Spec Kit artifact detection and CDD mapping | ✅ On |
 
 ---
 
-## 16 Templates
+## 18 Templates
 
 Every template includes professional metadata: `docguard:version`, `docguard:status`, badges, and revision history.
 
@@ -260,6 +263,7 @@ Every template includes professional metadata: `docguard:version`, `docguard:sta
 | DEPLOYMENT.md | Canonical | Infrastructure, CI/CD, DNS |
 | ADR.md | Canonical | Architecture Decision Records |
 | ROADMAP.md | Canonical | Project phases, feature tracking |
+| REQUIREMENTS.md | Canonical | Requirement IDs, V-Model traceability |
 | KNOWN-GOTCHAS.md | Implementation | Symptom/gotcha/fix entries |
 | TROUBLESHOOTING.md | Implementation | Error diagnosis guides |
 | RUNBOOKS.md | Implementation | Operational procedures |
@@ -268,6 +272,7 @@ Every template includes professional metadata: `docguard:version`, `docguard:sta
 | AGENTS.md | Agent | AI agent behavior rules |
 | CHANGELOG.md | Tracking | Change log |
 | DRIFT-LOG.md | Tracking | Deviation tracking |
+| llms.txt | Generated | AI-friendly project summary (llmstxt.org) |
 
 ---
 
@@ -280,7 +285,8 @@ your-project/
 │   ├── DATA-MODEL.md            # Database schemas, entity relationships
 │   ├── SECURITY.md              # Auth, permissions, secrets
 │   ├── TEST-SPEC.md             # Required tests, coverage rules
-│   └── ENVIRONMENT.md           # Environment variables, setup
+│   ├── ENVIRONMENT.md           # Environment variables, setup
+│   └── REQUIREMENTS.md          # Requirement IDs, V-Model traceability
 │
 ├── docs-implementation/         # Current state (optional)
 │   ├── KNOWN-GOTCHAS.md         # Lessons learned
@@ -291,6 +297,7 @@ your-project/
 ├── AGENTS.md                    # AI agent behavior rules
 ├── CHANGELOG.md                 # Change tracking
 ├── DRIFT-LOG.md                 # Documented deviations
+├── llms.txt                     # AI-friendly project summary
 └── .docguard.json              # DocGuard configuration
 ```
 

package/cli/commands/guard.mjs

@@ -22,6 +22,10 @@ import { validateDocsDiff } from '../validators/docs-diff.mjs';
 import { validateMetadataSync } from '../validators/metadata-sync.mjs';
 import { validateMetricsConsistency } from '../validators/metrics-consistency.mjs';
 import { validateDocsCoverage } from '../validators/docs-coverage.mjs';
+import { validateDocQuality } from '../validators/doc-quality.mjs';
+import { validateTodoTracking } from '../validators/todo-tracking.mjs';
+import { validateSchemaSync } from '../validators/schema-sync.mjs';
+import { validateSpecKitIntegration } from '../scanners/speckit.mjs';
 
 /**
  * Internal guard — returns structured data, no console output, no process.exit.
@@ -57,6 +61,10 @@ export function runGuardInternal(projectDir, config) {
     { key: 'docsDiff', name: 'Docs-Diff', fn: () => validateDocsDiff(projectDir, config) },
     { key: 'metadataSync', name: 'Metadata-Sync', fn: () => validateMetadataSync(projectDir, config) },
     { key: 'docsCoverage', name: 'Docs-Coverage', fn: () => validateDocsCoverage(projectDir, config) },
+    { key: 'docQuality', name: 'Doc-Quality', fn: () => validateDocQuality(projectDir, config) },
+    { key: 'todoTracking', name: 'TODO-Tracking', fn: () => validateTodoTracking(projectDir, config) },
+    { key: 'schemaSync', name: 'Schema-Sync', fn: () => validateSchemaSync(projectDir, config) },
+    { key: 'specKit', name: 'Spec-Kit', fn: () => validateSpecKitIntegration(projectDir, config) },
     // Metrics-Consistency runs post-loop (needs guard results)
   ];
 

package/cli/commands/llms.mjs

@@ -0,0 +1,159 @@
+/**
+ * llms Command — Generate llms.txt from canonical documentation
+ *
+ * llms.txt is a proposed standard (Jeremy Howard, Answer.AI, 2024) for providing
+ * AI-friendly content summaries at a project root. This command generates it
+ * from existing canonical docs.
+ *
+ * Usage:
+ *   docguard llms                 — Generate/regenerate llms.txt
+ *   docguard llms --stdout        — Print to stdout instead of file
+ *
+ * Integration:
+ *   - `docguard init` includes llms.txt in standard template
+ *   - `docguard generate` auto-regenerates llms.txt
+ *   - `docguard guard` validates llms.txt exists and is current
+ */
+
+import { existsSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { resolve, join, basename } from 'node:path';
+import { c } from '../shared.mjs';
+
+// ──── Doc descriptions for llms.txt ────
+const DOC_DESCRIPTIONS = {
+  'ARCHITECTURE.md': 'System architecture, component boundaries, and tech stack',
+  'DATA-MODEL.md': 'Database schemas, entity relationships, and data flow',
+  'SECURITY.md': 'Authentication, authorization, secrets management, and security policies',
+  'TEST-SPEC.md': 'Test coverage requirements, testing strategy, and quality rules',
+  'ENVIRONMENT.md': 'Setup instructions, environment variables, and prerequisites',
+  'API-REFERENCE.md': 'API endpoints, request/response formats, and integration docs',
+  'DEPLOYMENT.md': 'Deployment procedures, CI/CD pipelines, and infrastructure',
+  'MONITORING.md': 'Observability, logging, alerting, and health checks',
+  'PERFORMANCE.md': 'Performance requirements, benchmarks, and optimization',
+  'ACCESSIBILITY.md': 'WCAG compliance, accessibility standards, and testing',
+};
+
+const OPTIONAL_DOCS = {
+  'DRIFT-LOG.md': 'Known deviations from canonical documentation',
+  'CHANGELOG.md': 'Version history and release notes',
+  'ROADMAP.md': 'Planned features and development roadmap',
+  'REQUIREMENTS.md': 'Tracked requirements with traceability IDs',
+  'AGENTS.md': 'AI agent behavior rules and workflow instructions',
+  'CURRENT-STATE.md': 'Current implementation status and known issues',
+};
+
+/**
+ * Generate llms.txt content from project docs.
+ */
+export function generateLlmsTxt(projectDir, config) {
+  const lines = [];
+
+  // ── Header ──
+  const projectName = config.projectName || basename(projectDir);
+  const description = getProjectDescription(projectDir);
+
+  lines.push(`# ${projectName}`);
+  if (description) {
+    lines.push(`> ${description}`);
+  }
+  lines.push('');
+
+  // ── Canonical Docs ──
+  const docsDir = resolve(projectDir, 'docs-canonical');
+  const existingDocs = [];
+
+  if (existsSync(docsDir)) {
+    try {
+      const entries = readdirSync(docsDir).filter(f => f.endsWith('.md')).sort();
+      for (const entry of entries) {
+        const desc = DOC_DESCRIPTIONS[entry] || `${entry.replace('.md', '')} documentation`;
+        existingDocs.push({ path: `docs-canonical/${entry}`, name: entry, desc });
+      }
+    } catch { /* ignore */ }
+  }
+
+  if (existingDocs.length > 0) {
+    lines.push('## Docs');
+    lines.push('');
+    for (const doc of existingDocs) {
+      lines.push(`- [${doc.name.replace('.md', '')}](${doc.path}): ${doc.desc}`);
+    }
+    lines.push('');
+  }
+
+  // ── Optional Docs ──
+  const optionalFound = [];
+  for (const [file, desc] of Object.entries(OPTIONAL_DOCS)) {
+    if (existsSync(resolve(projectDir, file))) {
+      optionalFound.push({ path: file, name: file, desc });
+    }
+  }
+
+  if (optionalFound.length > 0) {
+    lines.push('## Optional');
+    lines.push('');
+    for (const doc of optionalFound) {
+      lines.push(`- [${doc.name.replace('.md', '')}](${doc.path}): ${doc.desc}`);
+    }
+    lines.push('');
+  }
+
+  // ── Footer ──
+  lines.push('---');
+  lines.push(`Generated by DocGuard v${config.version || 'unknown'} | [docguard-cli](https://www.npmjs.com/package/docguard-cli)`);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Get project description from package.json or ARCHITECTURE.md.
+ */
+function getProjectDescription(projectDir) {
+  // Try package.json first
+  const pkgPath = resolve(projectDir, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      if (pkg.description) return pkg.description;
+    } catch { /* ignore */ }
+  }
+
+  // Try ARCHITECTURE.md first line after the header
+  const archPath = resolve(projectDir, 'docs-canonical', 'ARCHITECTURE.md');
+  if (existsSync(archPath)) {
+    try {
+      const content = readFileSync(archPath, 'utf-8');
+      const lines = content.split('\n');
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed && !trimmed.startsWith('#') && !trimmed.startsWith('|') && !trimmed.startsWith('-')) {
+          return trimmed.substring(0, 200);
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  return null;
+}
+
+/**
+ * Public command — generate llms.txt file.
+ */
+export function runLlms(projectDir, config, flags) {
+  const content = generateLlmsTxt(projectDir, config);
+
+  if (flags.stdout) {
+    console.log(content);
+    return;
+  }
+
+  const outputPath = resolve(projectDir, 'llms.txt');
+  writeFileSync(outputPath, content, 'utf-8');
+
+  console.log(`${c.bold}📄 DocGuard llms.txt Generator${c.reset}`);
+  console.log(`${c.green}✅ Generated ${outputPath}${c.reset}`);
+  console.log(`${c.dim}   Standard: llms.txt (Jeremy Howard, Answer.AI, 2024)${c.reset}`);
+  console.log(`${c.dim}   DocGuard keeps this in sync with your canonical docs.${c.reset}`);
+  console.log('');
+}

package/cli/commands/score.mjs

@@ -131,6 +131,30 @@ export function runScore(projectDir, config, flags) {
     console.log(`  ${c.dim}Methodology: CJE multi-signal composite (Lopez et al., TRACE, IEEE TMLCN 2026)${c.reset}\n`);
   }
 
+  // ── ALCOA+ Compliance Scoring ──
+  // Maps existing validators to the 9 ALCOA+ attributes (FDA data integrity framework)
+  // Always shown — gives enterprise positioning value
+  const alcoa = computeAlcoaCompliance(projectDir, config, scores);
+
+  console.log(`  ${c.bold}🏛️  ALCOA+ Compliance${c.reset} ${c.dim}(FDA Data Integrity Framework)${c.reset}`);
+  console.log(`  ${c.dim}─────────────────────────────────${c.reset}`);
+
+  for (const attr of alcoa.attributes) {
+    const icon = attr.met ? `${c.green}✅` : `${c.yellow}⚠️`;
+    const status = attr.met ? `${c.green}${attr.evidence}` : `${c.yellow}${attr.gap}`;
+    console.log(`  ${icon} ${attr.name.padEnd(16)}${c.reset} — ${status}${c.reset}`);
+    if (!attr.met && attr.fix) {
+      console.log(`  ${c.dim}     Fix: ${attr.fix}${c.reset}`);
+    }
+  }
+
+  const alcoaColor = alcoa.score >= 78 ? c.green : alcoa.score >= 56 ? c.yellow : c.red;
+  console.log(`\n  ${alcoaColor}${c.bold}ALCOA+ Score: ${alcoa.score}% (${alcoa.met}/${alcoa.total} attributes)${c.reset}`);
+  if (alcoa.met < alcoa.total) {
+    console.log(`  ${c.dim}${alcoa.total - alcoa.met} action(s) needed for full compliance${c.reset}`);
+  }
+  console.log('');
+
   // Badge snippet
   const bColor = totalScore >= 90 ? 'brightgreen' : totalScore >= 80 ? 'green' : totalScore >= 70 ? 'yellowgreen' : totalScore >= 60 ? 'yellow' : totalScore >= 50 ? 'orange' : 'red';
   const badgeUrl = `https://img.shields.io/badge/CDD_Score-${totalScore}%2F100_(${grade})-${bColor}`;
@@ -146,6 +170,144 @@ export function runScoreInternal(projectDir, config) {
   return { score: totalScore, grade, categories: scores };
 }
 
+/**
+ * ALCOA+ Compliance Scoring
+ *
+ * Maps DocGuard's existing validators to the 9 ALCOA+ attributes
+ * (FDA 21 CFR Part 11 / EMA Annex 11 data integrity framework).
+ *
+ * ALCOA+ = Attributable, Legible, Contemporaneous, Original, Accurate
+ *        + Complete, Consistent, Enduring, Available
+ *
+ * Reference: WHO Technical Report Series, No. 996, 2016, Annex 5
+ */
+function computeAlcoaCompliance(projectDir, config, scores) {
+  const attributes = [];
+
+  // 1. Attributable — Can we trace who wrote/reviewed docs?
+  const hasGit = existsSync(resolve(projectDir, '.git'));
+  const docsDir = resolve(projectDir, 'docs-canonical');
+  let hasReviewedMeta = false;
+  if (existsSync(docsDir)) {
+    try {
+      const docs = readdirSync(docsDir).filter(f => f.endsWith('.md'));
+      for (const doc of docs) {
+        const content = readFileSync(join(docsDir, doc), 'utf-8');
+        if (content.includes('docguard:last-reviewed') || content.includes('last-reviewed')) {
+          hasReviewedMeta = true;
+          break;
+        }
+      }
+    } catch { /* ignore */ }
+  }
+  attributes.push({
+    name: 'Attributable',
+    met: hasGit,
+    evidence: hasGit ? `Git authorship found${hasReviewedMeta ? ', review metadata present' : ''}` : null,
+    gap: !hasGit ? 'No version control found' : null,
+    fix: !hasGit ? 'Initialize git repository: git init' : null,
+  });
+
+  // 2. Legible — Are docs readable and well-written?
+  const legible = scores.docQuality >= 60;
+  attributes.push({
+    name: 'Legible',
+    met: legible,
+    evidence: legible ? `Doc quality score: ${scores.docQuality}% (readable)` : null,
+    gap: !legible ? `Doc quality score: ${scores.docQuality}% (needs improvement)` : null,
+    fix: !legible ? 'Run docguard diagnose for specific readability improvements' : null,
+  });
+
+  // 3. Contemporaneous — Are docs kept current?
+  let freshnessMet = true;
+  if (existsSync(docsDir)) {
+    try {
+      const docs = readdirSync(docsDir).filter(f => f.endsWith('.md'));
+      for (const doc of docs) {
+        const stat_ = statSync(join(docsDir, doc));
+        const daysSinceModified = (Date.now() - stat_.mtimeMs) / (1000 * 60 * 60 * 24);
+        if (daysSinceModified > 30) {
+          freshnessMet = false;
+          break;
+        }
+      }
+    } catch { /* ignore */ }
+  }
+  attributes.push({
+    name: 'Contemporaneous',
+    met: freshnessMet,
+    evidence: freshnessMet ? 'All docs updated within 30 days' : null,
+    gap: !freshnessMet ? 'Some docs not updated in 30+ days' : null,
+    fix: !freshnessMet ? 'Review and update stale docs, add <!-- docguard:last-reviewed YYYY-MM-DD -->' : null,
+  });
+
+  // 4. Original — Are docs stored as originals (not copies)?
+  const hasCanonicalDir = existsSync(docsDir);
+  attributes.push({
+    name: 'Original',
+    met: hasCanonicalDir,
+    evidence: hasCanonicalDir ? 'Canonical docs present as markdown originals' : null,
+    gap: !hasCanonicalDir ? 'No docs-canonical/ directory found' : null,
+    fix: !hasCanonicalDir ? 'Run docguard init to create canonical documentation' : null,
+  });
+
+  // 5. Accurate — Do docs match the code?
+  const accurate = scores.drift >= 80 && scores.docQuality >= 50;
+  attributes.push({
+    name: 'Accurate',
+    met: accurate,
+    evidence: accurate ? `Drift: ${scores.drift}%, doc quality: ${scores.docQuality}%` : null,
+    gap: !accurate ? `Drift: ${scores.drift}%, doc quality: ${scores.docQuality}% — docs may be inaccurate` : null,
+    fix: !accurate ? 'Run docguard diagnose to find doc/code mismatches' : null,
+  });
+
+  // 6. Complete — Are all required docs present?
+  const complete = scores.structure >= 80;
+  attributes.push({
+    name: 'Complete',
+    met: complete,
+    evidence: complete ? `Structure score: ${scores.structure}% — required docs present` : null,
+    gap: !complete ? `Structure score: ${scores.structure}% — missing required docs` : null,
+    fix: !complete ? 'Run docguard init to create missing documentation' : null,
+  });
+
+  // 7. Consistent — Are versions, metadata, and references in sync?
+  const consistent = scores.changelog >= 50;
+  attributes.push({
+    name: 'Consistent',
+    met: consistent,
+    evidence: consistent ? `Changelog: ${scores.changelog}% — versions tracked` : null,
+    gap: !consistent ? `Changelog: ${scores.changelog}% — version inconsistencies` : null,
+    fix: !consistent ? 'Update CHANGELOG.md with [Unreleased] section and version headers' : null,
+  });
+
+  // 8. Enduring — Will docs survive infrastructure changes?
+  const enduring = hasGit;
+  attributes.push({
+    name: 'Enduring',
+    met: enduring,
+    evidence: enduring ? 'Git-backed repository with version history' : null,
+    gap: !enduring ? 'No version control — docs could be lost' : null,
+    fix: !enduring ? 'Initialize git repository: git init' : null,
+  });
+
+  // 9. Available — Can anyone access the docs?
+  const available = hasCanonicalDir;
+  attributes.push({
+    name: 'Available',
+    met: available,
+    evidence: available ? 'Docs in plain markdown — no vendor lock-in, universally accessible' : null,
+    gap: !available ? 'No docs directory found' : null,
+    fix: !available ? 'Run docguard init to create accessible documentation' : null,
+  });
+
+  const met = attributes.filter(a => a.met).length;
+  const total = attributes.length;
+  const score = Math.round((met / total) * 100);
+
+  return { attributes, met, total, score };
+}
+
 function calcAllScores(projectDir, config) {
   const scores = {};
   const details = {}; // Per-category failure details for actionable suggestions

package/cli/docguard.mjs

@@ -37,6 +37,7 @@ import { runWatch } from './commands/watch.mjs';
 import { runDiagnose } from './commands/diagnose.mjs';
 import { runPublish } from './commands/publish.mjs';
 import { runTrace } from './commands/trace.mjs';
+import { runLlms } from './commands/llms.mjs';
 
 // ── Shared constants (imported to break circular dependencies) ──────────
 import { c, PROFILES } from './shared.mjs';
@@ -354,6 +355,8 @@ async function main() {
       flags.signals = true;
     } else if (args[i] === '--debate') {
       flags.debate = true;
+    } else if (args[i] === '--stdout') {
+      flags.stdout = true;
     }
   }
 
@@ -427,6 +430,9 @@ async function main() {
     case 'traceability':
       runTrace(projectDir, config, flags);
       break;
+    case 'llms':
+      runLlms(projectDir, config, flags);
+      break;
     default:
       console.error(`${c.red}Unknown command: ${command}${c.reset}`);
       console.log(`Run ${c.cyan}docguard --help${c.reset} for usage.`);

package/cli/scanners/speckit.mjs

@@ -0,0 +1,234 @@
+/**
+ * Spec Kit Scanner — Detect and integrate with GitHub Spec Kit artifacts
+ *
+ * Auto-detects .specify/ directory (Spec Kit projects) and maps Spec Kit
+ * artifacts to CDD canonical docs. Enables DocGuard to work seamlessly
+ * with Spec Kit-managed projects.
+ *
+ * Spec Kit artifact mapping:
+ *   .specify/           → Project uses Spec Kit
+ *   specs/[name]/spec.md  → Requirements (maps to REQUIREMENTS.md / docs-canonical/)
+ *   specs/[name]/plan.md  → Design decisions (maps to ARCHITECTURE.md)
+ *   specs/[name]/tasks.md → Work items (maps to ROADMAP.md)
+ *   constitution.md      → Project rules (maps to AGENTS.md)
+ *   memory/              → Learned context (maps to DRIFT-LOG.md)
+ *
+ * Credit: Integration inspired by GitHub's Spec Kit framework
+ *         (github.com/github/spec-kit)
+ *
+ * Zero dependencies — pure Node.js built-ins only.
+ */
+
+import { existsSync, readFileSync, readdirSync, writeFileSync, statSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+/**
+ * Detect if a project uses Spec Kit.
+ * Returns details about detected Spec Kit artifacts.
+ */
+export function detectSpecKit(projectDir) {
+  const result = {
+    detected: false,
+    specifyDir: false,
+    specs: [],
+    constitution: false,
+    memory: false,
+  };
+
+  // Check for .specify/ directory
+  const specifyDir = resolve(projectDir, '.specify');
+  if (existsSync(specifyDir)) {
+    result.detected = true;
+    result.specifyDir = true;
+  }
+
+  // Check for specs/ directory with spec.md files
+  const specsDir = resolve(projectDir, 'specs');
+  if (existsSync(specsDir)) {
+    try {
+      const features = readdirSync(specsDir);
+      for (const feature of features) {
+        const featureDir = join(specsDir, feature);
+        try {
+        const fstat = statSync(featureDir);
+        if (!fstat.isDirectory()) continue;
+        } catch { continue; }
+
+        const specFile = join(featureDir, 'spec.md');
+        const planFile = join(featureDir, 'plan.md');
+        const tasksFile = join(featureDir, 'tasks.md');
+
+        if (existsSync(specFile) || existsSync(planFile) || existsSync(tasksFile)) {
+          result.detected = true;
+          result.specs.push({
+            name: feature,
+            hasSpec: existsSync(specFile),
+            hasPlan: existsSync(planFile),
+            hasTasks: existsSync(tasksFile),
+          });
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  // Check for constitution.md
+  const constitutionPath = resolve(projectDir, 'constitution.md');
+  if (existsSync(constitutionPath)) {
+    result.detected = true;
+    result.constitution = true;
+  }
+
+  // Check for memory/ directory
+  const memoryDir = resolve(projectDir, 'memory');
+  if (existsSync(memoryDir)) {
+    result.detected = true;
+    result.memory = true;
+  }
+
+  return result;
+}
+
+/**
+ * Map Spec Kit artifact to CDD equivalent.
+ * Returns the canonical doc name and section.
+ */
+const SPECKIT_CDD_MAP = {
+  'spec.md': { cddDoc: 'REQUIREMENTS.md', section: 'Requirements', type: 'requirement' },
+  'plan.md': { cddDoc: 'ARCHITECTURE.md', section: 'Design Decisions', type: 'design' },
+  'tasks.md': { cddDoc: 'ROADMAP.md', section: 'Task Backlog', type: 'roadmap' },
+};
+
+/**
+ * Generate CDD canonical docs from Spec Kit artifacts.
+ * Used by `docguard generate --from-speckit`.
+ *
+ * @param {string} projectDir - Project root
+ * @param {object} config - DocGuard config
+ * @param {object} flags - CLI flags
+ * @returns {object} - { generated: string[], skipped: string[], errors: string[] }
+ */
+export function generateFromSpecKit(projectDir, config, flags) {
+  const results = { generated: [], skipped: [], errors: [] };
+
+  const speckit = detectSpecKit(projectDir);
+  if (!speckit.detected) {
+    results.errors.push('No Spec Kit artifacts detected. This project does not use Spec Kit.');
+    return results;
+  }
+
+  // ── Generate REQUIREMENTS.md from spec.md files ──
+  if (speckit.specs.some(s => s.hasSpec)) {
+    const reqPath = resolve(projectDir, 'REQUIREMENTS.md');
+    if (existsSync(reqPath) && !flags.force) {
+      results.skipped.push('REQUIREMENTS.md already exists (use --force to overwrite)');
+    } else {
+      const lines = [
+        '# Requirements',
+        '',
+        '> Auto-generated from Spec Kit spec.md files by DocGuard',
+        '',
+      ];
+
+      for (const spec of speckit.specs) {
+        if (!spec.hasSpec) continue;
+        const specPath = join(projectDir, 'specs', spec.name, 'spec.md');
+        const content = readFileSync(specPath, 'utf-8');
+
+        lines.push(`## ${spec.name}`);
+        lines.push('');
+        lines.push(content.trim());
+        lines.push('');
+        lines.push('---');
+        lines.push('');
+      }
+
+      lines.push(`<!-- Generated by DocGuard from Spec Kit artifacts on ${new Date().toISOString().split('T')[0]} -->`);
+
+      writeFileSync(reqPath, lines.join('\n'), 'utf-8');
+      results.generated.push('REQUIREMENTS.md');
+    }
+  }
+
+  // ── Map constitution.md to AGENTS.md context ──
+  if (speckit.constitution) {
+    const constitutionPath = resolve(projectDir, 'constitution.md');
+    const agentsPath = resolve(projectDir, 'AGENTS.md');
+
+    if (existsSync(agentsPath)) {
+      const agentsContent = readFileSync(agentsPath, 'utf-8');
+
+      // Check if AGENTS.md already references constitution
+      if (!agentsContent.includes('constitution.md') && !agentsContent.includes('Constitution')) {
+        results.skipped.push('AGENTS.md exists but does not reference constitution.md — consider adding a reference');
+      } else {
+        results.skipped.push('AGENTS.md already references constitution.md');
+      }
+    }
+  }
+
+  // ── Map memory/ to DRIFT-LOG.md context ──
+  if (speckit.memory) {
+    results.skipped.push('memory/ directory detected — maps conceptually to DRIFT-LOG.md (no auto-generation needed)');
+  }
+
+  return results;
+}
+
+/**
+ * Validate Spec Kit artifact consistency.
+ * Used by guard to give CDD credit for Spec Kit artifacts.
+ *
+ * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
+ */
+export function validateSpecKitIntegration(projectDir, config) {
+  const results = { errors: [], warnings: [], passed: 0, total: 0 };
+
+  const speckit = detectSpecKit(projectDir);
+
+  // If no Spec Kit detected, silently pass
+  if (!speckit.detected) {
+    return results;
+  }
+
+  // Check 1: .specify/ directory exists → Spec Kit initialized
+  results.total++;
+  if (speckit.specifyDir) {
+    results.passed++;
+  } else {
+    results.warnings.push('Spec Kit artifacts detected but .specify/ directory missing. Run `specify init` to initialize');
+  }
+
+  // Check 2: Each spec has corresponding canonical doc coverage
+  for (const spec of speckit.specs) {
+    if (spec.hasSpec) {
+      results.total++;
+      // Check if spec.md content appears in any canonical doc
+      const specPath = join(projectDir, 'specs', spec.name, 'spec.md');
+      const content = readFileSync(specPath, 'utf-8');
+
+      // Look for requirement IDs in the spec
+      const hasReqIds = /\b(REQ|FR|NFR|US|STORY|AC)-\d{2,4}\b/.test(content);
+
+      if (hasReqIds) {
+        results.passed++;
+      } else {
+        results.warnings.push(
+          `specs/${spec.name}/spec.md has no requirement IDs. Add IDs (e.g., REQ-001) for traceability`
+        );
+      }
+    }
+  }
+
+  // Check 3: Constitution mapped to AGENTS.md
+  if (speckit.constitution) {
+    results.total++;
+    const agentsPath = resolve(projectDir, 'AGENTS.md');
+    if (existsSync(agentsPath)) {
+      results.passed++;
+    } else {
+      results.warnings.push('constitution.md exists but no AGENTS.md found. Create one for AI agent rules');
+    }
+  }
+
+  return results;
+}