docguard-cli 0.9.4 → 0.9.6

package/extensions/spec-kit-docguard/skills/docguard-score/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: docguard-score
+description: CDD maturity assessment with category-aware improvement roadmap. Runs scoring
+  engine, analyzes category breakdown, identifies highest-impact improvements, and
+  generates a before/after improvement plan with projected score gains.
+compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
+metadata:
+  author: docguard
+  version: 0.9.5
+  source: extensions/spec-kit-docguard/skills/docguard-score
+---
+
+# DocGuard Score Skill
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Run DocGuard's CDD maturity scoring engine, analyze the category breakdown, identify highest-ROI improvements, and produce an actionable improvement roadmap showing projected score gains per fix.
+
+## Execution Flow
+
+### Step 1: Run Scoring Engine
+
+Execute both tools for comprehensive data:
+
+```bash
+npx docguard-cli score 2>&1
+npx docguard-cli guard 2>&1
+```
+
+If in DocGuard dev environment:
+```bash
+node cli/docguard.mjs score 2>&1
+node cli/docguard.mjs guard 2>&1
+```
+
+### Step 2: Parse Score Breakdown
+
+Extract the category-level scores:
+
+| Category | Score | Weight | Points | Potential Gain |
+|----------|:-----:|:------:|:------:|:--------------:|
+| Structure | X% | ×25 | N | [25 - N] |
+| Doc Quality | X% | ×20 | N | [20 - N] |
+| Testing | X% | ×15 | N | [15 - N] |
+| Security | X% | ×10 | N | [10 - N] |
+| Environment | X% | ×10 | N | [10 - N] |
+| Drift | X% | ×10 | N | [10 - N] |
+| Changelog | X% | ×5 | N | [5 - N] |
+| Architecture | X% | ×5 | N | [5 - N] |
+
+Calculate `Potential Gain` for each category = (weight - current points).
+
+### Step 3: Grade Classification
+
+| Grade | Score | Description |
+|-------|:-----:|------------|
+| A+ | 95-100 | Exemplary — production-grade documentation, CDD fully adopted |
+| A | 85-94 | Strong — minor improvements possible, CI-gate ready |
+| B | 70-84 | Good — documentation covers essentials, some gaps exist |
+| C | 50-69 | Fair — significant documentation debt, multiple gaps |
+| D | 30-49 | Poor — major structural gaps, limited doc coverage |
+| F | 0-29 | Critical — documentation infrastructure missing |
+
+### Step 4: ROI-Based Improvement Roadmap
+
+Sort categories by `Potential Gain / Effort` ratio:
+
+For each category below 100%, calculate:
+- **Gap**: What checks are failing?
+- **Effort**: How hard is it to fix? (LOW = update metadata, MEDIUM = add content, HIGH = research + write)
+- **Impact**: Points gained if fixed to 100%
+- **ROI**: Impact / Effort ranking
+
+Generate an improvement plan ordered by ROI:
+
+```markdown
+### Improvement Roadmap
+
+| Priority | Category | Current | Target | Points Gain | Effort | Action |
+|:--------:|----------|:-------:|:------:|:-----------:|--------|--------|
+| 1 | Structure | 80% | 100% | +5 | LOW | Create REQUIREMENTS.md |
+| 2 | Changelog | 60% | 100% | +2 | LOW | Add missing entry for v0.9.5 |
+| 3 | Doc Quality | 85% | 100% | +3 | MEDIUM | Fix negation language in SECURITY.md |
+| 4 | Testing | 70% | 100% | +4.5 | HIGH | Add E2E test documentation |
+```
+
+### Step 5: Guard Check Correlation
+
+Cross-reference the score with guard results:
+
+- For each failing guard check, show which score category it impacts
+- Calculate: "If you fix these N guard warnings, score will increase from X to Y"
+- Show the **minimum set of fixes** needed to reach the next grade level
+
+```markdown
+### Path to Next Grade
+
+**Current**: B (78/100)
+**Next Grade**: A (85/100) — need +7 points
+
+**Minimum fixes for grade A**:
+1. Fix Structure (3 checks failing) → +5 points
+2. Fix Changelog (1 check failing) → +2 points
+Total effort: ~30 minutes
+```
+
+### Step 6: ALCOA+ Compliance Summary
+
+If the score engine reports ALCOA+ attributes, include:
+
+| Attribute | Status | Description |
+|-----------|--------|------------|
+| Attributable | ✅/❌ | Author information in metadata |
+| Legible | ✅/❌ | Readable formatting and structure |
+| Contemporaneous | ✅/❌ | Docs updated within freshness window |
+| Original | ✅/❌ | Primary source documentation |
+| Accurate | ✅/❌ | Content matches codebase |
+| Complete | ✅/❌ | All required sections present |
+| Consistent | ✅/❌ | No cross-document conflicts |
+| Enduring | ✅/❌ | Durable format (markdown, version controlled) |
+| Available | ✅/❌ | Accessible to all team members |
+
+### Step 7: Historical Comparison
+
+If user has run score before (check git log for score badge changes):
+
+```markdown
+### Score History
+| Date | Score | Grade | Change |
+|------|:-----:|:-----:|:------:|
+| 2026-03-14 | 100 | A+ | +22 |
+| 2026-03-13 | 78 | B | baseline |
+```
+
+### Step 8: Completion Report
+
+```markdown
+## CDD Maturity Assessment
+
+**Project**: [name]
+**Score**: [X]/100 ([grade])
+**Guard**: [N]/[M] checks passed
+**ALCOA+**: [N]/9 attributes met
+
+### Category Health
+[Table from Step 2]
+
+### Improvement Roadmap
+[Plan from Step 4]
+
+### Path to Next Grade
+[Analysis from Step 5]
+
+### Suggested Next Steps
+- `/docguard.fix` — Fix the top [N] issues automatically
+- `/docguard.review` — Deep semantic analysis for accuracy verification
+- `/docguard.guard` — Verify fixes pass all validators
+```
+
+## Behavior Rules
+
+- **ALWAYS run real CLI** — never simulate scores
+- **Show math** — explain how score is calculated (category × weight)
+- **Be actionable** — every recommendation must have a specific action
+- **Compare before/after** — if user has previously run score in this session, show improvement
+- **Focus on ROI** — surface the cheapest fixes with the biggest score impact first
+
+## Context
+
+$ARGUMENTS

package/extensions/spec-kit-docguard/templates/extensions.yml

@@ -0,0 +1,39 @@
+# DocGuard Extension Hooks for Spec Kit
+# Place this file at .specify/extensions.yml in your project root
+# to integrate DocGuard into the spec-kit workflow.
+#
+# DocGuard will automatically run as a quality gate after implementation
+# and optionally before task generation.
+
+schema_version: "1.0"
+
+extension: docguard
+
+hooks:
+  # Run DocGuard guard after /speckit.implement completes
+  # This ensures documentation stays in sync with code changes
+  after_implement:
+    - extension: docguard
+      command: docguard.guard
+      description: "Validate documentation passes CDD standards after implementation"
+      enabled: true
+      optional: false  # Mandatory — always runs after implement
+      prompt: "Run DocGuard guard to verify documentation quality after implementation changes"
+
+  # Run DocGuard review before /speckit.tasks to catch doc drift early
+  before_tasks:
+    - extension: docguard
+      command: docguard.review
+      description: "Review documentation consistency before generating tasks"
+      enabled: true
+      optional: true  # Optional — user can skip
+      prompt: "Run DocGuard review to check documentation health before task generation?"
+
+  # Run DocGuard guard after /speckit.tasks to validate doc coverage
+  after_tasks:
+    - extension: docguard
+      command: docguard.score
+      description: "Show CDD maturity score after task generation"
+      enabled: true
+      optional: true
+      prompt: "Check CDD maturity score after task generation?"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {
@@ -24,7 +24,8 @@
     "documentation",
     "governance",
     "ai-agents",
-    "spec-guard",
+    "spec-kit",
+    "spec-driven-development",
     "docguard",
     "validation",
     "cli",
@@ -47,6 +48,8 @@
   "files": [
     "cli/",
     "templates/",
+    "commands/",
+    "extensions/",
     "docs/",
     "STANDARD.md",
     "PHILOSOPHY.md",

package/templates/REQUIREMENTS.md.template

@@ -0,0 +1,68 @@
+# Requirements
+
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status draft -->
+
+> Tracks functional requirements, non-functional requirements, and success criteria.
+> Use requirement IDs (FR-001, NFR-001, SC-001) for traceability back to code and tests.
+
+![CDD Canonical](https://img.shields.io/badge/CDD-Canonical-blue)
+
+## Functional Requirements
+
+<!-- List functional requirements with FR-NNN IDs -->
+
+| ID | Priority | Requirement | Status | Test Coverage |
+|----|----------|-------------|--------|---------------|
+| FR-001 | P1 | System MUST [capability] | 🔴 Draft | ❌ |
+| FR-002 | P1 | System MUST [capability] | 🔴 Draft | ❌ |
+| FR-003 | P2 | Users MUST be able to [interaction] | 🔴 Draft | ❌ |
+
+## Non-Functional Requirements
+
+<!-- Quality attributes: performance, security, reliability -->
+
+| ID | Category | Requirement | Metric |
+|----|----------|-------------|--------|
+| NFR-001 | Performance | Response time < 200ms p95 | Measured via [tool] |
+| NFR-002 | Security | All endpoints require authentication | Validated by guard |
+| NFR-003 | Reliability | 99.9% uptime SLA | Monitored via [tool] |
+
+## Success Criteria
+
+<!-- Measurable outcomes — aligned with spec-kit SC-NNN format -->
+
+| ID | Criteria | Measurement | Target |
+|----|----------|-------------|--------|
+| SC-001 | [Measurable user outcome] | [How measured] | [Target value] |
+| SC-002 | [Performance metric] | [How measured] | [Target value] |
+
+## User Scenarios
+
+<!-- Spec-kit aligned: Given/When/Then acceptance scenarios -->
+
+### User Story 1 - [Title] (Priority: P1)
+
+[Description of user journey]
+
+**Acceptance Scenarios**:
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+## Traceability Matrix
+
+<!-- Maps requirements → code → tests -->
+
+| Requirement | Source File | Test File | Status |
+|-------------|------------|-----------|--------|
+| FR-001 | `src/[file]` | `tests/[file]` | ❌ |
+
+## Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 0.1.0 | YYYY-MM-DD | DocGuard Init | Initial template |
+
+---
+
+*Generated by [DocGuard](https://github.com/raccioly/docguard) — aligned with [Spec Kit](https://github.com/github/spec-kit) standards.*

package/templates/commands/docguard.fix.md

@@ -1,65 +1,61 @@
-# /docguard.fix — Find and fix all CDD documentation issues
+---
+description: Find and fix all CDD documentation issues using AI-driven research
+handoffs:
+  - label: Verify Fixes
+    agent: docguard.guard
+    prompt: Run guard to verify all fixes pass
+  - label: Check Score
+    agent: docguard.score
+    prompt: Show score improvement after fixes
+---
 
-You are an AI agent responsible for maintaining documentation quality using DocGuard (Canonical-Driven Development).
+# /docguard.fix — Find and Fix CDD Documentation Issues
 
-## Step 1: Assess Current State
+You are an AI agent responsible for maintaining documentation quality using DocGuard.
 
-Run this command and read the output:
+## Step 1: Assess Current State
 
 ```bash
-npx docguard fix --format json
+npx docguard-cli diagnose
 ```
 
-Parse the JSON result. It will contain:
-- `issueCount`: total number of issues
-- `issues[]`: each issue with `type`, `severity`, `file`, and `fix.ai_instruction`
+Parse the output to identify all issues — categorized as errors or warnings with AI-ready fix prompts.
 
-If `issueCount` is 0, report "All CDD documentation is up to date" and stop.
+If no issues found, report "All CDD documentation is up to date" and stop.
 
 ## Step 2: Fix Each Issue
 
-For each issue in the JSON output:
-
-### If type is `missing-file`:
-Run `npx docguard fix --auto` first to create skeleton files, then continue to Step 3.
+For each issue, determine the fix type:
 
-### If type is `empty-doc` or `partial-doc`:
-The document exists but has template placeholders or insufficient content.
-Proceed to Step 3 for this document.
+| Issue Type | Action |
+|-----------|--------|
+| `missing-file` | Run `npx docguard-cli fix --doc <name>` to generate |
+| `empty-doc` / `partial-doc` | Proceed to Step 3 for codebase research |
+| `missing-config` | Create `.docguard.json` based on project type |
+| `stale-doc` | Update `docguard:last-reviewed` date and content |
+| `quality-issue` | Fix negation language, add missing sections |
 
-### If type is `missing-config`:
-Create `.docguard.json` based on the project. Detect the project type from `package.json`.
+## Step 3: Write Real Content
 
-## Step 3: Write Real Content for Each Document
-
-For each document that needs content, run:
+For each document that needs content:
 
 ```bash
-npx docguard fix --doc <name>
+npx docguard-cli fix --doc <name>
 ```
 
-Where `<name>` is one of: `architecture`, `data-model`, `security`, `test-spec`, `environment`
+Where `<name>` is: `architecture`, `data-model`, `security`, `test-spec`, `environment`
 
 Read the output carefully — it contains:
-- **RESEARCH STEPS**: Exactly what files to read and commands to run to understand the project
-- **WRITE THE DOCUMENT**: The expected structure and content for each section
-
-Execute the research steps, then write the document with REAL project content. No placeholders.
-
-## Step 4: Verify
-
-After fixing all documents, run:
-
-```bash
-npx docguard guard
-```
+- **RESEARCH STEPS**: Exactly what files to read and commands to run
+- **WRITE THE DOCUMENT**: Expected structure and content for each section
 
-All checks should pass. If any fail, read the output and fix the remaining issues.
+Execute the research steps, then write with REAL project content. No placeholders.
 
-Then run:
+## Step 4: Verify (Iterate up to 3 times)
 
 ```bash
-npx docguard score
+npx docguard-cli guard
+npx docguard-cli score
 ```
 
-Report the final CDD score to the user.
+All checks should pass. If any fail, read the output and fix remaining issues. Report the final CDD score.

package/templates/commands/docguard.guard.md

@@ -1,33 +1,46 @@
-# /docguard.guard — Validate CDD compliance and fix any issues
+---
+description: Run DocGuard guard validation — check all 19 validators and fix any issues
+handoffs:
+  - label: Fix Issues
+    agent: docguard.fix
+    prompt: Fix all documentation issues found by guard
+  - label: Check Score
+    agent: docguard.score
+    prompt: Show CDD maturity score after fixes
+---
+
+# /docguard.guard — Validate CDD Compliance
 
 You are an AI agent enforcing Canonical-Driven Development (CDD) compliance using DocGuard.
 
 ## Step 1: Run Guard
 
 ```bash
-npx docguard guard
+npx docguard-cli guard
 ```
 
-Read the output. It shows pass/fail for each validator:
-- Structure, Doc Sections, Docs-Sync, Drift, Changelog, Test-Spec, Environment, Freshness
+Read the output. It shows pass (✅), warn (⚠️), or fail (❌) for each of the 19 validators:
+
+| Priority | Validators |
+|----------|-----------|
+| CRITICAL | Structure, Security, Test-Spec |
+| HIGH | Doc Sections, Drift, Changelog, Traceability |
+| MEDIUM | Freshness, Docs-Coverage, Doc-Quality, Metrics-Consistency |
+| LOW | TODO-Tracking, Schema-Sync, Spec-Kit, Metadata-Sync |
 
 ## Step 2: Handle Results
 
 ### If all checks pass:
 Report success and the score:
 ```bash
-npx docguard score
+npx docguard-cli score
 ```
 
 ### If checks fail:
-Run the fix workflow:
-```bash
-npx docguard fix
-```
-
-Read the output to understand what needs fixing. For documents that need real content:
+For each failing check, provide an **exact fix** — specific file, section, and content.
+Then run the fix workflow:
 ```bash
-npx docguard fix --doc <name>
+npx docguard-cli fix --doc <name>
 ```
 
 Execute the research steps in the output, write real content, then re-run guard to verify.
@@ -35,6 +48,6 @@ Execute the research steps in the output, write real content, then re-run guard
 ## Step 3: Report
 
 Show the user:
-1. Which checks passed/failed
+1. Which checks passed/failed (with severity)
 2. What was fixed
 3. Final CDD score

package/templates/commands/docguard.init.md

@@ -1,54 +1,61 @@
-# /docguard.init — Set up CDD documentation for this project
+---
+description: Initialize Canonical-Driven Development in a new or existing project
+handoffs:
+  - label: Generate Docs
+    agent: docguard.fix
+    prompt: Generate and populate all canonical documentation from codebase
+  - label: Check Status
+    agent: docguard.guard
+    prompt: Run guard to see initial documentation status
+---
 
-You are an AI agent initializing Canonical-Driven Development (CDD) for a new or existing project using DocGuard.
+# /docguard.init — Set Up CDD Documentation
+
+You are an AI agent initializing Canonical-Driven Development (CDD) for a new or existing project.
 
 ## Step 1: Initialize Skeleton Files
 
 ```bash
-npx docguard init
+npx docguard-cli init
 ```
 
-This creates the folder structure and template files. But the templates are EMPTY — they need real content.
+This creates the folder structure and template files. The templates are skeletons — they need real content.
 
 ## Step 2: Detect and Configure Project Type
 
-Create `.docguard.json` based on what you find:
-
 ```bash
 cat package.json
 ```
 
-Determine:
-- `projectType`: "cli" (has `bin` field), "webapp" (has react/next/vue), "api" (has express/fastify), or "library" (default)
-- `needsE2E`: true for webapps, false for CLIs/libraries
-- `needsEnvVars`: true for APIs/webapps with env config, false for CLIs
-- `needsDatabase`: true if database dependencies found
+Create `.docguard.json` based on what you find:
 
-Write `.docguard.json` with these settings.
+| Signal | Setting |
+|--------|---------|
+| Has `bin` field | `projectType: "cli"` |
+| Has react/next/vue | `projectType: "webapp"`, `needsE2E: true` |
+| Has express/fastify | `projectType: "api"`, `needsEnvVars: true` |
+| Has database deps | `needsDatabase: true` |
+| Default | `projectType: "library"` |
 
 ## Step 3: Write Real Documentation
 
-For each canonical document, generate an AI prompt and write real content:
+For each canonical document, generate a research prompt and write real content:
 
 ```bash
-npx docguard fix --doc architecture
+npx docguard-cli fix --doc architecture
+npx docguard-cli fix --doc data-model
+npx docguard-cli fix --doc security
+npx docguard-cli fix --doc test-spec
+npx docguard-cli fix --doc environment
 ```
 
-Read the output, execute the RESEARCH STEPS, then write the ARCHITECTURE.md with real project content.
-
-Repeat for each document:
-```bash
-npx docguard fix --doc data-model
-npx docguard fix --doc security
-npx docguard fix --doc test-spec
-npx docguard fix --doc environment
-```
+For each: read the output, execute RESEARCH STEPS, then write with real project content.
 
-## Step 4: Verify Everything
+## Step 4: Verify
 
 ```bash
-npx docguard guard
-npx docguard score
+npx docguard-cli guard
+npx docguard-cli score
 ```
 
 All checks should pass. Report the final score.
@@ -56,7 +63,7 @@ All checks should pass. Report the final score.
 ## Step 5: Set Up Git Hooks (Optional)
 
 ```bash
-npx docguard hooks
+npx docguard-cli hooks
 ```
 
-This installs pre-commit (guard), pre-push (score), and commit-msg (conventional commits) hooks.
+Installs pre-commit (guard), pre-push (score), and commit-msg (conventional commits) hooks.

package/templates/commands/docguard.review.md

@@ -1,44 +1,54 @@
-# /docguard.review — Review documentation vs code for drift
+---
+description: Review documentation quality — identify drift, coverage gaps, and improvements
+handoffs:
+  - label: Fix Issues
+    agent: docguard.fix
+    prompt: Fix the documentation issues identified in the review
+  - label: Run Guard
+    agent: docguard.guard
+    prompt: Validate all checks pass after review
+---
+
+# /docguard.review — Review Documentation vs Code
 
 You are an AI agent reviewing documentation quality and detecting drift between docs and code.
 
-## Step 1: Run Diff
+## Step 1: Run Diagnostics
 
 ```bash
-npx docguard diff
+npx docguard-cli diagnose
+npx docguard-cli diff
+npx docguard-cli score
 ```
 
-Read the output carefully. It shows where documentation no longer matches the codebase.
+Read all output. Identify where documentation no longer matches the codebase.
 
-## Step 2: Run Guard
+## Step 2: Semantic Analysis (Beyond CLI)
 
-```bash
-npx docguard guard
-```
-
-Note any failed validators — these indicate docs that need updating.
-
-## Step 3: Check Freshness
+For each canonical doc, verify alignment with actual code:
 
-For each file listed in the guard output with a freshness warning:
-1. Read the document
-2. Read the related source code
-3. Compare: does the doc accurately describe the current code?
-4. If not, update the doc to match reality
+| Analysis | What to Check |
+|----------|--------------|
+| Architecture ↔ Code | Components in ARCHITECTURE.md exist as real modules |
+| Data Model ↔ Code | Schemas in DATA-MODEL.md match actual implementations |
+| Security Claims | Auth mechanisms in SECURITY.md match actual code |
+| Test Coverage | Critical flows in TEST-SPEC.md have actual test files |
+| Terminology | Same concepts named consistently across all docs |
 
-## Step 4: Update Stale Docs
+## Step 3: Update Stale Docs
 
 For each stale or drifted document:
 1. Read the relevant source code files
-2. Update the document to match current implementation
+2. Update the specific section that changed
 3. Update the `docguard:last-reviewed` date to today
 4. If the change is intentional drift, add an entry to DRIFT-LOG.md
+5. Add entry to CHANGELOG.md under [Unreleased]
 
-## Step 5: Verify
+## Step 4: Verify
 
 ```bash
-npx docguard guard
-npx docguard score
+npx docguard-cli guard
+npx docguard-cli score
 ```
 
-Report the final results to the user.
+Report findings, changes made, and the final score.