docguard-cli 0.9.5__tar.gz

docguard_cli-0.9.5/.docguard.json

@@ -0,0 +1,40 @@
+{
+  "projectName": "docguard",
+  "version": "0.3",
+
+  "projectType": "cli",
+
+  "requiredFiles": {
+    "canonical": [
+      "docs-canonical/ARCHITECTURE.md",
+      "docs-canonical/DATA-MODEL.md",
+      "docs-canonical/SECURITY.md",
+      "docs-canonical/TEST-SPEC.md",
+      "docs-canonical/ENVIRONMENT.md"
+    ],
+    "agentFile": ["AGENTS.md", "CLAUDE.md"],
+    "changelog": "CHANGELOG.md",
+    "driftLog": "DRIFT-LOG.md"
+  },
+
+  "projectTypeConfig": {
+    "needsEnvVars": false,
+    "needsEnvExample": false,
+    "needsE2E": false,
+    "needsDatabase": false,
+    "testFramework": "node:test",
+    "runCommand": "node cli/docguard.mjs"
+  },
+
+  "validators": {
+    "structure": true,
+    "docsSync": true,
+    "drift": true,
+    "changelog": true,
+    "architecture": true,
+    "testSpec": true,
+    "security": true,
+    "environment": true,
+    "freshness": true
+  }
+}

docguard_cli-0.9.5/.docguardignore

@@ -0,0 +1,9 @@
+# DocGuard Ignore — files to exclude from validation
+# Format: one pattern per line, # comments, blank lines skipped
+
+# Research documents (external/archival — not project source docs)
+Research/
+Research/**
+
+# VS Code extension build artifacts
+vscode-extension/out/

docguard_cli-0.9.5/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,30 @@
+---
+name: 🐛 Bug Report
+about: Report a bug in DocGuard
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Describe the bug
+<!-- A clear description of what the bug is -->
+
+## To Reproduce
+1. Run `docguard ...`
+2. See error
+
+## Expected behavior
+<!-- What you expected to happen -->
+
+## Environment
+- **OS**: <!-- e.g. macOS 15, Ubuntu 24 -->
+- **Node.js**: <!-- e.g. 20.x -->
+- **DocGuard**: <!-- e.g. 0.1.0 -->
+
+## DocGuard config
+```json
+<!-- Paste your .docguard.json here -->
+```
+
+## Additional context
+<!-- Screenshots, error output -->

docguard_cli-0.9.5/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,27 @@
+---
+name: ✨ Feature Request
+about: Suggest a new feature for DocGuard
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## Is your feature request related to a problem?
+<!-- A clear description of what the problem is -->
+
+## Describe the solution you'd like
+<!-- What you want to happen -->
+
+## Describe alternatives you've considered
+<!-- Any alternative solutions you've considered -->
+
+## Which CDD phase does this relate to?
+- [ ] Phase 1: DEFINE (documentation creation)
+- [ ] Phase 2: BUILD (code generation/implementation)
+- [ ] Phase 3: GUARD (validation/enforcement)
+- [ ] Phase 4: EVOLVE (drift tracking/maintenance)
+- [ ] CLI/tooling
+- [ ] Standard/spec
+
+## Additional context
+<!-- Screenshots, examples, links -->

docguard_cli-0.9.5/.github/workflows/ci.yml

@@ -0,0 +1,89 @@
+name: DocGuard CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full git history for freshness validator
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      # ── Automated Test Suite ──
+      - name: Run Tests
+        run: npm test
+
+      # ── Self-validation (dogfooding) ──
+      - name: CLI Version
+        run: node cli/docguard.mjs --version
+
+      - name: Guard (self-check)
+        run: |
+          # Exit 0 = pass, Exit 1 = errors (fail CI), Exit 2 = warnings only (allow)
+          node cli/docguard.mjs guard || [ $? -eq 2 ]
+
+      - name: Score
+        run: node cli/docguard.mjs score
+
+      - name: Score JSON
+        run: node cli/docguard.mjs score --format json
+
+      - name: Diff
+        run: node cli/docguard.mjs diff
+
+      - name: Badge
+        run: node cli/docguard.mjs badge
+
+      - name: Diagnose
+        run: node cli/docguard.mjs diagnose
+
+      # ── Cross-project tests ──
+      - name: Init in temp dir
+        run: |
+          mkdir -p /tmp/docguard-test
+          node cli/docguard.mjs init --dir /tmp/docguard-test --force
+
+      - name: Guard after init (exit 2 = warnings OK for empty projects)
+        run: |
+          node cli/docguard.mjs guard --dir /tmp/docguard-test || [ $? -eq 2 ]
+
+      - name: Generate in empty dir
+        run: |
+          mkdir -p /tmp/docguard-gen
+          node cli/docguard.mjs generate --dir /tmp/docguard-gen
+
+      - name: Generate --force
+        run: node cli/docguard.mjs generate --dir /tmp/docguard-gen --force
+
+      - name: Agents
+        run: node cli/docguard.mjs agents --dir /tmp/docguard-test
+
+      - name: Hooks --list
+        run: node cli/docguard.mjs hooks --list
+
+  # ── npm publish dry-run on tags ──
+  publish-check:
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: 'https://registry.npmjs.org'
+      - name: Publish dry-run
+        run: npm publish --dry-run

docguard_cli-0.9.5/.github/workflows/spec-kit-extension.yml

@@ -0,0 +1,40 @@
+name: Build Spec Kit Extension Asset
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+
+jobs:
+  build-extension:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Get release tag
+        id: tag
+        run: echo "version=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
+
+      - name: Sync version in extension.yml
+        run: |
+          sed -i "s/version: \".*\"/version: \"${GITHUB_REF_NAME#v}\"/" extensions/spec-kit-docguard/extension.yml
+          echo "Updated extension.yml to version ${GITHUB_REF_NAME#v}"
+          grep 'version:' extensions/spec-kit-docguard/extension.yml
+
+      - name: Build extension ZIP
+        run: |
+          cd extensions/spec-kit-docguard
+          zip -r "../../spec-kit-docguard-${{ steps.tag.outputs.version }}.zip" . -x ".*"
+          cd ../..
+          echo "--- ZIP contents ---"
+          unzip -l "spec-kit-docguard-${{ steps.tag.outputs.version }}.zip"
+
+      - name: Upload to release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release upload "${{ steps.tag.outputs.version }}" \
+            "spec-kit-docguard-${{ steps.tag.outputs.version }}.zip" \
+            --clobber

docguard_cli-0.9.5/.gitignore

@@ -0,0 +1,30 @@
+# Dependencies
+node_modules/
+
+# Internal research (not part of the public package)
+Research/
+
+# Environment files
+.env
+.env.local
+.env.development
+.env.production
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Build artifacts
+dist/
+build/
+coverage/
+
+# SpecGuard generated docs (for THIS project testing)
+# Note: In real projects, docs-canonical/ SHOULD be committed.
+# These are excluded here because they're template-generated test files.

docguard_cli-0.9.5/.npmignore

@@ -0,0 +1,28 @@
+# Development
+.git/
+.github/
+.specguard.json
+Research/
+docs-canonical/
+docs-implementation/
+
+# Generated docs (templates are included via templates/)
+DRIFT-LOG.md
+ROADMAP.md
+COMPARISONS.md
+
+# Tests
+tests/
+
+# Config
+.gitignore
+.eslintrc*
+.prettierrc*
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

docguard_cli-0.9.5/AGENTS.md

@@ -0,0 +1,54 @@
+# AI Agent Instructions — docguard
+
+> This project follows **Canonical-Driven Development (CDD)**.
+> Documentation is the source of truth. Read before coding.
+
+## Workflow
+
+1. **Read** `docs-canonical/` before suggesting changes
+2. **Check** existing patterns in the codebase
+3. **Run** `docguard diagnose` to see what needs fixing
+4. **Confirm** your approach before writing code
+5. **Implement** matching existing code style
+6. **Log** any deviations in `DRIFT-LOG.md` with `// DRIFT: reason`
+7. **Verify** with `docguard guard` — all checks must pass
+
+## Project Stack
+
+- **Language**: JavaScript (ES modules)
+- **Runtime**: Node.js 18+
+- **Dependencies**: Zero (pure Node.js built-ins)
+- **Testing**: `node:test` (built-in)
+- **Version**: 0.5.0
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `docs-canonical/ARCHITECTURE.md` | System design |
+| `docs-canonical/DATA-MODEL.md` | Database schemas |
+| `docs-canonical/SECURITY.md` | Auth & secrets |
+| `docs-canonical/TEST-SPEC.md` | Test requirements |
+| `docs-canonical/ENVIRONMENT.md` | Environment setup |
+| `CHANGELOG.md` | Change tracking |
+| `DRIFT-LOG.md` | Documented deviations |
+
+## Commands (13 total)
+
+| Command | Purpose |
+|---------|---------|
+| `diagnose` | **Primary** — identify issues + generate AI fix prompts |
+| `guard` | Validate project (CI gate) |
+| `fix --doc <name>` | AI prompt for specific document |
+| `score` | CDD maturity score (0-100) |
+| `init` | Initialize CDD docs |
+| `generate` | Reverse-engineer docs from code |
+| `ci` | CI/CD pipeline check |
+
+## Rules
+
+- Never commit without updating CHANGELOG.md
+- If code deviates from docs, add `// DRIFT: reason`
+- Security rules in SECURITY.md are mandatory
+- Test requirements in TEST-SPEC.md must be met
+- Run `docguard guard` before pushing — all checks must pass

docguard_cli-0.9.5/CHANGELOG.md

@@ -0,0 +1,276 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.9.5] - 2026-03-14
+
+### Added — Spec Kit Alignment (Mega Release)
+
+#### Spec Kit Scanner Rewrite
+- **Correct file paths**: Now checks `.specify/specs/NNN-feature/spec.md` (v3+ standard) with fallback to legacy `specs/*/spec.md`
+- **Constitution detection**: Checks `.specify/memory/constitution.md` (v3+) with fallback to root `constitution.md`
+- **Spec quality validation**: Validates mandatory sections (User Scenarios, Requirements, Success Criteria), FR-IDs, SC-IDs per spec-kit spec-template.md
+- **Plan quality validation**: Checks for Summary, Technical Context, Project Structure sections
+- **Tasks quality validation**: Verifies phased breakdown (Phase 1, 2+) and T-xxx task IDs
+- **Informational warning**: Spec-Kit validator now suggests `specify init` when no spec-kit artifacts found (was silent `0/0`)
+
+#### Traceability Enhancement
+- **SC-xxx** (Success Criteria) added to requirement ID patterns — aligns with spec-kit SC-001 format
+- **T-xxx** (Task IDs) added — recognizes spec-kit T001, T002 task identifiers
+- Scans `.specify/specs/` path in addition to legacy `specs/`
+
+#### Slash Commands (Spec Kit Extension)
+- New `commands/` directory with 4 AI agent slash commands: `/docguard.guard`, `/docguard.review`, `/docguard.fix`, `/docguard.score`
+- Shipped as part of npm package — available via `specify extension add docguard`
+- Works with Claude Code, Copilot, Cursor, Gemini, Antigravity, and more
+
+#### REQUIREMENTS.md Template
+- New `REQUIREMENTS.md.template` aligned with spec-kit FR-xxx, SC-xxx, Given/When/Then standards
+- Added to `docguard init` template catalog (defaultYes: true)
+
+#### Python Support (PyPI)
+- `pyproject.toml` and `docguard_cli/wrapper.py` for `pip install docguard-cli`
+- Thin Python wrapper delegates to `npx docguard-cli` — requires Node.js 18+
+- Python developers can now use `docguard guard`, `docguard score`, etc.
+
+### Fixed
+- `speckit.mjs` writeFileSync → safeWrite (backup safety, same as v0.9.4 pattern)
+
+## [0.9.4] - 2026-03-13
+
+### Fixed — Critical: Generate File Safety (Data Loss Prevention)
+- **`diagnose --auto` no longer passes `--force` to `generate`**: This was the root cause of silent doc overwriting. `diagnose --auto` now only creates missing files, never overwrites existing ones.
+- **`.bak` backup on `--force`**: When `generate --force` is explicitly used, all existing files are backed up as `.bak` before being overwritten. Content is never permanently lost.
+- **`--force` warning banner**: Shows how many existing files will be overwritten before proceeding.
+- **`safeWrite()` helper**: All 9 write operations in generate now go through a single safety wrapper.
+
+## [0.9.3] - 2026-03-13
+
+### Changed — Prose-Only Extraction Engine (Breaking improvement)
+- **`extractProse()` replaces `stripMarkdown()`**: Instead of stripping markdown and measuring residue (where table cells became "146-word sentences"), the new engine identifies and extracts only actual prose paragraphs. Reference docs (mostly tables/code) with <50 words of prose skip readability scoring entirely.
+- **Technical vocabulary normalization**: 80+ tech terms (DynamoDB, WebSocket, middleware, TypeScript, etc.) are treated as simple 2-syllable words for Flesch scoring. Known terms don't penalize readability.
+- **Markdown-aware sentence detection**: File paths (`src/auth.ts`), version numbers (`v0.9.2`), URLs, and abbreviations (`e.g.`, `i.e.`) no longer cause false sentence splits.
+- **Relaxed thresholds for technical docs**: Flesch 30→15, grade 16→18, sentence length 25→30, passive voice 20→25%, negation 15→20%.
+- **Impact**: Doc-Quality scores improved from 81% (13/16) to 95% (38/40) on DocGuard itself. API reference docs that scored 0/100 now skip gracefully or score fairly.
+
+## [0.9.2] - 2026-03-13
+
+### Fixed
+- **Flesch readability false positives**: Improved `stripMarkdown()` to remove mermaid diagrams, HTML tags, definition-style lines, and lines with >60% special characters. Docs with tables no longer score 0/100.
+- **Flesch threshold**: Lowered from 30→20 for technical documentation — developer docs inherently score lower than prose.
+- **NUL file on macOS**: `findUnderstandingCli()` used Windows `2>NUL` redirect which created a stray `NUL` file on Mac/Linux. Now uses platform-specific `which`/`where`.
+- **Unused import**: Removed `mkdirSync` from `diagnose.mjs` (was imported but never used).
+
+### Verified
+- `diagnose` is read-only by default — file creation only happens with explicit `--auto` flag.
+- `metrics-consistency` properly reads `.docguardignore` patterns.
+
+## [0.9.1] - 2026-03-13
+
+### Fixed
+- **Test detection**: `calcTestingScore` now detects co-located tests in `src/`, `app/`, `lib/`, `packages/`, `modules/` — not just top-level `tests/` directories. Projects using `src/**/__tests__/` or `src/**/*.test.*` patterns now score correctly.
+- **Test-spec fallback**: Validator fallback check now scans for co-located test files and checks vitest/jest config presence.
+- **Vitest config support**: Score calculation now reads `vitest.config.ts`/`jest.config.ts` include patterns to detect custom test directories.
+
+## [0.9.0] - 2026-03-13
+
+### Added
+- **Doc Quality Validator** — 8 deterministic writing quality metrics (passive voice, readability, atomicity, sentence length, negation/conditional load). Inspired by IEEE 830/ISO 29148.
+- **Understanding Integration** — Optional deep scan via the [Understanding](https://github.com/Testimonial/understanding) CLI for full 31-metric doc quality analysis. Runs automatically when `understanding` CLI is installed, providing actionable insights alongside DocGuard's native 8 metrics. Credit: Testimonial/understanding project.
+- **Spec Kit Integration** — Auto-detects [Spec Kit](https://github.com/github/spec-kit) projects (`.specify/`, `specs/`, `constitution.md`, `memory/`), maps Spec Kit artifacts to CDD canonical docs, and supports `docguard generate --from-speckit` for one-command conversion. Validates spec.md requirement IDs trace to tests. Credit: GitHub Spec Kit framework.
+- **Requirement Traceability (V-Model)** — scans docs for requirement IDs (REQ-001, FR-001, US-001, etc.) and validates they trace to test files. Opt-in by convention: just add IDs and DocGuard auto-enforces. Inspired by [spec-kit-v-model](https://github.com/leocamello/spec-kit-v-model) and IEEE 1016.
+- **TODO/FIXME Tracking** — detects untracked code annotations and skipped tests without explanation. Inspired by [spec-kit-cleanup](https://github.com/dsrednicki/spec-kit-cleanup).
+- **Schema Sync Validator** — detects database models from 7 ORM frameworks (Prisma, Drizzle, TypeORM, Sequelize, Knex, Django, Rails) and validates they're documented in DATA-MODEL.md.
+- **`docguard llms` command** — generates `llms.txt` from canonical docs following the [llms.txt standard](https://llmstxt.org/) (Jeremy Howard, Answer.AI, 2024).
+- **ALCOA+ Compliance Scoring** — maps existing validators to the 9 FDA data integrity attributes (Attributable, Legible, Contemporaneous, Original, Accurate, Complete, Consistent, Enduring, Available). Always shown in `docguard score` output with per-attribute evidence, gaps, and fix recommendations.
+- **`enterprise-ai` profile** — EU AI Act Annex IV compliance profile with stricter freshness (14-day threshold), required DATA-MODEL.md, and Risk Assessment section in SECURITY.md.
+- **OpenAPI cross-check** — if route files and an OpenAPI spec exist, validates routes have matching paths in the spec. Warns to re-run spec generator if out of sync.
+
+### Changed
+- Validator count: 14 → 18 validators, 108 → 130+ automated checks
+- `docguard score` now always shows ALCOA+ compliance breakdown
+
+## [0.8.2] - 2026-03-13
+
+### Added
+- **Docs-Coverage Validator** — detects undocumented code features: config files on disk, code-referenced configs (resolve/existsSync calls), source dirs not in ARCHITECTURE.md, README section completeness per Standard README spec.
+- **Metadata-Sync Validator** — cross-checks package.json version against extension.yml and markdown file references; context-aware matching (URLs, install commands, YAML only).
+- **Metrics-Consistency Validator** — catches stale hardcoded numbers in docs ("92 checks" when actual is 114); requires 2+ digit numbers and negative lookbehind for ratio patterns.
+- **`.docguardignore` support** — per-project file exclusions (like `.gitignore`), parsed by `loadIgnorePatterns()` in `shared.mjs`, integrated with Metrics-Consistency and Metadata-Sync validators.
+
+### Fixed
+- **Co-located test detection** — `generate` now recursively scans `src/**/__tests__/` and `*.test.*`/`*.spec.*` files; reads `vitest.config.ts`/`jest.config.ts` for custom patterns.
+- **Test files as source files** — test files are now filtered out of all source lists (services, routes, models, components, middlewares) before mapping.
+- **Diagnose suggest-only** — `diagnose` no longer auto-creates files by default; pass `--auto` to enable auto-fix. Shows actionable suggestions when not in auto mode.
+- **Diagnose score cap** — target score in AI prompt now capped at 100 (was showing 105/100).
+
+### Changed
+- **Guard checks** — increased from 86 to 114 with 5 new validators (docs-coverage, metadata-sync, metrics-consistency, docs-diff, freshness).
+- **Validators** — increased from 9 to 14.
+
+## [0.8.0] - 2026-03-13
+
+### Added
+- **Docs-Diff Validator** — New validator checks for entity/route/field drift between code and canonical docs. Integrated into `guard` and `diagnose` runs.
+- **File Existence Checks** — `test-spec` validator now verifies that source files and test files referenced in the Source-to-Test Map actually exist on disk (catches stale references).
+- **Dynamic Score Suggestions** — Score output now shows specific, AI-actionable suggestions per doc (e.g., "TEST-SPEC.md: missing section: ## Coverage Rules → Run `docguard fix --doc test-spec`") instead of generic advice.
+- **Recommended Test Patterns** — TEST-SPEC.md template now includes guidance on config-awareness tests, regression guards, edge cases.
+- **Mermaid Diagram** — ARCHITECTURE.md now includes a visual architecture diagram.
+
+### Fixed
+- **Scoring: Config-Awareness** — `calcEnvironmentScore` and `calcSecurityScore` now respect `needsEnvExample: false` — CLI projects no longer penalized for missing `.env.example`.
+- **Scoring: node:test Recognition** — `calcTestingScore` now checks `.docguard.json` `testFramework` and `package.json` scripts for `node --test`, giving full marks for built-in test runners.
+- **Scoring: Fake Bonus Removed** — Removed `docguard:version` metadata bonus from `calcDocQualityScore` — it was inflating scores by awarding points for a non-existent feature.
+- **Circular Dependencies** — Extracted `c` (colors) and `PROFILES` into new `cli/shared.mjs`, breaking 14 circular import cycles between `docguard.mjs` and all command files.
+- **CI Workflow** — Fixed failing CI by removing deleted `audit` command steps, adding `--force` to interactive `init`, and adding `diagnose` step.
+
+### Changed
+- **`audit` command** — Now an alias for `guard` (old `audit.mjs` deleted).
+- **Architecture + Security validators** — Enabled by default in `.docguard.json`.
+- **Guard checks** — Increased from 52 to 86 with all validators enabled.
+- **Test suite** — 30 → 33 tests, including config-awareness and regression guards.
+
+## [0.7.3] - 2026-03-13
+
+### Added
+- **Spec-Kit Extension** — DocGuard is now available as a GitHub Spec Kit community extension. 6 commands registered (`guard`, `diagnose`, `score`, `trace`, `generate`, `init`) with `after_tasks` hook for automatic validation. Located in `extensions/spec-kit-docguard/`.
+
+## [0.7.2] - 2026-03-13
+
+### Added
+- **Config-aware traceability** — `guard`, `diagnose`, and `trace` now respect `.docguard.json` `requiredFiles.canonical`. Excluded docs are skipped entirely.
+- **Orphan detection** — Warns when files exist in `docs-canonical/` but are excluded from config, with actionable cleanup instructions: "Delete them or add to .docguard.json".
+
+### Fixed
+- Trace no longer hardcodes all 6 docs — only evaluates what the user's config requires.
+
+## [0.7.1] - 2026-03-13
+
+### Added
+- **Traceability Validator** — New `validateTraceability` runs automatically in `guard` and `diagnose`. Checks that each canonical doc (ARCHITECTURE, DATA-MODEL, TEST-SPEC, SECURITY, ENVIRONMENT) has matching source code artifacts. Reports PARTIAL/UNLINKED/MISSING coverage.
+- **DocGuard in Generated Tech Stacks** — `docguard generate` now always includes DocGuard in the Documentation Tools table of generated ARCHITECTURE.md.
+
+### Fixed
+- **Guard warnings resolved** — TEST-SPEC.md `watch.mjs` partial coverage justified with ISO 29119 §7.2; DRIFT-LOG.md populated with template-string entries.
+- **Test file regex** — `.test.mjs` and `.spec.mjs` files now match in traceability and trace commands.
+- **51 guard checks** (was 46) — all passing on DocGuard itself.
+
+## [0.7.0] - 2026-03-13
+
+### Added
+- **Quality Labels in Guard** — Each validator now displays `[HIGH]`, `[MEDIUM]`, or `[LOW]` quality labels for actionable triage. Inspired by CJE quality stratification (Lopez et al., TRACE, IEEE TMLCN 2026).
+- **Standards Citations in Generated Docs** — All 6 generated canonical docs now include a standards reference footer citing the governing industry standard (arc42/C4, ISO 29119, OWASP ASVS, OpenAPI 3.1, 12-Factor App). Inspired by RAG-grounded standards alignment (Lopez et al., AITPG, IEEE TSE 2026).
+- **`docguard trace` Command** — New requirements traceability matrix generator. Maps canonical docs ↔ source code ↔ tests with TRACED/PARTIAL/UNLINKED/MISSING coverage signals. Supports `--format json`.
+- **`docguard score --signals` Flag** — Multi-signal quality breakdown showing per-signal contribution bars with quality labels. Inspired by CJE composite scoring.
+- **`docguard diagnose --debate` Flag** — Multi-perspective AI prompts using three-agent Advocate/Challenger/Synthesizer pattern. Inspired by AITPG multi-agent role specialization and TRACE adversarial debate.
+- **Agent-Aware Prompt Complexity** — `diagnose` auto-detects AI agent tier from AGENTS.md and adjusts prompt verbosity (concise for advanced models, step-by-step for smaller models). Inspired by CJE equalizer effect (Lopez et al., TRACE 2026).
+- **Research & Academic Credits** — Added full IEEE-style citations for AITPG and TRACE papers, ORCID, and concept attribution table to CONTRIBUTING.md. Added research credits to README.md and academic foundations to PHILOSOPHY.md.
+
+### Changed
+- **15 commands total**: added `trace` (alias: `traceability`)
+- **Version bump**: 0.6.0 → 0.7.0
+
+## [0.6.0] - 2026-03-13
+
+### Added
+- **Doc Tool Detection** — `generate` now detects 8 existing doc tools (OpenAPI, TypeDoc, JSDoc, Storybook, Docusaurus, Mintlify, Redocly, Swagger). Built-in YAML parser for OpenAPI specs (zero deps). Leverages existing tools instead of replacing them.
+- **Deep Route Scanning** — Parses actual route definitions from source code across 6 frameworks: Next.js (App Router + Pages Router), Express, Fastify, Hono, Django, FastAPI. OpenAPI-first: uses spec if available, falls back to code scanning.
+- **Deep Schema Scanning** — Parses schema definitions from 4 ORMs: Prisma (fields, types, relations, enums), Drizzle, Zod, Mongoose. Generates mermaid ER diagrams automatically.
+- **`API-REFERENCE.md` Generator** — New canonical doc generated from deep route scanning. Groups endpoints by resource, shows auth status, handler names, and per-endpoint parameter/response tables.
+- **`docguard publish --platform mintlify`** — Scaffolds Mintlify v2 docs from canonical documentation. Generates `docs.json`, `introduction.mdx`, `quickstart.mdx`, and maps all canonical docs to `.mdx` pages with proper frontmatter.
+- **AGENTS.md Standard Compliance** — Enhanced AGENTS.md template with Permissions & Guardrails section, Monorepo Support, Safety Rules, and `agents.md` standard tags.
+- **Scanner Modules** — New `cli/scanners/` directory with `doc-tools.mjs`, `routes.mjs`, `schemas.mjs`.
+
+### Changed
+- **ARCHITECTURE.md** — Now arc42-aligned (all 12 sections: §1-§12) with C4 Model mermaid diagrams (Level 1 Context, Level 2 Container), Runtime View sequence diagrams, Deployment View, and Glossary.
+- **DATA-MODEL.md** — Enhanced with field-level detail from ORM parsing (types, required, PK/UK, defaults), relationship tables, enum sections, and auto-generated mermaid ER diagrams.
+- **Dynamic Version** — Banner and `--version` now read from `package.json` (no more stale hardcoded version strings).
+- **Version bump**: 0.5.2 → 0.6.0
+- **14 commands total**: added `publish` (alias: `pub`)
+
+## [0.5.0] - 2026-03-13
+
+### Added
+- **`docguard diagnose`** — The AI orchestrator. Chains guard→fix in one command. Runs all validators, maps every failure to an AI-actionable fix prompt, and outputs a complete remediation plan. Three output modes: `text` (default), `json` (for automation), `prompt` (AI-ready). Alias: `dx`.
+- **`guard --format json`** — Structured JSON output for CI/CD and AI agents. Includes profile, validator results, and timestamps.
+- **Compliance Profiles** — Three presets (`starter`, `standard`, `enterprise`) that adjust required docs and validators. Set via `--profile` flag on init or `"profile"` in `.docguard.json`.
+- **`score --tax`** — Documentation tax estimate: tracks doc count, code churn, and outputs estimated weekly maintenance time with LOW/MEDIUM/HIGH rating.
+- **`init --profile starter`** — Minimal CDD setup (just ARCHITECTURE.md + CHANGELOG) for side projects.
+- **GitHub Actions CI template** — Ships in `templates/ci/github-actions.yml`, ready-to-use workflow.
+- **`watch --auto-fix`** — When guard finds issues, auto-outputs AI fix prompts.
+- **Init auto-populate** — After creating skeletons, outputs `docguard diagnose` prompt instead of manual instructions.
+- **Guard → Diagnose hint** — Guard output now prompts `Run docguard diagnose` when issues exist.
+
+### Changed
+- **Guard refactored**: `runGuardInternal()` extracted for reuse by diagnose, CI, and watch (no subprocess needed).
+- **CI rewritten**: Uses `runGuardInternal` directly instead of spawning subprocess. Includes profile and validator data in JSON.
+- **Watch rewritten**: Uses `runGuardInternal` (no process.exit killing the watcher). Proper debounced re-runs.
+- **Version bump**: 0.4.0 → 0.5.0
+- **13 commands total**: audit, init, guard, score, diagnose, diff, agents, generate, hooks, badge, ci, fix, watch
+- **30 tests** across 17 suites (up from 24/14)
+
+## [0.4.0] - 2026-03-12
+
+### Added
+- **`docguard badge`** — Generate shields.io CDD score badges for README (score, type, guarded-by)
+- **`docguard ci`** — Single command for CI/CD pipelines (guard + score, JSON output, exit codes)
+- `.npmignore` for clean npm publish
+- `--threshold <n>` flag for minimum CI score enforcement
+- `--fail-on-warning` flag for strict CI mode
+- npm publish dry-run in CI workflow on tag push
+
+### Changed
+- Score command refactored with `runScoreInternal` for reuse by badge/ci
+- CI workflow now runs actual test suite + dogfoods DocGuard on itself
+- 10 total commands (audit, init, guard, score, diff, agents, generate, hooks, badge, ci)
+
+## [0.3.0] - 2026-03-12
+
+### Added
+- **`docguard hooks`** — Install pre-commit (guard), pre-push (score enforcement), and commit-msg (conventional commits) git hooks
+- **GitHub Action** (`action.yml`) — Reusable marketplace action with score thresholds, PR comments, and fail-on-warning support
+- **Import analysis** in architecture validator — Builds full import graph, detects circular dependencies (DFS), auto-parses layer boundaries from ARCHITECTURE.md
+- **Project type intelligence** — Auto-detect cli/library/webapp/api from package.json
+- `.docguard.json` with `projectTypeConfig` (needsE2E, needsEnvVars, etc.)
+- 15 real tests covering all commands (node:test)
+
+### Changed
+- Architecture validator now auto-detects layer violations from ARCHITECTURE.md (no config needed)
+- Validators respect projectTypeConfig — no false positives for CLI tools
+
+### Fixed
+- Environment validator no longer warns about .env.example for CLI tools
+- Test-spec validator no longer warns about E2E journeys for CLI tools
+
+## [0.2.0] - 2026-03-12
+
+### Added
+- **`docguard score`** — Weighted CDD maturity score (0-100) with bar charts, grades A+ through F
+- **`docguard diff`** — Compares canonical docs against actual code (routes, entities, env vars)
+- **`docguard agents`** — Auto-generates agent-specific config files for Cursor, Copilot, Cline, Windsurf, Claude Code, Gemini
+- **`docguard generate`** — Reverse-engineer canonical docs from existing codebase (15+ frameworks, 8+ databases, 6 ORMs)
+- **Freshness validator** — Uses git commit history to detect stale documentation
+- **Full document type registry** — All 16 CDD document types with required/optional flags and descriptions
+- 8 new templates: KNOWN-GOTCHAS, TROUBLESHOOTING, RUNBOOKS, VENDOR-BUGS, CURRENT-STATE, ADR, DEPLOYMENT, ROADMAP
+
+### Fixed
+- Diff command false positives — entity extraction no longer picks up table headers
+
+## [0.1.0] - 2026-03-12
+
+### Added
+- Initial release of DocGuard CLI
+- `docguard audit` — Scan project, report documentation status
+- `docguard init` — Initialize CDD docs from professional templates
+- `docguard guard` — Validate project against canonical documentation
+- 9 validators: structure, doc-sections, docs-sync, drift, changelog, test-spec, environment, security, architecture
+- 8 core templates with docguard metadata headers
+- Stack-specific configs: Next.js, Fastify, Python, generic
+- Zero dependencies — pure Node.js
+- GitHub CI workflow (Node 18/20/22 matrix)
+- MIT license