docguard-cli 0.24.0 → 0.25.1

package/cli/commands/generate.mjs

@@ -40,10 +40,40 @@ function backupFile(filePath) {
  * Call this instead of raw writeFileSync when generating docs.
  */
 function safeWrite(filePath, content) {
+  mkdirSync(dirname(filePath), { recursive: true });
   backupFile(filePath);
   writeFileSync(filePath, content, 'utf-8');
 }
 
+/**
+ * B7 (field report): after generate emits canonical docs, register them in
+ * `.docguard.json` requiredFiles.canonical so `guard` doesn't immediately flag
+ * the generator's OWN output as an "orphaned" doc ("exists but not in your
+ * requiredFiles"). Only ADDS (never removes/deletes), only docs-canonical/*.md
+ * that actually exist on disk, and only when a config file already exists (init
+ * owns config creation). Idempotent — a second run with nothing new is a no-op.
+ * @returns {number} count of paths newly registered.
+ */
+function registerGeneratedCanonicalDocs(projectDir, candidatePaths) {
+  const cfgPath = resolve(projectDir, '.docguard.json');
+  if (!existsSync(cfgPath)) return 0;
+  let cfg;
+  try { cfg = JSON.parse(readFileSync(cfgPath, 'utf-8')); } catch { return 0; }
+  const canon = [...new Set(candidatePaths)].filter(p =>
+    p.startsWith('docs-canonical/') && p.endsWith('.md') && existsSync(resolve(projectDir, p))
+  );
+  if (canon.length === 0) return 0;
+  if (!cfg.requiredFiles || typeof cfg.requiredFiles !== 'object') cfg.requiredFiles = {};
+  const existing = Array.isArray(cfg.requiredFiles.canonical) ? cfg.requiredFiles.canonical : [];
+  const seen = new Set(existing);
+  let added = 0;
+  for (const p of canon) if (!seen.has(p)) { existing.push(p); seen.add(p); added++; }
+  if (added === 0) return 0;
+  cfg.requiredFiles.canonical = existing;
+  try { writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n', 'utf-8'); } catch { return 0; }
+  return added;
+}
+
 const CODE_EXTENSIONS = new Set([
   '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
   '.py', '.java', '.go', '.rs', '.rb', '.php', '.cs',
@@ -113,6 +143,19 @@ function appendStandardsCitation(content, docName) {
   return content.trimEnd() + '\n' + footer;
 }
 
+/**
+ * F1 (field report): web-shaped surface (HTTP endpoints, SDK deps, routes)
+ * auto-extracted from a cli/library/unknown-kind project is often pattern-
+ * matches in the project's OWN source (e.g. a scanner/linter whose code mentions
+ * express, boto3, jwt as detection strings), not real usage. We do NOT suppress
+ * it — that could hide a real surface (a false-green) — we flag it 'low'
+ * confidence so the surface is verified before being documented. Web kinds
+ * (webapp/api/service) stay 'normal'.
+ */
+function surfaceConfidence(kind) {
+  return ['webapp', 'api', 'service'].includes(kind) ? 'normal' : 'low';
+}
+
 /**
  * `docguard generate --plan` — AI-powered Generate.
  * Builds the code-truth skeleton (marked sections) and emits the agent task
@@ -139,6 +182,7 @@ export function runGeneratePlan(projectDir, config, flags) {
         screens: plan.surface.screens.length,
         components: plan.surface.components.length,
         envVars: plan.surface.envVars.length,
+        confidence: surfaceConfidence(plan.profile.kind),
       },
       docs: plan.docs.map(d => ({
         path: d.path,
@@ -169,11 +213,18 @@ export function runGeneratePlan(projectDir, config, flags) {
           : `> **AI task:** ${sec.task}\n<!-- docguard:pending agent writes this section -->`;
         content = upsertSection(content, sec.id, body, { source: sec.source }).content;
       }
-      writeFileSync(full, content, 'utf-8');
+      // Route through safeWrite: creates the parent dir (docs-implementation/ may
+      // not exist yet — was an ENOENT crash) and snapshots a .bak before writing.
+      safeWrite(full, content);
       wrote++;
     }
+    // B7: register the scaffolded canonical docs so guard doesn't flag them.
+    const registered = registerGeneratedCanonicalDocs(projectDir, plan.docs.map(d => d.path));
     console.log(`${c.bold}🔮 DocGuard Generate --plan --write — ${config.projectName}${c.reset}`);
     console.log(`  ${c.green}✅ Scaffolded ${wrote} doc(s)${c.reset} with code-truth sections + ${plan.agentTasks.length} agent task(s).`);
+    if (registered > 0) {
+      console.log(`  ${c.dim}Registered ${registered} canonical doc(s) in .docguard.json requiredFiles.${c.reset}`);
+    }
     console.log(`  ${c.dim}Now run your AI agent (/docguard.fix) to write the prose sections, then ${c.cyan}docguard guard${c.dim}.${c.reset}\n`);
     return;
   }
@@ -182,6 +233,10 @@ export function runGeneratePlan(projectDir, config, flags) {
   console.log(`${c.bold}🔮 DocGuard Generate Plan — ${config.projectName}${c.reset}`);
   console.log(`${c.dim}   ${plan.profile.polyglot ? 'Polyglot' : 'Single-language'}: ${plan.profile.languages.join(', ')} | frameworks: ${plan.profile.frameworks.join(', ') || '—'} | kind: ${plan.profile.kind}${c.reset}\n`);
   console.log(`  ${c.bold}Code-truth surface:${c.reset} ${plan.surface.endpoints.length} endpoints · ${plan.surface.entities.length} entities · ${plan.surface.screens.length} screens · ${plan.surface.components.length} components · ${plan.surface.envVars.length} env vars\n`);
+  const webSurface = plan.surface.endpoints.length + plan.surface.entities.length + plan.surface.screens.length + plan.surface.components.length;
+  if (surfaceConfidence(plan.profile.kind) === 'low' && webSurface > 0) {
+    console.log(`  ${c.yellow}⚠️  Low-confidence surface:${c.reset} ${c.dim}this looks like a ${plan.profile.kind} (not a web app), so the HTTP/SDK/route surface above may be pattern-matches in your OWN source — not real usage. Verify before documenting; pin any corrected code section with ${c.cyan}pinned="reason"${c.dim}.${c.reset}\n`);
+  }
   console.log(`  ${c.bold}Documents to build (${plan.docs.length}):${c.reset}`);
   for (const d of plan.docs) {
     const code = d.sections.filter(s => s.source === 'code').length;
@@ -301,8 +356,19 @@ export function runGenerate(projectDir, config, flags) {
   created += rootResults.created;
   skipped += rootResults.skipped;
 
+  // B7: keep guard coherent — register the canonical docs we emitted so the
+  // traceability validator doesn't flag the generator's own output.
+  const registered = registerGeneratedCanonicalDocs(projectDir, [
+    'docs-canonical/ARCHITECTURE.md', 'docs-canonical/API-REFERENCE.md',
+    'docs-canonical/DATA-MODEL.md', 'docs-canonical/ENVIRONMENT.md',
+    'docs-canonical/TEST-SPEC.md', 'docs-canonical/SECURITY.md',
+  ]);
+
   console.log(`\n${c.bold}  ─────────────────────────────────────${c.reset}`);
   console.log(`  ${c.green}Generated: ${created}${c.reset}  Skipped: ${skipped} (already exist)`);
+  if (registered > 0) {
+    console.log(`  ${c.dim}Registered ${registered} canonical doc(s) in .docguard.json requiredFiles.${c.reset}`);
+  }
   if (docTools._detected.length > 0) {
     console.log(`  ${c.dim}Leveraged: ${docTools._detected.join(', ')} (existing tools detected)${c.reset}`);
   }

package/cli/commands/init.mjs

@@ -118,6 +118,7 @@ function shouldRunGenerate(projectDir, flags) {
   if (flags.skipPrompts)     return false; // non-interactive (CI) keeps deterministic skeleton path
   if (flags.wizard)          return false; // wizard has its own scan step
   if (flags.profile)         return false; // explicit profile = user knows what they want
+  if (flags.fix)             return false; // --fix = deterministic create-missing-from-templates (headless)
 
   // If canonical docs already exist, this is a re-init, not a first-run.
   const canonicalDir = resolve(projectDir, 'docs-canonical');
@@ -198,8 +199,11 @@ export async function runInit(projectDir, config, flags) {
 
   let selectedDocs;
 
-  if (flags.skipPrompts || flags.force) {
-    // Non-interactive — use profile defaults
+  if (flags.skipPrompts || flags.force || flags.fix) {
+    // Non-interactive — use profile defaults. `--fix` lands here too: its
+    // documented contract is "auto-create missing files from templates", so it
+    // must never block on prompts (CI / headless / agent use). The create-loop
+    // below already skips existing files, so --fix only fills gaps.
     const profileCanonical = profile.requiredFiles?.canonical || allDocs.map(d => d.file);
     selectedDocs = allDocs.filter(d => profileCanonical.includes(d.file));
     console.log(`  ${c.dim}Non-interactive mode — using ${profileName} profile defaults${c.reset}\n`);

package/cli/commands/sync.mjs

@@ -104,6 +104,12 @@ export function runSync(projectDir, config, flags) {
       if (sec.source !== 'code') continue;
       const existing = getSection(content, sec.id);
       if (!existing) continue; // sync refreshes sections that already exist
+      // B5: a pinned section is intentionally hand-maintained — never revert it.
+      // (Pairs with the Generated-Staleness exemption for the same marker.)
+      if (existing.attrs?.pinned !== undefined) {
+        skipped.push({ doc: doc.path, reason: `section ${sec.id} is pinned (hand-maintained) — not synced` });
+        continue;
+      }
       if (existing.body.trim() === String(sec.body).trim()) continue; // already current
       // L-1: when --since is provided, only update sections whose underlying
       // source files appear in the changed set. Avoids spurious updates when

package/cli/docguard.mjs

@@ -125,7 +125,7 @@ ${c.bold}Options:${c.reset}
                   code-truth skeleton. Add --write to scaffold, --format json
                   for the machine-readable manifest.
   --doc <name>    Generate AI prompt for specific doc (architecture, security, etc.)
-  --profile <p>   Compliance profile: starter, standard, enterprise (init command)
+  --profile <p>   Profile: starter, standard, cli, library, enterprise (init command)
   --tax           Show estimated documentation maintenance cost (with score)
   --help          Show this help message
   --version       Show version
@@ -133,6 +133,8 @@ ${c.bold}Options:${c.reset}
 ${c.bold}Profiles:${c.reset}
   ${c.green}starter${c.reset}      Minimal CDD — just ARCHITECTURE.md + CHANGELOG (side projects)
   ${c.green}standard${c.reset}     Full CDD — all 5 canonical docs (default, team projects)
+  ${c.green}cli${c.reset}          CLI tool — no HTTP API / DB (ARCHITECTURE, TEST-SPEC, SECURITY, ENVIRONMENT)
+  ${c.green}library${c.reset}      Library — public API, no HTTP/DB (ARCHITECTURE, API-REFERENCE, TEST-SPEC)
   ${c.green}enterprise${c.reset}   Strict CDD — all docs + all validators + freshness enforced
 
 ${c.bold}Examples:${c.reset}
@@ -158,6 +160,135 @@ ${c.bold}Learn more:${c.reset}
 `);
 }
 
+// ── Per-command help (v0.24, field report B6) ───────────────────────────────
+// `docguard <command> --help` now prints the flags + examples for THAT command,
+// so a flag like `generate --plan --write` or `init --skeleton` is discoverable.
+// Only flags that genuinely apply to each command are listed (derived from the
+// vetted global help above). Commands without a focused entry fall back to the
+// global help, which still lists them.
+const COMMAND_HELP = {
+  init: {
+    summary: 'Bootstrap CDD docs — smart-scans existing code, or writes blank templates.',
+    usage: 'docguard init [--skeleton|--wizard] [--profile <p>] [--with <name>] [--fix]',
+    flags: [
+      ['--skeleton', 'Blank templates instead of the smart scan-and-propose'],
+      ['--wizard', 'Guided interactive onboarding'],
+      ['--with <name>', 'Add a scaffolder: agents, hooks, ci, badge, llms, publish'],
+      ['--profile <p>', 'starter | standard | cli | library | enterprise (default: standard)'],
+      ['--skip-prompts', 'Non-interactive; create the profile defaults (CI)'],
+      ['--fix', 'Headless: create any missing required docs from templates'],
+      ['--force', 'Overwrite existing files (.bak backup kept)'],
+    ],
+    examples: ['docguard init', 'docguard init --skeleton', 'docguard init --profile starter --skip-prompts', 'docguard init --with ci'],
+  },
+  generate: {
+    summary: 'Reverse-engineer canonical docs from existing code.',
+    usage: 'docguard generate [--plan [--write] [--format json]] [--force]',
+    flags: [
+      ['--plan', 'AI scan: emit the agent task manifest + code-truth skeleton'],
+      ['--write', 'With --plan: scaffold the skeleton docs to disk'],
+      ['--format json', 'With --plan: machine-readable manifest'],
+      ['--force', 'Overwrite existing docs (.bak backup kept)'],
+    ],
+    examples: ['docguard generate', 'docguard generate --plan', 'docguard generate --plan --write', 'docguard generate --plan --format json'],
+  },
+  guard: {
+    summary: 'Validate code against canonical docs (all validators).',
+    usage: 'docguard guard [--format json] [--changed-only] [--fail-on-warning]',
+    flags: [
+      ['--format json', 'Machine-readable results for CI'],
+      ['--changed-only', 'Only validate docs/code touched in the working tree'],
+      ['--fail-on-warning', 'Exit non-zero on warnings (strict CI)'],
+    ],
+    examples: ['docguard guard', 'docguard guard --format json'],
+  },
+  score: {
+    summary: 'CDD maturity score (0–100).',
+    usage: 'docguard score [--diff] [--tax] [--format json]',
+    flags: [
+      ['--diff', 'Delta between two refs'],
+      ['--tax', 'Estimated documentation maintenance cost'],
+      ['--format json', 'Machine-readable score'],
+    ],
+    examples: ['docguard score', 'docguard score --tax'],
+  },
+  diff: {
+    summary: 'Show gaps between docs and code.',
+    usage: 'docguard diff [--since <ref>]',
+    flags: [['--since <ref>', 'Restrict to files changed since <ref> (impact mode)']],
+    examples: ['docguard diff', 'docguard diff --since HEAD~5'],
+  },
+  sync: {
+    summary: 'Refresh code-truth doc sections (preview by default).',
+    usage: 'docguard sync [--write] [--since <ref>]',
+    flags: [
+      ['--write', 'Apply the refresh (default is a dry-run preview)'],
+      ['--since <ref>', 'Only sync sections whose source files changed since <ref>'],
+    ],
+    examples: ['docguard sync', 'docguard sync --write'],
+  },
+  fix: {
+    summary: 'Generate AI fix instructions for docs (or apply deterministic fixes).',
+    usage: 'docguard fix [--doc <name>] [--auto] [--write] [--force]',
+    flags: [
+      ['--doc <name>', 'Target a specific doc (architecture, security, …)'],
+      ['--auto', 'Auto-fix what is mechanically possible'],
+      ['--write', 'Apply deterministic fixes in place (docguard:generated docs)'],
+      ['--force', 'Allow edits outside docguard:generated docs'],
+    ],
+    examples: ['docguard fix --doc architecture', 'docguard diagnose'],
+  },
+  trace: {
+    summary: 'Requirements traceability matrix.',
+    usage: 'docguard trace [--reverse]',
+    flags: [['--reverse', 'Code→doc map instead of doc→code']],
+    examples: ['docguard trace', 'docguard trace --reverse'],
+  },
+  upgrade: {
+    summary: 'Migrate .docguard.json schema + CLI.',
+    usage: 'docguard upgrade [--apply] [--pr]',
+    flags: [
+      ['--apply', 'Write the migration (default is a preview)'],
+      ['--pr', 'Open a team-wide PR with the migration'],
+    ],
+    examples: ['docguard upgrade', 'docguard upgrade --apply'],
+  },
+  ci: {
+    summary: 'Generate CI / pipeline config.',
+    usage: 'docguard ci [--threshold <n>] [--fail-on-warning]',
+    flags: [
+      ['--threshold <n>', 'Minimum score for CI pass'],
+      ['--fail-on-warning', 'Fail CI on warnings'],
+    ],
+    examples: ['docguard ci'],
+  },
+  memory: {
+    summary: 'Show what DocGuard remembers about the project.',
+    usage: 'docguard memory [--diff]',
+    flags: [['--diff', 'Drill into drift between memory and code']],
+    examples: ['docguard memory', 'docguard memory --diff'],
+  },
+};
+
+function printCommandHelp(command) {
+  const h = COMMAND_HELP[command];
+  if (!h) { printHelp(); return; } // no focused entry — global help still lists it
+  printBanner();
+  console.log(`${c.bold}docguard ${command}${c.reset} — ${h.summary}\n`);
+  console.log(`${c.bold}Usage:${c.reset}\n  ${h.usage}\n`);
+  if (h.flags?.length) {
+    console.log(`${c.bold}Options:${c.reset}`);
+    for (const [flag, desc] of h.flags) console.log(`  ${c.cyan}${flag.padEnd(18)}${c.reset} ${desc}`);
+    console.log('');
+  }
+  if (h.examples?.length) {
+    console.log(`${c.bold}Examples:${c.reset}`);
+    for (const ex of h.examples) console.log(`  ${c.dim}${ex}${c.reset}`);
+    console.log('');
+  }
+  console.log(`${c.dim}All commands: ${c.cyan}docguard --help${c.reset}`);
+}
+
 // ── Main ───────────────────────────────────────────────────────────────────
 async function main() {
   const args = process.argv.slice(2);
@@ -324,11 +455,11 @@ async function main() {
     process.exit(0);
   }
 
-  // v0.24: `docguard <command> --help` shows usage instead of running the
-  // command. There is no per-command help yet, so global help is correct — and,
-  // unlike before, non-destructive (generate no longer scaffolds on --help).
+  // v0.24: `docguard <command> --help` shows that command's own flags +
+  // examples (field report B6); commands without a focused entry fall back to
+  // the global help. Non-destructive (generate no longer scaffolds on --help).
   if (flags.help) {
-    printHelp();
+    printCommandHelp(command);
     process.exit(0);
   }
 
@@ -338,8 +469,12 @@ async function main() {
   // Headless flags (`--write`, `--check-only`, `--auto`) also suppress chrome.
   // v0.16-P5: --quiet (-q) joins the headless club for users who want
   // banner-free output without committing to a specific machine format.
+  // v0.24 (field report): `--plan` is a read-only preview — "show me, don't
+  // touch" — so it joins the club to suppress the banner AND ensureSkills'
+  // .agent/.specify writes, which were a surprising side effect of a bare
+  // `generate --plan` (and were already suppressed for `--plan --write`).
   const jsonMode = flags.format === 'json';
-  const headless = jsonMode || flags.write || flags.checkOnly || flags.changedOnly || flags.quiet;
+  const headless = jsonMode || flags.write || flags.checkOnly || flags.changedOnly || flags.quiet || flags.plan;
 
   if (!headless) printBanner();
 

package/cli/scanners/project-type.mjs

@@ -15,6 +15,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, dirname, basename } from 'node:path';
+import { shouldIgnore, relPosix } from '../shared-ignore.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build', 'coverage', 'target',
@@ -42,7 +43,8 @@ function readSafe(p) { try { return readFileSync(p, 'utf-8'); } catch { return '
 function readJson(p) { try { return JSON.parse(readFileSync(p, 'utf-8')); } catch { return null; } }
 
 /** Recursively find manifest files (bounded depth, ignoring vendor dirs). */
-function findManifests(projectDir, maxDepth = 4) {
+function findManifests(projectDir, maxDepth = 4, config = {}) {
+  const root = resolve(projectDir);
   const found = []; // { absDir, file, lang }
   const walk = (dir, depth) => {
     if (depth > maxDepth) return;
@@ -51,15 +53,20 @@ function findManifests(projectDir, maxDepth = 4) {
     for (const e of entries) {
       if (e.isDirectory()) {
         if (IGNORE_DIRS.has(e.name) || e.name.startsWith('.')) continue;
+        // Honor config.ignore / .docguardignore: a user who excludes tests/ or
+        // base-research/ must not have those dirs' manifests (e.g. a fixture
+        // package.json declaring express) misclassify the project's stack.
+        if (shouldIgnore(relPosix(root, join(dir, e.name)), config)) continue;
         walk(join(dir, e.name), depth + 1);
       } else if (e.isFile()) {
+        if (shouldIgnore(relPosix(root, join(dir, e.name)), config)) continue;
         const m = MANIFESTS.find(x => x.file === e.name);
         if (m) found.push({ absDir: dir, file: e.name, lang: m.lang });
         else if (e.name.endsWith('.csproj')) found.push({ absDir: dir, file: e.name, lang: 'C#' });
       }
     }
   };
-  walk(resolve(projectDir), 0);
+  walk(root, 0);
   return found;
 }
 
@@ -255,8 +262,8 @@ function buildEcosystem(projectDir, m) {
  * Multiple manifests in the same dir+language merge into one ecosystem.
  * @returns {Array<{ language, manifest, dir, framework, kind, deps, entryPoints }>}
  */
-export function detectEcosystems(projectDir, _config = {}) {
-  const manifests = findManifests(projectDir);
+export function detectEcosystems(projectDir, config = {}) {
+  const manifests = findManifests(projectDir, 4, config);
   const byKey = new Map(); // `${dir}::${lang-family}` → ecosystem
 
   // Group Python manifests (pyproject/requirements/setup/Pipfile) in same dir.

package/cli/shared-ignore.mjs

@@ -113,7 +113,13 @@ export function mergeIgnoreFile(projectDir, config) {
  * @returns {RegExp}
  */
 function globToRegex(pattern) {
-  const escaped = pattern
+  // gitignore-style trailing slash ("dir/") means "this directory and everything
+  // under it". Strip it so "dir/" matches identically to "dir" — otherwise the
+  // escaped pattern keeps the slash and the alternation below can only match a
+  // literal "dir//" (double slash), so the pattern silently matches nothing.
+  // `|| pattern` guards the degenerate all-slashes case (e.g. "/") from emptying.
+  const normalized = pattern.replace(/\/+$/, '') || pattern;
+  const escaped = normalized
     .replace(/\./g, '\\.')
     .replace(/\*\*/g, '§§')     // temp placeholder for **
     .replace(/\*/g, '[^/]*')

package/cli/shared.mjs

@@ -183,6 +183,38 @@ export const PROFILES = {
       freshness: true,
     },
   },
+  // F3 (field report): non-web-centric profiles. The default doc set assumes an
+  // HTTP API + database; for a CLI or library that structure fights the project.
+  // These drop the HTTP/DB-shaped requirements. (A bespoke CLI-REFERENCE doc type
+  // is a separate, larger follow-up; until then API-REFERENCE doubles as the
+  // library's module-API reference.)
+  cli: {
+    description: 'CLI / command-line tool — no HTTP API or database assumed.',
+    requiredFiles: {
+      canonical: [
+        'docs-canonical/ARCHITECTURE.md',
+        'docs-canonical/TEST-SPEC.md',
+        'docs-canonical/SECURITY.md',
+        'docs-canonical/ENVIRONMENT.md',
+      ],
+      agentFile: ['AGENTS.md', 'CLAUDE.md'],
+      changelog: 'CHANGELOG.md',
+      driftLog: 'DRIFT-LOG.md',
+    },
+  },
+  library: {
+    description: 'Library / package — public API matters; no HTTP server or DB assumed.',
+    requiredFiles: {
+      canonical: [
+        'docs-canonical/ARCHITECTURE.md',
+        'docs-canonical/API-REFERENCE.md',
+        'docs-canonical/TEST-SPEC.md',
+      ],
+      agentFile: ['AGENTS.md', 'CLAUDE.md'],
+      changelog: 'CHANGELOG.md',
+      driftLog: 'DRIFT-LOG.md',
+    },
+  },
   'enterprise-ai': {
     description: 'EU AI Act compliance — Annex IV documentation requirements, ALCOA+ alignment, strict freshness. For AI/ML projects under regulatory scrutiny.',
     requiredFiles: {

package/cli/validators/generated-staleness.mjs

@@ -173,6 +173,19 @@ export function validateGeneratedStaleness(projectDir, config = {}) {
       if (!onDisk) continue;
 
       result.total++;
+
+      // B5 (field report): a `pinned` attribute on the section's open marker
+      //   <!-- docguard:section id=… source=code pinned="reason" -->
+      // marks the section as intentionally hand-maintained — the scanner
+      // mislabeled this surface (e.g. a scanner/tool repo whose source contains
+      // framework-like strings; see F1). Exempt it from staleness and count it
+      // as a pass, mirroring the docguard:quality opt-out marker. This is the
+      // escape hatch from the "stale forever / sync --write reverts it" trap.
+      if (onDisk.attrs?.pinned !== undefined) {
+        result.passed++;
+        continue;
+      }
+
       const expected = String(sec.body || '').trim();
       const actual = String(onDisk.body || '').trim();
 
@@ -194,7 +207,9 @@ export function validateGeneratedStaleness(projectDir, config = {}) {
         : '';
 
       result.warnings.push(
-        `${basename(doc.path)} → section "${sec.id}" is stale${hint}. Run \`docguard sync --write\` to refresh code-truth sections.`
+        `${basename(doc.path)} → section "${sec.id}" is stale${hint}. Run \`docguard sync --write\` to refresh code-truth sections. ` +
+        `If this section is intentionally hand-maintained (the scanner mislabeled it), pin it: ` +
+        `add \`pinned="reason"\` to its \`<!-- docguard:section id=${sec.id} … -->\` marker.`
       );
       // v0.14-P3: structured fix so `docguard fix --write` can fix this
       // mechanically (no AI needed — scanner already produced the right body).

package/extensions/spec-kit-docguard/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.24.0"
+  version: "0.25.1"
   description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with automated validators, 4 AI behavior skills, spec-kit skill chaining, and workflow hooks. One pinned runtime dependency (@babel/parser); pure Node.js otherwise."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"
@@ -28,22 +28,18 @@ provides:
     - name: "speckit.docguard.guard"
       file: "commands/guard.md"
       description: "Run 19-validator quality gate with severity triage and remediation plan"
-      aliases: ["speckit.docguard.guard"]
 
     - name: "speckit.docguard.fix"
       file: "commands/generate.md"
       description: "AI-driven documentation repair with codebase research and validation loops"
-      aliases: ["speckit.docguard.fix"]
 
     - name: "speckit.docguard.review"
       file: "commands/diagnose.md"
       description: "Cross-document semantic consistency analysis (read-only)"
-      aliases: ["speckit.docguard.review"]
 
     - name: "speckit.docguard.score"
       file: "commands/score.md"
       description: "CDD maturity score with ROI-based improvement roadmap"
-      aliases: ["speckit.docguard.score"]
 
     - name: "speckit.docguard.diagnose"
       file: "commands/diagnose.md"

package/extensions/spec-kit-docguard/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.24.0
+  version: 0.25.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.24.0 -->
+<!-- docguard:version: 0.25.0 -->
 
 # DocGuard Fix Skill
 

package/extensions/spec-kit-docguard/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.24.0
+  version: 0.25.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.24.0 -->
+<!-- docguard:version: 0.25.0 -->
 
 # DocGuard Guard Skill
 

package/extensions/spec-kit-docguard/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.24.0
+  version: 0.25.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.24.0 -->
+<!-- docguard:version: 0.25.0 -->
 
 # DocGuard Review Skill
 

package/extensions/spec-kit-docguard/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.24.0
+  version: 0.25.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.24.0 -->
+<!-- docguard:version: 0.25.0 -->
 
 # DocGuard Score Skill
 

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

@@ -4,10 +4,10 @@ description: Keep canonical documentation ALWAYS UP TO DATE. Refreshes code-trut
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.24.0
+  version: 0.25.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.24.0 -->
+<!-- docguard:version: 0.25.0 -->
 
 # DocGuard Sync Skill
 

package/extensions/spec-kit-docguard/templates/github-workflows/docguard-autofix.yml

@@ -13,7 +13,7 @@
 # Setup:
 #   1. Copy this file to .github/workflows/docguard-autofix.yml
 #   2. Ensure the workflow has the permissions block below (write access).
-#   3. Pinned to the `@v0.24.0` release tag for reproducible CI. Change it to a
+#   3. Pinned to the `@v0.25.0` release tag for reproducible CI. Change it to a
 #      newer tag to upgrade, or to `@main` to always track the latest (unpinned).
 #
 # Security note: this workflow makes commits back to the PR branch. It refuses
@@ -44,7 +44,7 @@ jobs:
           fetch-depth: 0
 
       - name: Run DocGuard fix --write + auto-commit + PR comment
-        uses: raccioly/docguard@v0.24.0
+        uses: raccioly/docguard@v0.25.0
         with:
           command: fix
           auto-commit: 'true'

package/extensions/spec-kit-docguard/templates/github-workflows/docguard-guard.yml

@@ -28,7 +28,7 @@ jobs:
           fetch-depth: 0
 
       - name: Run all validators
-        uses: raccioly/docguard@v0.24.0
+        uses: raccioly/docguard@v0.25.0
         with:
           command: guard
           # Flip to 'true' once your repo is clean — turns warnings into hard failures.
@@ -42,7 +42,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Score & comment
-        uses: raccioly/docguard@v0.24.0
+        uses: raccioly/docguard@v0.25.0
         with:
           command: score
           format: json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {