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

{docguard_cli-0.15.3/extensions/spec-kit-docguard → docguard_cli-0.17.0/.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.15.3
+  version: 0.17.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.15.3 -->
+<!-- docguard:version: 0.17.0 -->
 
 # DocGuard Fix Skill
 

{docguard_cli-0.15.3/extensions/spec-kit-docguard → docguard_cli-0.17.0/.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.15.3
+  version: 0.17.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.15.3 -->
+<!-- docguard:version: 0.17.0 -->
 
 # 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.15.3/extensions/spec-kit-docguard → docguard_cli-0.17.0/.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.15.3
+  version: 0.17.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.15.3 -->
+<!-- docguard:version: 0.17.0 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.15.3 → docguard_cli-0.17.0}/.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.15.3
+  version: 0.17.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.15.3 -->
+<!-- docguard:version: 0.17.0 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.15.3 → docguard_cli-0.17.0}/.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.15.3
+  version: 0.17.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

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

@@ -7,6 +7,77 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 for the first time. **8 user-reported items shipped, 519 tests** (was
+497, +22). 22 validators. The Python user's top two asks (language-aware
+TRACE_MAP, hook-overwrite protection) are both in.
+
+### Fixed
+
+- **P1 — JSON+ANSI bleed in `score`/`trace`/`diff` `--format json`.** Critical CI bug. The v0.12 headless-mode fix only covered `guard` and (later) `diagnose`; three other commands leaked colored banners before the JSON body, breaking `jq` / `python -c "json.loads(...)"` pipelines. All five JSON-emitting commands now produce clean parseable output.
+- **P4 — `docguard diff` false positive on system env vars.** Backticked mentions of `PATH`, `HOME`, `USER`, `SHELL`, etc. inside ENVIRONMENT.md prose ("the venv `PATH`") were flagged as documented-but-not-implemented user env vars. Added a `SYSTEM_ENV_VARS` denylist to both `diff` and the `Environment` validator. The 30-name list covers OS/shell/CI vars; user-app names (`DATABASE_URL`, `API_KEY`, etc.) still count as documented.
+
+### Added
+
+- **P2 — Language-aware `TRACE_MAP`** (top user ask). The original JS/TS-only patterns false-negatived on Python (`test_*.py`), Rust (`tests/*.rs`), Go (`*_test.go`), Java (`*Test.java`), Ruby (`*_spec.rb`), and PHP test layouts. Every `TRACE_MAP` entry — Test files, Entry points, Config files, Schemas, Env files — now matches the equivalent patterns across ecosystems. New `tests/trace-multilang.test.mjs` (16 tests) locks the cross-language matching in.
+- **P3 — Hook overwrite protection** (2nd user ask). `docguard hooks --type pre-commit` previously clobbered user customizations on re-install. Now wraps DocGuard's content in `# BEGIN DOCGUARD MANAGED — do not edit between these markers` / `# END DOCGUARD MANAGED` markers and **splices only the managed block** on re-install, preserving everything around it. Legacy pre-v0.16 hooks (no markers) prompt the user to re-run with `--force` to upgrade. Third-party pre-existing hooks refuse to clobber without `--force`.
+- **P5 — `--quiet` / `-q` flag.** Suppresses the banner + ensureSkills decorative line. Useful inside git hooks and CI loops where the 5-line banner becomes 30 lines of noise. Doesn't affect validator output itself.
+- **P6 — `docguard explain <warning>` command** (user wishlist). Paste any warning text and get back: which validator emitted it, what triggered it, how to fix, a passing example, and the standard it references. Cuts source-spelunking time from 5-10 minutes to seconds. Covers all 16 validators. Also accepts a validator key directly (`docguard explain freshness`). JSON mode for tooling.
+- **P7 — N/A markers for required doc sections.** A project that legitimately has no auth (CLI, library, internal tool) can now declare it via `<!-- docguard:section authentication n/a — CLI tool, no user accounts -->` instead of writing "Absent by design" boilerplate. The marker requires a reason (non-empty after the dash) so it can't be a silent opt-out. Doc-Sections counts the marked section as passed.
+- **P8 — `--no-spec-kit` flag for `init`.** Default-on stays for discoverability, but minimalist library projects can now skip the `.specify/`, `.agent/`, `commands/` scaffolding entirely with `docguard init --no-spec-kit`.
+
+### Internal
+
+- **3 new test files**: `tests/trace-multilang.test.mjs` (16), `tests/section-na-markers.test.mjs` (5), plus expanded `tests/hooks.test.mjs` (+2 for managed-block). **Total: 497 → 519 tests (+22 new).**
+- New top-level command: `cli/commands/explain.mjs` with a 16-validator explainer table.
+- New helpers in `cli/commands/hooks.mjs`: `wrapManaged()`, `spliceManagedBlock()`, `BEGIN_MARKER`, `END_MARKER`.
+- New `SYSTEM_ENV_VARS` constant exported from `cli/commands/diff.mjs` (mirrored in `cli/validators/environment.mjs`).
+- Headless-mode flag check (`flags.quiet`) added to the main dispatcher.
+- No new NPM deps.
+
+### Out of scope (deferred to v0.17)
+
+User feedback items NOT addressed in this release:
+
+- **F6 — Score "Top improvements" cache** (low repro confidence — user cleared on the next run, may have been observer effect).
+- **F7 — Validator count drift in tool's own scaffolding** (philosophical: counts ARE accurate per-run; the issue is that DocGuard's OWN docs mention the count and naturally drift as validators are added. Could compute at runtime; defer for now.)
+- **F8 — Version pin in `.docguard.json`** (CDD reproducibility — record the DocGuard version that last passed). Medium effort, real value.
+- **F10 — Memory accuracy drill-down** (`docguard memory --diff` to show which claims don't match code). Bigger feature.
+- **N1 — Validator naming consistency** (`testSpec` JSON key / `test-spec` CLI flag / `Test-Spec` display). Breaking change; needs migration story.
+- **N3 — `--tax` fold** (philosophical: `--tax` does add information, just not enough to feel different).
+
 ## [0.15.3] - 2026-05-26
 
 Repo hygiene release — scrubbed a client-specific project name from public artifacts.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docguard-cli
-Version: 0.15.3
+Version: 0.17.0
 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.15.3 → docguard_cli-0.17.0}/cli/commands/diff.mjs

@@ -25,8 +25,12 @@ const CODE_EXTENSIONS = new Set([
 ]);
 
 export function runDiff(projectDir, config, flags) {
-  console.log(`${c.bold}🔍 DocGuard Diff — ${config.projectName}${c.reset}`);
-  console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
+  // v0.16-P1: headless mode for JSON output (matches guard/score/trace fix).
+  const isJson = flags.format === 'json';
+  if (!isJson) {
+    console.log(`${c.bold}🔍 DocGuard Diff — ${config.projectName}${c.reset}`);
+    console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
+  }
 
   const results = [];
 
@@ -97,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');
@@ -129,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;
 
@@ -196,7 +200,26 @@ function diffEntities(dir, config = {}) {
   };
 }
 
-function diffEnvVars(dir, config = {}) {
+// v0.16-P4: common system environment variables that get backticked in
+// prose ("the venv `PATH`", "your `HOME` directory") but are NEVER user-set
+// application env vars. Excluding them from the docVars set kills the
+// false-positive class reported by the Python user where `PATH` was flagged
+// as "documented-but-not-implemented".
+//
+// Conservative list — only the names that are unambiguously OS/shell vars.
+// Application names like `DATABASE_URL`, `API_KEY` etc. still count.
+const SYSTEM_ENV_VARS = new Set([
+  'PATH', 'HOME', 'USER', 'USERNAME', 'SHELL', 'PWD', 'OLDPWD', 'TMPDIR', 'TEMP', 'TMP',
+  'LANG', 'LC_ALL', 'LC_CTYPE', 'LC_MESSAGES', 'TZ',
+  'EDITOR', 'VISUAL', 'PAGER', 'TERM', 'COLORTERM',
+  'DISPLAY', 'SSH_AUTH_SOCK', 'SSH_CONNECTION', 'SSH_TTY',
+  'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_CACHE_HOME', 'XDG_RUNTIME_DIR',
+  // CI/build platform vars (set by the platform, not by the app)
+  'CI', 'GITHUB_TOKEN', 'GITHUB_ACTIONS', 'GITHUB_REF', 'GITHUB_SHA',
+  'NODE_ENV', // could be app-set but more often platform-set; conservative skip
+]);
+
+export function diffEnvVars(dir, config = {}) {
   const envDocPath = resolve(dir, 'docs-canonical/ENVIRONMENT.md');
   if (!existsSync(envDocPath)) return null;
 
@@ -208,6 +231,9 @@ function diffEnvVars(dir, config = {}) {
   const varRegex = /`([A-Z][A-Z0-9_]*[A-Z0-9])`/g;
   let match;
   while ((match = varRegex.exec(content)) !== null) {
+    // v0.16-P4: skip backticked system vars that appear in prose. They're
+    // never user-set application env vars; flagging them produces noise.
+    if (SYSTEM_ENV_VARS.has(match[1])) continue;
     docVars.add(match[1]);
   }
 
@@ -237,7 +263,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.17.0/cli/commands/explain.mjs

@@ -0,0 +1,286 @@
+/**
+ * Explain Command — v0.16-P6.
+ *
+ * Asked for by a user who'd spent 5-10 minutes per warning spelunking
+ * through validators/*.mjs source to understand what the validator wanted.
+ * `docguard explain "<warning text>"` matches the warning back to its
+ * validator and prints:
+ *   - Which validator emitted it
+ *   - What pattern triggered it
+ *   - A passing example
+ *   - The doc / spec / standard it's checking against
+ *
+ * Also supports `docguard explain <validator-key>` to show the whole
+ * validator's purpose without needing a specific warning.
+ *
+ * Zero NPM dependencies. Pure lookup table.
+ */
+
+import { c } from '../shared.mjs';
+
+/**
+ * Validator-key → human-readable explainer. Keyed by the same key DocGuard
+ * uses internally for severity overrides + lite-mode selection.
+ *
+ * Each entry has:
+ *   - title:    one-line summary
+ *   - what:     what the validator checks (declarative)
+ *   - why:      why it matters (motivation)
+ *   - triggers: array of common warning fragments and what each means
+ *   - example:  a tiny passing snippet
+ *   - standard: the spec/practice the validator references
+ */
+const EXPLAINERS = {
+  structure: {
+    title: 'Structure — required CDD files exist',
+    what: 'Verifies the canonical files declared in .docguard.json `requiredFiles.canonical` are present, plus AGENTS.md/CLAUDE.md, CHANGELOG.md, DRIFT-LOG.md.',
+    why:  'A documentation memory needs known anchor points. Missing files = broken memory.',
+    triggers: [
+      ['Missing required file', 'A canonical doc declared in your config doesn\'t exist on disk. Create it or remove it from `requiredFiles.canonical`.'],
+      ['Missing agent file', 'No AGENTS.md or CLAUDE.md found. Create one — even a stub establishes the agent contract.'],
+    ],
+    example: 'docs-canonical/ARCHITECTURE.md, AGENTS.md, CHANGELOG.md all present',
+    standard: 'CDD STANDARD (this project\'s STANDARD.md)',
+  },
+  docsSync: {
+    title: 'Docs-Sync — code files are referenced in canonical docs',
+    what: 'Walks route/service files in your source tree. For each, checks that the file path or basename appears in any canonical doc.',
+    why:  'Code that exists but isn\'t mentioned in any doc is invisible to future contributors and AI agents.',
+    triggers: [
+      ['not referenced in any canonical doc', 'A route or service file has no mention anywhere in docs-canonical/. Add a one-line reference (path or filename) to ARCHITECTURE.md or DATA-MODEL.md.'],
+    ],
+    example: '`src/services/auth.ts` mentioned in ARCHITECTURE.md\'s Components table',
+    standard: 'arc42 Component Map',
+  },
+  drift: {
+    title: 'Drift-Comments — every `// DRIFT:` has a DRIFT-LOG entry',
+    what: 'Scans code for `// DRIFT: reason` comments (also # / /* / -- variants). Each must have a row in DRIFT-LOG.md.',
+    why:  'DRIFT comments document conscious deviations from canonical specs. Without log entries, the deviation is invisible.',
+    triggers: [
+      ['DRIFT comment but DRIFT-LOG.md doesn\'t exist', 'Create DRIFT-LOG.md or remove the DRIFT comment.'],
+      ['no matching DRIFT-LOG.md entry', 'Add a row to DRIFT-LOG.md documenting the deviation, OR remove the // DRIFT: comment if the deviation is no longer current.'],
+    ],
+    example: '// DRIFT: using S3 SDK v2 here for compatibility — DRIFT-LOG.md has a row dated and explaining why',
+    standard: 'CDD principle: log every intentional deviation',
+  },
+  changelog: {
+    title: 'Changelog — Keep a Changelog format',
+    what: 'CHANGELOG.md must have a top-level `# Changelog` heading and an `## [Unreleased]` section.',
+    why:  'Standard format makes changelogs machine-readable. The Unreleased section is where new work accumulates between releases.',
+    triggers: [
+      ['Missing # Changelog heading', 'Start CHANGELOG.md with `# Changelog`.'],
+      ['Missing ## [Unreleased] section', 'Add `## [Unreleased]` between `# Changelog` and your first dated release.'],
+    ],
+    example: '# Changelog\\n\\n## [Unreleased]\\n\\n## [1.0.0] - 2026-01-01',
+    standard: 'Keep a Changelog v1.1.0 (https://keepachangelog.com)',
+  },
+  testSpec: {
+    title: 'Test-Spec — declared tests exist',
+    what: 'Reads TEST-SPEC.md\'s test mapping (rows linking sources to test files) and verifies each referenced test file exists.',
+    why:  'A spec that claims test coverage for X but the test file is missing is a stale promise.',
+    triggers: [
+      ['no service-to-test mappings', 'TEST-SPEC.md has no recognized mapping table. Add a table with `| Source | Test file | Status |` columns.'],
+      ['referenced test file does not exist', 'A path in TEST-SPEC.md\'s mapping doesn\'t exist. Update the path or remove the row.'],
+    ],
+    example: '| `src/auth.ts` | `tests/auth.test.ts` | ✅ |',
+    standard: 'ISO/IEC/IEEE 29119-3 (test specification)',
+  },
+  environment: {
+    title: 'Environment — env vars used in code are documented',
+    what: 'Greps `process.env.X` and `import.meta.env.X` (plus `os.environ` for Python) across source. Each name must appear in ENVIRONMENT.md or .env.example/.env.template.',
+    why:  'Undocumented env vars are runtime surprises waiting to happen.',
+    triggers: [
+      ['used but not documented', 'Code reads an env var that ENVIRONMENT.md doesn\'t list. Add it to the table.'],
+      ['VITE_API_URL or similar prefix', 'Naked prefixes like `VITE_` (no suffix) get filtered out — they\'re convention markers, not real var names.'],
+    ],
+    example: '`DATABASE_URL` listed in ENVIRONMENT.md\'s Environment Variables table AND read via `process.env.DATABASE_URL` in code',
+    standard: '12-Factor App III. Config',
+  },
+  security: {
+    title: 'Security — secrets handling + auth presence',
+    what: 'Checks SECURITY.md for required sections, and scans code for committed secrets / unsafe patterns.',
+    why:  'OWASP ASVS baseline.',
+    triggers: [
+      ['Missing "Authentication" section', 'Add `## Authentication` to SECURITY.md. If the project genuinely has no auth (CLI, library), use the v0.16-P7 N/A marker: `<!-- docguard:section authentication n/a — reason -->`.'],
+      ['Possible secret', 'A pattern matching common secret formats (API keys, JWT secrets) was found in committed code. Move to env var or .env.example.'],
+    ],
+    example: 'SECURITY.md has `## Authentication` describing JWT flow; no `sk_live_*` strings in code',
+    standard: 'OWASP ASVS v4.0',
+  },
+  freshness: {
+    title: 'Freshness — docs updated alongside code',
+    what: 'For each canonical doc, counts code commits since the doc\'s last commit. >10 commits = stale.',
+    why:  'Docs drift silently. This validator surfaces the drift before it becomes invisible.',
+    triggers: [
+      ['code commits since last doc update', 'Run `docguard sync --write` to refresh code-truth sections, then review the prose for accuracy.'],
+      ['DRIFT-LOG.md may be stale', 'DRIFT comments in code outpaced log entries. Add the entries.'],
+    ],
+    example: 'ARCHITECTURE.md last committed within 10 code commits',
+    standard: 'CDD principle: docs and code commit together',
+  },
+  traceability: {
+    title: 'Traceability — every FR/SC ID has test coverage',
+    what: 'Scans specs/ for FR-### and SC-### requirement IDs. Each must appear in a test file as `@req FR-###`.',
+    why:  'Untraceable requirements drift from implementation.',
+    triggers: [
+      ['has no test coverage', 'Add `// @req FR-012` (or similar) as a comment in the test that verifies the requirement.'],
+      ['orphaned test reference', 'A `@req` comment references an ID that doesn\'t exist in any spec. Update the ID or remove the marker.'],
+    ],
+    example: 'spec.md defines `**FR-012**: ...` and test file has `// @req FR-012` near the test that verifies it',
+    standard: 'ISO/IEC/IEEE 29148 (requirements traceability)',
+  },
+  apiSurface: {
+    title: 'API-Surface — endpoints in code match API-REFERENCE.md',
+    what: 'Compares routes scanned from code (Express, Next, FastAPI, Spring, etc.) against endpoints listed in API-REFERENCE.md and OpenAPI specs.',
+    why:  'Documented but missing endpoints are dead links. Endpoints in code that aren\'t documented are invisible.',
+    triggers: [
+      ['documented but absent', 'API-REFERENCE.md lists an endpoint that scanRoutes() can\'t find. Remove or fix the doc; `fix --write` removes when marked.'],
+      ['present but undocumented', 'A route exists in code but API-REFERENCE.md doesn\'t list it. Add it.'],
+    ],
+    example: 'GET /api/users in src/routes/users.ts AND in API-REFERENCE.md\'s Endpoints table',
+    standard: 'OpenAPI 3.1',
+  },
+  metricsConsistency: {
+    title: 'Metrics-Consistency — quoted numbers match reality',
+    what: 'Greps canonical + root docs for "N validators" / "N checks" claims and compares against the actual runtime count.',
+    why:  'Stale numeric claims ("19 validators" when it\'s now 22) erode credibility.',
+    triggers: [
+      ['says "N validators" but actual count is M', 'Run `docguard fix --write` — this is auto-fixable.'],
+    ],
+    example: 'AGENTS.md says "22 validators" and `docguard guard` shows 22 active validators',
+    standard: 'CDD principle: documented metrics match reality',
+  },
+  crossReference: {
+    title: 'Cross-Reference — internal markdown links resolve',
+    what: 'Scans canonical docs for `[text](./OTHER.md#anchor)` and `#anchor` links. Verifies the target file exists and the anchor matches a heading.',
+    why:  'Broken doc-to-doc links are the most-clicked dead ends in onboarding.',
+    triggers: [
+      ['broken link: target file not found', 'The file path doesn\'t exist. Fix the path or remove the link.'],
+      ['broken anchor', 'Anchor doesn\'t match any heading. Hint: `(did you mean #X?)` is appended for near-misses; if marked `[auto-fixable]`, run `docguard fix --write`.'],
+    ],
+    example: '`[Setup](#prerequisites)` in ENVIRONMENT.md AND `## Prerequisites` heading present',
+    standard: 'GitHub Flavored Markdown anchor rules',
+  },
+  generatedStaleness: {
+    title: 'Generated-Staleness — source=code sections match scanner output',
+    what: 'For each `<!-- docguard:section source=code -->` block, re-runs the memory plan scanner and compares against on-disk content. Also flags status: draft docs unmodified for > 14 days.',
+    why:  'Code-truth sections must reflect what the code actually says. Forgotten drafts rot.',
+    triggers: [
+      ['is stale', 'A code-truth section drifted. Run `docguard sync --write` (or `docguard fix --write` since v0.14-P3 — the validator now emits a regenerate-section fix).'],
+      ['status: draft for', 'A doc has been in draft for too long. Promote to `status: current` or remove. Threshold via `config.draftStalenessDays`.'],
+    ],
+    example: 'All source=code sections match what the scanner would produce right now',
+    standard: 'CDD principle: code-truth sections are machine-owned',
+  },
+  todoTracking: {
+    title: 'TODO-Tracking — TODOs are tracked + skipped tests explained',
+    what: 'Finds TODO/FIXME/HACK comments in source. Each must be referenced in tracking docs (ROADMAP.md, GitHub issues, etc.). Also flags `it.skip()` / `test.skip()` without an adjacent `// REASON:` comment.',
+    why:  'TODOs in code that no one tracks are silent debt.',
+    triggers: [
+      ['Skipped test without explanation', 'Add `// REASON: <why>` immediately above the skip.'],
+      ['Untracked TODO', 'Reference the TODO from ROADMAP.md by file:line, OR add it to a GitHub issue and link the issue ID in the comment.'],
+    ],
+    example: '// REASON: waiting on upstream fix in libfoo v2.5\\ntest.skip("foo", () => {})',
+    standard: 'Pragmatic Programmer (debt visibility)',
+  },
+  specKit: {
+    title: 'Spec-Kit — spec.md/plan.md/tasks.md have required sections',
+    what: 'For projects using Spec Kit, validates each spec/*.md against the spec-kit-template required sections.',
+    why:  'Spec Kit\'s value comes from consistent shape across specs.',
+    triggers: [
+      ['Missing mandatory section', 'Add the section listed in the warning. Reference the template at .specify/templates/'],
+    ],
+    example: 'plan.md has Summary, Technical Context, Constitution Check, Project Structure',
+    standard: 'GitHub Spec Kit',
+  },
+};
+
+/**
+ * Match a warning text fragment against the explainer table. Returns the
+ * matching entry's key + the trigger entry that best matches, or null when
+ * no match is confident enough.
+ */
+function matchWarning(query) {
+  const q = query.toLowerCase();
+
+  // Exact validator-key lookup (e.g. `docguard explain freshness`)
+  if (EXPLAINERS[query]) return { key: query, trigger: null };
+  // Also try kebab-case (e.g. `cross-reference` → `crossReference`)
+  const camelized = query.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+  if (EXPLAINERS[camelized]) return { key: camelized, trigger: null };
+
+  // Search trigger phrases
+  let best = null;
+  let bestScore = 0;
+  for (const [key, e] of Object.entries(EXPLAINERS)) {
+    for (const [phrase, _hint] of e.triggers) {
+      if (q.includes(phrase.toLowerCase())) {
+        const score = phrase.length; // prefer the more-specific phrase
+        if (score > bestScore) {
+          best = { key, trigger: [phrase, _hint] };
+          bestScore = score;
+        }
+      }
+    }
+  }
+  return best;
+}
+
+export function runExplain(projectDir, _config, flags) {
+  const query = (flags.args || []).join(' ').trim();
+  const isJson = flags.format === 'json';
+
+  if (!query) {
+    if (isJson) {
+      console.log(JSON.stringify({ validators: Object.keys(EXPLAINERS) }, null, 2));
+      return;
+    }
+    console.log(`${c.bold}🧭 docguard explain${c.reset} ${c.dim}— usage:${c.reset}`);
+    console.log(`  ${c.cyan}docguard explain <validator-key>${c.reset}    e.g. docguard explain freshness`);
+    console.log(`  ${c.cyan}docguard explain "<warning text>"${c.reset}   e.g. docguard explain "no service-to-test mappings"`);
+    console.log(`\n${c.dim}Known validators:${c.reset}`);
+    for (const [k, e] of Object.entries(EXPLAINERS)) {
+      console.log(`  ${c.cyan}${k.padEnd(22)}${c.reset} ${c.dim}${e.title}${c.reset}`);
+    }
+    return;
+  }
+
+  const match = matchWarning(query);
+  if (!match) {
+    if (isJson) {
+      console.log(JSON.stringify({ query, match: null }, null, 2));
+      return;
+    }
+    console.log(`${c.yellow}No matching validator or warning found for: "${query}"${c.reset}`);
+    console.log(`${c.dim}Try: ${c.cyan}docguard explain${c.dim} (no args) to list all validators.${c.reset}`);
+    process.exit(1);
+  }
+
+  const e = EXPLAINERS[match.key];
+  if (isJson) {
+    console.log(JSON.stringify({ query, match: { key: match.key, ...e, matchedTrigger: match.trigger } }, null, 2));
+    return;
+  }
+
+  console.log(`${c.bold}🧭 ${e.title}${c.reset}`);
+  console.log(`${c.dim}   validator key: ${match.key}${c.reset}\n`);
+
+  console.log(`${c.bold}What it checks:${c.reset}\n  ${e.what}\n`);
+  console.log(`${c.bold}Why:${c.reset}\n  ${e.why}\n`);
+
+  if (match.trigger) {
+    console.log(`${c.bold}Your warning ("${query}") matches:${c.reset}`);
+    console.log(`  ${c.yellow}${match.trigger[0]}${c.reset}`);
+    console.log(`  ${match.trigger[1]}\n`);
+  } else {
+    console.log(`${c.bold}Common warnings:${c.reset}`);
+    for (const [phrase, hint] of e.triggers) {
+      console.log(`  ${c.yellow}${phrase}${c.reset}`);
+      console.log(`    ${c.dim}${hint}${c.reset}`);
+    }
+    console.log('');
+  }
+
+  console.log(`${c.bold}Passing example:${c.reset}\n  ${c.dim}${e.example}${c.reset}\n`);
+  console.log(`${c.bold}Standard:${c.reset} ${c.dim}${e.standard}${c.reset}`);
+}

{docguard_cli-0.15.3 → docguard_cli-0.17.0}/cli/commands/guard.mjs

@@ -11,6 +11,80 @@ 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-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 +438,15 @@ 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}`);
+    }
+
     // 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 +485,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);