docguard-cli 0.9.8 → 0.9.10

package/cli/commands/score.mjs

@@ -7,6 +7,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
 import { execSync } from 'node:child_process';
 import { c } from '../shared.mjs';
+import { validateSecurity } from '../validators/security.mjs';
 
 const WEIGHTS = {
   structure: 25,     // Required files exist
@@ -410,15 +411,32 @@ function calcTestingScore(dir, config) {
   const testDirs = ['tests', 'test', '__tests__', 'spec', 'e2e'];
   const hasTopLevelTestDir = testDirs.some(d => existsSync(resolve(dir, d)));
 
-  // Check co-located tests: src/**/__tests__/ and src/**/*.test.* / src/**/*.spec.*
+  // Check co-located tests: **/__tests__/ and **/*.test.* / **/*.spec.*
+  // Scan ALL common source roots — not just src/, also backend/, packages/, etc.
   let hasColocatedTests = false;
   if (!hasTopLevelTestDir) {
     hasColocatedTests = findColocatedTests(dir);
   }
 
+  // Check if testPatterns config points to existing test locations
+  let hasPatternTests = false;
+  if (!hasTopLevelTestDir && !hasColocatedTests) {
+    const patterns = config.testPatterns || [];
+    if (patterns.length > 0) {
+      for (const pattern of patterns) {
+        // Extract the root directory from the pattern
+        const rootDir = pattern.split('/')[0].split('*')[0];
+        if (rootDir && existsSync(resolve(dir, rootDir))) {
+          hasPatternTests = true;
+          break;
+        }
+      }
+    }
+  }
+
   // Check vitest/jest config for custom test patterns
   let hasConfigTests = false;
-  if (!hasTopLevelTestDir && !hasColocatedTests) {
+  if (!hasTopLevelTestDir && !hasColocatedTests && !hasPatternTests) {
     const testConfigs = ['vitest.config.ts', 'vitest.config.js', 'vitest.config.mts', 'jest.config.ts', 'jest.config.js'];
     for (const cfgFile of testConfigs) {
       const cfgPath = resolve(dir, cfgFile);
@@ -448,7 +466,7 @@ function calcTestingScore(dir, config) {
     }
   }
 
-  if (hasTopLevelTestDir || hasColocatedTests || hasConfigTests) score += 40;
+  if (hasTopLevelTestDir || hasColocatedTests || hasPatternTests || hasConfigTests) score += 40;
 
   // ── Check 2: TEST-SPEC.md exists (30 pts) ──
   if (existsSync(resolve(dir, 'docs-canonical/TEST-SPEC.md'))) score += 30;
@@ -490,7 +508,8 @@ function calcTestingScore(dir, config) {
  */
 function findColocatedTests(dir) {
   // Scan these common source roots for co-located tests
-  const sourceRoots = ['src', 'app', 'lib', 'packages', 'modules'];
+  // Includes backend/, server/ for monorepo-style projects (e.g., backend/src/__tests__/)
+  const sourceRoots = ['src', 'app', 'lib', 'packages', 'modules', 'backend', 'server'];
   const ignoreSet = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', '.cache']);
 
   for (const root of sourceRoots) {
@@ -534,25 +553,44 @@ function calcSecurityScore(dir, config) {
   let score = 0;
   const ptc = config.projectTypeConfig || {};
 
-  // SECURITY.md exists
-  if (existsSync(resolve(dir, 'docs-canonical/SECURITY.md'))) score += 30;
+  // SECURITY.md exists (25 pts)
+  if (existsSync(resolve(dir, 'docs-canonical/SECURITY.md'))) score += 25;
 
-  // .gitignore exists and includes .env
+  // .gitignore exists and includes .env (15 + 15 pts)
   const gitignorePath = resolve(dir, '.gitignore');
   if (existsSync(gitignorePath)) {
-    score += 20;
+    score += 15;
     const content = readFileSync(gitignorePath, 'utf-8');
-    if (content.includes('.env')) score += 20;
+    if (content.includes('.env')) score += 15;
   }
 
-  // No .env file committed (check if .env exists but .gitignore covers it)
-  if (!existsSync(resolve(dir, '.env')) || existsSync(gitignorePath)) score += 15;
+  // No .env file committed (10 pts)
+  if (!existsSync(resolve(dir, '.env')) || existsSync(gitignorePath)) score += 10;
 
-  // .env.example exists (safe template) — only check if project needs env vars
+  // .env.example exists (safe template) — only check if project needs env vars (10 pts)
   if (ptc.needsEnvExample === false) {
-    score += 15; // Full marks — project doesn't need env vars
+    score += 10; // Full marks — project doesn't need env vars
   } else if (existsSync(resolve(dir, '.env.example'))) {
-    score += 15;
+    score += 10;
+  }
+
+  // No hardcoded secrets found by security validator (25 pts)
+  // Commands MAY compose validator results (Constitution IV, v1.1.0)
+  try {
+    const secResults = validateSecurity(dir, config);
+    if (secResults.errors.length === 0) {
+      score += 25;
+    } else {
+      // Partial credit: deduct proportionally, but give at least some credit
+      // if there are few findings relative to project size
+      const findingCount = secResults.errors.length;
+      if (findingCount <= 2) score += 15;
+      else if (findingCount <= 5) score += 5;
+      // 6+ findings = 0 pts for this check
+    }
+  } catch {
+    // If validator fails to run, give benefit of the doubt
+    score += 25;
   }
 
   return Math.min(100, score);
@@ -668,8 +706,12 @@ function getSuggestion(category, score, details) {
   const suggestions = {
     structure: 'Run `docguard init` to create missing documentation',
     docQuality: 'Run `docguard fix` to get AI prompts for each doc that needs content',
-    testing: 'Add tests/ directory and configure TEST-SPEC.md',
-    security: 'Create SECURITY.md and add .env to .gitignore → Run `docguard fix --doc security`',
+    testing: score < 40
+      ? 'Add test files (tests/, src/**/__tests__/, or configure testPatterns in .docguard.json) and create TEST-SPEC.md'
+      : 'Configure TEST-SPEC.md and add CI test step → Run `docguard fix --doc test-spec`',
+    security: score < 50
+      ? 'Create SECURITY.md and add .env to .gitignore → Run `docguard fix --doc security`'
+      : 'Review security findings with `docguard guard --verbose` — configure securityIgnore for false positives',
     environment: 'Document env variables and create .env.example → Run `docguard fix --doc environment`',
     drift: 'Create DRIFT-LOG.md and log any code deviations',
     changelog: 'Maintain CHANGELOG.md with [Unreleased] section',

package/cli/commands/setup.mjs

@@ -13,7 +13,8 @@
  * 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.
+ * Zero NPM runtime dependencies — pure Node.js built-ins only.
+ * Framework dependency: spec-kit (convention, not code).
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
@@ -22,7 +23,7 @@ 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';
+import { ensureSkills, detectAgentMode, isSpecKitInitialized, getDetectedAgent } from '../ensure-skills.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -211,11 +212,17 @@ export async function runSetup(projectDir, config, flags) {
 
   console.log(`  ${c.bold}Step 3/7: AI Skills${c.reset}`);
 
-  const skillNames = ['docguard-guard', 'docguard-fix', 'docguard-review', 'docguard-score'];
+  const docguardSkills = ['docguard-guard', 'docguard-fix', 'docguard-review', 'docguard-score'];
+  const speckitSkills = [
+    'speckit-specify', 'speckit-plan', 'speckit-tasks', 'speckit-implement',
+    'speckit-analyze', 'speckit-clarify', 'speckit-checklist', 'speckit-constitution',
+    'speckit-taskstoissues',
+  ];
+  const allSkillNames = [...docguardSkills, ...speckitSkills];
   const skillsDest = resolve(projectDir, '.agent/skills');
   let missingSkills = [];
 
-  for (const skill of skillNames) {
+  for (const skill of allSkillNames) {
     const skillPath = resolve(skillsDest, skill, 'SKILL.md');
     if (existsSync(skillPath)) {
       console.log(`  ${c.green}✅${c.reset} ${skill}`);
@@ -227,19 +234,28 @@ export async function runSetup(projectDir, config, flags) {
   }
 
   if (missingSkills.length > 0) {
-    const install = interactive
-      ? await askYesNo(`     → Install ${missingSkills.length} AI skill(s) to .agent/skills/?`)
-      : true;
+    const hasSpeckitMissing = missingSkills.some(s => s.startsWith('speckit-'));
+    const hasDocguardMissing = missingSkills.some(s => s.startsWith('docguard-'));
 
-    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++;
+    if (hasSpeckitMissing) {
+      console.log(`  ${c.dim}   Spec-kit skills installed via: ${c.cyan}specify init --here --force --ai-skills${c.reset}`);
+    }
+
+    if (hasDocguardMissing) {
+      const install = interactive
+        ? await askYesNo(`     → Install ${missingSkills.filter(s => s.startsWith('docguard-')).length} DocGuard skill(s) to .agent/skills/?`)
+        : true;
+
+      if (install) {
+        for (const skill of missingSkills.filter(s => s.startsWith('docguard-'))) {
+          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++;
+          }
         }
       }
     }
@@ -354,16 +370,20 @@ export async function runSetup(projectDir, config, flags) {
 
   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}`);
+  // Check spec-kit framework (Extension-First: detect .specify/ directory)
+  const specKitInitialized = isSpecKitInitialized(projectDir);
+  const specifyDir = resolve(projectDir, '.specify');
+  if (specKitInitialized) {
+    const agent = getDetectedAgent(projectDir);
+    console.log(`  ${c.green}✅${c.reset} spec-kit ${c.dim}(SDD configured${agent ? `, agent: ${agent}` : ''})${c.reset}`);
     alreadyGood++;
+  } else if (existsSync(specifyDir)) {
+    console.log(`  ${c.yellow}⚠️${c.reset}  spec-kit ${c.dim}(.specify/ exists but not fully initialized)${c.reset}`);
+    console.log(`  ${c.dim}     Run: ${c.cyan}specify init --here --force --ai-skills${c.reset}`);
   } 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}`);
+    console.log(`  ${c.dim}──${c.reset}  spec-kit ${c.dim}(not configured — recommended for full SDD+CDD workflow)${c.reset}`);
+    console.log(`  ${c.dim}     Install: ${c.cyan}uv tool install specify-cli --from git+https://github.com/github/spec-kit.git${c.reset}`);
+    console.log(`  ${c.dim}     Then: ${c.cyan}docguard init${c.reset} ${c.dim}(will auto-run specify init)${c.reset}`);
   }
 
   // Check for spec-kit extensions
@@ -421,8 +441,8 @@ export async function runSetup(projectDir, config, flags) {
             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';
+              ? readFileSync(preCommitHook, 'utf-8') + '\n\n# DocGuard CDD validation\nnpx docguard-cli guard --fail-on-warning\n'
+              : '#!/bin/sh\n\n# DocGuard CDD validation\nnpx docguard-cli guard --fail-on-warning\n';
 
             writeFileSync(preCommitHook, hookContent, { mode: 0o755 });
             console.log(`     ${c.green}✅ Pre-commit hook installed${c.reset}`);
@@ -447,9 +467,19 @@ export async function runSetup(projectDir, config, flags) {
     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}`);
+  const agentMode = detectAgentMode(projectDir);
+  console.log(`\n  ${c.bold}Next steps:${c.reset} ${c.dim}(${agentMode === 'llm' ? 'LLM mode' : 'CLI mode'})${c.reset}`);
+  if (agentMode === 'llm') {
+    if (!isSpecKitInitialized(projectDir)) {
+      console.log(`  ${c.dim}Bootstrap:${c.reset}      ${c.cyan}/speckit.constitution${c.reset}`);
+    }
+    console.log(`  ${c.dim}Fill docs:${c.reset}      ${c.cyan}/docguard.guard${c.reset}`);
+    console.log(`  ${c.dim}Fix issues:${c.reset}     ${c.cyan}/docguard.fix${c.reset}`);
+    console.log(`  ${c.dim}Review:${c.reset}         ${c.cyan}/docguard.review${c.reset}`);
+  } else {
+    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

@@ -3,13 +3,13 @@
 /**
  * DocGuard CLI — The enforcement tool for Canonical-Driven Development (CDD)
  * 
- * Zero dependencies. Pure Node.js.
+ * Zero NPM runtime dependencies. Pure Node.js.
  * 
  * Usage:
- *   npx docguard audit     — Scan project, report what docs exist/missing
- *   npx docguard init      — Initialize CDD docs from templates
- *   npx docguard guard     — Validate project against its canonical docs
- *   npx docguard --help    — Show help
+ *   npx docguard-cli audit     — Scan project, report what docs exist/missing
+ *   npx docguard-cli init      — Initialize CDD docs from templates
+ *   npx docguard-cli guard     — Validate project against its canonical docs
+ *   npx docguard-cli --help    — Show help
  * 
  * @see https://github.com/raccioly/docguard
  */
@@ -128,6 +128,15 @@ export function loadConfig(projectDir) {
         ...getProjectTypeDefaults(merged.projectType),
         ...(merged.projectTypeConfig || {}),
       };
+      // Normalize testPattern (string) → testPatterns (array) for backward compat
+      if (merged.testPattern && !merged.testPatterns) {
+        merged.testPatterns = [merged.testPattern];
+      } else if (merged.testPattern && merged.testPatterns) {
+        // Both set — merge, deduplicate
+        if (!merged.testPatterns.includes(merged.testPattern)) {
+          merged.testPatterns.push(merged.testPattern);
+        }
+      }
       return merged;
     } catch (e) {
       console.error(`${c.red}Error parsing .docguard.json: ${e.message}${c.reset}`);

package/cli/ensure-skills.mjs

@@ -4,12 +4,16 @@
  * 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.
+ * Also provides agent mode detection (LLM vs CLI) and spec-kit availability.
+ *
+ * Zero npm dependencies — pure Node.js built-ins only.
+ * Framework dependency: spec-kit (convention, not code).
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, cpSync } from 'node:fs';
-import { resolve, dirname, join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { execSync } from 'node:child_process';
 import { c } from './shared.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -23,23 +27,224 @@ const COMMANDS_SOURCE = resolve(__dirname, '..', 'commands');
 const SKILLS_DEST = '.agent/skills';
 const COMMANDS_DEST = 'commands';
 
+// ── Agent Mode Detection ────────────────────────────────────────────────
+
+/**
+ * Detect if user is in LLM mode (AI agent) or CLI mode (terminal).
+ * DocGuard is LLM-first — defaults to 'llm' when any agent signal detected.
+ *
+ * @param {string} projectDir - The project root directory
+ * @returns {'llm' | 'cli'}
+ */
+export function detectAgentMode(projectDir) {
+  // First check .specify/init-options.json for explicit AI agent selection
+  const initOptions = resolve(projectDir, '.specify', 'init-options.json');
+  if (existsSync(initOptions)) {
+    try {
+      const opts = JSON.parse(readFileSync(initOptions, 'utf-8'));
+      if (opts.ai) return 'llm'; // spec-kit was initialized with an AI agent
+    } catch { /* ignore */ }
+  }
+
+  // Check for LLM signal directories/files
+  const llmSignals = [
+    '.agent/skills',
+    '.cursor',
+    '.claude',
+    '.specify',
+    '.github/copilot-instructions.md',
+    'CLAUDE.md',
+    '.gemini',
+    '.agents',
+  ];
+
+  for (const signal of llmSignals) {
+    if (existsSync(resolve(projectDir, signal))) return 'llm';
+  }
+
+  return 'cli';
+}
+
+/**
+ * Get the detected AI agent name from spec-kit init options.
+ * Returns null if spec-kit hasn't been initialized.
+ *
+ * @param {string} projectDir - The project root directory
+ * @returns {string | null}
+ */
+export function getDetectedAgent(projectDir) {
+  const initOptions = resolve(projectDir, '.specify', 'init-options.json');
+  if (existsSync(initOptions)) {
+    try {
+      const opts = JSON.parse(readFileSync(initOptions, 'utf-8'));
+      return opts.ai || null;
+    } catch { /* ignore */ }
+  }
+  return null;
+}
+
+/**
+ * Detect which AI agent is in use, returning the spec-kit --ai flag value.
+ * Matches spec-kit's supported agents: agy, claude, copilot, cursor-agent,
+ * gemini, windsurf, codex, roo, etc.
+ *
+ * Priority: .specify/init-options.json > filesystem signals > null
+ *
+ * @param {string} projectDir - The project root directory
+ * @returns {string | null} - spec-kit --ai flag value, or null if unknown
+ */
+export function detectAIAgent(projectDir) {
+  // 1. Check spec-kit init options (already initialized — trust it)
+  const existing = getDetectedAgent(projectDir);
+  if (existing) return existing;
+
+  // 2. Map filesystem signals to spec-kit agent IDs
+  // Order matters: more specific signals first
+  const agentSignals = [
+    { signal: '.cursor',                        agent: 'cursor-agent' },
+    { signal: '.claude',                        agent: 'claude' },
+    { signal: 'CLAUDE.md',                      agent: 'claude' },
+    { signal: '.gemini',                        agent: 'gemini' },
+    { signal: '.agents',                        agent: 'agy' },         // Antigravity
+    { signal: '.github/copilot-instructions.md', agent: 'copilot' },
+    { signal: '.windsurf',                      agent: 'windsurf' },
+    { signal: '.codex',                         agent: 'codex' },
+    { signal: '.roo',                           agent: 'roo' },
+    { signal: '.amp',                           agent: 'amp' },
+    { signal: '.kiro',                          agent: 'kiro-cli' },
+    { signal: '.tabnine',                       agent: 'tabnine' },
+  ];
+
+  for (const { signal, agent } of agentSignals) {
+    if (existsSync(resolve(projectDir, signal))) return agent;
+  }
+
+  // 3. No signal found — return null (caller decides: interactive vs generic)
+  return null;
+}
+
+/**
+ * Check if the specify CLI (spec-kit) is available on PATH.
+ *
+ * @returns {boolean}
+ */
+export function isSpecKitAvailable() {
+  try {
+    const cmd = process.platform === 'win32' ? 'where specify' : 'which specify';
+    execSync(cmd, { encoding: 'utf-8', stdio: 'pipe', timeout: 3000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
- * Silently ensure skills and commands are installed in the project.
+ * Check if spec-kit has been initialized in this project.
+ *
+ * @param {string} projectDir - The project root directory
+ * @returns {boolean}
+ */
+export function isSpecKitInitialized(projectDir) {
+  return existsSync(resolve(projectDir, '.specify', 'init-options.json'));
+}
+
+// ── Spec-Kit Integration Gate ───────────────────────────────────────────
+
+// Read DocGuard package version (for skill auto-update)
+const PKG_VERSION = (() => {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf-8'));
+    return pkg.version || '0.0.0';
+  } catch { return '0.0.0'; }
+})();
+
+const SPEC_KIT_INSTALL_CMD = 'uv tool install specify-cli --from git+https://github.com/github/spec-kit.git';
+
+/**
+ * Ensure spec-kit is initialized in the project.
+ * Called on every command run — this is the persistent nudge.
+ *
+ * - If .specify/ exists → do nothing
+ * - If specify CLI available → auto-run specify init with detected agent
+ * - If specify CLI not available → show prominent install reminder (every time)
+ *
+ * @param {string} projectDir - The project root directory
+ * @param {object} flags - CLI flags
+ * @returns {{ specKitReady: boolean }}
+ */
+export function ensureSpecKit(projectDir, flags = {}) {
+  const silent = flags.format === 'json';
+
+  // Already initialized — nothing to do
+  if (isSpecKitInitialized(projectDir)) {
+    return { specKitReady: true };
+  }
+
+  // Spec-kit CLI available — auto-initialize
+  if (isSpecKitAvailable()) {
+    if (!silent) {
+      console.log(`  ${c.cyan}🌱 Spec Kit detected — auto-initializing SDD workflow...${c.reset}`);
+    }
+    try {
+      const detectedAgent = detectAIAgent(projectDir);
+      const aiFlag = detectedAgent
+        ? `--ai ${detectedAgent}`
+        : '--ai generic --ai-commands-dir .agent/commands/';
+      const scriptFlag = process.platform === 'win32' ? '--script ps' : '--script sh';
+      execSync(
+        `specify init --here --force ${aiFlag} --ai-skills --ignore-agent-tools --no-git ${scriptFlag}`,
+        { cwd: projectDir, encoding: 'utf-8', stdio: 'pipe', timeout: 30000 }
+      );
+      if (!silent) {
+        console.log(`  ${c.green}✅ Spec Kit initialized${c.reset} ${c.dim}(agent: ${detectedAgent || 'generic'}, 9 skills installed)${c.reset}\n`);
+      }
+      return { specKitReady: true };
+    } catch {
+      // Failed silently — will show reminder instead
+    }
+  }
+
+  // No specify CLI — show prominent reminder (every time, no dismiss)
+  if (!silent) {
+    console.log(`  ${c.yellow}┌─────────────────────────────────────────────────────────┐${c.reset}`);
+    console.log(`  ${c.yellow}│${c.reset}  ${c.bold}💡 Spec Kit not installed${c.reset}                                ${c.yellow}│${c.reset}`);
+    console.log(`  ${c.yellow}│${c.reset}                                                          ${c.yellow}│${c.reset}`);
+    console.log(`  ${c.yellow}│${c.reset}  DocGuard is a Spec Kit extension. Install Spec Kit      ${c.yellow}│${c.reset}`);
+    console.log(`  ${c.yellow}│${c.reset}  for the full experience: 13 AI skills, SDD workflow,    ${c.yellow}│${c.reset}`);
+    console.log(`  ${c.yellow}│${c.reset}  project constitution, and seamless agent integration.   ${c.yellow}│${c.reset}`);
+    console.log(`  ${c.yellow}│${c.reset}                                                          ${c.yellow}│${c.reset}`);
+    console.log(`  ${c.yellow}│${c.reset}  ${c.cyan}${SPEC_KIT_INSTALL_CMD}${c.reset}`);
+    console.log(`  ${c.yellow}│${c.reset}                                                          ${c.yellow}│${c.reset}`);
+    console.log(`  ${c.yellow}│${c.reset}  ${c.dim}Then run: ${c.cyan}docguard init${c.reset}                                ${c.yellow}│${c.reset}`);
+    console.log(`  ${c.yellow}└─────────────────────────────────────────────────────────┘${c.reset}\n`);
+  }
+
+  return { specKitReady: false };
+}
+
+// ── Skill Installation ──────────────────────────────────────────────────
+
+/**
+ * Silently ensure DocGuard skills and commands are installed in the project.
+ * Also checks spec-kit integration and auto-updates stale skills.
  *
  * @param {string} projectDir - The project root directory
  * @param {object} flags - CLI flags (format, etc.)
- * @returns {{ skillsInstalled: boolean, commandsInstalled: boolean }}
+ * @returns {{ skillsInstalled: boolean, commandsInstalled: boolean, specKitReady: boolean }}
  */
 export function ensureSkills(projectDir, flags = {}) {
-  const result = { skillsInstalled: false, commandsInstalled: false };
+  const result = { skillsInstalled: false, commandsInstalled: false, specKitReady: false };
   const silent = flags.format === 'json';
 
-  // ── Skills ────────────────────────────────────────────────────────────
-  const skillsCheck = resolve(projectDir, SKILLS_DEST, 'docguard-guard', 'SKILL.md');
-  if (!existsSync(skillsCheck) && existsSync(SKILLS_SOURCE)) {
+  // ── Spec-Kit Gate (runs on every command) ─────────────────────────────
+  const specKitResult = ensureSpecKit(projectDir, flags);
+  result.specKitReady = specKitResult.specKitReady;
+
+  // ── DocGuard Skills (install + auto-update) ───────────────────────────
+  if (existsSync(SKILLS_SOURCE)) {
     try {
       const skillDirs = readdirSync(SKILLS_SOURCE).filter(d =>
-        existsSync(resolve(SKILLS_SOURCE, d, 'SKILL.md'))
+        d.startsWith('docguard-') && existsSync(resolve(SKILLS_SOURCE, d, 'SKILL.md'))
       );
 
       for (const skillDir of skillDirs) {
@@ -49,14 +254,26 @@ export function ensureSkills(projectDir, flags = {}) {
         }
         const srcSkill = resolve(SKILLS_SOURCE, skillDir, 'SKILL.md');
         const destSkill = resolve(destDir, 'SKILL.md');
+
         if (!existsSync(destSkill)) {
+          // New install
           writeFileSync(destSkill, readFileSync(srcSkill, 'utf-8'), 'utf-8');
+          result.skillsInstalled = true;
+        } else {
+          // Auto-update: check if package version is newer than installed
+          const installedContent = readFileSync(destSkill, 'utf-8');
+          const versionMatch = installedContent.match(/docguard:version:\s*(\S+)/);
+          const installedVersion = versionMatch ? versionMatch[1] : '0.0.0';
+
+          if (installedVersion !== PKG_VERSION) {
+            writeFileSync(destSkill, readFileSync(srcSkill, 'utf-8'), 'utf-8');
+            result.skillsInstalled = true;
+          }
         }
       }
 
-      result.skillsInstalled = true;
-      if (!silent) {
-        console.log(`  ${c.cyan}✨ DocGuard AI skills installed → ${SKILLS_DEST}/${c.reset}`);
+      if (result.skillsInstalled && !silent) {
+        console.log(`  ${c.cyan}✨ DocGuard AI skills installed/updated → ${SKILLS_DEST}/${c.reset}`);
       }
     } catch {
       // Silent failure — skills are optional enhancement
@@ -94,3 +311,4 @@ export function ensureSkills(projectDir, flags = {}) {
 
   return result;
 }
+

package/cli/scanners/speckit.mjs

@@ -19,7 +19,7 @@
  * Credit: Integration with GitHub's Spec Kit framework
  *         (github.com/github/spec-kit)
  *
- * Zero dependencies — pure Node.js built-ins only.
+ * Zero NPM runtime dependencies — pure Node.js built-ins only.
  */
 
 import { existsSync, readFileSync, readdirSync, statSync, copyFileSync, writeFileSync } from 'node:fs';