docguard-cli 0.15.3 → 0.17.0

package/cli/commands/diff.mjs

@@ -25,8 +25,12 @@ const CODE_EXTENSIONS = new Set([
 ]);
 
 export function runDiff(projectDir, config, flags) {
-  console.log(`${c.bold}🔍 DocGuard Diff — ${config.projectName}${c.reset}`);
-  console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
+  // v0.16-P1: headless mode for JSON output (matches guard/score/trace fix).
+  const isJson = flags.format === 'json';
+  if (!isJson) {
+    console.log(`${c.bold}🔍 DocGuard Diff — ${config.projectName}${c.reset}`);
+    console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
+  }
 
   const results = [];
 
@@ -97,7 +101,7 @@ export function runDiff(projectDir, config, flags) {
 
 // ── Diff Functions ─────────────────────────────────────────────────────────
 
-function diffRoutes(dir, config = {}) {
+export function diffRoutes(dir, config = {}) {
   // Documented surface: prefer the dedicated API reference, fall back to ARCHITECTURE.md.
   const apiRefPath = resolve(dir, 'docs-canonical/API-REFERENCE.md');
   const archPath = resolve(dir, 'docs-canonical/ARCHITECTURE.md');
@@ -129,7 +133,7 @@ const CODE_ENTITY_NOISE = new Set([
   'models', 'model', 'utils', 'helpers', 'constants', 'config', 'common', 'base',
 ]);
 
-function diffEntities(dir, config = {}) {
+export function diffEntities(dir, config = {}) {
   const dataModelPath = resolve(dir, 'docs-canonical/DATA-MODEL.md');
   if (!existsSync(dataModelPath)) return null;
 
@@ -196,7 +200,26 @@ function diffEntities(dir, config = {}) {
   };
 }
 
-function diffEnvVars(dir, config = {}) {
+// v0.16-P4: common system environment variables that get backticked in
+// prose ("the venv `PATH`", "your `HOME` directory") but are NEVER user-set
+// application env vars. Excluding them from the docVars set kills the
+// false-positive class reported by the Python user where `PATH` was flagged
+// as "documented-but-not-implemented".
+//
+// Conservative list — only the names that are unambiguously OS/shell vars.
+// Application names like `DATABASE_URL`, `API_KEY` etc. still count.
+const SYSTEM_ENV_VARS = new Set([
+  'PATH', 'HOME', 'USER', 'USERNAME', 'SHELL', 'PWD', 'OLDPWD', 'TMPDIR', 'TEMP', 'TMP',
+  'LANG', 'LC_ALL', 'LC_CTYPE', 'LC_MESSAGES', 'TZ',
+  'EDITOR', 'VISUAL', 'PAGER', 'TERM', 'COLORTERM',
+  'DISPLAY', 'SSH_AUTH_SOCK', 'SSH_CONNECTION', 'SSH_TTY',
+  'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_CACHE_HOME', 'XDG_RUNTIME_DIR',
+  // CI/build platform vars (set by the platform, not by the app)
+  'CI', 'GITHUB_TOKEN', 'GITHUB_ACTIONS', 'GITHUB_REF', 'GITHUB_SHA',
+  'NODE_ENV', // could be app-set but more often platform-set; conservative skip
+]);
+
+export function diffEnvVars(dir, config = {}) {
   const envDocPath = resolve(dir, 'docs-canonical/ENVIRONMENT.md');
   if (!existsSync(envDocPath)) return null;
 
@@ -208,6 +231,9 @@ function diffEnvVars(dir, config = {}) {
   const varRegex = /`([A-Z][A-Z0-9_]*[A-Z0-9])`/g;
   let match;
   while ((match = varRegex.exec(content)) !== null) {
+    // v0.16-P4: skip backticked system vars that appear in prose. They're
+    // never user-set application env vars; flagging them produces noise.
+    if (SYSTEM_ENV_VARS.has(match[1])) continue;
     docVars.add(match[1]);
   }
 
@@ -237,7 +263,7 @@ function diffEnvVars(dir, config = {}) {
   };
 }
 
-function diffTechStack(dir, config = {}) {
+export function diffTechStack(dir, config = {}) {
   const archPath = resolve(dir, 'docs-canonical/ARCHITECTURE.md');
   if (!existsSync(archPath)) return null;
 

package/cli/commands/explain.mjs

@@ -0,0 +1,286 @@
+/**
+ * Explain Command — v0.16-P6.
+ *
+ * Asked for by a user who'd spent 5-10 minutes per warning spelunking
+ * through validators/*.mjs source to understand what the validator wanted.
+ * `docguard explain "<warning text>"` matches the warning back to its
+ * validator and prints:
+ *   - Which validator emitted it
+ *   - What pattern triggered it
+ *   - A passing example
+ *   - The doc / spec / standard it's checking against
+ *
+ * Also supports `docguard explain <validator-key>` to show the whole
+ * validator's purpose without needing a specific warning.
+ *
+ * Zero NPM dependencies. Pure lookup table.
+ */
+
+import { c } from '../shared.mjs';
+
+/**
+ * Validator-key → human-readable explainer. Keyed by the same key DocGuard
+ * uses internally for severity overrides + lite-mode selection.
+ *
+ * Each entry has:
+ *   - title:    one-line summary
+ *   - what:     what the validator checks (declarative)
+ *   - why:      why it matters (motivation)
+ *   - triggers: array of common warning fragments and what each means
+ *   - example:  a tiny passing snippet
+ *   - standard: the spec/practice the validator references
+ */
+const EXPLAINERS = {
+  structure: {
+    title: 'Structure — required CDD files exist',
+    what: 'Verifies the canonical files declared in .docguard.json `requiredFiles.canonical` are present, plus AGENTS.md/CLAUDE.md, CHANGELOG.md, DRIFT-LOG.md.',
+    why:  'A documentation memory needs known anchor points. Missing files = broken memory.',
+    triggers: [
+      ['Missing required file', 'A canonical doc declared in your config doesn\'t exist on disk. Create it or remove it from `requiredFiles.canonical`.'],
+      ['Missing agent file', 'No AGENTS.md or CLAUDE.md found. Create one — even a stub establishes the agent contract.'],
+    ],
+    example: 'docs-canonical/ARCHITECTURE.md, AGENTS.md, CHANGELOG.md all present',
+    standard: 'CDD STANDARD (this project\'s STANDARD.md)',
+  },
+  docsSync: {
+    title: 'Docs-Sync — code files are referenced in canonical docs',
+    what: 'Walks route/service files in your source tree. For each, checks that the file path or basename appears in any canonical doc.',
+    why:  'Code that exists but isn\'t mentioned in any doc is invisible to future contributors and AI agents.',
+    triggers: [
+      ['not referenced in any canonical doc', 'A route or service file has no mention anywhere in docs-canonical/. Add a one-line reference (path or filename) to ARCHITECTURE.md or DATA-MODEL.md.'],
+    ],
+    example: '`src/services/auth.ts` mentioned in ARCHITECTURE.md\'s Components table',
+    standard: 'arc42 Component Map',
+  },
+  drift: {
+    title: 'Drift-Comments — every `// DRIFT:` has a DRIFT-LOG entry',
+    what: 'Scans code for `// DRIFT: reason` comments (also # / /* / -- variants). Each must have a row in DRIFT-LOG.md.',
+    why:  'DRIFT comments document conscious deviations from canonical specs. Without log entries, the deviation is invisible.',
+    triggers: [
+      ['DRIFT comment but DRIFT-LOG.md doesn\'t exist', 'Create DRIFT-LOG.md or remove the DRIFT comment.'],
+      ['no matching DRIFT-LOG.md entry', 'Add a row to DRIFT-LOG.md documenting the deviation, OR remove the // DRIFT: comment if the deviation is no longer current.'],
+    ],
+    example: '// DRIFT: using S3 SDK v2 here for compatibility — DRIFT-LOG.md has a row dated and explaining why',
+    standard: 'CDD principle: log every intentional deviation',
+  },
+  changelog: {
+    title: 'Changelog — Keep a Changelog format',
+    what: 'CHANGELOG.md must have a top-level `# Changelog` heading and an `## [Unreleased]` section.',
+    why:  'Standard format makes changelogs machine-readable. The Unreleased section is where new work accumulates between releases.',
+    triggers: [
+      ['Missing # Changelog heading', 'Start CHANGELOG.md with `# Changelog`.'],
+      ['Missing ## [Unreleased] section', 'Add `## [Unreleased]` between `# Changelog` and your first dated release.'],
+    ],
+    example: '# Changelog\\n\\n## [Unreleased]\\n\\n## [1.0.0] - 2026-01-01',
+    standard: 'Keep a Changelog v1.1.0 (https://keepachangelog.com)',
+  },
+  testSpec: {
+    title: 'Test-Spec — declared tests exist',
+    what: 'Reads TEST-SPEC.md\'s test mapping (rows linking sources to test files) and verifies each referenced test file exists.',
+    why:  'A spec that claims test coverage for X but the test file is missing is a stale promise.',
+    triggers: [
+      ['no service-to-test mappings', 'TEST-SPEC.md has no recognized mapping table. Add a table with `| Source | Test file | Status |` columns.'],
+      ['referenced test file does not exist', 'A path in TEST-SPEC.md\'s mapping doesn\'t exist. Update the path or remove the row.'],
+    ],
+    example: '| `src/auth.ts` | `tests/auth.test.ts` | ✅ |',
+    standard: 'ISO/IEC/IEEE 29119-3 (test specification)',
+  },
+  environment: {
+    title: 'Environment — env vars used in code are documented',
+    what: 'Greps `process.env.X` and `import.meta.env.X` (plus `os.environ` for Python) across source. Each name must appear in ENVIRONMENT.md or .env.example/.env.template.',
+    why:  'Undocumented env vars are runtime surprises waiting to happen.',
+    triggers: [
+      ['used but not documented', 'Code reads an env var that ENVIRONMENT.md doesn\'t list. Add it to the table.'],
+      ['VITE_API_URL or similar prefix', 'Naked prefixes like `VITE_` (no suffix) get filtered out — they\'re convention markers, not real var names.'],
+    ],
+    example: '`DATABASE_URL` listed in ENVIRONMENT.md\'s Environment Variables table AND read via `process.env.DATABASE_URL` in code',
+    standard: '12-Factor App III. Config',
+  },
+  security: {
+    title: 'Security — secrets handling + auth presence',
+    what: 'Checks SECURITY.md for required sections, and scans code for committed secrets / unsafe patterns.',
+    why:  'OWASP ASVS baseline.',
+    triggers: [
+      ['Missing "Authentication" section', 'Add `## Authentication` to SECURITY.md. If the project genuinely has no auth (CLI, library), use the v0.16-P7 N/A marker: `<!-- docguard:section authentication n/a — reason -->`.'],
+      ['Possible secret', 'A pattern matching common secret formats (API keys, JWT secrets) was found in committed code. Move to env var or .env.example.'],
+    ],
+    example: 'SECURITY.md has `## Authentication` describing JWT flow; no `sk_live_*` strings in code',
+    standard: 'OWASP ASVS v4.0',
+  },
+  freshness: {
+    title: 'Freshness — docs updated alongside code',
+    what: 'For each canonical doc, counts code commits since the doc\'s last commit. >10 commits = stale.',
+    why:  'Docs drift silently. This validator surfaces the drift before it becomes invisible.',
+    triggers: [
+      ['code commits since last doc update', 'Run `docguard sync --write` to refresh code-truth sections, then review the prose for accuracy.'],
+      ['DRIFT-LOG.md may be stale', 'DRIFT comments in code outpaced log entries. Add the entries.'],
+    ],
+    example: 'ARCHITECTURE.md last committed within 10 code commits',
+    standard: 'CDD principle: docs and code commit together',
+  },
+  traceability: {
+    title: 'Traceability — every FR/SC ID has test coverage',
+    what: 'Scans specs/ for FR-### and SC-### requirement IDs. Each must appear in a test file as `@req FR-###`.',
+    why:  'Untraceable requirements drift from implementation.',
+    triggers: [
+      ['has no test coverage', 'Add `// @req FR-012` (or similar) as a comment in the test that verifies the requirement.'],
+      ['orphaned test reference', 'A `@req` comment references an ID that doesn\'t exist in any spec. Update the ID or remove the marker.'],
+    ],
+    example: 'spec.md defines `**FR-012**: ...` and test file has `// @req FR-012` near the test that verifies it',
+    standard: 'ISO/IEC/IEEE 29148 (requirements traceability)',
+  },
+  apiSurface: {
+    title: 'API-Surface — endpoints in code match API-REFERENCE.md',
+    what: 'Compares routes scanned from code (Express, Next, FastAPI, Spring, etc.) against endpoints listed in API-REFERENCE.md and OpenAPI specs.',
+    why:  'Documented but missing endpoints are dead links. Endpoints in code that aren\'t documented are invisible.',
+    triggers: [
+      ['documented but absent', 'API-REFERENCE.md lists an endpoint that scanRoutes() can\'t find. Remove or fix the doc; `fix --write` removes when marked.'],
+      ['present but undocumented', 'A route exists in code but API-REFERENCE.md doesn\'t list it. Add it.'],
+    ],
+    example: 'GET /api/users in src/routes/users.ts AND in API-REFERENCE.md\'s Endpoints table',
+    standard: 'OpenAPI 3.1',
+  },
+  metricsConsistency: {
+    title: 'Metrics-Consistency — quoted numbers match reality',
+    what: 'Greps canonical + root docs for "N validators" / "N checks" claims and compares against the actual runtime count.',
+    why:  'Stale numeric claims ("19 validators" when it\'s now 22) erode credibility.',
+    triggers: [
+      ['says "N validators" but actual count is M', 'Run `docguard fix --write` — this is auto-fixable.'],
+    ],
+    example: 'AGENTS.md says "22 validators" and `docguard guard` shows 22 active validators',
+    standard: 'CDD principle: documented metrics match reality',
+  },
+  crossReference: {
+    title: 'Cross-Reference — internal markdown links resolve',
+    what: 'Scans canonical docs for `[text](./OTHER.md#anchor)` and `#anchor` links. Verifies the target file exists and the anchor matches a heading.',
+    why:  'Broken doc-to-doc links are the most-clicked dead ends in onboarding.',
+    triggers: [
+      ['broken link: target file not found', 'The file path doesn\'t exist. Fix the path or remove the link.'],
+      ['broken anchor', 'Anchor doesn\'t match any heading. Hint: `(did you mean #X?)` is appended for near-misses; if marked `[auto-fixable]`, run `docguard fix --write`.'],
+    ],
+    example: '`[Setup](#prerequisites)` in ENVIRONMENT.md AND `## Prerequisites` heading present',
+    standard: 'GitHub Flavored Markdown anchor rules',
+  },
+  generatedStaleness: {
+    title: 'Generated-Staleness — source=code sections match scanner output',
+    what: 'For each `<!-- docguard:section source=code -->` block, re-runs the memory plan scanner and compares against on-disk content. Also flags status: draft docs unmodified for > 14 days.',
+    why:  'Code-truth sections must reflect what the code actually says. Forgotten drafts rot.',
+    triggers: [
+      ['is stale', 'A code-truth section drifted. Run `docguard sync --write` (or `docguard fix --write` since v0.14-P3 — the validator now emits a regenerate-section fix).'],
+      ['status: draft for', 'A doc has been in draft for too long. Promote to `status: current` or remove. Threshold via `config.draftStalenessDays`.'],
+    ],
+    example: 'All source=code sections match what the scanner would produce right now',
+    standard: 'CDD principle: code-truth sections are machine-owned',
+  },
+  todoTracking: {
+    title: 'TODO-Tracking — TODOs are tracked + skipped tests explained',
+    what: 'Finds TODO/FIXME/HACK comments in source. Each must be referenced in tracking docs (ROADMAP.md, GitHub issues, etc.). Also flags `it.skip()` / `test.skip()` without an adjacent `// REASON:` comment.',
+    why:  'TODOs in code that no one tracks are silent debt.',
+    triggers: [
+      ['Skipped test without explanation', 'Add `// REASON: <why>` immediately above the skip.'],
+      ['Untracked TODO', 'Reference the TODO from ROADMAP.md by file:line, OR add it to a GitHub issue and link the issue ID in the comment.'],
+    ],
+    example: '// REASON: waiting on upstream fix in libfoo v2.5\\ntest.skip("foo", () => {})',
+    standard: 'Pragmatic Programmer (debt visibility)',
+  },
+  specKit: {
+    title: 'Spec-Kit — spec.md/plan.md/tasks.md have required sections',
+    what: 'For projects using Spec Kit, validates each spec/*.md against the spec-kit-template required sections.',
+    why:  'Spec Kit\'s value comes from consistent shape across specs.',
+    triggers: [
+      ['Missing mandatory section', 'Add the section listed in the warning. Reference the template at .specify/templates/'],
+    ],
+    example: 'plan.md has Summary, Technical Context, Constitution Check, Project Structure',
+    standard: 'GitHub Spec Kit',
+  },
+};
+
+/**
+ * Match a warning text fragment against the explainer table. Returns the
+ * matching entry's key + the trigger entry that best matches, or null when
+ * no match is confident enough.
+ */
+function matchWarning(query) {
+  const q = query.toLowerCase();
+
+  // Exact validator-key lookup (e.g. `docguard explain freshness`)
+  if (EXPLAINERS[query]) return { key: query, trigger: null };
+  // Also try kebab-case (e.g. `cross-reference` → `crossReference`)
+  const camelized = query.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+  if (EXPLAINERS[camelized]) return { key: camelized, trigger: null };
+
+  // Search trigger phrases
+  let best = null;
+  let bestScore = 0;
+  for (const [key, e] of Object.entries(EXPLAINERS)) {
+    for (const [phrase, _hint] of e.triggers) {
+      if (q.includes(phrase.toLowerCase())) {
+        const score = phrase.length; // prefer the more-specific phrase
+        if (score > bestScore) {
+          best = { key, trigger: [phrase, _hint] };
+          bestScore = score;
+        }
+      }
+    }
+  }
+  return best;
+}
+
+export function runExplain(projectDir, _config, flags) {
+  const query = (flags.args || []).join(' ').trim();
+  const isJson = flags.format === 'json';
+
+  if (!query) {
+    if (isJson) {
+      console.log(JSON.stringify({ validators: Object.keys(EXPLAINERS) }, null, 2));
+      return;
+    }
+    console.log(`${c.bold}🧭 docguard explain${c.reset} ${c.dim}— usage:${c.reset}`);
+    console.log(`  ${c.cyan}docguard explain <validator-key>${c.reset}    e.g. docguard explain freshness`);
+    console.log(`  ${c.cyan}docguard explain "<warning text>"${c.reset}   e.g. docguard explain "no service-to-test mappings"`);
+    console.log(`\n${c.dim}Known validators:${c.reset}`);
+    for (const [k, e] of Object.entries(EXPLAINERS)) {
+      console.log(`  ${c.cyan}${k.padEnd(22)}${c.reset} ${c.dim}${e.title}${c.reset}`);
+    }
+    return;
+  }
+
+  const match = matchWarning(query);
+  if (!match) {
+    if (isJson) {
+      console.log(JSON.stringify({ query, match: null }, null, 2));
+      return;
+    }
+    console.log(`${c.yellow}No matching validator or warning found for: "${query}"${c.reset}`);
+    console.log(`${c.dim}Try: ${c.cyan}docguard explain${c.dim} (no args) to list all validators.${c.reset}`);
+    process.exit(1);
+  }
+
+  const e = EXPLAINERS[match.key];
+  if (isJson) {
+    console.log(JSON.stringify({ query, match: { key: match.key, ...e, matchedTrigger: match.trigger } }, null, 2));
+    return;
+  }
+
+  console.log(`${c.bold}🧭 ${e.title}${c.reset}`);
+  console.log(`${c.dim}   validator key: ${match.key}${c.reset}\n`);
+
+  console.log(`${c.bold}What it checks:${c.reset}\n  ${e.what}\n`);
+  console.log(`${c.bold}Why:${c.reset}\n  ${e.why}\n`);
+
+  if (match.trigger) {
+    console.log(`${c.bold}Your warning ("${query}") matches:${c.reset}`);
+    console.log(`  ${c.yellow}${match.trigger[0]}${c.reset}`);
+    console.log(`  ${match.trigger[1]}\n`);
+  } else {
+    console.log(`${c.bold}Common warnings:${c.reset}`);
+    for (const [phrase, hint] of e.triggers) {
+      console.log(`  ${c.yellow}${phrase}${c.reset}`);
+      console.log(`    ${c.dim}${hint}${c.reset}`);
+    }
+    console.log('');
+  }
+
+  console.log(`${c.bold}Passing example:${c.reset}\n  ${c.dim}${e.example}${c.reset}\n`);
+  console.log(`${c.bold}Standard:${c.reset} ${c.dim}${e.standard}${c.reset}`);
+}

package/cli/commands/guard.mjs

@@ -11,6 +11,80 @@ import { c, resolveSeverity } from '../shared.mjs';
 import { detectAgentMode, isSpecKitInitialized } from '../ensure-skills.mjs';
 import { checkUpgradeStatus } from './upgrade.mjs';
 import { changedFilesSince, isGitRepo } from '../shared-git.mjs';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { fileURLToPath as fp } from 'node:url';
+import { dirname as dn } from 'node:path';
+
+// v0.17-P1: CLI version for version-pin checks (F8). Reproducibility for CDD —
+// users can pin the docguard version their config was last validated against.
+const _PKG = JSON.parse(readFileSync(resolvePath(dn(fp(import.meta.url)), '..', '..', 'package.json'), 'utf-8'));
+const CLI_VERSION = _PKG.version;
+
+/**
+ * v0.17-P1: parse a semver-ish version string into a comparable tuple.
+ * Tolerates trailing pre-release tags (`0.16.0-rc.1`). Returns null on garbage.
+ */
+function _parseSemver(v) {
+  if (!v || typeof v !== 'string') return null;
+  const m = v.match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/**
+ * v0.17-P1: returns +1 if a > b, 0 if equal, -1 if a < b. Unparseable
+ * input sorts as equal (silent — never blocks a guard run).
+ */
+function _semverCompare(a, b) {
+  const pa = _parseSemver(a);
+  const pb = _parseSemver(b);
+  if (!pa || !pb) return 0;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] > pb[i]) return 1;
+    if (pa[i] < pb[i]) return -1;
+  }
+  return 0;
+}
+
+/**
+ * v0.17-P1: emit a "you're running a newer CLI than the config was pinned
+ * against" nudge. Cheap, file-local check. Returns the nudge text or null.
+ */
+function _checkVersionPin(config) {
+  const pinned = config.docguardVersion;
+  if (!pinned) return null;
+  const cmp = _semverCompare(CLI_VERSION, pinned);
+  if (cmp > 0) {
+    return `Running CLI v${CLI_VERSION} but config pins v${pinned}. ` +
+      `New validators/rules may have appeared. Run \`docguard guard --pin\` to update the pin once you've reviewed any new findings.`;
+  }
+  if (cmp < 0) {
+    return `Running CLI v${CLI_VERSION} but config pins v${pinned} (newer). ` +
+      `Older CLI may be missing checks the config expects. Upgrade with \`npm i -g docguard-cli@latest\`.`;
+  }
+  return null;
+}
+
+/**
+ * v0.17-P1: update the docguardVersion field in .docguard.json after a
+ * successful guard run. Triggered by `docguard guard --pin`. Idempotent.
+ */
+function _updateVersionPin(projectDir) {
+  const cfgPath = resolvePath(projectDir, '.docguard.json');
+  if (!existsSync(cfgPath)) return { written: false, reason: '.docguard.json not found — run `docguard init` first' };
+  let raw, cfg;
+  try { raw = readFileSync(cfgPath, 'utf-8'); cfg = JSON.parse(raw); } catch (e) {
+    return { written: false, reason: `could not parse .docguard.json: ${e.message}` };
+  }
+  if (cfg.docguardVersion === CLI_VERSION) {
+    return { written: false, reason: `already pinned at v${CLI_VERSION}` };
+  }
+  const prev = cfg.docguardVersion || '(unset)';
+  cfg.docguardVersion = CLI_VERSION;
+  writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n', 'utf-8');
+  return { written: true, from: prev, to: CLI_VERSION };
+}
 import { validateStructure, validateDocSections } from '../validators/structure.mjs';
 import { validateDrift } from '../validators/drift.mjs';
 import { validateChangelog } from '../validators/changelog.mjs';
@@ -364,6 +438,15 @@ export function runGuard(projectDir, config, flags) {
       console.log(`\n  ${c.yellow}↑ ${upgradeHint}${c.reset}`);
     }
 
+    // v0.17-P1: version-pin nudge. When .docguard.json carries a
+    // docguardVersion field and the running CLI doesn't match, emit a
+    // one-line note. Keeps CDD reproducibility honest — "same project,
+    // same docs, different score across versions" no longer silent.
+    const pinHint = _checkVersionPin(config);
+    if (pinHint) {
+      console.log(`\n  ${c.yellow}📌 ${pinHint}${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
@@ -402,6 +485,24 @@ export function runGuard(projectDir, config, flags) {
 
   console.log('');
 
+  // v0.17-P1: --pin updates docguardVersion in .docguard.json to the running
+  // CLI version. Only meaningful AFTER a clean (or near-clean) guard run —
+  // pinning to a version that just failed defeats the reproducibility goal.
+  // We allow pinning when status is PASS or WARN; refuse on FAIL.
+  if (flags.pin) {
+    if (data.status === 'FAIL') {
+      console.log(`  ${c.red}✗ Cannot --pin after a FAIL run.${c.reset} Fix the errors first, then retry.`);
+    } else {
+      const r = _updateVersionPin(projectDir);
+      if (r.written) {
+        console.log(`  ${c.green}📌 docguardVersion pinned: ${r.from} → ${r.to}${c.reset}`);
+      } else {
+        console.log(`  ${c.dim}📌 ${r.reason}${c.reset}`);
+      }
+    }
+    console.log('');
+  }
+
   // 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);

package/cli/commands/hooks.mjs

@@ -4,6 +4,56 @@
  */
 
 import { existsSync, writeFileSync, mkdirSync, chmodSync, readFileSync, unlinkSync } from 'node:fs';
+
+// v0.16-P3: managed-block markers. Letting users extend the hook with their
+// own commands (data-file guards, lint checks, etc.) without us clobbering
+// them on re-install. Format:
+//
+//   #!/bin/sh
+//   # ... user's prelude ...
+//
+//   # BEGIN DOCGUARD MANAGED — do not edit between these markers
+//   ... DocGuard's content ...
+//   # END DOCGUARD MANAGED
+//
+//   # ... user's postlude ...
+//
+// On re-install, we splice ONLY the content between the markers, preserving
+// everything else verbatim. Without markers (legacy hooks or third-party
+// pre-existing hooks), behavior falls back to the existing --force flow.
+const BEGIN_MARKER = '# BEGIN DOCGUARD MANAGED — do not edit between these markers';
+const END_MARKER   = '# END DOCGUARD MANAGED';
+
+/**
+ * Wrap a hook body in BEGIN/END markers so future re-installs can splice
+ * just the managed portion. The shebang stays at the top, outside the block.
+ */
+function wrapManaged(body) {
+  // Pull shebang off the front if present so it stays at the top.
+  const lines = body.split('\n');
+  let shebang = '';
+  if (lines[0] && lines[0].startsWith('#!')) {
+    shebang = lines.shift() + '\n';
+  }
+  return `${shebang}${BEGIN_MARKER}\n${lines.join('\n').replace(/\n+$/, '')}\n${END_MARKER}\n`;
+}
+
+/**
+ * Splice DocGuard's managed content into an existing hook file that has
+ * the BEGIN/END markers. Returns the new file content (string) or null
+ * when the markers aren't found (caller falls back to legacy behavior).
+ */
+function spliceManagedBlock(existing, newBody) {
+  const startIdx = existing.indexOf(BEGIN_MARKER);
+  const endIdx   = existing.indexOf(END_MARKER);
+  if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) return null;
+  const before = existing.slice(0, startIdx);
+  const after  = existing.slice(endIdx + END_MARKER.length);
+  // newBody has its own shebang — strip it since we're splicing into the
+  // middle of an existing file (which already has one).
+  const bodyNoShebang = newBody.replace(/^#!.*\n/, '');
+  return `${before}${BEGIN_MARKER}\n${bodyNoShebang.replace(/\n+$/, '')}\n${END_MARKER}${after}`;
+}
 import { resolve } from 'node:path';
 import { c } from '../shared.mjs';
 
@@ -228,26 +278,45 @@ export function runHooks(projectDir, config, flags) {
 
   for (const name of hookTypes) {
     const hookPath = resolve(hooksDir, name);
+    const useAutofix = name === 'pre-commit' && flags.autoFix;
+    const newContent = wrapManaged(useAutofix ? PRE_COMMIT_AUTOFIX : HOOKS[name].content);
+    const desc = useAutofix ? 'Apply mechanical fixes (fix --write) then guard' : HOOKS[name].description;
 
-    if (existsSync(hookPath) && !flags.force) {
-      // Check if it's already a DocGuard hook
+    if (existsSync(hookPath)) {
       const existing = readFileSync(hookPath, 'utf-8');
-      if (existing.includes('DocGuard')) {
-        console.log(`  ${c.dim}⏭️  ${name} (DocGuard hook already installed)${c.reset}`);
+
+      // v0.16-P3: managed-block path — splice just the DocGuard portion,
+      // preserve everything outside it. The user can extend the hook with
+      // their own commands above/below the markers without losing them on
+      // re-install.
+      const spliced = spliceManagedBlock(existing, newContent);
+      if (spliced !== null) {
+        writeFileSync(hookPath, spliced, 'utf-8');
+        chmodSync(hookPath, 0o755);
+        console.log(`  ${c.green}↻ ${name}${c.reset}: updated DocGuard managed block (preserved user content around it)`);
+        installed++;
+        continue;
+      }
+
+      // No markers found. Two sub-cases:
+      //   (a) Legacy DocGuard hook (pre-v0.16, no markers, contains "DocGuard")
+      //       → upgrade in place when --force is set
+      //   (b) Third-party hook the user wrote themselves
+      //       → refuse without --force; warn about clobber risk
+      if (!flags.force) {
+        if (existing.includes('DocGuard')) {
+          console.log(`  ${c.yellow}⚠️  ${name}: legacy DocGuard hook (pre-v0.16) without managed markers. Re-run with --force to upgrade it to the managed-block format.${c.reset}`);
+        } else {
+          console.log(`  ${c.yellow}⚠️  ${name}: an existing hook is present and has no DocGuard markers. Re-run with --force to overwrite (your hook will be replaced — back it up first!).${c.reset}`);
+        }
         skipped++;
         continue;
       }
-      console.log(`  ${c.yellow}⚠️  ${name}: existing hook found (use --force to overwrite)${c.reset}`);
-      skipped++;
-      continue;
+      // --force path: write fresh managed-block version
     }
 
-    // pre-commit supports an auto-fix variant (applies mechanical fixes first).
-    const useAutofix = name === 'pre-commit' && flags.autoFix;
-    const content = useAutofix ? PRE_COMMIT_AUTOFIX : HOOKS[name].content;
-    writeFileSync(hookPath, content, 'utf-8');
-    chmodSync(hookPath, 0o755); // Make executable
-    const desc = useAutofix ? 'Apply mechanical fixes (fix --write) then guard' : HOOKS[name].description;
+    writeFileSync(hookPath, newContent, 'utf-8');
+    chmodSync(hookPath, 0o755);
     console.log(`  ${c.green}✅ ${name}${c.reset}: ${desc}`);
     installed++;
   }

package/cli/commands/init.mjs

@@ -253,10 +253,14 @@ poetry.lock
 
   // ── Spec-Kit Integration (Extension-First) ────────────────────────────
   // Delegate LLM/IDE detection and spec-kit skill install to `specify init`
+  // v0.16-P8: --no-spec-kit lets users skip the .specify/.agent/commands
+  // scaffolding (minimalist library projects, CI containers, etc.).
   const specKitAvailable = isSpecKitAvailable();
   const specKitInitialized = isSpecKitInitialized(projectDir);
 
-  if (specKitAvailable && !specKitInitialized) {
+  if (flags.noSpecKit) {
+    console.log(`\n  ${c.dim}⏭️  Spec Kit init skipped (--no-spec-kit).${c.reset}`);
+  } else if (specKitAvailable && !specKitInitialized) {
     console.log(`\n  ${c.bold}🌱 Spec Kit Integration${c.reset}`);
 
     // Detect which AI agent is in use (matches spec-kit's --ai flag)

package/cli/commands/memory.mjs

@@ -0,0 +1,143 @@
+/**
+ * Memory Command — v0.17-P2.
+ *
+ * `docguard memory` shows the documentation-memory accuracy headline that
+ * already appears in `docguard score`, but adds a `--diff` mode that drills
+ * into WHICH claims don't match code. Reported by a Python user:
+ *
+ *   "Memory accuracy 83% with no drill-down. The headline number was the
+ *    only signal — there's no `docguard memory --diff` to show which doc
+ *    claim doesn't match the code."
+ *
+ * The numbers are the same ones `score` shows; this command's value is
+ * making them inspectable per-domain.
+ *
+ * Domains drilled into:
+ *   - Endpoints: API-REFERENCE.md vs scanned routes
+ *   - Entities:  DATA-MODEL.md vs scanned schemas
+ *   - Env vars:  ENVIRONMENT.md vs process.env / import.meta.env usage
+ *   - Tech:      ARCHITECTURE.md vs detected stack
+ *
+ * Zero NPM dependencies. Pure orchestration of existing diff helpers.
+ */
+
+import { c } from '../shared.mjs';
+import { diffRoutes, diffEntities, diffEnvVars, diffTechStack } from './diff.mjs';
+
+/**
+ * Compute an accuracy score for a single domain. Returns:
+ *   { matched, total, accuracy: 0..100, onlyInDocs, onlyInCode }
+ * `null` when the domain isn't applicable (e.g. no API-REFERENCE.md).
+ */
+function _domainAccuracy(d) {
+  if (!d) return null;
+  const matched = (d.matched || []).length;
+  const onlyDocs = (d.onlyInDocs || []).length;
+  const onlyCode = (d.onlyInCode || []).length;
+  const total = matched + onlyDocs + onlyCode;
+  if (total === 0) return null;
+  return {
+    title: d.title,
+    icon: d.icon,
+    matched,
+    onlyInDocs: d.onlyInDocs || [],
+    onlyInCode: d.onlyInCode || [],
+    total,
+    accuracy: Math.round((matched / total) * 100),
+  };
+}
+
+export function runMemory(projectDir, config, flags) {
+  const isJson = flags.format === 'json';
+  const wantsDiff = flags.diff || (flags.args || []).includes('--diff');
+
+  const domains = {
+    endpoints: _domainAccuracy(diffRoutes(projectDir, config)),
+    entities:  _domainAccuracy(diffEntities(projectDir, config)),
+    envVars:   _domainAccuracy(diffEnvVars(projectDir, config)),
+    techStack: _domainAccuracy(diffTechStack(projectDir, config)),
+  };
+
+  // Roll up across applicable domains.
+  let totalMatched = 0;
+  let totalChecks = 0;
+  for (const d of Object.values(domains)) {
+    if (!d) continue;
+    totalMatched += d.matched;
+    totalChecks += d.total;
+  }
+  const overallAccuracy = totalChecks > 0
+    ? Math.round((totalMatched / totalChecks) * 100)
+    : 0;
+
+  if (isJson) {
+    console.log(JSON.stringify({
+      project: config.projectName,
+      accuracy: overallAccuracy,
+      domains,
+      totals: { matched: totalMatched, checks: totalChecks },
+      timestamp: new Date().toISOString(),
+    }, null, 2));
+    return;
+  }
+
+  // ── Text output ──
+  console.log(`${c.bold}🧠 DocGuard Memory${c.reset} ${c.dim}— ${config.projectName}${c.reset}\n`);
+
+  const accColor = overallAccuracy >= 90 ? c.green : overallAccuracy >= 70 ? c.yellow : c.red;
+  console.log(`  ${c.bold}Accuracy:${c.reset} ${accColor}${overallAccuracy}%${c.reset} ${c.dim}(${totalMatched}/${totalChecks} doc claims match code)${c.reset}\n`);
+
+  if (totalChecks === 0) {
+    console.log(`  ${c.dim}No applicable domains found — add canonical docs (API-REFERENCE.md, DATA-MODEL.md, ENVIRONMENT.md) and rerun.${c.reset}`);
+    return;
+  }
+
+  // Per-domain breakdown
+  console.log(`  ${c.bold}By domain:${c.reset}`);
+  for (const [name, d] of Object.entries(domains)) {
+    if (!d) continue;
+    const domainColor = d.accuracy >= 90 ? c.green : d.accuracy >= 70 ? c.yellow : c.red;
+    console.log(`     ${d.icon} ${c.cyan}${d.title.padEnd(22)}${c.reset} ${domainColor}${String(d.accuracy).padStart(3)}%${c.reset}  ${c.dim}${d.matched}/${d.total} matched${c.reset}`);
+  }
+
+  if (!wantsDiff) {
+    if (overallAccuracy < 100) {
+      console.log(`\n  ${c.dim}Run ${c.cyan}docguard memory --diff${c.dim} to see WHICH claims don't match.${c.reset}`);
+    }
+    return;
+  }
+
+  // --diff mode: detail per domain
+  console.log(`\n  ${c.bold}── Drill-down ──${c.reset}`);
+  let anyShown = false;
+  for (const [_, d] of Object.entries(domains)) {
+    if (!d) continue;
+    if (d.onlyInDocs.length === 0 && d.onlyInCode.length === 0) continue;
+    anyShown = true;
+    console.log(`\n  ${d.icon} ${c.bold}${d.title}${c.reset} ${c.dim}(${d.accuracy}%)${c.reset}`);
+
+    if (d.onlyInDocs.length > 0) {
+      console.log(`     ${c.red}✗ In docs but missing from code${c.reset} ${c.dim}(${d.onlyInDocs.length}):${c.reset}`);
+      for (const item of d.onlyInDocs.slice(0, 10)) {
+        console.log(`         ${c.red}-${c.reset} ${item}`);
+      }
+      if (d.onlyInDocs.length > 10) console.log(`         ${c.dim}... ${d.onlyInDocs.length - 10} more${c.reset}`);
+    }
+
+    if (d.onlyInCode.length > 0) {
+      console.log(`     ${c.yellow}⚠ In code but missing from docs${c.reset} ${c.dim}(${d.onlyInCode.length}):${c.reset}`);
+      for (const item of d.onlyInCode.slice(0, 10)) {
+        console.log(`         ${c.yellow}+${c.reset} ${item}`);
+      }
+      if (d.onlyInCode.length > 10) console.log(`         ${c.dim}... ${d.onlyInCode.length - 10} more${c.reset}`);
+    }
+  }
+
+  if (!anyShown) {
+    console.log(`\n  ${c.green}✅ All claims match — nothing to drill into.${c.reset}`);
+  } else {
+    console.log(`\n  ${c.dim}Fix options:${c.reset}`);
+    console.log(`    ${c.dim}• Removed-from-code items: ${c.cyan}docguard fix --write${c.dim} (deletes documented-but-absent endpoints)${c.reset}`);
+    console.log(`    ${c.dim}• Missing-from-docs items: ${c.cyan}/docguard.fix --doc <name>${c.dim} (AI fills in the gap)${c.reset}`);
+  }
+}

package/cli/commands/score.mjs

@@ -21,8 +21,15 @@ const WEIGHTS = {
 };
 
 export function runScore(projectDir, config, flags) {
-  console.log(`${c.bold}📊 DocGuard Score — ${config.projectName}${c.reset}`);
-  console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
+  // v0.16-P1: suppress banner in JSON mode so stdout stays parseable.
+  // Was already fixed for guard/diagnose in v0.12; score/trace/diff missed
+  // the pattern. Reported on a Python project where `score --format json`
+  // mixed ANSI escapes with JSON.
+  const isJson = flags.format === 'json';
+  if (!isJson) {
+    console.log(`${c.bold}📊 DocGuard Score — ${config.projectName}${c.reset}`);
+    console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
+  }
 
   const { scores, totalScore, grade, details } = calcAllScores(projectDir, config);
 

package/cli/commands/trace.mjs

@@ -21,65 +21,107 @@ const CODE_EXTENSIONS = new Set([
   '.py', '.java', '.go', '.rs', '.rb', '.php', '.cs',
 ]);
 
+// v0.16-P2: language-aware patterns. The original JS/TS-only sets created
+// 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`).
+// Each `glob` is now a single regex that ALSO matches the equivalent
+// patterns in other ecosystems we care about.
 const TEST_PATTERNS = [
-  /\.test\.[jt]sx?$/,
-  /\.spec\.[jt]sx?$/,
-  /test_.*\.py$/,
+  // JS/TS
+  /\.test\.[jt]sx?$/, /\.spec\.[jt]sx?$/, /\.test\.(mjs|cjs)$/,
+  // Python — pytest conventions
+  /(^|\/)test_[^/]+\.py$/, /[^/]+_test\.py$/, /(^|\/)tests?\/[^/]+\.py$/,
+  // Go
   /_test\.go$/,
-  /Test\.java$/,
+  // Java/Kotlin — JUnit/TestNG conventions
+  /(?:Test|Tests|Spec|IT)\.(?:java|kt)$/,
+  // Rust — tests live in tests/ or as #[cfg(test)] modules; pattern below covers integration tests
+  /(^|\/)tests\/[^/]+\.rs$/,
+  // Ruby/RSpec
+  /_spec\.rb$/, /_test\.rb$/,
+  // PHP/PHPUnit
+  /Test\.php$/, /(^|\/)tests?\/[^/]+\.php$/,
 ];
 
 /**
  * Mapping of canonical documents to the code/config artifacts they trace to.
  * Each entry defines what source patterns prove coverage of that canonical doc.
+ *
+ * v0.16-P2: every glob is now multi-language. JS/TS patterns are preserved
+ * (the most common case); Python/Rust/Go/Java/Ruby/PHP equivalents are
+ * appended so non-JS projects don't false-negative.
  */
 const TRACE_MAP = {
   'ARCHITECTURE.md': {
     standard: 'arc42 / C4 Model',
     sourcePatterns: [
-      { label: 'Entry points', glob: /^(index|main|app|server)\.[jt]sx?$/ },
-      { label: 'Config files', glob: /^(package\.json|tsconfig.*|next\.config|vite\.config)/ },
-      { label: 'Route handlers', glob: /(routes?|api|pages|app)\// },
+      // Entry points: JS (index/main/app/server.[jt]sx?), Python (__main__.py, main.py, app.py, cli.py),
+      // Go (main.go, cmd/), Rust (main.rs, lib.rs), Java (Application.java, Main.java)
+      { label: 'Entry points', glob: /(?:^|\/)(?:index|main|app|server|cli|__main__|Application|Main)\.(?:[jt]sx?|mjs|cjs|py|go|rs|java|kt|rb)$|(?:^|\/)cmd\// },
+      // Config files: JS (package.json/tsconfig/next.config/vite.config), Python (pyproject.toml/setup.py/setup.cfg),
+      // Rust (Cargo.toml), Go (go.mod), Java/Kotlin (pom.xml/build.gradle), Ruby (Gemfile), PHP (composer.json)
+      { label: 'Config files', glob: /(?:^|\/)(?:package\.json|tsconfig|next\.config|vite\.config|pyproject\.toml|setup\.(?:py|cfg)|Cargo\.toml|go\.mod|pom\.xml|build\.gradle|Gemfile|composer\.json)/ },
+      // Route handlers + module dirs
+      { label: 'Route handlers / modules', glob: /(?:^|\/)(?:routes?|api|pages|app|controllers?|handlers?|views?|services?)\// },
     ],
   },
   'DATA-MODEL.md': {
     standard: 'C4 Component / ER (Chen)',
     sourcePatterns: [
-      { label: 'Schema definitions', glob: /(schema|model|entity|migration|prisma)/i },
-      { label: 'Type definitions', glob: /types?\.[jt]sx?$/ },
-      { label: 'Database configs', glob: /(drizzle|knex|sequelize|typeorm)/i },
+      // Schema/model files: JS (schema/model/entity/migration/prisma), Python (models.py/schema.py/Pydantic/SQLAlchemy),
+      // Go (models/), Rust (struct definitions in models/), Java (entities/)
+      { label: 'Schema definitions', glob: /(?:schema|model|entity|migration|prisma)/i },
+      // Type definitions: JS types.ts, Python types.py, Rust types.rs
+      { label: 'Type definitions', glob: /(?:^|\/)types?\.(?:[jt]sx?|mjs|py|rs|go|java|kt)$/ },
+      // ORM/database libs (any language)
+      { label: 'Database configs', glob: /(?:drizzle|knex|sequelize|typeorm|sqlalchemy|alembic|django|diesel|sqlx|gorm|hibernate|active.?record)/i },
     ],
   },
   'TEST-SPEC.md': {
     standard: 'ISO/IEC/IEEE 29119-3',
     sourcePatterns: [
-      { label: 'Test files', glob: /\.(test|spec)\.(mjs|cjs|[jt]sx?)$/ },
-      { label: 'Test config', glob: /(jest|vitest|playwright|cypress)\.config/ },
-      { label: 'E2E tests', glob: /(e2e|integration)\// },
+      // Test files in any ecosystem (mirrors TEST_PATTERNS above)
+      { label: 'Test files', glob: /\.(?:test|spec)\.(?:mjs|cjs|[jt]sx?)$|(?:^|\/)test_[^/]+\.py$|[^/]+_test\.py$|_test\.go$|(?:Test|Spec|IT)\.(?:java|kt)$|(?:^|\/)tests?\/[^/]+\.(?:rs|py|rb|php)$|_(?:spec|test)\.rb$|Test\.php$/ },
+      // Test runner configs: JS (jest/vitest/playwright/cypress), Python (pytest.ini/tox.ini), Rust (Cargo.toml has [[test]]),
+      // Java (pom.xml/build.gradle), Go (no config file typically)
+      { label: 'Test config', glob: /(?:jest|vitest|playwright|cypress|pytest|tox|phpunit)\.config|(?:^|\/)pytest\.ini$|(?:^|\/)tox\.ini$|(?:^|\/)phpunit\.xml$/ },
+      { label: 'E2E / integration tests', glob: /(?:^|\/)(?:e2e|integration|tests?\/integration)\// },
     ],
   },
   'SECURITY.md': {
     standard: 'OWASP ASVS v4.0',
     sourcePatterns: [
-      { label: 'Auth modules', glob: /(auth|login|session|jwt|oauth|middleware)/i },
-      { label: 'Secret configs', glob: /\.(env|env\.example|env\.local)$/ },
-      { label: 'Gitignore', glob: /^\.gitignore$/ },
+      // Auth modules — semantic, language-agnostic
+      { label: 'Auth modules', glob: /(?:auth|login|session|jwt|oauth|middleware|guard|csrf|cors|permissions?|policy)/i },
+      // Secret configs — .env family + secrets.* / keyring patterns
+      { label: 'Secret configs', glob: /\.env(?:\.|$)|(?:^|\/)secrets?\.(?:py|js|ts|yaml|yml|json)$|keyring/i },
+      // Gitignore + ignore files
+      { label: 'Ignore files', glob: /^\.(?:git|docker|npm)ignore$/ },
     ],
   },
   'ENVIRONMENT.md': {
     standard: '12-Factor App',
     sourcePatterns: [
-      { label: 'Env files', glob: /\.env/ },
-      { label: 'Docker configs', glob: /(Dockerfile|docker-compose|\.dockerignore)/ },
-      { label: 'CI/CD configs', glob: /\.(github|gitlab-ci|circleci)/ },
+      // .env family across all ecosystems
+      { label: 'Env files', glob: /\.env(?:\.|$)|(?:^|\/)\.envrc$/ },
+      // Containerization
+      { label: 'Container configs', glob: /(?:^|\/)(?:Dockerfile|docker-compose|\.dockerignore|Containerfile)/ },
+      // Python venv / requirements / lock files
+      { label: 'Python env', glob: /(?:^|\/)(?:requirements[^/]*\.txt|Pipfile|poetry\.lock|uv\.lock|pyproject\.toml)$/ },
+      // CI/CD configs
+      { label: 'CI/CD configs', glob: /(?:^|\/)\.(?:github|gitlab-ci|circleci|drone|gitea)/ },
     ],
   },
   'API-REFERENCE.md': {
     standard: 'OpenAPI 3.1',
     sourcePatterns: [
-      { label: 'Route handlers', glob: /(routes?|controllers?|handlers?)\// },
-      { label: 'OpenAPI spec', glob: /(openapi|swagger)\.(json|ya?ml)/ },
-      { label: 'API middleware', glob: /middleware\// },
+      // Route handlers + Python views/urls + Java/Spring controllers
+      { label: 'Route handlers', glob: /(?:^|\/)(?:routes?|controllers?|handlers?|views?|urls?\.py)/ },
+      // OpenAPI / API specs
+      { label: 'API spec', glob: /(?:openapi|swagger|asyncapi)\.(?:json|ya?ml)/ },
+      // Middleware / decorators
+      { label: 'API middleware', glob: /(?:^|\/)middleware\/|decorators?\.py$/ },
     ],
   },
 };
@@ -190,9 +232,14 @@ export function runTrace(projectDir, config, flags) {
     return runTraceReverse(projectDir, config, flags);
   }
 
-  console.log(`${c.bold}🔗 DocGuard Trace — ${config.projectName}${c.reset}`);
-  console.log(`${c.dim}   Directory: ${projectDir}${c.reset}`);
-  console.log(`${c.dim}   Generating requirements traceability matrix...${c.reset}\n`);
+  // v0.16-P1: same headless-mode pattern as guard/score. Reported by Python
+  // user — trace --format json was leaking ANSI escapes before the body.
+  const isJson = flags.format === 'json';
+  if (!isJson) {
+    console.log(`${c.bold}🔗 DocGuard Trace — ${config.projectName}${c.reset}`);
+    console.log(`${c.dim}   Directory: ${projectDir}${c.reset}`);
+    console.log(`${c.dim}   Generating requirements traceability matrix...${c.reset}\n`);
+  }
 
   // ── 1. Build set of required doc basenames from config ──
   const requiredDocs = new Set(

package/cli/docguard.mjs

@@ -42,6 +42,8 @@ import { runLlms } from './commands/llms.mjs';
 import { runSetup } from './commands/setup.mjs';
 import { runUpgrade } from './commands/upgrade.mjs';
 import { runImpact } from './commands/impact.mjs';
+import { runExplain } from './commands/explain.mjs';
+import { runMemory } from './commands/memory.mjs';
 import { ensureSkills } from './ensure-skills.mjs';
 
 // ── Shared constants (imported to break circular dependencies) ──────────
@@ -120,7 +122,10 @@ export function loadConfig(projectDir) {
         ? deepMerge(defaults, profilePreset)
         : defaults;
 
-      const merged = deepMerge(withProfile, userConfig);
+      // v0.17-P4: normalize validator/severity keys before merging so the
+      // user can write either kebab-case (`test-spec`) or camelCase (`testSpec`)
+      // and the internal lookups (always camelCase) still hit.
+      const merged = deepMerge(withProfile, normalizeConfig(userConfig));
       merged.profile = profileName;
 
       // Auto-detect project type if not set
@@ -209,6 +214,46 @@ function getProjectTypeDefaults(type) {
   return defaults[type] || defaults.unknown;
 }
 
+/**
+ * v0.17-P4: normalize validator-key naming so users can write either
+ * `validators: { "test-spec": true }` (kebab-case, matches CLI display)
+ * or `validators: { testSpec: true }` (camelCase, matches JSON internals)
+ * in `.docguard.json`. We normalize the WHOLE config tree's known validator
+ * keys to camelCase before merging. Same treatment applied to `severity`.
+ *
+ * Non-validator keys are left alone. Unknown keys (forward-compat) are
+ * normalized blindly: kebab-case→camelCase always.
+ */
+const _KNOWN_VALIDATORS = [
+  'structure', 'docsSync', 'drift', 'changelog', 'testSpec', 'environment',
+  'security', 'architecture', 'freshness', 'traceability', 'docsDiff',
+  'apiSurface', 'metadataSync', 'docsCoverage', 'docQuality', 'todoTracking',
+  'schemaSync', 'specKit', 'crossReference', 'generatedStaleness',
+  'metricsConsistency',
+];
+
+function _kebabToCamel(k) {
+  return k.replace(/-([a-z])/g, (_, ch) => ch.toUpperCase());
+}
+
+function _normalizeValidatorKeys(map) {
+  if (!map || typeof map !== 'object' || Array.isArray(map)) return map;
+  const out = {};
+  for (const [k, v] of Object.entries(map)) {
+    const normalized = k.includes('-') ? _kebabToCamel(k) : k;
+    out[normalized] = v;
+  }
+  return out;
+}
+
+function normalizeConfig(cfg) {
+  if (!cfg || typeof cfg !== 'object') return cfg;
+  const out = { ...cfg };
+  if (out.validators) out.validators = _normalizeValidatorKeys(out.validators);
+  if (out.severity)   out.severity   = _normalizeValidatorKeys(out.severity);
+  return out;
+}
+
 function deepMerge(target, source) {
   const result = { ...target };
   for (const key of Object.keys(source)) {
@@ -395,6 +440,25 @@ async function main() {
       // avoid collision with `docguard init --profile <name>`. `--show-timings`
       // is the long form for users who prefer explicit verbs.
       flags.timings = true;
+    } else if (args[i] === '--quiet' || args[i] === '-q') {
+      // v0.16-P5: suppress the banner + ensureSkills decorative line.
+      // Useful inside git hooks (every commit prints the banner otherwise)
+      // and any CI/script that pipes docguard's output.
+      flags.quiet = true;
+    } else if (args[i] === '--no-spec-kit') {
+      // v0.16-P8: opt-out of automatic Spec Kit init during `docguard init`.
+      // Default stays on (discoverability), but lets minimalist library
+      // projects skip the .specify/.agent/commands scaffolding.
+      flags.noSpecKit = 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.
+      // Different from `--pr` (used by upgrade) — this is for guard.
+      flags.pin = true;
+    } else if (args[i] === '--diff') {
+      // 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].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).
@@ -442,10 +506,12 @@ async function main() {
   // ensureSkills' install message would corrupt the output for any
   // programmatic consumer (CI, dashboards, the Score-on-PR Action recipe).
   // Headless flags (`--write`, `--check-only`, `--auto`) also suppress chrome.
+  // v0.16-P5: --quiet (-q) joins the headless club for users who want
+  // banner-free output without committing to a specific machine format.
   const jsonMode = flags.format === 'json';
-  const headless = jsonMode || flags.write || flags.checkOnly || flags.changedOnly;
+  const headless = jsonMode || flags.write || flags.checkOnly || flags.changedOnly || flags.quiet;
 
-  if (!jsonMode) printBanner();
+  if (!headless) printBanner();
 
   const config = loadConfig(projectDir);
 
@@ -527,6 +593,13 @@ async function main() {
     case 'impact':
       runImpact(projectDir, config, flags);
       break;
+    case 'explain':
+    case 'help-warning':
+      runExplain(projectDir, config, flags);
+      break;
+    case 'memory':
+      runMemory(projectDir, config, flags);
+      break;
     default:
       console.error(`${c.red}Unknown command: ${command}${c.reset}`);
       console.log(`Run ${c.cyan}docguard --help${c.reset} for usage.`);

package/cli/validators/environment.mjs

@@ -45,9 +45,21 @@ export function validateEnvironment(projectDir, config) {
     // tokens like `VITE_` (the convention prefix) from being treated as a real
     // variable name.
     const varRe = /`([A-Z][A-Z0-9_]*[A-Z0-9])`/g;
+    // v0.16-P4: skip backticked SYSTEM env vars (PATH, HOME, USER, etc.).
+    // They appear in ENVIRONMENT.md prose ("the venv `PATH`") but aren't
+    // user-set application vars. Mirrors the same skip in diff.mjs.
+    const SYSTEM = new Set([
+      'PATH','HOME','USER','USERNAME','SHELL','PWD','OLDPWD','TMPDIR','TEMP','TMP',
+      'LANG','LC_ALL','LC_CTYPE','LC_MESSAGES','TZ',
+      'EDITOR','VISUAL','PAGER','TERM','COLORTERM',
+      'DISPLAY','SSH_AUTH_SOCK','SSH_CONNECTION','SSH_TTY',
+      'XDG_CONFIG_HOME','XDG_DATA_HOME','XDG_CACHE_HOME','XDG_RUNTIME_DIR',
+      'CI','GITHUB_TOKEN','GITHUB_ACTIONS','GITHUB_REF','GITHUB_SHA','NODE_ENV',
+    ]);
     let m;
     while ((m = varRe.exec(content)) !== null) {
       if (m[1].length < 3) continue; // 'OK' / 'ID' etc. are too short to be env var refs
+      if (SYSTEM.has(m[1])) continue; // v0.16-P4: prose mentions of system vars are not docs
       documented.add(m[1]);
     }
     for (const envFile of ['.env.example', '.env.template']) {

package/cli/validators/structure.mjs

@@ -89,14 +89,36 @@ export function validateDocSections(projectDir, config) {
       // Match an actual heading at line start (any level), not a substring that
       // could appear in a table-of-contents link or a code block.
       const headingText = section.replace(/^#+\s*/, '');
-      const headingRe = new RegExp(
-        '^#{2,6}\\s+' + headingText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\b',
-        'm'
+      const escapedHeading = headingText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const headingRe = new RegExp('^#{2,6}\\s+' + escapedHeading + '\\b', 'm');
+      // v0.16-P7: N/A marker. A project can declare a required section as
+      // "not applicable" via an HTML comment instead of writing boilerplate
+      // "Absent by design" prose. Format:
+      //   <!-- docguard:section authentication n/a — JWT not used; we're a CLI -->
+      // The section name in the marker is matched case-insensitively against
+      // the heading slug (lowercase, hyphenated). Requires a reason after `—`
+      // or `--` so it's not a silent opt-out.
+      const slug = headingText.toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, '')
+        .replace(/\s+/g, '-');
+      // Reason must start with an actual letter or digit (not `>` from `-->`
+      // and not whitespace). This makes sure `<!-- ... n/a -->` (no reason)
+      // is rejected, while `<!-- ... n/a — CLI tool -->` is accepted.
+      const naRe = new RegExp(
+        '<!--\\s*docguard:section\\s+' + slug.replace(/-/g, '[-_]') + '\\s+n/a\\s*[—-]+\\s*[A-Za-z0-9]',
+        'i'
       );
       if (headingRe.test(content)) {
         results.passed++;
+      } else if (naRe.test(content)) {
+        // v0.16-P7: explicit N/A — counts as passed (the project has owned
+        // the absence) and doesn't pollute the warnings list.
+        results.passed++;
       } else {
-        results.warnings.push(`${file}: missing section "${section}"`);
+        results.warnings.push(
+          `${file}: missing section "${section}". ` +
+          `If genuinely not applicable, add: <!-- docguard:section ${slug} n/a — your reason -->`
+        );
       }
     }
   }

package/commands/docguard.guard.md

@@ -1,5 +1,5 @@
 ---
-description: Run DocGuard guard validation — check project documentation against CDD standards with 22 validators
+description: Run DocGuard guard validation — check project documentation against CDD standards with all validators
 handoffs:
   - label: Fix All Issues
     agent: docguard.fix
@@ -23,7 +23,7 @@ Run the DocGuard CLI to validate all documentation against Canonical-Driven Deve
 npx docguard-cli guard
 ```
 
-2. **Parse the output**. Each of the 22 validators reports ✅ (pass), ⚠️ (warning), ❌ (fail), or ➖ (N/A — nothing to validate). **A ➖ N/A is NOT a pass**: it means the validator found nothing to check (e.g. no API-REFERENCE.md, no DB schema, no layer boundaries declared). Don't read N/A as "healthy" — read it as "not assessed".
+2. **Parse the output**. Each of the validators reports ✅ (pass), ⚠️ (warning), ❌ (fail), or ➖ (N/A — nothing to validate). **A ➖ N/A is NOT a pass**: it means the validator found nothing to check (e.g. no API-REFERENCE.md, no DB schema, no layer boundaries declared). Don't read N/A as "healthy" — read it as "not assessed".
 
    | Validator | What It Checks |
    |-----------|---------------|

package/extensions/spec-kit-docguard/commands/guard.md

@@ -14,7 +14,7 @@ handoffs:
 
 # DocGuard Guard
 
-Validate your project against its canonical documentation. Runs 160+ automated checks across 22 validators.
+Validate your project against its canonical documentation. Runs 160+ automated checks across validators.
 
 ## User Input
 

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

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.15.3"
+  version: "0.17.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"
@@ -58,7 +58,7 @@ provides:
   workflows:
     - name: "docguard-guard"
       file: "templates/github-workflows/docguard-guard.yml"
-      description: "Mandatory CI gate — runs all 20 validators on PR + main push"
+      description: "Mandatory CI gate — runs all validators on PR + main push"
     - name: "docguard-autofix"
       file: "templates/github-workflows/docguard-autofix.yml"
       description: "PR-time auto-fix — applies mechanical doc fixes + comments summary"

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.15.3
+  version: 0.17.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.15.3 -->
+<!-- docguard:version: 0.17.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.15.3
+  version: 0.17.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.15.3 -->
+<!-- docguard:version: 0.17.0 -->
 
 # DocGuard Guard Skill
 
@@ -139,7 +139,7 @@ For each finding, provide a **specific, actionable fix** — not "fix the issue"
 
 Based on the triage results:
 
-- **If all PASS**: "All 22 validators passed. Project is CDD-compliant. Ready to commit."
+- **If all PASS**: "All validators passed. Project is CDD-compliant. Ready to commit."
 - **If only MEDIUM/LOW warnings**: "Non-blocking warnings found. Safe to commit, but consider running `/docguard.fix` for automated remediation."
 - **If HIGH or CRITICAL failures**: "Blocking issues found. Fix these before committing. Suggest running `/docguard.fix --doc [most impactful doc]` next."
 

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.15.3
+  version: 0.17.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.15.3 -->
+<!-- docguard:version: 0.17.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.15.3
+  version: 0.17.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.15.3 -->
+<!-- docguard:version: 0.17.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.15.3
+  version: 0.17.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

package/extensions/spec-kit-docguard/templates/github-workflows/docguard-guard.yml

@@ -1,4 +1,4 @@
-# DocGuard Guard — runs all 20 validators on every PR and main push.
+# DocGuard Guard — runs all validators on every PR and main push.
 #
 # This is the canonical CI gate. It does NOT modify your repo — it only
 # reports. Pair with `docguard-autofix.yml` if you want mechanical fixes

package/package.json

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

package/templates/commands/docguard.guard.md

@@ -1,5 +1,5 @@
 ---
-description: Run DocGuard guard validation — check all 22 validators and fix any issues
+description: Run DocGuard guard validation — check all validators and fix any issues
 handoffs:
   - label: Fix Issues
     agent: docguard.fix
@@ -19,7 +19,7 @@ You are an AI agent enforcing Canonical-Driven Development (CDD) compliance usin
 npx docguard-cli guard
 ```
 
-Read the output. It shows pass (✅), warn (⚠️), or fail (❌) for each of the 22 validators:
+Read the output. It shows pass (✅), warn (⚠️), or fail (❌) for each of the validators:
 
 | Priority | Validators |
 |----------|-----------|