docguard-cli 0.18.1__tar.gz → 0.21.0__tar.gz

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

{docguard_cli-0.18.1/extensions/spec-kit-docguard → docguard_cli-0.21.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.18.1
+  version: 0.21.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.18.1 -->
+<!-- docguard:version: 0.21.0 -->
 
 # DocGuard Guard Skill
 

{docguard_cli-0.18.1/extensions/spec-kit-docguard → docguard_cli-0.21.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.18.1
+  version: 0.21.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.18.1 -->
+<!-- docguard:version: 0.21.0 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.18.1 → docguard_cli-0.21.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.18.1
+  version: 0.21.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.18.1 -->
+<!-- docguard:version: 0.21.0 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.18.1 → docguard_cli-0.21.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.18.1
+  version: 0.21.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

{docguard_cli-0.18.1 → docguard_cli-0.21.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.18.1 → docguard_cli-0.21.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:
@@ -18,7 +19,7 @@ jobs:
         with:
           fetch-depth: 0 # Full git history for freshness validator
 
-      - uses: actions/setup-node@v5
+      - uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node-version }}
 
@@ -81,7 +82,7 @@ jobs:
     needs: test
     steps:
       - uses: actions/checkout@v5
-      - uses: actions/setup-node@v5
+      - uses: actions/setup-node@v6
         with:
           node-version: 20
           registry-url: 'https://registry.npmjs.org'

{docguard_cli-0.18.1 → docguard_cli-0.21.0}/.github/workflows/release.yml

@@ -52,7 +52,7 @@ jobs:
       - uses: actions/checkout@v5
         with:
           fetch-depth: 0
-      - uses: actions/setup-node@v5
+      - uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node-version }}
       - name: Run Tests
@@ -151,7 +151,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: actions/setup-node@v5
+      - uses: actions/setup-node@v6
         with:
           node-version: 20
           registry-url: 'https://registry.npmjs.org'
@@ -167,7 +167,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: '3.12'
 

{docguard_cli-0.18.1 → docguard_cli-0.21.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.18.1 → docguard_cli-0.21.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.18.1 → docguard_cli-0.21.0}/CHANGELOG.md

@@ -7,6 +7,279 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.21.0] - 2026-05-26
+
+**Time-to-value.** The funnel-unblocker release. Until v0.21, a dev shopping
+for documentation tools had to install DocGuard, run `init`, write some
+canonical docs, and only then could they see what the tool actually does.
+v0.21 compresses that to **30 seconds, zero install**:
+
+```bash
+npx docguard-cli demo
+```
+
+Plus: `docguard init` now auto-detects existing projects and switches to
+"scan and propose" mode (reverse-engineering canonical docs from your code)
+instead of dumping a blank skeleton. The blank-skeleton path is still one
+flag away (`--skeleton`).
+
+### Added
+
+- **`docguard demo`** — the marquee feature of this release. Copies a baked-in
+  fixture (`templates/demo-fixture/` — a 4-service payments API with
+  intentional drift) to a temp directory, git-inits it, runs guard + score
+  against it, then prints a **curated narrative**: top-5 findings spanning
+  multiple validators, each annotated with the real-world impact ("Your AI
+  agent reads the architecture doc and gives wrong answers about how the
+  system works"), the CDD maturity score, and a clear three-line CTA showing
+  both `npm install -g` and `npx` paths. Temp fixture is cleaned up on exit
+  (or kept via `--keep` for inspection). Total time: ~0.5s for the guard
+  run; total experience: ~30s from `npx` to the install CTA.
+- **`templates/demo-fixture/`** — ships with the package (already in
+  `files: ["templates/"]`). 12-file pretend "acme-payments" project with
+  drift across 7 validator categories: undocumented 4th service, missing
+  API endpoint in reference, env var drift between `.env.example` and
+  `ENVIRONMENT.md`, `CHANGELOG` missing `[Unreleased]`, README sections
+  per Standard README spec missing, etc.
+- **`docguard init --skeleton`** — explicit opt-in to the v0.20 blank-template
+  behavior. For greenfield projects where the scan would find nothing.
+- **`docguard demo --keep`** — preserves the temp fixture and reports its
+  path. Useful for poking around what a real-world DocGuard-managed project
+  looks like.
+
+### Changed
+
+- **Smart `docguard init` first-run.** When `init` runs in a directory that
+  has existing source code (`cli/`, `src/`, `lib/`, `app/`, or 10+ source
+  files at top level) AND no `docs-canonical/`, it automatically dispatches
+  to `runGenerate` with `--plan` — the "scan and propose" path. Heuristic
+  opts out for: `--skeleton`, `--wizard`, `--skip-prompts` (CI), explicit
+  `--profile`, or projects that already have canonical docs (re-init case).
+  Result: the 80% of adopters who arrive with an existing codebase get
+  immediate value from the very first command, instead of staring at a
+  blank skeleton.
+- **`--help` updates.** New top section: "First-time? Try the demo (no
+  install, no setup): `npx docguard-cli demo`". `demo` listed in Tools.
+  `init` description updated to mention the new auto-detect behavior and
+  the `--skeleton` opt-out.
+- **README.** New CTA block at the top under the H1, above the Table of
+  Contents: prominent `npx docguard-cli demo` callout drives the funnel.
+  Validator/command counts updated by `canonical-sync` to 14 commands.
+
+### Tests
+
+- 582 → **596 tests** (+14):
+  - `tests/demo-command.test.mjs` (6): demo exits 0; output contains banner
+    + findings + score + CTA; `--quiet` suppresses banner; temp fixture is
+    cleaned up by default; `--keep` preserves it; top-5 findings span 3+
+    distinct validators (variety, not noise).
+  - `tests/init-smart-detection.test.mjs` (8): empty dir → skeleton; dir
+    with `src/` → smart mode; dir with `cli/` → smart mode; `--skeleton`
+    forces skeleton even with code present; `--skip-prompts` keeps skeleton
+    (CI determinism); pre-existing canonical docs skip smart mode; 10+
+    top-level Python files trigger smart mode; <10 + no code dir → skeleton.
+
+### Strategic context
+
+This is item #2 from the v0.19 SURFACE-AUDIT's adoption-friction analysis
+("no demo path — devs have to install, init, write docs, run guard just to
+see what we do"). v0.20 closed friction #1 (surface sprawl); v0.21 closes
+#2 (time-to-value). Next up per the 5-release arc: v0.22 — AI-native fix
+loop (`docguard fix --apply` calls Claude/Codex and opens a PR with the
+fix end-to-end).
+
+## [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.