docguard-cli 0.11.1 → 0.12.0

package/README.md

@@ -343,7 +343,7 @@ DocGuard provides AI agent slash commands for integrated workflows. Installed au
 
 | Command | What It Does |
 |:--------|:-------------|
-| `/docguard.guard` | Run quality validation — check all 20 validators |
+| `/docguard.guard` | Run quality validation — check all 21 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 |
@@ -433,20 +433,42 @@ DocGuard runs its own `guard`, `score`, `diff`, `diagnose`, and `badge` commands
 
 ## ⚙️ CI/CD Integration
 
-### GitHub Actions
+> **Full recipes:** see [`docs-canonical/CI-RECIPES.md`](./docs-canonical/CI-RECIPES.md) for guard, auto-fix (commits mechanical fixes back to PRs), nightly sync, score-on-PR, and pre-commit configs.
+
+### GitHub Actions — Guard (most common)
 
 ```yaml
-name: DocGuard CDD Check
-on: [pull_request]
+name: DocGuard Guard
+on: [pull_request, push]
 jobs:
   docguard:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: '20' }
-      - run: npx docguard-cli guard
-      - run: npx docguard-cli score --format json
+        with: { fetch-depth: 0 }
+      - uses: raccioly/docguard@v0.12.0
+        with:
+          command: guard
+```
+
+### GitHub Actions — Auto-Fix (commits mechanical fixes back)
+
+```yaml
+name: DocGuard Auto-Fix
+on: { pull_request: { types: [opened, synchronize, reopened] } }
+permissions: { contents: write, pull-requests: write }
+jobs:
+  autofix:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.ref }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fetch-depth: 0
+      - uses: raccioly/docguard@v0.12.0
+        with: { command: fix, auto-commit: 'true', comment-on-pr: 'true' }
 ```
 
 ### Pre-commit Hook
@@ -455,14 +477,11 @@ jobs:
 npx docguard-cli hooks --type pre-commit
 ```
 
-### GitHub Marketplace
+### Workflow starters (copy directly)
 
-```yaml
-- uses: raccioly/docguard@v0.9.7
-  with:
-    command: guard
-    fail-on-warning: true
-```
+Two ready-to-use templates ship with the Spec Kit extension and as standalone files:
+- `extensions/spec-kit-docguard/templates/github-workflows/docguard-guard.yml` — mandatory CI gate
+- `extensions/spec-kit-docguard/templates/github-workflows/docguard-autofix.yml` — PR auto-fix
 
 ---
 

package/cli/commands/diff.mjs

@@ -10,6 +10,8 @@ import { collectPackageJsons, detectDocker, grepEnvUsage, resolveSourceRoots } f
 import { parseApiReferenceDoc, compareEndpoints } from '../scanners/api-doc.mjs';
 import { resolveApiSurface } from '../validators/api-surface.mjs';
 import { collectCodeTests } from '../validators/docs-diff.mjs';
+import { scanSchemasDeep } from '../scanners/schemas.mjs';
+import { detectDocTools } from '../scanners/doc-tools.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build',
@@ -163,22 +165,17 @@ function diffEntities(dir, config = {}) {
     docEntities.add(name.toLowerCase());
   }
 
-  // Find model/entity files in code — monorepo-aware (honors config.sourceRoot/workspaces).
+  // Use the REAL exported entity names from scanSchemasDeep, not file basenames
+  // (a file `dynamoModels.ts` exports `User`/`Order`/etc. — its basename is not
+  // an entity). scanSchemasDeep covers JS ORMs, SQLAlchemy/Pydantic, Diesel,
+  // Go structs, JPA, Rails, and OpenAPI schemas.
+  const docTools = detectDocTools(dir);
+  const schemas = scanSchemasDeep(dir, {}, docTools);
   const codeEntities = new Set();
-  const modelSubdirs = ['models', 'entities', 'schema', 'schemas', 'prisma'];
-  const roots = resolveSourceRoots(dir, config);
-  for (const root of roots) {
-    for (const sub of modelSubdirs) {
-      const modelDir = join(root, sub);
-      if (!existsSync(modelDir)) continue;
-      const files = getFilesRecursive(modelDir);
-      for (const f of files) {
-        const name = basename(f, extname(f)).toLowerCase();
-        // Skip non-entity infrastructure/aggregation filenames.
-        if (CODE_ENTITY_NOISE.has(name)) continue;
-        codeEntities.add(name);
-      }
-    }
+  for (const e of (schemas.entities || [])) {
+    const n = String(e.name || '').toLowerCase();
+    if (!n || CODE_ENTITY_NOISE.has(n)) continue;
+    codeEntities.add(n);
   }
 
   // No code-side entity source (e.g. DynamoDB single-table design with no model
@@ -207,7 +204,8 @@ function diffEnvVars(dir, config = {}) {
 
   // Extract env var names from ENVIRONMENT.md
   const docVars = new Set();
-  const varRegex = /`([A-Z][A-Z0-9_]{2,})`/g;
+  // Reject names ending in `_` (e.g. the literal prefix `VITE_` in prose).
+  const varRegex = /`([A-Z][A-Z0-9_]*[A-Z0-9])`/g;
   let match;
   while ((match = varRegex.exec(content)) !== null) {
     docVars.add(match[1]);
@@ -220,7 +218,7 @@ function diffEnvVars(dir, config = {}) {
     const envExamplePath = resolve(dir, envFile);
     if (existsSync(envExamplePath)) {
       const envContent = readFileSync(envExamplePath, 'utf-8');
-      const envRegex = /^([A-Z][A-Z0-9_]+)\s*=/gm;
+      const envRegex = /^([A-Z][A-Z0-9_]*[A-Z0-9])\s*=/gm;
       while ((match = envRegex.exec(envContent)) !== null) {
         codeVars.add(match[1]);
       }

package/cli/commands/guard.mjs

@@ -7,8 +7,9 @@
  *   runGuardInternal() → returns data, no side effects (for diagnose, ci)
  */
 
-import { c } from '../shared.mjs';
+import { c, resolveSeverity } from '../shared.mjs';
 import { detectAgentMode, isSpecKitInitialized } from '../ensure-skills.mjs';
+import { checkUpgradeStatus } from './upgrade.mjs';
 import { validateStructure, validateDocSections } from '../validators/structure.mjs';
 import { validateDrift } from '../validators/drift.mjs';
 import { validateChangelog } from '../validators/changelog.mjs';
@@ -25,6 +26,7 @@ import { validateMetadataSync } from '../validators/metadata-sync.mjs';
 import { validateMetricsConsistency } from '../validators/metrics-consistency.mjs';
 import { validateDocsCoverage } from '../validators/docs-coverage.mjs';
 import { validateDocQuality } from '../validators/doc-quality.mjs';
+import { validateCrossReferences } from '../validators/cross-reference.mjs';
 import { validateTodoTracking } from '../validators/todo-tracking.mjs';
 import { validateSchemaSync } from '../validators/schema-sync.mjs';
 import { validateSpecKitIntegration } from '../scanners/speckit.mjs';
@@ -100,6 +102,7 @@ export function runGuardInternal(projectDir, config) {
     { key: 'todoTracking', name: 'TODO-Tracking', fn: () => validateTodoTracking(projectDir, config) },
     { key: 'schemaSync', name: 'Schema-Sync', fn: () => validateSchemaSync(projectDir, config) },
     { key: 'specKit', name: 'Spec-Kit', fn: () => validateSpecKitIntegration(projectDir, config) },
+    { key: 'crossReference', name: 'Cross-Reference', fn: () => validateCrossReferences(projectDir, config) },
     // Metrics-Consistency runs post-loop (needs guard results)
   ];
 
@@ -133,6 +136,25 @@ export function runGuardInternal(projectDir, config) {
   const totalPassed = activeResults.reduce((sum, r) => sum + r.passed, 0);
   const totalChecks = activeResults.reduce((sum, r) => sum + r.total, 0);
 
+  // Per-validator severity overrides (v0.5 schema). Affects EXIT-CODE only,
+  // not display. Annotate each validator with its resolved severity and roll
+  // up effective error/warning counts:
+  //   - high  → validator's warnings get promoted to "effective errors"
+  //   - low   → validator's warnings are demoted (ignored for exit code)
+  //   - medium (default) → warnings stay as-is
+  for (const v of activeResults) {
+    v.severity = resolveSeverity(config, v.key);
+  }
+  let effectiveErrors = totalErrors;
+  let effectiveWarnings = 0;
+  for (const v of activeResults) {
+    const wCount = v.warnings.length;
+    if (wCount === 0) continue;
+    if (v.severity === 'high') effectiveErrors += wCount;
+    else if (v.severity === 'low') { /* ignored for exit */ }
+    else effectiveWarnings += wCount;
+  }
+
   const overallStatus = totalErrors > 0 ? 'FAIL' : totalWarnings > 0 ? 'WARN' : 'PASS';
 
   return {
@@ -143,22 +165,66 @@ export function runGuardInternal(projectDir, config) {
     total: totalChecks,
     errors: totalErrors,
     warnings: totalWarnings,
+    // v0.5: severity-aware counts for exit-code logic. The display still uses
+    // the raw counts above so users see every warning, but CI only fails on
+    // things they've marked as high-severity.
+    effectiveErrors,
+    effectiveWarnings,
     validators: results,
     timestamp: new Date().toISOString(),
   };
 }
 
+/**
+ * The "pre-commit lite" validator set — fast checks suitable for running
+ * on every commit/save. Tuned for <2s wall-clock on average repos.
+ *
+ * The list is intentionally short: validators that catch >80% of the
+ * common doc drift that developers introduce mid-feature (route added but
+ * not documented, env var renamed but not updated in ENVIRONMENT.md,
+ * endpoint deleted but still in API-REFERENCE.md). Heavy validators —
+ * Freshness (git log), Traceability (REQ scan), Doc-Quality (prose lint) —
+ * stay off for speed.
+ */
+export const CHANGED_ONLY_VALIDATORS = ['docsSync', 'environment', 'apiSurface'];
+
+/**
+ * Build a validators map that enables only the pre-commit-lite set.
+ * Used by `docguard guard --changed-only`.
+ */
+function liteValidatorsConfig() {
+  const all = [
+    'structure', 'docsSync', 'drift', 'changelog', 'testSpec', 'environment',
+    'security', 'architecture', 'freshness', 'traceability', 'docsDiff',
+    'apiSurface', 'metadataSync', 'docsCoverage', 'docQuality', 'todoTracking',
+    'schemaSync', 'specKit', 'crossReference', 'metricsConsistency',
+  ];
+  const out = {};
+  for (const k of all) out[k] = CHANGED_ONLY_VALIDATORS.includes(k);
+  return out;
+}
+
 /**
  * Public guard — prints results and exits.
  */
 export function runGuard(projectDir, config, flags) {
+  // --changed-only: pre-commit lite mode. Overrides the validator set to a
+  // fast subset (Docs-Sync, Environment, API-Surface). Designed for husky/
+  // lefthook hooks; expects to finish in under 2 seconds.
+  if (flags.changedOnly) {
+    config = { ...config, validators: liteValidatorsConfig() };
+    console.log(`${c.cyan}⚡ docguard guard --changed-only${c.reset} ${c.dim}(running ${CHANGED_ONLY_VALIDATORS.length} fast validators only — pre-commit lite mode)${c.reset}\n`);
+  }
+
   const data = runGuardInternal(projectDir, config);
 
   // ── JSON output ──
   if (flags.format === 'json') {
     console.log(JSON.stringify(data, null, 2));
-    if (data.errors > 0) process.exit(1);
-    if (data.warnings > 0) process.exit(2);
+    // Use severity-aware effective counts for exit code; raw counts stay in the JSON
+    // for display tools that want to show the full picture.
+    if (data.effectiveErrors > 0) process.exit(1);
+    if (data.effectiveWarnings > 0) process.exit(2);
     process.exit(0);
   }
 
@@ -194,16 +260,26 @@ export function runGuard(projectDir, config, flags) {
       console.log(`  ${c.yellow}⚠️  ${v.name}${c.reset} ${qBadge}${c.dim}  ${v.passed}/${v.total} checks passed${c.reset}`);
     }
 
-    if (flags.verbose || v.status === 'fail') {
+    // --show-failing forces enumeration of every error/warning regardless of
+    // overall validator status — useful when a validator passes overall
+    // (passed < total) without surfacing the specific failing checks.
+    const show = flags.verbose || flags.showFailing;
+    if (show || v.status === 'fail') {
       for (const err of v.errors) {
         console.log(`     ${c.red}✗ ${err}${c.reset}`);
       }
     }
-    if (flags.verbose || v.status === 'warn') {
+    if (show || v.status === 'warn') {
       for (const warn of v.warnings) {
         console.log(`     ${c.yellow}⚠ ${warn}${c.reset}`);
       }
     }
+    // If a validator reports passed < total but has no errors/warnings, surface
+    // the gap honestly so users aren't left wondering where the deficit went.
+    if (v.status === 'pass' && v.total > v.passed && v.errors.length === 0 && v.warnings.length === 0) {
+      const gap = v.total - v.passed;
+      console.log(`     ${c.yellow}⚠ ${gap} check(s) did not pass but emitted no message — likely a validator bug. Please file an issue.${c.reset}`);
+    }
   }
 
   // Summary
@@ -233,14 +309,55 @@ export function runGuard(projectDir, config, flags) {
   const badgeUrl = `https://img.shields.io/badge/CDD_Guard-${data.passed}%2F${data.total}_passed-${bColor}`;
   console.log(`\n  ${c.dim}📎 Badge: ![CDD Guard](${badgeUrl})${c.reset}`);
 
+  // Schema upgrade nudge — fires when the project's .docguard.json schema is
+  // behind the CLI's CURRENT_SCHEMA_VERSION. Cheap, file-local check; no
+  // network access. Suppressed in JSON output to keep machine consumers clean.
+  if (!flags || flags.format !== 'json') {
+    const upgradeHint = checkUpgradeStatus(projectDir);
+    if (upgradeHint) {
+      console.log(`\n  ${c.yellow}↑ ${upgradeHint}${c.reset}`);
+    }
+
+    // K-6 / S-2: sweep-needed nudge. Aggregates freshness warnings — if 2+
+    // canonical docs are stale (matching the "X code commits since last doc
+    // update" pattern), suggest a single `docguard sync --write` pass that
+    // refreshes every code-truth section in one shot. Individual freshness
+    // warnings already named the docs; this nudge just turns "5 warnings"
+    // into one actionable recommendation.
+    const freshness = data.validators.find(v => v.key === 'freshness');
+    if (freshness && freshness.warnings) {
+      const staleDocs = freshness.warnings.filter(w => /\d+ code commits since/.test(w));
+      if (staleDocs.length >= 2) {
+        console.log(`\n  ${c.yellow}↻ ${staleDocs.length} docs are stale (10+ commits since last update). Run ${c.cyan}docguard sync --write${c.yellow} to refresh code-truth sections in one pass.${c.reset}`);
+      }
+    }
+  }
+
   // Spec-kit reminder — persistent nudge if not initialized
   if (!isSpecKitInitialized(projectDir)) {
     console.log(`\n  ${c.yellow}💡${c.reset} ${c.dim}Enhance DocGuard with Spec Kit: ${c.cyan}uv tool install specify-cli --from git+https://github.com/github/spec-kit.git${c.reset}`);
   }
 
+  // When severity overrides demoted warnings to "low" (or promoted them to
+  // "high"), show a one-line note so the user knows the exit code may not
+  // match what they expected from reading the warning count.
+  const severityShifted =
+    data.effectiveErrors !== data.errors || data.effectiveWarnings !== data.warnings;
+  if (severityShifted) {
+    const upgraded = data.effectiveErrors - data.errors;
+    const ignored = data.warnings - data.effectiveWarnings - upgraded;
+    const parts = [];
+    if (upgraded > 0) parts.push(`${upgraded} warning(s) escalated to fail (severity=high)`);
+    if (ignored > 0) parts.push(`${ignored} warning(s) ignored for exit code (severity=low)`);
+    if (parts.length > 0) {
+      console.log(`\n  ${c.dim}Severity override: ${parts.join('; ')}.${c.reset}`);
+    }
+  }
+
   console.log('');
 
-  if (data.errors > 0) process.exit(1);
-  if (data.warnings > 0) process.exit(2);
+  // v0.5: severity-aware exit codes (see runGuardInternal for the rollup).
+  if (data.effectiveErrors > 0) process.exit(1);
+  if (data.effectiveWarnings > 0) process.exit(2);
   process.exit(0);
 }

package/cli/commands/init.mjs

@@ -168,7 +168,7 @@ export async function runInit(projectDir, config, flags) {
 
     const defaultConfig = {
       projectName: config.projectName,
-      version: '0.4',
+      version: '0.5',
       profile: profileName,
       projectType: detectedType,
       projectTypeConfig: ptc,
@@ -186,6 +186,13 @@ export async function runInit(projectDir, config, flags) {
         environment: true,
         freshness: true,
       },
+      // Per-validator severity overrides (v0.5+).
+      //   'high':   warnings from this validator fail CI (exit 1)
+      //   'medium': default — warnings exit 2 (informational)
+      //   'low':    warnings ignored for exit code (exit 0)
+      // Empty by default — every validator uses 'medium'. Add entries to dial
+      // strictness up (CI-critical checks) or down (experimental validators).
+      severity: {},
     };
 
     writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2) + '\n', 'utf-8');
@@ -196,6 +203,50 @@ export async function runInit(projectDir, config, flags) {
     console.log(`  ${c.yellow}⏭️${c.reset}  .docguard.json ${c.dim}(already exists)${c.reset}`);
   }
 
+  // ── Create .docguardignore ────────────────────────────────────────────
+  // Starter ignore file with gitignore-style syntax. Patterns here are merged
+  // into config.ignore at load time so every validator honors them.
+  const ignorePath = resolve(projectDir, '.docguardignore');
+  if (!existsSync(ignorePath)) {
+    const ignoreContent = `# .docguardignore — paths to exclude from DocGuard validation.
+# Gitignore-style syntax: one pattern per line, # for comments.
+# Merged into config.ignore (in .docguard.json) at runtime.
+#
+# Common examples:
+#   build/                   # exclude a directory
+#   **/__generated__/**      # exclude anything in any __generated__ dir
+#   vendor/legacy.ts         # exclude a single file
+#   **/*.snap                # exclude all files matching a glob
+#
+# Build outputs, vendored libs, generated code are good candidates here.
+
+# Vendored / generated code that's not yours to document
+**/__generated__/**
+**/generated/**
+**/*.generated.*
+
+# Migrations and lock files
+**/migrations/**
+**/*.lock
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+Cargo.lock
+poetry.lock
+
+# Common build artifacts (defaults also cover these, but listing here is clearer)
+# dist/
+# build/
+# coverage/
+`;
+    writeFileSync(ignorePath, ignoreContent, 'utf-8');
+    created.push('.docguardignore');
+    console.log(`  ${c.green}✅${c.reset} Created: ${c.cyan}.docguardignore${c.reset} ${c.dim}(gitignore-style exclusions)${c.reset}`);
+  } else {
+    skipped.push('.docguardignore');
+    console.log(`  ${c.yellow}⏭️${c.reset}  .docguardignore ${c.dim}(already exists)${c.reset}`);
+  }
+
   // ── Spec-Kit Integration (Extension-First) ────────────────────────────
   // Delegate LLM/IDE detection and spec-kit skill install to `specify init`
   const specKitAvailable = isSpecKitAvailable();

package/cli/commands/upgrade.mjs

@@ -0,0 +1,250 @@
+/**
+ * `docguard upgrade` — check whether the installed CLI and the project's
+ * .docguard.json schema are current, and (with --apply) migrate them.
+ *
+ * Why this exists:
+ *   Users were running stale CLI versions against new project setups, getting
+ *   confusing "validator missing" or "field unknown" warnings. A one-shot
+ *   `docguard upgrade` lets them see the gap and fix it in seconds.
+ *
+ * Three modes:
+ *   docguard upgrade                — report current vs latest, exit 0
+ *   docguard upgrade --check-only   — same report, exit 1 if behind (for CI)
+ *   docguard upgrade --apply        — actually run `npm i -g docguard-cli@latest`
+ *                                     and migrate .docguard.json if needed
+ *
+ * Network access (npm registry fetch) is OPTIONAL — if offline, we fall back
+ * to "could not check remote version" without erroring.
+ */
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+import { c, CURRENT_SCHEMA_VERSION, compareVersions } from '../shared.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG = JSON.parse(readFileSync(resolve(__dirname, '..', '..', 'package.json'), 'utf-8'));
+const INSTALLED_VERSION = PKG.version;
+
+/**
+ * Fetch the latest published version from the npm registry. Uses node's
+ * built-in fetch (Node 18+). Returns null on timeout/error/offline.
+ *
+ * 3-second timeout — we never want this command to feel slow.
+ */
+async function fetchLatestNpmVersion() {
+  const controller = new AbortController();
+  const t = setTimeout(() => controller.abort(), 3000);
+  try {
+    const r = await fetch('https://registry.npmjs.org/docguard-cli/latest', {
+      signal: controller.signal,
+      headers: { Accept: 'application/json' },
+    });
+    if (!r.ok) return null;
+    const data = await r.json();
+    return data && data.version ? data.version : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+/**
+ * Read the project's stored schema version from .docguard.json. Returns:
+ *   - null    : file missing OR unparseable (caller shows "init recommended")
+ *   - '0.0'   : file exists but no `version` field (pre-0.4 schemas — these
+ *               predate the version field and need migration)
+ *   - 'x.y'   : the stored version string
+ */
+function readProjectSchemaVersion(projectDir) {
+  const p = resolve(projectDir, '.docguard.json');
+  if (!existsSync(p)) return null;
+  try {
+    const cfg = JSON.parse(readFileSync(p, 'utf-8'));
+    // Pre-0.4 schemas (e.g. wu-whatsappinbox's original config from 2024)
+    // have no `version` field. Treat as 0.0 so the migration runs end-to-end.
+    return cfg.version || '0.0';
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Idempotent migration: walk the project config and add any fields introduced
+ * since the stored schema version. Returns { changed, newConfig }.
+ *
+ * Each migration is keyed by the version it migrates TO. Adding a new schema
+ * version means adding one entry here.
+ */
+function migrateSchema(cfg, fromVersion) {
+  const migrations = {
+    // v0.4 — pre-0.4 schemas (no `version` field, often `project` instead
+    // of `projectName`) normalize here. Rename `project` → `projectName`
+    // when only the old field is present, stamp the version, no other change.
+    '0.4': (c) => {
+      const out = { ...c, version: '0.4' };
+      if (!out.projectName && out.project) {
+        out.projectName = out.project;
+        delete out.project;
+      }
+      return out;
+    },
+    // v0.5 — K-4 per-validator severity overrides. Migration is purely
+    // additive: existing projects get an empty severity map and default
+    // (medium) behavior. No behavioral change unless they explicitly opt in.
+    '0.5': (c) => ({ ...c, severity: c.severity || {}, version: '0.5' }),
+  };
+  let current = { ...cfg };
+  let changed = false;
+  const target = CURRENT_SCHEMA_VERSION;
+  // No migrations yet — current schema matches the constant.
+  if (compareVersions(fromVersion, target) >= 0) return { changed: false, newConfig: current };
+  for (const [ver, fn] of Object.entries(migrations)) {
+    if (compareVersions(fromVersion, ver) < 0 && compareVersions(ver, target) <= 0) {
+      current = fn(current);
+      changed = true;
+    }
+  }
+  if (changed) current.version = target;
+  return { changed, newConfig: current };
+}
+
+/**
+ * Apply a CLI upgrade by running `npm install -g docguard-cli@latest`. We
+ * shell out instead of importing npm — npm is not a runtime dependency and
+ * we want zero-deps. Returns the spawn result.
+ */
+function applyCliUpgrade() {
+  const r = spawnSync('npm', ['install', '-g', 'docguard-cli@latest'], {
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+  });
+  return r;
+}
+
+export async function runUpgrade(projectDir, _config, flags) {
+  const checkOnly = flags.checkOnly || flags['check-only'];
+  const apply = flags.apply;
+
+  console.log(`${c.bold}🔧 DocGuard Upgrade${c.reset}`);
+  console.log(`${c.dim}   Checking CLI and schema versions...${c.reset}\n`);
+
+  // CLI version check
+  const latest = await fetchLatestNpmVersion();
+  const cliCmp = latest ? compareVersions(INSTALLED_VERSION, latest) : 0;
+  const cliBehind = cliCmp < 0;
+
+  // Schema version check
+  const projectSchema = readProjectSchemaVersion(projectDir);
+  const schemaCmp = projectSchema ? compareVersions(projectSchema, CURRENT_SCHEMA_VERSION) : 0;
+  const schemaBehind = projectSchema !== null && schemaCmp < 0;
+
+  // ── Report ──────────────────────────────────────────────────────────────
+  console.log(`  ${c.cyan}CLI${c.reset}    installed: ${c.bold}v${INSTALLED_VERSION}${c.reset}`);
+  if (latest) {
+    if (cliBehind) {
+      console.log(`         latest:    ${c.yellow}v${latest}${c.reset} ${c.yellow}(behind)${c.reset}`);
+    } else if (cliCmp > 0) {
+      console.log(`         latest:    v${latest} ${c.dim}(you're ahead — dev build)${c.reset}`);
+    } else {
+      console.log(`         latest:    ${c.green}v${latest}${c.reset} ${c.green}(current)${c.reset}`);
+    }
+  } else {
+    console.log(`         latest:    ${c.dim}could not check (offline?)${c.reset}`);
+  }
+
+  console.log();
+  // Two distinct null cases vs. '0.0' (pre-0.4):
+  //   null    → no .docguard.json at all → run init
+  //   '0.0'   → file exists but missing the `version` field → migration eligible
+  //   other   → real version string
+  const labelForProject = projectSchema === null
+    ? `${c.dim}(no .docguard.json found)${c.reset}`
+    : projectSchema === '0.0'
+      ? `${c.yellow}pre-0.4 (no version field)${c.reset}`
+      : `${c.bold}v${projectSchema}${c.reset}`;
+  console.log(`  ${c.cyan}Schema${c.reset} project:   ${labelForProject}`);
+  if (projectSchema) {
+    if (schemaBehind) {
+      console.log(`         current:   ${c.yellow}v${CURRENT_SCHEMA_VERSION}${c.reset} ${c.yellow}(behind)${c.reset}`);
+    } else if (schemaCmp > 0) {
+      console.log(`         current:   v${CURRENT_SCHEMA_VERSION} ${c.dim}(project is ahead — newer CLI needed)${c.reset}`);
+    } else {
+      console.log(`         current:   ${c.green}v${CURRENT_SCHEMA_VERSION}${c.reset} ${c.green}(current)${c.reset}`);
+    }
+  } else {
+    console.log(`         current:   v${CURRENT_SCHEMA_VERSION} ${c.dim}— run ${c.cyan}docguard init${c.dim} to create one${c.reset}`);
+  }
+
+  console.log();
+
+  // ── Decide what to do ───────────────────────────────────────────────────
+  const anythingBehind = cliBehind || schemaBehind;
+  if (!anythingBehind) {
+    console.log(`  ${c.green}✅ Everything is up to date.${c.reset}`);
+    return;
+  }
+
+  // What needs doing
+  console.log(`${c.bold}  Recommended actions:${c.reset}`);
+  if (cliBehind) {
+    console.log(`    ${c.yellow}•${c.reset} Upgrade CLI:    ${c.cyan}npm install -g docguard-cli@latest${c.reset}`);
+  }
+  if (schemaBehind) {
+    console.log(`    ${c.yellow}•${c.reset} Migrate schema: ${c.cyan}docguard upgrade --apply${c.reset} ${c.dim}(or hand-edit .docguard.json)${c.reset}`);
+  }
+  console.log();
+
+  // ── --check-only: exit 1 to fail CI ─────────────────────────────────────
+  if (checkOnly) {
+    console.log(`${c.red}Exit 1 — versions behind (--check-only mode).${c.reset}`);
+    process.exit(1);
+  }
+
+  // ── --apply: actually run the migration ─────────────────────────────────
+  if (apply) {
+    console.log(`${c.bold}  Applying upgrades...${c.reset}\n`);
+
+    if (cliBehind) {
+      console.log(`  ${c.dim}Running:${c.reset} npm install -g docguard-cli@latest`);
+      const r = applyCliUpgrade();
+      if (r.status !== 0) {
+        console.error(`  ${c.red}✗ CLI upgrade failed.${c.reset} Try with sudo, or check npm permissions.`);
+        process.exit(1);
+      }
+      console.log(`  ${c.green}✓ CLI upgraded.${c.reset}`);
+    }
+
+    if (schemaBehind && projectSchema) {
+      const cfgPath = resolve(projectDir, '.docguard.json');
+      const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
+      const { changed, newConfig } = migrateSchema(cfg, projectSchema);
+      if (changed) {
+        writeFileSync(cfgPath, JSON.stringify(newConfig, null, 2) + '\n', 'utf-8');
+        console.log(`  ${c.green}✓ Schema migrated ${projectSchema} → ${newConfig.version}.${c.reset}`);
+      } else {
+        console.log(`  ${c.dim}Schema migration was a no-op (no recipe registered yet for ${projectSchema} → ${CURRENT_SCHEMA_VERSION}).${c.reset}`);
+      }
+    }
+
+    console.log(`\n  ${c.green}✅ Upgrade complete.${c.reset} Run ${c.cyan}docguard guard${c.reset} to verify.`);
+  }
+}
+
+/**
+ * Lightweight check for the post-guard nudge — returns a string when the
+ * project is behind, null when it's current. Cheap to call; never throws.
+ */
+export function checkUpgradeStatus(projectDir) {
+  const schema = readProjectSchemaVersion(projectDir);
+  if (!schema) return null;
+  if (compareVersions(schema, CURRENT_SCHEMA_VERSION) < 0) {
+    // '0.0' is the internal sentinel for pre-0.4 schemas (no `version` field).
+    // Surface that as a friendlier label so users don't see "Schema 0.0".
+    const label = schema === '0.0' ? 'pre-0.4 (no version field)' : `v${schema}`;
+    return `Schema ${label} is behind current v${CURRENT_SCHEMA_VERSION}. Run \`docguard upgrade --apply\` to migrate.`;
+  }
+  return null;
+}