docguard-cli 0.46.0__tar.gz → 0.48.0__tar.gz

docguard_cli-0.48.0/.agent/commands/docguard.fix.md

@@ -0,0 +1,90 @@
+---
+description: Find and fix all CDD documentation issues using AI-driven research
+handoffs:
+  - label: Verify Fixes
+    agent: docguard.guard
+    prompt: Run guard to verify all fixes pass
+  - label: Check Score
+    agent: docguard.score
+    prompt: Show score improvement after fixes
+---
+
+# /docguard.fix — Find and Fix CDD Documentation Issues
+
+You are an AI agent responsible for maintaining documentation quality using DocGuard.
+
+## Running DocGuard
+
+Run `docguard` from PATH when it is installed. Otherwise run
+`npx --yes docguard-cli@0.48.0`, the release these instructions ship with, in its
+place. Every `docguard …` command below means one of the two.
+
+## Step 1: Mechanical fixes first (no AI judgment needed)
+
+```bash
+docguard fix --write
+```
+
+This deterministically applies the safe fix class: broken doc anchors, stale
+counts bound to code collections, stale version references. Each fix is
+provenance-checked and fail-closed — it never rewrites content whose source of
+truth it cannot verify. Doing this first shrinks the issue list you research.
+
+## Step 2: Assess what remains
+
+```bash
+docguard diagnose
+```
+
+Parse the output — issues are categorized with AI-ready fix prompts. Every
+finding carries a stable code; run `docguard explain <CODE>` whenever
+the right remediation isn't obvious from the message.
+
+If no issues remain, report "All CDD documentation is up to date" and stop.
+
+## Step 3: Fix each issue
+
+| Issue Type | Action |
+|-----------|--------|
+| `missing-file` | Run `docguard fix --doc <name>` to generate |
+| `empty-doc` / `partial-doc` | Proceed to Step 4 for codebase research |
+| `missing-config` | Create `.docguard.json` based on project type |
+| `stale-doc` | Update `docguard:last-reviewed` date and content |
+| `quality-issue` | Fix negation language, add missing sections |
+| false positive | Suppress at the site: `// docguard:ignore <CODE>` (with a reason comment), and report it: `docguard feedback` |
+
+**Doc wrong vs code wrong:** a doc/code mismatch does not automatically mean
+the doc is stale. Canonical docs are the spec — if the code drifted from a
+documented decision, flag the code (or record the deviation with a
+`// DRIFT: reason` comment + DRIFT-LOG.md entry) instead of silently rewriting
+the doc to match the regression.
+
+## Step 4: Write real content
+
+For each document that needs content:
+
+```bash
+docguard fix --doc <name>
+```
+
+Where `<name>` is: `architecture`, `data-model`, `security`, `test-spec`, `environment`
+
+Read the output carefully — it contains:
+- **RESEARCH STEPS**: Exactly what files to read and commands to run
+- **WRITE THE DOCUMENT**: Expected structure and content for each section
+
+Execute the research steps, then write with REAL project content. No placeholders.
+Never edit inside `<!-- docguard:section ... source=code -->` markers by hand —
+those bodies are regenerated from code by `docguard sync --write`; pin them
+(`pinned="reason"`) if a hand-maintained exception is genuinely needed.
+
+## Step 5: Verify (iterate up to 3 times)
+
+```bash
+docguard guard
+docguard score
+```
+
+All checks should pass. If any fail, read the output and fix remaining issues.
+Report the final CDD score, plus anything you suppressed (with reasons) or
+reported as a false positive.

docguard_cli-0.48.0/.agent/commands/docguard.guard.md

@@ -0,0 +1,74 @@
+---
+description: Run DocGuard guard validation — check all validators and fix any issues
+handoffs:
+  - label: Fix Issues
+    agent: docguard.fix
+    prompt: Fix all documentation issues found by guard
+  - label: Check Score
+    agent: docguard.score
+    prompt: Show CDD maturity score after fixes
+---
+
+# /docguard.guard — Validate CDD Compliance
+
+You are an AI agent enforcing Canonical-Driven Development (CDD) compliance using DocGuard.
+
+## Running DocGuard
+
+Run `docguard` from PATH when it is installed. Otherwise run
+`npx --yes docguard-cli@0.48.0`, the release these instructions ship with, in its
+place. Every `docguard …` command below means one of the two.
+
+## Step 1: Run Guard (machine-readable)
+
+```bash
+docguard guard --format json
+```
+
+Read the JSON contract — do not parse prose:
+
+| Field | Meaning |
+|-------|---------|
+| `status` | `PASS` / `WARN` / `FAIL` (severity-aware; matches the exit code: 0/2/1). Under the strict default exit `4` means a validator that applies examined nothing: read `strict.unexamined[]` for each cause and `howToConfigure`; do not set `"enforcement": "standard"` to clear it |
+| `findings[]` | Structured issues: `{code, severity, confidence, message, location, suggestion}` |
+| `nextStep` | The single suggested follow-up command (`null` on PASS) |
+| `reportable[]` | Low-confidence findings (possible false positives) — verify before acting |
+| `coverage` | Markdown tier map: `canonical / tracked / ignored / unclassified[]` |
+| `semanticClaims.count` | Documented counts/limits/enums NOT yet verified against code |
+| `validators[]` | Per-validator results, including `na` (nothing to validate ≠ pass) |
+| `precisionEvidence` | Benchmark evidence for the finding codes in this run: `coverage` counts how many have ever been measured, `codes[CODE]` is `measured` or `not-measured`, and `caveat` must accompany any quoted rate |
+
+## Step 2: Understand each finding before fixing
+
+- Every finding carries a stable code (e.g. `STR001`, `ENV003`, `XRF002`). Run
+  `docguard explain <CODE>` for its contract, cause, and remediation.
+- `confidence: "low"` means the scanner itself is unsure — verify against the
+  code before changing anything, and report real false positives with
+  `docguard feedback`.
+- A finding's `suggestion` may include a ready-to-run `command` or an inline
+  `pragma`. Prefer those over inventing your own fix.
+
+## Step 3: Fix, suppress, or escalate
+
+1. **Mechanical issues first**: `docguard fix --write` applies safe,
+   provenance-checked fixes (broken anchors, stale counts/versions). Never
+   hand-edit what the tool can fix deterministically.
+2. **Prose/content issues**: follow the the `docguard-fix` skill workflow (research →
+   write real content).
+3. **Genuine false positives**: suppress at the finding site with the code —
+   `// docguard:ignore <CODE>` on (or above) the flagged line — or mark a whole
+   validator not-applicable in a doc:
+   `<!-- docguard:validator <key> n/a — reason -->`. Always include the reason.
+   Never suppress to silence a real issue.
+4. If `semanticClaims.count > 0`, offer to run `docguard verify --semantic`
+   and check each extracted claim against the code — a green guard asserts
+   structure, not the truth of documented numbers.
+
+## Step 4: Report
+
+Show the user:
+1. `status` and pass/total, plus anything in `coverage.unclassified` (docs no
+   validator watches — suggest enrolling or ignoring them)
+2. Each finding fixed (by code), each suppressed (with reason), each reported
+   as a false positive
+3. Final score: `docguard score`

docguard_cli-0.48.0/.agent/commands/docguard.review.md

@@ -0,0 +1,77 @@
+---
+description: Review documentation quality — identify drift, coverage gaps, and improvements
+handoffs:
+  - label: Fix Issues
+    agent: docguard.fix
+    prompt: Fix the documentation issues identified in the review
+  - label: Run Guard
+    agent: docguard.guard
+    prompt: Validate all checks pass after review
+---
+
+# /docguard.review — Review Documentation vs Code
+
+You are an AI agent reviewing documentation quality and detecting drift between docs and code.
+
+## Running DocGuard
+
+Run `docguard` from PATH when it is installed. Otherwise run
+`npx --yes docguard-cli@0.48.0`, the release these instructions ship with, in its
+place. Every `docguard …` command below means one of the two.
+
+## Step 1: Run Diagnostics
+
+```bash
+docguard diagnose
+docguard diff
+docguard score
+```
+
+Read all output. Identify where documentation no longer matches the codebase.
+Findings carry stable codes — `docguard explain <CODE>` when unclear.
+
+## Step 2: Verify Documented Claims Against Code
+
+```bash
+docguard verify --semantic
+```
+
+This extracts every checkable claim in the canonical docs — counts, limits,
+rate numbers, retention windows, status enums — as a task list with the nearest
+cited code path. **You perform each verification**: read the cited code, compare
+the value, and report every mismatch with both values. This is the highest-value
+review step; deterministic validators cannot judge these.
+
+## Step 3: Semantic Analysis (Beyond CLI)
+
+For each canonical doc, verify alignment with actual code:
+
+| Analysis | What to Check |
+|----------|--------------|
+| Architecture ↔ Code | Components in ARCHITECTURE.md exist as real modules |
+| Data Model ↔ Code | Schemas in DATA-MODEL.md match actual implementations |
+| Security Claims | Auth mechanisms in SECURITY.md match actual code |
+| Test Coverage | Critical flows in TEST-SPEC.md have actual test files |
+| Terminology | Same concepts named consistently across all docs |
+
+## Step 4: Update Stale Docs
+
+For each stale or drifted document:
+1. **Decide which side is wrong first.** Canonical docs are the spec — if the
+   code regressed from a documented decision, flag the code (or record a
+   `// DRIFT: reason` + DRIFT-LOG.md entry); don't rewrite the doc to match a
+   regression.
+2. Sections inside `<!-- docguard:section ... source=code -->` markers are
+   regenerated — run `docguard sync --write` instead of editing by hand.
+3. For hand-maintained sections: read the relevant source, update the specific
+   section, refresh `docguard:last-reviewed` to today.
+4. Add entry to CHANGELOG.md under [Unreleased].
+
+## Step 5: Verify
+
+```bash
+docguard guard
+docguard score
+```
+
+Report findings, changes made, and the final score.

docguard_cli-0.48.0/.agent/commands/docguard.score.md

@@ -0,0 +1,67 @@
+---
+description: CDD maturity score with ROI-based improvement roadmap — shows category breakdown, grade progression, and highest-impact fixes
+handoffs:
+  - label: Fix Top Issues
+    agent: docguard.fix
+    prompt: Fix the highest-ROI documentation issues to improve score
+  - label: Full Review
+    agent: docguard.review
+    prompt: Perform deep semantic analysis for accuracy verification
+  - label: Run Guard
+    agent: docguard.guard
+    prompt: Verify current guard status after improvements
+---
+
+# DocGuard Score — CDD Maturity Assessment
+
+Calculate and display the project's Canonical-Driven Development maturity score with ROI-based improvement roadmap.
+
+## Running DocGuard
+
+Run `docguard` from PATH when it is installed. Otherwise run
+`npx --yes docguard-cli@0.48.0`, the release these instructions ship with, in its
+place. Every `docguard …` command below means one of the two.
+
+## What to do
+
+1. **Run the scoring engine**:
+```bash
+docguard score
+```
+
+2. **For JSON output** (CI/CD integration):
+```bash
+docguard score --format json
+```
+
+3. **Interpret the grade**:
+
+   | Grade | Score | Meaning |
+   |-------|:-----:|---------|
+   | A+ | 95-100 | Exemplary — production-grade documentation |
+   | A | 85-94 | Strong — minor improvements possible |
+   | B | 70-84 | Good — some gaps to address |
+   | C | 50-69 | Fair — significant documentation debt |
+   | D | 30-49 | Poor — major gaps in documentation |
+   | F | 0-29 | Critical — documentation infrastructure missing |
+
+4. **Analyze category breakdown** (sorted by weight):
+
+   | Category | Weight | What It Measures |
+   |----------|:------:|-----------------|
+   | Structure | 25% | Required CDD files exist |
+   | Doc Quality | 20% | Readability, sections, IEEE 830 compliance |
+   | Testing | 15% | Test documentation coverage |
+   | Security | 10% | Security docs, secrets handling |
+   | Environment | 10% | Environment and setup docs |
+   | Drift | 10% | Code deviation tracking |
+   | Changelog | 5% | Change log maintenance |
+   | Architecture | 5% | Architecture documentation |
+
+5. **Build an ROI-ranked improvement roadmap**:
+   - Calculate `Potential Gain = weight - current points` for each category
+   - Sort by `Potential Gain / Effort` ratio
+   - Show: "If you fix [X], score will increase from [Y] to [Z]"
+   - Show the **minimum set of fixes** to reach the next grade level
+
+6. **Track progress**: Compare current score against previous runs to show improvement.

docguard_cli-0.48.0/.agent/skills/docguard-fix/SKILL.md

@@ -0,0 +1,265 @@
+---
+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 --yes docguard-cli@0.48.0)
+metadata:
+  author: docguard
+  version: 0.48.0
+  source: extensions/spec-kit-docguard/skills/docguard-fix
+---
+<!-- docguard:version: 0.48.0 -->
+
+# DocGuard Fix Skill
+
+## Running DocGuard
+
+Run `docguard` from PATH when it is installed. Otherwise run
+`npx --yes docguard-cli@0.48.0`, the release these instructions ship with, in its
+place. Every `docguard …` command below means one of the two.
+
+## 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 configurable 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
+
+## Scope: `act` findings only
+
+Read `disposition` from `docguard guard --format json` before repairing anything.
+
+- **`act`** — DocGuard asserts a defect and names the correction. In scope.
+- **`escalate`** — DocGuard observed a signal and the judgement belongs to a human (freshness history, diff-overlap suspicion, documented-endpoint absence). **Out of scope for this skill.** Report them for review; never edit a document to silence one. A history heuristic saying a review is DUE is not evidence that the document is wrong, and stamping a new review date to clear it destroys the signal without doing the review.
+
+Also read `parserTier`: a finding produced by `regex-fallback` or `fallback-language` came from a pattern match rather than a syntax tree, so verify the underlying source before rewriting a document around it.
+
+## Execution Flow
+
+### Step 0: Apply Mechanical Fixes First (no AI needed)
+
+```bash
+docguard fix --write 2>&1
+```
+
+Removes endpoints documented in `docs-canonical/API-REFERENCE.md` that the OpenAPI
+spec confirms no longer exist (table row + detail block). Only edits
+`docguard:generated` whole documents. Mapped human docs expose only unique
+`source=code` sections, and `--force` cannot bypass ownership. The operation is
+idempotent and prints what changed. Don't hand-edit generated sections.
+
+### Step 1: Diagnose Current State
+
+Run the diagnostic to identify all issues (each tagged `mechanical` or `agent`):
+
+```bash
+docguard 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:
+<!-- docguard:authoring-contract — generated by `npm run docs:reference` from cli/authoring-contract.mjs; edit the registry, not this block -->
+   - **ARCHITECTURE.md**: System Overview, Component Map, Tech Stack; recommended: Layer Boundaries, Data Flow
+   - **DATA-MODEL.md**: Entities (when the project has a database); recommended: Relationships, Indexes
+   - **SECURITY.md**: Authentication, Secrets Management; recommended: Authorization, Security Boundaries
+   - **TEST-SPEC.md**: Test Categories, Coverage Rules; recommended: Test Commands
+   - **ENVIRONMENT.md**: Environment Variables (when the code reads any), Setup Steps; recommended: Configuration Files
+<!-- /docguard:authoring-contract -->
+   - **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
+   docguard 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 the `docguard-guard` skill 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
+
+## Evidence Findings
+
+Run `docguard verify --evidence --format json` when guard returns an `EVD` code.
+Repair invalid, missing, ambiguous, stale, or unsupported evidence at the named
+source. For `EVD002`, inspect the approved requirement and implementation before
+editing either side; current code does not automatically override canonical
+intent. Rerun evidence verification after the targeted change. Never broaden a
+statement template or remove an evidence declaration merely to make guard pass.
+
+## 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
+
+## When DocGuard says it is old
+
+If DocGuard's output says its version was released more than 14 days ago, tell
+the user and offer to run `docguard upgrade`, which checks npm for a newer
+version only when it runs. Never upgrade DocGuard without the user's agreement,
+and never treat the note as a failure: it says a newer version may exist, not
+that one does.
+
+## Context
+
+$ARGUMENTS