docguard-cli 0.18.1 → 0.21.0

package/cli/docguard.mjs

@@ -44,6 +44,7 @@ import { runUpgrade } from './commands/upgrade.mjs';
 import { runImpact } from './commands/impact.mjs';
 import { runExplain } from './commands/explain.mjs';
 import { runMemory } from './commands/memory.mjs';
+import { runDemo } from './commands/demo.mjs';
 import { ensureSkills } from './ensure-skills.mjs';
 
 // ── Shared constants (imported to break circular dependencies) ──────────
@@ -282,36 +283,41 @@ function printHelp() {
   console.log(`${c.bold}Usage:${c.reset}
   docguard <command> [options]
 
-${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}First-time? Try the demo (no install, no setup):${c.reset}
+  ${c.green}npx docguard-cli demo${c.reset}    ${c.dim}— 30-second tour against a sample project${c.reset}
 
-${c.bold}Enforcement:${c.reset}
-  ${c.green}guard${c.reset}      Validate project against canonical docs (51+ checks)
-  ${c.green}diagnose${c.reset}   AI orchestrator — guard → fix in one command
+${c.bold}The Daily 5${c.reset} ${c.dim}— what you'll reach for 95% of the time${c.reset}
+  ${c.green}init${c.reset}       Bootstrap a project — auto-detects existing code and scans (${c.cyan}--skeleton${c.reset} for blank templates, ${c.cyan}--wizard${c.reset} for guided, ${c.cyan}--with <name>${c.reset} for scaffolders)
+  ${c.green}guard${c.reset}      Validate against canonical docs (23 validators)
+  ${c.green}diff${c.reset}       Show gaps between docs and code (add ${c.cyan}--since <ref>${c.reset} for changed-file impact)
+  ${c.green}sync${c.reset}       Refresh code-truth doc sections — keeps memory always up to date
+  ${c.green}score${c.reset}      CDD maturity score (0-100; ${c.cyan}--diff${c.reset} for delta between refs)
 
-${c.bold}Memory (build & maintain docs):${c.reset}
-  ${c.green}generate --plan${c.reset}  AI-powered: scan any project, emit agent task manifest + skeleton
-  ${c.green}sync${c.reset}       Refresh code-truth doc sections to match current code (always up to date)
-
-${c.bold}Analysis:${c.reset}
-  ${c.green}score${c.reset}      CDD maturity score (0-100)
-  ${c.green}trace${c.reset}      Requirements traceability matrix
-  ${c.green}diff${c.reset}       Show gaps between docs and code (detailed view)
-
-${c.bold}CI/CD & Automation:${c.reset}
-  ${c.green}ci${c.reset}         Pipeline gate (guard + score, exit codes)
-  ${c.green}hooks${c.reset}      Install/manage git hooks
-  ${c.green}watch${c.reset}      Watch for changes, re-run guard
-
-${c.bold}Utilities:${c.reset}
+${c.bold}Tools (situational, but day-to-day useful)${c.reset}
+  ${c.green}demo${c.reset}       Zero-install tour: see what DocGuard catches against a sample project in 30s
+  ${c.green}diagnose${c.reset}   AI orchestrator — guard → emit fix prompts in one command
   ${c.green}fix${c.reset}        Generate AI fix instructions for specific docs
-  ${c.green}agents${c.reset}     Generate agent config files (AGENTS.md, CLAUDE.md)
-  ${c.green}badge${c.reset}      Generate CDD score badges for README
-
-${c.bold}Experimental:${c.reset}
-  ${c.dim}publish${c.reset}    Scaffold external doc sites (Mintlify)
+  ${c.green}generate${c.reset}   Reverse-engineer canonical docs from existing code (${c.cyan}--plan${c.reset} for AI scan)
+  ${c.green}explain${c.reset}    Explain a validator key or warning text
+  ${c.green}memory${c.reset}     Show what DocGuard remembers (${c.cyan}--diff${c.reset} drills into drift)
+  ${c.green}trace${c.reset}      Requirements traceability matrix (${c.cyan}--reverse${c.reset} for code→doc map)
+  ${c.green}upgrade${c.reset}    Migrate ${c.cyan}.docguard.json${c.reset} schema + CLI (${c.cyan}--apply --pr${c.reset} for team-wide PR)
+  ${c.green}watch${c.reset}      Live mode: re-run guard on file changes
+
+${c.bold}init --with <name>${c.reset} ${c.dim}— optional scaffolders, picked at init time${c.reset}
+  ${c.dim}agents${c.reset}     AGENTS.md / CLAUDE.md / .cursor/rules / Copilot instructions
+  ${c.dim}hooks${c.reset}      Git pre-commit / pre-push hooks
+  ${c.dim}ci${c.reset}         GitHub Actions / pipeline config
+  ${c.dim}badge${c.reset}      Shields.io score badges for README
+  ${c.dim}llms${c.reset}       llms.txt generation
+  ${c.dim}publish${c.reset}    External doc-site scaffold (Mintlify) ${c.dim}— experimental${c.reset}
+
+${c.bold}Deprecation aliases${c.reset} ${c.dim}— still work in v0.20.x with a yellow warning${c.reset}
+  ${c.dim}setup${c.reset} → ${c.cyan}init --wizard${c.reset}
+  ${c.dim}agents · hooks · ci · badge · llms · publish${c.reset} → ${c.cyan}init --with <name>${c.reset}
+  ${c.dim}impact${c.reset} → ${c.cyan}diff --since <ref>${c.reset}
+  ${c.dim}audit${c.reset} → ${c.green}guard${c.reset} ${c.dim}(permanent — no warning, no removal planned)${c.reset}
+  ${c.dim}See docs-implementation/MIGRATION-v0.20.md for the full timeline.${c.reset}
 
 ${c.bold}Options:${c.reset}
   --dir <path>    Project directory (default: current directory)
@@ -459,6 +465,26 @@ async function main() {
       // v0.17-P2: `docguard memory --diff` drills into accuracy mismatches.
       // Distinct from the `diff` command itself (which is a top-level cmd).
       flags.diff = true;
+    } else if (args[i] === '--with' && args[i + 1]) {
+      // v0.20: `docguard init --with agents,hooks,ci,badge,llms,publish`
+      // folds the six standalone scaffolders into init. Comma-separated
+      // names, each dispatched to the matching runner after init finishes.
+      flags.with = args[i + 1].split(',').map(s => s.trim()).filter(Boolean);
+      i++;
+    } else if (args[i] === '--wizard') {
+      // v0.20: `docguard init --wizard` runs the 7-step interactive
+      // onboarding flow (previously `docguard setup`). `setup` keeps
+      // working as a deprecation alias.
+      flags.wizard = true;
+    } else if (args[i] === '--skeleton') {
+      // v0.21: `docguard init --skeleton` opts out of smart "scan and propose"
+      // detection and forces the blank-template path. Useful for greenfield
+      // projects and CI flows that want deterministic output.
+      flags.skeleton = true;
+    } else if (args[i] === '--keep') {
+      // v0.21: `docguard demo --keep` doesn't delete the temp fixture after
+      // running (useful for poking around what DocGuard set up).
+      flags.keep = true;
     } else if (!args[i].startsWith('--') && i > 0) {
       // Positional args go into flags.args for commands that take them (e.g.
       // `docguard trace --reverse <path>`). Skip the command itself (i === 0).
@@ -522,17 +548,61 @@ async function main() {
     ensureSkills(projectDir, flags);
   }
 
+  // v0.20: deprecation aliases. The legacy command keeps working through v0.20
+  // and emits a yellow stderr warning suggesting the new shape. Quiet mode
+  // (e.g. inside hooks) suppresses the warning so CI output stays clean.
+  // The full deprecation timeline is in docs-implementation/MIGRATION-v0.20.md.
+  const DEPRECATED_COMMANDS = {
+    setup:   { since: '0.20', replacement: 'docguard init --wizard' },
+    agents:  { since: '0.20', replacement: 'docguard init --with agents' },
+    hooks:   { since: '0.20', replacement: 'docguard init --with hooks' },
+    ci:      { since: '0.20', replacement: 'docguard init --with ci' },
+    badge:   { since: '0.20', replacement: 'docguard init --with badge' },
+    llms:    { since: '0.20', replacement: 'docguard init --with llms' },
+    publish: { since: '0.20', replacement: 'docguard init --with publish' },
+    impact:  { since: '0.20', replacement: 'docguard diff --since <ref>' },
+  };
+
+  // v0.20: dropped aliases — the 10 cute variants the audit identified.
+  // `audit` is intentionally NOT here; it remains a permanent silent alias
+  // for `guard` (per SURFACE-AUDIT §8.1 — older CI scripts depend on it).
+  const DROPPED_ALIASES = {
+    onboard:        'setup (deprecated) — try `docguard init --wizard`',
+    gen:            'generate',
+    badges:         'badge (deprecated) — try `docguard init --with badge`',
+    pipeline:       'ci (deprecated) — try `docguard init --with ci`',
+    repair:         'fix',
+    dx:             'diagnose',
+    pub:            'publish (deprecated) — try `docguard init --with publish`',
+    traceability:   'trace',
+    'help-warning': 'explain',
+    update:         'upgrade',
+  };
+
+  if (DROPPED_ALIASES[command]) {
+    console.error(`${c.red}Unknown command: ${command}${c.reset}`);
+    console.error(`${c.yellow}Hint: this alias was removed in v0.20. Try ${c.cyan}docguard ${DROPPED_ALIASES[command]}${c.yellow}.${c.reset}`);
+    console.error(`${c.dim}See docs-implementation/MIGRATION-v0.20.md for the full list.${c.reset}`);
+    process.exit(1);
+  }
+
+  if (DEPRECATED_COMMANDS[command] && !flags.quiet) {
+    const { since, replacement } = DEPRECATED_COMMANDS[command];
+    console.error(`${c.yellow}⚠ Deprecated since v${since}:${c.reset} ${c.cyan}docguard ${command}${c.reset} → use ${c.cyan}${replacement}${c.reset}`);
+    console.error(`${c.dim}  The old form still works in v0.20.x but will be removed in v1.0. See MIGRATION-v0.20.md.${c.reset}`);
+  }
+
   switch (command) {
     case 'audit':
-      // audit is an alias for guard — guard does everything the old audit did + 50 more checks
+      // Permanent silent alias for guard (SURFACE-AUDIT §8.1).
       runGuard(projectDir, config, flags);
       break;
     case 'init':
       await runInit(projectDir, config, flags);
       break;
     case 'setup':
-    case 'onboard':
-      await runSetup(projectDir, config, flags);
+      // v0.20: deprecated → dispatches to init --wizard
+      await runInit(projectDir, config, { ...flags, wizard: true });
       break;
     case 'guard':
       runGuard(projectDir, config, flags);
@@ -541,32 +611,35 @@ async function main() {
       runScore(projectDir, config, flags);
       break;
     case 'diff':
-      runDiff(projectDir, config, flags);
+      // v0.20: `docguard diff --since <ref>` dispatches to the impact-mode
+      // analyzer (post-commit "which docs reference files changed since X").
+      // Without --since it's the standard current-state drift report.
+      if (flags.since) {
+        runImpact(projectDir, config, flags);
+      } else {
+        runDiff(projectDir, config, flags);
+      }
       break;
     case 'agents':
-      runAgents(projectDir, config, flags);
+      // v0.20: deprecated → dispatches through init --with
+      await runInit(projectDir, config, { ...flags, with: ['agents'], skipPrompts: true });
       break;
     case 'generate':
-    case 'gen':
       runGenerate(projectDir, config, flags);
       break;
     case 'hooks':
-      runHooks(projectDir, config, flags);
+      await runInit(projectDir, config, { ...flags, with: ['hooks'], skipPrompts: true });
       break;
     case 'badge':
-    case 'badges':
-      runBadge(projectDir, config, flags);
+      await runInit(projectDir, config, { ...flags, with: ['badge'], skipPrompts: true });
       break;
     case 'ci':
-    case 'pipeline':
-      runCI(projectDir, config, flags);
+      await runInit(projectDir, config, { ...flags, with: ['ci'], skipPrompts: true });
       break;
     case 'fix':
-    case 'repair':
       runFix(projectDir, config, flags);
       break;
     case 'diagnose':
-    case 'dx':
       runDiagnose(projectDir, config, flags);
       break;
     case 'watch':
@@ -576,30 +649,35 @@ async function main() {
       runSync(projectDir, config, flags);
       break;
     case 'publish':
-    case 'pub':
-      runPublish(projectDir, config, flags);
+      await runInit(projectDir, config, { ...flags, with: ['publish'], skipPrompts: true });
       break;
     case 'trace':
-    case 'traceability':
       runTrace(projectDir, config, flags);
       break;
     case 'llms':
-      runLlms(projectDir, config, flags);
+      await runInit(projectDir, config, { ...flags, with: ['llms'], skipPrompts: true });
       break;
     case 'upgrade':
-    case 'update':
       await runUpgrade(projectDir, config, flags);
       break;
     case 'impact':
-      runImpact(projectDir, config, flags);
+      // v0.20: deprecated alias for `diff --since`. Default --since HEAD~1
+      // matches impact's historical behavior.
+      runImpact(projectDir, config, { ...flags, since: flags.since || 'HEAD~1' });
       break;
     case 'explain':
-    case 'help-warning':
       runExplain(projectDir, config, flags);
       break;
     case 'memory':
       runMemory(projectDir, config, flags);
       break;
+    case 'demo':
+      // v0.21: zero-install "ah-ha" moment — runs guard against a baked-in
+      // fixture (templates/demo-fixture/) and prints curated drift findings
+      // with real-world-impact annotations. No state changes outside the
+      // temp fixture dir, which is cleaned up on exit.
+      runDemo(projectDir, config, flags);
+      break;
     default:
       console.error(`${c.red}Unknown command: ${command}${c.reset}`);
       console.log(`Run ${c.cyan}docguard --help${c.reset} for usage.`);

package/cli/validators/canonical-sync.mjs

@@ -0,0 +1,211 @@
+/**
+ * Canonical-Sync Validator — v0.19-A.
+ *
+ * The missing self-check. Until this validator existed, `guard` could not
+ * see when the docs lied about DocGuard's own surface. README claimed
+ * "ships 19 commands" while 21 files existed in `cli/commands/`; the
+ * architecture diagram drifted across 5 releases (15 → 19 → still wrong)
+ * because no validator was checking. SURFACE-AUDIT.md §7 specifies the
+ * rules; this is the implementation.
+ *
+ * Scope: DocGuard's own repository only. Gated by `package.json` name ===
+ * "docguard-cli". For every other project, this validator returns N/A —
+ * the "ships N commands" pattern is meaningless in a generic project's
+ * docs (their N refers to their own product, not DocGuard's surface).
+ *
+ * What it checks:
+ *   1. README "ships N commands" matches `cli/commands/*.mjs` file count
+ *   2. README "N validators" matches `runGuardInternal()` output length
+ *      (or, if no guardResults passed, falls back to file count + the 2
+ *      inlined validators: Doc Sections in structure.mjs + Spec-Kit)
+ *   3. Validator names enumerated inline in README appear in guard output
+ *
+ * What it explicitly skips:
+ *   - ROADMAP.md (historical phase logs — "Built with 9 validators" is
+ *     legitimately about v0.7, not today)
+ *   - CHANGELOG.md (same — entries describe what shipped, not current state)
+ *   - docs-implementation/ (snapshots of past state)
+ *   - `<!-- docguard:section source=human -->` blocks (prose, not inventory)
+ *
+ * Self-counting: per SURFACE-AUDIT §8.5, this validator counts itself.
+ * After v0.19 ships, README claims "23 validators" (the previous 22 +
+ * canonical-sync). The check passes only if the README matches reality
+ * INCLUDING the new validator.
+ *
+ * Severity: HIGH — a doc lying about the basic surface is a credibility
+ * killer for a documentation-quality tool.
+ *
+ * Zero NPM runtime dependencies — pure Node.js built-ins only.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+/**
+ * Validate that README count claims about DocGuard's surface match code-truth.
+ * Returns N/A for non-DocGuard projects.
+ *
+ * @param {string} projectDir - Project root directory
+ * @param {object} config - DocGuard config (unused but required by validator interface)
+ * @param {Array} [guardResults] - Results array from runGuardInternal (optional but recommended)
+ * @returns {{ errors: string[], warnings: string[], fixes: object[], passed: number, total: number, na?: boolean, naReason?: string }}
+ */
+export function validateCanonicalSync(projectDir, config, guardResults) {
+  const result = { errors: [], warnings: [], fixes: [], passed: 0, total: 0 };
+
+  // ── Gate: only run in DocGuard's own repo ─────────────────────────────
+  const pkgPath = resolve(projectDir, 'package.json');
+  if (!existsSync(pkgPath)) {
+    return { ...result, na: true, naReason: 'no package.json' };
+  }
+
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+  } catch {
+    return { ...result, na: true, naReason: 'unreadable package.json' };
+  }
+
+  if (pkg.name !== 'docguard-cli') {
+    return {
+      ...result,
+      na: true,
+      naReason: 'canonical-sync only runs in the docguard-cli repo (it polices DocGuard\'s own surface)',
+    };
+  }
+
+  // ── Gather code-truth ────────────────────────────────────────────────
+  const cliDir = resolve(projectDir, 'cli');
+  const commandsDir = resolve(cliDir, 'commands');
+  const validatorsDir = resolve(cliDir, 'validators');
+
+  if (!existsSync(commandsDir) || !existsSync(validatorsDir)) {
+    return { ...result, na: true, naReason: 'cli/commands or cli/validators not found' };
+  }
+
+  const commandFiles = readdirSync(commandsDir).filter(f => f.endsWith('.mjs'));
+  const actualCommandFileCount = commandFiles.length;
+
+  // v0.20: the user-facing command count is what shows up in --help's "Daily 5"
+  // and "Tools" sections — NOT the file count, since deprecation aliases dispatch
+  // through the same files. Parse cli/docguard.mjs to find names in those
+  // sections so the README claim and code-truth stay in lockstep across renames.
+  const cliEntry = resolve(cliDir, 'docguard.mjs');
+  let actualUserFacingCount = actualCommandFileCount; // fallback if parse fails
+  if (existsSync(cliEntry)) {
+    try {
+      const cliSrc = readFileSync(cliEntry, 'utf-8');
+      // Match `${c.green}<name>${c.reset}` inside the Daily 5 / Tools blocks.
+      // Anything in init --with / Deprecation aliases sections uses c.dim, so
+      // they're naturally excluded.
+      const helpBlock = cliSrc.match(/The Daily 5[\s\S]*?Deprecation aliases/);
+      if (helpBlock) {
+        const greenNames = [...helpBlock[0].matchAll(/\$\{c\.green\}(\w+)\$\{c\.reset\}/g)]
+          .map(m => m[1]);
+        // Unique names (init shows up only once)
+        actualUserFacingCount = [...new Set(greenNames)].length;
+      }
+    } catch { /* fall through to file-count fallback */ }
+  }
+  const actualCommandCount = actualUserFacingCount;
+
+  // Validator count: always use the file-count truth source. It's run-order
+  // independent (canonical-sync runs BEFORE metrics-consistency at guard time,
+  // so guardResults.length would undercount by 1). File count + 1 for the
+  // single inlined validator (Doc Sections, exported alongside Structure from
+  // structure.mjs).
+  const validatorFiles = readdirSync(validatorsDir).filter(f => f.endsWith('.mjs'));
+  const actualValidatorCount = validatorFiles.length + 1; // +1 for Doc Sections inlined in structure.mjs
+
+  // Names list (currently unused for warnings, but kept for future Check 3
+  // where the README enumerates validator names inline).
+  let actualValidatorNames = [];
+  if (Array.isArray(guardResults) && guardResults.length > 0) {
+    actualValidatorNames = guardResults.map(r => r.name).filter(Boolean);
+  }
+
+  // ── Read README ─────────────────────────────────────────────────────
+  const readmePath = resolve(projectDir, 'README.md');
+  if (!existsSync(readmePath)) {
+    result.warnings.push('canonical-sync: README.md not found — cannot check surface claims');
+    result.total = 1;
+    return result;
+  }
+
+  let readme;
+  try {
+    readme = readFileSync(readmePath, 'utf-8');
+  } catch {
+    result.warnings.push('canonical-sync: README.md unreadable');
+    result.total = 1;
+    return result;
+  }
+
+  // ── Check 1: "ships N commands" ─────────────────────────────────────
+  result.total++;
+  const shipsCommandsRe = /ships\s+\*{0,2}(\d+)\s+commands?\*{0,2}/i;
+  const m1 = readme.match(shipsCommandsRe);
+  if (m1) {
+    const claimed = Number(m1[1]);
+    if (claimed === actualCommandCount) {
+      result.passed++;
+    } else {
+      const detail = actualUserFacingCount !== actualCommandFileCount
+        ? `${actualCommandCount} user-facing commands in --help (${actualCommandFileCount} files including deprecation aliases)`
+        : `${actualCommandCount} command file(s)`;
+      result.warnings.push(
+        `README.md claims "ships ${claimed} commands" but the real count is ${detail}. Update the README.`
+      );
+    }
+  } else {
+    // No claim found — that's OK, just don't check this one
+    result.passed++;
+  }
+
+  // ── Check 2: "N validators" in surface context ──────────────────────
+  // Match phrases like "22 validators", "all 22 validators", "the 22 validators"
+  // but NOT phase-log entries like "Built with 9 validators" (those are
+  // historical, and ROADMAP.md/CHANGELOG.md are skipped at the file level).
+  result.total++;
+  const validatorMatches = [...readme.matchAll(/(?:all|the|with|across|ships?)\s+\*{0,2}(\d+)\s+validators?\*{0,2}/gi)];
+  if (validatorMatches.length > 0) {
+    const wrongClaims = validatorMatches
+      .map(m => Number(m[1]))
+      .filter(n => n !== actualValidatorCount);
+    if (wrongClaims.length === 0) {
+      result.passed++;
+    } else {
+      const uniqueWrong = [...new Set(wrongClaims)];
+      result.warnings.push(
+        `README.md claims ${uniqueWrong.map(n => `"${n} validators"`).join(' / ')} but guard reports ${actualValidatorCount}. Update the README.`
+      );
+    }
+  } else {
+    result.passed++;
+  }
+
+  // ── Check 3: architecture-diagram counts ────────────────────────────
+  // Catches the specific "Commands (N)" and "Validators (N)" patterns in
+  // the mermaid block that drifted across 5 releases.
+  result.total++;
+  const archMatches = [
+    { re: /Commands\s*\((\d+)\)/, label: 'Commands', expected: actualCommandCount },
+    { re: /Validators\s*\((\d+)\)/, label: 'Validators', expected: actualValidatorCount },
+  ];
+  const archWrong = [];
+  for (const { re, label, expected } of archMatches) {
+    const m = readme.match(re);
+    if (m && Number(m[1]) !== expected) {
+      archWrong.push(`${label} (${m[1]}) → should be (${expected})`);
+    }
+  }
+  if (archWrong.length === 0) {
+    result.passed++;
+  } else {
+    result.warnings.push(
+      `README.md architecture diagram has stale counts: ${archWrong.join('; ')}. Update the mermaid block.`
+    );
+  }
+
+  return result;
+}

package/cli/validators/spec-kit.mjs

@@ -0,0 +1,14 @@
+/**
+ * Spec-Kit Validator — Validates Spec Kit artifacts (specs/, plans/, tasks/, constitution).
+ *
+ * v0.19-D: Architectural move. The validation logic still lives in
+ * `scanners/speckit.mjs` (where the spec-kit data is scanned), but the
+ * validator entry-point now lives here in `validators/` so the file count
+ * matches the validator count. This also makes the canonical-sync validator's
+ * truth source (`ls cli/validators/*.mjs`) align with what `guard` reports.
+ *
+ * Re-exports `validateSpecKitIntegration` from the scanner. Importers should
+ * use this path (`validators/spec-kit.mjs`) going forward.
+ */
+
+export { validateSpecKitIntegration } from '../scanners/speckit.mjs';

package/docs/quickstart.md

@@ -68,7 +68,7 @@ diagnose  →  AI reads prompts  →  AI fixes docs  →  guard verifies
 ## Verify
 
 ```bash
-npx docguard-cli guard        # Pass/fail check (22 validators)
+npx docguard-cli guard        # Pass/fail check (23 validators)
 npx docguard-cli score        # 0-100 maturity score
 ```
 

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

@@ -4,7 +4,7 @@ Enterprise-grade Canonical-Driven Development (CDD) enforcement and **AI-readabl
 
 ## Features
 
-- **22 Validators** — Structure, Security, Doc Quality, Test-Spec, Drift-Comments, API-Surface, Freshness, Cross-Reference, and 13 more
+- **23 Validators** — Structure, Security, Doc Quality, Test-Spec, Drift-Comments, API-Surface, Freshness, Cross-Reference, and 13 more
 - **Language-agnostic** — JS/TS, Python, Rust, Go, Java/Kotlin, Ruby, PHP, C#. Polyglot/monorepo-aware.
 - **AI-powered Generate** — `generate --plan` builds the code-truth skeleton in `<!-- docguard:section -->` markers and emits a structured agent task manifest; the AI writes the prose.
 - **Always up to date** — `sync` surgically refreshes code-truth doc sections in place, **preserves human prose**, flags prose for agent review.

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

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.18.1"
+  version: "0.21.0"
   description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with 19 automated validators, 4 AI behavior skills, spec-kit skill chaining, and workflow hooks. Zero NPM runtime dependencies."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"
@@ -28,22 +28,22 @@ provides:
     - name: "speckit.docguard.guard"
       file: "commands/guard.md"
       description: "Run 19-validator quality gate with severity triage and remediation plan"
-      aliases: ["docguard.guard"]
+      aliases: ["speckit.docguard.guard"]
 
     - name: "speckit.docguard.fix"
       file: "commands/generate.md"
       description: "AI-driven documentation repair with codebase research and validation loops"
-      aliases: ["docguard.fix"]
+      aliases: ["speckit.docguard.fix"]
 
     - name: "speckit.docguard.review"
       file: "commands/diagnose.md"
       description: "Cross-document semantic consistency analysis (read-only)"
-      aliases: ["docguard.review"]
+      aliases: ["speckit.docguard.review"]
 
     - name: "speckit.docguard.score"
       file: "commands/score.md"
       description: "CDD maturity score with ROI-based improvement roadmap"
-      aliases: ["docguard.score"]
+      aliases: ["speckit.docguard.score"]
 
     - name: "speckit.docguard.diagnose"
       file: "commands/diagnose.md"

package/extensions/spec-kit-docguard/skills/docguard-fix/SKILL.md

@@ -6,10 +6,10 @@ description: AI-driven documentation repair with structured research workflow, t
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.18.1
+  version: 0.21.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.18.1 -->
+<!-- docguard:version: 0.21.0 -->
 
 # DocGuard Fix Skill
 

package/extensions/spec-kit-docguard/skills/docguard-guard/SKILL.md

@@ -7,10 +7,10 @@ description: Run DocGuard guard validation against Canonical-Driven Development
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.18.1
+  version: 0.21.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.18.1 -->
+<!-- docguard:version: 0.21.0 -->
 
 # DocGuard Guard Skill
 

package/extensions/spec-kit-docguard/skills/docguard-review/SKILL.md

@@ -6,10 +6,10 @@ description: Cross-document consistency analysis and quality assessment. Perform
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.18.1
+  version: 0.21.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.18.1 -->
+<!-- docguard:version: 0.21.0 -->
 
 # DocGuard Review Skill
 

package/extensions/spec-kit-docguard/skills/docguard-score/SKILL.md

@@ -6,10 +6,10 @@ description: CDD maturity assessment with category-aware improvement roadmap. Ru
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.18.1
+  version: 0.21.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.18.1 -->
+<!-- docguard:version: 0.21.0 -->
 
 # DocGuard Score Skill
 

package/extensions/spec-kit-docguard/skills/docguard-sync/SKILL.md

@@ -4,7 +4,7 @@ description: Keep canonical documentation ALWAYS UP TO DATE. Refreshes code-trut
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.18.1
+  version: 0.21.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

package/package.json

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

package/templates/demo-fixture/.docguard.json

@@ -0,0 +1,8 @@
+{
+  "projectName": "acme-payments",
+  "version": "0.5",
+  "profile": "standard",
+  "sourcePatterns": {
+    "routes": "src/**/*.mjs"
+  }
+}

package/templates/demo-fixture/.env.example

@@ -0,0 +1,5 @@
+# Required at boot — see docs-canonical/ENVIRONMENT.md for context.
+DATABASE_URL=postgres://acme:devpass@localhost:5432/payments
+STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxxx
+# Intentional drift: JWT_SECRET is used in code but NOT documented in ENVIRONMENT.md
+JWT_SECRET=change-me-in-prod

package/templates/demo-fixture/AGENTS.md

@@ -0,0 +1,14 @@
+# AGENTS.md — Acme Payments
+
+> Rules for AI agents working in this repo.
+
+## Project context
+Acme Payments is a payments microservice. Money is involved — assume every change needs a test.
+
+## Architecture
+Three services: API, Worker, Scheduler. See `docs-canonical/ARCHITECTURE.md` for the canonical map.
+
+## Style
+- ES modules (`.mjs`)
+- Async/await throughout, no callbacks
+- Throw `PaymentError` for domain errors