docguard-cli 0.10.0 → 0.11.1

package/cli/writers/api-reference.mjs

@@ -0,0 +1,101 @@
+/**
+ * API-REFERENCE.md Writer — deterministic, structural edits only.
+ *
+ * Used by `docguard fix --write` to MECHANICALLY remove endpoints that are
+ * documented but no longer exist in the actual API surface. This performs NO
+ * content rewriting (that needs an LLM) — it only deletes the structural pieces
+ * that document a now-absent endpoint:
+ *   1. its summary-table row:   | `GET` | `/api/...` | ... |
+ *   2. its detail block:        #### GET `/api/...`  … up to the next heading
+ *
+ * Pure string transform — idempotent, no disk I/O here.
+ *
+ * Zero NPM dependencies — pure Node.js built-ins only.
+ */
+
+import { normalizePath, endpointKey } from '../scanners/api-doc.mjs';
+
+const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']);
+const HEADING_RE = /^#{1,6}\s/;
+// An endpoint detail heading: "#### GET `/path`" (backticks optional, any level).
+const ENDPOINT_HEADING_RE = /^#{2,6}\s+`?(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)`?\s+`?(\/[^\s`|]+)`?/i;
+
+/** True if the doc is DocGuard-generated (safe for `--write` to edit). */
+export function hasGeneratedMarker(content) {
+  return /<!--\s*docguard:generated\s+true\s*-->/i.test(content || '');
+}
+
+/**
+ * If a markdown line is an API summary-table row, return its endpoint key.
+ * Row shape: | `GET` | `/api/...` | ... |
+ */
+function tableRowKey(line) {
+  if (!line.includes('|')) return null;
+  const cells = line.split('|').map(s => s.trim()).filter(s => s.length > 0);
+  if (cells.length < 2) return null;
+  const method = cells[0].replace(/`/g, '').trim().toUpperCase();
+  if (!HTTP_METHODS.has(method)) return null;
+  for (let i = 1; i < cells.length; i++) {
+    const cand = cells[i].replace(/`/g, '').trim();
+    if (cand.startsWith('/')) return endpointKey(method, cand);
+  }
+  return null;
+}
+
+/** If a line is an endpoint detail heading, return its endpoint key. */
+function headingKey(line) {
+  const m = line.match(ENDPOINT_HEADING_RE);
+  if (!m) return null;
+  return endpointKey(m[1], m[2]);
+}
+
+/**
+ * Remove the table row(s) and detail block(s) for the given endpoints.
+ *
+ * @param {string} content - API-REFERENCE.md content
+ * @param {Array<{method:string,path:string}>} endpoints - endpoints to remove
+ * @returns {{ content: string, removed: string[] }} new content + removed keys
+ */
+export function removeEndpoints(content, endpoints) {
+  const targets = new Set((endpoints || []).map(e => endpointKey(e.method, e.path)));
+  if (targets.size === 0) return { content, removed: [] };
+
+  const lines = content.split('\n');
+  const out = [];
+  const removed = new Set();
+  let skippingBlock = false;
+
+  for (const line of lines) {
+    const isHeading = HEADING_RE.test(line);
+
+    if (isHeading) {
+      // Any heading terminates a block we were skipping.
+      const hk = headingKey(line);
+      if (hk && targets.has(hk)) {
+        // Start (or continue into a new) skipped detail block.
+        skippingBlock = true;
+        removed.add(hk);
+        continue; // drop the heading line itself
+      }
+      // A non-target heading ends skipping and is kept.
+      skippingBlock = false;
+      out.push(line);
+      continue;
+    }
+
+    if (skippingBlock) continue; // inside a removed detail block
+
+    // Not skipping: drop a matching summary-table row.
+    const rk = tableRowKey(line);
+    if (rk && targets.has(rk)) {
+      removed.add(rk);
+      continue;
+    }
+
+    out.push(line);
+  }
+
+  return { content: out.join('\n'), removed: [...removed] };
+}
+
+export { normalizePath };

package/cli/writers/mechanical.mjs

@@ -0,0 +1,116 @@
+/**
+ * Mechanical Fix Registry — applies deterministic, no-LLM fixes in place.
+ *
+ * Validators surface structured `fixes[]` actions; this module knows how to
+ * apply each TYPE safely and idempotently. These are surgical token/structure
+ * edits the validator already located precisely — never prose rewrites.
+ *
+ * Fix types:
+ *   - replace-count   : stale "N validators/checks" → actual count (Metrics-Consistency)
+ *   - replace-version : stale version ref → current version (Metadata-Sync)
+ *   - insert-changelog-unreleased : add a `## [Unreleased]` header (Changelog)
+ *   - remove-endpoint : delete a documented-but-absent endpoint (API-Surface; delegated)
+ *
+ * Pure file edits, no LLM. Zero NPM dependencies.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { removeEndpoints, hasGeneratedMarker } from './api-reference.mjs';
+
+const esc = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** replace-count: "<found> <label>" → "<actual> <label>" in the file. */
+function applyReplaceCount(projectDir, fix) {
+  const full = resolve(projectDir, fix.file);
+  if (!existsSync(full)) return { applied: false };
+  const content = readFileSync(full, 'utf-8');
+  const re = new RegExp(`\\b${esc(fix.found)}(\\s+(?:automated\\s+)?${esc(fix.label)}\\b)`, 'g');
+  const next = content.replace(re, `${fix.actual}$1`);
+  if (next === content) return { applied: false };
+  writeFileSync(full, next, 'utf-8');
+  return { applied: true, detail: `${fix.file}: "${fix.found} ${fix.label}" → "${fix.actual} ${fix.label}"` };
+}
+
+/** replace-version: stale version → current, ONLY in actionable contexts. */
+function applyReplaceVersion(projectDir, fix) {
+  const full = resolve(projectDir, fix.file);
+  if (!existsSync(full)) return { applied: false };
+  const content = readFileSync(full, 'utf-8');
+  const f = esc(fix.found);
+  // Mirror metadata-sync's actionable detection so we never touch prose.
+  const patterns = [
+    new RegExp(`((?:archive|tags|releases|download)\\/v?)${f}`, 'g'),
+    new RegExp(`(@)${f}`, 'g'),
+    new RegExp(`(version:\\s*["']?)${f}`, 'g'),
+  ];
+  let next = content;
+  for (const re of patterns) next = next.replace(re, `$1${fix.actual}`);
+  if (next === content) return { applied: false };
+  writeFileSync(full, next, 'utf-8');
+  return { applied: true, detail: `${fix.file}: v${fix.found} → v${fix.actual}` };
+}
+
+/** insert-changelog-unreleased: add `## [Unreleased]` after the title/intro. */
+function applyInsertChangelogUnreleased(projectDir, fix) {
+  const full = resolve(projectDir, fix.file);
+  if (!existsSync(full)) return { applied: false };
+  const content = readFileSync(full, 'utf-8');
+  if (/\[unreleased\]/i.test(content)) return { applied: false }; // idempotent
+  const lines = content.split('\n');
+  // Insert before the first version heading `## [x.y.z]`, else after the H1, else top.
+  let idx = lines.findIndex(l => /^##\s*\[\d/.test(l));
+  if (idx < 0) {
+    const h1 = lines.findIndex(l => /^#\s/.test(l));
+    idx = h1 >= 0 ? h1 + 1 : 0;
+  }
+  const block = idx > 0 && lines[idx - 1].trim() !== '' ? ['', '## [Unreleased]', ''] : ['## [Unreleased]', ''];
+  lines.splice(idx, 0, ...block);
+  writeFileSync(full, lines.join('\n'), 'utf-8');
+  return { applied: true, detail: `${fix.file}: added ## [Unreleased]` };
+}
+
+/** remove-endpoint: delegate to the API-REFERENCE writer (marker-gated). */
+function applyRemoveEndpoint(projectDir, fix, { force = false } = {}) {
+  const full = resolve(projectDir, fix.doc || 'docs-canonical/API-REFERENCE.md');
+  if (!existsSync(full)) return { applied: false };
+  const content = readFileSync(full, 'utf-8');
+  if (!hasGeneratedMarker(content) && !force) {
+    return { applied: false, skipped: `${fix.doc} not docguard:generated (use --force)` };
+  }
+  const { content: next, removed } = removeEndpoints(content, [{ method: fix.method, path: fix.path }]);
+  if (removed.length === 0 || next === content) return { applied: false };
+  writeFileSync(full, next, 'utf-8');
+  return { applied: true, detail: `${fix.doc}: removed ${fix.method} ${fix.path}` };
+}
+
+const APPLIERS = {
+  'replace-count': applyReplaceCount,
+  'replace-version': applyReplaceVersion,
+  'insert-changelog-unreleased': applyInsertChangelogUnreleased,
+  'remove-endpoint': applyRemoveEndpoint,
+};
+
+export const MECHANICAL_FIX_TYPES = Object.keys(APPLIERS);
+
+/** Apply a single structured fix. Returns { applied, detail?, skipped? }. */
+export function applyMechanicalFix(projectDir, fix, opts = {}) {
+  const fn = APPLIERS[fix.type];
+  if (!fn) return { applied: false, skipped: `unknown fix type: ${fix.type}` };
+  return fn(projectDir, fix, opts);
+}
+
+/**
+ * Apply a batch of fixes; returns a summary.
+ * @returns {{ applied: object[], skipped: object[] }}
+ */
+export function applyMechanicalFixes(projectDir, fixes, opts = {}) {
+  const applied = [];
+  const skipped = [];
+  for (const fix of fixes) {
+    const r = applyMechanicalFix(projectDir, fix, opts);
+    if (r.applied) applied.push({ ...fix, detail: r.detail });
+    else if (r.skipped) skipped.push({ ...fix, reason: r.skipped });
+  }
+  return { applied, skipped };
+}

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/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/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
 
 - **20 Validators** — Structure, Security, Doc Quality, Test-Spec, Drift-Comments, API-Surface, 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
+- **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/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/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.9.9"
+  version: "0.11.1"
   description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with 19 automated validators, 4 AI behavior skills, spec-kit skill chaining, and workflow hooks. Zero NPM runtime dependencies."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"