docguard-cli 0.5.1

package/templates/KNOWN-GOTCHAS.md.template

@@ -0,0 +1,69 @@
+# Known Gotchas
+
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status living -->
+<!-- docguard:last-reviewed YYYY-MM-DD -->
+
+> **Implementation document** — Current state. Lessons learned during development and operations.  
+> This is a living document. Add entries as you discover them.
+
+| Metadata | Value |
+|----------|-------|
+| **Status** | ![Status](https://img.shields.io/badge/status-living-blue) |
+| **Version** | `0.1.0` |
+| **Last Updated** | YYYY-MM-DD |
+
+---
+
+## How to Use This Document
+
+Each gotcha follows this format:
+- **Heading** = The component or area
+- **Symptom**: What you observe
+- **Gotcha**: The non-obvious root cause
+- **Fix**: The verified solution
+- **Step/Date**: When this was discovered (for traceability)
+
+---
+
+## 1. <!-- Component/Area Name -->
+
+### <!-- Short Descriptive Title -->
+
+**Symptom**: <!-- What does the user/developer observe? -->
+
+**Gotcha**: <!-- The non-obvious root cause that trips people up -->
+
+**Fix**: <!-- The verified solution -->
+
+<!-- Optional: code example -->
+```
+<!-- code fix example -->
+```
+
+> Discovered: YYYY-MM-DD
+
+---
+
+## 2. <!-- Next Component/Area -->
+
+### <!-- Short Descriptive Title -->
+
+**Symptom**: <!-- What you observe -->
+
+**Gotcha**: <!-- Root cause -->
+
+**Fix**: <!-- Solution -->
+
+> Discovered: YYYY-MM-DD
+
+---
+
+## Quick Reference Table
+
+<!-- Summary of all gotchas for quick scanning -->
+
+| # | Area | Gotcha Summary | Severity |
+|---|------|---------------|----------|
+| 1 | | | <!-- 🔴 Critical / 🟡 Medium / 🟢 Low --> |
+| 2 | | | |

package/templates/ROADMAP.md.template

@@ -0,0 +1,82 @@
+# Roadmap
+
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status living -->
+<!-- docguard:last-reviewed YYYY-MM-DD -->
+<!-- docguard:owner @your-github-username -->
+
+> **Canonical document** — Design intent. The planned evolution of this project.  
+> Updated as priorities shift. Completed items move to CHANGELOG.md.
+
+| Metadata | Value |
+|----------|-------|
+| **Status** | ![Status](https://img.shields.io/badge/status-living-blue) |
+| **Version** | `0.1.0` |
+| **Last Updated** | YYYY-MM-DD |
+| **Owner** | @your-github-username |
+
+---
+
+## Vision
+
+<!-- One sentence: where is this project going? -->
+
+## Current Phase
+
+<!-- What phase is the project in right now? -->
+
+| Phase | Name | Status | Timeline |
+|:-----:|------|:------:|----------|
+| 0 | <!-- e.g. Foundation --> | ✅ Complete | <!-- e.g. Q1 2026 --> |
+| 1 | <!-- e.g. Core Features --> | 🔄 In Progress | <!-- e.g. Q2 2026 --> |
+| 2 | <!-- e.g. Integrations --> | ⏳ Planned | <!-- e.g. Q3 2026 --> |
+| 3 | <!-- e.g. Scale --> | 💭 Future | <!-- e.g. Q4 2026 --> |
+
+---
+
+## Phase 0: <!-- Name --> ✅
+
+<!-- Summary of what was accomplished -->
+
+- [x] <!-- Completed item 1 -->
+- [x] <!-- Completed item 2 -->
+
+## Phase 1: <!-- Name --> 🔄
+
+<!-- What's being built now -->
+
+- [x] <!-- Already done -->
+- [ ] <!-- In progress -->
+- [ ] <!-- Planned this phase -->
+
+## Phase 2: <!-- Name --> ⏳
+
+<!-- What comes after the current phase -->
+
+- [ ] <!-- Feature 1 -->
+- [ ] <!-- Feature 2 -->
+
+## Phase 3: <!-- Name --> 💭
+
+<!-- Longer-term vision -->
+
+- [ ] <!-- Feature 1 -->
+- [ ] <!-- Feature 2 -->
+
+---
+
+## Parking Lot
+
+<!-- Ideas that don't have a phase yet — captured so they're not lost -->
+
+| Idea | Source | Notes |
+|------|--------|-------|
+| | <!-- e.g. user request, team discussion --> | |
+
+---
+
+## Revision History
+
+| Date | Description |
+|------|------------|
+| YYYY-MM-DD | Initial roadmap created |

package/templates/RUNBOOKS.md.template

@@ -0,0 +1,115 @@
+# Operational Runbooks
+
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status living -->
+<!-- docguard:last-reviewed YYYY-MM-DD -->
+
+> **Implementation document** — Current state. Step-by-step procedures for operations.  
+> Each runbook is a self-contained procedure that can be executed independently.
+
+| Metadata | Value |
+|----------|-------|
+| **Status** | ![Status](https://img.shields.io/badge/status-living-blue) |
+| **Version** | `0.1.0` |
+| **Last Updated** | YYYY-MM-DD |
+
+---
+
+## Table of Contents
+
+- [1. Deployment](#1-deployment)
+- [2. Emergency Rollback](#2-emergency-rollback)
+- [3. Health Monitoring](#3-health-monitoring)
+- [4. Data Backup & Restore](#4-data-backup--restore)
+- [5. Incident Response](#5-incident-response)
+
+---
+
+## 1. Deployment
+
+### Steps
+
+1. <!-- e.g. Push to GitHub → triggers build -->
+2. <!-- e.g. New container builds -->
+3. <!-- e.g. Health check passes -->
+4. <!-- Verification step -->
+
+### Verification
+
+```bash
+# Verify deployment succeeded
+```
+
+---
+
+## 2. Emergency Rollback
+
+### When to Use
+
+<!-- Under what conditions should a rollback be triggered? -->
+
+### Steps
+
+```bash
+# Rollback command
+```
+
+### Constraints
+
+- <!-- e.g. Database migrations must be backward-compatible -->
+
+---
+
+## 3. Health Monitoring
+
+### Endpoints
+
+| Endpoint | Auth Required | Purpose |
+|----------|:---:|---------|
+| <!-- e.g. GET /health --> | No | Liveness check |
+| <!-- e.g. GET /health/detailed --> | Yes | Component-level status |
+
+### Response Interpretation
+
+| Status | Action |
+|--------|--------|
+| `healthy` | All systems operational |
+| `degraded` | Non-critical issue, investigate |
+| `unhealthy` | Critical failure, escalate immediately |
+
+---
+
+## 4. Data Backup & Restore
+
+### Create Backup
+
+```bash
+# Backup command
+```
+
+### Restore from Backup
+
+```bash
+# Restore command
+```
+
+> ⚠️ Always verify backup integrity before restoring.
+
+---
+
+## 5. Incident Response
+
+### Severity Levels
+
+| Level | Definition | Response Time | Escalation |
+|-------|-----------|:---:|------------|
+| **P0** | System down | Immediate | Page on-call |
+| **P1** | Major feature broken | 15 min | Notify team lead |
+| **P2** | Minor issue | 1 hour | Create ticket |
+| **P3** | Cosmetic/low impact | Next sprint | Backlog |
+
+### Common Outage Scenarios
+
+| Scenario | Impact | Mitigation |
+|----------|--------|------------|
+| <!-- e.g. Database down --> | <!-- e.g. All writes fail --> | <!-- e.g. Switch to read-only mode --> |

package/templates/SECURITY.md.template

@@ -0,0 +1,42 @@
+# Security
+
+> **Canonical document** — Design intent. This file defines the security model.  
+> Last updated: YYYY-MM-DD
+
+---
+
+## Authentication
+
+<!-- How users/services authenticate -->
+
+| Method | Implementation | Details |
+|--------|---------------|---------|
+| <!-- e.g. JWT --> | <!-- e.g. RS256 tokens --> | <!-- e.g. 15min expiry --> |
+| | | |
+
+## Authorization
+
+<!-- Roles and permissions -->
+
+| Role | Permissions | Scope |
+|------|------------|-------|
+| <!-- e.g. admin --> | <!-- e.g. read, write, delete --> | <!-- e.g. All resources --> |
+| | | |
+
+## Secrets Management
+
+<!-- Where secrets are stored, never in code -->
+
+| Secret | Storage | Access Pattern |
+|--------|---------|---------------|
+| <!-- e.g. DB credentials --> | <!-- e.g. AWS Secrets Manager --> | <!-- e.g. Loaded at startup --> |
+| | | |
+
+## Security Rules
+
+<!-- Explicit rules that code must follow -->
+
+- All API routes MUST require authentication except: <!-- list public routes -->
+- Secrets MUST NOT appear in code, logs, or error messages
+- All user input MUST be validated before processing
+- PII (email, phone, name) MUST be masked in logs

package/templates/TEST-SPEC.md.template

@@ -0,0 +1,55 @@
+# Test Specification
+
+> **Canonical document** — Design intent. This file declares what tests MUST exist.  
+> Last updated: YYYY-MM-DD
+
+---
+
+## Test Categories
+
+<!-- Which test types this project requires -->
+
+| Category | Required | Applies To | Suggested Tools |
+|----------|----------|-----------|-----------------|
+| Unit | ✅ Yes | Services, utilities, helpers | <!-- e.g. jest, vitest, pytest --> |
+| Integration | ✅ Yes | API routes, DB operations | <!-- e.g. supertest, httpx --> |
+| E2E | ✅ Yes | Critical user journeys | <!-- e.g. playwright, cypress --> |
+| Canary | ⚠️ Optional | Health checks, smoke tests | <!-- custom scripts --> |
+| Load | ⚠️ Optional | High-traffic endpoints | <!-- e.g. k6, artillery --> |
+| Security | ⚠️ Optional | Auth flows, input validation | <!-- e.g. OWASP ZAP --> |
+| Contract | ⚠️ Optional | Public-facing APIs | <!-- e.g. pact, dredd --> |
+
+## Coverage Rules
+
+<!-- Glob patterns: which source files must have matching test files -->
+
+| Source Pattern | Required Test Pattern | Category |
+|---------------|----------------------|----------|
+| <!-- e.g. src/services/**/*.ts --> | <!-- e.g. tests/unit/**/*.test.ts --> | Unit |
+| <!-- e.g. src/routes/**/*.ts --> | <!-- e.g. tests/integration/**/*.test.ts --> | Integration |
+
+## Service-to-Test Map
+
+<!-- Specific mapping of source files to their test files -->
+
+| Source File | Unit Test | Integration Test | Status |
+|------------|-----------|-----------------|--------|
+| | | | <!-- ✅ / ⚠️ / ❌ --> |
+
+## Critical User Journeys (E2E Required)
+
+<!-- Each journey listed here MUST have a corresponding E2E test file -->
+
+| # | Journey Description | Test File | Status |
+|---|-------------------|-----------|--------|
+| 1 | <!-- e.g. Login → Dashboard → View Data --> | <!-- e.g. e2e/login-flow.spec.ts --> | |
+| 2 | | | |
+
+## Canary Tests (Pre-Deploy Gates)
+
+<!-- Tests that MUST pass before any deployment -->
+
+| Canary | What It Checks | File |
+|--------|---------------|------|
+| Health | <!-- e.g. /health returns 200 --> | |
+| Auth | <!-- e.g. Login flow completes --> | |

package/templates/TROUBLESHOOTING.md.template

@@ -0,0 +1,96 @@
+# Troubleshooting Guide
+
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status living -->
+<!-- docguard:last-reviewed YYYY-MM-DD -->
+
+> **Implementation document** — Current state. Solutions for common issues.  
+> Organized by category. Each entry includes symptoms, diagnosis, and fix.
+
+| Metadata | Value |
+|----------|-------|
+| **Status** | ![Status](https://img.shields.io/badge/status-living-blue) |
+| **Version** | `0.1.0` |
+| **Last Updated** | YYYY-MM-DD |
+
+---
+
+## 1. Setup & Local Environment
+
+### <!-- Issue Title -->
+
+**Error**: `<!-- exact error message -->`
+
+**Cause**: <!-- Root cause explanation -->
+
+**Solution**:
+```bash
+# Fix command
+```
+
+---
+
+## 2. Database & Persistence
+
+### <!-- Issue Title -->
+
+**Symptom**: <!-- What you observe -->
+
+**Cause**: <!-- Why this happens -->
+
+**Remediation**:
+1. <!-- Step 1 -->
+2. <!-- Step 2 -->
+
+---
+
+## 3. Authentication & Authorization
+
+### <!-- Issue Title -->
+
+**Error**: `<!-- exact error message -->`
+
+**Diagnostic**:
+1. <!-- How to diagnose -->
+
+**Fix**: <!-- Solution -->
+
+---
+
+## 4. Deployment & Infrastructure
+
+### <!-- Issue Title -->
+
+**Symptom**: <!-- What you observe -->
+
+| Symptom | Probable Cause | Resolution |
+|---------|---------------|------------|
+| <!-- e.g. 502 after deploy --> | <!-- e.g. Health check failing --> | <!-- e.g. Check /health endpoint --> |
+
+---
+
+## 5. Build & Dependencies
+
+### <!-- Issue Title -->
+
+**Error**: `<!-- exact error message -->`
+
+**Fix**: <!-- Solution -->
+
+---
+
+## 6. Third-Party Services
+
+### <!-- Service Name -->
+
+**Issue**: <!-- What goes wrong -->
+
+**Workaround**: <!-- How to fix or work around -->
+
+---
+
+## Quick Diagnosis Table
+
+| Symptom | Category | Solution |
+|---------|----------|----------|
+| | | |

package/templates/VENDOR-BUGS.md.template

@@ -0,0 +1,74 @@
+# Vendor Bug Reports & Integration Issues
+
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status living -->
+<!-- docguard:last-reviewed YYYY-MM-DD -->
+
+> **Implementation document** — Current state. Tracks bugs filed with third-party vendors and workarounds.  
+> Essential for avoiding repeated investigation of known vendor issues.
+
+| Metadata | Value |
+|----------|-------|
+| **Status** | ![Status](https://img.shields.io/badge/status-living-blue) |
+| **Version** | `0.1.0` |
+| **Last Updated** | YYYY-MM-DD |
+
+---
+
+## Active Vendor Issues
+
+| # | Vendor | Issue | Filed Date | Ticket # | Status | Workaround |
+|---|--------|-------|:---:|----------|--------|------------|
+| 1 | <!-- e.g. AWS --> | <!-- Short description --> | YYYY-MM-DD | <!-- e.g. #12345 --> | <!-- 🟡 Open / 🟢 Fixed / 🔴 Won't Fix --> | <!-- Brief workaround --> |
+| 2 | | | | | | |
+
+---
+
+## Detailed Reports
+
+### V-001: <!-- Vendor — Short Title -->
+
+**Vendor**: <!-- e.g. AWS App Runner -->  
+**Filed**: YYYY-MM-DD  
+**Ticket**: <!-- e.g. AWS Support Case #12345 / GitHub Issue #789 -->  
+**Status**: 🟡 Open
+
+**Description**: 
+<!-- What the issue is -->
+
+**Steps to Reproduce**:
+1. <!-- Step 1 -->
+2. <!-- Step 2 -->
+
+**Expected Behavior**: 
+<!-- What should happen -->
+
+**Actual Behavior**: 
+<!-- What actually happens -->
+
+**Workaround**:
+<!-- How we work around this in our code -->
+
+```
+<!-- Code workaround if applicable -->
+```
+
+**Impact on Our System**: 
+<!-- How this affects our architecture/code -->
+
+**Resolution**: 
+<!-- Leave empty until resolved. When resolved, document the fix and version. -->
+
+---
+
+### V-002: <!-- Next Issue -->
+
+<!-- Same format as above -->
+
+---
+
+## Resolved Issues
+
+| # | Vendor | Issue | Filed | Resolved | Fix Version |
+|---|--------|-------|:---:|:---:|-----------|
+| | | | | | |

package/templates/ci/github-actions.yml

@@ -0,0 +1,39 @@
+name: DocGuard CDD Check
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  docguard:
+    name: CDD Compliance
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Run DocGuard CI
+        run: npx docguard ci --format json --threshold 70 > docguard-report.json
+
+      - name: Display Results
+        if: always()
+        run: |
+          echo "## DocGuard Report" >> $GITHUB_STEP_SUMMARY
+          echo '```json' >> $GITHUB_STEP_SUMMARY
+          cat docguard-report.json >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+
+      - name: Upload Report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docguard-report
+          path: docguard-report.json

package/templates/commands/docguard.fix.md

@@ -0,0 +1,65 @@
+# /docguard.fix — Find and fix all CDD documentation issues
+
+You are an AI agent responsible for maintaining documentation quality using DocGuard (Canonical-Driven Development).
+
+## Step 1: Assess Current State
+
+Run this command and read the output:
+
+```bash
+npx docguard fix --format json
+```
+
+Parse the JSON result. It will contain:
+- `issueCount`: total number of issues
+- `issues[]`: each issue with `type`, `severity`, `file`, and `fix.ai_instruction`
+
+If `issueCount` is 0, 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.
+
+### 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.
+
+### If type is `missing-config`:
+Create `.docguard.json` based on the project. Detect the project type from `package.json`.
+
+## Step 3: Write Real Content for Each Document
+
+For each document that needs content, run:
+
+```bash
+npx docguard fix --doc <name>
+```
+
+Where `<name>` is one of: `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
+```
+
+All checks should pass. If any fail, read the output and fix the remaining issues.
+
+Then run:
+
+```bash
+npx docguard score
+```
+
+Report the final CDD score to the user.

package/templates/commands/docguard.guard.md

@@ -0,0 +1,40 @@
+# /docguard.guard — Validate CDD compliance and fix any issues
+
+You are an AI agent enforcing Canonical-Driven Development (CDD) compliance using DocGuard.
+
+## Step 1: Run Guard
+
+```bash
+npx docguard guard
+```
+
+Read the output. It shows pass/fail for each validator:
+- Structure, Doc Sections, Docs-Sync, Drift, Changelog, Test-Spec, Environment, Freshness
+
+## Step 2: Handle Results
+
+### If all checks pass:
+Report success and the score:
+```bash
+npx docguard 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:
+```bash
+npx docguard fix --doc <name>
+```
+
+Execute the research steps in the output, write real content, then re-run guard to verify.
+
+## Step 3: Report
+
+Show the user:
+1. Which checks passed/failed
+2. What was fixed
+3. Final CDD score