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

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

@@ -6,10 +6,10 @@ description: AI-driven documentation repair with structured research workflow, t
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.9.9
+  version: 0.11.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.9.9 -->
+<!-- docguard:version: 0.11.1 -->
 
 # DocGuard Fix Skill
 
@@ -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.10.0/extensions/spec-kit-docguard → docguard_cli-0.11.1/.agent}/skills/docguard-guard/SKILL.md

@@ -7,10 +7,10 @@ description: Run DocGuard guard validation against Canonical-Driven Development
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.9.9
+  version: 0.11.1
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.9.9 -->
+<!-- docguard:version: 0.11.1 -->
 
 # DocGuard Guard Skill
 

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

@@ -6,10 +6,10 @@ description: Cross-document consistency analysis and quality assessment. Perform
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.9.9
+  version: 0.11.1
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.9.9 -->
+<!-- docguard:version: 0.11.1 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.10.0 → docguard_cli-0.11.1}/.agent/skills/docguard-score/SKILL.md

@@ -6,10 +6,10 @@ description: CDD maturity assessment with category-aware improvement roadmap. Ru
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.9.9
+  version: 0.11.1
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.9.9 -->
+<!-- docguard:version: 0.11.1 -->
 
 # DocGuard Score Skill
 

docguard_cli-0.11.1/.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.11.1
+  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.1}/.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.1}/.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.1}/.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.1}/AGENTS.md

@@ -96,6 +96,7 @@ extensions/spec-kit-docguard/
 
 ## Rules
 
+- **PR-first workflow — no direct-to-main commits.** Create a branch (`git checkout -b <type>/<slug>`), push, `gh pr create`, let CI run, self-review, squash-merge. Tag releases only after merge on `main`. The only acceptable direct-to-main: typo fixes in comments or README badge URLs.
 - Never commit without updating CHANGELOG.md
 - If code deviates from docs, add `// DRIFT: reason`
 - Security rules in SECURITY.md are mandatory

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

@@ -7,6 +7,97 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.1] - 2026-05-25
+
+Patch release addressing false positives surfaced by the v0.11.0 audit of the `wu-whatsappinbox` enterprise monorepo, generalized into a multi-tool IaC detector, plus several DocGuard self-audit improvements. Spec: `specs/003-v011-false-positives/`.
+
+### Fixed
+- **Docs-Sync no longer misclassifies frontend API clients as backend routes.** Dropped the ambiguous bare `'api'` from the route-directory convention list. `src/api/client.ts` (frontend axios) and similar are no longer scanned as Express/Next.js routes (FP-1). For Next.js App Router (`src/app/api`, `app/api`), only files matching the strict `route.{ts,tsx,js,jsx,mjs}` filename convention are counted — helper files in the same tree are skipped (FR-001, FR-002).
+- **Test files are no longer flagged as undocumented services or routes.** The docs-sync route and service loops now skip paths under `__tests__/` and filenames matching `*.{test,spec}.{ts,tsx,js,jsx,mjs,py,java,go}` (FP-2, FR-003, FR-004). Eliminates ~7 spurious warnings per monorepo with co-located tests.
+- **Build outputs no longer flagged as undocumented source.** Added `cdk.out`, `out`, `.nuxt`, `.claude` to the docs-coverage `IGNORE_DIRS` set (FP-3, FR-005).
+- **`config.ignore` is now honored by Docs-Coverage's source-directory scan** (FP-3, FR-006 / IR-5). Closes a long-standing inconsistency where other validators respected the user's ignore but the source-dir scan did not. Patterns like `**/cdk.out/**` now match the directory itself as well as files inside it.
+- **Worktree copies no longer double-counted.** `globMatch` in `cli/shared-ignore.mjs` now rejects paths under `.claude/worktrees/`, `.git/worktrees/`, and `.jj/` at any depth — same treatment as `node_modules` (FP-4, FR-007). Affects every Claude-Code project using parallel-agent worktrees.
+- **Check 1 (config files) no longer flags build-cache dotdirs as undocumented configs.** Now skips directories — `.nuxt`, `.claude`, etc. are excluded by `IGNORE_DIRS` for the source-dir scan instead.
+- **Check 1 (config files) now honors `config.ignore` too.** Originally fixed only for the source-directory scan; a follow-up audit reproduced the same FP-3 class with `.local` in `ignore` still being flagged. Both Docs-Coverage scans now call `shouldIgnore(entry, config) || shouldIgnore(entry + '/', config)`. Closes FR-015 (audit-confirmed gap).
+- **Test-Spec validator parses multi-path Journey rows correctly.** Previously a Journey cell like `` `path/a.test.ts`, `path/b.test.ts` `` was stripped of all backticks then `existsSync()`d as one string — a 100% false-positive rate on multi-path rows. Now: split on commas outside backticks, strip backticks per segment, evaluate each independently. Row passes if ANY referenced file has evidence. Glob entries (`foo_*.test.ts`) are expanded; `(N suites)` / `(N tests)` annotations are accepted as the author's explicit coverage claim. Closes FP-6 and FR-016.
+- **TODO-Tracking validator no longer false-positives on its own keyword list.** Previously the regex matched `TEMP(?!late|orar)` inside its own source. Two-part fix: (1) match restricted to text following a comment marker (`//`, `#`, `/*`, `<!--`, block `*`), (2) the validator skips its own source file (`cli/validators/todo-tracking.mjs`) since the docstring legitimately names the keywords.
+- **TODO-Tracking validator no longer false-positives on test fixture strings.** Test files commonly contain `// TODO:` inside template literals (`writeFileSync(..., '// TODO:')`) that single-line heuristics can't distinguish from real comments. Test files are now skipped by default; opt back in with `config.todoTracking.includeTestFiles = true`.
+- **Traceability validator's own fixtures no longer leak as orphan refs.** `tests/traceability.test.mjs` previously contained literal `REQ-001`/`REQ-002`/`REQ-003` strings that the validator scanned and reported as orphaned test references. Fixtures now build the IDs from parts so the validator's pattern doesn't match.
+
+### Added
+- **Multi-tool IaC detector + consolidated documentation reminder.** New `cli/scanners/iac.mjs` identifies projects shipping any of: **AWS CDK** (`cdk.json`), **Terraform** (`*.tf` files), **Pulumi** (`Pulumi.yaml`), **AWS SAM** (`template.yaml` with `AWS::Serverless::`), and **Serverless Framework** (`serverless.yml`). When an IaC project's ARCHITECTURE.md has no Infrastructure heading, DocGuard emits ONE actionable warning per detected tool naming the marker file location and the expected source layout — instead of multiple generic per-directory warnings (FR-009, FR-010, FR-011). The generic per-dir warnings inside IaC packages (`bin/`, `lib/`, `modules/`, `stacks/`, `constructs/`, `handlers/`, etc.) are suppressed in favor of these consolidated messages. The legacy `cli/scanners/cdk.mjs` is preserved as a thin re-export for backward compatibility.
+- **`## Infrastructure (IaC)` section in `templates/ARCHITECTURE.md.template`.** New projects initialized via `docguard init` start with placeholder tables for AWS CDK, Terraform, and Pulumi/SAM/Serverless layouts plus a Deployment Pipeline subsection (FR-012). Explicitly skippable for non-IaC projects via a header comment.
+- **`DEFAULT_IGNORE_DIRS`** exported from `cli/shared-ignore.mjs` — canonical shared ignore set covering build outputs (`dist`, `build`, `out`, `cdk.out`, `target`, `.gradle`), VCS internals (`.git`, `.jj`, `.hg`, `.svn`), package caches (`node_modules`, `vendor`, `.venv`, `__pycache__`), and framework synth outputs (`.next`, `.nuxt`, `.turbo`, `.vercel`, `.cache`, `.svelte-kit`) (FR-008). Added `target` (Rust/Java), `.gradle`, and `.svelte-kit` per the updated wu-whatsappinbox audit. Available for any future validator to import; existing per-validator `IGNORE_DIRS` sets are left in place (deferred migration).
+
+### Changed
+- **DocGuard package version bumped to 0.11.1** across `package.json` and all `extensions/spec-kit-docguard/` files (extension.yml + 5 SKILL.md files were referencing stale `v0.9.9`/`v0.10.0`).
+- **`docs-canonical/ARCHITECTURE.md`** updated to add `cli/writers/` and `cli/shared-*.mjs` to the Component Map and Layer Boundaries — closes a real doc gap surfaced by dogfooding (the writers/ directory has shipped for several releases without being documented).
+- **`specs/003-v011-false-positives/plan.md`** restructured to match the spec-kit `plan-template.md` shape (added Summary, Technical Context, Constitution Check, Project Structure sections). `tasks.md` rewritten with the spec-kit phased T### convention.
+
+### Internal
+- New test files: `tests/cdk-detection.test.mjs` (CDK + multi-tool IaC detector tests + `globMatch` worktree rejection + `DEFAULT_IGNORE_DIRS` shape). Existing test suites extended with regression cases for FP-1..FP-5, TODO-tracking false-positive guards, and IaC-tool detection across Terraform/Pulumi/SAM/Serverless. New tests are annotated with `// @req FR-NNN` / `// @req SC-NNN` comments for traceability. **Total: 329 tests passing (was 306, +23 new).**
+- **DocGuard self-audit improvements**: ran `docguard guard` on the repo as part of this release. Warnings dropped from **57 → 15** across the session by fixing real drift (stale extension versions, missing `cli/writers/` mention, traceability gaps) and reducing self-referential false positives (TODO validator scanning its own keyword list).
+- **Round 2 fixes after a second audit report**: FP-3 part B (`checkConfigFiles` honoring `config.ignore`), FP-6 (Test-Spec multi-path Journey row parsing with glob and `(N suites)` annotation support), additional `DEFAULT_IGNORE_DIRS` entries for Rust/Java/SvelteKit. **Total tests passing: 336** (was 306).
+- No new NPM dependencies. Zero schema or config-file changes.
+
+### Out of scope (deferred to v0.12)
+- Feature requests IR-1..IR-4, IR-6..IR-8 (per-validator severity, `--diff-only`, draft-staleness warning, `sync --section`, `.docguardignore` template at init, extended Next.js detection, `routesGlob`/`servicesGlob` overrides). IR-5 (honor ignore in source-dir scan) shipped as part of this release alongside FP-3.
+- Migrating all 17 modules that define their own `IGNORE_DIRS` constant to import `DEFAULT_IGNORE_DIRS` — mechanical, large diff, tracked separately.
+- Multi-line string-literal detection in TODO-Tracking — current heuristic still false-positives on `// TODO:` inside multi-line template literals. Workaround: keep test files out of TODO scanning (now default) or use `config.todoIgnore` globs.
+
+Credit: feedback from running v0.11.0 on the `wu-whatsappinbox` enterprise monorepo (audit score 98/100, 40 warnings).
+
+## [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.1/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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docguard-cli
-Version: 0.10.0
+Version: 0.11.1
 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.1}/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 |