docguard-cli 0.9.5 → 0.9.7

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

package/extensions/spec-kit-docguard/scripts/bash/docguard-suggest-fix.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# DocGuard — Suggest fixes based on guard/diagnose results
+# Runs guard, parses results, outputs prioritized fix suggestions as JSON
+#
+# Usage:
+#   ./docguard-suggest-fix.sh [--json] [--top N]
+#
+# JSON output fields:
+#   GUARD_PASS    — number of passing checks
+#   GUARD_TOTAL   — total checks
+#   FINDINGS      — array of {validator, severity, message, fix}
+#   TOP_FIX       — the single highest-impact fix suggestion
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+JSON_MODE=false
+TOP_N=5
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --json) JSON_MODE=true ;;
+        --top)
+            shift
+            TOP_N="${1:-5}"
+            ;;
+        --help|-h)
+            echo "Usage: $0 [--json] [--top N]"
+            echo ""
+            echo "Options:"
+            echo "  --json     Output in JSON format"
+            echo "  --top N    Show top N fix suggestions (default: 5)"
+            echo "  --help     Show this help"
+            exit 0
+            ;;
+        *) echo "Unknown option: $1" >&2; exit 1 ;;
+    esac
+    shift
+done
+
+# Find project
+PROJECT_ROOT=$(find_docguard_root "$(pwd)") || {
+    echo "Error: No DocGuard project found." >&2
+    exit 1
+}
+
+CLI_CMD=$(find_docguard_cli "$PROJECT_ROOT") || {
+    echo "Error: DocGuard CLI not found." >&2
+    exit 1
+}
+
+cd "$PROJECT_ROOT"
+
+# Run guard and capture output
+GUARD_OUTPUT=$(eval $CLI_CMD guard 2>&1 || true)
+
+# Parse pass/total
+GUARD_SUMMARY=$(echo "$GUARD_OUTPUT" | grep -o '[0-9]*/[0-9]* passed' || echo "0/0 passed")
+GUARD_PASS=$(echo "$GUARD_SUMMARY" | sed 's|/.*||')
+GUARD_TOTAL=$(echo "$GUARD_SUMMARY" | sed 's|.*/||; s| .*||')
+
+# Extract warnings and failures
+FINDINGS="[]"
+if echo "$GUARD_OUTPUT" | grep -q "⚠\|❌"; then
+    # Extract warning/failure lines with validator context
+    FINDING_LINES=$(echo "$GUARD_OUTPUT" | grep -A1 "⚠\|❌" | grep "⚠ \|❌ " || true)
+    
+    if [ -n "$FINDING_LINES" ]; then
+        FINDINGS="["
+        first=true
+        count=0
+        while IFS= read -r line; do
+            [ $count -ge $TOP_N ] && break
+            if [ "$first" = true ]; then first=false; else FINDINGS="$FINDINGS,"; fi
+            
+            # Clean the line
+            clean_line=$(echo "$line" | sed 's/^[[:space:]]*//' | sed 's/⚠ //' | sed 's/❌ //')
+            
+            # Determine severity
+            severity="MEDIUM"
+            echo "$line" | grep -q "❌" && severity="CRITICAL"
+            echo "$line" | grep -qi "security\|secret" && severity="CRITICAL"
+            echo "$line" | grep -qi "structure\|missing" && severity="HIGH"
+            
+            FINDINGS="$FINDINGS{\"message\":\"$(json_escape "$clean_line")\",\"severity\":\"$severity\"}"
+            count=$((count + 1))
+        done <<< "$FINDING_LINES"
+        FINDINGS="$FINDINGS]"
+    fi
+fi
+
+if $JSON_MODE; then
+    echo "{\"guardPass\":$GUARD_PASS,\"guardTotal\":$GUARD_TOTAL,\"findings\":$FINDINGS}"
+else
+    echo "Guard: $GUARD_PASS/$GUARD_TOTAL passed"
+    echo ""
+    if [ "$GUARD_PASS" = "$GUARD_TOTAL" ]; then
+        echo "✅ All checks passed! No fixes needed."
+    else
+        echo "Suggested fixes (top $TOP_N):"
+        echo "$GUARD_OUTPUT" | grep "⚠ \|❌ " | head -$TOP_N | while IFS= read -r line; do
+            echo "  → $(echo "$line" | sed 's/^[[:space:]]*//')"
+        done
+    fi
+fi

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

@@ -0,0 +1,218 @@
+---
+name: docguard-fix
+description: AI-driven documentation repair with structured research workflow, template-aware
+  generation, and quality validation loops. Generates or fixes canonical documentation
+  by researching the actual codebase, not using placeholders. Iterates until guard passes.
+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-fix
+---
+
+# DocGuard Fix Skill
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+If user specifies `--doc <name>`, focus on that single document.
+If no arguments, fix ALL issues found by `docguard diagnose`.
+
+## Goal
+
+Research the actual codebase to generate or repair canonical documentation that passes DocGuard's 19-validator guard suite. This skill replaces generic templates with real, project-specific content and iterates until quality checks pass.
+
+## Operating Constraints
+
+- **NEVER use placeholder content** — every section must reference real files, real modules, real dependencies
+- **ALWAYS back up before overwriting** — use `safeWrite()` pattern or create `.bak` files
+- **Maximum 3 validation iterations** — if still failing after 3 rounds, report remaining issues and stop
+- **Research before writing** — understand the codebase first, then generate documentation
+
+## Execution Flow
+
+### Step 1: Diagnose Current State
+
+Run the diagnostic to identify all issues:
+
+```bash
+npx docguard-cli diagnose 2>&1
+```
+
+Parse the output to build an issue inventory:
+
+| Issue ID | Severity | Category | File | Description | Autofix? |
+|----------|----------|----------|------|-------------|----------|
+| I001 | ERROR | Structure | SECURITY.md | Missing file | Yes |
+| I002 | WARN | Freshness | ARCHITECTURE.md | 5 commits behind | Yes |
+| ... | ... | ... | ... | ... | ... |
+
+If `$ARGUMENTS` contains `--doc <name>`, filter to only issues affecting that document.
+
+### Step 2: Prioritize Fix Order
+
+Sort issues by fix dependency and impact:
+
+1. **Structure** first (missing files must exist before checking sections)
+2. **Doc Sections** second (sections must exist before checking quality)
+3. **Doc-Quality** third (readability and language improvements)
+4. **Freshness** fourth (update `last-reviewed` dates)
+5. **Metadata-Sync** fifth (ensure headers are consistent)
+6. **Everything else** last
+
+### Step 3: Research the Codebase (Per Document)
+
+For each document that needs fixing, execute a **targeted research pass**. Research must be thorough — read actual code, not just filenames.
+
+#### For ARCHITECTURE.md:
+1. Read `package.json` for project name, description, dependencies, scripts
+2. List top-level directory structure (`ls -la`, focus on `src/`, `lib/`, `cli/`, `app/`)
+3. Identify entry points — check `main`, `bin`, `exports` in package.json
+4. For each major directory, read 2-3 representative files to understand purpose
+5. Map the import graph — which modules import which
+6. Identify external dependencies and their roles
+
+#### For SECURITY.md:
+1. Check `.gitignore` for security-related patterns (`.env`, secrets, keys)
+2. Search for auth patterns: `grep -r "auth\|token\|jwt\|session\|password\|secret" src/ lib/ --include="*.js" --include="*.mjs"`
+3. Check `package.json` for auth dependencies (passport, jwt, bcrypt)
+4. Look for middleware, guards, or permission checks
+5. Check for `.env` files (document variable names only, NEVER values)
+6. Look for CORS, rate limiting, input validation
+
+#### For TEST-SPEC.md:
+1. Read `package.json` scripts for test commands
+2. Find test files: `find . -name "*.test.*" -o -name "*.spec.*" | head -20`
+3. Read test configuration (jest.config, vitest.config, etc.)
+4. Read 2-3 test files to understand patterns
+5. Check for E2E setup (playwright, cypress)
+6. Look for CI config that runs tests
+
+#### For DATA-MODEL.md:
+1. Search for schema definitions: `grep -r "Schema\|model\|Table\|Entity\|interface\|type " src/ lib/`
+2. Check for ORM configs (prisma, sequelize, mongoose, drizzle)
+3. Look for migration files
+4. Check for TypeScript interfaces/types defining data shapes
+5. Look for Zod schemas, JSON schemas, validation files
+6. If no database: document config file formats
+
+#### For ENVIRONMENT.md:
+1. Read `package.json` for engines, scripts, dependencies
+2. Check for `.nvmrc`, `.node-version`, `.tool-versions`
+3. Search for `process.env` usage: `grep -r "process.env" src/ lib/ cli/`
+4. Check for `.env.example` or `.env.template`
+5. Check for Docker/docker-compose files
+6. Look for setup scripts
+
+### Step 4: Generate or Fix Document Content
+
+For each document, follow this strict writing protocol:
+
+1. **Load the metadata header template**:
+   ```markdown
+   # [Document Title]
+   
+   <!-- docguard:version X.X.X -->
+   <!-- docguard:status active -->
+   <!-- docguard:last-reviewed YYYY-MM-DD -->
+   ```
+
+2. **Write each mandatory section** using research findings:
+   - Use **actual file paths**, module names, and dependency names
+   - Use **markdown tables** for structured data (fields, types, constraints)
+   - Use **code blocks** for command examples (with actual working commands)
+   - Keep language **positive** (avoid negation — "MUST use" not "MUST NOT avoid")
+   - Write at **Flesch-Kincaid grade level 8-10** (clear, professional, not academic)
+
+3. **Validate mandatory sections exist**. Each canonical doc requires:
+   - **ARCHITECTURE.md**: System Overview, Component Map, Layer Boundaries, Data Flow, Technology Choices
+   - **SECURITY.md**: Auth Mechanism, Secrets Inventory, Secrets Storage, Permissions, Security Boundaries
+   - **TEST-SPEC.md**: Test Framework, Test Structure, Test Commands, Critical Flows, Coverage
+   - **DATA-MODEL.md**: Data Structures/Schemas, Field Types/Constraints, Relationships, Indexes
+   - **ENVIRONMENT.md**: Prerequisites, Setup Steps, Environment Variables
+   - **REQUIREMENTS.md**: Functional Requirements (FR-IDs), Non-Functional Requirements
+
+4. **Apply DocGuard quality rules**:
+   - Section count ≥ 3 per document
+   - No TODO/placeholder text in final output
+   - Positive language (IEEE 830 §4.3 compliance)
+   - Each section has substantive content (not just a heading)
+
+### Step 5: Format Compliance
+
+Ensure every generated document follows CDD format rules:
+
+- **Metadata header**: Must include `docguard:version`, `docguard:status`, `docguard:last-reviewed`
+- **Heading hierarchy**: Single `# H1`, then `## H2` sections, then `### H3` subsections
+- **Tables**: Use markdown tables for structured data (pipes aligned, header separators with 3+ dashes)
+- **Code blocks**: Use fenced blocks with language identifier for all commands/code
+- **Line length**: Keep lines under 120 characters for readability
+- **No trailing whitespace**
+
+### Step 6: Validation Loop (Max 3 Iterations)
+
+After writing/fixing each document:
+
+1. **Run guard on the specific validator**:
+   ```bash
+   npx docguard-cli guard 2>&1
+   ```
+
+2. **Parse results** for the affected validators
+3. **If still failing**:
+   - Identify exactly which checks are still failing
+   - Apply targeted fixes (not a full rewrite)
+   - Re-run guard
+4. **If passing after iteration**: Move to next document
+5. **If still failing after 3 iterations**: Report remaining issues with specific error details
+
+### Step 7: Completion Report
+
+After all fixes are applied, output:
+
+```markdown
+## DocGuard Fix Report
+
+### Documents Fixed
+| Document | Action | Checks Before | Checks After | Status |
+|----------|--------|:------------:|:------------:|--------|
+| SECURITY.md | Created | 0/2 | 2/2 | ✅ |
+| ARCHITECTURE.md | Updated sections | 6/8 | 8/8 | ✅ |
+
+### Guard Score
+- **Before**: [X]/[Y] checks passed
+- **After**: [X]/[Y] checks passed
+- **Improvement**: +[N] checks
+
+### Remaining Issues (if any)
+- [Issue description] — [Why it couldn't be auto-fixed]
+
+### Suggested Next Steps
+- Run `/docguard.guard` to verify full compliance
+- Review generated content for accuracy
+- Commit with: `docs: fix CDD documentation [list of docs fixed]`
+```
+
+## Behavior Rules
+
+- **Research FIRST, write SECOND** — never generate content without reading the codebase
+- **Be specific to THIS project** — don't add generic boilerplate for features the project doesn't have
+- **Back up before overwriting** — if file exists, create `.bak` first or use `safeWrite()`
+- **Respect existing content** — when updating, preserve user-written sections and only add/fix missing parts
+- **Log deviations** — if you deviate from canonical expectations, add `// DRIFT: reason` in DRIFT-LOG.md
+- **Never include secrets** — document variable/secret NAMES only, never actual values
+
+## Integration with Spec Kit
+
+If `.specify/` directory exists:
+- Check `constitution.md` for project principles before generating docs
+- Align documentation language with constitutional requirements
+- If `specs/*/spec.md` exists, cross-reference requirements with TEST-SPEC.md
+
+## Context
+
+$ARGUMENTS

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

@@ -0,0 +1,167 @@
+---
+name: docguard-guard
+description: Run DocGuard guard validation against Canonical-Driven Development standards.
+  Parses output, triages severity, suggests targeted fixes, and optionally chains to
+  docguard-fix for automated remediation. Use as a quality gate before commits or after
+  implementation phases.
+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-guard
+---
+
+# DocGuard Guard Skill
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Execute DocGuard's 19-validator guard suite against the current project, parse structured results, triage findings by severity and impact, and produce an actionable remediation plan. This skill transforms raw CLI output into an AI-digestible quality assessment.
+
+## Pre-Execution Checks
+
+1. **Verify DocGuard is available**:
+   - Check if `npx docguard-cli --version` succeeds
+   - If not available, check if `node cli/docguard.mjs --help` exists (local dev mode)
+   - If neither works: ERROR "DocGuard CLI not found. Install with: npm i -g docguard-cli"
+
+2. **Detect project root**:
+   - Look for `.docguard.json`, `docs-canonical/`, or `CHANGELOG.md` as project markers
+   - If none found: ERROR "No CDD project detected. Run `docguard init` first."
+
+## Execution Flow
+
+### Step 1: Run Guard with Machine-Readable Output
+
+Execute the guard command and capture full output:
+
+```bash
+npx docguard-cli guard 2>&1
+```
+
+If in a DocGuard development environment (cli/docguard.mjs exists), use:
+```bash
+node cli/docguard.mjs guard 2>&1
+```
+
+### Step 2: Parse Validator Results
+
+Extract from guard output each validator's status. Build an internal results table:
+
+| Validator | Priority | Checks Passed | Total Checks | Status |
+|-----------|----------|---------------|--------------|--------|
+| Structure | HIGH | N | M | ✅/⚠️/❌ |
+| Doc Sections | HIGH | N | M | ✅/⚠️/❌ |
+| ... | ... | ... | ... | ... |
+
+**Status mapping**:
+- `✅` = All checks passed
+- `⚠️` = Warning (non-blocking, but should fix)
+- `❌` = Failure (blocking — must fix before commit)
+
+### Step 3: Severity Triage
+
+Classify every non-passing check using this priority matrix:
+
+**CRITICAL (fix immediately)**:
+- Structure failures (missing canonical docs)
+- Security failures (hardcoded secrets, missing SECURITY.md)
+- Test-Spec failures (tests don't match spec)
+
+**HIGH (fix before commit)**:
+- Doc Sections failures (missing required sections)
+- Drift detection (undocumented code deviations)
+- Changelog gaps
+- Traceability breaks
+
+**MEDIUM (fix this sprint)**:
+- Freshness warnings (stale docs)
+- Docs-Coverage gaps (undocumented config files)
+- Doc-Quality issues (readability, negation language)
+- Metrics-Consistency mismatches
+
+**LOW (fix when convenient)**:
+- TODO-Tracking items
+- Schema-Sync gaps
+- Metadata-Sync minor mismatches
+- Spec-Kit warnings (spec structure gaps)
+
+### Step 4: Generate Triage Report
+
+Output a structured markdown report:
+
+```markdown
+## DocGuard Guard Report
+
+**Score**: [X]/[Y] checks passed ([percentage]%)
+**Overall Status**: ✅ PASS | ⚠️ WARN | ❌ FAIL
+
+### Summary by Priority
+
+| Priority | Count | Validators Affected |
+|----------|-------|-------------------|
+| CRITICAL | N | [list] |
+| HIGH | N | [list] |
+| MEDIUM | N | [list] |
+| LOW | N | [list] |
+
+### Findings
+
+#### CRITICAL
+1. [Validator]: [Specific issue] → **Fix**: [Exact action to take]
+
+#### HIGH
+1. [Validator]: [Specific issue] → **Fix**: [Exact action to take]
+
+[... continue for MEDIUM/LOW only if user requests or total findings < 10]
+```
+
+### Step 5: Remediation Recommendations
+
+For each finding, provide a **specific, actionable fix** — not "fix the issue" but the exact file, section, and content to change:
+
+- **Missing file**: "Create `docs-canonical/SECURITY.md` with metadata header and these sections: [list]"
+- **Missing section**: "Add `## Threat Model` section to `docs-canonical/SECURITY.md` after line N"
+- **Stale doc**: "Update `<!-- docguard:last-reviewed YYYY-MM-DD -->` in [file] to today's date"
+- **Negation language**: "Replace 'Never store secrets in...' with 'Store secrets exclusively in...'"
+- **Undocumented config**: "Add `.venv` documentation to `docs-canonical/ARCHITECTURE.md` under Developer Tools"
+
+### Step 6: Offer Next Actions
+
+Based on the triage results:
+
+- **If all PASS**: "All 19 validators passed. Project is CDD-compliant. Ready to commit."
+- **If only MEDIUM/LOW warnings**: "Non-blocking warnings found. Safe to commit, but consider running `/docguard.fix` for automated remediation."
+- **If HIGH or CRITICAL failures**: "Blocking issues found. Fix these before committing. Suggest running `/docguard.fix --doc [most impactful doc]` next."
+
+Present the user with options:
+1. "Fix all automatically" → Suggest: `/docguard.fix`
+2. "Fix specific doc" → Suggest: `/docguard.fix --doc [name]`
+3. "Ignore warnings and proceed" → Warn about CDD compliance gap
+
+## Behavior Rules
+
+- **ALWAYS run the actual CLI** — never simulate or guess guard results
+- **Parse real output** — don't hallucinate check counts or validator names
+- **Be specific** — every fix recommendation must reference an actual file path
+- **Respect severity** — don't escalate LOW to CRITICAL or vice versa
+- **Track progress** — if user runs guard multiple times, compare before/after
+- If user provides `$ARGUMENTS` like "just structure" or "only security", filter report to those validators
+
+## Integration with Spec Kit
+
+If this project has `.specify/` directory (spec-kit enabled):
+- Include Spec-Kit validator results in the triage
+- Cross-reference spec quality issues with `specs/*/spec.md` file paths
+- Suggest `/speckit.analyze` if spec-related findings exceed 3
+
+## Context
+
+$ARGUMENTS