docguard-cli 0.17.0__tar.gz → 0.17.1__tar.gz

{docguard_cli-0.17.0/extensions/spec-kit-docguard → docguard_cli-0.17.1/.agent}/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
 

{docguard_cli-0.17.0/extensions/spec-kit-docguard → docguard_cli-0.17.1/.agent}/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
 

{docguard_cli-0.17.0/extensions/spec-kit-docguard → docguard_cli-0.17.1/.agent}/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
 

{docguard_cli-0.17.0 → docguard_cli-0.17.1}/.agent/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
 

{docguard_cli-0.17.0 → docguard_cli-0.17.1}/.agent/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
 ---
 

{docguard_cli-0.17.0 → docguard_cli-0.17.1}/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.1] - 2026-05-26
+
+Patch responding to a client-project feedback round: 1 real bug (B-7) and
+a discoverability improvement that helps users on older versions find the
+features they're asking for. **537 tests** (was 530, +7). 22 validators.
+
+### Fixed
+
+- **B-7: `diff` and `guard.Environment` disagreed on env-var coverage.** My v0.16-P4 `SYSTEM_ENV_VARS` denylist was over-broad: `NODE_ENV`, `CI`, `GITHUB_TOKEN`, `GITHUB_REF`, `GITHUB_SHA` are legitimately app env vars (apps read `process.env.NODE_ENV` for production/dev branching, `process.env.CI` to detect CI runs, etc.). The denylist stripped them from the doc side of `diff` only, so a project that documented `NODE_ENV` in BOTH `ENVIRONMENT.md` AND `.env.example` would correctly pass the `Environment` validator but `diff` would falsely flag it as "in code but not documented". Trimmed the denylist to truly-system-only vars (PATH, HOME, SHELL, TERM, etc. — the names no sane app would treat as runtime config). Reported by the client project running v0.16.0; their env-var accuracy went 79/82 → 80/82 with the bogus `NODE_ENV` flag gone. New `tests/b7-node-env-symmetry.test.mjs` locks in the symmetry.
+
+### Added
+
+- **What's-new highlights on the guard footer.** When `.docguard.json` carries a `docguardVersion` pin and the running CLI is newer, the guard footer now prints a short "New since v<pin>" list of headline features from intermediate releases. Top 5 inline, "N more in CHANGELOG.md" pointer when there's more. Closes the recurring pattern of users asking for features that shipped one or two releases ago — `sync --since`, `docguard impact`, `docguard explain`, `memory --diff`, `--quiet`, and Cross-Reference anchor hints all appear in the table.
+
+### Note to readers asking about S-1, S-11, S-12
+
+These three features are **already shipped** as of the listed releases. The v0.17.1 what's-new nudge surfaces them inline for any project still pinned to v0.12 or earlier. Quick recap:
+
+- **S-1: `docguard sync --since <ref>`** — shipped in **v0.13.0** as L-1. Refreshes only canonical doc sections touched by code changes in the diff range. Run `docguard sync --write --since main` on a feature branch to skip unrelated doc churn.
+- **S-11: `docguard impact --since <ref>`** — shipped in **v0.13.1**. Post-commit "changed files → affected canonical doc sections" map. Run `docguard impact --since HEAD~1` after a commit; JSON mode for CI bots.
+- **S-12: Anchor "did you mean...?" hints** — shipped in **v0.13.1** + extended in **v0.14.1** so high-confidence matches (edit distance ≤ 2, single close candidate) are now `[auto-fixable]` via `docguard fix --write`.
+
+Upgrade with `docguard upgrade --apply` or `npm i -g docguard-cli@latest` to pick them up.
+
+### Internal
+
+- **2 new test files**: `tests/b7-node-env-symmetry.test.mjs` (4 — diff/validator symmetry), `tests/whats-new.test.mjs` (3 — highlights surface). **Total: 530 → 537 tests (+7 new).**
+- **`SYSTEM_ENV_VARS`** trimmed in both `cli/commands/diff.mjs` and `cli/validators/environment.mjs` (single source of truth would be better; deferred).
+- **New highlight table** `_RELEASE_HIGHLIGHTS` in `cli/commands/guard.mjs` — add an entry per release going forward.
+- **Dry-run on the client project**: env accuracy 80/82, the 2 remaining mismatches are genuine doc-only drift (not bugs in our tool). Full guard still 672/672 PASS.
+- No new NPM deps.
+
 ## [0.17.0] - 2026-05-26
 
 Feature release picking up the 4 deferred items from v0.16 — **reproducibility

{docguard_cli-0.17.0 → docguard_cli-0.17.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docguard-cli
-Version: 0.17.0
+Version: 0.17.1
 Summary: The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation. Zero dependencies.
 Project-URL: Homepage, https://github.com/raccioly/docguard
 Project-URL: Documentation, https://github.com/raccioly/docguard#readme

{docguard_cli-0.17.0 → docguard_cli-0.17.1}/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 = {}) {

{docguard_cli-0.17.0 → docguard_cli-0.17.1}/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+

{docguard_cli-0.17.0 → docguard_cli-0.17.1}/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) {

{docguard_cli-0.17.0 → docguard_cli-0.17.1}/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"

{docguard_cli-0.17.0/.agent → docguard_cli-0.17.1/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
 

{docguard_cli-0.17.0/.agent → docguard_cli-0.17.1/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
 

{docguard_cli-0.17.0/.agent → docguard_cli-0.17.1/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
 

{docguard_cli-0.17.0 → docguard_cli-0.17.1}/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
 

{docguard_cli-0.17.0 → docguard_cli-0.17.1}/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
 ---
 

{docguard_cli-0.17.0 → docguard_cli-0.17.1}/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": {

{docguard_cli-0.17.0 → docguard_cli-0.17.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 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. Zero dependencies."
 readme = "README.md"
 license = { text = "MIT" }

docguard_cli-0.17.1/tests/b7-node-env-symmetry.test.mjs

@@ -0,0 +1,97 @@
+/**
+ * v0.17.1-B7 — regression: NODE_ENV documented in BOTH ENVIRONMENT.md AND
+ * .env.example should NOT appear in `docguard diff`'s "in code but not
+ * documented" list. The wu repo reported asymmetry between guard (PASS)
+ * and diff (warning) because my v0.16-P4 SYSTEM_ENV_VARS denylist
+ * incorrectly included NODE_ENV / CI / GITHUB_*.
+ *
+ * @req SC-B7-001 — NODE_ENV present in both doc + .env.example is counted as documented by diff
+ * @req SC-B7-002 — Environment validator agrees with diff on NODE_ENV (no asymmetry)
+ * @req SC-B7-003 — PATH (truly system) still filtered out from doc-side prose mentions
+ */
+import { describe, it, afterEach } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { diffEnvVars } from '../cli/commands/diff.mjs';
+import { validateEnvironment } from '../cli/validators/environment.mjs';
+
+function makeRepo(files) {
+  const dir = mkdtempSync(join(tmpdir(), 'docguard-b7-'));
+  for (const [rel, content] of Object.entries(files)) {
+    const full = join(dir, rel);
+    mkdirSync(join(full, '..'), { recursive: true });
+    writeFileSync(full, content);
+  }
+  return dir;
+}
+
+describe('B-7: diff/validator symmetry on NODE_ENV', () => {
+  let dir;
+  afterEach(() => { if (dir) rmSync(dir, { recursive: true, force: true }); });
+
+  it('NODE_ENV in both ENVIRONMENT.md table AND .env.example is NOT flagged by diff', () => {
+    dir = makeRepo({
+      'docs-canonical/ENVIRONMENT.md':
+        '# Environment\n\n' +
+        '## Environment Variables\n\n' +
+        '| Variable | Description |\n' +
+        '|----------|-------------|\n' +
+        '| `NODE_ENV` | App mode: development/production |\n',
+      '.env.example': 'NODE_ENV=development\n',
+      'src/index.ts': 'const m = process.env.NODE_ENV;',
+      'package.json': JSON.stringify({ name: 't', version: '0.0.0' }),
+    });
+    const d = diffEnvVars(dir, {});
+    assert.ok(d, 'diffEnvVars should produce a result');
+    assert.ok(!d.onlyInCode.includes('NODE_ENV'),
+      `NODE_ENV must not appear in 'in code but not documented' list; got onlyInCode: ${d.onlyInCode.join(', ')}`);
+  });
+
+  it('validator + diff agree: both count NODE_ENV as documented', () => {
+    dir = makeRepo({
+      'docs-canonical/ENVIRONMENT.md':
+        '# Env\n## Prerequisites\n## Environment Variables\n\n| Variable | Description |\n|---|---|\n| `NODE_ENV` | mode |\n',
+      '.env.example': 'NODE_ENV=development\n',
+      'src/main.ts': 'export const x = process.env.NODE_ENV;',
+      'package.json': JSON.stringify({ name: 't', version: '0.0.0' }),
+    });
+    const v = validateEnvironment(dir, { projectTypeConfig: { needsEnvVars: true } });
+    // Validator should NOT emit a warning about NODE_ENV being undocumented
+    assert.ok(
+      !v.warnings.some(w => /NODE_ENV/.test(w) && /undocumented/i.test(w)),
+      `validator should not flag NODE_ENV as undocumented; warnings: ${v.warnings.join(' | ')}`
+    );
+  });
+
+  it('PATH (truly system) is still filtered from doc-prose mentions', () => {
+    dir = makeRepo({
+      // PATH is mentioned in prose with backticks but is NOT a real app env var
+      'docs-canonical/ENVIRONMENT.md':
+        '# Env\n\nThe `cli` binary is on the venv `PATH`.\n',
+      'src/main.ts': 'export const x = 1;',  // no process.env.PATH reading
+      'package.json': JSON.stringify({ name: 't', version: '0.0.0' }),
+    });
+    const d = diffEnvVars(dir, {});
+    if (d) {
+      assert.ok(!d.onlyInDocs.includes('PATH'),
+        'PATH (system var in prose) should not appear in onlyInDocs');
+    }
+  });
+
+  it('CI is no longer filtered (apps DO check process.env.CI)', () => {
+    dir = makeRepo({
+      'docs-canonical/ENVIRONMENT.md':
+        '# Env\n\n## Environment Variables\n\n| Variable | Description |\n|---|---|\n| `CI` | true when running in CI |\n',
+      '.env.example': 'CI=false\n',
+      'src/main.ts': 'export const inCi = !!process.env.CI;',
+      'package.json': JSON.stringify({ name: 't', version: '0.0.0' }),
+    });
+    const d = diffEnvVars(dir, {});
+    assert.ok(d, 'should produce a result');
+    assert.ok(!d.onlyInCode.includes('CI'),
+      'CI documented + in code should not be flagged');
+  });
+});

docguard_cli-0.17.1/tests/whats-new.test.mjs

@@ -0,0 +1,65 @@
+/**
+ * v0.17.1 — "What's new since v<pin>" surfaces in the guard footer when the
+ * running CLI is newer than the pinned version. Closes the recurring user
+ * pattern of asking for features that shipped one or two releases ago.
+ *
+ * @req SC-WN-001 — pin at older version surfaces the highlight reel
+ * @req SC-WN-002 — pin at current version shows no highlights
+ * @req SC-WN-003 — highlights list is bounded (max 5 inline, "N more" pointer otherwise)
+ */
+import { describe, it, afterEach } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const CLI = join(process.cwd(), 'cli/docguard.mjs');
+
+function makeRepo(extra = {}) {
+  const dir = mkdtempSync(join(tmpdir(), 'docguard-whatsnew-'));
+  mkdirSync(join(dir, 'docs-canonical'));
+  writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 't', version: '0.0.1' }));
+  writeFileSync(join(dir, 'docs-canonical/ARCHITECTURE.md'), '# A\nstub\n');
+  writeFileSync(join(dir, 'CHANGELOG.md'), '# Changelog\n## [Unreleased]\n');
+  writeFileSync(join(dir, 'AGENTS.md'), '# Agents\n');
+  writeFileSync(join(dir, 'DRIFT-LOG.md'), '# Drift\n');
+  writeFileSync(join(dir, '.docguard.json'), JSON.stringify({
+    projectName: 't', profile: 'starter', version: '0.5', ...extra,
+  }, null, 2));
+  const env = { ...process.env };
+  spawnSync('git', ['init', '-q'], { cwd: dir, env });
+  spawnSync('git', ['-c', 'user.email=t@t', '-c', 'user.name=t', 'add', '-A'], { cwd: dir, env });
+  spawnSync('git', ['-c', 'user.email=t@t', '-c', 'user.name=t', 'commit', '-q', '-m', 'init'], { cwd: dir, env });
+  return dir;
+}
+
+describe("guard footer — what's-new highlights", () => {
+  let dir;
+  afterEach(() => { if (dir) rmSync(dir, { recursive: true, force: true }); });
+
+  it('pinning at v0.12.0 surfaces the headline features shipped since', () => {
+    dir = makeRepo({ docguardVersion: '0.12.0' });
+    const r = spawnSync('node', [CLI, 'guard', '--quiet'], { cwd: dir, encoding: 'utf-8' });
+    assert.match(r.stdout, /New since v0\.12\.0/);
+    // Should mention at least one of the headline features that shipped after v0.12
+    assert.match(r.stdout, /sync --since|docguard impact|docguard explain|memory --diff/,
+      `expected at least one headline feature; got: ${r.stdout.slice(-800)}`);
+  });
+
+  it('pinning at current CLI version shows no what\'s-new (clean)', () => {
+    const PKG = JSON.parse(readFileSync('package.json', 'utf-8'));
+    dir = makeRepo({ docguardVersion: PKG.version });
+    const r = spawnSync('node', [CLI, 'guard', '--quiet'], { cwd: dir, encoding: 'utf-8' });
+    assert.doesNotMatch(r.stdout, /New since v/);
+  });
+
+  it('caps at 5 inline highlights with "N more" pointer when more exist', () => {
+    dir = makeRepo({ docguardVersion: '0.11.0' });
+    const r = spawnSync('node', [CLI, 'guard', '--quiet'], { cwd: dir, encoding: 'utf-8' });
+    // Should be capped at 5 lines + "N more in CHANGELOG.md"
+    const lines = r.stdout.split('\n').filter(l => /^\s+•\s+v0\./.test(l));
+    assert.ok(lines.length <= 5, `expected at most 5 inline highlights; got ${lines.length}`);
+    assert.match(r.stdout, /more in CHANGELOG\.md/, 'should point at CHANGELOG.md for the rest');
+  });
+});