docguard-cli 0.9.4 → 0.9.6

package/commands/docguard.guard.md

@@ -0,0 +1,60 @@
+---
+description: Run DocGuard guard validation — check project documentation against CDD standards with 19 validators
+handoffs:
+  - label: Fix All Issues
+    agent: docguard.fix
+    prompt: Fix all documentation issues found by guard
+  - label: Deep Review
+    agent: docguard.review
+    prompt: Perform semantic cross-document consistency analysis
+  - label: Check Score
+    agent: docguard.score
+    prompt: Show CDD maturity score and improvement roadmap
+---
+
+# DocGuard Guard — Documentation Quality Gate
+
+Run the DocGuard CLI to validate all documentation against Canonical-Driven Development standards.
+
+## What to do
+
+1. **Run the guard command**:
+```bash
+npx docguard-cli guard
+```
+
+2. **Parse the output**. Each of the 19 validators reports ✅ (pass), ⚠️ (warning), or ❌ (fail):
+
+   | Validator | What It Checks |
+   |-----------|---------------|
+   | Structure | Required CDD files exist |
+   | Doc Sections | Canonical docs have required sections |
+   | Docs-Sync | External doc references are valid |
+   | Drift | Code deviations logged in DRIFT-LOG.md |
+   | Changelog | CHANGELOG.md is maintained |
+   | Test-Spec | Tests match TEST-SPEC.md rules |
+   | Environment | Environment documentation |
+   | Security | No hardcoded secrets, SECURITY.md quality |
+   | Architecture | Architecture documentation |
+   | Freshness | Docs updated within commit window |
+   | Traceability | Requirements trace to tests |
+   | Docs-Diff | Doc changes match code changes |
+   | Metadata-Sync | Metadata headers are consistent |
+   | Docs-Coverage | All config files documented |
+   | Doc-Quality | Readability, IEEE 830 compliance |
+   | TODO-Tracking | TODOs are tracked |
+   | Schema-Sync | Schema documentation matches code |
+   | Spec-Kit | Spec quality (FR-IDs, sections) |
+   | Metrics-Consistency | Internal counts are accurate |
+
+3. **Triage findings by severity**:
+   - **CRITICAL**: Structure, Security, Test-Spec failures
+   - **HIGH**: Doc Sections, Drift, Changelog, Traceability failures
+   - **MEDIUM**: Freshness, Docs-Coverage, Doc-Quality, Metrics-Consistency warnings
+   - **LOW**: TODO-Tracking, Schema-Sync, Spec-Kit, Metadata-Sync warnings
+
+4. For each failing check, provide an **exact fix** — specific file, section, and content to change.
+
+5. After fixing, re-run `npx docguard-cli guard` to verify. Iterate until all checks pass.
+
+6. Exit codes: 0 = all pass, 1 = failures, 2 = warnings only.

package/commands/docguard.review.md

@@ -0,0 +1,53 @@
+---
+description: Cross-document consistency analysis — semantic review of documentation health, accuracy, and alignment with codebase
+handoffs:
+  - label: Fix Issues Found
+    agent: docguard.fix
+    prompt: Fix the documentation issues identified in the review
+  - label: Run Guard
+    agent: docguard.guard
+    prompt: Validate all documentation passes CDD standards
+---
+
+# DocGuard Review — Documentation Quality Analysis
+
+Perform comprehensive, read-only analysis of documentation health with semantic cross-document consistency checking.
+
+## What to do
+
+1. **Run the full diagnostic**:
+```bash
+npx docguard-cli diagnose
+npx docguard-cli score
+```
+
+2. **Perform semantic analysis** (beyond what CLI can check):
+
+   | Analysis Pass | What to Check |
+   |--------------|--------------|
+   | Terminology | Same concepts named consistently across docs |
+   | Architecture ↔ Code | Components listed in ARCHITECTURE.md exist in codebase |
+   | Data Model ↔ Code | Schemas in DATA-MODEL.md match actual implementations |
+   | Test Coverage | Critical flows in TEST-SPEC.md have actual test files |
+   | Security Claims | Auth mechanisms in SECURITY.md match actual code |
+   | Cross-References | Internal doc links resolve to valid targets |
+
+3. **Score each document** on 5 dimensions:
+
+   | Criterion | Weight | What to Evaluate |
+   |-----------|:------:|-----------------|
+   | Completeness | 30% | All mandatory sections present |
+   | Accuracy | 30% | Content matches actual codebase |
+   | Clarity | 20% | Readable, specific, no unexplained jargon |
+   | Currency | 10% | Up-to-date with latest code changes |
+   | Cross-refs | 10% | References are valid and bidirectional |
+
+4. **Classify findings by severity**:
+   - 🔴 **CRITICAL**: Security claim mismatch, missing mandatory doc, broken architecture reference
+   - 🟠 **HIGH**: Undocumented component, stale content (>5 commits behind), terminology conflict
+   - 🟡 **MEDIUM**: Missing cross-reference, minor coverage gap, readability issue
+   - 🟢 **LOW**: Minor formatting, optional section missing, style inconsistency
+
+5. **Output a structured report** with findings table, per-document health scores, and priority-ordered recommendations.
+
+6. **Do NOT modify files** — this is read-only analysis. Suggest fixes for user approval.

package/commands/docguard.score.md

@@ -0,0 +1,61 @@
+---
+description: CDD maturity score with ROI-based improvement roadmap — shows category breakdown, grade progression, and highest-impact fixes
+handoffs:
+  - label: Fix Top Issues
+    agent: docguard.fix
+    prompt: Fix the highest-ROI documentation issues to improve score
+  - label: Full Review
+    agent: docguard.review
+    prompt: Perform deep semantic analysis for accuracy verification
+  - label: Run Guard
+    agent: docguard.guard
+    prompt: Verify current guard status after improvements
+---
+
+# DocGuard Score — CDD Maturity Assessment
+
+Calculate and display the project's Canonical-Driven Development maturity score with ROI-based improvement roadmap.
+
+## What to do
+
+1. **Run the scoring engine**:
+```bash
+npx docguard-cli score
+```
+
+2. **For JSON output** (CI/CD integration):
+```bash
+npx docguard-cli score --format json
+```
+
+3. **Interpret the grade**:
+
+   | Grade | Score | Meaning |
+   |-------|:-----:|---------|
+   | A+ | 95-100 | Exemplary — production-grade documentation |
+   | A | 85-94 | Strong — minor improvements possible |
+   | B | 70-84 | Good — some gaps to address |
+   | C | 50-69 | Fair — significant documentation debt |
+   | D | 30-49 | Poor — major gaps in documentation |
+   | F | 0-29 | Critical — documentation infrastructure missing |
+
+4. **Analyze category breakdown** (sorted by weight):
+
+   | Category | Weight | What It Measures |
+   |----------|:------:|-----------------|
+   | Structure | 25% | Required CDD files exist |
+   | Doc Quality | 20% | Readability, sections, IEEE 830 compliance |
+   | Testing | 15% | Test documentation coverage |
+   | Security | 10% | Security docs, secrets handling |
+   | Environment | 10% | Environment and setup docs |
+   | Drift | 10% | Code deviation tracking |
+   | Changelog | 5% | Change log maintenance |
+   | Architecture | 5% | Architecture documentation |
+
+5. **Build an ROI-ranked improvement roadmap**:
+   - Calculate `Potential Gain = weight - current points` for each category
+   - Sort by `Potential Gain / Effort` ratio
+   - Show: "If you fix [X], score will increase from [Y] to [Z]"
+   - Show the **minimum set of fixes** to reach the next grade level
+
+6. **Track progress**: Compare current score against previous runs to show improvement.

package/docs/installation.md

@@ -2,25 +2,30 @@
 
 ## Requirements
 
-- **Node.js** ≥ 18
+- **Node.js** ≥ 18 (required for both npm and Python installations)
 - **git** (optional — needed for freshness validation)
 
-## Install via npx (Recommended)
+## Install via npm
 
-No installation needed. Run directly:
+### Option 1: Run directly (no install)
 
 ```bash
-npx docguard --help
+npx docguard-cli diagnose
 ```
 
 This downloads and runs DocGuard on demand. Always uses the latest version.
 
-## Install as Dev Dependency
+### Option 2: Install globally
 
-For projects that want a pinned version:
+```bash
+npm i -g docguard-cli
+docguard diagnose
+```
+
+### Option 3: Dev dependency (pinned version)
 
 ```bash
-npm install --save-dev docguard
+npm install --save-dev docguard-cli
 ```
 
 Then use via npm scripts in `package.json`:
@@ -35,34 +40,44 @@ Then use via npm scripts in `package.json`:
 }
 ```
 
-## Install Globally
+## Install via Python (PyPI)
 
 ```bash
-npm install -g docguard
+pip install docguard-cli
+docguard diagnose
 ```
 
-Then use anywhere:
+> **Note:** The Python package is a thin wrapper that delegates to `npx docguard-cli`. Node.js 18+ must be installed on the system.
+
+The Python wrapper:
+- Detects Node.js 18+ on your system
+- Runs `npx docguard-cli` with all arguments forwarded
+- Provides clear error messages if Node.js is missing
+
+## Install as Spec Kit Extension
+
+If your project uses [GitHub Spec Kit](https://github.com/github/spec-kit):
 
 ```bash
-docguard guard
-docguard score
+specify extension add docguard
 ```
 
+This installs DocGuard's slash commands into your AI agent's command palette.
+
 ## Verify Installation
 
 ```bash
-npx docguard --version
+npx docguard-cli --version
+# Output: docguard v0.9.5
 ```
 
-Should output `DocGuard v0.4.0` (or current version).
-
 ## CI/CD Installation
 
 In GitHub Actions or similar:
 
 ```yaml
 - name: Run DocGuard
-  run: npx docguard ci --threshold 70
+  run: npx docguard-cli guard
 ```
 
 No separate install step needed — `npx` handles it.
@@ -71,11 +86,14 @@ No separate install step needed — `npx` handles it.
 
 ```bash
 # If installed as dev dependency
-npm update docguard
+npm update docguard-cli
 
 # If installed globally
-npm update -g docguard
+npm update -g docguard-cli
+
+# If installed via Python
+pip install --upgrade docguard-cli
 
 # If using npx — always runs latest automatically
-npx docguard@latest --version
+npx docguard-cli@latest --version
 ```

package/docs/quickstart.md

@@ -20,16 +20,32 @@ cd your-project
 npx docguard-cli init
 ```
 
-Creates all 5 canonical docs + tracking files + AI slash commands.
+Creates all 6 canonical docs (including REQUIREMENTS.md) + tracking files + AI slash commands.
 
-### Option C: From existing code (best for established projects)
+### Option C: Spec-Driven Development (spec-kit projects)
+
+If you're using [GitHub Spec Kit](https://github.com/github/spec-kit):
+
+```bash
+# 1. Initialize spec-kit
+specify init . --ai claude
+
+# 2. Add DocGuard as enforcement layer
+specify extension add docguard
+
+# 3. Write specs with AI, validate with DocGuard
+/speckit.specify Build an app that...
+npx docguard-cli guard
+```
+
+### Option D: From existing code (established projects)
 
 ```bash
 cd your-project
 npx docguard-cli generate
 ```
 
-Scans your codebase and generates pre-filled documentation.
+Scans your codebase and generates pre-filled documentation, including REQUIREMENTS.md with spec-kit-aligned FR/SC IDs.
 
 ## Fill the Docs (AI Does It)
 
@@ -52,9 +68,8 @@ diagnose  →  AI reads prompts  →  AI fixes docs  →  guard verifies
 ## Verify
 
 ```bash
-npx docguard-cli guard        # Pass/fail check
+npx docguard-cli guard        # Pass/fail check (19 validators)
 npx docguard-cli score        # 0-100 maturity score
-npx docguard-cli score --tax  # How much time docs cost you
 ```
 
 ## Automate
@@ -66,7 +81,7 @@ npx docguard-cli hooks
 # CI/CD pipelines
 npx docguard-cli ci --threshold 70
 
-# Live watch mode with auto-fix
+# Live watch mode
 npx docguard-cli watch --auto-fix
 ```
 

package/extensions/spec-kit-docguard/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricardo Accioly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/extensions/spec-kit-docguard/README.md

@@ -0,0 +1,105 @@
+# DocGuard — CDD Enforcement Extension for Spec Kit
+
+Enterprise-grade Canonical-Driven Development (CDD) enforcement for [Spec Kit](https://github.com/github/spec-kit). Validates, scores, and fixes project documentation with 19 automated validators, AI-driven research workflows, and spec-kit integration hooks.
+
+## Features
+
+- **19 Validators** — Structure, Security, Doc Quality, Test-Spec, Drift, Freshness, and 13 more
+- **4 AI Skills** — Enterprise-grade AI behavior protocols (not just step-lists)
+- **3 Bash Scripts** — JSON-output orchestration for AI consumption
+- **Workflow Chaining** — YAML handoffs enable guard → fix → review → score flows
+- **Spec Kit Hooks** — Mandatory quality gate after `/speckit.implement`
+- **Zero Dependencies** — Pure Node.js built-ins only
+
+## Installation
+
+```bash
+npm install -g docguard-cli
+```
+
+Or use via npx:
+```bash
+npx docguard-cli guard
+```
+
+## Quick Start
+
+```bash
+# Initialize CDD in your project
+docguard init
+
+# Check documentation health
+docguard guard
+
+# Get AI-ready fix prompts
+docguard fix --doc architecture
+
+# Calculate maturity score
+docguard score
+```
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `docguard.guard` | Run 19-validator quality gate with severity triage |
+| `docguard.fix` | AI-driven documentation repair with codebase research |
+| `docguard.review` | Cross-document semantic consistency analysis (read-only) |
+| `docguard.score` | CDD maturity score with ROI improvement roadmap |
+| `docguard.diagnose` | Diagnose issues + generate multi-perspective AI prompts |
+| `docguard.generate` | Reverse-engineer canonical docs from codebase |
+| `docguard.init` | Initialize CDD structure in a project |
+| `docguard.trace` | Generate requirements traceability matrix |
+
+## AI Skills
+
+DocGuard provides 4 enterprise-grade AI behavior protocols modeled after Spec Kit's skill architecture:
+
+| Skill | Lines | What It Does |
+|-------|:-----:|-------------|
+| `docguard-guard` | 155 | 6-step execution with severity triage, structured reporting, remediation recommendations |
+| `docguard-fix` | 195 | 7-step research workflow with per-document codebase research, 3-iteration validation loops |
+| `docguard-review` | 170 | Semantic cross-document analysis with 6 analysis passes and quality scoring matrix |
+| `docguard-score` | 165 | CDD maturity assessment with ROI-based improvement roadmap and grade progression |
+
+Skills differ from commands in a critical way: **commands tell agents what to run** (step-lists), while **skills tell agents how to think, validate, and iterate** (behavior protocols).
+
+## Spec Kit Integration
+
+### Workflow Hooks
+
+DocGuard integrates into the spec-kit workflow through hooks:
+
+```yaml
+hooks:
+  after_implement:   # Mandatory — always runs after /speckit.implement
+    command: docguard.guard
+  before_tasks:      # Optional — review docs before task generation
+    command: docguard.review
+  after_tasks:       # Optional — show score after tasks
+    command: docguard.score
+```
+
+### Workflow Chaining
+
+All commands support YAML handoffs for seamless workflow chaining:
+
+```
+guard → fix → review → score
+  ↑                      ↓
+  └──────────────────────┘
+```
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `docguard-check-docs.sh` | Discover docs, return JSON inventory with metadata |
+| `docguard-suggest-fix.sh` | Run guard, prioritize fixes as JSON |
+| `docguard-init-doc.sh` | Initialize canonical doc with metadata header |
+
+All scripts support `--json` mode for AI-parseable output.
+
+## License
+
+MIT © Ricardo Accioly

package/extensions/spec-kit-docguard/commands/diagnose.md

@@ -0,0 +1,43 @@
+---
+description: "Diagnose documentation issues and generate AI-ready fix prompts"
+handoffs:
+  - label: Fix All Issues
+    agent: docguard.fix
+    prompt: Fix all documentation issues found
+  - label: Run Guard
+    agent: docguard.guard
+    prompt: Validate all checks pass
+---
+
+# DocGuard Diagnose
+
+Runs guard validation, analyzes failures, and generates AI-ready prompts to fix documentation issues.
+
+## User Input
+
+$ARGUMENTS
+
+## Steps
+
+1. Run DocGuard diagnose on the current project:
+
+```bash
+npx --yes docguard-cli@latest diagnose $ARGUMENTS
+```
+
+2. Review the output:
+   - **Issues found** — categorized as errors or warnings
+   - **Remediation plan** — ordered list of fix commands
+   - **AI-ready prompt** — copy/paste to your AI agent for automated fixes
+
+3. For multi-perspective analysis, add `--debate` to get three-agent prompts (Advocate/Challenger/Synthesizer).
+
+## Flags
+
+- `--format json` — Output as JSON
+- `--debate` — Generate multi-perspective AI prompts
+- `--dir <path>` — Run on a different directory
+
+## Research
+
+Inspired by AITPG (IEEE TSE 2026) multi-agent prompting and TRACE (IEEE TMLCN 2026) calibrated quality evaluation.

package/extensions/spec-kit-docguard/commands/generate.md

@@ -0,0 +1,50 @@
+---
+description: "Reverse-engineer canonical documentation from existing codebase"
+handoffs:
+  - label: Validate Generated Docs
+    agent: docguard.guard
+    prompt: Validate generated documentation passes all checks
+  - label: Review Quality
+    agent: docguard.review
+    prompt: Review quality of generated documentation
+---
+
+# DocGuard Generate
+
+Scans your codebase and generates canonical documentation: ARCHITECTURE.md, DATA-MODEL.md, TEST-SPEC.md, SECURITY.md, ENVIRONMENT.md, and API-REFERENCE.md.
+
+## User Input
+
+$ARGUMENTS
+
+## Steps
+
+1. Run DocGuard generate on the current project:
+
+```bash
+npx --yes docguard-cli@latest generate $ARGUMENTS
+```
+
+2. Review the generated docs in `docs-canonical/`. Each document includes:
+   - Structured sections based on industry standards
+   - Data extracted from your actual codebase (routes, schemas, configs)
+   - Standards citation footer referencing relevant specifications
+   - DocGuard metadata headers for freshness tracking
+
+3. Customize with `--doc <name>` to generate a specific document only.
+
+## Generated Documents
+
+| Document | Source | Standard |
+|----------|--------|----------|
+| ARCHITECTURE.md | Routes, configs, dependencies | arc42 / C4 Model |
+| DATA-MODEL.md | Schema files, type definitions | C4 Component / ER |
+| TEST-SPEC.md | Test files, test configs | ISO/IEC/IEEE 29119-3 |
+| SECURITY.md | Auth modules, .gitignore, secrets | OWASP ASVS v4.0 |
+| ENVIRONMENT.md | .env files, Docker, CI/CD configs | 12-Factor App |
+| API-REFERENCE.md | Route handlers, OpenAPI specs | OpenAPI 3.1 |
+
+## Flags
+
+- `--doc <name>` — Generate a specific document only
+- `--dir <path>` — Run on a different directory

package/extensions/spec-kit-docguard/commands/guard.md

@@ -0,0 +1,73 @@
+---
+description: "Run 19-validator quality gate with severity triage and actionable remediation"
+handoffs:
+  - label: Fix All Issues
+    agent: docguard.fix
+    prompt: Fix all documentation issues found by guard
+  - label: Deep Review
+    agent: docguard.review
+    prompt: Perform semantic cross-document consistency analysis
+  - label: Check Score
+    agent: docguard.score
+    prompt: Show CDD maturity score and improvement roadmap
+---
+
+# DocGuard Guard
+
+Validate your project against its canonical documentation. Runs 160+ automated checks across 19 validators.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Execution
+
+1. Run DocGuard guard validation:
+```bash
+npx --yes docguard-cli@latest guard $ARGUMENTS
+```
+
+2. Parse each validator's result and build a severity-ranked findings table.
+
+3. **Triage by severity**:
+   - **CRITICAL**: Structure, Security, Test-Spec failures → fix immediately
+   - **HIGH**: Doc Sections, Drift, Changelog, Traceability → fix before commit
+   - **MEDIUM**: Freshness, Docs-Coverage, Doc-Quality, Metrics → fix this sprint
+   - **LOW**: TODO-Tracking, Schema-Sync, Spec-Kit, Metadata → fix when convenient
+
+4. For each failing check, provide an **exact fix** — specific file, section, and content.
+
+5. Re-run guard after fixes. Iterate until all checks pass (max 3 iterations).
+
+## Validators (19 total)
+
+| Validator | What It Checks |
+|-----------|---------------|
+| Structure | Required CDD files exist |
+| Doc Sections | Canonical docs have required sections |
+| Docs-Sync | External doc references are valid |
+| Drift | `// DRIFT:` comments have DRIFT-LOG entries |
+| Changelog | CHANGELOG.md is maintained |
+| Test-Spec | TEST-SPEC.md matches actual test files |
+| Environment | Environment docs and .env.example exist |
+| Security | No hardcoded secrets, .gitignore configured |
+| Architecture | Layer boundaries and diagrams present |
+| Freshness | Docs updated after recent code changes |
+| Traceability | Canonical docs linked to source code |
+| Docs-Diff | Entity/route/field drift between code and docs |
+| Metadata-Sync | Metadata headers are consistent |
+| Docs-Coverage | All config files documented |
+| Doc-Quality | Readability, IEEE 830 compliance |
+| TODO-Tracking | TODOs are tracked |
+| Schema-Sync | Schema documentation matches code |
+| Spec-Kit | Spec quality (FR-IDs, sections) |
+| Metrics-Consistency | Internal counts are accurate |
+
+## Flags
+
+- `--format json` — Output results as JSON
+- `--dir <path>` — Run on a different directory

package/extensions/spec-kit-docguard/commands/init.md

@@ -0,0 +1,38 @@
+---
+description: "Initialize Canonical-Driven Development in a project"
+handoffs:
+  - label: Generate Docs
+    agent: docguard.fix
+    prompt: Generate documentation content from codebase
+  - label: Check Status
+    agent: docguard.guard
+    prompt: Run guard to see initial status
+---
+
+# DocGuard Init
+
+Initialize CDD in your project. Creates the `docs-canonical/` directory, required files (CHANGELOG.md, DRIFT-LOG.md, AGENTS.md), and optionally sets a compliance profile.
+
+## User Input
+
+$ARGUMENTS
+
+## Steps
+
+1. Run DocGuard init on the current project:
+
+```bash
+npx --yes docguard-cli@latest init $ARGUMENTS
+```
+
+2. Choose a compliance profile:
+   - **starter** — Minimal CDD (architecture + changelog only)
+   - **standard** — Full CDD (all 5 canonical docs)
+   - **enterprise** — Strict CDD (all docs, all validators, freshness enforced)
+
+3. After init, run `speckit.docguard.generate` to populate the canonical docs with real data from your codebase.
+
+## Flags
+
+- `--profile <name>` — Set compliance profile (starter, standard, enterprise)
+- `--dir <path>` — Run on a different directory