docguard-cli 0.15.3 → 0.16.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 = [];
 
@@ -196,6 +200,25 @@ function diffEntities(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
+]);
+
 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]);
   }
 

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/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/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,7 @@ 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 { ensureSkills } from './ensure-skills.mjs';
 
 // ── Shared constants (imported to break circular dependencies) ──────────
@@ -395,6 +396,16 @@ 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].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 +453,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 +540,10 @@ async function main() {
     case 'impact':
       runImpact(projectDir, config, flags);
       break;
+    case 'explain':
+    case 'help-warning':
+      runExplain(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/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.16.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"

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.16.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.15.3 -->
+<!-- docguard:version: 0.16.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.16.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.15.3 -->
+<!-- docguard:version: 0.16.0 -->
 
 # DocGuard Guard Skill
 

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

@@ -6,10 +6,10 @@ description: Cross-document consistency analysis and quality assessment. Perform
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.15.3
+  version: 0.16.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.15.3 -->
+<!-- docguard:version: 0.16.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.16.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.15.3 -->
+<!-- docguard:version: 0.16.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.16.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

package/package.json

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