docguard-cli 0.9.4 → 0.9.6

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

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

@@ -0,0 +1,182 @@
+---
+name: docguard-review
+description: Cross-document consistency analysis and quality assessment. Performs read-only
+  analysis across all canonical docs, identifies drift, coverage gaps, and quality issues.
+  Produces a structured report with severity-ranked findings. Modeled after speckit-analyze.
+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-review
+---
+
+# DocGuard Review Skill
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Perform a comprehensive, **read-only** analysis of the project's documentation health. Unlike `/docguard.guard` (which runs CLI validators), this skill performs **semantic analysis** — checking whether documentation actually matches the codebase, whether cross-references are consistent, and whether the documentation tells a coherent story.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report only. Offer remediation suggestions that the user must explicitly approve before any changes are made.
+
+## Execution Flow
+
+### Step 1: Gather Documentation Inventory
+
+1. **List all canonical docs**: Read every file in `docs-canonical/`
+2. **List support files**: Check for `CHANGELOG.md`, `DRIFT-LOG.md`, `AGENTS.md`, `README.md`, `ROADMAP.md`
+3. **Check for spec-kit artifacts**: If `.specify/` exists, include `specs/*/spec.md`, `specs/*/plan.md`, `specs/*/tasks.md`
+4. **Build a document map**:
+
+| Document | Exists | Last Modified | Size | Metadata Version |
+|----------|--------|---------------|------|-----------------|
+| ARCHITECTURE.md | ✅ | 2026-03-14 | 5.2KB | 0.5.0 |
+| SECURITY.md | ✅ | 2026-03-14 | 3.1KB | 0.5.0 |
+| ... | ... | ... | ... | ... |
+
+### Step 2: Run Quantitative Analysis
+
+Execute DocGuard's diagnostic and scoring tools:
+
+```bash
+npx docguard-cli diagnose 2>&1
+npx docguard-cli score 2>&1
+npx docguard-cli guard 2>&1
+```
+
+Record:
+- Guard pass/fail counts per validator
+- CDD maturity score (0-100)
+- ALCOA+ compliance attributes
+- Category breakdown
+
+### Step 3: Semantic Cross-Document Analysis
+
+This is the **unique value** of the review skill — analysis that CLI validators cannot do.
+
+#### A. Terminology Consistency
+- Extract key technical terms from each document
+- Flag terms used differently across documents (e.g., "validator" vs "checker" vs "rule")
+- Flag abbreviations used without definition
+- Build a de facto glossary
+
+#### B. Architecture ↔ Code Alignment
+- Read ARCHITECTURE.md component list
+- Verify each listed component actually exists as a directory/module
+- Flag components that exist in code but are missing from ARCHITECTURE.md
+- Flag components listed in ARCHITECTURE.md that don't exist in code
+
+#### C. Data Model ↔ Code Alignment
+- Read DATA-MODEL.md schemas/structures
+- Search codebase for actual data structures
+- Flag schemas documented but not implemented
+- Flag schemas implemented but not documented
+
+#### D. Test Coverage ↔ Test-Spec Alignment
+- Read TEST-SPEC.md critical flows
+- Check actual test files exist for each critical flow
+- Flag test scenarios documented but not implemented
+- Flag test files with no corresponding TEST-SPEC.md entry
+
+#### E. Security Claims ↔ Implementation
+- Read SECURITY.md auth/secrets claims
+- Verify auth implementation exists in code
+- Check that listed secrets are actually used
+- Flag security-relevant code not mentioned in SECURITY.md
+
+#### F. Cross-Reference Integrity
+- Find all internal doc links (`[text](file)` and `See ARCHITECTURE.md`)
+- Verify every referenced file/section actually exists
+- Flag broken cross-references
+- Flag orphaned sections not referenced anywhere
+
+### Step 4: Quality Assessment
+
+For each document, evaluate:
+
+| Criterion | Weight | Score | Notes |
+|-----------|--------|-------|-------|
+| Completeness | 30% | 0-10 | Are all mandatory sections present? |
+| Accuracy | 30% | 0-10 | Does content match actual codebase? |
+| Clarity | 20% | 0-10 | Readability, specificity, no jargon |
+| Currency | 10% | 0-10 | Is content up-to-date with latest code? |
+| Cross-refs | 10% | 0-10 | Are references valid and bidirectional? |
+
+### Step 5: Severity Classification
+
+Classify every finding using this matrix:
+
+- **CRITICAL**: Security claim doesn't match implementation, 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**: Formatting inconsistency, optional section missing, minor terminology drift
+
+### Step 6: Produce Analysis Report
+
+Output a structured markdown report (do NOT write to disk):
+
+```markdown
+## DocGuard Documentation Review
+
+### Executive Summary
+- **Overall Health**: [A+/A/B/C/D/F] ([score]/100)
+- **Documents Analyzed**: [N]
+- **Findings**: [CRITICAL: N, HIGH: N, MEDIUM: N, LOW: N]
+- **Top Risk**: [Most impactful finding]
+
+### Findings Table
+
+| ID | Category | Severity | Location | Summary | Recommendation |
+|----|----------|----------|----------|---------|----------------|
+| R01 | Terminology | HIGH | ARCH:L15, SEC:L22 | "validator" vs "checker" | Standardize on "validator" |
+| R02 | Coverage | MEDIUM | DATA-MODEL.md | Schema X undocumented | Add Schema X to Data Model |
+
+### Per-Document Health
+
+| Document | Completeness | Accuracy | Clarity | Currency | Cross-refs | Overall |
+|----------|:----------:|:-------:|:------:|:-------:|:----------:|:-------:|
+| ARCHITECTURE.md | 9/10 | 8/10 | 9/10 | 7/10 | 10/10 | 8.8/10 |
+| SECURITY.md | 8/10 | 9/10 | 8/10 | 9/10 | 7/10 | 8.4/10 |
+
+### Semantic Consistency
+- **Terminology conflicts**: [N found]
+- **Architecture gaps**: [N components undocumented]
+- **Broken cross-refs**: [N found]
+- **Test coverage gaps**: [N critical flows untested]
+
+### Recommendations (Priority Order)
+1. [Most impactful fix] — estimated effort: [LOW/MEDIUM/HIGH]
+2. [Second most impactful] — estimated effort: [LOW/MEDIUM/HIGH]
+3. ...
+```
+
+### Step 7: Offer Next Actions
+
+Based on findings:
+- **If CRITICAL issues**: "Run `/docguard.fix --doc [name]` to resolve blocking issues"
+- **If only LOW/MEDIUM**: "Documentation is healthy. Consider `/docguard.fix` for polish"
+- **If all clean**: "Documentation is excellent. No action needed."
+
+Ask: "Would you like me to fix the top N issues? (I'll show you what I plan to change before applying)"
+
+## Behavior Rules
+
+- **NEVER modify files** — this is strictly read-only analysis
+- **ALWAYS run real CLI commands** — don't simulate or guess results
+- **Be specific** — cite exact file paths, line numbers, and content
+- **Compare actual code vs docs** — don't just validate formatting
+- **Limit findings to 50** — aggregate overflow in a summary count
+- **Prioritize high-signal findings** — one CRITICAL finding is worth ten LOW findings
+
+## Context
+
+$ARGUMENTS