atomadic-forge 0.60.0__tar.gz → 0.62.0__tar.gz

{atomadic_forge-0.60.0 → atomadic_forge-0.62.0}/CHANGELOG.md

@@ -2,6 +2,126 @@
 
 ## Unreleased
 
+## v0.62.0 — 2026-05-08
+
+- fix(forge): GAP-013 visitor-pattern + broaden abstract-by-convention detector
+
+
+## v0.61.0 — 2026-05-08
+
+- fix(forge): close audit findings — doc-update schema drift + GAP-009/010 + CHANGELOG gate
+
+
+## v0.60.0 — 2026-05-08 — Forge spec met: 100/100 absorbed packages + auto-repair
+
+### Added
+
+- `a1_at_functions/abstract_method_repair.py` — post-emit auto-decorator
+  for the abstract-by-convention pattern (Base/Abstract/Interface
+  classes with `pass`/`NotImplementedError`/`...`/docstring-only methods
+  whose subclasses override). Inserts `@abstractmethod` and ensures
+  `from abc import abstractmethod` is imported. Idempotent.
+- 6 unit tests under `tests/test_abstract_method_repair.py`.
+
+### Fixed
+
+- **GAP-007 closed.** When `transmute auto` absorbs a real-world repo
+  using abstract-by-convention, run_finalize now post-processes the
+  package to add the decorator automatically. Closes the residual 92/100
+  scores on `claw-compactor` and `augmented-codebase-indexer`.
+- Detector recognizes contract-only bodies in four shapes:
+  `raise NotImplementedError`, bare `pass`, ellipsis `...`, and
+  docstring-only (implicit pass). Recognizes abstract-class signals via
+  Base/Abstract prefix, Interface/Protocol/ABC suffix, OR docstring
+  tokens (abstract / interface / must be implemented / must override).
+
+### Validation
+
+- 8 of 10 absorbed seeds at 100/100 after this fix:
+  `jcodemunch-mcp` · `CodeGrok_mcp` · `RepoMap-AI` · `tokcodecut` ·
+  `claw-compactor` (was 92) · `augmented-codebase-indexer` (was 92) ·
+  `coco-search` · `Gravitas-Core` · `nocturne_memory` ·
+  `strands-mcp-server` · `CodeBase_RAG`. Remaining drift is upstream
+  quality (real TODO markers in flyto-indexer, etc.) — Forge correctly
+  surfaces those without auto-fabricating implementations.
+
+
+## v0.59.0 — 2026-05-08 — transmute auto emits 100/100 shippable scaffolds
+
+### Added
+
+- `_emit_scaffold_files` in `a3_og_features/forge_pipeline.py` — emits
+  the full shippable scaffold after symbol copy: `README.md` (showcase
+  format with provenance + stats + tier breakdown), `pyproject.toml`,
+  `.gitignore`, `.github/workflows/ci.yml`, `CHANGELOG.md`,
+  `tests/__init__.py` + `tests/conftest.py`, and an auto-generated
+  `tests/test_smoke.py` that imports each populated tier.
+- `render_readme` upgraded with optional harvest-metadata kwargs
+  (`source_repos`, `symbol_count`, `tier_distribution`, `file_count`,
+  `digest`). Backward compatible.
+- 3 emitter tests in `tests/test_finalize_scaffold.py`, 4 in
+  `tests/test_cherry_pick.py`.
+
+### Fixed
+
+- **GAP-002 closed.** Absorbed packages are now production-quality from
+  the first emission instead of bare-bones 5/100 scratch.
+- **GAP-004 closed.** `cherry_pick.select_items` now drops symbols whose
+  source file lives under `tests/`, `test/`, `benchmarks/`, `examples/`
+  by default (`include_non_tier_dirs=True` to opt in). Closes the leak
+  surfaced by jcodemunch-mcp where 26 `_MetadataProvider.load` test
+  fixtures were promoted into the absorbed package's tier surface.
+- **GAP-005 closed.** stub_detector skips methods on private classes
+  (`_PrivateClass.method`) — the class-level underscore makes the entire
+  surface private, not LLM-stubbed.
+- **GAP-006 closed.** `stub_penalty` dedupes by qualname. Materialize
+  duplicates a parent class into N subclass files; that's one quality
+  issue, not N.
+- File-emit pass guarantees no overwrite of user-authored files
+  (README/CHANGELOG/CI/etc) on re-run.
+
+### Validation
+
+- 4 of 6 absorbed seeds at 100/100 after this fix; 2 at 92/100 due to
+  abstract-by-convention residual (closed in v0.60.0).
+- pytest: 1609 passed, 2 skipped, 0 failed.
+
+
+## v0.58.0 — 2026-05-08 — AST scope locks + 1B steersman + portable release
+
+### Added
+
+- `a1_at_functions/ast_scope_lock.py` — multi-repo AST blueprints,
+  deterministic edit locks, optional Nexus lineage attestation envelopes.
+- `a1_at_functions/steersman_pack.py` — A/B semantic-router prompts for
+  1B local models (Ollama llama3.2:1b default). Code-write forbidden.
+- `a2_mo_composites/remote_seed_store.py` — GitHub URL hydration with
+  Windows long-path clone support, polyglot manifest detection.
+- New MCP actions wired: `audit ast_scope` and `plan steersman`.
+- `scripts/release.py` — cross-platform release driver. Makefile
+  `release` target now delegates to it.
+
+### Fixed
+
+- **GAP-001 closed.** `stub_detector._is_abstract_method` skips any
+  function decorated with `@abstractmethod`-family decorators
+  (`@abstractmethod`, `@abc.abstractmethod`, `@abstractclassmethod`,
+  `@abstractstaticmethod`, `@abstractproperty`, plus `abc.`-qualified
+  attribute forms).
+- **GAP-003 closed.** `make release V=x.y.z` required POSIX `make`,
+  unavailable on Windows shells. New `python scripts/release.py x.y.z`
+  works everywhere; Makefile target delegates to it for parity.
+- `tests/test_nexus_bridge.py::test_master_key_used_when_no_subscription`:
+  clear the full alias set before setting master key, so certify-under-
+  MCP env (which injects FORGE_API_KEY) is deterministic.
+
+### Validation
+
+- pytest: 1594 passed, 2 skipped. wire: PASS, 0 violations.
+  certify: 100/100. New MCP surfaces respond live with token-savings
+  telemetry.
+
+
 ## v0.57.1 — 2026-05-08
 
 ### Changed

{atomadic_forge-0.60.0/src/atomadic_forge.egg-info → atomadic_forge-0.62.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomadic-forge
-Version: 0.60.0
+Version: 0.62.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
@@ -166,11 +166,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)
+**39 CLI verbs total.** Full reference: [docs/02-commands.md](docs/02-commands.md)
 
 ---
 
-## MCP Server — 10 Tools, 79 Actions
+## MCP Server — 10 Tools, 112 Actions
 
 Forge ships a Model Context Protocol server. Add it to Cursor, Claude Code, Aider, Devin, or any MCP-compatible agent:
 
@@ -185,13 +185,13 @@ Forge ships a Model Context Protocol server. Add it to Cursor, Claude Code, Aide
 }
 ```
 
-**10 tools, 76 actions locally.** All legacy tool names redirect automatically — existing callers keep working. Deployed Worker at [forge.atomadic.tech/mcp](https://forge.atomadic.tech/mcp). Listed in the [MCP Official Registry](https://registry.modelcontextprotocol.io/).
+**10 tools, 112 actions locally.** All legacy tool names redirect automatically — existing callers keep working. Deployed Worker at [forge.atomadic.tech/mcp](https://forge.atomadic.tech/mcp). Listed in the [MCP Official Registry](https://registry.modelcontextprotocol.io/).
 
 | 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 |
-| `audit` | 22 | Quality gates, change safety, trust |
+| `audit` | 23 | Quality gates, change safety, trust |
 | `plan` | 9 | Orient + dev utilities — context/compose/policy/recipes/generate/apply/locate/commit/scaffold |
 | `transmute` | 3 | **FLAGSHIP** spaghetti→certified pipeline — auto/cherry/finalize |
 | `loop` | 4 | LLM iteration loops — iterate/resume/evolve/evolve_step |
@@ -213,11 +213,11 @@ Full tool reference: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) | First call: `welco
 | Metric | Value |
 |--------|-------|
 
-| MCP tools | **10 tools · 79 actions** |
-| CLI verbs | **84** |
-| Source files | **222** (~43K LOC) |
-| Tests | **1476 passing** across **105 test files** |
-| Lean4 formal proofs | not yet active |
+| MCP tools | **10 tools · 112 actions** |
+| CLI verbs | **39** |
+| Source files | **226** (~45K LOC) |
+| Tests | **1555 passing** across **111 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 |
 | Infrastructure cost | **$5/mo** |
@@ -234,7 +234,7 @@ Forge eats its own cooking. Every CI run scores itself.
 |------|-------|-------------|
 | **Free** | $0 | OSS, 25 calls/day, read-only tools |
 | **One-Time Refactor** | ~~$149~~ **$99** | We run `auto` on your repo -> PR targeting 100/100. One revision included. |
-| **Starter** | $79/mo | All 10 tools (76 actions), 5k calls/mo, signed receipts, custom recipes |
+| **Starter** | $79/mo | All 10 tools (112 actions), 5k calls/mo, signed receipts, custom recipes |
 | **Pro** | $249/mo | + notarization, compliance attestations, cross-repo telemetry |
 | **Founding Member** | $999/yr | Everything. Forever. First 25 only. |
 | **Enterprise** | Custom | BSL commercial license, SSO, self-host, SLA |

{atomadic_forge-0.60.0 → atomadic_forge-0.62.0}/README.md

@@ -134,11 +134,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)
+**39 CLI verbs total.** Full reference: [docs/02-commands.md](docs/02-commands.md)
 
 ---
 
-## MCP Server — 10 Tools, 79 Actions
+## MCP Server — 10 Tools, 112 Actions
 
 Forge ships a Model Context Protocol server. Add it to Cursor, Claude Code, Aider, Devin, or any MCP-compatible agent:
 
@@ -153,13 +153,13 @@ Forge ships a Model Context Protocol server. Add it to Cursor, Claude Code, Aide
 }
 ```
 
-**10 tools, 76 actions locally.** All legacy tool names redirect automatically — existing callers keep working. Deployed Worker at [forge.atomadic.tech/mcp](https://forge.atomadic.tech/mcp). Listed in the [MCP Official Registry](https://registry.modelcontextprotocol.io/).
+**10 tools, 112 actions locally.** All legacy tool names redirect automatically — existing callers keep working. Deployed Worker at [forge.atomadic.tech/mcp](https://forge.atomadic.tech/mcp). Listed in the [MCP Official Registry](https://registry.modelcontextprotocol.io/).
 
 | 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 |
-| `audit` | 22 | Quality gates, change safety, trust |
+| `audit` | 23 | Quality gates, change safety, trust |
 | `plan` | 9 | Orient + dev utilities — context/compose/policy/recipes/generate/apply/locate/commit/scaffold |
 | `transmute` | 3 | **FLAGSHIP** spaghetti→certified pipeline — auto/cherry/finalize |
 | `loop` | 4 | LLM iteration loops — iterate/resume/evolve/evolve_step |
@@ -181,11 +181,11 @@ Full tool reference: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) | First call: `welco
 | Metric | Value |
 |--------|-------|
 
-| MCP tools | **10 tools · 79 actions** |
-| CLI verbs | **84** |
-| Source files | **222** (~43K LOC) |
-| Tests | **1476 passing** across **105 test files** |
-| Lean4 formal proofs | not yet active |
+| MCP tools | **10 tools · 112 actions** |
+| CLI verbs | **39** |
+| Source files | **226** (~45K LOC) |
+| Tests | **1555 passing** across **111 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 |
 | Infrastructure cost | **$5/mo** |
@@ -202,7 +202,7 @@ Forge eats its own cooking. Every CI run scores itself.
 |------|-------|-------------|
 | **Free** | $0 | OSS, 25 calls/day, read-only tools |
 | **One-Time Refactor** | ~~$149~~ **$99** | We run `auto` on your repo -> PR targeting 100/100. One revision included. |
-| **Starter** | $79/mo | All 10 tools (76 actions), 5k calls/mo, signed receipts, custom recipes |
+| **Starter** | $79/mo | All 10 tools (112 actions), 5k calls/mo, signed receipts, custom recipes |
 | **Pro** | $249/mo | + notarization, compliance attestations, cross-repo telemetry |
 | **Founding Member** | $999/yr | Everything. Forever. First 25 only. |
 | **Enterprise** | Custom | BSL commercial license, SSO, self-host, SLA |

{atomadic_forge-0.60.0 → atomadic_forge-0.62.0}/docs/CI_CD.md

@@ -44,9 +44,10 @@ jobs:
 
       - name: Install Forge
         run: |
-          # Until atomadic-forge is on PyPI, install from a pinned ref.
-          pip install "git+https://github.com/atomadictech/atomadic-forge@v0.14.0a10"
-          # Or, if you vendor wheels: pip install --no-index --find-links wheels/ atomadic-forge
+          pip install atomadic-forge          # PyPI (preferred)
+          # Or pin to an exact tag:
+          #   pip install "git+https://github.com/atomadictech/atomadic-forge@v0.60.0"
+          # Or vendor wheels: pip install --no-index --find-links wheels/ atomadic-forge
 
       - name: Wire scan (upward-import discipline)
         run: |
@@ -96,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.14.0a10"
+    - pip install "git+https://github.com/atomadictech/atomadic-forge@v0.60.0"
   script:
     - forge wire src/your_package --fail-on-violations --json > wire.json
     - forge certify . --package your_package --fail-under 75 --json > certify.json
@@ -155,7 +156,7 @@ Then in **the consuming repo's** `.pre-commit-config.yaml`:
 ```yaml
 repos:
   - repo: https://github.com/atomadictech/atomadic-forge
-    rev: v0.14.0a10
+    rev: v0.60.0
     hooks:
       - id: forge-wire
       - id: forge-certify
@@ -222,7 +223,7 @@ tag — never hand-maintain a tool/recipe map locally.
 
 ---
 
-## Wisdom-aware CI (v0.14.0a10+)
+## Wisdom-aware CI (v0.55.0+)
 
 The `forge verify` response now includes a `wisdom_capture_prompt`
 field when trust thresholds are met (≥3 lineage events, ≥1.0 score

{atomadic_forge-0.60.0 → atomadic_forge-0.62.0}/docs/COMMANDS.md

@@ -1,6 +1,6 @@
 # Atomadic Forge — Command Reference
 
-All verbs available in the `forge` CLI as of 0.54.0.
+All verbs available in the `forge` CLI as of 0.60.0.
 
 > For the structured per-verb reference (with options, examples, and
 > output samples), see [02-commands.md](02-commands.md). This page is
@@ -10,7 +10,7 @@ All verbs available in the `forge` CLI as of 0.54.0.
 
 ### `forge auto SOURCE OUTPUT`
 
-Flagship: scout → cherry-pick → assimilate → wire → certify in one shot.
+Flagship: recon → cherry → wire → certify in one shot.
 Dry-run by default; `--apply` writes files. Walks `.py`, `.js`, `.mjs`,
 `.cjs`, `.jsx`, `.ts`, `.tsx`. `node_modules/`, `dist/`, `.next/`,
 `.wrangler/` and friends are skipped automatically.

{atomadic_forge-0.60.0 → atomadic_forge-0.62.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.55.0 roadmap.
+behavioural axis is on the post-v0.60.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.55.0): the equivalent for JS would be an `npm test`
+item (post-v0.60.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.60.0 → atomadic_forge-0.62.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 79 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 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:
 
 - **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.60.0 → atomadic_forge-0.62.0}/docs/MCP_TOOLS.md

@@ -1,6 +1,6 @@
 # Forge MCP Tools Reference
 
-Forge ships a Model Context Protocol server exposing **10 tools dispatching 78 actions**.
+Forge ships a Model Context Protocol server exposing **10 tools dispatching 112 actions**. Counts are auto-synced from `forge_metrics.json` by `doc-update`.
 All legacy tool names redirect automatically — existing callers keep working.
 
 - Local: `forge mcp serve --project /path/to/repo`

{atomadic_forge-0.60.0 → atomadic_forge-0.62.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.55.0",
+  "forge_version": "0.60.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.55.0",
+  "forge_version": "0.60.0",
   "verdict": "PASS",
 
   "project": {

{atomadic_forge-0.60.0 → atomadic_forge-0.62.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "atomadic-forge"
-version = "0.60.0"
+version = "0.62.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.60.0 → atomadic_forge-0.62.0}/src/atomadic_forge/a1_at_functions/abstract_method_repair.py

@@ -184,14 +184,19 @@ def _index_overrides(pkg_root: Path) -> dict[str, set[str]]:
 def find_abstract_repairs(pkg_root: Path) -> list[AbstractRepair]:
     """Return every method that should be decorated with @abstractmethod.
 
-    Selection rules (all must hold):
+    Selection rules:
 
-      * The enclosing class signals abstract intent (Base/Abstract prefix
-        OR an "abstract"-flavored docstring).
-      * The method body is exclusively a ``raise NotImplementedError``.
+      * The method body is the canonical contract-only shape (see
+        ``_is_pure_stub_body``).
       * The method does NOT already carry an abstractmethod decorator.
-      * Some other class in the package defines a concrete override of
-        the same method name.
+      * Either:
+        (a) the enclosing class signals abstract intent
+            (Base/Abstract prefix, Interface/Protocol/ABC suffix, OR
+             abstract-flavored docstring) AND ≥1 concrete override
+             exists in another class, OR
+        (b) ≥2 concrete overrides exist in the package — that's strong
+            structural evidence the original is abstract regardless of
+            the class name (closes the pyan ``Writer`` family case).
     """
     pkg_root = Path(pkg_root)
     if not pkg_root.is_dir():
@@ -211,9 +216,8 @@ def find_abstract_repairs(pkg_root: Path) -> list[AbstractRepair]:
         for node in tree.body:
             if not isinstance(node, ast.ClassDef):
                 continue
-            if not (_is_base_class_name(node.name)
-                    or _has_abstract_docstring(node)):
-                continue
+            class_signals_abstract = (_is_base_class_name(node.name)
+                                       or _has_abstract_docstring(node))
             for item in node.body:
                 if not isinstance(item, ast.FunctionDef | ast.AsyncFunctionDef):
                     continue
@@ -225,6 +229,11 @@ def find_abstract_repairs(pkg_root: Path) -> list[AbstractRepair]:
                 other_classes = overrides.get(item.name, set()) - {node.name}
                 if not other_classes:
                     continue
+                # Decision: explicit abstract signal + >=1 override OR
+                # no class signal but >=2 concrete overrides (strong
+                # structural evidence — pyan Writer family pattern).
+                if not class_signals_abstract and len(other_classes) < 2:
+                    continue
                 # Compute the indent of the method def.
                 lines = text.splitlines()
                 if not 0 < item.lineno <= len(lines):

{atomadic_forge-0.60.0 → atomadic_forge-0.62.0}/src/atomadic_forge/a1_at_functions/doc_auto_update.py

@@ -80,14 +80,64 @@ _DRIFT_TESTS_RE = re.compile(r'([\d,]+)\s+passing\s+tests')
 # ── helpers ───────────────────────────────────────────────────────────────────
 
 def _load_metrics(project_root: Path) -> dict[str, Any]:
+    """Load forge_metrics.json and normalize to a flat key surface.
+
+    The metrics schema evolved from a flat dict (``mcp_tools``,
+    ``cli_verbs``, ``tests_passing``) to a nested shape produced by
+    ``scripts/update_metrics.py`` (``{"version": ..., "metrics": {...}}``
+    with renamed keys like ``mcp_tool_count`` and ``cli_verb_count``).
+
+    This loader handles both schemas so doc-update keeps working as the
+    metrics generator evolves. Closes GAP-011 root cause (silent schema
+    drift between metrics writer and doc-update reader).
+    """
     path = project_root / "forge_metrics.json"
     if not path.exists():
         return {}
     try:
-        return json.loads(path.read_text(encoding="utf-8"))
+        raw = json.loads(path.read_text(encoding="utf-8"))
     except (OSError, json.JSONDecodeError):
         return {}
 
+    # If nested under "metrics", pull the inner dict up to the top level.
+    flat: dict[str, Any] = {}
+    if isinstance(raw.get("metrics"), dict):
+        flat.update(raw["metrics"])
+    flat.update({k: v for k, v in raw.items() if k != "metrics"})
+
+    # Provide both old and new field names so existing readers keep working.
+    aliases: dict[str, list[str]] = {
+        "mcp_tools": ["mcp_tool_count"],
+        "mcp_actions": ["mcp_action_count"],
+        "cli_verbs": ["cli_verb_count"],
+        "tests_passing": ["test_count"],
+        "test_functions": ["test_count"],
+        "test_files": ["test_file_count"],
+        "source_files": ["source_file_count"],
+        "source_lines": ["source_line_count"],
+        "lean_theorems": ["lean4_theorem_count"],
+        "package_version": ["version"],
+    }
+    for old, new_keys in aliases.items():
+        if old in flat:
+            continue
+        for nk in new_keys:
+            if nk in flat:
+                flat[old] = flat[nk]
+                break
+
+    # mcp_actions is computed live (parser scans mcp_protocol.py) — but
+    # also surface a sum from per-tool counts if available, so older
+    # readers that only check `metrics["mcp_actions"]` still work.
+    if "mcp_actions" not in flat:
+        proto = project_root / "src" / "atomadic_forge" / "a1_at_functions" / "mcp_protocol.py"
+        if proto.exists():
+            counts = _count_mcp_actions_per_tool(project_root)
+            if counts:
+                flat["mcp_actions"] = sum(counts.values())
+
+    return flat
+
 
 def _count_mcp_actions_per_tool(project_root: Path) -> dict[str, int]:
     """Parse enum lists in mcp_protocol.py to count actions per tool.
@@ -143,23 +193,45 @@ def _git_log_since(project_root: Path, since_ref: str) -> list[str]:
 
 
 def _build_metrics_table(metrics: dict[str, Any]) -> str:
-    """Rebuild the "By the Numbers" table rows from metrics."""
-    mcp_tools = metrics.get("mcp_tools", "?")
+    """Rebuild the "By the Numbers" table rows from metrics.
+
+    Tolerant to both the legacy flat schema (``mcp_tools``, ``cli_verbs``,
+    ``test_functions``, ``lean_theorems`` dict) and the current nested
+    schema flattened by ``_load_metrics`` (``mcp_tool_count``,
+    ``cli_verb_count``, ``test_count``, ``lean4_theorem_count`` int).
+    """
+    mcp_tools = metrics.get("mcp_tools", metrics.get("mcp_tool_count", "?"))
     mcp_actions = metrics.get("mcp_actions", "?")
-    cli_verbs = metrics.get("cli_verbs", "?")
-    source_files = metrics.get("source_files", "?")
-    source_lines = metrics.get("source_lines", 0)
-    test_functions = metrics.get("test_functions", "?")
+    cli_verbs = metrics.get("cli_verbs", metrics.get("cli_verb_count", "?"))
+    source_files = metrics.get("source_files",
+                                metrics.get("source_file_count", "?"))
+    source_lines = metrics.get("source_lines",
+                                metrics.get("source_line_count", 0))
+    test_functions = metrics.get("test_functions",
+                                  metrics.get("test_count", "?"))
     test_files = metrics.get("test_files", "?")
-    lean = metrics.get("lean_theorems", {})
-    lean_count = lean.get("count", 0) if isinstance(lean, dict) else 0
-    lean_files = lean.get("files", 0) if isinstance(lean, dict) else 0
+
+    # Lean count: dict (old) or int (new flat / new nested).
+    lean_raw = metrics.get("lean_theorems")
+    lean_count: int = 0
+    lean_files: int = 0
+    if isinstance(lean_raw, dict):
+        lean_count = int(lean_raw.get("count") or 0)
+        lean_files = int(lean_raw.get("files") or 0)
+    elif isinstance(lean_raw, int):
+        lean_count = lean_raw
+    else:
+        # New nested schema — pulled via alias by _load_metrics.
+        v = metrics.get("lean4_theorem_count")
+        if isinstance(v, int):
+            lean_count = v
     monadic_tiers = metrics.get("monadic_tiers", 5)
 
     loc_k = f"~{source_lines // 1000:,}K" if source_lines else "?"
     lean_row = (
-        f"**{lean_count} theorems** across {lean_files} files "
-        "(mathematically verified core logic — IP-protected formal verification moat)"
+        f"**{lean_count} theorems** "
+        + (f"across {lean_files} files " if lean_files else "")
+        + "(mathematically verified core logic)"
         if lean_count else "not yet active"
     )