docguard-cli 0.9.11 → 0.11.0

package/cli/writers/sections.mjs

@@ -0,0 +1,148 @@
+/**
+ * Section-addressable docs — the foundation for surgical, non-destructive doc
+ * maintenance.
+ *
+ * Canonical docs mix two kinds of content:
+ *   - CODE-DERIVED sections (endpoint tables, entity lists, env-var tables) that
+ *     DocGuard can regenerate from the codebase, and
+ *   - HUMAN prose (rationale, "why", design intent) that must NEVER be clobbered.
+ *
+ * We mark the regenerable regions with HTML comments so the doc stays plain,
+ * readable markdown:
+ *
+ *   <!-- docguard:section id=api-endpoints source=code -->
+ *   | `GET` | `/api/x` | … |
+ *   <!-- /docguard:section -->
+ *
+ * DocGuard rewrites ONLY the bytes between a section's open/close markers.
+ * Everything outside any marker (the human writing) is preserved exactly.
+ *
+ * Pure string transforms — idempotent, no disk I/O. Zero NPM dependencies.
+ */
+
+const OPEN_RE = /^[ \t]*<!--\s*docguard:section\b([^>]*?)-->[ \t]*$/;
+const CLOSE_RE = /^[ \t]*<!--\s*\/docguard:section\s*-->[ \t]*$/;
+
+/** Parse `id=foo source=code` style attributes from an open-marker tail. */
+function parseAttrs(attrStr) {
+  const attrs = {};
+  const re = /(\w[\w-]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"']+))/g;
+  let m;
+  while ((m = re.exec(attrStr)) !== null) {
+    attrs[m[1]] = m[2] ?? m[3] ?? m[4] ?? '';
+  }
+  return attrs;
+}
+
+/**
+ * Parse all well-formed sections in a document.
+ * A section is a line matching the open marker, then content lines, then a
+ * close-marker line. An open with no matching close is ignored (not corrupted).
+ * @returns {Array<{ id, source, attrs, openLine, closeLine, body }>}
+ */
+export function parseSections(content) {
+  const lines = String(content).split('\n');
+  const sections = [];
+  let open = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (open === null) {
+      const om = line.match(OPEN_RE);
+      if (om) {
+        const attrs = parseAttrs(om[1] || '');
+        open = { attrs, openLine: i };
+      }
+    } else if (CLOSE_RE.test(line)) {
+      sections.push({
+        id: open.attrs.id || '',
+        source: open.attrs.source || 'code',
+        attrs: open.attrs,
+        openLine: open.openLine,
+        closeLine: i,
+        body: lines.slice(open.openLine + 1, i).join('\n'),
+      });
+      open = null;
+    }
+    // Note: a second open before a close just extends the search for a close;
+    // we keep the FIRST open's start, so malformed nesting can't corrupt content.
+  }
+  return sections;
+}
+
+/** Get a single section by id, or null. */
+export function getSection(content, id) {
+  return parseSections(content).find(s => s.id === id) || null;
+}
+
+/** List section ids present in a document. */
+export function listSections(content) {
+  return parseSections(content).map(s => s.id);
+}
+
+/** Render a full marked section block (open marker + body + close marker). */
+export function renderSection(id, body, { source = 'code' } = {}) {
+  const inner = String(body).replace(/^\n+/, '').replace(/\n+$/, '');
+  return `<!-- docguard:section id=${id} source=${source} -->\n${inner}\n<!-- /docguard:section -->`;
+}
+
+/**
+ * Replace ONLY the body of an existing section, preserving its markers and all
+ * surrounding content. Idempotent: if the new body matches, returns unchanged.
+ * @returns {{ content: string, replaced: boolean }}
+ */
+export function replaceSection(content, id, newBody) {
+  const lines = String(content).split('\n');
+  const sections = parseSections(content);
+  const sec = sections.find(s => s.id === id);
+  if (!sec) return { content, replaced: false };
+
+  const inner = String(newBody).replace(/^\n+/, '').replace(/\n+$/, '');
+  if (sec.body === inner) return { content, replaced: false }; // idempotent no-op
+
+  const before = lines.slice(0, sec.openLine + 1);
+  const after = lines.slice(sec.closeLine);
+  const next = [...before, ...inner.split('\n'), ...after].join('\n');
+  return { content: next, replaced: true };
+}
+
+/**
+ * Replace a section's body if it exists; otherwise INSERT a new section.
+ * Insert position: `after:<id>` (after another section), 'top' (after the H1 /
+ * first heading), or 'end' (default, appended).
+ * @returns {{ content: string, action: 'replaced'|'inserted'|'unchanged' }}
+ */
+export function upsertSection(content, id, newBody, { source = 'code', position = 'end' } = {}) {
+  if (getSection(content, id)) {
+    const r = replaceSection(content, id, newBody);
+    return { content: r.content, action: r.replaced ? 'replaced' : 'unchanged' };
+  }
+
+  const block = renderSection(id, newBody, { source });
+  const lines = String(content).split('\n');
+
+  // Insert after a named section.
+  const afterMatch = /^after:(.+)$/.exec(position);
+  if (afterMatch) {
+    const target = parseSections(content).find(s => s.id === afterMatch[1].trim());
+    if (target) {
+      const before = lines.slice(0, target.closeLine + 1);
+      const after = lines.slice(target.closeLine + 1);
+      return { content: [...before, '', block, ...after].join('\n'), action: 'inserted' };
+    }
+  }
+
+  // Insert just after the first heading (keeps the doc title on top).
+  if (position === 'top') {
+    const hIdx = lines.findIndex(l => /^#{1,6}\s/.test(l));
+    if (hIdx >= 0) {
+      const before = lines.slice(0, hIdx + 1);
+      const after = lines.slice(hIdx + 1);
+      return { content: [...before, '', block, ...after].join('\n'), action: 'inserted' };
+    }
+  }
+
+  // Default: append at end (single trailing newline).
+  const base = String(content).replace(/\n+$/, '');
+  return { content: `${base}\n\n${block}\n`, action: 'inserted' };
+}

package/commands/docguard.fix.md

@@ -11,11 +11,27 @@ handoffs:
 
 # DocGuard Fix — AI-Assisted Documentation Repair
 
-Generate or repair canonical documentation by researching the actual codebase.
+Generate or repair canonical documentation. DocGuard splits fixes into two kinds:
 
-## What to do
+- **Mechanical (deterministic, no AI):** structural edits DocGuard applies itself with
+  `docguard fix --write` — e.g. removing an endpoint from `docs-canonical/API-REFERENCE.md`
+  that the OpenAPI spec confirms no longer exists (its table row + detail block are deleted).
+- **Agent (needs an AI):** content rewrites that require judgment — e.g. replacing an
+  X-Ray prose section with CloudWatch, or writing a new endpoint's request/response block.
+  These use the research-prompt workflow below.
 
-1. **Identify what needs fixing**:
+## Apply mechanical fixes first (fast, safe)
+
+```bash
+npx docguard-cli fix --write          # removes stale documented endpoints; idempotent
+```
+- Only edits docs marked `<!-- docguard:generated true -->` (use `--force` to override).
+- Prints exactly what it removed. Re-run is a no-op if nothing changed.
+- Run `docguard guard` afterward; whatever remains is agent work (below).
+
+## What to do (agent work)
+
+1. **Identify what needs fixing** (each issue is tagged `mechanical` or `agent`):
 ```bash
 npx docguard-cli diagnose
 ```

package/commands/docguard.guard.md

@@ -1,5 +1,5 @@
 ---
-description: Run DocGuard guard validation — check project documentation against CDD standards with 19 validators
+description: Run DocGuard guard validation — check project documentation against CDD standards with 20 validators
 handoffs:
   - label: Fix All Issues
     agent: docguard.fix
@@ -23,14 +23,14 @@ Run the DocGuard CLI to validate all documentation against Canonical-Driven Deve
 npx docguard-cli guard
 ```
 
-2. **Parse the output**. Each of the 19 validators reports ✅ (pass), ⚠️ (warning), or ❌ (fail):
+2. **Parse the output**. Each of the 20 validators reports ✅ (pass), ⚠️ (warning), ❌ (fail), or ➖ (N/A — nothing to validate). **A ➖ N/A is NOT a pass**: it means the validator found nothing to check (e.g. no API-REFERENCE.md, no DB schema, no layer boundaries declared). Don't read N/A as "healthy" — read it as "not assessed".
 
    | Validator | What It Checks |
    |-----------|---------------|
    | Structure | Required CDD files exist |
    | Doc Sections | Canonical docs have required sections |
    | Docs-Sync | External doc references are valid |
-   | Drift | Code deviations logged in DRIFT-LOG.md |
+   | Drift-Comments | `// DRIFT:` code comments logged in DRIFT-LOG.md |
    | Changelog | CHANGELOG.md is maintained |
    | Test-Spec | Tests match TEST-SPEC.md rules |
    | Environment | Environment documentation |
@@ -39,6 +39,7 @@ npx docguard-cli guard
    | Freshness | Docs updated within commit window |
    | Traceability | Requirements trace to tests |
    | Docs-Diff | Doc changes match code changes |
+   | API-Surface | API-REFERENCE.md endpoints match the real API surface (OpenAPI spec / routes) |
    | Metadata-Sync | Metadata headers are consistent |
    | Docs-Coverage | All config files documented |
    | Doc-Quality | Readability, IEEE 830 compliance |
@@ -49,7 +50,7 @@ npx docguard-cli guard
 
 3. **Triage findings by severity**:
    - **CRITICAL**: Structure, Security, Test-Spec failures
-   - **HIGH**: Doc Sections, Drift, Changelog, Traceability failures
+   - **HIGH**: Doc Sections, Drift-Comments, Changelog, Traceability, API-Surface (documented-but-absent endpoint) failures
    - **MEDIUM**: Freshness, Docs-Coverage, Doc-Quality, Metrics-Consistency warnings
    - **LOW**: TODO-Tracking, Schema-Sync, Spec-Kit, Metadata-Sync warnings
 

package/docs/doc-sections.md

@@ -0,0 +1,37 @@
+# Section-Addressable Docs
+
+DocGuard maintains canonical docs *surgically*: it regenerates the parts that are
+derived from code while never touching the prose a human wrote. It does this with
+HTML-comment markers that keep the document plain, readable markdown.
+
+## The marker format
+
+```markdown
+<!-- docguard:section id=api-endpoints source=code -->
+| `GET` | `/api/users` | … |
+<!-- /docguard:section -->
+```
+
+- **`id`** — a stable identifier for the section (e.g. `api-endpoints`, `entities`,
+  `env-vars`, `screens`). DocGuard addresses sections by id.
+- **`source`** — `code` means DocGuard owns and may regenerate this block from the
+  codebase; `human` means it is author-owned and DocGuard will not rewrite it.
+
+Markers must each sit on their own line. An open marker with no matching close is
+ignored (DocGuard never corrupts a malformed doc).
+
+## What DocGuard does and does not touch
+
+- It rewrites **only** the bytes between a `source=code` section's open and close
+  markers when the underlying code changes.
+- **Everything outside any marker — and any `source=human` section — is preserved
+  exactly.** Your rationale, "why" notes, and design intent are safe.
+
+## Why this matters
+
+This is the foundation for two things:
+
+1. **Complete generation** — `docguard generate` writes code-derived sections inside
+   markers, then an AI agent fills the prose around them.
+2. **Always up to date** — `docguard sync` refreshes just the affected section when
+   code changes, instead of regenerating (and clobbering) the whole document.

package/docs/quickstart.md

@@ -68,7 +68,7 @@ diagnose  →  AI reads prompts  →  AI fixes docs  →  guard verifies
 ## Verify
 
 ```bash
-npx docguard-cli guard        # Pass/fail check (19 validators)
+npx docguard-cli guard        # Pass/fail check (20 validators)
 npx docguard-cli score        # 0-100 maturity score
 ```
 

package/extensions/spec-kit-docguard/README.md

@@ -1,13 +1,16 @@
 # DocGuard — CDD Enforcement Extension for Spec Kit
 
-Enterprise-grade Canonical-Driven Development (CDD) enforcement for [Spec Kit](https://github.com/github/spec-kit). Validates, scores, and fixes project documentation with 19 automated validators, AI-driven research workflows, and spec-kit integration hooks.
+Enterprise-grade Canonical-Driven Development (CDD) enforcement and **AI-readable project memory** for [Spec Kit](https://github.com/github/spec-kit). DocGuard builds a complete, language-aware documentation memory of any codebase (`generate --plan`), keeps it always up to date as code changes (`sync`), and verifies it (`guard`) — with deterministic mechanical fixes (`fix --write`) where it can and grounded agent prompts where prose is needed.
 
 ## Features
 
-- **19 Validators** — Structure, Security, Doc Quality, Test-Spec, Drift, Freshness, and 13 more
-- **4 AI Skills** — Enterprise-grade AI behavior protocols (not just step-lists)
-- **3 Bash Scripts** — JSON-output orchestration for AI consumption
-- **Workflow Chaining** — YAML handoffs enable guard → fix → review → score flows
+- **20 Validators** — Structure, Security, Doc Quality, Test-Spec, Drift-Comments, API-Surface, Freshness, and 13 more
+- **Language-agnostic** — JS/TS, Python, Rust, Go, Java/Kotlin, Ruby, PHP, C#. Polyglot/monorepo-aware.
+- **AI-powered Generate** — `generate --plan` builds the code-truth skeleton in `<!-- docguard:section -->` markers and emits a structured agent task manifest; the AI writes the prose.
+- **Always up to date** — `sync` surgically refreshes code-truth doc sections in place, **preserves human prose**, flags prose for agent review.
+- **Mechanical `fix --write`** — deterministic, no-LLM: remove stale documented endpoints, refresh stale "N validators" counts, replace stale version refs, insert missing `## [Unreleased]`.
+- **5 AI Skills** — docguard-fix, docguard-guard, docguard-sync, docguard-review, docguard-score (enterprise-grade behavior protocols, not just step-lists)
+- **Workflow Chaining** — YAML handoffs enable guard → sync → fix → review → score flows
 - **Spec Kit Hooks** — Quality gate integrations at implement, tasks, and review phases
 - **Zero Dependencies** — Pure Node.js built-ins only
 

package/extensions/spec-kit-docguard/commands/fix.md

@@ -0,0 +1,74 @@
+---
+description: Fix documentation drift — mechanical (no AI) or AI-driven research, depending on the issue
+allowed-tools: Bash, Read, Edit
+---
+
+# DocGuard Fix
+
+DocGuard splits drift into two kinds and is explicit about which is which.
+
+- **Mechanical** (deterministic, no AI): apply with `docguard fix --write`. Covers
+  removing endpoints documented but absent in code, refreshing stale "N validators"
+  counts, replacing stale version references, inserting a missing `## [Unreleased]`.
+- **Agent** (needs judgment): content rewrites — e.g. updating an X-Ray section to
+  CloudWatch, writing a new endpoint's request/response block.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Execution
+
+### Step 1 — Apply mechanical fixes (fast, safe, no AI)
+
+```bash
+npx --yes docguard-cli@latest fix --write
+```
+
+Output lists every applied fix. Idempotent: re-running is a no-op if nothing changed.
+Only edits `<!-- docguard:generated true -->` docs unless `--force`.
+
+### Step 2 — Identify remaining issues by kind
+
+```bash
+npx --yes docguard-cli@latest diagnose --format json
+```
+
+Each issue is tagged `fixKind: mechanical` (mostly handled by step 1) or
+`fixKind: agent`. Focus on the agent ones.
+
+### Step 3 — Use the deep doc prompt for content rewrites
+
+For each affected canonical doc, get a research-grounded prompt:
+
+```bash
+npx --yes docguard-cli@latest fix --doc architecture
+npx --yes docguard-cli@latest fix --doc data-model
+npx --yes docguard-cli@latest fix --doc api-reference
+npx --yes docguard-cli@latest fix --doc security
+npx --yes docguard-cli@latest fix --doc test-spec
+npx --yes docguard-cli@latest fix --doc environment
+```
+
+Execute the research steps in each prompt: read actual code files, map modules,
+trace routes, extract real schemas, identify real auth patterns. Then write the
+sections — using real file paths, real module names, real dependencies. No placeholders.
+
+### Step 4 — Verify
+
+```bash
+npx --yes docguard-cli@latest guard
+```
+
+Iterate until clean (max 3 rounds; if still failing, report remaining issues).
+
+## Flags
+
+- `--write` — apply deterministic fixes in place (step 1).
+- `--doc <name>` — emit a research-grounded prompt for one specific document (step 3).
+- `--force` — for `--write`, edit docs that lack the generated marker.
+- `--format json` — machine-readable issue list (with `fixKind`).

package/extensions/spec-kit-docguard/commands/generate.md

@@ -11,7 +11,12 @@ handoffs:
 
 # DocGuard Generate
 
-Scans your codebase and generates canonical documentation: ARCHITECTURE.md, DATA-MODEL.md, TEST-SPEC.md, SECURITY.md, ENVIRONMENT.md, and API-REFERENCE.md.
+Scans your codebase (JS/TS, Python, Rust, Go, Java/Kotlin, Ruby, PHP, C# — polyglot/monorepo-aware) and generates the canonical documentation memory: ARCHITECTURE.md, DATA-MODEL.md, TEST-SPEC.md, SECURITY.md, ENVIRONMENT.md, API-REFERENCE.md, SCREENS.md.
+
+Two modes:
+
+- **`--plan`** (AI-powered, recommended) — emits a structured agent task manifest + writes the code-truth skeleton inside `<!-- docguard:section -->` markers. The AI agent then writes the prose grounded in scanned facts. Human prose is preserved.
+- **default** — purely deterministic generation: writes templated docs with TODO placeholders. Use when no AI agent is available.
 
 ## User Input
 
@@ -19,7 +24,25 @@ $ARGUMENTS
 
 ## Steps
 
-1. Run DocGuard generate on the current project:
+1. **Preview the plan** — what code-truth facts were captured + what the agent will write:
+
+```bash
+npx --yes docguard-cli@latest generate --plan $ARGUMENTS
+```
+
+2. **Scaffold the skeleton docs** (marked sections filled with code-truth, prose sections as agent-task placeholders):
+
+```bash
+npx --yes docguard-cli@latest generate --plan --write $ARGUMENTS
+```
+
+3. **Or get the machine-readable manifest** to drive an agent:
+
+```bash
+npx --yes docguard-cli@latest generate --plan --format json $ARGUMENTS
+```
+
+4. **Fallback** (no AI, deterministic generation):
 
 ```bash
 npx --yes docguard-cli@latest generate $ARGUMENTS

package/extensions/spec-kit-docguard/commands/guard.md

@@ -14,7 +14,7 @@ handoffs:
 
 # DocGuard Guard
 
-Validate your project against its canonical documentation. Runs 160+ automated checks across 19 validators.
+Validate your project against its canonical documentation. Runs 160+ automated checks across 20 validators.
 
 ## User Input
 
@@ -31,11 +31,11 @@ You **MUST** consider the user input before proceeding (if not empty).
 npx --yes docguard-cli@latest guard $ARGUMENTS
 ```
 
-2. Parse each validator's result and build a severity-ranked findings table.
+2. Parse each validator's result and build a severity-ranked findings table. Status glyphs: ✅ pass, ⚠️ warning, ❌ fail, ➖ N/A (nothing to validate — NOT a pass; the dimension was not assessed).
 
 3. **Triage by severity**:
    - **CRITICAL**: Structure, Security, Test-Spec failures → fix immediately
-   - **HIGH**: Doc Sections, Drift, Changelog, Traceability → fix before commit
+   - **HIGH**: Doc Sections, Drift-Comments, Changelog, Traceability, API-Surface → fix before commit
    - **MEDIUM**: Freshness, Docs-Coverage, Doc-Quality, Metrics → fix this sprint
    - **LOW**: TODO-Tracking, Schema-Sync, Spec-Kit, Metadata → fix when convenient
 
@@ -43,14 +43,14 @@ npx --yes docguard-cli@latest guard $ARGUMENTS
 
 5. Re-run guard after fixes. Iterate until all checks pass (max 3 iterations).
 
-## Validators (19 total)
+## Validators (20 total)
 
 | Validator | What It Checks |
 |-----------|---------------|
 | Structure | Required CDD files exist |
 | Doc Sections | Canonical docs have required sections |
 | Docs-Sync | External doc references are valid |
-| Drift | `// DRIFT:` comments have DRIFT-LOG entries |
+| Drift-Comments | `// DRIFT:` comments have DRIFT-LOG entries |
 | Changelog | CHANGELOG.md is maintained |
 | Test-Spec | TEST-SPEC.md matches actual test files |
 | Environment | Environment docs and .env.example exist |
@@ -59,6 +59,7 @@ npx --yes docguard-cli@latest guard $ARGUMENTS
 | Freshness | Docs updated after recent code changes |
 | Traceability | Canonical docs linked to source code |
 | Docs-Diff | Entity/route/field drift between code and docs |
+| API-Surface | API-REFERENCE.md endpoints match the real API surface (OpenAPI spec / routes) |
 | Metadata-Sync | Metadata headers are consistent |
 | Docs-Coverage | All config files documented |
 | Doc-Quality | Readability, IEEE 830 compliance |

package/extensions/spec-kit-docguard/commands/sync.md

@@ -0,0 +1,62 @@
+---
+description: Keep canonical docs always up to date — refresh code-truth sections in place, preserve human prose
+allowed-tools: Bash, Read, Edit
+---
+
+# DocGuard Sync
+
+Keep the documentation memory ALWAYS UP TO DATE. Sync re-derives every code-truth
+section (endpoints, entities, screens, tech stack, env vars) and refreshes the
+matching `source=code` sections of existing canonical docs in place. **Human prose
+is never touched** — it lives outside markers or in `source=human` sections.
+
+When a code section changes, the prose sections in that doc are flagged for agent review.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Execution
+
+1. Preview what will change (dry run, never writes):
+
+```bash
+npx --yes docguard-cli@latest sync $ARGUMENTS
+```
+
+2. If only `source=code` sections are stale, apply the mechanical refresh:
+
+```bash
+npx --yes docguard-cli@latest sync --write $ARGUMENTS
+```
+
+3. For each "prose to review" line, **read the affected doc and update the
+   surrounding human-written section to match the new code reality** (e.g. if the
+   endpoints table grew, update the API overview prose). Then re-run guard:
+
+```bash
+npx --yes docguard-cli@latest guard
+```
+
+## Flags
+
+- `--since <ref>` — also report which code files changed since this git ref (context for prose updates).
+- `--write` — apply the mechanical refreshes. Default is a dry-run preview.
+- `--force` — sync docs even without the `<!-- docguard:generated true -->` marker.
+- `--format json` — machine-readable output (`updates`, `reviews`, `skipped`).
+
+## When to use
+
+- **Before opening a PR:** `docguard sync --since main` to refresh any stale sections.
+- **On a pre-commit hook:** auto-keep the memory current.
+- **After a big refactor:** confirm the doc map still matches the territory.
+
+## Triage glyphs
+
+- `↻` mechanically refreshed (code section updated)
+- `•` stale (will refresh with `--write`)
+- `🤖` prose to review — open the doc, update the relevant human-written section

package/extensions/spec-kit-docguard/skills/docguard-fix/SKILL.md

@@ -36,9 +36,19 @@ Research the actual codebase to generate or repair canonical documentation that
 
 ## Execution Flow
 
+### Step 0: Apply Mechanical Fixes First (no AI needed)
+
+```bash
+npx docguard-cli fix --write 2>&1
+```
+
+Removes endpoints documented in `docs-canonical/API-REFERENCE.md` that the OpenAPI
+spec confirms no longer exist (table row + detail block). Only edits
+`docguard:generated` docs, idempotent, prints what changed. Don't hand-edit these.
+
 ### Step 1: Diagnose Current State
 
-Run the diagnostic to identify all issues:
+Run the diagnostic to identify all issues (each tagged `mechanical` or `agent`):
 
 ```bash
 npx docguard-cli diagnose 2>&1

package/extensions/spec-kit-docguard/skills/docguard-guard/SKILL.md

@@ -78,7 +78,8 @@ Classify every non-passing check using this priority matrix:
 
 **HIGH (fix before commit)**:
 - Doc Sections failures (missing required sections)
-- Drift detection (undocumented code deviations)
+- Drift-Comments (a `// DRIFT:` comment without a DRIFT-LOG.md entry)
+- API-Surface (API-REFERENCE.md documents an endpoint that no longer exists in code)
 - Changelog gaps
 - Traceability breaks
 
@@ -138,7 +139,7 @@ For each finding, provide a **specific, actionable fix** — not "fix the issue"
 
 Based on the triage results:
 
-- **If all PASS**: "All 19 validators passed. Project is CDD-compliant. Ready to commit."
+- **If all PASS**: "All 20 validators passed. Project is CDD-compliant. Ready to commit."
 - **If only MEDIUM/LOW warnings**: "Non-blocking warnings found. Safe to commit, but consider running `/docguard.fix` for automated remediation."
 - **If HIGH or CRITICAL failures**: "Blocking issues found. Fix these before committing. Suggest running `/docguard.fix --doc [most impactful doc]` next."
 

package/extensions/spec-kit-docguard/skills/docguard-sync/SKILL.md

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