docguard-cli 0.9.4 → 0.9.6

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

package/extensions/spec-kit-docguard/scripts/bash/docguard-init-doc.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# DocGuard — Initialize a new canonical document with metadata header
+# Copies template and adds DocGuard metadata scaffolding
+#
+# Usage:
+#   ./docguard-init-doc.sh <doc-name> [--json] [--version X.X.X]
+#
+# Examples:
+#   ./docguard-init-doc.sh architecture
+#   ./docguard-init-doc.sh security --json --version 0.5.0
+#
+# JSON output fields:
+#   DOC_PATH     — absolute path to created document
+#   DOC_NAME     — canonical document name
+#   TEMPLATE     — template used (if any)
+#   CREATED      — whether file was created (true/false)
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+JSON_MODE=false
+DOC_VERSION="0.1.0"
+DOC_NAME=""
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --json) JSON_MODE=true ;;
+        --version)
+            shift
+            DOC_VERSION="${1:-0.1.0}"
+            ;;
+        --help|-h)
+            echo "Usage: $0 <doc-name> [--json] [--version X.X.X]"
+            echo ""
+            echo "Document names: architecture, data-model, security, test-spec, environment, requirements"
+            echo ""
+            echo "Options:"
+            echo "  --json          Output in JSON format"
+            echo "  --version X.X.X Set initial version (default: 0.1.0)"
+            echo "  --help          Show this help"
+            exit 0
+            ;;
+        *)
+            if [ -z "$DOC_NAME" ]; then
+                DOC_NAME="$1"
+            else
+                echo "Error: Unexpected argument: $1" >&2
+                exit 1
+            fi
+            ;;
+    esac
+    shift
+done
+
+if [ -z "$DOC_NAME" ]; then
+    echo "Error: Document name required" >&2
+    echo "Usage: $0 <doc-name> [--json] [--version X.X.X]" >&2
+    exit 1
+fi
+
+# Normalize document name
+DOC_NAME_UPPER=$(echo "$DOC_NAME" | tr '[:lower:]' '[:upper:]' | tr '-' '-')
+DOC_FILE="docs-canonical/${DOC_NAME_UPPER}.md"
+
+# Find project root
+PROJECT_ROOT=$(find_docguard_root "$(pwd)") || {
+    echo "Error: No DocGuard project found." >&2
+    exit 1
+}
+
+cd "$PROJECT_ROOT"
+
+DOC_PATH="$PROJECT_ROOT/$DOC_FILE"
+CREATED=false
+TEMPLATE_USED=""
+
+# Check if file already exists
+if [ -f "$DOC_PATH" ]; then
+    if $JSON_MODE; then
+        echo "{\"docPath\":\"$(json_escape "$DOC_PATH")\",\"docName\":\"$(json_escape "$DOC_NAME_UPPER")\",\"created\":false,\"reason\":\"File already exists\"}"
+    else
+        echo "⚠ $DOC_FILE already exists. Use docguard fix to update it."
+    fi
+    exit 0
+fi
+
+# Ensure docs-canonical directory exists
+ensure_dir "$PROJECT_ROOT/docs-canonical"
+
+# Check for template
+TEMPLATE_DIR="$PROJECT_ROOT/templates"
+TEMPLATE_FILE="$TEMPLATE_DIR/${DOC_NAME_UPPER}.md"
+
+# Generate metadata header
+TODAY=$(today_iso)
+HEADER="# ${DOC_NAME_UPPER}
+
+<!-- docguard:version ${DOC_VERSION} -->
+<!-- docguard:status active -->
+<!-- docguard:last-reviewed ${TODAY} -->
+"
+
+if [ -f "$TEMPLATE_FILE" ]; then
+    # Use template, but replace/add metadata header
+    cp "$TEMPLATE_FILE" "$DOC_PATH"
+    TEMPLATE_USED="$TEMPLATE_FILE"
+    
+    # Ensure metadata header exists
+    if ! grep -q "docguard:version" "$DOC_PATH"; then
+        # Prepend metadata after first heading
+        tmp_file=$(mktemp)
+        head -1 "$DOC_PATH" > "$tmp_file"
+        echo "" >> "$tmp_file"
+        echo "<!-- docguard:version ${DOC_VERSION} -->" >> "$tmp_file"
+        echo "<!-- docguard:status active -->" >> "$tmp_file"
+        echo "<!-- docguard:last-reviewed ${TODAY} -->" >> "$tmp_file"
+        tail -n +2 "$DOC_PATH" >> "$tmp_file"
+        mv "$tmp_file" "$DOC_PATH"
+    fi
+    CREATED=true
+else
+    # Generate from scratch with skeleton
+    cat > "$DOC_PATH" << EOF
+${HEADER}
+<!-- ACTION REQUIRED: This is a skeleton document. Fill each section with
+     real project-specific content. Run 'docguard fix --doc ${DOC_NAME}' for
+     AI-generated guidance on what to write. -->
+
+## Overview
+
+[Describe the purpose of this document and what it covers]
+
+## Details
+
+[Add project-specific content here]
+
+## References
+
+- [Link to related documents or resources]
+EOF
+    CREATED=true
+fi
+
+if $JSON_MODE; then
+    echo "{\"docPath\":\"$(json_escape "$DOC_PATH")\",\"docName\":\"$(json_escape "$DOC_NAME_UPPER")\",\"template\":\"$(json_escape "$TEMPLATE_USED")\",\"created\":$CREATED,\"version\":\"$(json_escape "$DOC_VERSION")\"}"
+else
+    echo "✅ Created $DOC_FILE"
+    [ -n "$TEMPLATE_USED" ] && echo "   Template: $TEMPLATE_USED"
+    echo "   Version: $DOC_VERSION"
+    echo "   Next: Run 'docguard fix --doc $DOC_NAME' for content guidance"
+fi