docguard-cli 0.17.0 → 0.17.1

package/cli/commands/diff.mjs

@@ -200,23 +200,31 @@ export 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).
 ]);
 
 export function diffEnvVars(dir, config = {}) {

package/cli/commands/guard.mjs

@@ -66,6 +66,40 @@ function _checkVersionPin(config) {
   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.
@@ -445,6 +479,18 @@ export function runGuard(projectDir, config, flags) {
     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+

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/extensions/spec-kit-docguard/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.17.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"

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.17.0
+  version: 0.17.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.17.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.17.0
+  version: 0.17.1
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.17.0 -->
+<!-- docguard:version: 0.17.1 -->
 
 # 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.17.0
+  version: 0.17.1
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.17.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.17.0
+  version: 0.17.1
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.17.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.17.0
+  version: 0.17.1
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

package/package.json

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