docguard-cli 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricardo Accioly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PHILOSOPHY.md

@@ -0,0 +1,150 @@
+# The Philosophy of Canonical-Driven Development
+
+> Why documentation must come first in the age of AI agents.
+
+---
+
+## The Problem We're Solving
+
+In 2026, AI coding agents can write thousands of lines of code in minutes. They can scaffold entire applications, implement complex features, and refactor entire codebases.
+
+But they have a fatal flaw: **they don't remember.**
+
+Every new session, every new agent, every new conversation starts from zero. The agent reads your code, makes assumptions, and builds on those assumptions. If the assumptions are wrong, the code drifts. If the code drifts long enough, nobody — human or AI — knows what the system was supposed to do in the first place.
+
+This is the **documentation crisis of the AI era:**
+
+> The faster AI writes code, the faster projects lose their design intent.
+
+---
+
+## The Insight
+
+The solution isn't to write better code. It's to write better **canonical documentation** — and make it machine-enforceable.
+
+> **Canonical** (adj.): accepted as being accurate and authoritative; the standard form.
+
+When every AI agent starts by reading canonical documentation that describes what the system IS, what it SHOULD do, and where it has DRIFTED — the agent doesn't need to guess. It doesn't need to reverse-engineer intent from code. It has the source of truth, in a format it can understand instantly.
+
+---
+
+## The Three Pillars of CDD
+
+### Pillar 1: Documentation IS the Source of Truth
+
+In traditional development, code is the source of truth. Documentation is an afterthought — written after code (if at all), rarely updated, and quickly stale.
+
+In CDD, this is inverted:
+
+| Traditional | CDD |
+|-------------|-----|
+| Code first, docs maybe | Docs first, code conforms |
+| Docs describe code | Code implements docs |
+| Docs rot silently | Drift is tracked explicitly |
+| Docs are optional | Docs are required and validated |
+
+This doesn't mean you write a 500-page specification before writing any code. It means:
+- When starting a project, write `ARCHITECTURE.md` before `index.ts`
+- When adding a feature, update `FEATURES.md` before opening your editor
+- When the code deviates, log it in `DRIFT-LOG.md` instead of pretending the docs are wrong
+
+### Pillar 2: Two Tiers, Two Purposes
+
+CDD separates documentation into two tiers:
+
+**Canonical docs** (`docs-canonical/`) are the blueprint. They represent design intent — what we WANT the system to be. They're updated deliberately, through design decisions, not as a side effect of coding.
+
+**Implementation docs** (`docs-implementation/`) are the map. They represent current state — what we HAVE built. They're updated as code changes, reflecting reality.
+
+The gap between these two tiers is **drift** — and drift is not a bug, it's a feature. Real projects always have some gap between intent and reality. CDD acknowledges this and provides a structured way to track it (`DRIFT-LOG.md`), instead of the traditional approach of either:
+- Pretending the docs are still accurate (lying)
+- Silently updating docs to match the broken code (losing intent)
+
+### Pillar 3: Machine-Enforceable, Not Machine-Generated
+
+Many tools generate docs from code. CDD does the opposite: it validates code against docs.
+
+This is a fundamental philosophical difference:
+
+| Generated Docs (traditional) | Enforced Docs (CDD) |
+|------------------------------|---------------------|
+| Machine reads code → produces docs | Machine reads docs → validates code |
+| Docs always match code (including bugs) | Docs represent intent (bugs are caught as drift) |
+| Docs are disposable artifacts | Docs are authoritative sources |
+| No governance, no warnings | Validators catch misalignment |
+
+DocGuard CAN generate docs from existing codebases (for adoption). But the intent is that once generated, those docs become the canonical source — and future code must conform to them.
+
+---
+
+## Why Now?
+
+Three forces are converging in 2025-2026 that make CDD necessary:
+
+### 1. AI Agents Are Becoming Primary Developers
+
+AI agents (Claude, Gemini, Copilot, Cursor) are writing an increasing share of production code. These agents need structured context to work effectively. The better the documentation, the better the output.
+
+### 2. Multi-Agent Development Is Real
+
+It's common for a single project to be worked on by Claude Code, Copilot, Cursor, and a human — sometimes in the same week. Each agent needs a common source of truth. `AGENTS.md` provides behavioral rules; canonical docs provide design knowledge.
+
+### 3. The Documentation Crisis Is Accelerating
+
+AI makes it trivially easy to add code. Nobody is making it easy to maintain documentation. The result: projects with 100,000 lines of code and a 50-line README. CDD addresses this by making documentation a first-class, validated artifact.
+
+---
+
+## CDD and Other Methodologies
+
+CDD doesn't replace existing methodologies. It enhances them:
+
+### CDD + TDD (Test-Driven Development)
+Write canonical docs first. The TEST-SPEC.md in your canonical docs declares what tests must exist. TDD then drives the implementation of those tests. CDD governs the test policy; TDD governs the test implementation.
+
+### CDD + BDD (Behavior-Driven Development)
+Behavior specifications can live in `docs-canonical/FEATURES.md`. BDD's Given/When/Then scenarios become part of the canonical record. DocGuard can validate that corresponding E2E tests exist.
+
+### CDD + SDD (Spec-Driven Development)
+SDD tools like GitHub Spec Kit handle the generation phase (spec → code). CDD adds the governance phase (code ↔ spec, continuously). Use Spec Kit for Phase 1-2 of the CDD lifecycle, then DocGuard for Phase 3-4.
+
+### CDD + Agile/Scrum
+Canonical docs don't need to be waterfall-length documents. A 30-line `ARCHITECTURE.md` is valid. The key is that it EXISTS, is MAINTAINED, and is VALIDATED. Sprint-by-sprint, canonical docs grow alongside the codebase.
+
+---
+
+## The CDD Promise
+
+If your project follows CDD:
+
+1. **Any AI agent can onboard** to your project in seconds — not minutes of code analysis, but seconds of reading structured documentation.
+
+2. **Design intent is never lost** — even when the original developer leaves, the canonical docs preserve WHY the system was designed the way it was.
+
+3. **Drift is conscious** — every deviation from the plan is documented, justified, and trackable. No silent rot.
+
+4. **Quality is enforceable** — DocGuard validators run in CI/CD, catching missing tests, undocumented routes, and unlogged drift before code ships.
+
+5. **Documentation stays alive** — because it's validated on every commit, docs can't rot. If code changes, DocGuard catches the misalignment.
+
+---
+
+## Getting Started
+
+CDD is designed for progressive adoption:
+
+**Day 1**: Create `AGENTS.md` and `docs-canonical/ARCHITECTURE.md`. Two files. That's CDD.
+
+**Week 1**: Add `DATA-MODEL.md`, `SECURITY.md`, `TEST-SPEC.md`, `ENVIRONMENT.md`. Run `docguard audit` to see your score.
+
+**Month 1**: Add `DRIFT-LOG.md`, `CHANGELOG.md`. Run `docguard guard` in your pre-commit hook. You're now fully CDD-compliant.
+
+**Forever**: Every commit is validated. Every drift is logged. Every agent understands your project.
+
+---
+
+## License
+
+This philosophy document and the CDD methodology are released under the [MIT License](https://opensource.org/licenses/MIT).
+
+CDD is an open methodology. Anyone can adopt, adapt, and contribute to it.

package/README.md

@@ -0,0 +1,309 @@
+# DocGuard
+
+> **AI-native documentation enforcement for Canonical-Driven Development (CDD).**  
+> AI diagnoses. AI fixes. AI verifies. Humans review.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org)
+[![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-brightgreen)](package.json)
+
+---
+
+## What is CDD?
+
+**Canonical-Driven Development** is a methodology where canonical documentation drives every phase of a project — from initial design through ongoing maintenance. Unlike traditional development where docs are written after code (and quickly rot), CDD treats documentation as the authoritative source that code must conform to.
+
+| Traditional | CDD |
+|-------------|-----|
+| Code first, docs maybe | Docs first, code conforms |
+| Docs rot silently | Drift is tracked explicitly |
+| Docs are optional | Docs are required and validated |
+| One agent, one context | Any agent, shared context |
+
+**DocGuard** is the CLI tool that enforces CDD — auditing, generating, and guarding your project documentation.
+
+📖 **[Read the full philosophy](PHILOSOPHY.md)** | 📋 **[Read the standard](STANDARD.md)** | ⚖️ **[See comparisons](COMPARISONS.md)** | 🗺️ **[Roadmap](ROADMAP.md)**
+
+---
+
+## Quick Start
+
+```bash
+# The primary command — AI diagnoses AND fixes everything
+npx docguard diagnose
+
+# Generate CDD docs from an existing codebase
+npx docguard generate
+
+# Start from scratch (minimal setup for side projects)
+npx docguard init --profile starter
+
+# Start from scratch (full enterprise setup)
+npx docguard init
+
+# CI gate — pass/fail for pipelines
+npx docguard guard
+```
+
+No installation needed. Zero dependencies. Works with Node.js 18+.
+
+### The AI Loop
+
+```
+diagnose  →  AI reads prompts  →  AI fixes docs  →  guard verifies
+   ↑                                                       ↓
+   └───────────────── issues found? ←──────────────────────┘
+```
+
+`diagnose` is the primary command. It runs all validators, maps every failure to an AI-actionable fix prompt, and outputs a remediation plan. Your AI agent runs it, fixes the docs, and runs `guard` to verify. Zero human intervention.
+
+---
+
+## 13 Commands
+
+### 🔮 Generate — Reverse-engineer docs from code
+```
+$ npx docguard generate
+
+🔮 DocGuard Generate — my-project
+   Scanning codebase to generate canonical documentation...
+
+  Detected Stack:
+    language: TypeScript ^5.0
+    framework: Next.js ^14.0
+    database: PostgreSQL
+    orm: Drizzle 0.33
+    testing: Vitest
+    hosting: AWS Amplify
+
+  ✅ ARCHITECTURE.md (4 components, 6 tech)
+  ✅ DATA-MODEL.md (12 entities detected)
+  ✅ ENVIRONMENT.md (18 env vars detected)
+  ✅ TEST-SPEC.md (45 tests, 8/10 services mapped)
+  ✅ SECURITY.md (auth: NextAuth.js)
+  ✅ AGENTS.md
+  ✅ CHANGELOG.md
+  ✅ DRIFT-LOG.md
+
+  Generated: 8  Skipped: 0
+```
+
+**Detects:** Next.js, React, Vue, Angular, Fastify, Express, Hono, Django, FastAPI, SvelteKit, and more.  
+**Scans for:** Routes, models, services, tests, env vars, components, middleware.
+
+### 📊 Score — CDD maturity assessment
+```
+$ npx docguard score
+
+  Category Breakdown
+
+  structure      ████████████████████ 100%  (×25) = 25 pts
+  docQuality     ██████████████████░░ 90%   (×20) = 18 pts
+  testing        █████████░░░░░░░░░░░ 45%   (×15) = 7 pts
+  security       █████████████████░░░ 85%   (×10) = 9 pts
+  environment    ██████████████░░░░░░ 70%   (×10) = 7 pts
+  drift          ████████████████████ 100%  (×10) = 10 pts
+  changelog      ██████████████░░░░░░ 70%   (×5)  = 4 pts
+  architecture   █████████████████░░░ 85%   (×5)  = 4 pts
+
+  CDD Maturity Score: 83/100 (A)
+  Great — Strong CDD compliance
+
+  Top improvements:
+  → testing: Add tests/ directory and configure TEST-SPEC.md
+```
+
+### 🔍 Diff — Canonical docs vs code comparison
+```
+$ npx docguard diff
+
+  🛣️ API Routes
+    In code but not documented:
+      + src/routes/webhooks.ts
+      + src/routes/admin/settings.ts
+    ✓ In sync: 12 routes
+
+  🔧 Environment Variables
+    Documented but not found in .env.example:
+      − REDIS_URL
+```
+
+### 🤖 Agents — Generate agent-specific configs
+```
+$ npx docguard agents
+
+  ✅ Cursor: .cursor/rules/cdd.mdc
+  ✅ GitHub Copilot: .github/copilot-instructions.md
+  ✅ Cline: .clinerules
+  ✅ Windsurf: .windsurfrules
+  ✅ Claude Code: CLAUDE.md
+  ✅ Gemini CLI: .gemini/settings.json
+
+  Created: 6  Skipped: 0
+```
+
+### 🔍 Audit — What docs exist/missing
+```
+$ npx docguard audit
+
+  Score: 8/8 required files (100%)
+```
+
+### 🏗️ Init — Create CDD docs from templates
+```
+$ npx docguard init
+
+  Created 9 files (8 docs + .docguard.json)
+```
+
+### 🛡️ Guard — Validate project against docs
+```
+$ npx docguard guard
+
+  ✅ Structure      8/8 checks passed
+  ✅ Doc Sections   10/10 checks passed
+  ✅ Drift          1/1 checks passed
+```
+
+---
+
+## CLI Flags
+
+| Flag | Description | Commands |
+|------|-------------|----------|
+| `--dir <path>` | Project directory (default: `.`) | All |
+| `--verbose` | Show detailed output | All |
+| `--format json` | Output as JSON for CI/CD | score, diff |
+| `--fix` | Auto-create missing files | guard |
+| `--force` | Overwrite existing files | generate, agents, init |
+| `--agent <name>` | Target specific agent | agents |
+
+---
+
+## 9 Validators
+
+| # | Validator | What It Checks | Default |
+|---|-----------|---------------|---------| 
+| 1 | **Structure** | Required CDD files exist | ✅ On |
+| 2 | **Doc Sections** | Canonical docs have required sections | ✅ On |
+| 3 | **Docs-Sync** | Routes/services referenced in docs | ✅ On |
+| 4 | **Drift** | `// DRIFT:` comments logged in DRIFT-LOG.md | ✅ On |
+| 5 | **Changelog** | CHANGELOG.md has [Unreleased] section | ✅ On |
+| 6 | **Test-Spec** | Tests exist per TEST-SPEC.md rules | ✅ On |
+| 7 | **Environment** | Env vars documented, .env.example exists | ✅ On |
+| 8 | **Security** | No hardcoded secrets in source code | ❌ Off |
+| 9 | **Architecture** | Imports follow layer boundaries | ❌ Off |
+
+---
+
+## 16 Templates
+
+Every template includes professional metadata: `docguard:version`, `docguard:status`, badges, and revision history.
+
+| Template | Type | Purpose |
+|----------|------|---------|
+| ARCHITECTURE.md | Canonical | System design, components, boundaries |
+| DATA-MODEL.md | Canonical | Schemas, entities, relationships |
+| SECURITY.md | Canonical | Auth, permissions, secrets |
+| TEST-SPEC.md | Canonical | Required tests, coverage |
+| ENVIRONMENT.md | Canonical | Env vars, setup steps |
+| DEPLOYMENT.md | Canonical | Infrastructure, CI/CD, DNS |
+| ADR.md | Canonical | Architecture Decision Records |
+| ROADMAP.md | Canonical | Project phases, feature tracking |
+| KNOWN-GOTCHAS.md | Implementation | Symptom/gotcha/fix entries |
+| TROUBLESHOOTING.md | Implementation | Error diagnosis guides |
+| RUNBOOKS.md | Implementation | Operational procedures |
+| VENDOR-BUGS.md | Implementation | Third-party issue tracker |
+| CURRENT-STATE.md | Implementation | Deployment status, tech debt |
+| AGENTS.md | Agent | AI agent behavior rules |
+| CHANGELOG.md | Tracking | Change log |
+| DRIFT-LOG.md | Tracking | Deviation tracking |
+
+---
+
+## CDD File Structure
+
+```
+your-project/
+├── docs-canonical/              # Design intent (the "blueprint")
+│   ├── ARCHITECTURE.md          # System design, components, boundaries
+│   ├── DATA-MODEL.md            # Database schemas, entity relationships
+│   ├── SECURITY.md              # Auth, permissions, secrets
+│   ├── TEST-SPEC.md             # Required tests, coverage rules
+│   └── ENVIRONMENT.md           # Environment variables, setup
+│
+├── docs-implementation/         # Current state (optional)
+│   ├── KNOWN-GOTCHAS.md         # Lessons learned
+│   ├── TROUBLESHOOTING.md       # Error solutions
+│   ├── RUNBOOKS.md              # Operational procedures
+│   └── CURRENT-STATE.md         # What's deployed now
+│
+├── AGENTS.md                    # AI agent behavior rules
+├── CHANGELOG.md                 # Change tracking
+├── DRIFT-LOG.md                 # Documented deviations
+└── .docguard.json              # DocGuard configuration
+```
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: DocGuard
+on: [pull_request]
+jobs:
+  guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npx docguard guard
+      - run: npx docguard score --format json
+```
+
+### Pre-commit Hook
+
+```bash
+# .git/hooks/pre-commit
+#!/bin/sh
+npx docguard guard
+```
+
+---
+
+## Agent Compatibility
+
+DocGuard works with **every major AI coding agent**:
+
+| Agent | Compatibility | Auto-Generate Config |
+|-------|:---:|:---:|
+| Google Antigravity | ✅ | — |
+| Claude Code | ✅ | `docguard agents --agent claude` |
+| GitHub Copilot | ✅ | `docguard agents --agent copilot` |
+| Cursor | ✅ | `docguard agents --agent cursor` |
+| Windsurf | ✅ | `docguard agents --agent windsurf` |
+| Cline | ✅ | `docguard agents --agent cline` |
+| Gemini CLI | ✅ | `docguard agents --agent gemini` |
+| Kiro (AWS) | ✅ | — |
+
+All canonical docs are **plain markdown** — any agent can read them. No vendor lock-in.
+
+---
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+[MIT](LICENSE) — Free to use, modify, and distribute.
+
+---
+
+**Made with ❤️ by [Ricardo Accioly](https://github.com/raccioly)**