atomadic-forge 0.75.3__tar.gz → 0.77.0__tar.gz

{atomadic_forge-0.75.3 → atomadic_forge-0.77.0}/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## v0.77.0 — 2026-05-08
+
+- fix(forge): cherry-pick — collapse Class.method explosion (root-cause)
+- feat(doc-update): auto-update 6 previously missed doc files on release
+
+
+## v0.76.0 — 2026-05-08
+
+- feat(forge): graft — surgical single-symbol cross-repo capability transfer
+- fix(lint): clear 14 ruff violations blocking CI
+- release: v0.75.3
+- fix(forge): GAP-014 — harvest fail-loud on missing/empty sources
+
+
 ## v0.75.3 — 2026-05-08
 
 ### Changed

{atomadic_forge-0.75.3/src/atomadic_forge.egg-info → atomadic_forge-0.77.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomadic-forge
-Version: 0.75.3
+Version: 0.77.0
 Summary: Atomadic Forge — absorb, enforce, emerge. Polyglot (Python · JavaScript/TypeScript · Rust · Go · Swift · Kotlin) architecture guardian for AI-generated code.
 Author: Atomadic
 License-Expression: BUSL-1.1
@@ -176,11 +176,11 @@ Forge enforces a **5-tier monadic law** — every source file belongs to exactly
 | `forge plan` | Bounded execution plan with risk + rollback |
 | `forge chat` | Terminal copilot over forge docs |
 
-**84 CLI verbs total.** Full reference: [docs/02-commands.md](docs/02-commands.md)
+**59 CLI verbs total.** Full reference: [docs/02-commands.md](docs/02-commands.md)
 
 ---
 
-## MCP Server — 10 Tools, 112 Actions
+## MCP Server — 10 Tools, 116 Actions
 
 Forge ships a Model Context Protocol server. Add it to Cursor, Claude Code, Aider, Devin, or any MCP-compatible agent:
 
@@ -200,7 +200,7 @@ Forge ships a Model Context Protocol server. Add it to Cursor, Claude Code, Aide
 | Tool | Actions | What it does |
 |------|---------|-------------|
 | `welcome` | — | RECOMMENDED FIRST CALL: onboarding scan, score, narrative, capability tour |
-| `explore` | 16 | Analyze, understand, discover — recon/explain/call_graph/call_graph_summary/smell/lineage/harvest/synergy/scan/swarm/churn/surface_gaps/capability_scout/dead_code/maintainability/concept_bridge |
+| `explore` | 17 | Analyze, understand, discover — recon/explain/call_graph/call_graph_summary/smell/lineage/harvest/synergy/scan/swarm/churn/surface_gaps/capability_scout/dead_code/maintainability/concept_bridge |
 | `audit` | 23 | Quality gates, change safety, trust |
 | `plan` | 10 | Orient + dev utilities — context/compose/policy/recipes/generate/apply/locate/commit/scaffold/steersman |
 | `transmute` | 3 | **FLAGSHIP** spaghetti→certified pipeline — auto/cherry/finalize |
@@ -223,10 +223,10 @@ Full tool reference: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) | First call: `welco
 | Metric | Value |
 |--------|-------|
 
-| MCP tools | **10 tools · 112 actions** |
-| CLI verbs | **84** |
-| Source files | **228** (~45K LOC) |
-| Tests | **1555 passing** across **112 test files** |
+| MCP tools | **10 tools · 116 actions** |
+| CLI verbs | **59** |
+| Source files | **232** (~47K LOC) |
+| Tests | **1588 passing** across **115 test files** |
 | Lean4 formal proofs | **872 theorems** (mathematically verified core logic) |
 | Monadic tiers | **5** (a0 → a4, strict upward-only composition) |
 | Languages | Python, JS/TS, Swift, Kotlin, Go, Rust |

{atomadic_forge-0.75.3 → atomadic_forge-0.77.0}/README.md

@@ -144,11 +144,11 @@ Forge enforces a **5-tier monadic law** — every source file belongs to exactly
 | `forge plan` | Bounded execution plan with risk + rollback |
 | `forge chat` | Terminal copilot over forge docs |
 
-**84 CLI verbs total.** Full reference: [docs/02-commands.md](docs/02-commands.md)
+**59 CLI verbs total.** Full reference: [docs/02-commands.md](docs/02-commands.md)
 
 ---
 
-## MCP Server — 10 Tools, 112 Actions
+## MCP Server — 10 Tools, 116 Actions
 
 Forge ships a Model Context Protocol server. Add it to Cursor, Claude Code, Aider, Devin, or any MCP-compatible agent:
 
@@ -168,7 +168,7 @@ Forge ships a Model Context Protocol server. Add it to Cursor, Claude Code, Aide
 | Tool | Actions | What it does |
 |------|---------|-------------|
 | `welcome` | — | RECOMMENDED FIRST CALL: onboarding scan, score, narrative, capability tour |
-| `explore` | 16 | Analyze, understand, discover — recon/explain/call_graph/call_graph_summary/smell/lineage/harvest/synergy/scan/swarm/churn/surface_gaps/capability_scout/dead_code/maintainability/concept_bridge |
+| `explore` | 17 | Analyze, understand, discover — recon/explain/call_graph/call_graph_summary/smell/lineage/harvest/synergy/scan/swarm/churn/surface_gaps/capability_scout/dead_code/maintainability/concept_bridge |
 | `audit` | 23 | Quality gates, change safety, trust |
 | `plan` | 10 | Orient + dev utilities — context/compose/policy/recipes/generate/apply/locate/commit/scaffold/steersman |
 | `transmute` | 3 | **FLAGSHIP** spaghetti→certified pipeline — auto/cherry/finalize |
@@ -191,10 +191,10 @@ Full tool reference: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) | First call: `welco
 | Metric | Value |
 |--------|-------|
 
-| MCP tools | **10 tools · 112 actions** |
-| CLI verbs | **84** |
-| Source files | **228** (~45K LOC) |
-| Tests | **1555 passing** across **112 test files** |
+| MCP tools | **10 tools · 116 actions** |
+| CLI verbs | **59** |
+| Source files | **232** (~47K LOC) |
+| Tests | **1588 passing** across **115 test files** |
 | Lean4 formal proofs | **872 theorems** (mathematically verified core logic) |
 | Monadic tiers | **5** (a0 → a4, strict upward-only composition) |
 | Languages | Python, JS/TS, Swift, Kotlin, Go, Rust |

{atomadic_forge-0.75.3 → atomadic_forge-0.77.0}/docs/CI_CD.md

@@ -46,7 +46,7 @@ jobs:
         run: |
           pip install atomadic-forge          # PyPI (preferred)
           # Or pin to an exact tag:
-          #   pip install "git+https://github.com/atomadictech/atomadic-forge@v0.60.0"
+          #   pip install "git+https://github.com/atomadictech/atomadic-forge@v0.77.0"
           # Or vendor wheels: pip install --no-index --find-links wheels/ atomadic-forge
 
       - name: Wire scan (upward-import discipline)
@@ -97,7 +97,7 @@ forge-certify:
   image: python:3.11-slim
   timeout: 10 minutes
   before_script:
-    - pip install "git+https://github.com/atomadictech/atomadic-forge@v0.60.0"
+    - pip install "git+https://github.com/atomadictech/atomadic-forge@v0.77.0"
   script:
     - forge wire src/your_package --fail-on-violations --json > wire.json
     - forge certify . --package your_package --fail-under 75 --json > certify.json
@@ -156,7 +156,7 @@ Then in **the consuming repo's** `.pre-commit-config.yaml`:
 ```yaml
 repos:
   - repo: https://github.com/atomadictech/atomadic-forge
-    rev: v0.60.0
+    rev: v0.77.0
     hooks:
       - id: forge-wire
       - id: forge-certify

{atomadic_forge-0.75.3 → atomadic_forge-0.77.0}/docs/COMMANDS.md

@@ -1,6 +1,6 @@
 # Atomadic Forge — Command Reference
 
-All verbs available in the `forge` CLI as of 0.60.0.
+All verbs available in the `forge` CLI as of 0.77.0
 
 > For the structured per-verb reference (with options, examples, and
 > output samples), see [02-commands.md](02-commands.md). This page is

{atomadic_forge-0.75.3 → atomadic_forge-0.77.0}/docs/FORMALIZATION.md

@@ -39,7 +39,7 @@ Forge certify scores out of **100** in two layers:
 JS / TS packages cap at **60/100** today: they earn the four
 structural axes, but the +25 runtime-import smoke and +30 behavioural
 pytest are Python-only. Wiring `npm test` / Vitest into the
-behavioural axis is on the post-v0.60.0 roadmap.
+behavioural axis is on the post-v0.77.0 roadmap.
 
 ---
 
@@ -131,7 +131,7 @@ runtime dependency makes the package unusable.
 
 **Why JS/TS does not get this gate yet.** AAM §5.4 (Threats to
 Validity) explicitly flags polyglot runtime gating as a roadmap
-item (post-v0.60.0): the equivalent for JS would be an `npm test`
+item (post-v0.77.0): the equivalent for JS would be an `npm test`
 invocation, which requires a Node toolchain we do not yet bundle.
 
 **Citation.** AAM §5.1 (Core Pipeline Pseudocode); AAM §5.4 (Threats

{atomadic_forge-0.75.3 → atomadic_forge-0.77.0}/docs/IDE_INTEGRATION.md

@@ -16,7 +16,7 @@ See `vscode-extension/README.md` for settings + usage.
 
 ## 2. MCP server (works with any MCP-aware assistant)
 
-Forge ships a fully-typed MCP server with **10 tools dispatching 112 actions** spanning recon, wire, certify, plan, enforce, emergent, synergy, wisdom, lineage, hive coordination, and AAAA-Nexus trust gates.  Any of these clients can attach:
+Forge ships a fully-typed MCP server with **10 tools dispatching 116 actions** spanning recon, wire, certify, plan, enforce, emergent, synergy, wisdom, lineage, hive coordination, and AAAA-Nexus trust gates.  Any of these clients can attach:
 
 - **Claude Code** (Anthropic CLI) — `claude mcp add atomadic-forge -- forge mcp serve --project ${workspaceFolder}`
 - **Cursor** — Settings → MCP Servers → add the same command above

{atomadic_forge-0.75.3 → atomadic_forge-0.77.0}/docs/MCP_TOOLS.md

@@ -1,6 +1,6 @@
 # Forge MCP Tools Reference
 
-Forge ships a Model Context Protocol server exposing **10 tools dispatching 112 registry-callable actions**. Counts are auto-synced from `forge_metrics.json` by `doc-update`.
+Forge ships a Model Context Protocol server exposing **10 tools dispatching 116 registry-callable actions**. Counts are auto-synced from `forge_metrics.json` by `doc-update`.
 The per-tool table below lists the primary dispatch actions; the headline total also includes compatibility routes that keep older callers working.
 All legacy tool names redirect automatically — existing callers keep working.
 
@@ -17,7 +17,7 @@ All legacy tool names redirect automatically — existing callers keep working.
 | Tool | Actions | Purpose |
 |------|---------|---------|
 | [`welcome`](#welcome) | — | Session onboarding: scan, score, narrative, capability tour |
-| [`explore`](#explore) | 16 | Analyze and understand a codebase — recon, call graphs, smells, harvest, discovery |
+| [`explore`](#explore) | 17 | Analyze and understand a codebase — recon, call graphs, smells, harvest, discovery |
 | [`audit`](#audit) | 23 | Quality gates, change safety, trust verification |
 | [`plan`](#plan) | 10 | Dev orientation and utilities — context packs, recipes, commit messages, steersman packs |
 | [`transmute`](#transmute) | 3 | **FLAGSHIP** spaghetti-to-certified pipeline |

{atomadic_forge-0.75.3 → atomadic_forge-0.77.0}/docs/RECEIPT.md

@@ -30,7 +30,7 @@ referenced from the Receipt.
 {
   "schema_version": "atomadic-forge.receipt/v1",
   "generated_at_utc": "2026-04-28T17:42:11Z",
-  "forge_version": "0.60.0",
+  "forge_version": "0.77.0",
   "verdict": "PASS",
   "project":           { ... },
   "certify":           { ... },
@@ -108,7 +108,7 @@ cited:
 {
   "schema_version": "atomadic-forge.receipt/v1",
   "generated_at_utc": "2026-04-28T17:42:11Z",
-  "forge_version": "0.60.0",
+  "forge_version": "0.77.0",
   "verdict": "PASS",
 
   "project": {

{atomadic_forge-0.75.3 → atomadic_forge-0.77.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "atomadic-forge"
-version = "0.75.3"
+version = "0.77.0"
 description = "Atomadic Forge — absorb, enforce, emerge. Polyglot (Python · JavaScript/TypeScript · Rust · Go · Swift · Kotlin) architecture guardian for AI-generated code."
 readme = "README.md"
 requires-python = ">=3.10"

{atomadic_forge-0.75.3 → atomadic_forge-0.77.0}/src/atomadic_forge/a1_at_functions/cherry_pick.py

@@ -62,6 +62,7 @@ def select_items(scout_report: dict, *, names: Iterable[str] | None = None,
             "confidence": _confidence_of(s),
             "reasons": _reasons_for(s),
         })
+    items = _dedup_methods_under_class(items)
     return {
         "schema_version": "atomadic-forge.cherry/v1",
         "source_repo": scout_report.get("repo", ""),
@@ -69,6 +70,32 @@ def select_items(scout_report: dict, *, names: Iterable[str] | None = None,
     }
 
 
+def _dedup_methods_under_class(items: list[dict]) -> list[dict]:
+    """Collapse ``Class.method`` items when ``Class`` is already selected.
+
+    The 47-file class explosion fix: scout enumerates a class plus every
+    public method as separate symbols (``IndexStore`` and
+    ``IndexStore.add``, ``IndexStore.search``, ...). Without this filter,
+    finalize copies the same source file once per qualname under
+    different slugs, exploding a single class into N near-identical files.
+
+    When the parent class is in the manifest, we drop its methods —
+    they ride along inside the class body. When the parent is absent
+    (rare; scout dropped it), we keep the methods so capability isn't
+    lost.
+    """
+    class_quals = {it["qualname"] for it in items if "." not in it["qualname"]}
+    out: list[dict] = []
+    for it in items:
+        qual = it["qualname"]
+        if "." in qual:
+            parent = qual.rsplit(".", 1)[0]
+            if parent in class_quals:
+                continue
+        out.append(it)
+    return out
+
+
 def _confidence_of(symbol: dict) -> float:
     # High confidence when name tokens drove the decision; lower when we fell
     # back to the kind-default (function→a1, class→a2).  Cheap proxy: complexity

atomadic_forge-0.77.0/src/atomadic_forge/a1_at_functions/cosine_similarity.py

@@ -0,0 +1,22 @@
+"""Grafted from search_symbols.py (lines 410–423) by `forge graft`."""
+from __future__ import annotations
+
+import math
+
+SCHEMA_VERSION_GRAFT_COSINE_SIMILARITY = "atomadic-forge.graft.cosine_similarity/v1"
+
+def cosine_similarity(a: list[float], b: list[float]) -> float:
+    """Cosine similarity in pure Python (no numpy).
+
+    Returns 0.0 if either vector is zero-length or the lists differ in size.
+    Uses ``math.sqrt`` and ``sum()`` — no external deps.
+    """
+    if not a or not b or len(a) != len(b):
+        return 0.0
+    dot = sum(x * y for x, y in zip(a, b, strict=False))
+    norm_a = math.sqrt(sum(x * x for x in a))
+    norm_b = math.sqrt(sum(y * y for y in b))
+    if norm_a == 0.0 or norm_b == 0.0:
+        return 0.0
+    return dot / (norm_a * norm_b)
+

{atomadic_forge-0.75.3 → atomadic_forge-0.77.0}/src/atomadic_forge/a1_at_functions/doc_auto_update.py

@@ -2,9 +2,11 @@
 
 Zero LLM tokens.  Reads forge_metrics.json, inspects MCP enum lists and CLI
 command decorators, then rewrites bounded sections in README.md, CHANGELOG.md,
-docs/IDE_INTEGRATION.md, WHITEPAPER.md, and docs/AGENTS_GUIDE.md
-programmatically.  Every value is derived from live code or the metrics artifact
-— no human-authored prose is touched.
+docs/IDE_INTEGRATION.md, WHITEPAPER.md, docs/AGENTS_GUIDE.md,
+tests/README.md, docs/CI_CD.md, docs/COMMANDS.md, docs/RECEIPT.md,
+docs/FORMALIZATION.md, and docs/MCP_TOOLS.md programmatically.  Every value
+is derived from live code or the metrics artifact — no human-authored prose
+is touched.
 
 Updateable sections
 -------------------
@@ -29,6 +31,26 @@ WHITEPAPER.md
 docs/AGENTS_GUIDE.md
   • Summary table rows matching ``| explore | NN actions |`` pattern (if present).
 
+tests/README.md
+  • "NN test files covering N,NNN passing tests" line.
+
+docs/CI_CD.md
+  • Git-pinned install URLs ``atomadic-forge@vX.Y.Z`` → current version.
+  • Pre-commit ``rev: vX.Y.Z`` pin → current version.
+
+docs/COMMANDS.md
+  • "as of X.Y.Z" version anchor in header.
+
+docs/RECEIPT.md
+  • ``"forge_version": "X.Y.Z"`` in example JSON payloads.
+
+docs/FORMALIZATION.md
+  • ``post-vX.Y.Z`` roadmap anchors.
+
+docs/MCP_TOOLS.md
+  • Header line ``NN tools dispatching NN registry-callable actions``.
+  • Per-tool action counts in the summary table.
+
 Pure: no subprocess unless git is requested.  No writes when dry_run=True.
 """
 from __future__ import annotations
@@ -78,6 +100,33 @@ _DRIFT_TOOLS_RE = re.compile(r'(\d+)\s+MCP\s+tools')
 _DRIFT_ACTIONS_RE = re.compile(r'dispatching\s+(\d+)\s+actions')
 _DRIFT_TESTS_RE = re.compile(r'([\d,]+)\s+passing\s+tests')
 
+# ── version-anchor regexes (update_version_anchors) ───────────────────────────
+# tests/README.md: "NN test files covering N,NNN passing tests"
+_TESTS_README_RE = re.compile(r'\d+ test files covering [\d,]+ passing tests')
+
+# docs/CI_CD.md: git-pinned install URL and pre-commit rev pin
+_CICD_GIT_URL_RE = re.compile(r'(atomadic-forge@)v[\d.]+')
+_CICD_REV_RE = re.compile(r'(rev:\s*)v[\d.]+')
+
+# docs/COMMANDS.md: "as of X.Y.Z" header anchor
+_COMMANDS_VER_RE = re.compile(r'(as of )[\d.]+')
+
+# docs/RECEIPT.md: forge_version in example JSON blocks (both occurrences)
+_RECEIPT_VER_RE = re.compile(r'("forge_version":\s*")[\d.]+(")')
+
+# docs/FORMALIZATION.md: "post-vX.Y.Z" roadmap anchors
+_FORMALIZATION_POST_VER_RE = re.compile(r'post-v[\d.]+')
+
+# docs/MCP_TOOLS.md: header count line
+_MCP_TOOLS_HEADER_RE = re.compile(
+    r'\d+ tools dispatching \d+ registry-callable actions'
+)
+# docs/MCP_TOOLS.md: per-tool summary table rows
+# Matches: | [`toolname`](#anchor) | NN | description |
+_MCP_TOOLS_ROW_RE = re.compile(
+    r'(\|\s*\[`(?P<tool>[^`]+)`\]\(#[^)]+\)\s*\|\s*)(?P<count>\d+)(\s*\|)'
+)
+
 
 # ── helpers ───────────────────────────────────────────────────────────────────
 
@@ -602,12 +651,146 @@ def detect_doc_drift(project_root: Path) -> dict[str, Any]:
     }
 
 
+# ── version-anchor updater ────────────────────────────────────────────────────
+
+def update_version_anchors(
+    project_root: Path,
+    *,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Rewrite version-pinned strings in docs that drift on every release.
+
+    Covers tests/README.md, docs/CI_CD.md, docs/COMMANDS.md, docs/RECEIPT.md,
+    docs/FORMALIZATION.md, and docs/MCP_TOOLS.md.  Each pattern is keyed to
+    live forge_metrics.json so no version string needs manual updating.
+    """
+    metrics = _load_metrics(project_root)
+    if not metrics:
+        return {
+            "schema_version": SCHEMA_VERSION_DOC_AUTO_UPDATE_V1,
+            "available": False,
+            "reason": "forge_metrics.json not found or empty",
+            "changes": [],
+            "dry_run": dry_run,
+        }
+
+    version = metrics.get("package_version", "")
+    test_files = metrics.get("test_files", "?")
+    test_functions = metrics.get("test_functions", "?")
+    mcp_tools = metrics.get("mcp_tools", "?")
+    mcp_actions = metrics.get("mcp_actions", "?")
+    changes: list[str] = []
+
+    # ── tests/README.md ───────────────────────────────────────────────────────
+    tests_readme = project_root / "tests" / "README.md"
+    if tests_readme.exists():
+        text = tests_readme.read_text(encoding="utf-8")
+        new_text = _TESTS_README_RE.sub(
+            f"{test_files} test files covering {test_functions} passing tests",
+            text,
+        )
+        if new_text != text:
+            if not dry_run:
+                tests_readme.write_text(new_text, encoding="utf-8")
+            changes.append(
+                f"tests/README.md: test counts → {test_files} files / {test_functions} tests"
+            )
+
+    if not version:
+        return {
+            "schema_version": SCHEMA_VERSION_DOC_AUTO_UPDATE_V1,
+            "available": True,
+            "changes": changes,
+            "warnings": ["package_version missing — skipped version-pinned files"],
+            "dry_run": dry_run,
+        }
+
+    # ── docs/CI_CD.md ─────────────────────────────────────────────────────────
+    cicd_path = project_root / "docs" / "CI_CD.md"
+    if cicd_path.exists():
+        text = cicd_path.read_text(encoding="utf-8")
+        new_text = _CICD_GIT_URL_RE.sub(rf"\g<1>v{version}", text)
+        new_text = _CICD_REV_RE.sub(rf"\g<1>v{version}", new_text)
+        if new_text != text:
+            if not dry_run:
+                cicd_path.write_text(new_text, encoding="utf-8")
+            changes.append(f"docs/CI_CD.md: pinned version → v{version}")
+
+    # ── docs/COMMANDS.md ──────────────────────────────────────────────────────
+    commands_path = project_root / "docs" / "COMMANDS.md"
+    if commands_path.exists():
+        text = commands_path.read_text(encoding="utf-8")
+        new_text = _COMMANDS_VER_RE.sub(rf"\g<1>{version}", text)
+        if new_text != text:
+            if not dry_run:
+                commands_path.write_text(new_text, encoding="utf-8")
+            changes.append(f"docs/COMMANDS.md: version anchor → {version}")
+
+    # ── docs/RECEIPT.md ───────────────────────────────────────────────────────
+    receipt_path = project_root / "docs" / "RECEIPT.md"
+    if receipt_path.exists():
+        text = receipt_path.read_text(encoding="utf-8")
+        new_text = _RECEIPT_VER_RE.sub(rf'\g<1>{version}\g<2>', text)
+        if new_text != text:
+            if not dry_run:
+                receipt_path.write_text(new_text, encoding="utf-8")
+            changes.append(f"docs/RECEIPT.md: forge_version → {version}")
+
+    # ── docs/FORMALIZATION.md ─────────────────────────────────────────────────
+    formalization_path = project_root / "docs" / "FORMALIZATION.md"
+    if formalization_path.exists():
+        text = formalization_path.read_text(encoding="utf-8")
+        new_text = _FORMALIZATION_POST_VER_RE.sub(f"post-v{version}", text)
+        if new_text != text:
+            if not dry_run:
+                formalization_path.write_text(new_text, encoding="utf-8")
+            changes.append(f"docs/FORMALIZATION.md: post-version anchors → post-v{version}")
+
+    # ── docs/MCP_TOOLS.md ─────────────────────────────────────────────────────
+    mcp_tools_path = project_root / "docs" / "MCP_TOOLS.md"
+    if mcp_tools_path.exists() and mcp_tools != "?" and mcp_actions != "?":
+        text = mcp_tools_path.read_text(encoding="utf-8")
+        # Header line
+        new_text = _MCP_TOOLS_HEADER_RE.sub(
+            f"{mcp_tools} tools dispatching {mcp_actions} registry-callable actions",
+            text,
+        )
+        # Per-tool summary table rows
+        action_counts = _count_mcp_actions_per_tool(project_root)
+
+        def _replace_mcp_tools_row(match: re.Match[str]) -> str:
+            tool = match.group("tool")
+            if tool not in action_counts:
+                return match.group(0)
+            new_count = str(action_counts[tool])
+            if match.group("count") == new_count:
+                return match.group(0)
+            return match.group(1) + new_count + match.group(4)
+
+        new_text = _MCP_TOOLS_ROW_RE.sub(_replace_mcp_tools_row, new_text)
+        if new_text != text:
+            if not dry_run:
+                mcp_tools_path.write_text(new_text, encoding="utf-8")
+            changes.append(
+                f"docs/MCP_TOOLS.md: header/rows → {mcp_tools} tools / {mcp_actions} actions"
+            )
+
+    return {
+        "schema_version": SCHEMA_VERSION_DOC_AUTO_UPDATE_V1,
+        "available": True,
+        "changes": changes,
+        "dry_run": dry_run,
+    }
+
+
 # ── main entry point ──────────────────────────────────────────────────────────
 
 def run_doc_auto_update(
     project_root: Path,
     *,
-    sections: tuple[str, ...] = ("readme", "changelog", "extended_docs"),
+    sections: tuple[str, ...] = (
+        "readme", "changelog", "extended_docs", "version_anchors"
+    ),
     dry_run: bool = False,
 ) -> dict[str, Any]:
     """Run all doc auto-update passes.
@@ -615,9 +798,13 @@ def run_doc_auto_update(
     Args:
         project_root: Repository root.
         sections: Which sections to update — any combination of
-                  ``"readme"``, ``"changelog"``, and ``"extended_docs"``.
-                  Defaults to all three.  ``"extended_docs"`` patches
-                  IDE_INTEGRATION.md, WHITEPAPER.md, and AGENTS_GUIDE.md.
+                  ``"readme"``, ``"changelog"``, ``"extended_docs"``, and
+                  ``"version_anchors"``.  Defaults to all four.
+                  ``"extended_docs"`` patches IDE_INTEGRATION.md,
+                  WHITEPAPER.md, and AGENTS_GUIDE.md.
+                  ``"version_anchors"`` patches tests/README.md,
+                  docs/CI_CD.md, docs/COMMANDS.md, docs/RECEIPT.md,
+                  docs/FORMALIZATION.md, and docs/MCP_TOOLS.md.
         dry_run: If True, return what would change without writing.
 
     Returns dict with ``schema_version``, ``results`` per section,
@@ -642,6 +829,11 @@ def run_doc_auto_update(
         results["extended_docs"] = r
         total += len(r.get("changes", []))
 
+    if "version_anchors" in sections:
+        r = update_version_anchors(root, dry_run=dry_run)
+        results["version_anchors"] = r
+        total += len(r.get("changes", []))
+
     # Self-verify: residual drift after all writes confirms every pattern fired.
     post_drift = detect_doc_drift(root) if not dry_run else {"drift_count": 0}