docguard-cli 0.9.5 → 0.9.6

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

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

@@ -0,0 +1,53 @@
+---
+description: "Calculate CDD maturity score with multi-signal quality breakdown"
+handoffs:
+  - label: Improve Score
+    agent: docguard.fix
+    prompt: Fix highest-ROI documentation issues to improve score
+  - label: Deep Review
+    agent: docguard.review
+    prompt: Perform semantic analysis for accuracy verification
+---
+
+# DocGuard Score
+
+Calculate your project's Canonical-Driven Development maturity score (0-100) across 8 weighted categories.
+
+## User Input
+
+$ARGUMENTS
+
+## Steps
+
+1. Run DocGuard score on the current project:
+
+```bash
+npx --yes docguard-cli@latest score $ARGUMENTS
+```
+
+2. Review the breakdown:
+   - **Structure** (25%) — required files present
+   - **Doc Quality** (20%) — docs have required sections
+   - **Testing** (15%) — test spec alignment
+   - **Security** (10%) — no hardcoded secrets
+   - **Environment** (10%) — env docs configured
+   - **Drift** (10%) — drift tracking discipline
+   - **Changelog** (5%) — changelog maintenance
+   - **Architecture** (5%) — layer boundary compliance
+
+3. For per-signal quality labels, add `--signals`.
+
+## Grading
+
+| Score | Grade | Status |
+|-------|-------|--------|
+| 90-100 | A | Strong CDD compliance |
+| 75-89 | B | Good, some gaps |
+| 50-74 | C | Needs work |
+| < 50 | D | Significant gaps |
+
+## Flags
+
+- `--signals` — Show multi-signal CJE composite breakdown with quality labels
+- `--tax` — Show estimated maintenance effort
+- `--format json` — Output as JSON

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

@@ -0,0 +1,56 @@
+---
+description: "Generate requirements traceability matrix"
+handoffs:
+  - label: Fix Coverage Gaps
+    agent: docguard.fix
+    prompt: Fix traceability gaps found in the matrix
+  - label: Run Guard
+    agent: docguard.guard
+    prompt: Validate traceability checks pass
+---
+
+# DocGuard Trace
+
+Generate a requirements traceability matrix mapping canonical docs ↔ source code ↔ tests. Config-aware — respects `.docguard.json` exclusions and detects orphaned files.
+
+## User Input
+
+$ARGUMENTS
+
+## Steps
+
+1. Run DocGuard trace on the current project:
+
+```bash
+npx --yes docguard-cli@latest trace $ARGUMENTS
+```
+
+2. Review the matrix. Each canonical doc gets a coverage signal:
+   - **TRACED** — doc + source code + tests all linked
+   - **PARTIAL** — doc exists, source found, no test coverage
+   - **UNLINKED** — doc exists but no matching source code
+   - **MISSING** — doc not found
+
+3. Orphaned files (exist but excluded from config) are flagged with cleanup instructions.
+
+## Standards
+
+Maps against industry standards per document type:
+
+| Document | Standard |
+|----------|----------|
+| ARCHITECTURE.md | arc42 / C4 Model |
+| DATA-MODEL.md | C4 Component / ER (Chen) |
+| TEST-SPEC.md | ISO/IEC/IEEE 29119-3 |
+| SECURITY.md | OWASP ASVS v4.0 |
+| ENVIRONMENT.md | 12-Factor App |
+| API-REFERENCE.md | OpenAPI 3.1 |
+
+## Flags
+
+- `--format json` — Output as JSON
+- `--dir <path>` — Run on a different directory
+
+## Research
+
+Inspired by ISO/IEC/IEEE 29119 traceability requirements (Lopez et al., AITPG, IEEE TSE 2026).

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

@@ -0,0 +1,109 @@
+schema_version: "1.0"
+
+extension:
+  id: "docguard"
+  name: "DocGuard — CDD Enforcement"
+  version: "0.9.6"
+  description: "Canonical-Driven Development enforcement with enterprise-grade AI skills. 19 automated validators, structured research workflows, quality validation loops, and spec-kit integration hooks. Zero dependencies."
+  author: "Ricardo Accioly"
+  repository: "https://github.com/raccioly/docguard"
+  license: "MIT"
+  homepage: "https://www.npmjs.com/package/docguard-cli"
+
+requires:
+  speckit_version: ">=0.1.0"
+  tools:
+    - name: "node"
+      required: true
+      version: ">=18.0.0"
+    - name: "npx"
+      required: true
+
+provides:
+  commands:
+    - name: "docguard.guard"
+      file: "commands/guard.md"
+      description: "Run 19-validator quality gate with severity triage and remediation plan"
+      aliases: ["speckit.docguard.guard"]
+
+    - name: "docguard.fix"
+      file: "commands/fix.md"
+      description: "AI-driven documentation repair with codebase research and validation loops"
+      aliases: ["speckit.docguard.fix"]
+
+    - name: "docguard.review"
+      file: "commands/review.md"
+      description: "Cross-document semantic consistency analysis (read-only)"
+      aliases: ["speckit.docguard.review"]
+
+    - name: "docguard.score"
+      file: "commands/score.md"
+      description: "CDD maturity score with ROI-based improvement roadmap"
+      aliases: ["speckit.docguard.score"]
+
+    - name: "speckit.docguard.diagnose"
+      file: "commands/review.md"
+      description: "Diagnose all issues and generate a complete AI remediation plan"
+
+    - name: "speckit.docguard.generate"
+      file: "commands/fix.md"
+      description: "Reverse-engineer canonical docs from existing codebase"
+
+  skills:
+    - name: "docguard-guard"
+      path: "skills/docguard-guard/SKILL.md"
+      description: "19-validator quality gate with severity triage and structured reporting"
+
+    - name: "docguard-fix"
+      path: "skills/docguard-fix/SKILL.md"
+      description: "AI-driven documentation repair with research workflow and validation loops"
+
+    - name: "docguard-review"
+      path: "skills/docguard-review/SKILL.md"
+      description: "Cross-document semantic consistency analysis with quality scoring"
+
+    - name: "docguard-score"
+      path: "skills/docguard-score/SKILL.md"
+      description: "CDD maturity assessment with ROI-based improvement roadmap"
+
+  scripts:
+    - name: "docguard-check-docs"
+      path: "scripts/bash/docguard-check-docs.sh"
+      description: "Discover project docs, return JSON inventory with metadata"
+
+    - name: "docguard-suggest-fix"
+      path: "scripts/bash/docguard-suggest-fix.sh"
+      description: "Run guard, parse results, output prioritized fix suggestions"
+
+    - name: "docguard-init-doc"
+      path: "scripts/bash/docguard-init-doc.sh"
+      description: "Initialize a new canonical document with metadata header"
+
+hooks:
+  after_implement:
+    command: "docguard.guard"
+    optional: false
+    prompt: "Run DocGuard validation after implementation"
+    description: "Mandatory quality gate — ensures docs stay in sync with code"
+
+  before_tasks:
+    command: "docguard.review"
+    optional: true
+    prompt: "Review documentation consistency before generating tasks?"
+
+  after_tasks:
+    command: "docguard.score"
+    optional: true
+    prompt: "Show CDD maturity score after task generation?"
+
+tags:
+  - "documentation"
+  - "validation"
+  - "quality"
+  - "cdd"
+  - "spec-driven"
+  - "traceability"
+  - "ai-agents"
+  - "enforcement"
+  - "spec-kit"
+  - "skills"

package/extensions/spec-kit-docguard/scripts/bash/common.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# DocGuard — Shared utilities for bash scripts
+# Used by all DocGuard orchestration scripts
+
+set -e
+
+# ── Project Root Detection ─────────────────────────────────────────────────
+
+find_docguard_root() {
+    local dir="${1:-$(pwd)}"
+    while [ "$dir" != "/" ]; do
+        # Check for DocGuard project markers
+        if [ -d "$dir/docs-canonical" ] || [ -f "$dir/.docguard.json" ] || [ -f "$dir/CHANGELOG.md" ]; then
+            echo "$dir"
+            return 0
+        fi
+        dir="$(dirname "$dir")"
+    done
+    return 1
+}
+
+# ── DocGuard CLI Detection ─────────────────────────────────────────────────
+
+find_docguard_cli() {
+    local root="${1:-$(pwd)}"
+    
+    # Check for local dev mode first
+    if [ -f "$root/cli/docguard.mjs" ]; then
+        echo "node $root/cli/docguard.mjs"
+        return 0
+    fi
+    
+    # Check for global install
+    if command -v docguard-cli >/dev/null 2>&1; then
+        echo "docguard-cli"
+        return 0
+    fi
+    
+    # Fall back to npx
+    if command -v npx >/dev/null 2>&1; then
+        echo "npx docguard-cli"
+        return 0
+    fi
+    
+    return 1
+}
+
+# ── JSON Escape ────────────────────────────────────────────────────────────
+
+json_escape() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    s="${s//$'\n'/\\n}"
+    s="${s//$'\t'/\\t}"
+    s="${s//$'\r'/\\r}"
+    printf '%s' "$s"
+}
+
+# ── JSON Output Helper ────────────────────────────────────────────────────
+
+json_output() {
+    # Build JSON from key=value pairs
+    # Usage: json_output key1 "value1" key2 "value2"
+    local result="{"
+    local first=true
+    while [ $# -ge 2 ]; do
+        if [ "$first" = true ]; then
+            first=false
+        else
+            result="$result,"
+        fi
+        result="$result\"$1\":\"$(json_escape "$2")\""
+        shift 2
+    done
+    result="$result}"
+    echo "$result"
+}
+
+# ── Date Helpers ───────────────────────────────────────────────────────────
+
+today_iso() {
+    date +%Y-%m-%d
+}
+
+# ── File Helpers ───────────────────────────────────────────────────────────
+
+file_exists() {
+    [ -f "$1" ]
+}
+
+dir_exists() {
+    [ -d "$1" ]
+}
+
+ensure_dir() {
+    mkdir -p "$1"
+}
+
+# ── Metadata Helpers ──────────────────────────────────────────────────────
+
+extract_metadata() {
+    local file="$1"
+    local key="$2"
+    grep "docguard:${key}" "$file" 2>/dev/null | sed "s/.*docguard:${key} //" | sed 's/ -->//' | tr -d '\r'
+}

package/extensions/spec-kit-docguard/scripts/bash/docguard-check-docs.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# DocGuard — Check project documentation status
+# Returns JSON with document inventory and health status
+#
+# Usage:
+#   ./docguard-check-docs.sh [--json] [--verbose]
+#
+# JSON output fields:
+#   PROJECT_ROOT  — absolute path to project root
+#   CLI_CMD       — command to run DocGuard CLI
+#   DOCS          — array of {name, path, exists, version, status, lastReviewed}
+#   SCORE         — CDD maturity score (if --verbose)
+#   GUARD_PASS    — number of passing guard checks (if --verbose)
+#   GUARD_TOTAL   — total guard checks (if --verbose)
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+JSON_MODE=false
+VERBOSE=false
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --json) JSON_MODE=true ;;
+        --verbose) VERBOSE=true ;;
+        --help|-h)
+            echo "Usage: $0 [--json] [--verbose]"
+            echo ""
+            echo "Options:"
+            echo "  --json     Output in JSON format for AI consumption"
+            echo "  --verbose  Include score and guard results"
+            echo "  --help     Show this help message"
+            exit 0
+            ;;
+        *) echo "Unknown option: $1" >&2; exit 1 ;;
+    esac
+    shift
+done
+
+# Find project root
+PROJECT_ROOT=$(find_docguard_root "$(pwd)") || {
+    echo "Error: No DocGuard project found. Run 'docguard init' first." >&2
+    exit 1
+}
+
+# Find CLI command
+CLI_CMD=$(find_docguard_cli "$PROJECT_ROOT") || {
+    echo "Error: DocGuard CLI not found. Install with: npm i -g docguard-cli" >&2
+    exit 1
+}
+
+cd "$PROJECT_ROOT"
+
+# Canonical documents to check
+CANONICAL_DOCS=(
+    "docs-canonical/ARCHITECTURE.md"
+    "docs-canonical/DATA-MODEL.md"
+    "docs-canonical/SECURITY.md"
+    "docs-canonical/TEST-SPEC.md"
+    "docs-canonical/ENVIRONMENT.md"
+    "docs-canonical/REQUIREMENTS.md"
+)
+
+# Support documents
+SUPPORT_DOCS=(
+    "CHANGELOG.md"
+    "DRIFT-LOG.md"
+    "AGENTS.md"
+    "README.md"
+    "ROADMAP.md"
+)
+
+if $JSON_MODE; then
+    # Build canonical docs JSON array
+    DOCS_JSON="["
+    first=true
+    for doc in "${CANONICAL_DOCS[@]}" "${SUPPORT_DOCS[@]}"; do
+        if [ "$first" = true ]; then first=false; else DOCS_JSON="$DOCS_JSON,"; fi
+        
+        doc_name=$(basename "$doc" .md)
+        doc_path="$PROJECT_ROOT/$doc"
+        doc_exists="false"
+        doc_version=""
+        doc_status=""
+        doc_reviewed=""
+        
+        if [ -f "$doc_path" ]; then
+            doc_exists="true"
+            doc_version=$(extract_metadata "$doc_path" "version" 2>/dev/null || echo "")
+            doc_status=$(extract_metadata "$doc_path" "status" 2>/dev/null || echo "")
+            doc_reviewed=$(extract_metadata "$doc_path" "last-reviewed" 2>/dev/null || echo "")
+        fi
+        
+        DOCS_JSON="$DOCS_JSON{\"name\":\"$(json_escape "$doc_name")\",\"path\":\"$(json_escape "$doc")\",\"exists\":$doc_exists"
+        [ -n "$doc_version" ] && DOCS_JSON="$DOCS_JSON,\"version\":\"$(json_escape "$doc_version")\""
+        [ -n "$doc_status" ] && DOCS_JSON="$DOCS_JSON,\"status\":\"$(json_escape "$doc_status")\""
+        [ -n "$doc_reviewed" ] && DOCS_JSON="$DOCS_JSON,\"lastReviewed\":\"$(json_escape "$doc_reviewed")\""
+        DOCS_JSON="$DOCS_JSON}"
+    done
+    DOCS_JSON="$DOCS_JSON]"
+    
+    # Optionally include score and guard
+    EXTRAS=""
+    if $VERBOSE; then
+        SCORE_OUTPUT=$(eval $CLI_CMD score --format json 2>/dev/null || echo "")
+        GUARD_OUTPUT=$(eval $CLI_CMD guard 2>&1 || true)
+        
+        # Extract score
+        SCORE=$(echo "$SCORE_OUTPUT" | grep -o '"total":[0-9]*' | head -1 | sed 's/"total"://' || echo "0")
+        
+        # Extract guard pass/total from output like "156/160 passed"
+        GUARD_PASS=$(echo "$GUARD_OUTPUT" | grep -o '[0-9]*/[0-9]* passed' | sed 's|/.*||' || echo "0")
+        GUARD_TOTAL=$(echo "$GUARD_OUTPUT" | grep -o '[0-9]*/[0-9]* passed' | sed 's|.*/||; s| .*||' || echo "0")
+        
+        EXTRAS=",\"score\":$SCORE,\"guardPass\":$GUARD_PASS,\"guardTotal\":$GUARD_TOTAL"
+    fi
+    
+    # Check for spec-kit
+    HAS_SPECKIT="false"
+    [ -d "$PROJECT_ROOT/.specify" ] && HAS_SPECKIT="true"
+    
+    echo "{\"projectRoot\":\"$(json_escape "$PROJECT_ROOT")\",\"cliCommand\":\"$(json_escape "$CLI_CMD")\",\"hasSpecKit\":$HAS_SPECKIT,\"docs\":$DOCS_JSON$EXTRAS}"
+else
+    echo "DocGuard Project: $PROJECT_ROOT"
+    echo "CLI: $CLI_CMD"
+    echo ""
+    echo "Canonical Documents:"
+    for doc in "${CANONICAL_DOCS[@]}"; do
+        if [ -f "$PROJECT_ROOT/$doc" ]; then
+            version=$(extract_metadata "$PROJECT_ROOT/$doc" "version" 2>/dev/null || echo "?")
+            reviewed=$(extract_metadata "$PROJECT_ROOT/$doc" "last-reviewed" 2>/dev/null || echo "?")
+            echo "  ✅ $doc (v$version, reviewed: $reviewed)"
+        else
+            echo "  ❌ $doc (MISSING)"
+        fi
+    done
+    echo ""
+    echo "Support Documents:"
+    for doc in "${SUPPORT_DOCS[@]}"; do
+        if [ -f "$PROJECT_ROOT/$doc" ]; then
+            echo "  ✅ $doc"
+        else
+            echo "  ❌ $doc (MISSING)"
+        fi
+    done
+    
+    if $VERBOSE; then
+        echo ""
+        eval $CLI_CMD score 2>&1 || true
+    fi
+fi