docguard-cli 0.23.0 → 0.24.0

package/cli/commands/score.mjs

@@ -6,7 +6,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
 import { execSync } from 'node:child_process';
-import { c } from '../shared.mjs';
+import { c, docHasSection } from '../shared.mjs';
 import { validateSecurity } from '../validators/security.mjs';
 import { runGuardInternal } from './guard.mjs';
 
@@ -407,16 +407,23 @@ function calcAllScores(projectDir, config) {
   const scores = {};
   const details = {}; // Per-category failure details for actionable suggestions
 
-  scores.structure = calcStructureScore(projectDir, config);
-  const dqResult = calcDocQualityScore(projectDir, config);
-  scores.docQuality = dqResult.score;
-  details.docQuality = dqResult.failures;
-  scores.testing = calcTestingScore(projectDir, config);
-  scores.security = calcSecurityScore(projectDir, config);
-  scores.environment = calcEnvironmentScore(projectDir, config);
-  scores.drift = calcDriftScore(projectDir, config);
-  scores.changelog = calcChangelogScore(projectDir, config);
-  scores.architecture = calcArchitectureScore(projectDir, config);
+  // Every calc*Score returns { score, failures } so the "Top improvements"
+  // line can name the sub-checks that actually failed instead of printing a
+  // static per-category template (field report, Issue B).
+  for (const [cat, fn] of [
+    ['structure',    calcStructureScore],
+    ['docQuality',   calcDocQualityScore],
+    ['testing',      calcTestingScore],
+    ['security',     calcSecurityScore],
+    ['environment',  calcEnvironmentScore],
+    ['drift',        calcDriftScore],
+    ['changelog',    calcChangelogScore],
+    ['architecture', calcArchitectureScore],
+  ]) {
+    const { score, failures } = fn(projectDir, config);
+    scores[cat] = score;
+    details[cat] = failures || [];
+  }
 
   let totalScore = 0;
   for (const [category, score] of Object.entries(scores)) {
@@ -432,23 +439,29 @@ function calcAllScores(projectDir, config) {
 function calcStructureScore(dir, config) {
   let found = 0;
   let total = 0;
+  const failures = [];
 
   for (const file of config.requiredFiles.canonical) {
     total++;
     if (existsSync(resolve(dir, file))) found++;
+    else failures.push({ issue: `missing ${file}` });
   }
 
   total++;
   const hasAgent = config.requiredFiles.agentFile.some(f => existsSync(resolve(dir, f)));
   if (hasAgent) found++;
+  else failures.push({ issue: `missing agent file (${config.requiredFiles.agentFile.join(' or ')})` });
 
   total++;
   if (existsSync(resolve(dir, config.requiredFiles.changelog))) found++;
+  else failures.push({ issue: `missing ${config.requiredFiles.changelog}` });
 
   total++;
   if (existsSync(resolve(dir, config.requiredFiles.driftLog))) found++;
+  else failures.push({ issue: `missing ${config.requiredFiles.driftLog}` });
 
-  return total === 0 ? 0 : Math.round((found / total) * 100);
+  const score = total === 0 ? 0 : Math.round((found / total) * 100);
+  return { score, failures };
 }
 
 function calcDocQualityScore(dir, config) {
@@ -476,7 +489,10 @@ function calcDocQualityScore(dir, config) {
 
     for (const section of sections) {
       total++;
-      if (content.includes(section)) {
+      // v0.24: synonym/number-tolerant (docHasSection) so arc42/C4 headings
+      // count — was a literal substring check that flagged equivalent sections
+      // as missing, making structured docs score worse than the skeleton.
+      if (docHasSection(content, section)) {
         found++;
       } else {
         failures.push({ file, issue: `missing section: ${section}`, fixCmd: `docguard fix --doc ${docName}` });
@@ -499,6 +515,7 @@ function calcDocQualityScore(dir, config) {
 
 function calcTestingScore(dir, config) {
   let score = 0;
+  const failures = [];
 
   // ── Check 1: Test files exist (40 pts) ──
   // Check top-level test directories
@@ -561,32 +578,47 @@ function calcTestingScore(dir, config) {
   }
 
   if (hasTopLevelTestDir || hasColocatedTests || hasPatternTests || hasConfigTests) score += 40;
+  else failures.push({ issue: 'no test files found (looked in tests/, src/**/__tests__, and configured testPatterns)' });
 
   // ── Check 2: TEST-SPEC.md exists (30 pts) ──
   if (existsSync(resolve(dir, 'docs-canonical/TEST-SPEC.md'))) score += 30;
+  else failures.push({ issue: 'TEST-SPEC.md missing', fixCmd: 'docguard fix --doc test-spec' });
 
   // ── Check 3: Test config or built-in runner (15 pts) ──
-  const testConfigs2 = ['jest.config.js', 'jest.config.ts', 'vitest.config.ts', 'vitest.config.js', 'pytest.ini', 'setup.cfg', '.mocharc.yml'];
-  const hasTestConfig = testConfigs2.some(f => existsSync(resolve(dir, f)));
+  const testConfigFiles = ['jest.config.js', 'jest.config.ts', 'vitest.config.ts', 'vitest.config.js', 'pytest.ini', 'setup.cfg', '.mocharc.yml'];
+  let hasTestRunner = testConfigFiles.some(f => existsSync(resolve(dir, f)));
+
+  // Python: pytest config usually lives inside pyproject.toml ([tool.pytest.ini_options])
+  // or tox.ini ([pytest]) — not a standalone file. Detect those too, so a uv/pytest
+  // project isn't told to "add a test runner" it already configured (field report, Issue B).
+  if (!hasTestRunner) {
+    for (const [file, marker] of [['pyproject.toml', /\[tool\.pytest/], ['tox.ini', /\[pytest\]/]]) {
+      const p = resolve(dir, file);
+      if (!existsSync(p)) continue;
+      try { if (marker.test(readFileSync(p, 'utf-8'))) { hasTestRunner = true; break; } } catch { /* skip */ }
+    }
+  }
 
-  if (hasTestConfig) {
-    score += 15;
-  } else {
+  // node:test has no config file — recognize it via projectTypeConfig or package.json.
+  if (!hasTestRunner) {
     const ptc = config.projectTypeConfig || {};
-    const pkgPath = resolve(dir, 'package.json');
     if (ptc.testFramework === 'node:test') {
-      score += 15;
-    } else if (existsSync(pkgPath)) {
-      try {
-        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-        const testScript = pkg.scripts?.test || '';
-        if (testScript.includes('node --test') || testScript.includes('node:test')) {
-          score += 15;
-        }
-      } catch { /* skip */ }
+      hasTestRunner = true;
+    } else {
+      const pkgPath = resolve(dir, 'package.json');
+      if (existsSync(pkgPath)) {
+        try {
+          const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+          const testScript = pkg.scripts?.test || '';
+          if (testScript.includes('node --test') || testScript.includes('node:test')) hasTestRunner = true;
+        } catch { /* skip */ }
+      }
     }
   }
 
+  if (hasTestRunner) score += 15;
+  else failures.push({ issue: 'no test runner config detected (jest/vitest/pytest/node:test)' });
+
   // ── Check 4: CI test step (15 pts) ──
   // Support multiple CI systems — not just GitHub Actions
   const ciFiles = [
@@ -613,8 +645,9 @@ function calcTestingScore(dir, config) {
   }
 
   if (hasCITest) score += 15;
+  else failures.push({ issue: 'no CI test step (.github/workflows, .gitlab-ci.yml, Jenkinsfile, etc.)' });
 
-  return Math.min(100, score);
+  return { score: Math.min(100, score), failures };
 }
 
 /**
@@ -668,9 +701,11 @@ function walkForTests(d, ignoreSet) {
 function calcSecurityScore(dir, config) {
   let score = 0;
   const ptc = config.projectTypeConfig || {};
+  const failures = [];
 
   // SECURITY.md exists (25 pts)
   if (existsSync(resolve(dir, 'docs-canonical/SECURITY.md'))) score += 25;
+  else failures.push({ issue: 'SECURITY.md missing', fixCmd: 'docguard fix --doc security' });
 
   // .gitignore exists and includes .env (15 + 15 pts)
   const gitignorePath = resolve(dir, '.gitignore');
@@ -678,16 +713,22 @@ function calcSecurityScore(dir, config) {
     score += 15;
     const content = readFileSync(gitignorePath, 'utf-8');
     if (content.includes('.env')) score += 15;
+    else failures.push({ issue: '.gitignore does not list .env' });
+  } else {
+    failures.push({ issue: '.gitignore missing' });
   }
 
   // No .env file committed (10 pts)
   if (!existsSync(resolve(dir, '.env')) || existsSync(gitignorePath)) score += 10;
+  else failures.push({ issue: '.env is committed without a .gitignore' });
 
   // .env.example exists (safe template) — only check if project needs env vars (10 pts)
   if (ptc.needsEnvExample === false) {
     score += 10; // Full marks — project doesn't need env vars
   } else if (existsSync(resolve(dir, '.env.example'))) {
     score += 10;
+  } else {
+    failures.push({ issue: '.env.example missing' });
   }
 
   // No hardcoded secrets found by security validator (25 pts)
@@ -703,26 +744,31 @@ function calcSecurityScore(dir, config) {
       if (findingCount <= 2) score += 15;
       else if (findingCount <= 5) score += 5;
       // 6+ findings = 0 pts for this check
+      failures.push({ issue: `${findingCount} possible secret(s) / unsafe pattern(s) in code — run \`docguard guard --verbose\`` });
     }
   } catch {
     // If validator fails to run, give benefit of the doubt
     score += 25;
   }
 
-  return Math.min(100, score);
+  return { score: Math.min(100, score), failures };
 }
 
 function calcEnvironmentScore(dir, config) {
   let score = 0;
   const ptc = config.projectTypeConfig || {};
+  const failures = [];
 
   if (existsSync(resolve(dir, 'docs-canonical/ENVIRONMENT.md'))) score += 40;
+  else failures.push({ issue: 'ENVIRONMENT.md missing', fixCmd: 'docguard fix --doc environment' });
 
   // .env.example — only check if project needs env vars
   if (ptc.needsEnvExample === false) {
     score += 30; // Full marks — project doesn't need env vars
   } else if (existsSync(resolve(dir, '.env.example'))) {
     score += 30;
+  } else {
+    failures.push({ issue: '.env.example missing' });
   }
 
   // Check for setup documentation
@@ -733,56 +779,79 @@ function calcEnvironmentScore(dir, config) {
       score += 30;
     } else {
       score += 15;  // README exists but no setup section
+      failures.push({ issue: 'README has no Setup / Getting Started section' });
     }
+  } else {
+    failures.push({ issue: 'README.md missing' });
   }
 
-  return Math.min(100, score);
+  return { score: Math.min(100, score), failures };
 }
 
 function calcDriftScore(dir, config) {
   // Perfect score if drift log exists and no unlogged drift comments
-  if (!existsSync(resolve(dir, config.requiredFiles.driftLog))) return 0;
+  if (!existsSync(resolve(dir, config.requiredFiles.driftLog))) {
+    return { score: 0, failures: [{ issue: `${config.requiredFiles.driftLog} missing` }] };
+  }
 
   let score = 50; // Drift log exists
+  const failures = [];
 
   const content = readFileSync(resolve(dir, config.requiredFiles.driftLog), 'utf-8');
 
   // Has structure (headers)
   if (content.includes('## ') || content.includes('| ')) score += 25;
+  else failures.push({ issue: `${config.requiredFiles.driftLog} has no headers or table structure` });
 
   // Has entries (not just template)
   const lines = content.split('\n').filter(l => l.trim() && !l.startsWith('#') && !l.startsWith('<!--'));
   if (lines.length > 3) score += 25;
+  else failures.push({ issue: `${config.requiredFiles.driftLog} has no entries yet (template only)` });
 
-  return Math.min(100, score);
+  return { score: Math.min(100, score), failures };
 }
 
 function calcChangelogScore(dir, config) {
   const path = resolve(dir, config.requiredFiles.changelog);
-  if (!existsSync(path)) return 0;
+  if (!existsSync(path)) {
+    return { score: 0, failures: [{ issue: `${config.requiredFiles.changelog} missing` }] };
+  }
 
   let score = 40; // Exists
+  const failures = [];
   const content = readFileSync(path, 'utf-8');
 
   if (content.includes('[Unreleased]') || content.includes('[unreleased]')) score += 30;
+  else failures.push({ issue: 'no [Unreleased] section' });
   if (/## \[[\d.]+\]/.test(content)) score += 30;
+  else failures.push({ issue: 'no versioned release headings (## [x.y.z])' });
 
-  return Math.min(100, score);
+  return { score: Math.min(100, score), failures };
 }
 
 function calcArchitectureScore(dir) {
   const archPath = resolve(dir, 'docs-canonical/ARCHITECTURE.md');
-  if (!existsSync(archPath)) return 0;
+  if (!existsSync(archPath)) {
+    return { score: 0, failures: [{ issue: 'ARCHITECTURE.md missing', fixCmd: 'docguard fix --doc architecture' }] };
+  }
 
   let score = 30;
+  const failures = [];
   const content = readFileSync(archPath, 'utf-8');
 
-  if (content.includes('## Layer Boundaries') || content.includes('## Component Map')) score += 25;
+  // v0.24: heading checks are synonym/number-tolerant (docHasSection) so arc42
+  // ("## 5.4 Layer boundaries") and C4 ("## Building Block View") docs score
+  // their real content instead of being told to add sections they have.
+  if (docHasSection(content, '## Layer Boundaries') || docHasSection(content, '## Component Map')) score += 25;
+  else failures.push({ issue: 'no Layer Boundaries / Component Map section' });
   if (content.includes('```mermaid') || content.includes('graph ')) score += 20;
-  if (content.includes('## External Dependencies')) score += 15;
-  if (content.includes('## Revision History')) score += 10;
+  else failures.push({ issue: 'no architecture diagram (mermaid / graph)' });
+  if (docHasSection(content, '## External Dependencies')) score += 15;
+  else failures.push({ issue: 'no External Dependencies section' });
+  if (docHasSection(content, '## Revision History')) score += 10;
+  else failures.push({ issue: 'no Revision History section' });
 
-  return Math.min(100, score);
+  return { score: Math.min(100, score), failures };
 }
 
 // ── Helpers ────────────────────────────────────────────────────────────────
@@ -803,37 +872,54 @@ function getGrade(score) {
   return 'F';
 }
 
+// Default fix command per category, used when a failure doesn't carry its own.
+const CATEGORY_FIX = {
+  structure:    'docguard init',
+  docQuality:   'docguard fix',
+  testing:      'docguard fix --doc test-spec',
+  security:     'docguard fix --doc security',
+  environment:  'docguard fix --doc environment',
+  architecture: 'docguard fix --doc architecture',
+};
+
+// Static fallback — only reached if a category scores < 100 but recorded no
+// specific failure (shouldn't happen now that every deduction tracks one).
+const STATIC_SUGGESTIONS = {
+  structure: 'Run `docguard init` to create missing documentation',
+  docQuality: 'Run `docguard fix` to get AI prompts for each doc that needs content',
+  testing: 'Add test files and create TEST-SPEC.md → Run `docguard fix --doc test-spec`',
+  security: 'Create SECURITY.md and add .env to .gitignore → Run `docguard fix --doc security`',
+  environment: 'Document env variables and create .env.example → Run `docguard fix --doc environment`',
+  drift: 'Create DRIFT-LOG.md and log any code deviations',
+  changelog: 'Maintain CHANGELOG.md with [Unreleased] section',
+  architecture: 'Add layer boundaries and Mermaid diagrams → Run `docguard fix --doc architecture`',
+};
+
 function getSuggestion(category, score, details) {
-  // Dynamic, specific suggestions based on actual failures
-  if (category === 'docQuality' && details?.docQuality?.length > 0) {
-    const failures = details.docQuality;
-    // Group by doc
+  const failures = details?.[category];
+
+  // docQuality groups its failures by doc (they carry { file, issue, fixCmd }).
+  if (category === 'docQuality' && failures?.length > 0) {
     const byDoc = {};
     for (const f of failures) {
-      const doc = f.file.replace('docs-canonical/', '');
+      const doc = (f.file || '').replace('docs-canonical/', '') || 'docs';
       if (!byDoc[doc]) byDoc[doc] = [];
       byDoc[doc].push(f.issue);
     }
     const parts = Object.entries(byDoc).map(([doc, issues]) => `${doc}: ${issues.join(', ')}`);
-    const fixCmd = failures.find(f => f.fixCmd)?.fixCmd || 'docguard fix';
+    const fixCmd = failures.find(f => f.fixCmd)?.fixCmd || CATEGORY_FIX.docQuality;
     return `${parts.join(' | ')} → Run \`${fixCmd}\``;
   }
 
-  const suggestions = {
-    structure: 'Run `docguard init` to create missing documentation',
-    docQuality: 'Run `docguard fix` to get AI prompts for each doc that needs content',
-    testing: score < 40
-      ? 'Add test files (tests/, src/**/__tests__/, or configure testPatterns in .docguard.json) and create TEST-SPEC.md'
-      : 'Configure TEST-SPEC.md and add CI test step → Run `docguard fix --doc test-spec`',
-    security: score < 50
-      ? 'Create SECURITY.md and add .env to .gitignore → Run `docguard fix --doc security`'
-      : 'Review security findings with `docguard guard --verbose` — configure securityIgnore for false positives',
-    environment: 'Document env variables and create .env.example → Run `docguard fix --doc environment`',
-    drift: 'Create DRIFT-LOG.md and log any code deviations',
-    changelog: 'Maintain CHANGELOG.md with [Unreleased] section',
-    architecture: 'Add layer boundaries and Mermaid diagrams → Run `docguard fix --doc architecture`',
-  };
-  return suggestions[category] || 'Review and improve this area';
+  // Every other category: name the sub-checks that actually failed, so the line
+  // never describes work that's already done (field report, Issue B).
+  if (failures?.length > 0) {
+    const base = failures.map(f => f.issue).join('; ');
+    const fixCmd = failures.find(f => f.fixCmd)?.fixCmd || CATEGORY_FIX[category];
+    return fixCmd ? `${base} → Run \`${fixCmd}\`` : base;
+  }
+
+  return STATIC_SUGGESTIONS[category] || 'Review and improve this area';
 }
 
 /**

package/cli/commands/setup.mjs

@@ -22,7 +22,7 @@ import { resolve, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
 import { execSync } from 'node:child_process';
-import { c } from '../shared.mjs';
+import { c, CURRENT_SCHEMA_VERSION } from '../shared.mjs';
 import { ensureSkills, detectAgentMode, isSpecKitInitialized, getDetectedAgent } from '../ensure-skills.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -133,7 +133,7 @@ export async function runSetup(projectDir, config, flags) {
 
       const defaultConfig = {
         projectName: config.projectName,
-        version: '0.4',
+        version: CURRENT_SCHEMA_VERSION, // single source of truth (shared.mjs)
         profile: 'standard',
         projectType: detectedType,
         projectTypeConfig: typeDefaults[detectedType] || typeDefaults.unknown,

package/cli/commands/trace.mjs

@@ -25,7 +25,7 @@ const CODE_EXTENSIONS = new Set([
 // false-negative warnings on Python/Rust/Go/Java projects (reported by the
 // quick-recon-tool Python user: TEST-SPEC.md was flagged unlinked even
 // though Python tests existed because `.test.mjs` didn't match `test_*.py`).
-import { TEST_PATTERNS, TRACE_MAP } from '../shared-trace-patterns.mjs';
+import { TEST_PATTERNS, TRACE_MAP, isTraceableSource } from '../shared-trace-patterns.mjs';
 
 
 /**
@@ -189,7 +189,7 @@ export function runTrace(projectDir, config, flags) {
     // Find matching source files for each pattern
     const traces = [];
     for (const pattern of traceInfo.sourcePatterns) {
-      const matches = projectFiles.filter(f => pattern.glob.test(f));
+      const matches = projectFiles.filter(f => isTraceableSource(f) && pattern.glob.test(f));
       traces.push({
         label: pattern.label,
         matchCount: matches.length,
@@ -374,7 +374,7 @@ function findRelatedTests(projectFiles, sourcePatterns) {
   const relatedTests = new Set();
 
   for (const pattern of sourcePatterns) {
-    const sourceFiles = projectFiles.filter(f => pattern.glob.test(f));
+    const sourceFiles = projectFiles.filter(f => isTraceableSource(f) && pattern.glob.test(f));
     for (const src of sourceFiles) {
       const srcBase = basename(src).replace(/\.[^.]+$/, '');
       const srcDir = src.split('/')[0];

package/cli/commands/upgrade.mjs

@@ -71,14 +71,48 @@ function readProjectSchemaVersion(projectDir) {
   }
 }
 
+/**
+ * Normalize the `requiredFiles` block to the canonical object shape
+ * (`{ canonical: [...], agentFile, changelog, driftLog }`). Validators read
+ * `config.requiredFiles?.canonical || []`, so a config whose `requiredFiles` is
+ * a bare array (a legacy/hand-edited shape) or an object that lost its
+ * `canonical` key makes Traceability/Structure/Freshness silently see an empty
+ * list and PASS — the exact false-green this tool exists to prevent.
+ *
+ * Returns `{ cfg, changed, notes }`. We only TRANSFORM the unambiguous case (a
+ * bare array can only ever have been the canonical doc list); any other broken
+ * shape is SURFACED as a note rather than guessed at.
+ */
+function normalizeRequiredFiles(cfg) {
+  const rf = cfg.requiredFiles;
+  const notes = [];
+  if (rf === undefined || rf === null) {
+    // No requiredFiles at all — validators default to empty and check nothing.
+    // Don't fabricate a list (we can't know the project's docs); surface it.
+    notes.push('⚠ requiredFiles is missing — Traceability/Structure/Freshness have nothing to verify (silent-pass risk). Run `docguard init` to generate it.');
+    return { cfg, changed: false, notes };
+  }
+  if (Array.isArray(rf)) {
+    notes.push('Normalized legacy requiredFiles array → { canonical: [...] } so canonical-doc checks see your docs again.');
+    return { cfg: { ...cfg, requiredFiles: { canonical: rf } }, changed: true, notes };
+  }
+  if (typeof rf === 'object' && !Array.isArray(rf.canonical)) {
+    notes.push('⚠ requiredFiles.canonical is missing or not an array — canonical-doc checks will silently pass. Restore it or run `docguard init`.');
+  }
+  return { cfg, changed: false, notes };
+}
+
 /**
  * Idempotent migration: walk the project config and add any fields introduced
- * since the stored schema version. Returns { changed, newConfig }.
+ * since the stored schema version, then normalize the requiredFiles shape.
+ * Returns { changed, newConfig, notes }.
  *
- * Each migration is keyed by the version it migrates TO. Adding a new schema
- * version means adding one entry here.
+ * Each version migration is keyed by the version it migrates TO. Adding a new
+ * schema version means adding one entry here. The requiredFiles normalization
+ * runs regardless of the version delta — a config can sit at the current
+ * version yet still carry a hand-edited shape that breaks validators silently.
  */
-function migrateSchema(cfg, fromVersion) {
+export 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`
@@ -99,16 +133,24 @@ function migrateSchema(cfg, fromVersion) {
   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;
+
+  // Version-keyed field migrations (additive). Skipped when already current.
+  if (compareVersions(fromVersion, target) < 0) {
+    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;
   }
-  if (changed) current.version = target;
-  return { changed, newConfig: current };
+
+  // requiredFiles shape normalization — independent of the version delta.
+  const norm = normalizeRequiredFiles(current);
+  current = norm.cfg;
+  if (norm.changed) changed = true;
+
+  return { changed, newConfig: current, notes: norm.notes };
 }
 
 /**
@@ -291,7 +333,13 @@ export async function runUpgrade(projectDir, _config, flags) {
     if (schemaBehind && projectSchema) {
       const cfgPath = resolve(projectDir, '.docguard.json');
       const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
-      const { changed, newConfig } = migrateSchema(cfg, projectSchema);
+      const { changed, newConfig, notes } = migrateSchema(cfg, projectSchema);
+      // Surface requiredFiles findings (a normalization that happened, or a
+      // broken shape we refuse to guess at) before reporting the version bump.
+      for (const n of notes || []) {
+        const warn = n.startsWith('⚠');
+        console.log(`  ${warn ? c.yellow : c.dim}${warn ? '' : '• '}${n}${c.reset}`);
+      }
       if (changed) {
         // v0.14-P4: --pr opens a PR for review instead of in-place editing.
         // Useful when the team wants a reviewable diff or has branch-protected

package/cli/config.mjs

@@ -10,13 +10,17 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve, basename } from 'node:path';
-import { c, PROFILES } from './shared.mjs';
+import { c, PROFILES, SEVERITY_LEVELS } from './shared.mjs';
 import { mergeIgnoreFile } from './shared-ignore.mjs';
 
 export function loadConfig(projectDir) {
   const configPath = resolve(projectDir, '.docguard.json');
   const defaults = {
     projectName: basename(projectDir),
+    // Legacy/unversioned fallback ONLY — the value a config is ASSUMED to be
+    // when its file has no `version` field. NOT the current schema version
+    // (that's CURRENT_SCHEMA_VERSION in shared.mjs, written by `init`). Kept low
+    // on purpose so a versionless (pre-0.4) config still trips the upgrade nudge.
     version: '0.2',
     profile: 'standard',
     requiredFiles: {
@@ -89,6 +93,19 @@ export function loadConfig(projectDir) {
       const merged = deepMerge(withProfile, normalizeConfig(userConfig));
       merged.profile = profileName;
 
+      // v0.24: severity accepts only high|medium|low and changes EXIT-CODE
+      // weight — it never mutes a warning from display. A value like "off"
+      // silently fell back to "medium", so users who wrote severity:{k:"off"}
+      // expecting silence still saw the warning and got no feedback (field
+      // report). Surface the misconfig and point at the real disable switch.
+      if (merged.severity && typeof merged.severity === 'object') {
+        for (const [key, val] of Object.entries(merged.severity)) {
+          if (typeof val === 'string' && !SEVERITY_LEVELS.has(val.toLowerCase())) {
+            console.error(`${c.yellow}⚠ .docguard.json: severity.${key} = "${val}" is not a valid level${c.reset} ${c.dim}(use high | medium | low). To silence a validator entirely, set ${c.reset}${c.cyan}validators.${key}: false${c.dim}.${c.reset}`);
+          }
+        }
+      }
+
       // Auto-detect project type if not set
       if (!merged.projectType) {
         merged.projectType = autoDetectProjectType(projectDir);

package/cli/docguard.mjs

@@ -241,6 +241,12 @@ async function main() {
       // Default stays on (discoverability), but lets minimalist library
       // projects skip the .specify/.agent/commands scaffolding.
       flags.noSpecKit = true;
+    } else if (args[i] === '--spec-kit') {
+      // v0.24: explicit opt-IN to the Spec Kit framework scaffold. The
+      // `starter` profile skips that scaffold by default (minimal, for side
+      // projects — it would otherwise drop ~30 files); pass --spec-kit to
+      // include it anyway. No effect on other profiles (already on by default).
+      flags.specKit = true;
     } else if (args[i] === '--pin') {
       // v0.17-P1: `docguard guard --pin` records the running CLI version
       // into .docguard.json (`docguardVersion` field) after a successful run.
@@ -298,6 +304,11 @@ async function main() {
       flags.debate = true;
     } else if (args[i] === '--stdout') {
       flags.stdout = true;
+    } else if (args[i] === '--help' || args[i] === '-h') {
+      // v0.24: capture --help anywhere on the line, not just as the bare
+      // command. Previously `docguard generate --help` fell through the parser
+      // and executed generate, scaffolding files into the cwd (field report).
+      flags.help = true;
     }
   }
 
@@ -313,6 +324,14 @@ async function main() {
     process.exit(0);
   }
 
+  // v0.24: `docguard <command> --help` shows usage instead of running the
+  // command. There is no per-command help yet, so global help is correct — and,
+  // unlike before, non-destructive (generate no longer scaffolds on --help).
+  if (flags.help) {
+    printHelp();
+    process.exit(0);
+  }
+
   // In JSON mode the entire stdout MUST be parseable JSON. The banner and
   // ensureSkills' install message would corrupt the output for any
   // programmatic consumer (CI, dashboards, the Score-on-PR Action recipe).