docguard-cli 0.10.0__tar.gz → 0.11.0__tar.gz

{docguard_cli-0.10.0/extensions/spec-kit-docguard → docguard_cli-0.11.0/.agent}/skills/docguard-fix/SKILL.md

@@ -36,9 +36,19 @@ Research the actual codebase to generate or repair canonical documentation that
 
 ## Execution Flow
 
+### Step 0: Apply Mechanical Fixes First (no AI needed)
+
+```bash
+npx docguard-cli 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` docs, idempotent, prints what changed. Don't hand-edit these.
+
 ### Step 1: Diagnose Current State
 
-Run the diagnostic to identify all issues:
+Run the diagnostic to identify all issues (each tagged `mechanical` or `agent`):
 
 ```bash
 npx docguard-cli diagnose 2>&1

docguard_cli-0.11.0/.agent/skills/docguard-sync/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: docguard-sync
+description: Keep canonical documentation ALWAYS UP TO DATE. Refreshes code-truth doc sections in place (mechanical, idempotent, preserves human prose) and flags the prose sections you must review when code changes.
+compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
+metadata:
+  author: docguard
+  version: 0.10.0
+  source: extensions/spec-kit-docguard/skills/docguard-sync
+---
+
+# DocGuard Sync Skill
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input. If `--since <ref>` is provided, include the
+git diff context in your reasoning when reviewing prose sections.
+
+## Goal
+
+When code changes, re-derive the code-truth surface (endpoints, entities,
+screens, tech stack, env vars), refresh the matching `<!-- docguard:section
+source=code -->` blocks in canonical docs in place, and **review/refresh the
+human-written prose** in the same docs so it still describes reality.
+
+## Operating Constraints
+
+- **Mechanical refreshes do not need you.** DocGuard does them itself. Your job
+  is the prose sections flagged as "review" — where the human writing may no
+  longer match the new code reality.
+- **Never edit anything outside the marked `source=human` sections** in
+  generated docs. The markers protect human writing; respect them.
+- **Use the dry run first** to see what will change before applying.
+
+## Execution Flow
+
+### Step 1 — Preview what's stale
+
+```bash
+npx --yes docguard-cli@latest sync 2>&1
+```
+
+Reads:
+- `↻` / `•` lines: code-truth sections that drifted (you don't need to write these).
+- `🤖 Prose to review` lines: human-written sections whose surrounding code changed — **these are yours**.
+
+### Step 2 — Apply the mechanical refresh
+
+```bash
+npx --yes docguard-cli@latest sync --write 2>&1
+```
+
+Re-derives every code-truth section from the current code and rewrites only those
+markers. Idempotent — running again is a no-op when up to date.
+
+### Step 3 — Review the flagged prose
+
+For each `🤖 Prose to review` entry:
+
+1. Open the doc (e.g. `docs-canonical/API-REFERENCE.md`).
+2. Locate the `<!-- docguard:section id=<id> source=human -->` block.
+3. **Read the surrounding `source=code` section first** — that's the new truth
+   (e.g. the refreshed endpoint list, the refreshed screens table).
+4. Update the human prose so it still accurately describes that truth.
+   Examples of what to update:
+   - The API overview's endpoint count, or its description of the surface area.
+   - The Architecture overview when new components/services appeared.
+   - The Screens flows when new screens were added/removed/renamed.
+5. Stay inside the `source=human` markers — don't touch the code sections.
+
+### Step 4 — Verify
+
+```bash
+npx --yes docguard-cli@latest guard
+```
+
+Confirm there are no errors. If the API surface drifted (`API-Surface` failures),
+combine with `docguard fix --write` (the mechanical removal of stale endpoints).
+
+### Step 5 — Loop
+
+The intended flow is `sync → guard → (fix if needed) → guard → commit`. Run sync
+again before opening a PR to make sure the memory is current.
+
+## What to do if `--since <ref>` is provided
+
+When `--since main` is given, DocGuard also lists the changed code files since
+that ref. Use that diff to:
+
+- Prioritize which prose sections to update first (the ones whose related code
+  files changed most).
+- Cite concrete change reasons in your prose updates ("Added `/api/orders`
+  endpoint in commit X" → update the API overview accordingly).
+
+## Common patterns
+
+| Symptom | Action |
+|---|---|
+| `↻ docs-canonical/API-REFERENCE.md → endpoints` | Code-truth refreshed by `--write`. No action needed. |
+| `🤖 docs-canonical/API-REFERENCE.md → overview` | Open the doc; update the `overview` prose to reflect the new endpoint set. |
+| `Skipped … not marked docguard:generated` | The doc isn't owned by DocGuard. Either add the marker (and commit ownership) or skip with `--force`. |
+| `Documentation memory is up to date` | Done — no drift. |
+
+## Anti-patterns (do NOT do these)
+
+- ❌ Editing inside `<!-- docguard:section source=code -->` — DocGuard will rewrite it on the next sync.
+- ❌ Removing the markers to "make the doc look cleaner" — that breaks future sync/regeneration.
+- ❌ Skipping `sync --write` and editing the code section by hand — let DocGuard do it.

{docguard_cli-0.10.0 → docguard_cli-0.11.0}/.github/workflows/ci.yml

@@ -14,11 +14,11 @@ jobs:
         node-version: [18, 20, 22]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0 # Full git history for freshness validator
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
           node-version: ${{ matrix.node-version }}
 
@@ -80,8 +80,8 @@ jobs:
     if: startsWith(github.ref, 'refs/tags/v')
     needs: test
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
         with:
           node-version: 20
           registry-url: 'https://registry.npmjs.org'

{docguard_cli-0.10.0 → docguard_cli-0.11.0}/.github/workflows/release.yml

@@ -19,7 +19,7 @@ jobs:
       version: ${{ steps.check.outputs.version }}
       changed: ${{ steps.check.outputs.changed }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 2 # Need previous commit to compare
 
@@ -49,10 +49,10 @@ jobs:
       matrix:
         node-version: [18, 20, 22]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
           node-version: ${{ matrix.node-version }}
       - name: Run Tests
@@ -68,7 +68,7 @@ jobs:
     outputs:
       tag: v${{ needs.detect-version.outputs.version }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0 # Fetch all history + tags for reliable tag detection
 
@@ -125,7 +125,7 @@ jobs:
     needs: [detect-version, create-release]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: Build extension ZIP
         run: |
@@ -150,8 +150,8 @@ jobs:
     needs: [detect-version, test, create-release]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
         with:
           node-version: 20
           registry-url: 'https://registry.npmjs.org'
@@ -166,7 +166,7 @@ jobs:
     needs: [detect-version, test, create-release]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: actions/setup-python@v5
         with:
           python-version: '3.12'

{docguard_cli-0.10.0 → docguard_cli-0.11.0}/.github/workflows/sync-speckit-catalog.yml

@@ -24,7 +24,7 @@ jobs:
 
     steps:
       - name: Checkout docguard repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Get version and metadata
         id: meta
@@ -71,7 +71,7 @@ jobs:
           echo "✅ Fork synced with upstream"
 
       - name: Checkout spec-kit fork (fresh after sync)
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           repository: raccioly/spec-kit
           token: ${{ secrets.SPECKIT_PR_TOKEN }}

{docguard_cli-0.10.0 → docguard_cli-0.11.0}/CHANGELOG.md

@@ -7,6 +7,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-05-22
+
+This release reshapes DocGuard from a documentation linter into an **AI-readable, always-current project memory builder** — for any language project, not just JS/web. The four-mode lifecycle (`generate → guard → sync → fix`) is now coherent end-to-end.
+
+### Added — AI-powered Generate
+- **`docguard generate --plan`** — the "killer feature" from the v2 vision, now real. Scans any project (JS/TS, Python, Rust, Go, Java/Kotlin, Ruby, PHP, C#; polyglot/monorepo-aware) and emits a **structured agent task manifest** + writes the code-truth skeleton inside `<!-- docguard:section -->` markers. The AI agent writes the prose grounded in scanned facts; human writing is preserved.
+- **`--plan --format json`** machine-readable manifest for agent consumption.
+- **`--plan --write`** scaffolds the skeleton docs (code sections filled, prose sections as agent-task placeholders).
+- Language-aware doc set: a Rust CLI gets ARCHITECTURE; a webapp gets ARCHITECTURE + API-REFERENCE + SCREENS + FEATURES + INTEGRATIONS + ENVIRONMENT + docs-implementation/{KNOWN-GOTCHAS,CURRENT-STATE,RUNBOOKS}.
+
+### Added — Always-up-to-date Sync
+- **`docguard sync`** — refreshes `source=code` doc sections in place when code changes. Mechanical, idempotent, **preserves human prose**. Flags the prose sections to review when their adjacent code changed.
+- `--since <ref>` adds git-diff context. `--write` applies; default is a dry-run preview. `--force` overrides the `docguard:generated` marker gate.
+
+### Added — Section-addressable docs
+- **`cli/writers/sections.mjs`** — marker format `<!-- docguard:section id=X source=code|human -->`. `parseSections` / `replaceSection` / `upsertSection` for surgical regen that never clobbers human prose. The keystone the rest of the program builds on.
+
+### Added — Language-agnostic project intelligence
+- **`cli/scanners/project-type.mjs`** detects every ecosystem from manifests: `package.json`, `pyproject.toml`/`requirements.txt`/`setup.py`/`Pipfile`, `Cargo.toml`, `go.mod`, `pom.xml`/`build.gradle`, `Gemfile`, `composer.json`, `*.csproj`. Polyglot-aware: returns each ecosystem's language, framework, kind, deps, entry points.
+- **Multi-language route scanners** in `routes.mjs`: Spring Boot (Java/Kotlin, class-level base + verb annotations), Rails (verb DSL + `resources` 7-action expansion), Go (Gin/Echo/Chi/Fiber/mux), Rust (Axum, Actix, Rocket).
+- **Multi-language schema/model scanners** in `schemas.mjs`: Python (SQLAlchemy + relationships + Pydantic/SQLModel), Rust Diesel `table!`, Go structs with `json`/`gorm`/`db` tags, Java/Kotlin JPA `@Entity`, Rails ActiveRecord `create_table` migrations.
+
+### Added — Deep frontend capture
+- **`cli/scanners/frontend.mjs`** captures the UI surface: screens/routes (React Router, Next App + Pages with wrapper-unwrapping), components, **state stores** (Zustand/Redux Toolkit/Jotai/MobX), **custom hooks** (incl. `export { X as useY }` aliases), **React Contexts**, **API-client→endpoint mapping** (axios/fetch/custom client), and **i18n keys** (used vs. defined in locale files, with missing-keys reported as drift).
+
+### Added — External integrations
+- **`cli/scanners/integrations.mjs`** — 30+ SDK registry covering Cloud (AWS, GCP, Azure, Cloudflare), Databases, Payments (Stripe/Braintree), Auth (Auth0/Clerk/NextAuth/Cognito), AI (OpenAI/Anthropic/LangChain), Messaging (Twilio/SendGrid/Slack/MessageBird), Observability (Sentry/Datadog/OpenTelemetry), Search, Queues, Storage. Surfaces as `INTEGRATIONS.md` in the memory plan.
+
+### Added — Mechanical fix registry
+- **`cli/writers/mechanical.mjs`** generalizes `docguard fix --write` into a deterministic, no-LLM applier covering: `remove-endpoint` (API-Surface), `replace-count` (Metrics-Consistency stale "N validators"), `replace-version` (Metadata-Sync stale refs — only in actionable contexts, never prose), `insert-changelog-unreleased`.
+- Validators emit structured `fixes[]` arrays surfaced through `guard --format json`, `diagnose --format json`, and applied by `fix --write` / `diagnose --auto`. The 9 previously detect-only validators now have real `FIX_INSTRUCTIONS` routes (no more generic "Manual review needed").
+
+### Added — Spec Kit extension parity
+- New extension commands: `extensions/spec-kit-docguard/commands/fix.md`, `commands/sync.md`. `generate.md` updated to document `--plan`.
+- New skill: `extensions/spec-kit-docguard/skills/docguard-sync/SKILL.md` — teaches the agent the refresh-and-review-prose loop. Extension README modernized to the memory-first vocabulary.
+
+### Changed
+- **PHILOSOPHY.md rewritten** from v1 governance-first ("not machine-generated") to the v2 memory-first reality (generate + guard + sync, bidirectional, language-agnostic). Honest about what the tool actually does.
+- **`docguard score`** displays **`Memory: Completeness X% · Accuracy Y%`** derived from the existing category scores; `--format json` adds `memory.{completeness, accuracy}` and per-category `axis` field. No weight changes.
+- CLI `--help` reframed around the memory lifecycle (audit/generate/guard/sync).
+
+### Fixed
+- Tightened a self-inflicted false positive (a literal `TODO` in a generate.mjs placeholder string was tripping DocGuard's own TODO-Tracking validator).
+- Fixed several scanner bugs caught by new tests: React Router wrapper-component unwrapping (`<RequireAuth><XPage/>`), Next.js base-path double-append, Go single-line struct regex, Spring Boot `@RequestMapping` class-level vs method-level disambiguation, locale-dir deduplication.
+
+### Infrastructure
+- CI: bumped `actions/checkout` and `actions/setup-node` to `@v5` across all four workflows (ahead of the June 2026 Node 24 default).
+
+### Tests
+- **Tests: 175 → 285 (+110)**. New test files: `api-doc`, `api-surface`, `shared-source`, `guard-classify`, `monorepo-scanning`, `sections`, `frontend`, `frontend-deep`, `i18n`, `project-type`, `memory-plan`, `integrations`, `routes-multilang`, `schemas-multilang`, `mechanical`, `api-write`, `multi-spec`, `sync`. All green.
+
 ## [0.10.0] - 2026-05-22
 
 ### Added

docguard_cli-0.11.0/PHILOSOPHY.md

@@ -0,0 +1,125 @@
+# The Philosophy of Canonical-Driven Development
+
+> Why every codebase needs a living, machine-readable memory — and how DocGuard builds and maintains one.
+
+---
+
+## The Problem We're Solving
+
+In 2026, AI coding agents can write thousands of lines of code in minutes. But they have a fatal flaw: **they don't remember.**
+
+Every new session, every new agent, every new conversation starts from zero. The agent re-reads your code, re-derives how the system works, makes assumptions, and builds on them. Humans hit the same wall: a new contributor faces 500 files and a 50-line README.
+
+This is the **comprehension crisis of the AI era:**
+
+> The faster AI writes code, the faster everyone loses the map of what was built.
+
+---
+
+## The Insight
+
+A project needs a **canonical memory** — a complete, structured, always-current description of what the system *is*: every endpoint, screen, entity, the architecture, the tech stack, the setup. Written so an AI agent (or a human) can load it in seconds and understand the whole project without re-reading the code.
+
+DocGuard's job is to **build that memory from the code, keep it true as the code changes, and protect the human reasoning inside it.**
+
+> **Canonical** (adj.): accepted as accurate and authoritative; the standard form.
+
+---
+
+## The Three Pillars of CDD
+
+### Pillar 1: Documentation is a first-class, validated artifact
+
+In traditional development, docs are an afterthought — written late (if at all), never updated, quickly stale. CDD makes documentation a **required, validated, and maintained** artifact, on the same footing as tests. If it isn't validated on every change, it rots; so DocGuard validates it.
+
+### Pillar 2: Two tiers — derived truth and human reasoning
+
+CDD separates documentation into two kinds of content, and treats them differently:
+
+- **Code-derived** (endpoints, entities, screens, tech stack, env vars): DocGuard generates and re-generates these *from the code*. They are mechanical, and DocGuard owns them.
+- **Human reasoning** (the "why", design intent, trade-offs, gotchas): authored by people (or an AI agent), and **never overwritten** by the tool.
+
+DocGuard keeps these in the same readable markdown using section markers
+(`<!-- docguard:section id=… source=code -->`), so it can refresh the derived
+parts surgically while leaving your writing untouched.
+
+### Pillar 3: Generate AND Guard — bidirectional, continuous
+
+Earlier versions of this document framed CDD as "validate code against docs, never generate docs from code." Experience proved that too narrow. The tool people actually want does **both directions, continuously:**
+
+| Direction | Mode | What it does |
+|-----------|------|--------------|
+| code → docs | **Generate** | Reverse-engineer a complete canonical memory from any codebase. DocGuard scans and builds the code-truth skeleton; an AI agent writes the prose. |
+| code ↔ docs | **Sync** | When code changes, refresh the affected doc sections automatically — mechanical where deterministic, agent-assisted for prose. |
+| docs ↔ code | **Guard** | Validate that the memory still matches reality. Catch documented-but-deleted endpoints, undocumented routes, missing tests, unlogged drift. |
+
+The CLI orchestrates (scan, structure, verify); the AI agent does the language-specific writing. Together they keep the memory both **complete** and **accurate**.
+
+---
+
+## Complete + Accurate = Trustworthy
+
+A memory is only useful if you can trust it. DocGuard measures two things:
+
+- **Completeness** — is the map whole? (No missing chapters: architecture, data model, API surface, screens, environment.)
+- **Accuracy** — does the map match the territory? (The documented endpoints exist; the documented env vars are used; the schemas match the models.)
+
+A document can be beautifully formatted and completely wrong. DocGuard's validators that compare docs against **code truth** are what make a green check mean something — and when a check has nothing to validate, it says so honestly instead of showing a misleading pass.
+
+---
+
+## Any language, any project
+
+DocGuard documents **any** project, not just web/JS. It detects the ecosystem
+(JavaScript/TypeScript, Python, Rust, Go, Java/Kotlin, Ruby, PHP, C#) and any
+polyglot/monorepo mix, then builds a memory shaped for that project: a Rust CLI
+gets a Rust-shaped doc set; a Django app a Django-shaped one; a React app gets
+its screens and components.
+
+---
+
+## Why Now?
+
+1. **AI agents are primary developers.** They need structured context to work well. A canonical memory is the highest-leverage context you can give them.
+2. **Multi-agent development is real.** Claude Code, Copilot, Cursor, and humans touch the same repo in the same week. They need one shared, current source of truth.
+3. **Code volume is exploding; comprehension isn't keeping up.** AI makes adding code trivial. DocGuard makes *understanding* it trivial — and keeps that understanding current.
+
+---
+
+## The Lifecycle
+
+```
+generate ──▶ guard ──▶ sync ──▶ guard ──▶ …
+  (build)    (verify)  (keep    (verify)
+                        current)
+```
+
+- **Day 1:** `docguard generate --plan` → a complete first-draft memory of your repo (agent fills the prose).
+- **Every change:** `docguard sync` refreshes the derived sections; `docguard guard` verifies; the agent updates prose where flagged.
+- **Forever:** the memory stays complete and true. Any agent or human can understand your project in seconds.
+
+---
+
+## CDD and Other Methodologies
+
+- **+ Spec Kit (SDD):** Spec Kit generates code from specs (the build phase); DocGuard maintains the living memory and governance afterward. DocGuard ships as a Spec Kit extension.
+- **+ TDD/BDD:** `TEST-SPEC.md` declares what must be tested; DocGuard verifies the tests exist; TDD/BDD drive their implementation.
+- **+ Agile:** the memory grows sprint by sprint alongside the code. A 30-line `ARCHITECTURE.md` that is complete, current, and validated beats a 300-page document that's stale.
+
+---
+
+## Academic Foundations
+
+CDD is a practitioner methodology whose patterns align with peer-reviewed research:
+
+- **Generate → validate → evaluate pipeline** — inspired by the AITPG framework (Lopez et al., IEEE TSE 2026): multi-agent generation grounded in standards produces more comprehensive documentation while staying semantically aligned with expert references.
+- **Calibrated quality evaluation** — DocGuard's HIGH/MEDIUM/LOW labels and multi-signal scoring adapt the CJE framework from TRACE (Lopez et al., IEEE TMLCN 2026).
+- **Standards-grounded generation** — each canonical document maps to a relevant standard (arc42, C4, OWASP ASVS, ISO 29119, OpenAPI, 12-Factor App).
+
+> **Lead researcher**: [Martin Manuel Lopez](https://github.com/martinmanuel9) · [ORCID 0009-0002-7652-2385](https://orcid.org/0009-0002-7652-2385), University of Arizona
+
+---
+
+## 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.

{docguard_cli-0.10.0 → docguard_cli-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docguard-cli
-Version: 0.10.0
+Version: 0.11.0
 Summary: The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation. Zero dependencies.
 Project-URL: Homepage, https://github.com/raccioly/docguard
 Project-URL: Documentation, https://github.com/raccioly/docguard#readme
@@ -154,7 +154,28 @@ 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 required.
+`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.
+
+### Mechanical vs. agent fixes
+
+DocGuard splits drift into two kinds and is explicit about which is which:
+
+| Kind | Example | How it's fixed |
+|------|---------|----------------|
+| **Mechanical** (deterministic) | An endpoint documented in `API-REFERENCE.md` that the OpenAPI spec confirms is gone | `docguard fix --write` deletes the row + detail block itself — **no AI** |
+| **Agent** (needs judgment) | Rewriting an X-Ray prose section as CloudWatch; writing a new endpoint's request/response | Routed to an AI agent via `diagnose` / `fix --doc` prompts |
+
+`docguard fix --write` only touches docs marked `<!-- docguard:generated true -->` (override with `--force`), is idempotent, and prints exactly what changed. It never rewrites prose — that stays with the agent.
+
+### Hands-off loop (set and forget)
+
+```
+guard ──▶ fix --write (mechanical, auto) ──▶ guard ──▶ diagnose (agent prompts for the rest)
+```
+
+- **CI / pre-commit:** `docguard hooks --type pre-commit --auto-fix` installs a hook that applies mechanical fixes, re-stages the docs, then runs `guard`; anything left is surfaced as agent prompts.
+- **Agent-driven:** `docguard diagnose --auto` scaffolds missing docs **and** applies mechanical fixes, then emits prompts for the content rewrites that remain.
+- **JSON for automation:** `guard`/`diagnose --format json` include a `mechanicalFixes` array and tag each issue `mechanical` vs `agent`, so an agent can apply or delegate precisely.
 
 ---
 
@@ -216,6 +237,7 @@ DocGuard ships **13 commands**:
 | `init` | Initialize CDD docs from templates (interactive) |
 | `score` | CDD maturity score (0–100) with weighted breakdown |
 | `fix --doc <name>` | Generate AI prompt for a specific document |
+| `fix --write` | Apply deterministic fixes (remove stale documented endpoints) — no AI |
 | `diff` | Compare canonical docs vs actual code artifacts |
 | `agents` | Generate agent-specific config files |
 | `trace` | Requirements traceability matrix |

{docguard_cli-0.10.0 → docguard_cli-0.11.0}/README.md

@@ -130,7 +130,28 @@ 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 required.
+`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.
+
+### Mechanical vs. agent fixes
+
+DocGuard splits drift into two kinds and is explicit about which is which:
+
+| Kind | Example | How it's fixed |
+|------|---------|----------------|
+| **Mechanical** (deterministic) | An endpoint documented in `API-REFERENCE.md` that the OpenAPI spec confirms is gone | `docguard fix --write` deletes the row + detail block itself — **no AI** |
+| **Agent** (needs judgment) | Rewriting an X-Ray prose section as CloudWatch; writing a new endpoint's request/response | Routed to an AI agent via `diagnose` / `fix --doc` prompts |
+
+`docguard fix --write` only touches docs marked `<!-- docguard:generated true -->` (override with `--force`), is idempotent, and prints exactly what changed. It never rewrites prose — that stays with the agent.
+
+### Hands-off loop (set and forget)
+
+```
+guard ──▶ fix --write (mechanical, auto) ──▶ guard ──▶ diagnose (agent prompts for the rest)
+```
+
+- **CI / pre-commit:** `docguard hooks --type pre-commit --auto-fix` installs a hook that applies mechanical fixes, re-stages the docs, then runs `guard`; anything left is surfaced as agent prompts.
+- **Agent-driven:** `docguard diagnose --auto` scaffolds missing docs **and** applies mechanical fixes, then emits prompts for the content rewrites that remain.
+- **JSON for automation:** `guard`/`diagnose --format json` include a `mechanicalFixes` array and tag each issue `mechanical` vs `agent`, so an agent can apply or delegate precisely.
 
 ---
 
@@ -192,6 +213,7 @@ DocGuard ships **13 commands**:
 | `init` | Initialize CDD docs from templates (interactive) |
 | `score` | CDD maturity score (0–100) with weighted breakdown |
 | `fix --doc <name>` | Generate AI prompt for a specific document |
+| `fix --write` | Apply deterministic fixes (remove stale documented endpoints) — no AI |
 | `diff` | Compare canonical docs vs actual code artifacts |
 | `agents` | Generate agent-specific config files |
 | `trace` | Requirements traceability matrix |