docguard-cli 0.5.1

package/docs/quickstart.md

@@ -0,0 +1,79 @@
+# DocGuard — Quick Start
+
+Get AI-enforced documentation in under 5 minutes.
+
+## For New Projects
+
+### Option A: Minimal (side projects)
+
+```bash
+cd your-project
+npx docguard init --profile starter
+```
+
+Creates only ARCHITECTURE.md + CHANGELOG — the bare minimum.
+
+### Option B: Full CDD (team projects)
+
+```bash
+cd your-project
+npx docguard init
+```
+
+Creates all 5 canonical docs + tracking files + AI slash commands.
+
+### Option C: From existing code (best for established projects)
+
+```bash
+cd your-project
+npx docguard generate
+```
+
+Scans your codebase and generates pre-filled documentation.
+
+## Fill the Docs (AI Does It)
+
+After init creates skeleton templates, run **one command**:
+
+```bash
+npx docguard diagnose
+```
+
+This outputs a complete AI remediation plan. If you're using Claude Code, Cursor, Copilot, or Antigravity, the AI reads the output and writes every doc automatically.
+
+**That's it.** The AI loop:
+
+```
+diagnose  →  AI reads prompts  →  AI fixes docs  →  guard verifies
+   ↑                                                       ↓
+   └───────────────── issues found? ←──────────────────────┘
+```
+
+## Verify
+
+```bash
+npx docguard guard        # Pass/fail check
+npx docguard score        # 0-100 maturity score
+npx docguard score --tax  # How much time docs cost you
+```
+
+## Automate
+
+```bash
+# Git hooks (auto-check on commit/push)
+npx docguard hooks
+
+# CI/CD pipelines
+npx docguard ci --threshold 70
+
+# Live watch mode with auto-fix
+npx docguard watch --auto-fix
+```
+
+## What's Next?
+
+- [Commands Reference](./commands.md) — All 13 commands
+- [Configuration](./configuration.md) — `.docguard.json` options
+- [Profiles](./profiles.md) — Starter vs Standard vs Enterprise
+- [AI Integration](./ai-integration.md) — How AI agents use DocGuard
+- [FAQ](./faq.md) — Common questions

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "docguard-cli",
+  "version": "0.5.1",
+  "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
+  "type": "module",
+  "bin": {
+    "docguard": "./cli/docguard.mjs"
+  },
+  "scripts": {
+    "docguard": "node cli/docguard.mjs",
+    "audit": "node cli/docguard.mjs audit",
+    "guard": "node cli/docguard.mjs guard",
+    "init": "node cli/docguard.mjs init",
+    "score": "node cli/docguard.mjs score",
+    "diff": "node cli/docguard.mjs diff",
+    "generate": "node cli/docguard.mjs generate",
+    "hooks": "node cli/docguard.mjs hooks",
+    "prepublishOnly": "node cli/docguard.mjs --version",
+    "test": "node --test tests/*.test.mjs"
+  },
+  "keywords": [
+    "canonical-driven-development",
+    "cdd",
+    "documentation",
+    "governance",
+    "ai-agents",
+    "spec-guard",
+    "docguard",
+    "validation",
+    "cli",
+    "developer-tools",
+    "documentation-standard"
+  ],
+  "author": "Ricardo Accioly",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/raccioly/docguard"
+  },
+  "homepage": "https://github.com/raccioly/docguard#readme",
+  "bugs": {
+    "url": "https://github.com/raccioly/docguard/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "cli/",
+    "templates/",
+    "docs/",
+    "STANDARD.md",
+    "PHILOSOPHY.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {}
+}

package/templates/ADR.md.template

@@ -0,0 +1,64 @@
+# Architecture Decision Records (ADR)
+
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status living -->
+<!-- docguard:last-reviewed YYYY-MM-DD -->
+
+> **Canonical document** — Design intent. Records significant architectural decisions and their rationale.  
+> Once accepted, ADRs are immutable. Superseded ADRs are preserved with a link to their replacement.
+
+| Metadata | Value |
+|----------|-------|
+| **Status** | ![Status](https://img.shields.io/badge/status-living-blue) |
+| **Version** | `0.1.0` |
+| **Last Updated** | YYYY-MM-DD |
+
+---
+
+## Index
+
+| # | Title | Status | Date |
+|---|-------|:---:|:---:|
+| ADR-001 | <!-- e.g. Use PostgreSQL over MongoDB --> | ✅ Accepted | YYYY-MM-DD |
+| ADR-002 | | | |
+
+---
+
+## ADR-001: <!-- Title -->
+
+**Status**: ✅ Accepted  
+**Date**: YYYY-MM-DD  
+**Author**: @your-github-username
+
+### Context
+
+<!-- What is the issue that we're seeing that motivates this decision? -->
+
+### Decision
+
+<!-- What is the change that we're proposing and/or doing? -->
+
+### Consequences
+
+<!-- What becomes easier or more difficult to do because of this change? -->
+
+#### Positive
+- <!-- Benefit 1 -->
+
+#### Negative
+- <!-- Tradeoff 1 -->
+
+#### Risks
+- <!-- Risk 1 -->
+
+### Alternatives Considered
+
+| Alternative | Pros | Cons | Why Not |
+|------------|------|------|---------|
+| <!-- e.g. MongoDB --> | <!-- e.g. Flexible schema --> | <!-- e.g. Weak joins --> | <!-- e.g. We need relational queries --> |
+
+---
+
+## ADR-002: <!-- Title -->
+
+<!-- Same format as ADR-001 -->

package/templates/AGENTS.md.template

@@ -0,0 +1,88 @@
+# Agent Instructions
+
+> This project follows **Canonical-Driven Development (CDD)**.  
+> Read canonical docs before making changes. Log drift when deviating.
+
+---
+
+## Project Overview
+
+<!-- What this project is, in 2-3 sentences -->
+
+## Project Documentation (CDD)
+
+This project uses Canonical-Driven Development. Key locations:
+
+- **Canonical docs** (design intent, READ-ONLY): `docs-canonical/`
+- **Implementation docs** (current state): `docs-implementation/`
+- **Drift tracking**: `DRIFT-LOG.md`
+- **Change tracking**: `CHANGELOG.md`
+
+## Build & Dev Commands
+
+| Command | Purpose |
+|---------|---------|
+| <!-- e.g. npm install --> | Install dependencies |
+| <!-- e.g. npm run dev --> | Start development server |
+| <!-- e.g. npm test --> | Run unit tests |
+
+## DocGuard — Documentation Enforcement
+
+This project uses **DocGuard** for CDD compliance. Run these commands to validate:
+
+```bash
+# Check documentation status
+npx docguard audit
+
+# Validate compliance (errors + warnings)
+npx docguard guard
+
+# See CDD maturity score
+npx docguard score
+
+# Find and fix CDD issues
+npx docguard fix
+
+# Get AI-ready fix prompt
+npx docguard fix --format prompt
+```
+
+### AI Agent Workflow (IMPORTANT)
+
+When working on this project, follow this workflow:
+
+1. **Before any work**: Run `npx docguard guard` to understand current compliance state
+2. **After making changes**: Run `npx docguard fix --format prompt` to find remaining issues
+3. **Fix what DocGuard reports**: Each issue includes an `ai_instruction` telling you exactly what to do
+4. **Run guard again**: Verify all issues are resolved before committing
+5. **Update CHANGELOG.md**: All changes need a changelog entry
+
+### Auto-Fix Available Issues
+
+If DocGuard detects missing files, run:
+```bash
+npx docguard fix --auto
+```
+
+This auto-creates required documentation from templates. Then review and fill in project-specific content.
+
+## Workflow Rules
+
+1. **Research first** — Check `docs-canonical/` before suggesting changes
+2. **Confirm before implementing** — Show a plan, wait for approval
+3. **Match existing patterns** — Search codebase for similar implementations
+4. **Document drift** — If deviating from canonical docs, add `// DRIFT: reason`
+5. **Update changelog** — All changes need a `CHANGELOG.md` entry
+6. **Run DocGuard** — After any documentation changes, run `npx docguard guard`
+
+## Code Conventions
+
+<!-- Project-specific style rules -->
+
+## File Change Rules
+
+- Changes to >3 files require explicit approval
+- Schema/data model changes require `DATA-MODEL.md` update
+- New dependencies require justification
+- Never commit without explicit approval
+- Documentation changes must pass `docguard guard` before commit

package/templates/ARCHITECTURE.md.template

@@ -0,0 +1,78 @@
+# Architecture
+
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status draft | review | approved -->
+<!-- docguard:last-reviewed YYYY-MM-DD -->
+<!-- docguard:owner @your-github-username -->
+
+> **Canonical document** — Design intent. This file describes WHAT the system is designed to be.  
+> ⚠️ Changes to this file require team review. Update `DRIFT-LOG.md` if code deviates.
+
+| Metadata | Value |
+|----------|-------|
+| **Status** | ![Status](https://img.shields.io/badge/status-draft-yellow) |
+| **Version** | `0.1.0` |
+| **Last Updated** | YYYY-MM-DD |
+| **Owner** | @your-github-username |
+
+---
+
+## System Overview
+
+<!-- One paragraph: What does this system do? Who is it for? -->
+
+## Component Map
+
+<!-- Major modules/packages and their responsibilities -->
+
+| Component | Responsibility | Location | Tests |
+|-----------|---------------|----------|-------|
+| <!-- e.g. API Server --> | <!-- e.g. Handles HTTP requests --> | <!-- e.g. src/server/ --> | <!-- e.g. tests/server/ --> |
+| | | | |
+
+## Layer Boundaries
+
+<!-- Which layers can call which? Prevents architecture drift. -->
+
+| Layer | Can Import From | Cannot Import From |
+|-------|----------------|-------------------|
+| <!-- e.g. Handlers --> | <!-- e.g. Services, Middleware --> | <!-- e.g. Repositories --> |
+| | | |
+
+## Tech Stack
+
+| Category | Technology | Version | License |
+|----------|-----------|---------|---------|
+| Language | | | |
+| Framework | | | |
+| Database | | | |
+| Auth | | | |
+| Hosting | | | |
+| CI/CD | | | |
+
+## External Dependencies
+
+<!-- Third-party services, APIs, and integrations -->
+
+| Service | Purpose | SLA | Fallback |
+|---------|---------|-----|----------|
+| <!-- e.g. Stripe --> | <!-- e.g. Payments --> | <!-- e.g. 99.99% --> | <!-- e.g. Queue + retry --> |
+
+## Diagrams
+
+<!-- Architecture diagrams using Mermaid, ASCII art, or linked images -->
+
+```mermaid
+graph TD
+    A[Client] --> B[API Gateway]
+    B --> C[Service Layer]
+    C --> D[Database]
+```
+
+---
+
+## Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 0.1.0 | YYYY-MM-DD | | Initial draft |

package/templates/CHANGELOG.md.template

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed
+
+### Removed

package/templates/CURRENT-STATE.md.template

@@ -0,0 +1,64 @@
+# Current State
+
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status living -->
+<!-- docguard:last-reviewed YYYY-MM-DD -->
+
+> **Implementation document** — Current state. What is actually deployed and working right now.  
+> Updated continuously as implementation progresses.
+
+| Metadata | Value |
+|----------|-------|
+| **Status** | ![Status](https://img.shields.io/badge/status-living-blue) |
+| **Version** | `0.1.0` |
+| **Last Updated** | YYYY-MM-DD |
+
+---
+
+## Deployment Status
+
+| Environment | URL | Status | Last Deploy |
+|------------|-----|:---:|:---:|
+| Production | <!-- URL --> | <!-- 🟢 Up / 🔴 Down --> | YYYY-MM-DD |
+| Staging | <!-- URL --> | | |
+| Local Dev | `localhost:3000` | | |
+
+## Feature Completion
+
+<!-- Track what's built vs what's planned -->
+
+| Feature | Canonical Doc | Implementation | Status |
+|---------|:---:|:---:|:---:|
+| <!-- e.g. User Auth --> | ✅ Documented | ✅ Implemented | 🟢 Live |
+| <!-- e.g. Payments --> | ✅ Documented | ⚠️ Partial | 🟡 In Progress |
+| <!-- e.g. Webhooks --> | ✅ Documented | ❌ Not Started | 🔴 Planned |
+
+## Active Drift
+
+<!-- Summary of all active drift entries — see DRIFT-LOG.md for details -->
+
+| Area | Drift Count | Severity |
+|------|:---:|----------|
+| <!-- e.g. API routes --> | <!-- e.g. 2 --> | <!-- e.g. Low --> |
+
+## Technical Debt
+
+<!-- Known shortcuts, TODO items, and planned refactors -->
+
+| # | Description | File(s) | Priority | Ticket |
+|---|------------|---------|:---:|--------|
+| 1 | | | <!-- P1/P2/P3 --> | |
+
+## Dependencies Health
+
+| Dependency | Current | Latest | Status |
+|-----------|---------|--------|:---:|
+| <!-- e.g. Node.js --> | <!-- e.g. 20.11 --> | <!-- e.g. 22.x --> | <!-- 🟢/🟡/🔴 --> |
+
+---
+
+## Revision History
+
+| Date | Description |
+|------|------------|
+| YYYY-MM-DD | Initial state capture |

package/templates/DATA-MODEL.md.template

@@ -0,0 +1,66 @@
+# Data Model
+
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status draft | review | approved -->
+<!-- docguard:last-reviewed YYYY-MM-DD -->
+<!-- docguard:owner @your-github-username -->
+
+> **Canonical document** — Design intent. This file describes the data structures and their relationships.  
+> ⚠️ Schema changes require this doc to be updated FIRST.
+
+| Metadata | Value |
+|----------|-------|
+| **Status** | ![Status](https://img.shields.io/badge/status-draft-yellow) |
+| **Version** | `0.1.0` |
+| **Last Updated** | YYYY-MM-DD |
+| **Owner** | @your-github-username |
+
+---
+
+## Entities
+
+<!-- All data entities (tables, collections, models) -->
+
+| Entity | Storage | Primary Key | Description |
+|--------|---------|-------------|-------------|
+| <!-- e.g. User --> | <!-- e.g. users table --> | <!-- e.g. userId (UUID) --> | <!-- e.g. Registered users --> |
+
+## Schema Definitions
+
+<!-- Define fields for each entity -->
+
+### <!-- EntityName -->
+
+| Field | Type | Required | Default | Constraints | Description |
+|-------|------|----------|---------|-------------|-------------|
+| | | | | | |
+
+## Relationships
+
+| From | To | Type | FK/Reference | Cascade |
+|------|-----|------|-------------|---------|
+| | | <!-- 1:1, 1:many, many:many --> | | <!-- ON DELETE behavior --> |
+
+## Indexes
+
+<!-- Indexes for query performance — document which index each query uses -->
+
+| Table | Index Name | Fields | Type | Purpose |
+|-------|-----------|--------|------|---------|
+| | | | <!-- B-tree, GSI, LSI --> | |
+
+## Migration Strategy
+
+<!-- How schema changes are applied -->
+
+| Strategy | Tool | Notes |
+|----------|------|-------|
+| <!-- e.g. Migrations --> | <!-- e.g. Drizzle, Prisma, Alembic --> | |
+
+---
+
+## Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 0.1.0 | YYYY-MM-DD | | Initial draft |

package/templates/DEPLOYMENT.md.template

@@ -0,0 +1,66 @@
+# Deployment
+
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status draft | review | approved -->
+<!-- docguard:last-reviewed YYYY-MM-DD -->
+<!-- docguard:owner @your-github-username -->
+
+> **Canonical document** — Design intent. Describes how the system is deployed.  
+> For step-by-step procedures, see `docs-implementation/RUNBOOKS.md`.
+
+| Metadata | Value |
+|----------|-------|
+| **Status** | ![Status](https://img.shields.io/badge/status-draft-yellow) |
+| **Version** | `0.1.0` |
+| **Last Updated** | YYYY-MM-DD |
+| **Owner** | @your-github-username |
+
+---
+
+## Infrastructure Overview
+
+```mermaid
+graph LR
+    A[Developer] -->|git push| B[GitHub]
+    B -->|webhook| C[CI/CD]
+    C -->|deploy| D[Production]
+    D --> E[Database]
+    D --> F[Cache]
+```
+
+## Environments
+
+| Environment | Provider | URL | Branch | Auto-Deploy |
+|------------|---------|-----|--------|:-----------:|
+| Production | <!-- e.g. AWS App Runner --> | | `main` | ✅ |
+| Staging | | | `staging` | ✅ |
+| Local | Docker | `localhost:3000` | — | — |
+
+## CI/CD Pipeline
+
+| Stage | Tool | Trigger | Duration |
+|-------|------|---------|:--------:|
+| Lint | <!-- e.g. ESLint --> | Push | ~1 min |
+| Test | <!-- e.g. Vitest --> | Push | ~3 min |
+| Build | <!-- e.g. Docker --> | Push | ~5 min |
+| Deploy | <!-- e.g. App Runner --> | Merge to main | ~5 min |
+
+## DNS & Domains
+
+| Domain | Provider | Record Type | Points To |
+|--------|---------|:-----------:|-----------|
+| <!-- e.g. app.example.com --> | <!-- e.g. Cloudflare --> | CNAME | <!-- e.g. App Runner URL --> |
+
+## Monitoring
+
+| Service | What It Monitors | Alert Channel |
+|---------|-----------------|-------------|
+| <!-- e.g. CloudWatch --> | <!-- e.g. Error rates --> | <!-- e.g. Slack #alerts --> |
+
+---
+
+## Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 0.1.0 | YYYY-MM-DD | | Initial draft |

package/templates/DRIFT-LOG.md.template

@@ -0,0 +1,18 @@
+# Drift Log
+
+> Documents conscious deviations from canonical specifications.  
+> Every `// DRIFT:` comment in code MUST have a matching entry here.
+
+---
+
+## Active Drift
+
+| ID | File | Line | Canonical Doc | Deviation | Reason | Date |
+|----|------|------|--------------|-----------|--------|------|
+| <!-- D-001 --> | <!-- src/file.ts --> | <!-- 42 --> | <!-- ARCHITECTURE.md --> | <!-- What deviates --> | <!-- Why --> | <!-- YYYY-MM-DD --> |
+
+## Resolved Drift
+
+| ID | Resolution | Date |
+|----|-----------|------|
+| <!-- D-000 --> | <!-- How it was resolved --> | <!-- YYYY-MM-DD --> |

package/templates/ENVIRONMENT.md.template

@@ -0,0 +1,43 @@
+# Environment & Configuration
+
+> **Canonical document** — Design intent. This file documents everything needed to run this project.  
+> Last updated: YYYY-MM-DD
+
+---
+
+## Prerequisites
+
+<!-- Runtime requirements, tools, and accounts needed -->
+
+| Requirement | Version | Purpose |
+|------------|---------|----------|
+| <!-- e.g. Node.js --> | <!-- e.g. 20.x+ --> | <!-- e.g. Runtime --> |
+| | | |
+
+## Environment Variables
+
+<!-- All environment variables the project needs -->
+
+| Variable | Required | Default | Description | Where to Get |
+|----------|----------|---------|-------------|-------------|
+| <!-- e.g. DATABASE_URL --> | ✅ Yes | — | <!-- e.g. DB connection string --> | <!-- e.g. AWS Console → RDS --> |
+| <!-- e.g. API_PORT --> | ❌ No | 3000 | <!-- e.g. Server port --> | — |
+
+## Configuration Files
+
+<!-- Config files, their purpose, and whether templates exist -->
+
+| File | Purpose | Template |
+|------|---------|----------|
+| <!-- e.g. .env.local --> | <!-- e.g. Local dev secrets --> | <!-- e.g. .env.example --> |
+| | | |
+
+## Setup Steps
+
+<!-- How to go from a fresh clone to a running project -->
+
+1. Clone the repository
+2. <!-- e.g. Copy `.env.example` to `.env.local` -->
+3. <!-- e.g. Fill in required environment variables -->
+4. <!-- e.g. Run `npm install` -->
+5. <!-- e.g. Run `npm run dev` -->