docguard-cli 0.10.0 → 0.11.0

package/PHILOSOPHY.md

@@ -1,172 +1,125 @@
 # The Philosophy of Canonical-Driven Development
 
-> Why documentation must come first in the age of AI agents.
+> 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. They can scaffold entire applications, implement complex features, and refactor entire codebases.
+In 2026, AI coding agents can write thousands of lines of code in minutes. But they have a fatal flaw: **they don't remember.**
 
-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.
 
-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 **comprehension crisis of the AI era:**
 
-This is the **documentation crisis of the AI era:**
-
-> The faster AI writes code, the faster projects lose their design intent.
+> The faster AI writes code, the faster everyone loses the map of what was built.
 
 ---
 
 ## The Insight
 
-The solution isn't to write better code. It's to write better **canonical documentation** — and make it machine-enforceable.
+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.
 
-> **Canonical** (adj.): accepted as being accurate and authoritative; the standard form.
+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.**
 
-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.
+> **Canonical** (adj.): accepted as accurate and authoritative; the standard form.
 
 ---
 
 ## 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 |
+### Pillar 1: Documentation is a first-class, validated artifact
 
-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
+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, Two Purposes
+### Pillar 2: Two tiers — derived truth and human reasoning
 
-CDD separates documentation into two tiers:
+CDD separates documentation into two kinds of content, and treats them differently:
 
-**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.
+- **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.
 
-**Implementation docs** (`docs-implementation/`) are the map. They represent current state — what we HAVE built. They're updated as code changes, reflecting reality.
+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.
 
-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: Generate AND Guard — bidirectional, continuous
 
-### Pillar 3: Machine-Enforceable, Not Machine-Generated
+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:**
 
-Many tools generate docs from code. CDD does the opposite: it validates code against docs.
+| 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. |
 
-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.
+The CLI orchestrates (scan, structure, verify); the AI agent does the language-specific writing. Together they keep the memory both **complete** and **accurate**.
 
 ---
 
-## Why Now?
-
-Three forces are converging in 2025-2026 that make CDD necessary:
+## Complete + Accurate = Trustworthy
 
-### 1. AI Agents Are Becoming Primary Developers
+A memory is only useful if you can trust it. DocGuard measures two things:
 
-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.
+- **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.)
 
-### 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.
+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.
 
 ---
 
-## 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.
+## Any language, any project
 
-### 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.
+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.
 
 ---
 
-## 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.
+## Why Now?
 
-5. **Documentation stays alive** — because it's validated on every commit, docs can't rot. If code changes, DocGuard catches the misalignment.
+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.
 
 ---
 
-## Getting Started
+## The Lifecycle
 
-CDD is designed for progressive adoption:
+```
+generate ──▶ guard ──▶ sync ──▶ guard ──▶ …
+  (build)    (verify)  (keep    (verify)
+                        current)
+```
 
-**Day 1**: Create `AGENTS.md` and `docs-canonical/ARCHITECTURE.md`. Two files. That's CDD.
+- **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.
 
-**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.
+## CDD and Other Methodologies
 
-**Forever**: Every commit is validated. Every drift is logged. Every agent understands your project.
+- **+ 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, but its core patterns align with peer-reviewed research in AI-driven documentation and quality evaluation:
-
-### The Three-Stage Pipeline
-
-DocGuard's architecture follows a **generate → validate → evaluate** pipeline inspired by the AITPG framework (Lopez et al., IEEE TSE 2026), which demonstrated that multi-agent debate over RAG-grounded standards produces 32% more comprehensive documentation while maintaining semantic alignment with expert references.
-
-### Calibrated Quality Evaluation
+CDD is a practitioner methodology whose patterns align with peer-reviewed research:
 
-DocGuard's quality scoring (HIGH/MEDIUM/LOW labels, multi-signal composite scores) adapts the Calibrated Judge Evaluation (CJE) framework from TRACE (Lopez et al., IEEE TMLCN 2026), which showed that weighted multi-signal scoring with confidence intervals provides actionable quality gating for enterprise deployment.
+- **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).
 
-### Standards-Grounded Generation
-
-Both AITPG and TRACE demonstrate that grounding AI-generated content in vectorized standards (ISO 29119, 3GPP) dramatically improves output quality. DocGuard applies this principle by mapping each canonical document to its relevant industry standard (arc42, C4, OWASP ASVS, ISO 29119, OpenAPI 3.1, 12-Factor App).
-
-> **Full citations**: See [CONTRIBUTING.md — Research & Academic Credits](CONTRIBUTING.md#research--academic-credits)
->
 > **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 to it.
+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.

package/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 |

package/cli/commands/diagnose.mjs

@@ -21,6 +21,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execSync, execFileSync } from 'node:child_process';
+import { applyAllMechanicalFixes } from './fix.mjs';
 
 // Map validator failures to the right fix --doc target
 const VALIDATOR_TO_DOC = {
@@ -65,13 +66,6 @@ const FIX_INSTRUCTIONS = {
     description: 'A // DRIFT: code comment has no matching DRIFT-LOG.md entry. Add the entry or remove the comment.',
     autoFixable: false,
   },
-  'API-Surface': {
-    action: 'Reconcile API-REFERENCE.md with the actual API surface',
-    command: 'docguard fix --doc api-reference',
-    llmCommand: '/docguard.fix --doc api-reference',
-    description: 'docs-canonical/API-REFERENCE.md documents endpoints that no longer exist in code (or omits real ones). Remove deleted endpoints and add missing ones to match the OpenAPI spec / route definitions, then log the change in CHANGELOG.md and DRIFT-LOG.md.',
-    autoFixable: false,
-  },
   'Changelog': {
     action: 'Update CHANGELOG.md',
     description: 'CHANGELOG.md is missing or has no [Unreleased] section. Add recent changes.',
@@ -112,6 +106,78 @@ const FIX_INSTRUCTIONS = {
     description: 'Documents haven\'t been reviewed since recent code changes. Re-run fix --doc for each stale doc.',
     autoFixable: false,
   },
+  // ── Routed (Phase F): these used to fall through to a generic "Manual review needed" ──
+  'Metrics-Consistency': {
+    action: 'Update stale number(s) in docs',
+    command: 'docguard fix --write',
+    llmCommand: 'docguard fix --write',
+    description: 'A doc claims a different count than the actual. Mechanical replace — no AI needed.',
+    autoFixable: true,
+  },
+  'Metadata-Sync': {
+    action: 'Update stale version reference(s)',
+    command: 'docguard fix --write',
+    llmCommand: 'docguard fix --write',
+    description: 'Docs reference an older version than the manifest. Mechanical replace — no AI needed.',
+    autoFixable: true,
+  },
+  'Docs-Sync': {
+    action: 'Reference the route/service in a canonical doc',
+    command: 'docguard fix --doc architecture',
+    llmCommand: '/docguard.fix --doc architecture',
+    description: 'A code file under routes/services is not referenced by any canonical doc. Add it (or its module) to ARCHITECTURE.md.',
+    autoFixable: false,
+  },
+  'Docs-Diff': {
+    action: 'Reconcile the documented vs. real surface',
+    command: 'docguard diff',
+    llmCommand: '/docguard.fix',
+    description: 'Tech stack or test files documented but not found in code (or vice versa). Inspect with `docguard diff`.',
+    autoFixable: false,
+  },
+  'Docs-Coverage': {
+    action: 'Reference the missing config/dotfile/source dir in docs',
+    command: 'docguard fix --doc architecture',
+    llmCommand: '/docguard.fix --doc architecture',
+    description: 'A project config/source dir is undocumented. Add a reference to the appropriate canonical doc.',
+    autoFixable: false,
+  },
+  'Doc-Quality': {
+    action: 'Improve readability / structure of the flagged doc',
+    command: 'docguard fix --doc',
+    llmCommand: '/docguard.fix --doc',
+    description: 'Passive voice, low atomicity, or weak structure detected. Re-run fix --doc for the affected file.',
+    autoFixable: false,
+  },
+  'TODO-Tracking': {
+    action: 'Track or remove the TODO/FIXME',
+    description: 'An untracked TODO/FIXME in source. Add it to ROADMAP.md / CURRENT-STATE.md, open an issue, or remove it.',
+    autoFixable: false,
+  },
+  'Traceability': {
+    action: 'Link the requirement ID to its test(s)',
+    description: 'A documented requirement ID has no matching reference in any test file. Add `@req FR-XXX` to the test that verifies it.',
+    autoFixable: false,
+  },
+  'Schema-Sync': {
+    action: 'Document the model in DATA-MODEL.md',
+    command: 'docguard fix --doc data-model',
+    llmCommand: '/docguard.fix --doc data-model',
+    description: 'A database model in code is not documented in DATA-MODEL.md. Add an Entity entry for it.',
+    autoFixable: false,
+  },
+  'Spec-Kit': {
+    action: 'Add the missing Spec Kit artifact / section',
+    description: 'A Spec Kit artifact (spec.md / plan.md / tasks.md) is missing a required section, FR-ID, or phased task structure. Edit the spec to match the standard.',
+    autoFixable: false,
+  },
+  'API-Surface': {
+    action: 'Reconcile API-REFERENCE.md with the real API surface',
+    command: 'docguard fix --write',
+    llmCommand: 'docguard fix --write',
+    description: 'Documented-but-absent endpoints can be deleted mechanically with `docguard fix --write`. Undocumented-in-code endpoints need an agent to write the request/response block (`/docguard.fix --doc api-reference`).',
+    autoFixable: true,
+  },
 };
 
 export function runDiagnose(projectDir, config, flags) {
@@ -127,29 +193,34 @@ export function runDiagnose(projectDir, config, flags) {
 
   // ── Step 3: Auto-fix (only with --auto flag) or suggest fixes ──
   const shouldAutoFix = flags.auto && flags.format !== 'json';
+  // Mechanical fixes = deterministic, no-LLM edits (e.g. remove a documented
+  // endpoint the spec confirms is gone). Surfaced by the API-Surface validator.
+  const mechanicalCount = countMechanicalFixes(guardData);
   if (issues.length > 0) {
     const autoFixable = issues.filter(i => i.autoFixable);
     const hasStructural = issues.some(i => i.validator === 'Structure');
 
-    if (shouldAutoFix && (hasStructural || autoFixable.length > 0)) {
-      // Run init to create missing files
+    if (shouldAutoFix && (hasStructural || autoFixable.length > 0 || mechanicalCount > 0)) {
+      // 1. init — create missing files
       try {
         const cliPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'docguard.mjs');
-        execFileSync(process.execPath, [cliPath, 'init', '--dir', projectDir], {
-          encoding: 'utf-8',
-          stdio: 'pipe',
-        });
+        execFileSync(process.execPath, [cliPath, 'init', '--dir', projectDir], { encoding: 'utf-8', stdio: 'pipe' });
       } catch { /* init may partially succeed */ }
 
-      // Run generate to fill in MISSING content only (never --force, which would overwrite existing docs)
+      // 2. generate — fill MISSING content only (never --force; won't overwrite existing docs)
       try {
         const cliPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'docguard.mjs');
-        execFileSync(process.execPath, [cliPath, 'generate', '--dir', projectDir], {
-          encoding: 'utf-8',
-          stdio: 'pipe',
-        });
+        execFileSync(process.execPath, [cliPath, 'generate', '--dir', projectDir], { encoding: 'utf-8', stdio: 'pipe' });
       } catch { /* generate may partially succeed */ }
 
+      // 3. mechanical fixes — apply ALL deterministic edits (no LLM):
+      // endpoint removal, stale counts, stale versions, changelog header.
+      let mechApplied = 0;
+      try {
+        const r = applyAllMechanicalFixes(projectDir, config, { force: flags.force });
+        mechApplied = r.applied.length;
+      } catch { /* best-effort */ }
+
       // Re-run guard to see what's still broken
       guardData = runGuardInternal(projectDir, config);
       issues = collectIssues(guardData);
@@ -157,20 +228,30 @@ export function runDiagnose(projectDir, config, flags) {
       if (!flags.format || flags.format === 'text') {
         const fixedCount = autoFixable.length - issues.filter(i => i.autoFixable).length;
         if (fixedCount > 0) {
-          console.log(`  ${c.green}⚡ Auto-fixed ${fixedCount} issue(s)${c.reset} (created/regenerated docs)\n`);
+          console.log(`  ${c.green}⚡ Auto-fixed ${fixedCount} issue(s)${c.reset} (created/regenerated docs)`);
         }
+        if (mechApplied > 0) {
+          console.log(`  ${c.green}⚡ Applied ${mechApplied} mechanical fix(es)${c.reset} (removed stale API endpoints)`);
+        }
+        if (fixedCount > 0 || mechApplied > 0) console.log('');
+      }
+    } else if (!shouldAutoFix && (!flags.format || flags.format === 'text')) {
+      // Suggest-only mode — be accurate about what each path does.
+      if (mechanicalCount > 0) {
+        console.log(`  ${c.green}🔧 ${mechanicalCount} issue(s) are mechanically fixable — no AI needed.${c.reset} Apply with:`);
+        console.log(`     ${c.cyan}docguard fix --write${c.reset}${c.dim}  (removes stale documented endpoints)${c.reset}`);
       }
-    } else if (!shouldAutoFix && (hasStructural || autoFixable.length > 0) && (!flags.format || flags.format === 'text')) {
-      // Suggest-only mode: tell user what they can do (LLM-first)
-      console.log(`  ${c.yellow}💡 ${autoFixable.length + (hasStructural ? 1 : 0)} issue(s) can be auto-fixed.${c.reset} Run with ${c.cyan}--auto${c.reset} to create/regenerate docs, or manually:`);
-      if (agentMode === 'llm') {
-        if (hasStructural) console.log(`     ${c.dim}/docguard.init${c.reset}`);
-        if (autoFixable.length > 0) console.log(`     ${c.dim}/docguard.fix${c.reset}`);
-      } else {
-        if (hasStructural) console.log(`     ${c.dim}docguard init --dir .${c.reset}`);
-        if (autoFixable.length > 0) console.log(`     ${c.dim}docguard generate --dir . --force${c.reset}`);
+      if (hasStructural || autoFixable.length > 0) {
+        console.log(`  ${c.yellow}💡 ${autoFixable.length + (hasStructural ? 1 : 0)} issue(s) can be scaffolded/regenerated.${c.reset} Run ${c.cyan}docguard diagnose --auto${c.reset} (creates missing docs + applies mechanical fixes), or:`);
+        if (agentMode === 'llm') {
+          if (hasStructural) console.log(`     ${c.dim}/docguard.init${c.reset}`);
+          if (autoFixable.length > 0) console.log(`     ${c.dim}/docguard.fix${c.reset}`);
+        } else {
+          if (hasStructural) console.log(`     ${c.dim}docguard init --dir .${c.reset}`);
+          if (autoFixable.length > 0) console.log(`     ${c.dim}docguard generate --dir . --force${c.reset}`);
+        }
       }
-      console.log('');
+      if (mechanicalCount > 0 || hasStructural || autoFixable.length > 0) console.log('');
     }
   }
 
@@ -201,46 +282,65 @@ export function runDiagnose(projectDir, config, flags) {
   }
 }
 
+/** Count deterministic (no-LLM) fixes available across guard results. */
+function countMechanicalFixes(guardData) {
+  let n = 0;
+  for (const v of guardData.validators) {
+    if (Array.isArray(v.fixes)) n += v.fixes.length;
+  }
+  return n;
+}
+
+/**
+ * A documented-but-absent endpoint is MECHANICALLY fixable (deterministic
+ * removal via `docguard fix --write`) — distinct from drift that needs an agent.
+ */
+function isMechanicalMessage(validator, message) {
+  return validator === 'API-Surface' && /not found in code/i.test(message);
+}
+
 /**
  * Collect issues from guard results with fix metadata.
  */
 function collectIssues(guardData) {
   const issues = [];
   for (const v of guardData.validators) {
-    if (v.status === 'skipped' || v.status === 'pass') continue;
+    if (v.status === 'skipped' || v.status === 'pass' || v.status === 'na') continue;
 
     const fixInfo = FIX_INSTRUCTIONS[v.name] || { action: `Review ${v.name}`, description: 'Manual review needed.', autoFixable: false };
     const docTarget = VALIDATOR_TO_DOC[v.name];
 
-    for (const err of v.errors) {
-      issues.push({
-        severity: 'error',
-        validator: v.name,
-        message: err,
-        action: fixInfo.action,
-        command: fixInfo.command || null,
-        llmCommand: fixInfo.llmCommand || null,
-        docTarget,
-        autoFixable: fixInfo.autoFixable || false,
-      });
-    }
-    for (const warn of v.warnings) {
-      issues.push({
-        severity: 'warning',
+    const mkIssue = (severity, message) => {
+      const mechanical = isMechanicalMessage(v.name, message);
+      return {
+        severity,
         validator: v.name,
-        message: warn,
-        action: fixInfo.action,
-        command: fixInfo.command || null,
-        llmCommand: fixInfo.llmCommand || null,
-        docTarget,
+        message,
+        action: mechanical ? 'Remove stale endpoint from API-REFERENCE.md' : fixInfo.action,
+        // Mechanical fixes point at the deterministic CLI applier, not an LLM.
+        command: mechanical ? 'docguard fix --write' : (fixInfo.command || null),
+        llmCommand: mechanical ? null : (fixInfo.llmCommand || null),
+        mechanical,
+        docTarget: mechanical ? null : docTarget,
         autoFixable: fixInfo.autoFixable || false,
-      });
-    }
+      };
+    };
+
+    for (const err of v.errors) issues.push(mkIssue('error', err));
+    for (const warn of v.warnings) issues.push(mkIssue('warning', warn));
   }
   return issues;
 }
 
 function outputJSON(guardData, scoreData, issues) {
+  // Structured, deterministic fix actions an agent or `--write` can apply directly.
+  const mechanicalFixes = [];
+  for (const v of guardData.validators) {
+    if (Array.isArray(v.fixes)) {
+      for (const f of v.fixes) mechanicalFixes.push({ validator: v.name, ...f });
+    }
+  }
+
   const result = {
     project: guardData.project,
     profile: guardData.profile,
@@ -254,8 +354,13 @@ function outputJSON(guardData, scoreData, issues) {
       message: i.message,
       action: i.action,
       command: i.command,
+      // 'mechanical' = deterministic CLI fix (docguard fix --write);
+      // 'agent' = needs an AI agent to write content.
+      fixKind: i.mechanical ? 'mechanical' : 'agent',
       docTarget: i.docTarget,
     })),
+    // Deterministic actions consumable by `docguard fix --write` or an agent.
+    mechanicalFixes,
     // Unique fix commands for automation
     fixCommands: [...new Set(issues.filter(i => i.command).map(i => i.command))],
     timestamp: new Date().toISOString(),