docguard-cli 0.16.0 → 0.17.1

package/cli/commands/diff.mjs

@@ -101,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');
@@ -133,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;
 
@@ -200,26 +200,34 @@ 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".
+// v0.16-P4 (revised in v0.17.1): conservative denylist of system env vars
+// that appear in prose ("the venv `PATH`") but are never user-set app env
+// vars. v0.17.1-B7: trimmed to TRULY-system-only after wu feedback —
+// NODE_ENV / CI / GITHUB_* are legitimately app env vars when read via
+// process.env. Including them caused diff to falsely flag `NODE_ENV` as
+// "in code but not docs" even when ENVIRONMENT.md documented it.
 //
-// Conservative list — only the names that are unambiguously OS/shell vars.
-// Application names like `DATABASE_URL`, `API_KEY` etc. still count.
+// Rule of thumb for inclusion: would a sane Node/Python/Go app ever
+// `process.env.X` this name and treat it as app config? If yes → NOT a
+// system var. PATH/HOME/SHELL/TERM never satisfy that bar.
 const SYSTEM_ENV_VARS = new Set([
-  'PATH', 'HOME', 'USER', 'USERNAME', 'SHELL', 'PWD', 'OLDPWD', 'TMPDIR', 'TEMP', 'TMP',
+  // POSIX shell / OS
+  'PATH', 'HOME', 'USER', 'USERNAME', 'SHELL', 'PWD', 'OLDPWD',
+  'TMPDIR', 'TEMP', 'TMP',
+  // Locale
   'LANG', 'LC_ALL', 'LC_CTYPE', 'LC_MESSAGES', 'TZ',
+  // Terminal / interactive
   'EDITOR', 'VISUAL', 'PAGER', 'TERM', 'COLORTERM',
+  // SSH / Display
   'DISPLAY', 'SSH_AUTH_SOCK', 'SSH_CONNECTION', 'SSH_TTY',
+  // XDG base directory spec
   '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
+  // NOTE: NODE_ENV / CI / GITHUB_* used to be here. Removed in v0.17.1
+  // because apps DO read them as app config (e.g. NODE_ENV=production
+  // gates branching in nearly every Node.js app).
 ]);
 
-function diffEnvVars(dir, config = {}) {
+export function diffEnvVars(dir, config = {}) {
   const envDocPath = resolve(dir, 'docs-canonical/ENVIRONMENT.md');
   if (!existsSync(envDocPath)) return null;
 
@@ -263,7 +271,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/guard.mjs

@@ -11,6 +11,114 @@ 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.1: small in-code highlight reel surfaced when a project's pinned
+ * version is behind the running CLI. The biggest recurring user pattern is
+ * "I asked for feature X" → "X shipped two releases ago". This eliminates
+ * the need to grep the CHANGELOG. Keep entries short and command-oriented.
+ *
+ * Add to this table on every release. Format: [introducedIn, oneLineFeature].
+ */
+const _RELEASE_HIGHLIGHTS = [
+  ['0.13.0', '`docguard sync --since <ref>` — surgical refresh of code-truth doc sections'],
+  ['0.13.1', '`docguard impact --since <ref>` — changed files → affected canonical docs map'],
+  ['0.13.1', '`Cross-Reference` validator + "did you mean #X?" hints for broken anchors'],
+  ['0.14.1', '`docguard fix --write` auto-fixes high-confidence anchor matches'],
+  ['0.15.0', '`docguard guard --timings` — per-validator wall-time profile'],
+  ['0.15.0', '`.docguard.json` JSON Schema for VS Code autocomplete'],
+  ['0.16.0', '`docguard explain "<warning>"` — paste any warning, get the validator help'],
+  ['0.16.0', '`docguard guard --quiet` — suppress banner in hooks/CI'],
+  ['0.16.0', '`docguard init --no-spec-kit` — opt out of Spec Kit scaffolding'],
+  ['0.16.0', 'Language-aware test patterns (Python `test_*.py`, Rust `tests/*.rs`, Go `*_test.go`, ...)'],
+  ['0.17.0', '`docguard memory --diff` — drill into accuracy mismatches (which claim ≠ code)'],
+  ['0.17.0', '`docguard guard --pin` — record running CLI version into .docguard.json'],
+];
+
+function _whatsNewSince(pinnedVersion) {
+  if (!pinnedVersion) return [];
+  const out = [];
+  for (const [introducedIn, feature] of _RELEASE_HIGHLIGHTS) {
+    if (_semverCompare(introducedIn, pinnedVersion) > 0) {
+      out.push(`v${introducedIn}: ${feature}`);
+    }
+  }
+  return out;
+}
+
+/**
+ * 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 +472,27 @@ 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}`);
+      // v0.17.1: surface features added since the pinned version so users
+      // who pinned at v0.12 and just upgraded actually KNOW about sync,
+      // impact, explain, memory --diff, etc. The biggest user complaint
+      // pattern is "I asked for X but X already shipped two releases ago."
+      const whatsNew = _whatsNewSince(config.docguardVersion);
+      if (whatsNew.length > 0) {
+        console.log(`  ${c.dim}New since v${config.docguardVersion}:${c.reset}`);
+        for (const item of whatsNew.slice(0, 5)) {
+          console.log(`    ${c.dim}• ${item}${c.reset}`);
+        }
+        if (whatsNew.length > 5) console.log(`    ${c.dim}... ${whatsNew.length - 5} more in CHANGELOG.md${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 +531,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/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/docguard.mjs

@@ -43,6 +43,7 @@ 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) ──────────
@@ -121,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
@@ -210,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)) {
@@ -406,6 +450,15 @@ async function main() {
       // Default stays on (discoverability), but lets minimalist library
       // projects skip the .specify/.agent/commands scaffolding.
       flags.noSpecKit = true;
+    } else if (args[i] === '--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).
@@ -544,6 +597,9 @@ async function main() {
     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,16 +45,18 @@ 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.
+    // v0.16-P4 (revised in v0.17.1-B7): skip backticked SYSTEM env vars
+    // (PATH, HOME, USER, etc.) that appear in ENVIRONMENT.md prose. Trimmed
+    // to TRULY-system-only after wu feedback — NODE_ENV / CI / GITHUB_* were
+    // causing asymmetric flagging between diff and this validator. Apps
+    // legitimately treat NODE_ENV as app config; keep the list to vars that
+    // no sane application would read as runtime config.
     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) {

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.16.0"
+  version: "0.17.1"
   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.16.0
+  version: 0.17.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.16.0 -->
+<!-- docguard:version: 0.17.1 -->
 
 # 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.16.0
+  version: 0.17.1
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.16.0 -->
+<!-- docguard:version: 0.17.1 -->
 
 # 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.16.0
+  version: 0.17.1
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.16.0 -->
+<!-- docguard:version: 0.17.1 -->
 
 # 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.16.0
+  version: 0.17.1
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.16.0 -->
+<!-- docguard:version: 0.17.1 -->
 
 # 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.16.0
+  version: 0.17.1
   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.16.0",
+  "version": "0.17.1",
   "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 |
 |----------|-----------|