docguard-cli 0.18.1 → 0.20.0

package/README.md

@@ -15,6 +15,7 @@
 ## Table of Contents
 
 - [What is DocGuard?](#what-is-docguard)
+- [What's New](#-whats-new)
 - [Quick Start](#-quick-start)
 - [Spec Kit Integration](#-spec-kit-integration)
 - [Usage](#usage)
@@ -50,15 +51,15 @@ DocGuard is an official [GitHub Spec Kit](https://github.com/github/spec-kit) co
 
 ```mermaid
 graph TD
-    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (15)"]
+    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (13)"]
     Commands --> guard["guard"]
     Commands --> generate["generate"]
     Commands --> score["score"]
     Commands --> diagnose["diagnose"]
     Commands --> setup["setup wizard"]
-    Commands --> other["diff · init · fix · trace<br/>agents · hooks · badge · ci · watch"]
+    Commands --> other["diff · init · fix · trace · impact · sync<br/>explain · memory · upgrade · agents · hooks · badge · ci · watch"]
 
-    guard --> Validators["Validators (19)"]
+    guard --> Validators["Validators (23)"]
     generate --> Scanners["Scanners (4)<br/>routes · schemas · doc-tools · speckit"]
     score --> Scoring["Weighted Scoring<br/>8 categories"]
     diagnose --> Validators
@@ -81,6 +82,37 @@ graph TD
 
 ---
 
+## ✨ What's New
+
+Recent highlights across the v0.16 → v0.19 line:
+
+- **`docguard explain <validator>`** — `docguard explain freshness` prints purpose, rules, common
+  failures, and fix recipes for any of the 23 validators. No need to dig into source.
+- **`docguard memory --diff`** — surface what changed in your canonical docs between two refs
+  (`HEAD~10..HEAD` by default). Great for code review and changelog drafting.
+- **`docguard score --diff`** — see exactly which validators moved the score up or down between
+  two commits. Pinpoints regressions without re-running the full suite by hand.
+- **`docguard upgrade --apply --pr`** — when the config schema bumps, DocGuard migrates
+  `.docguard.json` for you and (optionally) opens a PR with the change.
+- **Language-aware patterns** — test discovery and trace mapping now understand Python, Rust, Go,
+  Java, Ruby, and PHP layouts in addition to JS/TS. Sensible defaults, override via config.
+- **Per-validator severity overrides** — escalate `freshness` to `high` for production repos,
+  demote `doc-quality` to `low` for prototypes. Configurable per-project.
+- **JSON Schema for `.docguard.json`** — IDE autocomplete, in-line docs, and validation via
+  `$schema`. Shipped in the package at `schemas/docguard-config.schema.json`.
+- **Version pin (`docguardVersion` + `--pin`)** — pin the CLI version your project supports so
+  CI fails loudly if someone bumps DocGuard without re-running the suite.
+- **Cross-process plan cache** — repeated runs reuse the validator plan across processes when
+  the working tree hasn't changed. ~30% faster guard runs on typical repos.
+- **Headless-aware banner** — `--quiet`, `--format json`, `--write`, and `--changed-only`
+  automatically suppress the banner so JSON output stays parse-clean.
+- **npm-pack smoke gate** — every release now extracts the actual tarball and runs the CLI
+  end-to-end before publish, catching missing-file regressions.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full history.
+
+---
+
 ## ⚡ Quick Start
 
 ### Node.js (npm)
@@ -203,24 +235,49 @@ This installs DocGuard's slash commands (`/docguard.guard`, `/docguard.review`,
 
 ## Usage
 
-DocGuard ships **13 commands**:
+DocGuard ships **13 commands** (the "Daily 5" + 8 situational tools). Six additional one-shot scaffolders are accessed via `docguard init --with <name>`. Eight v0.19 commands continue to work as deprecation aliases through v0.20.x — see [MIGRATION-v0.20.md](docs-implementation/MIGRATION-v0.20.md).
+
+**The Daily 5** — what you'll reach for 95% of the time:
+
+| Command | What It Does |
+|:--------|:-------------|
+| `init`  | Bootstrap a project (`--wizard` for interactive · `--with <name>` for scaffolders) |
+| `guard` | Validate against canonical docs — 23 validators |
+| `diff`  | Show gaps between docs and code (`--since <ref>` for impact mode) |
+| `sync`  | Refresh code-truth doc sections — keeps memory always up to date |
+| `score` | CDD maturity score (0-100; `--diff` for delta between refs) |
+
+**Tools (situational, but day-to-day useful):**
 
 | Command | Purpose |
 |:--------|:--------|
-| `diagnose` | **Primary** — identify every issue + generate AI fix prompts |
-| `guard` | Validate project against canonical docs (CI gate) |
-| `generate` | Reverse-engineer docs from existing codebase |
-| `init` | Initialize CDD docs from templates (interactive) |
-| `score` | CDD maturity score (0–100) with weighted breakdown |
-| `fix --doc <name>` | Generate AI prompt for a specific document |
-| `fix --write` | Apply deterministic fixes (remove stale documented endpoints) — no AI |
-| `diff` | Compare canonical docs vs actual code artifacts |
-| `agents` | Generate agent-specific config files |
-| `trace` | Requirements traceability matrix |
-| `ci` | CI/CD pipeline check with threshold |
-| `watch` | Live watch mode with auto-fix |
-| `hooks` | Install git hooks (pre-commit, pre-push) |
-| `llms` | Generate `llms.txt` (AI-friendly project summary) |
+| `diagnose` | AI orchestrator — guard → emit fix prompts in one command |
+| `fix` | Generate AI fix instructions for specific docs (`--doc <name> --format prompt`) |
+| `fix --write` | Apply deterministic fixes (no AI — version bumps, counts, anchors, sections) |
+| `fix --history` | Audit log of every mechanical fix applied (from `.docguard/fixed.json`) |
+| `generate` | Reverse-engineer docs from existing codebase (`--plan` for AI scan) |
+| `explain <warning>` | Paste any warning — get the validator's docstring + fix path |
+| `memory` | Per-domain accuracy headline (endpoints / entities / env / tech) |
+| `memory --diff` | Drill into which specific claims don't match code |
+| `score --diff` | Drill into which checks pulled each category down |
+| `trace` / `trace --reverse <file>` | Requirements traceability — forward AND reverse |
+| `upgrade [--apply] [--pr]` | Check + migrate `.docguard.json` schema; `--pr` opens a PR |
+| `watch` | Live mode: re-run guard on file changes |
+
+**`init --with <name>` scaffolders** — picked at init time:
+
+| Scaffolder | What It Generates |
+|:-----------|:------------------|
+| `agents` | `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, `.github/copilot-instructions.md` |
+| `hooks` | Git pre-commit / pre-push hooks |
+| `ci` | GitHub Actions / pipeline YAML |
+| `badge` | Shields.io score badges for README |
+| `llms` | `llms.txt` (AI-friendly summary) |
+| `publish` | External doc-site config (Mintlify) — experimental |
+
+Run them solo (`docguard init --with hooks`) or stacked (`docguard init --with agents,hooks,badge,ci`).
+
+**Deprecation aliases** — `setup` · `agents` · `hooks` · `ci` · `badge` · `llms` · `publish` · `impact` keep working in v0.20.x with a yellow stderr warning. `audit → guard` is permanent (no warning). See [MIGRATION-v0.20.md](docs-implementation/MIGRATION-v0.20.md).
 
 ### CLI Flags
 
@@ -228,10 +285,22 @@ DocGuard ships **13 commands**:
 |:-----|:------------|:---------|
 | `--dir <path>` | Project directory (default: `.`) | All |
 | `--verbose` | Show detailed output | All |
-| `--format json` | Machine-readable output for CI/CD | score, guard, diff |
+| `--quiet` / `-q` | Suppress banner — for hooks, CI loops, scripts | All |
+| `--format json` | Machine-readable output (clean JSON, no ANSI bleed) | guard, score, diff, trace, diagnose, memory, impact, explain |
 | `--force` | Overwrite existing files (creates `.bak` backups) | generate, agents, init |
-| `--profile <name>` | Starter, standard, or enterprise | init |
-| `--agent <name>` | Target specific AI agent | agents |
+| `--force-redo` | Bypass ping-pong suppression in `.docguard/fixed.json` | fix --write |
+| `--profile <name>` | Starter / standard / enterprise | init |
+| `--no-spec-kit` | Skip auto-init of `.specify/` / `.agent/` scaffolding | init |
+| `--changed-only [--since <ref>]` | Pre-commit lite mode (5 fast validators on changed files only) | guard |
+| `--timings` | Per-validator wall-time profile (slowest first) | guard |
+| `--show-failing` | Show warnings/errors even when status is PASS | guard |
+| `--pin` | Record running CLI version into `.docguard.json` (reproducibility) | guard |
+| `--diff` | Per-category drill-down | score, memory |
+| `--check-only` | Exit 1 if behind (for CI) | upgrade |
+| `--apply` | Actually run the migration | upgrade |
+| `--pr` | Open a PR with the migration | upgrade |
+| `--reverse <file>` | Reverse traceability (code → docs) | trace |
+| `--history` | Show fix audit log | fix |
 
 ### Example Output
 
@@ -266,30 +335,47 @@ $ npx docguard-cli generate
 
 ## 🔍 Validators
 
-DocGuard runs **19 automated validators** on every `guard` check:
+DocGuard runs **23 automated validators** on every `guard` check. Every one is **language-aware** as of v0.16 — patterns for Python (`test_*.py`), Rust (`tests/*.rs`), Go (`*_test.go`), Java (`*Test.java`), Ruby (`*_spec.rb`), PHP, and JS/TS all match.
 
 | # | Validator | What It Checks | Default |
 |:--|:----------|:--------------|:--------|
 | 1 | **Structure** | Required CDD files exist | ✅ On |
-| 2 | **Doc Sections** | Canonical docs have required sections | ✅ On |
+| 2 | **Doc Sections** | Canonical docs have required sections (or N/A markers) | ✅ On |
 | 3 | **Docs-Sync** | Routes/services referenced in docs + OpenAPI cross-check | ✅ On |
-| 4 | **Drift-Comments** | `// DRIFT:` comments logged in DRIFT-LOG.md | ✅ On |
+| 4 | **Drift-Comments** | `// DRIFT:` comments logged in DRIFT-LOG.md (skips test files by default) | ✅ On |
 | 5 | **Changelog** | CHANGELOG.md has [Unreleased] section | ✅ On |
 | 6 | **Test-Spec** | Tests exist per TEST-SPEC.md rules | ✅ On |
-| 7 | **Environment** | Env vars documented, .env.example exists | ✅ On |
+| 7 | **Environment** | Env vars documented, `.env.example` exists | ✅ On |
 | 8 | **Security** | No hardcoded secrets in source code | ✅ On |
-| 9 | **Architecture** | Imports follow layer boundaries | ✅ On |
-| 10 | **Freshness** | Docs not stale relative to code changes | ✅ On |
+| 9 | **Architecture** | Imports follow layer boundaries (honors `config.ignore`) | ✅ On |
+| 10 | **Freshness** | Docs not stale relative to code changes (rename-aware via `git log --follow`) | ✅ On |
 | 11 | **Traceability** | Requirement IDs (FR, SC, NFR, US, AC, T) trace to tests | ✅ On |
 | 12 | **Docs-Diff** | Code artifacts match documented entities | ✅ On |
-| 13 | **Metadata-Sync** | Version refs consistent across docs | ✅ On |
-| 14 | **Docs-Coverage** | Code features referenced in documentation | ✅ On |
-| 15 | **Metrics-Consistency** | Hardcoded numbers match actual counts | ✅ On |
-| 16 | **Doc-Quality** | Writing quality (readability, passive voice, atomicity) | ✅ On |
-| 17 | **TODO-Tracking** | Untracked TODOs/FIXMEs and skipped tests | ✅ On |
+| 13 | **API-Surface** | API-REFERENCE.md endpoints match real routes (OpenAPI cross-check) | ✅ On |
+| 14 | **Metadata-Sync** | Version refs consistent across docs | ✅ On |
+| 15 | **Docs-Coverage** | Code features referenced in documentation | ✅ On |
+| 16 | **Doc-Quality** | Writing quality (readability, passive voice, atomicity, IEEE 830) | ✅ On |
+| 17 | **TODO-Tracking** | Untracked TODOs/FIXMEs and skipped tests (skips test files by default) | ✅ On |
 | 18 | **Schema-Sync** | Database models documented in DATA-MODEL.md | ✅ On |
 | 19 | **Spec-Kit** | Spec quality validation (FR-IDs, mandatory sections, phased tasks) | ✅ On |
-| 20 | **API-Surface** | API-REFERENCE.md endpoints match the real API surface (OpenAPI spec / routes); flags documented-but-deleted endpoints | ✅ On |
+| 20 | **Cross-Reference** | Internal markdown links + anchors resolve (with "did you mean?" hints) | ✅ On |
+| 21 | **Generated-Staleness** | `source=code` sections match scanner output; `status: draft` doc age | ✅ On |
+| 22 | **Canonical-Sync** | DocGuard's own README count claims match code-truth (DocGuard repo only — N/A elsewhere) | ✅ On |
+| 23 | **Metrics-Consistency** | Hardcoded numbers match actual counts | ✅ On |
+
+**Per-validator controls** (in `.docguard.json`):
+```json
+{
+  "validators": {
+    "test-spec": false,                 // disable (kebab-case OR camelCase both accepted)
+    "freshness": true
+  },
+  "severity": {
+    "todoTracking": "high",             // warnings fail CI
+    "freshness": "low"                  // warnings ignored for exit code
+  }
+}
+```
 
 ---
 
@@ -343,7 +429,7 @@ DocGuard provides AI agent slash commands for integrated workflows. Installed au
 
 | Command | What It Does |
 |:--------|:-------------|
-| `/docguard.guard` | Run quality validation — check all 22 validators |
+| `/docguard.guard` | Run quality validation — check all 23 validators |
 | `/docguard.review` | Analyze doc quality and suggest improvements |
 | `/docguard.fix` | Generate targeted fix prompts for specific issues |
 | `/docguard.score` | Show CDD maturity score with category breakdown |

package/cli/commands/guard.mjs

@@ -139,7 +139,8 @@ import { validateCrossReferences } from '../validators/cross-reference.mjs';
 import { validateGeneratedStaleness } from '../validators/generated-staleness.mjs';
 import { validateTodoTracking } from '../validators/todo-tracking.mjs';
 import { validateSchemaSync } from '../validators/schema-sync.mjs';
-import { validateSpecKitIntegration } from '../scanners/speckit.mjs';
+import { validateSpecKitIntegration } from '../validators/spec-kit.mjs';
+import { validateCanonicalSync } from '../validators/canonical-sync.mjs';
 
 /**
  * Internal guard — returns structured data, no console output, no process.exit.
@@ -237,6 +238,22 @@ export function runGuardInternal(projectDir, config) {
     }
   }
 
+  // ── Canonical-Sync runs AFTER main loop, BEFORE metrics-consistency.
+  //    Needs the live validator results to count "real" validators that ran.
+  //    (Pre-canonical-sync ordering — comes before metrics-consistency so the
+  //    metrics validator sees a stable surface count.)
+  if (validators.canonicalSync !== false) {
+    const start = performance.now();
+    try {
+      const result = validateCanonicalSync(projectDir, config, results);
+      const durationMs = Math.round((performance.now() - start) * 100) / 100;
+      results.push({ ...result, name: 'Canonical-Sync', key: 'canonicalSync', durationMs, ...classifyResult(result) });
+    } catch (err) {
+      const durationMs = Math.round((performance.now() - start) * 100) / 100;
+      results.push({ name: 'Canonical-Sync', key: 'canonicalSync', status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1, durationMs });
+    }
+  }
+
   // ── Metrics-Consistency runs AFTER all other validators (needs their results) ──
   if (validators.metricsConsistency !== false) {
     const start = performance.now();
@@ -317,7 +334,8 @@ function liteValidatorsConfig() {
     'structure', 'docsSync', 'drift', 'changelog', 'testSpec', 'environment',
     'security', 'architecture', 'freshness', 'traceability', 'docsDiff',
     'apiSurface', 'metadataSync', 'docsCoverage', 'docQuality', 'todoTracking',
-    'schemaSync', 'specKit', 'crossReference', 'generatedStaleness', 'metricsConsistency',
+    'schemaSync', 'specKit', 'crossReference', 'generatedStaleness',
+    'canonicalSync', 'metricsConsistency',
   ];
   const out = {};
   for (const k of all) out[k] = CHANGED_ONLY_VALIDATORS.includes(k);

package/cli/commands/init.mjs

@@ -17,6 +17,45 @@ import { execSync } from 'node:child_process';
 import { c, PROFILES } from '../shared.mjs';
 import { ensureSkills, detectAgentMode, detectAIAgent, isSpecKitAvailable, isSpecKitInitialized, getDetectedAgent } from '../ensure-skills.mjs';
 
+// v0.20: scaffolder names that can be passed via `init --with <name>` and
+// dispatched to the corresponding standalone runner. Each name maps to its
+// canonical command module. Keep in sync with cli/docguard.mjs router.
+const SCAFFOLDER_DISPATCH = {
+  agents:  async (dir, cfg, flags) => (await import('./agents.mjs')).runAgents(dir, cfg, flags),
+  hooks:   async (dir, cfg, flags) => (await import('./hooks.mjs')).runHooks(dir, cfg, flags),
+  ci:      async (dir, cfg, flags) => (await import('./ci.mjs')).runCI(dir, cfg, flags),
+  badge:   async (dir, cfg, flags) => (await import('./badge.mjs')).runBadge(dir, cfg, flags),
+  llms:    async (dir, cfg, flags) => (await import('./llms.mjs')).runLlms(dir, cfg, flags),
+  publish: async (dir, cfg, flags) => (await import('./publish.mjs')).runPublish(dir, cfg, flags),
+};
+
+/**
+ * Run one or more scaffolders after init has completed.
+ * Called when `docguard init --with agents,hooks,ci` is invoked.
+ * Each scaffolder runs in sequence; if one throws, the rest are skipped
+ * (matches the standalone command's failure semantics).
+ */
+async function runScaffolders(projectDir, config, flags, names) {
+  const unknown = names.filter(n => !SCAFFOLDER_DISPATCH[n]);
+  if (unknown.length > 0) {
+    console.error(`${c.red}Unknown --with target(s): ${unknown.join(', ')}${c.reset}`);
+    console.log(`${c.dim}Valid: ${Object.keys(SCAFFOLDER_DISPATCH).join(', ')}${c.reset}`);
+    process.exit(1);
+  }
+
+  console.log(`\n${c.bold}🧰 Scaffolders:${c.reset} ${c.cyan}${names.join(', ')}${c.reset}\n`);
+
+  for (const name of names) {
+    console.log(`${c.dim}── ${name} ───────────────────────────────────────${c.reset}`);
+    try {
+      await SCAFFOLDER_DISPATCH[name](projectDir, config, flags);
+    } catch (err) {
+      console.error(`${c.red}✗ ${name} failed: ${err.message}${c.reset}`);
+      process.exit(1);
+    }
+  }
+}
+
 function detectProjectType(dir) {
   const pkgPath = resolve(dir, 'package.json');
   if (existsSync(pkgPath)) {
@@ -54,6 +93,14 @@ function askQuestion(prompt) {
 // ── Init Command ─────────────────────────────────────────────────────────
 
 export async function runInit(projectDir, config, flags) {
+  // v0.20: `--wizard` dispatches to the full interactive onboarding (formerly
+  // `docguard setup`). Done before profile validation so the wizard can ask
+  // for the profile itself if needed.
+  if (flags.wizard) {
+    const { runSetup } = await import('./setup.mjs');
+    return runSetup(projectDir, config, flags);
+  }
+
   const profileName = flags.profile || 'standard';
   const profile = PROFILES[profileName];
 
@@ -369,4 +416,11 @@ poetry.lock
 
   // Auto-install DocGuard skills and commands (spec-kit skills handled by specify init)
   ensureSkills(projectDir, flags);
+
+  // v0.20: `docguard init --with agents,hooks,ci,badge,llms,publish` runs
+  // the named scaffolders after init has finished. Each one runs in sequence
+  // and uses the same flags object (so --force / --skip-prompts propagate).
+  if (Array.isArray(flags.with) && flags.with.length > 0) {
+    await runScaffolders(projectDir, config, flags, flags.with);
+  }
 }

package/cli/docguard.mjs

@@ -282,36 +282,37 @@ 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}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}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}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 (use ${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}Tools (situational, but day-to-day useful)${c.reset}
+  ${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 +460,17 @@ 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].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 +534,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 +597,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,25 +635,23 @@ 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':

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.20.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.20.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.18.1 -->
+<!-- docguard:version: 0.20.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.20.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.18.1 -->
+<!-- docguard:version: 0.20.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.20.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.18.1 -->
+<!-- docguard:version: 0.20.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.20.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.18.1 -->
+<!-- docguard:version: 0.20.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.20.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.20.0",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {