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

{atomadic_forge-0.77.0 → atomadic_forge-0.79.0}/.github/workflows/metrics-auto-regen.yml

@@ -33,7 +33,7 @@ jobs:
   regen:
     runs-on: ubuntu-latest
     timeout-minutes: 8
-    if: ${{ !contains(github.event.head_commit.message, '[skip ci]') && !contains(github.event.head_commit.message, 'chore(metrics): auto-regenerate') }}
+    if: ${{ !contains(github.event.head_commit.message || '', '[skip ci]') && !contains(github.event.head_commit.message || '', 'chore(metrics): auto-regenerate') }}
     steps:
       - uses: actions/checkout@v4
         with:

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

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## v0.79.0 — 2026-05-08
+
+- feat(forge): replay — deterministic golden-recipe execution
+- fix(compat): replace datetime.UTC with timezone.utc for Python 3.10 compat
+- fix(ci): null-safe head_commit.message in metrics-auto-regen if condition
+- chore(metrics): sync forge_metrics.json after cli_verb_count method change
+- fix(surface): regenerate surface.json with package_version 0.78.0
+- fix(metrics): replace upward a4 import in _live_cli_verb_count with file scan
+- chore(release): sync artifacts + doc anchors for v0.78.0
+
+
+## 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)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomadic-forge
-Version: 0.77.0
+Version: 0.79.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 | **1588 passing** across **115 test files** |
+| Source files | **235** (~47K LOC) |
+| Tests | **1597 passing** across **117 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.77.0 → atomadic_forge-0.79.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 | **1588 passing** across **115 test files** |
+| Source files | **235** (~47K LOC) |
+| Tests | **1597 passing** across **117 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.77.0 → atomadic_forge-0.79.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.77.0"
+          #   pip install "git+https://github.com/atomadictech/atomadic-forge@v0.78.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.77.0"
+    - pip install "git+https://github.com/atomadictech/atomadic-forge@v0.78.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.77.0
+    rev: v0.78.0
     hooks:
       - id: forge-wire
       - id: forge-certify

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

@@ -1,6 +1,6 @@
 # Atomadic Forge — Command Reference
 
-All verbs available in the `forge` CLI as of 0.77.0
+All verbs available in the `forge` CLI as of 0.78.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.77.0 → atomadic_forge-0.79.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.77.0 roadmap.
+behavioural axis is on the post-v0.78.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.77.0): the equivalent for JS would be an `npm test`
+item (post-v0.78.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.77.0 → atomadic_forge-0.79.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.77.0",
+  "forge_version": "0.78.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.77.0",
+  "forge_version": "0.78.0",
   "verdict": "PASS",
 
   "project": {

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "atomadic-forge"
-version = "0.77.0"
+version = "0.79.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.77.0 → atomadic_forge-0.79.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.77.0 → atomadic_forge-0.79.0}/src/atomadic_forge/a1_at_functions/doc_auto_update.py

@@ -58,7 +58,7 @@ from __future__ import annotations
 import json
 import re
 import subprocess
-from datetime import UTC, datetime
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
@@ -318,7 +318,7 @@ def _build_metrics_table(metrics: dict[str, Any]) -> str:
 
 def _build_changelog_block(version: str, log_lines: list[str]) -> str:
     """Generate a CHANGELOG section for the given version."""
-    today = datetime.now(UTC).strftime("%Y-%m-%d")
+    today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
     items = "\n".join(f"- {line}" for line in log_lines[:20]) if log_lines else "- (see git log)"
     return (
         f"## v{version} — {today}\n\n"

{atomadic_forge-0.77.0 → atomadic_forge-0.79.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.77.0 → atomadic_forge-0.79.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.77.0 → atomadic_forge-0.79.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.77.0 → atomadic_forge-0.79.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.77.0 → atomadic_forge-0.79.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.79.0/src/atomadic_forge/a3_og_features/recipe_replay.py

@@ -0,0 +1,158 @@
+"""Tier a3 — Recipe Replayer: deterministic execution of golden recipes.
+
+Each ``GoldenRecipe`` carries a ``validation_gate`` list of shell
+commands that an LLM agent would otherwise reason about and run one
+at a time. The replayer just runs them — no LLM round-trip per step
+— and reports per-step verdict + token savings.
+
+Token savings basis: each command an LLM would have planned + dispatched
+costs ~80 tokens of round-trip overhead (read prior result, decide next
+step, emit tool call). Replaying N commands deterministically avoids
+N × 80 tokens.
+"""
+from __future__ import annotations
+
+import subprocess
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from ..a1_at_functions.lifetime_savings import append_savings
+from ..a1_at_functions.recipes import get_recipe
+
+SCHEMA_VERSION_REPLAY_V1 = "atomadic-forge.replay/v1"
+TOKENS_PER_LLM_DISPATCH = 80
+
+
+@dataclass
+class StepResult:
+    command: str
+    exit_code: int
+    duration_ms: int
+    stdout_tail: str
+    stderr_tail: str
+    skipped: bool = False
+
+
+@dataclass
+class ReplayReport:
+    schema_version: str
+    recipe_name: str
+    project_root: str
+    steps: list[StepResult]
+    verdict: str  # PASS | FAIL | PARTIAL
+    pass_count: int
+    fail_count: int
+    skipped_count: int
+    duration_ms: int
+    tokens_saved_estimate: int
+
+    def to_dict(self) -> dict[str, Any]:
+        return {**asdict(self),
+                 "steps": [asdict(s) for s in self.steps]}
+
+
+def _tail(text: str, lines: int = 10) -> str:
+    if not text:
+        return ""
+    return "\n".join(text.splitlines()[-lines:])
+
+
+def replay_recipe(
+    *,
+    recipe_name: str,
+    project_root: Path,
+    stop_on_fail: bool = True,
+    dry_run: bool = False,
+) -> ReplayReport:
+    """Replay a golden recipe's ``validation_gate`` deterministically.
+
+    Args:
+        recipe_name: name from :func:`recipes.list_recipes`.
+        project_root: cwd for the subprocesses.
+        stop_on_fail: when True, remaining steps are marked skipped on
+            the first non-zero exit. When False, every step runs and
+            failures accumulate.
+        dry_run: print the plan, mark all steps skipped, don't shell out.
+
+    Raises:
+        KeyError: when ``recipe_name`` is not in the catalogue.
+    """
+    recipe = get_recipe(recipe_name)
+    if recipe is None:
+        raise KeyError(f"unknown recipe: {recipe_name!r}")
+
+    commands = list(recipe.get("validation_gate") or [])
+    project_root = Path(project_root).resolve()
+
+    t0 = time.monotonic()
+    steps: list[StepResult] = []
+    failed = False
+    for cmd in commands:
+        if dry_run or (failed and stop_on_fail):
+            steps.append(StepResult(
+                command=cmd, exit_code=-1, duration_ms=0,
+                stdout_tail="", stderr_tail="", skipped=True,
+            ))
+            continue
+        s_t0 = time.monotonic()
+        try:
+            proc = subprocess.run(  # noqa: S602
+                cmd, cwd=project_root, shell=True,
+                capture_output=True, text=True, timeout=600,
+            )
+            steps.append(StepResult(
+                command=cmd,
+                exit_code=proc.returncode,
+                duration_ms=int((time.monotonic() - s_t0) * 1000),
+                stdout_tail=_tail(proc.stdout),
+                stderr_tail=_tail(proc.stderr),
+            ))
+            if proc.returncode != 0:
+                failed = True
+        except (OSError, subprocess.TimeoutExpired) as exc:
+            steps.append(StepResult(
+                command=cmd, exit_code=-2,
+                duration_ms=int((time.monotonic() - s_t0) * 1000),
+                stdout_tail="", stderr_tail=str(exc),
+            ))
+            failed = True
+
+    pass_count = sum(1 for s in steps
+                      if not s.skipped and s.exit_code == 0)
+    fail_count = sum(1 for s in steps
+                      if not s.skipped and s.exit_code != 0)
+    skipped_count = sum(1 for s in steps if s.skipped)
+
+    if dry_run:
+        verdict = "DRY_RUN"
+    elif fail_count == 0 and pass_count > 0:
+        verdict = "PASS"
+    elif fail_count > 0 and pass_count > 0:
+        verdict = "PARTIAL"
+    else:
+        verdict = "FAIL"
+
+    # Token-savings: every non-skipped command avoided one LLM dispatch.
+    tokens_saved = (pass_count + fail_count) * TOKENS_PER_LLM_DISPATCH
+
+    if tokens_saved > 0 and not dry_run:
+        append_savings(
+            project_root=project_root,
+            tool=f"replay/{recipe_name}",
+            tokens_saved=tokens_saved,
+        )
+
+    return ReplayReport(
+        schema_version=SCHEMA_VERSION_REPLAY_V1,
+        recipe_name=recipe_name,
+        project_root=str(project_root),
+        steps=steps,
+        verdict=verdict,
+        pass_count=pass_count,
+        fail_count=fail_count,
+        skipped_count=skipped_count,
+        duration_ms=int((time.monotonic() - t0) * 1000),
+        tokens_saved_estimate=tokens_saved,
+    )

{atomadic_forge-0.77.0 → atomadic_forge-0.79.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.77.0 → atomadic_forge-0.79.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.77.0 → atomadic_forge-0.79.0}/src/atomadic_forge/a4_sy_orchestration/cli.py

@@ -2734,6 +2734,16 @@ 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."),
+        # v0.79.0 — replay: deterministic golden-recipe execution.
+        # Skips the LLM round-trip per step that an agent would
+        # otherwise spend planning + dispatching each command.
+        ("atomadic_forge.commands.replay", "replay",
+         "Replay a golden recipe's validation_gate deterministically."),
         ("atomadic_forge.commands.emergent_swarm", "emergent-swarm",
          "Round-5: cross-repo emergent composition discovery."),
         ("atomadic_forge.commands.emergent_swarm", "emergent_swarm",

{atomadic_forge-0.77.0 → atomadic_forge-0.79.0}/src/atomadic_forge/commands/metrics.py

@@ -32,19 +32,14 @@ from atomadic_forge.a2_mo_composites.repo_public_surface_sync import (
 from atomadic_forge.a3_og_features.forge_metrics_feature import emit_forge_metrics
 
 
-def _live_cli_verb_count() -> int:
-    """a4-side helper: count registered CLI verbs from the live Typer app.
-
-    Lives here (a4) instead of a3 because the metrics feature must not
-    import the CLI module — that would be an upward tier import.
-    """
-    try:
-        from atomadic_forge.a4_sy_orchestration import cli as _cli
-        commands = getattr(_cli.app, "registered_commands", []) or []
-        groups = getattr(_cli.app, "registered_groups", []) or []
-        return len(commands) + len(groups)
-    except Exception:
+def _live_cli_verb_count(project_root: Path = Path(".")) -> int:
+    """Count CLI verbs by scanning cli.py for @app.command( decorators."""
+    import re
+    cli_path = project_root / "src" / "atomadic_forge" / "a4_sy_orchestration" / "cli.py"
+    if not cli_path.exists():
         return 0
+    text = cli_path.read_text(encoding="utf-8", errors="replace")
+    return len(re.findall(r'@\w+\.command\(', text))
 
 COMMAND_NAME = "metrics"
 COMMAND_HELP = (
@@ -95,7 +90,7 @@ def run(
         apply=apply,
         proof_corpus_root=mhed,
         skip_self_cert=not self_cert,
-        cli_verbs_count=_live_cli_verb_count(),
+        cli_verbs_count=_live_cli_verb_count(project),
         tests_passing=tests_passing,
     )
     if json_out:

atomadic_forge-0.79.0/src/atomadic_forge/commands/replay.py

@@ -0,0 +1,101 @@
+"""Tier a4 — `forge replay` CLI surface.
+
+Run a golden recipe's validation_gate deterministically — no LLM in
+the loop. Each command an LLM would otherwise plan + dispatch costs
+real round-trip tokens; replaying skips that overhead entirely.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from atomadic_forge.a1_at_functions.recipes import list_recipes
+from atomadic_forge.a3_og_features.recipe_replay import replay_recipe
+
+COMMAND_NAME = "replay"
+COMMAND_HELP = (
+    "Replay a golden recipe's validation_gate deterministically — zero "
+    "LLM round-trips. Use `--list` to see available recipes."
+)
+
+app = typer.Typer(no_args_is_help=False, help=COMMAND_HELP)
+
+
+@app.callback(invoke_without_command=True)
+def run(
+    recipe: Annotated[str, typer.Argument(
+        help="Recipe name (use --list to see all).")] = "",
+    project: Annotated[Path, typer.Option(
+        "--project", "-p",
+        help="Project root used as cwd for each step.",
+        exists=True, file_okay=False, dir_okay=True,
+        resolve_path=True)] = Path("."),
+    list_all: Annotated[bool, typer.Option(
+        "--list", help="List available recipes and exit.")] = False,
+    dry_run: Annotated[bool, typer.Option(
+        "--dry-run", help="Print the plan without running.")] = False,
+    keep_going: Annotated[bool, typer.Option(
+        "--keep-going",
+        help="Run every step even if one fails (default: stop on first fail).",
+    )] = False,
+    json_out: Annotated[bool, typer.Option(
+        "--json", help="Emit machine-readable JSON.")] = False,
+) -> None:
+    """Replay a recipe's validation_gate."""
+    if list_all:
+        names = list_recipes()
+        if json_out:
+            typer.echo(json.dumps({"recipes": names}, indent=2))
+            return
+        typer.echo("Available recipes:")
+        for n in names:
+            typer.echo(f"  • {n}")
+        return
+
+    if not recipe:
+        typer.secho("forge replay: pass a recipe name or --list", fg="red", err=True)
+        raise typer.Exit(2)
+
+    try:
+        report = replay_recipe(
+            recipe_name=recipe,
+            project_root=project,
+            stop_on_fail=not keep_going,
+            dry_run=dry_run,
+        )
+    except KeyError as exc:
+        typer.secho(f"forge replay: {exc}", fg="red", err=True)
+        raise typer.Exit(2) from exc
+
+    if json_out:
+        typer.echo(json.dumps(report.to_dict(), indent=2, default=str))
+        if report.verdict in ("FAIL", "PARTIAL"):
+            raise typer.Exit(1)
+        return
+
+    typer.echo("")
+    typer.echo(f"Replay — {recipe}")
+    typer.echo("-" * 60)
+    for i, step in enumerate(report.steps, 1):
+        if step.skipped:
+            mark = typer.style("SKIP", fg="yellow")
+        elif step.exit_code == 0:
+            mark = typer.style("PASS", fg="green")
+        else:
+            mark = typer.style("FAIL", fg="red")
+        typer.echo(f"  [{i}] {mark}  {step.command}")
+        if step.exit_code not in (0, -1) and step.stderr_tail:
+            for line in step.stderr_tail.splitlines()[:3]:
+                typer.echo(f"        {line}")
+    typer.echo("-" * 60)
+    typer.echo(f"  verdict:        {report.verdict}")
+    typer.echo(f"  pass / fail:    {report.pass_count} / {report.fail_count}"
+               + (f"  ({report.skipped_count} skipped)"
+                   if report.skipped_count else ""))
+    typer.echo(f"  duration:       {report.duration_ms} ms")
+    typer.echo(f"  tokens saved:   ~{report.tokens_saved_estimate:,}")
+    if report.verdict in ("FAIL", "PARTIAL"):
+        raise typer.Exit(1)

atomadic_forge-0.79.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}%)")