docguard-cli 0.9.6 → 0.9.7

package/cli/commands/diff.mjs

@@ -157,7 +157,12 @@ function diffEntities(dir) {
     'EntityName', 'Entity', 'metadata', 'tbd', 'cascade', 'fields',
     'purpose', 'version', 'author', 'example', 'TODO', 'Overview',
     'Revision', 'History', 'Entities', 'Relationships', 'Indexes',
-    'Migration', 'Strategy',
+    'Migration', 'Strategy', 'Trade-offs', 'Tradeoffs', 'Notes',
+    'Summary', 'Details', 'Configuration', 'Setup', 'Reference',
+    'Appendix', 'Glossary', 'FAQ', 'Introduction', 'Background',
+    'Prerequisites', 'Requirements', 'Assumptions', 'Constraints',
+    'Dependencies', 'Architecture', 'Design', 'Implementation',
+    'Testing', 'Deployment', 'Monitoring', 'Operations', 'Security',
   ]);
 
   const headerRegex = /^### (\S+)/gm;
@@ -165,9 +170,11 @@ function diffEntities(dir) {
   while ((match = headerRegex.exec(content)) !== null) {
     const name = match[1].replace(/[`*]/g, '');
     // Skip template placeholders (<!-- ... -->) and noise words
-    if (name.startsWith('<!--') || name.length <= 1 || HEADER_NOISE.has(name) || HEADER_NOISE.has(name.toLowerCase())) {
+    if (name.startsWith('<!--') || name.length <= 2 || HEADER_NOISE.has(name) || HEADER_NOISE.has(name.toLowerCase())) {
       continue;
     }
+    // Skip hyphenated words (e.g., 'Trade-offs', 'Set-up') — these are section titles, not entities
+    if (name.includes('-')) continue;
     docEntities.add(name.toLowerCase());
   }
 
@@ -194,10 +201,16 @@ function diffEntities(dir) {
     // Common table headers and template words
     'true', 'false', 'header', 'checks', 'project', 'count', 'grade',
     'breakdown', 'issuecount', 'autofixable', 'projectname', 'projecttype',
+    // Common doc section words (not entity names)
+    'trade', 'offs', 'tradeoffs', 'setup', 'overview', 'summary',
+    'details', 'configuration', 'reference', 'pattern', 'patterns',
+    'strategy', 'approach', 'impact', 'benefit', 'risk', 'concern',
+    'action', 'result', 'outcome', 'inverted', 'composite', 'secondary',
   ]);
   while ((match = tableRegex.exec(content)) !== null) {
     const name = match[1];
-    if (name.length > 2 && !TABLE_NOISE.has(name.toLowerCase())) {
+    // Skip short names (<=3 chars) and noise words
+    if (name.length > 3 && !TABLE_NOISE.has(name.toLowerCase())) {
       docEntities.add(name.toLowerCase());
     }
   }

package/cli/commands/init.mjs

@@ -8,6 +8,7 @@ import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
 import { c, PROFILES } from '../shared.mjs';
+import { ensureSkills } from '../ensure-skills.mjs';
 
 function detectProjectType(dir) {
   const pkgPath = resolve(dir, 'package.json');
@@ -285,4 +286,7 @@ export async function runInit(projectDir, config, flags) {
   } else {
     console.log(`\n  ${c.dim}Run${c.reset} ${c.cyan}docguard diagnose${c.reset} ${c.dim}to check for issues.${c.reset}\n`);
   }
+
+  // Auto-install skills and commands
+  ensureSkills(projectDir, flags);
 }

package/cli/commands/setup.mjs

@@ -0,0 +1,455 @@
+/**
+ * Setup Command — Interactive onboarding wizard for DocGuard
+ *
+ * Walks through 7 steps to ensure DocGuard is fully configured:
+ *   1. Project detection & config
+ *   2. Canonical docs
+ *   3. AI skills
+ *   4. Slash commands
+ *   5. Agent configs
+ *   6. External integrations (spec-kit, understanding)
+ *   7. Git hooks
+ *
+ * Each step shows current status (✅/⚠️) and offers to fix what's missing.
+ * Supports --skip-prompts for non-interactive CI mode.
+ *
+ * Zero dependencies — pure Node.js built-ins only.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { resolve, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline';
+import { execSync } from 'node:child_process';
+import { c } from '../shared.mjs';
+import { ensureSkills } from '../ensure-skills.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const TEMPLATES_DIR = resolve(__dirname, '../../templates');
+const SKILLS_SOURCE = resolve(__dirname, '../../extensions/spec-kit-docguard/skills');
+const COMMANDS_SOURCE = resolve(__dirname, '../../commands');
+
+// ── Readline Helper ─────────────────────────────────────────────────────
+
+function askQuestion(prompt) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(res => {
+    rl.question(prompt, answer => {
+      rl.close();
+      res(answer.trim().toLowerCase());
+    });
+  });
+}
+
+async function askYesNo(prompt, defaultYes = true) {
+  const label = defaultYes ? 'Y/n' : 'y/N';
+  const answer = await askQuestion(`${prompt} [${label}]: `);
+  if (answer === '') return defaultYes;
+  return answer === 'y' || answer === 'yes';
+}
+
+// ── Project Type Detection ──────────────────────────────────────────────
+
+function detectProjectType(dir) {
+  const pkgPath = resolve(dir, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+      if (pkg.bin) return 'cli';
+      if (allDeps.next || allDeps.react || allDeps.vue || allDeps['@angular/core'] ||
+          allDeps.svelte || allDeps.nuxt) return 'webapp';
+      if (allDeps.express || allDeps.fastify || allDeps.hono || allDeps.koa) return 'api';
+      if (pkg.main || pkg.exports || pkg.module) return 'library';
+    } catch { /* fall through */ }
+  }
+  if (existsSync(resolve(dir, 'manage.py'))) return 'webapp';
+  if (existsSync(resolve(dir, 'setup.py')) || existsSync(resolve(dir, 'pyproject.toml'))) return 'library';
+  return 'unknown';
+}
+
+// ── CLI Detection ───────────────────────────────────────────────────────
+
+function isCliAvailable(name) {
+  try {
+    const cmd = process.platform === 'win32' ? `where ${name}` : `which ${name}`;
+    execSync(`${cmd} 2>/dev/null`, { encoding: 'utf-8', timeout: 3000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function detectAgentDirs(projectDir) {
+  const agentDirs = [
+    { name: 'GitHub Copilot', dir: '.github', commandsPath: '.github/commands' },
+    { name: 'Cursor', dir: '.cursor', commandsPath: '.cursor/rules' },
+    { name: 'Google Gemini', dir: '.gemini', commandsPath: '.gemini/commands' },
+    { name: 'Claude Code', dir: '.claude', commandsPath: '.claude/commands' },
+    { name: 'Antigravity', dir: '.agents', commandsPath: '.agents/workflows' },
+  ];
+
+  return agentDirs.filter(a => existsSync(resolve(projectDir, a.dir)));
+}
+
+// ── Main Setup Wizard ───────────────────────────────────────────────────
+
+export async function runSetup(projectDir, config, flags) {
+  console.log(`${c.bold}🧙 DocGuard Setup Wizard${c.reset}`);
+  console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
+
+  const interactive = !flags.skipPrompts;
+  let configured = 0;
+  let alreadyGood = 0;
+
+  // ── Step 1: Project Detection & Config ──────────────────────────────
+
+  console.log(`  ${c.bold}Step 1/7: Project Detection${c.reset}`);
+
+  const detectedType = detectProjectType(projectDir);
+  console.log(`  ${c.green}✅${c.reset} Project type: ${c.cyan}${detectedType}${c.reset}`);
+
+  const configPath = resolve(projectDir, '.docguard.json');
+  if (existsSync(configPath)) {
+    const cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
+    console.log(`  ${c.green}✅${c.reset} .docguard.json exists (profile: ${c.cyan}${cfg.profile || 'standard'}${c.reset})`);
+    alreadyGood++;
+  } else {
+    console.log(`  ${c.yellow}⚠️${c.reset}  .docguard.json missing`);
+    const create = interactive
+      ? await askYesNo(`     → Create config file?`)
+      : true;
+
+    if (create) {
+      const typeDefaults = {
+        cli:     { needsEnvVars: false, needsEnvExample: false, needsE2E: false, needsDatabase: false },
+        library: { needsEnvVars: false, needsEnvExample: false, needsE2E: false, needsDatabase: false },
+        webapp:  { needsEnvVars: true,  needsEnvExample: true,  needsE2E: true,  needsDatabase: true },
+        api:     { needsEnvVars: true,  needsEnvExample: true,  needsE2E: false, needsDatabase: true },
+        unknown: { needsEnvVars: true,  needsEnvExample: true,  needsE2E: false, needsDatabase: true },
+      };
+
+      const defaultConfig = {
+        projectName: config.projectName,
+        version: '0.4',
+        profile: 'standard',
+        projectType: detectedType,
+        projectTypeConfig: typeDefaults[detectedType] || typeDefaults.unknown,
+      };
+
+      writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2) + '\n', 'utf-8');
+      console.log(`     ${c.green}✅ Created .docguard.json${c.reset}`);
+      configured++;
+    }
+  }
+
+  console.log('');
+
+  // ── Step 2: Canonical Docs ──────────────────────────────────────────
+
+  console.log(`  ${c.bold}Step 2/7: Canonical Docs${c.reset}`);
+
+  const canonicalDocs = [
+    { file: 'docs-canonical/ARCHITECTURE.md', template: 'ARCHITECTURE.md.template', label: 'Architecture',     defaultYes: true },
+    { file: 'docs-canonical/DATA-MODEL.md',   template: 'DATA-MODEL.md.template',   label: 'Data Model',      defaultYes: ['webapp', 'api'].includes(detectedType) },
+    { file: 'docs-canonical/SECURITY.md',     template: 'SECURITY.md.template',     label: 'Security',        defaultYes: ['webapp', 'api'].includes(detectedType) },
+    { file: 'docs-canonical/TEST-SPEC.md',    template: 'TEST-SPEC.md.template',    label: 'Test Spec',       defaultYes: true },
+    { file: 'docs-canonical/ENVIRONMENT.md',  template: 'ENVIRONMENT.md.template',  label: 'Environment',     defaultYes: ['webapp', 'api'].includes(detectedType) },
+    { file: 'docs-canonical/REQUIREMENTS.md', template: 'REQUIREMENTS.md.template', label: 'Requirements',    defaultYes: true },
+  ];
+
+  const trackingFiles = [
+    { file: 'AGENTS.md',     template: 'AGENTS.md.template',     label: 'Agent Instructions' },
+    { file: 'CHANGELOG.md',  template: 'CHANGELOG.md.template',  label: 'Changelog' },
+    { file: 'DRIFT-LOG.md',  template: 'DRIFT-LOG.md.template',  label: 'Drift Log' },
+  ];
+
+  let missingDocs = [];
+
+  // Check canonical docs
+  for (const doc of [...canonicalDocs, ...trackingFiles]) {
+    const fullPath = resolve(projectDir, doc.file);
+    if (existsSync(fullPath)) {
+      console.log(`  ${c.green}✅${c.reset} ${doc.file}`);
+      alreadyGood++;
+    } else {
+      console.log(`  ${c.yellow}⚠️${c.reset}  ${doc.file} ${c.dim}(missing)${c.reset}`);
+      missingDocs.push(doc);
+    }
+  }
+
+  if (missingDocs.length > 0) {
+    const create = interactive
+      ? await askYesNo(`     → Create ${missingDocs.length} missing doc(s) from templates?`)
+      : true;
+
+    if (create) {
+      const today = new Date().toISOString().split('T')[0];
+      for (const doc of missingDocs) {
+        const destPath = resolve(projectDir, doc.file);
+        const templatePath = resolve(TEMPLATES_DIR, doc.template);
+
+        const destDir = dirname(destPath);
+        if (!existsSync(destDir)) {
+          mkdirSync(destDir, { recursive: true });
+        }
+
+        if (existsSync(templatePath)) {
+          const content = readFileSync(templatePath, 'utf-8').replace(/YYYY-MM-DD/g, today);
+          writeFileSync(destPath, content, 'utf-8');
+          console.log(`     ${c.green}✅ Created ${doc.file}${c.reset}`);
+          configured++;
+        }
+      }
+    }
+  }
+
+  console.log('');
+
+  // ── Step 3: AI Skills ──────────────────────────────────────────────
+
+  console.log(`  ${c.bold}Step 3/7: AI Skills${c.reset}`);
+
+  const skillNames = ['docguard-guard', 'docguard-fix', 'docguard-review', 'docguard-score'];
+  const skillsDest = resolve(projectDir, '.agent/skills');
+  let missingSkills = [];
+
+  for (const skill of skillNames) {
+    const skillPath = resolve(skillsDest, skill, 'SKILL.md');
+    if (existsSync(skillPath)) {
+      console.log(`  ${c.green}✅${c.reset} ${skill}`);
+      alreadyGood++;
+    } else {
+      console.log(`  ${c.yellow}⚠️${c.reset}  ${skill} ${c.dim}(not installed)${c.reset}`);
+      missingSkills.push(skill);
+    }
+  }
+
+  if (missingSkills.length > 0) {
+    const install = interactive
+      ? await askYesNo(`     → Install ${missingSkills.length} AI skill(s) to .agent/skills/?`)
+      : true;
+
+    if (install) {
+      for (const skill of missingSkills) {
+        const srcSkill = resolve(SKILLS_SOURCE, skill, 'SKILL.md');
+        const destDir = resolve(skillsDest, skill);
+        if (existsSync(srcSkill)) {
+          if (!existsSync(destDir)) mkdirSync(destDir, { recursive: true });
+          writeFileSync(resolve(destDir, 'SKILL.md'), readFileSync(srcSkill, 'utf-8'), 'utf-8');
+          console.log(`     ${c.green}✅ Installed ${skill}${c.reset}`);
+          configured++;
+        }
+      }
+    }
+  }
+
+  console.log('');
+
+  // ── Step 4: Slash Commands ─────────────────────────────────────────
+
+  console.log(`  ${c.bold}Step 4/7: Slash Commands${c.reset}`);
+
+  // Check root commands/ dir
+  const rootCommandsDir = resolve(projectDir, 'commands');
+  const rootCommandsExist = existsSync(resolve(rootCommandsDir, 'docguard.guard.md'));
+
+  if (rootCommandsExist) {
+    console.log(`  ${c.green}✅${c.reset} commands/ ${c.dim}(root)${c.reset}`);
+    alreadyGood++;
+  } else {
+    console.log(`  ${c.yellow}⚠️${c.reset}  commands/ ${c.dim}(not installed)${c.reset}`);
+  }
+
+  // Detect agent directories and sync commands
+  const detectedAgents = detectAgentDirs(projectDir);
+  let unsyncedAgents = [];
+
+  for (const agent of detectedAgents) {
+    const agentCommandCheck = resolve(projectDir, agent.commandsPath, 'docguard.guard.md');
+    if (existsSync(agentCommandCheck)) {
+      console.log(`  ${c.green}✅${c.reset} ${agent.commandsPath}/ ${c.dim}(${agent.name})${c.reset}`);
+      alreadyGood++;
+    } else {
+      console.log(`  ${c.yellow}⚠️${c.reset}  ${agent.commandsPath}/ ${c.dim}(${agent.name} — not synced)${c.reset}`);
+      unsyncedAgents.push(agent);
+    }
+  }
+
+  const needsCommands = !rootCommandsExist || unsyncedAgents.length > 0;
+
+  if (needsCommands && existsSync(COMMANDS_SOURCE)) {
+    const install = interactive
+      ? await askYesNo(`     → Install/sync slash commands?`)
+      : true;
+
+    if (install) {
+      const commandFiles = readdirSync(COMMANDS_SOURCE).filter(f => f.endsWith('.md'));
+
+      // Install to root commands/
+      if (!rootCommandsExist) {
+        if (!existsSync(rootCommandsDir)) mkdirSync(rootCommandsDir, { recursive: true });
+        for (const file of commandFiles) {
+          const destPath = resolve(rootCommandsDir, file);
+          if (!existsSync(destPath)) {
+            writeFileSync(destPath, readFileSync(resolve(COMMANDS_SOURCE, file), 'utf-8'), 'utf-8');
+          }
+        }
+        console.log(`     ${c.green}✅ Installed to commands/${c.reset}`);
+        configured++;
+      }
+
+      // Sync to agent-specific dirs
+      for (const agent of unsyncedAgents) {
+        const destDir = resolve(projectDir, agent.commandsPath);
+        if (!existsSync(destDir)) mkdirSync(destDir, { recursive: true });
+        for (const file of commandFiles) {
+          const destPath = resolve(destDir, file);
+          if (!existsSync(destPath)) {
+            writeFileSync(destPath, readFileSync(resolve(COMMANDS_SOURCE, file), 'utf-8'), 'utf-8');
+          }
+        }
+        console.log(`     ${c.green}✅ Synced to ${agent.commandsPath}/ (${agent.name})${c.reset}`);
+        configured++;
+      }
+    }
+  }
+
+  console.log('');
+
+  // ── Step 5: Agent Configs ──────────────────────────────────────────
+
+  console.log(`  ${c.bold}Step 5/7: Agent Configs${c.reset}`);
+
+  const agentConfigs = [
+    { file: 'AGENTS.md',  label: 'Agent Instructions' },
+    { file: 'CLAUDE.md',  label: 'Claude Code' },
+    { file: '.cursor/rules/cdd.mdc', label: 'Cursor' },
+    { file: '.github/copilot-instructions.md', label: 'GitHub Copilot' },
+  ];
+
+  let missingConfigs = [];
+  for (const cfg of agentConfigs) {
+    const fullPath = resolve(projectDir, cfg.file);
+    if (existsSync(fullPath)) {
+      console.log(`  ${c.green}✅${c.reset} ${cfg.file} ${c.dim}(${cfg.label})${c.reset}`);
+      alreadyGood++;
+    } else {
+      // AGENTS.md is handled in step 2, skip it here
+      if (cfg.file !== 'AGENTS.md') {
+        console.log(`  ${c.dim}──${c.reset}  ${cfg.file} ${c.dim}(${cfg.label} — not generated)${c.reset}`);
+        missingConfigs.push(cfg);
+      }
+    }
+  }
+
+  if (missingConfigs.length > 0) {
+    console.log(`  ${c.dim}   Run ${c.cyan}docguard agents${c.dim} to generate agent-specific configs${c.reset}`);
+  }
+
+  console.log('');
+
+  // ── Step 6: Integrations ───────────────────────────────────────────
+
+  console.log(`  ${c.bold}Step 6/7: Integrations${c.reset}`);
+
+  // Check spec-kit framework
+  const speckitDir = resolve(projectDir, '.speckit');
+  const hasSpeckit = existsSync(speckitDir) || existsSync(resolve(projectDir, 'spec.md'));
+  if (hasSpeckit) {
+    console.log(`  ${c.green}✅${c.reset} spec-kit ${c.dim}(spec-driven development configured)${c.reset}`);
+    alreadyGood++;
+  } else {
+    console.log(`  ${c.dim}──${c.reset}  spec-kit ${c.dim}(not configured — optional)${c.reset}`);
+    console.log(`  ${c.dim}     Spec Kit enables spec-driven development with AI agents${c.reset}`);
+    console.log(`  ${c.dim}     See: ${c.cyan}https://github.com/github/spec-kit${c.reset}`);
+  }
+
+  // Check for spec-kit extensions
+  const extensionsDir = resolve(projectDir, 'extensions');
+  
+  // DocGuard extension (this project IS DocGuard, so check if extension is bundled)
+  const docguardExt = resolve(extensionsDir, 'spec-kit-docguard', 'extension.yml');
+  if (existsSync(docguardExt)) {
+    console.log(`  ${c.green}✅${c.reset} docguard extension ${c.dim}(spec-kit CDD enforcement)${c.reset}`);
+    alreadyGood++;
+  } else {
+    // DocGuard is installed as a CLI, not necessarily as a spec-kit extension
+    console.log(`  ${c.green}✅${c.reset} docguard CLI ${c.dim}(standalone — 19 validators + 31 quality metrics)${c.reset}`);
+    alreadyGood++;
+  }
+
+  // Understanding extension (spec-kit community extension)
+  const understandingExt = resolve(extensionsDir, 'spec-kit-understanding', 'extension.yml');
+  if (existsSync(understandingExt)) {
+    console.log(`  ${c.green}✅${c.reset} understanding ${c.dim}(spec-kit deep doc analysis)${c.reset}`);
+    alreadyGood++;
+  } else {
+    console.log(`  ${c.dim}──${c.reset}  understanding ${c.dim}(spec-kit extension — optional)${c.reset}`);
+    console.log(`  ${c.dim}     Install via spec-kit: ${c.cyan}https://github.com/github/spec-kit/tree/main/extensions${c.reset}`);
+  }
+
+  console.log('');
+
+  // ── Step 7: Git Hooks ──────────────────────────────────────────────
+
+  console.log(`  ${c.bold}Step 7/7: Git Hooks${c.reset}`);
+
+  const gitDir = resolve(projectDir, '.git');
+  if (!existsSync(gitDir)) {
+    console.log(`  ${c.dim}──${c.reset}  No .git directory ${c.dim}(not a git repo)${c.reset}`);
+  } else {
+    const preCommitHook = resolve(gitDir, 'hooks', 'pre-commit');
+    let hasDocguardHook = false;
+
+    if (existsSync(preCommitHook)) {
+      const content = readFileSync(preCommitHook, 'utf-8');
+      hasDocguardHook = content.includes('docguard');
+    }
+
+    if (hasDocguardHook) {
+      console.log(`  ${c.green}✅${c.reset} pre-commit hook ${c.dim}(docguard guard)${c.reset}`);
+      alreadyGood++;
+    } else {
+      console.log(`  ${c.dim}──${c.reset}  pre-commit hook ${c.dim}(not installed)${c.reset}`);
+      if (interactive) {
+        const install = await askYesNo(`     → Install docguard guard as pre-commit hook?`, false);
+        if (install) {
+          try {
+            const hooksDir = resolve(gitDir, 'hooks');
+            if (!existsSync(hooksDir)) mkdirSync(hooksDir, { recursive: true });
+
+            const hookContent = existsSync(preCommitHook)
+              ? readFileSync(preCommitHook, 'utf-8') + '\n\n# DocGuard CDD validation\nnpx docguard guard --fail-on-warning\n'
+              : '#!/bin/sh\n\n# DocGuard CDD validation\nnpx docguard guard --fail-on-warning\n';
+
+            writeFileSync(preCommitHook, hookContent, { mode: 0o755 });
+            console.log(`     ${c.green}✅ Pre-commit hook installed${c.reset}`);
+            configured++;
+          } catch (e) {
+            console.log(`     ${c.yellow}⚠️  Failed to install hook: ${e.message}${c.reset}`);
+          }
+        }
+      }
+    }
+  }
+
+  // ── Summary ────────────────────────────────────────────────────────
+
+  console.log(`\n  ${c.bold}─────────────────────────────────────${c.reset}`);
+
+  if (configured > 0) {
+    console.log(`  ${c.green}✅ Setup complete!${c.reset} ${configured} item(s) configured, ${alreadyGood} already good.`);
+  } else if (alreadyGood > 0) {
+    console.log(`  ${c.green}✅ Everything is set up!${c.reset} ${alreadyGood} item(s) verified.`);
+  } else {
+    console.log(`  ${c.dim}No changes made.${c.reset}`);
+  }
+
+  console.log(`\n  ${c.bold}Next steps:${c.reset}`);
+  console.log(`  ${c.dim}Fill docs:${c.reset}      ${c.cyan}docguard diagnose${c.reset}`);
+  console.log(`  ${c.dim}Validate:${c.reset}       ${c.cyan}docguard guard${c.reset}`);
+  console.log(`  ${c.dim}Check score:${c.reset}    ${c.cyan}docguard score${c.reset}`);
+  console.log('');
+}

package/cli/docguard.mjs

@@ -38,6 +38,8 @@ import { runDiagnose } from './commands/diagnose.mjs';
 import { runPublish } from './commands/publish.mjs';
 import { runTrace } from './commands/trace.mjs';
 import { runLlms } from './commands/llms.mjs';
+import { runSetup } from './commands/setup.mjs';
+import { ensureSkills } from './ensure-skills.mjs';
 
 // ── Shared constants (imported to break circular dependencies) ──────────
 import { c, PROFILES } from './shared.mjs';
@@ -218,6 +220,7 @@ function printHelp() {
 
 ${c.bold}Getting Started:${c.reset}
   ${c.green}init${c.reset}       Initialize CDD docs (interactive setup)
+  ${c.green}setup${c.reset}      Full onboarding wizard (skills, integrations, hooks)
   ${c.green}generate${c.reset}   Reverse-engineer canonical docs from existing code
 
 ${c.bold}Enforcement:${c.reset}
@@ -376,6 +379,11 @@ async function main() {
 
   const config = loadConfig(projectDir);
 
+  // Silent auto-check: install skills/commands if missing
+  if (command !== 'setup' && command !== 'init') {
+    ensureSkills(projectDir, flags);
+  }
+
   switch (command) {
     case 'audit':
       // audit is an alias for guard — guard does everything the old audit did + 50 more checks
@@ -384,6 +392,10 @@ async function main() {
     case 'init':
       await runInit(projectDir, config, flags);
       break;
+    case 'setup':
+    case 'onboard':
+      await runSetup(projectDir, config, flags);
+      break;
     case 'guard':
       runGuard(projectDir, config, flags);
       break;

package/cli/ensure-skills.mjs

@@ -0,0 +1,96 @@
+/**
+ * Ensure Skills — Silent auto-check for DocGuard AI skills and commands
+ *
+ * Called before every command execution. If skills or commands are missing,
+ * copies them from the package's bundled assets into the project directory.
+ *
+ * Zero dependencies — pure Node.js built-ins only.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, cpSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { c } from './shared.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Source locations in the npm package
+const SKILLS_SOURCE = resolve(__dirname, '..', 'extensions', 'spec-kit-docguard', 'skills');
+const COMMANDS_SOURCE = resolve(__dirname, '..', 'commands');
+
+// Destination in the user's project
+const SKILLS_DEST = '.agent/skills';
+const COMMANDS_DEST = 'commands';
+
+/**
+ * Silently ensure skills and commands are installed in the project.
+ *
+ * @param {string} projectDir - The project root directory
+ * @param {object} flags - CLI flags (format, etc.)
+ * @returns {{ skillsInstalled: boolean, commandsInstalled: boolean }}
+ */
+export function ensureSkills(projectDir, flags = {}) {
+  const result = { skillsInstalled: false, commandsInstalled: false };
+  const silent = flags.format === 'json';
+
+  // ── Skills ────────────────────────────────────────────────────────────
+  const skillsCheck = resolve(projectDir, SKILLS_DEST, 'docguard-guard', 'SKILL.md');
+  if (!existsSync(skillsCheck) && existsSync(SKILLS_SOURCE)) {
+    try {
+      const skillDirs = readdirSync(SKILLS_SOURCE).filter(d =>
+        existsSync(resolve(SKILLS_SOURCE, d, 'SKILL.md'))
+      );
+
+      for (const skillDir of skillDirs) {
+        const destDir = resolve(projectDir, SKILLS_DEST, skillDir);
+        if (!existsSync(destDir)) {
+          mkdirSync(destDir, { recursive: true });
+        }
+        const srcSkill = resolve(SKILLS_SOURCE, skillDir, 'SKILL.md');
+        const destSkill = resolve(destDir, 'SKILL.md');
+        if (!existsSync(destSkill)) {
+          writeFileSync(destSkill, readFileSync(srcSkill, 'utf-8'), 'utf-8');
+        }
+      }
+
+      result.skillsInstalled = true;
+      if (!silent) {
+        console.log(`  ${c.cyan}✨ DocGuard AI skills installed → ${SKILLS_DEST}/${c.reset}`);
+      }
+    } catch {
+      // Silent failure — skills are optional enhancement
+    }
+  }
+
+  // ── Slash Commands ────────────────────────────────────────────────────
+  const commandsCheck = resolve(projectDir, COMMANDS_DEST, 'docguard.guard.md');
+  if (!existsSync(commandsCheck) && existsSync(COMMANDS_SOURCE)) {
+    try {
+      const commandFiles = readdirSync(COMMANDS_SOURCE).filter(f => f.endsWith('.md'));
+
+      if (commandFiles.length > 0) {
+        const destDir = resolve(projectDir, COMMANDS_DEST);
+        if (!existsSync(destDir)) {
+          mkdirSync(destDir, { recursive: true });
+        }
+
+        for (const file of commandFiles) {
+          const destPath = resolve(destDir, file);
+          if (!existsSync(destPath)) {
+            writeFileSync(destPath, readFileSync(resolve(COMMANDS_SOURCE, file), 'utf-8'), 'utf-8');
+          }
+        }
+
+        result.commandsInstalled = true;
+        if (!silent) {
+          console.log(`  ${c.cyan}✨ DocGuard slash commands installed → ${COMMANDS_DEST}/${c.reset}`);
+        }
+      }
+    } catch {
+      // Silent failure — commands are optional enhancement
+    }
+  }
+
+  return result;
+}

package/cli/validators/doc-quality.mjs

@@ -33,8 +33,8 @@ const THRESHOLDS = {
   passiveVoiceRatio:     { warn: 0.25, label: 'Passive voice ratio' },       // >25% passive = warn
   ambiguousPronounRatio: { warn: 0.15, label: 'Ambiguous pronoun ratio' },   // >15% ambiguous pronouns = warn
   atomicityScore:        { warn: 0.35, label: 'Non-atomic sentence ratio' }, // >35% compound sentences = warn
-  fleschReadingEase:     { warn: 15,   label: 'Flesch reading ease' },       // <15 = truly unreadable prose
-  fleschKincaidGrade:    { warn: 18,   label: 'Flesch-Kincaid grade' },      // >18 = graduate level+
+  fleschReadingEase:     { warn: 5,    label: 'Flesch reading ease' },       // <5 = truly unreadable prose (tech docs typically score 10-30)
+  fleschKincaidGrade:    { warn: 22,   label: 'Flesch-Kincaid grade' },      // >22 = PhD level+ (tech docs typically 14-20)
   avgSentenceLength:     { warn: 30,   label: 'Avg sentence length' },       // >30 words = too long
   negationLoad:          { warn: 0.20, label: 'Negation load' },             // >20% sentences with negation = warn
   conditionalLoad:       { warn: 0.30, label: 'Conditional load' },          // >30% sentences conditional = warn

package/cli/validators/docs-sync.mjs

@@ -118,18 +118,53 @@ export function validateDocsSync(projectDir, config) {
         if (!['.ts', '.js', '.mjs'].includes(ext)) continue;
 
         // Skip index/middleware files
-        const name = basename(file, ext).toLowerCase();
-        if (name === 'index' || name === 'middleware' || name.startsWith('_')) continue;
+        const rawName = basename(file, ext).toLowerCase();
+        if (rawName === 'index' || rawName === 'middleware' || rawName.startsWith('_')) continue;
 
         results.total++;
 
-        // Check if a likely route path exists in the OpenAPI spec
-        // Route file "users.ts" → check for "/users" in spec
-        if (openapiContent.includes(`/${name}`) || openapiContent.includes(`"${name}"`)) {
+        // Strategy 1: Parse the route file for actual route paths
+        // Look for router.get('/path'), app.post('/path'), etc.
+        let routeFileContent = '';
+        try { routeFileContent = readFileSync(file, 'utf-8').toLowerCase(); } catch { /* skip */ }
+
+        const actualRoutes = [];
+        const routeDefRegex = /(?:router|app|route)\s*\.\s*(?:get|post|put|delete|patch|all|use)\s*\(\s*['"`](\/[^'"`]*)['"`]/gi;
+        let routeMatch;
+        while ((routeMatch = routeDefRegex.exec(routeFileContent)) !== null) {
+          actualRoutes.push(routeMatch[1]);
+        }
+
+        let matched = false;
+
+        if (actualRoutes.length > 0) {
+          // Check if ANY of the actual route paths appear in the OpenAPI spec
+          matched = actualRoutes.some(route => {
+            // Normalize: /api/conversations/:id → /api/conversations
+            const basePath = route.replace(/\/:[^/]+/g, '').replace(/\/{[^}]+}/g, '');
+            return openapiContent.includes(basePath) || openapiContent.includes(route);
+          });
+        } else {
+          // Strategy 2 (fallback): Strip common suffixes and check filename
+          // userRoutes.ts → 'user', conversationRoutes.ts → 'conversation'
+          const cleanName = rawName
+            .replace(/routes?$/i, '')
+            .replace(/controllers?$/i, '')
+            .replace(/handlers?$/i, '')
+            .replace(/router$/i, '');
+
+          if (cleanName.length > 0) {
+            matched = openapiContent.includes(`/${cleanName}`) ||
+                      openapiContent.includes(`"${cleanName}"`) ||
+                      openapiContent.includes(`'${cleanName}'`);
+          }
+        }
+
+        if (matched) {
           results.passed++;
         } else {
           results.warnings.push(
-            `Route file ${basename(file)} exists but no /${name} path found in ${openapiFile}. ` +
+            `Route file ${basename(file)} exists but no matching paths found in ${openapiFile}. ` +
             `Run your spec generator (e.g., zod-to-openapi) to update the API spec`
           );
         }

package/cli/validators/todo-tracking.mjs

@@ -110,14 +110,19 @@ function checkSkippedTests(projectDir) {
       const isSkipped = SKIP_PATTERNS.some(p => p.test(line));
       if (!isSkipped) continue;
 
-      // Check surrounding lines (1 above, 1 below, and inline) for explanation
-      const prevLine = i > 0 ? lines[i - 1] : '';
-      const nextLine = i < lines.length - 1 ? lines[i + 1] : '';
+      // Check surrounding lines (3 above, 1 below, and inline) for explanation
+      // Developers commonly place block comments above the skip call
+      const surroundingLines = [];
+      for (let j = Math.max(0, i - 3); j <= Math.min(lines.length - 1, i + 1); j++) {
+        surroundingLines.push(lines[j]);
+      }
+
+      // Also check for block comment pattern: /* REASON: ... */ or /** ... REASON: ... */
+      const blockCommentPattern = /\/\*[\s\S]*?(REASON|SKIP|TODO|FIXME|NOTE|WHY)\s*:/i;
 
       const hasReason =
-        SKIP_REASON_PATTERN.test(prevLine) ||
-        SKIP_REASON_PATTERN.test(line) ||
-        SKIP_REASON_PATTERN.test(nextLine);
+        surroundingLines.some(l => SKIP_REASON_PATTERN.test(l)) ||
+        blockCommentPattern.test(surroundingLines.join('\n'));
 
       if (hasReason) {
         skippedWithReason++;

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

@@ -8,7 +8,7 @@ Enterprise-grade Canonical-Driven Development (CDD) enforcement for [Spec Kit](h
 - **4 AI Skills** — Enterprise-grade AI behavior protocols (not just step-lists)
 - **3 Bash Scripts** — JSON-output orchestration for AI consumption
 - **Workflow Chaining** — YAML handoffs enable guard → fix → review → score flows
-- **Spec Kit Hooks** — Mandatory quality gate after `/speckit.implement`
+- **Spec Kit Hooks** — Quality gate integrations at implement, tasks, and review phases
 - **Zero Dependencies** — Pure Node.js built-ins only
 
 ## Installation
@@ -40,16 +40,14 @@ docguard score
 
 ## Commands
 
-| Command | Purpose |
-|---------|---------|
-| `docguard.guard` | Run 19-validator quality gate with severity triage |
-| `docguard.fix` | AI-driven documentation repair with codebase research |
-| `docguard.review` | Cross-document semantic consistency analysis (read-only) |
-| `docguard.score` | CDD maturity score with ROI improvement roadmap |
-| `docguard.diagnose` | Diagnose issues + generate multi-perspective AI prompts |
-| `docguard.generate` | Reverse-engineer canonical docs from codebase |
-| `docguard.init` | Initialize CDD structure in a project |
-| `docguard.trace` | Generate requirements traceability matrix |
+| Command | Alias | Purpose |
+|---------|-------|---------|
+| `speckit.docguard.guard` | `docguard.guard` | Run 19-validator quality gate with severity triage |
+| `speckit.docguard.fix` | `docguard.fix` | AI-driven documentation repair with codebase research |
+| `speckit.docguard.review` | `docguard.review` | Cross-document semantic consistency analysis (read-only) |
+| `speckit.docguard.score` | `docguard.score` | CDD maturity score with ROI improvement roadmap |
+| `speckit.docguard.diagnose` | — | Diagnose issues + generate multi-perspective AI prompts |
+| `speckit.docguard.generate` | — | Reverse-engineer canonical docs from codebase |
 
 ## AI Skills
 
@@ -72,12 +70,12 @@ DocGuard integrates into the spec-kit workflow through hooks:
 
 ```yaml
 hooks:
-  after_implement:   # Mandatory — always runs after /speckit.implement
-    command: docguard.guard
+  after_implement:   # Optional — quality gate after /speckit.implement
+    command: speckit.docguard.guard
   before_tasks:      # Optional — review docs before task generation
-    command: docguard.review
+    command: speckit.docguard.review
   after_tasks:       # Optional — show score after tasks
-    command: docguard.score
+    command: speckit.docguard.score
 ```
 
 ### Workflow Chaining

package/extensions/spec-kit-docguard/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.9.6"
+  version: "0.9.7"
   description: "Canonical-Driven Development enforcement with enterprise-grade AI skills. 19 automated validators, structured research workflows, quality validation loops, and spec-kit integration hooks. Zero dependencies."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"
@@ -21,78 +21,62 @@ requires:
 
 provides:
   commands:
-    - name: "docguard.guard"
+    - name: "speckit.docguard.guard"
       file: "commands/guard.md"
       description: "Run 19-validator quality gate with severity triage and remediation plan"
-      aliases: ["speckit.docguard.guard"]
+      aliases: ["docguard.guard"]
 
-    - name: "docguard.fix"
-      file: "commands/fix.md"
+    - name: "speckit.docguard.fix"
+      file: "commands/generate.md"
       description: "AI-driven documentation repair with codebase research and validation loops"
-      aliases: ["speckit.docguard.fix"]
+      aliases: ["docguard.fix"]
 
-    - name: "docguard.review"
-      file: "commands/review.md"
+    - name: "speckit.docguard.review"
+      file: "commands/diagnose.md"
       description: "Cross-document semantic consistency analysis (read-only)"
-      aliases: ["speckit.docguard.review"]
+      aliases: ["docguard.review"]
 
-    - name: "docguard.score"
+    - name: "speckit.docguard.score"
       file: "commands/score.md"
       description: "CDD maturity score with ROI-based improvement roadmap"
-      aliases: ["speckit.docguard.score"]
+      aliases: ["docguard.score"]
 
     - name: "speckit.docguard.diagnose"
-      file: "commands/review.md"
+      file: "commands/diagnose.md"
       description: "Diagnose all issues and generate a complete AI remediation plan"
 
     - name: "speckit.docguard.generate"
-      file: "commands/fix.md"
+      file: "commands/generate.md"
       description: "Reverse-engineer canonical docs from existing codebase"
 
-  skills:
-    - name: "docguard-guard"
-      path: "skills/docguard-guard/SKILL.md"
-      description: "19-validator quality gate with severity triage and structured reporting"
-
-    - name: "docguard-fix"
-      path: "skills/docguard-fix/SKILL.md"
-      description: "AI-driven documentation repair with research workflow and validation loops"
-
-    - name: "docguard-review"
-      path: "skills/docguard-review/SKILL.md"
-      description: "Cross-document semantic consistency analysis with quality scoring"
-
-    - name: "docguard-score"
-      path: "skills/docguard-score/SKILL.md"
-      description: "CDD maturity assessment with ROI-based improvement roadmap"
-
+  # Helper scripts for CI/CD and automation
   scripts:
     - name: "docguard-check-docs"
-      path: "scripts/bash/docguard-check-docs.sh"
+      file: "scripts/bash/docguard-check-docs.sh"
       description: "Discover project docs, return JSON inventory with metadata"
 
     - name: "docguard-suggest-fix"
-      path: "scripts/bash/docguard-suggest-fix.sh"
+      file: "scripts/bash/docguard-suggest-fix.sh"
       description: "Run guard, parse results, output prioritized fix suggestions"
 
     - name: "docguard-init-doc"
-      path: "scripts/bash/docguard-init-doc.sh"
+      file: "scripts/bash/docguard-init-doc.sh"
       description: "Initialize a new canonical document with metadata header"
 
 hooks:
   after_implement:
-    command: "docguard.guard"
-    optional: false
-    prompt: "Run DocGuard validation after implementation"
-    description: "Mandatory quality gate — ensures docs stay in sync with code"
+    command: "speckit.docguard.guard"
+    optional: true
+    prompt: "Run DocGuard validation after implementation?"
+    description: "Quality gate — ensures docs stay in sync with code"
 
   before_tasks:
-    command: "docguard.review"
+    command: "speckit.docguard.review"
     optional: true
     prompt: "Review documentation consistency before generating tasks?"
 
   after_tasks:
-    command: "docguard.score"
+    command: "speckit.docguard.score"
     optional: true
     prompt: "Show CDD maturity score after task generation?"
 
@@ -106,4 +90,3 @@ tags:
   - "ai-agents"
   - "enforcement"
   - "spec-kit"
-  - "skills"

package/extensions/spec-kit-docguard/templates/extensions.yml

@@ -14,16 +14,16 @@ hooks:
   # This ensures documentation stays in sync with code changes
   after_implement:
     - extension: docguard
-      command: docguard.guard
+      command: speckit.docguard.guard
       description: "Validate documentation passes CDD standards after implementation"
       enabled: true
-      optional: false  # Mandatory — always runs after implement
-      prompt: "Run DocGuard guard to verify documentation quality after implementation changes"
+      optional: true
+      prompt: "Run DocGuard guard to verify documentation quality after implementation changes?"
 
   # Run DocGuard review before /speckit.tasks to catch doc drift early
   before_tasks:
     - extension: docguard
-      command: docguard.review
+      command: speckit.docguard.review
       description: "Review documentation consistency before generating tasks"
       enabled: true
       optional: true  # Optional — user can skip
@@ -32,7 +32,7 @@ hooks:
   # Run DocGuard guard after /speckit.tasks to validate doc coverage
   after_tasks:
     - extension: docguard
-      command: docguard.score
+      command: speckit.docguard.score
       description: "Show CDD maturity score after task generation"
       enabled: true
       optional: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {