docguard-cli 0.14.0__tar.gz → 0.14.1__tar.gz

{docguard_cli-0.14.0/extensions/spec-kit-docguard → docguard_cli-0.14.1/.agent}/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.14.0
+  version: 0.14.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.14.0 -->
+<!-- docguard:version: 0.14.1 -->
 
 # DocGuard Fix Skill
 

{docguard_cli-0.14.0/extensions/spec-kit-docguard → docguard_cli-0.14.1/.agent}/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.14.0
+  version: 0.14.1
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.14.0 -->
+<!-- docguard:version: 0.14.1 -->
 
 # DocGuard Guard Skill
 

{docguard_cli-0.14.0/extensions/spec-kit-docguard → docguard_cli-0.14.1/.agent}/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.14.0
+  version: 0.14.1
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.14.0 -->
+<!-- docguard:version: 0.14.1 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.14.0 → docguard_cli-0.14.1}/.agent/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.14.0
+  version: 0.14.1
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.14.0 -->
+<!-- docguard:version: 0.14.1 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.14.0 → docguard_cli-0.14.1}/.agent/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.14.0
+  version: 0.14.1
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

{docguard_cli-0.14.0 → docguard_cli-0.14.1}/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.1] - 2026-05-26
+
+Patch + small feature release responding to the wu-whatsappinbox v0.12 feedback.
+**492 tests** (was 481, +11). 22 validators.
+
+### Fixed
+
+- **N-1: Metrics-Consistency double-counted warnings.** When a doc mentioned the stale validator/check count multiple times (e.g. once in a heading, once in a body table), the validator emitted one warning per regex match — producing "4 warnings for 2 files" on wu-whatsappinbox. Now dedupes by `(file, label, found-value)` so a single file contributes ONE warning per distinct drift value. The `replace-count` mechanical fix already uses replace-all semantics, so one fix per (file, label) is sufficient. **Reported by wu-whatsappinbox.**
+
+### Added
+
+- **S-12+: High-confidence anchor matches now auto-fix via `fix --write`.** v0.13.1 added "did you mean #X?" hints when Cross-Reference flagged a broken anchor. v0.14.1 takes the next step: when the suggested anchor is **unambiguous** (edit distance ≤ 2 AND no other candidates within the same distance), the warning is tagged `[auto-fixable]` and the validator emits a `replace-anchor` mechanical fix. New `replace-anchor` applier in `cli/writers/mechanical.mjs` rewrites only the anchor inside markdown link form `](#X)`, leaves plain-text occurrences and link text alone, is idempotent. **Three of five wu broken-anchor cases in v0.12.0 were "heading renamed, link not updated" — those are now `fix --write`-resolvable.**
+
+### Note to wu — the "still open" suggestions are all already shipped
+
+The S-1, S-11, S-12 items in the v0.12 feedback letter all shipped earlier. The user just needs to upgrade:
+
+- **S-1** (`sync --since <ref>` surgical refresh) → shipped in **v0.13.0** as L-1. Run `docguard sync --write --since main` to refresh only sections touched by code in the diff.
+- **S-11** (changed-file → affected-doc map) → shipped in **v0.13.1** as the `docguard impact` command. Run `docguard impact --since HEAD~1` after a commit; JSON mode for CI bots.
+- **S-12** (anchor "did you mean..." hints) → shipped in **v0.13.1**. Extended in this release (v0.14.1) so high-confidence matches are auto-fixable.
+
+Run `docguard upgrade --apply` (or `npm i -g docguard-cli@latest`) to pick all of these up.
+
+### Internal
+
+- **2 new test files**: `tests/metrics-dedup.test.mjs` (4) and `tests/anchor-autofix.test.mjs` (7). **Total: 481 → 492 tests (+11).**
+- **New mechanical fix type**: `replace-anchor`. The APPLIERS registry now lists 6 types.
+- **New helper** in `cli/validators/cross-reference.mjs`: `isUnambiguousSuggestion()` — gates the auto-fix on edit distance ≤ 2 AND single close candidate.
+- No new NPM deps.
+
+### Out of scope (deferred to v0.15)
+
+Same backlog as v0.14:
+- Generated-Staleness perf optimization (33% of validator time).
+- Shared tree walk.
+- Cross-validator `config.changedFiles` opt-in.
+- `upgrade --pr` battle-test.
+
 ## [0.14.0] - 2026-05-26
 
 Feature release closing the v0.13 backlog (4 features) + 2 quality investments

{docguard_cli-0.14.0 → docguard_cli-0.14.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docguard-cli
-Version: 0.14.0
+Version: 0.14.1
 Summary: The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation. Zero dependencies.
 Project-URL: Homepage, https://github.com/raccioly/docguard
 Project-URL: Documentation, https://github.com/raccioly/docguard#readme

{docguard_cli-0.14.0 → docguard_cli-0.14.1}/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;
 }

{docguard_cli-0.14.0 → docguard_cli-0.14.1}/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++;
         }
       }

{docguard_cli-0.14.0 → docguard_cli-0.14.1}/cli/writers/mechanical.mjs

@@ -143,12 +143,45 @@ function applyRegenerateSection(projectDir, fix) {
   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);

{docguard_cli-0.14.0 → docguard_cli-0.14.1}/extensions/spec-kit-docguard/extension.yml

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

{docguard_cli-0.14.0/.agent → docguard_cli-0.14.1/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.14.0
+  version: 0.14.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.14.0 -->
+<!-- docguard:version: 0.14.1 -->
 
 # DocGuard Fix Skill
 

{docguard_cli-0.14.0/.agent → docguard_cli-0.14.1/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.14.0
+  version: 0.14.1
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.14.0 -->
+<!-- docguard:version: 0.14.1 -->
 
 # DocGuard Guard Skill
 

{docguard_cli-0.14.0/.agent → docguard_cli-0.14.1/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.14.0
+  version: 0.14.1
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.14.0 -->
+<!-- docguard:version: 0.14.1 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.14.0 → docguard_cli-0.14.1}/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.14.0
+  version: 0.14.1
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.14.0 -->
+<!-- docguard:version: 0.14.1 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.14.0 → docguard_cli-0.14.1}/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.14.0
+  version: 0.14.1
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

{docguard_cli-0.14.0 → docguard_cli-0.14.1}/package.json

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

{docguard_cli-0.14.0 → docguard_cli-0.14.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "docguard-cli"
-version = "0.14.0"
+version = "0.14.1"
 description = "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation. Zero dependencies."
 readme = "README.md"
 license = { text = "MIT" }

docguard_cli-0.14.1/tests/anchor-autofix.test.mjs

@@ -0,0 +1,144 @@
+/**
+ * v0.14.1-S12+ — high-confidence anchor matches auto-fix via `fix --write`.
+ *
+ * @req SC-S12X-001 — Cross-Reference emits a replace-anchor fix for unambiguous matches
+ * @req SC-S12X-002 — NO fix emitted when multiple anchors are equally close
+ * @req SC-S12X-003 — NO fix emitted when the only candidate is far (distance > 2)
+ * @req SC-S12X-004 — replace-anchor applier rewrites only the anchor inside link form
+ * @req SC-S12X-005 — replace-anchor is idempotent (no double-apply)
+ * @req SC-S12X-006 — applier won't touch raw-text occurrences of the slug
+ */
+import { describe, it, afterEach } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { validateCrossReferences } from '../cli/validators/cross-reference.mjs';
+import { applyMechanicalFix, MECHANICAL_FIX_TYPES } from '../cli/writers/mechanical.mjs';
+
+function makeRepo(files) {
+  const dir = mkdtempSync(join(tmpdir(), 'docguard-anchor-fix-'));
+  for (const [rel, content] of Object.entries(files)) {
+    const full = join(dir, rel);
+    mkdirSync(join(full, '..'), { recursive: true });
+    writeFileSync(full, content);
+  }
+  return dir;
+}
+
+describe('replace-anchor is registered', () => {
+  it('appears in MECHANICAL_FIX_TYPES', () => {
+    assert.ok(MECHANICAL_FIX_TYPES.includes('replace-anchor'));
+  });
+});
+
+describe('Cross-Reference emits replace-anchor for high-confidence matches', () => {
+  let dir;
+  afterEach(() => { if (dir) rmSync(dir, { recursive: true, force: true }); });
+
+  it('typo: single-char edit distance produces an auto-fix', () => {
+    dir = makeRepo({
+      'docs-canonical/ARCHITECTURE.md':
+        '# A\n\nSee [setup](#authentication).\n\n## Authenticatio\nstub\n',
+        // Heading "Authenticatio" slugifies to `authenticatio`. Link says `authentication` (1 char extra). Distance = 1.
+    });
+    const r = validateCrossReferences(dir, {});
+    assert.ok(Array.isArray(r.fixes));
+    const fix = r.fixes.find(f => f.type === 'replace-anchor');
+    assert.ok(fix, `expected a replace-anchor fix; warnings: ${r.warnings.join(' | ')}`);
+    assert.equal(fix.from, 'authentication');
+    assert.equal(fix.to, 'authenticatio');
+    // The warning should mark it as auto-fixable so the user sees the hint
+    assert.ok(r.warnings[0].includes('[auto-fixable]'),
+      'high-confidence warning should be tagged [auto-fixable]');
+  });
+
+  it('does NOT emit a fix when match distance > 2 (low confidence)', () => {
+    dir = makeRepo({
+      'docs-canonical/ARCHITECTURE.md':
+        '# A\n\nSee [foo](#totally-different-name).\n\n## Setup\nstub\n',
+    });
+    const r = validateCrossReferences(dir, {});
+    // Either no suggestion at all, or no high-confidence fix
+    assert.ok(
+      !r.fixes.some(f => f.type === 'replace-anchor'),
+      'low-confidence match must NOT produce a fix'
+    );
+  });
+
+  it('does NOT emit a fix when multiple anchors are equally close (ambiguous)', () => {
+    dir = makeRepo({
+      'docs-canonical/ARCHITECTURE.md':
+        '# A\n\nSee [setup](#config).\n\n' +
+        '## configg\nstub\n' +     // distance 1 from "config"
+        '## configs\n' +            // also distance 1 from "config"
+        'stub\n',
+    });
+    const r = validateCrossReferences(dir, {});
+    assert.ok(
+      !r.fixes.some(f => f.type === 'replace-anchor'),
+      'ambiguous match (two close candidates) must NOT auto-fix'
+    );
+  });
+});
+
+describe('applyReplaceAnchor — mechanical', () => {
+  let dir;
+  afterEach(() => { if (dir) rmSync(dir, { recursive: true, force: true }); });
+
+  it('rewrites the anchor inside a markdown link', () => {
+    dir = makeRepo({
+      'docs-canonical/X.md':
+        '# X\n\nSee [setup](#old-anchor).\n\n## new-anchor\nstub\n',
+    });
+    const r = applyMechanicalFix(dir, {
+      type: 'replace-anchor',
+      doc: 'docs-canonical/X.md',
+      from: 'old-anchor',
+      to: 'new-anchor',
+    }, { recordHistory: false });
+    assert.equal(r.applied, true);
+    const result = readFileSync(resolve(dir, 'docs-canonical/X.md'), 'utf-8');
+    assert.match(result, /\(#new-anchor\)/);
+    assert.doesNotMatch(result, /\(#old-anchor\)/);
+  });
+
+  it('is idempotent: second apply is a no-op (skipped)', () => {
+    dir = makeRepo({
+      'docs-canonical/X.md':
+        '# X\n\nSee [setup](#new-anchor).\n\n## new-anchor\nstub\n',
+    });
+    const r = applyMechanicalFix(dir, {
+      type: 'replace-anchor',
+      doc: 'docs-canonical/X.md',
+      from: 'old-anchor',
+      to: 'new-anchor',
+    }, { recordHistory: false });
+    // No #old-anchor in file → applier should report skipped
+    assert.equal(r.applied, false);
+    assert.match(r.skipped, /not found/);
+  });
+
+  it('does NOT touch plain-text occurrences of the slug', () => {
+    dir = makeRepo({
+      'docs-canonical/X.md':
+        '# X\n\n' +
+        'The slug `old-anchor` appears in prose here.\n' +
+        'See [setup](#old-anchor).\n' +
+        '## new-anchor\n',
+    });
+    const r = applyMechanicalFix(dir, {
+      type: 'replace-anchor',
+      doc: 'docs-canonical/X.md',
+      from: 'old-anchor',
+      to: 'new-anchor',
+    }, { recordHistory: false });
+    assert.equal(r.applied, true);
+    const result = readFileSync(resolve(dir, 'docs-canonical/X.md'), 'utf-8');
+    // The plain-text backticked `old-anchor` must STAY
+    assert.match(result, /`old-anchor` appears in prose/);
+    // The link anchor MUST be updated
+    assert.match(result, /\(#new-anchor\)/);
+  });
+});

docguard_cli-0.14.1/tests/metrics-dedup.test.mjs

@@ -0,0 +1,112 @@
+/**
+ * v0.14.1-N1 — Metrics-Consistency dedup.
+ *
+ * Reported by wu-whatsappinbox: a file that mentions a stale validator/check
+ * count multiple times (e.g. once in a heading, once in a body table) was
+ * producing one warning per occurrence — "4 warnings for 2 files".
+ *
+ * @req SC-N1-001 — same drift in one file → one warning (not one per match)
+ * @req SC-N1-002 — distinct drift values in one file are separate warnings
+ * @req SC-N1-003 — replace-count fix is emitted exactly once per (file, label)
+ * @req SC-N1-004 — passed count uses unique-per-(file,label), not per-match
+ */
+import { describe, it, afterEach } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { validateMetricsConsistency } from '../cli/validators/metrics-consistency.mjs';
+
+function makeRepo(files) {
+  const dir = mkdtempSync(join(tmpdir(), 'docguard-metrics-dedup-'));
+  for (const [rel, content] of Object.entries(files)) {
+    const full = join(dir, rel);
+    mkdirSync(join(full, '..'), { recursive: true });
+    writeFileSync(full, content);
+  }
+  return dir;
+}
+
+// Simulate guard results so Metrics-Consistency knows what the "actual" count is.
+function fakeGuardResults(validatorCount, checkTotal) {
+  // Build N validators with checkTotal/N checks each (approx) so totals add up.
+  const validators = [];
+  const each = Math.floor(checkTotal / validatorCount);
+  for (let i = 0; i < validatorCount; i++) {
+    validators.push({ status: 'pass', total: each, passed: each });
+  }
+  // Pad last one to hit the exact target
+  validators[validators.length - 1].total += checkTotal - each * validatorCount;
+  return validators;
+}
+
+describe('Metrics-Consistency — dedup per (file, label, found)', () => {
+  let dir;
+  afterEach(() => { if (dir) rmSync(dir, { recursive: true, force: true }); });
+
+  it('same drift mentioned twice in one file → ONE warning, not two', () => {
+    dir = makeRepo({
+      'README.md':
+        '# Project\n\n' +
+        '## What\n\nDocGuard ships **21 validators** out of the box.\n\n' +
+        '## Reference\n\nSee the [21 validators table](#table) below.\n',
+    });
+    // Actual count is 22 (one more than the doc claims)
+    const r = validateMetricsConsistency(dir, { projectName: 't' }, fakeGuardResults(22, 100));
+    const driftWarnings = r.warnings.filter(w => /21 validators/.test(w) && /README\.md/.test(w));
+    assert.equal(driftWarnings.length, 1,
+      `expected 1 warning for README.md, got ${driftWarnings.length}: ${driftWarnings.join(' | ')}`);
+    const driftFixes = (r.fixes || []).filter(f => f.file === 'README.md' && f.label === 'validators');
+    assert.equal(driftFixes.length, 1,
+      `expected 1 replace-count fix for README.md, got ${driftFixes.length}`);
+  });
+
+  it('two DIFFERENT stale values in one file produce two warnings', () => {
+    dir = makeRepo({
+      'README.md':
+        '# Project\n\n' +
+        'DocGuard says **20 validators** here.\n' +
+        'But over here it says **19 validators**.\n',
+    });
+    const r = validateMetricsConsistency(dir, { projectName: 't' }, fakeGuardResults(22, 100));
+    const driftWarnings = r.warnings.filter(w => /README\.md/.test(w) && /validators/.test(w));
+    // Two distinct stale values → two warnings (one per value)
+    assert.equal(driftWarnings.length, 2);
+    const driftFixes = (r.fixes || []).filter(f => f.file === 'README.md' && f.label === 'validators');
+    assert.equal(driftFixes.length, 2,
+      'two distinct drifts → two fixes (each fixes a different "found" value)');
+  });
+
+  it('same number mentioned twice in correct form → ONE passed credit, not two', () => {
+    // The validator counts itself (+1) so 21 fake guards → "actual = 22 validators".
+    dir = makeRepo({
+      'README.md':
+        '# Project\n\n' +
+        '22 validators in total.\n' +
+        'See the 22 validators table.\n',
+    });
+    const r = validateMetricsConsistency(dir, { projectName: 't' }, fakeGuardResults(21, 100));
+    // README has TWO "22 validators" occurrences but only one pass should be credited.
+    assert.equal(r.warnings.filter(w => /README\.md/.test(w)).length, 0,
+      'matching number should not produce a warning');
+    // Validators-pattern contribution should be exactly 1 pass for README (not 2).
+    // We can't assert total directly because other patterns/files also contribute,
+    // but we can verify the README-validators key was deduped via the internal state.
+    // Workaround: assert total <= 2 (validators pattern + checks pattern at most once each).
+    assert.ok(r.total <= 2,
+      `README contributes at most 2 totals (validators + checks once each); got total=${r.total}`);
+  });
+
+  it('distinct files with the same stale value each get their own warning', () => {
+    dir = makeRepo({
+      'README.md':       '# A\n\n21 validators.\n',
+      'AGENTS.md':       '# B\n\n21 validators.\n',
+      'docs/quickstart.md': '# C\n\n21 validators.\n',
+    });
+    const r = validateMetricsConsistency(dir, { projectName: 't' }, fakeGuardResults(22, 100));
+    const driftWarnings = r.warnings.filter(w => /21 validators/.test(w));
+    assert.equal(driftWarnings.length, 3,
+      'one warning per FILE that has the drift (3 distinct files = 3 warnings)');
+  });
+});