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

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

{docguard_cli-0.17.1/extensions/spec-kit-docguard → docguard_cli-0.20.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.17.1
+  version: 0.20.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.17.1 -->
+<!-- docguard:version: 0.20.0 -->
 
 # DocGuard Guard Skill
 

{docguard_cli-0.17.1/extensions/spec-kit-docguard → docguard_cli-0.20.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.17.1
+  version: 0.20.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.17.1 -->
+<!-- docguard:version: 0.20.0 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.17.1 → docguard_cli-0.20.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.17.1
+  version: 0.20.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.17.1 -->
+<!-- docguard:version: 0.20.0 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.17.1 → docguard_cli-0.20.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.17.1
+  version: 0.20.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

{docguard_cli-0.17.1 → docguard_cli-0.20.0}/.docguardignore

@@ -26,3 +26,8 @@ __pycache__/
 # Backups created by generate --force
 *.bak
 
+# Surface audit doc — contains historical observations like "guard ran 22
+# validators" that document the pre-v0.19 state. Auto-fixing those to the
+# current count would erase the historical record the audit exists to preserve.
+docs-canonical/SURFACE-AUDIT.md
+

{docguard_cli-0.17.1 → docguard_cli-0.20.0}/.github/workflows/ci.yml

@@ -1,6 +1,7 @@
 name: DocGuard CI
 
 on:
+  workflow_dispatch: # Manual recovery for admin-bypass pushes that don't auto-trigger
   push:
     branches: [main]
   pull_request:

{docguard_cli-0.17.1 → docguard_cli-0.20.0}/.github/workflows/supply-chain.yml

@@ -1,6 +1,7 @@
 name: Supply-Chain Security
 
 on:
+  workflow_dispatch: # Manual recovery for admin-bypass pushes that don't auto-trigger
   pull_request:
     branches: [main]
   schedule:

{docguard_cli-0.17.1 → docguard_cli-0.20.0}/AGENTS.md

@@ -41,7 +41,7 @@
 | Command | Purpose |
 |---------|---------|
 | `diagnose` | **Primary** — identify issues + generate AI fix prompts |
-| `guard` | Validate project (CI gate) — 22 validators |
+| `guard` | Validate project (CI gate) — 23 validators |
 | `generate` | Reverse-engineer docs from code |
 | `fix --doc <name>` | AI prompt for specific document |
 | `score` | CDD maturity score (0-100) |

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

@@ -7,6 +7,242 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.20.0] - 2026-05-26
+
+**Consolidation.** 21 user-facing commands become 13. The promise from
+v0.19's SURFACE-AUDIT delivered in full — without breaking any existing
+user. Eight v0.19 commands keep working with deprecation warnings; one
+permanent alias (`audit → guard`) stays forever; ten cute aliases nobody
+documented are removed.
+
+This is the cleanup release. **No new functionality** — every behavior
+that worked in v0.19 still works in v0.20. The win is cognitive surface:
+new users see four clear sections in `--help` instead of seven muddled
+ones, and the "Daily 5" framing tells them exactly what to learn first.
+
+### Changed — surface shape
+
+- **`docguard init --with <name>`** is the new entry point for the
+  six one-shot scaffolders. Names: `agents`, `hooks`, `ci`, `badge`,
+  `llms`, `publish`. Comma-separated for chaining
+  (`docguard init --with agents,hooks,badge,ci`). The original six
+  commands (`docguard agents`, `docguard hooks`, …) still work — they
+  emit a yellow stderr deprecation warning and dispatch through
+  `init --with` internally.
+- **`docguard init --wizard`** replaces `docguard setup`. Same 7-step
+  interactive flow; `setup` is now a deprecation alias.
+- **`docguard diff --since <ref>`** replaces `docguard impact`. The
+  underlying impact analyzer is the same code path. `impact` is now a
+  deprecation alias.
+- **`docguard --help` reorganized** into four sections: **The Daily 5**
+  (init, guard, diff, sync, score), **Tools** (8 situational verbs),
+  **`init --with <name>`** (the six scaffolders), and **Deprecation
+  aliases** (a footnote with the v1.0 timeline). Down from seven
+  alphabetically-organized sections.
+
+### Removed — cute aliases (the ten dropped)
+
+These were in the router but never in `--help`. None of them had
+documentation. v0.20 errors with a one-line hint to the canonical
+command:
+
+  `onboard` · `gen` · `badges` · `pipeline` · `repair` · `dx` ·
+  `pub` · `traceability` · `help-warning` · `update`
+
+Try `docguard onboard` in v0.20 and you'll get:
+```
+Unknown command: onboard
+Hint: this alias was removed in v0.20. Try docguard setup
+(deprecated) — try `docguard init --wizard`.
+See docs-implementation/MIGRATION-v0.20.md for the full list.
+```
+
+### Kept permanently
+
+- **`audit → guard`** — the one alias that stays forever. Older blog
+  posts, tutorials, and CI scripts reference it. No deprecation warning,
+  no removal planned.
+
+### Added
+
+- **`docs-implementation/MIGRATION-v0.20.md`** — full migration guide.
+  Before/after table for every renamed command, the deprecation
+  timeline, a grep recipe to detect old usage in your repo, common
+  questions, and concrete examples (CI workflow, pre-commit hook,
+  fresh-project bootstrap, post-commit "what docs am I responsible
+  for?").
+- **`canonical-sync` validator (v0.19) now counts user-facing commands**,
+  not just files in `cli/commands/`. It parses `cli/docguard.mjs` to
+  find names in the Daily 5 + Tools sections, so the README's
+  "ships 13 commands" claim stays accurate across renames without
+  counting deprecation aliases.
+- **`tests/v020-consolidation.test.mjs`** — 24 tests covering: every
+  `--with` target dispatches; multi-scaffolder runs in order; unknown
+  `--with` targets error; every deprecation alias still works and
+  warns; `--quiet` suppresses the warning; all ten dropped aliases
+  error with a hint; `audit` is silent.
+
+### Fixed
+
+- **Spec-Kit extension aliases now satisfy the
+  `speckit.{extension}.{command}` schema** (issue #1, reported by
+  `c05m1x`). `extensions/spec-kit-docguard/extension.yml` previously
+  declared aliases as `docguard.guard` / `docguard.fix` /
+  `docguard.review` / `docguard.score`, which spec-kit rejects with
+  *"Validation Error: Invalid alias 'docguard.guard': must follow
+  pattern 'speckit.{extension}.{command}'"*. All four aliases now
+  match the canonical names (`speckit.docguard.guard` etc.), letting
+  `specify extension add docguard` succeed cleanly. The reporter's
+  secondary complaint about `--from` path-resolution is a separate
+  upstream spec-kit issue and tracked there.
+
+### Workflow hygiene
+
+- **`workflow_dispatch:` added to `ci.yml` and `supply-chain.yml`** so
+  admin-bypass pushes that don't auto-trigger workflows can be
+  recovered manually. (Came out of the v0.19.0 publish incident where
+  a branch-protection bypass appears to have suppressed the auto-trigger.)
+
+### Tests
+
+- 558 → **582 tests** (+24 from `tests/v020-consolidation.test.mjs`).
+- Canonical-Sync re-runs clean (`23 validators · 13 user-facing commands`).
+
+### Deprecation timeline
+
+- **v0.20.x → v0.x**: deprecated commands work with yellow warning.
+- **v1.0.0**: deprecated commands removed. At least 2-3 months out.
+- **forever**: `audit → guard` stays.
+
+See **[MIGRATION-v0.20.md](docs-implementation/MIGRATION-v0.20.md)** for
+the full guide.
+
+## [0.19.0] - 2026-05-26
+
+**Self-aware.** The headline change: until v0.19, `guard` could not see
+when the README lied about DocGuard's own surface. v0.18.1 shipped with
+"ships 19 commands" while the codebase had 21, and the architecture
+diagram had drifted across five releases without anyone noticing —
+because no validator was checking. v0.19 closes that gap.
+
+Triggered by a surface audit (see `docs-canonical/SURFACE-AUDIT.md`) that
+found three different command counts in three different places, six
+commands that exist in the router but were never surfaced in `--help`,
+and 11 undocumented alias variants. This release fixes the *self-policing*
+piece. The actual consolidation of the 21-command surface down to ~13
+verbs is staged for v0.20 with a migration guide.
+
+### Added
+
+- **A — `canonical-sync` validator.** New 23rd validator that runs on
+  every `guard` and asserts: (1) README "ships N commands" matches
+  `cli/commands/*.mjs` file count; (2) README "N validators" matches the
+  live runtime count; (3) architecture-diagram `Commands (N)` and
+  `Validators (N)` mermaid labels match reality. Gated by
+  `package.json` name === "docguard-cli" — returns N/A in every other
+  project. Counts itself per SURFACE-AUDIT §8.5 (current claim is "23
+  validators" = 22 files + 1 inlined Doc Sections, where Canonical-Sync
+  is among the 22). Severity high. 9 unit tests, all green.
+- **B — Six ghost commands surfaced in `--help`.** `explain`, `impact`,
+  `llms`, `memory`, `upgrade` now appear under their natural sections
+  (Analysis, Memory, CI/CD, Utilities). The historical `audit → guard`
+  alias is documented in a new "Aliases" footnote — kept permanently for
+  backwards-compat with older CI scripts.
+- **P1 — `tests/npm-pack-smoke.test.mjs`.** Builds the actual tarball
+  that would be published to npm, extracts it, and runs the CLI against
+  a tiny fixture. Catches the class of bugs where a needed file is
+  missing from `package.json`'s `files:` array. Opt-out via
+  `NPM_PACK_SMOKE=0` but on by default — v0.15.0 nearly shipped with a
+  missing `schemas/` directory until we added it to the files array, and
+  this gate would have caught that.
+
+### Changed
+
+- **C — README counts corrected to reality.** "ships 19 commands" → "ships
+  21 commands". Architecture diagram `Commands (19)` → `(21)`,
+  `Validators (22)` → `(23)`. "any of the 22 validators" → "23 validators"
+  in the What's-New section. Validators section now lists 23 with
+  Canonical-Sync added between Generated-Staleness and Metrics-Consistency.
+  Going forward, `canonical-sync` enforces these stay accurate.
+- **D — `Spec-Kit` validator moved to `cli/validators/`.** Was previously
+  exported from `cli/scanners/speckit.mjs` — architecturally backwards
+  (scanners read state, validators have severity/pass-fail semantics).
+  New thin file at `cli/validators/spec-kit.mjs` re-exports the function;
+  scanner logic stays where it lives. Now `ls cli/validators/*.mjs \| wc -l`
+  matches the validator surface (22 files + 1 for Doc Sections inlined).
+- **P2 — Node-based `gh` stub for upgrade-pr e2e.** v0.18.0's shell-script
+  stub passed on macOS but failed on Linux CI runners because of PATH
+  interaction with the runner's `/usr/bin/gh`. v0.18.1 gated the test
+  behind `E2E=1`. v0.19 rewrites the stub in Node (the runtime — present
+  on every platform DocGuard supports). Net result: upgrade --pr e2e now
+  runs in regular CI on every platform with no opt-in required.
+
+### Documentation
+
+- **`docs-canonical/SURFACE-AUDIT.md`** (new).** Full survey of the 21
+  commands, 23 validators, and every count claim in every canonical doc.
+  Sections cover: hard data, every drift, overlap matrix between commands,
+  proposed target surface for v0.20 (~13 verbs after consolidation),
+  migration plan with deprecation aliases, the canonical-sync spec, and
+  open questions answered. Maintainer-facing — refresh quarterly or when
+  surface changes by more than ±3 commands.
+
+### Notes / Deferred
+
+- The consolidation itself (folding `agents`/`badge`/`ci`/`hooks`/`llms`/
+  `publish` into `init --with`; renaming `setup` → `init --wizard`;
+  renaming `impact` → `diff --since`; dropping the 11 cute aliases) is
+  intentionally **deferred to v0.20.0** with a migration guide. v0.19
+  establishes the self-policing first so the v0.20 surface changes can't
+  silently break the docs.
+- P4 (Generated-Staleness depth optimization) was superseded by v0.18-P2's
+  cross-process disk cache, which covers the same scenario at the
+  plan-cache layer for all validators.
+
+## [0.18.1] - 2026-05-26
+
+Hotfix: v0.18.0 publish failed because the new `upgrade --pr` end-to-end test (which used a shell-script stub `gh`) was platform-specific — passed on macOS, failed on Linux CI runners due to interaction with the runner's existing `/usr/bin/gh`. Gated the test behind `E2E=1` (same pattern as the stress test) so the regular CI suite stays green. The production `upgrade --pr` code path is still covered by `tests/upgrade-pr.test.mjs`. v0.19 will switch to a Node-based gh stub.
+
+All v0.18.0 features ship intact:
+- P1 Generated-Staleness fast-path (30% faster guard)
+- P2 cross-process plan cache (.docguard/plan.cache.json)
+- P3 `score --diff` per-category drill-down
+- P4 upgrade-pr battle-test (now opt-in via E2E=1)
+
+## [0.18.0] - 2026-05-26
+
+Performance + drill-down release. Closes the four v0.18 backlog items:
+Generated-Staleness fast-path (**30% faster guard runs**), cross-process
+plan cache, `score --diff` drill-down, and an end-to-end battle-test for
+`upgrade --apply --pr`. **546 tests** (was 537, +9). 22 validators.
+
+### Performance
+
+- **P1 — Generated-Staleness fast-path.** The validator used to call `buildMemoryPlan` (~400ms) on EVERY guard run, even on projects with no `<!-- docguard:section source=code -->` markers and no `status: draft` docs (i.e. most projects today). New cheap pre-flight: scan canonical docs for either signal first; if neither is present, return N/A in <5ms. **Result on the client repo: total validator time 1431ms → 998ms — a 30% reduction.** Generated-Staleness dropped from "slowest validator at 26-33% of guard time" to "doesn't appear in the slow-list at all".
+- **P2 — Cross-process plan cache (`.docguard/plan.cache.json`).** The v0.15-P1 in-process cache only helped within a single process. CI flows that run guard → sync → fix as separate processes each rebuilt the plan. v0.18 adds a disk-backed L2 cache keyed by a tree-state hash (git HEAD + manifest mtimes). Cache invalidates automatically when source files change. Disabled with `config.diskCache: false`; survives corrupt files silently; never the only cache layer — L1 (in-process) still wins for same-run flows. Cuts the typical 3-step CI flow from 3× to 1× build time.
+
+### Added
+
+- **P3 — `docguard score --diff` per-category drill-down.** Symmetric to v0.17's `memory --diff`. The score headline ("Architecture: 80/100") used to require source-spelunking to understand. New `--diff` mode joins the score categories to live guard validator warnings and shows the underlying errors/warnings per weak category. Cap of 5 per category + "N more" pointer. Plus an inline tip: `docguard explain "<warning>"` for full per-warning help.
+
+### Internal
+
+- **P4 — End-to-end battle-test for `upgrade --apply --pr`.** The v0.14-P4 PR flow shipped without ever being exercised end-to-end. New `tests/upgrade-pr-e2e.test.mjs` wires up a local bare-repo remote + a stub `gh` binary on a fresh PATH directory and asserts: branch created, migration applied, commit landed on remote, `gh pr create` invoked with `--title` + `--body`. No real GitHub credentials needed; lives in regular CI from now on.
+- **3 new test files**: `tests/plan-disk-cache.test.mjs` (7), `tests/upgrade-pr-e2e.test.mjs` (2). Existing test suites already covered Generated-Staleness and score behavior. **Total: 537 → 546 tests (+9 new).**
+- **New helpers** in `cli/scanners/memory-plan.mjs`: `_treeStateHash`, `_readDiskCache`, `_writeDiskCache`, `_DISK_CACHE_PATH`, `_DISK_CACHE_VERSION`.
+- **New helpers** in `cli/validators/generated-staleness.mjs`: `_quickScan` (cheap marker pre-flight).
+- **New helpers** in `cli/commands/score.mjs`: `_SCORE_TO_VALIDATORS` mapping, `_showScoreDiff`.
+- **`buildMemoryPlan` cache strategy**: L1 (per-process Map) → L2 (per-tree disk file) → fresh build. Tree-state hash uses `git rev-parse HEAD` + manifest mtimes (package.json, pyproject.toml, Cargo.toml, etc.) for invalidation.
+- **Dry-run on client repo**: env accuracy still 80/82, 672/672 PASS, validator time 1431ms → 998ms.
+- No new NPM deps.
+
+### Backlog for v0.19
+
+- **F6** stale score cache (still low repro confidence)
+- Deeper Generated-Staleness optimization for projects that DO use markers (the v0.18 fast-path only helps projects without)
+- README polish — the README has aged through ~14 releases and could use a refresh
+- A pre-release smoke gate that runs against multiple synthetic fixture projects before publishing
+
 ## [0.17.1] - 2026-05-26
 
 Patch responding to a client-project feedback round: 1 real bug (B-7) and

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docguard-cli
-Version: 0.17.1
+Version: 0.20.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
@@ -39,6 +39,7 @@ Description-Content-Type: text/markdown
 ## Table of Contents
 
 - [What is DocGuard?](#what-is-docguard)
+- [What's New](#-whats-new)
 - [Quick Start](#-quick-start)
 - [Spec Kit Integration](#-spec-kit-integration)
 - [Usage](#usage)
@@ -74,15 +75,15 @@ DocGuard is an official [GitHub Spec Kit](https://github.com/github/spec-kit) co
 
 ```mermaid
 graph TD
-    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (15)"]
+    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (13)"]
     Commands --> guard["guard"]
     Commands --> generate["generate"]
     Commands --> score["score"]
     Commands --> diagnose["diagnose"]
     Commands --> setup["setup wizard"]
-    Commands --> other["diff · init · fix · trace<br/>agents · hooks · badge · ci · watch"]
+    Commands --> other["diff · init · fix · trace · impact · sync<br/>explain · memory · upgrade · agents · hooks · badge · ci · watch"]
 
-    guard --> Validators["Validators (19)"]
+    guard --> Validators["Validators (23)"]
     generate --> Scanners["Scanners (4)<br/>routes · schemas · doc-tools · speckit"]
     score --> Scoring["Weighted Scoring<br/>8 categories"]
     diagnose --> Validators
@@ -105,6 +106,37 @@ graph TD
 
 ---
 
+## ✨ What's New
+
+Recent highlights across the v0.16 → v0.19 line:
+
+- **`docguard explain <validator>`** — `docguard explain freshness` prints purpose, rules, common
+  failures, and fix recipes for any of the 23 validators. No need to dig into source.
+- **`docguard memory --diff`** — surface what changed in your canonical docs between two refs
+  (`HEAD~10..HEAD` by default). Great for code review and changelog drafting.
+- **`docguard score --diff`** — see exactly which validators moved the score up or down between
+  two commits. Pinpoints regressions without re-running the full suite by hand.
+- **`docguard upgrade --apply --pr`** — when the config schema bumps, DocGuard migrates
+  `.docguard.json` for you and (optionally) opens a PR with the change.
+- **Language-aware patterns** — test discovery and trace mapping now understand Python, Rust, Go,
+  Java, Ruby, and PHP layouts in addition to JS/TS. Sensible defaults, override via config.
+- **Per-validator severity overrides** — escalate `freshness` to `high` for production repos,
+  demote `doc-quality` to `low` for prototypes. Configurable per-project.
+- **JSON Schema for `.docguard.json`** — IDE autocomplete, in-line docs, and validation via
+  `$schema`. Shipped in the package at `schemas/docguard-config.schema.json`.
+- **Version pin (`docguardVersion` + `--pin`)** — pin the CLI version your project supports so
+  CI fails loudly if someone bumps DocGuard without re-running the suite.
+- **Cross-process plan cache** — repeated runs reuse the validator plan across processes when
+  the working tree hasn't changed. ~30% faster guard runs on typical repos.
+- **Headless-aware banner** — `--quiet`, `--format json`, `--write`, and `--changed-only`
+  automatically suppress the banner so JSON output stays parse-clean.
+- **npm-pack smoke gate** — every release now extracts the actual tarball and runs the CLI
+  end-to-end before publish, catching missing-file regressions.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full history.
+
+---
+
 ## ⚡ Quick Start
 
 ### Node.js (npm)
@@ -227,24 +259,49 @@ This installs DocGuard's slash commands (`/docguard.guard`, `/docguard.review`,
 
 ## Usage
 
-DocGuard ships **13 commands**:
+DocGuard ships **13 commands** (the "Daily 5" + 8 situational tools). Six additional one-shot scaffolders are accessed via `docguard init --with <name>`. Eight v0.19 commands continue to work as deprecation aliases through v0.20.x — see [MIGRATION-v0.20.md](docs-implementation/MIGRATION-v0.20.md).
+
+**The Daily 5** — what you'll reach for 95% of the time:
+
+| Command | What It Does |
+|:--------|:-------------|
+| `init`  | Bootstrap a project (`--wizard` for interactive · `--with <name>` for scaffolders) |
+| `guard` | Validate against canonical docs — 23 validators |
+| `diff`  | Show gaps between docs and code (`--since <ref>` for impact mode) |
+| `sync`  | Refresh code-truth doc sections — keeps memory always up to date |
+| `score` | CDD maturity score (0-100; `--diff` for delta between refs) |
+
+**Tools (situational, but day-to-day useful):**
 
 | Command | Purpose |
 |:--------|:--------|
-| `diagnose` | **Primary** — identify every issue + generate AI fix prompts |
-| `guard` | Validate project against canonical docs (CI gate) |
-| `generate` | Reverse-engineer docs from existing codebase |
-| `init` | Initialize CDD docs from templates (interactive) |
-| `score` | CDD maturity score (0–100) with weighted breakdown |
-| `fix --doc <name>` | Generate AI prompt for a specific document |
-| `fix --write` | Apply deterministic fixes (remove stale documented endpoints) — no AI |
-| `diff` | Compare canonical docs vs actual code artifacts |
-| `agents` | Generate agent-specific config files |
-| `trace` | Requirements traceability matrix |
-| `ci` | CI/CD pipeline check with threshold |
-| `watch` | Live watch mode with auto-fix |
-| `hooks` | Install git hooks (pre-commit, pre-push) |
-| `llms` | Generate `llms.txt` (AI-friendly project summary) |
+| `diagnose` | AI orchestrator — guard → emit fix prompts in one command |
+| `fix` | Generate AI fix instructions for specific docs (`--doc <name> --format prompt`) |
+| `fix --write` | Apply deterministic fixes (no AI — version bumps, counts, anchors, sections) |
+| `fix --history` | Audit log of every mechanical fix applied (from `.docguard/fixed.json`) |
+| `generate` | Reverse-engineer docs from existing codebase (`--plan` for AI scan) |
+| `explain <warning>` | Paste any warning — get the validator's docstring + fix path |
+| `memory` | Per-domain accuracy headline (endpoints / entities / env / tech) |
+| `memory --diff` | Drill into which specific claims don't match code |
+| `score --diff` | Drill into which checks pulled each category down |
+| `trace` / `trace --reverse <file>` | Requirements traceability — forward AND reverse |
+| `upgrade [--apply] [--pr]` | Check + migrate `.docguard.json` schema; `--pr` opens a PR |
+| `watch` | Live mode: re-run guard on file changes |
+
+**`init --with <name>` scaffolders** — picked at init time:
+
+| Scaffolder | What It Generates |
+|:-----------|:------------------|
+| `agents` | `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, `.github/copilot-instructions.md` |
+| `hooks` | Git pre-commit / pre-push hooks |
+| `ci` | GitHub Actions / pipeline YAML |
+| `badge` | Shields.io score badges for README |
+| `llms` | `llms.txt` (AI-friendly summary) |
+| `publish` | External doc-site config (Mintlify) — experimental |
+
+Run them solo (`docguard init --with hooks`) or stacked (`docguard init --with agents,hooks,badge,ci`).
+
+**Deprecation aliases** — `setup` · `agents` · `hooks` · `ci` · `badge` · `llms` · `publish` · `impact` keep working in v0.20.x with a yellow stderr warning. `audit → guard` is permanent (no warning). See [MIGRATION-v0.20.md](docs-implementation/MIGRATION-v0.20.md).
 
 ### CLI Flags
 
@@ -252,10 +309,22 @@ DocGuard ships **13 commands**:
 |:-----|:------------|:---------|
 | `--dir <path>` | Project directory (default: `.`) | All |
 | `--verbose` | Show detailed output | All |
-| `--format json` | Machine-readable output for CI/CD | score, guard, diff |
+| `--quiet` / `-q` | Suppress banner — for hooks, CI loops, scripts | All |
+| `--format json` | Machine-readable output (clean JSON, no ANSI bleed) | guard, score, diff, trace, diagnose, memory, impact, explain |
 | `--force` | Overwrite existing files (creates `.bak` backups) | generate, agents, init |
-| `--profile <name>` | Starter, standard, or enterprise | init |
-| `--agent <name>` | Target specific AI agent | agents |
+| `--force-redo` | Bypass ping-pong suppression in `.docguard/fixed.json` | fix --write |
+| `--profile <name>` | Starter / standard / enterprise | init |
+| `--no-spec-kit` | Skip auto-init of `.specify/` / `.agent/` scaffolding | init |
+| `--changed-only [--since <ref>]` | Pre-commit lite mode (5 fast validators on changed files only) | guard |
+| `--timings` | Per-validator wall-time profile (slowest first) | guard |
+| `--show-failing` | Show warnings/errors even when status is PASS | guard |
+| `--pin` | Record running CLI version into `.docguard.json` (reproducibility) | guard |
+| `--diff` | Per-category drill-down | score, memory |
+| `--check-only` | Exit 1 if behind (for CI) | upgrade |
+| `--apply` | Actually run the migration | upgrade |
+| `--pr` | Open a PR with the migration | upgrade |
+| `--reverse <file>` | Reverse traceability (code → docs) | trace |
+| `--history` | Show fix audit log | fix |
 
 ### Example Output
 
@@ -290,30 +359,47 @@ $ npx docguard-cli generate
 
 ## 🔍 Validators
 
-DocGuard runs **19 automated validators** on every `guard` check:
+DocGuard runs **23 automated validators** on every `guard` check. Every one is **language-aware** as of v0.16 — patterns for Python (`test_*.py`), Rust (`tests/*.rs`), Go (`*_test.go`), Java (`*Test.java`), Ruby (`*_spec.rb`), PHP, and JS/TS all match.
 
 | # | Validator | What It Checks | Default |
 |:--|:----------|:--------------|:--------|
 | 1 | **Structure** | Required CDD files exist | ✅ On |
-| 2 | **Doc Sections** | Canonical docs have required sections | ✅ On |
+| 2 | **Doc Sections** | Canonical docs have required sections (or N/A markers) | ✅ On |
 | 3 | **Docs-Sync** | Routes/services referenced in docs + OpenAPI cross-check | ✅ On |
-| 4 | **Drift-Comments** | `// DRIFT:` comments logged in DRIFT-LOG.md | ✅ On |
+| 4 | **Drift-Comments** | `// DRIFT:` comments logged in DRIFT-LOG.md (skips test files by default) | ✅ On |
 | 5 | **Changelog** | CHANGELOG.md has [Unreleased] section | ✅ On |
 | 6 | **Test-Spec** | Tests exist per TEST-SPEC.md rules | ✅ On |
-| 7 | **Environment** | Env vars documented, .env.example exists | ✅ On |
+| 7 | **Environment** | Env vars documented, `.env.example` exists | ✅ On |
 | 8 | **Security** | No hardcoded secrets in source code | ✅ On |
-| 9 | **Architecture** | Imports follow layer boundaries | ✅ On |
-| 10 | **Freshness** | Docs not stale relative to code changes | ✅ On |
+| 9 | **Architecture** | Imports follow layer boundaries (honors `config.ignore`) | ✅ On |
+| 10 | **Freshness** | Docs not stale relative to code changes (rename-aware via `git log --follow`) | ✅ On |
 | 11 | **Traceability** | Requirement IDs (FR, SC, NFR, US, AC, T) trace to tests | ✅ On |
 | 12 | **Docs-Diff** | Code artifacts match documented entities | ✅ On |
-| 13 | **Metadata-Sync** | Version refs consistent across docs | ✅ On |
-| 14 | **Docs-Coverage** | Code features referenced in documentation | ✅ On |
-| 15 | **Metrics-Consistency** | Hardcoded numbers match actual counts | ✅ On |
-| 16 | **Doc-Quality** | Writing quality (readability, passive voice, atomicity) | ✅ On |
-| 17 | **TODO-Tracking** | Untracked TODOs/FIXMEs and skipped tests | ✅ On |
+| 13 | **API-Surface** | API-REFERENCE.md endpoints match real routes (OpenAPI cross-check) | ✅ On |
+| 14 | **Metadata-Sync** | Version refs consistent across docs | ✅ On |
+| 15 | **Docs-Coverage** | Code features referenced in documentation | ✅ On |
+| 16 | **Doc-Quality** | Writing quality (readability, passive voice, atomicity, IEEE 830) | ✅ On |
+| 17 | **TODO-Tracking** | Untracked TODOs/FIXMEs and skipped tests (skips test files by default) | ✅ On |
 | 18 | **Schema-Sync** | Database models documented in DATA-MODEL.md | ✅ On |
 | 19 | **Spec-Kit** | Spec quality validation (FR-IDs, mandatory sections, phased tasks) | ✅ On |
-| 20 | **API-Surface** | API-REFERENCE.md endpoints match the real API surface (OpenAPI spec / routes); flags documented-but-deleted endpoints | ✅ On |
+| 20 | **Cross-Reference** | Internal markdown links + anchors resolve (with "did you mean?" hints) | ✅ On |
+| 21 | **Generated-Staleness** | `source=code` sections match scanner output; `status: draft` doc age | ✅ On |
+| 22 | **Canonical-Sync** | DocGuard's own README count claims match code-truth (DocGuard repo only — N/A elsewhere) | ✅ On |
+| 23 | **Metrics-Consistency** | Hardcoded numbers match actual counts | ✅ On |
+
+**Per-validator controls** (in `.docguard.json`):
+```json
+{
+  "validators": {
+    "test-spec": false,                 // disable (kebab-case OR camelCase both accepted)
+    "freshness": true
+  },
+  "severity": {
+    "todoTracking": "high",             // warnings fail CI
+    "freshness": "low"                  // warnings ignored for exit code
+  }
+}
+```
 
 ---
 
@@ -367,7 +453,7 @@ DocGuard provides AI agent slash commands for integrated workflows. Installed au
 
 | Command | What It Does |
 |:--------|:-------------|
-| `/docguard.guard` | Run quality validation — check all 22 validators |
+| `/docguard.guard` | Run quality validation — check all 23 validators |
 | `/docguard.review` | Analyze doc quality and suggest improvements |
 | `/docguard.fix` | Generate targeted fix prompts for specific issues |
 | `/docguard.score` | Show CDD maturity score with category breakdown |