docguard-cli 0.9.3 → 0.9.5

package/cli/commands/diagnose.mjs

@@ -120,10 +120,10 @@ export function runDiagnose(projectDir, config, flags) {
         });
       } catch { /* init may partially succeed */ }
 
-      // Run generate to fill in content
+      // Run generate to fill in MISSING content only (never --force, which would overwrite existing docs)
       try {
         const cliPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'docguard.mjs');
-        execSync(`node "${cliPath}" generate --dir "${projectDir}" --force`, {
+        execSync(`node "${cliPath}" generate --dir "${projectDir}"`, {
           encoding: 'utf-8',
           stdio: 'pipe',
         });

package/cli/commands/generate.mjs

@@ -5,7 +5,7 @@
  * This is the "killer feature" — take any project and auto-generate CDD docs.
  */
 
-import { existsSync, readFileSync, writeFileSync, readdirSync, statSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, readdirSync, statSync, mkdirSync, copyFileSync } from 'node:fs';
 import { resolve, join, extname, basename, relative, dirname } from 'node:path';
 import { c } from '../shared.mjs';
 import { detectDocTools } from '../scanners/doc-tools.mjs';
@@ -18,6 +18,30 @@ const IGNORE_DIRS = new Set([
   '.amplify-hosting', '.serverless',
 ]);
 
+/**
+ * Create a .bak backup of an existing file before --force overwrites it.
+ * Only backs up if the file exists and has content.
+ */
+function backupFile(filePath) {
+  if (existsSync(filePath)) {
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      if (content.trim().length > 0) {
+        copyFileSync(filePath, filePath + '.bak');
+      }
+    } catch { /* backup failure is non-fatal */ }
+  }
+}
+
+/**
+ * Safe write — creates a .bak backup before overwriting existing files.
+ * Call this instead of raw writeFileSync when generating docs.
+ */
+function safeWrite(filePath, content) {
+  backupFile(filePath);
+  writeFileSync(filePath, content, 'utf-8');
+}
+
 const CODE_EXTENSIONS = new Set([
   '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
   '.py', '.java', '.go', '.rs', '.rb', '.php', '.cs',
@@ -137,6 +161,21 @@ export function runGenerate(projectDir, config, flags) {
     mkdirSync(docsDir, { recursive: true });
   }
 
+  // ── Safety: warn if --force will overwrite existing files ──
+  if (flags.force) {
+    const targetFiles = [
+      'docs-canonical/ARCHITECTURE.md', 'docs-canonical/API-REFERENCE.md',
+      'docs-canonical/DATA-MODEL.md', 'docs-canonical/ENVIRONMENT.md',
+      'docs-canonical/TEST-SPEC.md', 'docs-canonical/SECURITY.md',
+      'AGENTS.md', 'CHANGELOG.md', 'DRIFT-LOG.md',
+    ];
+    const existing = targetFiles.filter(f => existsSync(resolve(projectDir, f)));
+    if (existing.length > 0) {
+      console.log(`  ${c.yellow}⚠️  --force: ${existing.length} existing file(s) will be overwritten.${c.reset}`);
+      console.log(`  ${c.dim}   Backups saved as .bak files.${c.reset}\n`);
+    }
+  }
+
   let created = 0;
   let skipped = 0;
 
@@ -633,7 +672,7 @@ See \\\`docs-canonical/KNOWN-GOTCHAS.md\\\` for known issues.
 | 0.1.0 | ${new Date().toISOString().split('T')[0]} | DocGuard Generate | Auto-generated (arc42 + C4 aligned) |
 `;
 
-  writeFileSync(path, appendStandardsCitation(content, 'ARCHITECTURE.md'), 'utf-8');
+  safeWrite(path, appendStandardsCitation(content, 'ARCHITECTURE.md'), 'utf-8');
   console.log(`  ${c.green}✅ ARCHITECTURE.md${c.reset} (arc42 §1-§12, ${componentRows.length} components, ${Object.values(stack).filter(Boolean).length} tech)`);
   return true;
 }
@@ -730,7 +769,7 @@ ${resourceSections}
 | 0.1.0 | ${new Date().toISOString().split('T')[0]} | DocGuard Generate | Auto-generated (${deepRoutes.length} endpoints from ${deepRoutes[0]?.source || 'code'}) |
 `;
 
-  writeFileSync(path, appendStandardsCitation(content, 'API-REFERENCE.md'), 'utf-8');
+  safeWrite(path, appendStandardsCitation(content, 'API-REFERENCE.md'), 'utf-8');
   console.log(`  ${c.green}✅ API-REFERENCE.md${c.reset} (${deepRoutes.length} endpoints, ${Object.keys(groups).length} resources)`);
   return true;
 }
@@ -885,7 +924,7 @@ ${erDiagram}
 | 0.1.0 | ${new Date().toISOString().split('T')[0]} | DocGuard Generate | Auto-generated (${entities.length} entities, ${relationships.length} relationships from ${schemaSource}) |
 `;
 
-  writeFileSync(path, appendStandardsCitation(content, 'DATA-MODEL.md'), 'utf-8');
+  safeWrite(path, appendStandardsCitation(content, 'DATA-MODEL.md'), 'utf-8');
   console.log(`  ${c.green}✅ DATA-MODEL.md${c.reset} (${entities.length} entities, ${relationships.length} relationships from ${schemaSource})`);
   return true;
 }
@@ -948,7 +987,7 @@ ${envVarRows || '| <!-- No .env.example found --> | | | | |'}
 | 0.1.0 | ${new Date().toISOString().split('T')[0]} | DocGuard Generate | Auto-generated (${scan.envVars.length} env vars found) |
 `;
 
-  writeFileSync(path, appendStandardsCitation(content, 'ENVIRONMENT.md'), 'utf-8');
+  safeWrite(path, appendStandardsCitation(content, 'ENVIRONMENT.md'), 'utf-8');
   console.log(`  ${c.green}✅ ENVIRONMENT.md${c.reset} (${scan.envVars.length} env vars detected)`);
   return true;
 }
@@ -1033,7 +1072,7 @@ ${serviceRows || '| <!-- No services found --> | | | |'}
 | 0.1.0 | ${new Date().toISOString().split('T')[0]} | DocGuard Generate | Auto-generated (${scan.tests.length} test files, ${serviceMap.filter(s => s.status === '✅').length}/${serviceMap.length} mapped) |
 `;
 
-  writeFileSync(path, appendStandardsCitation(content, 'TEST-SPEC.md'), 'utf-8');
+  safeWrite(path, appendStandardsCitation(content, 'TEST-SPEC.md'), 'utf-8');
   console.log(`  ${c.green}✅ TEST-SPEC.md${c.reset} (${scan.tests.length} tests, ${serviceMap.filter(s => s.status === '✅').length}/${serviceMap.length} services mapped)`);
   return true;
 }
@@ -1099,7 +1138,7 @@ ${scan.envVars.filter(v => isSecretVar(v.name)).map(v =>
 | 0.1.0 | ${new Date().toISOString().split('T')[0]} | DocGuard Generate | Auto-generated |
 `;
 
-  writeFileSync(path, appendStandardsCitation(content, 'SECURITY.md'), 'utf-8');
+  safeWrite(path, appendStandardsCitation(content, 'SECURITY.md'), 'utf-8');
   console.log(`  ${c.green}✅ SECURITY.md${c.reset} (auth: ${stack.auth || 'not detected'})`);
   return true;
 }
@@ -1209,7 +1248,7 @@ npx docguard-cli generate       # Generate docs from code
 - Test requirements in TEST-SPEC.md must be met
 - Documentation changes must pass \`docguard guard\`
 `;
-    writeFileSync(agentsPath, content, 'utf-8');
+    safeWrite(agentsPath, content);
     console.log(`  ${c.green}✅ AGENTS.md${c.reset} (AGENTS.md standard compliant)`);
     created++;
   } else {
@@ -1231,7 +1270,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Added
 - CDD documentation via DocGuard generate
 `;
-    writeFileSync(changelogPath, content, 'utf-8');
+    safeWrite(changelogPath, content);
     console.log(`  ${c.green}✅ CHANGELOG.md${c.reset}`);
     created++;
   } else {
@@ -1251,7 +1290,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 |------|------|---------------|-------------------|----------|------------|
 | | | | | | |
 `;
-    writeFileSync(driftPath, content, 'utf-8');
+    safeWrite(driftPath, content);
     console.log(`  ${c.green}✅ DRIFT-LOG.md${c.reset}`);
     created++;
   } else {

package/cli/commands/init.mjs

@@ -70,6 +70,7 @@ export async function runInit(projectDir, config, flags) {
     { key: 'SECURITY', file: 'docs-canonical/SECURITY.md', template: 'SECURITY.md.template', desc: 'Auth, secrets, security controls', defaultYes: ['webapp', 'api'].includes(detectedType) },
     { key: 'TEST-SPEC', file: 'docs-canonical/TEST-SPEC.md', template: 'TEST-SPEC.md.template', desc: 'Test strategy, coverage requirements', defaultYes: true },
     { key: 'ENVIRONMENT', file: 'docs-canonical/ENVIRONMENT.md', template: 'ENVIRONMENT.md.template', desc: 'Environment variables, deployment config', defaultYes: ['webapp', 'api'].includes(detectedType) },
+    { key: 'REQUIREMENTS', file: 'docs-canonical/REQUIREMENTS.md', template: 'REQUIREMENTS.md.template', desc: 'Functional requirements, user stories (spec-kit aligned)', defaultYes: true },
   ];
 
   let selectedDocs;

package/cli/scanners/speckit.mjs

@@ -1,30 +1,114 @@
 /**
- * Spec Kit Scanner — Detect and integrate with GitHub Spec Kit artifacts
+ * Spec Kit Scanner — Detect, validate, and integrate with GitHub Spec Kit
  *
- * 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.
+ * Auto-detects Spec Kit artifacts and validates their quality against
+ * spec-kit standards (github.com/github/spec-kit).
  *
- * 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)
+ * v0.9.5 — Aligned with spec-kit's actual file structure:
+ *   .specify/                          → Project uses Spec Kit
+ *   .specify/specs/NNN-feature/spec.md → Requirements (FR-IDs, User Scenarios)
+ *   .specify/specs/NNN-feature/plan.md → Implementation plan (Technical Context)
+ *   .specify/specs/NNN-feature/tasks.md → Task breakdown (Phased)
+ *   .specify/memory/constitution.md    → Project governing principles
  *
- * Credit: Integration inspired by GitHub's Spec Kit framework
+ * Also supports legacy paths (pre-v3 spec-kit):
+ *   specs/[name]/spec.md              → Legacy spec location
+ *   constitution.md                   → Legacy constitution at root
+ *   memory/                           → Legacy memory at root
+ *
+ * Credit: Integration with 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 { existsSync, readFileSync, readdirSync, statSync, copyFileSync, writeFileSync } from 'node:fs';
 import { resolve, join } from 'node:path';
 
+// ──── Spec Kit Mandatory Sections ────
+// Based on spec-kit's spec-template.md, plan-template.md, tasks-template.md
+
+const SPEC_MANDATORY_SECTIONS = [
+  'User Scenarios',        // or "User Stories"
+  'Requirements',          // must have FR-xxx IDs
+  'Success Criteria',      // must have SC-xxx IDs
+];
+
+const PLAN_MANDATORY_SECTIONS = [
+  'Summary',
+  'Technical Context',
+  'Project Structure',
+];
+
+const TASKS_MANDATORY_PATTERNS = [
+  /Phase\s+\d/i,           // Must have phased breakdown
+];
+
+// ──── Safety Helper ────
+
+/**
+ * Create a .bak backup before overwriting existing files.
+ */
+function backupFile(filePath) {
+  if (existsSync(filePath)) {
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      if (content.trim().length > 0) {
+        copyFileSync(filePath, filePath + '.bak');
+      }
+    } catch { /* non-fatal */ }
+  }
+}
+
+function safeWrite(filePath, content) {
+  backupFile(filePath);
+  writeFileSync(filePath, content, 'utf-8');
+}
+
+// ──── Detection ────
+
+/**
+ * Scan a specs directory for feature spec folders.
+ * Returns array of { name, hasSpec, hasPlan, hasTasks, specPath, planPath, tasksPath }.
+ */
+function scanSpecsDir(specsDir) {
+  const specs = [];
+  if (!existsSync(specsDir)) return specs;
+
+  try {
+    const features = readdirSync(specsDir);
+    for (const feature of features) {
+      const featureDir = join(specsDir, feature);
+      try {
+        if (!statSync(featureDir).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)) {
+        specs.push({
+          name: feature,
+          hasSpec: existsSync(specFile),
+          hasPlan: existsSync(planFile),
+          hasTasks: existsSync(tasksFile),
+          specPath: existsSync(specFile) ? specFile : null,
+          planPath: existsSync(planFile) ? planFile : null,
+          tasksPath: existsSync(tasksFile) ? tasksFile : null,
+        });
+      }
+    }
+  } catch { /* ignore */ }
+
+  return specs;
+}
+
 /**
  * Detect if a project uses Spec Kit.
- * Returns details about detected Spec Kit artifacts.
+ * Checks both spec-kit v3+ paths (.specify/) and legacy paths.
+ *
+ * @returns {{ detected, specifyDir, specs[], constitution, constitutionPath, memory, source }}
  */
 export function detectSpecKit(projectDir) {
   const result = {
@@ -32,87 +116,189 @@ export function detectSpecKit(projectDir) {
     specifyDir: false,
     specs: [],
     constitution: false,
+    constitutionPath: null,
     memory: false,
+    source: null,  // 'specify' (v3+) or 'legacy'
   };
 
-  // Check for .specify/ directory
+  // ── 1. Check for .specify/ directory (v3+ standard) ──
   const specifyDir = resolve(projectDir, '.specify');
   if (existsSync(specifyDir)) {
     result.detected = true;
     result.specifyDir = true;
+    result.source = 'specify';
+
+    // Specs under .specify/specs/ (v3 standard path)
+    const v3Specs = scanSpecsDir(resolve(specifyDir, 'specs'));
+    if (v3Specs.length > 0) {
+      result.specs.push(...v3Specs);
+    }
+
+    // Constitution at .specify/memory/constitution.md (v3 standard)
+    const v3Constitution = resolve(specifyDir, 'memory', 'constitution.md');
+    if (existsSync(v3Constitution)) {
+      result.constitution = true;
+      result.constitutionPath = v3Constitution;
+    }
+
+    // Memory directory at .specify/memory/ (v3 standard)
+    const v3Memory = resolve(specifyDir, 'memory');
+    if (existsSync(v3Memory)) {
+      result.memory = 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 */ }
+  // ── 2. Legacy paths (fallback for pre-v3 or manual setups) ──
+  // Only check legacy if not already detected via .specify/
+  if (result.specs.length === 0) {
+    const legacySpecs = scanSpecsDir(resolve(projectDir, 'specs'));
+    if (legacySpecs.length > 0) {
+      result.detected = true;
+      result.source = result.source || 'legacy';
+      result.specs.push(...legacySpecs);
+    }
   }
 
-  // Check for constitution.md
-  const constitutionPath = resolve(projectDir, 'constitution.md');
-  if (existsSync(constitutionPath)) {
-    result.detected = true;
-    result.constitution = true;
+  // Constitution at project root (legacy)
+  if (!result.constitution) {
+    const rootConstitution = resolve(projectDir, 'constitution.md');
+    if (existsSync(rootConstitution)) {
+      result.detected = true;
+      result.constitution = true;
+      result.constitutionPath = rootConstitution;
+      result.source = result.source || 'legacy';
+    }
   }
 
-  // Check for memory/ directory
-  const memoryDir = resolve(projectDir, 'memory');
-  if (existsSync(memoryDir)) {
-    result.detected = true;
-    result.memory = true;
+  // Memory at project root (legacy)
+  if (!result.memory) {
+    const rootMemory = resolve(projectDir, 'memory');
+    if (existsSync(rootMemory)) {
+      result.detected = true;
+      result.memory = true;
+      result.source = result.source || 'legacy';
+    }
   }
 
   return result;
 }
 
+// ──── Quality Validation ────
+
+/**
+ * Check if a markdown file contains specific section headings.
+ *
+ * @param {string} content - File content
+ * @param {string[]} sections - Required section heading texts
+ * @returns {{ found: string[], missing: string[] }}
+ */
+function checkSections(content, sections) {
+  const found = [];
+  const missing = [];
+
+  for (const section of sections) {
+    // Match both "## Requirements" and "### Functional Requirements"
+    const pattern = new RegExp(`^#{1,4}\\s+.*${section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'im');
+    if (pattern.test(content)) {
+      found.push(section);
+    } else {
+      missing.push(section);
+    }
+  }
+
+  return { found, missing };
+}
+
+/**
+ * Validate the quality of a spec.md file against spec-kit standards.
+ *
+ * Checks:
+ *   - Has mandatory sections (User Scenarios, Requirements, Success Criteria)
+ *   - Has FR-xxx requirement IDs
+ *   - Has acceptance scenarios (Given/When/Then)
+ */
+function validateSpecQuality(specPath) {
+  const issues = [];
+  const content = readFileSync(specPath, 'utf-8');
+
+  // Check mandatory sections
+  const { missing } = checkSections(content, SPEC_MANDATORY_SECTIONS);
+  for (const section of missing) {
+    issues.push(`Missing mandatory section: "${section}" (spec-kit spec-template.md)`);
+  }
+
+  // Check for FR-xxx or FR-NNN requirement IDs
+  const hasFRIds = /\b(FR|REQ|NFR)-\d{2,4}\b/.test(content);
+  if (!hasFRIds) {
+    issues.push('No requirement IDs found (expected FR-001, REQ-001, etc.)');
+  }
+
+  // Check for SC-xxx success criteria IDs
+  const hasSCIds = /\bSC-\d{2,4}\b/.test(content);
+  if (!hasSCIds) {
+    issues.push('No success criteria IDs found (expected SC-001, SC-002, etc.)');
+  }
+
+  return issues;
+}
+
+/**
+ * Validate the quality of a plan.md file.
+ */
+function validatePlanQuality(planPath) {
+  const issues = [];
+  const content = readFileSync(planPath, 'utf-8');
+
+  const { missing } = checkSections(content, PLAN_MANDATORY_SECTIONS);
+  for (const section of missing) {
+    issues.push(`Missing mandatory section: "${section}" (spec-kit plan-template.md)`);
+  }
+
+  return issues;
+}
+
 /**
- * Map Spec Kit artifact to CDD equivalent.
- * Returns the canonical doc name and section.
+ * Validate the quality of a tasks.md file.
  */
+function validateTasksQuality(tasksPath) {
+  const issues = [];
+  const content = readFileSync(tasksPath, 'utf-8');
+
+  // Must have phased breakdown
+  const hasPhases = TASKS_MANDATORY_PATTERNS.some(p => p.test(content));
+  if (!hasPhases) {
+    issues.push('No phased task breakdown found (expected "Phase 1:", "Phase 2:", etc.)');
+  }
+
+  // Must have task IDs
+  const hasTaskIds = /\bT\d{3}\b/.test(content);
+  if (!hasTaskIds) {
+    issues.push('No task IDs found (expected T001, T002, etc.)');
+  }
+
+  return issues;
+}
+
+// ──── CDD Mapping ────
+
 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 from Spec Kit ────
+
 /**
  * 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.');
+    results.errors.push('No Spec Kit artifacts detected. Run `specify init` to initialize, or install via: uv tool install specify-cli --from git+https://github.com/github/spec-kit.git');
     return results;
   }
 
@@ -131,8 +317,7 @@ export function generateFromSpecKit(projectDir, config, flags) {
 
       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');
+        const content = readFileSync(spec.specPath, 'utf-8');
 
         lines.push(`## ${spec.name}`);
         lines.push('');
@@ -144,20 +329,17 @@ export function generateFromSpecKit(projectDir, config, flags) {
 
       lines.push(`<!-- Generated by DocGuard from Spec Kit artifacts on ${new Date().toISOString().split('T')[0]} -->`);
 
-      writeFileSync(reqPath, lines.join('\n'), 'utf-8');
+      safeWrite(reqPath, lines.join('\n'));
       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 {
@@ -166,17 +348,27 @@ export function generateFromSpecKit(projectDir, config, flags) {
     }
   }
 
-  // ── Map memory/ to DRIFT-LOG.md context ──
+  // ── Map memory/ to DRIFT-LOG.md ──
   if (speckit.memory) {
-    results.skipped.push('memory/ directory detected — maps conceptually to DRIFT-LOG.md (no auto-generation needed)');
+    results.skipped.push('memory/ directory detected — maps conceptually to DRIFT-LOG.md');
   }
 
   return results;
 }
 
+// ──── Guard Validator ────
+
 /**
- * Validate Spec Kit artifact consistency.
- * Used by guard to give CDD credit for Spec Kit artifacts.
+ * Validate Spec Kit integration quality.
+ *
+ * When spec-kit is NOT detected:
+ *   - Shows 1 informational warning suggesting spec-kit
+ *
+ * When spec-kit IS detected:
+ *   - Validates spec.md quality (mandatory sections, FR-IDs, SC-IDs)
+ *   - Validates plan.md quality (mandatory sections)
+ *   - Validates tasks.md quality (phased breakdown, T-IDs)
+ *   - Checks constitution → AGENTS.md mapping
  *
  * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
  */
@@ -185,41 +377,80 @@ export function validateSpecKitIntegration(projectDir, config) {
 
   const speckit = detectSpecKit(projectDir);
 
-  // If no Spec Kit detected, silently pass
+  // If no Spec Kit detected, suggest it
   if (!speckit.detected) {
+    results.total++;
+    results.warnings.push(
+      'No Spec Kit artifacts detected. Consider `specify init` for spec-driven development (github.com/github/spec-kit)'
+    );
     return results;
   }
 
-  // Check 1: .specify/ directory exists → Spec Kit initialized
+  // ── Check 1: .specify/ directory exists ──
   results.total++;
   if (speckit.specifyDir) {
     results.passed++;
   } else {
-    results.warnings.push('Spec Kit artifacts detected but .specify/ directory missing. Run `specify init` to initialize');
+    results.warnings.push(
+      'Spec Kit artifacts found but .specify/ directory missing. Run `specify init` to create standard structure'
+    );
   }
 
-  // Check 2: Each spec has corresponding canonical doc coverage
+  // ── Check 2: Validate each spec's quality ──
   for (const spec of speckit.specs) {
-    if (spec.hasSpec) {
+    // 2a: spec.md quality
+    if (spec.hasSpec && spec.specPath) {
       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');
+      try {
+        const issues = validateSpecQuality(spec.specPath);
+        if (issues.length === 0) {
+          results.passed++;
+        } else {
+          for (const issue of issues) {
+            results.warnings.push(`specs/${spec.name}/spec.md: ${issue}`);
+          }
+        }
+      } catch {
+        results.warnings.push(`specs/${spec.name}/spec.md: Could not read file`);
+      }
+    }
 
-      // Look for requirement IDs in the spec
-      const hasReqIds = /\b(REQ|FR|NFR|US|STORY|AC)-\d{2,4}\b/.test(content);
+    // 2b: plan.md quality
+    if (spec.hasPlan && spec.planPath) {
+      results.total++;
+      try {
+        const issues = validatePlanQuality(spec.planPath);
+        if (issues.length === 0) {
+          results.passed++;
+        } else {
+          for (const issue of issues) {
+            results.warnings.push(`specs/${spec.name}/plan.md: ${issue}`);
+          }
+        }
+      } catch {
+        results.warnings.push(`specs/${spec.name}/plan.md: Could not read file`);
+      }
+    }
 
-      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`
-        );
+    // 2c: tasks.md quality
+    if (spec.hasTasks && spec.tasksPath) {
+      results.total++;
+      try {
+        const issues = validateTasksQuality(spec.tasksPath);
+        if (issues.length === 0) {
+          results.passed++;
+        } else {
+          for (const issue of issues) {
+            results.warnings.push(`specs/${spec.name}/tasks.md: ${issue}`);
+          }
+        }
+      } catch {
+        results.warnings.push(`specs/${spec.name}/tasks.md: Could not read file`);
       }
     }
   }
 
-  // Check 3: Constitution mapped to AGENTS.md
+  // ── Check 3: Constitution → AGENTS.md mapping ──
   if (speckit.constitution) {
     results.total++;
     const agentsPath = resolve(projectDir, 'AGENTS.md');

package/cli/validators/traceability.mjs

@@ -72,6 +72,7 @@ const TRACE_MAP = {
 
 // ──── 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,
@@ -83,6 +84,8 @@ const DEFAULT_REQ_PATTERNS = [
   /\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
+  /\b(T)(\d{3,4})\b/g,       // Spec Kit: Task IDs (T001, T002)
 ];
 
 /**
@@ -305,15 +308,20 @@ function getRequirementDocPaths(projectDir, config) {
     if (existsSync(p) && !paths.includes(p)) paths.push(p);
   }
 
-  // Spec Kit artifacts: specs/*/spec.md
-  const specsDir = resolve(projectDir, 'specs');
-  if (existsSync(specsDir)) {
-    try {
-      for (const feature of readdirSync(specsDir)) {
-        const specPath = join(specsDir, feature, 'spec.md');
-        if (existsSync(specPath)) paths.push(specPath);
-      }
-    } catch { /* ignore */ }
+  // Spec Kit artifacts: .specify/specs/*/spec.md (v3+) and specs/*/spec.md (legacy)
+  const specKitDirs = [
+    resolve(projectDir, '.specify', 'specs'),  // v3+ standard
+    resolve(projectDir, 'specs'),               // legacy
+  ];
+  for (const specsDir of specKitDirs) {
+    if (existsSync(specsDir)) {
+      try {
+        for (const feature of readdirSync(specsDir)) {
+          const specPath = join(specsDir, feature, 'spec.md');
+          if (existsSync(specPath) && !paths.includes(specPath)) paths.push(specPath);
+        }
+      } catch { /* ignore */ }
+    }
   }
 
   return paths;

package/commands/docguard.fix.md

@@ -0,0 +1,45 @@
+---
+description: Generate AI prompts to fix specific documentation issues identified by DocGuard
+---
+
+# DocGuard Fix — AI-Assisted Documentation Repair
+
+Generate targeted fix prompts for specific documentation issues.
+
+## What to do
+
+1. First, identify what needs fixing:
+```bash
+npx docguard-cli diagnose
+```
+
+2. Generate fix prompts for specific documents:
+```bash
+# Fix a specific canonical doc
+npx docguard-cli fix --doc architecture
+npx docguard-cli fix --doc security
+npx docguard-cli fix --doc test-spec
+npx docguard-cli fix --doc data-model
+npx docguard-cli fix --doc environment
+```
+
+3. The fix command generates a detailed AI prompt. Read the prompt and execute its instructions:
+   - It will reference the project's actual code structure
+   - It will list specific sections to add or update
+   - It will include examples aligned with the project's tech stack
+
+4. After fixing, verify the improvement:
+```bash
+npx docguard-cli guard
+```
+
+5. If the project uses Spec Kit, ensure specs align with spec-kit templates:
+   - `spec.md` must have: User Scenarios, Requirements (FR-IDs), Success Criteria (SC-IDs)
+   - `plan.md` must have: Summary, Technical Context, Project Structure
+   - `tasks.md` must have: Phased breakdown (Phase 1, 2, 3+), Task IDs (T001+)
+
+## Important
+
+- Never overwrite existing documentation without creating a `.bak` backup
+- Use `--force` only when explicitly instructed by the user
+- Log any deviations from canonical docs in DRIFT-LOG.md with `// DRIFT: reason`

package/commands/docguard.guard.md

@@ -0,0 +1,27 @@
+---
+description: Run DocGuard guard validation — check project documentation quality against CDD standards
+---
+
+# DocGuard Guard — Documentation Quality Gate
+
+Run the DocGuard CLI to validate all documentation against Canonical-Driven Development standards.
+
+## What to do
+
+1. Run the guard command:
+```bash
+npx docguard-cli guard
+```
+
+2. Review the output. Each validator reports ✅ (pass) or ❌ (fail):
+   - **Structure**: Required CDD files exist
+   - **Doc Sections**: Canonical docs have required sections
+   - **Drift**: Code deviations logged in DRIFT-LOG.md
+   - **Test-Spec**: Tests match TEST-SPEC.md rules
+   - **Security**: No hardcoded secrets
+   - **Spec-Kit**: Spec quality validation (FR-IDs, sections)
+   - **Doc-Quality**: Readability and writing quality
+
+3. If any checks fail, run `docguard diagnose` for a remediation plan.
+
+4. All checks must pass before committing. Exit code 0 = pass, 1 = fail, 2 = warnings only.

package/commands/docguard.review.md

@@ -0,0 +1,35 @@
+---
+description: Review documentation quality — identify improvements and suggest fixes based on CDD and spec-kit standards
+---
+
+# DocGuard Review — Documentation Quality Analysis
+
+Analyze the project's documentation quality and suggest specific improvements.
+
+## What to do
+
+1. Run the full diagnostic:
+```bash
+npx docguard-cli diagnose
+```
+
+2. Run the scoring engine:
+```bash
+npx docguard-cli score
+```
+
+3. For each issue found, analyze the root cause:
+   - **Missing sections**: Check which mandatory sections are absent from canonical docs
+   - **Low readability**: Identify overly complex sentences or passive voice
+   - **Drift**: Find `// DRIFT:` comments in code not logged in DRIFT-LOG.md
+   - **Stale docs**: Compare doc modification dates against code changes
+   - **Spec quality**: Verify specs have FR-IDs, SC-IDs, and Given/When/Then scenarios
+
+4. Suggest specific improvements for each issue. Quote the relevant section and propose the fix.
+
+5. Prioritize fixes by impact:
+   - 🔴 HIGH: Missing docs, security issues, broken traceability
+   - 🟡 MEDIUM: Low readability, missing sections, stale content
+   - 🟢 LOW: Minor formatting, missing badges, metadata sync
+
+6. After making changes, re-run `npx docguard-cli guard` to verify improvements.

package/commands/docguard.score.md

@@ -0,0 +1,42 @@
+---
+description: Show CDD maturity score — comprehensive documentation health assessment with category breakdown
+---
+
+# DocGuard Score — CDD Maturity Assessment
+
+Calculate and display the project's Canonical-Driven Development maturity score.
+
+## What to do
+
+1. Run the scoring engine:
+```bash
+npx docguard-cli score
+```
+
+2. For JSON output (CI/CD integration):
+```bash
+npx docguard-cli score --format json
+```
+
+3. Interpret the results:
+
+   | Grade | Score | Meaning |
+   |-------|-------|---------|
+   | A+ | 95-100 | Exemplary — production-grade documentation |
+   | A | 85-94 | Strong — minor improvements possible |
+   | B | 70-84 | Good — some gaps to address |
+   | C | 50-69 | Fair — significant documentation debt |
+   | D | 30-49 | Poor — major gaps in documentation |
+   | F | 0-29 | Critical — documentation infrastructure missing |
+
+4. Focus on the category breakdown:
+   - **Structure** (25%): Do required files exist?
+   - **Doc Quality** (20%): Readability, completeness, sections
+   - **Testing** (15%): Test coverage documentation
+   - **Security** (10%): Security documentation
+   - **Environment** (10%): Environment variable documentation
+   - **Drift** (10%): Deviation tracking
+   - **Changelog** (5%): Change log maintenance
+   - **Architecture** (5%): Architecture documentation
+
+5. Prioritize improvements by category weight — fixing Structure issues has the highest impact.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {
@@ -24,7 +24,8 @@
     "documentation",
     "governance",
     "ai-agents",
-    "spec-guard",
+    "spec-kit",
+    "spec-driven-development",
     "docguard",
     "validation",
     "cli",
@@ -47,6 +48,7 @@
   "files": [
     "cli/",
     "templates/",
+    "commands/",
     "docs/",
     "STANDARD.md",
     "PHILOSOPHY.md",

package/templates/REQUIREMENTS.md.template

@@ -0,0 +1,68 @@
+# Requirements
+
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status draft -->
+
+> Tracks functional requirements, non-functional requirements, and success criteria.
+> Use requirement IDs (FR-001, NFR-001, SC-001) for traceability back to code and tests.
+
+![CDD Canonical](https://img.shields.io/badge/CDD-Canonical-blue)
+
+## Functional Requirements
+
+<!-- List functional requirements with FR-NNN IDs -->
+
+| ID | Priority | Requirement | Status | Test Coverage |
+|----|----------|-------------|--------|---------------|
+| FR-001 | P1 | System MUST [capability] | 🔴 Draft | ❌ |
+| FR-002 | P1 | System MUST [capability] | 🔴 Draft | ❌ |
+| FR-003 | P2 | Users MUST be able to [interaction] | 🔴 Draft | ❌ |
+
+## Non-Functional Requirements
+
+<!-- Quality attributes: performance, security, reliability -->
+
+| ID | Category | Requirement | Metric |
+|----|----------|-------------|--------|
+| NFR-001 | Performance | Response time < 200ms p95 | Measured via [tool] |
+| NFR-002 | Security | All endpoints require authentication | Validated by guard |
+| NFR-003 | Reliability | 99.9% uptime SLA | Monitored via [tool] |
+
+## Success Criteria
+
+<!-- Measurable outcomes — aligned with spec-kit SC-NNN format -->
+
+| ID | Criteria | Measurement | Target |
+|----|----------|-------------|--------|
+| SC-001 | [Measurable user outcome] | [How measured] | [Target value] |
+| SC-002 | [Performance metric] | [How measured] | [Target value] |
+
+## User Scenarios
+
+<!-- Spec-kit aligned: Given/When/Then acceptance scenarios -->
+
+### User Story 1 - [Title] (Priority: P1)
+
+[Description of user journey]
+
+**Acceptance Scenarios**:
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+## Traceability Matrix
+
+<!-- Maps requirements → code → tests -->
+
+| Requirement | Source File | Test File | Status |
+|-------------|------------|-----------|--------|
+| FR-001 | `src/[file]` | `tests/[file]` | ❌ |
+
+## Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 0.1.0 | YYYY-MM-DD | DocGuard Init | Initial template |
+
+---
+
+*Generated by [DocGuard](https://github.com/raccioly/docguard) — aligned with [Spec Kit](https://github.com/github/spec-kit) standards.*