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

{docguard_cli-0.16.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.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
 

{docguard_cli-0.16.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.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."
 

{docguard_cli-0.16.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.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
 

{docguard_cli-0.16.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.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
 

{docguard_cli-0.16.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.16.0
+  version: 0.17.1
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

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

@@ -7,6 +7,68 @@ 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
+(version pin), accuracy drill-down (memory --diff), self-scaffolding drift fix,
+and naming flexibility (kebab + camel both accepted)**. **530 tests** (was 519,
++11). 22 validators.
+
+### Added
+
+- **P1: Version pin in `.docguard.json` (F8).** CDD reproducibility. Add `docguardVersion: "0.17.0"` to your config and `docguard guard` will nudge if the running CLI differs (newer or older). New `docguard guard --pin` action records the running CLI version after a passing run — opt-in, never automatic, refuses on FAIL status so you don't pin a broken state. Closes the "same project, different score across versions" surprise reported by a Python user.
+- **P2: `docguard memory --diff` (F10).** The memory-accuracy headline (e.g. "Accuracy: 83%") no longer requires source-spelunking to explain. New `docguard memory` shows per-domain accuracy (Endpoints / Entities / Env vars / Tech stack); add `--diff` for the drill-down listing *which* claims don't match code in each domain. JSON mode for tooling. Reuses the existing diff helpers — no new scanning logic.
+- **P3: Drift-proofed validator-count language in templates (F7).** Templates in `commands/`, `extensions/spec-kit-docguard/commands/`, `extensions/spec-kit-docguard/skills/`, and CI workflow examples no longer bake in "N validators" — replaced with "all validators" or "the full validator suite". User's own docs that legitimately quote a count are still validated by Metrics-Consistency; only DocGuard's own scaffolding (which would drift on every new validator) is detached from the number.
+- **P4: Validator naming consistency (additive, N1).** `.docguard.json` now accepts both kebab-case (`"test-spec": false`) and camelCase (`testSpec: false`) for both `validators` and `severity` maps. Normalized to camelCase internally before merge. Pre-existing configs keep working unchanged; new configs can use whichever style matches their team's convention. No breaking change.
+
+### Internal
+
+- **2 new test files**: `tests/version-pin.test.mjs` (6 — nudge behavior + `--pin` action), `tests/validator-naming.test.mjs` (5 — both casings accepted). **Total: 519 → 530 tests (+11 new).**
+- **New module**: `cli/commands/memory.mjs` (~140 lines).
+- **Exported from `cli/commands/diff.mjs`**: `diffRoutes`, `diffEntities`, `diffEnvVars`, `diffTechStack` so `memory.mjs` can reuse them without duplicating logic.
+- **New helpers in `cli/docguard.mjs`**: `normalizeConfig()`, `_kebabToCamel()`, `_KNOWN_VALIDATORS`.
+- **New helpers in `cli/commands/guard.mjs`**: `_parseSemver`, `_semverCompare`, `_checkVersionPin`, `_updateVersionPin`.
+- **Templates scrubbed** of numeric validator counts (6 files).
+- Dry-run on a real client project: 99% memory accuracy, 3 specific env-var mismatches surfaced by `memory --diff`.
+- No new NPM deps.
+
+### Out of scope (deferred to v0.18)
+
+- **F6** stale score cache — still low repro confidence; deferred until we get a reliable reproducer.
+- **Bigger items**: deeper Generated-Staleness optimization (still ~26% of guard time on large repos), `upgrade --pr` battle-test against a real GitHub remote, cross-process plan cache.
+
 ## [0.16.0] - 2026-05-26
 
 Feature release driven entirely by feedback from a real Python project running

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docguard-cli
-Version: 0.16.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.16.0 → docguard_cli-0.17.1}/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;
 

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

docguard_cli-0.17.1/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}`);
+  }
+}

{docguard_cli-0.16.0 → docguard_cli-0.17.1}/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.`);

{docguard_cli-0.16.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) {