docguard-cli 0.13.1 → 0.14.1

package/cli/commands/fix.mjs

@@ -272,13 +272,16 @@ IMPORTANT: A new contributor should be able to follow this doc and have the proj
  * insert-changelog-unreleased (Changelog).
  * @returns {{ applied: object[], skipped: object[], total: number }}
  */
-export function applyAllMechanicalFixes(projectDir, config, { force = false } = {}) {
+export function applyAllMechanicalFixes(projectDir, config, opts = {}) {
+  const { force = false, forceRedo = false } = opts;
   const guardData = runGuardInternal(projectDir, config);
   const fixes = [];
   for (const v of guardData.validators) {
     if (Array.isArray(v.fixes)) fixes.push(...v.fixes);
   }
-  const { applied, skipped } = applyMechanicalFixes(projectDir, fixes, { force });
+  // v0.14-P1: forwarding forceRedo so users with `--force-redo` can override
+  // ping-pong suppression for a specific fix they actually want re-applied.
+  const { applied, skipped } = applyMechanicalFixes(projectDir, fixes, { force, forceRedo });
   return { applied, skipped, total: fixes.length };
 }
 
@@ -333,7 +336,10 @@ function runHistoryMode(projectDir, flags) {
 
 function runWriteMode(projectDir, config, flags) {
   const isJson = flags.format === 'json';
-  const { applied, skipped, total } = applyAllMechanicalFixes(projectDir, config, { force: flags.force });
+  const { applied, skipped, total } = applyAllMechanicalFixes(projectDir, config, {
+    force: flags.force,
+    forceRedo: flags.forceRedo,  // v0.14-P1: bypass ping-pong suppression
+  });
 
   if (isJson) {
     console.log(JSON.stringify({

package/cli/commands/guard.mjs

@@ -109,27 +109,36 @@ export function runGuardInternal(projectDir, config) {
     // Metrics-Consistency runs post-loop (needs guard results)
   ];
 
+  // v0.14-Q2: per-validator timing. Cheap (one `performance.now()` pair per
+  // validator) and the data is what we'd need to optimize anything later.
+  // Exposed via --profile in the public guard.
   for (const { key, name, fn } of validatorMap) {
     if (validators[key] === false) {
-      results.push({ name, key, status: 'skipped', quality: null, errors: [], warnings: [], passed: 0, total: 0 });
+      results.push({ name, key, status: 'skipped', quality: null, errors: [], warnings: [], passed: 0, total: 0, durationMs: 0 });
       continue;
     }
 
+    const start = performance.now();
     try {
       const result = fn();
-      results.push({ ...result, name, key, ...classifyResult(result) });
+      const durationMs = Math.round((performance.now() - start) * 100) / 100;
+      results.push({ ...result, name, key, durationMs, ...classifyResult(result) });
     } catch (err) {
-      results.push({ name, key, status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1 });
+      const durationMs = Math.round((performance.now() - start) * 100) / 100;
+      results.push({ name, key, status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1, durationMs });
     }
   }
 
   // ── Metrics-Consistency runs AFTER all other validators (needs their results) ──
   if (validators.metricsConsistency !== false) {
+    const start = performance.now();
     try {
       const result = validateMetricsConsistency(projectDir, config, results);
-      results.push({ ...result, name: 'Metrics-Consistency', key: 'metricsConsistency', ...classifyResult(result) });
+      const durationMs = Math.round((performance.now() - start) * 100) / 100;
+      results.push({ ...result, name: 'Metrics-Consistency', key: 'metricsConsistency', durationMs, ...classifyResult(result) });
     } catch (err) {
-      results.push({ name: 'Metrics-Consistency', key: 'metricsConsistency', status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1 });
+      const durationMs = Math.round((performance.now() - start) * 100) / 100;
+      results.push({ name: 'Metrics-Consistency', key: 'metricsConsistency', status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1, durationMs });
     }
   }
 
@@ -326,6 +335,26 @@ export function runGuard(projectDir, config, flags) {
   const badgeUrl = `https://img.shields.io/badge/CDD_Guard-${data.passed}%2F${data.total}_passed-${bColor}`;
   console.log(`\n  ${c.dim}📎 Badge: ![CDD Guard](${badgeUrl})${c.reset}`);
 
+  // v0.14-Q2: --timings prints per-validator timing, sorted slowest-first.
+  // Designed for self-diagnosis on slow repos: shows exactly which validator
+  // to optimize first. Cheap to opt into; off by default to keep output clean.
+  // (Originally proposed as `--profile` but that flag is taken by `init`.)
+  if (flags.timings) {
+    console.log(`\n  ${c.bold}⏱  Profile${c.reset} ${c.dim}(per-validator wall time, slowest first)${c.reset}`);
+    const timed = data.validators
+      .filter(v => typeof v.durationMs === 'number' && v.status !== 'skipped')
+      .sort((a, b) => b.durationMs - a.durationMs);
+    const total = timed.reduce((sum, v) => sum + v.durationMs, 0);
+    for (const v of timed.slice(0, 10)) {
+      const pct = total > 0 ? Math.round((v.durationMs / total) * 100) : 0;
+      const bar = '▇'.repeat(Math.max(1, Math.round(pct / 5)));
+      console.log(`     ${v.durationMs.toFixed(1).padStart(7)}ms  ${pct.toString().padStart(2)}%  ${bar.padEnd(20)} ${v.name}`);
+    }
+    if (timed.length > 10) console.log(`     ${c.dim}... ${timed.length - 10} faster validators omitted${c.reset}`);
+    console.log(`     ${c.dim}─────────${c.reset}`);
+    console.log(`     ${c.bold}${total.toFixed(1).padStart(7)}ms${c.reset}  ${c.dim}total validator time${c.reset}`);
+  }
+
   // Schema upgrade nudge — fires when the project's .docguard.json schema is
   // behind the CLI's CURRENT_SCHEMA_VERSION. Cheap, file-local check; no
   // network access. Suppressed in JSON output to keep machine consumers clean.

package/cli/commands/upgrade.mjs

@@ -124,6 +124,65 @@ function applyCliUpgrade() {
   return r;
 }
 
+/**
+ * v0.14-P4: open a PR with the schema migration. Used when the team wants
+ * a reviewable change instead of an in-place edit. Requires `gh` CLI on
+ * PATH. Returns { ok: bool, prUrl?: string, error?: string }.
+ */
+function openUpgradePR(projectDir, migratedConfig, fromVersion, toVersion) {
+  // Pre-flight: gh must be installed
+  const which = spawnSync('which', ['gh'], { encoding: 'utf-8' });
+  if (which.status !== 0) {
+    return { ok: false, error: 'gh CLI not found. Install: https://cli.github.com' };
+  }
+
+  const branch = `docguard/upgrade-schema-${toVersion}-${Date.now().toString(36)}`;
+  // Branch off current HEAD
+  let r = spawnSync('git', ['checkout', '-b', branch], { cwd: projectDir, encoding: 'utf-8' });
+  if (r.status !== 0) return { ok: false, error: `git checkout failed: ${r.stderr || r.stdout}` };
+
+  // Write the migrated config
+  try {
+    writeFileSync(
+      resolve(projectDir, '.docguard.json'),
+      JSON.stringify(migratedConfig, null, 2) + '\n',
+      'utf-8'
+    );
+  } catch (e) {
+    return { ok: false, error: `write .docguard.json failed: ${e.message}` };
+  }
+
+  // Commit
+  r = spawnSync('git', ['add', '.docguard.json'], { cwd: projectDir, encoding: 'utf-8' });
+  if (r.status !== 0) return { ok: false, error: `git add failed: ${r.stderr}` };
+
+  const commitMsg = `chore(docguard): migrate .docguard.json schema ${fromVersion} → ${toVersion}\n\nAutomated migration via \`docguard upgrade --apply --pr\`.`;
+  r = spawnSync('git', ['commit', '-m', commitMsg], { cwd: projectDir, encoding: 'utf-8' });
+  if (r.status !== 0) return { ok: false, error: `git commit failed: ${r.stderr || r.stdout}` };
+
+  // Push
+  r = spawnSync('git', ['push', '-u', 'origin', branch], { cwd: projectDir, encoding: 'utf-8' });
+  if (r.status !== 0) return { ok: false, error: `git push failed: ${r.stderr || r.stdout}` };
+
+  // Open PR
+  const prBody =
+    `Automated schema migration from \`${fromVersion}\` → \`${toVersion}\`.\n\n` +
+    `This PR was opened by \`docguard upgrade --apply --pr\`. It updates the\n` +
+    `\`.docguard.json\` schema version and any additive fields the new schema\n` +
+    `introduces (e.g. \`severity: {}\` for v0.5).\n\n` +
+    `Review and merge to keep your team's DocGuard config in sync.\n\n` +
+    `> 🤖 Generated by [DocGuard](https://github.com/raccioly/docguard)`;
+  r = spawnSync('gh', [
+    'pr', 'create',
+    '--title', `chore(docguard): migrate schema ${fromVersion} → ${toVersion}`,
+    '--body', prBody,
+  ], { cwd: projectDir, encoding: 'utf-8' });
+  if (r.status !== 0) return { ok: false, error: `gh pr create failed: ${r.stderr || r.stdout}` };
+
+  const prUrl = (r.stdout || '').trim().split('\n').pop();
+  return { ok: true, prUrl };
+}
+
 export async function runUpgrade(projectDir, _config, flags) {
   const checkOnly = flags.checkOnly || flags['check-only'];
   const apply = flags.apply;
@@ -222,8 +281,23 @@ export async function runUpgrade(projectDir, _config, flags) {
       const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
       const { changed, newConfig } = migrateSchema(cfg, projectSchema);
       if (changed) {
-        writeFileSync(cfgPath, JSON.stringify(newConfig, null, 2) + '\n', 'utf-8');
-        console.log(`  ${c.green}✓ Schema migrated ${projectSchema} → ${newConfig.version}.${c.reset}`);
+        // v0.14-P4: --pr opens a PR for review instead of in-place editing.
+        // Useful when the team wants a reviewable diff or has branch-protected
+        // .docguard.json. Falls back to in-place if pre-flight fails.
+        if (flags.pr) {
+          console.log(`  ${c.dim}Opening PR with migrated config...${c.reset}`);
+          const pr = openUpgradePR(projectDir, newConfig, projectSchema, newConfig.version);
+          if (pr.ok) {
+            console.log(`  ${c.green}✓ Schema migration PR opened:${c.reset} ${c.cyan}${pr.prUrl}${c.reset}`);
+          } else {
+            console.error(`  ${c.red}✗ PR creation failed:${c.reset} ${pr.error}`);
+            console.log(`  ${c.dim}Tip: run without --pr to apply in place, or fix the underlying issue.${c.reset}`);
+            process.exit(1);
+          }
+        } else {
+          writeFileSync(cfgPath, JSON.stringify(newConfig, null, 2) + '\n', 'utf-8');
+          console.log(`  ${c.green}✓ Schema migrated ${projectSchema} → ${newConfig.version}.${c.reset}`);
+        }
       } else {
         console.log(`  ${c.dim}Schema migration was a no-op (no recipe registered yet for ${projectSchema} → ${CURRENT_SCHEMA_VERSION}).${c.reset}`);
       }

package/cli/docguard.mjs

@@ -386,6 +386,15 @@ async function main() {
       flags.reverse = true;
     } else if (args[i] === '--history') {
       flags.history = true;
+    } else if (args[i] === '--force-redo') {
+      flags.forceRedo = true;
+    } else if (args[i] === '--pr') {
+      flags.pr = true;
+    } else if (args[i] === '--timings' || args[i] === '--show-timings') {
+      // v0.14-Q2: per-validator timing display. Renamed from `--profile` to
+      // avoid collision with `docguard init --profile <name>`. `--show-timings`
+      // is the long form for users who prefer explicit verbs.
+      flags.timings = true;
     } else if (!args[i].startsWith('--') && i > 0) {
       // Positional args go into flags.args for commands that take them (e.g.
       // `docguard trace --reverse <path>`). Skip the command itself (i === 0).

package/cli/shared-source.mjs

@@ -254,6 +254,16 @@ export function grepEnvUsage(projectDir, config = {}) {
     }
   };
 
+  // v0.14-P2: when config.changedFiles is populated (by --changed-only),
+  // restrict the scan to ONLY those paths. Skips the recursive tree walk
+  // entirely — turns "scan 5000 files" into "scan 3 files" in pre-commit mode.
+  if (Array.isArray(config.changedFiles) && config.changedFiles.length > 0) {
+    for (const rel of config.changedFiles) {
+      visit(resolve(projectDir, rel));
+    }
+    return names;
+  }
+
   for (const root of roots) walk(root);
   return names;
 }

package/cli/validators/api-surface.mjs

@@ -192,6 +192,22 @@ export function validateApiSurface(projectDir, config) {
   const warnings = [];
   const fixes = [];
 
+  // v0.14-P2: when --changed-only scoping is active and NONE of the changed
+  // files look like route/spec/controller files, this validator has nothing
+  // to add — return N/A so the lite-mode total reflects only what was actually
+  // checked. Route patterns mirror the SECTION_FILE_MATCHERS in sync.mjs.
+  if (Array.isArray(config.changedFiles)) {
+    const ROUTE_RE = /(^|\/)(routes|controllers|handlers|app\/api)\/|openapi|swagger/i;
+    const anyRouteFile = config.changedFiles.some(f => ROUTE_RE.test(f));
+    if (!anyRouteFile) {
+      return {
+        errors, warnings, passed: 0, total: 0, fixes,
+        applicable: false,
+        note: 'no route/spec files in changed set',
+      };
+    }
+  }
+
   const drift = computeApiSurfaceDrift(projectDir, config);
 
   // ── Multi-spec divergence (independent of the API-REFERENCE doc) ──

package/cli/validators/cross-reference.mjs

@@ -27,7 +27,7 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { resolve, join, dirname, basename } from 'node:path';
+import { resolve, join, dirname, basename, relative } from 'node:path';
 
 /**
  * Slugify a heading the way GitHub's markdown anchors work.
@@ -294,6 +294,7 @@ function collectCanonicalDocs(projectDir) {
 export function validateCrossReferences(projectDir, _config = {}) {
   const errors = [];
   const warnings = [];
+  const fixes = [];
   let passed = 0;
   let total = 0;
 
@@ -364,13 +365,27 @@ export function validateCrossReferences(projectDir, _config = {}) {
         if (!matches) {
           const where = targetPath === docPath ? 'same doc' : basename(targetPath);
           // S-12: suggest the closest matching anchor when there's a near-miss.
-          // Three of five wu user-fixes were "heading renamed, link not updated"
-          // — a suggested-slug hint makes those deterministic-fixable.
           const suggestion = anchors ? suggestAnchor(normalizedAnchor, anchors) : null;
           const hint = suggestion ? ` (did you mean #${suggestion}?)` : '';
+          // v0.14.1-S12+: when the suggestion is HIGH-CONFIDENCE — unambiguous
+          // and very close (edit distance <= 2) — emit a mechanical fix so
+          // `docguard fix --write` resolves it without AI. Other near-misses
+          // still get the hint but no fix (the user needs to verify intent).
+          const isHighConfidence = suggestion && isUnambiguousSuggestion(normalizedAnchor, suggestion, anchors);
           warnings.push(
-            `${docName}:${ref.line} — broken anchor: "#${ref.anchor}" in ${where} doesn't match any heading${hint}`
+            `${docName}:${ref.line} — broken anchor: "#${ref.anchor}" in ${where} doesn't match any heading${hint}` +
+            (isHighConfidence ? ' [auto-fixable]' : '')
           );
+          if (isHighConfidence) {
+            fixes.push({
+              type: 'replace-anchor',
+              doc: relative(projectDir, docPath),
+              line: ref.line,
+              from: ref.anchor,
+              to: suggestion,
+              summary: `${docName}:${ref.line} #${ref.anchor} → #${suggestion}`,
+            });
+          }
           continue;
         }
       }
@@ -379,5 +394,28 @@ export function validateCrossReferences(projectDir, _config = {}) {
     }
   }
 
-  return { errors, warnings, passed, total };
+  return { errors, warnings, passed, total, fixes };
+}
+
+/**
+ * v0.14.1-S12+ — is the suggested anchor an unambiguous, high-confidence
+ * match? Two criteria, both must hold:
+ *   1. Edit distance between the broken anchor and the suggestion is <= 2
+ *      (catches typos and minor renames, refuses major slug rewrites).
+ *   2. The suggestion is the ONLY anchor that close — no other anchor
+ *      within distance <= 2. Avoids fixing to the wrong candidate when
+ *      multiple are similar.
+ */
+function isUnambiguousSuggestion(broken, suggestion, anchors) {
+  if (!broken || !suggestion || !anchors) return false;
+  const sugDist = editDistance(broken, suggestion);
+  if (sugDist > 2) return false;
+  // Count other anchors that are also within the same tight budget.
+  let closeCandidates = 0;
+  for (const a of anchors) {
+    if (a === suggestion) continue;
+    if (editDistance(broken, a) <= 2) closeCandidates++;
+    if (closeCandidates > 0) return false; // ambiguous
+  }
+  return true;
 }

package/cli/validators/generated-staleness.mjs

@@ -56,7 +56,11 @@ function extractDocStatus(content) {
 }
 
 export function validateGeneratedStaleness(projectDir, config = {}) {
-  const result = { errors: [], warnings: [], passed: 0, total: 0 };
+  // v0.14-P3: also emit a `fixes` array. Each fix is structured so
+  // `applyMechanicalFixes` can consume it via the new regenerate-section
+  // applier. Lets `fix --write` actually CLOSE the loop on drift instead
+  // of just warning. No AI needed — the scanner already knows the right body.
+  const result = { errors: [], warnings: [], passed: 0, total: 0, fixes: [] };
 
   // Build the canonical memory plan (what the docs SHOULD contain). If this
   // fails or produces no docs, the validator is N/A.
@@ -138,6 +142,15 @@ 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.`
       );
+      // v0.14-P3: structured fix so `docguard fix --write` can fix this
+      // mechanically (no AI needed — scanner already produced the right body).
+      result.fixes.push({
+        type: 'regenerate-section',
+        doc: doc.path,
+        sectionId: sec.id,
+        body: sec.body,
+        summary: `${basename(doc.path)} § ${sec.id} regenerated from scanner`,
+      });
     }
   }
 

package/cli/validators/metrics-consistency.mjs

@@ -64,6 +64,14 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
     { key: 'validators', regex: /(?<!\d\/)\b(\d{2,})\s+validators?\b/gi, label: 'validators' },
   ];
 
+  // v0.14.1-N1: dedup by (file, label, found) — a file that mentions the
+  // stale number multiple times produces ONE warning, not one per occurrence.
+  // The replace-count applier already uses replace-all semantics, so a single
+  // fix per (file, label) is sufficient. Previously: "X.md" appearing 2× with
+  // the same drift would generate 2 warnings + 2 fixes (the second a no-op).
+  const reportedDrift = new Set();      // key: `${relPath}|${label}|${found}`
+  const reportedPass  = new Set();      // key: `${relPath}|${label}` — only count one pass per (file, label)
+
   for (const mdFile of mdFiles) {
     const relPath = relative(projectDir, mdFile);
     // Skip changelog (historical numbers are fine by definition)
@@ -79,16 +87,32 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
 
       regex.lastIndex = 0;
       let match;
+      // Collect distinct (found-value) instances within THIS file first,
+      // then emit ONE warning per distinct value. A file that says "20" on
+      // line 5 and "20" on line 50 is the same drift; "20" on line 5 and
+      // "19" on line 50 are two distinct drifts.
+      const distinctFoundInFile = new Set();
       while ((match = regex.exec(content)) !== null) {
-        total++;
-        const found = parseInt(match[1], 10);
-        if (found !== actuals[key] && found > 0) {
+        distinctFoundInFile.add(parseInt(match[1], 10));
+      }
+      if (distinctFoundInFile.size === 0) continue;
+
+      for (const found of distinctFoundInFile) {
+        if (found > 0 && found !== actuals[key]) {
+          const driftKey = `${relPath}|${label}|${found}`;
+          if (reportedDrift.has(driftKey)) continue;
+          reportedDrift.add(driftKey);
+          total++;
           warnings.push(
             `${relPath} says "${found} ${label}" but actual count is ${actuals[key]}. Fix with \`docguard fix --write\``
           );
-          // Deterministic, surgical token replacement — safe to auto-apply.
           fixes.push({ type: 'replace-count', file: relPath, label, found, actual: actuals[key] });
         } else {
+          // Matches the actual count — one pass per (file, label), not per occurrence.
+          const passKey = `${relPath}|${label}`;
+          if (reportedPass.has(passKey)) continue;
+          reportedPass.add(passKey);
+          total++;
           passed++;
         }
       }

package/cli/writers/fix-memory.mjs

@@ -97,6 +97,12 @@ export function appendFixes(projectDir, fixes, appliedBy = 'fix --write') {
 
   for (const f of fixes) {
     const id = fingerprintFix(f);
+    const prior = byId.get(id);
+    // v0.14-P1: maintain applyCount across applies so ping-pong suppression
+    // can tell a fresh fix (count 1) from a recurring one (count 2+).
+    const applyCount = (prior && typeof prior.applyCount === 'number')
+      ? prior.applyCount + 1
+      : 1;
     const entry = {
       id,
       type: f.type || 'unknown',
@@ -104,8 +110,11 @@ export function appendFixes(projectDir, fixes, appliedBy = 'fix --write') {
       summary: f.summary || '',
       appliedAt: now,
       appliedBy,
+      applyCount,
+      // Keep firstAppliedAt for audit clarity — when did we first see this fix?
+      firstAppliedAt: (prior && prior.firstAppliedAt) || now,
     };
-    byId.set(id, entry); // overwrites prior with same fingerprint → updates appliedAt
+    byId.set(id, entry); // overwrites prior with same fingerprint
   }
 
   let entries = Array.from(byId.values());
@@ -131,3 +140,42 @@ export function isFixRecorded(projectDir, candidate) {
   const id = fingerprintFix(candidate);
   return loadFixMemory(projectDir).entries.some(e => e.id === id);
 }
+
+/**
+ * v0.14-P1 — fix-history suppression.
+ *
+ * Decide whether a candidate fix should be SUPPRESSED on this run because
+ * it's a known ping-pong pattern. A "ping-pong" is when the same
+ * fingerprint has been applied + reverted N or more times — usually a sign
+ * the user disagrees with the fix and we should stop re-suggesting it.
+ *
+ * Rules:
+ *   - Default threshold: 2 (apply → revert → apply is the third attempt → suppress)
+ *   - Configurable via opts.pingPongThreshold
+ *   - Override entirely via opts.force (set when caller passes --force-redo)
+ *
+ * Returns { suppressed: boolean, reason?: string }.
+ *
+ * @req SC-P1-001 — never suppresses on first apply
+ * @req SC-P1-002 — suppresses after N applies of the same fingerprint
+ * @req SC-P1-003 — force: true overrides suppression
+ */
+export function shouldSuppressFix(projectDir, candidate, opts = {}) {
+  if (opts.force) return { suppressed: false };
+  const id = fingerprintFix(candidate);
+  const mem = loadFixMemory(projectDir);
+  // Count occurrences of this fingerprint. Each `appendFixes` for an existing
+  // ID overwrites in place, so a single entry could represent many applies;
+  // we track a separate `applyCount` field for accurate ping-pong detection.
+  const entry = mem.entries.find(e => e.id === id);
+  if (!entry) return { suppressed: false };
+  const count = entry.applyCount || 1;
+  const threshold = opts.pingPongThreshold || 2;
+  if (count >= threshold) {
+    return {
+      suppressed: true,
+      reason: `applied ${count} time(s) before — possible ping-pong. Use --force-redo to apply anyway.`,
+    };
+  }
+  return { suppressed: false };
+}

package/cli/writers/mechanical.mjs

@@ -14,6 +14,29 @@
  * Pure file edits, no LLM. Zero NPM dependencies.
  */
 
+// v0.14-P1: resolve the suppression predicate at module load. Top-level
+// await is supported by ESM; if the import fails (e.g. partial install),
+// `_shouldSuppress` stays null and suppression is silently disabled —
+// fail-open, never block legit fixes.
+let _shouldSuppress = null;
+try {
+  const mod = await import('./fix-memory.mjs');
+  if (mod && typeof mod.shouldSuppressFix === 'function') {
+    _shouldSuppress = mod.shouldSuppressFix;
+  }
+} catch {
+  _shouldSuppress = null;
+}
+
+// v0.14-P3: section read/write API — loaded once at module init for the
+// regenerate-section applier. Same defensive pattern as the suppressor.
+let _sectionsModule = null;
+try {
+  _sectionsModule = await import('./sections.mjs');
+} catch {
+  _sectionsModule = null;
+}
+
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { removeEndpoints, hasGeneratedMarker } from './api-reference.mjs';
@@ -84,11 +107,81 @@ function applyRemoveEndpoint(projectDir, fix, { force = false } = {}) {
   return { applied: true, detail: `${fix.doc}: removed ${fix.method} ${fix.path}` };
 }
 
+/**
+ * v0.14-P3 — regenerate-section: rewrite a `source=code` section's body
+ * with the scanner's expected output. Emitted by the Generated-Staleness
+ * validator (M-1) when on-disk content drifts from what the memory plan
+ * would produce.
+ *
+ * Idempotent: if the section already matches `fix.body`, do nothing.
+ * Bounded: only writes inside `<!-- docguard:section id=X source=code -->`
+ * markers — never touches surrounding prose.
+ *
+ * fix shape: { type: 'regenerate-section', doc, sectionId, body }
+ */
+function applyRegenerateSection(projectDir, fix) {
+  if (!fix.doc || !fix.sectionId || fix.body == null) {
+    return { applied: false, skipped: 'regenerate-section needs doc, sectionId, body' };
+  }
+  const full = resolve(projectDir, fix.doc);
+  if (!existsSync(full)) return { applied: false, skipped: `doc not found: ${fix.doc}` };
+  const content = readFileSync(full, 'utf-8');
+  // Lazy-import the section writer to avoid a top-level circular risk.
+  // section APIs are synchronous and well-isolated; this works because
+  // mechanical.mjs already uses top-level await for fix-memory.
+  const { getSection, replaceSection } = _sectionsModule || {};
+  if (typeof getSection !== 'function' || typeof replaceSection !== 'function') {
+    return { applied: false, skipped: 'sections module unavailable' };
+  }
+  const existing = getSection(content, fix.sectionId);
+  if (!existing) return { applied: false, skipped: `section ${fix.sectionId} not present in ${fix.doc}` };
+  if (existing.body.trim() === String(fix.body).trim()) {
+    return { applied: false, skipped: `${fix.doc} § ${fix.sectionId} already current` };
+  }
+  const next = replaceSection(content, fix.sectionId, fix.body).content;
+  writeFileSync(full, next, 'utf-8');
+  return { applied: true, detail: `${fix.doc}: regenerated § ${fix.sectionId}` };
+}
+
+/**
+ * v0.14.1-S12+ — replace-anchor: rewrite a broken markdown anchor with a
+ * high-confidence suggested slug. Emitted by Cross-Reference when its
+ * fuzzy match is unambiguous (edit distance <= 2, no other close candidates).
+ *
+ * fix shape: { type: 'replace-anchor', doc, from, to, line?, summary? }
+ *
+ * Bounded: only rewrites occurrences of `](#${from})` and `](#X${from})`-like
+ * forms — won't touch the broken slug if it happens to appear as plain text.
+ * Idempotent: if no occurrence is found (already fixed), no-op.
+ */
+function applyReplaceAnchor(projectDir, fix) {
+  if (!fix.doc || !fix.from || !fix.to) {
+    return { applied: false, skipped: 'replace-anchor needs doc, from, to' };
+  }
+  const full = resolve(projectDir, fix.doc);
+  if (!existsSync(full)) return { applied: false, skipped: `doc not found: ${fix.doc}` };
+  const content = readFileSync(full, 'utf-8');
+
+  // Match an anchor inside a markdown link: `](#from)` OR `](path#from)`.
+  // Use a regex that captures the prefix and suffix so we only touch the
+  // anchor part — leaving the link text and path intact.
+  const fromEsc = esc(fix.from);
+  const re = new RegExp(`(\\]\\([^)]*#)${fromEsc}([)\\s])`, 'g');
+  const next = content.replace(re, `$1${fix.to}$2`);
+  if (next === content) {
+    return { applied: false, skipped: `${fix.doc}: anchor #${fix.from} not found (already fixed?)` };
+  }
+  writeFileSync(full, next, 'utf-8');
+  return { applied: true, detail: `${fix.doc}: #${fix.from} → #${fix.to}` };
+}
+
 const APPLIERS = {
   'replace-count': applyReplaceCount,
   'replace-version': applyReplaceVersion,
   'insert-changelog-unreleased': applyInsertChangelogUnreleased,
   'remove-endpoint': applyRemoveEndpoint,
+  'regenerate-section': applyRegenerateSection,
+  'replace-anchor': applyReplaceAnchor,
 };
 
 export const MECHANICAL_FIX_TYPES = Object.keys(APPLIERS);
@@ -113,7 +206,22 @@ export function applyMechanicalFix(projectDir, fix, opts = {}) {
 export function applyMechanicalFixes(projectDir, fixes, opts = {}) {
   const applied = [];
   const skipped = [];
+
   for (const fix of fixes) {
+    // v0.14-P1: ping-pong suppression. If this same fingerprint has been
+    // applied >= N times before (default 2) and --force-redo isn't set,
+    // skip with a clear reason. Suppression is OFF when:
+    //   - recordHistory === false (e.g. dry-run tests don't want this state)
+    //   - forceRedo === true (user explicitly asked to re-apply)
+    if (opts.recordHistory !== false && !opts.forceRedo && _shouldSuppress) {
+      const decision = _shouldSuppress(projectDir, fix, {
+        pingPongThreshold: opts.pingPongThreshold,
+      });
+      if (decision.suppressed) {
+        skipped.push({ ...fix, reason: `suppressed: ${decision.reason}` });
+        continue;
+      }
+    }
     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 });

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

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.13.1"
+  version: "0.14.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"

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.13.1
+  version: 0.14.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.13.1 -->
+<!-- docguard:version: 0.14.1 -->
 
 # 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.13.1
+  version: 0.14.1
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.13.1 -->
+<!-- docguard:version: 0.14.1 -->
 
 # 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.13.1
+  version: 0.14.1
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.13.1 -->
+<!-- docguard:version: 0.14.1 -->
 
 # 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.13.1
+  version: 0.14.1
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.13.1 -->
+<!-- docguard:version: 0.14.1 -->
 
 # DocGuard Score Skill
 

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

@@ -4,7 +4,7 @@ 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.13.1
+  version: 0.14.1
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

package/package.json

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