docguard-cli 0.28.0 → 0.30.0

package/README.es.md

@@ -0,0 +1,102 @@
+<!-- docguard:translation source=README.md lang=es reviewed=2026-07-03 -->
+<!-- El README en inglés es la fuente canónica. Esta es una versión curada — los
+     números y listas volátiles viven solo en el original para que nunca diverjan del código. -->
+
+# 🛡️ DocGuard
+
+[English](README.md) · [Português (BR)](README.pt-BR.md) · **Español**
+
+> **La capa de enforcement para Spec-Driven Development.**
+> Valida. Puntúa. Garantiza. Entrega documentación que los agentes de IA realmente pueden usar.
+
+[![CI](https://github.com/raccioly/docguard/actions/workflows/ci.yml/badge.svg)](https://github.com/raccioly/docguard/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/docguard-cli)](https://www.npmjs.com/package/docguard-cli)
+[![PyPI](https://img.shields.io/pypi/v/docguard-cli)](https://pypi.org/project/docguard-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+> **✨ Mira lo que DocGuard detecta en 30 segundos — sin instalar nada:**
+> ```bash
+> npx docguard-cli demo
+> ```
+
+## ¿Qué es DocGuard?
+
+DocGuard es la herramienta de enforcement del **Canonical-Driven Development (CDD)**:
+una metodología donde la documentación es la fuente de la verdad y la herramienta
+**verifica, de forma determinista, que siga siendo verdad respecto al código**.
+
+La diferencia frente a otras herramientas de documentación: un resultado verde de
+DocGuard significa *"los documentos coinciden con el código, de forma verificable"* —
+no solo "los archivos existen". Extrae rutas, esquemas, variables de entorno, conteos
+y afirmaciones documentadas, y los compara contra el código real. Núcleo sin llamadas
+a LLM: determinista, offline, auditable.
+
+## Inicio rápido
+
+```bash
+# en el directorio de tu proyecto
+npx docguard-cli init       # crea los documentos canónicos (detecta tu stack)
+npx docguard-cli guard      # valida — verde significa "docs correctos"
+npx docguard-cli score      # nota de madurez de la documentación (0-100)
+```
+
+Para un proyecto existente, el camino inverso funciona mejor:
+
+```bash
+npx docguard-cli generate --plan --write   # ingeniería inversa: docs desde el código
+```
+
+## Los 5 comandos del día a día
+
+| Comando | Qué hace |
+|:--------|:---------|
+| `init`  | Inicializa el proyecto (detecta el stack automáticamente) |
+| `guard` | Valida los documentos contra el código — la puerta de CI |
+| `diff`  | Muestra las brechas entre docs y código (`--since <ref>` para impacto de PR) |
+| `sync`  | Regenera las secciones de "verdad del código" en los documentos |
+| `score` | Nota de madurez CDD, con desglose por categoría |
+
+La lista completa de comandos, validadores y flags está en el
+[README en inglés](README.md#usage) — el propio DocGuard la mantiene
+sincronizada con el código.
+
+## Integración con IA (nativa, no improvisada)
+
+DocGuard está diseñado para ser usado **por** agentes de IA, no solo por humanos:
+
+- **Servidor MCP** — `claude mcp add docguard -- npx docguard-cli mcp` expone
+  guard/score/explain/verify/diagnose como herramientas nativas para Claude,
+  Cursor y cualquier cliente MCP.
+- **Contrato JSON estable** — `guard --format json` con códigos de hallazgo
+  estables, explicables (`docguard explain <CÓDIGO>`) y suprimibles en línea.
+- **SARIF** — `guard --format sarif` se integra con GitHub Code Scanning.
+- **llms.txt / llms-full.txt / context pack** — superficies de contexto para
+  LLMs que leen el repositorio.
+- **GitHub Action** — anotaciones inline en el diff del PR + comentario fijo
+  con el impacto en los documentos canónicos.
+- **`agents --sync`** — AGENTS.md se convierte en la fuente canónica de
+  CLAUDE.md, las reglas de Cursor, las instrucciones de Copilot y demás — sin
+  duplicación manual, sin drift.
+
+Guía completa: [docs/ai-integration.md](docs/ai-integration.md) (en inglés).
+
+## Instalación permanente
+
+```bash
+npm install -g docguard-cli    # Node.js 18+
+# o vía Python:
+pip install docguard-cli       # wrapper de PyPI (requiere Node.js 18+)
+```
+
+## Comunidad
+
+- [Discusiones](https://github.com/raccioly/docguard/discussions) — preguntas e ideas
+- [Issues](https://github.com/raccioly/docguard/issues) — bugs y peticiones de features
+- [CHANGELOG](CHANGELOG.md) — historial completo de versiones
+- [Cómo contribuir](CONTRIBUTING.md)
+
+---
+
+**Licencia MIT** · Hecho para equipos que tratan la documentación como un contrato, no como un adorno.

package/README.md

@@ -1,5 +1,7 @@
 # 🛡️ DocGuard
 
+**English** · [Português (BR)](README.pt-BR.md) · [Español](README.es.md)
+
 > **The enforcement layer for Spec-Driven Development.**
 > Validate. Score. Enforce. Ship documentation that AI agents can actually use.
 
@@ -27,7 +29,7 @@
 ## Table of Contents
 
 - [What is DocGuard?](#what-is-docguard)
-- [What's New](#-whats-new)
+- [Why DocGuard?](#why-docguard)
 - [Quick Start](#-quick-start)
 - [Spec Kit Integration](#-spec-kit-integration)
 - [Usage](#usage)
@@ -38,6 +40,7 @@
 - [Examples](#-examples)
 - [Testing](#-testing)
 - [CI/CD Integration](#%EF%B8%8F-cicd-integration)
+- [What's New](#-whats-new)
 - [File Structure](#-file-structure)
 - [Configuration](#%EF%B8%8F-configuration)
 - [Research Credits](#-research-credits)
@@ -63,7 +66,7 @@ DocGuard is an official [GitHub Spec Kit](https://github.com/github/spec-kit) co
 
 ```mermaid
 graph TD
-    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (17)"]
+    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (18)"]
     Commands --> guard["guard"]
     Commands --> generate["generate"]
     Commands --> score["score"]
@@ -94,35 +97,14 @@ graph TD
 
 ---
 
-## ✨ What's New
-
-Recent highlights across the v0.16 → v0.19 line:
-
-- **`docguard explain <validator>`** — `docguard explain freshness` prints purpose, rules, common
-  failures, and fix recipes for any of the 24 validators. No need to dig into source.
-- **`docguard memory --diff`** — surface what changed in your canonical docs between two refs
-  (`HEAD~10..HEAD` by default). Great for code review and changelog drafting.
-- **`docguard score --diff`** — see exactly which validators moved the score up or down between
-  two commits. Pinpoints regressions without re-running the full suite by hand.
-- **`docguard upgrade --apply --pr`** — when the config schema bumps, DocGuard migrates
-  `.docguard.json` for you and (optionally) opens a PR with the change.
-- **Language-aware traceability** — both `docguard trace` *and* the guard-time Traceability validator
-  understand Python, Rust, Go, Java, Ruby, and PHP layouts in addition to JS/TS, via a shared pattern
-  set (`cli/shared-trace-patterns.mjs`) so the two never drift apart.
-- **Per-validator severity overrides** — escalate `freshness` to `high` for production repos,
-  demote `doc-quality` to `low` for prototypes. Configurable per-project.
-- **JSON Schema for `.docguard.json`** — IDE autocomplete, in-line docs, and validation via
-  `$schema`. Shipped in the package at `schemas/docguard-config.schema.json`.
-- **Version pin (`docguardVersion` + `--pin`)** — pin the CLI version your project supports so
-  CI fails loudly if someone bumps DocGuard without re-running the suite.
-- **Cross-process plan cache** — repeated runs reuse the validator plan across processes when
-  the working tree hasn't changed. ~30% faster guard runs on typical repos.
-- **Headless-aware banner** — `--quiet`, `--format json`, `--write`, and `--changed-only`
-  automatically suppress the banner so JSON output stays parse-clean.
-- **npm-pack smoke gate** — every release now extracts the actual tarball and runs the CLI
-  end-to-end before publish, catching missing-file regressions.
+## Why DocGuard?
 
-See [CHANGELOG.md](CHANGELOG.md) for the full history.
+Documentation that drifts from code is worse than no documentation — it
+confidently misleads humans and AI agents alike. DocGuard treats your canonical
+docs as an enforced contract: deterministic validators diff what the docs claim
+against what the code does, on every commit, with no LLM required. The full
+thesis (and the research behind it) lives in [PHILOSOPHY.md](PHILOSOPHY.md);
+recent feature highlights moved [below](#-whats-new).
 
 ---
 
@@ -150,6 +132,19 @@ docguard diagnose
 
 > **Note:** The Python package is a thin wrapper that delegates to `npx`. Node.js 18+ is required on the system.
 
+### More ways to integrate
+
+- **pre-commit** — changed-only guard on every commit:
+  ```yaml
+  repos:
+    - repo: https://github.com/raccioly/docguard
+      rev: v0.29.0
+      hooks: [{ id: docguard-guard }]   # docguard-guard-full for pre-push
+  ```
+- **MCP** (Claude, Cursor, any MCP client) — `claude mcp add docguard -- npx -y docguard-cli mcp`; 5 read-only tools (guard, score, explain, verify-claims, diagnose). Registry manifest ships in-repo (`server.json`, Smithery-ready).
+- **GitLab CI** — component staged at [`templates/ci/gitlab-component.yml`](templates/ci/gitlab-component.yml) (guard/score/ci job with a SARIF artifact).
+- **Homebrew** — `brew install raccioly/tap/docguard` (formula in [`packaging/homebrew/`](packaging/homebrew/)).
+
 ### Core Workflow
 
 ```bash
@@ -250,7 +245,7 @@ This installs DocGuard's slash commands (`/docguard.init`, `/docguard.guard`, `/
 
 ## Usage
 
-DocGuard ships **17 commands** (the "Daily 5" + 12 situational tools, including the zero-install `demo`). Six additional one-shot scaffolders are accessed via `docguard init --with <name>`. Eight v0.19 commands continue to work as deprecation aliases through v0.20.x — see [MIGRATION-v0.20.md](docs-implementation/MIGRATION-v0.20.md).
+DocGuard ships **18 commands** (the "Daily 5" + 13 situational tools, including the zero-install `demo` and the `mcp` server). Six additional one-shot scaffolders are accessed via `docguard init --with <name>`. Eight v0.19 commands continue to work as deprecation aliases through v0.20.x — see [MIGRATION-v0.20.md](docs-implementation/MIGRATION-v0.20.md).
 
 **The Daily 5** — what you'll reach for 95% of the time:
 
@@ -271,15 +266,19 @@ DocGuard ships **17 commands** (the "Daily 5" + 12 situational tools, including
 | `fix` | Generate AI fix instructions for specific docs (`--doc <name> --format prompt`) |
 | `fix --write` | Apply deterministic fixes (no AI — version bumps, counts, anchors, sections) |
 | `fix --history` | Audit log of every mechanical fix applied (from `.docguard/fixed.json`) |
-| `generate` | Reverse-engineer docs from existing codebase (`--plan` for AI scan) |
+| `generate` | Reverse-engineer docs from existing codebase (`--plan` for AI scan) — includes auto-generated Mermaid ER diagrams from your detected schemas (Prisma/Drizzle/TypeORM/Sequelize/Django/Rails) in DATA-MODEL.md |
 | `agent` | One-shot agent task graph — ordered, pre-filled code-truth, per-task verify (`--format json`) |
 | `explain <warning\|CODE>` | Paste any warning — or a finding code like `SEC001` — to get the validator's docstring, fix path, and how to suppress |
 | `verify --semantic` | Extract documented numbers/limits/enums (retention days, rate limits, GSI/role counts, status enums) as a task list for an agent to check against code — the semantic-drift class regex/AST can't see |
+| `verify --instructions` | Audit AGENTS.md/CLAUDE.md themselves for drift: duplicate rules, never-vs-always contradictions, stale file pointers, unknown commands — plus clustered rule pairs as agent judgment tasks |
 | `feedback` | Report likely false positives back to DocGuard — local-first record + a 1-click prefilled, redacted GitHub issue (zero typing) |
+| `mcp` | MCP server over stdio — exposes guard/score/explain/verify/diagnose as native tools for Claude, Cursor, and any MCP client. Setup: `claude mcp add docguard -- npx docguard-cli mcp` |
 | `memory` | Per-domain accuracy headline (endpoints / entities / env / tech) |
 | `memory --diff` | Drill into which specific claims don't match code |
+| `memory --pack` | Write `.docguard/context-pack.md` — compact, code-truth-stamped session-start context for AI agents |
 | `score --diff` | Drill into which checks pulled each category down |
 | `trace` / `trace --reverse <file>` | Requirements traceability — forward AND reverse |
+| `trace --features` | Per-feature spec-adherence scores (requirement coverage, task completion, task evidence, artifacts) — worst-first with fix hints |
 | `upgrade [--apply] [--pr]` | Check + migrate `.docguard.json` schema; `--pr` opens a PR |
 | `watch` | Live mode: re-run guard on file changes |
 
@@ -306,6 +305,11 @@ Run them solo (`docguard init --with hooks`) or stacked (`docguard init --with a
 | `--verbose` | Show detailed output | All |
 | `--quiet` / `-q` | Suppress banner — for hooks, CI loops, scripts | All |
 | `--format json` | Machine-readable output (clean JSON, no ANSI bleed) | guard, score, diff, trace, diagnose, memory, impact, explain |
+| `--format sarif` | SARIF 2.1.0 output — findings as rules/results for GitHub Code Scanning and SARIF dashboards | guard |
+| `--full` | Generate `llms-full.txt` (full doc bodies inlined) instead of the `llms.txt` link index | llms |
+| `--pack` | Write `.docguard/context-pack.md` — agent session-start context | memory |
+| `--sync` | Regenerate the agent-file family (CLAUDE.md, Copilot, Cursor, …) from AGENTS.md; hash-marked, never touches hand-written files without `--force` | agents |
+| `--check` | CI gate for the synced agent-file family — exit 2 when a variant is stale | agents |
 | `--force` | Overwrite existing files (creates `.bak` backups) | generate, agents, init |
 | `--force-redo` | Bypass ping-pong suppression in `.docguard/fixed.json` | fix --write |
 | `--profile <name>` | Starter / standard / enterprise | init |
@@ -547,6 +551,7 @@ DocGuard runs its own `guard`, `score`, `diff`, `diagnose`, and `badge` commands
 ```yaml
 name: DocGuard Guard
 on: [pull_request, push]
+permissions: { pull-requests: write }   # for the sticky PR comment (optional)
 jobs:
   docguard:
     runs-on: ubuntu-latest
@@ -558,6 +563,17 @@ jobs:
           command: guard
 ```
 
+On pull requests, guard mode also gives inline PR feedback (both default on):
+
+| Input | Default | Description |
+|-------|---------|-------------|
+| `annotations` | `true` | Inline `::error`/`::warning` annotations on the PR diff, one per guard finding (capped at 50; a final notice reports how many were elided) |
+| `pr-comment` | `true` | Sticky PR comment with the guard verdict, top findings (by code), and which canonical docs the PR's changed files impact (`diff --since origin/<base>`). Needs `permissions: pull-requests: write`; degrades to a log warning without it |
+
+Both run even when guard fails — that's when the feedback matters. Prefer native
+code-scanning integration? `docguard guard --format sarif` uploads straight to
+GitHub Code Scanning via `github/codeql-action/upload-sarif`.
+
 ### GitHub Actions — Auto-Fix (commits mechanical fixes back)
 
 ```yaml
@@ -592,6 +608,38 @@ Two ready-to-use templates ship with the Spec Kit extension and as standalone fi
 
 ---
 
+## ✨ What's New
+
+Recent highlights across the v0.16 → v0.19 line:
+
+- **`docguard explain <validator>`** — `docguard explain freshness` prints purpose, rules, common
+  failures, and fix recipes for any of the 24 validators. No need to dig into source.
+- **`docguard memory --diff`** — surface what changed in your canonical docs between two refs
+  (`HEAD~10..HEAD` by default). Great for code review and changelog drafting.
+- **`docguard score --diff`** — see exactly which validators moved the score up or down between
+  two commits. Pinpoints regressions without re-running the full suite by hand.
+- **`docguard upgrade --apply --pr`** — when the config schema bumps, DocGuard migrates
+  `.docguard.json` for you and (optionally) opens a PR with the change.
+- **Language-aware traceability** — both `docguard trace` *and* the guard-time Traceability validator
+  understand Python, Rust, Go, Java, Ruby, and PHP layouts in addition to JS/TS, via a shared pattern
+  set (`cli/shared-trace-patterns.mjs`) so the two never drift apart.
+- **Per-validator severity overrides** — escalate `freshness` to `high` for production repos,
+  demote `doc-quality` to `low` for prototypes. Configurable per-project.
+- **JSON Schema for `.docguard.json`** — IDE autocomplete, in-line docs, and validation via
+  `$schema`. Shipped in the package at `schemas/docguard-config.schema.json`.
+- **Version pin (`docguardVersion` + `--pin`)** — pin the CLI version your project supports so
+  CI fails loudly if someone bumps DocGuard without re-running the suite.
+- **Cross-process plan cache** — repeated runs reuse the validator plan across processes when
+  the working tree hasn't changed. ~30% faster guard runs on typical repos.
+- **Headless-aware banner** — `--quiet`, `--format json`, `--write`, and `--changed-only`
+  automatically suppress the banner so JSON output stays parse-clean.
+- **npm-pack smoke gate** — every release now extracts the actual tarball and runs the CLI
+  end-to-end before publish, catching missing-file regressions.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full history.
+
+---
+
 ## 📁 File Structure
 
 ```

package/README.pt-BR.md

@@ -0,0 +1,101 @@
+<!-- docguard:translation source=README.md lang=pt-BR reviewed=2026-07-03 -->
+<!-- O README em inglês é a fonte canônica. Esta é uma versão curada — números
+     e listas voláteis ficam apenas no original para nunca divergirem do código. -->
+
+# 🛡️ DocGuard
+
+[English](README.md) · **Português (BR)** · [Español](README.es.md)
+
+> **A camada de enforcement para Spec-Driven Development.**
+> Valide. Pontue. Garanta. Entregue documentação que agentes de IA conseguem realmente usar.
+
+[![CI](https://github.com/raccioly/docguard/actions/workflows/ci.yml/badge.svg)](https://github.com/raccioly/docguard/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/docguard-cli)](https://www.npmjs.com/package/docguard-cli)
+[![PyPI](https://img.shields.io/pypi/v/docguard-cli)](https://pypi.org/project/docguard-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+> **✨ Veja o que o DocGuard detecta em 30 segundos — sem instalar nada:**
+> ```bash
+> npx docguard-cli demo
+> ```
+
+## O que é o DocGuard?
+
+O DocGuard é a ferramenta de enforcement do **Canonical-Driven Development (CDD)** —
+uma metodologia em que a documentação é a fonte da verdade e a ferramenta **verifica,
+deterministicamente, que ela continua verdadeira em relação ao código**.
+
+A diferença para outras ferramentas de documentação: um resultado verde do DocGuard
+significa *"os documentos correspondem ao código, de forma verificável"* — não apenas
+"os arquivos existem". Ele extrai rotas, schemas, variáveis de ambiente, contagens e
+afirmações documentadas, e compara tudo com o código real. Núcleo com zero chamadas a
+LLM: determinístico, offline, auditável.
+
+## Início rápido
+
+```bash
+# no diretório do seu projeto
+npx docguard-cli init       # cria os documentos canônicos (detecta seu stack)
+npx docguard-cli guard      # valida — verde significa "docs corretos"
+npx docguard-cli score      # nota de maturidade da documentação (0-100)
+```
+
+Para um projeto existente, o caminho inverso funciona melhor:
+
+```bash
+npx docguard-cli generate --plan --write   # engenharia reversa: docs a partir do código
+```
+
+## Os 5 comandos do dia a dia
+
+| Comando | O que faz |
+|:--------|:----------|
+| `init`  | Inicializa o projeto (detecta o stack automaticamente) |
+| `guard` | Valida os documentos contra o código — o portão de CI |
+| `diff`  | Mostra a diferença entre docs e código (`--since <ref>` para impacto de PR) |
+| `sync`  | Regenera as seções de "verdade do código" nos documentos |
+| `score` | Nota de maturidade CDD, com detalhamento por categoria |
+
+A lista completa de comandos, validadores e flags está no
+[README em inglês](README.md#usage) — mantida sincronizada com o código pelo
+próprio DocGuard.
+
+## Integração com IA (nativo, não improvisado)
+
+O DocGuard foi desenhado para ser usado **por** agentes de IA, não só por humanos:
+
+- **Servidor MCP** — `claude mcp add docguard -- npx docguard-cli mcp` expõe
+  guard/score/explain/verify/diagnose como ferramentas nativas para Claude,
+  Cursor e qualquer cliente MCP.
+- **Contrato JSON estável** — `guard --format json` com códigos de finding
+  estáveis, explicáveis (`docguard explain <CÓDIGO>`) e supressíveis na linha.
+- **SARIF** — `guard --format sarif` integra com o GitHub Code Scanning.
+- **llms.txt / llms-full.txt / context pack** — superfícies de contexto para
+  LLMs que leem o repositório.
+- **GitHub Action** — anotações inline no diff do PR + comentário fixo com o
+  impacto nos documentos canônicos.
+- **`agents --sync`** — o AGENTS.md vira fonte canônica para CLAUDE.md, regras
+  do Cursor, instruções do Copilot e afins — sem duplicação manual, sem drift.
+
+Guia completo: [docs/ai-integration.md](docs/ai-integration.md) (em inglês).
+
+## Instalação permanente
+
+```bash
+npm install -g docguard-cli    # Node.js 18+
+# ou via Python:
+pip install docguard-cli       # wrapper PyPI (requer Node.js 18+)
+```
+
+## Comunidade
+
+- [Discussões](https://github.com/raccioly/docguard/discussions) — perguntas e ideias
+- [Issues](https://github.com/raccioly/docguard/issues) — bugs e pedidos de feature
+- [CHANGELOG](CHANGELOG.md) — histórico completo de versões
+- [Como contribuir](CONTRIBUTING.md)
+
+---
+
+**Licença MIT** · Feito para times que tratam documentação como contrato, não como enfeite.

package/STANDARD.md

@@ -610,16 +610,26 @@ Project-level configuration file that customizes validation for the specific pro
 
 ## 8. Validator Reference
 
-| # | Validator | Checks | Default | Severity |
-|---|-----------|--------|---------|----------|
-| 1 | **structure** | All required files exist | ✅ On | Error |
-| 2 | **docs-sync** | Source files have matching canonical doc entries | ✅ On | Warning |
-| 3 | **drift** | `// DRIFT:` comments have DRIFT-LOG entries | ✅ On | Error |
-| 4 | **changelog** | Staged changes have CHANGELOG entries | ✅ On | Warning |
-| 5 | **architecture** | Imports follow declared layer boundaries | ❌ Off | Error |
-| 6 | **test-spec** | Required tests exist per TEST-SPEC.md | ✅ On | Warning |
-| 7 | **security** | No secrets in code, security patterns followed | ❌ Off | Error |
-| 8 | **environment** | Env vars documented, .env.example exists | ✅ On | Warning |
+This specification defines the **CDD structure** — the files, sections, and
+markers of §4–§7. Validators are an **implementation detail of the DocGuard
+CLI** and are additive across releases, so this document deliberately does not
+enumerate them (an embedded table drifted two major versions behind the CLI —
+the exact failure mode CDD exists to prevent).
+
+The founding eight (structure, docs-sync, drift, changelog, architecture,
+test-spec, security, environment) map directly to the file formats in §5; the
+CLI has since grown well past twenty. For the authoritative, machine-governed
+list:
+
+- run `docguard guard` — every validator prints its name and result;
+- run `docguard explain <validator>` for any validator's contract;
+- see the [README Validators section](README.md#-validators), whose counts are
+  enforced against code by the `canonical-sync` validator on every guard run.
+
+A conforming third-party CDD implementation MUST validate the structural rules
+of §4–§6 (required files, section presence, DRIFT markers ↔ DRIFT-LOG) and MAY
+implement any further checks; the exit-code contract below is the stable
+interface.
 
 ### Exit Codes
 

package/cli/commands/agents.mjs

@@ -1,10 +1,19 @@
 /**
  * Agents Command — Generate agent-specific config files from AGENTS.md
  * Creates .cursor/rules/, .clinerules, .github/copilot-instructions.md, etc.
+ *
+ * v0.29 sync mode: AGENTS.md is the CANONICAL source; the generated family
+ * (CLAUDE.md, .clinerules, copilot-instructions, …) carries a source-hash
+ * marker. `--sync` regenerates every marked (or missing) variant; `--check`
+ * is the CI staleness gate (exit 2 when a marked variant's hash no longer
+ * matches AGENTS.md). Files that exist WITHOUT our marker are user content —
+ * never overwritten without --force. This kills the hand-duplication drift
+ * between agent files, which is exactly the failure class DocGuard exists for.
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
 import { c } from '../shared.mjs';
 
 const AGENT_TARGETS = {
@@ -40,6 +49,44 @@ const AGENT_TARGETS = {
   },
 };
 
+// ── Sync markers (v0.29) ─────────────────────────────────────────────────────
+
+const sourceHash = (content) => createHash('sha256').update(content).digest('hex').slice(0, 16);
+
+/**
+ * Stamp generated content with the sync marker. Text formats get HTML-comment
+ * lines; JSON gets a `_docguardSync` field (comments would break parsing).
+ * For frontmatter files (.mdc) the marker goes AFTER the closing `---` so the
+ * frontmatter stays the first bytes, as Cursor requires.
+ */
+function stampMarker(content, hash, targetPath) {
+  const marker = `<!-- docguard:agents-sync source=AGENTS.md hash=${hash} -->\n<!-- Do not edit — regenerate with: docguard agents --sync -->\n`;
+  if (targetPath.endsWith('.json')) {
+    try {
+      const obj = JSON.parse(content);
+      obj._docguardSync = { source: 'AGENTS.md', hash, note: 'Do not edit — regenerate with: docguard agents --sync' };
+      return JSON.stringify(obj, null, 2);
+    } catch { return content; }
+  }
+  if (content.startsWith('---\n')) {
+    const end = content.indexOf('\n---', 4);
+    if (end !== -1) {
+      const cut = end + 4;
+      return content.slice(0, cut) + '\n' + marker + content.slice(cut);
+    }
+  }
+  return marker + '\n' + content;
+}
+
+/** Extract the recorded source hash from a generated file, or null if unmarked. */
+function extractMarkerHash(content, targetPath) {
+  if (targetPath.endsWith('.json')) {
+    try { return JSON.parse(content)._docguardSync?.hash ?? null; } catch { return null; }
+  }
+  const m = content.match(/docguard:agents-sync source=AGENTS\.md hash=([0-9a-f]{16})/);
+  return m ? m[1] : null;
+}
+
 export function runAgents(projectDir, config, flags) {
   console.log(`${c.bold}🤖 DocGuard Agents — ${config.projectName}${c.reset}`);
   console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
@@ -53,6 +100,15 @@ export function runAgents(projectDir, config, flags) {
 
   const agentsContent = readFileSync(agentsPath, 'utf-8');
 
+  // ── v0.29: --check — CI staleness gate for the synced family ──
+  if (flags.check) {
+    return runAgentsCheck(projectDir, agentsContent, flags);
+  }
+  // ── v0.29: --sync — regenerate marked/missing variants from AGENTS.md ──
+  if (flags.sync) {
+    return runAgentsSync(projectDir, config, agentsContent, flags);
+  }
+
   // Parse which agents to generate for
   let targets = Object.keys(AGENT_TARGETS);
   const specificAgent = flags.agent;
@@ -95,6 +151,99 @@ export function runAgents(projectDir, config, flags) {
   console.log(`  Created: ${created}  Skipped: ${skipped}\n`);
 }
 
+// ── Sync + Check modes (v0.29) ───────────────────────────────────────────────
+
+/**
+ * `docguard agents --sync` — regenerate the agent-file family from AGENTS.md.
+ *
+ * Semantics per target:
+ *   - missing            → generate (stamped with the current source hash)
+ *   - exists, our marker → regenerate (marked files are OURS to update)
+ *   - exists, unmarked   → SKIP with a warning (hand-written user content;
+ *                          --force overrides, which is the only destructive
+ *                          path and is explicit)
+ */
+function runAgentsSync(projectDir, config, agentsContent, flags) {
+  const hash = sourceHash(agentsContent);
+  let synced = 0, fresh = 0, skipped = 0;
+
+  let targets = Object.keys(AGENT_TARGETS);
+  if (flags.agent) {
+    if (!AGENT_TARGETS[flags.agent]) {
+      console.log(`  ${c.red}Unknown agent: ${flags.agent}${c.reset}`);
+      console.log(`  Available: ${targets.join(', ')}\n`);
+      process.exit(1);
+    }
+    targets = [flags.agent];
+  }
+
+  for (const key of targets) {
+    const target = AGENT_TARGETS[key];
+    const targetPath = resolve(projectDir, target.path);
+    const exists = existsSync(targetPath);
+
+    if (exists) {
+      const current = readFileSync(targetPath, 'utf-8');
+      const recorded = extractMarkerHash(current, target.path);
+      if (recorded === null && !flags.force) {
+        console.log(`  ${c.yellow}⚠️  ${target.name}: ${target.path} exists without a sync marker (hand-written?) — skipped. Use --force to adopt it.${c.reset}`);
+        skipped++;
+        continue;
+      }
+      if (recorded === hash) {
+        console.log(`  ${c.dim}✓  ${target.name}: ${target.path} already in sync${c.reset}`);
+        fresh++;
+        continue;
+      }
+    }
+
+    const content = stampMarker(target.generate(agentsContent, config), hash, target.path);
+    const dir = dirname(targetPath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(targetPath, content, 'utf-8');
+    console.log(`  ${c.green}✅ ${target.name}${c.reset}: ${target.path} ${c.dim}(${exists ? 'resynced' : 'created'}, hash ${hash})${c.reset}`);
+    synced++;
+  }
+
+  console.log(`\n${c.bold}  ─────────────────────────────────────${c.reset}`);
+  console.log(`  Synced: ${synced}  In sync: ${fresh}  Skipped (unmarked): ${skipped}`);
+  console.log(`  ${c.dim}CI gate: ${c.cyan}docguard agents --check${c.dim} exits 2 when a variant goes stale.${c.reset}\n`);
+}
+
+/**
+ * `docguard agents --check` — CI staleness gate. Only files that CARRY our
+ * marker are judged (an unmarked or absent variant is the user's choice, not
+ * drift). Stale marked file → warning + exit code 2 (matches guard's
+ * warnings-exit contract). Uses process.exitCode, never process.exit, so
+ * stdout always drains (bug-105 discipline).
+ */
+function runAgentsCheck(projectDir, agentsContent, flags) {
+  const hash = sourceHash(agentsContent);
+  const stale = [];
+  let inSync = 0, unmanaged = 0;
+
+  for (const [, target] of Object.entries(AGENT_TARGETS)) {
+    const targetPath = resolve(projectDir, target.path);
+    if (!existsSync(targetPath)) { unmanaged++; continue; }
+    let recorded = null;
+    try { recorded = extractMarkerHash(readFileSync(targetPath, 'utf-8'), target.path); } catch { /* unreadable → unmanaged */ }
+    if (recorded === null) { unmanaged++; continue; }
+    if (recorded === hash) inSync++;
+    else stale.push(target.path);
+  }
+
+  if (stale.length > 0) {
+    for (const p of stale) {
+      console.log(`  ${c.yellow}⚠ ${p} is stale — AGENTS.md changed since it was generated.${c.reset}`);
+    }
+    console.log(`\n  ${c.yellow}${stale.length} agent file(s) out of sync.${c.reset} Fix: ${c.cyan}docguard agents --sync${c.reset}\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  console.log(`  ${c.green}✅ Agent-file family in sync${c.reset} ${c.dim}(${inSync} synced, ${unmanaged} unmanaged/absent — unmarked files are yours, not checked)${c.reset}\n`);
+}
+
 // ── Generator Functions ────────────────────────────────────────────────────
 
 function getCddBlock(config) {

package/cli/commands/diff.mjs

@@ -6,6 +6,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname, basename } from 'node:path';
 import { c } from '../shared.mjs';
+import { walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
 import { collectPackageJsons, detectDocker, grepEnvUsage, resolveSourceRoots } from '../shared-source.mjs';
 import { parseApiReferenceDoc, compareEndpoints } from '../scanners/api-doc.mjs';
 import { resolveApiSurface } from '../validators/api-surface.mjs';
@@ -379,22 +380,12 @@ function diffTests(dir, config = {}) {
 
 // ── Utilities ──────────────────────────────────────────────────────────────
 
+// v0.29 consolidation: traversal delegates to the shared canonical walker
+// (this copy was hiding in commands/, missed by the first validator sweep).
 function getFilesRecursive(dir) {
   const results = [];
-  if (!existsSync(dir)) return results;
-
-  const entries = readdirSync(dir);
-  for (const entry of entries) {
-    if (IGNORE_DIRS.has(entry) || entry.startsWith('.')) continue;
-    const fullPath = join(dir, entry);
-    try {
-      const stat = statSync(fullPath);
-      if (stat.isDirectory()) {
-        results.push(...getFilesRecursive(fullPath));
-      } else if (stat.isFile() && CODE_EXTENSIONS.has(extname(fullPath))) {
-        results.push(fullPath);
-      }
-    } catch { /* skip */ }
-  }
+  sharedWalkFiles(dir, (fullPath) => {
+    if (CODE_EXTENSIONS.has(extname(fullPath))) results.push(fullPath);
+  }, { ignoreDirs: IGNORE_DIRS });
   return results;
 }