atomadic-forge 0.76.0__tar.gz → 0.78.0__tar.gz

{atomadic_forge-0.76.0 → atomadic_forge-0.78.0}/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## v0.78.0 — 2026-05-08
+
+- feat(forge): token-savings auto-ledger across every enriched verb
+
+
+## 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

{atomadic_forge-0.76.0/src/atomadic_forge.egg-info → atomadic_forge-0.78.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomadic-forge
-Version: 0.76.0
+Version: 0.78.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
@@ -225,8 +225,8 @@ Full tool reference: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) | First call: `welco
 
 | MCP tools | **10 tools · 116 actions** |
 | CLI verbs | **59** |
-| Source files | **232** (~47K LOC) |
-| Tests | **1578 passing** across **114 test files** |
+| Source files | **233** (~47K LOC) |
+| Tests | **1592 passing** across **116 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.76.0 → atomadic_forge-0.78.0}/README.md

@@ -193,8 +193,8 @@ Full tool reference: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) | First call: `welco
 
 | MCP tools | **10 tools · 116 actions** |
 | CLI verbs | **59** |
-| Source files | **232** (~47K LOC) |
-| Tests | **1578 passing** across **114 test files** |
+| Source files | **233** (~47K LOC) |
+| Tests | **1592 passing** across **116 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.76.0 → atomadic_forge-0.78.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.76.0 → atomadic_forge-0.78.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.76.0 → atomadic_forge-0.78.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.76.0 → atomadic_forge-0.78.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.76.0 → atomadic_forge-0.78.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.76.0 → atomadic_forge-0.78.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "atomadic-forge"
-version = "0.76.0"
+version = "0.78.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.76.0 → atomadic_forge-0.78.0}/src/atomadic_forge/a1_at_functions/certify_checks.py

@@ -588,4 +588,6 @@ def certify(root: Path, *, project: str = "Atomadic project",
             basis_kind="files",
         ),
         summary=_summarize_certify(base),
+        project_root=root,
+        tool="certify",
     )

{atomadic_forge-0.76.0 → atomadic_forge-0.78.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.76.0 → atomadic_forge-0.78.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}
 

{atomadic_forge-0.76.0 → atomadic_forge-0.78.0}/src/atomadic_forge/a1_at_functions/response_enricher.py

@@ -90,18 +90,40 @@ def enrich_response(
     *,
     scope: dict[str, Any] | None = None,
     summary: str = "",
+    project_root: Any = None,
+    tool: str = "",
 ) -> dict[str, Any]:
     """Return ``report`` with ``scope`` and ``summary`` injected.
 
     Existing keys are not modified. If the report already carries a
     ``scope`` or ``summary`` from upstream, the new values overwrite
     (callers control the order).
+
+    When ``project_root`` and ``tool`` are provided AND the supplied
+    ``scope.tokens_saved_estimate`` is positive, this also appends an
+    entry to the project's lifetime-savings ledger so every verb
+    contributes to the boastable total. Best-effort: a ledger write
+    failure never affects the returned report.
     """
     out = dict(report)
     if scope is not None:
         out["scope"] = scope
     if summary:
         out["summary"] = summary
+    if project_root is not None and tool:
+        try:
+            est = int((scope or {}).get("tokens_saved_estimate") or 0)
+        except (TypeError, ValueError):
+            est = 0
+        if est > 0:
+            try:
+                from pathlib import Path as _P
+
+                from .lifetime_savings import append_savings as _append
+                _append(project_root=_P(str(project_root)),
+                         tool=tool, tokens_saved=est)
+            except Exception:  # pragma: no cover - never break tool response
+                pass
     return out
 
 

{atomadic_forge-0.76.0 → atomadic_forge-0.78.0}/src/atomadic_forge/a1_at_functions/scout_walk.py

@@ -508,6 +508,8 @@ def harvest_repo(
             basis_kind="files",
         ),
         summary=summarize_recon(base),
+        project_root=root,
+        tool="recon",
     )
 
 

{atomadic_forge-0.76.0 → atomadic_forge-0.78.0}/src/atomadic_forge/a1_at_functions/wire_check.py

@@ -598,4 +598,6 @@ def scan_violations(
             basis_kind="files",
         ),
         summary=_summarize_wire(report),
+        project_root=package_root,
+        tool="wire",
     )

{atomadic_forge-0.76.0 → atomadic_forge-0.78.0}/src/atomadic_forge/a3_og_features/emergent_feature.py

@@ -104,6 +104,8 @@ class EmergentScan:
                 basis_kind="symbols",
             ),
             summary=_summarize_emergent(dict(base)),
+            project_root=self.src_root,
+            tool="emergent",
         )
         return enriched  # type: ignore[return-value]
 

{atomadic_forge-0.76.0 → atomadic_forge-0.78.0}/src/atomadic_forge/a3_og_features/forge_pipeline.py

@@ -420,6 +420,8 @@ def run_auto(*, target: Path, output: Path, package: str = "absorbed",
             basis_kind="both",
         ),
         summary=_summarize_auto(base),
+        project_root=target,
+        tool="auto",
     )
 
 

{atomadic_forge-0.76.0 → atomadic_forge-0.78.0}/src/atomadic_forge/a3_og_features/synergy_feature.py

@@ -64,6 +64,8 @@ class SynergyScan:
                 basis_kind="symbols",
             ),
             summary=_summarize_synergy(dict(base)),
+            project_root=self.src_root,
+            tool="synergy",
         )  # type: ignore[return-value]
 
     def implement(self, candidate_id: str, report: SynergyScanReport,

{atomadic_forge-0.76.0 → atomadic_forge-0.78.0}/src/atomadic_forge/a3_og_features/verify_umbrella.py

@@ -311,6 +311,8 @@ def verify(
             basis_kind="files",
         ),
         summary=_summarize_verify(base),
+        project_root=project_root,
+        tool="verify",
     )
 
 

{atomadic_forge-0.76.0 → atomadic_forge-0.78.0}/src/atomadic_forge/a4_sy_orchestration/cli.py

@@ -2734,6 +2734,11 @@ def _register_specialty_apps() -> None:
         ("atomadic_forge.commands.graft", "graft",
          "Pull one symbol from a source file into the target's tier "
          "surface and optionally auto-wire CLI + MCP."),
+        # v0.78.0 — token-savings: lifetime ledger of LLM round-trips
+        # spared. Every enriched verb appends to .atomadic-forge/
+        # lifetime_savings.jsonl automatically.
+        ("atomadic_forge.commands.token_savings", "token-savings",
+         "Show the project's lifetime token-savings ledger."),
         ("atomadic_forge.commands.emergent_swarm", "emergent-swarm",
          "Round-5: cross-repo emergent composition discovery."),
         ("atomadic_forge.commands.emergent_swarm", "emergent_swarm",

atomadic_forge-0.78.0/src/atomadic_forge/commands/token_savings.py

@@ -0,0 +1,70 @@
+"""Tier a4 — `forge token-savings` CLI surface.
+
+Display the lifetime token-savings ledger for a project. Every Forge
+verb that reports a ``scope.tokens_saved_estimate`` automatically
+appends to this ledger via ``response_enricher.enrich_response``, so
+the running total is the cumulative LLM round-trip cost the Forge has
+spared the caller — boastable, verifiable, file-backed.
+
+The ledger lives at ``<project>/.atomadic-forge/lifetime_savings.jsonl``.
+One JSON object per line, append-only. Read it directly to audit.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from atomadic_forge.a1_at_functions.lifetime_savings import (
+    read_savings_summary,
+)
+
+COMMAND_NAME = "token-savings"
+COMMAND_HELP = (
+    "Show the project's lifetime token-savings ledger — the cumulative "
+    "LLM round-trips the Forge has spared, broken down by tool."
+)
+
+app = typer.Typer(no_args_is_help=False, help=COMMAND_HELP)
+
+
+@app.callback(invoke_without_command=True)
+def run(
+    project: Annotated[Path, typer.Option(
+        "--project", "-p",
+        help="Project root (must contain .atomadic-forge/).",
+        exists=True, file_okay=False, dir_okay=True, resolve_path=True)] = (
+        Path(".")),
+    json_out: Annotated[bool, typer.Option(
+        "--json", help="Emit machine-readable JSON.")] = False,
+) -> None:
+    """Show lifetime token-savings for the project."""
+    summary = read_savings_summary(project_root=project)
+
+    if json_out:
+        typer.echo(json.dumps(summary, indent=2, default=str))
+        return
+
+    typer.echo("")
+    typer.echo("Forge — lifetime token-savings ledger")
+    typer.echo("-" * 60)
+    typer.echo(f"  project:        {project}")
+    typer.echo(f"  ledger:         {summary['ledger_file']}")
+    if not summary["ledger_present"]:
+        typer.secho("  (no ledger yet — run any verb to start logging)",
+                     fg="yellow")
+        return
+    total = int(summary["tokens_saved_lifetime"])
+    typer.echo(f"  entries:        {summary['entry_count']}")
+    typer.echo(f"  tokens saved:   {total:,}")
+    typer.echo(f"  first seen:     {summary['first_seen_at']}")
+    typer.echo(f"  last seen:      {summary['last_seen_at']}")
+    by_tool = summary.get("by_tool") or {}
+    if by_tool:
+        typer.echo("")
+        typer.echo("  by tool:")
+        for tool, n in sorted(by_tool.items(), key=lambda kv: -kv[1]):
+            pct = (100.0 * n / total) if total else 0.0
+            typer.echo(f"    {tool:<14} {n:>10,}  ({pct:5.1f}%)")

{atomadic_forge-0.76.0 → atomadic_forge-0.78.0/src/atomadic_forge.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomadic-forge
-Version: 0.76.0
+Version: 0.78.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
@@ -225,8 +225,8 @@ Full tool reference: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) | First call: `welco
 
 | MCP tools | **10 tools · 116 actions** |
 | CLI verbs | **59** |
-| Source files | **232** (~47K LOC) |
-| Tests | **1578 passing** across **114 test files** |
+| Source files | **233** (~47K LOC) |
+| Tests | **1592 passing** across **116 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 |